Patch from Rene Liebscher: this adds "--help-foo" options to list the

values that "--foo" can take for various commands: eg. what formats for
"sdist" and "bdist", what compilers for "build_ext" and "build_clib".

I have *not* reviewed this patch; I'm checking it in as-is because it also
fixes a paper-bag-over-head bug in bdist.py, and because I won't have
time to review it properly for several days: so someone else can
test it for me, instead!

Lib/distutils/archive_util.py

@@ -110,11 +110,11 @@ def make_zipfile (base_name, base_dir, verbose=0, dry_run=0):
 
 
 ARCHIVE_FORMATS = {
-    'gztar': (make_tarball, [('compress', 'gzip')]),
+    'gztar': (make_tarball, [('compress', 'gzip')],"gzipped tar-file"),
-    'bztar': (make_tarball, [('compress', 'bzip2')]),
+    'bztar': (make_tarball, [('compress', 'bzip2')],"bzip2-ed tar-file"),
-    'ztar':  (make_tarball, [('compress', 'compress')]),
+    'ztar':  (make_tarball, [('compress', 'compress')],"compressed tar-file"),
-    'tar':   (make_tarball, [('compress', None)]),
+    'tar':   (make_tarball, [('compress', None)],"uncompressed tar-file"),
-    'zip':   (make_zipfile, [])
+    'zip':   (make_zipfile, [],"zip-file")
     }
 
 def check_archive_formats (formats):

Lib/distutils/ccompiler.py

@@ -726,10 +726,22 @@ default_compiler = { 'posix': 'unix',
 # Map compiler types to (module_name, class_name) pairs -- ie. where to
 # find the code that implements an interface to this compiler.  (The module
 # is assumed to be in the 'distutils' package.)
-compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler'),
+compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler',"standard UNIX-style compiler"),
-                   'msvc': ('msvccompiler', 'MSVCCompiler'),
+                   'msvc': ('msvccompiler', 'MSVCCompiler',"Microsoft Visual C++"),
+                   'cygwin':  ('cygwinccompiler', 'CygwinCCompiler',"Cygwin-Gnu-Win32-C-Compiler"),
+                   'mingw32': ('cygwinccompiler', 'Mingw32CCompiler',"MinGW32-C-Compiler (or cygwin in this mode)"),
                  }
 
+# prints all possible arguments to --compiler
+def show_compilers():
+    from distutils.fancy_getopt import FancyGetopt 
+    list_of_compilers=[]
+    for compiler in compiler_class.keys():
+	list_of_compilers.append(("compiler="+compiler,None,compiler_class[compiler][2]))
+    list_of_compilers.sort()
+    pretty_printer=FancyGetopt(list_of_compilers)
+    pretty_printer.print_help("List of available compilers:")
+    
 
 def new_compiler (plat=None,
                   compiler=None,
@@ -755,7 +767,7 @@ def new_compiler (plat=None,
         if compiler is None:
             compiler = default_compiler[plat]
         
-        (module_name, class_name) = compiler_class[compiler]
+        (module_name, class_name,long_description) = compiler_class[compiler]
     except KeyError:
         msg = "don't know how to compile C/C++ code on platform '%s'" % plat
         if compiler is not None:

Lib/distutils/command/bdist.py

@@ -21,8 +21,7 @@ class bdist (Command):
     user_options = [('bdist-base=', 'b',
                      "temporary directory for creating built distributions"),
                     ('formats=', None,
-                     "formats for distribution " +
+                     "formats for distribution"),
-                     "(gztar, bztar, zip, rpm, ... )"),
                    ]
 
     # The following commands do not take a format option from bdist
@@ -33,12 +32,28 @@ class bdist (Command):
     default_format = { 'posix': 'gztar',
                        'nt': 'zip', }
 
-    format_command = { 'gztar': 'bdist_dumb',
+    format_command = { 'gztar': ('bdist_dumb',"gzipped tar-file"),
-                       'bztar': 'bdist_dumb',
+                       'bztar': ('bdist_dumb',"bzip2-ed tar-file"),
-                       'ztar':  'bdist_dumb',
+                       'ztar':  ('bdist_dumb',"compressed tar-file"),
-                       'tar':   'bdist_dumb',
+                       'tar':   ('bdist_dumb',"tar-file"),
-                       'rpm':   'bdist_rpm',
+                       'rpm':   ('bdist_rpm',"rpm distribution"),
-                       'zip':   'bdist_dumb', }
+                       'zip':   ('bdist_dumb',"zip-file"),
+		        }
+
+    # prints all possible arguments to --format
+    def show_formats():
+	from distutils.fancy_getopt import FancyGetopt 
+	list_of_formats=[]
+	for format in bdist.format_command.keys():
+	    list_of_formats.append(("formats="+format,None,bdist.format_command[format][1]))
+	list_of_formats.sort()
+	pretty_printer=FancyGetopt(list_of_formats)
+	pretty_printer.print_help("List of available distribution formats:")
+
+    help_options = [
+        ('help-formats', None,
+         "lists available distribution formats",show_formats),
+	]
 
 
     def initialize_options (self):
@@ -74,14 +89,14 @@ class bdist (Command):
         for format in self.formats:
 
             try:
-                cmd_name = self.format_command[self.format]
+                cmd_name = self.format_command[format][0]
             except KeyError:
                 raise DistutilsOptionError, \
-                      "invalid format '%s'" % self.format
+                      "invalid format '%s'" % format
 
             sub_cmd = self.reinitialize_command(cmd_name)
             if cmd_name not in self.no_format_option:
-                sub_cmd.format = self.format
+                sub_cmd.format = format
             self.run_command (cmd_name)
 
     # run()

Lib/distutils/command/build.py

@@ -9,6 +9,7 @@ __revision__ = "$Id$"
 import sys, os
 from distutils.core import Command
 from distutils.util import get_platform
+from distutils.ccompiler import show_compilers
 
 class build (Command):
 
@@ -35,6 +36,10 @@ class build (Command):
         ('force', 'f',
          "forcibly build everything (ignore file timestamps)"),
         ]
