Practical Unix Manuals: mdoc | Hacker News Reader

Practical Unix Manuals: mdoc

manpages.bsd.lv

161 pointsbeefhash35 comments

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.

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.)

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>.

which I find preferable.

This seems a good approach. I just thought maybe we can use React to render this kind of stuff?

DocBook XML isn't bad, but don't you find the markup incredibly verbose?

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.

As this comment proved unexpectedly popular, here is a 15 second video of how it looks when paging through the man page:

http://oirase.annexia.org/tmp/virt-p2v-man.ogv

Now that is a proper man page!

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.

[1] http://asciidoctor.org/docs/user-manual/#man-pages

[2] https://raw.githubusercontent.com/asciidoctor/asciidoctor/ma...

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.

* https://jdebp.eu/Softwares/nosh/italics-in-manuals.html

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).

> one has to employ the MANROFFOPT environment variable, setting it to "-P-i".

This didn't work for me (Debian unstable), because man called nroff, which doesn't understand the -P option.

So I put

  DEFINE  troff   groff -mandoc -P-i
  DEFINE  nroff   groff -mandoc -P-i

in /etc/manpath.config . This did the trick, but I'm not sure it didn't break something else.

Aha! A typing error. One should set it to

    -- -P-i

Note the -- option. This causes nroff to just pass the -P-i option straight through to groff.

My markup choice is between asciidoc and emacs org-mode, but I haven't done man pages. I wonder if there is an org mode man page system?

I love man pages they are often easy to read, but roff is not that easy to author. So it nice to see good documentation being posted.

   .Sh SYNOPSIS 
   .Nm 
   .Op Fl C 
   .Op Fl o Ar output 
   .Op Ar prefix

becomes this:

   SYNOPSIS
   hello	[-C] [-o output] [prefix]

Semantic formating is nice, but atm I'm not sure there is much value to write the above vs using markdown and just convert it to roff.

Semantic markup has a use, at least on OpenBSD. You can use the semantic markup for searching manual pages, like this[1]:

> Search for manuals in the library section mentioning both the “optind” and the “optarg” variables:

> $ apropos -s 3 Va=optind -a Va=optarg

[1] https://man.openbsd.org/whatis.1

I wish I could use semantic markup to jump to a definition, either of an option or a subcommand.

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.

Interesting, so theoretically that is something that every distro could and should be doing?

When does someone need to search for that sort of thing?

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.

[1] https://man.openbsd.org/?query=Ev%3DLANG&apropos=1&sec=0&arc...

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.

I'm not sure Markdown->Roff makes sense. I know Pandoc can do it, but how do you convey semantic information with Markdown? I'd sooner write YAML.

It works, not as good as a good template for LibreOffice though, my point was that the sematics is lost with markdown and you only get formating.

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.

Most of the problem with that is the cryptic abbreviations. A symbol lexical filter would let you have this:

    .SectionHeader
    .Name
    .Optional Flag C
    .Optional Flag o Argument output 
    .Optional Argument prefix

or with some punctuation:

    .SectionHeader
    .Name
    .Optional Flag: C
    .Optional Flag: o Argument: output 
    .Optional Argument: prefix

which is quite readable.

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.

What's USL?

Unix System Laboratories - https://en.wikipedia.org/wiki/Unix_System_Laboratories

HN doesn't consider trailing dot part of the URL, so you need to URL-escape the dot (%2e) to make it work.

(But I set up a redirect, so now the dotless URL works, too.)

Reply on news.ycombinator.com