[RFC] Condense help listings

John Arbash Meinel john at arbash-meinel.com
Sun Sep 24 06:12:51 BST 2006


Aaron Bentley wrote:
> Hi all,
> 
> I've attached a bundle that condenses the listing produced by 'bzr help
> commands'.
> 
> The new format looks like this:
> add               Add specified files or directories.
> annotate          Show the origin of each line in a file.
> baz-import        Import an Arch or Baz archive into a bzr repository.
>                   <bzrtools>
> baz-import-branch Import an Arch or Baz branch into a bzr branch. <bzrtools>
> 
> (Strikingly like Mercurial)
> 

I think I like the look of it. You can do 'bzr help foo' to get the
detailed help of foo. It might have been nice to have the summaries
available when it was a shorter list. I wonder about changing it to:

baz-import <bzrtools> Import an Arch or Baz...

And probably (bzrtools) might be nicer. So I'm happy with the single
line entries, it makes things look less cluttered.

> Changes
> 1. the listing doesn't include usage info, just the command
> 2. the command isn't prefixed, e.g. 'bzr add'
> 3. to keep the listing short, plugins are shown with '<plugin>', not
> '(from plugin "plugin")'
> 
> The width of the command column is set to the width of the longest
> command name displayed.
> 
> What do people think?
> 
> Aaron

------------------------------------------------------------------------

# Bazaar revision bundle v0.8
#
# message:
#   Fix testcase
# committer: Aaron Bentley <aaron.bentley at utoronto.ca>
# date: Sat 2006-09-23 14:43:36.319000006 -0400

=== modified file bzrlib/help.py //
last-changed:aaron.bentley at utoronto.ca-2006
... 0923172850-790fb842f3df42fe
--- bzrlib/help.py
+++ bzrlib/help.py
@@ -21,6 +21,7 @@

 # TODO: `help commands --all` should show hidden commands
 import textwrap
+from bzrlib import osutils

 global_help = \
 """Bazaar -- a free distributed version-control tool
@@ -150,18 +151,30 @@
     names.update(plugin_command_names())
     names = list(names)
     names.sort()
+    commands = [(n, get_cmd_object(n)) for n in names]


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)

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.

You're format string also is creating a trailing ' ' when the plugin
name is empty

+    max_name = max([len(n) for n, o in commands if not o.hidden])
+    format_string = '%%-%ds %%s %%s' % max_name
+    indent = ' ' * (max_name+1)
+    width = osutils.terminal_width() - 1
     for cmd_name in names:
         cmd_object = get_cmd_object(cmd_name)
         if cmd_object.hidden:
             continue
-        print >>outfile, command_usage(cmd_object)
-
         plugin_name = cmd_object.plugin_name()
-        print_command_plugin(cmd_object, outfile, '        %s\n')
+        if plugin_name is None:
+            plugin_name = ''
+        else:
+            plugin_name = '<%s>' % plugin_name

^- Here just do plugin_name = '' or plugin_name = ' <%s>', that gives
you the extra space when you need it, and avoids it otherwise.

         cmd_help = cmd_object.help()
         if cmd_help:
             firstline = cmd_help.split('\n', 1)[0]
-            print >>outfile, '        ' + firstline
+        else:
+            firstline = ''
+        helpstring = format_string % (cmd_name, firstline, plugin_name)
+        lines = textwrap.wrap(helpstring, subsequent_indent=indent,
+                              width=width)
+        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).


=== modified file bzrlib/tests/test_plugins.py
--- bzrlib/tests/test_plugins.py
+++ bzrlib/tests/test_plugins.py
@@ -148,8 +148,8 @@
         help = {}
         current = None
         for line in self.capture('help commands').splitlines():
-            if line.startswith('bzr '):
-                current = line.split()[1]
+            if not line.startswith(' '):
+                current = line.split()[0]
             help[current] = help.get(current, '') + line

         return help
@@ -189,7 +189,7 @@
             help = self.capture('help myplug')
             self.assertContainsRe(help, 'From plugin "myplug"')
             help = self.split_help_commands()['myplug']
-            self.assertContainsRe(help, 'From plugin "myplug"')
+            self.assertContainsRe(help, '<myplug>')
         finally:
             # remove the plugin 'plugin'
             if getattr(bzrlib.plugins, 'plugin', None):


A couple small cleanups and it has my go ahead. I think it is a little
late for 0.11, though.

John
=:->

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060924/c23b1db9/attachment.pgp 


More information about the bazaar mailing list