nixos-manual: start gradual conversion to markdown

[raboof]

Basically copied from the nixpkgs manual infrastructure.

Converted 'installation/upgrading' as a test.

I guess we should find a way to represent the 'xref linkend'
links to 'proper' markdown as well

Motivation for this change

Wanted to document creating udev rules to load kernel modules when certain USB devices are plugged in, but didn't really want to deal with docbook, so shaved this yak first ;)

Things done

• Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
• Built on platform(s)
  • NixOS
  • macOS
  • other Linux distributions
• Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
• Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
• Tested execution of all binary files (usually in ./result/bin/)
• Determined the impact on package closure size (by running nix path-info -S before and after)
• Ensured that relevant documentation is up to date
• Fits CONTRIBUTING.md.

/cc @ryantm

[ryantm]

This approach may be problematic because NixOS needs to build it's own manual as part of rebuilds (I think).

Cc @jtojnar

[jtojnar]

That is right, NixOS systems depend on NixOS manual by default so we would have to introduce pandoc into the NixOS build closure. I would not mind since we compile pandoc statically these days and its closure is pretty small, and for most people, the binary cache is leveraged for the manual anyway, but there was some opposition, particularly from @edolstra.

Also, I do not think it is really possible to achieve the closure size of libxslt + docbook-xsl if we want to use anything but the barest CommonMark implementation. And NixOS/rfcs#72 mandates extensibility and I am not aware of any extensible Markdown implementations outside of Pandoc, Python/Sphinx and JavaScript ecosystems.

Since NixOS/rfcs#72, was not concrete enough, I am afraid we cannot really do much until the expectations for building NixOS manual are settled.

[raboof]

OK, I guess this change is premature :). Let's gather some experience converting the nixpkgs manual, and revisit this later.

NixOS systems depend on NixOS manual by default

Random thought: in the "in case of emergency" situations where this is useful, I'd be happy reading the raw markdown version...

[edolstra]

Also, I do not think it is really possible to achieve the closure size of libxslt + docbook-xsl if we want to use anything but the barest CommonMark implementation.

Given that Markdown is supposed to be a light-weight, trivial format, it would be quite sad if it required adding gigabytes and hours of build-time dependencies...

Of course, we could disable building the manual by default (see #83871) in which case the issue would be moot.

[jtojnar]

Given that Markdown is supposed to be a light-weight, trivial format, it would be quite sad if it required adding gigabytes and hours of build-time dependencies...

Well, the issue is that that supposition is at odds with requirements for complex technical documentation documents. That is why CommonMark/Markdown is almost never used as is and most implementations extend it. Even NixOS/rfcs#72, vague as it is on other implementation details, acknowledges the necessity of extensions.

[ryantm]

@raboof We can still move forward with the conversion without including Pandoc in the closure, we just need to store the generated Docbook XML files in the git repository. I was thinking there could be a separate folder for these generated documents so we don't accidentally edit them manually.

[flokli]

Copied from #107444 (comment):

Keeping both files in sync won't work. People are not aware they need to edit both files when updating docs, and these files will just diverge.

Yes, pandoc is a heavy ask, but we also build half of firefox due to polkit rules being in javascript, so having pandoc in the build closure is a small problem - and if people want to quickly iterate on a new rebuild, disabling the manual for that local test is probably the better way forward than dumping two different and slowly diverging documentation file formats.