#1256 Docs: Convert single-page ReaLearn Reference into Antora component

using custom-made asciidoc-file-splitter

doc/realearn/antora.yml

@@ -0,0 +1,10 @@
+name: realearn
+title: ReaLearn
+version: 1.0
+nav:
+  - modules/ROOT/nav.adoc
+start_page: introduction.adoc
+asciidoc:
+  attributes:
+    # For making menu and button macros work
+    experimental: true

doc/realearn/modules/ROOT/nav.adoc

@@ -0,0 +1,139 @@
+* xref:introduction.adoc[]
+* xref:key-concepts.adoc[]
+* xref:user-interface.adoc[]
+** xref:user-interface/main-panel.adoc[]
+*** xref:user-interface/main-panel/inputoutput-section.adoc[]
+*** xref:user-interface/main-panel/menu-bar.adoc[]
+*** xref:user-interface/main-panel/let-through-checkboxes.adoc[]
+*** xref:user-interface/main-panel/show-buttons.adoc[]
+*** xref:user-interface/main-panel/preset-section.adoc[]
+*** xref:user-interface/main-panel/mapping-group-section.adoc[]
+*** xref:user-interface/main-panel/notes-button.adoc[]
+*** xref:user-interface/main-panel/mappings-toolbar.adoc[]
+*** xref:user-interface/main-panel/mapping-row.adoc[]
+*** xref:user-interface/main-panel/bottom-area.adoc[]
+** xref:user-interface/mapping-panel.adoc[]
+*** xref:user-interface/mapping-panel/general-section.adoc[]
+*** xref:user-interface/mapping-panel/advanced-settings-dialog.adoc[]
+*** xref:user-interface/mapping-panel/source-section.adoc[]
+*** xref:user-interface/mapping-panel/target-section.adoc[]
+*** xref:user-interface/mapping-panel/glue-section.adoc[]
+*** xref:user-interface/mapping-panel/bottom-section.adoc[]
+* xref:source-types.adoc[]
+** xref:source-types/category-none.adoc[]
+** xref:source-types/category-midi.adoc[]
+*** xref:source-types/category-midi/cc-value-source.adoc[]
+*** xref:source-types/category-midi/note-velocity-source.adoc[]
+*** xref:source-types/category-midi/note-number-source.adoc[]
+*** xref:source-types/category-midi/pitch-wheel-source.adoc[]
+*** xref:source-types/category-midi/channel-after-touch-source.adoc[]
+*** xref:source-types/category-midi/program-change-source.adoc[]
+*** xref:source-types/category-midi/nrpn-value-source.adoc[]
+*** xref:source-types/category-midi/polyphonic-after-touch-source.adoc[]
+*** xref:source-types/category-midi/midi-clock-tempo-source.adoc[]
+*** xref:source-types/category-midi/midi-clock-transport-source.adoc[]
+*** xref:source-types/category-midi/raw-midi-sysex-source.adoc[]
+*** xref:source-types/category-midi/midi-script-source.adoc[]
+*** xref:source-types/category-midi/display.adoc[]
+*** xref:source-types/category-midi/specific-program-change.adoc[]
+** xref:source-types/category-osc.adoc[]
+** xref:source-types/category-keyboard.adoc[]
+** xref:source-types/category-reaper.adoc[]
+*** xref:source-types/category-reaper/midi-device-changes-source.adoc[]
+*** xref:source-types/category-reaper/realearn-unit-start-source.adoc[]
+*** xref:source-types/category-reaper/timer-source.adoc[]
+*** xref:source-types/category-reaper/realearn-parameter.adoc[]
+*** xref:source-types/category-reaper/speech-source.adoc[]
+** xref:source-types/category-virtual.adoc[]
+* xref:target-types.adoc[]
+** xref:target-types/global-targets.adoc[]
+*** xref:target-types/global-targets/global-last-touched.adoc[]
+*** xref:target-types/global-targets/global-mouse-target.adoc[]
+*** xref:target-types/global-targets/global-set-automation-mode-override.adoc[]
+** xref:target-types/project-targets.adoc[]
+*** xref:target-types/project-targets/project-any-on-solomute82308203.adoc[]
+*** xref:target-types/project-targets/project-invoke-reaper-action.adoc[]
+*** xref:target-types/project-targets/project-invoke-transport-action.adoc[]
+*** xref:target-types/project-targets/project-browse-tracks.adoc[]
+*** xref:target-types/project-targets/project-seek.adoc[]
+*** xref:target-types/project-targets/project-set-playrate.adoc[]
+*** xref:target-types/project-targets/project-set-tempo.adoc[]
+** xref:target-types/markerregion-targets.adoc[]
+*** xref:target-types/markerregion-targets/markerregion-go-to.adoc[]
+** xref:target-types/track-targets.adoc[]
+*** xref:target-types/track-targets/track.adoc[]
+*** xref:target-types/track-targets/track-armdisarm.adoc[]
+*** xref:target-types/track-targets/track-enabledisable-all-fx.adoc[]
+*** xref:target-types/track-targets/track-enabledisable-parent-send.adoc[]
+*** xref:target-types/track-targets/track-muteunmute.adoc[]
+*** xref:target-types/track-targets/track-peak.adoc[]
+*** xref:target-types/track-targets/track-phase-invertnormal.adoc[]
+*** xref:target-types/track-targets/track-selectunselect.adoc[]
+*** xref:target-types/track-targets/track-set-automation-mode.adoc[]
+*** xref:target-types/track-targets/track-set-monitoring-mode.adoc[]
+*** xref:target-types/track-targets/track-set-automation-touch-state.adoc[]
+*** xref:target-types/track-targets/track-set-pan.adoc[]
+*** xref:target-types/track-targets/track-set-stereo-pan-width.adoc[]
+*** xref:target-types/track-targets/track-set-volume.adoc[]
+*** xref:target-types/track-targets/track-showhide.adoc[]
+*** xref:target-types/track-targets/track-solounsolo.adoc[]
+*** xref:target-types/track-targets/fx-chain-browse-fxs.adoc[]
+** xref:target-types/fx-targets.adoc[]
+*** xref:target-types/fx-targets/fx.adoc[]
+*** xref:target-types/fx-targets/fx-enabledisable.adoc[]
+*** xref:target-types/fx-targets/fx-set-onlineoffline.adoc[]
+*** xref:target-types/fx-targets/fx-load-snapshot.adoc[]
+*** xref:target-types/fx-targets/fx-browse-presets.adoc[]
+*** xref:target-types/fx-targets/fx-openclose.adoc[]
+** xref:target-types/fx-parameter-targets.adoc[]
+*** xref:target-types/fx-parameter-targets/fx-parameter-set-automation-touch-state.adoc[]
+*** xref:target-types/fx-parameter-targets/fx-parameter-set-value.adoc[]
+** xref:target-types/pot-targets.adoc[]
+*** xref:target-types/pot-targets/pot-browse-filter-items.adoc[]
+*** xref:target-types/pot-targets/pot-browse-presets.adoc[]
+*** xref:target-types/pot-targets/pot-preview-preset.adoc[]
+*** xref:target-types/pot-targets/pot-load-preset.adoc[]
+** xref:target-types/sendreceive-targets.adoc[]
+*** xref:target-types/sendreceive-targets/send-automation-mode.adoc[]
+*** xref:target-types/sendreceive-targets/send-monostereo.adoc[]
+*** xref:target-types/sendreceive-targets/send-muteunmute.adoc[]
+*** xref:target-types/sendreceive-targets/send-phase-invertnormal.adoc[]
+*** xref:target-types/sendreceive-targets/send-set-automation-touch-state.adoc[]
+*** xref:target-types/sendreceive-targets/send-set-pan.adoc[]
+*** xref:target-types/sendreceive-targets/send-set-volume.adoc[]
+** xref:target-types/playtime-targets.adoc[]
+*** xref:target-types/playtime-targets/playtime-slot-management-action.adoc[]
+*** xref:target-types/playtime-targets/playtime-slot-transport-action.adoc[]
+*** xref:target-types/playtime-targets/playtime-slot-seek.adoc[]
+*** xref:target-types/playtime-targets/playtime-slot-volume.adoc[]
+*** xref:target-types/playtime-targets/playtime-column-action.adoc[]
+*** xref:target-types/playtime-targets/playtime-row-action.adoc[]
+*** xref:target-types/playtime-targets/playtime-matrix-action.adoc[]
+*** xref:target-types/playtime-targets/playtime-control-unit-scroll.adoc[]
+*** xref:target-types/playtime-targets/playtime-browse-cells.adoc[]
+** xref:target-types/midi-targets.adoc[]
+*** xref:target-types/midi-targets/midi-send-message-target.adoc[]
+** xref:target-types/osc-targets.adoc[]
+*** xref:target-types/osc-targets/osc-send-message.adoc[]
+** xref:target-types/realearn-targets.adoc[]
+*** xref:target-types/realearn-targets/realearn-enabledisable-instances.adoc[]
+*** xref:target-types/realearn-targets/realearn-dummy-target.adoc[]
+*** xref:target-types/realearn-targets/realearn-enabledisable-mappings.adoc[]
+*** xref:target-types/realearn-targets/realearn-load-mapping-snapshot.adoc[]
+*** xref:target-types/realearn-targets/realearn-modify-mapping.adoc[]
+*** xref:target-types/realearn-targets/realearn-take-mapping-snapshot.adoc[]
+*** xref:target-types/realearn-targets/realearn-browse-group-mappings.adoc[]
+** xref:target-types/virtual-target.adoc[]
+* xref:further-concepts.adoc[]
+** xref:further-concepts/general-concepts.adoc[]
+** xref:further-concepts/instance-concepts.adoc[]
+** xref:further-concepts/unit-concepts.adoc[]
+** xref:further-concepts/compartment-concepts.adoc[]
+** xref:further-concepts/mapping-concepts.adoc[]
+** xref:further-concepts/glue-concepts.adoc[]
+** xref:further-concepts/target-concepts.adoc[]
+** xref:further-concepts/source-concepts.adoc[]
+* xref:best-practices.adoc[]
+* xref:provided-reaper-actions.adoc[]
+* xref:configuration-files.adoc[]
+* xref:design-decisions.adoc[]

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

