Improve docs

doc/architecture/design-decisions.adoc

@@ -12,7 +12,6 @@ The link:https://docs.helgoboss.org/realearn/user-interface/mapping-panel/advanc
 
 Deciding for textual configuration and YAML in particular was a conscious decision with the goal to provide a developer-friendly framework for rapidly extending ReaLearn with advanced features that don't urgently need a graphical user interface.
 
-[qanda]
 Why ask the user to enter text instead of providing a convenient graphical user interface?::
 * That's mostly a tradeoff due to the fact that my time available for developing ReaLearn is limited.
 * It's much work to develop a graphical user interface for every feature.
@@ -24,7 +23,7 @@ Textual configuration can be more powerful in many situations once the user know
 
 Why YAML?::
 * YAML has the advantage of being popular among programmers, widely supported, highly structured and relatively well readable/writable by both humans and machines.
-* Many text editors offer built-in support for editing YAML.
+* Many link:https://en.wikipedia.org/wiki/Text_editor[text editors] offer built-in support for editing YAML.
 * Makes it easy to provide data for even very complex features.
 
 Why not a scripting language?::

doc/helgobox/modules/ROOT/pages/app/user-interface/navigation-bar.adoc

@@ -2,7 +2,7 @@
 
 The bar on the left is the _Navigation bar_.
 
-Its main purpose is to switch between different user interface pages.
+Its main purpose is to switch between different pages.
 You can show or hide it using the xref:app/user-interface/title-bar.adoc#title-bar-toggle-nav-bar[] button in the xref:app/user-interface/title-bar.adoc[].
 
 include::partial$generated/elements/navbar/home.adoc[]

doc/helgobox/modules/ROOT/pages/plug-in/user-interface/menu-bar.adoc

@@ -14,22 +14,30 @@ This will open Pot Browser.
 See xref:products.adoc#pot-browser[] for details.
 
 [[show-app]] Show App::
-Shows the Helgobox App associated with this Helgobox instance.
+Shows the xref:helgobox::app.adoc[] associated with this xref:helgobox::key-concepts.adoc#instance[].
 
 [[close-app]] Close App::
-Closes the Helgobox App associated with this Helgobox instance.
+Closes the xref:helgobox::app.adoc[] associated with this xref:helgobox::key-concepts.adoc#instance[].
 
 [[server]] Server::
-Helgobox features a built-in server which allows the old ReaLearn Companion App (and in the future also the Helgobox App) to connect to Helgobox.
+Helgobox features a built-in server which allows the old ReaLearn Companion App (and in the future also the xref:helgobox::app.adoc[]) to connect to Helgobox.
 The server runs globally, not per instance!
 
 Enable and start!::: This starts the server and makes sure it will automatically be started next time you use Helgobox.
 Disable and stop!::: This stops the server and makes sure it will not be started next time you use Helgobox.
 Add firewall rule::: Attempts to add a firewall rule for making the server accessible from other devices or displays instructions how to do it.
 
+[[export-to-clipboard]]
 == Export to clipboard button
 
-Pressing the export button allows you to copy Helgobox settings to the clipboard so you can import them in another instance or edit them in a text editor.
+Pressing the export button allows you to copy Helgobox settings to the clipboard so you can import them in another instance or edit them in a link:https://en.wikipedia.org/wiki/Text_editor[text editor].
+
+--
+The following list only describes the general-purpose menu entries. For the rest, see:
+
+* xref:realearn::user-interface/main-panel/menu-bar.adoc#export-to-clipboard-button[ReaLearn entries]
+* xref:playtime::user-interface/menus/export-to-clipboard-menu.adoc[Playtime entries]
+--
 
 Export instance as JSON::
 Copies a _complete_ dump of this xref:key-concepts.adoc#instance[] to the clipboard in JSON format.

doc/helgobox/modules/ROOT/partials/generated/elements/title-bar/helgobox-info.adoc

