#1256 Docs: Improve doc contents

doc/realearn/modules/ROOT/nav.adoc

@@ -134,6 +134,6 @@
 ** xref:further-concepts/target-concepts.adoc[]
 ** xref:further-concepts/source-concepts.adoc[]
 * xref:best-practices.adoc[]
-* xref:provided-reaper-actions.adoc[]
+* xref:reaper-actions.adoc[]
 * xref:configuration-files.adoc[]
 * xref:design-decisions.adoc[]

doc/realearn/modules/ROOT/pages/best-practices.adoc

@@ -1,4 +1,3 @@
-[appendix]
 = Best practices
 
 [[best-practices-input-output,Best practices for setting input and output]]
@@ -62,14 +61,14 @@ Or make an encoder generally slower or faster.
 Or you could simulate a rotary encoder by making two buttons on your controller act as -/+ buttons emitting relative values.
 This is possible by mapping them to the same xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] in xref:user-interface/mapping-panel/glue-section.adoc#incremental-button[].
 
-Before you go ahead and do that for each control element, you might want to check out what this is good for: Navigate back to the xref:key-concepts.adoc#main-compartment[], learn the xref:key-concepts.adoc#source[] of some xref:key-concepts.adoc#main-mapping[] and touch the xref:key-concepts.adoc#control-element[] that you have just mapped: Take note how ReaLearn will assign a xref:key-concepts.adoc#virtual-source[] this time, not a xref:source-types/category-midi.adoc#midi-source[]!
+Before you go ahead and do that for each control element, you might want to check out what this is good for: Navigate back to the xref:key-concepts.adoc#main-compartment[], learn the xref:key-concepts.adoc#source[] of some xref:key-concepts.adoc#main-mapping[] and touch the xref:key-concepts.adoc#control-element[] that you have just mapped: Take note how ReaLearn will assign a xref:key-concepts.adoc#virtual-source[] this time, not a xref:source-types/category-midi.adoc[MIDI source]!
 It will also display the name of the xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] as source label.
 
 Now, let's say at some point you swap your xref:key-concepts.adoc#controller[] with another one that has a similar layout, all you need to do is to switch the xref:further-concepts/compartment-concepts.adoc#controller-preset[] and you are golden!
 You have decoupled your xref:key-concepts.adoc#main-mapping[] from the actual xref:key-concepts.adoc#controller[].
 Plus, you can now take full advantage of the xref:further-concepts/unit-concepts.adoc#projection[] feature.
 
-All of this might be a bit of an effort but it's well worth it!
+All of this might be a bit of an effort, but it's well worth it!
 Plus, there's a way to do this _a lot_ faster by using _batch learning_:
 
 . Press the xref:user-interface/main-panel/mappings-toolbar.adoc#learn-many-button[].

doc/realearn/modules/ROOT/pages/configuration-files.adoc

@@ -1,39 +1,31 @@
-[appendix]
 = Configuration files
 
 ReaLearn creates and/or reads a few files in REAPER's resource directory.
 
-[cols="m,1"]
-|===
+`Data/helgoboss`:: Directory which contains data such as presets or resources that need to be distributed via ReaPack
 
-| File | Description
+`Data/helgoboss/auto-load-configs/fx.json`:: Contains global FX-to-preset links, see xref:further-concepts/unit-concepts.adoc#auto-load[]
 
-| Data/helgoboss | Directory which contains data such as presets or resources that need to be distributed via ReaPack
+`Data/helgoboss/archives`:: Directory which contains archives e.g. the compressed app, distributed via ReaPack
 
-| Data/helgoboss/auto-load-configs/fx.json | Contains global FX-to-preset links, see xref:further-concepts/unit-concepts.adoc#auto-load[]
+`Data/helgoboss/doc`:: Contains offline documentation, e.g. this guide as PDF
 
-| Data/helgoboss/archives | Directory which contains archives e.g. the compressed app, distributed via ReaPack
+`Data/helgoboss/presets/controller`:: Contains preset for the controller compartment
 
-| Data/helgoboss/doc | Contains offline documentation, e.g. this guide as PDF
+`Data/helgoboss/presets/main`:: Contains preset for the main compartment
 
