merge flags&aliases help output into just 'options'

IPython/config/application.py

@@ -44,26 +44,28 from IPython.utils.text import indent, wrap_paragraphs, dedent
 # Descriptions for the various sections
 #-----------------------------------------------------------------------------
 
-flag_description = """
-Flags are command-line arguments passed as '--<flag>'.
-These take no parameters, unlike regular key-value arguments.
-They are typically used for setting boolean flags, or enabling
-modes that involve setting multiple options together.
-""".strip() # trim newlines of front and back
+# merge flags&aliases into options
+option_description = """
+IPython command-line arguments are passed as '--<flag>', or '--<name>=<value>'.
 
-alias_description = """
-These are commonly set parameters, given abbreviated aliases for convenience.
-They are set in the same `--name=value` way as class parameters, where
-<name> is replaced by the real parameter for which it is an alias.
+Arguments that take values are actually aliases to full Configurables, whose
+aliases are listed on the help line. For more information on full
+configurables, see '--help-all'.
 """.strip() # trim newlines of front and back
 
 keyvalue_description = """
 Parameters are set from command-line arguments of the form:
 `--Class.trait=value`.
-This line is evaluated in Python, so simple expressions are allowed, e.g.
-    `--C.a='range(3)'`   For setting C.a=[0,1,2]
+This line is evaluated in Python, so simple expressions are allowed, e.g.::
+`--C.a='range(3)'` For setting C.a=[0,1,2].
 """.strip() # trim newlines of front and back
 
+subcommand_description = """
+Subcommands are launched as `{app} cmd [args]`. For information on using
+subcommand 'cmd', do: `{app} cmd -h`.
+""".strip().format(app=os.path.basename(sys.argv[0]))
+# get running program name
+
 #-----------------------------------------------------------------------------
 # Application class
 #-----------------------------------------------------------------------------
@@ -84,9 +86,9 class Application(SingletonConfigurable):
     # of the help.
     description = Unicode(u'This is an application.')
     # default section descriptions
-    flag_description = Unicode(flag_description)
-    alias_description = Unicode(alias_description)
+    option_description = Unicode(option_description)
     keyvalue_description = Unicode(keyvalue_description)
+    subcommand_description = Unicode(subcommand_description)
     
 
     # A sequence of Configurable subclasses whose config=True attributes will
@@ -190,13 +192,7 class Application(SingletonConfigurable):
         if not self.aliases:
             return
         
-        lines = ['Aliases']
-        lines.append('-'*len(lines[0]))
-        lines.append('')
-        for p in wrap_paragraphs(self.alias_description):
-            lines.append(p)
-            lines.append('')
-        
+        lines = []
         classdict = {}
         for cls in self.classes:
             # include all parents (up to, but excluding Configurable) in available names
@@ -212,7 +208,7 class Application(SingletonConfigurable):
             # reformat first line
             help[0] = help[0].replace(longname, alias) + ' (%s)'%longname
             lines.extend(help)
-        lines.append('')
+        # lines.append('')
         print os.linesep.join(lines)
     
     def print_flag_help(self):
@@ -220,18 +216,26 class Application(SingletonConfigurable):
         if not self.flags:
             return
         
-        lines = ['Flags']
-        lines.append('-'*len(lines[0]))
-        lines.append('')
-        for p in wrap_paragraphs(self.flag_description):
-            lines.append(p)
-            lines.append('')
-        
+        lines = []
         for m, (cfg,help) in self.flags.iteritems():
             lines.append('--'+m)
             lines.append(indent(dedent(help.strip())))
+        # lines.append('')
+        print os.linesep.join(lines)
+    
+    def print_options(self):
+        if not self.flags and not self.aliases:
+            return
+        lines = ['Options']
+        lines.append('-'*len(lines[0]))
         lines.append('')
-        print '\n'.join(lines)
+        for p in wrap_paragraphs(self.option_description):
+            lines.append(p)
+            lines.append('')
+        print os.linesep.join(lines)
+        self.print_flag_help()
+        self.print_alias_help()
+        print
     
     def print_subcommands(self):
         """Print the subcommand part of the help."""
@@ -240,12 +244,16 class Application(SingletonConfigurable):
         
         lines = ["Subcommands"]
         lines.append('-'*len(lines[0]))
+        lines.append('')
+        for p in wrap_paragraphs(self.subcommand_description):
+            lines.append(p)
+            lines.append('')
         for subc, (cls,help) in self.subcommands.iteritems():
             lines.append("%s : %s"%(subc, cls))
             if help:
                 lines.append(indent(dedent(help.strip())))
         lines.append('')
-        print '\n'.join(lines)
+        print os.linesep.join(lines)
     
     def print_help(self, classes=False):
         """Print the help for each Configurable class in self.classes.
@@ -253,8 +261,7 class Application(SingletonConfigurable):
         If classes=False (the default), only flags and aliases are printed.
         """
         self.print_subcommands()
-        self.print_flag_help()
-        self.print_alias_help()
+        self.print_options()
         
         if classes:
             if self.classes: