Hi Stefan,
Stefan Hagen wrote on Wed, Aug 30, 2023 at 09:41:20AM +0200:
> There's no good way to handle a conflict that's introduced with an
> update. So what we would do is to move the manpages into the install
> directory. (thanks to espie@ for the suggestion)
Actually, i regard that as bad advice, espie@ shouldn't say such things.
Moving ports manual pages out of the standard /usr/local/man/ tree
is a last resort measure that should be reserved for the most
extreme cases - for example, language systems having huge numbers of
manual pages, many of which conflict with base system manual pages
(like lang/tcl, or to a lesser degree, plan9/plan9port) and for
collections of manual pages that simply don't document the system
they get installed on (like books/man-pages-posix).
For a small application-level port like x11/fvwm3, i regard moving
a handful of manual pages out of /usr/local/man/ as totally
inappropriate:
* Almost nobody ever bothers with putting "manpath" directives
into man.conf(5). And that's a good thing. Having to maintain a
list of manual page trees would be cumbersome. Besides, the more
trees you configure, the more error prone and the less efficient
manual page searching and lookup becomes. And there isn't really
any problem that needs to be solved with this configuration option.
Looking up manual pages ought to work by default, without users
having to worry about configuring anything - and porters can indeed
help making things work by default.
The consequence is that, if you move some manual pages out of
/usr/local/man/, most users simply won't ever see them, not even
when they are actively searching for them.
* Even if a user is aware where these pages are and wants to
look at them specifically, the simplest command achieving that is
man -M /usr/local/share/fvwm3/man FvwmPager
That's an awful lot to type, even with the help of tab completion.
For people coding in tcl a lot, doing something like
alias tm='man -M /usr/local/lib/tcl/tcl8.5/man'
in a shell initialization file would arguably be acceptable
even if not particularly elegant, but for fvwm3, such a
concoction would be quite the overkill.
I have occasionally considered making commands like
man -M tcl open
work, but the design isn't as trivial as it seems, getting it
right on the first try matters, and demand is so limited even
for stuff like tcl and man-pages-posix that i did not do it yet,
even though eventually, i certainly hope to. Even if we had that
already, it would seem unlikely to me that people would remember
using if for fvwm3.
> You'll then get a nice little info to add this path to your man path
> when the package is installed:
>
> --- +fvwm3-1.0.7 -------------------
> You may wish to add /usr/local/share/fvwm3/man to /etc/man.conf
I absolutely hate that message. It is not nice at all, and it is
almost always bad advice. You even get that message for tcl
and for man-pages-posix, where it makes absolutely zero sense.
And for a simple port like fvwm3, you would really be willing
to manually edit a system configuration file merely to read a
handful of manual pages contained in that port?
I certainly wouldn't do that, it feels so insulting.
Fortunately, there is a simple solution:
> +@man share/fvwm3/man/man1/FvwmAnimate.1
> +@man share/fvwm3/man/man1/FvwmAuto.1
> +@man share/fvwm3/man/man1/FvwmBacker.1
> +@man share/fvwm3/man/man1/FvwmButtons.1
> +@man share/fvwm3/man/man1/FvwmCommand3.1
> +@man share/fvwm3/man/man1/FvwmConsole.1
> +@man share/fvwm3/man/man1/FvwmEvent.1
> +@man share/fvwm3/man/man1/FvwmForm.1
> +@man share/fvwm3/man/man1/FvwmIconMan.1
> +@man share/fvwm3/man/man1/FvwmIdent.1
> +@man share/fvwm3/man/man1/FvwmMFL.1
> +@man share/fvwm3/man/man1/FvwmPager.1
> +@man share/fvwm3/man/man1/FvwmPerl.1
> +@man share/fvwm3/man/man1/FvwmPrompt.1
> +@man share/fvwm3/man/man1/FvwmRearrange.1
> +@man share/fvwm3/man/man1/FvwmScript.1
Change the file names of the above to fvwm3-FvwmPager.1 etc.
and install them /usr/local/man/.
Whether you use FvwmCommand3.1 or fvwm3-FvwmCommand3.1
is a matter of taste, both seem fine. It would be ideal to do it
in such a way that, for consistency, bot of these work:
man FvwmCommand3
man fvwm3-FvwmCommand3
> +@man share/fvwm3/man/man1/fvwm3-convert-2.6.1
> +@man share/fvwm3/man/man1/fvwm3-menu-desktop.1
> +@man share/fvwm3/man/man1/fvwm3-menu-directory.1
> +@man share/fvwm3/man/man1/fvwm3-menu-xlock.1
> +@man share/fvwm3/man/man1/fvwm3-perllib.1
> +@man share/fvwm3/man/man1/fvwm3-root.1
> +@man share/fvwm3/man/man1/fvwm3.1
> +@man share/fvwm3/man/man1/fvwm3all.1
> +@man share/fvwm3/man/man1/fvwm3commands.1
> +@man share/fvwm3/man/man1/fvwm3menus.1
> +@man share/fvwm3/man/man1/fvwm3styles.1
Those can go to /usr/local/man/ without any tweaking, i guess.
That way,
man -a FvwmPager
will display all three FvwmPager(1) manual pages when both ports are
installed, because our man(1) implementation takes page names
from all of the file names, .TH arguments, and NAME entries.
So you can easily have multiple manual pages with the same names
within the same manual tree (here, usr/local/man/), as long as the
file names differ. Even if the content of the individual pages should
fail to identify the fvwm version,
man -w FvwmPager
will tell you which is which.
And as a bonus,
man fvwm3-FvwmPager
works as soon as you are aware the is more than one and you know
which one you want - with absolutely zero user configuration needed,
sane defaults out of the box.
Of course, you should test that it all works as expected before
committing the port, but i don't see why it shouldn't.
Yours,
Ingo
