Add manual page for gbp.conf

Closes: #661748
Thanks: Jari Alto for the POD version

7 files changed, 254 insertions, 6 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 8772f472..b10ec10f 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,6 +1,6 @@
 #!/usr/bin/make
 
-COMMANDS = git-buildpackage  \
+MANS = git-buildpackage  \
            git-import-dsc    \
            git-import-dscs   \
            git-import-orig   \
@@ -8,10 +8,11 @@ COMMANDS = git-buildpackage  \
            gbp-pull          \
            gbp-clone         \
            gbp-pq            \
-           gbp-create-remote-repo
+           gbp-create-remote-repo \
+           gbp.conf
 
 MANUAL=manual-html
-SGML_MANPAGES=$(patsubst %,%.1,$(COMMANDS))
+SGML_MANPAGES=$(patsubst %,%.1,$(MANS))
 POD_MANPAGES=git-pbuilder.1
 MANPAGES=$(SGML_MANPAGES) $(POD_MANPAGES)
 VERSION_ENT=version.ent
diff --git a/docs/chapters/cfgfile.sgml b/docs/chapters/cfgfile.sgml
index d7c7a0da..fbff9e05 100644
--- a/docs/chapters/cfgfile.sgml
+++ b/docs/chapters/cfgfile.sgml
@@ -12,7 +12,7 @@
       </varlistentry>
       <varlistentry>
       <term>.gbp.conf</term>
-      <listitem><para>per repository/branch configuration</para></listitem> 
+      <listitem><para>per repository/branch configuration (deprecated)</para></listitem> 
       </varlistentry> 
       <varlistentry>
       <term>debian/gbp.conf</term>
@@ -23,7 +23,7 @@
       <listitem><para>per (local) repository configuration</para></listitem> 
       </varlistentry> 
     </variablelist>
-    All have the same format. They consist of (at most) five sections, all of them are optional:
+    All have the same format. They consist of several sections, all of them are optional:
     <variablelist>
       <varlistentry>
       <term>[DEFAULT]</term>
@@ -50,14 +50,20 @@
       <listitem><para>Options in this section apply to &git-dch; only and override options from the
       [DEFAULT] section.</para></listitem>
       </varlistentry>
+      <varlistentry>
+      <term>...</term>
+      <listitem><para>Same for the other <command>git-*</command> and <command>gbp-*</command> commands</para></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>
+<para>
     in the config file. In the special case of &git-buildpackage; the stripped
     prefix is not '--' but '--git-'. Here's a more complete example:
+</para>
 <programlisting>
 [DEFAULT]
 # the default build command
@@ -83,5 +89,7 @@ upstream-branch=notdfsgclean
 [git-dch]
 git-log=--no-merges
 </programlisting>
-    </para>
+<para>
+For more details see the <xref linkend="gbp.man.gbp.conf"> manual page.
+</para>
 </chapter>
diff --git a/docs/common.ent b/docs/common.ent
index 735511ae..9c1b2894 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -17,6 +17,7 @@
   <!ENTITY pbuildercmd		"<command>pbuilder</command>">
   <!ENTITY pdebuildcmd		"<command>pdebuild</command>">
   <!ENTITY debuildcmd		"<command>debuild</command>">
