Make tutorial a valid asciidoc article.

There should be only one level 0 title, so redefine underline rules in
asciidoc.conf to keep the existing underlines when possible.  Form a new
level 1 part "Technical Information" from the text at the end.  Make
introduction a preamble - it's too short to be a level 1 section.

Add doc/Makefile to process the tutorial automatically.  make needs to
be run explicitly in the doc directory.

Signed-off-by: Pavel Roskin <proski@gnu.org>

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644 (file)
index 0000000..07704b8
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,17 @@
+DOCS = tutorial.txt
+DOCS_HTML = $(DOCS:.txt=.html)
+DOCS_PDF = $(DOCS:.txt=.pdf)
+
+all: $(DOCS_HTML) $(DOCS_PDF)
+
+%.html: %.txt
+       asciidoc $<
+
+%.xml: %.txt
+       asciidoc --backend=docbook $<
+
+%.pdf: %.xml
+       xmlto pdf $<
+
+clean:
+       rm -f *.xml *.html *.pdf

diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
new file mode 100644 (file)
index 0000000..5b8d95f
--- /dev/null
+++ b/doc/asciidoc.conf
@@ -0,0 +1,3 @@
+[titles]
+underlines="##","==","--","~~","^^"
+

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 7183e41..5899c38 100644 (file)
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -1,8 +1,6 @@
 StGIT Tutorial
-==============
+##############
 
-Introduction
-------------
 
 StGIT is a Python application that provides functionality similar to
 quilt (i.e. pushing/popping patches to/from a stack) using GIT instead
@@ -334,8 +332,11 @@ result in an empty patch (StGIT notifying the user) that can be safely
 deleted.
 
 
-A Bit of StGIT Patch Theory
-===========================
+Technical Information
+=====================
+
+A bit of StGIT patch theory
+---------------------------
 
 We assume that a patch is a diff between two nodes - bottom and top. A
 node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
@@ -374,8 +375,9 @@ The above operation allows easy patch re-ordering.
 Removing (popping) a patch from the stack is done by simply setting the
 Nst to Nb.
 
-.git/ Directory Structure
 
+Layout of the .git directory
+----------------------------
 
   HEAD                 -> refs/heads/<something>
   objects/