[MERGE] improve documentation of send/merge relationship

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Peter Schuller wrote:
| The attached patch/bundle attempts to clarify in 'bzr help send' that
| 'bzr merge' is to be used to merge the generated merge directive, and
| clarifies the output of 'bzr help merge' to explicitly explain this
| mode of operation.
|
|

+    with bzr send. If neither is specified, the default is the upstream branch
+    or the branch most recently remembered using --remember.

^- Maybe "most recently saved using --remember" or "most recently merged with
- --remember".

+    When merging branches, by default it will merge the latest revision.  If
+    you specify a revision, that revision will be merged.  If you specify two
+    revisions, the first will be used as a BASE, and the second one as OTHER.
+    Revision numbers are always relative to the specified branch.

^- When merging a branch, by default the tip will be merged. To pick a different
revision, pass --revision. If you specify two values, the first will be used as
BASE and the second one as OTHER. Revision numbers are always relative to the
branch being merged.

We might also want to mention "cherrypicking" as part of what happens when you
specify two revisions.

- -    takes_args = ['branch?']
+    takes_args = ['branch|merge_directive?']

^- This makes the help look nice, but breaks the command.

Specifically, the name here is turned into a python variable to pass to the "def
run()" function.

And you can't have a variable named "branch|merge_directive". We could change
this to "branch_or_merge_directive" if you prefer.

Because the "takes_args" is broken, we can't actually merge this as is.

BB:tweak

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFH3S7iJdeBCYSNAAMRAmZwAJwLLybBtXpz4BCpHXIqf8TQLwK3/wCgsSIG
6GeRUM5VwtnKsOY/3rGm3t8=
=vaKI
-----END PGP SIGNATURE-----