doc: assorted improvements, clarification and troubleshooting update.

doc/building.dox

@@ -337,7 +337,7 @@ compressed archive or use the command line:
 git clone git://github.com/mosra/magnum.git
 @endcode
 
-Relevant information about CMake usage was described in
+Relevant information about CMake usage is described in
 @ref building-corrade-cmake "Corrade download and installation guide", this
 guide is assuming you have at least basic knowledge of CMake.
 
@@ -366,6 +366,17 @@ Also, if you plan to install the library to non-standard location, you might
 want to set `CMAKE_INSTALL_RPATH` to `lib/` subdir of given prefix (e.g.
 `/home/xyz/projects/lib`), so the dynamic libraries can be found at runtime.
 
+@m_class{m-note m-default}
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-linux "Linux" and @ref platforms-macos "macOS"
+    platform docs for a troubleshooting guide and more information about
+    building your projects for Unix-like systems.
+    @endparblock
+
 @subsection building-windows Building on Windows
 
 On Windows you can use either MSVC or the MinGW-w64 compiler. It's then up to
@@ -417,6 +428,17 @@ see @ref building-features "below" for more information.
 Installation to given prefix can be done from within QtCreator by adding a new
 `make install` build rule.
 
+@m_class{m-note m-default}
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-windows "Windows platform docs" for a
+    troubleshooting guide and more information about building your projects for
+    Windows.
+    @endparblock
+
 @subsection building-features Enabling or disabling features
 
 The libraries are build as shared by default. If you are developing for a
@@ -763,15 +785,10 @@ See @ref platforms-gl-es-angle for more information about using ANGLE.
 
 @section building-cross Cross-compiling
 
-For cross-compiling you need to have *both* target and native version of
+For cross-compiling you need to have the toolchains submodule updated. Either
-Corrade installed, because Corrade needs to run `corrade-rc` utility on the
+run the following command, or, if you build from source archive, download a
-host system as part of the build process. If native version of `corrade-rc` is
+snapshot of the toolchains repository from https://github.com/mosra/toolchains
-not found on the system, cross-compilation will fail.
+and put the contents in the `toolchains/` subdirectory.
-
-You also need to have the toolchains submodule updated. Either run the
-following command, or, if you build from source archive, download a snapshot of
-the toolchains repository from https://github.com/mosra/toolchains and put the
-contents in the `toolchains/` subdirectory.
 
 @code{.sh}
 git submodule update --init
@@ -782,6 +799,20 @@ Note that CMake for some reason treats `CMAKE_PREFIX_PATH` and
 add dependency paths to both `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` to
 make it able to find the dependencies.
 
+@anchor building-cross-corrade-rc
+
+<b></b>
+
+@m_class{m-block m-primary}
+
+@par Native build of corrade-rc
+    You also need to have *both* target and native version of Corrade
+    installed, because Corrade needs to run `corrade-rc` utility on the host
+    system as part of the build process. If native version of `corrade-rc` is
+    not found on the system, cross-compilation will fail. If `corrade-rc` is
+    not in `PATH`, point CMake to it using
+    `-DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc`.
+
 @subsection building-cross-winrt Cross-compiling for Windows RT
 
 As said above, you need a native build of the `corrade-rc` executable and
@@ -798,7 +829,9 @@ SDL has support for WinRT applications --- download the source from
 https://www.libsdl.org/download-2.0.php and use project files from the
 `VisualC-WinRT` directory. Because WinRT applications run in a sandbox, it's
 recommended to build the library as static so you don't have to bundle all the
-DLLs. Example:
+DLLs. Example is below, you can omit specifying `CORRADE_RC_EXECUTABLE` if
+@ref building-cross-corrade-rc "natively-built corrade-rc" is accessible
+through `PATH`.
 
 @code{.bat}
 mkdir build-winrt && cd build-winrt
@@ -818,8 +851,16 @@ instead. When done, you can install the package using
 @cb{.bat} cmake --build . --target install @ce to make it available to
 depending projects.
 
-See @ref platforms-windows for more information about building your projects
+@m_class{m-note m-default}
-for WinRT.
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-windows "Windows platform docs" for a
+    troubleshooting guide and more information about building your projects for
+    Windows.
+    @endparblock
 
 @subsection building-cross-win Cross-compiling for Windows using MinGW-w64
 
@@ -857,8 +898,16 @@ cmake --build .
 Then you can install the package using @cb{.sh} cmake --build . --target install @ce
 to make it available to depending projects.
 
