Re: man pages are littered with .ft C and others

[Jonas Fonseca <fonseca@diku.dk>]

Jakub Narebski <jnareb@gmail.com> wrote Sun, Feb 03, 2008:
> Junio C Hamano wrote:
> > Jakub Narebski <jnareb@gmail.com> writes:
> >
> > [From] http://thread.gmane.org/gmane.comp.version-control.git/53457/focus=53458
> Julian Phillips:
> > Are you using docbook xsl 1.72?  There are known problems building the 
> > manpages with that version.  1.71 works, and 1.73 should work when it get 
> > released.

I was able to solve this problem with this patch, which adds a XSL file
used specifically for DOCBOOK_XSL_172=YesPlease and where dots and
backslashes are escaped properly so they won't be substituted to the
wrong thing further down the "DocBook XSL pipeline". Doing the escaping
in the existing callout.xsl breaks v1.70.1. Hopefully v1.73 will end
this part of the manpage nightmare.

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 7a32546..43781fb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -45,6 +45,7 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
+MANPAGE_XSL = callouts.xsl
 INSTALL?=install
 RM ?= rm -f
 DOC_REF = origin/man
@@ -65,6 +66,7 @@ ASCIIDOC_EXTRA += -a asciidoc7compatible
 endif
 ifdef DOCBOOK_XSL_172
 ASCIIDOC_EXTRA += -a docbook-xsl-172
+MANPAGE_XSL = manpage-1.72.xsl
 endif
 
 #
@@ -159,7 +161,7 @@ $(MAN_HTML): %.html : %.txt
 
 %.1 %.5 %.7 : %.xml
 	$(RM) $@
-	xmlto -m callouts.xsl man $<
+	xmlto -m $(MANPAGE_XSL) man $<
 
 %.xml : %.txt
 	$(RM) $@+ $@
diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
new file mode 100644
index 0000000..fe3cd72
--- /dev/null
+++ b/Documentation/manpage-1.72.xsl
@@ -0,0 +1,17 @@
+<!-- callout.xsl: converts asciidoc callouts to man page format -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:template match="co">
+	<xsl:value-of select="concat('&#x2593;fB(',substring-after(@id,'-'),')&#x2593;fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+	<xsl:text>&#x2302;sp&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+	<xsl:value-of select="concat('&#x2593;fB',substring-after(@arearefs,'-'),'. &#x2593;fR')"/>
+	<xsl:apply-templates/>
+	<xsl:text>&#x2302;br&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>

> Besids, I have different set of problems; only with literal blocks.
> So while DOCBOOK_XSL_172 is not set... let me check...
> 
> Hmmm...
> 
> Before
> $ man git-diff-tree
> 
>        Example:
> 
>        .ft C
>        :100644 100644 5be4a4...... 000000...... M file.c
>        .ft
> 
> $ make DOCBOOK_XSL_172=YesPlease doc
> $ man Documentation/git-diff-tree.1
> 
>        Example:
> 
>               :100644 100644 5be4a4...... 000000...... M file.cWhen -z  option  is
>               not  used, TAB, LF, and backslash characters in pathnames are repre-
>               sented as \t, \n, and \\, respectively.
> 
> So setting DOCBOOK_XSL_172 while it fixes the bug (even if docbook-xsl
> is version 1.68.1, not 1.72), but introduces another.
> 
> Unfortunately I don't know enough about AsciiDoc, DocBook and XML
> toolchain to even *try* to fix this issue.

I have no idea what this could be. The literallayout block is
overwritten in Documentation/asciidoc.conf unless when DOCBOOK_XSL_172
is set. Newer AsciiDoc installations seem to use a different set of
DocBook tags than what is overwritten by git's asciidoc.conf.

-- 
Jonas Fonseca