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

Re: Removing the manpage requirement for GUI programs?

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

Attachment: signature.asc
Description: Digital signature

Reply to: