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

[Lennart Jablonka]

Quoth Ingo Schwarze:
> > > 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?   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.

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.¹   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.

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)).”

That’s it for a little discussion of this.

¹ https://9front.org/propaganda/books