Merge lp:~mbp/bzr-builddeb/doc into lp:bzr-builddeb

[Martin Pool]

This tries to make the merge-upstream help clearer, based on <http://jameswestby.net/bzr/builddeb/user_manual/normal.html>.

I'm not sure it's correct; please review carefully.

[Robert Collins (lifeless)]

This looks broadly ok to me. I think the examples should include one
appropriate for upstream-in-bzr projects, like bzr itself.

[Martin Pool (mbp)]

If I can get it to work for bzr I'll change the example :)

--
Martin

[James Westby (james-w)]

I've merged this with some added improvements of my own, thanks.

James

review: Approve

=== modified file 'cmds.py'
--- cmds.py	2010-05-28 20:49:11 +0000
+++ cmds.py	2010-06-30 04:49:22 +0000
@@ -461,34 +461,46 @@
 
     You must supply the source to import from, and the version number of the
     new release. The source can be a .tar.gz, .tar, .tar.bz2, .tgz or .zip
-    archive, or a directory. The source may also be a remote file.
+    archive, or a directory. The source may also be a remote file described by a URL.
 
     You must supply the version number of the new upstream release
-    using --version.
+    using --version, unless you're importing from an upstream branch, in which
+    case it can be guessed from that.
 
     The distribution this version is targetted at can be specified with
-    --distribution. This will be used to guess the version number, so you
-    can always correct it in the changelog.
+    --distribution. 
 
     If there is no debian changelog in the branch to retrieve the package
     name from then you must pass the --package option. If this version
     will change the name of the source package then you can use this option
     to set the new name.
+
+    examples::
+
+        bzr merge-upstream --version 0.2 \
+            http://example.org/releases/scruff-0.2.tar.gz
+
+    If there is no upstream release tarball, and you want bzr-builddeb to
+    create the tarball for you::
+
+        bzr merge-upstream --version 0.2 http://scruff.org/bzr/scruff.dev
+      
     """
     takes_args = ['location?', 'upstream_branch?']
     aliases = ['mu']
 
     package_opt = Option('package', help="The name of the source package.",
                          type=str)
-    version_opt = Option('version', help="The version number of this release.",
-                         type=str)
+    version_opt = Option('version',
+        help="The version number of this release, for example \"0.2\".",
+        type=str)
     distribution_opt = Option('distribution', help="The distribution that "
             "this release is targetted at.", type=str)
     directory_opt = Option('directory',
                            help='Working tree into which to merge.',
                            short_name='d', type=unicode)
     last_version_opt = Option('last-version',
-                              help='The previous version that was merged..',
+                              help='The previous version that was merged.',
                               type=str)
     force_opt = Option('force',
                        help=('Force a merge even if the upstream branch '