Hi Alexis & Onf, At 2024-10-25T23:02:42+1100, Alexis wrote: > i find it odd, though, that the dev also wrote: > > > On macOS, it's man mdoc. Thankfully, there is little difference > > between them. > > Like .... In the sense that man(7) and mdoc(7) are both collections of > roff macros, sure. And there's certainly some overlap in terms of the > specific macros involved, like SH/Sh, SS/Ss and PP/Pp. But most of the > macros listed in the table at the start of groff_man_style(7) aren't > ones one would use when writing mdoc(7), and there's even one conflict > (setting aside case): man(7) 'SY', Synopsis Start, vs mdoc(7) 'Sy', > Symbolic i.e. boldface. Use man(7) or mdoc(7), but if you're writing > mdoc(7), write mdoc(7). :-)
I agree. There's some bad information out there that seems in part to arise due to confusion over what the `-mandoc` option means. It doesn't mean you can or should write a man page using the union of the man(7) and mdoc(7) macro name spaces. For example: https://truss.works/blog/2016/12/9/man-splained The good news is, I've never yet seen a man page that actually mixed man(7) and mdoc(7) calls in practice. If that were to happen, I might have to add a facility for package "unloading" to our "an.tmac" and "doc.tmac" files. (I expect the mechanism would be an unloading macro in each package, called from "andoc.tmac", that invoked `rm` on a bunch of "public" macros.) At 2024-10-25T16:51:26+0200, onf wrote: > I wonder if the author tried Drew DeVault's scdoc, it seems to work > well for simpler manpages. (Output is man.) I'm not crazy about the non-idiomatic section titles or organization. But the bigger point is that it's _easy_ to implement this sort of thing for _simpler_ man pages, as you put it. The problem is that the boundary between "simple" and "not simple" is not well-defined by any man(7) generator I've seen, so a page author using one of these "easier", "simpler", or "smarter" tools doesn't have a good way of knowing, short of experimentation, when they're going to end up off the beaten track anticipated by the author of the converter. Worse, to hearken back to Kernighan's critique of standard Pascal, "there is no escape". As far as I know, none of pod2man(1), asciidoctor(1), docutils(1), or pandoc(1) supports a syntax for inlining "raw" man(7)/*roff source into a document. I can well imagine why people don't want to support that, but when combined with the deficiency in the previous paragraph I think it erects a barrier to composition of adequate man pages, let alone good ones. I admit that that's not a complaint users of these conversion source languages seem to raise often. I suppose that this is for the usual reason that most programmers (and their managers) disdain technical writing. It's not "real work" and doesn't "deliver value". Approximately no one measures the cost of inadequate documentation to staff or the benefit of improving it, even from the first marginal increment beyond zero--that is, having any at all--therefore its presumed value is zero.[1] A "deep" insight like this, plus the right connections, can land you a well-compensated senior position at a tech company with a large market capitalization. Counting on innovation to improve your firm's fortunes is a sucker's bet. Ensuring that negative externalities stay off the ledger, like other forms of accounting fraud, is more reliable, and seldom punished. Regards, Branden [1] Just look at the uchardet library--it's been getting by without any API documentation for something like 15 years. Even groff uses it!
signature.asc
Description: PGP signature
