Re: .so colophon.man

[Alejandro Colomar (man-pages)]

Hi Ingo,

On 7/31/22 14:20, Ingo Schwarze wrote:
> Hi Alejandro,
>
> Alejandro Colomar wrote on Sat, Jul 30, 2022 at 10:45:42PM +0200:
>
> > I'm wondering if it wouldn't be easier to have a constant '.so
> > man-pages-colophon.man' line at the end of all of the Linux man-pages,
> > instead of appending a COLOPHON at every release.  The
> > man-pages-colophon.man file would be shiped together with the pages,
> > and it would be created by `make dist`.
>
> I seem to very dimly recall that once in the past, i encountered a
> tool that assumed each manual page either consists of a single .so
> line, or does not contain .so at all.

I myself wrote tools (the Makefile I think assumes that) that assume 
files containing .so are link pages.  Maybe you recall my code.

I [cw]ould fix that, of course.

[...]
> Now the bug is that when finding a .so link, this version treats
> the .so link with priority, assuming getent(1) is just a
> symbolic link for "man-pages-colophon.man".  So it looks up
> its own entry for man-pages-colophon.man in its own database,
> intending to add the information found in getent.1 to that
> entry.  When a file contains nothing but .so, that of course
> makes sense because you don't want two database entries for the
> same manual page, even if that page documents more than of
> function or utility.  But in this case, it realizes there is
> no database entry for "man-pages-colophon.man" - no wonder because
> it already decided earlier that's not a manual page.
>
> And here is the bug: not finding "man-pages-colophon.man"
> in the manual page database, it ends up setting
>
>    meta->macroset = MACROSET_NONE;
>
> because it wrongly thinks this probably is merely a dead link.
> That results in completely ignoring the content of the manual
> page (even though there was no problem parsing it whatsoever)
> and instead only using the information from the file name
> as indicated by these three messages:
>
>    No one-line description, using filename "getent"
>    Name missing in NAME section
>    Adding to database
>
> (The reason for adding the file to the database anyway is that
> even if it is a dead link, adding it to the database makes sense
> such that the user realizes the system *intends* to supply a
> manual page for the name but only provides a dead link, such
> that the user can report the dead link to the package maintainer
> rather than thinking the software author failed to write any
> manual page at all and never intended to write one.
>
> Of course i need to fix this bug in makewhatis(8).

Okay.

[...]
> > Do you think it would be a good idea?
>
> Not really.
>
> First, putting this information into every single manual page
> IMHO is a bad idea.  Such information ought to be part of
> packaging information and not displayed with each and every
> page.  If users want to find the version of some package,
> they should use commands like
>
>    # Debian
>     $ dpkg-query -S bunzip2.1
>    bzip2: /usr/share/man/man1/bunzip2.1.gz
>     $ dpkg-query -s bzip2
>    [...]
>    Version: 1.0.6-9.2~deb10u1
>
> or
>
>    # OpenBSD
>     $ pkg_locate bunzip2.1
>    bzip2-1.0.8p0:archivers/bzip2:/usr/local/man/man1/bunzip2.1
>     $ grep HOMEPAGE /usr/ports/archivers/bzip2/Makefile
>    HOMEPAGE=       https://sourceware.org/bzip2/

I agree with this.  The version information is better served by dpkg, 
and the "reporting bugs" information is better served by apt-cache.  In 
general, distributors provide that info, and providing it ourselves 
hardcoded in the page is multiplicating the information.

I guess it was good for publicity of the project back when mtk took 
maintainership of it, but I think there's no such need anymore, and I 
prefer simplicity and conventions.

I think I'll remove the COLOPHON.  One less problem.

> Repeating that informtion in every manual page is embarassingly
> verbose; users normally don't want to see that.
>
> If you do want the COLOPHON nonetheless, using .so is clearly
> more fragile than including it outright.
>
> If you do want to use .so nonetheless, putting the included file
> into the root of the manpath is ugly; imagine the mess if more
> projects did that, in particular if you also start creating more
> section suffixes.  If the file man-pages-colophon.man belongs
> anywhere, then it belongs into man0/ - that's just what AT&T
> originally used that directory for: front matter, support files,
> scripts, and snippets.
>
> You might perhaps argue that you want to COLOPHON included with every
> page such that if anybony tears out a single manual page from the
> package and reuses it somewhere else, that information is retained.
> But *if* that is your argument, using .so defeats that particular
> purpose, too.
>
> > I was making the COLOPHON be part of the `make dist` command (to avoid
> > having to generate it separately), and this would simplify things a lot.
> > Not having to append to files controlled by make(1) would avoid having
> > to rerun many recipes.
>
> Your choice what matters more: convenience for upstream package
> maintainers or robustness for users.
>
> For downstream package maintainers, having to handle files
> included by manual pages is also an unusual task that might
> confuse some.  Besides, a few may have get used to how some
> POSIX manual page packages are abusing man0/ for the wrong
> purpose and may consequently feel even more confused.
>
> Yours,
>    Ingo

Agreed.

Cheers,

Alex


--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/