documentation updates

11 files changed, 114 insertions, 28 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">
diff --git a/docs/common.ent b/docs/common.ent
index 70bf212f..7c4d38da 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -2,7 +2,7 @@
   <!ENTITY dhsurname   		"<surname>Guenther</surname>">
   <!ENTITY dhdate      		"<date>2006-10-02</date>">
   <!ENTITY dhsection   		"<manvolnum>1</manvolnum>">
-  <!ENTITY dhemail     		"<email>&lt;agx@sigxcpu.org&gt;</email>">
+  <!ENTITY dhemail     		"<email>agx@sigxcpu.org</email>">
   <!ENTITY dhusername  		"Guido Guenther">
   <!ENTITY git-buildpackage 	"<command>git-buildpackage</command>">
   <!ENTITY git-import-orig	"<command>git-import-orig</command>">
@@ -16,8 +16,9 @@
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY git	       "<productname>Git</productname>">
   <!ENTITY pbuilder    "<productname>Pbuilder</productname>">
+  <!ENTITY gitloaddirs "<productname>Git_load_dirs</productname>">
   <!ENTITY debuild     "<productname>Debuild</productname>">
+  <!ENTITY gpg 	       "<productname>GPG</productname>">
   <!ENTITY dpkg-buildpackage "<productname>Dpkg-buildpackage</productname>">
   <!ENTITY gnu         "<acronym>GNU</acronym>">
   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
-
diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml
index 6a9deadf..ea7db3e1 100644
--- a/docs/manpages/git-buildpackage.sgml
+++ b/docs/manpages/git-buildpackage.sgml
@@ -7,11 +7,6 @@
       &dhfirstname;
       &dhsurname;
     </author>
-    <copyright>
-      <year>2006</year>
-      <holder>&dhusername;</holder>
-    </copyright>
-    &dhdate;
   </refentryinfo>
   <refmeta>
     <refentrytitle>git-buildpackage</refentrytitle>
diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml
index 06b01650..cc56761f 100644
--- a/docs/manpages/git-import-dsc.sgml
+++ b/docs/manpages/git-import-dsc.sgml
@@ -7,11 +7,6 @@
       &dhfirstname;
       &dhsurname;
     </author>
-    <copyright>
-      <year>2006</year>
-      <holder>&dhusername;</holder>
-    </copyright>
-    &dhdate;
   </refentryinfo>
   <refmeta>
     <refentrytitle>git-import-dsc</refentrytitle>
diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml
index eb551edc..f223b0f4 100644
--- a/docs/manpages/git-import-orig.sgml
+++ b/docs/manpages/git-import-orig.sgml
@@ -7,11 +7,6 @@
       &dhfirstname;
       &dhsurname;
     </author>
-    <copyright>
-      <year>2006</year>
-      <holder>&dhusername;</holder>
-    </copyright>
-    &dhdate;
   </refentryinfo>
   <refmeta>
    <refentrytitle>git-import-orig</refentrytitle> 
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 3e4e2205..99ff76ec 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -7,7 +7,7 @@
     commandline arguments: </para>
     <variablelist>
       <varlistentry>
-      <term>/etc/git-buildpacakge/gbp.conf</term>
+      <term>/etc/git-buildpackage/gbp.conf</term>
       <listitem><para>system wide configuraton</para></listitem>
       </varlistentry>
       <varlistentry>
diff --git a/docs/manual.sgml b/docs/manual.sgml
index b3c5fd11..0ffbe3fe 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -19,9 +19,8 @@
 
   &ch.intro;
   &ch.import;
-<!---
   &ch.building;
--->
+  &ch.cfgfile;
   &ch.special;
 
   <appendix id="gbp.man.reference">
diff --git a/gbp.conf b/gbp.conf
index e8ed3b14..02357fac 100644
--- a/gbp.conf
+++ b/gbp.conf
@@ -6,14 +6,14 @@
 # the default branch for upstream sources
 #upstream-branch=upstream
 # the default branch for the debian patch
-#debian-branch=debian
+#debian-branch=master
 
 # Special options for git-buildpackage
 [git-buildpackage]
 #upstream-branch=dfsgclean
-# Uncomment this to automatically sign tags
+# Uncomment this to automatically GPG sign tags
 #sign-tags = True
-# Keyid to sign tags with
+# Keyid to GPG sign tags with
 #keyid = 0xdeadbeef
 
 # Special options for git-import-orig