-| Data/helgoboss/presets/controller | Contains preset for the controller compartment
+`Helgoboss`:: Directory which contains rather personal or device-specific data, not touched via ReaPack
 
-| Data/helgoboss/presets/main | Contains preset for the main compartment
+`licensing.json`:: Contains license keys
 
-| Helgoboss | Directory which contains rather personal or device-specific data, not touched via ReaPack
+`Helgoboss/App`:: Contains the uncompressed App, if installed
 
-| licensing.json | Contains license keys
+`Helgoboss/Pot/previews`:: Directory which contains previews recorded by xref:further-concepts/instance-concepts.adoc#pot-browser[Pot Browser]
 
-| Helgoboss/App | Contains the uncompressed App, if installed
-
-| Helgoboss/Pot/previews | Directory which contains previews recorded by xref:further-concepts/instance-concepts.adoc#pot-browser[Pot Browser]
-
-| Helgoboss/ReaLearn/osc.json | Global OSC device configurations, see xref:user-interface/main-panel/inputoutput-section.adoc#manage-osc-devices[]
-
-| Helgoboss/ReaLearn/realearn.ini | Very basic global configuration, currently mainly regarding ReaLearn's built-in server.
+`Helgoboss/ReaLearn/osc.json`:: Global OSC device configurations, see xref:user-interface/main-panel/inputoutput-section.adoc#manage-osc-devices[]
 
+`Helgoboss/ReaLearn/realearn.ini`:: Very basic global configuration, currently mainly regarding ReaLearn's built-in server.
++
 Currently supported properties (subject to change): `server_enabled`, `server_http_port`, `server_https_port`, `server_grpc_port`, `companion_web_app_url`
 
-| Helgoboss/Server/certificates | Contains a list of certificates and corresponding private keys in order to allow encrypted communication with ReaLearn Companion and App.
-
-|===
+`Helgoboss/Server/certificates`:: Contains a list of certificates and corresponding private keys in order to allow encrypted communication with ReaLearn Companion and App.

doc/realearn/modules/ROOT/pages/further-concepts.adoc

@@ -1,4 +1,3 @@
-[split=1]
 = Further concepts
 
 This section describes further concepts.

doc/realearn/modules/ROOT/pages/further-concepts/general-concepts.adoc

@@ -16,17 +16,6 @@ A full-blown programming language derived from the famous Lua language that is a
 [TIP]
 ====
 
-You can also use the export for some very basic A/B testing:
-
-1. Choose _Export session as JSON_
-2. Change some settings and test them
-3. Restore the old settings by pressing _Import from clipboard_.
-
-====
-
-[TIP]
-====
-
 For the programmers and script junkies out there: It's perfectly possible to program ReaLearn from outside by passing it a snippet of JSON via https://www.reaper.fm/sdk/reascript/reascripthelp.html#TrackFX_SetNamedConfigParm[`TrackFX_SetNamedConfigParm()`].
 Parameter name is `set-state`.
 This mechanism is implemented on ReaLearn side using https://www.reaper.fm/sdk/vst/vst_ext.php[REAPER's named parameter mechanism] (search for `named_parameter_name`).
@@ -58,4 +47,9 @@ local state = [[
 ]]
 reaper.TrackFX_SetNamedConfigParm(track, 0, "set-state", state)
 ----
