doc: Explain how to link to options in the manual

[nh2]

I'm trying to write a release notes entry and spending an unjustified amount of time trying to make the hyperlink to a NixOS option documentation work.

I want to link to systemd.services.<name>.unitConfig.

Searching in the existing release notes code, I found repeated usage of at least the following patterns, out of which only one works:

• <option>networking.interfaces.&lt;name&gt;.useDHCP = true;</option>
  • does not work, no hyperlink is created
• <varname>hardware.logitech.lcd.enable</varname>
  • does not work, no hyperlink is created; probably <varname> wasn't made for this
• <literal>security.acme.certs._name_.user</literal>
  • does not work (as expected, given that it's <literal>, no hyperlink is created, and that's probably fine given that this is the old value for the option), but it still renders wrong in the manual, namely as security.acme.certs._name_.user
• services.tinc.networks.<name>.bindToAddress
  • does not work (<literal> was used so no link is created)
• <xref linkend="opt-systemd.network.networks._name_.dhcpV4Config"/>
  • works

Thus, only few people seem to know how to link to a NixOS option, so the manual is full of non-working links.

Proposed solution

• Why does <option> even exist if it doesn't link correctly? Is it for command line options? We need to explain it.
• Could we have a <nixos-option> tag that "just works" without escaping and magic prefixes e.g. <nixos-option>systemd.services._name_.unitConfig</nixos-option>?
• We should recommend one way to refer to no-longer-existing / removed options (probably <literal>).
• We should explain somewhere easy to find what the correct way is, and that <option>, <varname>, <literal> are all wrong for this purpose.
  This should probaly be done in contributing-to-this-manual.xml.

---

CC a somwhat arbitrary list of contributers that might be interested/knowledgeable in this: @edolstra @jonringer @jtojnar @doronbehar

[nh2]

I cannot figure out how NixOS/rfcs#72 would affect or improve this.

In the example from there, the services.xserver.libinput.enable from the code listing links to the NixOS option correctly, but I don't know how they do it or where the sources for that are.

Can you tell me @mboes?

[jonringer]

A lot of this might change with the common mark rfc

[jtojnar]

DocBook elements have semantic definitions but not really a prescribed rendering. You can read their definitions in the DocBook documentation:

• https://tdg.docbook.org/tdg/5.0/literal.html
• https://tdg.docbook.org/tdg/5.0/option.html
• https://tdg.docbook.org/tdg/5.0/varname.html

Yeah, according to the specification <option> is for command options and we are overloading the meaning. I guess <varname> is the most correct choice but <option> sounds a lot nicer so it gets used most often 🤷‍♀️

In the default stylesheet we use for rendering DocBook to HTML, the elements are simply rendered as <code> or something similar, with class attribute to distinguish them for styling with CSS. If we want links, we need to add them separately.

We render the Options appendix as <variablelist>. Each entry is assigned an xml:id generated from its name like this:

nixpkgs/nixos/lib/make-options-doc/options-to-docbook.xsl

Line 23 in eaaf925

<xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '&lt;', '_'), '>', '_'))" />

The ID then can be used across the whole document by either:

• adding xlink:href="#opt-foo" attribute to any element – this will turn it into a link
• using <xref linkend="opt-foo" /> – this will create a link with automatically generated label based on the target (often used for chapters but will work for <varlistentry> too)

There are other options for linking, including a cross-document linking using olink but the two options above are the most relevant.

We could also add a rule to the stylesheet, that would linkify all <option>s that contain a string matching an existing NixOS option. Not sure how it would affect performance, though. A custom element would be easier in that regard since we could just replace it with <xref /> without any set up.

With the impending doom port to CommonMark, I am not sure if it is worth it to spend any time on this, though.

[FRidh]

I cannot figure out how NixOS/rfcs#72 would affect or improve this.

In the example from there, the services.xserver.libinput.enable from the code listing links to the NixOS option correctly, but I don't know how they do it or where the sources for that are.

Can you tell me @mboes?

I found the link to the sources NixOS/rfcs#72 (comment). As mentioned there, only a single file was markdown, the rest was actually the result of a docbook to restructuredtext conversion. Restructuredtext has a lot more metadata.

[stale]

I marked this as stale due to inactivity. → More info

[jonringer]

the 21.11 release notes will be written in markdown. Going to close as linking to options (at least in context of dockbook) is no longer relevant.

[jtojnar]

We still need to link to options and I have seen someone suggest the incorrect syntax on Matrix yesterday.

Currently, it is [`enable`](#opt-services.xserver.libinput.enable) for options with custom label and <xref linkend="opt-services.xserver.libinput.enable"/> for automatic label. Using the anchor format is important since otherwise (e.g. using options.html#hash) will cause the link not to be checked.

Linking options in submodules also is not trivial (replace <, > and * for _ in the anchor). Or just copy the anchor from the option link on the options page.

Eventually, I want to use empty links for the automatic anchors (e.g. [](#opt-services.xserver.libinput.enable)), which has precedent in MyST but we are not there yet.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-10-22-documentation-team-meeting-notes-12-nixcon-edition/22689/1