[PATCH] stgit: make tutorial a valid asciidoc article

[PATCH] stgit: make tutorial a valid asciidoc article

[Pavel Roskin]

There should be only one level 0 title in an article, so lower ranks of
all headers by one.  Make capitalization uniform in the headers - level
1 is capitalized, but level 2 is not.  Create a new level 1 part
"Technical Information".

Make ".git/ Directory Structure" a level 2 header and rephrase.
asciidoc doesn't like headers starting with a dot.

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

 doc/tutorial.txt |   34 +++++++++++++++++++---------------
 1 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 7183e41..eae26f4 100644
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -16,10 +16,10 @@ information on GIT, see the GIT_tutorial
 
 
 Basic Operation
-===============
+---------------
 
 Help
-----
+~~~~
 
 For a full list of StGIT commands:
 
@@ -31,7 +31,7 @@ For help on individual subcommands:
 
 
 Repository initialisation
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In stand-alone mode, StGIT is used in conjunction with a GIT repository
 that is already initialised (using 'git-init-db'). StGIT cannot be used
@@ -59,7 +59,7 @@ will automatically prepare them for use 
 
 
 Working with remote repositories
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 With a single command, StGIT can create and initialize a GIT repository
 which mirrors a remote GIT repository. This is known as cloning. All GIT
@@ -97,7 +97,7 @@ separated into its own branch to make it
 just your patches.
 
 Getting started: creating a patch
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Changes to your working directory are saved in a patch. An StGIT patch
 is simply a saved set of modifications to your working directory, plus a
@@ -140,7 +140,7 @@ commands:
 
 
 Stack manipulation: managing multiple patches
----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 StGIT can manage more than one patch at a time. A series of StGIT
 patches in a GIT branch are known collectively as a stack. The new patch
@@ -200,7 +200,7 @@ you want to permanently store the applie
 them with StGIT.
 
 Converting between StGIT patches and text diffs
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As mentioned in the introduction, StGIT stores modifications to your
 working tree in the form of GIT commits. This means if you want to apply
@@ -270,10 +270,10 @@ the bottom of the topmost one and perfor
 
 
 Advanced Usage
-==============
+--------------
 
 Handling merge conflicts
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Pushing a patch on the stack can fail if the patch cannot be applied
 cleanly. This usually happens if there are overlapping changes in the
@@ -293,7 +293,7 @@ resolve the conflict.
 
 
 Configuration file
-------------------
+~~~~~~~~~~~~~~~~~~
 
 StGIT tries to read the configuration options from the following files:
 /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the
@@ -307,7 +307,7 @@ specify a smarter tool to be used.
 
 
 Templates
----------
+~~~~~~~~~
 
 The 'export' and 'mail' commands use templates for generating the patch
 files or e-mails. The default templates are installed under <prefix>/
@@ -324,7 +324,7 @@ lines.
 
 
 Merging two patches into one
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There is no command to do this directly at the moment but one can export
 the patch to be merged and use the 'stg fold' command on the generated
@@ -334,8 +334,11 @@ result in an empty patch (StGIT notifyin
 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 +377,9 @@ The above operation allows easy patch re
 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/


-- 
Regards,
Pavel Roskin

Re: [PATCH] stgit: make tutorial a valid asciidoc article

[Catalin Marinas]

On 13/01/06, Pavel Roskin <proski@gnu.org> wrote:
> There should be only one level 0 title in an article, so lower ranks of
> all headers by one.  Make capitalization uniform in the headers - level
> 1 is capitalized, but level 2 is not.  Create a new level 1 part
> "Technical Information".
>
> Make ".git/ Directory Structure" a level 2 header and rephrase.
> asciidoc doesn't like headers starting with a dot.

I agree with most of this but what's the difference when adding "~~~~"
instead of "----"?

Thanks.

--
Catalin

Re: [PATCH] stgit: make tutorial a valid asciidoc article

[Pavel Roskin]

On Mon, 2006-01-16 at 08:21 +0000, Catalin Marinas wrote:
> On 13/01/06, Pavel Roskin <proski@gnu.org> wrote:
> > There should be only one level 0 title in an article, so lower ranks of
> > all headers by one.  Make capitalization uniform in the headers - level
> > 1 is capitalized, but level 2 is not.  Create a new level 1 part
> > "Technical Information".
> >
> > Make ".git/ Directory Structure" a level 2 header and rephrase.
> > asciidoc doesn't like headers starting with a dot.
> 
> I agree with most of this but what's the difference when adding "~~~~"
> instead of "----"?

An article can only have one level 0 title, which is underlined by
"====".  There may be more than one level 0 title in a book, but we
probably shouldn't do it.  Books have page breaks and table of contents
for every level 0 title.

This means that the existing hierarchy should be moved one step down.
Level 1 uses "----" and level 2 uses "~~~~".  I guess your objection is
that the visual distinction between level 1 and level 2 is insignificant
in the original ASCII file.  I agree.

It's possible to override the underline rules by placing asciidoc.conf
in the same directory as the document.  I think "####" would be just
fine for the level 0.  Then we can keep the rest.

Also, I've added a makefile.  It's not used by default, but those who
want to read a tutorial, can generate it in html or pdf format.

Here's the new patch.
---

Make tutorial a valid asciidoc article.

From: Pavel Roskin <proski@gnu.org>

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>
---

 doc/Makefile      |   17 +++++++++++++++++
 doc/asciidoc.conf |    3 +++
 doc/tutorial.txt  |   14 ++++++++------
 3 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
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
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
--- 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 notifyin
 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
 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/


-- 
Regards,
Pavel Roskin

Re: [PATCH] stgit: make tutorial a valid asciidoc article

[Catalin Marinas]

On 16/01/06, Pavel Roskin <proski@gnu.org> wrote:
> Also, I've added a makefile.  It's not used by default, but those who
> want to read a tutorial, can generate it in html or pdf format.
>
> Here's the new patch.

That's great, thanks. I'll push it, probably tomorrow.

--
Catalin