Re: [PATCH v2 1/3] system_data_types.7: ffix

G. Branden Robinson
2020-09-28T11:14:00Z

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

Hi Michael and Alex!

At 2020-09-28T12:34:40+0200, Michael Kerrisk (man-pages) wrote:
> On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
> > I had been using .PP because I hadn't seen .br before.
> >
> > I think .br is the correct format,
> > following the pattern in already existing man pages.
>
> I don't disagree with the formatting change, but I am wondering if
> there's a better way to do it.

There are a few ways to skin cats in even the restricted dialect of
man(7) that I advocate. (The other groff developers seem to generally
agree, but I will admit that I am probably more puritanical and maniacal
than most of them. :) )

> I tend to consider (perhaps wrongly) that the use of .sp and .br is
> unidiomatic,

In my book you're certainly right. There are a few reasons for keeping
the lexicon of macros/requests appearing in man pages small.

1. man pages, far more than any other type of *roff source document, get
parsed by things are not *roff typesetting engines. The less *roff
they have to simulate, the easier it will be for them to achieve
intelligible rendering. mandoc(1) is probably the premier example in
this respect, and I believe I understand from its current developer
Ingo Schwarze that it handles rather more *roff than we would prefer.
There have also been numerous "man2html" processors developed over
the years, typically of somewhat dispiriting quality.

2. Even in the world of *roff typesetters there is diversity. For a
long time groff was the only freely-licensed game in town, but
nowadays I know of Heirloom Doctools, Plan 9, Solaris 10, DWB 3.3,
and neatroff implementations. The smaller the language, the easier
it is to get consensus and parity around portable constructs.

3. A smaller language is easier to learn and easier to retain for
people who are part-time documenters. A person who only tackles
documentation maintenance once every four to six months, say, is
going to have an easier time with a language with maybe two dozen
tags, several of which fall into groupings with a predictable naming
pattern, than they will with, say, the 417 tags of DocBook[1].

For groff 1.22.4, released in December 2018, I made sure to
front-load the groff_man(7) page with a quick reference for all
non-deprecated tags. My hope is that man page writers who have been
around the block with the man(7) language once before can type "man
groff_man" and be refreshed after having to hit the space bar at most
twice.

A corollary of point (3), especially when it comes to the mixing of
*roff requests with macros, is that their subtle interactions can be
frustrating to learners--and even to experienced users. Someone who
leans what .sp does may be surprised to find it not working between a
section heading (.SH) and the first line of text afterwards. Similar
frustrations can arise with the .in request when mixed with .RS and .RE.

> and over the years I have replaced a large of them with alternatives.
> (For example, in many cases, .sp was being used when .PP should have
> been.)
>
> If Branden does not tell us of something better, I will just apply
> your patch as is.

_Personally_, I prefer system_data_types(7) as of
efbe7900b931789849a978c619106a8973e679cd to any intrusion of .br
requests. And as a C programmer I find it clear enough.

I do wonder about the huge list of header files providing `size_t`, but
I guess my raised eyebrow is better aimed at the ISO C committee than
here. :)

Regards,
Branden

[1] https://tdg.docbook.org/tdg/4.5/docbook.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]