doc: massive refactor and simplification to migrate to mkdocs

Signed-off-by: Joachim Wiberg <[email protected]>

Author: troglobit

README.md

@@ -6,6 +6,7 @@ install and try out Finit on various Linux distributions.
 
 * [Alpine](alpine/)
 * [Debian](debian/)
+* [Void](void/)
 
 If you have ideas on how to simplify, extend, or even add new example
 configurations for other distributions you are most welcome! :)

contrib/README.md

@@ -1 +1 @@
-config.md
+index.md

doc/README.md

@@ -1,16 +1,6 @@
 Building Finit
 ==============
 
-* [Introduction](#introduction)
-* [Configure](#configure)
-* [Example](#example)
-* [Running](#running)
-* [Debugging](#debugging)
-
-
-Introduction
-------------
-
 Finit comes with a traditional configure script to control features and
 optional plugins to enable.  It depends on two external libraries:
 

doc/build.md

@@ -29,7 +29,7 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
   system bootstrap.
 
   Very useful for selecting different boot modes, e.g. manufacturing test,
-  firmware upgrade, or rescue mode.
+  firmware upgrade, or [rescue mode][rescue].
 
 > [!NOTE]
 > `<boot/...>` conditions cannot be cleared with `initctl`!
@@ -39,10 +39,10 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 
         ./configure --with-config=/etc/finit.conf
 
-   Useful when starting up in various rescue mode, factory, or
+   Useful when starting up in various [rescue mode][rescue], factory, or
    production test setups.  Use the top-level configuration file
-   directive `rcsd /path/to/finit.d` to override the default
-   rcS.d directory.
+   directive `rcsd /path/to/finit.d` to override the default rcS.d
+   directory.
 
 * `finit.debug[=bool]`: Enable finit debug.  This is operated
 	independently of the kernel `debug` setting.  New as of Finit v4.
@@ -75,7 +75,7 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 * `init=/bin/sh`: Bypass system default init and tell kernel to start a
 	shell.  Note, this shell is very limited and does not support
 	signals and has no job control.  Recommend using, and modifying,
-	`rescue` mode instead.
+	[`rescue` mode][rescue] instead.
 
 * `loglevel=<0-7>`, sets the kernel's log level, which is more granular
   than `debug`.  Also, when `loglevel=7`, Finit will *not disable*
@@ -90,12 +90,11 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 * `quiet`: Suppress kernel logging to console, except for warnings and
   errors.  Also, see `loglevel` and `quiet` above.
 
-* `rescue`: Start rescue/maintenance mode.  If your system comes with
-    the bundled `sulogin` program (Finit, or from util-linux/Busybox),
-    you will be given a root login to a maintenance shell.  However, if
-    `sulogin` is missing, the file `/lib/finit/rescue.conf` is read and
-    the system booted in a limited fallback mode.  See [config.md][]
-    for more information.
+* `rescue`: Start [rescue/maintenance mode][rescue].  If your system
+    comes with the bundled `sulogin` program (Finit, or from util-linux,
+    or Busybox), you will be given a root login to a maintenance shell.
+    However, if `sulogin` is missing, the file `/lib/finit/rescue.conf`
+    is read and the system booted in a limited fallback mode.
 
     This option can be disabled with `configure --without-rescue`
 
@@ -116,5 +115,5 @@ The `bool` setting is one of `on, off, true false, 1, 0`.
 
 For more on kernel boot parameters, see the man page [bootparam(7)][].
 
-[config.md]:    config.md#rescue-mode
+[rescue]:       config/rescue.md
 [bootparam(7)]: https://www.man7.org/linux/man-pages/man7/bootparam.7.html

doc/cmdline.md

@@ -0,0 +1,13 @@
+Rebooting & Halting
+===================
+
+Traditionally, rebooting and halting a UNIX system is done by switching
+to the corresponding runlevel (0 or 6).  Over time this has changed and
+Finit comes with its own tooling providing: `shutdown`, `reboot`,
+`poweroff`, and `suspend`.  These commands are also available from the
+[`initctl`](initctl.md) tool.
+
+For compatibility reasons Finit listens to the same set of signals as
+BusyBox init.  This is not 100% compatible with SysV init, but clearly
+the more common combination for Finit.  For more details, see the
+[Signal](signals.md) section.

doc/commands.md

@@ -1,21 +1,8 @@
-Finit Conditions
-================
+Conditions
+==========
 
-![The service state machine](svc-machine.png "The service state machine")
-
-* [Introduction](#introduction)
-* [Triggering](#triggering)
-* [Built-in Conditions](#built-in--conditions)
-* [Debugging](#debugging)
-* [Internals](#internals)
-
-
-Introduction
-------------
-
-Conditions are a relatively new addition to Finit, introduced in v3,
-with the intention of providing a mechanism for common synchronization
-problems.  For example:
+Conditions were added to Finit in v3 with the intention of providing a
+mechanism for common synchronization problems.  For example:
 
 - *"wait for service A to start before starting service B"*, or
 - *"wait for basic network access to be available"*
@@ -89,7 +76,8 @@ User-defined conditions are controlled using the `initctl cond set` and
 
 The purpose of user-defined conditions is to be able to start or stop
 services, or run/task jobs, on external site-dependent stimuli.
-Example:
+
+**Example:**
 
     service [2345] <usr/foo> alarm --arg foo -- Foo alarm
 
@@ -277,6 +265,8 @@ A condition is always in one of three states:
 All conditions that have not explicitly been set are interpreted as
 being in the `off` state.
 
+![The service state machine](svc-machine.png "The service state machine")
+
 When a reconfiguration is requested, Finit transitions all conditions to
 the `flux` state.  As a result, services that depend on a condition are
 sent `SIGSTOP`.  Once the new state of the condition is asserted, the