Re: Unsupported nroff macros on MacOS X

[Ken Hornstein]

>mandoc is a pain.  It's one of many programs which attempt to interpret
>man pages whilst being an incomplete implementation.  I hang out in
>places which like to talk about troff/nroff, including for man pages,
>and mandoc's flaws crop up a lot.

So .... I'll admit my ignorance here.  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.

>Others have mentioned the mdoc macros.  These are an alternative to man.
>Their big selling point is semantic mark-up rather than presentation.
>But they have their own problems, they're YA-standard, and I'd avoid
>them.  Stick with simple man macros and troff/nroff with ASCII, UTF-8,
>and PostScript/PDF as targets.

Sigh.  Well, I'll admit my biases here.  In my youth somehow I missed
the troff boat; we used a lot of SunOS 4 and that didn't seem to have a
complete troff implementation (nor any documentation), and everyone a
bit older than me had System V experience which did come with a complete
troff manual and somehow it seemed like everybody else had figured out
troff, but other than modifying the occasional man page (which was mostly
done by copying other man pages) I never did really grok troff.

I realize that this is all solvable and the original troff manuals are
available online.  But ... well, I'm busy and all that, and I kind of
view it like learning Morse code; yes, it would be cool, but I just
don't have the time.

I did a quick Google, and I found this answer which is similar to
my question:

https://unix.stackexchange.com/questions/391399/what-is-the-difference-between-the-mdoc-macro-set-for-troff-and-the-plain-man-ma

Now obviously that person has their own biases, but this paragraph is
very telling to me:

  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.

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.  And it seems
like it is everywhere now?  Is there a reason to NOT use it?

I am open to more input on this topic.  My specific question is: should
we replace the .fc macros in nmh man pages with mdoc macros?  It seems like
that should Just Work on all common platforms today.

--Ken