[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Unsupported nroff macros on MacOS X
From: |
Ken Hornstein |
Subject: |
Re: Unsupported nroff macros on MacOS X |
Date: |
Mon, 03 Apr 2023 11:35:35 -0400 |
>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
- Unsupported nroff macros on MacOS X, Ken Hornstein, 2023/04/02
- Re: Unsupported nroff macros on MacOS X, Robert Elz, 2023/04/02
- Re: Unsupported nroff macros on MacOS X, Greg Minshall, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Anthony J. Bentley, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ralph Corderoy, 2023/04/03
- Re: Unsupported nroff macros on MacOS X,
Ken Hornstein <=
- Re: Unsupported nroff macros on MacOS X, Ralph Corderoy, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ken Hornstein, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ralph Corderoy, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Anthony J. Bentley, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ken Hornstein, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, doug dougwellington . com, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ken Hornstein, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Michael Richardson, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Ken Hornstein, 2023/04/03
- Re: Unsupported nroff macros on MacOS X, Steffen Nurpmeso, 2023/04/03