#1256 Docs: Move Helgobox installation instructions to Helgobox refer…

…ence

README.adoc

@@ -12,137 +12,29 @@ image:https://github.com/helgoboss/helgobox/actions/workflows/linux-armv7.yml/ba
 image:https://img.shields.io/badge/license-GPL-blue.svg[GitHub license,link=https://raw.githubusercontent.com/helgoboss/realearn/master/LICENSE]
 image:https://img.shields.io/badge/Donate-PayPal-orange.svg[Donate,link=https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=9CTAK2KKA8Z2S&source=url]
 
-Helgobox is a suite that unites multiple creative link:https://www.reaper.fm[REAPER] tools by Helgoboss.
+Helgobox is a link:https://www.reaper.fm[REAPER] plug-in that unites multiple creative products by link:https://www.helgoboss.org[Helgoboss].
 It currently contains link:https://www.helgoboss.org/projects/realearn[ReaLearn] (a versatile controller integration tool, free) and
 link:https://www.helgoboss.org/projects/playtime[Playtime] (a modern session view, paid).
 
 == Installation
 
-Helgobox is provided as https://reapack.com/[ReaPack] package, which is great because it allows you to keep your installation up-to-date very easily.
-
-There are multiple ways to carry out the initial installation.
-
-=== Install automatically via ReaBoot
-
-The easiest way to install Helgobox is via the following ReaBoot link: link:https://reaboot.com/install/https%3A%2F%2Fraw.githubusercontent.com%2Fhelgoboss%2Fhelgobox%2Fmaster%2Freaboot.json[Install Helgobox]
-
-=== Install manually via ReaPack
-
-As an alternative, you can install Helgobox via ReaPack directly:
-
-. Install https://reapack.com/[ReaPack] if not done so already
-. Extensions → ReaPack → Import repositories…
-. Copy and paste the following repository URL:
-+
- https://github.com/helgoboss/reaper-packages/raw/master/index.xml
-+
-. Extensions → ReaPack → Browse packages…
-. Search for `helgobox`
-. Right mouse click on the Helgobox package → Install…
-. OK or Apply
-. Restart REAPER
-
-=== Install manually without ReaPack
-
-If you are more the download type of person, you can find the latest `dll`, `dylib` and `so` files here at GitHub on the https://github.com/helgoboss/helgobox/releases[releases page] for manual installation.
-
-You also must install Helgobox manually if you plan to use it in both REAPER for Windows 32-bit and REAPER for Windows 64-bit because then it's important to use two separate VST plug-in directories.
-
-*Please note that it's impossible to run Helgobox as a bridged plug-in.* If you have "Preferences → Plug-ins → Compatibility → VST bridging/firewalling" set to "In separate plug-in process" or "In dedicated process per plug-in", you will need to add an exception for Helgobox by setting "Run as" to "Native only"!
-
-=== Update to the latest stable version
-
-Helgobox development moves fast.
-In order to take advantage of new features, improvements and fixes, you should check for updates from time to time.
-
-. Extensions → ReaPack → Synchronize packages
-** It will tell you if a new version has been installed.
-. Restart REAPER
-
-=== Important note for Linux users
-
-- You also need `libxdo` installed, otherwise ReaLearn won't scan.
-- Debian/Ubuntu: `sudo apt-get install -y libxdo-dev`
-
-=== Test new features and improvements
-
-If you want to get access to cutting-edge but untested versions of Helgobox, you have two options:
-
-Install a specific pre-release:
-
-. Right mouse click on the Helgobox package → Versions
-. Select any version ending on `-pre.*` or `-rc.*`
-. OK or Apply
-. Restart REAPER
-
-Enable pre-releases globally:
-
-. Extensions → ReaPack → Manage repositories → Options… → Enable pre-releases globally (bleeding edge)
-. After that, whenever you synchronize packages, you will get the latest stuff.
+See section link:https://docs.helgoboss.org/helgobox/installation.html[Installation] of the Helgobox Reference.
 
 == Usage
 
