Re: Unsupported nroff macros on MacOS X

[Robert Elz]

    Date:        Mon, 03 Apr 2023 11:35:35 -0400
    From:        Ken Hornstein <kenh@pobox.com>
    Message-ID:  <20230403153539.DE26B1EFD4B@pb-smtp21.pobox.com>

  | What's the difference between mandoc and mdoc?
  | It seems like mandoc is just the program that interprets nroff source?
  | A lesser implementation, as you say.

A restricted implementation, that interprets just the parts of general *roff
that (is believed) man page authors ought be including in man page sources.

mdoc is a *roff macro package which implements a set of macros useful for
making documentation (in particular, manual pages).  A replacement for man(7).

  | I never did really grok troff.

Pity - it can be lots of fun (and like many things highly general and
very powerful, also quite frustrating at times).

  | And that describes me exactly!  The frustrating thing for _me_ is that
  | doing simple stuff (like formatting command options) in man pages seems
  | kinda complicated and mdoc has macros which deal with that exactly.  Like
  | it does all of the stuff I'd ever want to do in man pages.

Yes, that is its point.

  | And it seems like it is everywhere now?

Just about, yes.

  | Is there a reason to NOT use it?

For writing something new, none at all.   But for converting something
someone has already made work, and is full of low level *roff noise to
achieve peculiar effects (that you first have to understand the point of,
then decide if you really need to keep, and then work out how do achieve
with mdoc) then, yes, lots of reasons...

  | My specific question is: should
  | we replace the .fc macros in nmh man pages with mdoc macros?

As I believe you're now aware, you cannot just do that.   It is all or
nothing (as with almost any other *roff macro package) - you cannot take
pieces from one and simply use them with another (though a macro package
can be built as an extension to another macro set - when I was teaching
(a horrible time for the students involved) I had a set of exam paper
macros, which were built on top of ms to produce (several types of) exam
papers - with the ability to include the answers in line, so those are
available for pre-exam review and then for the markers, without being
printed for the students...

If you create something new, use mdoc, it is far easier (particularly once
you get used to its "parsable" and "callable" macro conventions).  What's
more, when you use -mdoc (or mandoc) the macros are smart enough to detect
whether the man page is really -mdoc or is actually -man and use the 
appropriate set of macros for that particular page, so no-one needs to
try to work out whether they should be using -mdoc or -man on the command
line, just use -mdoc always.

kre