Re: [PATCH v2] mount_setattr.2: New manual page documenting the mount_setattr() system call

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 6758 bytes --]

[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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]