-See @ref platforms-windows for more information about building your projects
+@m_class{m-note m-default}
-for Windows.
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-windows "Windows platform docs" for a
+    troubleshooting guide and more information about building your projects for
+    Windows.
+    @endparblock
 
 @subsection building-cross-emscripten Cross-compiling for Emscripten
 
@@ -878,7 +927,10 @@ pass it explicitly on command-line using `-DEMSCRIPTEN_PREFIX`. Default is
 porting and they are generally slower, thus `BUILD_STATIC` is implicitly
 enabled.
 
-Then create build directory and run `cmake` and the build command in it.
+Then create build directory and run `cmake` and the build command in it. You
+can omit specifying `CORRADE_RC_EXECUTABLE` if
+@ref building-cross-corrade-rc "natively-built corrade-rc" is accessible
+through `PATH`.
 
 WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0
 equivalent) by disabling `TARGET_GLES2`. If you enable one of the
@@ -893,22 +945,12 @@ cmake .. \
     -DCMAKE_BUILD_TYPE=Release \
     -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
     -DCMAKE_INSTALL_PREFIX=/usr/lib/emscripten/system \
+    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
     -DMAGNUM_DEPLOY_PREFIX=/srv/http/magnum \
     -DWITH_SDL2APPLICATION=ON
 cmake --build .
 @endcode
 
-@note
-    If you set `CMAKE_INSTALL_PREFIX` to a path contained in
-    `EMSCRIPTEN_TOOLCHAIN_PATH` and dependencies are installed there as well,
-    things should "just work". Otherwise you might get the following error:
-@note <pre>CMake Error at .../Modules/FindPackageHandleStandardArgs.cmake:138 (message):
-  Could NOT find Corrade (missing: CORRADE_INCLUDE_DIR
-  _CORRADE_CONFIGURE_FILE)</pre>
-@note
-    This can be solved by adding the location where Corrade is installed to
-    `CMAKE_PREFIX_PATH` or `CMAKE_FIND_ROOT_PATH`.
-
 Then you can install the library using @cb{.sh} cmake --build . --target install @ce
 to make it available to depending projects.
 
@@ -923,8 +965,16 @@ named `PKGBUILD-emscripten`, `PKGBUILD-emscripten-webgl2`,
 WebGL 1 / WebGL 2 optimized asm.js build (*slow* to compile), the second for
 unoptimized build (faster to compile) and the third for WebAssembly build.
 
-See @ref platforms-html5 for more information about building your projects for
+@m_class{m-note m-default}
-Emscripten.
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-html5 "Emscripten platform docs" for a
+    troubleshooting guide and more information about building your projects for
+    Emscripten.
+    @endparblock
 
 @subsection building-cross-ios Cross-compiling for iOS
 
@@ -934,6 +984,9 @@ Set `CMAKE_OSX_ROOT` to the SDK you want to target and enable all desired
 architectures in `CMAKE_OSX_ARCHITECTURES`. Be sure to set
 `CMAKE_INSTALL_PREFIX` to prefix where you store other iOS dependencies such as
 @ref building-corrade-cross-ios "Corrade built for iOS" or a SDL2 iOS build.
+You can omit specifying `CORRADE_RC_EXECUTABLE` if
+@ref building-cross-corrade-rc "natively-built corrade-rc" is accessible
+through `PATH`.
 
 As every application is in its own sandbox, it doesn't make sense to build
 shared libraries (although it is supported). Enable `BUILD_STATIC` to build
@@ -941,6 +994,8 @@ static libraries. Dynamically loaded plugins are not supported on iOS at the
 moment, thus `BUILD_PLUGINS_STATIC` is implicitly enabled. OpenGL ES 2.0 is
 enabled by default, switch to 3.0 by disabling `TARGET_GLES2`.
 
+@m_class{m-console-wrap}
+
 @code{.sh}
 mkdir build-ios && cd build-ios
 cmake .. \
@@ -948,6 +1003,7 @@ cmake .. \
     -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
     -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
     -DCMAKE_INSTALL_PREFIX=~/ios-libs \
+    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
     -DBUILD_STATIC=ON \
     -DBUILD_PLUGINS_STATIC=ON \
     -DTARGET_GLES2=OFF \
@@ -959,19 +1015,22 @@ cmake --build .
 Then you can install the library using @cb{.sh} cmake --build . --target install @ce
 to make it available to depending projects.
 
