{"thread":{"id":"2302","subject":"[RFH] building docs with asciidoc 6.0.3","startedAt":"2005-11-01T23:19:42Z","lastAt":"2005-11-01T23:19:42Z","messageCount":1,"participants":["Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"10959","messageId":"7v1x207y7l.fsf@assigned-by-dhcp.cox.net","threadId":"2302","inReplyTo":null,"subject":"[RFH] building docs with asciidoc 6.0.3","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-11-01T23:19:42Z","receivedAt":"2005-11-01T23:19:42Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Debian sarge comes with asciidoc 6.0.3 which does not have\nxhtml11, so I whipped up this patch to work things around, but\nunsuccessfully.  The manpage backend seems to be busted.\n\nThere are three problems in our documentation source I am aware\nof, with asciidoc 6.0.3.  This patch only works around two of\nthem -- I have not found a good workaround for the other one.\n\n * anchor generation by \"Foo[[Bar]]\" does not seem to work, but\n   can be worked around by spelling it out as \"Foo anchor:Bar[]\".\n\n * blockquote style display element (for examples, look for\n   revert-branch-rebase.txt in the attached patch) cannot\n   contain lines that begin with '--'; it seems to confuse the\n   end-of-block detection logic.  The patch works it around by\n   indenting the quoted material by one space (yuck).\n\n * xml generated by manpage backend splits the refentry name at\n   the first dash, so 'git-cat-file(1)' manpage (and everybody\n   else whose name begins with 'git-') is generated in git.1.  I\n   think this is a bug in asciidoc 6.0.3, and do not have a good\n   workaround.\n\nNote that I am reluctant to take a patch to the Makefile rule\nthat lets xmlto to generate git.1 and renames it to\ngit-cat-file.1.  The generated git-cat-file.xml file incorrectly\nlabels the refentry like this:\n\n    <refnamediv>\n        <refname>git</refname>\n        <refpurpose>cat-file - Provide content or type information\n     for repository objects</refpurpose>\n\nbut we would not know what other breakage there is.\n\nIn the meantime I plan to build my debs in a vanilla sarge\nchrooted environment, updated minimally to use asciidoc 7.0.2.\n\nHelp from asciidoc savvy people are welcome.\n\n---\n\n Documentation/Makefile                       |   10 +++--\n Documentation/asciidoc.conf                  |    4 ++\n Documentation/git.txt                        |    4 +-\n Documentation/howto/revert-branch-rebase.txt |   54 +++++++++++++-------------\n Documentation/tutorial.txt                   |   24 ++++++------\n debian/rules                                 |   11 +++++\n 6 files changed, 61 insertions(+), 46 deletions(-)\n\napplies-to: d6c9d63786e4bfb10982af5b9d84193a810c25f1\ndc02b117c1493f4f54646b692ac169b4824766ae\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3cfa360..4f308d5 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -1,6 +1,8 @@\n MAN1_TXT=$(wildcard git-*.txt) gitk.txt\n MAN7_TXT=git.txt\n \n+XHTML_VER = xhtml11\n+\n DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))\n \n ARTICLES = tutorial\n@@ -62,7 +64,7 @@ clean:\n \trm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html\n \n %.html : %.txt\n-\tasciidoc -b xhtml11 -d manpage -f asciidoc.conf $<\n+\tasciidoc -b $(XHTML_VER) -d manpage -f asciidoc.conf $<\n \n %.1 %.7 : %.xml\n \txmlto man $<\n@@ -75,7 +77,7 @@ git.html: git.txt ../README\n glossary.html : glossary.txt sort_glossary.pl\n \tcat $< | \\\n \tperl sort_glossary.pl | \\\n-\tasciidoc -b xhtml11 - > glossary.html\n+\tasciidoc -b $(XHTML_VER) - > glossary.html\n \n howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \trm -f $@+ $@\n@@ -83,13 +85,13 @@ howto-index.txt: howto-index.sh $(wildca\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n-\tasciidoc -b xhtml11 $*.txt\n+\tasciidoc -b $(XHTML_VER) $*.txt\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \n $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n \trm -f $@+ $@\n-\tsed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+\n+\tsed -e '1,/^$$/d' $? | asciidoc -b $(XHTML_VER) - >$@+\n \tmv $@+ $@\n \n install-webdoc : html\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex fa0877d..d2b9d53 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -23,4 +23,8 @@ ifdef::backend-xhtml11[]\n <a href=\"{target}.html\">{target}{0?({0})}</a>\n endif::backend-xhtml11[]\n \n+ifdef::backend-xhtml[]\n+[gitlink-inlinemacro]\n+<a href=\"{target}.html\">{target}{0?({0})}</a>\n+endif::backend-xhtml[]\n \ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 59d0dc8..653fc03 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -573,8 +573,8 @@ git Diffs\n \tgitlink:git-diff-files[1];\n \tgitlink:git-diff-tree[1]\n \n-Discussion[[Discussion]]\n-------------------------\n+Discussion anchor:Discussion[]\n+----------------------------\n include::../README[]\n \n Author\ndiff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt\nindex e4cce5b..b69832e 100644\n--- a/Documentation/howto/revert-branch-rebase.txt\n+++ b/Documentation/howto/revert-branch-rebase.txt\n@@ -31,17 +31,17 @@ the change I would want to undo.  Furthe\n merge introduced 5 commits or so:\n \n ------------------------------------------------\n-$ git show-branch --more=4 master master^2 | head\n-! [master] Merge refs/heads/portable from http://www.cs.berkeley....\n- ! [master^2] Replace C99 array initializers with code.\n---\n-+  [master] Merge refs/heads/portable from http://www.cs.berkeley....\n-++ [master^2] Replace C99 array initializers with code.\n-++ [master^2~1] Replace unsetenv() and setenv() with older putenv().\n-++ [master^2~2] Include sys/time.h in daemon.c.\n-++ [master^2~3] Fix ?: statements.\n-++ [master^2~4] Replace zero-length array decls with [].\n-+  [master~1] tutorial note about git branch\n+ $ git show-branch --more=4 master master^2 | head\n+ ! [master] Merge refs/heads/portable from http://www.cs.berkeley....\n+  ! [master^2] Replace C99 array initializers with code.\n+ --\n+ +  [master] Merge refs/heads/portable from http://www.cs.berkeley....\n+ ++ [master^2] Replace C99 array initializers with code.\n+ ++ [master^2~1] Replace unsetenv() and setenv() with older putenv().\n+ ++ [master^2~2] Include sys/time.h in daemon.c.\n+ ++ [master^2~3] Fix ?: statements.\n+ ++ [master^2~4] Replace zero-length array decls with [].\n+ +  [master~1] tutorial note about git branch\n ------------------------------------------------\n \n The '--more=4' above means \"after we reach the merge base of refs,\n@@ -180,20 +180,20 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcb\n And the final repository status looks like this:\n \n ------------------------------------------------\n-$ git show-branch --more=1 master pu rc\n-! [master] Revert \"Replace zero-length array decls with [].\"\n- ! [pu] git-repack: Add option to repack all objects.\n-  * [rc] Merge refs/heads/master from .\n----\n- +  [pu] git-repack: Add option to repack all objects.\n- +  [pu~1] More documentation updates.\n- +  [pu~2] Show commits in topo order and name all commits.\n- +  [pu~3] mailinfo and applymbox updates\n- +  [pu~4] Document \"git cherry-pick\" and \"git revert\"\n- +  [pu~5] Remove git-apply-patch-script.\n- +  [pu~6] Redo \"revert\" using three-way merge machinery.\n-  + [rc] Merge refs/heads/master from .\n-+++ [master] Revert \"Replace zero-length array decls with [].\"\n-  + [rc~1] Merge refs/heads/master from .\n-+++ [master~1] Merge refs/heads/portable from http://www.cs.berkeley....\n+ $ git show-branch --more=1 master pu rc\n+ ! [master] Revert \"Replace zero-length array decls with [].\"\n+  ! [pu] git-repack: Add option to repack all objects.\n+   * [rc] Merge refs/heads/master from .\n+ ---\n+  +  [pu] git-repack: Add option to repack all objects.\n+  +  [pu~1] More documentation updates.\n+  +  [pu~2] Show commits in topo order and name all commits.\n+  +  [pu~3] mailinfo and applymbox updates\n+  +  [pu~4] Document \"git cherry-pick\" and \"git revert\"\n+  +  [pu~5] Remove git-apply-patch-script.\n+  +  [pu~6] Redo \"revert\" using three-way merge machinery.\n+   + [rc] Merge refs/heads/master from .\n+ +++ [master] Revert \"Replace zero-length array decls with [].\"\n+   + [rc~1] Merge refs/heads/master from .\n+ +++ [master~1] Merge refs/heads/portable from http://www.cs.berkeley....\n ------------------------------------------------\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nindex b9f737e..f654c3c 100644\n--- a/Documentation/tutorial.txt\n+++ b/Documentation/tutorial.txt\n@@ -1466,18 +1466,18 @@ two 'git resolve' commands in a row, you\n branch heads (this is known as 'making an Octopus'):\n \n ------------\n-$ git pull . commit-fix diff-fix\n-$ git show-branch\n-! [commit-fix] Fix commit message normalization.\n- ! [diff-fix] Fix rename detection.\n-  * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\n----\n-  + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\n-+ + [commit-fix] Fix commit message normalization.\n- ++ [diff-fix] Fix rename detection.\n- ++ [diff-fix~1] Better common substring algorithm.\n-  + [master~1] Release candidate #1\n-+++ [master~2] Pretty-print messages.\n+ $ git pull . commit-fix diff-fix\n+ $ git show-branch\n+ ! [commit-fix] Fix commit message normalization.\n+  ! [diff-fix] Fix rename detection.\n+   * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\n+ ---\n+   + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'\n+ + + [commit-fix] Fix commit message normalization.\n+  ++ [diff-fix] Fix rename detection.\n+  ++ [diff-fix~1] Better common substring algorithm.\n+   + [master~1] Release candidate #1\n+ +++ [master~2] Pretty-print messages.\n ------------\n \n Note that you should not do Octopus because you can.  An octopus\ndiff --git a/debian/rules b/debian/rules\nindex 568d430..a944f3f 100755\n--- a/debian/rules\n+++ b/debian/rules\n@@ -41,7 +41,16 @@ MAN_DESTDIR := $(DESTDIR)/$(MANDIR)\n build: debian/build-stamp\n debian/build-stamp:\n \tdh_testdir\n-\t$(MAKE) prefix=$(PREFIX) PYTHON_PATH=/usr/bin/python2.4 all doc test\n+\tif test -f /etc/asciidoc/xhtml11.conf; \\\n+\tthen \\\n+\t\tXHTML_VER=xhtml11; \\\n+\telse \\\n+\t\tXHTML_VER=xhtml; \\\n+\tfi && \\\n+\t$(MAKE) prefix=$(PREFIX) \\\n+\t\tXHTML_VER=$$XHTML_VER \\\n+\t\tPYTHON_PATH=/usr/bin/python2.4 \\\n+\t\tall doc test\n \ttouch debian/build-stamp\n \n debian-clean:\n---\n0.99.9.GIT\n"}]}