Re: [PATCH] man7/: ffix

[G. Branden Robinson]

Hi Alex,

At 2023-03-12T22:39:20+0100, Alejandro Colomar wrote:
> On 3/12/23 17:44, G. Branden Robinson wrote:
> > In groff 1.23.0 (which still doesn't have its final tag :( ), the
> > man(7) macro package remaps the `I` (italic) style to `BI`
> > (bold+italic) if it is available and the font being used for
> > (subsection) headings is configured to be bold.
> 
> Yup, I tested it only with 1.23.0-rc3.  I assume 1.22.4 will do
> something reasonable, but probably not so good.

groff 1.22.4 man(7) performs no font remapping in (sub)section headings,
so if you ask for font style `I` there, that is what you will get, at a
lighter stroke weight than the adjacent upright bold material.

Perhaps only typographers and nit-pickers will notice the difference...

> Heh, I remember having some problem related to this reading mandoc(1)
> (or maybe it was mdoc(7)).  I don't remember which it was, but having
> a quick look at mandoc(1), I found some flag insufficiently
> documented: '-l'.  See the only mentions in his page:
> 
>        MANPAGER  Any  non‐empty  value  of  the  environment  variable
>                  MANPAGER is used instead of the  standard  pagination
>                  program,  less(1); see man(1) for details.  Only used
>                  if -a or -l is specified.
> 
>        PAGER     Specifies the pagination program to use when MANPAGER
>                  is not defined.  If neither PAGER nor MANPAGER is de‐
>                  fined, less(1) is used.  Only used if  -a  or  -l  is
>                  specified.
> 
> That's probably a glitch of not having a comprehensive list of options
> and their description.

...or a glitch of not integrating discussion the `-l` option into the
narrative as Ingo suggested I do.  I further note that at least as of
mandoc 1.14.6 in Debian, `-l` is also not documented in its man page's
"Synopsis" section.

I can't hurl too many stones--there are groff man pages where I not only
do not practice what I preach, but where I haven't even gotten around to
recasting a former contributor's rambling asides and rather anguished
English.

> Going more into what concerns me, which is man3, I often miss an
> ARGUMENTS (or PARAMETERS, to be more precise) section in the pages for
> functions.  Sometimes it would be just one line per argument, but in
> other cases it would help a lot have more organized information.  I'll
> show you a few cases where I've used it, and where I think it made a
> difference.
> 
> <https://github.com/shadow-maint/shadow/blob/master/lib/stpecpy.h>
> <https://github.com/shadow-maint/shadow/blob/master/lib/stpeprintf.h>
> <https://github.com/shadow-maint/shadow/blob/master/libmisc/agetpass.c>

I don't have strong feelings about this.  A deeper principle I hold is
that functions shouldn't take a lot of arguments in the first place.  If
they do, it is a sign that

1. a data structure is called for, and a pointer to it should be passed;

and/or

2. the function is too complex, tries to do too much, and should be
   decomposed into orthogonal features.

The latter doesn't mean you can't also provide a convenience function to
handle common cases, or show the user how to implement one.  To recall
and old disagreement of ours, this is why I prefer memset() to bzero()
as a standard library function.  (Yes, memset() takes more arguments,
but it is also more _general_.  But I digress...)

On the TUHS list in the past year or so, someone posted, or shared a
link to, a reminiscence by a 1970s Bell Labs CSRC person that they
introduced the system call with the longest signature seen in Unix to
date (I think it was mmap(2)).  They expressed nervousness about it,
fearing cries of inelegance from their peers--perhaps even the figure
of Ken Thompson himself darkening the office doorway.

But it went in anyway, apparently, on the strength of the functionality.
Maybe the prospect of fighting Multics on its own ground was too
appealing to pass up.

> It's kind of a synopsis of the parameters.  Would it be better _after_
> the description?  Maybe.

Maybe not.  _If_ you're going to have an "Arguments" heading for
section 2 or 3 man page, placing it between "Synopsis" and "Description"
seems appropriate.

> Is it better than having it all in the description?  I think it is.
> Will we see this in the Linux man-pages some day?  Maybe.  What's your
> opinion?

I think you should collect more opinions.  Also consider going back to
the Unix Programmer's Manuals of the 1970s and see how they tackled the
issue.  The complications of history are not going to make _every_
simplification impossible.  And you may well find places where these
manuals were ill-written or the API badly designed.  (Inter-process
communication was not born elegant in Unix and still isn't to this day.)

> Yup, I think the man pages should serve as both (short) tutorials
> *and* quick references.  If I need further info, I go to
> StackOverflow, but I'd like to understand at least the basics of a
> function when reading its page (and I've learnt many of the man3
> functions by reading the pages while maintaining them; for example, I
> didn't even know there was a regex(3) function until I saw the page
> being mentioned in a ffix patch by Michael; a few weeks later I needed
> it, and could use it by just reading the manual; then I added the
> example program with something close to what I did with it).

I learned years ago that the only way I can truly learn anything that
isn't simple is to start rewriting its documentation, which usually
means conducting a lot of experiments.  In the 6 years or so I've been
contributing to groff I've amassed a set of 1,433 files in my
"EXPERIMENTS" subdirectory.  I've also thrown many experiments away.

Other people may have an easier time forming accurate models of
programming systems in their heads, but for me the right approach
appears to be radical skepticism combined with a record of findings
(i.e., expanding or correcting the documentation where appropriate).

> Something I do is first look at the synopsis, have a quick look at the
> description searching for one line that describes each argument, and
> then look at the example program to guess myself about the function.
> Only after that is when I try to read the entire page to know the
> details.  But most of a function should be obvious already before
> reading the description, or the design of the function would be
> dubious.

I broadly agree.  This is one reason naming things well is important.

> Which reminds me that when I move to 1.23.0 as a dependency, we should
> have another look at Deri's script, and simplify it.

I feel a powerful urge to simplify his "an:cln" macro to near
triviality by filling a feature gap in the formatter.

https://savannah.gnu.org/bugs/?62264

Assuming groff internals work the way my mental model says they do, and
the test of that will come with more experiments...

Regards,
Branden

signature.asc
Description: PGP signature