Re: pre-proposal: get rid of undocumented(7)
On Jun 15, Chris Waters wrote:
> How about this as an idea: if you have no man page, you have to put a
> file in /usr/doc/<package>/no-man-page that describes the situation,
> briefly. Something along the lines of "I'm working on it", or "I'm
> not working on it because I don't know roff", or "I'm not working on
> it because the program is evolving too rapidly for me to track", or
> "upstream promised one next release", or whatever seems appropriate.
> Unlike undocumented(7), this could actually be somewhat useful, as it
> would let the users know exactly what the situation is.
I'm not firmly convinced that writing a man page for 99% of things is
so hard as we make it out to be (hell, dh_make gives you a template
for free). My suggestion would be to require any executable to have a
man page, which at a minimum must be specific to the executable. See
the approach taken by the ntp package for example...
NTP(1) NTP(1)
NTP
ntp - the network time protocol
DESCRIPTION
The NTP distribution does not include man pages, but it
does include a thorough manual in HTML. To help Debian
users manage disk space, this documentation is packaged
separately from the executables.
To learn more about the NTP protocol and this software,
please install the ntp-doc package and then look in
/usr/doc/ntp-doc where you will find an html documentation
tree.
AUTHOR
This manual page was written by Bdale Garbee
<bdale@gag.com> for the Debian GNU/Linux system (but may
be used by others).
Then, users can file wishlist bugs if the man page is incomplete or
otherwise deficient (i.e. does not document the command line options).
I don't expect the equivalent of "man X" for every command (IMHO "man
X" is overkill anyway), but I at least expect the command line options
to be documented there (and it's reasonable to have a wishlist bug for
that sort of thing).
Chris
--
=============================================================================
| Chris Lawrence | Get your Debian 2.1 CD-ROMs |
| <quango@watervalley.net> | http://www.lordsutch.com/ |
| | |
| Grad Student, Pol. Sci. | Are you tired of politics as usual? |
| University of Mississippi | http://www.lp.org/ |
=============================================================================
Reply to: