nixos/man: prevent duplication of options

[jtojnar]

Description of changes

libxslt 1.1.35 fixed conflict resolution for templates to match the specification. This uncovered a bug in docbook-xsl (docbook/xslt10-stylesheets#240), which causes option names to be duplicated into the option descriptions.

Until it is resolved upstream, let’s fix the conflict by ambiguity by moving the link to a different element.

Fixes: #166304

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 22.05 Release Notes (or backporting 21.11 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

[dtzWill]

Thanks for tackling this!

I can confirm this resolves the reported issue. Although not quite out of the woods yet.

I'm not familiar with docbook really ("what other impact might moving this have?"), so instead of trying to sort that went and diff(oscope)d the manuals (man/html/epub) before and after.

And unfortunately this also changes the HTML and epub manuals.

The HTML one seems visually fine (although options are now blue instead of the red-ish 'code' styling), but comparing with old manual, there are lots of differences like this:

334c334
<                 <a class="xref" href="options.html#opt-boot.loader.grub.device"><code class="option">boot.loader.grub.device</code></a> to
---
>                 <a class="xref" href="options.html#opt-boot.loader.grub.device"><code class="option"><a class="option" href="options.html#opt-boot.loader.grub.device">boot.loader.grub.device</a></code></a> to
341c341
<                 <a class="xref" href="options.html#opt-boot.loader.systemd-boot.enable"><code class="option">boot.loader.systemd-boot.enable</code></a>
---
>                 <a class="xref" href="options.html#opt-boot.loader.systemd-boot.enable"><code class="option"><a class="option" href="options.html#opt-boot.loader.systemd-boot.enable">boot.loader.systemd-boot.enable</a></code></a>

So it seems we're now generating a nested <a> for options now (<a ...><code ...><a ...>$optionname</a></code></a>)?

The epub manual diffoscope appears to be the same sort of change, I haven't looked more closely.

For now, just reporting what I found. No answers/solutions yet 😇 .

[jtojnar]

Weird, building the manual with nix-build nixos/release.nix -A manualHTML.x86_64-linux and looking at result/share/doc/nixos/options.html, I see only single link:

[dtzWill]

Weird, building the manual with nix-build nixos/release.nix -A manualHTML.x86_64-linux and looking at result/share/doc/nixos/options.html, I see only single link:

Wow I wasn't sure how this was possible (some impurity from somewhere?) until realized: I was comparing the index.html's while you compared the options.html. Only you mentioned which you compared and I didn't 😇 .

With this detail realized, I agree options.html only has the one link. index.html has the change I mentioned, however.
And comparing against the manual before this, options.html has a change as well:

Before:

<code class="option">appstream.enable</code>

After:

<a class="option" href="options.html#opt-appstream.enable">appstream.enable</a>

Which changes the manual visually and makes each option a link to itself (same page, but with anchor for that option). This actually seems like reasonable or even desirable behavior for me-- it helps easily create links to options if you're browsing and want to share.

Anyway, mostly want to make sure we like the new output! 👍

[jtojnar]

Oh, that makes sense, the xrefs will transclude the target element contents by default.

[jtojnar]

I tried to move the id attribute to a separate link:

--- a/nixos/lib/make-options-doc/options-to-docbook.xsl
+++ b/nixos/lib/make-options-doc/options-to-docbook.xsl
@@ -22,11 +22,13 @@
         <xsl:for-each select="attrs">
           <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '&lt;', '_'), '>', '_'), ':', '_'))" />
           <varlistentry>
-            <term xlink:href="#{$id}">
-              <xsl:attribute name="xml:id"><xsl:value-of select="$id"/></xsl:attribute>
-              <option>
-                <xsl:value-of select="attr[@name = 'name']/string/@value" />
-              </option>
+            <term>
+              <link xlink:href="#{$id}">
+                <xsl:attribute name="xml:id"><xsl:value-of select="$id"/></xsl:attribute>
+                <option>
+                  <xsl:value-of select="attr[@name = 'name']/string/@value" />
+                </option>
+              </link>
             </term>
 
             <listitem>

But that does not work either:

Don't know what gentext to create for xref to: "link"

Forgot that xref can only link to certain elements.

[jtojnar]

I applied a patch to the stylesheets that should resolve the issue. Limiting scope to the manual to avoid stdenv rebuild.

[dtzWill]

Thanks!!