Bug#1094145: debian-policy: Remove or significantly minimize manual page requirement
On Sat, Jan 25, 2025 at 10:23:01AM -0500, Jeremy Bícha wrote:
> On Sat, Jan 25, 2025 at 5:21 AM Bill Allombert <ballombe@debian.org> wrote:
> > The man page provides a link between the executable name and the app.
> > This is useful in a lot of situation. Writing such a manpage is not
> > a waste of time.
>
> I think apps already have .desktop files that provide that link.
How do you match a binary to a desktop file ? It is far from obvious or
natural, and GUI packages tend to carry extra binaries that are not in any
.desktop files.
> As an example of how new contributors are taking time to make manpages
> that are not helpful only to silence a Lintian warning, see
> https://salsa.debian.org/danialbehzadi/showtime/-/blob/debian/latest/debian/showtime.1
> which was created today.
>
> For an example of an app that I don't believe needs a manpage, see
> gnome-clocks. It provides useful information about itself in the About
> dialog and in the user Help, both can be easily accessed in the ☰
> menu.
Not before you run it, assuming it will even start, which can cause annoying
side effect (for example, playing sound, creating files in ~/.config, etc.).
We should not need to run an app before having an idea of what it does.
> I think manpages can be helpful for command line utilities. I use
> manpages myself frequently. I especially appreciate
> https://manpages.debian.org/ which allows me to make use of
> documentation without needing to install anything.
>
> My opinion is that current Debian Policy and the associated Lintian
> warning are encouraging Debian contributors to simply run help2man,
> either in debian/rules or once when they create an initial package. I
> am skeptical whether help2man provides value. I am skeptical whether
> Debian-specific manpages provide value.
They do add value, because at least 'man foo' says something, and it is unsafe to
run a random binary with the option --help just to see what happens.
Cheers,
--
Bill. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: