Re: [PATCH] Fix typesetting in Bugs section of 'git-rebase' man page (web version)

On Jan 14, 2014, at 21:36, Jason St. John wrote:

Hmmm. I've also had some problems as well getting a correct man page build although it's the non-web version. In my case I use the git- config.1 man page to detect the problem. Uninteresting lines have been replaced with "[...]" for brevity in the following samples. Using 'MANWIDTH=65 man -c ./git-config.1' the bad man page has a section that looks like this:

     http.<url>.*
        Any of the http.* options above can be applied
        selectively to some urls. For a config key to
        match a URL, each element of the config key is
        compared to that of the URL, in the following
        order:

	1. Scheme (e.g., https in
	   https://example.com/). This field must
	   match exactly between the config key and
	   the URL.
            [...]
	5. User name (e.g., user in
	   https://user@example.com/repo.git). If the
            [...]
	   precedence than a config key with a user
	   name.
	   The list above is ordered by decreasing
	   precedence; a URL that matches a config
            [...]
	   be preferred over a config key match of
	   https://user@example.com.

	   All URLs are normalized before attempting
	   any matching (the password part, if
            [...]
	   any URLs visited as a result of a
	   redirection do not participate in matching.

        i18n.commitEncoding
	   Character encoding the commit messages are
	   stored in; Git itself does not care per se,

The rest of the man page continues to be incorrectly indented too far, but I've omitted it for brevity.

The good output for the same section looks like this:

     http.<url>.*
        Any of the http.* options above can be applied
        selectively to some urls. For a config key to
        match a URL, each element of the config key is
        compared to that of the URL, in the following
        order:

	1. Scheme (e.g., https in
	   https://example.com/). This field must
	   match exactly between the config key and
	   the URL.
            [...]
	5. User name (e.g., user in
	   https://user@example.com/repo.git). If the
            [...]
	   precedence than a config key with a user
	   name.

        The list above is ordered by decreasing
        precedence; a URL that matches a config key's
        [...]
        preferred over a config key match of
        https://user@example.com.

        All URLs are normalized before attempting any
        matching (the password part, if embedded in the
        [...]
        URLs visited as a result of a redirection do
        not participate in matching.

    i18n.commitEncoding
        Character encoding the commit messages are
        stored in; Git itself does not care per se, but

I have two different systems to build these pages on:

System A:
   OS X + Mac Ports
   asciidoc --version
     asciidoc 8.6.6
   xmlto --version
     xmlto version 0.0.24
   docbook-xsl is 1.75.2_0
   produces bad git-config.1

System B:
   Ubuntu
   asciidoc --version
     asciidoc 8.5.2
   xmlto --version
     xmlto version 0.0.23
   docbook-xsl is 1.75.2+dfsg-3
   produces good git-config.1

The git-config.1 file is built like so:

1. asciidoc produces git-config.xml from git-config.txt

2. xmlto produces git-config.1 from git-config.xml

System A:
   git-config.txt: md5=c63cbafddb1bc3d6c38b6b2941f8cbce
   git-config.xml: md5=99c0caa45ec02e8712c346e8842a7ce6
   git-config.1:   md5=812f8d180ec82c2786b95e986219a5d0

System B:
   git-config.txt: md5=c63cbafddb1bc3d6c38b6b2941f8cbce
   git-config.xml: md5=99c0caa45ec02e8712c346e8842a7ce6
   git-config.1:   md5=7298467bedd0225d5edefa8700bc9b2a

So actually the problem here is not the asciidoc step, it's actually the xmlto step.

And, if I make the following changes to the git-config.1 file produced on system A:

     diff --git git-config.1 git-config-fix.1
     --- git-config.1
     +++ git-config-fix.1
     @@ -3299,7 +3299,7 @@ user
      in
      https://user@example\&.com/repo\&.git)\&. If the config key  
has[...]
      .RE
     -.RS 4
     +.sp
      The list above is ordered by decreasing precedence; a URL that  
[...]
      https://user@example\&.com/foo/bar
      a config key match of
     @@ -4460,7 +4460,7 @@ normal
      all
      \- Show also individual files in untracked directories\&.
      .RE
     -.RS 4
     +.sp
      If this variable is not specified, it defaults to
      \fInormal\fR\&. This variable can be overridden with the [...]
      \fBgit-status\fR(1)

Then it will format properly again (and in fact the $googlecode/git- manpages-*.tar.gz files have the same correct ".sp" instead of ".RS 4" lines).

Trying xmlto versions 0.0.23 and 0.0.25 on System A still produce the same wrong output, so while it appears to be the xmlto step that's the problem, it's not xmlto itself.

After much gnashing of teeth and digging it turns out the problem is in the docbook-xsl sources. Debian includes a patch file "8530_manpages_lists_indentation_fix.dpatch" in [1]:

---- BEGIN PATCH ----
#! /bin/sh /usr/share/dpatch/dpatch-run
## 8530_manpages_lists_indentation_fix.dpatch by Daniel Leidert (dale)  
<daniel.leidert@wgdd.de>
##
## All lines beginning with `## DP:' are a description of the patch.
## DP: Upstream fix from revision 8530 ( dleidert ):
## DP:   Fix two indentation issues: In the first case there is no  
corresponding
## DP:   .RS macro (Debian #519438, sf.net 2793873). In the second  
case an .RS
## DP:   instead of the probably intended .sp leads to an indentation  
bug
## DP:   (Debian #527309, sf.net #2642139).
## DP:
## DP: <URL:http://docbook.svn.sourceforge.net/docbook/?rev=8530&view=rev 
 >
## DP: <URL:http://sourceforge.net/search/?type_of_search=artifact&group_id=21935&words=2642139 
 >
## DP: <URL:http://bugs.debian.org/519438>
## DP: <URL:http://bugs.debian.org/527309>

@DPATCH@ diff -urNad trunk~/manpages/lists.xsl trunk/manpages/lists.xsl --- trunk~/manpages/lists.xsl 2009-03-27 02:25:08.000000000 +0100 +++ trunk/manpages/lists.xsl 2009-11-04 00:54:35.000000000 +0100