pq: add images to explain workflow

9 files changed, 138 insertions, 20 deletions

diff --git a/docs/Makefile b/docs/Makefile
index edac5a91..28a05393 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -31,12 +31,16 @@ GBP_VERSION=../gbp/version.py
 DEB_VERSION=$(shell sed -ne 's/^gbp_version\s\+=\s\+"\([.a-z0-9~-]\+\)"/\1/p' $(GBP_VERSION))
 CHANGELOG=../debian/changelog
 MAN_DATE=$(shell dpkg-parsechangelog -l ../debian/changelog -SDate | TZ=UTC LC_ALL=C date -f- +'%d %B %Y')
+IMAGES=$(wildcard images/*png)
+DEST_IMAGES=$(subst images/,$(MANUAL)/images/,$(IMAGES))
 
 # Stuff to build docs outside Debian
 HAVE_SGML2X ?= 1
 GTK_DOC_CATALOG_FILE ?= /usr/share/sgml/gtk-doc/gtk-doc.cat
 
-all: $(MANUAL) $(MANPAGES)
+all: manual $(MANPAGES)
+
+manual: $(MANUAL) html_images css
 
 $(MANUAL): manual.sgml chapters/*.sgml manpages/*.sgml common.ent $(VERSION_ENT)
 ifeq ($(HAVE_SGML2X),1)
@@ -46,8 +50,15 @@ else
 endif
 	sed -i 's/^CLASS="[A-Z0-9]\+"/\L&/' manual-html/*.html
 	cp /usr/share/gtk-doc/data/*.png $(MANUAL)
+
+css: gbp.css gbp.svg
 	cp gbp.css gbp.svg $(MANUAL)
 
+html_images: $(DEST_IMAGES)
+$(MANUAL)/images/%.png: images/%.png
+	mkdir -p -p $(basename $@)
+	install $< $@
+
 # We build manpages under 'buildxref/' just to get an updated cross-reference
 # file (manpage.refs), before building the final manpages
 BUILD_MAN_XREF_PAGES=$(patsubst %,buildxref/%,$(SGML_MANPAGES))
@@ -78,4 +89,3 @@ clean:
 	-rm -r manual-html/
 	-rm *.1 *.5 manpage.* $(VERSION_ENT)
 	-rm -r buildxref
-
diff --git a/docs/chapters/patches.sgml b/docs/chapters/patches.sgml
index ab3b0d33..5607dae2 100644
--- a/docs/chapters/patches.sgml
+++ b/docs/chapters/patches.sgml
@@ -62,6 +62,17 @@
       currently checked out is named <filename>debian/sid</filename>.
     </para>
 
+    <mediaobject>
+      <imageobject>
+	<imagedata fileref="images/pq-unapplied.png" format="PNG"/
+		   </imageobject>
+      <caption>
+	<para>
+	  The debian branch we start from.
+	</para>
+      </caption>
+    </mediaobject>
+
     <para>Let's first create the patch-queue branch and import the
       contents of <filename>debian/patches</filename> onto it using
       &gbp-pq;
@@ -83,6 +94,18 @@
   (<filename>patch-queue/debian/sid</filename>) automatically.
 </para>
 
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/pq-applied.png" format="PNG"/
+    </imageobject>
+    <caption>
+      <para>
+	The patch-queue branch with patches
+	from <filename>debian/patches</filename> applied.
+      </para>
+    </caption>
+  </mediaobject>
+
 <para>
   Now you can work on the patch-queue branch (add, remove, rebase,
   test) to get your patches into shape:
@@ -138,14 +161,38 @@
   <title>Importing a new upstream version</title>
 
   <para>
-    Ideally one would import the current set of patches to the
-    patch-queue branch
-    (&gbp <option>pq</option> <option>import</option>) before
-    importing the new upstream version, then rebase these
-    (&gbp <option>pq</option> <option>rebase</option>) and finally
-    export (&gbp <option>pq</option> <option>export</option>) but
-    don't worry if you forgot to do so before importing the new version
-    (or if another team member imported the version already).
+    To update your patches for a new upstream version one
+  </para>
+  <orderedlist>
+    <listitem>
+      <para>
+	Imports the current patches onto the patch-queue branch (if
+	not done already) using &gbp-pq-import;.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+	Imports the new upstream version with
+	&gbp-import-orig; <option>--uscan</option>.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+	Rebases the patches onto the new upstream version using
+	&gbp-pq-rebase;.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+	Exports the patches to <filename>debian/patches</filename> using
+	&gbp-pq-export;.
+      </para>
+    </listitem>
+  </orderedlist>
+
+  <para>
+    But don't worry if you forgot to do so before importing the new
+    version (or if another team member imported the version already).
   </para>
 
   <para>
@@ -155,7 +202,7 @@
   </para>
 
 <programlisting>
-    &gbp-pq; import --force --time-machine=10
+    &gbp-pq-import; --force --time-machine=10
 </programlisting>
 
   <para>
@@ -168,11 +215,23 @@
     finds such a commit on your debian branch it will create the
     patch-queue branch from there and switch you to that branch. You
     can now rework your patches to apply to the new upstream version
-    by using &gbp-pq <option>rebase</option>:
+    by using &gbp-pq-rebase;:
   </para>
 
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/pq-time-machine.png" format="PNG"/
+		 </imageobject>
+    <caption>
+      <para>
+	The patch-queue branch and debian branch after importing the
+	patches.
+      </para>
+    </caption>
+  </mediaobject>
+
 <programlisting>
-    &gbp-pq; rebase
+    &gbp-pq-rebase;
 </programlisting>
 
 <para>
@@ -186,24 +245,51 @@
   <para>
     Should the rebase fail (e.g. because the upstream source changed
     at the same place your patches modify the code) you can resolve
-    this by using  the options of &gitcmd; <option>rebase</option>. If
+    this by using  the options of &gitcmd; <option>rebase</option> (if
     you simply want to abort use
-    &gitcmd; <option>rebase</option> <option>--abort</option>.
+    &gitcmd; <option>rebase</option> <option>--abort</option>).
   </para>
 
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/pq-rebase.png" format="PNG"/
+		 </imageobject>
+    <caption>
+      <para>
+	The patch-queue branch after rebasing the patches. Patches
+	that were merged upstream were dropped.
+      </para>
+    </caption>
+  </mediaobject>
+
   <para>
     Once done you can export your commits to patch files again:
   </para>
 <programlisting>
-  &gbp-pq; export --commit
+  &gbp-pq-export; --commit
 </programlisting>
+
+  <para>
+    The export will also switch you back to the debian branch.
+  </para>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/pq-export.png" format="PNG"/
+		 </imageobject>
+    <caption>
+      <para>
+	The debian branch after exporting the patches and committing the changes.
+      </para>
+    </caption>
+  </mediaobject>
+
   <para>
     See this in action in a
     <ulink url="https://honk.sigxcpu.org/piki/projects/git-buildpackage/videos/gbp-pq-new-upstream-version.ogv">short
       video</ulink>.
   </para>
-</sect1>
 
+</sect1>
 <sect1 id="gbp.patches.firstpatch">
   <title>Adding your first patch</title>
 
@@ -216,7 +302,7 @@
       <para>Launch an import. If there's nothing to import &gbp-pq; will just
 	create an empty branch and switch your working copy to it:
 <programlisting>
-  &gbp-pq; import
+  &gbp-pq-import;
 </programlisting>
       </para>
     </listitem>
@@ -231,7 +317,7 @@
 	To generate the new Quilt patch set use
       </para>
 <programlisting>
-  &gbp-pq; export --commit
+  &gbp-pq-export; --commit
 </programlisting>
 <para>
   This will switch you back to your debian branch branch, generate the
@@ -255,7 +341,7 @@
       They can be recreated by any team member easily by using</para>
 
 <programlisting>
-  &gbp-pq; import --force
+  &gbp-pq-import; --force
 </programlisting>
 
 <para>
diff --git a/docs/common.ent b/docs/common.ent
index 5224419d..b1f25770 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -16,6 +16,9 @@
   <!ENTITY gbp-pull		"<command>gbp&nbsp;pull</command>">
   <!ENTITY gbp-clone		"<command>gbp&nbsp;clone</command>">
   <!ENTITY gbp-pq		"<command>gbp&nbsp;pq</command>">
+  <!ENTITY gbp-pq-import	"<command>gbp&nbsp;pq&nbsp<option>import</option></command>">
+  <!ENTITY gbp-pq-rebase	"<command>gbp&nbsp;pq&nbsp<option>rebase</option></command>">
+  <!ENTITY gbp-pq-export	"<command>gbp&nbsp;pq&nbsp<option>export</option></command>">
   <!ENTITY gbp-pristine-tar	"<command>gbp&nbsp;pristine-tar</command>">
   <!ENTITY gbp-create-remote-repo "<command>gbp&nbsp;create-remote-repo</command>">
   <!ENTITY git-pbuilder		"<command>git-pbuilder</command>">
diff --git a/docs/gbp.css b/docs/gbp.css
index c3087577..c3d017e1 100644
--- a/docs/gbp.css
+++ b/docs/gbp.css
@@ -111,3 +111,22 @@ table.warning td {
 table.footnotes td {
     border: none;
 }
+
+div.mediaobject {
+    background: #f5f5f5;
+    border-width: 2px;
+    border-color: lightgrey;
+    border-style: solid;
+}
+
+div.mediaobject img {
+    margin-left: auto;
+    margin-right: auto;
+    display: block;
+    padding: 5px 0px 0px 0px;
+}
+
+div.mediaobject p {
+    text-align: center;
+    font-style: italic;
+}
diff --git a/docs/images/pq-applied.png b/docs/images/pq-applied.png
new file mode 100644
index 00000000..caa606ea
--- /dev/null
+++ b/docs/images/pq-applied.png
diff --git a/docs/images/pq-export.png b/docs/images/pq-export.png
new file mode 100644
index 00000000..f1e10ee3
--- /dev/null
+++ b/docs/images/pq-export.png
diff --git a/docs/images/pq-rebase.png b/docs/images/pq-rebase.png
new file mode 100644
index 00000000..a280950c
--- /dev/null
+++ b/docs/images/pq-rebase.png
diff --git a/docs/images/pq-time-machine.png b/docs/images/pq-time-machine.png
new file mode 100644
index 00000000..035af899
--- /dev/null
+++ b/docs/images/pq-time-machine.png
diff --git a/docs/images/pq-unapplied.png b/docs/images/pq-unapplied.png
new file mode 100644
index 00000000..d472fed0
--- /dev/null
+++ b/docs/images/pq-unapplied.png