threads / discuss / 11843

man pages are littered with .ft C and others

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

## tl;dr

11 messages between Feb 2, 2008 and Feb 5, 2008.

replies: 10people: 5as markdown or json

Adam Flott· Feb 2, 2008, 17:25 UTC · lore

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
Geert Bosch· Feb 2, 2008, 17:46 UTC · re: Adam Flott · lore

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

On Feb 2, 2008, at 12:25, Adam Flott <adam@npjh.com> wrote:
Show 18 quoted lines
> 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
Jakub Narebski· Feb 2, 2008, 18:49 UTC · re: Adam Flott · lore

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

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).
Show 14 quoted lines
> 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)
Show 7 quoted lines
> 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
Junio C Hamano· Feb 3, 2008, 08:36 UTC · re: Jakub Narebski · lore

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

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?
Jakub Narebski· Feb 3, 2008, 10:39 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 7 quoted lines
> 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
Jonas Fonseca· Feb 4, 2008, 22:01 UTC · re: Jakub Narebski · lore

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

Jakub Narebski <jnareb@gmail.com> wrote Sun, Feb 03, 2008:
Show 8 quoted lines
> 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
Jakub Narebski· Feb 4, 2008, 23:26 UTC · re: Jonas Fonseca · lore

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

On Mon, 4 Feb 2008, Jonas Fonseca wrote:
Show 16 quoted lines
> 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

[...]
Show 33 quoted lines
> > 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
Jonas Fonseca· Feb 5, 2008, 00:00 UTC · re: Jakub Narebski · lore

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

Jakub Narebski <jnareb@gmail.com> wrote Tue, Feb 05, 2008:
Show 20 quoted lines
> 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
Junio C Hamano· Feb 5, 2008, 00:28 UTC · re: Jonas Fonseca · lore

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

Jonas Fonseca <fonseca@diku.dk> writes:
Show 7 quoted lines
> 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 ;-).

Jakub Narebski· Feb 5, 2008, 01:21 UTC · re: Jakub Narebski · lore

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

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
Junio C Hamano· Feb 5, 2008, 09:59 UTC · re: Jonas Fonseca · lore

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

Jonas Fonseca <fonseca@diku.dk> writes:
Show 6 quoted lines
> 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.

← back to recent threads