From 5c7d2d9d93cb1406d25f3454fe680a645c74d06b Mon Sep 17 00:00:00 2001
From: Pawel Lampe <pawel.lampe@gmail.com>
Date: Tue, 5 Mar 2024 12:44:03 +0100
Subject: [PATCH] Align 'Quickstart guide' in docs/ to the one in README.md

---
 docs/00-Introduction.md | 69 ++++++++++++++++++++++-------------------
 1 file changed, 37 insertions(+), 32 deletions(-)

diff --git a/docs/00-Introduction.md b/docs/00-Introduction.md
index f8f0909..1505030 100644
--- a/docs/00-Introduction.md
+++ b/docs/00-Introduction.md
@@ -58,66 +58,71 @@ Let it run, and move on to the **Quickstart guide**.
 
 ### Quickstart guide
 
-1. Integrate 'wkdev-sdk' with your shell environment.
+1. Integrate `wkdev-sdk` with your shell environment.
 
-Add the following to your shell configuration file (e.g. ~/.bashrc, ~/.zprofile, ...)
-to ensure that the ${WKDEV_SDK} environment variable points to the correct location
-of your 'wkdev-sdk' Git checkout. It also extends the ${PATH} to make the 'wkdev-\*' scripts
+Add the following to your shell configuration file (e.g. `~/.bashrc`, `~/.zprofile`, ...)
+to ensure that the `${WKDEV_SDK}` environment variable points to the correct location
+of your `wkdev-sdk` Git checkout. It also extends the `${PATH}` to make the `wkdev-*` scripts
 provided by this repository accessible without having to specifcy full paths in the shell.
 
-```
-# wkdev-sdk integration
-pushd /absolute/path/to/your/Git/checkout/of/wkdev-sdk &>/dev/null
-source ./register-sdk-on-host.sh
-popd &>/dev/null
+```sh
+source /absolute/path/to/your/Git/checkout/of/wkdev-sdk/register-sdk-on-host.sh
 ```
 
-Launch a new shell, or `source` your shell configuration files to verify, ${WKDEV_SDK}
-now expects as intented - pointing to your wkdev-sdk checkout.
+Launch a new shell, or `source` your shell configuration files to verify, `${WKDEV_SDK}`
+now expects as intented - pointing to your `wkdev-sdk` checkout.
 
-2. Create a new 'wkdev' container for WebKit development
+2. Create a new **wkdev** container for WebKit development
 
 Execute the following command on your host system:
 
-```wkdev-create --name wkdev --create-home --home ${HOME}/wkdev-home (--verbose)```
+```sh
+wkdev-create --name wkdev --create-home --home "${HOME}/wkdev-home"
+```
 
-This will create a container named 'wkdev', and transparently maps the current hoser user/ID
-into the container. Within the container, the ${HOME} directtory is not equal to the host
-${HOME} directory: ${HOME}/wkdev-home (from host) is bind-mounted into the container as
-"/home/hostuser". This avoids pollution of files in your host ${HOME} directory -- for
-convenience it's still exposed in the container, as ${HOST_HOME}.
+This will create a container named **wkdev**.
 
-NOTE: wkdev-create will auto-detect the whole environment: X11, Wayland, PulseAudio, etc.
-and eventually needs 'root' permissions on the 'host' system to perform first-time-run-only
-initializations (such as allowing GPU profiiling, by modifying root-owned config files, etc.)
+Within the container, the `${HOME}` directory is not equal to the host `${HOME}` directory:
+`${HOME}/wkdev-home` (from host) is bind-mounted into the container as `/home/${USER}`.
+This avoids pollution of files in your host `${HOME}` directory and for convenience
+it's still exposed in the container, as `${HOST_HOME}`.
 
-3. Enter the new 'wkdev' container
+The `name` and `home` values above are the defaults so you can omit them in regular usage.
+
+NOTE: `wkdev-create` will auto-detect the whole environment: X11, Wayland, PulseAudio, etc.
+and eventually needs **root** permissions on the *host system* to perform first-time-run-only
+initializations (such as allowing GPU profiling, by modifying `root`-owned config files, etc.)
+
+3. Enter the new **wkdev** container
 
 Execute the following command on your host system:
 
-```wkdev-enter --name wkdev```
+```
+wkdev-enter --name wkdev
+```
 
 After a few seconds you enter the container shell.
 
 4. Verify host system integration is working properly
 
-Run the test script in the container, which tests various workloads:
+You may optionally run the test script in the container, which tests various workloads:
 
-```wkdev-test-host-integration```
+```sh
+wkdev-test-host-integration
+```
 
 5. Compile WPE WebKit
 
-```
-cd ${HOST_HOME}/path/to/your/WebKit/checkout
-git pull
-Tools/Scripts/build-webkit --wpe --release --cmakeargs "-DCMAKE_BUILD_TYPE=RelWithDebInfo -DENABLE_THUNDER=OFF"
+```sh
+cd "${HOST_HOME}/path/to/your/WebKit/checkout"
+./Tools/Scripts/build-webkit --wpe --release
 ```
 
 To run tests / execute MiniBrowser, try;
 
-```
-Tools/Scripts/run-webkit-tests --wpe --release fast/css # Full tests take a long time
-Tools/Scripts/run-minibrowser --wpe https://browserbench.org/MotionMark1.2/
+```sh
+./Tools/Scripts/run-webkit-tests --wpe --release fast/css # Full tests take a long time
+./Tools/Scripts/run-minibrowser --wpe https://browserbench.org/MotionMark1.2/
 ```
 
 6. READY!