{"thread":{"id":"3067","subject":"[PATCH] stgit: make tutorial a valid asciidoc article","startedAt":"2006-01-13T08:54:46Z","lastAt":"2006-01-21T18:32:38Z","messageCount":4,"participants":["Pavel Roskin","Catalin Marinas"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"14607","messageId":"1137142486.20073.77.camel@dv","threadId":"3067","inReplyTo":null,"subject":"[PATCH] stgit: make tutorial a valid asciidoc article","fromName":"Pavel Roskin","fromEmail":"proski@gnu.org","sentAt":"2006-01-13T08:54:46Z","receivedAt":"2006-01-13T08:54:46Z","isPatch":true,"sender":{"key":"proski@gnu.org","avatar":null},"body":"There should be only one level 0 title in an article, so lower ranks of\nall headers by one. Make capitalization uniform in the headers - level\n1 is capitalized, but level 2 is not. Create a new level 1 part\n\"Technical Information\".\n\nMake \".git/ Directory Structure\" a level 2 header and rephrase.\nasciidoc doesn't like headers starting with a dot.\n\nSigned-off-by: Pavel Roskin \n---\n\n doc/tutorial.txt | 34 +++++++++++++++++++---------------\n 1 files changed, 19 insertions(+), 15 deletions(-)\n\ndiff --git a/doc/tutorial.txt b/doc/tutorial.txt\nindex 7183e41..eae26f4 100644\n--- a/doc/tutorial.txt\n+++ b/doc/tutorial.txt\n@@ -16,10 +16,10 @@ information on GIT, see the GIT_tutorial\n \n \n Basic Operation\n-===============\n+---------------\n \n Help\n-----\n+~~~~\n \n For a full list of StGIT commands:\n \n@@ -31,7 +31,7 @@ For help on individual subcommands:\n \n \n Repository initialisation\n--------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n \n In stand-alone mode, StGIT is used in conjunction with a GIT repository\n that is already initialised (using 'git-init-db'). StGIT cannot be used\n@@ -59,7 +59,7 @@ will automatically prepare them for use \n \n \n Working with remote repositories\n---------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n With a single command, StGIT can create and initialize a GIT repository\n which mirrors a remote GIT repository. This is known as cloning. All GIT\n@@ -97,7 +97,7 @@ separated into its own branch to make it\n just your patches.\n \n Getting started: creating a patch\n----------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n Changes to your working directory are saved in a patch. An StGIT patch\n is simply a saved set of modifications to your working directory, plus a\n@@ -140,7 +140,7 @@ commands:\n \n \n Stack manipulation: managing multiple patches\n----------------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n StGIT can manage more than one patch at a time. A series of StGIT\n patches in a GIT branch are known collectively as a stack. The new patch\n@@ -200,7 +200,7 @@ you want to permanently store the applie\n them with StGIT.\n \n Converting between StGIT patches and text diffs\n------------------------------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n As mentioned in the introduction, StGIT stores modifications to your\n working tree in the form of GIT commits. This means if you want to apply\n@@ -270,10 +270,10 @@ the bottom of the topmost one and perfor\n \n \n Advanced Usage\n-==============\n+--------------\n \n Handling merge conflicts\n-------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~\n \n Pushing a patch on the stack can fail if the patch cannot be applied\n cleanly. This usually happens if there are overlapping changes in the\n@@ -293,7 +293,7 @@ resolve the conflict.\n \n \n Configuration file\n-------------------\n+~~~~~~~~~~~~~~~~~~\n \n StGIT tries to read the configuration options from the following files:\n /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the\n@@ -307,7 +307,7 @@ specify a smarter tool to be used.\n \n \n Templates\n----------\n+~~~~~~~~~\n \n The 'export' and 'mail' commands use templates for generating the patch\n files or e-mails. The default templates are installed under /\n@@ -324,7 +324,7 @@ lines.\n \n \n Merging two patches into one\n-----------------------------\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n There is no command to do this directly at the moment but one can export\n the patch to be merged and use the 'stg fold' command on the generated\n@@ -334,8 +334,11 @@ result in an empty patch (StGIT notifyin\n deleted.\n \n \n-A Bit of StGIT Patch Theory\n-===========================\n+Technical Information\n+---------------------\n+\n+A bit of StGIT patch theory\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n We assume that a patch is a diff between two nodes - bottom and top. A\n node is a commit SHA1 id or tree SHA1 id in the GIT terminology:\n@@ -374,8 +377,9 @@ The above operation allows easy patch re\n Removing (popping) a patch from the stack is done by simply setting the\n Nst to Nb.\n \n-.git/ Directory Structure\n \n+Layout of the .git directory\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n HEAD\t\t\t-> refs/heads/\n objects/\n\n\n-- \nRegards,\nPavel Roskin\n"},{"id":"14715","messageId":"b0943d9e0601160021t3b40ba3fp@mail.gmail.com","threadId":"3067","inReplyTo":"1137142486.20073.77.camel@dv","subject":"Re: [PATCH] stgit: make tutorial a valid asciidoc article","fromName":"Catalin Marinas","fromEmail":"catalin.marinas@gmail.com","sentAt":"2006-01-16T08:21:54Z","receivedAt":"2006-01-16T08:21:54Z","isPatch":true,"sender":{"key":"catalin.marinas@gmail.com","avatar":null},"body":"On 13/01/06, Pavel Roskin wrote:\n> There should be only one level 0 title in an article, so lower ranks of\n> all headers by one. Make capitalization uniform in the headers - level\n> 1 is capitalized, but level 2 is not. Create a new level 1 part\n> \"Technical Information\".\n>\n> Make \".git/ Directory Structure\" a level 2 header and rephrase.\n> asciidoc doesn't like headers starting with a dot.\n\nI agree with most of this but what's the difference when adding \"~~~~\"\ninstead of \"----\"?\n\nThanks.\n\n--\nCatalin\n"},{"id":"14749","messageId":"1137451068.5043.19.camel@dv","threadId":"3067","inReplyTo":"b0943d9e0601160021t3b40ba3fp@mail.gmail.com","subject":"Re: [PATCH] stgit: make tutorial a valid asciidoc article","fromName":"Pavel Roskin","fromEmail":"proski@gnu.org","sentAt":"2006-01-16T22:37:48Z","receivedAt":"2006-01-16T22:37:48Z","isPatch":true,"sender":{"key":"proski@gnu.org","avatar":null},"body":"On Mon, 2006-01-16 at 08:21 +0000, Catalin Marinas wrote:\n> On 13/01/06, Pavel Roskin wrote:\n> > There should be only one level 0 title in an article, so lower ranks of\n> > all headers by one. Make capitalization uniform in the headers - level\n> > 1 is capitalized, but level 2 is not. Create a new level 1 part\n> > \"Technical Information\".\n> >\n> > Make \".git/ Directory Structure\" a level 2 header and rephrase.\n> > asciidoc doesn't like headers starting with a dot.\n> \n> I agree with most of this but what's the difference when adding \"~~~~\"\n> instead of \"----\"?\n\nAn article can only have one level 0 title, which is underlined by\n\"====\". There may be more than one level 0 title in a book, but we\nprobably shouldn't do it. Books have page breaks and table of contents\nfor every level 0 title.\n\nThis means that the existing hierarchy should be moved one step down.\nLevel 1 uses \"----\" and level 2 uses \"~~~~\". I guess your objection is\nthat the visual distinction between level 1 and level 2 is insignificant\nin the original ASCII file. I agree.\n\nIt's possible to override the underline rules by placing asciidoc.conf\nin the same directory as the document. I think \"####\" would be just\nfine for the level 0. Then we can keep the rest.\n\nAlso, I've added a makefile. It's not used by default, but those who\nwant to read a tutorial, can generate it in html or pdf format.\n\nHere's the new patch.\n---\n\nMake tutorial a valid asciidoc article.\n\nFrom: Pavel Roskin \n\nThere should be only one level 0 title, so redefine underline rules in\nasciidoc.conf to keep the existing underlines when possible. Form a new\nlevel 1 part \"Technical Information\" from the text at the end. Make\nintroduction a preamble - it's too short to be a level 1 section.\n\nAdd doc/Makefile to process the tutorial automatically. make needs to\nbe run explicitly in the doc directory.\n\nSigned-off-by: Pavel Roskin \n---\n\n doc/Makefile | 17 +++++++++++++++++\n doc/asciidoc.conf | 3 +++\n doc/tutorial.txt | 14 ++++++++------\n 3 files changed, 28 insertions(+), 6 deletions(-)\n\ndiff --git a/doc/Makefile b/doc/Makefile\nnew file mode 100644\nindex 0000000..07704b8\n--- /dev/null\n+++ b/doc/Makefile\n@@ -0,0 +1,17 @@\n+DOCS = tutorial.txt\n+DOCS_HTML = $(DOCS:.txt=.html)\n+DOCS_PDF = $(DOCS:.txt=.pdf)\n+\n+all: $(DOCS_HTML) $(DOCS_PDF)\n+\n+%.html: %.txt\n+\tasciidoc $<\n+\n+%.xml: %.txt\n+\tasciidoc --backend=docbook $<\n+\n+%.pdf: %.xml\n+\txmlto pdf $<\n+\n+clean:\n+\trm -f *.xml *.html *.pdf\ndiff --git a/doc/asciidoc.conf b/doc/asciidoc.conf\nnew file mode 100644\nindex 0000000..5b8d95f\n--- /dev/null\n+++ b/doc/asciidoc.conf\n@@ -0,0 +1,3 @@\n+[titles]\n+underlines=\"##\",\"==\",\"--\",\"~~\",\"^^\"\n+\ndiff --git a/doc/tutorial.txt b/doc/tutorial.txt\nindex 7183e41..5899c38 100644\n--- a/doc/tutorial.txt\n+++ b/doc/tutorial.txt\n@@ -1,8 +1,6 @@\n StGIT Tutorial\n-==============\n+##############\n \n-Introduction\n-------------\n \n StGIT is a Python application that provides functionality similar to\n quilt (i.e. pushing/popping patches to/from a stack) using GIT instead\n@@ -334,8 +332,11 @@ result in an empty patch (StGIT notifyin\n deleted.\n \n \n-A Bit of StGIT Patch Theory\n-===========================\n+Technical Information\n+=====================\n+\n+A bit of StGIT patch theory\n+---------------------------\n \n We assume that a patch is a diff between two nodes - bottom and top. A\n node is a commit SHA1 id or tree SHA1 id in the GIT terminology:\n@@ -374,8 +375,9 @@ The above operation allows easy patch re\n Removing (popping) a patch from the stack is done by simply setting the\n Nst to Nb.\n \n-.git/ Directory Structure\n \n+Layout of the .git directory\n+----------------------------\n \n HEAD\t\t\t-> refs/heads/\n objects/\n\n\n-- \nRegards,\nPavel Roskin\n"},{"id":"14986","messageId":"b0943d9e0601211032t2d7e6ba9x@mail.gmail.com","threadId":"3067","inReplyTo":"1137451068.5043.19.camel@dv","subject":"Re: [PATCH] stgit: make tutorial a valid asciidoc article","fromName":"Catalin Marinas","fromEmail":"catalin.marinas@gmail.com","sentAt":"2006-01-21T18:32:38Z","receivedAt":"2006-01-21T18:32:38Z","isPatch":true,"sender":{"key":"catalin.marinas@gmail.com","avatar":null},"body":"On 16/01/06, Pavel Roskin wrote:\n> Also, I've added a makefile. It's not used by default, but those who\n> want to read a tutorial, can generate it in html or pdf format.\n>\n> Here's the new patch.\n\nThat's great, thanks. I'll push it, probably tomorrow.\n\n--\nCatalin\n"}]}