add some more documentation

some of the layout is based on what darcs-buildpackage does

16 files changed, 332 insertions, 16 deletions

diff --git a/debian/changelog b/debian/changelog
index 280f333f..19e961ea 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+git-buildpackage (0.2.20) unstable; urgency=low
+
+  * add some more documentation
+
+ -- Guido Guenther <agx@sigxcpu.org>  Fri, 22 Dec 2006 15:05:09 +0100
+
 git-buildpackage (0.2.19) unstable; urgency=low
 
   * git-buildpackage: add an option (--git-cleaner) that allows to specify
diff --git a/debian/docs b/debian/docs
index e845566c..7fdec518 100644
--- a/debian/docs
+++ b/debian/docs
@@ -1 +1,2 @@
 README
+docs/manual-html/
diff --git a/debian/links b/debian/links
new file mode 100644
index 00000000..803c8fee
--- /dev/null
+++ b/debian/links
@@ -0,0 +1 @@
+/usr/share/doc/git-buildpackage/manual-html/gbp.html /usr/share/doc/git-buildpackage/manual-html/index.html
diff --git a/debian/rules b/debian/rules
index 6ea935f3..4cea6597 100755
--- a/debian/rules
+++ b/debian/rules
@@ -9,17 +9,23 @@ include /usr/share/cdbs/1/class/python-distutils.mk
 
 COMMANDS=git-buildpackage git-import-dsc git-import-orig
 MANPAGES=$(patsubst %,docs/%.1,$(COMMANDS))
+MANUAL=docs/manual-html
 PYCHECKS=$(patsubst %,%.py,$(COMMANDS))
 PYCHECK_LEVEL=Error
 
 docs/%.1: docs/man.%.sgml
 	docbook-to-man $< > $@
 
