|
From: | doug dougwellington . com |
Subject: | Re: Unsupported nroff macros on MacOS X |
Date: | Mon, 3 Apr 2023 19:40:09 +0000 |
Ken wrote:
>
I am assuming that we still want to ship man pages
To
keep with the original intent of the project, I suspect that is the thing to do.
> I am kinda against depending on some third-party tool
Where does built-in turn into third-party? With all the modern package managers, it's trivial to install other tools as needed.
> I'm not sure what the
options are in this space [snip] some
> other
markup format that can output man pages and HTML.
Having been in the python world for so long, I had to deal
with markdown, restructured text, docutils, sphinx, etc. Then there's the beast that is Doxygen. They all have benefits and tradeoffs. How hard do we hold onto the old ways vs. embracing new tools?
From: nmh-workers-bounces+doug=dougwellington.com@nongnu.org <nmh-workers-bounces+doug=dougwellington.com@nongnu.org> on behalf of Robert Elz <kre@munnari.OZ.AU>
Sent: Monday, April 3, 2023 12:13 PM To: Ken Hornstein <kenh@pobox.com> Cc: nmh-workers@nongnu.org <nmh-workers@nongnu.org> Subject: Re: Unsupported nroff macros on MacOS X 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 |
[Prev in Thread] | Current Thread | [Next in Thread] |