much text, such doc, very wow

doc/parse-options.fnl

@@ -72,13 +72,17 @@
       (let [e (or (. modules path) [])]
         (table.insert e option)
         (tset modules path e))))
-  (each [name module (pairs modules)]
-    (print (or (read-preamble name) (headline name)))
-    (let [options (sort-options module)]
-      (each [_ o (ipairs options)]
-        (if (= o.type "parametrisable s6-rc service definition")
-            (print-service o)
-            (print-option o))))))
+  (tset modules "lib/modules.nix" nil)
+  (let [module-names (doto (icollect [n _ (pairs modules)] n) table.sort)]
+    (io.stderr:write (view module-names))
+    (each [_ name (ipairs module-names)]
+      (let [module (. modules name)
+            options (sort-options module)]
+        (print (or (read-preamble name) (headline name)))
+        (each [_ o (ipairs options)]
+          (if (= o.type "parametrisable s6-rc service definition")
+              (print-service o)
+              (print-option o)))))))
 
 ;; for each element el, add to table modules keyed on
 ;; el.declarations

doc/user.rst

@@ -83,19 +83,42 @@ Creating configuration.nix
 ==========================
 
 
-You need to create a :file:`configuration.nix` that describes your device
-and the services that you want to run on it. Start by copying
-:file:`vanilla-configuration.nix` and adjusting it, or look in the `examples`
-directory for some pre-written configurations.
+You need to create a :file:`configuration.nix` that describes your
+device and the services that you want to run on it. The best way to
+get started is by reading one of the examples such as
+:file:`examples/rotuer.nix` and modifying it to your needs.
 
 :file:`configuration.nix` conventionally describes the packages, services,
 user accounts etc of the device. It does not describe the hardware
 itself, which is specified separately in the build command (as you
 will see below).
 
-Your configuration may include modules: it probably *should*
-include the ``standard`` module unless you understand what it
-does and what happens if you leave it out.
+Most of the functionality of a Liminix system is driven by *services*
+which are declared by *modules*: thus, to add for example an NTP service
+you first add :file:`modules/ntp` to your ``imports`` list, then
+you create a service by calling :code:`config.system.service.ntp.build { .... }`
+with the appropriate service-dependent configuration parameters.
+
+.. code-block:: nix
+
+  let svc = config.system.service;
+  in {
+    # ...
+    imports = [
+      ./modules/ntp
+      # ....
+    ];
+    config.services.ntp = svc.ntp.build {
+      pools = { "pool.ntp.org" = ["iburst"]; };
+      makestep = { threshold = 1.0; limit = 3; };
+    };
+
+A :ref:`full list of module options <module-options>` is provided
+later in this manual.
+
+You *most likely* want to include the ``standard`` module unless you
+have a quite unusual use case for a very minimal system, in which case
+you will understand what it does and what happens if you leave it out.
 
 .. code-block:: nix
 
@@ -319,4 +342,6 @@ Caveats
 Configuration options
 *********************
 
+.. _module-options:
+
 .. include:: modules.rst

modules/base.nix

@@ -1,3 +1,7 @@
+## Base options
+## ============
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkEnableOption mkOption types isDerivation hasAttr ;

modules/busybox.nix

@@ -1,3 +1,11 @@
+## Busybox
+## =======
+##
+## Busybox provides stripped-down versions of many usual
+## Linux/Unix tools, and may be configured to include only
+## the commands (termed "applets") required by the user or
+## by other included modules.
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption mkEnableOption types mapAttrsToList;
@@ -47,12 +55,14 @@ in {
     programs.busybox = {
       applets =  mkOption {
         type = types.listOf types.str;
+        description = "Applets required";
         default = [];
         example = ["sh" "getty" "login"];
       };
       options = mkOption {
         # mostly the values are y n or m, but sometimes
         # other strings are also used
+        description = "Other busybox config flags that do not map directly to applet names (often prefixed FEATURE_)";
         type = types.attrsOf types.nonEmptyStr;
         default =  { };
       };

modules/hardware.nix

@@ -1,3 +1,11 @@
+## Hardware-dependent options
+## ==========================
+##
+## These are attributes of the hardware not of the application
+## you want to run on it, and would usually be set in the "device" file:
+## :file:`devices/manuf-model/default.nix`
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkEnableOption mkOption types isDerivation hasAttr ;

modules/ppp/default.nix

@@ -1,11 +1,12 @@
 ## PPP
 ## ===
 ##
-## A rudimentary PPPoE (PPP over Ethernet) configuration to address
-## the case where your Liminix device is connected to an upstream
-## network using PPPoE. This is typical for UK broadband connections
-## (except "cable"), and common in some other localities as well: ask
-## your ISP if this is you.
+## A PPPoE (PPP over Ethernet) configuration to address the case where
+## your Liminix device is connected to an upstream network using
+## PPPoE. This is typical for UK broadband connections where the
+## physical connection is made by OpenReach ("Fibre To The X") and
+## common in some other localities as well: ask your ISP if this is
+## you.
 
 { lib, pkgs, config, ...}:
 let

modules/users.nix

@@ -1,3 +1,16 @@
+## Users
+## =====
+##
+## User- and group-related configuration.
+##
+## Changes made here are reflected in files such as :file:/etc/shadow,
+## :file:/etc/passwd, :file:/etc/group etc. If you are familiar with
+## user configuration in NixOS, please note that Liminix does not have
+## the concept of "mutable users" - files in /etc/ are symlinks to
+## the immutable store, so you can't e.g  change a password with
+## :command:`passwd`
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib)