[CC list brutally trimmed as usual] Hi Alex! At 2021-07-31T14:30:49+0200, Alejandro Colomar (man-pages) wrote: > On 7/31/21 11:43 AM, Christian Brauner wrote: > > While I'm respectfully ranting, I'd like to say that in an ideal > > world we would end up writing rst in the not too distant future just > > as we do for the kernel documentation. [...] > > This is no comment on your work at all! But groff is a __giant__ > > __giant__ pain imho. > > Agree. :) > > Especially since it's something that you don't usually use, except > when writing manual pages, which is not something that you do everyday > (unless you're maintainer of the man pages, that is). I get frustrated by groff and the man(7) macros, too, though much less often than I used to, because I've learned enough that the design principles have become clearer to me, and because when I find actual bugs, often I can fix them. I've ended up as a groff/roff/man(7) advocate not because I think they're perfect but because having watched the development of Unix/Linux documentation since 1996 I can attest to the truth of the following stone tablet. https://xkcd.com/927/ > BTW, I started using groff_man(7) to write other documents of mine > replacing LibreOffice (legal documents, for example), and it's really > nice, once you truly understand the language. Wow! I wouldn't do that and I've revised nearly every line of groff's man(7) macro package. I mean, I _could_ if ordered to, but there's a superior alternative right next door, called ms(7). It's what most of the classic Bell Labs Unix white papers were written (before 1980 or so, when the Labs started to adopt mm(7)). Since attaching PDFs to emails destined for linux-man meets with an ill-fate, hit me up if you're interested in a 22-page document called ms.ms. It's Larry Kollar's "Using _groff_ with the _ms_ Package". He originally wrote it in about 2001; he took it out of mothballs at my request because the groff team decided it would be a good idea to document the macro package using itself (much as groff_man_style(7) tries to). (We'd had it documented in the groff Texinfo manual instead, which some distributors won't ship because it uses some obnoxious features of the GNU FDL that are not DFSG-free.) For the past several months I've been revising every section of it to bring it up to date (and, as it happens, research the history of ms in ways that were much harder to do 20 years ago, in the days before TUHS). I've gotten some good feedback on it so far, and I aim to put my name on it as co-author once I've finished revising every section. A _lot_ of what you know will port from man(7) to ms(7). An exception I'm sorry to point out is the font styling macros, which share some of the same names but have different semantics with respect to positional arguments. You'll also see some features, like keeps, and may wonder, as I do, why we don't have them in man(7). Anyway, hit me up if you want this document and I'll shoot it your way. Or if you have Groff Git HEAD checked out, you'll find it you can build it yourself. :) > > I genuinely like writing documentation because it gives me time to > > think about the semantics I put into code. But I hate writing > > manpages or rather dread writing them because I know I'm going to be > > losing hours or a day not on content but on formatting. And then > > rounds of reviews with subtle differences between .I and .IR and > > whatnot. As a developer and maintainer I can't usually afford losing > > that much time which means I postpone writing manpages especially > > complex ones such as this. Font styling bedevils nearly everyone to some extent. If it's excessively frustrating, I would use only the .B and .I macros on a first pass, and let the formatter insert extra spaces initially. Let's take the instant case for an example. You knew you wanted roman parentheses and "struct mount_attr" in italics. So type exactly that, hitting return every time the font needs to change. It also harms nothing to put all the arguments to a single-font macro in one set of double-quotes, making one argument to the macro; this is similar to the shell. ( .I "struct mount_attr" ) Later, when the page is nearing completion and it's time to boil off those pesky extra spaces, you can return to this trio of lines, and think: "Okay, I need <R>oman first, then <I>talics, followed by roman again. Roman, then Italics. = = That means you want the "RI" font alternation macro. .RI ( "struct mount_attr" ) This condenses it into one line, with a roman left parenthesis, the data type in italics, and then a roman right parenthesis. No extra space. man(7) only gives you three font styles to work with, so there are six font style alternation macros. .BI .BR .IB .IR .RB .RI They all work precisely analogously. Does this help? In revising the groff man pages over the past four years I've learned to my shock that even there, some page authors seem not to know that all six of those macros exist. They tie themselves in knots trying to get what they want with a subset, and the result is usually ugly at least in source form--sometimes in formatted output, too. > > I already tried to make sure to use semantic newlines. I'll try to > > go over this once more now but I'm reluctant to send a v3 just > > because of that in case I should miss any. Especially since I've > > just recently seen manpages get an ack where that requirement wasn't > > fulfilled. An automatic formatter for this scenario would be > > appreciated. > > Okay, I don't know how to write such an automatic formatter (and also > don't have the time to write such a complex thing), but maybe Branden > knows if such a thing exists. I've heard good things about pandoc but have not tried it myself, let alone carefully evaluated the quality of its man(7) output. Frankly, the quality of much auto-generated man(7) output is abysmal and no doubt contributed to the macro language's poor reputation. People view the source of a man page produced by docbook-to-man, for example, and rightly recoil in horror. Unfortunately they don't understand that they're looking at the *roff equivalent of Obfuscated C. Just today I was working on the "Notes" section of groff_man_style(7), and came across a generator I'd never heard of called "Ronn"[1]. It's been defunct for many years, but the lousy man(7) markup in produced in pages like texdoc(1) has persisted long after it. But it's better than docbook-to-man. What wouldn't be? Regards, Branden [1] https://github.com/rtomayko/ronn
Attachment:
signature.asc
Description: PGP signature
