Documentation updates

1 files changed, 37 insertions, 33 deletions

diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
index fcf46c2..3ab3bc3 100644
--- a/docs/chapters/special.sgml
+++ b/docs/chapters/special.sgml
@@ -8,55 +8,59 @@
 &gitcmd; branch dfsg_clean upstream
     </screen>
     <para>
-    This creates the <emphasis>dfsg_clean</emphasis> branch from the tip of
-    your <emphasis>upstream</emphasis> branch.  Then, when importing a new
+    This creates the <emphasis>dfsg_clean</emphasis> branch from the tip of a
+    branch called <emphasis>upstream</emphasis>.  Then, when importing a new
     upstream version, you import the new version on the
-    <emphasis>upstream</emphasis> branch as usual and just don't merge to the
-    master branch by default:
+    <option>upstream-branch</option> (by default named
+    <emphasis>upstream</emphasis>) as usual and just don't merge to the
+    <emphasis>debian-branch</emphasis>  (by default named
+    <emphasis>master</emphasis>):
     </para>
     <screen>
-&git-import-orig; --no-merge nondfsg-clean-package_10.4.orig.tar.gz
-&gitcmd; tag 10.4
+&git-import-orig; --no-merge <filename>/path/to/nondfsg-clean-package_10.4.orig.tar.gz</filename>
+&gitcmd; <option>tag</option> 10.4
     </screen>
     <para>
-    After the import you can switch to the dfsg branch and get the newly
-    imported changes from the upstream branch:
+    After the import you can switch to the <emphasis>dfsg_clean</emphasis>
+    branch and get the newly imported changes from the upstream branch:
     </para>
     <screen>
-&gitcmd; checkout dfsg_clean
-&gitcmd; pull . upstream
+&gitcmd; <option>checkout</option> dfsg_clean
+&gitcmd; <option>pull</option> <filename>.</filename> upstream
     </screen>
-    <para>
-    Now make this dfsg clean (preverably by a cleanup script), commit your changes and merge to the master branch:
-    </para>
+    <para>Now make this checkout dfsg clean (preverably by a cleanup script), commit
+    your changes and merge to your <option>debian-branch</option>:</para>
     <screen>
 cleanup-script.sh
 &gitcmd; commit -a -m "Make source dfsg clean"
-&gitcmd; tag 10.4.dfsg
-&gitcmd; checkout master
-&gitcmd; pull . dfsg_clean
+&gitcmd; tag <replaceable>10.4.dfsg</replaceable>
+&gitcmd; checkout <replaceable>master</replaceable>
+&gitcmd; pull <replaceable>.</replaceable> <replaceable>dfsg_clean</replaceable>
     </screen>
 
     <sect1 id="gbp.special.nmus">
     <title>Importing NMUs</title>
     <para>
-    First create a branch that holds the NMUs once:
+    First create a branch that holds the NMUs from the tip of your
+    <option>debian-branch</option> (default is <emphasis>master</emphasis>) once:
     </para>
     <screen>
-&gitcmd; <option>branch</option> <replaceable>nmu</replaceable>
+&gitcmd; <option>branch</option> <replaceable>nmu</replaceable> <replaceable>master</replaceable>
     </screen>
     <para>
     To import an NMU instead of a new upstream version simply import the
-    unpacked NUMs source tree into your repository:
+    unpacked NUMs source tree into your repository using &git-import-orig:
     </para>
     <screen>
-&gitcmd; checkout master
-&git-import-orig; -u 10-1.1 --upstream-branch=nmu /path/to/nmu-10/
+&gitcmd; checkout <replaceable>master</replaceable>
+&git-import-orig; <option>-u</option> <replaceable>10-1.1</replaceable> <option>--upstream-branch</option>=<replaceable>nmu</replaceable> <filename>/path/to/nmu-10/</filename>
     </screen>
     <para>
-    This will import the NMU on the <emphasis>nmu</emphasis> branch instead of
-    the <emphasis>upstream</emphasis> branch but merge the changes to the
-    <emphasis>master</emphasis> branch as usual.
+    This will import the NMU onto the branched named <emphasis>nmu</emphasis> branch instead of
+    the default <option>upstream-branch</option> and merge the changes to the
+    <option>debian-branch</option> as usual. This method can also be used to
+    import "old" releases into the &git; repository when migrating to &git; from
+    another VCS.
     </para>
     </sect1>
 
@@ -64,15 +68,15 @@ cleanup-script.sh
     <title>Using &pbuilder;</title>
     <para>
     Since pbuilder use different command line arguments than
-    &debuild; and &dpkg-buildpackage; we have to use a small script that's
+    &debuild; and &dpkg-buildpackage; we have to use a tiny script that gets
     invoked by &git-buildpackage;:
 <programlisting>
 cat &lt;&lt;EOF &gt;/usr/local/bin/git-pbuilder
 #!/bin/sh
 # pass all options to dpkg-buildpackage:
-pdebuild --debbuildopts "-i\.git -I.git $*"
+<command>pdebuild</command> <option>--debbuildopts</option> "-i\.git -I.git $*"
 EOF
-chmod a+x /usr/local/bin/git-pbuilder
+<command>chmod</command> a+x /usr/local/bin/git-pbuilder
 </programlisting>
 
     Furthermore we need a different clean command, since &pdebuildcmd;
@@ -100,7 +104,7 @@ builder = /usr/local/bin/git-pbuilder
     <title>Working on random packages</title>
     <para>
     Whenever you need to work on an arbitrary Debian package you can check it
-    right into &git;:
+    right into &git; with one command:
 <programlisting>
 apt-get source --download-only <filename>package</filename>
 git-import-dsc <filename>package</filename>*.dsc
@@ -108,11 +112,11 @@ cd <filename>package</filename>
 git-branch debian
 </programlisting>
     <para>
-    This puts the orig.tar.gz onto the <emphasis>upstream</emphasis> branch and
-    the Debian patch onto branch <emphasis>debian</emphasis>. Now you can
-    easily modify the package on the master branch, revert changes you made,
-    create other branches for testing, see what changes you made, etc.. When
-    finished just do</para>
+    This puts the orig.tar.gz onto the <option>upstream-branch</option> and
+    the Debian patch onto a branch called <emphasis>debian</emphasis>. Now you
+    can easily modify the package, revert changes you made, create other
+    branches for testing, see what changes you made, etc..  When finished just
+    do</para>
 <programlisting>
 git-commit -a
 git-diff debian --