-See @ref platforms-ios documentation for more information about building your
+@m_class{m-note m-default}
-projects for iOS.
+
+@par
+    @parblock
+    @m_class{m-noindent}
+
+    See the @ref platforms-ios "iOS platform docs" for a troubleshooting guide
+    and more information about building your projects for iOS.
+    @endparblock
 
 @subsection building-cross-android Crosscompiling for Android
 
 You will need [Android NDK](https://developer.android.com/ndk/) installed and
 configured and @ref building-corrade-cross-android "Corrade built for Android".
-CMake 3.7 is required, as it has Android support builtin. The supported
+At least CMake 3.7 is required, as it has Android support built-in. The
-toolchain is now Clang with libc++, GCC is not supported anymore.
+supported toolchain is now Clang with libc++, GCC is not supported anymore.
-
-@attention
-    You might want to grab at least CMake 3.9.2 instead of just 3.7, as it
-    [fixes an issue with the Clang toolchain](https://gitlab.kitware.com/cmake/cmake/issues/17253).
 
 Create a build directory and run `cmake` and the build command in it. Set
 `CMAKE_SYSTEM_NAME` to `Android` to enable the crosscompilation,
@@ -979,7 +1038,9 @@ Create a build directory and run `cmake` and the build command in it. Set
 with libc++, `CMAKE_SYSTEM_VERSION` to minimal API version level you wish to
 use and `CMAKE_ANDROID_ARCH_ABI` to target platform ABI. Check the
 [CMake Android cross-compiling documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android)
-for further information.
+for further information. You can omit specifying `CORRADE_RC_EXECUTABLE` if
+@ref building-cross-corrade-rc "natively-built corrade-rc" is accessible
+through `PATH`.
 
 If you set `CMAKE_INSTALL_PREFIX` to `/usr` subdirectory of the particular
 Android platform sysroot, the package will get found automatically when
@@ -1003,6 +1064,7 @@ cmake .. \
     -DCMAKE_ANDROID_STL_TYPE=c++_static \
     -DCMAKE_BUILD_TYPE=Release \
     -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-22/arch-arm/usr \
+    -DCORRADE_RC_EXECUTABLE=/path/to/corrade-rc \
     -DMAGNUM_INCLUDE_INSTALL_PREFIX=/opt/android-ndk/sysroot/usr \
     -DTARGET_GLES2=OFF \
     -DWITH_ANDROIDAPPLICATION=ON
@@ -1016,21 +1078,16 @@ For ArchLinux there is also a prepared package file in `package/archlinux/`,
 named `PKGBUILD-android-arm64`; see @ref building-packages-arch "above" for
 more information.
 
-@attention
+@m_class{m-note m-default}
-    On Windows it's possible that you get the following CMake error when
+
-    configuring the project:
+@par
-@attention
+    @parblock
-    <blockquote>
+    @m_class{m-noindent}
-    CMAKE_SYSTEM_NAME is 'Android' but 'NVIDIA Nsight Tegra Visual Studio
+
-    Edition' is not installed.
+    See the @ref platforms-android "Android platform docs" for a
-    </blockquote>
+    troubleshooting guide and more information about building your projects for
-@attention
+    Android.
-    This is because MSVC as the default generator on Windows is not able to
+    @endparblock
-    build arbitrary Android projects. To fix it, use a different generator (for
-    example Ninja, by passing `-G Ninja` to CMake).
-
-See @ref platforms-android for more information about building your projects
-for Android.
 
 @section building-ci Continuous Integration
 

doc/getting-started.dox

@@ -77,23 +77,53 @@ project(MyApplication)
 
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})
 
+# Add Corrade and Magnum as subprojects, enable Sdl2Application
+set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
 add_subdirectory(corrade)
 add_subdirectory(magnum)
+
 add_subdirectory(src)
 @endcode
 
