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)]
+  (tset modules "lib/modules.nix" nil)
-    (print (or (read-preamble name) (headline name)))
+  (let [module-names (doto (icollect [n _ (pairs modules)] n) table.sort)]
-    (let [options (sort-options module)]
+    (io.stderr:write (view module-names))
-      (each [_ o (ipairs options)]
+    (each [_ name (ipairs module-names)]
-        (if (= o.type "parametrisable s6-rc service definition")
+      (let [module (. modules name)
-            (print-service o)
+            options (sort-options module)]
-            (print-option o))))))
+        (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
+You need to create a :file:`configuration.nix` that describes your
-and the services that you want to run on it. Start by copying
+device and the services that you want to run on it. The best way to
-:file:`vanilla-configuration.nix` and adjusting it, or look in the `examples`
+get started is by reading one of the examples such as
-directory for some pre-written configurations.
+: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*
+Most of the functionality of a Liminix system is driven by *services*
-include the ``standard`` module unless you understand what it
+which are declared by *modules*: thus, to add for example an NTP service
-does and what happens if you leave it out.
+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
+## A PPPoE (PPP over Ethernet) configuration to address the case where
-## the case where your Liminix device is connected to an upstream
+## your Liminix device is connected to an upstream network using
-## network using PPPoE. This is typical for UK broadband connections
+## PPPoE. This is typical for UK broadband connections where the
-## (except "cable"), and common in some other localities as well: ask
+## physical connection is made by OpenReach ("Fibre To The X") and
-## your ISP if this is you.
+## 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)