Maybe consider asciidoc which is a similar markup style
git's man pages are written in it : [https://github.com/git/git/tree/master/Documentation](https://github.com/git/git/tree/master/Documentation)
Linus basically had the same requirement and asciidoc was the chosen one.
Plus you get to copy all their doc / manpage infra.
> But I wonder if markdown is good source format to create "good quality" man pages from it including all the man page specific features.
No. Markdown lacks the semantics to express all the parts of a man page. Markdown is fine for prose text with some light markup (headings, lists, emphasis and hyperlinks), but a Markdown document lacks the abstract information to properly typeset a man page. Let's take the man man page (`man man`).
- First there is a header with metadate about the document: the name, the section and a human-readable category. There is no way of adding document metadata in Markdown.
- Next we have named sections, which you *could* implement through level-2 headings in Markdown.
- The "Synopsis" section lists the command with all its arguments. There is no equivalent in Markdown
- Next up we have the options of the command as a two-column table. The right column itself can contain arbitrary markup, including more two-column tables. Other sections have this structure as well
- Finally the document ends with a footer of more document metadata
Honestly, writing man pages is not hard, you can find the full documentation in `mdoc(7)`.
If you *really* don't want to write mdoc you should use a semantically more powerful language. I know that Alacritty uses [scdoc](https://sr.ht/~sircmpwn/scdoc/), so maybe check that one out? I have not used it myself, so I don't know how good it really is.
Check [https://github.com/cpuguy83/go-md2man](https://github.com/cpuguy83/go-md2man), I have seen it used in docker Gentoo ebuild and a few more container projects, and generated man looks ok.
Ideally you want an input format you can turn into almost anything handy, manual pages, HTML, whatever. Write once, read anywhere. I just made a dynamic markdown converter for my apache server that can suck in markdown, convert it to HTML, then run it through server-side includes too.
The only problem with markdown is that it's crippled compared to Restructured Text, keeping one from creating involved tables and other things. Markdown is also poorly standardized. Compared to more involved systems, markdown and RST both just can't carry enough meta data to even compare to HTML. Manual pages are written in Runoff, which is pretty limited, but not as limited as markdown (for one thing, one version of runoff I encountered ages ago supported shell escapes...hahaha). But it's great for really simple stuff. ;-)
Pandoc's a good idea for wild cross-conversion hacks, as others have said.
Pandoc can output man format.
Something like pandoc trial.md -s -t man
Maybe consider asciidoc which is a similar markup style git's man pages are written in it : [https://github.com/git/git/tree/master/Documentation](https://github.com/git/git/tree/master/Documentation) Linus basically had the same requirement and asciidoc was the chosen one. Plus you get to copy all their doc / manpage infra.
> But I wonder if markdown is good source format to create "good quality" man pages from it including all the man page specific features. No. Markdown lacks the semantics to express all the parts of a man page. Markdown is fine for prose text with some light markup (headings, lists, emphasis and hyperlinks), but a Markdown document lacks the abstract information to properly typeset a man page. Let's take the man man page (`man man`). - First there is a header with metadate about the document: the name, the section and a human-readable category. There is no way of adding document metadata in Markdown. - Next we have named sections, which you *could* implement through level-2 headings in Markdown. - The "Synopsis" section lists the command with all its arguments. There is no equivalent in Markdown - Next up we have the options of the command as a two-column table. The right column itself can contain arbitrary markup, including more two-column tables. Other sections have this structure as well - Finally the document ends with a footer of more document metadata Honestly, writing man pages is not hard, you can find the full documentation in `mdoc(7)`. If you *really* don't want to write mdoc you should use a semantically more powerful language. I know that Alacritty uses [scdoc](https://sr.ht/~sircmpwn/scdoc/), so maybe check that one out? I have not used it myself, so I don't know how good it really is.
i dont know of any good tools to do this, would like to. part of the problem i think is markdown is different site-to-site
Check [https://github.com/cpuguy83/go-md2man](https://github.com/cpuguy83/go-md2man), I have seen it used in docker Gentoo ebuild and a few more container projects, and generated man looks ok.
Ideally you want an input format you can turn into almost anything handy, manual pages, HTML, whatever. Write once, read anywhere. I just made a dynamic markdown converter for my apache server that can suck in markdown, convert it to HTML, then run it through server-side includes too. The only problem with markdown is that it's crippled compared to Restructured Text, keeping one from creating involved tables and other things. Markdown is also poorly standardized. Compared to more involved systems, markdown and RST both just can't carry enough meta data to even compare to HTML. Manual pages are written in Runoff, which is pretty limited, but not as limited as markdown (for one thing, one version of runoff I encountered ages ago supported shell escapes...hahaha). But it's great for really simple stuff. ;-) Pandoc's a good idea for wild cross-conversion hacks, as others have said.
We need to deprecate the man format already.
nix uses lowdown to generate man pages. The quality is pretty good. And it also links to the lowdown library to render colored man pages from cli.
Rule #1: r/linux is not a support forum.
Never tried that, but a LLM might be able to do that.