[getopt-sig] Documentation, functionality, options, syncing

[A.T. Hofkamp]

Hello,

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

    parser.AddOption('-h')
    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:

    def usage():
       print "helptext how to use the program using -h, -x, and -t"
       parser.checkOptions(['-h','-x','-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:

    def usage():
       if parser.hasOption('-h'):
          print "help text about -h"
       if parser.hasOption('-x'):
          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
    documentation.
    (e.g. one could load help from a file, and have multi-lingual help).


Albert
-- 
Constructing a computer program is like writing a painting