[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#39830: AMENDMENT]: get rid of undocumented(7) symlinks



severity 39830 normal
retitle 39830 [AMENDMENT 28/10/1999] get rid of undocumented(7) symlinks
thanks

I proposed to change the "Manual pages" section of our policy to get
rid of the undocumented(7) symlinks.

This proposal was seconded by Chris Waters <xtifr@dsp.net> and Chris
Lawrence <quango@watervalley.net>, so I change the status to
"amendment" now.

Here's a new version of my proposal, where I merged in the ideas which
were introduced in the discussion:

-------------------------- schnipp -----------------------------------
--- policy-3.0.1.1.sgml	Wed Oct 27 13:52:33 1999
+++ policy.sgml	Thu Oct 28 16:13:29 1999
@@ -3025,21 +3025,21 @@
 	  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/share/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 (the
+	  maintainer of the package is allowed to do write this bug
+	  report himself, too).  Do not close the bug report until a
+	  proper manpage is available<footnote>It is not very hard to
+	  write a man page, see the <url
+	  id="http://www.schweikhardt.net/man_page_howto.html";
+	  name="Man-Page-HOWTO">, <tt>man(7)</tt>, or the examples
+	  created by <tt>debmake</tt> or <tt>dh_make</tt></footnote>.
+	  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/share/doc/<var>package</var>/TODO.Debian</tt>.</p>
+
 	<p>
 	  You may forward a complaint about a missing manpage to the
 	  upstream authors, and mark the bug as forwarded in 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.

Ciao

        Roland

-- 
 * roland@spinnaker.de * http://www.spinnaker.de/ *


Reply to: