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

Re: Removing the manpage requirement for GUI programs?

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

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

Reply to: