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

[Greg Ward]

[me, on line-wrapping in Optik's help output]
> Note that lines are nicely wrapped to 80 columns.  (Actually it's 78,
> and yes it is hard-coded -- despite getting some useful answers on
> c.l.py, I haven't gotten around to actually coding any of the 14
> different ways to find out how big the terminal is.)  (You can see the
 
[Albert]
> Shouldn't that be part of the line-wrapping library ?

What line-wrapping library?  Currently all there is is the wrap_text()
function buried in the distutils.fancy_getopt module.  This probably
should be moved to somewhere more visible in the standard library, but I
haven't dealt with that yet.


> Ok, what about a multi-lingual program ?  I don't have much experience
> in this area, but I can imagine that the help of an option should be
> available in multiple languages. All text in the program is collected
> in 1 file for each language, and I have a unique key that finds the
> text when I want to output a message.  Can I store the key as help
> text in the option ?

Nobody said that help text has to be a static string.

   parser.add_option("-f", "--file",
                     help=lookup_text("OPT_HELP_FILE"))

Or if you prefer implicit over explicit:

   parser.add_option("-f", "--file",
                     help=_("Read input from FILE"))

(I believe this is how Mailman does I18N: the _() function uses one
language -- presumably English -- as the key, and looks up the same
message in a different language.)

If you want to get a bit fancier:

   parser.add_option("-f", "--file",
                     metavar=_("FILE"),
                     help=_("Read %s" % _("FILE")))

so your help output might read either
  -fFILE, --file=FILE        Read FILE
or
  -fFICHIER, --file=FICHIER  Lire FICHIER
(Sorry, English and French are all I know.)

But this is purely guesswork.  I know very little about I18N.
                       
> Another case is that I have written a frontend program that handles
> several different types of files. The help text of the program does
> not only print the options, but also the types of files it
> understands, with a description of what it does with each type as a
> seperate piece of text. How does that fit in your integrated help ?

Again, nobody said help text has to be static.

> I think the problem is not that it may not be useful to organize help
> text like you do, but that it is an all-or-nothing option. If I want
> to use it, I need the help to fit in the format/layout you
> designed. That may work tody, but what about tomorrow ?  If I don't
> want to use the help texts, I must start from scratch, which is a
> waste of time, since I probably could use some of the functionality.

Certainly Optik's help-formatting code needs to be split up into
multiple methods to make it more customizable and extensible.  Possibly
it needs to be factored out into a separate class.  But it's hard to do
that without real-life examples of how help formatting needs to be
customized or extended.

        Greg
-- 
Greg Ward - geek-at-large                               gward@python.net
http://starship.python.net/~gward/
Know thyself.  If you need help, call the CIA.