[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: .so

From: Alejandro Colomar (man-pages)
Subject: Re: .so
Date: Sun, 31 Jul 2022 14:38:30 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

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' line at the end of all of the Linux man-pages,
instead of appending a COLOPHON at every release.  The 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 "".  So it looks up
its own entry for 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 "" - no wonder because
it already decided earlier that's not a manual page.

And here is the bug: not finding ""
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).


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


   # OpenBSD
    $ pkg_locate bunzip2.1
    $ grep HOMEPAGE /usr/ports/archivers/bzip2/Makefile

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





Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]