+  <!ENTITY gbp.conf		"<filename>gbp.conf</filename>">
 
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY git	       "<productname>Git</productname>">
diff --git a/docs/man.gbp.conf.sgml b/docs/man.gbp.conf.sgml
new file mode 100644
index 00000000..c01433fe
--- /dev/null
+++ b/docs/man.gbp.conf.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+]>
+
+<reference>
+<title>gbp.conf Manual</title>
+&man.gbp.conf;
+</reference>
diff --git a/docs/manpages/gbp.conf.sgml b/docs/manpages/gbp.conf.sgml
new file mode 100644
index 00000000..d3f7d6ad
--- /dev/null
+++ b/docs/manpages/gbp.conf.sgml
@@ -0,0 +1,225 @@
+<refentry id="gbp.man.gbp.conf">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta>
+   <refentrytitle>gbp.conf</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>&gbp.conf;</refname>
+    <refpurpose>git-buildpackage configuration file</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+   <variablelist>
+      <varlistentry>
+      <term>/etc/git-buildpackage/gbp.conf</term>
+      <listitem><para>system wide</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>~/.gbp.conf</term>
+      <listitem><para>per user</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>.gbp.conf</term>
+      <listitem><para>per branch, can be published with the
+      repository (deprecated)</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>debian/gbp.conf</term>
+      <listitem><para>per branch, can be published with the
+      repository</para></listitem>
+      </varlistentry>
+      <varlistentry>
+      <term>.git/gbp.conf</term>
+      <listitem><para>per repository</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+      The <filename>gbp.conf</filename> provides default global options and specific options
+      for &git-buildpackage; commands. All have the same format and are parsed in the above order. The
+      file consists of several sections, one for each command. Comments start with a hash sign
+      (<option>#</option>). The generic file syntax is:
+    </para>
+<programlisting>
+    [DEFAULT]
+    # This is section for global settings. Affects all commands
+    key = value
+
+    [&lt;command&gt;]
+    # Specific sections for each command, like &git-buildpackage;
+    key = value
+</programlisting>
+
+<para>
+
+<option>key=value</option> pairs of the command sections reflect the command line
+options and their settings. For example <xref linkend="gbp.man.git.buildpackage">
+manualpage contains the <option>--git-export-dir</option>=<parameter>diirectory</parameter>
+option which can be turned into configuration file setting by dropping the
+<option>--git</option> prefix with:
+
+<programlisting>
+    [git-buildpackage]
+    export-dir = directory
+</programlisting>
+
+<para>
+Notice that some option are actually repeatable, or take Python lists.
+For example the <xref linkend="gbp.man.git.import.orig"> commmand has the
+<option>--filter</option>=<parameter>pattern</parameter> option which can
+be truned into a configuration file option like this:
+
+<programlisting>
+    [git-import-orig]
+    filter = .svn
+    filter = .hg
+</programlisting>
+
+<para>
+An alternative way is to write it using Python list syntax:
+</para>
+
+<programlisting>
+    [git-import-orig]
+    filter = [ '.svn', '.hg' ]
+</programlisting>
+
+<para>
+Boolean options can bei either <option>True</option> or <option>False</option>. For example
+<xref linkend="gbp.man.git.import.orig">; has the <option>--pristine-tar</option> and
+<option>--no-pristine-tar</option> options which translate to:
+</para>
+<programlisting>
+    [git-import-orig]
+    pristine-tar = True
+</programlisting>
+
+<para>and</para>
+
+<programlisting>
+    [git-import-orig]
+    pristine-tar = False
+</programlisting>
+<para>respectively.</para>
+
+  </refsect1>
+  <refsect1>
+    <title>EXAMPLES</title>
+<para>
+An example set up for packaging work:
+</para>
+
+<programlisting>
+ # $HOME/gbp.conf
+
+ [DEFAULT]
+ pristine-tar = True
+ cleaner = fakeroot debian/rules clean
+
+ [git-buildpackage]
+ export-dir  = ../build-area/
+
+ [git-import-orig]
+ dch = False
+ filter = .svn
+ filter = .hg
+ filter = .bzr
+ filter = CVS
+ filter = debian/*
+ filter = */debian/*
+ filter-pristine-tar = True
+
+ [git-import-dsc]
+ filter = [
+        'CVS',
+        '.cvsignore',
+        '.hg',
+        '.hgignore'
+        '.bzr',
+        '.bzrignore',
+        '.gitignore'
+        ]
+
+ # End of file
+</programlisting>
+
+<refsect1>
+  <title>FILES</title>
+<para>
+  See See <filename>/etc/git-buildpackage/gbp.conf</filename> for an example.
+</para>
+</refsect1>
+
+<refsect1>
+  <title>STANDARDS</title>
+<para>
+  The at <ulink url="file:///usr/share/doc/git-buildpackage/manual-html/index.html">
+    <citetitle>The Git-Buildpackage Manual</citetitle></ulink> at
+  <filename>/usr/share/doc/git-buildpackage/manual-html/index.html</filename>
+</para>
+</refsect1>
+
+<refsect1>
+  <title>SEE ALSO</title>
+  <para>
+    <citerefentry>
+      <refentrytitle>gbp-clone</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>gbp-create-remote-repo</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>gbp-pq</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>
+    <citerefentry>
+      <refentrytitle>gbp-pull</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-dch</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-import-dsc</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-import-dscs</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-import-orig</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-pbuilder</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>git-buildpackage</refentrytitle>
+      <manvolnum>1</manvolnum>
+    </citerefentry>,
+  </para>
+</refsect1>
+<refsect1>
+  <title>AUTHORS</title>
+  <para>&dhusername; &dhemail;</para>
+  <para>This manual page is based on a POD version by Jari Aalto <email>jari.aalto@cante.net</email>.
+	Released under license GNU GPL version 2 or (at your option) any later.
+    version.
+  </para>
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index be577db8..058b66d4 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -7,5 +7,6 @@
 <!ENTITY man.gbp.clone SYSTEM "gbp-clone.sgml">
 <!ENTITY man.gbp.pq SYSTEM "gbp-pq.sgml">
 <!ENTITY man.gbp.create.remote.repo SYSTEM "gbp-create-remote-repo.sgml">
+<!ENTITY man.gbp.conf SYSTEM "gbp.conf.sgml">
 <!ENTITY man.git.config-files SYSTEM "man.conffiles.sgml">
 <!ENTITY man.seealso.common SYSTEM "man.seealso.sgml">
diff --git a/docs/manual.sgml b/docs/manual.sgml
index 3e3add82..4b9026fa 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -36,6 +36,7 @@
     &man.gbp.pull;
     &man.gbp.pq;
     &man.gbp.create.remote.repo;
+    &man.gbp.conf;
   </appendix>
   <appendix id="gbp.copyleft">
     <title>Copyright</title>