Re: [PATCH] stgit: make tutorial a valid asciidoc article
- From
- Pavel Roskin <proski@gnu.org>
- Date
- Jan 16, 2006, 22:37 UTC
- Message-ID
- <1137451068.5043.19.camel@dv>
- In-Reply-To
- <b0943d9e0601160021t3b40ba3fp@mail.gmail.com>
On Mon, 2006-01-16 at 08:21 +0000, Catalin Marinas wrote:
Show 11 quoted lines
> 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