+$(MANUAL): docs/manual.sgml docs/chapters/*.sgml docs/manpages/*.sgml
+	docbook-2-html -s gtk $<
+
 %.py: %
 	ln -s $< $@
 	PYTHONPATH=. pychecker -e $(PYCHECK_LEVEL) -q $<
 
-build/git-buildpackage:: $(MANPAGES) $(PYCHECKS)
+build/git-buildpackage:: $(MANPAGES) $(MANUAL) $(PYCHECKS)
 
 clean::
-	-rm docs/*.1 git-*.py
+	-rm docs/*.1  git-*.py
+	-rm -rf docs/manual-html/
+
diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
new file mode 100644
index 00000000..6cba1aeb
--- /dev/null
+++ b/docs/chapters/building.sgml
@@ -0,0 +1,4 @@
+<chapter id="gbp.building">
+    <title>Building Packages from the &git; repository</title>
+    <para>TBD</para>
+</chapter>
diff --git a/docs/chapters/chapters.ent b/docs/chapters/chapters.ent
new file mode 100644
index 00000000..eaa7e712
--- /dev/null
+++ b/docs/chapters/chapters.ent
@@ -0,0 +1,5 @@
+<!ENTITY ch.intro SYSTEM "intro.sgml">
+<!ENTITY ch.workflow SYSTEM "workflow.sgml">
+<!ENTITY ch.import SYSTEM "import.sgml">
+<!ENTITY ch.building SYSTEM "building.sgml">
+<!ENTITY ch.special SYSTEM "special.sgml">
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
new file mode 100644
index 00000000..7e54ed58
--- /dev/null
+++ b/docs/chapters/import.sgml
@@ -0,0 +1,69 @@
+<chapter id="gbp.import">
+    <title>Importing Sources</title>
+    <sect1 id="dbp.import.existing">
+    <title>Importing already existing &debian; packages</title>
+    <para>Imporing an already exsting debian package into a git repository is as easy as:
+    <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
+    used.
+    </para>
+    </sect1>
+    <sect1 id="dbp.import.new.upstream">
+    <title>Importing a new upstream version</title>
+    <para>Change into your git repository, make sure it has all local
+    modifications committed and do:
+    <screen>
+&git-import-orig; /path/to/package_0.2.orig.tar.gz
+    </screen>
+    </para>
+    </sect1>
+    <sect1 id="dbp.import.convert">
+    <title>Converting an existing &git; repository</title>
+    <sect2>
+    <title>Upstream sources on a branch</title>
+    <para>
+    If the upstream sources are already on a separate branch things are pretty
+    simple. You can either rename that branch to <emphasis>upstream</emphasis>
+    with:
+    <screen>
+mv .git/theupstream-branch .git/upstream
+    </screen> 
+    or you can tell &git-buildpackage; the name of the branch:
+    <screen>
+cat &lt;&lt;EOF &gt; <filename>.git/gbp.conf</filename>
+[DEFAULT]
+# this is the upstream-branch:
+upstream-branch=theupstream-branch
+    </screen>
+    If you use &git-import-orig; to import new upstream sources, they will
+    end up on <emphasis>theupstream-branch</emphasis> and merged to
+    <emphasis>master</emphasis>.
+    </para>
+    </sect2>
+    <sect2>
+    <title>Upstream sources not on a branch</title>
+    <para>
+    If you don't have an upstream branch but started you repository with only
+    the upstream sources (not the debian patch) you can simply branch from that
+    point. So use &gitkcmd; or &gitcmd;-log to locate the commit-id of that commit
+    and create the upstream branch from there, e.g.:
+<screen>
+    COMMIT_ID=`&gitcmd; log --pretty=oneline | tail -1 | awk '{ print $1 }'`
+    &gitcmd; branch upstream $COMMIT_ID
+</screen>
+    The important thing here is that the <envar>COMMIT_ID</envar> specifies a
+    point on the master branch that carried <emphasis>only</emphasis> the
+    upstream sources and not the debian modifications. The above example
+    assumes that this was the first commit to that repository.
+    </para>
+    <warning><para>There's currently no easy way to use &git-import-orig; with
+    a repository that never had the upstream sources as a single commit. Using
+    it on such repositories might lead to unexpected merge results. You can use
+    <command>git_load_dirs</command> instead.</para></warning>
+    </sect2>
+    </sect1>
+</chapter>
diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml
new file mode 100644
index 00000000..b1fb35e2
--- /dev/null
+++ b/docs/chapters/intro.sgml
@@ -0,0 +1,51 @@
+<chapter id="gbp.intro">
+    <title>Introduction</title>
+    <para>
+      Welcome to &git-buildpackage;, a system that integrates the
+      <ulink url="http://www.debian.org/">Debian</ulink> package build
+      system with <ulink url="http://git.or.cz/">Git</ulink>.
+    </para>
+
+<sect1 id="gbp.repository">
+	<title>Repository Layout</title>
+	<para>
+	Since &git; knows about branches (and in fact handles them very well)
+	the git repository usually looks like: a so called
+	<emphasis>master</emphasis> branch (the default branch) holds your
+	current development work. Another branch called
+	<emphasis>upstream</emphasis> holds the upstream sources. Other
+	branches like <emphasis>nmu</emphasis> or
+	<emphasis>dfsg_free</emphasis> might help with certain kinds of
+	packages.  Git-Buildpackage currently only works with your local
+	git-repository, in order to publish your changes simply use
+	<command>git-push</command>.
+	</para>
+</sect1> 
+
+<sect1 id="gbp.workflow">
+    <title>Workflow</title>
+    <para>
+    	A typical workflow consists of the following steps:
+    </para>
+    <orderedlist>
+	<listitem><para>Import a Debian package via &git-import-dsc;. This
+	imports the &debian; Package on the master branch and the upstream
+	sources on the upstream branch.</para></listitem>
+	<listitem><para>Develop, test, commit changes. During this time you can
+	always build the package with &git-buildpackage; In case you have
+	uncommitted changes in your source tree you can use the
+	<option>--git-ignore-new</option> option.</para></listitem>
+	<listitem><para>Once satisfied you can build the final package with
+	&git-buildpackage; <option>--git-tag</option>. This
+	additionally creates a tag within &git; so you can switch back to that
+	version later at any time.</para></listitem>
+	<listitem><para>When a new upstream version is released you can import
+	this via &git-import-orig; onto the upstream branch.
+	&git-import-orig; will also try to merge the new upstream version onto
+	the master branch. After resolving any potential conflicts go back to 2.
+	</para></listitem>
+    </orderedlist>
+    <para>These steps will be explaind in more details in the following sections.</para>
+</sect1>
+
+</chapter>
diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
new file mode 100644
index 00000000..03de2ec1
--- /dev/null
+++ b/docs/chapters/special.sgml
@@ -0,0 +1,104 @@
+<chapter id="gbp.special">
+    <title>Special usage cases</title>
+    <sect1 id="dbp.special.dfsgfree">
+    <title>Handling non-DFSG clean upstream sources</title>
+    <para>If you have to handle non DFSG clean upstream sources you can use a
+    different branch which you have to create once:
+    <screen>
+&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
+    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:
+    </para>
+    <screen>
+&git-import-orig; --no-merge nondfsg-clean-package_10.4.orig.tar.gz
+&gitcmd; tag; 10.4
+    </screen>
+    <para>
+    After the import you can switch to the dfsg branch and get the newly
+    imported changes from the upstream branch:
+    </para>
+    <screen>
+&gitcmd; checkout dfsg_clean
+&gitcmd; pull . upstream
+    </screen>
+    <para>
+    Now make this dfsg clean (preverably by a cleanup script), commit your changes and merge to the master branch:
+    </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
+    </screen>
+
+    <sect1 id="dbp.special.nmus">
+    <title>Importing NMUs</title>
+    <para>
+    First create a branch that holds the NMUs once:
+    </para>
+    <screen>
+&gitcmd; <option>branch</option> <replaceable>nmu</replaceable>
+    </screen>
+    <para>
+    To import an NMU instead of a new upstream version you can use:
+    </para>
+    <screen>
+&gitcmd; checkout master
+&git-import-orig; -u 10-1.1 --upstream-branch=nmu nmu-10-1.1.tar.gz
+    </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.
+    </para>
+    <note>
+    <para>
+    You need to have the NMU as a single tar.gz, you can't use the
+    dsc and diff.gz here, this will be fixed in a later version.
+    <para>
+    </note>
+    </sect1>
+
+    <sect1 id="dbp.special.pbuilder">
+    <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
+    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 "$*"
+EOF
+chmod a+x /usr/local/bin/git-pbuilder
+</programlisting>
+
+    Furthermore we need a different clean command, since &pdebuildcmd;
+    <option>clean</option> means something different than &debuildcmd;
+    <option>clean</option>. We could put all this on the command line, but
+    let's put it into the config file to safe typing:
+
+<programlisting>
+cat &lt;&lt;EOF &gt; <filename>~/.gbp.conf</filename>
+[DEFAULT]
+# tell git-buildpackage howto clean the source tree
+cleaner = fakeroot debian/rules clean
+# this is how we invoke pbuilder, arguments passed to git-buildpackage will be
+# passed to dpkg-buildpackge in the chroot
+builder = /usr/local/bin/git-pbuilder
+</programlisting>
+	
+     Invoking &git-buildpackage; will now invoke &pdebuildcmd;</para>
+     <para>
+     If you don't want this for all your invocations of &git-buildpackage; you can instead
+     put this into <filename>.git/gbp.conf</filename> in one of your &git; repositories.
+    </para>
+
+</chapter>
diff --git a/docs/common.ent b/docs/common.ent
index f3f4fb64..f091df77 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -3,14 +3,21 @@
   <!ENTITY dhdate      		"<date>2006-10-02</date>">
   <!ENTITY dhsection   		"<manvolnum>1</manvolnum>">
   <!ENTITY dhemail     		"<email>agx@sigxcpu.org</email>">
-  <!ENTITY dhusername  		"&dhfirstname; &dhsurname">
+  <!ENTITY dhusername  		"Guido Guenther">
   <!ENTITY git-buildpackage 	"<command>git-buildpackage</command>">
   <!ENTITY git-import-orig	"<command>git-import-orig</command>">
   <!ENTITY git-import-dsc	"<command>git-import-dsc</command>">
   <!ENTITY gitcmd		"<command>git</command>">
+  <!ENTITY gitkcmd		"<command>gitk</command>">
+  <!ENTITY pbuildercmd		"<command>pbuilder</command>">
+  <!ENTITY pdebuildcmd		"<command>pdebuild</command>">
+  <!ENTITY debuildcmd		"<command>debuild</command>">
 
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY git	       "<productname>Git</productname>">
+  <!ENTITY pbuilder    "<productname>Pbuilder</productname>">
+  <!ENTITY debuild     "<productname>Debuild</productname>">
+  <!ENTITY dpkg-buildpackage "<productname>Dpkg-buildpackage</productname>">
   <!ENTITY gnu         "<acronym>GNU</acronym>">
   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
 
diff --git a/docs/copyright.sgml b/docs/copyright.sgml
new file mode 100644
index 00000000..f9ea8515
--- /dev/null
+++ b/docs/copyright.sgml
@@ -0,0 +1,22 @@
+  <para>
+    git-buildpackage, all associated scripts and programs, this manual,
+    and all build scripts are Copyright &copy; 2006 Guido Guenther.
+  </para>
+      <para>
+        This program is free software; you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation; Version 2 of the License.
+      </para>
+
+      <para>
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU General Public License for more details.
+      </para>
+
+      <para>
+        You should have received a copy of the GNU General Public License
+        along with this program; if not, write to the Free Software
+        Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+      </para>
diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml
index 70c1dfda..a221f906 100644
--- a/docs/manpages/git-buildpackage.sgml
+++ b/docs/manpages/git-buildpackage.sgml
@@ -106,7 +106,7 @@
         <term><option>--git-upstream-branch</option>=<replaceable>branch_name</replaceable>
         </term>
         <listitem>
-	  <para>Branch to build the orig.tar.gz from. Default is 'upstream'</para>
+	  <para>Branch to build the orig.tar.gz from. Default is <replaceable>upstream</replaceable></para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -114,8 +114,8 @@
         </term>
         <listitem>
 	  <para>If you're not on this branch when invoking &git-buildpackage;
-	  it will fail. Default is 'master'.  This option will be ignored
-	  when using <option>--git-ignore-new</option>.
+	  it will fail. Default is <replaceable>master</replaceable>.  This
+	  option will be ignored when using <option>--git-ignore-new</option>.
 	  </para>
         </listitem>
       </varlistentry>
@@ -123,7 +123,7 @@
   </refsect1>
   <refsect1>
       &man.git.config-files;
-      <para>All options in the config files are specified without the 'git-' prefix.
+      <para>All options in the config files are specified without the 'git-' prefix.</para>
   <refsect1>
     <title>SEE ALSO</title>
 
diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml
index 42c0fa7e..656f6498 100644
--- a/docs/manpages/git-import-dsc.sgml
+++ b/docs/manpages/git-import-dsc.sgml
@@ -50,7 +50,8 @@
         <term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
         </term>
         <listitem>
-	  <para>The branch in the Git repository the upstream sources are put onto. Default is 'upstream'</para>
+	  <para>The branch in the Git repository the upstream sources are put
+	  onto. Default is <replaceable>upstream</replaceable></para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml
index 7bc169a7..979bf61a 100644
--- a/docs/manpages/git-import-orig.sgml
+++ b/docs/manpages/git-import-orig.sgml
@@ -39,7 +39,7 @@
     <title>DESCRIPTION</title>
     <para>
     &git-import-orig; imports a tar.gz file given by
-    <replaceable>tar_gz<replaceable> into the git-buildpackage repository. If
+    <replaceable>tar_gz</replaceable> into the git-buildpackage repository. If
     <replaceable>tar_gz</replaceable> is already of the form
     package_version.orig.tar.gz, it reads the version information from the
     tarball's filename otherwise it can be specified on the commandline.
@@ -64,7 +64,8 @@
         <term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
         </term>
         <listitem>
-	  <para>The branch in the Git repository the upstream sources are put onto. Default is 'upstream'</para>
+	  <para>The branch in the Git repository the upstream sources are put
+	  onto. Default is <replaceable>upstream</replaceable></para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -72,9 +73,9 @@
         </term>
         <listitem>
 	  <para>The branch in the Git repository the Debian package is being
-	  developed on, default is 'master'. After importing the new sources on
-	  the upstream branch, &git-import-orig; will try to merge the new
-	  version onto this branch.</para>
+	  developed on, default is <replaceable>master</replaceable>. After
+	  importing the new sources on the upstream branch, &git-import-orig;
+	  will try to merge the new version onto this branch.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 43f2a241..3e4e2205 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -3,8 +3,8 @@
 <!ENTITY man.git.buildpackage SYSTEM "git-buildpackage.sgml">
 <!ENTITY man.git.config-files "
     <title>CONFIGURATION FILES</title>
-    Three configuration files are parsed to set defaults for the above
-    commandline arguments:
+    <para> Three configuration files are parsed to set defaults for the above
+    commandline arguments: </para>
     <variablelist>
       <varlistentry>
       <term>/etc/git-buildpacakge/gbp.conf</term>
@@ -20,5 +20,5 @@
       </varlistentry> 
     </variablelist>
       <para>
-      See /etc/git-buildpacakge/gbp.conf for an example.
+      See /etc/git-buildpackage/gbp.conf for an example.
       </para>">
diff --git a/docs/manual.sgml b/docs/manual.sgml
new file mode 100644
index 00000000..b3c5fd11
--- /dev/null
+++ b/docs/manual.sgml
@@ -0,0 +1,38 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+  <!ENTITY % CHAPTERS SYSTEM "chapters/chapters.ent">
+  %CHAPTERS;
+  <!ENTITY gbp.copyright SYSTEM "copyright.sgml">
+]>
+
+<book id="gbp">
+  <bookinfo>
+    <title>Building Debian Packages with git-buildpackage</title>
+    <author>
+      &dhfirstname; &dhsurname; 
+    </author>
+    <address>&dhemail;</address>
+  </bookinfo>
+
+  &ch.intro;
+  &ch.import;
+<!---
+  &ch.building;
+-->
+  &ch.special;
+
+  <appendix id="gbp.man.reference">
+    <title>Command Reference</title>
+    &man.git.buildpackage;
+    &man.git.importdsc;
+    &man.git.importorig;
+  </appendix>
+  <appendix id="gbp.copyleft">
+    <title>Copyright</title>
+    &gbp.copyright;
+  </appendix>
+</book>
+