doc: Add support for manpage references

[jtojnar]

Motivation for this change

NixOS manual, especially its Options appendix often reference UNIX man pages. Unfortunately, unlike DocBook, Markdown does not support such references. But even DocBook’s rendering is not very useful for people not familiar with the foo(volnum) notation (NixOS/nixos-search#327).

First, let’s add support for MyST’s roles, which will allow us to reference it using {manpage}`foo(volnum)` syntax. Second, let’s add a filter that automatically linkifies stuff.

Additionally, since the syntax has been getting out of hand, let’s add a conversion script: maintainers/scripts/db-to-md.sh <file.xml>

What has been done

• Checked that everything still works and renders fine
  • Regenerated DocBook files for NixOS manual
  • Built Nixpkgs manual
  • Tested the conversion script
• Ported the changes to NixOS search: import-scripts: Linkify manpage links nixos-search#329

Related issues

NixOS search issue that triggered this: NixOS/nixos-search#303

Closes: #127394 – Pandoc filter that is now part of the conversion script.

cc @ryantm @blaggacao

Thanks @Kreyren for bringing this to my attention.

[ryantm]

I'm currently opposed to adding this syntax. Why can't we do this?

[tmpfiles.d(5)](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html)

[jtojnar]

As discussed on Matrix, I prefer having the man page reference decoupled from the (optional) on-line target. Especially for option documentation, which is the next area I will be focusing at.

I feel like adding explicit links is too much effort for option description authors – they would have to look for online versions of the man pages. Especially for the common ones (e.g. systemd.time(7)) we could do that automatically, as long as we know about the reference.

The second reason is that I needed some syntax to use by the docbook-to-markdown conversion script. I felt rST roles, or rather MyST syntax are a good choice since we might switch to MyST in the future anyway: #105036

The syntax is quite inobtrusive, renders reasonably on regular CommonMark renderers (GitHub) and if person does not know about it, they can always just omit it.

---

Rendered:

[jtojnar]

Merged as per discussion on Matrix. We can easily improve or remove the syntax in the future if we decide to.