2010/2/27 Josselin Mouette
<joss@debian.org>
Hi,
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.
GUI applications usually take only a few simple command-line options,
and more importantly, when you use a modern development framework, these
options will always be documented correctly with the --help switch.
Manual pages, OTOH, are not maintained properly by upstream developers.
I think it is a waste of time to write manual pages that won’t be
maintained upstream, and that won’t contain more useful information than
--help. The purpose of a manual page is to document precisely the
behavior of a program, and for GUI applications there is usually an
associated GUI documentation instead.
Therefore I propose that we drop the requirement of a manual page if
these conditions are met:
* the program requires graphical interaction with the user, and is
not meant to be used from a script;
* the command-line switches are properly documented with a --help
option.
For extra points, we could agree on a way to generate manual pages
automatically, either at installation time or on the fly, using
help2man.
Any comments before I submit a bug against the policy?
Cheers,
--
.''`. Josselin Mouette
: :' :
`. `' “I recommend you to learn English in hope that you in
`- future understand things” -- Jörg Schilling