4 ms·

I disagree. I have been writing man pages for a while, and mastering the language is hard. The documentation for both mdoc and mandb format is not covering the

I disagree. I have been writing man pages for a while, and mastering the language is hard. The documentation for both mdoc and mandb format is not covering the whole language, and the only remaining reference for roff itself seems to be the book by Brian Kernigham. mdoc and mandb are like a macro set on top of roff. Just this week i considered proposing to $distro to convert all manpages to markdown as part of the build process, and then use a markdown renderer on the shipped system to display them. This would allow the distro to stop shipping *roff per default. Markdown profits from the much larger amount of tooling. There are a ton of WYSIWYG editors that would allow non-technical users to write such documentation. I imagine we would all profit if creating manual pages was that easy. On the other side, Markdown is even less formalized. Its like 15 different dialects from different programs that differ in their feature sets and parsing rules. I do not believe things like "How do i quote an asterisk or underscore so it is rendered verbatim" can be portably achieved in Markdown.

packetlost 2y ago
scdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc https://git.sr.ht/~sircmpwn/scdoc
- blueflow 2y ago
  Until i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.
  - packetlost 2y ago
    I'm not a fan of Drew's political grandstanding (or views, in some cases) but scdoc is good and packaged in many distros. There's no foundation for him to abuse with it, so it's safe.
    - pkal 2y ago
      The IRC bouncer Soju uses scdoc and this has been personally annoying, as I refuse to install it just to build semantically less expressive documentation than when using the very well documented (https://mandoc.bsd.lv/man/mdoc.7.html https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I asked the maintainer if they were interested in a contribution to translate it, and they just dismissed it out of the box.
      - packetlost 2y ago
        Who cares how expressive it is? It hits all the core pieces of formatting you can realistically do in a terminal using syntax that is familiar to a much wider range of developers. The output is completely usable and reasonable. I'd rather use something closer to markdown than roff macro gunk that is largely irrelevant anywhere else.
- homebrewer 2y ago
  adoc is fine and is more widely supported. Linux (the kernel) documentation is written in adoc, along with man pages for many projects like git: https://github.com/git/git/blob/master/Documentation/git-rm.adoc?plain=1 https://github.com/git/git/blob/master/Documentation/git-rm....
  - packetlost 2y ago
    I wasn't aware AsciiDoc could be used to generate man docs. I'm not a huge fan of AsciiDoc's syntax, but I can see that being preferable to other options.
  - WhyNotHugo 2y ago
    Asciidoc doesn't support links in man pages. It can only link to URLs. If you check the repo which you linked, you'll see they use some perl code to actually inject links.
- WhyNotHugo 2y ago
  I've used it quite a bit. It doesn't support links to other pages nor links to other sections. Which arguably is fine, since man page readers don't render them anyway, but HTML renders also suffer because of this.
thechao 2y ago
Yeah. Without even looking at google, I bet there's a "mandown" project that formalizes markdown with man extensions. The irony of the poor state of affairs of the quality of documentation for mdoc & mandb are not lost on me. EDIT: couldn't resist. There's at least two mandown projects.
- mattkrause 2y ago
  It's such a good name that, once you thought of it, you'd almost be obligated to start writing the code.
alabastervlog 2y ago
Even the most vanilla of markdown (the Daring Fireball kind) means committing to a good chunk of a Web rendering stack. You'd need some pared-down version.
rollcat 2y ago
I don't think Markdown is the right language to solve these problems. As you've noted, it's not standardised at all, and you'd have to pick an interpreter that everyone could agree on (and that means C). Markdown also doesn't do semantic references. It does do plain links, you can give them a title; or you can use a default title, so perhaps you could infer the semantics from the context, maybe like: Use the flag [-R][] to recursively apply to all files and subdirectories. Please refer to [chmod(2)][] for the details. But that feels like overloading one kind of syntax with so many different meanings. Take HTML as a counterexample, it has <link rel="...">, which fits neatly into the rest of the language. Why do these semantics matter? Well, you can obviously render roff into HTML and browse the man pages online; also, someone ought to write a simple and smart pager that can follow these references (Emacs doesn't count as simple). Anything that aims to replace roff should preserve its most important features, have a proper formal spec, and be easy to write a parser for - in super plain dumb C/flex/yacc.
- tgv 2y ago
  Semantics also matter for the apropos/whatis database. Not sure how many people know about them.
  - delusional 2y ago
    I only knew `apropros` from gdb. It looks pretty neat as an alternative to googling that function i never remember the name of. Thanks :)
MyOutfitIsVague 2y ago
RST/Sphinx solves that problem in that there is a single canonical dialect, and it's already effectively used in many very large projects, including the Linux kernel and (obviously) the Python programming language.
- arnsholt 2y ago
  Another big plus in my book is that rST has a much more well defined model for extensions than Markdown.
  - westurner 2y ago
    MyST Markdown has syntax for docutils roles and directives. Does the sphinx-build groff manpage builder also build from markdown, which sphinx also supports?
