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

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette <joss@debian.org> writes:

> 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.

If the flags are properly documented with --help, isn't it usually fairly
trivial to generate a man page using help2man?

Running random programs with --help to try to get help is not appealing.
Some programs will proceed to do things if you run them even with options
like that, since they don't do option parsing.  It's also very nice to
have everything documented in one, shared system so that you can always
use the same command to get basic help for anything.

> 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.

If you do this, there's no need to drop the requirement that there be a
manual page, so no Policy change is required.

Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Reply to: