Re: [PATCH] [grotty]: Use terminfo.

[Ingo Schwarze]

Hi Lennart,

Lennart Jablonka wrote on Tue, Aug 22, 2023 at 05:56:51PM +0000:
> Quoth Ingo Schwarze:
>> Lennart Jablonka wrote:
>>> G. Branden Robinson wrote:

>>>> Until it does, read "terminfo(3)" as "putp(3)".  It's brings
>>>> up the relevant page and is quicker to type anyway.

>> Good advice.

>>> That conflicts with my sense of aesthetic.   References should use
>>> the man page title.   The correct way to refer to putp’s man page
>>> is something like “Print stuff using putp (see terminfo(3)).”

>> Absolutely not.  It is very widespread practice to refer to a page
>> by any of its names that can be found by man(1).  Best practice,
>> in any particular instance of a reference, is to use the name that
>> is most logical.  So pointing to putp(3) is actually better in the
>> example you are constructing above because this makes more sense to the
>> reader and is easier to understand.  The user has no reason to care
>> which other function may or may no be documented in the same page.
>> Besides, that is likely an operating-system specific implementation
>> detail and often even changes over time within an operating system.
>> I have personally merged and split manual pages many times in the past,
>> and it would be a maintenance nightmare if performing such a merge or
>> split would require changing all cross-references to the manual pages
>> involved in the split or merge.  On Linux, the inconvenience would
>> be even more dire than on BSD systems because you would have to deal
>> with many different package maintainers, some of whom may be slow to
>> respond, let alone roll a new release for their package, so in Linux,
>> your policy would render manual page maintenance next to unworkable.
 
> I recognize the burden it would be on the maintainers.   I do feel like 
> you’re exaggerating:  How often does it change which man page a function 
> or whatever is documented in?

In OpenBSD, i'd estimate such cases arise roughly every few weeks
on average.  Since OpenBSD is a relatively compact system focussing
on stability and simplicity, i'd expect the rate being larger in more
modularized, larger, and more feature-hungry systems.

Besides, while the work involved in maintaining cross references among
manual pages does not constitute the majority of work when maintaining
manual pages, it is not insignificant either, in particular when it
comes to larger libraries like OpenSSL or LibreSSL.  Even with the
current, simple scheme, i have spent many days of work on improving
cross references, and i have watched others do similar work.

> But then, I don’t work on man pages nearly as much as you do.

>> Besides, "using putp (see terminfo(3))" looks ugly, is unnecessarily
>> wordy, and causes a distraction of the reader for not benefit
>> whatsoever.
 
> Oh, but there is a benefit:  If you print your collection of man pages, 
> calling it something like “OpenBSD Programmer’s Manual,” the man pages 
> will be sorted by their titles.   If done well, you’ll also have a KWIC 
> index of the NAME lines, but it’s still easier to find the page you’re 
> looking for if you have the title directly.

In particular when you care about locating information quickly and
easily, putting it on dead trees is a very bad idea.  KWIC was a
great idea when invented more than 150 years ago and still quite
useful when used for the AT&T UNIX manuals in the 1970ies (because
they didn't have CRT displays at Bell Labs at first).  Even though i
did have a monochrome CRT when using HP200 machines in the 1980ies,
i still used printed documentation because those machines had no hard
disks and the floppies they used weren't even large enough to hold
the complete operation system, let alone documentation, and swapping
floppies and waiting for them to be read would have been awkward.
But i'd say printed software documentation became obsolete roughly
around 1990.

Nowdays, i have a hard time taking KWIC seriously even as a crude
workaround for a lack of semantic search and regular expression
capabilities.

> That’s not much of a concern today.   Few projects today of those that 
> have many man pages collect them in one work.   Groff does;  man-pages 
> does.   Stanley Lieber provides printed man pages for 9front.¹
> ¹ https://9front.org/propaganda/books

That looks like a work of love, aesthetic enjoyment, and nostalgia
to me.  But making the text harder to read for users reading manuals
at the command line or on the web and harder to maintain at the same
time, to marginally help searchability of the printed version, which
remains atrocious by today's standards either way - what a bad tradeoff...

> An OpenBSD Programmer’s Manual?   I’d like to see that, but I doubt
> anyone will do it.   Still, it is a concern.   For those who feel
> good about being able to print man pages, at least.

Every user would have to print and re-print that over and over again,
each time on freshly killed trees, at least twice a years.  Some
users are updating their OpenBSD systems as often as weekly...

> You could observe project boundaries.   Ncurses man pages could refer to 
> curs_terminfo(3X), Groff to putp(3) (were it to refer to putp at all).   
> That would work if it wasn’t too complicated for all those independent 
> man page authors.   Except, of course, that someone integrating man 
> pages from a different project won’t want to change how those man pages 
> reference others.   To go through ncurses’ man pages, changing “sscanf(3)” 
> to “sscanf (see scanf(3)).”

Sure, it's not a big deal if different projects use different styles,
including somewhat awkward, cumbersome, redundant and error-prone
styles like "sscanf (see scanf(3))".  My point is that you tried to
tell people the simplest, most widespread way of always referencing
the function most relevant in the context, which is also easiest to
read, easiest to maintain, and least error-prone, is somehow bad,
and that you labeled a somewhat idiosyncratic style that is unlikely
to work well in practice as "the correct way".  Trying to justify
that, you also used the ill-defined and undefinable terminology "*the*
name of a manual page" (which you snipped here).

Yours,
  Ingo