Something of a tangent, and a historical note...

- N/troff (the raw stuff) is actually *very* low level, which
  actually makes it darned difficult to convert from one format
  to another.  Fortunately...

- When CSRG rewrote all the man pages and came up with -mdoc
  format, most of the "raw" man page formatting got cleaned up.

Cynthia Livingston actually came up with the macros, and at one
point was interacting with the author of groff to fix up a few
things so that her rather amazing macros worked right. :-)  I
suggested she even consider not using *roff directly, but she
pulled it off.

The real idea here, which recurs in things like SGML and LaTeX,
is to label each entity with its (deep-level) *meaning*, rather
than how it is to appear on a screen or page.  The appearance on
a screen or page then falls out from its meaning: a cross-reference
to another man page comes out as "foo(3)", or an HTML link, or
whatever.  Even the HTML folks finally caught on: this is what
"style sheets" are really about. :-)

If you read mdoc.samples(7), this idea should really leap out at
you.  Writing in -mdoc macros provides a relatively easy way to
"re-parse" any piece of documentation into any other displayable
format.  The hard parts occur when raw troff gets in for some reason
(such as to work around embedded-space bugs, or to get superscript
and subscript formatting in troff for the printed version, or
whatever).

Some man pages are, of course, still in the old -man macros, with
literal \fBbold\fP and \fIitalic\fP sequences sprinkled in, rather
than writing:

	.Nm make		(name of the program)
	.Op Fl D Ar variable	(-D flag takes an argument)

etc.  These are much harder to HTML-ize and otherwise reformat --
you have to guess that "\fBmake\fP" refers to the current document
and "\fImake\fP(1)" is a cross-reference.  Meanwhile, some authors
choose to use "\fImake\fP" to refer to the current document instead.
The formatted pages are thus inconsistent too.  Alas, people insist
on using the old -man macros, for compatibility with, e.g., SunOS
(even though the new -mdoc stuff *works* with the old macros, through
roff trickery, so every Unix-clone vendor could easily just ship the
new macros...).

Chris