tgv 2y ago
If you want to know more about nroff (which is what man calls when you want text output, I believe), then you could e.g. read https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pdf/nroff.pdf https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pd..., or https://www.quut.com/berlin/ms/troff.html https://www.quut.com/berlin/ms/troff.html. It's terse, like nroff itself. I think people tried to convert man pages by redefining the macros and then let nroff produce the output.
jandrese 2y ago
As noted there are already HTML versions of the manpages that work without apparent issue. It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file. Then again GNU tried something similar with the info pages and it never really caught on. I think that was more due to the info program being kinda hard to use and the search facility being awkward.
- PhilipRoman 2y ago
  man -H
- WhyNotHugo 2y ago
  > It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file. `mandoc -T html` will do this for you with functional links between man pages and links to sections inside man pages.
- taeric 2y ago
  GNU trying with info pages was largely hampered by the fragmented UNIX world of the day? I seem to recall various UNIX controllers were far more active in standards and such than they seem to be today. Specifically, I don't think any one company had the dominance that would be needed to drive a large migration. Not that I'm certain that company exists today. There does seem to have been more consolidation than we had back then.
  - jandrese 2y ago
    I think it was more hampered by the default viewer program operating like EMACS, which if you're a regular EMACS user is great if you're not it is not terribly ergonomic. What was the command to find the next search item? Ctrl-X N?
- cafard 2y ago
  I didn't think info was at all bad. But the boss who had responded 'uh-hu' to a demo of documentation in Linux, responded 'Wow!' to the same document converted to HTML and displayed in Mosaic. These days, I suppose that I only see info in connection with Emacs.
WhyNotHugo 2y ago
Sounds like your major gripe with mdoc(7) is that lack of better documentation for the format and a shortage of tools to generate it. I agree on this second item, most tools don't support adding cross-references / links. At this point, markdown is 12 different standards, some of which even diverge on the most basic things like their treatment of newlines and how to wrap text. But even so, markdown provides mark-up for styles, with no semantic meaning. mdoc has macros to mark-up flags, optional flags, arguments, environment variables, files, etc. How to format this depends on the reader, and we can have much richer readers than we do right now. Simply converting man to markdown discards most of this information. A new format isn't going to help solve this; what we want is better guides and tools for produce high quality mdoc pages.
trod1234 2y ago
I disagree as well, but on a bit different grounds. Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented either. You can have commands where the flag is followed by an argument, but that flag also is positional, and the position is not documented. You can't just read the man page and get a working command, there's a lot of trial and error which is naturally solved by having a section of commands in an extended form with examples. Powershell does this, and they took it, from somewhere though I'm having trouble recalling the exact name at the moment I know it wasn't an innovation on their part they just glued a bunch of things together that were used in isolation.

packetlost 2y ago

scdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc https://git.sr.ht/~sircmpwn/scdoc

blueflow 2y ago
Until i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.
- packetlost 2y ago
  I'm not a fan of Drew's political grandstanding (or views, in some cases) but scdoc is good and packaged in many distros. There's no foundation for him to abuse with it, so it's safe.
  - pkal 2y ago
    The IRC bouncer Soju uses scdoc and this has been personally annoying, as I refuse to install it just to build semantically less expressive documentation than when using the very well documented (https://mandoc.bsd.lv/man/mdoc.7.html https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I asked the maintainer if they were interested in a contribution to translate it, and they just dismissed it out of the box.
    - packetlost 2y ago
      Who cares how expressive it is? It hits all the core pieces of formatting you can realistically do in a terminal using syntax that is familiar to a much wider range of developers. The output is completely usable and reasonable. I'd rather use something closer to markdown than roff macro gunk that is largely irrelevant anywhere else.
homebrewer 2y ago
adoc is fine and is more widely supported. Linux (the kernel) documentation is written in adoc, along with man pages for many projects like git: https://github.com/git/git/blob/master/Documentation/git-rm.adoc?plain=1 https://github.com/git/git/blob/master/Documentation/git-rm....
- packetlost 2y ago
  I wasn't aware AsciiDoc could be used to generate man docs. I'm not a huge fan of AsciiDoc's syntax, but I can see that being preferable to other options.
- WhyNotHugo 2y ago
  Asciidoc doesn't support links in man pages. It can only link to URLs. If you check the repo which you linked, you'll see they use some perl code to actually inject links.
WhyNotHugo 2y ago
I've used it quite a bit. It doesn't support links to other pages nor links to other sections. Which arguably is fine, since man page readers don't render them anyway, but HTML renders also suffer because of this.

thechao 2y ago

Yeah. Without even looking at google, I bet there's a "mandown" project that formalizes markdown with man extensions. The irony of the poor state of affairs of the quality of documentation for mdoc & mandb are not lost on me. EDIT: couldn't resist. There's at least two mandown projects.

mattkrause 2y ago
It's such a good name that, once you thought of it, you'd almost be obligated to start writing the code.

alabastervlog 2y ago

Even the most vanilla of markdown (the Daring Fireball kind) means committing to a good chunk of a Web rendering stack. You'd need some pared-down version.

rollcat 2y ago

I don't think Markdown is the right language to solve these problems. As you've noted, it's not standardised at all, and you'd have to pick an interpreter that everyone could agree on (and that means C). Markdown also doesn't do semantic references. It does do plain links, you can give them a title; or you can use a default title, so perhaps you could infer the semantics from the context, maybe like: Use the flag [-R][] to recursively apply to all files and subdirectories. Please refer to [chmod(2)][] for the details. But that feels like overloading one kind of syntax with so many different meanings. Take HTML as a counterexample, it has <link rel="...">, which fits neatly into the rest of the language. Why do these semantics matter? Well, you can obviously render roff into HTML and browse the man pages online; also, someone ought to write a simple and smart pager that can follow these references (Emacs doesn't count as simple). Anything that aims to replace roff should preserve its most important features, have a proper formal spec, and be easy to write a parser for - in super plain dumb C/flex/yacc.