-=== Quick start
-
-Helgobox is fired up just like any other VST instrument in REAPER: By adding it to an FX chain.
-
-Initially, you see the Helgobox plug-in, which mainly provides the ReaLearn user interface:
-
-.Main panel (containing the list of mappings)
-image::doc/realearn/modules/ROOT/images/realearn/screenshots/main-panel.png[]
-
-.Mapping panel (for editing one particular mapping)
-image::doc/realearn/modules/ROOT/images/realearn/screenshots/mapping-panel.png[]
-
-But there's also the Helgobox app, which mainly provides the Playtime user interface.
-You can open it either from the plug-in's menu or by using the convenient "Playtime" button in the main toolbar.
-
-[#videos]
-=== Videos
-
-==== ReaLearn
-
-link:https://www.youtube.com/watch?v=4ySGt9Ejc-M&list=PL0bFMT0iEtAgKY2BUSyjEO1I4s20lZa5G&index=1[The ReaLearn Tutorials] is a fairly new ongoing series of short video tutorials available.
-
-There's also a long https://www.youtube.com/watch?v=dUPyqYaIkYA[introduction video] from 2021. Watch 2 minutes to get a first impression and stay tuned if you are interested in the details.
+See section link:https://docs.helgoboss.org/helgobox/usage.html[Usage] of the Helgobox Reference.
 
-=== User guide
+== Documentation
 
-==== ReaLearn
+We have:
 
-ReaLearn features a large and complete user guide.
-
-- https://github.com/helgoboss/helgobox/blob/master/doc/realearn-user-guide.adoc[Read it right here on GitHub] (preferred, best readability)
-- https://github.com/helgoboss/helgobox/releases/latest/download/realearn-user-guide.pdf[Download user guide as PDF file]
-
-TIP: The main focus of ReaLearn's user guide is being comprehensive, so it's more like a reference manual and can get quite detailed and technical.
-If you prefer a simple hands-on approach, the <<videos,tutorial videos>> are a better choice.
-
-=== Supported controllers
-
-ReaLearn is designed to be generic and support any controller.
-That's why you won't find a definitive list of supported controllers!
-But there's a link:doc/controllers.adoc[list of tested controllers].
-
-TIP: Keep in mind: Even if your controller is not on the list, you probably can make it work with ReaLearn!
-
-=== Available presets
-
-- link:https://github.com/helgoboss/helgobox/tree/master/resources/controller-presets[Controller presets]
-- link:https://github.com/helgoboss/helgobox/tree/master/resources/main-presets[Main presets]
+- link:https://github.com/helgoboss/helgobox/wiki[Helgobox Wiki] (suitable for beginners, includes links to video tutorials)
+- link:https://docs.helgoboss.org[Helgoboss Docs website] (extensive references, includes PDF downloads)
 
 == Architecture
 
 See link:ARCHITECTURE.adoc[architecture documentation].
 
 == Contributing
 
-See link:CONTRIBUTING.adoc[contributing documentation].
-
-== Links
-
-* https://www.helgoboss.org/projects/realearn/[Website]
-* http://forum.cockos.com/showthread.php?t=178015[Forum] (dedicated thread in REAPER forum)
-* https://github.com/helgoboss/helgobox/issues[Issue tracker]
-* https://bitbucket.org/helgoboss/realearn/issues[Old issue tracker] (for ReaLearn &lt; v1.10.0)
-* https://github.com/helgoboss/realearn-companion[ReaLearn Companion app]
+See link:CONTRIBUTING.adoc[contributing documentation].

doc/helgobox/README.adoc

@@ -0,0 +1,6 @@
+= Helgobox Reference
+:experimental:
+
+This reference is written in AsciiDoc and follows the directory conventions of the documentation site generator link:https://antora.org/[Antora].
+
+A good place to start is link:modules/ROOT/pages/introduction.adoc[].

doc/helgobox/antora.yml

@@ -0,0 +1,12 @@
+name: helgobox
+title: Helgobox Reference
+version: ~
+nav:
+  - modules/ROOT/nav.adoc
+start_page: introduction.adoc
+asciidoc:
+  attributes:
+    # For making menu and button macros work
+    experimental: true
+    # For showing prev/next links
+    page-pagination: ''

doc/helgobox/modules/ROOT/nav.adoc

@@ -0,0 +1,3 @@
+* xref:introduction.adoc[]
+* xref:installation.adoc[]
+* xref:usage.adoc[]

doc/helgobox/modules/ROOT/pages/installation.adoc

@@ -0,0 +1,120 @@
+= Installation
+
+REAPER fans will be glad to know that Helgobox is provided as a https://reapack.com/[ReaPack] package.
+ReaPack is a popular 3rd-party package manager for REAPER that makes installing add-ons easy and keeps your installation up to date effortlessly.
+
+== Installing Helgobox
+
+Please choose:
+
+[loweralpha]
+. <<just-give-me-helgobox>>
+. <<i-have-reapack>>
+. <<i-want-to-install-reapack>>
+. <<install-without-reapack>>
+
+[[just-give-me-helgobox]]
+=== I don't have ReaPack. Just give me Helgobox already!
+
+For users who don't have ReaPack installed already, there's a **convenient installer** that automatically installs both ReaPack and Helgobox.
+It gets you up and running in no time!
+
+Simply press the following link and follow the instructions: link:https://reaboot.com/install/https%3A%2F%2Fraw.githubusercontent.com%2Fhelgoboss%2Fhelgobox%2Fmaster%2Freaboot.json[Install Helgobox]
+
+[WARNING]
+.The installer is currently in beta!
+====
+If you encounter any issues, please visit <<i-want-to-install-reapack>>.
+Report any installer problems to [email protected].
+Thank you!
+====
+
+==== Known issues
+
+Installer shows error "no column found for name: flags"::
+It's an issue related to having an older ReaPack version installed.
+I need to look into it.
+Because this means that you have ReaPack installed already, a simple workaround is to follow the instructions in <<i-have-reapack>>.
+
+[[i-have-reapack]]
+=== I have ReaPack
+
+Here's how you can install Helgobox via ReaPack:
+
+. In REAPER, select menu:Extensions[ReaPack > Import repositories…]
+. Copy and paste the following repository URL into the text area:
++
+ https://github.com/helgoboss/reaper-packages/raw/master/index.xml
++
+. Select menu:Extensions[ReaPack > Browse packages…]
+. Search for `helgobox`
+. Right mouse click on the Helgobox package and choose menu:Install…[]
+. Press btn:[OK] or btn:[Apply]
+. Restart REAPER
+
+[[i-want-to-install-reapack]]
+=== I want to install via ReaPack but don't have it yet
+
+. Install ReaPack, following the link:https://reapack.com/user-guide[installation section of its user guide]
+. Restart REAPER
+. Follow the instructions in <<i-have-reapack>>
+
+[[install-without-reapack]]
+=== I want to install Helgobox manually, without ReaPack
+
+If you are more the download type of person, you can find the latest `dll`, `dylib` and `so` files here at GitHub on the https://github.com/helgoboss/helgobox/releases[releases page] for manual installation.
+
+You also must install Helgobox manually if you plan to use it in both REAPER for Windows 32-bit and REAPER for Windows 64-bit because then it's important to use two separate VST plug-in directories.
+
+== Validating the installation
+
+You know that Helgobox is installed successfully if you see the menu menu:Extensions[Helgobox].
+
+In addition, there should be a plug-in entry "VSTi: Helgobox - ReaLearn & Playtime (Helgoboss)" when right-clicking the empty area of REAPER's track panel and choosing menu:Insert virtual instrument on new track...[].
+
+NOTE: On Helgobox for Linux, the extension menu entry doesn't exist yet.
+But the plug-in should be there.
+
+== Troubleshooting
+
+=== Helgobox plug-in doesn't appear in the list of plug-ins
+
+If the Helgobox plug-in doesn't appear in the list of plug-ins, please proceed as follows:
+
+. If you are on Linux, make sure that `libxdo` is installed!
+** On Debian/Ubuntu: `sudo apt-get install -y libxdo-dev`
+
+. Make sure that Helgobox runs as native plug-in!
+** By default, each plug-in runs as native plug-in.
+If not, you probably changed the configuration at some point.
+** You can fix that by right-clicking Helgobox in the plug-in list and select menu:Run as[Native only (prevent bridging)].
+** It's technically impossible to run Helgobox as a bridged plug-in!
+
+== Updating Helgobox
+
+Helgobox development moves fast!
+In order to take advantage of latest features, improvements and fixes, you should check the link:https://www.helgoboss.org/projects/helgobox[Helgobox page] for updates from time to time.
+
+Here's how you can install the latest stable Helgobox version:
+
+. Run menu:Extensions[ReaPack > Synchronize packages]
+** ReaPack will show you a summary at the end, which tells you whether a new Helgobox version has been installed.
+. Restart REAPER
+
+== Testing new features and improvements
+
+If you want to get access to cutting-edge but untested versions of Helgobox, you can install Helgobox pre-releases.
+
+=== Install a specific pre-release of Helgobox
+
+. menu:Extensions[ReaPack > Browse packages...]
+. Right-click the Helgobox package and navigate to the submenu menu:Versions[]
+. Select the desired pre-release version (versions containing `-pre` or `-rc`)
+. Press btn:[OK] or btn:[Apply]
+. Restart REAPER
+
+=== Enable pre-releases globally
+
+. menu:Extensions[ReaPack > Manage repositories]
+. menu:Options…[Enable pre-releases globally (bleeding edge)]
+. After that, whenever you synchronize packages, you will get the latest stuff.

doc/helgobox/modules/ROOT/pages/introduction.adoc

@@ -0,0 +1,9 @@
+= Introduction
+
+link:https://www.helgoboss.org/projects/helgobox[Helgobox] is an instrument plug-in for REAPER that unites the products link:https://www.helgoboss.org/projects/realearn[ReaLearn] and link:https://www.helgoboss.org/projects/playtime[Playtime] under one roof.
+
+In addition to the plug-in, it comes with the Helgobox App, a modern user interface for the Helgobox Instrument.
+It runs embedded in REAPER and in the future also as a separate mobile app (iOS, Android).
+
+The reference of Helgobox itself is mainly about its installation process.
+If you want to learn more about the contained products, please refer to the link:https://docs.helgoboss.org/realearn[ReaLearn Reference] or link:https://docs.helgoboss.org/playtime[Playtime Reference].

doc/helgobox/modules/ROOT/pages/usage.adoc

@@ -0,0 +1,32 @@
+= Usage
+
+This section illustrates absolute basics of using Helgobox. For more information, please refer to the link:https://docs.helgoboss.org/realearn[ReaLearn Reference] or link:https://docs.helgoboss.org/playtime[Playtime Reference].
+
+== Add plug-in instance
+
+Helgobox is fired up just like any other VST instrument in REAPER: By adding an instance of it to an FX chain:
+
+. Right-click the empty space in REAPER's track control panel
+. Select menu:Insert virtual instrument on new track...[]
+. Double-click entry "VSTi: Helgobox - ReaLearn & Playtime (Helgoboss)"
+
+Initially, you see the Helgobox instrument plug-in, which primarily provides the user interface for link:https://www.helgoboss.org/projects/realearn[ReaLearn]:
+
+.Plug-in window
+image::images/helgobox/screenshots/plugin-window.png[]
+
+== Show the Helgobox App
+
+Helgobox also provides an App, which primarily provides the user interface for link:https://www.helgoboss.org/projects/playtime[Playtime].
+Each Helgobox instance can display its own App window, embedded into REAPER:
+
+. Open the Helgobox instrument plug-in
+. Press menu:Menu[Show App]
+
+.App window
+image::images/helgobox/screenshots/app-window.png[]
+
+As an alternative, you can use the convenient btn:[Playtime] button in REAPER's main toolbar. If you don't see it, do this:
+
+. Select menu:Extensions[Helgobox > Show welcome screen]
+. Check "Add Playtime button to main toolbar"

doc/realearn/modules/ROOT/pages/introduction.adoc

@@ -13,7 +13,7 @@ This reference provides a detailed description of ReaLearn's user interface, con
 [IMPORTANT]
 ====
 
-**If you are a beginner, please use the link:https://github.com/helgoboss/helgobox/wiki/ReaLearn-Home[Wiki] instead!**
+**If you are a beginner, please use the link:https://github.com/helgoboss/helgobox/wiki/ReaLearn-Home[ReaLearn Wiki] instead!**
 
 This reference is targeted at users who are already familiar with the ReaLearn basics and want to look up specific information. The Wiki is perfect if you are just starting off. It guides you through the very basics and contains links to easily digestable video tutorials.
 ====