Rewrite parts of the readme

README.md

@@ -1,9 +1,10 @@
 # yabridge
 
-Yet Another way to use Windows VST2 plugins in Linux VST hosts, including an
+Yet Another way to use Windows VST plugins in Linux VST hosts. Yabridge
-optional bitbridge to run 32-bit Windows plugins in 64-bit Linux hosts. This
+seamlessly supports running both 64-bit Windows VST2 plugins as well as 32-bit
-project aims to be as transparent as possible to achieve the best possible
+Windows VST2 plugins in a 64-bit Linux VST host. This project aims to be as
-plugin compatibility while also being easy to debug and maintain.
+transparent as possible to achieve the best possible plugin compatibility while
+also staying easy to debug and maintain.
 
 ## TODOs
 
@@ -14,8 +15,8 @@ There are a few things that should be done before releasing this, including:
 - Add missing details if any to the architecture section.
 - Rewrite parts of this readme.
 - Briefly verify that this also works fine in Reaper and Ardour.
-- Finish 32-bit bitbridge.
+- Upstream the updated `lib32-boost-libs` PKGBUILD needed for building the
-  - Upstream the updated `lib32-boost-libs` PKGBUILD.
+  bitbridge.
 
 ## Tested with
 
@@ -36,15 +37,16 @@ There are two ways to use yabridge.
 ### Symlinking (recommended)
 
 The recommended way to use yabridge is through symbolic links. This allows you
-to update yabridge for all of your plugins in one go, and it also avoids having
+to update yabridge for all of your plugins in one go, as well as avoiding having
 to install it globally.
 
 You can either use the precompiled binaries from the GitHub releases section, or
 you could build yabridge directly from source. If you use the precompiled
-binaries, then simply extract them to `~/.local/share/yabridge` or any other
+binaries, then you can simply extract them to `~/.local/share/yabridge` or to
-place in your home directory. If you choose to build from source, then you can
+any other location in your home directory. If you choose to build from source,
-directly use the binaries from the `build/` directory. For the section below I'm
+then you can use the compiled binaries directly from the `build/` directory. For
-going to assume you've placed the files in `~/.local/share/yabridge`.
+the section below I'm going to assume you've placed the files in
+`~/.local/share/yabridge`.
 
 To set up yabridge for a VST plugin called
 `~/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.dll`, simply create a
@@ -55,10 +57,10 @@ symlink from `~/.local/share/yabridge/libyabridge.so` to
 ln -s ~/.local/share/yabridge/libyabridge.so "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.so"
 ```
 
-For instance, if you wanted to set up yabridge for any of the VST plugins under
+As an example, if you wanted to set up yabridge for any of the VST plugins under
-`~/.wine/drive_c/Program Files/Steinberg/VstPlugins`, you could run this
+`~/.wine/drive_c/Program Files/Steinberg/VstPlugins`, you could run the
-oneliner in Bash. This will also skip any `.dll` files that are not actually VST
+following script in Bash. This will also skip any `.dll` files that are not
-plugins.
+actually VST plugins.
 
 ```shell
 find "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins" -type f -iname '*.dll' -print0 |
@@ -69,19 +71,20 @@ find "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins" -type f -iname '*.
 
 ### Copying
 
-It's also possible to use yabridge by making copies of `libyabridge.so` instead
+It is also possible to use yabridge by creating copies of `libyabridge.so`
-of creating symlinks. This is not recommended as it makes updating a hassle. If
+instead of making symlinks. This is not recommended as it makes updating a
-you choose to do this, then you'll have to make sure `yabridge-host.exe` and
+hassle, but it may be required if your host has issues using symlinks. If you
+choose to do this, then you'll have to make sure `yabridge-host.exe` and
 `yabridge-host.exe.so` are somewhere in your search path as otherwise yabridge
-won't know where to find them. Either copy them to `/usr/local/bin` (not
+won't be able to find them. Either copy them to `/usr/local/bin` (not
 recommended) or to `~/.local/bin` and make sure that the directory is in your
 `PATH` environment variable.
 
 ## Runtime dependencies and known issues
 
 Any VST2 plugin should function out of the box, although some plugins will need