tgv 2y ago
Semantics also matter for the apropos/whatis database. Not sure how many people know about them.
- delusional 2y ago
  I only knew `apropros` from gdb. It looks pretty neat as an alternative to googling that function i never remember the name of. Thanks :)

MyOutfitIsVague 2y ago

RST/Sphinx solves that problem in that there is a single canonical dialect, and it's already effectively used in many very large projects, including the Linux kernel and (obviously) the Python programming language.

arnsholt 2y ago
Another big plus in my book is that rST has a much more well defined model for extensions than Markdown.
- westurner 2y ago
  MyST Markdown has syntax for docutils roles and directives. Does the sphinx-build groff manpage builder also build from markdown, which sphinx also supports?

tgv 2y ago

If you want to know more about nroff (which is what man calls when you want text output, I believe), then you could e.g. read https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pdf/nroff.pdf https://www.nesssoftware.com/home/mwc/doc/coherent/manual/pd..., or https://www.quut.com/berlin/ms/troff.html https://www.quut.com/berlin/ms/troff.html. It's terse, like nroff itself. I think people tried to convert man pages by redefining the macros and then let nroff produce the output.

jandrese 2y ago

As noted there are already HTML versions of the manpages that work without apparent issue. It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file. Then again GNU tried something similar with the info pages and it never really caught on. I think that was more due to the info program being kinda hard to use and the search facility being awkward.

PhilipRoman 2y ago
man -H
WhyNotHugo 2y ago
> It makes me think about having the documentation converted to html and then have a thin script that invokes w3m on the correct file. `mandoc -T html` will do this for you with functional links between man pages and links to sections inside man pages.
taeric 2y ago
GNU trying with info pages was largely hampered by the fragmented UNIX world of the day? I seem to recall various UNIX controllers were far more active in standards and such than they seem to be today. Specifically, I don't think any one company had the dominance that would be needed to drive a large migration. Not that I'm certain that company exists today. There does seem to have been more consolidation than we had back then.
- jandrese 2y ago
  I think it was more hampered by the default viewer program operating like EMACS, which if you're a regular EMACS user is great if you're not it is not terribly ergonomic. What was the command to find the next search item? Ctrl-X N?
cafard 2y ago
I didn't think info was at all bad. But the boss who had responded 'uh-hu' to a demo of documentation in Linux, responded 'Wow!' to the same document converted to HTML and displayed in Mosaic. These days, I suppose that I only see info in connection with Emacs.

WhyNotHugo 2y ago

Sounds like your major gripe with mdoc(7) is that lack of better documentation for the format and a shortage of tools to generate it. I agree on this second item, most tools don't support adding cross-references / links. At this point, markdown is 12 different standards, some of which even diverge on the most basic things like their treatment of newlines and how to wrap text. But even so, markdown provides mark-up for styles, with no semantic meaning. mdoc has macros to mark-up flags, optional flags, arguments, environment variables, files, etc. How to format this depends on the reader, and we can have much richer readers than we do right now. Simply converting man to markdown discards most of this information. A new format isn't going to help solve this; what we want is better guides and tools for produce high quality mdoc pages.

trod1234 2y ago

I disagree as well, but on a bit different grounds. Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented either. You can have commands where the flag is followed by an argument, but that flag also is positional, and the position is not documented. You can't just read the man page and get a working command, there's a lot of trial and error which is naturally solved by having a section of commands in an extended form with examples. Powershell does this, and they took it, from somewhere though I'm having trouble recalling the exact name at the moment I know it wasn't an innovation on their part they just glued a bunch of things together that were used in isolation.