docs: revamp RPM docs

Signed-off-by: Markus Lehtonen <markus.lehtonen@linux.intel.com>

3 files changed, 54 insertions, 39 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 53be8027..ec9c34d8 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -26,11 +26,13 @@ GTK_DOC_CATALOG_FILE ?= /usr/share/sgml/gtk-doc/gtk-doc.cat
 
 all: $(MANUAL) $(MANPAGES)
 
-$(MANUAL): manual.sgml chapters/*.sgml manpages/*.sgml
+$(MANUAL): manual.sgml manual-rpm.sgml chapters/*.sgml manpages/*.sgml
 ifeq ($(HAVE_SGML2X),1)
 	docbook-2-html -s local $<
+	docbook-2-html -s local manual-rpm.sgml
 else
 	docbook2html -d local-nosgml2x.dsl -c $(GTK_DOC_CATALOG_FILE) -o $(MANUAL) $<
+	docbook2html -d local-nosgml2x.dsl -c $(GTK_DOC_CATALOG_FILE) -o $(MANUAL) manual-rpm.sgml
 endif
 	cp /usr/share/gtk-doc/data/*.png $(MANUAL)
 
@@ -42,6 +44,8 @@ git-pbuilder.1: ../bin/git-pbuilder
 
 manual.sgml: $(VERSION_ENT)
 
+manual-rpm.sgml: $(VERSION_ENT)
+
 $(VERSION_ENT): $(GBP_VERSION)
 	echo '<!ENTITY gbp-version "$(DEB_VERSION)">' > $(VERSION_ENT)
 
diff --git a/docs/chapters/intro-rpm.sgml b/docs/chapters/intro-rpm.sgml
index bdb91de9..2e15bc86 100644
--- a/docs/chapters/intro-rpm.sgml
+++ b/docs/chapters/intro-rpm.sgml
@@ -3,27 +3,36 @@
     <para>
         Git-buildpackage is a <ulink url="http://www.debian.org/">Debian</ulink>
         toolset for maintaining and building packages in/from git repositories.
-        The (still experimental) RPM variants of the tool, extend the support
+        The still experimental RPM variants of the tool, extend the support
         from Debian-only to building and maintaining RPM packages, too.
-        The documentation of git-buildpackage-rpm reflects the the
-        <xref linkend="gbp">Debian git-buildpackage documentation</xref>.
+        The documentation of git-buildpackage-rpm here reflects the the
+        <ulink url="gbp.html">Debian git-buildpackage documentation</>
+        <!--<xref linkend="gbp">Debian git-buildpackage documentation</xref>.-->
     </para>
     <para>
-        The RPM versions of the tools can do basically all the same tasks as
-        the Debian versions, except for changelog generation. However, the
-        philosophy is somewhat different in some parts. One clear difference is
-        that git-buildpackage-rpm will always build in a separate build
-        directory whereas git-buildpackage (the Debian) tool builds in the
-        git working dir by default. The Debian/RPM tool equivalence is:
+        The RPM versions of the tools can in their current state 
+        do basically all the same tasks as the Debian versions, except for changelog generation.
+        However, the philosophy is somewhat different in some parts. The RPM tools
+        read the .spec file instead of changelog in determining packaging
+        information (version number, name etc). Another clear difference is
+        that &git-buildpackage-rpm; will always build in a separate build
+        directory whereas &git-buildpackage; (the Debian) tool builds in the
+        git working dir, by default.
+        Third, conceptual, difference (for non-native packages) is that you may
+        have packaging files in an orphan branch, without development sources:
+        i.e. you develop code in 'patch-queue' branch that doesn't contain any
+        packaging files, and, do 'pq-rpm export' to 'packaging' branch that only
+        contains packaging files (.spec file, patches etc.) but no sources.
+        The Debian/RPM tool equivalence is:
         <itemizedlist>
-            <listitem>git-buildpackage –> rpm: <emphasis>git-buildpackage-rpm</></listitem>
-            <listitem>git-import-dsc –> rpm: <emphasis>git-import-srpm</></listitem>
-            <listitem>git-import-orig –> rpm: <emphasis>git-import-orig-rpm</></listitem>
-            <listitem>gbp-pq –> rpm: <emphasis>gbp-pq-rpm</></listitem>
-            <listitem>gbp-clone –> rpm: <emphasis>gbp-clone</> (the same tool)</listitem>
-            <listitem>gbp-pull –> rpm: <emphasis>gbp-pull</> (the same tool)</listitem>
-            <listitem>git-dch –> rpm: not available</listitem>
-            <listitem>git-import-dscs –> rpm: not available</listitem>
+            <listitem><para>&git-buildpackage; -> RPM: &git-buildpackage-rpm;</para></listitem>
+            <listitem><para>&git-import-dsc; -> RPM: &git-import-srpm;</para></listitem>
+            <listitem><para>&git-import-orig; -> RPM: &git-import-orig-rpm;</para></listitem>
+            <listitem><para>&gbp-pq; -> RPM: &gbp-pq-rpm;</para></listitem>
+            <listitem><para>&gbp-clone; -> RPM: &gbp-clone; (the same tool)</para></listitem>
+            <listitem><para>&gbp-pull; -> RPM: &gbp-pull; (the same tool)</para></listitem>
+            <listitem><para>&git-dch; -> RPM: not available</para></listitem>
+            <listitem><para>&git-import-dscs; -> RPM: not available</para></listitem>
         </itemizedlist>
     </para>
 
@@ -35,18 +44,18 @@
         in a separate branch. Other branches are:
     </para>
 	<itemizedlist>
-        <listitem><option>packaging-branch</> contains packaging files (spec
+        <listitem><para><option>packaging-branch</> contains packaging files (spec
         and source files, e.g. patches, needed by rpmbuild, except for the orig
-        tarball). This branch can contain the development sources as well
-        (always true for native packages).</listitem>
-        <listitem><option>upstream-branch</> contains upstream sources.
+        tarball). This branch <emphasis>may</> contain the development sources as well
+        (always true for native packages).</para></listitem>
+        <listitem><para><option>upstream-branch</> contains upstream sources.
         This can either be a branch you import to or a branch of an upstream
-        repository you pull from.</listitem>
-        <listitem><option>pristine-tar-branch</> contains pristine-tar data to
-        recreate the original upstream tarball from the upstream-branch.</listitem>
-        <listitem><option>patch-queue/* branches</> are related to 
+        repository you pull from.</para></listitem>
+        <listitem><para><option>pristine-tar-branch</> contains pristine-tar data to
+        recreate the original upstream tarball from the upstream-branch.</para></listitem>
+        <listitem><para><option>patch-queue/* branches</> are related to 
         <option>packaging-branch(es)</>. The patch-queue branch is the upstream
-        plus the patches from packaging branch applied.</listitem>
+        plus the patches from packaging branch applied.</para></listitem>
 	</itemizedlist>
 </sect1>
 
@@ -56,13 +65,13 @@
     	The basic workflow is very similar to Debian:
     </para>
     <orderedlist>
-        <listitem>Import a package via &git-import-srpm; OR clone from the 
-        distro git with gbp-clone if the package is already maintained with
-        &git-buildpackage-rpm;.</listitem>
-        <listitem>Develop, test, commit changes.</listitem>
-        <listitem>Once satisfied you can build the final package with
+        <listitem><para>Import a package via &git-import-srpm; OR clone from the 
+        distro git with &gbp-clone; if the package is already maintained with
+        &git-buildpackage-rpm;.</para></listitem>
+        <listitem><para>Develop, test, commit changes.</para></listitem>
+        <listitem><para>Once satisfied you can build the final package with
         &git-buildpackage-rpm; (optionally with --git-tag to create a tag in
-        git) and push it to git server.</listitem>
+        git) and push it to git server.</para></listitem>
     </orderedlist>
 </sect1>
 
diff --git a/docs/chapters/setup-rpm.sgml b/docs/chapters/setup-rpm.sgml
index 05c7d294..d6d24d37 100644
--- a/docs/chapters/setup-rpm.sgml
+++ b/docs/chapters/setup-rpm.sgml
@@ -1,7 +1,7 @@
-<chapter id="gbp.rpm.setup">
-    <title>Project/Git setup</title>
+<chapter id="gbp.rpm.development">
+    <title>Development flow</title>
 
-    <sect1 id="gbp.setup-rpm.models">
+    <sect1 id="gbp.rpm.setup.models">
         <title>Development models</title>
         <para>The &git-buildpackage-rpm; toolset basically supports three different
         models of package maintenance.</para>
@@ -21,7 +21,7 @@
             All changes (packaging and source code) are done to the same branch,
             i.e., the <option>packaging-branch</>, based on the <option>upstream-branch</>.
             When package is built,
-            &git-build-package-rpm; can automatically generate patches from
+            &git-buildpackage-rpm; can automatically generate patches from
             upstream version to packaging branch head (one patch per commit).
             and modify the spec file accordingly.
             </para>
@@ -42,7 +42,7 @@
         </sect2>
     </sect1>
 
-    <sect1 id="gbp.setup-rpm.scratch">
+    <sect1 id="gbp.rpm.setup.scratch">
         <title>Starting from scratch with a non-native package</title>
         <para>In this case, you most probably want to package software not yet
         found in your distro. First, create an empty repository:
@@ -78,9 +78,10 @@
             </screen></para>
             </listitem>
         </orderedlist>
+        </para>
     </sect1>
 
-    <sect1 id="gbp.setup-rpm.convert">
+    <sect1 id="gbp.rpm.setup.convert">
         <title>Converting an existing git repository of a non-native package</title>
         <para>In this case, you already have a git repository containing the 
         upstream source, but it was created neither with &gbp-clone; nor &git-import-srpm;.
@@ -92,6 +93,7 @@
         OR just add the name of your upstream branch to gbp.conf.
         Then, you just create a packaging/development branch(es) with git and
         add packaging files to the packaging branch.
+        </para>
     </sect1>
 </chapter>