From: Francis Daly Date: Sun, 05 Mar 2006 23:13:36 GMT Subject: [PATCH] Tweak asciidoc output to work with broken docbook-xsl Message-ID: <20060305231336.GA21797@craic.sysops.org> docbook-xsl v1.68 incorrectly converts "" from docbook to manpage by not rendering it verbatim. v1.69 handles it correctly, but not many current popular distributions ship with it. asciidoc by default converts "listingblock" to "". This change causes asciidoc in git to convert "listingblock" to "", which both old and new docbook-xsl handle correctly. The difference can be seen in any manpage which includes a multi-line example, such as git-branch. --- This one may want some consideration, because it involves changing how git interacts with asciidoc in order to make up for how an older version of docbook-xsl is broken. Clear? What version of docbook-xsl are people who make git manpages using? If it's not 1.69, the manpages (at least, those with multi-line examples) display incorrectly. Many current popular distributions seem to be using version 1.68. http://www.kernel.org/pub/software/scm/git/RPMS/x86_64/git-core-1.2.4-1.x86_64.rpm ftp://ftp.kddlabs.co.jp/pub/Linux/packages/fedora/extras/4/i386/git-core-1.2.4-1.fc4.i386.rpm (found on pbone, with "redhat/" removed from url; for Fedora 4) The 1.2.1 packages linked from http://packages.debian.org/unstable/devel/git-core all show the errors. ftp://ftp.kddlabs.co.jp/pub/Linux/packages/fedora/extras/development/i386/git-core-1.2.4-1.fc5.i386.rpm (found on pbone, with "redhat/" removed from the url; for Fedora Other, presumably 5) is correct. Clearly the *right* solution is for binary builders to update their toolchains. Maybe leaving this as-is will be an impetus for them to do so. Below is a not-right workaround which allows the git manpages render correctly when built by someone with an old docbook-xsl package. If this is acceptable, all well and good. If not, I'll contact the package builders and invite them to upgrade or patch before building new packages. Documentation/asciidoc.conf | 7 +++++++ 1 files changed, 7 insertions(+), 0 deletions(-) 1885a1ac69eabd6fa882f4464d3c66303d707566 diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index fa0877d..37e9ada 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -23,4 +23,11 @@ ifdef::backend-xhtml11[] {target}{0?({0})} endif::backend-xhtml11[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +{title} + +| + +{title#} -- 1.2.GIT -- Francis Daly francis@daoine.org