doc/manual: use `nixos-render-docs`

Now that all the DocBook documentation is gone, we can switch to the
new NixOS documentation generator. No meaningful change in HTML output,
except that I removed the rather pointless preface and changed the
title accordingly. Manual page output is greatly improved; it was
kind of broken before. The `sed` hack is pretty gross but I have
confirmed that nixpkgs will be happy to accept a PR to make things
a little more customizable.

This also drops the `manual` alias (deprecated in nixpkgs in 2018
and imported into nix-darwin), and `manualEpub` (because the NixOS
documentation generator doesn't support it and also nobody wants this
as an ebook).

6 files changed, 66 insertions, 566 deletions

diff --git a/doc/manual/default.nix b/doc/manual/default.nix
index 2ebd514..2225b51 100644
--- a/doc/manual/default.nix
+++ b/doc/manual/default.nix
@@ -40,145 +40,7 @@ let
     };
   };
 
-  sources = lib.sourceFilesBySuffices ./. [".xml"];
-
-  modulesDoc = builtins.toFile "modules.xml" ''
-    <section xmlns:xi="http://www.w3.org/2001/XInclude" id="modules">
-    ${(lib.concatMapStrings (path: ''
-      <xi:include href="${path}" />
-    '') (lib.catAttrs "value" (config.meta.doc or [])))}
-    </section>
-  '';
-
-  generatedSources = runCommand "generated-docbook" {} ''
-    mkdir $out
-    ln -s ${modulesDoc} $out/modules.xml
-    ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml
-    printf "%s" "${version}" > $out/version
-  '';
-
-  copySources =
-    ''
-      cp -prd $sources/* . || true
-      ln -s ${generatedSources} ./generated
-      chmod -R u+w .
-    '';
-
-  toc = builtins.toFile "toc.xml"
-    ''
-      <toc role="chunk-toc">
-        <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-darwin-manual"><?dbhtml filename="index.html"?>
-          <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry>
-          <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry>
-        </d:tocentry>
-      </toc>
-    '';
-
-  manualXsltprocOptions = toString [
-    "--param section.autolabel 1"
-    "--param section.label.includes.component.label 1"
-    "--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"
-    "--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"
-    "--param xref.with.number.and.title 1"
-    "--param toc.section.depth 3"
-    "--stringparam admon.style ''"
-    "--stringparam callout.graphics.extension .svg"
-    "--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}"
-  ];
-
-  manual-combined = runCommand "darwin-manual-combined"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
-      meta.description = "The NixOS manual as plain docbook XML";
-    }
-    ''
-      ${copySources}
-
-      xmllint --xinclude --output ./manual-combined.xml ./manual.xml
-      xmllint --xinclude --noxincludenode \
-         --output ./man-pages-combined.xml ./man-pages.xml
-
-      # outputs the context of an xmllint error output
-      # LEN lines around the failing line are printed
-      function context {
-        # length of context
-        local LEN=6
-        # lines to print before error line
-        local BEFORE=4
-
-        # xmllint output lines are:
-        # file.xml:1234: there was an error on line 1234
-        while IFS=':' read -r file line rest; do
-          echo
-          if [[ -n "$rest" ]]; then
-            echo "$file:$line:$rest"
-            local FROM=$(($line>$BEFORE ? $line - $BEFORE : 1))
-            # number lines & filter context
-            nl --body-numbering=a "$file" | sed -n "$FROM,+$LEN p"
-          else
-            if [[ -n "$line" ]]; then
-              echo "$file:$line"
-            else
-              echo "$file"
-            fi
-          fi
-        done
-      }
-
-      function lintrng {
-        xmllint --debug --noout --nonet \
-          --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \
-          "$1" \
-          2>&1 | context 1>&2
-          # ^ redirect assumes xmllint doesn’t print to stdout
-      }
-
-      lintrng manual-combined.xml
-      lintrng man-pages-combined.xml
-
-      mkdir $out
-      cp manual-combined.xml $out/
-      cp man-pages-combined.xml $out/
-    '';
-
-  olinkDB = runCommand "manual-olinkdb"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
-    }
-    ''
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam collect.xref.targets only \
-        --stringparam targets.filename "$out/manual.db" \
-        --nonet \
-        ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \
-        ${manual-combined}/manual-combined.xml
-
-      cat > "$out/olinkdb.xml" <<EOF
-      <?xml version="1.0" encoding="utf-8"?>
-      <!DOCTYPE targetset SYSTEM
-        "file://${docbook_xsl_ns}/xml/xsl/docbook/common/targetdatabase.dtd" [
-        <!ENTITY manualtargets SYSTEM "file://$out/manual.db">
-      ]>
-      <targetset>
-        <targetsetinfo>
-            Allows for cross-referencing olinks between the manpages
-            and manual.
-        </targetsetinfo>
-
-        <document targetdoc="manual">&manualtargets;</document>
-      </targetset>
-      EOF
-    '';
-
 in rec {
-  inherit generatedSources;
-
   # TODO: Use `optionsDoc.optionsJSON` directly once upstream
   # `nixosOptionsDoc` is more customizable.
   optionsJSON = runCommand "options.json"
@@ -194,10 +56,10 @@ in rec {
           "$out/share/doc/darwin"
     '';
 
-  # Generate the NixOS manual.
+  # Generate the nix-darwin manual.
   manualHTML = runCommand "darwin-manual-html"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
+      styles = lib.sourceFilesBySuffices (pkgs.path + "/doc") [ ".css" ];
       meta.description = "The Darwin manual in HTML format";
       allowedReferences = ["out"];
     }
@@ -205,82 +67,75 @@ in rec {
       # Generate the HTML manual.
       dst=$out/share/doc/darwin
       mkdir -p $dst
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
-        --stringparam id.warnings "1" \
-        --nonet --output $dst/ \
-        ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \
-        ${manual-combined}/manual-combined.xml \
-        |& tee xsltproc.out
-      grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false
-      rm xsltproc.out
-
-      mkdir -p $dst/images/callouts
-      cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/
 
-      cp ${./style.css} $dst/style.css
-      cp ${./overrides.css} $dst/overrides.css
+      cp $styles/style.css $dst
+      cp $styles/overrides.css $dst
       cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
 
+      substitute ${./manual.md} manual.md \
+        --replace '@DARWIN_VERSION@' "${version}"\
+        --replace \
+          '@DARWIN_OPTIONS_JSON@' \
+          ${optionsJSON}/share/doc/darwin/options.json
+
+      # TODO: --manpage-urls?
+      nixos-render-docs -j $NIX_BUILD_CORES manual html \
+        --manpage-urls ${pkgs.writeText "manpage-urls.json" "{}"} \
+        --revision ${lib.escapeShellArg revision} \
+        --generator "nixos-render-docs ${pkgs.lib.version}" \
+        --stylesheet style.css \
+        --stylesheet overrides.css \
+        --stylesheet highlightjs/mono-blue.css \
+        --script ./highlightjs/highlight.pack.js \
+        --script ./highlightjs/loader.js \
+        --toc-depth 1 \
+        --chunk-toc-depth 1 \
+        ./manual.md \
+        $dst/index.html
+
       mkdir -p $out/nix-support
       echo "nix-build out $out" >> $out/nix-support/hydra-build-products
       echo "doc manual $dst" >> $out/nix-support/hydra-build-products
-    ''; # */
-
-  # Alias for backward compatibility. TODO(@oxij): remove eventually.
-  manual = manualHTML;
+    '';
 