@@ -4,5 +4,5 @@ ifndef::pdf-theme[[[title-bar-helgobox-info,Helgobox Info image:helgobox::genera
 
 image::helgobox::generated/screenshots/elements/title-bar/helgobox-info.png[Helgobox Info, role="related thumb right", float=right]
 
-Shows the version number of this Helgobox installation as well as the ID of the Helgobox instance to which this App window is connected.
+Shows the version number of this Helgobox installation as well as the numeric ID of the Helgobox instance to which this App window is connected.
 

doc/playtime-clip-engine.adoc

@@ -107,7 +107,7 @@ Future versions of the Clip Engine will handle deleted tracks more gracefully.
 As we don't have the Playtime App yet, you need to do this by adjusting Lua code.
 
 . Press _Export to clipboard_ and choose _Export clip matrix as Lua_.
-. Paste the code into a text editor of your choice.
+. Paste the code into a link:https://en.wikipedia.org/wiki/Text_editor[text editor] of your choice.
 . Adjust the code and copy it.
 . Press _Import from clipboard_ and confirm.
 

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

@@ -168,7 +168,7 @@ The clip _stop timing_ is  very similar to the <<clip-start-timing>> but determi
 [[loop]]
 === Loop
 
-In Playtime, a _loop_ is a <<clip>> that is _looped_, which simply means that it seamlessly repeats after it reached its end.
+In Playtime, a _loop_ is a <<clip>> that is _looped_, which simply means that it seamlessly repeats.
 
 [[one-shot]]
 === One-shot
@@ -203,7 +203,7 @@ It helps musicians understand the rhythm and feel of the music.
 The top number of a time signature (the *3* in 3/4) is called _nominator_ and shows the number of beats per measure.
 
 [[time-signature-denominator]]
-The bottom number is called (the *4* in 3/4), _denominator_ and shows the type of note that counts as one <<beat>>.
+The bottom number (the *4* in 3/4)  is called _denominator_ and shows the type of note that counts as one <<beat>>.
 
 [[in-sync]]
 == In sync

doc/playtime/modules/ROOT/pages/user-interface/menus/export-to-clipboard-menu.adoc

@@ -0,0 +1,11 @@
+= Export to clipboard menu
+
+This menu can be found in the xref:helgobox::plug-in/user-interface.adoc[plug-in window].
+
+The following list only describes the Playtime-related menu entries. For the rest, see xref:helgobox::plug-in/user-interface/menu-bar.adoc#export-to-clipboard[] in the Helgobox Reference.
+
+[[export-playtime-matrix-as-json]] Export Playtime matrix as JSON::
+Copies a dump of the xref:key-concepts.adoc#matrix[] (including its settings and contents) to the clipboard in JSON format.
+
+Export Playtime matrix as Lua::
+Like <<export-playtime-matrix-as-json>> but generates Lua/Luau code instead. This can be helpful if you want to xref:advanced-usage-scenarios/generate-matrix.adoc[generate a matrix using code].

doc/playtime/modules/ROOT/pages/user-interface/menus/slot-menu.adoc

@@ -10,4 +10,6 @@ include::partial$generated/menus/slot/clear.adoc[]
 include::partial$generated/menus/slot/import-selected-item.adoc[]
 include::partial$generated/menus/slot/import-files.adoc[]
 include::partial$generated/menus/slot/export-primary-clip-to-arrangement.adoc[]
-include::partial$generated/menus/slot/export-primary-clip-to-clipboard-as-lua.adoc[]
+include::partial$generated/menus/slot/export-primary-clip-to-clipboard-as-lua.adoc[]
+
+This can be helpful if you want to xref:advanced-usage-scenarios/generate-matrix.adoc[generate a matrix using code].

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

@@ -3,7 +3,6 @@
 [[best-practices-input-output,Best practices for setting input and output]]
 == Setting input and output
 
-[qanda]
 Prefer output to a specific device over xref:user-interface/main-panel/input-output-section.adoc#fx-output[]!::
 It's usually better to select a specific output device because sending MIDI feedback to the FX output has drawbacks.
 +
@@ -90,6 +89,7 @@ list].
 Because ReaLearn's xref:further-concepts/compartment.adoc#compartment-parameter[compartment parameters] are freely assignable, they have very generic names by default.
 However, as soon as you give them meaning by using them in a specific way, it can be very helpful to give them a name by using the xref:user-interface/main-panel/menu-bar.adoc#compartment-parameters[].
 
+[[troubleshooting-luau-import]]
 == Troubleshooting Luau import
 
 The way Luau import works in ReaLearn is:

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

@@ -228,7 +228,7 @@ Each ReaLearn compartment contains 100 freely assignable parameters.
 Compartment parameters can be used in the following ways:
 
 * For xref:further-concepts/mapping.adoc#conditional-activation[] (lets the parameter value influence which mappings are active)
-* For xref:further-concepts/target.adoc#dynamic-selector[] (lets the parameter value influence which object (track, FX etc.) is targeted for a specific mapping)
+* For xref:further-concepts/target.adoc#dynamic-selector[] (lets the parameter value influence which object, such as track or FX, is targeted for a specific mapping)
 * As xref:sources/reaper/realearn-parameter.adoc[] (lets the parameter value control any ReaLearn target)
 
 They can be customized as described in xref:user-interface/main-panel/menu-bar.adoc#compartment-parameters[].
@@ -241,7 +241,7 @@ Parameter values will be reset whenever you load a preset (just the ones in that
 By default, <<compartment-parameter,compartment parameters>> have a xref:further-concepts/target.adoc#continuous-value-range[].
 Although that makes them very versatile, it's often easier to work with a xref:further-concepts/target.adoc#discrete-value-range[].
 
-Entering a value count (see xref:user-interface/main-panel/menu-bar.adoc#set-compartment-parameter-value-count[]) makes the parameter have a xref:further-concepts/target.adoc#discrete-value-range[] with the given number of integer values.
+Entering a value count (see xref:user-interface/main-panel/menu-bar.adoc#set-compartment-parameter-value-count[]) turns this into a parameter with a xref:further-concepts/target.adoc#discrete-value-range[], with the given number of integer values.
 For example, a value count of 10 means that the parameter can represent exactly 10 values (0 to 9).
 
 [CAUTION]

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

@@ -8,7 +8,7 @@ ReaLearn can import and export data in 2 formats:
 
 link:https://www.json.org/json-en.html[JSON]::
 A wide-spread data exchange format.
-It's a text format, so if you are familiar with the search & replace feature of your favorite text editor, this is one way to do batch editing.
+It's a text format, so if you are familiar with the search & replace feature of your favorite link:https://en.wikipedia.org/wiki/Text_editor[text editor], this is one way to do batch editing.
 
 link:https://luau.org/[Luau]::
 A full-blown programming language derived from the famous Lua language that is also used in REAPER itself.

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

@@ -3,12 +3,12 @@
 [[auto-units]]
 == Auto units
 
-Each xref:helgobox:ROOT:key-concepts.adoc#instance[] optionally supports the automatic addition and configuration of a xref:key-concepts.adoc#unit[] with a user-defined main preset if a certain type of controller is connected and automatic removal if it is disconnected.
+Each xref:key-concepts.adoc#instance[] optionally supports the automatic addition and configuration of a xref:key-concepts.adoc#unit[] with a user-defined xref:further-concepts/compartment.adoc#main-preset[] if a certain type of controller is connected, and automatic removal if it is disconnected.
 
 The general procedure is:
 
-. Globally define once what controllers you have at your disposal and choose which main preset you want to use for which controller (in the xref:user-interface/settings-dialog.adoc[] of the app)
-. Enable global control for one Helgobox instance using xref:user-interface/main-panel/menu-bar.adoc#enable-global-control[].
+. Globally define once what controllers you have at your disposal and choose which main preset you want to use for which controller (in the xref:user-interface/settings-dialog.adoc[] of the xref:helgobox::app.adoc[])
+. Enable global control for one xref:key-concepts.adoc#instance[] using xref:user-interface/main-panel/menu-bar.adoc#enable-global-control[].
 
 === Global control
 

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

@@ -293,14 +293,13 @@ This was the default behavior for ReaLearn versions up to 1.11.0 and is just kep
 
 IMPORTANT: **This selector is deprecated!** You shouldn't use it anymore.
 
-[[sticky-selectors]]
-=== Sticky selectors
+=== Sticky vs. non-sticky selectors
 
 We call object selectors _sticky_ if they refer to a particular object (e.g. a track).
 
-Sticky selectors:: `<Master>`, `<This>`, `Particular`
+[[sticky-selectors]] Sticky selectors:: `<Master>`, `<This>`, `Particular`
 
-Non-sticky selectors:: `<Dynamic>`, `<Focused>`, `<Selected>`, `<Unit>`, `<All selected>`, `Named`, `All named`, `At position`, `From Playtime column`
+[[non-sticky-selectors]] Non-sticky selectors:: `<Dynamic>`, `<Focused>`, `<Selected>`, `<Unit>`, `<All selected>`, `Named`, `All named`, `At position`, `From Playtime column`
 
 [[target-property]]
 == Target property

doc/realearn/modules/ROOT/pages/reaper-actions.adoc

@@ -20,5 +20,5 @@ This is great for subsequent fine-tuning.
 
 Helgobox/ReaLearn: Learn source for last touched target (reassigning target):: This behaves similar to REAPER's built-in MIDI learn in that it always relates to the target that has been touched last.
 
-Helgobox/ReaLearn: Send feedback for all instances:: Makes each ReaLearn instance/unit in all project tabs send feedback for all mappings.
+[[send-feedback-for-all-instances]] Helgobox/ReaLearn: Send feedback for all instances:: Makes each ReaLearn instance/unit in all project tabs send feedback for all mappings.
 That shouldn't be necessary most of the time because ReaLearn usually sends feedback automatically, but there are situations when it might come in handy.

doc/realearn/modules/ROOT/pages/user-interface/main-panel/input-output-section.adoc

@@ -14,7 +14,7 @@ ReaLearn works with MIDI or OSC input.
 In addition, it can listen to keyboard input.
 
 [[fx-input]] MIDI: <FX input>::
-When selected, ReaLearn captures all MIDI events that flow into this ReaLearn VSTi FX instance (= track MIDI path).
+When selected, ReaLearn captures all MIDI events that flow into this ReaLearn VSTi FX instance, for example coming from track MIDI items, track MIDI receives or the track input.
 This is the default selection.
 
 MIDI: _Some input device_::
@@ -35,7 +35,7 @@ This submenu contains OSC devices for which control is currently disabled.
 
 
 [[manage-osc-devices]] Manage OSC devices::
-Allows one to display and modify the list of OSC devices (globally).
+Lets you display and modify the list of OSC devices (globally).
 
 <New>:::
 Opens a dialog window for adding a new OSC device.
@@ -44,13 +44,15 @@ See <<osc-device-dialog>>.
 _Some OSC device_:::
 
 Edit::::
-Lets you edit an existing device.
+Lets you edit the device.
 See <<osc-device-dialog>>.
 
 Remove::::
 Removes the device.
 This is a global action.
 If you remove a device, all existing ReaLearn instances which use this device will point to a device that doesn't exist anymore.
++
+CAUTION: This can't be undone!
 
 Enabled for control:::: If you disable this, ReaLearn will stop listening to this device.
 This can save resources, so you should do this with each device that is not in use (as an alternative for removing it forever).
@@ -87,8 +89,10 @@ This is the default.
 
 [[fx-output]] MIDI: <FX output>::
 This makes feedback MIDI events stream down to the next FX in the chain or to the track's hardware MIDI output.
++
+CAUTION: Under normal circumstances, it is better to use <<midi-some-output-device, select a specific output device>> instead. See xref:best-practices.adoc#best-practices-input-output[].
 
-MIDI: _Some output device_::
+[[midi-some-output-device]] MIDI: _Some output device_::
 If selected, ReaLearn will send feedback to the given MIDI output device.
 This only works if _Enable output to this device_ is checked in REAPER's preferences (menu:Options[Settings > MIDI Outputs]).