More examples at the end of trychange.py help and move the -R flag to the right group

trychange.py

 #!/usr/bin/python
 # Copyright (c) 2009 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 """Client-side script to send a try job to the try server. It communicates to
 the try server by either writting to a svn repository or by directly connecting
 to the server by HTTP.
 """
 
 import datetime
@@ skipping 27 matching lines @@
 
 __version__ = '1.2'
 
 
 # Constants
 HELP_STRING = "Sorry, Tryserver is not available."
 USAGE = r"""%prog [options]
 
 Client-side script to send a try job to the try server. It communicates to
 the try server by either writting to a svn repository or by directly connecting
-to the server by HTTP.
+to the server by HTTP."""
 
+EPILOG = """
 Examples:
+  Send a patch directly from rietveld:
+    %(prog)s -R codereview.chromium.org/1337
+        --email recipient@example.com --root src
+
   Try a change against a particular revision:
-    %prog -r 123
+    %(prog)s -r 123
 
   A git patch off a web site (git inserts a/ and b/) and fix the base dir:
-    %prog --url http://url/to/patch.diff --patchlevel 1 --root src
-
-  Or from rietveld:
-    %prog -R codereview.chromium.org/1337 --email me@example.com --root src
+    %(prog)s --url http://url/to/patch.diff --patchlevel 1 --root src
 
   Use svn to store the try job, specify an alternate email address and use a
   premade diff file on the local drive:
-    %prog --email user@example.com
+    %(prog)s --email user@example.com
             --svn_repo svn://svn.chromium.org/chrome-try/try --diff foo.diff
 
   Running only on a 'mac' slave with revision 123 and clobber first; specify
   manually the 3 source files to use for the try job:
-    %prog --bot mac --revision 123 --clobber -f src/a.cc -f src/a.h
+    %(prog)s --bot mac --revision 123 --clobber -f src/a.cc -f src/a.h
             -f include/b.h
-
-  When called from gcl, use the format gcl try <change_name>.
 """
 
 class InvalidScript(Exception):
   def __str__(self):
     return self.args[0] + '\n' + HELP_STRING
 
 
 class NoTryServerAccess(Exception):
   def __str__(self):
     return self.args[0] + '\n' + HELP_STRING
@@ skipping 361 matching lines @@
   for i in range(len(diff)):
     if diff[i].startswith('--- ') or diff[i].startswith('+++ '):
       new_file = posixpath.join(path_diff, diff[i][4:]).replace('\\', '/')
       diff[i] = diff[i][0:4] + new_file
   return diff
 
 
 def TryChange(argv,
               file_list,
               swallow_exception,
-              prog=None):
+              prog=None,
+              extra_epilog=None):
   """
   Args:
     argv: Arguments and options.
     file_list: Default value to pass to --file.
     swallow_exception: Whether we raise or swallow exceptions.
   """
   # Parse argv
+  epilog = EPILOG % { 'prog': prog }
+  if extra_epilog:
+    epilog += extra_epilog
   parser = optparse.OptionParser(usage=USAGE,
                                  version=__version__,
-                                 prog=prog)
+                                 prog=prog,
+                                 epilog=epilog)
+  # Remove epilog formatting
+  parser.format_epilog = lambda x: parser.epilog
   parser.add_option("-v", "--verbose", action="count", default=0,
                     help="Prints debugging infos")
   group = optparse.OptionGroup(parser, "Result and status")
   group.add_option("-u", "--user", default=getpass.getuser(),
                    help="Owner user name [default: %default]")
   group.add_option("-e", "--email",
                    default=os.environ.get('TRYBOT_RESULTS_EMAIL_ADDRESS',
                         os.environ.get('EMAIL_ADDRESS')),
                    help="Email address where to send the results. Use either "
                         "the TRYBOT_RESULTS_EMAIL_ADDRESS environment "
                         "variable or EMAIL_ADDRESS to set the email address "
                         "the try bots report results to [default: %default]")
   group.add_option("-n", "--name",
                    help="Descriptive name of the try job")
   group.add_option("--issue", type='int',
                    help="Update rietveld issue try job status")
   group.add_option("--patchset", type='int',
                    help="Update rietveld issue try job status. This is "
                         "optional if --issue is used, In that case, the "
                         "latest patchset will be used.")
   group.add_option("--dry_run", action='store_true',
                    help="Just prints the diff and quits")
-  group.add_option("-R", "--rietveld_url", default="codereview.appspot.com",
-                   metavar="URL",
-                   help="The root code review url. Default:%default")
   parser.add_option_group(group)
 
   group = optparse.OptionGroup(parser, "Try job options")
   group.add_option("-b", "--bot", action="append",
                     help="Only use specifics build slaves, ex: '--bot win' to "
                          "run the try job only on the 'win' slave; see the try "
                          "server waterfall for the slave's name")
   group.add_option("-r", "--revision",
                     help="Revision to use for the try job; default: the "
                          "revision will be determined by the try server; see "
@@ skipping 20 matching lines @@
   parser.add_option_group(group)
 
   group = optparse.OptionGroup(parser, "Patch to run")
   group.add_option("-f", "--file", default=file_list, dest="files",
                    metavar="FILE", action="append",
                    help="Use many times to list the files to include in the "
                         "try, relative to the repository root")
   group.add_option("--diff",
                    help="File containing the diff to try")
   group.add_option("--url",
-                   help="Url where to grab a patch")
+                   help="Url where to grab a patch, e.g. "
+                        "http://example.com/x.diff")
+  group.add_option("-R", "--rietveld_url", default="codereview.appspot.com",
+                   metavar="URL",
+                   help="Has 2 usages, both refer to the rietveld instance: "
+                        "Specify which code review patch to use as the try job "
+                        "or rietveld instance to update the try job results "
+                        "Default:%default")
   group.add_option("--root",
                    help="Root to use for the patch; base subdirectory for "
                         "patch created in a subdirectory")
   group.add_option("-p", "--patchlevel", type='int', metavar="LEVEL",
                    help="Used as -pN parameter to patch")
   group.add_option("-s", "--sub_rep", action="append", default=[],
                    help="Subcheckout to use in addition. This is mainly "
                         "useful for gclient-style checkouts. Use @rev or "
                         "@branch or @branch1..branch2 to specify the "
                         "revision/branch to diff against.")
@@ skipping 185 matching lines @@
   except (InvalidScript, NoTryServerAccess), e:
     if swallow_exception:
       return 1
     print e
     return 1
   return 0
 
 
 if __name__ == "__main__":
   sys.exit(TryChange(None, [], False))