-  # Index page of the NixOS manual.
+  # Index page of the nix-darwin manual.
   manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
 
-  manualEpub = runCommand "darwin-manual-epub"
-    { inherit sources;
-      buildInputs = [ libxml2.bin libxslt.bin zip ];
-    }
-    ''
-      # Generate the epub manual.
-      dst=$out/share/doc/darwin
-
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
-        --nonet --xinclude --output $dst/epub/ \
-        ${docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
-        ${manual-combined}/manual-combined.xml
-
-      mkdir -p $dst/epub/OEBPS/images/callouts
-      cp -r ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/epub/OEBPS/images/callouts # */
-      echo "application/epub+zip" > mimetype
-      manual="$dst/darwin-manual.epub"
-      zip -0Xq "$manual" mimetype
-      cd $dst/epub && zip -Xr9D "$manual" *
-
-      rm -rf $dst/epub
+  manualEpub = builtins.throw "The nix-darwin EPUB manual has been removed.";
 
-      mkdir -p $out/nix-support
-      echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products
-    '';
-
-
-  # Generate the NixOS manpages.
+  # Generate the nix-darwin manpages.
   manpages = runCommand "darwin-manpages"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
       allowedReferences = ["out"];
     }
     ''
       # Generate manpages.
-      mkdir -p $out/share/man
-      xsltproc --nonet \
-        --maxdepth 6000 \
-        --param man.output.in.separate.dir 1 \
-        --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" \
-        ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \
-        ${manual-combined}/man-pages-combined.xml
+      mkdir -p $out/share/man/man5
+      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
+        --revision ${lib.escapeShellArg revision} \
+        ${optionsJSON}/share/doc/darwin/options.json \
+        $out/share/man/man5/configuration.nix.5
+
+      # TODO: get these parameterized in upstream nixos-render-docs
+      sed -i -e '
+        /^\.TH / s|NixOS|Darwin|g
+
+        /^\.SH "NAME"$/ {
+          N
+          s|NixOS|Darwin|g
+        }
+
+        /^\.SH "DESCRIPTION"$/ {
+          N; N
+          s|/etc/nixos/configuration|configuration|g
+          s|NixOS|Darwin|g
+          s|nixos|darwin|g
+        }
+
+        /\.SH "AUTHORS"$/ {
+          N; N
+          s|Eelco Dolstra and the Nixpkgs/NixOS contributors|Daiderd Jordan and the nix-darwin contributors|g
+        }
+      ' $out/share/man/man5/configuration.nix.5
     '';
