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

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


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 87sk8mxzh3.fsf@windlord.stanford.edu">http://lists.debian.org/87sk8mxzh3.fsf@windlord.stanford.edu

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>


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



--
David Coe
+1 410 489 9521

On Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette wrote:
> 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.

A manual page contains more information than just command line switches.
For example, iceweasel's manpage contains information about environment
variables and files that it uses. This is almost never found in --help
output. Also, in order for this requirement to be acceptable, every
binary in Debian that does not have a manpage must, upon first upload,
have a working --help output. Otherwise, as Russ pointed out, we have
no way of knowing whether the program supports --help. If it has no
manpage, it could be buggy and need a manpage, or it could be buggy and
need --help, but there's no way to know.

Also, if I'm looking through /usr/games for new ways to waste time, how
am I supposed to immediately intuit whether this program is GUI or not?
With a manual page, I can learn about the program and determine whether
it's a game I want to play at all.

Additionally, in some cases, the --help output is not sufficient to
explain what a program does. "gcc-4.4 --help" does not list all the
options; one has to use "gcc-4.4 -v --help". Also, using only the
latter, please tell me what the "-dM" argument does when passed to
gcc-4.4.

Although this example is not a GUI program, it is a great example of why
--help output is often not sufficient. In my opinion, your proposed
change to policy will not result in the elimination of many manpages,
because in most cases, the programs will be inadequately documented by
the --help output. --help output is for the case where you already are
intimately familiar with the program and what it does, and need a quick
reminder, or for cases when manpages are not available (emergency
single-user boot).

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

Le samedi 27 février 2010 Ã* 19:49 +0000, brian m. carlson a écrit :
> Additionally, in some cases, the --help output is not sufficient to
> explain what a program does. "gcc-4.4 --help" does not list all the
> options; one has to use "gcc-4.4 -v --help". Also, using only the
> latter, please tell me what the "-dM" argument does when passed to
> gcc-4.4.
>
> Although this example is not a GUI program, it is a great example of why
> --help output is often not sufficient.

Indeed it is not sufficient for gcc-4.4. But I still think it is
sufficient for gcalctool.

> In my opinion, your proposed
> change to policy will not result in the elimination of many manpages,
> because in most cases, the programs will be inadequately documented by
> the --help output. --help output is for the case where you already are
> intimately familiar with the program and what it does, and need a quick
> reminder, or for cases when manpages are not available (emergency
> single-user boot).

We are talking of programs that you will not have the idea to run with
the command line unless you know what they do. Programs that are usually
run through a graphical menu.

The current situation is that there are a lot of outdated and/or
inaccurate manpages, while the --help output contains the same amount of
information and is guaranteed to be up-to-date.

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

I think it is a good idea to have a centralized system where one can find information about a particular program. Otherwise we take the risk of having a sparse information system. If help2man helps to create the man page from the program help, which is the burden then?

---
Department of Chemistry -- Surface Science Research Centre
University of Liverpool
Crown Street
Liverpool, L69 7ZD
United Kingdom

"Treat the Earth well. It was not given to you by your parents, it was loaned to you by your children." (Ancient native American Indian proverb)
________________________________________
From: Josselin Mouette [joss@debian.org]
Sent: 27 February 2010 20:03
To: debian-devel@lists.debian.org
Subject: Re: Removing the manpage requirement for GUI programs?

Le samedi 27 février 2010 Ã* 19:49 +0000, brian m. carlson a écrit :
> Additionally, in some cases, the --help output is not sufficient to
> explain what a program does. "gcc-4.4 --help" does not list all the
> options; one has to use "gcc-4.4 -v --help". Also, using only the
> latter, please tell me what the "-dM" argument does when passed to
> gcc-4.4.
>
> Although this example is not a GUI program, it is a great example of why
> --help output is often not sufficient.

Indeed it is not sufficient for gcc-4.4. But I still think it is
sufficient for gcalctool.

> In my opinion, your proposed
> change to policy will not result in the elimination of many manpages,
> because in most cases, the programs will be inadequately documented by
> the --help output. --help output is for the case where you already are
> intimately familiar with the program and what it does, and need a quick
> reminder, or for cases when manpages are not available (emergency
> single-user boot).

We are talking of programs that you will not have the idea to run with
the command line unless you know what they do. Programs that are usually
run through a graphical menu.

The current situation is that there are a lot of outdated and/or
inaccurate manpages, while the --help output contains the same amount of
information and is guaranteed to be up-to-date.

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


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: DEBB97EA3EEF8E489B88CEFA9B3F36E255F22E6797@STAFFMB X2.livad.liv.ac.uk">http://lists.debian.org/DEBB97EA3EEF8E489B88CEFA9B3F36E255F22E6797@STAFFMB X2.livad.liv.ac.uk

On Sat, Feb 27, 2010 at 09:03:04PM +0100, Josselin Mouette wrote:
> Le samedi 27 février 2010 à 19:49 +0000, brian m. carlson a écrit :
> > Additionally, in some cases, the --help output is not sufficient to
> > explain what a program does. "gcc-4.4 --help" does not list all the
> > options; one has to use "gcc-4.4 -v --help". Also, using only the
> > latter, please tell me what the "-dM" argument does when passed to
> > gcc-4.4.
> >
> > Although this example is not a GUI program, it is a great example of why
> > --help output is often not sufficient.
>
> Indeed it is not sufficient for gcc-4.4. But I still think it is
> sufficient for gcalctool.

lakeview ok % gcalctool --help
Usage:
gcalctool - Perform mathematical calculations

Help Options:
-v, --version Show release version
-h, -?, --help Show help options
--help-all Show all help options
--help-gtk Show GTK+ options

Application Options:
-u, --unittest Perform unittests
-s, --solve <equation> Solve the given equation


Tell me what user files gcalctool may access, using only this
information. Also tell me, using *only the information provided*, how
to force GTK+ to make all X calls synchronous. You can't, because that
information is not provided in the --help output.

In the latter case, --help-all might be useful, but the output is not
sufficient, and so the package would, according to your proposed
standard, need a manpage, or to be patched to make --help work like
--help-all. In the former case, the information is not provided at all,
except in the manpage.

Furthermore, gcalctool can be scripted with -s, and the --help output
does not describe the syntax: is it infix? postfix? How do you express
powers? Must powers be integers? What precision is available? The
manpage does not either, but that is a bug in the manpage. That
information should not be present in the --help output. It is entirely
too long.

> We are talking of programs that you will not have the idea to run with
> the command line unless you know what they do. Programs that are usually
> run through a graphical menu.

Maybe I'm the exception, but I end up running a lot of graphical
programs from the command line. When I'm building PDFs, I generally run
evince from the command line. I often use wireshark from the command
line. And those are just two from the top of my head.

> The current situation is that there are a lot of outdated and/or
> inaccurate manpages, while the --help output contains the same amount of
> information and is guaranteed to be up-to-date.

I understand that. I don't feel that this is the right way to go about
it, though. As others have pointed out, apropos doesn't work without a
manpage. And the --help output is woefully insufficient for a large
number of programs, including those with remotely subtle arguments.

I'm happy to write or update manual pages, if needed. If you provide a
list of those that need work, I'll start working on them, so don't think
I'm just a naysayer that wants to push off work on others.

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

On Sat, 2010-02-27 at 11:14 -0800, Russ Allbery wrote:
> 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.

manpages can prove to be useful in many situation and they have a few
nice features:
1. "man" offer a consistent API. (as opposed to -h/--help/-help/--usage/
--help-foo, --help-bar, etc).
2. whatis foo
3. apropos bar
4. reading the manpage doesn't require to execute the program
- it's safe to be run as root
- it's doesn't create dummy .foo files
- it never spawns any background process

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

And if it isn't trivial, it probably isn't trivial for humans either.

Franklin


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 1267304202.7886.2868.camel@solid.paris.klabs.be">h ttp://lists.debian.org/1267304202.7886.2868.camel@solid.paris.klabs.be

[2010-02-27 20:06] Josselin Mouette <joss@debian.org>
>
> 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.

Man pages have one more important advantage: Every command has one.

Do not underestimate this. On Debian systems, people know, if they
want to find out how to run a command and what command line options it
has, they look in its man page, cause every command has one.

If some graphical programs would not provide one, the the user would
first try to look in the man page and if it does not exist, he needs
to try --help (maybe he even needs to look for additional
documentation which would be application specific).

In my eyes, the largest advantage of man pages is that every command
has one.


meillo


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 1NlTwH-4mP-00@serveme">http://lists.debian.org/1NlTwH-4mP-00@serveme

markus schnalke wrote:
> [2010-02-27 20:06] Josselin Mouette <joss@debian.org>
>> 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.
>
> Man pages have one more important advantage: Every command has one.

Count me in for that argument too.

I personally heavily rely on man (and I'm so glad the imagemagick
command-line options are back into their manual page). I think it would
be a loss to not have one for each command.

Cheers,

Vincent


--
Vincent Fourmond, Debian Developer
http://vince-debian.blogspot.com/

It was funny how people were people everywhere you went, even if the
people concerned weren't the people the people who made up the phrase
``people are people everywhere' had traditionally thought of as people.
-- Terry Pratchet, The Fifth Elephant

Vincent, not listening to anything for now


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4B898F3C.9010600@debian.org">http://lists.debian.org/4B898F3C.9010600@debian.org