This is the help text of compileall:

 usage: python compileall.py [-l] [-f] [-q] [-d destdir] [-x regexp] [-i list] [directory|file ...]
 -l: don't recurse down
 -f: force rebuild even if timestamps are up-to-date
 -q: quiet operation
 -d destdir: purported directory name for error messages
    if no directory arguments, -l sys.path is assumed
 -x regexp: skip files matching the regular expression regexp
    the regexp is searched for in the full path of the file
 -i list: expand list with its content (file and directory names)
 -b: Produce legacy byte-compile file paths

1) I do not understand the help of -d and -i.  Experimenting with the script, reading the code and eventually looking at the file history would certainly clear that.

2) The short usage line at the top also lacks mention of “-b”.

3) (minor) I want to rephrase -x, -d and -b.

Bug week-end candidate!

In addition, the line “if no directory arguments, -l sys.path is assumed” seems misplaced.

Here is a proposed patch to both docs and help output.  The help output now looks like this:

usage: compileall.py [-h] [-l] [-f] [-q] [-b] [-d DESTDIR] [-x REGEXP]
                     [-i FILE]
                     [FILE|DIR [FILE|DIR ...]]

Utilities to support installing Python libraries.

positional arguments:
  FILE|DIR    zero or more file and directory names to compile; if no
              arguments given, defaults to the equivalent of -l sys.path

optional arguments:
  -h, --help  show this help message and exit
  -l          don't recurse into subdirectories
  -f          force rebuild even if timestamps are up to date
  -q          output only error messages
  -b          use legacy (pre-PEP3147) compiled file locations
  -d DESTDIR  directory to prepend to file paths for use in compile time
              tracebacks and in runtime tracebacks in cases where the source
              file is unavailable
  -x REGEXP   skip files matching the regular expression. The regexp is
              searched for in the full path to each file considered for
              compilation.
  -i FILE     add all the files and directories listed in FILE to the list
              considered for compilation. If "-", names are read from stdin.

+1 -- Didn't read through all of the diff, but in general I trust you enough to believe that the new version is better than the old :)

Committed in r87338.  Backporting the relevant bits will be a bit of a pain, anyone who feels like doing it is welcome to.  I may or may not get to it myself.

Hi David, I made this patch to port the improvements you made to 2.7.  The new usage message looks like this:

usage: python compileall.py [-l] [-f] [-q] [-d destdir] [-x regexp] [-i list] [directory|file ...]

arguments: zero or more file and directory names to compile; if no arguments given, 
           defaults to the equivalent of -l sys.path

options:
-l: don't recurse into subdirectories
-f: force rebuild even if timestamps are up-to-date
-q: output only error messages
-d destdir: directory to prepend to file paths for use in compile-time tracebacks and in
            runtime tracebacks in cases where the source file is unavailable
-x regexp: skip files matching the regular expression regexp; the regexp is searched for
           in the full path of each file considered for compilation
-i file: add all the files and directories listed in file to the list considered for
         compilation; if "-", names are read from stdin

I noticed some minor style issues, so I (IMO) improved them in my 2.7 patch and made a 3.x patch with the same minor touch-ups.

Looks fine except for your changes to the parenthesized defaults.  Those should be '0' and 'False' for 2.7 and 3.x, respectively, since that's what they areally are.

New changeset 755a57f987ca by Éric Araujo in branch '3.2':
#10454: a few edits to compileall help messages
http://hg.python.org/cpython/rev/755a57f987ca

New changeset 892e0ee4ca32 by Éric Araujo in branch 'default':
Merge doc changes from 3.2 (#10454, #12298)
http://hg.python.org/cpython/rev/892e0ee4ca32

New changeset 4ae85348e3e8 by Éric Araujo in branch '2.7':
Clarify compileall command-line options (#10454).
http://hg.python.org/cpython/rev/4ae85348e3e8