@@ -0,0 +1,109 @@
+[appendix]
+= Best practices
+
+[[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/inputoutput-section.adoc#fx-output[]!::
+It's usually better to select a specific output device because sending MIDI feedback to the FX output has drawbacks.
++
+First, it doesn't participate in ReaLearn's multi-unit feedback orchestration.
+That means you might experience misbehaving LEDs/faders/displays when using multiple units.
++
+Second, it doesn't work if ReaLearn FX is suspended, e.g. in the following cases:
+
+* ReaLearn FX is disabled.
+* Project is paused and ReaLearn track is not armed.
+* ReaLearn FX is on input FX chain and track is not armed.
+
+[[using-the-controller-compartment]]
+== Using the controller compartment
+
+The xref:key-concepts.adoc#controller-compartment[] lets you describe a xref:key-concepts.adoc#controller[] simply by adding xref:key-concepts.adoc#mapping[mappings].
+When you do that, each xref:key-concepts.adoc#controller-mapping[] represents a xref:key-concepts.adoc#control-element[] on your xref:key-concepts.adoc#controller[], e.g. a xref:further-concepts/mapping-concepts.adoc#momentary-button[] or xref:further-concepts/mapping-concepts.adoc#fader[].
+
+Describing your controller is optional but it brings benefits:
+
+* You can use the xref:further-concepts/unit-concepts.adoc#projection[] feature to project your controller mapping to a smartphone or tablet (link:https://www.youtube.com/watch?v=omuYBznEShk&feature=youtu.be[watch video]).
+* You can use xref:further-concepts/compartment-concepts.adoc#controller-preset[controller presets] either built-in ones or those made by other users ... and thereby save precious setup time.
+Or you can contribute them yourself!
+* You can make your xref:key-concepts.adoc#main-mapping[main mappings] independent of the actually used xref:key-concepts.adoc#controller[].
+This is done using xref:key-concepts.adoc#virtual-source[virtual sources] and xref:key-concepts.adoc#virtual-target[virtual targets].
+* It allows you to give your knobs, buttons etc. descriptive and friendly names instead of just e.g. "CC 15".
+* You don't need to learn your <<control-element, control elements> again and again.
+Although the process of learning an element is easy in ReaLearn, it can take some time in case the xref:further-concepts/source-concepts.adoc#midi-source-character[] is not guessed correctly.
+Just do it once and be done with it!
+
+If you want to make ReaLearn "learn" about your nice controller device, all you need to do is to create a suitable controller mapping for each of its control elements.
+
+Let's first look at the "slow" way to do this - adding and editing each controller mapping one by one:
+
+. Press the xref:user-interface/main-panel/mappings-toolbar.adoc#add-one-button[].
+. Learn the xref:key-concepts.adoc#source[] by pressing the xref:user-interface/main-panel/mapping-row.adoc#row-learn-source-button[] and touching the control element.
+. Press the xref:user-interface/main-panel/mapping-row.adoc#row-edit-button[].
+. Enter a descriptive name for the xref:key-concepts.adoc#control-element[].
++
+TIP: This name will appear in many places so you want it to be short, clear and unique!
+. Assign a unique xref:key-concepts.adoc#virtual-target[].
+** At this point we don't want to assign a xref:key-concepts.adoc#real-target[] yet.
+The point of xref:further-concepts/compartment-concepts.adoc#controller-preset[controller presets] is to make them as reusable as possible, that's why we choose a xref:key-concepts.adoc#virtual-target[].
+** In the _Category_ dropdown, choose _Virtual_.
+** As _Type_, choose xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-button[] if your control element is a sort of button (something which you can press) or xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-multi[] in all other cases.
+** Use for each xref:key-concepts.adoc#control-element[] a unique combination of xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type[] and xref:further-concepts/compartment-concepts.adoc#virtual-control-element-id[], starting with number *1* and counting.
++
+TIP: It's okay and desired to have one control element mapped to "Multi 1" and one to "Button 1".
+** Just imagine the "8 generic knobs + 8 generic buttons" layout which is typical for lots of popular controllers.
+You can easily model that by assigning 8 multis and 8 buttons.
+** Maybe you have realized that the xref:user-interface/mapping-panel/glue-section.adoc#glue-section[] is available for controller mappings as well!
+That opens up all kinds of possibilities.
+You could for example restrict the target range for a certain control element.
+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[]!
+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!
+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[].
+. Choose whether you want to learn all the xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-multi[] elements on your xref:key-concepts.adoc#controller[] or all the xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-button[] elements.
+. Simply touch all relevant xref:key-concepts.adoc#control-element[control elements] in the desired order.
+ReaLearn will take care of automatically incrementing the xref:further-concepts/compartment-concepts.adoc#virtual-control-element-id[].
+. Press btn:[Stop].
+. Done!
+** At this point it's recommended to recheck the learned mappings.
+** ReaLearn's xref:further-concepts/source-concepts.adoc#midi-source-character[] detection for MIDI CCs is naturally just a guess, so it can be wrong.
+If so, just adjust the character in the corresponding xref:user-interface/mapping-panel.adoc#mapping-panel[].
+
+You can share your preset with other users by sending them to link:mailto:&#105;&#110;&#102;&#x6f;&#x40;&#104;&#101;&#108;&#103;&#x6f;&#98;&#111;&#115;&#x73;&#46;&#111;&#x72;&#103;[&#105;&#110;&#102;&#x6f;&#x40;&#104;&#101;&#108;&#103;&#x6f;&#98;&#111;&#115;&#x73;&#46;&#111;&#x72;&#103;].
+I will add it to https://github.com/helgoboss/helgobox/tree/master/resources/controller-presets[this
+list].
+
+== Naming compartment parameters
+
+Because ReaLearn's xref:further-concepts/compartment-concepts.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-menu[].
+
+== Troubleshooting Luau import
+
+The way Luau import works in ReaLearn is:
+
+. ReaLearn attempts to execute the Luau script in the clipboard.
+. ReaLearn attempts to interpret the returned value as ReaLearn API object.
+. ReaLearn loads the API object
+
+If step 1 fails, ReaLearn displays an error messages that hopefully contains a line number.
+If step 2 fails, ReaLearn shows a validation error message.
+
+If importing Luau code fails and the displayed error message is not helpful, you can try xref:user-interface/main-panel/menu-bar.adoc#dry-run-lua-script[].
+This action enables you to just execute step 1 and see the "expanded" result.
+This can help to make sense of a possible validation error message in step 2.
+
+[appendix]

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

@@ -0,0 +1,39 @@
+[appendix]
+= Configuration files
+
+ReaLearn creates and/or reads a few files in REAPER's resource directory.
+
+[cols="m,1"]
+|===
+
+| File | Description
+
+| Data/helgoboss | Directory which contains data such as presets or resources that need to be 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/archives | Directory which contains archives e.g. the compressed app, distributed via ReaPack
+
+| Data/helgoboss/doc | Contains offline documentation, e.g. this guide as PDF
+
+| Data/helgoboss/presets/controller | Contains preset for the controller compartment
+
+| Data/helgoboss/presets/main | Contains preset for the main compartment
+
+| Helgoboss | Directory which contains rather personal or device-specific data, not touched via ReaPack
+
+| licensing.json | Contains license keys
+
+| 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.
+
+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.
+
+|===