What exactly is the difference between the
man macro set and the
mdoc macro sets?
man is minimal and simplistic, having only bare-bones commands to define section headings, paragraphs, and subheadings. The package includes some basic formatting commands like
.BI, and not much else.
mdoc, on the other hand, is a full-featured DSL of its own, with dedicated markup commands for common manpage elements like switches, option and parameter lists, function types and return values, flags, command synopses, and virtually everything you'd expect a manpage markup language to have. See
mdoc(7) for a complete reference.
mdoc a superset of the
man are completely unrelated packages, sharing only a common ancestry and the same goal of marking up computer manual-pages.
What I have noticed is that both
mdoc and plain
man share some macros
They don't share anything. It's possible that what you've seen are native Roff commands, which is the underlying typesetting language in which the
man macros are written in. These tend to be used heavily in documents which use
man, but less so in those which use
You can easily distinguish native Roff commands from macros by the way standard Roff packages capitalise their macro names. For
man, each macro's name is uppercased, like
.SH, etc. For
mdoc, only the first letter is uppercased:
The Groff manpage for
mdoc states that the plain
man macro's are the predecessor to
mdoc but does not say if
A complete reference for writing UNIX manual pages with the -mdoc macro package; a content-based and domain-based formatting package for GNU troff(1). Its predecessor, the -man(7) package, addressed page layout leaving the manipulation of fonts and other typesetting details to the individual author.
I don't think "predecessor" here was intended to mean anything more than "something similar which was being used before". :-)
Which is more portable across POSIX systems and various implementations of
troff other than Groff (like Heirloom Troff)?
mdoc macros have been well-supported for a long time now, having first debuted in 4.4BSD and shipped with every Groff install by default. Both packages can be considered equally portable, unless you're preparing documents for antique terminals from the mid-70s. :)
Is the difference some BSD vs SYSV and/or GNU thing?
You're on the right track. Modern BSD systems use a program called
mandoc to format and display manpages, which is a clean reimplementation of
mdoc using natively-compiled C. It only supports a subset of the Roff language — enough so that legacy manpages display correctly.
Mandoc isn't a true typesetting program the way Groff and Heirloom are. Its focus is specifically on computer manuals: and only documents authored with
mdoc are guaranteed to render consistently and correctly on BSD-derived platforms. More detailed criticisms of
man can be found in
and does that make using plain
Kind of. Unless you're an experienced manpage author with a sound understanding of Roff grammar and the pipeline's mechanics, you really shouldn't be using anything other than
mdoc for authoring your manual-pages. Veteran
troff users may find
mdoc to be needlessly verbose or restrictive, finding
man to be lighter and less intrusive. However, these authors are experienced enough to know damn well what they're doing ― so unless you're a grizzled veteran, just stick to using
If you're interested in learning more about Roff history, and this answer wasn't FMTEYEWTK already, here're some links to authoritative learning material: