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

[G. Branden Robinson]

Hi Sven,

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

> and ncurses does not install an "init" symlink in the bin/ directory.

As a rule the ncurses man pages are not parameterized in what's
available in the configuration, but in what the package is prepared to
_support_.  For example, you get man pages for tons of wide-character
configuration-only symbols even if you don't build the library that way.
(And even if the wide-character-only man pages were dropped, references
would still be plentiful not only by cross reference, but in the content
of pages that discuss the wide and non-wide APIs together.)

I also think I would have trouble advocating such parameterization.
ncurses should document its full potential, and if the user can be left
unsure of how to determine what their system's ncurses configuration is,
the man pages should help them to figure it out.  ("A simple matter of
documentation", as the saying doesn't quite go...)

I therefore don't see why what ncurses _installs_ is relevant.  What is
being documented is that one can put a hard or symbolic link to tput
called "init" in /usr/local/bin or $HOME/bin, and it will behave as
documented ("tput init")[1].

Further, ordinary users have little reason to run init(8).  I would
expect users administrating their own systems to be sophisticated enough
to realize that multiple man pages may be available under the same name
(this is one reason why the manual has sections).  A classic example is
"printf".

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

> This causes an init.1 symlink to tput.1 to be installed, which is bad
> because there is no corresponding program and at least on Debian the
> manpage clashes with the one provided by the systemd-sysv package.

As noted, I don't see a real problem here, but I also don't see the
construction of man page symlink farms as worthwhile _if_ the system's
mandb(8) or makewhatis(8) program is adequate to the task of building
indices of man pages.  I acknowledge: that circumstance may not obtain
everywhere.  But by the same token, getting rid of the symlinks on such
a system wouldn't solve the problem if that system _did have a competent
indexer; the confusion you fear, and which I think you are overstating,
would reappear thanks to the linkage constructed in the man page index
used by man(1).

Finally, I would venture that the novice user at a shell prompt whose
confusion you fear is likely going to be as interested (in more) on how
to control the behavior of terminal, and particularly its recovery from
a bad state, than in a command that is seldom used from the shell, and
requires superuser privileges to run in the first place.

Regards,
Branden

[1] Try it!

$ tput
[get usage message]
$ (cd ~/bin && ln -s /usr/bin/tput init)
$ type -p init
[verify that your symlink is found]
$ tput smso # "mess up" your terminal
$ init
[observe repaired terminal state and lack of usage message]
$ rm ~/bin/init

signature.asc
Description: PGP signature