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

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

[-- 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 --]