On Fri, Mar 05, 2010 at 04:09:05PM +0800, Paul Wise wrote: > 2010/2/28 Josselin Mouette <joss@debian.org>: > > > currently policy §12.1 mandates that “each program, utility, and > > function should have an associated manual page”. However, the more I > > stomp on bug reports about manual pages, the less I am convinced of > > their usefulness for GUI programs. > > How about replacing "an associated manual page" with "associated > documentation"? Also add a sentence or two saying that said > documentation may be in any format(s) (manual pages suggested) > viewable in Debian and should be well maintained. This still has the problem that I don't know immediately where to get the documentation. Do I use the GNOME help system? KDE's? man? info? a DVI? a PDF? The benefit of manual pages is that there is one uniform way to get basic documentation on a command and how it is to be run. Other documentation can be referenced from that manual page. Allowing "any format viewable in Debian" potentially requires the average user to install lots of random packages just to view basic documentation on invoking a program. Also, providing, for example, PDF documentation as the sole form for a command line program is not particularly useful for a machine that doesn't have X installed. Note that I'm not suggesting that other documentation shouldn't be provided; it should, and all Debian programs should be documented sufficiently. I'm just arguing that allowing using any random format isn't helpful, since it has the same problem as no manual page at all: how do I find out basic information about this program and how to invoke it? Also, IIRC, man-db is installed by default as part of the system. That means that a package that provides a manual page is easily usable out of the box on any Debian system. -- brian m. carlson / brian with sandals: Houston, Texas, US +1 713 440 7475 | http://crustytoothpaste.ath.cx/~bmc | My opinion only OpenPGP: RSA v4 4096b 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
Attachment:
signature.asc
Description: Digital signature