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
Attachment:
signature.asc
Description: Digital signature