documentation: more improvements

book/src/compiling.md

@@ -46,6 +46,8 @@ Note that when targetting Windows Store, WinMM APIs are not available, only UWP
 
 Both MSVC and MSYS2 are supported (on all MSYS2 toolchains).
 
+Note that for MIDI 2 support it is currently necessary for the end-user to install the [Windows MIDI Services](https://github.com/microsoft/MIDI/releases) on their computer. As of version 5, libremidi has been tested on Windows 10 and 11 with the DP9 NAMM Preview 4 release.
+
 ## On macOS & iOS
 Note that for MIDI 2 support, the application needs to target at least macOS 11.0.
 e.g. `-DCMAKE_OSX_DEPLOYMENT_TARGET=11` or more recent needs to be passed to CMake.

book/src/error-handling.md

@@ -1,7 +1,16 @@
 # Error handling
 
-The default error handling in the real-time API is done with an error type inspired from the proposed [std::error](https://github.com/charles-salvia/std_error). It has the advantage of working correctly in a header-only library and easily allows to turn the error into an exception if needed, as well as getting back the original host API error code if any, for instance an ALSA or WinMM error code.
+The default error handling in the real-time API is done with an error type inspired from the proposed [std::error](https://github.com/charles-salvia/std_error). It has the advantage of working correctly in a header-only library unlike standard `std::error_code` and easily allows turning the error into an exception if needed, as well as getting back the original host API error code if any, for instance an ALSA or WinMM error code.
 
+Example: 
+```cpp
+if (auto err = midiin.open_port(pi[0]); err != stdx::error{}) {
+  std::print("{}", err.message());
+  if(err == std::errc::bad_argument)
+    err.throw_exception();
+  // etc.
+}
+```
 ## Error callbacks
 
 It is also possible to set a callback function which will be invoked upon error, for the `midi_in`, `observer` `midi_out` classes.

book/src/header-only.md

@@ -9,8 +9,11 @@ The library can be used header-only, with minimal modifications to your build sy
   * Linux: `LIBREMIDI_ALSA=1` and link against `-lasound -phtread`.
   * Windows (WinMM): `LIBREMIDI_WINMM=1` and link against `winmm`.
   * Windows (UWP): `LIBREMIDI_WINUWP=1` ; note that there is complex linking logic detailed in the CMakeLists.txt when using UWP.
+  * Windows (MIDI services): `LIBREMIDI_WINMIDI=1`. Windows SDK headers and Windows MIDI headers are required.
   * emscripten: `LIBREMIDI_EMSCRIPTEN=1`.
   * Any platform with JACK: `LIBREMIDI_JACK=1`.
+  * Network API: `LIBREMIDI_NETWORK=1` and include boost.
+  * Keyboard API: `LIBREMIDI_KEYBOARD=1`.
 
 * Add the `include` folder to your include path.
 * `#include <libremidi/libremidi.hpp>` in your source code.

book/src/midi-2-in.md

@@ -1,19 +1,22 @@
 # Reading MIDI 2 messages from a device through callbacks
 
-Note that MIDI 2 support is still experimental and subject to change.
-Note also that the MIDI 1 and MIDI 2 send functions (not yet receive) are useable no matter 
+Note that the MIDI 1 and MIDI 2 send and receive functions are useable no matter 
 the kind of backend used (e.g. one can send UMPs to MIDI 1 backends and MIDI 1 messages to MIDI 2 backends). This conversion is done in a best-effort way.
 
+Note also that libremidi by default will upscale MIDI 1 to MIDI 2 channel events when coming from user-code: it is safe to assume than when using UMP input, only MIDI 2 channel events have to be processed, not MIDI 1 channel events encapsulated into UMPs.
+
+For Windows MIDI Services, a toggle allows to change this behaviour.
+
 ```cpp
 // Set the configuration of our MIDI port, same warnings apply than for MIDI 1.
 // Note that an UMP message is always at most 4 * 32 bits = 16 bytes.
 // Added to the 64-bit timestamp this is 24 bytes for a libremidi::ump 
 // which is definitely small enough to be passed by value.
 // Note that libremidi::ump is entirely constexpr.
 auto my_callback = [](libremidi::ump message) {
-  // how many bytes
+  // how many 32-bit UMP base elements (e.g. at least 1 uint32_t)
   message.size();
-  // access to the individual bytes
+  // access to the individual UMP 
   message[i];
   // access to the timestamp
   message.timestamp;

book/src/midi-2-integrations.md

@@ -7,7 +7,7 @@ libremidi integrates with the existing MIDI 2 ecosystem.
 We ship Atsushi Eno's [cmidi2](https://github.com/atsushieno/cmidi2) header-only MIDI 2 implementation as part of the library.
 This allows to quickly match incoming messages with MIDI 2 types. A lot of useful utility functions are provided.
 
-See the `midi2_echo.cpp` example: it uses the following printing function:
+See a basic `midi2_echo.cpp` example: it uses the following printing function:
 
 ```cpp
 std::ostream& operator<<(std::ostream& s, const libremidi::ump& message)

book/src/polling.md

@@ -7,7 +7,7 @@ which can then be injected into your app's main loop.
 
 Thus, this enables complete control over threading (and can also remove the need for synchronisation as this allows to make a callback-based yet single-threaded app, for simple applications which do not wish to reimplement MIDI filtering & parsing for back-ends such as ALSA Sequencer or RawMidi).
 
-Since this feature is pretty complicated to implement, we recommend checking the examples: 
+Since this feature is pretty complicated to implement correctly, we recommend checking the examples: 
 
 See:
 - `poll_share.cpp` for a complete example for ALSA RawMidi (recommended).