>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
