From eb16a35ff3a28cbfb19bbd4df0f2a2fa43defd00 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Tue, 8 Apr 2025 21:24:31 +0100
Subject: [PATCH] convert "supported hardware" to an appendix

---
 doc/Makefile     |  4 ++--
 doc/hardware.nix | 14 +-------------
 doc/index.adoc   | 15 +++++++++++++++
 3 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 9cadbdba..237a512c 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,8 +12,8 @@ DOCS=\
 
 hardware.adoc: hardware.nix
 	pandoc -f rst -t asciidoc -o $@ hardware.rst
-	# don't even ask
-	sed -E -i.bak -e 's/^=(=*) /\1 /g' hardware.adoc
+	# sections in an appendix need to start at ===
+	sed -E -i.bak -e 's/^(=*) /=\1 /g' hardware.adoc
 
 html: Makefile  $(patsubst %,%.adoc,$(DOCS))
 	asciidoctor  -D _build -d book index.adoc
diff --git a/doc/hardware.nix b/doc/hardware.nix
index 5f6a3f0e..e133704c 100644
--- a/doc/hardware.nix
+++ b/doc/hardware.nix
@@ -11,7 +11,7 @@ let
       d' = {
         description = ''
           ${n}
-          ${substring 0 (stringLength n) "********************************"}
+          ${substring 0 (stringLength n) "============================"}
         '';
       } // d;
     in
@@ -19,18 +19,6 @@ let
   ) devices;
 in
 writeText "hwdoc" ''
-  Supported hardware
-  ##################
-
-  For development, the `GL.iNet GL-MT300A <https://www.gl-inet.com/products/gl-mt300a/>`_
-  is an attractive choice as it has a builtin "debrick" procedure in the
-  boot monitor and is also comparatively simple to
-  attach serial cables to (soldering not required), so it
-  is lower-risk than some devices.
-
-  For a more powerful device, something with an ath10k would be the safe bet,
-  or the Linksys E8450 which seems popular in the openwrt community.
-
   ${lib.concatStringsSep "\n\n" texts}
 
 ''
diff --git a/doc/index.adoc b/doc/index.adoc
index b7871012..b8f3aa42 100644
--- a/doc/index.adoc
+++ b/doc/index.adoc
@@ -1,5 +1,6 @@
 = Liminix
 Daniel Barlow
+:doctype: book
 :toc: left
 
 include::intro.adoc[]
@@ -20,4 +21,18 @@ include::modules.adoc[]
 
 include::code-of-conduct.adoc[]
 
+[appendix]
+= Supported hardware
+
+=== Recommended devices
+
+For development, the supported GL.iNet devices are all good choices if
+you can find them, as they have a builtin "debrick" procedure in the
+boot monitor and are also comparatively simple to attach serial cables
+to (soldering not required), so are lower-risk than some other devices.
+
+For a more powerful device, something with an ath10k wireless would be
+the safe bet, or the Linksys E8450 which seems popular in the OpenWrt
+community.
+
 include::hardware.adoc[]