I use perldoc / POD to write man pages and that works well. It's simple to write and there are tools to convert it straight to man pages, text or HTML.
I used POD for a while; but after using DocBook XML for manuals for a work project some years ago I switched to primarily using that, and generating HTML, roff, and others from it.
Instead of explicit italicization and boldface
to the hard disks: Firstly, the qemu-nbd I<-r> (readonly) option is
I write semantic markup
The <arg choice='plain'>--upstart-compatibility</arg> option causes <command>tcp-socket-listen</command> to set the <envar>UPSTART_FDS</envar> environment variable to 3, and the <envar>UPSTART_EVENTS</envar> environment variable to <literal>socket</literal>.
No. As you can see from the aforegiven snippet, which is fairly representative although it was the result of my going looking for a sentence with a lot of different elements in it, it isn't.
roff is quite horrible to read and write. There's a much better solution than banging your head against an archaic and unforgiving file format: AsciiDoctor's manpage backend [1]. You write in asciidoc, with some required structure that's quite easy to follow, and it spits out a proper roff document for you. Asciidoctor's own manpage [2] is, of course, generated in this way, and it's a pretty good example of the form.
The main issue with this is that AsciiDoc cannot express semantics. When writing manpages, you can specify that something is a flag or a function parameter, etc.
I'd argue that (1) manpages are for humans to read, and (2) there is effectively only one presentation style for the conveying the semantic contents. So as long as the author of the manpage follows the standard conventions for manpage presentation style, they are in fact expressing the semantics. And it's a lot easier to learn the conventions (flags in bold, arguments in italics, etc.) and write them in lightweight markup than it is to learn roff.
Semantic markup has more uses than just consistent presentation. For example, most of the BSD's use mandoc rather than groff for rendering which allows you to do more detailed searches with apropos. Note that the linked article refers to the mdoc macros. These aren't especially new and are very well supported but the man macros are still more common. If you dig into the details, the mdoc macros have many advantages.
Using mandoc instead of groff is a bit of a step backwards, note.
grotty is capable of ECMA-48:1976 and ISO 8613-6:1994 control sequences, and can actually do proper italicization, boldface, underline, and colour in manual pages; which many terminals nowadays have supported for decades.
mandoc still only knows the old 1960s TTY-37 control sequences that use overstrike for boldface and underline and that have no notion of italicization or colour.
When FreeBSD switched from groff to mandoc, I went looking for any way to have mandoc support ECMA-48:1976 and ISO 8613-6:1994 control sequences. It turned out to be a large amount of work to bring it up to parity with something that the GNU toolchain has had since the 1990s (and is in fact the GNU toolchain's native mode of operation).
You can actually. If you use mandoc instead of mandb, it automatically generates and passes tag files to less. Then you can just type ":t e" to jump to the docs for the -e option, for example.
A more realistic example might be that you're changing $LANG and now something broke. You can thus search for everything that uses LANG[1] and see what's most likely to have broken in what way.
There are some many things that are affected by locale environment variables (most of the time without documenting it explicitly), that this particular query is mostly useless.
> I love man pages they are often easy to read, but roff is not that easy to author
To be fair, writing the programs or functions that the manual page is purporting to document isn't easy either. I have written manpages (and plenty of code) and in my experience, the hardest part is not the markup but getting the actual content right.
There are badly written documentation out there, and they will not be better just because they are formated as a man page instead of Microsoft Word, but the worst kind are the ones which are never written and that syntax is quite a blocker. Your comment highlights my bias for man pages, I forgive a lot more when it's read in prefered format rather than .docs.
It might not be trendy like Markdown or YAML (both of which I like, and have their uses), but to markup text with higher-level semantics (i.e. not relating to formatting) the best option is XML.
Sure, but do you really want to hand write XML? It's nice for computers but makes for really ugly source when humans are involved, and humans are still very heavily involved when it comes to writing documentation.
quick plug for someone to do the legwork get heirloom troff in some real (read BSD) unix so that the whole roff toolchain is reintegrated after USL, that would be great.
As a long time roff user, I really prefer groff. It's better.
It does colors, the pic implementation is programmable, it's just better.
So here is a vote against heirloom and for groff. And I get it, the BSD crowd hates GNU and I have my own issues with the GNU folks, but come on, use better when it is better.
For example: https://raw.githubusercontent.com/libguestfs/libguestfs/mast... and the output as HTML: http://libguestfs.org/virt-p2v.1.html
(The output in 'man' looks really good too, but I don't have an easy way to demonstrate that.)