Re: [PATCH 12/40] man/tput.1: Revise (1/10) (NAME, SYNOPSIS, DESCRIPTION introduction).

[G. Branden Robinson]

Hi Sven,

At 2024-01-15T17:42:48+0100, Sven Joachim wrote:
> On 2024-01-14 06:40 -0600, G. Branden Robinson wrote:
> 
> > At 2024-01-14T12:55:13+0100, Sven Joachim wrote:
> >> On 2024-01-12 13:28 -0600, G. Branden Robinson wrote:
> >>
> >> > Content:
> >> > * Add "init" as page topic name (like "reset"), since tput
> >> >   specially supports being called by that name.
> >>
> >> Perhaps, but "init" is also the name of the program run as PID 1,
> >
> > I'm aware.  I've been using Unix since before systemd was a gleam in
> > Lennart's Apple-aping po(e)ttering eye... ;-)
> 
> This is not the place for ramblings about systemd or Lennart
> Poettering.

One fifteen-word sentence that identifies the reason and personage for
the very clash you're complaining about is not a "ramble".  It is not "a
going or moving from place to place without any determinate business or
object."  It takes two to clash; I'm identifying the counterparty.

The system (and ultimately, the person) responsible for putting an
"init" man page in section 1 of the manual imposes a question of
priority--both in the historical sense and in terms of importance.

If you have a problem with my claim, you're going to need to express it
less opaquely for me to understand it.  If you mean to make some sort of
innuendo, then I counter that you are the one who is misusing the forum.

Now then--on to less radioactive, and more empirical, matters.

> Anyway, whoever has the idea of special-casing tput's argv[0] as
> "init" must have been crazy,

I happily concede the possibility.  Not my circus, not my monkeys--I'm
documenting the carnival I see.

> since I am sure that "init" was PID 1's name even back then.

What appears in ps(1) or top(1) output as argv[0] is not necessarily a
reliable predictor of what one can look up as the name of a man page.
In fact, it's become a _worse_ predictor over time on Linux systems.  I
expect little luck with man pages for "kworker" (followed by an
implausible sequence of characters for a man page name) or "Isolated Web
Content".

But really, that horse left the barn in the 1970s or '80s when someone
decided to have the shell rewrite its argv[0] to stick a dash at the
front.[1]  (What moron would assume that was part of the command name,
eh?)  I don't know who gets to wear the blame for that idea.[2]

> > I therefore don't see why what ncurses _installs_ is relevant.
> 
> It obviously is relevant for distribution packagers like Werner and
> me, who need to remove or rename the init.1 symlink.

As Obi-Wan Kenobi said, "you must do what you feel is right, of course."

> Manpages can have the same name, but sharing also the same section does
> not work.
> 
> > $ man -aw printf
> > /usr/share/man/man1/printf.1.gz
> > /usr/share/man/man3/printf.3.gz
> >
> > $ man -aw init
> > /home/branden/ncurses-HEAD/share/man/man1/tput.1
> > /usr/share/man/man1/systemd.1.gz
> >
> > I see no deep distinction between these scenarios.
> 
> The latter leads to a file clash by default, the former does not.

I didn't realize that man-db was hiding from me the fact that a stub
`so` page was present.  (I don't claim that such hiding is wrong; having
"man -aw" show a pile of stub pages that point to one already in its
list would deliver little value.)  I see now that, on my Debian system,
the `systemd-sysv` package does indeed ship it.

$ dpkg -S /usr/share/man/man1/init.1.gz
systemd-sysv: /usr/share/man/man1/init.1.gz

So, yes, that's a problem.  There are a few possible solutions.

1.  ncurses changes nothing, and distributors decide which page wins;

or

2a.  ncurses extends its "ncurses" section suffix convention (in some
     configurations) from section 3 to section 1, at least for this
     page;
2b.  as 2a, but only for systemd-using hosts;
2c.  ncurses stops creating this particular symlink, as a regrettable
     inconsistency with its practice of creating them for each topic
     listed in each page's "NAME" section;
