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

Removing the manpage requirement for GUI programs?


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

For extra points, we could agree on a way to generate manual pages
automatically, either at installation time or on the fly, using

Any comments before I submit a bug against the policy?

 .''`.      Josselin Mouette
: :' :
`. `'   “I recommend you to learn English in hope that you in
  `-     future understand things”  -- Jörg Schilling

Attachment: signature.asc
Description: Ceci est une partie de message =?ISO-8859-1?Q?num=E9riquement?= =?ISO-8859-1?Q?_sign=E9e?=

Reply to: