Removing the manpage requirement for GUI programs?

classic Classic list List threaded Threaded
74 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

Removing the manpage requirement for GUI programs?

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

signature.asc (197 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Russ Allbery-2
Josselin Mouette <[hidden email]> 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 ([hidden email])               <http://www.eyrie.org/~eagle/>


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/87sk8mxzh3.fsf@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

David Coe
In reply to this post by Josselin Mouette
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 <[hidden email]>
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
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Brian M. Carlson
In reply to this post by Josselin Mouette
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

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

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

signature.asc (197 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Removing the manpage requirement for GUI programs?

Fuentes, Adolfo
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 [[hidden email]]
Sent: 27 February 2010 20:03
To: [hidden email]
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 [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/DEBB97EA3EEF8E489B88CEFA9B3F36E255F22E6797@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Brian M. Carlson
In reply to this post by Josselin Mouette
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

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Frank Lin PIAT
In reply to this post by Russ Allbery-2
On Sat, 2010-02-27 at 11:14 -0800, Russ Allbery wrote:

> Josselin Mouette <[hidden email]> 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 [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/1267304202.7886.2868.camel@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

markus schnalke
In reply to this post by Josselin Mouette
[2010-02-27 20:06] Josselin Mouette <[hidden email]>
>
> 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 [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/1NlTwH-4mP-00@serveme

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Vincent Fourmond-4
markus schnalke wrote:
> [2010-02-27 20:06] Josselin Mouette <[hidden email]>
>> 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 [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/4B898F3C.9010600@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Thilo Six
In reply to this post by Josselin Mouette
Josselin Mouette wrote the following on 27.02.2010 21:03

-- <snip> --

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

I have just downloaded the lenny gcalctool_5.22.3-2_i386.deb.
Where in /usr/share/gnome/help/gcalctool do you read about the file
"~/.gcalctoolrc" as you can in man 1 gcalctool?

Being able to diagnose and understand a programm even with no running X
sometimes is vital for a systems health.

--
bye Thilo

4096R/0xC70B1A8F
721B 1BA0 095C 1ABA 3FC6  7C18 89A4 A2A0 C70B 1A8F


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/hmc7cp$8ie$1@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette
In reply to this post by Brian M. Carlson
Le samedi 27 février 2010 à 20:29 +0000, brian m. carlson a écrit :
> lakeview ok % gcalctool --help
> Usage:
>   gcalctool - Perform mathematical calculations

> 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.
This is where you are wrong. The manual page is incorrect and does not,
as you might think, describe all files gcalctool might access. Actually,
the .gcalctoolrc file that is described in the manual page is an ancient
artifact that has close to 0 use.

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

The information is in the HTML documentation. Are you going to duplicate
that information too, and introduce a new way for the documentation to
be out of sync?

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

And do you often read evince’s manual page?

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

Sorry but I think this would be a waste of time. There are real bugs to
fix instead of working on manual pages. First you would only repeat what
can be found in --help, since there’s nothing more to say about most GUI
programs. Then, once you would have written them, they’d need to be
forwarded, and more importantly you’d need to ensure at *every major
release* that they are still in sync.

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

signature.asc (197 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Removing the manpage requirement for GUI programs?

Josselin Mouette
In reply to this post by Fuentes, Adolfo
Le samedi 27 février 2010 à 20:14 +0000, Fuentes, Adolfo a écrit :
> 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?

Thank you for volunteering to write and maintain the tools to do that
automatically. Your help is much appreciated.

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

signature.asc (197 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Don Armstrong
In reply to this post by Josselin Mouette
On Sat, 27 Feb 2010, Josselin Mouette wrote:
> 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.

If the manpage doesn't contain any more information than the help
output, then it probably should be replaced with help2man so that it
stays up to date.

The crux of your argument is that for many GUI programs, manpages
aren't as essential as other forms of documentation, and developer
time would be better spent doing making other improvements.

Policy deals with this correctly by the manpage requirement as a
should requirement. It's a bug when the manpage doesn't exist, but
it's not RC. For some packages, it may not be a bug that can be
properly fixed due to developer-availability and upstream awareness.

I think you'd agree that manpages that were always up-to-date would be
nice for every thing in Debian would be nice, if only we had enough
time to make it all happen.


Don Armstrong

--
The smallest quantity of bread that can be sliced and toasted has yet
to be experimentally determined. In the quantum limit we must
necessarily encounter fundamental toast particles which the author
will unflinchingly designate here as "croutons".
 -- Cser, Jim. Nanotechnology and the Physical Limits of Toastability.
    AIR 1:3, June, 1995.

http://www.donarmstrong.com              http://rzlab.ucr.edu


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100227233049.GL28743@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette
Le samedi 27 février 2010 à 15:30 -0800, Don Armstrong a écrit :

> If the manpage doesn't contain any more information than the help
> output, then it probably should be replaced with help2man so that it
> stays up to date.
>
> The crux of your argument is that for many GUI programs, manpages
> aren't as essential as other forms of documentation, and developer
> time would be better spent doing making other improvements.
>
> Policy deals with this correctly by the manpage requirement as a
> should requirement. It's a bug when the manpage doesn't exist, but
> it's not RC. For some packages, it may not be a bug that can be
> properly fixed due to developer-availability and upstream awareness.
>
> I think you'd agree that manpages that were always up-to-date would be
> nice for every thing in Debian would be nice, if only we had enough
> time to make it all happen.
Yes, I overall agree with your arguments. However having it in the
policy means we get bug reports about manual pages and have to deal with
them, while they are not the primary source of documentation for
command-line options.

In my opinion, we’d be better off with no manual page than with one that
is not maintained correctly. However the current policy encourages
shipping a buggy manual page over not shipping it at all.

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

signature.asc (197 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Russ Allbery-2
Josselin Mouette <[hidden email]> writes:

> Yes, I overall agree with your arguments. However having it in the
> policy means we get bug reports about manual pages and have to deal with
> them, while they are not the primary source of documentation for
> command-line options.

> In my opinion, we’d be better off with no manual page than with one that
> is not maintained correctly. However the current policy encourages
> shipping a buggy manual page over not shipping it at all.

I think that's a bit of a reach.  That may be how some of your bug
reporters are interpreting Policy, but Policy doesn't say anything about
what bugs are more severe.  I don't think attributing that position to
Policy is entirely fair.

I agree with you that badly out-of-date man pages can be worse than no man
pages at all and it's a question of balancing two bugs, something that
package maintainers often have to do.

--
Russ Allbery ([hidden email])               <http://www.eyrie.org/~eagle/>


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/873a0mkzxo.fsf@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Don Armstrong
In reply to this post by Josselin Mouette
On Sun, 28 Feb 2010, Josselin Mouette wrote:
> However having it in the policy means we get bug reports about
> manual pages and have to deal with them, while they are not the
> primary source of documentation for command-line options.

I'd hope you'd still get bug reports even if it wasn't in policy.[1] I
know I've filed them for packages that I find have inadequate or
missing manpages when I actually go looking for the documentation.

> In my opinion, we’d be better off with no manual page than with one that
> is not maintained correctly. However the current policy encourages
> shipping a buggy manual page over not shipping it at all.

If the manpage is wrong, I think it'd be worse than not shipping one.
If it's merely incomplete, and references something that is complete,
that's better than nothing. At least you get a reference to where you
should be looking at.

What'd be ideal in these cases is to get the manpages present
upstream, and to integrate them more tightly into the upstream's
documentation, so that upstream updates them when they change command
line options.


Don Armstrong

1: If someone is filing bugs for packages which are missing manpages
when they've never actually wanted to look at the manpage, that's
pathetic. Sure, it may be a bug, but why file a bug when you'll never
notice if it's fixed?
--
I may not have gone where I intended to go, but I think I have ended
up where I needed to be.
 -- Douglas Adams _The Long Dark Tea-Time of the Soul_

http://www.donarmstrong.com              http://rzlab.ucr.edu


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/20100227235258.GM28743@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Ben Finney-5
In reply to this post by Brian M. Carlson
"brian m. carlson" <[hidden email]> writes:

> 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.
Agreed, this is very useful information for any program regardless of
its UI.

The argument about upstream failing to maintain manpages is not specific
to GUI programs (there are plenty of text-based programs whose upstream
developers don't care about a manpage), so even if this requirement were
to be relaxed I don't see what's special about the GUI aspect.

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

Exactly. The purposes of ‘foo --help’ are quite different from ‘man 1
foo’, and having one does not obviate the need or usefulness of the
other.

--
 \     “Wrinkles should merely indicate where smiles have been.” —Mark |
  `\                                    Twain, _Following the Equator_ |
_o__)                                                                  |
Ben Finney

attachment0 (203 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Javier Barroso-3
In reply to this post by Josselin Mouette
2010/2/27 Josselin Mouette <[hidden email]>:

> 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?
As debian user, I really hate when I find a command which I don't know
what is and doesn't have man page. I think this happens to me in other
distributions more than in debian.

I think, at least a description should be provided. Obviously there
are GUI programs which their names give you clues about them, but
others, like "baobab" not. Imagine programs like baobab without any
manpage, It is hard to launch a program if you don't know about what
it's going to do. It is safe to launch any program if you can read
about it before.

Thank you very much


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: http://lists.debian.org/81c921f31002271615j8a1ba1ficcf47c2c8f1b3c6f@...

Reply | Threaded
Open this post in threaded view
|

Re: Removing the manpage requirement for GUI programs?

Ben Finney-5
In reply to this post by Josselin Mouette
Josselin Mouette <[hidden email]> writes:

> Yes, I overall agree with your arguments. However having it in the
> policy means we get bug reports about manual pages and have to deal
> with them, while they are not the primary source of documentation for
> command-line options.

If manpages were useful only for documenting command-line options, this
would be a valid point. As has been pointed out, though, manpages for
programs are useful for much more than that.

> In my opinion, we’d be better off with no manual page than with one
> that is not maintained correctly. However the current policy
> encourages shipping a buggy manual page over not shipping it at all.

This is a problem, yes, I hadn't thought about it that way. Thank you.

So is it feasible to instead come up with a phrasing that encourages
full up-to-date manpages, but doesn't encourage keeping out-of-date
manpages?

--
 \      “Software patents provide one more means of controlling access |
  `\      to information. They are the tool of choice for the internet |
_o__)                                     highwayman.” —Anthony Taylor |
Ben Finney

attachment0 (203 bytes) Download Attachment
1234