Re: Bug#39463,#39482,#39493: timidity, cdrdao, cdtool has no manpage for something

[Jim Lynch <jim@laney.edu>]

> 
> Date:    Tue, 15 Jun 1999 11:54:58 +0200
> To:      Roland Rosenfeld <roland@debian.org>
> cc:      Martin Mitchell <martin@debian.org>,
> 	 Debian Policy List <debian-policy@lists.debian.org>
> From:    Santiago Vila <sanvila@unex.es>
> Subject: Re: Bug#39463,#39482,#39493: timidity, cdrdao, cdtool has no manpage f
>      ***or something
> 
> On Mon, 14 Jun 1999, Roland Rosenfeld wrote:
> 
> > | 6.1. Manual pages
> > | -----------------
> > |
> > |     You must install manual pages in `nroff' source form, in appropriate
> > |     places under `/usr/man'. You should only use sections 1 to 9 (see the
> > |     FSSTND for more details). You must _not_ install a preformatted `cat
> > |     page'.
> > |
> > |     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
> >                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> I think this is a stupid policy and should be changed.

My initial gut reaction is to come right out and say "You have GOT to be
kidding, right??"

However, I will suspend my utter disbelief and ask that you provide a unified
diff showing current policy versus your changes. I feel this is the only
possible response that is sensible, because in my opinion, the whole of the
debian project needs enough documentation to reproduce itself in its entirety. 

Should it come to pass that you provide this diff, I will resubscribe to -devel
and post all these messages, because such a fundamental change brewing needs
to be brought to all developers who are listening. I might do so anyway unless
you drop this.

Specifically, if man pages are not required, HOW do you propose that a user
(possibly new) make any sense at all of a binary if it is not documented??

In other news, not only do I think man pages ought to be manditory per bin,
but I am getting really tired of going "well gee, I just installed this 
package, now WHERE the *&^&% are all the files??" 

Yes, I know you can dpkg -whatever package to find it. Still, I think that 
each package should maybe have a manifest installed as documentation, either
as a file in /usr/doc/package/MANIFEST, in each man page, or howbout this:
BOTH. This includes: files the package installed, and to a limited degree,
files it's possible for the package to create. (obviously, to try this for
fileutils' cat in its "cat > whatever" form would be a lot of work...)

When someone says RTFM to someone else, I think there should be a good
FM to R! And lack thereof is a Bug... 

-Jim