Rewrite documentation on yabridge.toml files

CHANGELOG.md

@@ -35,6 +35,11 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 - Added a workaround for reparenting issues with the plugin editor GUI on a
   [specific i3 setup](https://github.com/robbert-vdh/yabridge/issues/40).
 
+### Documentation
+
+- The documentation on `yabridge.toml` files and the available options has been
+  rewritten in an effort to make it easier to comprehend.
+
 ## [1.6.1] - 2020-09-28
 
 ### Fixed
@@ -110,7 +115,7 @@ Versioning](https://semver.org/spec/v2.0.0.html).
   embedding. Right now the only known plugins that may need this are
   _PSPaudioware_ plugins with expandable GUIs such as E27. The behaviour can be
   enabled on a per-plugin basis in the plugin configuration. See the
-  [readme](https://github.com/robbert-vdh/yabridge#miscellaneous-fixes-and-workarounds)
+  [readme](https://github.com/robbert-vdh/yabridge#compatibility-options)
   for more details.
 
 ### Changed

README.md

@@ -23,7 +23,7 @@ compatibility while also staying easy to debug and maintain.
   - [Wine prefixes](#wine-prefixes)
   - [Configuration](#configuration)
     - [Plugin groups](#plugin-groups)
-    - [Miscellaneous fixes and workarounds](#miscellaneous-fixes-and-workarounds)
+    - [Compatibility options](#compatibility-options)
     - [Example](#example)
 - [Troubleshooting common issues](#troubleshooting-common-issues)
 - [Performance tuning](#performance-tuning)
@@ -206,19 +206,28 @@ override the Wine prefix for all instances of yabridge.
 
 ### Configuration
 
+Yabridge can be configured on a per plugin basis to host multiple plugins within
+a single process using [plugin groups](#plugin-groups), as well as to improve
+compatibility with certain hosts and plugins through a variety of [compatibility
+options](#compatibility-options)
+
 Configuring yabridge for specific plugins is done through a `yabridge.toml` file
-located in either the same directory as the symlink to or copy of
+located in either the same directory as the plugin's `.so` file you're trying to
-`libyabridge.so` you're trying to configure or in any of its parent directories.
+configure, or in any of its parent directories. This file contains case
-This file contains case sensitive
+sensitive [glob](https://www.man7.org/linux/man-pages/man7/glob.7.html) patterns
-[glob](https://www.man7.org/linux/man-pages/man7/glob.7.html) patterns that
+that match paths to yabridge `.so` files relative to the `yabridge.toml` file.
-paths of yabridge `.so` files relative to that `yabridge.toml` file. These
+These patterns can also match an entire directory to apply settings to all
-patterns can also match an entire directory to apply settings to all plugins
+plugins within that directory. To avoid confusion, only the first
-within that directory. For simplicity's sake, only the first `yabridge.toml`
+`yabridge.toml` file found and only the first matching glob pattern within that
-file found and only the first matching glob pattern within that file will be
+file will be considered. See below for an [example](#example) of a
-considered. See below for an [example](#example) of a `yabridge.toml` file.
+`yabridge.toml` file.
 
 #### Plugin groups
 
+| Option  | Values            | Description                                                            |
+| ------- | ----------------- | ---------------------------------------------------------------------- |
+| `group` | `{"<string>",""}` | Defaults to `""`, meaning that the plugin will be hosted individually. |
+
 Some plugins have the ability to communicate with other instances of that same
 plugin or even with other plugins made by the same manufacturer. This is often
 used in mixing plugins to allow different tracks to reference each other without
@@ -235,34 +244,24 @@ process. Of course, plugin groups with the same name but in different Wine
 prefixes and with different architectures will be run independently of each
 other. See below for an [example](#example) of how these groups can be set up.
 
-#### Miscellaneous fixes and workarounds
+#### Compatibility options
 
-Because Linux VST hosts are typically not tested using Windows VST plugins and
+| Option                       | Values         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-because some Windows VST plugins make incorrect assumptions about the host or
+| ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-the environment, you may run into implementation issues when combining certain
+| `editor_double_embed`        | `{true,false}` | Compatibility option for plugins that rely on the absolute screen coordinates of the window they're embedded in. Since the Wine window gets embedded inside of a window provided by your DAW, these coordinates won't match up and the plugin would end up drawing in the wrong location without this option. Currently the only known plugins that require this option are _PSPaudioware_ plugins with expandable GUIs, such as E27. Defaults to `false`. |
-hosts and VST plugins. This section contains a few options you can use to work
+| `hack_reaper_update_display` | `{true,false}` | Compatibility option for _REAPER_ and _Renoise_. This disables the `audioMasterUpdateDisplay()` function, which in these hosts will introduce mutual recursion which is currently not supported by yabridge's communication model. Defaults to `false`.                                                                                                                                                                                                    |
-around these issues. The [known issues](#runtime-dependencies-and-known-issues)
-section contains more information on when these options might be necessary.
-Yabridge will show which of these options are active on startup as part of the
-initialization message.
 
-- Both _REAPER_ and _Renoise_ can freeze when the plugin uses the
+These options are workarounds for issues mentioned in the [known
-  `audioMasterUpdateDisplay()` function while the host is updating the editor
+issues](#runtime-dependencies-and-known-issues) section. Depending on the hosts
-  window. As a temporary workaround until this is fixed you can set the
+and plugins you use you might want to enable some of them. When using REAPER,
-  `hack_reaper_update_display` option to `true`. If you set this option for the
+it's recommended to enable `hack_reaper_update_display` for all of your plugins.
-  `["*"]` pattern like in the example below, then this will be applied to all
+To do this, create a `yabridge.toml` file next to your plugin's .so files with
-  yabridge `.so` files in the directory of the `yabridge.toml` files and all
+the following contents:
-  directories below it. If you have added any other patterns to the
+
-  `yabridge.toml` file you'll also have to add the setting there since yabridge
+```toml
-  will only read settings from the first matching pattern. See the example below
+["*"]
-  for more clarification.
+hack_reaper_update_display = true
-- The way yabridge embeds editor windows will work for most plugins. There is a
+```
-  second embedding mode available that adds yet another layer of embedding. This
-  can be enabled by setting the `editor_double_embed` option to `true`. At the
-  moment the only known plugins that need this are _PSPaudioware_ plugins with
-  expandable GUIs such as E27 as those plugins will otherwise draw in the wrong
-  location after the GUI has been expanded. This setting may be replaced in the
-  future if we can come up with a better solution.
 
 #### Example
 
@@ -277,37 +276,28 @@ group = "fabfilter"
 ["MeldaProduction/Tools/MMultiAnalyzer.so"]
 group = "melda"
 
-["PSPaudioware"]
-editor_double_embed = true
-
 # Matches an entire directory and all files inside it, make sure to not include
 # a trailing slash
 ["ToneBoosters"]
 hack_reaper_update_display = true
 group = "toneboosters"
 
-# Simple glob patterns can be used to avoid a unneeded repitition
+["PSPaudioware"]
+editor_double_embed = true
+
+# Simple glob patterns can be used to avoid unneeded repetition
 ["iZotope*/Neutron *"]
 group = "izotope"
 
+# Since this file has already been matched by the above glob pattern, this won't
+# do anything
+["iZotope7/Neutron 2 Mix Tap.so"]
+group = "This will be ignored!"
+
 # Of course, you can also add multiple plugins to the same group by hand
 ["iZotope7/Insight 2.so"]
 group = "izotope"
 
-# This won't do anything as this file has already been matched by the pattern
-# above
-["iZotope7/Neutron 2 Mix Tap.so"]
-group = "This will be ignored!"
-
-# Don't do this unless you know what you're doing! This matches all plugins in
-# this directory and all of its subdirectories, which will cause all of them to
-# be hosted in a single process. While this would increase startup and plugin
-# scanning performance considerably, it will also break any form of individual
-# plugin sandboxing provided by the host and could potentially introduce all
-# kinds of weird issues.
-# ["*"]
-# group = "all"
-
 # This will apply a workaround for an implementation issue in REAPER and Renoise
 # to all plugins in the current directory _that are not already matched by one
 # of the above patterns_. You will have to add this option to any other entries
@@ -424,9 +414,8 @@ include:
 
 - **REAPER** and **Renoise** can both freeze when using plugins that call the
   `audioMasterUpdateDisplay()` function because of mutual recursion limitations.
-  Until this is fixed you can set an
+  Until this is fixed you can set an [option](#compatibility-options) through
-  [option](#miscellaneous-fixes-and-workarounds) through `yabridge.toml` to work
+  `yabridge.toml` to work around this.
-  around this.
 - **Native Instruments** plugins work, but Native Access is unable to finish
   installing the plugins. To work around this you can open the .iso file
   downloaded to your downloads directory and run the installer directly. When
@@ -441,8 +430,7 @@ include:
   when the window gets dragged offscreen on the top and left dies of the screen.
 - **PSPaudioware** plugins with expandable GUIs, such as E27, may have their GUI
   appear in the wrong location after the GUI has been expanded. You can enable
-  an alternative [editor hosting mode](#miscellaneous-fixes-and-workarounds) to
+  an alternative [editor hosting mode](#compatibility-options) to fix this.
-  fix this.
 - Plugins like **FabFilter Pro-Q 3** that can share data between different
   instances of the same plugin plugins have to be hosted within a single process
   for that functionality to work. See the [plugin groups](#plugin-groups)