A typesetting problem with git man pages

A typesetting problem with git man pages

[Teemu Likonen]

I compile git and its man pages myself and I just noticed that the man
pages (invoked with "git help log", for example) have a typesetting
problem. There are ".ft" commands here and there, like this:

    .ft C
    [i18n]
            commitencoding = ISO-8859-1
    .ft

Does anybody know why "man" prints those ".ft" commands? The
corresponding code in git-log.1 file is this:

    \&.ft C
    [i18n]
            commitencoding = ISO\-8859\-1
    \&.ft

Recently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and
it is possible that some tools which are related to compiling the man
pages are now newer versions.

Re: A typesetting problem with git man pages

[Jonas Fonseca]

On Wed, Oct 29, 2008 at 20:16, Teemu Likonen <tlikonen@iki.fi> wrote:
> Does anybody know why "man" prints those ".ft" commands? The
> corresponding code in git-log.1 file is this:
>
>    \&.ft C
>    [i18n]
>            commitencoding = ISO\-8859\-1
>    \&.ft
>
> Recently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and
> it is possible that some tools which are related to compiling the man
> pages are now newer versions.

I had a similar problem after upgrading on Ubuntu and came up with a
patch to optionally disable some of asciidoc.conf (commit
7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.

-- 
Jonas Fonseca

Re: A typesetting problem with git man pages

[Jeff King]

On Wed, Oct 29, 2008 at 09:16:52PM +0200, Teemu Likonen wrote:

> I compile git and its man pages myself and I just noticed that the man
> pages (invoked with "git help log", for example) have a typesetting
> problem. There are ".ft" commands here and there, like this:

I think this is Yet Another docbook or asciidoc issue. The resulting XML
from asciidoc is:

  <literallayout>
  &#10;.ft C&#10;
  ... the actual example contents ...
  &#10;.ft&#10;
  </literallayout>

which kind of seems wrong to me, since it implies that that is part of
the literal layout, and would be subject to quoting. It gets rendered
into git-log.1 as:

  \&.ft C
  ... the actual examples contents
  \&.ft

so the problem is the extra \&. But I don't know why that is being
generated. It _should_ be part of the character entity, I thought, but
xmlto seems to be rendering it as the newline character entity _plus_
the ampersand.

So it seems like a bug to me in the XML parser, but it is more likely
that I'm somehow clueless about XML.

-Peff

Re: A typesetting problem with git man pages

[Jonas Fonseca]

On Wed, Oct 29, 2008 at 20:39, Jeff King <peff@peff.net> wrote:
> so the problem is the extra \&. But I don't know why that is being
> generated. It _should_ be part of the character entity, I thought, but
> xmlto seems to be rendering it as the newline character entity _plus_
> the ampersand.
>
> So it seems like a bug to me in the XML parser, but it is more likely
> that I'm somehow clueless about XML.

The way I understand it is that the DocBook XSL (stylesheet) doing the
conversion from xml to the manpage ensures that possible problematic
characters that could break the manpage are escaped. A dot in the
start of a line is problematic since it could be interpreted as markup
by the manpage viewer and in the mentioned case, the code was not
generated by the stylesheet, thus it must be escaped. So IMO, the
stylesheet is hardly to blame, the problem is that the asciidoc.conf
file defines a macro for literallayout, in which it expects manpage
code to be passed through unescaped.

-- 
Jonas Fonseca

Re: A typesetting problem with git man pages

[Teemu Likonen]

Jonas Fonseca (2008-10-29 20:35 +0100) wrote:

> On Wed, Oct 29, 2008 at 20:16, Teemu Likonen <tlikonen@iki.fi> wrote:
>> Does anybody know why "man" prints those ".ft" commands? The
>> corresponding code in git-log.1 file is this:

> I had a similar problem after upgrading on Ubuntu and came up with a
> patch to optionally disable some of asciidoc.conf (commit
> 7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.

Ah, thank you. That fixed it.

In case someone is interested there is still a minor flaw that an
example command and the following paragraph is printed with no empty
line between them. Like in the beginning of "git help tutorial", for
example:

    First, note that you can get documentation for a command such as git
    log --graph with:

        $ man git-log             
    It is a good idea to introduce yourself to git [...]

It would be nicer if there was empty line after "$ man git-log". I can't
remember if this is new issue or not. This applies only to man pages; in
html pages there are nice boxes around example commands and equal
spacing before and after them.

[PATCH] asciidoc: add minor workaround to add an empty line after code blocks

[Jonas Fonseca]

Insert an empty <simpara> in manpages after code blocks to force and
empty line.

The problem can be seen on the manpage for the git tutorial, where an
example command and the following paragraph is printed with no empty
line between them:

     First, note that you can get documentation for a command such as git
     log --graph with:
 
         $ man git-log             
     It is a good idea to introduce yourself to git [...]

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---
 Documentation/asciidoc.conf |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

 Teemu Likonen <tlikonen@iki.fi> wrote Thu, Oct 30, 2008:
 > In case someone is interested there is still a minor flaw that an
 > example command and the following paragraph is printed with no empty
 > line between them. Like in the beginning of "git help tutorial", for
 > example:
 > 
 >     First, note that you can get documentation for a command such as git
 >     log --graph with:
 > 
 >         $ man git-log             
 >     It is a good idea to introduce yourself to git [...]
 > 
 > It would be nicer if there was empty line after "$ man git-log". I can't
 > remember if this is new issue or not. This applies only to man pages; in
 > html pages there are nice boxes around example commands and equal
 > spacing before and after them.

 This is an old issue reported by Theodore Ts'o and fixed partially in
 commit 63c97ce228f2d2697a8ed954a9592dfb5f286338 for the URL section of
 the fetch/pull/push manpages. I have fixed this in tig using an
 approach similar to the attached. Simple and clean, but only tested
 with docbook-xsl version 1.72 so I have made it conditional.

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 40d43b7..2da867d 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -40,6 +40,26 @@ endif::doctype-manpage[]
 </literallayout>
 {title#}</example>
 endif::docbook-xsl-172[]
+
+ifdef::docbook-xsl-172[]
+ifdef::doctype-manpage[]
+# The following two small workarounds insert a simple paragraph after screen
+[listingblock]
+<example><title>{title}</title>
+<screen>
+|
+</screen><simpara></simpara>
+{title#}</example>
+
+[verseblock]
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+{title#}<literallayout>
+|
+</literallayout><simpara></simpara>
+{title#}</para></formalpara>
+endif::doctype-manpage[]
+endif::docbook-xsl-172[]
 endif::backend-docbook[]
 
 ifdef::doctype-manpage[]
-- 
1.6.0.3.756.gb776d.dirty

-- 
Jonas Fonseca

Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks

[Teemu Likonen]

Jonas Fonseca (2008-10-30 11:45 +0100) wrote:

> Insert an empty <simpara> in manpages after code blocks to force and
> empty line.

>  This is an old issue reported by Theodore Ts'o and fixed partially in
>  commit 63c97ce228f2d2697a8ed954a9592dfb5f286338 for the URL section
>  of the fetch/pull/push manpages. I have fixed this in tig using an
>  approach similar to the attached. Simple and clean, but only tested
>  with docbook-xsl version 1.72 so I have made it conditional.

Thanks. Your patch seems to work and code blocks look much nicer now. I
tested command-line "man" as well as Emacs' "M-x man" and "M-x woman".
I'm using docbook-xsl Debian package version 1.73.2.dfsg.1-4.

Another kind of formatting issue exists with some other example
commands, like in "git rebase" manpage, for example. Not that I care
that much, but here's an example. The asciidoc source (git-rebase.txt)
contains:

    then the command

        git rebase --onto topicA~5 topicA~3 topicA

    would result in the removal of commits F and G:

In final manpage output it looks like this:

    then the command                               

        git rebase --onto topicA~5 topicA~3 topicA 
    would result in the removal of commits F and G:

Re: A typesetting problem with git man pages

[Teemu Likonen]

Jonas Fonseca (2008-10-29 20:35 +0100) wrote:

> On Wed, Oct 29, 2008 at 20:16, Teemu Likonen <tlikonen@iki.fi> wrote:
>> Does anybody know why "man" prints those ".ft" commands? The
>> corresponding code in git-log.1 file is this:
>>
>>    \&.ft C
>>    [i18n]
>>            commitencoding = ISO\-8859\-1
>>    \&.ft
>>
>> Recently I upgraded my system from Debian 4.0 (Etch) to 5.0 (Lenny) and
>> it is possible that some tools which are related to compiling the man
>> pages are now newer versions.
>
> I had a similar problem after upgrading on Ubuntu and came up with a
> patch to optionally disable some of asciidoc.conf (commit
> 7f55cf451c9e7). Try putting DOCBOOK_XSL_172=Yes in your config.mak.

Alas, there are still problems - or at least I have. Let's look at the
"git checkout" manual page and its output in the "EXAMPLES" section:


        $ 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     
    â                                                   
    âfB1. âfRswitch branch â                            
    âfB2. âfRtake out a file out of other commit â      
    âfB3. âfRrestore hello.c from HEAD of current branch

    If you have an unfortunate branch that is named hello.c, this step
    would be confused as an instruction to switch to that branch. You
    should instead write:

        $ git checkout -- hello.c
    â
    .RE

    2.  After working in a wrong branch, switching to the correct branch
       would be done using:

           $ git checkout mytopic


The corresponding code in the git-checkout.txt file:


    ------------                                   
    $ git checkout master             <1>          
    $ git checkout master~2 Makefile  <2>          
    $ rm -f hello.c                                
    $ git checkout hello.c            <3>          
    ------------                                   
    +                                              
    <1> switch branch                              
    <2> take out a file out of other commit        
    <3> restore hello.c from HEAD of current branch
    +
    If you have an unfortunate branch that is named `hello.c`, this
    step would be confused as an instruction to switch to that branch.
    You should instead write:
    +
    ------------
    $ git checkout -- hello.c
    ------------

    . After working in a wrong branch, switching to the correct
    branch would be done using:
    +
    ------------
    $ git checkout mytopic
    ------------

Re: A typesetting problem with git man pages

[Teemu Likonen]

Teemu Likonen (2008-10-31 09:37 +0200) wrote:

> Alas, there are still problems - or at least I have. Let's look at the
> "git checkout" manual page and its output in the "EXAMPLES" section:
>
>
>         $ 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     
>     â                                                   
>     âfB1. âfRswitch branch â                            
>     âfB2. âfRtake out a file out of other commit â      
>     âfB3. âfRrestore hello.c from HEAD of current branch

This has been reported to Debian so perhaps the issue is
Debian-specific. I don't know. The bug was found in Debian git-core
package version 1:1.5.6-1.

    http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490863

Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks

[Junio C Hamano]

Thanks; I do not have an environment with docbook-xsl-172 handy, so I'll
just take your word and apply it to 'maint'.

Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks

[Thomas Adam]

Hello --

2008/11/1 Junio C Hamano <gitster@pobox.com>:
> Thanks; I do not have an environment with docbook-xsl-172 handy, so I'll
> just take your word and apply it to 'maint'.

Just out of interest, how much progression on the asciidoc Git
documentation is there with respect to the latest version of asciidoc
which might give new features, if that makes sense?   Something the
ELinks project does is distribute a fixed version of the asciidoc
script to avoid annoying asciidoc errors each time there's a new
asciidoc release.

Is this something worth considering for Git as well?

-- Thomas Adam

Re: [PATCH] asciidoc: add minor workaround to add an empty line after code blocks

[Kalle Olavi Niemitalo]

"Thomas Adam" <thomas.adam22@gmail.com> writes:

> Something the ELinks project does is distribute a fixed version
> of the asciidoc script to avoid annoying asciidoc errors each
> time there's a new asciidoc release.

Actually, we only distribute the AsciiDoc configuration files.
I should perhaps add the actual asciidoc Python script to the
ELinks source tree as well.  That seems to be the recommendation
in the AsciiDoc manual.

http://www.methods.co.nz/asciidoc/userguide.html#_shipping_stand_alone_asciidoc_source