Merge pull request #14700: olinks for NixOS manual

This allows to use <olink> tags inside NixOS options to reference
sections from the manual. I've originally introduced it in #14476 to
reference the Taskserver specific documentation from the options
reference but as suggested by @nbp, this was done as a separate pull
request to ensure greater visibility rather than being "hidden" in the
Taskserver branch.

The build time for the manual is around 30s on my machine without this
change and 34s with this change, so it shouldn't have a very big impact
on the build time of the manual.

Olinks between the options reference and the manual now will look like
this:

"More instructions about NixOS in conjuction with Taskserver can be
found in the NixOS manual at Chapter 15, Taskserver."

More documentation about olinks can be found here:

http://www.sagehill.net/docbookxsl/Olinking.html

Acked-by: Eelco Dolstra <eelco.dolstra@logicblox.com>

1 files changed, 62 insertions, 13 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 86a39322ba51..50b1bb9c7354 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -74,6 +74,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.
@@ -116,18 +173,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
 
@@ -159,6 +206,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
 
@@ -178,7 +226,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
@@ -190,6 +238,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
     '';