From db70623bff0f77d29f70c7267c24c15f4d71ae71 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Fri, 17 Feb 2023 20:54:18 +0000
Subject: [PATCH] improve markup

---
 doc/developer.rst | 58 ++++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/doc/developer.rst b/doc/developer.rst
index 258c06c5..23b9634c 100644
--- a/doc/developer.rst
+++ b/doc/developer.rst
@@ -8,7 +8,7 @@ documents various affordances for iteration and experiments.
 
 In general, packages and tools that run on the "build" machine are
 available in the ``buildEnv`` derivation and can most easily
-be added to your environment by running ``nix-shell``
+be added to your environment by running :command:`nix-shell`
 
 
 
@@ -27,7 +27,7 @@ To build it,
 
     nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
 
-In a ``buildEnv`` nix-shell, you can use the ``mips-vm`` command
+In a ``buildEnv`` nix-shell, you can use the :command:`mips-vm` command
 to run Qemu with appropriate options. It connects the Liminix
 serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/monitor.html>`_ to stdin/stdout. Use ^P (not ^A) to switch to the monitor.
 
@@ -37,9 +37,9 @@ serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/m
 
 If you run with ``--background /path/to/some/directory`` as the first
 parameter, it will fork into the background and open Unix sockets in
-that directory for console and monitor.  Use ``connect-vm`` (also in the
-``buildEnv`` environment) to connect to either of these sockets, and ^O
-to disconnect.
+that directory for console and monitor.  Use :command:`connect-vm`
+(also in the ``buildEnv`` environment) to connect to either of these
+sockets, and ^O to disconnect.
 
 Networking
 ==========
@@ -47,13 +47,13 @@ Networking
 VMs can network with each other using QEMU
 socket networking.  We observe these conventions, so that we can run
 multiple emulated instances and have them wired up to each other in
-the right way
+the right way:
 
 * multicast 230.0.0.1:1234  : access (interconnect between router and "isp")
 * multicast 230.0.0.1:1235  : lan
 * multicast 230.0.0.1:1236  : world (the internet)
 
-A VM started with ``mips-vm`` is connected to "lan" and "access", and
+A VM started with :command:`mips-vm` is connected to "lan" and "access", and
 the emulated border network gateway (see below) runs PPPoE and is
 connected to "access" and "world".
 
@@ -65,8 +65,8 @@ In pkgs/routeros there is a derivation to install and configure
 concentrator connected to the ``access`` and ``world`` networks, so that
 Liminix PPPoE client support can be tested without actual hardware.
 
-This is made available as the ``routeros`` command in ``buildEnv``, so you
-can do something like::
+This is made available as the :command:`routeros` command in
+``buildEnv``, so you can do something like::
 
     mkdir ros-sockets
     nix-shell
@@ -95,8 +95,8 @@ TFTP.
 There is a rudimentary TFTP server bundled with the system which runs
 from the command line, has an allowlist for client connections, and
 follows symlinks, so you can have your device download images direct
-from the ``./result`` directory without exposing ``/nix/store/`` to the
-internet or mucking about copying files to ``/tftproot``. If the
+from the :file:`./result` directory without exposing :file:`/nix/store/` to the
+internet or mucking about copying files to :file:`/tftproot`. If the
 permitted device is to be given the IP address 192.168.8.251 you might
 do something like this:
 
@@ -122,9 +122,9 @@ image instead of flashing. In your device configuration add
   };
 
 and then build ``outputs.tftproot``. This creates a file in
-``result/`` called ``boot.scr`` containing commands that you can copy
-and paste into U-Boot which will transfer the kernel and filesystem
-over TFTP and boot the kernel from RAM.
+``result/`` called ``boot.scr``, which you can copy and paste into
+U-Boot to transfer the kernel and filesystem over TFTP and boot the
+kernel from RAM.
 
 
 Networking
@@ -144,16 +144,16 @@ router from the internet so you can borrow the cable/fibre/DSL.
 * an L2TP service such as https://www.aa.net.uk/broadband/l2tp-service/
 
 You need to configure the Ethernet card for VFIO passthru, then
-you can execute ``run-border-vm`` in a ``buildEnv`` shell,
+you can execute :command:`run-border-vm` in a ``buildEnv`` shell,
 which starts up QEMU using the NixOS configuration in
-``bordervm-configuration.nix``.
+:file:`bordervm-configuration.nix`.
 
 In this VM
 
-* your Liminix checkout is mounted under ``/home/liminix/liminix``
+* your Liminix checkout is mounted under :file:`/home/liminix/liminix`
 
 * TFTP is listening on the ethernet device and serving
-  ``/home/liminix/liminix``.  The server IP address is 10.0.0.1
+  :file:`/home/liminix/liminix`.  The server IP address is 10.0.0.1
 
 * a PPPOE-L2TP relay is running on the same ethernet card, which
   spawns L2TPv2 Access Concentrator sessions to your specified
@@ -163,18 +163,20 @@ In this VM
   service can be configured into your test device - bordervm
   doesn't need to know about them.
 
-To configure bordervm, you need a file called ``bordervm.conf.nix``
-which you can create by copying and appropriately editing  ``bordervm.conf-example.nix``
+To configure bordervm, you need a file called :file:`bordervm.conf.nix`
+which you can create by copying and appropriately editing  :file:`bordervm.conf-example.nix`
 
-Note: If you make changes to the bordervm configuration after
-executing ``run-border-vm``, you need to remove the ``border.qcow2``
-disk image file otherwise the changes won't get picked up.
+.. note::
+
+    If you make changes to the bordervm configuration after executing
+    :command:`run-border-vm`, you need to remove the :file:`border.qcow2` disk
+    image file otherwise the changes won't get picked up.
 
 
 Running tests
 *************
 
-You can run all of the tests by evaluating ``ci.nix``, which is the
+You can run all of the tests by evaluating :file:`ci.nix`, which is the
 input I use in Hydra. Note that it expects Nixpkgs stable `and` unstable
 as inputs, because it builds the qemu device against both.
 
@@ -197,9 +199,13 @@ Diagnosing unexpectedly large images
 Sometimes you can add a package and it causes the image size to balloon
 because it has dependencies on other things you didn't know about. Build the
 ``outputs.manifest`` attribute, which is a JSON representation of the
-filesystem, and you can run ``nix-store --query`` on it.::
+filesystem, and you can run :command:`nix-store --query` on it.
 
-    nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.manifest -o manifest
+.. code-block:: console
+
+    nix-build -I liminix-config=path/to/your/configuration.nix \
+      --arg device "import ./devices/qemu" -A outputs.manifest \
+      -o manifest
     nix-store -q --tree manifest