-some additional dependencies for their editor GUIs to work correctly. Notable
+some additional dependencies for their GUIs to work correctly. Notable examples
-examples include:
+include:
 
 - **Serum** requires you to disable `d2d1.dll` in `winecfg` and to install
   `gdiplus` through `winetricks`.
@@ -152,9 +155,9 @@ to load is 32-bit or 64-bit, and will run either `yabridge-host.exe` or
 
 ## Debugging
 
-Wine's error messages and warning are typically very helpful whenever a plugin
+Wine's error messages and warning are generally very helpful whenever a plugin
-doesn't work right away. Sadly this information is not always available. For
+doesn't work right away. Sadly this information is not always available. Bitwig,
-instance Bitwig hides a plugin's STDOUT and STDERR streams from you. To make it
+for instance, hides a plugin's STDOUT and STDERR streams from you. To make it
 easier to debug malfunctioning plugins, yabridge offers two environment
 variables:
 
@@ -167,13 +170,13 @@ variables:
 - `YABRIDGE_DEBUG_LEVEL={0,1}` allows you to set the verbosity of the debug
   information. Every level increases the verbosity of the debug information:
 
-  - A value of `0` (the default) means that yabridge will only output messages
+  - A value of `0` (the default) means that yabridge will only write messages
     from the Wine process and some basic information such as the plugin being
     loaded and the wineprefix being used.
   - A value of `1` will log information about most events and function calls
-    being sent between the VST host and the plugin. This filters out some events
+    sent between the VST host and the plugin. This filters out some events such
-    such as `effEditIdle()` and `audioMasterGetTime()` since those are sent tens
+    as `effEditIdle()` and `audioMasterGetTime()` since those are sent tens of
-    of times per second by for every plugin.
+    times per second by for every plugin.
   - A value of `2` will cause all of the events to be logged, including the
     events mentioned above. This can be very verbose but it can be crucial for
     debugging plugin-specific problems.
@@ -181,10 +184,10 @@ variables:
   More detailed information about these levels can be found in
   `src/common/logging.h`.
 
-Wine's own [logging facilities](https://wiki.winehq.org/Debug_Channels) enabled
+Wine's own [logging facilities](https://wiki.winehq.org/Debug_Channels) can also
-through the `WINEDEBUG` environment variable can also be very helpful when
+be very helpful when diagnosing problems. In particular the `message` and
-diagnosing problems. In particular the `message` and `relay` channels are very
+`relay` channels are very useful to trace the execution path within the loading
-useful to trace the execution path within the loading VST plugin itself.
+VST plugin itself.
 
 ### Attaching a debugger
 
@@ -198,22 +201,14 @@ env YABRIDGE_DEBUG_FILE=/tmp/yabridge.log YABRIDGE_DEBUG_LEVEL=1 carla --gdb
 Doing the same thing for the Wine VST host can be a bit tricky. You'll need to
 launch winedbg in a seperate detached terminal emulator so it doesn't terminate
 together with the plugin, and winedbg can be a bit picky in the arguments it
-accepts. I've already set this up behind a feature flag for KDE Plasma. Other
+accepts. I've already set this up behind a feature flag for use in KDE Plasma.
-desktop environments and window managers will require some slight modifications
+Other desktop environments and window managers will require some slight
-in `src/plugin/host-bridge.cpp`. To enable this, simply run:
+modifications in `src/plugin/host-bridge.cpp`. To enable this, simply run:
 
 ```shell
 meson configure build --buildtype=debug -Duse-winedbg=true
 ```
 
-## Rationale
-
-I started this project because the alternatives were either unmaintained, not
-self-contained or very difficult to work with. With this implementation I'd like
-to prioritize maintainability and correctness, with performance being a
-secondary goal. Please let me know if you have any suggestions on how to improve
-this!
-
 ## Architecture
 
 The project consists of two components, a Linux native VST plugin