Do you have a script for adding the links? I think it would be best if the links were added during the build, otherwise the files will be quite messy or people will keep forgetting to add the links.

Do you have a script for adding the links? I think it would be best if the links were added during the build, otherwise the files will be quite messy or people will keep forgetting to add the links.

Unfortunately no - they were added by hand.

Automating the process is non-trivial, for the following reasons:

• the tool would need to differentiate between terms which are options and terms which are package names. e.g. services.postgresql.package and pkgs.postgresql96 are defined in different places (and I don't know if the latter always has documentation)
• the tool would need to be capable of parsing Nix, so that it could understand that foo.bar = { baz = null } means that the link should reference foo.bar.baz
• the tool would need to understand wildcards like systemd.services._name_.serviceConfig
• we'd probably need to extend the docbook syntax somehow so that the tool would know which sections to replace, since not all <programlisting>s contain Nix, and not all Nix is in <programlisting>s
• what dependencies do we consider acceptable for building the manual? Haskell is a good fit for this kind of problem and already has libraries for parsing Nix, but I don't know how maintainable the community would find it

It's not unfeasible, but it's a decent chunk of work. My suggestion is that we start by manually maintaining the links, and figure out how/if we want to automate it.

Just one issue: you've modified the indentation in various places, which is mostly fine, except in some cases where the elements actually preserve whitespace, particularly sections. In these cases it results in worse rendering, since the leading whitespace is preserved. However, I see you've also fixed the same issue in some other places, which is also nice.

I was learning the docbook syntax as I worked through this, so I probably did those sections before I realised that <screen> preserved indentation. Should be fixed now, let me know if I've missed any.

This should be ready to merge now, unless I've missed anything.

what dependencies do we consider acceptable for building the manual? Haskell is a good fit for this kind of problem and already has libraries for parsing Nix, but I don't know how maintainable the community would find it

Haskell is much too big. NixOS docs's build closure should remain fairly small.