# [PATCH] Tweak asciidoc output to work with broken docbook-xsl

3 messages from 2006-03-05 to 2006-03-06. Participants: Francis Daly, Junio C Hamano.
Thread: https://gitlist.dev/t/3575

## Francis Daly, 2006-03-05 23:13

Subject: [PATCH] Tweak asciidoc output to work with broken docbook-xsl
Message-ID: <20060305231336.GA21797@craic.sysops.org>
URL: https://gitlist.dev/e/20060305231336.GA21797%40craic.sysops.org

```
docbook-xsl v1.68 incorrectly converts "<screen>" 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 "<screen>". This change
causes asciidoc in git to convert "listingblock" to "<literallayout>", 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[]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
 
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout>
+{title#}</example>
 
-- 
1.2.GIT

-- 
Francis Daly        francis@daoine.org

```

## Junio C Hamano, 2006-03-06 00:53

Subject: Re: [PATCH] Tweak asciidoc output to work with broken docbook-xsl
Message-ID: <7vr75gcs20.fsf@assigned-by-dhcp.cox.net>
URL: https://gitlist.dev/e/7vr75gcs20.fsf%40assigned-by-dhcp.cox.net
In-Reply-To: <20060305231336.GA21797@craic.sysops.org>

```
Francis Daly <francis@daoine.org> writes:

> docbook-xsl v1.68 incorrectly converts "<screen>" 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 "<screen>". This change
> causes asciidoc in git to convert "listingblock" to "<literallayout>", which
> both old and new docbook-xsl handle correctly.

Have you tested html generation side?  With 1.68 I seem to be
getting an disaster.

How about this instead?

---
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index fa0877d..7ce7151 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -18,6 +18,16 @@ ifdef::backend-docbook[]
 {0#</citerefentry>}
 endif::backend-docbook[]
 
+ifdef::backend-docbook[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout>
+{title#}</example>
+endif::backend-docbook[]
+
 ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>

```

## Francis Daly, 2006-03-06 01:09

Subject: Re: [PATCH] Tweak asciidoc output to work with broken docbook-xsl
Message-ID: <20060306010907.GA22105@craic.sysops.org>
URL: https://gitlist.dev/e/20060306010907.GA22105%40craic.sysops.org
In-Reply-To: <7vr75gcs20.fsf@assigned-by-dhcp.cox.net>

```
On Sun, Mar 05, 2006 at 04:53:11PM -0800, Junio C Hamano wrote:
> Francis Daly <francis@daoine.org> writes:

> > asciidoc by default converts "listingblock" to "<screen>". This change
> > causes asciidoc in git to convert "listingblock" to "<literallayout>", which
> > both old and new docbook-xsl handle correctly.
> 
> Have you tested html generation side?  With 1.68 I seem to be
> getting an disaster.

Oh how stupid of me.

Yes, of course you're right.  The backend matters.

Clearly, I don't read the html pages; and no-one (with old stylesheets)
reads the man pages ;-)

Thanks,

	f
-- 
Francis Daly        francis@daoine.org

```