manpages: add references to pbuilder and cowbuilder

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

4 files changed, 34 insertions, 29 deletions

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index e492768..6223e87 100644
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -406,7 +406,8 @@ is a single debrebase stitch.
 =head1 BUILDING AND UPLOADING
 
 You can use dpkg-buildpackage(1) for test builds.  When you are ready
-to build for an upload, use B<dgit sbuild>.
+to build for an upload, use B<dgit sbuild>, B<dgit pbuilder> or B<dgit
+cowbuilder>.
 
 Upload with B<dgit push> or B<dgit push-source>.  Remember to pass
 I<--new> if the package is new in the target suite.
diff --git a/dgit-maint-gbp.7.pod b/dgit-maint-gbp.7.pod
index b761296..29a712f 100644
--- a/dgit-maint-gbp.7.pod
+++ b/dgit-maint-gbp.7.pod
@@ -58,8 +58,12 @@ where I<--allow-dirty> is needed for testing uncommitted changes, and
 I<OPTIONS> are any further options to be passed on to
 gbp-buildpackage(1).
 
-When you are ready to build for upload, you will probably want to use
-sbuild(1) or pbuilder(1), or do a source-only upload.  Either
+If you are doing a source-only upload, you do not need to prepare a
+I<_source.changes>, as B<dgit push-source> will take of that on your
+behalf.
+
+If you need to include binaries with your upload, you will probably
+want to use sbuild(1), pbuilder(1) or cowbuilder(1):
 
 =over 4
 
@@ -67,37 +71,33 @@ sbuild(1) or pbuilder(1), or do a source-only upload.  Either
 
 =back
 
-or
+replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.
 
-=over 4
+We use I<--rm-old-changes> to ensure that there is exactly one changes
+file corresponding to this package, so we can be confident we're
+uploading what we intend (though B<dgit push> will do some safety
+checks).
 
-    % dgit --rm-old-changes gbp-build --git-pbuilder
+Note that none of the commands in this section are required to upload
+with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1),
+cowbuilder(1) and sbuild(1) directly.  However, the defaults for these
+tools may leave you with something that dgit will refuse to upload
+because it doesn't match your git HEAD.
 
-=back
+As a general rule, leave all signing and tagging to dgit.
+
+=head1 UPLOADING
 
-or
+Don't use I<--git-tag>: B<dgit push> will do this for you.  To do a
+source-only upload:
 
 =over 4
 
-    % dgit --rm-old-changes --gbp build-source
+    % dgit --gbp push-source
 
 =back
 
-We use I<--rm-old-changes> to ensure that there is exactly one changes
-file corresponding to this package, so we can be confident we're
-uploading what we intend (though B<dgit push> will do some safety
-checks).
-
-Note that all of the commands in this section are not required to
-upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
-sbuild(1) directly.  However, the defaults for these tools may leave
-you with something that dgit will refuse to upload because it doesn't
-match your git HEAD.  As a general rule, leave all signing and tagging
-to dgit.
-
-=head1 UPLOADING
-
-Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
+or if you need to include binaries,
 
 =over 4
 
diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index 79d2a60..c20a252 100644
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -311,11 +311,11 @@ important information present in README.source.
 
 =head1 BUILDING AND UPLOADING
 
-Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
-push> as detailed in dgit(1).  If any command fails, dgit will provide
-a carefully-worded error message explaining what you should do.  If
-it's not clear, file a bug against dgit.  Remember to pass I<--new>
-for the first upload.
+Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit
+cowbuilder>, B<dgit push-source>, and B<dgit push> as detailed in
+dgit(1).  If any command fails, dgit will provide a carefully-worded
+error message explaining what you should do.  If it's not clear, file
+a bug against dgit.  Remember to pass I<--new> for the first upload.
 
 As an alternative to B<dgit build> and friends, you can use a tool
 like gitpkg(1).  This works because like dgit, gitpkg(1) enforces that
diff --git a/dgit-maint-native.7.pod b/dgit-maint-native.7.pod
index 34aaaff..ac57728 100644
--- a/dgit-maint-native.7.pod
+++ b/dgit-maint-native.7.pod
@@ -65,6 +65,10 @@ Simply prepare your git tree in the usual way, and then:
 
 (Do not make any tags yourself: dgit push will do that.)
 
+You may use B<dgit pbuilder> or B<dgit cowbuilder>
+instead of B<dgit sbuild>;
+see dgit(1) for the syntax of those subcommands.
+
 The --overwrite option tells dgit that you are expecting
 that your git history is not a descendant of the
 history which dgit synthesised from the previous