documentation updates

4 files changed, 106 insertions, 5 deletions

diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
index 6cba1aeb..13969231 100644
--- a/docs/chapters/building.sgml
+++ b/docs/chapters/building.sgml
@@ -1,4 +1,21 @@
 <chapter id="gbp.building">
-    <title>Building Packages from the &git; repository</title>
-    <para>TBD</para>
+    <title>Building packages from the &git; repository</title>
+    <para>
+    In order to build a &debian; package from the &git; repository you use:
+    &git-buildpackage;. During the development phase (when you're either not
+    on the <emphasis>master</emphasis>-branch or when you have uncommitted
+    changes in your repository) you'll usually use:
+<screen>
+&git-buildpackage; <option>--git-ignore-new</option>
+</screen>
+    Once you're satisfied with the build and want to do a relese you commit all
+    you changes and issue:
+<screen>
+&git-buildpackage; <option>--git-tag</option>
+</screen>
+    This will again build the debian package and tag the final result after
+    extracting the current version from the changelog. If you want &gpg; signed
+    tags you can use the <option>--git-sign</option> and
+    <option>--git-keyid</option> options.
+    </para>
 </chapter>
diff --git a/docs/chapters/cfgfile.sgml b/docs/chapters/cfgfile.sgml
new file mode 100644
index 00000000..990d68e1
--- /dev/null
+++ b/docs/chapters/cfgfile.sgml
@@ -0,0 +1,75 @@
+<chapter id="gbp.cfgfile">
+    <title>Configuration files</title>
+    <para>Three configuration files a parsed in this order:
+    <variablelist>
+      <varlistentry>
+      <term>/etc/git-buildpackage/gbp.conf</term>
+      <listitem><para>system wide configuraton</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>~/.gbp.conf</term>
+      <listitem><para>per user configuration</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>.git/gbp.conf</term>
+      <listitem><para>per repository configuration</para></listitem> 
+      </varlistentry> 
+    </variablelist>
+    All three have the same format. They consist of (at most) four sections, all of them are optional:
+    <variablelist>
+      <varlistentry>
+      <term>[DEFAULT]</term>
+      <listitem><para>Options in this section apply to &git-buildpackage;,
+      &git-import-orig; and &git-import-dsc;.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>[git-buildpackage]</term>
+      <listitem><para>Options in this section apply to &git-buildpackage; only and override options from the
+      [DEFAULT] section.</listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>[git-import-orig]</term>
+      <listitem><para>Options in this section apply to &git-import-orig; only and override options from the
+      [DEFAULT] section.</listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>[git-import-dsc]</term>
+      <listitem><para>Options in this section apply to &git-import-dsc; only and override options from the
+      [DEFAULT] section.</listitem>
+      </varlistentry>
+    </variablelist>
+    The actual options in these sections are the command line options without
+    the '--' prefix. So <option>--upstream-branch=</option><replaceable>dfsgfree</replaceable> would read:
+<screen>
+<option>upstream-branch</option>=<replaceable>dfsgfree</replaceable>
+</screen>
+    in the config file. In the special case of &git-buildpackage; the stripped
+    prefix is not '--' but '--git-'.
+    Here's a full example:
+<screen>
+[DEFAULT]
+# the default build command
+builder=debuild
+# the default branch for upstream sources
+upstream-branch=upstream
+# the default branch for the debian patch
+debian-branch=master
+
+# Special options for git-buildpackage
+[git-buildpackage]
+upstream-branch=dfsgclean
+# Sign tags with GPG:
+sign-tags = True
+# Keyid to sign tags with
+#keyid = 0xdeadbeef
+
+# Special options for git-import-orig
+[git-import-orig]
+upstream-branch=notdfsgclean
+
+# Special options for git-import-dsc
+[git-import-dsc]
+upstream-branch=notdfsgclean
+</screen>
+    </para>
+</chapter>
diff --git a/docs/chapters/chapters.ent b/docs/chapters/chapters.ent
index eaa7e712..68fea426 100644
--- a/docs/chapters/chapters.ent
+++ b/docs/chapters/chapters.ent
@@ -2,4 +2,5 @@
 <!ENTITY ch.workflow SYSTEM "workflow.sgml">
 <!ENTITY ch.import SYSTEM "import.sgml">
 <!ENTITY ch.building SYSTEM "building.sgml">
+<!ENTITY ch.cfgfile SYSTEM "cfgfile.sgml">
 <!ENTITY ch.special SYSTEM "special.sgml">
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index b91298a0..1b754d63 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -6,10 +6,12 @@
     <screen>
 &git-import-dsc; package_0.1-1.dsc
     </screen>
-    This will put the upstream sources onto the <option>upstream</option>
-    branch and the debian patch on the <option>master</option> branch. In case
-    of a debian native package only the <option>master</option> branch is being
+    This will put the upstream sources onto the <emphasis>upstream</emphasis>
+    branch and the debian patch on the <emphasis>master</emphasis> branch. In case
+    of a debian native package only the <emphasis>master</emphasis> branch is being
     used.
+    You can specify different branch names via the
+    <option>--upstream-branch</option> and <option>--debian-branch</option> options.
     </para>
     </sect1>
     <sect1 id="gbp.import.new.upstream">
@@ -19,6 +21,12 @@
     <screen>
 &git-import-orig; /path/to/package_0.2.orig.tar.gz
     </screen>
+    This puts the upstream souces onto the <emphasis>upsream</emphasis> branch
+    using &git_load_dirs; to handle file removals and renames. The result of
+    this is then merged onto the <emphasis>master</emphasis> branch and a new
+    changelog entry gets created. You can again specify different branch names
+    via the <option>--upstream-branch</option> and
+    <option>--debian-branch</option> options.
     </para>
     </sect1>
     <sect1 id="gbp.import.convert">