[adding groff@ to CC] Hi, Alex! At 2021-08-01T13:50:09+0200, Alejandro Colomar (man-pages) wrote: > [I (GBR) wrote]: > > https://xkcd.com/927/ > > Agree. That's why I doubt very much that we'll ever change to RST (or > any other language). But I'll have to try and make the current > man-pages consistent enough so that people see it easy writing them... We definitely share this goal. > I think I tried groff_ms(7), or maybe it was groff_mm(7); I don't > remember. But I didn't like having to learn a new dialect, more so > when there are macros that act differently with the same name. Fair enough. I have to admit that some things about ms(7) surprised me; it was really aggressive with the use of diversions to collect input, and its approach to font style alternation was a bit timid at first which led to it being extended in a way which is tough to defend. When Bell Labs took their second crack at a general-purpose macro package, mm, they adopted man(7)'s names and semantics for font style alternation. Unfortunately, that approach doesn't scale well with the availability of large numbers of fonts/styles. (And design-wise, they got caught out in short order with the radical novelty of the Linotron 202's bold italic style.) > Since I already know man(7) very well, it's simpler for me to use it > everywhere. But maybe if you send me that document you might convince > me (but I doubt it). Attached. Since my last attempt to send a PDF to linux-man@ went into a black hole, I'll send you the document source (which is smaller anyway). Just format it with "groff -t -ms". I've even gotten it usable on terminals, though so far only on wide ones (at least 91 character cells; getting it any narrower would mean refactoring the tables, and I've deferred that until after I complete content revisions, if ever). > I think most languages out there are perfect examples of > <https://xkcd.com/927/>. This perspective, I don't share--I'm fond of C but also sometimes maddened by it. I think there is great value in exposure to other languages, well enough to a get a "feel" for them if not to use them in daily practice. I think doing so can help one's creativity in problem-solving. To name two examples, I've seen much to admire in Ada and Rust. I'd like to grow a Haskell brain. > BTW, I'm curious, and never knew this: what's the difference between > groff_man(7) and man(7)? They are each a page about groff_man, > written by different authors/projects, right? Yes. Michael and I were able to roughly sketch the history in a thread in May[1]. What would you think about retiring the linux-man man(7)? I've been hesitant to suggest this because it does some work that I don't want groff_man(7)[2] to do, because to do so is not its place--the prescription of system-specific conventions and practices. However, it occurs to me that much of this information is already being maintained more diligently in man-pages(7), and that which is truly more material to system _organization_ is probably better suited to intro(7) or even intro(1). groff names its macro package man pages with a "groff_" prefix because it was common, back in the 1990s, to install it on vendored, branded Unix system that already supplied a troff system--often Documenter's Workbench (DWB) troff, SoftQuad troff (sqtroff), or some descendant of an AT&T troff (sometimes from before Kernighan's device-independent rewrite of the system ca. 1980, sometimes later). On systems where nothing else provides the macro packages, this makes little sense. groff_{man,mdoc,me,mm,ms}(7) might as well be available simply as {man,mdoc,me,mm,ms}. Slightly absurdly, we also have a page named groff_mom(7) even though the mom macro package never existed in _any_ other implementation. I don't suggest a rename so much as an additional provision of an additional set of pages with .so requests bringing up the "real" pages. It's sort of like having symbolic links within the roff(7) language. I would emphasize that because there is style guidance in groff_man_style(7)[3], I think it would retain (only) that name even if groff were to start providing man(7), because the former page documents _groff's_ house style in areas where there is room for discretion). > That's what I don't like Yes, and it _still_ doesn't solve what we often call the "three-font problem" (discussed, with workarounds, at length in groff_man_style(7)). Bernd Warken, a groff contributor from several years, promoted a macro called "FONT" that would take alternating arguments: a font identifier followed by the argument to be set in it, repeat. So, you might have .FONT R [ B \-\-stylesheet= I file R ] The above is as good a solution I've seen, but no one (apart from Bernd, briefly) has expressed enthusiasm about extending man(7) with it. I think there are two reasons for that: (1) man needs more _semantic_ markup much more badly than it needs more style markup, and (2) there are limited returns for documents to be rendered in a terminal emulator, which is the dominant medium in which man pages are consumed. There's one style available you can't get at if you write a well-behaved man page (bold italics), but nothing else since most terminal emulators will only render one font family to the screen at a time. Finally it's hard to motivate such a thing. If you look at PostScript or PDF versions of grops(1) or gropdf(1), or the DVI version of grodvi(1), you'll see that the font repertoires are presented with samples. It's a handy demonstration for the reader whose device can render them, but I think the pages lose much for readers in terminals. > > > > 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. > > This was written by Christian, but you removed him from the CC list :) Whoops! Well, maybe he'll see it anyway. > > 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. > > I guess. I don't like autogenerated code in any language. I never > tried checkpatch.pl's auto fix for the same reasons. I remember the horror I experienced when I was being shown how to write Java in Eclipse. "Need getters and setters? Here! Just click this button and the IDE will write stubs _for_ you!" I had many reasons to run screaming away from Java but that was one of the best. If something is that bone-headedly simple, why is it being specified in the source code in the first place? It should either be defined in the language, with a provision for overriding the bonehead default) or you should be maintaining the software project in a higher-level language, using a macro processor that _produces_ Java, for instance. (More likely you'd just choose a better language that compiles to Java bytecode--not surprising that multiple projects in fact took that approach.) Regards, Branden [1] https://lore.kernel.org/linux-man/\ f21251ae-a136-8b09-af72-b5ad95f2b4cc@xxxxxxxxx/ [2] https://man7.org/linux/man-pages/man7/groff_man.7.html [3] https://man7.org/linux/man-pages/man7/groff_man_style.7.html
Attachment:
ms.ms
Description: Troff MS-macros document
Attachment:
signature.asc
Description: PGP signature
