[RFH] building docs with asciidoc 6.0.3
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:42:10
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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
dc02b117c1493f4f54646b692ac169b4824766aediff --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