RE: formatting paragraphs in descriptions

Greg,

> 
> On 23 May 2003, Wannheden, Knut said:
> > - At first I couldn't find the command description option for the
> > OptionParser, as it isn't used anywhere in the basic and 
> advanced guides.
> 
> Huh?  I don't understand what you're talking about -- could 
> you be more
> specific?
> 

I'm talking about the "description" keyword argument that can be passed to
the OptionParser constructor.  It just isn't mentioned in either the basic
(http://optik.sourceforge.net/basic.html) or advanced guide
(http://optik.sourceforge.net/advanced.html).

I think it would be nice if these guides would briefly mention what it is
for and how it shows up in the generated help text.

> > - Optik doesn't provide any mechanisms to parse the 
> positional arguments.  I
> > know this has discussed before and I've read the threads.  
> Maybe this could
> > be introduced incrementally.  To start with I think it 
> would be nice if
> > Optik could check that the number of positional arguments 
> is correct.
> > Currently I do this right after the parse and call 
> OptionParser#error(msg)
> > if it is incorrect.
> 
> That's gotta be the #1 most requested feature.  OK, OK, I'll do
> something about it, but not until *after* Optik 1.4.2 and 
> Python 2.3 are
> released.
> 

Great! ;-)

> > - The OptionParser#error(msg) function uses the 
> get_prog_name() function to
> > determine the program name to prepend the message with.  It 
> would be nice if
> > this could be set somehow.  I'd like this because I use subcommands.
> 
> Already fixed in CVS; will be in Optik 1.4.2 (and Python 2.3final
> hopefully!).
> 

Cool!  So now I can use the "prog" keyword argument for %prog in usage and
version strings.

This turns out to be really useful as I'm implementing a simple
command/subcommand framework on top of optik.  If you're interested I can
post my results once I have something useful.

> > Further I noticed that the HelpFormatter uses the textwrap 
> module to format
> > the help messages.  textwrap is documented to work with individual
> > paragraphs.  I think it would be nice if the default 
> HelpFormatter could
> > identify paragraphs in the command description and format 
> these individually
> > and preserve the paragraphs.
> 
> Your command description is probably too long.  Write a man page.  ;-)
> 

Yes, maybe you're right.  Unfortunately man pages, unlike optik's --help
option, are not portable :-)  And I do want Windows users to be able to read
the description.  So I'm using my custom HelpFormatter to preserve
paragraphs.

> > Also a newline between the description and
> > option help would be nice.  For this purpose I implemented my own
> > HelpFormatter which preserves any \n\n sequences in the 
> description and adds
> > a newline to the end to the description.  What do you think 
> about this?  If
> > you like I could send you my code that does this, but it's 
> really trivial
> > :-)  Almost forgot, my HelpFormatter does one more thing: 
> It sets the
> > default width to 79 characters, as I in Windows command 
> prompts can end up
> > with an empty line inside the paragraph.
> 
> Hmm, default width should be slightly < 80... but it isn't!  I never
> noticed that before.  I'll set it to 78 just because I don't like odd
> numbers.  ;-)
> 

Heh, that works too!  textwrap even uses 70.

--
knut