[RFH] building docs with asciidoc 6.0.3

[RFH] building docs with asciidoc 6.0.3

[Junio C Hamano]

Debian sarge comes with asciidoc 6.0.3 which does not have
xhtml11, so I whipped up this patch to work things around, but
unsuccessfully.  The manpage backend seems to be busted.

There are three problems in our documentation source I am aware
of, with asciidoc 6.0.3.  This patch only works around two of
them -- I have not found a good workaround for the other one.

 * anchor generation by "Foo[[Bar]]" does not seem to work, but
   can be worked around by spelling it out as "Foo anchor:Bar[]".

 * blockquote style display element (for examples, look for
   revert-branch-rebase.txt in the attached patch) cannot
   contain lines that begin with '--'; it seems to confuse the
   end-of-block detection logic.  The patch works it around by
   indenting the quoted material by one space (yuck).

 * xml generated by manpage backend splits the refentry name at
   the first dash, so 'git-cat-file(1)' manpage (and everybody
   else whose name begins with 'git-') is generated in git.1.  I
   think this is a bug in asciidoc 6.0.3, and do not have a good
   workaround.

Note that I am reluctant to take a patch to the Makefile rule
that lets xmlto to generate git.1 and renames it to
git-cat-file.1.  The generated git-cat-file.xml file incorrectly
labels the refentry like this:

    <refnamediv>
        <refname>git</refname>
        <refpurpose>cat-file - Provide content or type information
     for repository objects</refpurpose>

but we would not know what other breakage there is.

In the meantime I plan to build my debs in a vanilla sarge
chrooted environment, updated minimally to use asciidoc 7.0.2.

Help from asciidoc savvy people are welcome.

---

 Documentation/Makefile                       |   10 +++--
 Documentation/asciidoc.conf                  |    4 ++
 Documentation/git.txt                        |    4 +-
 Documentation/howto/revert-branch-rebase.txt |   54 +++++++++++++-------------
 Documentation/tutorial.txt                   |   24 ++++++------
 debian/rules                                 |   11 +++++
 6 files changed, 61 insertions(+), 46 deletions(-)

applies-to: d6c9d63786e4bfb10982af5b9d84193a810c25f1
dc02b117c1493f4f54646b692ac169b4824766ae
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3cfa360..4f308d5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,6 +1,8 @@
 MAN1_TXT=$(wildcard git-*.txt) gitk.txt
 MAN7_TXT=git.txt
 
+XHTML_VER = xhtml11
+
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
 
 ARTICLES = tutorial
@@ -62,7 +64,7 @@ clean:
 	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html
 
 %.html : %.txt
-	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
+	asciidoc -b $(XHTML_VER) -d manpage -f asciidoc.conf $<
 
 %.1 %.7 : %.xml
 	xmlto man $<
@@ -75,7 +77,7 @@ git.html: git.txt ../README
 glossary.html : glossary.txt sort_glossary.pl
 	cat $< | \
 	perl sort_glossary.pl | \
-	asciidoc -b xhtml11 - > glossary.html
+	asciidoc -b $(XHTML_VER) - > glossary.html
 
 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	rm -f $@+ $@
@@ -83,13 +85,13 @@ howto-index.txt: howto-index.sh $(wildca
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	asciidoc -b xhtml11 $*.txt
+	asciidoc -b $(XHTML_VER) $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
 	rm -f $@+ $@
-	sed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+
+	sed -e '1,/^$$/d' $? | asciidoc -b $(XHTML_VER) - >$@+
 	mv $@+ $@
 
 install-webdoc : html
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index fa0877d..d2b9d53 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -23,4 +23,8 @@ ifdef::backend-xhtml11[]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
 
+ifdef::backend-xhtml[]
+[gitlink-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml[]
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 59d0dc8..653fc03 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -573,8 +573,8 @@ git Diffs
 	gitlink:git-diff-files[1];
 	gitlink:git-diff-tree[1]
 
-Discussion[[Discussion]]
-------------------------
+Discussion anchor:Discussion[]
+----------------------------
 include::../README[]
 
 Author
diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt
index e4cce5b..b69832e 100644
--- a/Documentation/howto/revert-branch-rebase.txt
+++ b/Documentation/howto/revert-branch-rebase.txt
@@ -31,17 +31,17 @@ the change I would want to undo.  Furthe
 merge introduced 5 commits or so:
 
 ------------------------------------------------
-$ git show-branch --more=4 master master^2 | head
-! [master] Merge refs/heads/portable from http://www.cs.berkeley....
- ! [master^2] Replace C99 array initializers with code.
---
-+  [master] Merge refs/heads/portable from http://www.cs.berkeley....
-++ [master^2] Replace C99 array initializers with code.
-++ [master^2~1] Replace unsetenv() and setenv() with older putenv().
-++ [master^2~2] Include sys/time.h in daemon.c.
-++ [master^2~3] Fix ?: statements.
-++ [master^2~4] Replace zero-length array decls with [].
-+  [master~1] tutorial note about git branch
+ $ git show-branch --more=4 master master^2 | head
+ ! [master] Merge refs/heads/portable from http://www.cs.berkeley....
+  ! [master^2] Replace C99 array initializers with code.
+ --
+ +  [master] Merge refs/heads/portable from http://www.cs.berkeley....
+ ++ [master^2] Replace C99 array initializers with code.
+ ++ [master^2~1] Replace unsetenv() and setenv() with older putenv().
+ ++ [master^2~2] Include sys/time.h in daemon.c.
+ ++ [master^2~3] Fix ?: statements.
+ ++ [master^2~4] Replace zero-length array decls with [].
+ +  [master~1] tutorial note about git branch
 ------------------------------------------------
 
 The '--more=4' above means "after we reach the merge base of refs,
@@ -180,20 +180,20 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcb
 And the final repository status looks like this:
 
 ------------------------------------------------
-$ git show-branch --more=1 master pu rc
-! [master] Revert "Replace zero-length array decls with []."
- ! [pu] git-repack: Add option to repack all objects.
-  * [rc] Merge refs/heads/master from .
----
- +  [pu] git-repack: Add option to repack all objects.
- +  [pu~1] More documentation updates.
- +  [pu~2] Show commits in topo order and name all commits.
- +  [pu~3] mailinfo and applymbox updates
- +  [pu~4] Document "git cherry-pick" and "git revert"
- +  [pu~5] Remove git-apply-patch-script.
- +  [pu~6] Redo "revert" using three-way merge machinery.
-  + [rc] Merge refs/heads/master from .
-+++ [master] Revert "Replace zero-length array decls with []."
-  + [rc~1] Merge refs/heads/master from .
-+++ [master~1] Merge refs/heads/portable from http://www.cs.berkeley....
+ $ git show-branch --more=1 master pu rc
+ ! [master] Revert "Replace zero-length array decls with []."
+  ! [pu] git-repack: Add option to repack all objects.
+   * [rc] Merge refs/heads/master from .
+ ---
+  +  [pu] git-repack: Add option to repack all objects.
+  +  [pu~1] More documentation updates.
+  +  [pu~2] Show commits in topo order and name all commits.
+  +  [pu~3] mailinfo and applymbox updates
+  +  [pu~4] Document "git cherry-pick" and "git revert"
+  +  [pu~5] Remove git-apply-patch-script.
+  +  [pu~6] Redo "revert" using three-way merge machinery.
+   + [rc] Merge refs/heads/master from .
+ +++ [master] Revert "Replace zero-length array decls with []."
+   + [rc~1] Merge refs/heads/master from .
+ +++ [master~1] Merge refs/heads/portable from http://www.cs.berkeley....
 ------------------------------------------------
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index b9f737e..f654c3c 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -1466,18 +1466,18 @@ two 'git resolve' commands in a row, you
 branch heads (this is known as 'making an Octopus'):
 
 ------------
-$ git pull . commit-fix diff-fix
-$ git show-branch
-! [commit-fix] Fix commit message normalization.
- ! [diff-fix] Fix rename detection.
-  * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
----
-  + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
-+ + [commit-fix] Fix commit message normalization.
- ++ [diff-fix] Fix rename detection.
- ++ [diff-fix~1] Better common substring algorithm.
-  + [master~1] Release candidate #1
-+++ [master~2] Pretty-print messages.
+ $ git pull . commit-fix diff-fix
+ $ git show-branch
+ ! [commit-fix] Fix commit message normalization.
+  ! [diff-fix] Fix rename detection.
+   * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+ ---
+   + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+ + + [commit-fix] Fix commit message normalization.
+  ++ [diff-fix] Fix rename detection.
+  ++ [diff-fix~1] Better common substring algorithm.
+   + [master~1] Release candidate #1
+ +++ [master~2] Pretty-print messages.
 ------------
 
 Note that you should not do Octopus because you can.  An octopus
diff --git a/debian/rules b/debian/rules
index 568d430..a944f3f 100755
--- a/debian/rules
+++ b/debian/rules
@@ -41,7 +41,16 @@ MAN_DESTDIR := $(DESTDIR)/$(MANDIR)
 build: debian/build-stamp
 debian/build-stamp:
 	dh_testdir
-	$(MAKE) prefix=$(PREFIX) PYTHON_PATH=/usr/bin/python2.4 all doc test
+	if test -f /etc/asciidoc/xhtml11.conf; \
+	then \
+		XHTML_VER=xhtml11; \
+	else \
+		XHTML_VER=xhtml; \
+	fi && \
+	$(MAKE) prefix=$(PREFIX) \
+		XHTML_VER=$$XHTML_VER \
+		PYTHON_PATH=/usr/bin/python2.4 \
+		all doc test
 	touch debian/build-stamp
 
 debian-clean:
---
0.99.9.GIT