3

I am trying to create man pages for a side project and I have never used troff before and I am trying to figure out what exactly is the difference between the man macro set and the mdoc macro sets and which is more portable between POSIX OS'es and the various implementations of troff.

What I have noticed is that both mdoc and plain man share some macros and that BSD (at least FreeBSD) uses the mdoc manual format while GNU uses the plain man format.

So my questions are basically:

Is mdoc a superset of the man macros? and does that make using plain man legacy? The groff manpage for mdoc states that the plain man macro's are the predecessor to mdoc but does not say if mdoc supersedes man.

Is the difference some BSD vs SYSV and/or GNU thing?

Which is more portable across POSIX systems and various implementations of troff other than groff (like heirloom troff)?

  • That's a broad topic which really calls for a side-by-side comparison. However, none has been presented in earlier discussion. – Thomas Dickey Sep 10 '17 at 10:26
  • From OpenBSD's man 7 man: "Do not use man to write your manuals: It lacks support for semantic markup. Use the mdoc(7) language, instead." Both man(7) and mdoc(7) are reasonably portable these days, but mdoc(7) is particularly nice if you have mandoc(1). Which, of course, is NIH for GNU. – Satō Katsura Sep 10 '17 at 18:32
  • So for all intent and practical purposes the mdoc is a modern replacement for the plain man? – Zeno of Elea Sep 13 '17 at 20:08
3

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

Is mdoc a superset of the man macros?

No. mdoc and 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 mdoc and man macros are written in. These tend to be used heavily in documents which use man, but less so in those which use mdoc.

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 .PP, .TH, .SH, etc. For mdoc, only the first letter is uppercased: .Pp, .Dt, .Sh, etc.

The Groff manpage for mdoc states that the plain man macro's are the predecessor to mdoc but does not say if mdoc supersedes man.

groff_mdoc(7)
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)?

The 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 man(7).

and does that make using plain man legacy?

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

Further info

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:

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.