Documentation: Clean up BuildInstructions.md a bit

- Fix headings
- Consistent & more accurate code block language specifiers
- Add some newlines where appropriate
- Remove the strange "run ninja but actually you don't have to run ninja
  as ninja install takes care of that" part
- Don't repeat specific build commands in "Ports" section
- Reword "Keymap" section to more generic "Customize disk image"

1 files changed, 59 insertions, 38 deletions

diff --git a/Documentation/BuildInstructions.md b/Documentation/BuildInstructions.md
index 066db38bb5..f9038ade3b 100644
--- a/Documentation/BuildInstructions.md
+++ b/Documentation/BuildInstructions.md
@@ -1,69 +1,78 @@
-## SerenityOS build instructions
+# SerenityOS build instructions
 
-### Prerequisites
+## Prerequisites
 
-#### Linux prerequisites
+### Linux prerequisites
 
 Ensure your CMake version is >= 3.16 with `cmake --version`. If your system doesn't provide a suitable version of CMake, you can download a binary release from the [CMake website](https://cmake.org/download).
 
 Ensure your gcc version is >= 10 with `gcc --version`. Otherwise, install it.
 
 On Ubuntu it's in the repositories of 20.04 (Focal) and later - add the `ubuntu-toolchain-r/test` PPA if you're running an older version:
-```bash
+
+```console
 sudo add-apt-repository ppa:ubuntu-toolchain-r/test
 ```
 
 On Debian you can use the Debian testing branch:
-```bash
+
+```console
 sudo echo "deb http://http.us.debian.org/debian/ testing non-free contrib main" >> /etc/apt/sources.list
 sudo apt update
 ```
 
 Now on Ubuntu or Debian you can install gcc-10 with apt like this:
-```bash
+
+```console
 sudo apt install gcc-10 g++-10
 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 900 --slave /usr/bin/g++ g++ /usr/bin/g++-10
 ```
 
 If you don't want to stay on the Debian testing branch you can switch back by running:
-```bash
+
+```console
 sudo sed -i '$d' /etc/apt/sources.list
 sudo apt update
 ```
 
 Make sure you have all the dependencies installed (`ninja` is optional, but is faster in practice):
 
-**Debian / Ubuntu**
-```bash
+#### Debian / Ubuntu
+
+```console
 sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-i386 qemu-utils
 ```
 
-**Fedora**
-```bash
+#### Fedora
+
+```console
 sudo dnf install curl cmake mpfr-devel libmpc-devel gmp-devel e2fsprogs ninja-build patch @"C Development Tools and Libraries" @Virtualization
 ```
 
-**openSUSE**
-```bash
+#### openSUSE
+
+```console
 sudo zypper install curl cmake mpfr-devel mpc-devel ninja gmp-devel e2fsprogs patch qemu-x86 qemu-audio-pa gcc gcc-c++ patterns-devel-C-C++-devel_C_C++
 ```
 
-**Arch Linux / Manjaro**
-```bash
+#### Arch Linux / Manjaro
+
+```console
 sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu qemu-arch-extra
 ```
 
-**ALT Linux**
-```bash
+#### ALT Linux
+
+```console
 apt-get install curl cmake libmpc-devel gmp-devel e2fsprogs libmpfr-devel ninja-build patch gcc
 ```
 
-
-**NixOS**
+#### NixOS
 
 You can use a `nix-shell` script like the following to set up the correct environment:
 
 myshell.nix:
+
 ```
 with import <nixpkgs> {};
 
@@ -97,15 +106,18 @@ Then use this script: `nix-shell myshell.nix`.
 
 Once you're in nix-shell, you should be able to follow the build directions.
 
-#### macOS prerequisites
+### macOS prerequisites
+
 Make sure you have all the dependencies installed:
-```bash
+
+```console
 brew install coreutils qemu e2fsprogs m4 autoconf libtool automake bash gcc@10 ninja
 brew install --cask osxfuse
 Toolchain/BuildFuseExt2.sh
 ```
 
 Notes:
+
 - fuse-ext2 is not available as brew formula so it must be installed using `BuildFuseExt2.sh`
 - Xcode and `xcode-tools` must be installed (`git` is required by some scripts)
 - coreutils is needed to build gcc cross compiler
@@ -131,33 +143,40 @@ Notes:
 </dict>
 </plist>
 ```
