Rev 3379: (mbp) Better help and docs for send in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 3379
revision-id:pqm at pqm.ubuntu.com-20080424072816-jjx4v6pqude11ys2
parent: pqm at pqm.ubuntu.com-20080424051908-kyhfubgxkuvu5bqc
parent: mbp at sourcefrog.net-20080424033054-tder52xdjbq39x5t
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2008-04-24 08:28:16 +0100
message:
  (mbp) Better help and docs for send
modified:
  bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
  doc/en/user-guide/sending_changes.txt sending_changes.txt-20071123154453-dk2mjhrg1vpjm5w2-4
    ------------------------------------------------------------
    revno: 3377.2.2
    revision-id:mbp at sourcefrog.net-20080424033054-tder52xdjbq39x5t
    parent: mbp at sourcefrog.net-20080424012726-az7wb11knbdwzqhv
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Thu 2008-04-24 13:30:54 +1000
    message:
      Say 'merge directive' rather than just 'directive' in help
    modified:
      bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
    ------------------------------------------------------------
    revno: 3377.2.1
    revision-id:mbp at sourcefrog.net-20080424012726-az7wb11knbdwzqhv
    parent: pqm at pqm.ubuntu.com-20080422120059-sony5sthnlewabge
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: doc
    timestamp: Thu 2008-04-24 11:27:26 +1000
    message:
      doc: send -o, and more on send in user guide
    modified:
      bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
      doc/en/user-guide/sending_changes.txt sending_changes.txt-20071123154453-dk2mjhrg1vpjm5w2-4
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py	2008-04-12 06:46:35 +0000
+++ b/bzrlib/builtins.py	2008-04-24 03:30:54 +0000
@@ -4107,7 +4107,9 @@
                'rather than the one containing the working directory.',
                short_name='f',
                type=unicode),
-        Option('output', short_name='o', help='Write directive to this file.',
+        Option('output', short_name='o',
+               help='Write merge directive to this file; '
+                    'use - for stdout.',
                type=unicode),
         Option('mail-to', help='Mail the request to this address.',
                type=unicode),

=== modified file 'doc/en/user-guide/sending_changes.txt'
--- a/doc/en/user-guide/sending_changes.txt	2007-12-07 03:37:32 +0000
+++ b/doc/en/user-guide/sending_changes.txt	2008-04-24 01:27:26 +0000
@@ -34,22 +34,30 @@
 Creating a merge directive
 --------------------------
 
-To create a merge directive, use the ``send`` command. For example,
-this command creates a merge directive and saves it into the
-nominated output file::
+To create and optionally send a merge directive, use the ``send`` command. 
+
+By default, ``send`` will email the merge directive to the "submission
+address" for the branch, which is typically the lead developer or the
+development mailing list.  
+``send`` without options will create a merge directive, fire up your email
+tool and attach it, ready for you to add the explanatory text bit.
+(See the online help for ``send`` and
+`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_
+in the User Reference for further details on how to configure this.)
+
+Most projects like people to add some explanation to the mail along with
+the patch, explaining the reason for the patch, and why it is done the way
+it is.  This gives a reviewer some context before going into the
+line-by-line diff.
+
+Alternatively, if the ``--output`` (or ``-o``) option is given, ``send``
+will write the merge directive to a file, so you can mail it yourself,
+examine it, or save it for later use.  If an output file of ``-`` is
+given, the directive is written to stdout.  For example::
 
   cd X-fix-123
   bzr send -o ../fix-123.patch
 
-That file can then be emailed to a reviewer, together with an
-explanation of how and why you fixed the problem the way you did, say.
-
-Emailing merge directives is such a common thing that the ``send`` command
-without options will create a merge directive, fire up your email
-tool and attach it, ready for you to add the explanatory text bit.
-See the online help for ``send`` and
-`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_
-in the User Reference for further details on how to configure this.
 
 Applying a merge directive
 --------------------------