groff_man(7), man(7), and man-pages(7) (was: [PATCH v2] mount_setattr.2: ...)

[G. Branden Robinson]

[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@gmail.com/
[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

ms.ms
Description: Troff MS-macros document

signature.asc
Description: PGP signature