[RFC] Condense help listings

[Martin Pool]

On 24 Sep 2006, Aaron Bentley <aaron.bentley at utoronto.ca> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> John Arbash Meinel wrote:
> > I wonder about changing it to:
> > 
> > baz-import <bzrtools> Import an Arch or Baz...
> 
> I thought the description would be the most interesting thing for
> people, most of the time, so I stuck the plugin at the end.
> 
> > And probably (bzrtools) might be nicer. So I'm happy with the single
> > line entries, it makes things look less cluttered.
> 
> Parentheses are used in regular command descriptions, so I thought that
> would be confusing.  Perhaps "[bzrtools]"?
> 
> > v- Small thing: You don't need the extra [], since 'max()' works just
> > fine on a generator:
> > max_name = max(len(n) for n, o in commands if not o.hidden)
> 
> Okay.  I've tweaked this so the list of commands to show is created in
> one place and reused.
> 
> > Also, you can use "%-*s %s%s" % (max_name, name, plugin_name)
> > Rather than having to generate the format string ahead of time, and
> > double escaping all of the % characters.
> 
> Done.
> 
> > You're format string also is creating a trailing ' ' when the plugin
> > name is empty
> 
> Fixed.
> 
> > +        for line in lines:
> > +            print >> outfile, line
> > 
> > I really prefer 'outfile.write(line)' to print >> outfile, line
> > It means changing the format string to have a trailing '\n', but that
> > shouldn't be to hard. (For all I know, textwrap already does that).
> 
> Actually, it meant changing every line to end with '\n'.
> 
> > A couple small cleanups and it has my go ahead. I think it is a little
> > late for 0.11, though.
> 
> Agreed.
> 
> I've attached a patch that should address your technical concerns.
> 
> I'd like to hear what other people think, especially about how we should
> identify commands from plugins.

I like it too.  Saying 'bzr' at the start of every line is fairly
redundant; getting the synopsis in the current form is nice but the main
use of this should be to let people drill down to a command, or scan for
one whose name they have forgotten.

+1 from me; if you're quick it can be the first thing in 0.12 i think.

> -        helpstring = format_string % (cmd_name, firstline, plugin_name)
> +        helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
>          lines = textwrap.wrap(helpstring, subsequent_indent=indent,
>                                width=width)
>          for line in lines:
> -            print >> outfile, line
> -        
> +            outfile.write(line + '\n')

I would be inclined to add a '\n' to helpstring, then just
outfile.writelines(lines)

-- 
Martin