-@note
+@m_class{m-block m-warning}
-    In the long run it's better to install Corrade and Magnum separately
+
-    instead of cloning them into your project tree, as that vastly improves
+@par What the heck is ON CACHE BOOL? FORCE?!
-    your iteration times. Follow @ref building "the full installation guide" if
+    CMake is a buildsystem with a long history and even though some design
-    you want to go that route; don't forget to enable `WITH_SDL2APPLICATION`
+    decisions were not good in retrospect, preserving the behavior is crucial
-    when building Magnum so the bootstrap project can use it later. There are
+    for its reliability. The above is needed due to an unfortunate behavior of
-    also ready-to-use packages for various OSes and distributions.
+    the @cmake option() @ce command that got
-@note
+    [fixed in CMake 3.13](https://cmake.org/cmake/help/latest/policy/CMP0077.html).
-    If you have that, you don't need to clone the subprojects and modify the
+    If you can afford requiring CMake 3.13 for your project, you can change the
-    `CMakeLists.txt` file like above, you might only need to set
+    above to just the following:
-    `CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to a non-standard
+@par
-    location.
+    @code{.cmake}
+    cmake_minimum_required(VERSION 3.13) # important
+
+    ...
+
+    set(WITH_SDL2APPLICATION ON)
+    add_subdirectory(corrade)
+    add_subdirectory(magnum)
+    @endcode
+
+<b></b>
+
+@m_class{m-block m-success}
+
+@par Building Magnum separately
+    Even though using Magnum as a CMake subproject is a fully supported use
+    case, in the long run it might be better to build & install Corrade and
+    Magnum separately instead of cloning them into your project tree, as that
+    vastly improves your iteration times. Follow
+    @ref building "the full installation guide" if you want to go that route;
+    don't forget to enable `WITH_SDL2APPLICATION` when building Magnum so the
+    bootstrap project can correctly find and use it. There are also
+    ready-to-use packages for various OSes and distributions, as listed above.
+@par
+    If you have a separate installation (or a package), you don't need to clone
+    the subprojects and modify the `CMakeLists.txt` file like above, you might
+    only need to set `CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to
+    a non-standard location.
 
 @section getting-started-review Review project structure
 
@@ -151,22 +181,27 @@ In the following tutorials the code will be explained more thoroughly.
 
 @subsection getting-started-linux Linux, macOS and other Unix-based OSes
 
-In Linux (and other Unix-based OSs) you can build the application along with
+Because the bootstrap project is based on SDL2, make sure you have SDL2
-the subprojects using the following three commands: create out-of-source build
+installed. It's usually in your system's package manager, on macOS you can get
-directory, run `cmake`, enable SDL2 application in the Magnum subproject and
+it from Homebrew using @cb{.sh} brew install sdl2 @ce. The application along
+with the subprojects is built using the following three commands ---
+create an out-of-source build directory, run `cmake` to generate a project and
 then build everything. The compiled application binary will then appear in
 `src/` subdirectory of the build dir:
 
 @code{.sh}
 mkdir -p build && cd build
-cmake .. -DWITH_SDL2APPLICATION=ON
+cmake ..
 cmake --build .
 ./src/MyApplication
 @endcode
 
-@note If you installed Corrade and Magnum separately (instead of putting them
+@m_class{m-note m-success}
-    in the project as subprojects), the `-DWITH_SDL2APPLICATION=ON` is not
+
-    needed as that was already done when compiling & installing Magnum before.
+@par Generating an Xcode project
+    On macOS it's possible to generate an Xcode project by running CMake as
+    `cmake -G Xcode ..`. After that's done, you can open the generated project
+    from the `build` directory.
 
 @subsection getting-started-windows Windows
 
@@ -177,13 +212,14 @@ to find them. For running the executable properly, Windows also need to have
 all dependency DLLs copied along it. That can be done by setting
 `CMAKE_RUNTIME_OUTPUT_DIRECTORY`. It's then up to you whether you will use a
 command line, Visual Studio or for example QtCreator. With Visual Studio the
-most straightforward way to generate the project file is via the command line:
+most straightforward way to generate the project file is via the Developer
+Command Prompt, alternatively execute the correct `vcvarsall.bat` in order to
+populate the necessary environment variables.
 
 @code{.bat}
 mkdir build && cd build
 cmake .. ^
-    -DWITH_SDL2APPLICATION=ON ^
+    -DCMAKE_PREFIX_PATH="C:/Users/you/where/you/extracted/SDL" ^
-    -DCMAKE_PREFIX_PATH="C:/Users/you/where/you/extracted/SDL2-2.0.5" ^
     -DCMAKE_RUNTIME_OUTPUT_DIRECTORY="bin"
 @endcode
 
@@ -192,8 +228,7 @@ generated by CMake in the `build/` directory.
 
 With QtCreator just open project's root `CMakeLists.txt` file. It then asks you
 where to create build directory, allows you to specify initial CMake parameters
-(`-DWITH_SDL2APPLICATION=ON` and others) and then you can just press *Configure*
+and then you can just press *Configure* and everything is ready to be built.
-and everything is ready to be built.
 
 @note If you installed Corrade and Magnum separately, the install directory
     containing the DLLs needs to be in @cb{.bat} %PATH% @ce in order to

doc/platforms-android.dox

@@ -742,6 +742,53 @@ gradle build
 
 @section platforms-android-troubleshooting Troubleshooting
 
+@subsection platforms-android-cmake-too-old CMake is too old
+
+While the minimal CMake version that's required for building Magnum for Android
+is 3.7, you might want to grab at least CMake 3.9.2, as it
+[fixes an issue with the Clang toolchain](https://gitlab.kitware.com/cmake/cmake/issues/17253).
+
+@subsection platforms-android-ndk-too-new NDK is too new
+
+Last NDK version that's known to be reliably working with CMake is r17, newer
+versions suffer from various issues due to changes introduced in NDK internals.
+No work has been done yet on Magnum side to counter / work around those issues,
+optimistically waiting on CMake devs to figure it out instead. See
+[mosra/magnum#310](https://github.com/mosra/magnum/issues/310) for details.
+
+@subsection platforms-android-troubleshooting-windows-nsight CMake complaining about some NVIDIA Nsight Tegra Visual Studio Edition on Windows
+
+On Windows it's possible that you get the following CMake error when
+configuring an Android project:
+
+> CMAKE_SYSTEM_NAME is 'Android' but 'NVIDIA Nsight Tegra Visual Studio
+> Edition' is not installed.
+
+This is because Visual Studio Project Files as the default generator on Windows
+is not able to build for any other system than Windows itself. To fix it, use a
+different generator --- for example [Ninja](https://ninja-build.org/). Download
+the binary, put it somewhere on your `PATH` and pass `-G Ninja` to CMake.
+Alternatively, pass the path to it using
+`-DCMAKE_MAKE_PROGRAM=C:/path/to/ninja.exe`.
+
+@m_class{m-block m-success}
+
+@par Using Ninja that's bundled with Visual Studio
+    If you have Visual Studio with CMake support installed, instead of
+    downloading Ninja yourself, you can make use of the version that's bundled
+    with it. In version 2017 it's in the following location, adjust the path
+    for other versions:
+@par
+    @parblock
+    <!-- gotta love doxygen, making easy things hard and complex things such as
+         applying a class to a nested block element next-to-impossible -->
+    @m_class{m-console-wrap}
+
+    @code{.bat}
+    cmake -G Ninja -DCMAKE_MAKE_PROGRAM=C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja\ninja.exe ...
+    @endcode
+    @endparblock
+
 @subsection platforms-android-troubleshooting-multiple-devices ADB fails when more devices are connected
 
 If any `adb` command fails with

doc/platforms-html5.dox

@@ -508,6 +508,35 @@ location:
 export LLVM=/usr/local/opt/emscripten/libexec/llvm/bin
 @endcode
 
+@subsection platforms-html5-troubleshooting-windows-compiler CMake insists on using Visual C++ as a compiler
+
+On Windows, running CMake as-is without specifying a generator via `-G` will
+always use the Visual Studio compiler and seemingly ignore the Emscripten
+toolchain file altogether. This is because Visual Studio Project Files as the
+default generator on Windows is not able to build for any other system than
+Windows itself. To fix it, use a different generator --- for example
+[Ninja](https://ninja-build.org/). Download the binary, put it somewhere on
+your `PATH` and pass `-G Ninja` to CMake. Alternatively, pass the path to it
+using `-DCMAKE_MAKE_PROGRAM=C:/path/to/ninja.exe`.
+
+@m_class{m-block m-success}
+
+@par Using Ninja that's bundled with Visual Studio
+    If you have Visual Studio with CMake support installed, instead of
+    downloading Ninja yourself, you can make use of the version that's bundled
+    with it. In version 2017 it's in the following location, adjust the path
+    for other versions:
+@par
+    @parblock
+    <!-- gotta love doxygen, making easy things hard and complex things such as
+         applying a class to a nested block element next-to-impossible -->
+    @m_class{m-console-wrap}
+
+    @code{.bat}
+    cmake -G Ninja -DCMAKE_MAKE_PROGRAM=C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja\ninja.exe ...
+    @endcode
+    @endparblock
+
 @subsection platforms-html5-troubleshooting-bootstrap First Emscripten run takes long or fails
 
 Emscripten downloads and builds a lot of things on first startup or after
@@ -541,9 +570,11 @@ em++ -s WASM=1 main.cpp
 After this step it might be also needed to purge all CMake build directories
 and set them up again to ensure no bad state got cached.
 
-@subsection platforms-html5-troubleshooting-corrade-not-found CMake can't find _CORRADE_MODULE_DIR
+@subsection platforms-html5-troubleshooting-corrade-not-found CMake can't find CORRADE_INCLUDE_DIR, _CORRADE_CONFIGURE_FILE or _CORRADE_MODULE_DIR
 
-If initial CMake configuration fails with
+If you set `CMAKE_INSTALL_PREFIX` to a path contained in `EMSCRIPTEN_TOOLCHAIN_PATH` (which is specified in the toolchain file) and
+dependencies are installed there as well, things should "just work". In other
+cases you might end up with variants of the following error:
 
 @code{.shell-session}
   Could NOT find Corrade (missing: _CORRADE_MODULE_DIR)
@@ -559,7 +590,7 @@ cmake .. \
     -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/Emscripten-wasm.cmake \
     -DCMAKE_PREFIX_PATH=/your/emscripten/libs/ \
     -DCMAKE_FIND_ROOT_PATH=/your/emscripten/libs/ \
-    -G Ninja
+    ...
 @endcode
 
 @subsection platforms-html5-troubleshooting-loading-failed Application fails to load
@@ -623,8 +654,10 @@ JavaScript code. Using them in C++ sources triggers a warning from Clang:
 warning: '$' in identifier
 @endcode
 
-Solution is to disable the warning for the offending lines, here for example
+Solution is to disable the warning for the offending lines, below for example
-when modifying a title element contents through DOM:
+when modifying a title element contents through DOM. No @cpp #ifdef __clang__ @ce
+is necessary, as the code in question is only ever compiled by Emscripten's
+Clang anyway:
 
 @snippet platforms-html5.cpp emasm-dollar
 

doc/platforms-macos.dox

@@ -128,7 +128,7 @@ advertised programmatically. In case of CMake, you have to supply a custom
 
 Apple Clang has a different versioning scheme from upstream Clang, making it
 hard to know which Clang version corresponds to which Apple Clang version.
-Wikipedia has a [handy version mapping table](https://en.wikipedia.org/wiki/Xcode#Latest_versions).
+Wikipedia has a [handy version mapping table](https://en.wikipedia.org/wiki/Xcode#Toolchain_versions).
 
 CMake exposes Apple Clang as `AppleClang`, so a complete check for e.g.
 upstream version 5 needs to look like this:

doc/platforms-windows.dox

@@ -161,7 +161,8 @@ are in the @ref Platform-Sdl2Application-bootstrap-winrt "SDL2 bootstrap applica
 
 @code{.xml}
 <?xml version="1.0" encoding="utf-8"?>
-<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest">
+<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest"
+         xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest">
   <Identity Name="MyApplication" Publisher="CN=A Publisher" Version="1.1.0.0" />
   <Properties>
     <DisplayName>My Application</DisplayName>
@@ -172,7 +173,8 @@ are in the @ref Platform-Sdl2Application-bootstrap-winrt "SDL2 bootstrap applica
     <Resource Language="x-generate" />
   </Resources>
   <Applications>
-    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="MyApplication.App">
+    <Application Id="App" Executable="$targetnametoken$.exe"
+                 EntryPoint="MyApplication.App">
       <m2:VisualElements
         DisplayName="Magnum Windows Store Application"
         Description="My Application"

doc/snippets/getting-started-blue.cpp

@@ -44,7 +44,9 @@ class MyApplication: public Platform::Application {
 };
 
 /** [1] */
-MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
+MyApplication::MyApplication(const Arguments& arguments):
+    Platform::Application{arguments}
+{
     using namespace Magnum::Math::Literals;
 
     GL::Renderer::setClearColor(0xa5c9ea_rgbf);

doc/snippets/getting-started.cpp

@@ -37,7 +37,9 @@ class MyApplication: public Platform::Application {
         void drawEvent() override;
 };
 
-MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
+MyApplication::MyApplication(const Arguments& arguments):
+    Platform::Application{arguments}
+{
     // TODO: Add your initialization code here
 }