A typesetting problem with git man pages

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.

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

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

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

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

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

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.

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

---
 Documentation/asciidoc.conf |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

Teemu Likonen <[email protected]> wrote Thu, Oct 30, 2008:

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.

index 40d43b7..2da867d 100644
@@ -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

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:

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

Hello --

2008/11/1 Junio C Hamano <[email protected]>:

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

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