[getopt-sig] Documentation, functionality, options, syncing
Wed, 20 Feb 2002 09:58:03 +0100 (CET)
Yesterday I read the mailing list archive, and did some thinking.
Having documentation automagically generated seems to be a hot topic, so let's
start with that one.
- I believe that it is not possible to get really good quality documentation
from a number of one-liners that are part of an option. Especially, when
talking about man-page size (or bigger).
We should extend pydoc for such stuff.
Even with lesser size, I'd like to be in control of the order in which
help-text for options are printed (to allow grouping of similar options in
the help), and have proper line-break routines for instance.
- I also believe that it is a mistake to learn new Pythonists that writing a
one-liner for an option is documentation.
I'd rather have no documentation (so it is glaring obvious there is none) than
to have a one-liner that means nothing to anyone except the author.
- Please don't abuse pydoc strings for anything else than documentation of the
implementation. Your option-objects/functions/etc may be easy enough for you
not to write pydoc strings, but please don't make that decision for the rest
of the world too.
- The argument of having to keep documentation and options in sync did not
convince me that having help as part of the option, and having an option
parser having to deal with help-output is good.
On the other hand, I can understand the concern of keeping everything in
sync. There fore, I'd like to propose two different approaches to the matter.
Quite likely, others (with more experience in this field of keeping stuff in
sync) can improve and/or propose entirely new approaches.
* The first approach is to create the help text, while adding options to the
parser, i.e. something like
helptext.append('-h get this helptext')
* The first approach does not solve the problem if (like me) you want to be
more in control. That could possibly be solved with checking afterwards:
print "helptext how to use the program using -h, -x, and -t"
i.e. I query the parser whether it understands -h, -x and -t. If it does
not, or it has other options not mentioned here, it should protest.
* Less strict checking is also possible:
print "help text about -h"
print "help text about -x"
this also queries the parser, and uses its output to generate help. At the
same time, it leaves the author in full control of how to generate the
(e.g. one could load help from a file, and have multi-lingual help).
Constructing a computer program is like writing a painting