-
 }
diff --git a/doc/manual/man-pages.xml b/doc/manual/man-pages.xml
deleted file mode 100644
index 2490f63..0000000
--- a/doc/manual/man-pages.xml
+++ /dev/null
@@ -1,42 +0,0 @@
-<reference xmlns="http://docbook.org/ns/docbook"
-           xmlns:xlink="http://www.w3.org/1999/xlink"
-           xmlns:xi="http://www.w3.org/2001/XInclude">
- <title>Darwin Reference Pages</title>
- <info>
-  <author><personname><firstname>Daiderd</firstname><surname>Jordan</surname></personname>
-   <contrib>Author</contrib>
-  </author>
-  <copyright><year>2016-2019</year><holder>Daiderd Jordan</holder>
-  </copyright>
- </info>
-
- <refentry>
-  <refmeta>
-   <refentrytitle><filename>configuration.nix</filename>
-   </refentrytitle><manvolnum>5</manvolnum>
-   <refmiscinfo class="source">Darwin</refmiscinfo>
- <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
-  </refmeta>
-  <refnamediv>
-   <refname><filename>configuration.nix</filename>
-   </refname><refpurpose>Darwin system configuration specification</refpurpose>
-  </refnamediv>
-  <refsection>
-   <title>Description</title>
-   <para>
-    The file <filename>configuration.nix</filename> contains the
-    declarative specification of your Darwin system configuration. The command
-    <command>darwin-rebuild</command> takes this file and realises the system
-    configuration specified therein.
-   </para>
-  </refsection>
-  <refsection>
-   <title>Options</title>
-   <para>
-    You can use the following options in <filename>configuration.nix</filename>.
-   </para>
-   <xi:include href="./generated/options-db.xml"
-               xpointer="configuration-variable-list" />
-  </refsection>
- </refentry>
-</reference>
diff --git a/doc/manual/manual.md b/doc/manual/manual.md
new file mode 100644
index 0000000..131df7d
--- /dev/null
+++ b/doc/manual/manual.md
@@ -0,0 +1,8 @@
+# Darwin Configuration Options {#book-darwin-manual}
+## Version @DARWIN_VERSION@
+
+```{=include=} options
+id-prefix: opt-
+list-id: configuration-variable-list
+source: @DARWIN_OPTIONS_JSON@
+```
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
deleted file mode 100644
index a334342..0000000
--- a/doc/manual/manual.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<book xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="book-darwin-manual">
- <info>
-  <title>Darwin Manual</title>
-  <subtitle>Version <xi:include href="./generated/version" parse="text" />
-  </subtitle>
- </info>
- <preface xml:id="preface">
-  <title>Preface</title>
-  <para>Nix modules for darwin.</para>
- </preface>
- <chapter xml:id="sec-options">
-  <title>Configuration Options</title>
-  <xi:include href="./generated/options-db.xml"
-              xpointer="configuration-variable-list" />
- </chapter>
-</book>
-
diff --git a/doc/manual/overrides.css b/doc/manual/overrides.css
deleted file mode 100644
index 4c7d4a3..0000000
--- a/doc/manual/overrides.css
+++ /dev/null
@@ -1,9 +0,0 @@
-.docbook .xref img[src^=images\/callouts\/],
-.screen img,
-.programlisting img {
-    width: 1em;
-}
-
-.calloutlist img {
-    width: 1.5em;
-}
diff --git a/doc/manual/style.css b/doc/manual/style.css
deleted file mode 100644
index 474dd32..0000000
--- a/doc/manual/style.css
+++ /dev/null
@@ -1,291 +0,0 @@
-/* Copied from http://bakefile.sourceforge.net/, which appears
-   licensed under the GNU GPL. */
-
-
-/***************************************************************************
-                             Basic headers and text:
- ***************************************************************************/
-
-body
-{
-    font-family: "Nimbus Sans L", sans-serif;
-    font-size: 1em;
-    background: white;
-    margin: 2em 1em 2em 1em;
-}
-
-h1, h2, h3, h4
-{
-    color: #005aa0;
-}
-
-h1 /* title */
-{
-    font-size: 200%;
-}
-
-h2 /* chapters, appendices, subtitle */
-{
-    font-size: 180%;
-}
-
-div.book
-{
-    text-align: center;
-}
-
-div.book > div
-{
-    /*
-     * based on https://medium.com/@zkareemz/golden-ratio-62b3b6d4282a
-     * we do 70 characters per line to fit code listings better
-     * 70 * (font-size / 1.618)
-     * expression for emacs:
-     * (* 70 (/ 1 1.618))
-     */
-    max-width: 43.2em;
-    text-align: left;
-    margin: auto;
-}
-
-/* Extra space between chapters, appendices. */
-div.chapter > div.titlepage h2, div.appendix > div.titlepage h2
-{
-    margin-top: 1.5em;
-}
-
-div.section > div.titlepage h2 /* sections */
-{
-    font-size: 150%;
-    margin-top: 1.5em;
-}
-
-h3 /* subsections */
-{
-    font-size: 125%;
-}
-
-div.simplesect h2
-{
-    font-size: 110%;
-}
-
-div.appendix h3
-{
-    font-size: 150%;
-    margin-top: 1.5em;
-}
-
-div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
-{
-    margin-top: 1.4em;
-    font-size: 125%;
-}
-
-div.refsection h3
-{
-    font-size: 110%;
-}
-
-
-/***************************************************************************
-                               Examples:
- ***************************************************************************/
-
-div.example
-{
-    border: 1px solid #b0b0b0;
-    padding: 6px 6px;
-    margin-left: 1.5em;
-    margin-right: 1.5em;
-    background: #f4f4f8;
-    border-radius: 0.4em;
-    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
-}
-
-div.example p.title
-{
-    margin-top: 0em;
-}
-
-div.example pre
-{
-    box-shadow: none;
-}
-
-
-/***************************************************************************
-                            Screen dumps:
- ***************************************************************************/
-
-pre.screen, pre.programlisting
-{
-    border: 1px solid #b0b0b0;
-    padding: 3px 3px;
-    margin-left: 0.5em;
-    margin-right: 0.5em;
-
-    background: #f4f4f8;
-    font-family: monospace;
-    border-radius: 0.4em;
-    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
-}
-
-div.example pre.programlisting
-{
-    border: 0px;
-    padding: 0 0;
-    margin: 0 0 0 0;
-}
-
-/***************************************************************************
-                               Notes, warnings etc:
- ***************************************************************************/
-
-.note, .warning
-{
-    border: 1px solid #b0b0b0;
-    padding: 3px 3px;
-    margin-left: 1.5em;
-    margin-right: 1.5em;
-    margin-bottom: 1em;
-    padding: 0.3em 0.3em 0.3em 0.3em;
-    background: #fffff5;
-    border-radius: 0.4em;
-    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
-}
-
-div.note, div.warning
-{
-    font-style: italic;
-}
-
-div.note h3, div.warning h3
-{
-    color: red;
-    font-size: 100%;
-    padding-right: 0.5em;
-    display: inline;
-}
-
-div.note p, div.warning p
-{
-    margin-bottom: 0em;
-}
-
-div.note h3 + p, div.warning h3 + p
-{
-    display: inline;
-}
-
-div.note h3
-{
-    color: blue;
-    font-size: 100%;
-}
-
-div.navfooter *
-{
-    font-size: 90%;
-}
-
-
-/***************************************************************************
-                        Links colors and highlighting:
- ***************************************************************************/
-
-a { text-decoration: none; }
-a:hover { text-decoration: underline; }
-a:link { color: #0048b3; }
-a:visited { color: #002a6a; }
-
-
-/***************************************************************************
-                              Table of contents:
- ***************************************************************************/
-
-div.toc
-{
-    font-size: 90%;
-}
-
-div.toc dl
-{
-    margin-top: 0em;
-    margin-bottom: 0em;
-}
-
-
-/***************************************************************************
-                               Special elements:
- ***************************************************************************/
-
-tt, code
-{
-    color: #400000;
-}
-
-.term
-{
-    font-weight: bold;
-
-}
-
-div.variablelist dd p, div.glosslist dd p
-{
-    margin-top: 0em;
-}
-
-div.variablelist dd, div.glosslist dd
-{
-    margin-left: 1.5em;
-}
-
-div.glosslist dt
-{
-    font-style: italic;
-}
-
-.varname
-{
-    color: #400000;
-}
-
-span.command strong
-{
-    font-weight: normal;
-    color: #400000;
-}
-
-div.calloutlist table
-{
-    box-shadow: none;
-}
-
-table
-{
-    border-collapse: collapse;
-    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
-}
-
-table.simplelist
-{
-    text-align: left;
-    color: #005aa0;
-    border: 0;
-    padding: 5px;
-    background: #fffff5;
-    font-weight: normal;
-    font-style: italic;
-    box-shadow: none;
-    margin-bottom: 1em;
-}
-
-div.navheader table, div.navfooter table {
-    box-shadow: none;
-}
-
-div.affiliation
-{
-    font-style: italic;
-}