Re: ANN: ncurses-6.4-20230617

[G. Branden Robinson]

At 2023-06-25T11:09:46+0200, Sven Joachim wrote:
> On 2023-06-17 19:53 -0500, G. Branden Robinson wrote:
> > At 2023-06-17T21:33:04+0000, Thomas Dickey wrote:
> >> 20230617
> >>    + markup manpages with revision information (prompted by
> >>      discussion with Bjarni Ingi Gislason).
> >
> > Thank you for this; it's a definite quality of life improvement for
> > those who spend a lot of time looking at man pages.
> 
> Indeed.  Unfortunately there is a small problem: with the
> "--with-manpage-renames" option (default in Debian), the .TH lines no
> longer get replaced, and Debian's lintian tool goes nuts about it.
> 
> ,----
> | W: ncurses-bin: wrong-manual-section 1 != 1M 
> [usr/share/man/man1/captoinfo.1.gz:32]
> | W: ncurses-bin: wrong-manual-section 1 != 1M 
> [usr/share/man/man1/infocmp.1.gz:32]
> | W: ncurses-bin: wrong-manual-section 1 != 1M 
> [usr/share/man/man1/infotocap.1.gz:32]
> | W: ncurses-bin: wrong-manual-section 1 != 1M 
> [usr/share/man/man1/tic.1.gz:31]
> | W: ncurses-bin: wrong-manual-section 1 != 1M 
> [usr/share/man/man1/toe.1.gz:31]
> | W: ncurses-doc: wrong-manual-section 3curses != 3X 
> [usr/share/man/man3/panel.3curses.gz:31]
> | W: ncurses-doc: wrong-manual-section 3form != 3X 
> [usr/share/man/man3/cursor.3form.gz:32]
> | ... [100+ similar lines skipped]
> `----
> 
> It seems that man/make_sed.sh has to be updated for the improved .TH
> lines, but I have not looked what exactly needs to be done.

Might I suggest dropping the sectioning suffixes from ncurses' man
pages?

The convention in use descends from, I believe, the Version 7 Unix
manual,[1] where, for section 3, the section/suffixes were as follows:

3C      stdio library functions
3M      math library functions
3X      "various specialized libraries [without] distinctive captions"

An unadorned "3" applied to functions from the (pre-standard!) C (and
Fortran) runtime library that were neither stdio nor math components.[2]
(The naïve reader might wonder why abs(3) was not a "math" function.)

Version 7 also proposed a partitioning of the section 1 space, which,
apart from 1M, seems not to have lasted long.[3]  (When's the last time
you saw a man page in section 1G?)

By 4.4BSD, Berkeley Unix seems to have abandoned these conventions.[4]

System V Unix seems to have clung to them.  I was tempted to say "for
longer", but by the time 4.4BSD finally came out, System V was ossifying
at great speed.  GNU/Linux, arising in this same period, seems to have
treated man page section suffixes largely with disregard.

Given the long-standing divergence in practice, with no prospect of its
resurrection, and the fact that a system providing multiple curses
implementations may well have to relocate or rename the man pages of one
or more such implementations upon installation anyway,[5] I propose that
it would be simpler for ncurses to just get rid of the suffixes.

Lest anyone feel that I'm picking on ncurses, I note that X.Org needs
its windmilling man pages tilted at in similar fashion.

I have a follow-up idea if this one's not too shocking.  Let me know.

Regards,
Branden

[1] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man3/intro.3
[2] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man3/
[3] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man1/intro.1
[4] Contrast
    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/man/man3/intro.3
    with
    
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/share/man/man3/intro.3
    (and mind the conversion from man(7) to mdoc(7) macros).
[5] I note that even the cryptic "curs_" file names that most ncurses
    man pages use are identical to those from the System V Interface
    Definition.  These would be the pages that Eric Raymond claimed were
    not under copyright, and that he "reverse nroffed" upon import into
    ncurses about 29 years ago.[6]  Fortunately, decades of relentless
    rewriting by Thomas Dickey and others, and the possibility of SVID
    being an "orphaned work"[7] render this assessment less ominous than
    it might otherwise be.
[6] https://invisible-island.net/ncurses/ncurses-license.html#ncurses_1_8_5
[7] https://www.copyright.gov/orphan/orphan-report.pdf

signature.asc
Description: PGP signature