+
 </details>
 
-#### OpenBSD prerequisites
-```
+### OpenBSD prerequisites
+
+```console
 $ doas pkg_add bash cmake g++ gcc git gmake gmp ninja
 ```
 
 To use `ninja image` and `ninja run`, you'll need Qemu and other utilities:
-```
+
+```console
 $ doas pkg_add coreutils qemu sudo
 ```
 
-#### FreeBSD prerequisites
-```
+### FreeBSD prerequisites
+
+```console
 $ pkg add bash coreutils git gmake ninja sudo
 ```
 
-#### Windows
+### Windows prerequisites
+
 For Windows, you will require Windows Subsystem for Linux 2 (WSL2). [Follow the WSL2 instructions here.](https://github.com/SerenityOS/serenity/blob/master/Documentation/NotesOnWSL.md)
 Do note the ```Hardware acceleration``` and ```Note on filesystems``` sections, otherwise performance will be terrible.
 Once you have installed a distro for WSL2, follow the Linux prerequisites above for the distro you installed, then continue as normal.
 
 You may also want to install [ninja](https://github.com/ninja-build/ninja/releases)
 
-### Build
+## Build
+
 Go into the `Toolchain/` directory and run the **BuildIt.sh** script:
-```bash
+
+```console
 $ cd Toolchain
 $ ./BuildIt.sh
 ```
@@ -165,17 +184,18 @@ $ ./BuildIt.sh
 Building the toolchain will also automatically create a `Build/` directory for the build to live in.
 
 Once the toolchain has been built, go into the `Build/` directory and run the commands. Note that while `ninja` seems to be faster, you can also just use GNU make, by omitting `-G Ninja` and calling `make` instead of `ninja`:
-```bash
+
+```console
 $ cd ../Build
 $ cmake .. -G Ninja
-$ ninja
 $ ninja install
 ```
 
-This will compile all of SerenityOS and install the built files into `Root/` inside the build tree. `ninja install` actually pulls in the regular `ninja` (`ninja all`) automatically, so there isn't really a need to run it explicitly. `ninja` will automatically build as many jobs in parallel as it detects processors; `make` builds only one job in parallel. (Use the `-j` option with an argument if you want to change this.)
+This will compile all of SerenityOS and install the built files into `Root/` inside the build tree. `ninja` will automatically build as many jobs in parallel as it detects processors; `make` builds only one job in parallel. (Use the `-j` option with an argument if you want to change this.)
 
 Now to build a disk image, run `ninja image`, and take it for a spin by using `ninja run`.
-```bash
+
+```console
 $ ninja image
 $ ninja run
 ```
@@ -191,14 +211,15 @@ Outside of QEMU, Serenity will run on VirtualBox and VMware. If you're curious,
 
 Later on, when you `git pull` to get the latest changes, there's (usually) no need to rebuild the toolchain. You can simply run `ninja install`, `ninja image`, and `ninja run` again. CMake will only rebuild those parts that have been updated.
 
-#### Ports
-To add a package from the ports collection to Serenity, for example curl, go into `Ports/curl/` and run **./package.sh**. The sourcecode for the package will be downloaded and the package will be built. After that, run **make image** from the `Build/` directory to update the disk image. The next time you start Serenity with **make run**, `curl` will be available.
+## Ports
 
-#### Keymap
+To add a package from the ports collection to Serenity, for example curl, go into `Ports/curl/` and run `./package.sh`. The sourcecode for the package will be downloaded and the package will be built. After that, rebuild the disk image. The next time you start Serenity, `curl` will be available.
 
-Create a file with the exact name `sync-local.sh` in the project root (the same directory as `.clang-format`), with content like this:
+## Customize disk image
 
-```
+To add, modify or remove files of the disk image's file system, e.g. to change the default keyboard layout, you can create a file with the exact name `sync-local.sh` in the project root (the same directory as `.clang-format`), with content like this:
+
+```sh
 #!/bin/sh
 
 set -e