
Practical Unix Manuals: mdoc - beefhash
https://manpages.bsd.lv/
======
rwmj
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...](https://raw.githubusercontent.com/libguestfs/libguestfs/master/p2v/virt-p2v.pod)
and the output as HTML:
[http://libguestfs.org/virt-p2v.1.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.)

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

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

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

------
tkfu
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](http://asciidoctor.org/docs/user-manual/#man-pages)

[2]
[https://raw.githubusercontent.com/asciidoctor/asciidoctor/ma...](https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc)

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

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

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

~~~
JdeBP
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](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).

~~~
jwilk
> _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.

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

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

~~~
beefhash
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](https://man.openbsd.org/whatis.1)

~~~
nerdponx
I wish I could use semantic markup to _jump to a definition_ , either of an
option or a subcommand.

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

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

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

~~~
jwilk
What's USL?

~~~
mwest
Unix System Laboratories -
[https://en.wikipedia.org/wiki/Unix_System_Laboratories](https://en.wikipedia.org/wiki/Unix_System_Laboratories)

See also: USL vs. BSDi:
[https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc....](https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc._v._Berkeley_Software_Design,_Inc).

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