2d.  ncurses reverts my addition of "init" to the list of tput(1) page
     topics, as a regrettable inconsistency with tput and tset's support
     for "reset"; or
2e.  ncurses drops tput's support for being called as "init".

I assume 2e would break compatibility on some System V vendor Unix
curses whose tput behaves in a similar way, and which ncurses has
enjoyed supplanting for decades.  As the tput(1) page notes, X/Open did
not standardize the _utilities_ of a Curses implementation (including
tput) until Issue 7 (2009), by which time the Unix Wars were long over.

I assume 2d is the popular choice among distributors, since it restores
the status quo ante and that's where the safe money usually is.

2c has, I would guess, similar distributor appeal, but freights
ncurses's "install" target, already complex and relatively slow, with
(another?) special case.  I worry about its maintainability already.

2b would require Autoconf macro composition, a prospect that seems to
terrify most programmers sufficiently that they hasten to adopt and
praise alternatives like cmake, ninja, and ganja.  But I have some
Autoconf experience and am willing to take a crack at it; tell me the
shape of the desired solution.

I don't have a strong opinion about 2a, but if there aren't any
(non-contrived!) use cases for unprivileged users directing systemd with
/usr/bin/init, then I suggest that systemd has unjustifiably squatted on
that piece of the command (and man page) name space.

> Getting rid of the symlinks and relying on indices only also requires
> support in many other programs, for instance shell completion or
> Emacs' man package currently rely on filenames.

A fair point, especially if Emacs still maintains the paradigm that man
pages are a resource that should be utterly supplanted by GNU Info.

> Novice users, and even most experienced users, have little use for
> "tput init" either.

That's more of an argument for 2e than having the man page topic list be
gratuitously inconsistent with what the _program supports_.

You and I are arguing because you are approaching this problem from the
"system integration" perspective, and I am approaching it from the
"accurate and consistent documentation" perspective.  Sometimes such
things have to be balanced.

> It's not like 25 years ago when there were endless discussions about
> the behavior of the backspace key in Debian.

The keyboard is the original DWIM interface.  ;-)

> Anyway, this is for Thomas to decide

I agree; that his prerogative as maintainer.

> and I will shut up now.

As far as I'm concerned, you should keep participating if you have
something more to say and can do so relatively dispassionately.

I suppose I might have raised the temperature by neglecting one of the
rules of the Archetypal Irish Novel.[2]

"We Do Not Speak That Name In These Parts, Stranger"

...not realizing that you felt Debian's unwritten cultural rules applied
here as well.

But then I've never had much respect for taboos anyway.  ¯\_(ツ)_/¯

Regards,
Branden

[1] ...to indicate that the shell was "interactive".  What I think
    really drove this was the increasingly heavy load placed on the Unix
    kernel's process structure.  It acquired a _bunch_ of features
    mainly to support shells and job control...all that stuff in a few
    chapters of Stevens's _Advanced Programming in the Unix Environment_
    that only lunatics who decide to write a shell ever truly master.
    Anyway it was getting harder and harder for simple tools like top(1)
    and ps(1) to report everything you really wanted to know, especially
    on an 80x24 terminal,[4][5] and the ecosystem buckled under the
    strain, leading to ad hoc conventions.

[2] My guess is that it was considered important, and thus stuck,
    because administrators of dialup time-sharing systems desired a fast
    way to identify which one of a user's shells they needed to kill to
    kick them off the system.  We forget BOFH culture at our peril.

[3] https://the-toast.net/2014/06/30/every-irish-novel-ever/
[4] 
https://user-images.githubusercontent.com/775050/121336830-2dd2f780-c91c-11eb-84b6-e7dacf5324d0.png

[5] https://github.com/larsbrinkhoff/terminal-simulator
    ...for those wondering where that image comes from.

signature.asc
Description: PGP signature