+    help_options = [
+        ('help-compiler', None,
+         "lists available compilers",show_compilers),
+	]
 
     def initialize_options (self):
         self.build_base = 'build'

Lib/distutils/command/build_clib.py

@@ -23,7 +23,7 @@ import os, string
 from types import *
 from distutils.core import Command
 from distutils.errors import *
-from distutils.ccompiler import new_compiler
+from distutils.ccompiler import new_compiler,show_compilers
 
 
 class build_clib (Command):
@@ -42,6 +42,10 @@ class build_clib (Command):
         ('compiler=', 'c',
          "specify the compiler type"),
         ]
+    help_options = [
+        ('help-compiler', None,
+         "lists available compilers",show_compilers),
+	]
 
     def initialize_options (self):
         self.build_clib = None

Lib/distutils/command/build_ext.py

@@ -14,6 +14,7 @@ from distutils.core import Command
 from distutils.errors import *
 from distutils.dep_util import newer_group
 from distutils.extension import Extension
+from distutils.ccompiler import show_compilers
 
 # An extension name is just a dot-separated list of Python NAMEs (ie.
 # the same as a fully-qualified module name).
@@ -72,6 +73,10 @@ class build_ext (Command):
         ('compiler=', 'c',
          "specify the compiler type"),
         ]
+    help_options = [
+        ('help-compiler', None,
+         "lists available compilers",show_compilers),
+	]
 
 
     def initialize_options (self):

Lib/distutils/command/sdist.py

@@ -13,7 +13,7 @@ from glob import glob
 from distutils.core import Command
 from distutils.util import newer, create_tree, remove_tree, convert_path, \
      write_file
-from distutils.archive_util import check_archive_formats
+from distutils.archive_util import check_archive_formats,ARCHIVE_FORMATS
 from distutils.text_file import TextFile
 from distutils.errors import DistutilsExecError, DistutilsOptionError
 
@@ -35,11 +35,26 @@ class sdist (Command):
         ('force-manifest', 'f',
          "forcibly regenerate the manifest and carry on as usual"),
         ('formats=', None,
-         "formats for source distribution (tar, ztar, gztar, bztar, or zip)"),
+         "formats for source distribution"),
         ('keep-tree', 'k',
          "keep the distribution tree around after creating " +
          "archive file(s)"),
         ]
+    # prints all possible arguments to --formats
+    def show_formats():
+	from distutils.fancy_getopt import FancyGetopt 
+	list_of_formats=[]
+	for format in ARCHIVE_FORMATS.keys():
+	    list_of_formats.append(("formats="+format,None,ARCHIVE_FORMATS[format][2]))
+	list_of_formats.sort()
+	pretty_printer=FancyGetopt(list_of_formats)
+	pretty_printer.print_help("List of available distribution formats:")
+
+    help_options = [
+        ('help-formats', None,
+         "lists available distribution formats",show_formats),
+	]
+
     negative_opts = {'use-defaults': 'no-defaults'}
 
     default_format = { 'posix': 'gztar',

Lib/distutils/dist.py

@@ -437,16 +437,38 @@ class Distribution:
             negative_opt = copy (negative_opt)
             negative_opt.update (cmd_class.negative_opt)
 
+	# Check for help_options in command class
+	# They have a different format (tuple of four) so we need to preprocess them here 
+	help_options = []
+	if hasattr(cmd_class,"help_options") and type (cmd_class.help_options) is ListType:
+	    help_options = map(lambda x:(x[0],x[1],x[2]),cmd_class.help_options)
+
         # All commands support the global options too, just by adding
         # in 'global_options'.
         parser.set_option_table (self.global_options +
-                                 cmd_class.user_options)
+                                 cmd_class.user_options + help_options)
         parser.set_negative_aliases (negative_opt)
         (args, opts) = parser.getopt (args[1:])
         if hasattr(opts, 'help') and opts.help:
             self._show_help(parser, display_options=0, commands=[cmd_class])
             return
 
+	if hasattr(cmd_class,"help_options") and type (cmd_class.help_options) is ListType:
+	    help_option_found=0
+	    for help_option in cmd_class.help_options:
+		if hasattr(opts, parser.get_attr_name(help_option[0])):
+		    help_option_found=1
+		    #print "showing help for option %s of command %s" % (help_option[0],cmd_class)
+		    if callable(help_option[3]):
+			help_option[3]()
+		    else:
+        		raise DistutilsClassError, \
+                          ("command class %s must provide " +
+                           "a callable object for help_option '%s'") % \
+                          (cmd_class,help_option[0])
+	    if help_option_found: 
+		return
+
         # Put the options from the command-line into their official
         # holding pen, the 'command_options' dictionary.
         opt_dict = self.get_option_dict(command)
@@ -496,7 +518,11 @@ class Distribution:
                 klass = command
             else:
                 klass = self.get_command_class (command)
-            parser.set_option_table (klass.user_options)
+	    if hasattr(klass,"help_options") and type (klass.help_options) is ListType:
+		parser.set_option_table (klass.user_options+
+					 map(lambda x:(x[0],x[1],x[2]),klass.help_options))
+	    else:
+        	parser.set_option_table (klass.user_options)
             parser.print_help ("Options for '%s' command:" % klass.__name__)
             print
 
@@ -504,7 +530,7 @@ class Distribution:
         return
 
     # _show_help ()
-
+	
 
     def handle_display_options (self, option_order):
         """If there were any non-global "display-only" options