nixos/doc: Allow refs from options to the manual

My first attempt to do this was to just use a conditional <refsection/>
in order to not create exact references in the manpage but create the
reference in the HTML manual, as suggested by @edolstra on IRC.

Later I went on to use <olink/> to reference sections of the manual, but
in order to do that, we need to overhaul how we generate the manual and
manpages.

So, that's where we are now:

There is a new derivation called "manual-olinkdb", which is the olinkdb
for the HTML manual, which in turn creates the olinkdb.xml file and the
manual.db. The former contains the targetdoc references and the latter
the specific targetptr elements.

The reason why I included the olinkdb.xml verbatim is that first of all
the DTD is dependent on the Docbook XSL sources and the references
within the olinkdb.xml entities are relative to the current directory.

So using a store path for that would end up searching for the manual.db
directly in /nix/store/manual.db.

Unfortunately, the <olinks/> that end up in the output file are
relative, so for example if you're clicking on one of these within the
PDF, the URL is searched in the current directory.

However, the sections from the olink's text are still valid, so we could
use an alternative URL for that in the future.

The manual doesn't contain any links, so even referencing the relative
URL shouldn't do any harm.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @edolstra

1 files changed, 62 insertions, 13 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 130b016aa266..6261f83ac8b2 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -73,6 +73,63 @@ let
       </toc>
     '';
 
+  manualXsltprocOptions = toString [
+    "--param section.autolabel 1"
+    "--param section.label.includes.component.label 1"
+    "--stringparam html.stylesheet style.css"
+    "--param xref.with.number.and.title 1"
+    "--param toc.section.depth 3"
+    "--stringparam admon.style ''"
+    "--stringparam callout.graphics.extension .gif"
+    "--stringparam current.docid manual"
+    "--param chunk.section.depth 0"
+    "--param chunk.first.sections 1"
+    "--param use.id.as.filename 1"
+    "--stringparam generate.toc 'book toc appendix toc'"
+    "--stringparam chunk.toc ${toc}"
+  ];
+
+  olinkDB = stdenv.mkDerivation {
+    name = "manual-olinkdb";
+
+    inherit sources;
+
+    buildInputs = [ libxml2 libxslt ];
+
+    buildCommand = ''
+      ${copySources}
+
+      xsltproc \
+        ${manualXsltprocOptions} \
+        --stringparam collect.xref.targets only \
+        --stringparam targets.filename "$out/manual.db" \
+        --nonet --xinclude \
+        ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \
+        ./manual.xml
+
+      # Check the validity of the man pages sources.
+      xmllint --noout --nonet --xinclude --noxincludenode \
+        --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \
+        ./man-pages.xml
+
+      cat > "$out/olinkdb.xml" <<EOF
+      <?xml version="1.0" encoding="utf-8"?>
+      <!DOCTYPE targetset SYSTEM
+        "file://${docbook5_xsl}/xml/xsl/docbook/common/targetdatabase.dtd" [
+        <!ENTITY manualtargets SYSTEM "file://$out/manual.db">
+      ]>
+      <targetset>
+        <targetsetinfo>
+            Allows for cross-referencing olinks between the manpages
+            and the HTML/PDF manuals.
+        </targetsetinfo>
+
+        <document targetdoc="manual">&manualtargets;</document>
+      </targetset>
+      EOF
+    '';
+  };
+
 in rec {
 
   # The NixOS options in JSON format.
@@ -115,18 +172,8 @@ in rec {
       dst=$out/share/doc/nixos
       mkdir -p $dst
       xsltproc \
-        --param section.autolabel 1 \
-        --param section.label.includes.component.label 1 \
-        --stringparam html.stylesheet style.css \
-        --param xref.with.number.and.title 1 \
-        --param toc.section.depth 3 \
-        --stringparam admon.style "" \
-        --stringparam callout.graphics.extension .gif \
-        --param chunk.section.depth 0 \
-        --param chunk.first.sections 1 \
-        --param use.id.as.filename 1 \
-        --stringparam generate.toc "book toc appendix toc" \
-        --stringparam chunk.toc ${toc} \
+        ${manualXsltprocOptions} \
+        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
         --nonet --xinclude --output $dst/ \
         ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl ./manual.xml
 
@@ -158,6 +205,7 @@ in rec {
       dst=$out/share/doc/nixos
       mkdir -p $dst
       xmllint --xinclude manual.xml | dblatex -o $dst/manual.pdf - \
+        -P target.database.document="${olinkDB}/olinkdb.xml" \
         -P doc.collab.show=0 \
         -P latex.output.revhistory=0
 
@@ -177,7 +225,7 @@ in rec {
     buildCommand = ''
       ${copySources}
 
-      # Check the validity of the manual sources.
+      # Check the validity of the man pages sources.
       xmllint --noout --nonet --xinclude --noxincludenode \
         --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \
         ./man-pages.xml
@@ -189,6 +237,7 @@ in rec {
         --param man.output.base.dir "'$out/share/man/'" \
         --param man.endnotes.are.numbered 0 \
         --param man.break.after.slash 1 \
+        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
         ${docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \
         ./man-pages.xml
     '';