Man pages in mdoc(7) or equivalent #982

New issue

Open

opened 2025-08-28 22:53:08 +00:00 by sterni · 4 comments

sterni commented

2025-08-28 22:53:08 +00:00

The man pages currently shipped with Lix (which we inherited from Nix) are lower quality than they could be because they are conversions from markdown which is less expressive than the (domain specific) target languange mdoc.

Describe the solution you'd like

Convert the existing Lix man pages to mdoc.

Describe alternatives you've considered

Doing nothing.
Using scdoc. Scdoc doesn't actually support a lot of the semantic markup for documenting command line utilities which mdoc provides, so there is not a big advantage over using markdown.
DocBook. We probably don't want to go back to that (Nix 2.3 used it for the man pages).
AsciiDoc, similar to scdoc.
Using pandoc instead of lowdown for the conversion. I don't know if the man page output for pandoc is better than the one for lowdown, but I doubt it since pandoc has a generic intermediate representation which is designed around markdown mainly. Also depending on GHC for the Lix documentation is probably a nightmare.
Improving the existing markdown man pages (with lowdown for conversion). It is possible that we can for example get rid of the annoying links and get proper cross references. Not sure.
skribilio-mdoc, probably not ready.

Other consideration

For the manual, we may need markdown versions of the man pages. mandoc supports converting to markdown, but doesn't support certain features (e.g. tables). It also doesn't take advantage of CommonMark, e.g. I don't think there are proper definition lists.

## Is your feature request related to a problem? Please describe. The man pages currently shipped with Lix (which we inherited from Nix) are lower quality than they could be because they are conversions from markdown which is less expressive than the (domain specific) target languange mdoc. ## Describe the solution you'd like Convert the existing Lix man pages to [mdoc](https://mandoc.bsd.lv/man/mdoc.7.html). ## Describe alternatives you've considered - Doing nothing. - Using [scdoc](https://git.sr.ht/~sircmpwn/scdoc/). Scdoc doesn't actually support a lot of the semantic markup for documenting command line utilities which mdoc provides, so there is not a big advantage over using markdown. - DocBook. We probably don't want to go back to that (Nix 2.3 used it for the man pages). - AsciiDoc, similar to scdoc. - [Using pandoc](https://pandoc.org/MANUAL.html#variables-for-man-pages) instead of lowdown for the conversion. I don't know if the man page output for pandoc is better than the one for lowdown, but I doubt it since pandoc has a generic intermediate representation which is designed around markdown mainly. Also depending on GHC for the Lix documentation is probably a nightmare. - Improving the existing markdown man pages (with lowdown for conversion). It is possible that we can for example get rid of the annoying links and get proper cross references. Not sure. - [skribilio-mdoc](https://git.8pit.net/skribilo-mdoc/), probably not ready. ## Other consideration For the manual, we may need markdown versions of the man pages. [mandoc](https://mandoc.bsd.lv/) supports [converting to markdown](https://mandoc.bsd.lv/man/mandoc.1.html#Markdown_Output), but doesn't support certain features (e.g. tables). It also doesn't take advantage of CommonMark, e.g. I don't think there are proper definition lists.

pennae commented

2025-08-28 23:19:48 +00:00

Owner

why not use nixos-render-docs? that has most of the features we'd want and can render to manpages

sterni commented

2025-08-29 12:28:34 +00:00

Author

@pennae wrote in #982 (comment):

why not use nixos-render-docs?

I haven't interacted with its manual page rendering compatibility yet nor did I know about it. So I can't really comment on it.

I do know that nixos-render-docs explicitly does not make any stability guarantees and is strictly designed for use in Nixpkgs. I'm not sure if it is necessarily wise to depend on this in Lix. It would mean imposing some stability requirements on nixos-render-docs after the fact (for the sake of historical Lix versions). Also it would require distributors other than Nixpkgs to package nixos-render-docs if they want to have Lix with man pages. I'm not sure how “packageable” nixos-render-docs would be for others.

@pennae wrote in https://git.lix.systems/lix-project/lix/issues/982#issuecomment-14781: > why not use nixos-render-docs? I haven't interacted with its manual page rendering compatibility yet nor did I know about it. So I can't really comment on it. I do know that nixos-render-docs explicitly does not make any stability guarantees and is strictly designed for use in Nixpkgs. I'm not sure if it is necessarily wise to depend on this in Lix. It would mean imposing some stability requirements on nixos-render-docs after the fact (for the sake of historical Lix versions). Also it would require distributors other than Nixpkgs to package nixos-render-docs if they want to have Lix with man pages. I'm not sure how “packageable” nixos-render-docs would be for others.

pennae commented

2025-08-29 12:55:12 +00:00

Owner

we wrote nrd from scratch, and it's not all that big :) forking it and occasionally updating it to the nixpkgs version if new features appear is fully plausible. once we've forked it and are using it successfully for manual stuff it could even become a shared project that isn't tied strictly to nixpkgs (which it so far has been only for convenience reasons anyway)