-====
+====
+
+[#feedback-relay]
+== Feedback relay
+
+Feedback _relay_ happens when a feedback-enabled mapping becomes inactive and another feedback-enabled mapping with the same xref:key-concepts.adoc#source[] becomes active. In that case, ReaLearn has to swap the displayed value of the previous mapping target with the displayed value of the new mapping target.

doc/realearn/modules/ROOT/pages/further-concepts/glue-concepts.adoc

@@ -4,11 +4,11 @@
 == Target value sequence
 
 A target value sequence represents a list of possible target values.
-It can be entered using into the xref:user-interface/mapping-panel/glue-section.adoc#target-value-sequence-field[].
+It can be entered using into the xref:user-interface/mapping-panel/glue-section.adoc#value-sequence[].
 
 The mapping will set the target only to values contained in that sequence.
 Such a sequence doesn't just support single values but also ranges with customizable step sizes.
-All values are entered comma-separated using the target unit specified with the xref:user-interface/mapping-panel/target-section.adoc#target-unit-button[].
+All values are entered comma-separated using the target unit specified with the xref:user-interface/mapping-panel/target-section.adoc#display-unit[].
 
 .Single values
 ====
@@ -80,7 +80,7 @@ ReaLearn's feedback processing order is:
 === Text feedback: Text expression
 
 With this option, ReaLearn will send text feedback values to the source.
-This only works with sources that are capable of displaying text: That is any xref:source-types/category-osc.adoc#osc-source[OSC source] with argument type _String_, xref:source-types/category-midi/display.adoc#display-source[MIDI Display] and xref:source-types/category-midi/midi-script-source.adoc#midi-script-source[].
+This only works with sources that are capable of displaying text: That is any xref:source-types/category-osc.adoc[] with argument type _String_, xref:source-types/category-midi/display.adoc#display-source[MIDI Display] and xref:source-types/category-midi/midi-script-source.adoc#midi-script-source[].
 
 Text feedback can be combined with a _text expression_, which lets you define which text is going to be sent to the source _whenever the target value changes_ and immediately when entering the text.
 Whatever text you enter here, will be sent verbatim to the source.

doc/realearn/modules/ROOT/pages/further-concepts/mapping-concepts.adoc

@@ -103,7 +103,7 @@ When moving a rotary endless encoder clockwise, it will continuously emit increm
 When moving it counter-clockwise, it will continuously emit decrements.
 +
 IMPORTANT: It happens very often that controllers have rotary endless encoders, but they will act like knobs by default, sending absolute messages.
-That is a great waste and you should change that setting as soon as possible on the hardware side.
+That is a great waste, and you should change that setting as soon as possible on the hardware side.
 
 [[control-value]]
 == Control value
@@ -229,7 +229,7 @@ Please activate this mapping only if ReaLearn Parameter 1 is *on*!"
 
 The activation condition of a mapping determines under which circumstances a mapping is active or inactive, based on the value of a xref:further-concepts/compartment-concepts.adoc#compartment-parameter[] or based on the state of arbitrary xref:key-concepts.adoc#target[targets].
 It is especially practical if your controller has a limited amount of control elements and you want to give control elements several responsibilities.
-It let's you easily implement use cases such as:
+It lets you easily implement use cases such as:
 
 * "This knob should control the track pan, but only when my sustain pedal is pressed, otherwise it should control track volume!" (modifier use cases)
 * "I want to have two buttons for switching between different banks where each bank represents a group of mappings." (bank use cases)
@@ -436,7 +436,7 @@ But even for the xref:key-concepts.adoc#control[] direction, you might want to r
 One part of your message might represent a variable value.
 You might want to extract it and control the target with it.
 
-Fortunately, ReaLearn offers a uniform way to extract a variable value from the raw MIDI message (control) or encode the current target value as part of it (feedback).
+Fortunately, ReaLearn offers a uniform way to extract a variable value from the raw MIDI message (control) or encode the current target value into the raw MIDI message (feedback).
 Bytes which contain a variable value (or a part of it) _must_ be expressed using binary notation.
 
 .Variable pattern

doc/realearn/modules/ROOT/pages/further-concepts/source-concepts.adoc

@@ -201,7 +201,7 @@ You might see a corresponding error message when the editor tries to compile you
 [[osc-feedback-arguments-expression]]
 == OSC feedback arguments expression
 
-This expression is used to enable for more flexible feedback for the xref:source-types/category-osc.adoc#osc-source[].
+This expression is used to enable for more flexible feedback for the xref:source-types/category-osc.adoc[].
 
 It allows you to define exactly which feedback value is sent at which argument position.
 If this field is non-empty, the argument type will be ignored for the xref:key-concepts.adoc#feedback[] direction.

doc/realearn/modules/ROOT/pages/further-concepts/target-concepts.adoc

@@ -207,7 +207,7 @@ CAUTION: If you select many tracks, things can become quite slow!
 Master track of the project which hosts this ReaLearn instance.
 
 * If ReaLearn is on the monitoring FX chain, this resolves to the master track of the current project.
-* If you don't have ReaLearn on the monitoring FX chain but you want to control an FX on the monitoring FX chain, this option is the right choice as well.
+* If you don't have ReaLearn on the monitoring FX chain, but you want to control an FX on the monitoring FX chain, this option is the right choice as well.
 Make sure to enable the "Monitoring FX" checkbox.
 
 ==== All named selector
@@ -290,7 +290,7 @@ Targets can expose properties, which you can use for xref:further-concepts/glue-
 
 Which properties are available, depends very much on the type of the target type.
 
-There are some properties which are available for (almost) any target (for very target-specific properties, please look up the corresponding target in xref:target-types.adoc#target-types[]):
+There are some properties which are available for (almost) any target (for very target-specific properties, please look up the corresponding target in xref:target-types.adoc[]):
 
 .Common target properties
 [cols="m,1,3"]

doc/realearn/modules/ROOT/pages/further-concepts/unit-concepts.adoc

@@ -25,7 +25,7 @@ That means, ReaLearn can act as global MIDI filter.
 ** Also, MIDI events captured from a real MIDI device input are *never* forwarded to ReaLearn's FX output.
 +
 TIP: This global MIDI filter feature is only available in REAPER v6.36+.
-* If input is set to a OSC device
+* If input is set to an OSC device
 ** You won't see the checkboxes because they don't make sense for OSC.
 * The checkboxes don't have any effect on computer keyboard input.
 Keys are always passed through when doing text entry and never passed through if a mapping matches.
@@ -174,7 +174,7 @@ Behavior:
 
 * By default, ReaLearn units are not superior, just normal.
 This is most of the time okay, even if you have multiple units that share the same input and output ... as long as you don't have any conflicting mappings active at the same time.
-* For example, if 2 units use the same input or output device and they use different control elements, they can peacefully coexist.
+* For example, if 2 units use the same input or output device, and they use different control elements, they can peacefully coexist.
 And even if they share a control element for the _control direction_, they are still fine with it.
 The same control element will control 2 mappings, why not!
 * Things start to get hairy as soon as 2 units want to send _feedback_ to the same control elements at the same time.

doc/realearn/modules/ROOT/pages/key-concepts.adoc

@@ -80,7 +80,7 @@ You can change the output port using the xref:user-interface/main-panel/inputout
 
 Helgobox/ReaLearn is an instrument plug-in.
 That means you can add multiple instances of it, just as you would add multiple instances of a synth or effect.
-For example, one instance could be on the monitoring FX chain and two instances somewhere in your project.
+For example, you could place one instance on the monitoring FX chain and two instances somewhere in your project.
 
 [[unit]]
 == Unit
@@ -101,19 +101,19 @@ The two compartments in each unit are:
 This is the primary compartment.
 Its purpose is to define what the controller device should do, e.g., allowing a fader to control track volume or displaying the name of an FX parameter on a hardware display.
 +
-We refer to the mappings in this compartment [[main-mapping,Main mapping]] _main mappings_ and the presets _main presets_.
+We refer to the mappings in this compartment as [[main-mapping,Main mapping]] _main mappings_ and to the presets as _main presets_.
 
 [[controller-compartment]] Controller compartment::
 The controller compartment is optional and serves two main purposes: Describing all control elements of the controller, assigning them descriptive names and enabling xref:further-concepts/compartment-concepts.adoc#virtual-control[].
 +
-We refer to the mappings in this compartment [[controller-mapping,Controller mapping]] _controller mappings_ and the presets _controller presets_.
+We refer to the mappings in this compartment as [[controller-mapping,Controller mapping]] _controller mappings_ and to the presets as _controller presets_.
 
 [#mapping]
 == Mapping
 
 Each compartment contains a list of mappings.
-A mapping is one of the most important concepts in ReaLearn.
-It connects a <<control-element>> and/or <<feedback-element>> on your <<controller>> with an action or parameter in REAPER.
+
+A _mapping_ connects a <<control-element>> and/or <<feedback-element>> on your <<controller>> with an action or parameter in REAPER.
 
 === Anatomy of a mapping