Re: Long help lines and wrapping

David Goodger wrote:
> 
> Bob van der Poel wrote:
> > I'm trying to use the Optik package for parsing command line options.
> > However, I'm running into a problem overriding its line warping routines.
> 
> I trust you meant "wrapping", not "warping" :)

Yes. Obviously typing is not my specialty.

> > I'd like the help to print something like:
> >
> >       options:
> >         -p, --pattern   Set pattern. Available patterns are:
> >                 'xx'  use the xx pattern
> >                 'yy'  use the yy pattern
> >                 ... more list of pattern options
> >         -z, --zzzz  The Z option
> >         ... etc, etc
> 
> I have also had cases like this in the past, pre-Optik.  I think it would be
> a useful addition.
> 
> > Seems that optik thinks it knows better where the new lines should go.
> 
> Please don't be snide; all that does is invite people to ignore your
> message.

Opps, no snidness intended. I quite like optik and think it is a
valuable addition to the python suite. Sorry if my feeble attempt
at lightness/humour was misinterpreted.
 
> Optik doesn't "think" anything.  It simply doesn't support complex help
> text.  It supports single, wrappable paragraphs only.  Support for anything
> more complex would have to be implemented, but hasn't been yet.
> 
> I don't think special inline syntax is the best way to go.  That would be a
> quick & dirty fix that would only complicate matters for the general case
> and for any future additions.
> 
> Currently, Optik "Option" classes contain a "help" attribute, which is a
> string, None, or a special string constant "SUPPRESS"+"HELP".  After
> thinking it over a bit, I came up with the following implementation plan:
> 
> * Add a new "optik.help.Paragraph" class and subclasses.  Expose them
>   in optik/__init__.py for easy import and future stdlib integration.
>   Each class would define its own inter-object spacing and formatting
>   behavior.
> 
> * Change the "optik.Option.help" attribute to contain a list of these
>   objects.  Help objects would be restricted to a flat list structure.
> 
> * The "help" parameter of the "optik.Option" constructor would accept
>   single strings (as now), and would convert them to Paragraph objects.
>   It would also accept a list of Paragraph & subclass objects, to allow
>   for complex help messages.
> 
> * Modify "optik.help.HelpFormatter.format_option" to handle these
>   objects.  The "format_option" method would handle inter-paragraph
>   spacing.
> 
> * The basic Paragraph class would require blank lines between objects.
>   The "format" method would simply call "textwrap.wrap" on its data.
> 
> * A ListItem subclass would wrap its data, prepend a bullet ("*"),
>   but wouldn't require blank lines between objects (of the same class).
>   The data would be wrapped and further indented on second and
>   subsequent lines (like this text).
> 
> * A Literal subclass would also require blank lines between objects,
>   but would only indent its data; no line wrapping.  This would allow
>   arbitrary help text, unaffected by the Optik code.
> 
> So to get the help message wanted, you'd need code like this::
> 
>     from optik import OptionParser, Paragraph, ListItem
> 
>     parser = OptionParser()
>     parser.add_option("-p", "--pattern", metavar="<PATTERN>",
>         choices=('xx', 'yy'), help=[
>             Paragraph('Set pattern. Available patterns are:'),
>             ListItem('"xx": use the xx pattern'),
>             ListItem('"yy": use the yy pattern (long explanation here)')])
>     ...
> 
> Running the script with the "--help" option would result in an option list
> like this::
> 
>     options:
>       -h, --help           show this help message and exit
>       -p<PATTERN>, --pattern=<PATTERN>
>                            Set pattern. Available patterns are:
> 
>                            * "xx": use the xx pattern
>                            * "yy": use the yy pattern (long
>                              explanation here)
> 
>       -z, --zzzz           The Z option
> 
> The blank lines could be removed if you're more concerned about vertical
> real estate than readability.  I think vertical spacing should be
> customizable so that "optik.help.TitledHelpFormatter" remains compatible
> with reStructuredText.
> 
> If done properly, this could be a transparent, backwards-compatible addition
> to Optik with room for future growth.  A quick-fix should not be attempted.
> I am not volunteering to do the implementation at this time, but I'll be
> glad to help.  He whose itch is strongest should be the first to scratch.

Okay. This seems to be quite complete. But, I'm wondering if all this is
needed? After getting your message I did a bit of reading the source for
optik and wonder if this solution would be easier, and maybe even just
as useful???

Replace the wrap_text() function called in format_option() with a
routine specific to optik. This would follow the rules in the existing
wrap_text() with the following addition: if a \n is found in the text to
be wrapped, the text will be wrapped at this point. In addition, any
white space following the \n will be preserved.

If this was to work I could then set up my option like:

        parser.add_option("-p", "--pattern", type="string",
           action="store", dest="pattern", 
           help="Set Pattern. Available patterns are:\n" +
                "   xx use the xx pattern\n" +
                "   yy use the yy pattern") 

or even:

	help="""Set Pattern. Available patterns are:
   xx use the xx pattern\n" +
   yy use the yy pattern"""

Comments to this solution would be appreciated.

Just thinking a bit about this myself, I see a pro and a con.

Con: If existing code with '\n's already in the help strings used the
new routine, it might break. However, I don't see this being a big
issue? I may be wrong...

Pro: Setting up help strings in this manner, esp. with """ strings,
seems to be quite intutitive.

Question: If I were to impliment this by adding a new wrap_text() is
there a way this could be done without hacking into the optik code? I
see that wrap_text() is currently imported from distutils.fancy_getopt,
so I suppose that the answer is no. At the least, I'd have to take the
import line out of the code. Or is there a way to override this? I'm
thinking that it would be nice to use the existing package with a
different wrap function overlaid. If nothing else, this would simplify
testing.

Thanks.


-- 
Bob van der Poel ** Wynndel, British Columbia, CANADA **
EMAIL: [email protected]
WWW:   http://www.kootenay.com/~bvdpoel



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf