Debian Policy §12.1 has this section:
"Each program, utility, and function should have an associated manual
page included in the same package or a dependency. It is suggested
that all configuration files also have a manual page included as well.
Manual pages for protocols and other auxiliary things are optional.

If no manual page is available, this is considered as a bug and should
be reported to the Debian Bug Tracking System (the maintainer of the
package is allowed to write this bug report themselves, if they so
desire). Do not close the bug report until a proper man page is
available. [1]

You may forward a complaint about a missing man page to the upstream
authors, and mark the bug as forwarded in the Debian bug tracking
system. Even though the GNU Project do not in general consider the
lack of a man page to be a bug, we do; if they tell you that they
don’t consider it a bug you should leave the bug in our bug tracking
system open anyway.
…
[1] It is not very hard to write a man page. See the Man-Page-HOWTO,
man(7), the examples created by dh_make, the helper program help2man,
or the directory /usr/share/doc/man-db/examples."


I believe the Policy recommendation here is far too strong. It uses
should instead of must, but then it says someone should file a bug
whenever a manpage is not provided. A maintainer should not close this
bug.

It recognizes that the GNU Project doesn't consider missing man pages
to be bugs. My understanding is that that was because GNU prefers the
competing info documentation format.

This section of Policy is at least 20 years old and I believe the
Debian system has changed dramatically in that period.

There is a corresponding Lintian tag that is widely ignored.
https://udd.debian.org/lintian-tag/no-manual-page?affected=yes shows
5000 hits (only 630 of those are overrides) and it only gets as far in
the alphabet as gcc-11. I believe this demonstrates that there is
widespread consensus among Debian Developers and Maintainers that
Debian Policy should be ignored on this point, despite many years for
Debian contributors to comply. Therefore, I think most of this section
should be removed.

Debian Policy is creating work that may not be helpful
-----------------------------
- Many new contributors to Debian in an attempt to get their new
package "Lintian clean" spend significant time creating a manpage for
their app, often a GUI app with no command line options. The manpage
does not really have useful content.
- Many open bugs exist requesting manpages for apps where it may
similarly not be needed.
- Despite Debian Policy saying maintainers shouldn't, maintainers do
in fact close at least some of those bugs. I think this weakens the
strength of Debian Policy.
- It is difficult for contributors to use Lintian when some warnings
should be fixed and others like this one should probably be ignored
(at least from the perspective of many experienced contributors).
- It also encourages Debian contributors to create Debian-specific
manpages that are likely never updated, even if the upstream project
changes significantly.

Thank you,
Jeremy Bícha

FWIW, I think it is desirable to get as many man pages as we can.
To that end, I hope policy continues to:

*encourage writing man pages

* Encourage maintainers to take well written man pages as patches.

At the time that section of policy was last written, allowing people to
open bugs on missing man pages of non-RC severity (that's what should
means in policy language) was the way to do that.

I'm happy to  support text that reduces the bookkeeping requirements of
accomplishing those goals.
I do think it is reasonable to encourage maintainers to write man pages;
I do think well written man pages improve packages.
I understand maintainers have a lot on their plates, and I think it is
fine if  they don't spend the time improving packages in that way.

I do think a missing man page lintia tag is valuable, even at error
severity, although I would not stand in the way of consensus if others
disagree with me on this point.
I think overriding that tag is a fine way to mark that you are aware of
the missing man page and choose not to work on it now.


I cannot be part of a consensus that goes against the bulleted points I
have listed above.

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.

Maybe we need a tool dh_help2man that would automatically build man pages.
using ---help and the synopsis in debian/control.

Cheers,

Hello Jeremy,

It's very annoying when you install something and try to 'man foo' and
you don't get documentation.  I don't think that situation has got any
less annoying over the past twenty years.  It makes the system we are
producing less useful.

I don't think the fact that we have many open Lintian warnings about
this indicates a consensus that these manpages don't matter.  It just
indicates that there is always more work to be done than people able to
do it.

Packages being "Lintian clean" should not itself be a goal.
I think we should be doing a better job of letting new contributors know
that Lintian only make suggestions, and they can use their own
judgements about how to spend their time.

I think possibly we could weaken the requirement for GUI programs.
It's still annoying when they do have options and you want to know what
they are (or, you want to know that there aren't any options, so you
can't solve your problem that way) but it's less bad than for CLI
programs.  So maybe we could weaken the language down from 'should' for
GUI programs.

Hi!

I agree that man pages are extremely useful. Even for GUI
applications, which some times do not have complete --help output, or
not even any option showing a usage output at all, where they might
still support parsing some options. And where even if they have no support
at all for any CLI options, then I think it's still useful to document
briefly (say a tiny paragraph) what they do (more so if its name is very
cryptic), what environment variables they might honor, and what files
they might be using, such as configuration file locations or similar.

I think it's fine if maintainers do not have the time and/or motivation
to write these themselves, but I still find their omission to be a bug.

I'd like us to try to step away from help2man as part of our build
processes, because it does not play nice with cross-compilation, and
requires to build the tools twice (once for the build and once for the
host architectures), which complicates things substantially. I think
using this as an initial template is fine though, or perhaps as a rune
that the maintainer uses after each new upstream release and then
imports into the packaging. Ideally upstream would be convinced to
ship those though. :)

Thanks,
Guillem

I think apps already have .desktop files that provide that link.

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.

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.

Notably, Debian Policy does not use any words to describe what would
make a manpage great. Therefore, by Debian Policy, the showtime
manpage fully complies with Debian Policy, whereas gnome-clocks is in
violation.

I'm not sure that it's in Debian's scope to define what makes a
manpage good. I don't think it is needed in Debian Policy or even in
the Debian Developer Reference since those focus on packaging and the
problem of poor manpages is an upstream cross-distro issue. I guess
https://manpages.debian.org/man-pages might be the closest we have to
a standard for manpages.

Thank you,
Jeremy Bícha

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.

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.

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,

I will go as far as saying that of all package documentation we provide,
man pages are the most useful, because you can just do 'man somecommand'
and get something even if you have no idea what somecommand is supposed to
do.

On the other hand, we spend lot of time packaging doc in HTML or PDF format
that users never use. Instead they do random internet search and then complain
that the documentation they found on some website does not match the version of
the software in their Debian distribution. This is rather depressing both from
the Debian point of view and the upstream point of view.
I anticipate the problem is only going to become worse.

I do not know what we can do about it.

Cheers,

Hello,

I believe all these observations to be correct.