Bug#39830: debian-policy: [PROPOSED]: get rid of undocumented(7) symlinks
Package: debian-policy
Version: 2.5.1.0
Severity: wishlist
I propose the following change to chapter "6.1 Manual pages":
----------------------- schnipp --------------------------------
--- policy.sgml Tue Apr 27 18:14:00 1999
+++ policy.sgml Mon Jun 21 01:17:54 1999
@@ -2868,20 +2868,14 @@
page'.</p>
<p>
- If no manual page is available for a particular program,
- utility or function and this is reported as a bug on
- debian-bugs, a symbolic link from the requested manual page
- to the <manref name="undocumented" section="7"> manual page
- should be provided. This symbolic link can be created from
- <tt>debian/rules</tt> like this:
- <example>
- ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
- </example>
- This manpage claims that the lack of a manpage has been
- reported as a bug, so you may only do this if it really has
- (you can report it yourself, if you like). Do not close the
- bug report until a proper manpage is available.</p>
+ There must be a manual page at least for every program. If
+ no manual page is available, this is considered as a bug and
+ should be reported to the bug tracking system. Do not close
+ the bug report until a proper manpage is available. To
+ avoid duplicate bug reports about missing manual pages, you
+ should inform the user that you know about the missing
+ manual page in
+ <tt>/usr/doc/<var>package</var>/TODO.Debian</tt>.</p>
<p>
You may forward a complaint about a missing manpage to the
----------------------- schnipp --------------------------------
Background:
===========
Christoph Lameter <christoph@lameter.com> described the problem of the
undocumented(7) symlinks in debian-policy:
> The symlink causes a stupid manpage to show up saying that there is no
> manpage. I would prefer if man would simply say there is no manpage.
>
> The fact that there is already a bug filed is evident from the BTS. Why
> put a symlink to undocumented into the package?
>
> Sometimes I check for documentation by doing a dpkg -L. I see a manpage
> for a certain command and do a "man xxx". Result is a "undocumented"
> manpage. Very irritating. It would have saved some effort if there simply
> were no manpage.
I hope, that my changes fix this problem and clarify the question
whether a missing man page is considered as a bug.
Ciao
Roland
Reply to: