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

[Jakub Narebski <jnareb@gmail.com>]

On Mon, 4 Feb 2008, Jonas Fonseca wrote:
> 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.

I have applied this patch, and it makes manpages worse, not better.
I use DocBook XSL version 1.68.1

[...]
> > 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.

Now I have in git-diff-tree(1), result of (after applying above patch)
$ man Documentation/git-diff-tree.1

       git-diff-files [<pattern>...]
              compares the index and the files on the filesystem.

              An output line is formatted this way:

              in-place   edit    :100644  100644  bcd1234...  0123456...  M  file0
              copy-edit      :100644 100644 abcd123... 1234567... C68 file1  file2
              rename-edit     :100644 100644 abcd123... 1234567... R86 file1 file3
              create         :000000 100644 0000000... 1234567... A  file4  delete
              :100644  000000 1234567... 0000000... D file5 unmerged       :000000
              000000 0000000... 0000000... U file6That is, from the  left  to  the
              right:

[...]

       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.


Compare this to output of "man git-diff-tree", same situation, compiled
from SRPM, without any aditional options:

       git-diff-files [<pattern>...]
              compares the index and the files on the filesystem.

              An output line is formatted this way:

              .ft C
              in-place edit  :100644 100644 bcd1234... 0123456... M file0
              copy-edit      :100644 100644 abcd123... 1234567... C68 file1 file2
              rename-edit    :100644 100644 abcd123... 1234567... R86 file1 file3
              create         :000000 100644 0000000... 1234567... A file4
              delete         :100644 000000 1234567... 0000000... D file5
              unmerged       :000000 000000 0000000... 0000000... U file6
              .ft

              That is, from the left to the right:

[...]

       Example:

       .ft C
       :100644 100644 5be4a4...... 000000...... M file.c
       .ft

       When -z option is not used, TAB, LF, and backslash characters in  pathnames
       are represented as \t, \n, and \\, respectively.


HTH.

P.S. writing subset of AsciiDoc in Perl, which would write manpages, HTML
and perhaps info/texinfo files directly, without fragile xmlto toolchain,
looks better and better...

$ asciidoc --version
asciidoc 7.1.2
$ rpm -qa docbook*         
docbook-utils-0.6.14-4
docbook-style-xsl-1.68.1-1
docbook-style-dsssl-1.79-1
docbook-utils-pdf-0.6.14-4
docbook-dtds-1.0-26
$ xmlto --version
xmlto version 0.0.18
-- 
Jakub Narebski
Poland