improve layout of some dev docs

docs/developers/Building_Android.md

@@ -10,17 +10,17 @@ The following instructions apply to **v1.2 and later**. For earlier versions the
 2. JDK 11, not necessarily from Oracle
 3. Android command line tools or Android Studio for your OS: https://developer.android.com/studio/
 4. Android NDK version **r25c (25.2.9519653)**, there're multiple ways to obtain it:
-- - install with Android Studio
+    - install with Android Studio
-- - install with `sdkmanager` command line tool
+    - install with `sdkmanager` command line tool
-- - download from https://developer.android.com/ndk/downloads
+    - download from https://developer.android.com/ndk/downloads
-- - download with Conan, see [#NDK and Conan](#ndk-and-conan)
+    - download with Conan, see [#NDK and Conan](#ndk-and-conan)
-5.  (optional) Ninja: download from your package manager or from https://github.com/ninja-build/ninja/releases
+5. (optional) Ninja: download from your package manager or from https://github.com/ninja-build/ninja/releases
 
 ## Obtaining source code
 
 Clone https://github.com/vcmi/vcmi with submodules. Example for command line:
 
-```sh
+```
 git clone --recurse-submodules https://github.com/vcmi/vcmi.git
 ```
 
@@ -30,24 +30,24 @@ We use Conan package manager to build/consume dependencies, find detailed usage
 branch](https://github.com/vcmi/vcmi/tree/master/docs/conan.md).
 
 On the step where you need to replace **PROFILE**, choose:
--   `android-32` to build for 32-bit architecture (armeabi-v7a)
+- `android-32` to build for 32-bit architecture (armeabi-v7a)
--   `android-64` to build for 64-bit architecture (aarch64-v8a)
+- `android-64` to build for 64-bit architecture (aarch64-v8a)
 
 ### NDK and Conan
 
 Conan must be aware of the NDK location when you execute `conan install`. There're multiple ways to achieve that as written in the [Conan docs](https://docs.conan.io/1/integrations/cross_platform/android.html):
 
--   the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically. You need to create your own Conan profile that imports our Android profile and adds 2 new lines (you can of course just copy everything from our profile into yours without including) and then pass this new profile to `conan install`:
+- the easiest is to download NDK from Conan (option 1 in the docs), then all the magic happens automatically. You need to create your own Conan profile that imports our Android profile and adds 2 new lines (you can of course just copy everything from our profile into yours without including) and then pass this new profile to `conan install`:
 
-```sh
+```
 include(/path/to/vcmi/CI/conan/android-64)
 [tool_requires]
 android-ndk/r25c
 ```
 
--   to use an already installed NDK, you can simply pass it on the command line to `conan install`:
+- to use an already installed NDK, you can simply pass it on the command line to `conan install`:
 
-```sh
+```
 conan install -c tools.android:ndk_path=/path/to/ndk ...
 ```
 
@@ -59,7 +59,7 @@ Building for Android is a 2-step process. First, native C++ code is compiled to
 
 This is a traditional CMake project, you can build it from command line or some IDE. You're not required to pass any custom options (except Conan toolchain file), defaults are already good. If you wish to use your own CMake presets, inherit them from our `build-with-conan` preset. Example:
 
-```sh
+```
 cmake -S . -B ../build -G Ninja -D CMAKE_BUILD_TYPE=Debug --toolchain ...
 cmake --build ../build
 ```

docs/developers/Building_iOS.md

@@ -2,22 +2,24 @@
 
 ## Requirements
 
-1.  **macOS**
+1. **macOS**
-2.  Xcode: <https://developer.apple.com/xcode/>
+2. Xcode: <https://developer.apple.com/xcode/>
-3.  CMake 3.21+: `brew install --cask cmake` or get from <https://cmake.org/download/>
+3. CMake 3.21+: `brew install --cask cmake` or get from <https://cmake.org/download/>
 
 ## Obtaining source code
 
 Clone <https://github.com/vcmi/vcmi> with submodules. Example for command line:
 
-`git clone --recurse-submodules https://github.com/vcmi/vcmi.git`
+```
+git clone --recurse-submodules https://github.com/vcmi/vcmi.git
+```
 
 ## Obtaining dependencies
 
 There are 2 ways to get prebuilt dependencies:
 
--   [Conan package manager](https://github.com/vcmi/vcmi/tree/develop/docs/conan.md) - recommended. Note that the link points to the cutting-edge state in `develop` branch, for the latest release check the same document in the [master branch (https://github.com/vcmi/vcmi/tree/master/docs/conan.md).
+- [Conan package manager](https://github.com/vcmi/vcmi/tree/develop/docs/conan.md) - recommended. Note that the link points to the cutting-edge state in `develop` branch, for the latest release check the same document in the [master branch (https://github.com/vcmi/vcmi/tree/master/docs/conan.md).
--   [legacy manually built libraries](https://github.com/vcmi/vcmi-ios-deps) - can be used if you have Xcode 11/12 or to build for simulator / armv7 device
+- [legacy manually built libraries](https://github.com/vcmi/vcmi-ios-deps) - can be used if you have Xcode 11/12 or to build for simulator / armv7 device
 
 ## Configuring project
 
@@ -25,15 +27,17 @@ Only Xcode generator (`-G Xcode`) is supported!
 
 As a minimum, you must pass the following variables to CMake:
 
--   `BUNDLE_IDENTIFIER_PREFIX`: unique bundle identifier prefix, something like `com.MY-NAME`
+- `BUNDLE_IDENTIFIER_PREFIX`: unique bundle identifier prefix, something like `com.MY-NAME`
--   (if using legacy dependencies) `CMAKE_PREFIX_PATH`: path to the downloaded dependencies, e.g. `~/Downloads/vcmi-ios-depends/build/iphoneos`
+- (if using legacy dependencies) `CMAKE_PREFIX_PATH`: path to the downloaded dependencies, e.g. `~/Downloads/vcmi-ios-depends/build/iphoneos`
 
 There're a few [CMake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html): for device (Conan and legacy dependencies) and for simulator, named `ios-device-conan`, `ios-device` and `ios-simulator` respectively. You can also create your local "user preset" to avoid typing variables each time, see example [here](https://gist.github.com/kambala-decapitator/59438030c34b53aed7d3895aaa48b718).
 
 Open terminal and `cd` to the directory with source code. Configuration example for device with Conan:
 
-`cmake --preset ios-device-conan \`  
+```
-`  -D BUNDLE_IDENTIFIER_PREFIX=com.MY-NAME`
+cmake --preset ios-device-conan \
+  -D BUNDLE_IDENTIFIER_PREFIX=com.MY-NAME
+```
 
 By default build directory containing Xcode project will appear at `../build-ios-device-conan`, but you can change it with `-B` option. 
 
@@ -53,7 +57,9 @@ You must also install game files, see [Installation on iOS](../players/Installat
 
 ### From command line
 
-`cmake --build `<path to build directory>` --target vcmiclient -- -quiet`
+```
+cmake --build <path to build directory> --target vcmiclient -- -quiet
+```
 
 You can pass additional xcodebuild options after the `--`. Here `-quiet` is passed to reduce amount of output.
 

docs/developers/Building_macOS.md

@@ -2,18 +2,20 @@
 
 # Requirements
 
-1.  C++ toolchain, either of:
+1. C++ toolchain, either of:
-    -   Xcode Command Line Tools (aka CLT): `sudo xcode-select --install`
+    - Xcode Command Line Tools (aka CLT): `sudo xcode-select --install`
-    -   Xcode IDE: <https://developer.apple.com/xcode/>
+    - Xcode IDE: <https://developer.apple.com/xcode/>
-    -   (not tested) other C++ compilers, e.g. gcc/clang from [Homebrew](https://brew.sh/)
+    - (not tested) other C++ compilers, e.g. gcc/clang from [Homebrew](https://brew.sh/)
-2.  CMake: `brew install --cask cmake` or get from <https://cmake.org/download/>
+2. CMake: `brew install --cask cmake` or get from <https://cmake.org/download/>
-3.  (optional) Ninja: `brew install ninja` or get from <https://github.com/ninja-build/ninja/releases>
+3. (optional) Ninja: `brew install ninja` or get from <https://github.com/ninja-build/ninja/releases>
 
 # Obtaining source code
 
 Clone <https://github.com/vcmi/vcmi> with submodules. Example for command line:
 
-`git clone --recurse-submodules https://github.com/vcmi/vcmi.git`
+```
+git clone --recurse-submodules https://github.com/vcmi/vcmi.git
+```
 
 # Obtaining dependencies
 
@@ -25,51 +27,48 @@ Please find detailed instructions in [VCMI repository](https://github.com/vcmi/v
 
 On the step where you need to replace **PROFILE**, choose:
 
--   if you're on an Intel Mac: `macos-intel`
+- if you're on an Intel Mac: `macos-intel`
--   if you're on an Apple Silicon Mac: `macos-arm`
+- if you're on an Apple Silicon Mac: `macos-arm`
 
 Note: if you wish to build 1.0 release in non-`Release` configuration, you should define `USE_CONAN_WITH_ALL_CONFIGS=1` environment variable when executing `conan install`.
 
 ## Homebrew
 
-1.  [Install Homebrew](https://brew.sh/)
+1. [Install Homebrew](https://brew.sh/)
-2.  Install dependencies: 
+2. Install dependencies: `brew install boost minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb`
-`brew install boost minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb`
+3. If you want to watch in-game videos, also install FFmpeg: `brew install ffmpeg@4`
-3.  If you want to watch in-game videos, also install FFmpeg: 
+4. Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
-`brew install ffmpeg@4`
+    - `brew install qt@5` for Qt 5 or `brew install qt` for Qt 6
-4.  Install Qt dependency in either of the ways (note that you can skip this if you're not going to build Launcher):
+    - using [Qt Online Installer](https://www.qt.io/download) - choose **Go open source**
-    -   `brew install qt@5` for Qt 5 or `brew install qt` for Qt 6
-    -   using [Qt Online Installer](https://www.qt.io/download) - choose **Go open source**
 
 # Preparing build environment
 
 This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, then use either of the following ways:
 
--   select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
+- select an Xcode instance from Xcode application - Preferences - Locations - Command Line Tools
--   use `xcode-select` utility to set Xcode or Xcode Command Line Tools path: for example,
+- use `xcode-select` utility to set Xcode or Xcode Command Line Tools path: for example, `sudo xcode-select -s /Library/Developer/CommandLineTools`
-    `sudo xcode-select -s /Library/Developer/CommandLineTools`
+- set `DEVELOPER_DIR` environment variable pointing to Xcode or Xcode Command Line Tools path: for example, `export DEVELOPER_DIR=/Applications/Xcode.app`
--   set `DEVELOPER_DIR` environment variable pointing to Xcode or Xcode Command Line Tools path: for example, `export DEVELOPER_DIR=/Applications/Xcode.app`
 
 # Configuring project for building
 
 Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.
 
-1.  In Terminal `cd` to the source code directory
+1. In Terminal `cd` to the source code directory
-2.  Start assembling CMake invocation: type `cmake -S . -B BUILD_DIR` where *BUILD_DIR* can be any path, **don't press Return**
+2. Start assembling CMake invocation: type `cmake -S . -B BUILD_DIR` where *BUILD_DIR* can be any path, **don't press Return**
-3.  Decide which CMake generator you want to use:
+3. Decide which CMake generator you want to use:
-    -   Makefiles: no extra option needed or pass `-G 'Unix Makefiles'`
+    - Makefiles: no extra option needed or pass `-G 'Unix Makefiles'`
-    -   Ninja (if you have installed it): pass `-G Ninja`
+    - Ninja (if you have installed it): pass `-G Ninja`
-    -   Xcode IDE (if you have installed it): pass `-G Xcode`
+    - Xcode IDE (if you have installed it): pass `-G Xcode`
-4.  If you picked Makefiles or Ninja, pick desired *build type* - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in `CMAKE_BUILD_TYPE` option, for example: `-D CMAKE_BUILD_TYPE=Release`. If you don't pass this option,     `RelWithDebInfo` will be used.
+4. If you picked Makefiles or Ninja, pick desired *build type* - either of Debug / RelWithDebInfo / Release / MinSizeRel - and pass it in `CMAKE_BUILD_TYPE` option, for example: `-D CMAKE_BUILD_TYPE=Release`. If you don't pass this option,     `RelWithDebInfo` will be used.
-5.  If you don't want to build Launcher, pass `-D ENABLE_LAUNCHER=OFF`
+5. If you don't want to build Launcher, pass `-D ENABLE_LAUNCHER=OFF`
-6.  You can also pass `-Wno-dev` if you're not interested in CMake developer warnings
+6. You can also pass `-Wno-dev` if you're not interested in CMake developer warnings
-7.  Next step depends on the dependency manager you have picked:
+7. Next step depends on the dependency manager you have picked:
-    -   Conan: pass `-D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake` where **conan-generated** must be replaced with your directory choice
+    - Conan: pass `-D CMAKE_TOOLCHAIN_FILE=conan-generated/conan_toolchain.cmake` where **conan-generated** must be replaced with your directory choice
-    -   Homebrew: if you installed FFmpeg or Qt 5, you need to pass `-D "CMAKE_PREFIX_PATH="` variable. See below what you can insert after `=` (but **before the closing quote**), multiple values must be separated with `;` (semicolon):
+    - Homebrew: if you installed FFmpeg or Qt 5, you need to pass `-D "CMAKE_PREFIX_PATH="` variable. See below what you can insert after `=` (but **before the closing quote**), multiple values must be separated with `;` (semicolon):
-        -   if you installed FFmpeg, insert `$(brew --prefix ffmpeg@4)`
+        - if you installed FFmpeg, insert `$(brew --prefix ffmpeg@4)`
-        -   if you installed Qt 5 from Homebrew, insert:`$(brew --prefix qt@5)`
+        - if you installed Qt 5 from Homebrew, insert:`$(brew --prefix qt@5)`
-        -   if you installed Qt from Online Installer, insert your path to Qt directory, for example: `/Users/kambala/dev/Qt-libs/5.15.2/Clang64`
+        - if you installed Qt from Online Installer, insert your path to Qt directory, for example: `/Users/kambala/dev/Qt-libs/5.15.2/Clang64`
-        -   example for FFmpeg + Qt 5: `-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"`
+        - example for FFmpeg + Qt 5: `-D "CMAKE_PREFIX_PATH=$(brew --prefix ffmpeg@4);$(brew --prefix qt@5)"`
 8.  now press Return
 
 # Building project
@@ -82,10 +81,10 @@ Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and h
 
 ## From command line
 
-`cmake --build `<path to build directory>
+`cmake --build <path to build directory>`
 
--   If using Makefiles generator, you'd want to utilize all your CPU cores by appending `-- -j$(sysctl -n hw.ncpu)` to the above
+- If using Makefiles generator, you'd want to utilize all your CPU cores by appending `-- -j$(sysctl -n hw.ncpu)` to the above
--   If using Xcode generator, you can also choose which configuration to build by appending `--config `<configuration name> to the above, for example: `--config Debug`
+- If using Xcode generator, you can also choose which configuration to build by appending `--config <configuration name>` to the above, for example: `--config Debug`
 
 # Packaging project into DMG file
 
@@ -97,27 +96,23 @@ If you use Conan, it's expected that you use **conan-generated** directory at st
 
 You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.
 
-Alternatively you can run binaries directly from "bin" directory:
+Alternatively you can run binaries directly from the **bin** directory:
 
-    BUILD_DIR/bin/vcmilauncher
+- BUILD_DIR/bin/vcmilauncher
-    BUILD_DIR/bin/vcmiclient
+- BUILD_DIR/bin/vcmiclient
-    BUILD_DIR/bin/vcmiserver
+- BUILD_DIR/bin/vcmiserver
 
-CMake include commands to copy all needed assets from source directory into "bin" on each build. They'll work when you build from Xcode too.
+CMake include commands to copy all needed assets from source directory into the **bin** directory on each build. They'll work when you build from Xcode too.
 
 # Some useful debugging tips
 
 Anyone who might want to debug builds, but new to macOS could find following commands useful:
 
-- To attach DMG file from command line use
+- To attach DMG file from command line use `hdiutil attach vcmi-1.0.dmg`
-`hdiutil attach vcmi-1.0.dmg`
+- Detach volume: `hdiutil detach /Volumes/vcmi-1.0`
-- Detach volume:
+- To view dependency paths: `otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
-`hdiutil detach /Volumes/vcmi-1.0`
+- To display load commands such as `LC_RPATH`: `otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
-- To view dependency paths
-`otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
-- To display load commands such as LC_RPATH 
-`otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
 
 # Troubleshooting
 
-In case of troubles you can always consult our CI build scripts or contact the dev team via slack
+In case of troubles you can always consult our CI build scripts or contact the dev team via slack.