convert nixos manpages to commonmark

NixOS / nixpkgs

Nix Packages collection & NixOS

MIT License

16.59k stars 13.07k forks source link

convert nixos manpages to commonmark #161122

Open Artturin opened 2 years ago

Artturin commented 2 years ago

./nixos/doc/manual/man-configuration.xml
./nixos/doc/manual/man-nixos-build-vms.xml
./nixos/doc/manual/man-nixos-enter.xml
./nixos/doc/manual/man-nixos-generate-config.xml
./nixos/doc/manual/man-nixos-install.xml
./nixos/doc/manual/man-nixos-option.xml
./nixos/doc/manual/man-nixos-rebuild.xml
./nixos/doc/manual/man-nixos-version.xml
./nixos/doc/manual/man-pages.xml

sternenseemann commented 2 years ago

I'd rather have them in mdoc/troff format to be honest, since they are dedicated man pages anyways. Nix >= 2.4 shows how atrocious the results are when using markdown for man pages.

pennae commented 1 year ago

we've looked into this a bit. we could use markdown to write manpages if we add a few more extensions, but since troff can also render to html (albeit slightly less pretty) it seems that mdoc/troff is the better source format for these files.