From mboxrd@z Thu Jan 1 00:00:00 1970 From: Junio C Hamano Subject: [RFH] building docs with asciidoc 6.0.3 Date: Tue, 01 Nov 2005 15:19:42 -0800 Message-ID: <7v1x207y7l.fsf@assigned-by-dhcp.cox.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-From: git-owner@vger.kernel.org Wed Nov 02 00:20:55 2005 Return-path: Received: from vger.kernel.org ([209.132.176.167]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EX5QB-0001LN-E9 for gcvg-git@gmane.org; Wed, 02 Nov 2005 00:20:03 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751385AbVKAXTq (ORCPT ); Tue, 1 Nov 2005 18:19:46 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1751426AbVKAXTq (ORCPT ); Tue, 1 Nov 2005 18:19:46 -0500 Received: from fed1rmmtao11.cox.net ([68.230.241.28]:42438 "EHLO fed1rmmtao11.cox.net") by vger.kernel.org with ESMTP id S1751385AbVKAXTq (ORCPT ); Tue, 1 Nov 2005 18:19:46 -0500 Received: from assigned-by-dhcp.cox.net ([68.4.9.127]) by fed1rmmtao11.cox.net (InterMail vM.6.01.05.02 201-2131-123-102-20050715) with ESMTP id <20051101231920.UQYD9394.fed1rmmtao11.cox.net@assigned-by-dhcp.cox.net>; Tue, 1 Nov 2005 18:19:20 -0500 To: git@vger.kernel.org User-Agent: Gnus/5.110004 (No Gnus v0.4) Emacs/21.4 (gnu/linux) Sender: git-owner@vger.kernel.org Precedence: bulk X-Mailing-List: git@vger.kernel.org Archived-At: 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: git cat-file - Provide content or type information for repository objects 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[] {target}{0?({0})} endif::backend-xhtml11[] +ifdef::backend-xhtml[] +[gitlink-inlinemacro] +{target}{0?({0})} +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