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

Re: Removing the manpage requirement for GUI programs?

Keep in mind that the apropos command only searches man pages, so I strongly
support keeping them around and creating them (even if only from --help) when
they're missing.

2010/2/27 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.

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

David Coe
+1 410 489 9521

Reply to: