Source: debian-policy Version: 4.7.0.2 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
