man vs mdoc

Simple comparison of man(7) and mdoc(7) macros.

Example should look like this (common in SYNOPSIS section of manuals):

foo [-bar] [-c config-file ] file ...

First man(7) format:

.B foo [-bar] [-c
.I config-file
.B ]
.I file
.I ...

B macro stands for bold text, I for italic text.

Now mdoc(7) format:

.Nm foo
.Op Fl bar
.Op Fl c Ar config-file
.Ar file
.Ar

Nm stands for manual name, Op for command-line option, Fl for command-line flag, Ar for command-line argument.

It's easy to recognize that man(7) is all about presentation formatting, where mdoc(7) is structural format. What this means?

with groff pretty much nothing - both formats are translated to roff and structural data from mdoc(7) is lost.
with mdocml it matters. mdocml turns whole paradigm upside down: end format is mdoc/man, and roff macros (if there're any) are just additions. This way structural data from mdoc(7) isn't lost and can be used for html/pdf/ps output (nice looking docs without additional steps).

Links:

blinkkin/blinkkin.github.com