Lowdown Manpage Support
16 points by dzwdz
16 points by dzwdz
One alternative to lowdown is scdoc
Note that scdoc doesn't attempt to use any of the semantic features of mdoc.
Just a few days ago a friend of mine has complained that she wasn't able to jump to tags in a manpage written using scdoc (not sure which one). It seems that with scdoc people just manually format their manpage. See e.g. sway(1) - each option is made bold, and the options are indented (see also scdoc(5)).
Lowdown lets you actually mark something up as a definition list, and then mark command line flags etc inside of them.
Have you wanted to write a manpage for your library or program but are put off by the complexity of the weird manpage language? Read on.
This has just landed in Lowdown 3.0.0, which released last week. The author is part of the mandoc team, so I expect this to be pretty good.
This looks like a good way to make it easier to write man pages.
One of the things like about mdoc is the semantic markup makes it very clear what directive I should use in each situation. There are some style conventions that aren’t explicit in the markup, but they are very few and reasonably well documented, and the mandoc linter is good at spotting them. Unlike the old -man macros which are physical markup and rely on undocumented style conventions.
Lightweight markup seems like a regression: in the past I’ve found pod2man isn’t great at producing nicely formatted output because its markup is annoyingly weak. Even markdown is a step up from pod! But I still have to pay attention to which physical markup I should use so the result looks consistent with other man pages.
It looks like lowdown knows more about man page conventions than most other man generators, so (with mandoc lints) I hope it helps the author get things right with less guesswork.
I'm all for anything that gets us more manpages since they are much more accessible than a project's README if you are already in a terminal working on something.
It's no longer maintained, but years ago I used Ryan Tomayko's ronn for this. It's the same basic idea, you write a manpage in Markdown (e.g., this one), and ronn turns it into a properly formatted manpage.
It’s great to hear that Lowdown has added this. I’m the creator of an extremely low profile alternative, Predoc, and when I released Predoc last year it was—to the best of my knowledge—the only Markdown flavour that could produce good-looking manpages in semantically correct mdoc (examples). I hope Lowdown’s new support encourages more people to write mdoc-based manpages, they’re great :D
I personally my documentation in AsciiDoc; you can use the manpage doctype in a document without modification to get a properly-formatted manual page. See the AsciiDoctor documentation about that feature.
I used pandoc in the past for this purpose.