man pages are littered with .ft C and others

man pages are littered with .ft C and others

[Adam Flott]

I do remember at one point the man pages looking correctly (just tested
v1.5.3.8 and it shows the same problem). Therefore it is probably
some package I'm missing on my system.

And now, I see this scattered all over:

For example:

      .ft C
      $ git checkout master             \fB(1)\fR
      $ git checkout master~2 Makefile  \fB(2)\fR
      $ rm -f hello.c
      $ git checkout hello.c            \fB(3)\fR
      .ft

Seems that "------------" and <n>, and a few others aren't being
translated. Note: I'm not at all familiar with the layout of man pages
so I have no idea how to fix it or even diagnose it further.


Version info:
up to date Kubuntu 7.10

asciidoc/gutsy uptodate 8.2.1-2
docbook-dsssl/gutsy uptodate 1.79-4
docbook-utils/gutsy uptodate 0.6.14-1
docbook-xml/gutsy uptodate 4.5-4
docbook-xsl-doc-html/gutsy uptodate 1.72.0.dfsg.1-2
docbook-xsl/gutsy uptodate 1.72.0.dfsg.1-2
xmlto/gutsy uptodate 0.0.18-5.1build1


Anyone else seeing this?


Adam

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

[Geert Bosch]

On Feb 2, 2008, at 12:25, Adam Flott <adam@npjh.com> wrote:
> I do remember at one point the man pages looking correctly (just  
> tested
> v1.5.3.8 and it shows the same problem). Therefore it is probably
> some package I'm missing on my system.
>
> And now, I see this scattered all over:
>
> For example:
>
>     .ft C
>     $ git checkout master             \fB(1)\fR
>     $ git checkout master~2 Makefile  \fB(2)\fR
>     $ rm -f hello.c
>     $ git checkout hello.c            \fB(3)\fR
>     .ft
>
> Seems that "------------" and <n>, and a few others aren't being
> translated.
(...)
> Anyone else seeing this?
Yes, I'm seeing this on mac as well.

-geert

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

[Jakub Narebski]

Adam Flott <adam@npjh.com> writes:

> I do remember at one point the man pages looking correctly (just tested
> v1.5.3.8 and it shows the same problem). Therefore it is probably
> some package I'm missing on my system.

Or perhaps lack of configuration during build.

I have simply build git from original source RPM; this SRPM
does not use pre-compiled manpages (as it could), neither uses
configure to do autodetection of features (which might have
detected and fixed some build configuration needed).

Makefile has ASCIIDOC8 (set automatically by configure)
and DOCBOOK_XSL_172 (which is not autodetected).
 
> And now, I see this scattered all over:
> 
> For example:
> 
>       .ft C
>       $ git checkout master             \fB(1)\fR
>       $ git checkout master~2 Makefile  \fB(2)\fR
>       $ rm -f hello.c
>       $ git checkout hello.c            \fB(3)\fR
>       .ft
> 
> Seems that "------------" and <n>, and a few others aren't being
> translated. Note: I'm not at all familiar with the layout of man pages
> so I have no idea how to fix it or even diagnose it further.

I see the same error in manpages, for example in git-diff-tree(1)

       Example:

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

> Version info:
> up to date Kubuntu 7.10

Old Aurox Linux 11.1 (based on Fedora Core 4 + some updates)

> asciidoc/gutsy uptodate 8.2.1-2
> docbook-dsssl/gutsy uptodate 1.79-4
> docbook-utils/gutsy uptodate 0.6.14-1
> docbook-xml/gutsy uptodate 4.5-4
> docbook-xsl-doc-html/gutsy uptodate 1.72.0.dfsg.1-2
> docbook-xsl/gutsy uptodate 1.72.0.dfsg.1-2
> xmlto/gutsy uptodate 0.0.18-5.1build1

asciidoc-7.1.2-2.fc3.rf
docbook-dtds-1.0-26
docbook-style-dsssl-1.79-1
docbook-style-xsl-1.68.1-1
docbook-utils-0.6.14-4
docbook-utils-pdf-0.6.14-4
xmlto-0.0.18-6
 
$ asciidoc --version
asciidoc 7.1.2
$ xmlto --version
xmlto version 0.0.18

>From VERSION file in docbook-style-xsl:
<fm:project>
  <fm:Project>DocBook</fm:Project>
  <fm:Branch>XSL Stylesheets</fm:Branch>
  <fm:Version>1.68.1</fm:Version>

> Anyone else seeing this?

I'm also seeing this.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> I see the same error in manpages, for example in git-diff-tree(1)

http://thread.gmane.org/gmane.comp.version-control.git/53457/focus=53458

rings a bell?

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

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>> 
>> I see the same error in manpages, for example in git-diff-tree(1)
> 
> http://thread.gmane.org/gmane.comp.version-control.git/53457/focus=53458
> 
> rings a bell?

You mean:

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.

No, I am using docbook-style-xsl-1.68.1-1, and compiling git from RPM.
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.


P.S. Alternate soution would be for SRPM to contain pre-compiled
manpages, and not require asciidoc and its toolchain to provide
manpages.
-- 
Jakub Narebski
Poland

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

[Jonas Fonseca]

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

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

[Jakub Narebski]

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

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

[Jonas Fonseca]

Jakub Narebski <jnareb@gmail.com> wrote Tue, Feb 05, 2008:
> 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

OK, I might have been a bit unclear, but the patch was not intended for
you but for users of version 1.72+. ;)

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

But not as easy as just pulling the documentation branches.

-- 
Jonas Fonseca

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

[Junio C Hamano]

Jonas Fonseca <fonseca@diku.dk> writes:

> Jakub Narebski <jnareb@gmail.com> wrote Tue, Feb 05, 2008:
>
>> 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...
>
> But not as easy as just pulling the documentation branches.

But your approach has a small flaw of chicken-and-egg problem
;-).

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

[Jakub Narebski]

Jakub Narebski wrote:

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

Sorry, I must have had run "make doc" without "make clean" first.
Of course patch doesn't change anything for pre 1.72, and marked
as such.

One again, I'm sory for the confusion.

The old .ft C... .ft error remains.
-- 
Jakub Narebski
Poland

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

[Junio C Hamano]

Jonas Fonseca <fonseca@diku.dk> writes:

> 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 checked this with 1.71, 1.69 and 1.72 (with DOCBOOK_XSL_172).
It seems not to regress.

Applied to 'master'.  Thanks.