Re: [ANNOUNCE] Git 1.6.5.4

Junio C Hamano wrote:

This is what I plan to use.

-- >8 ---
From: Junio C Hamano <redacted>
Date: Thu, 3 Dec 2009 11:12:32 -0800
Subject: [PATCH] Documentation: xmlto 0.0.18 does not know --stringparam

Newer DocBook stylesheets want man.base.url.for.relative.links
parameter set when formatting manpages with external references
to turn them into full URLs, and leave a helpful "you should
set this parameter" message in the output.  Earlier we added
the MAN_BASE_URL make variable to specify the value for it.

When MAN_BASE_URL is not given, it ought to be safe to set the
parameter to empty; it would result in an empty leading path for
older stylesheets that ignore the parameter, and newer ones
would produce the same "relative URL" without the message.

Unfortunately, older xmlto (at least version 0.0.18 released in
early 2004 that comes with RHEL/CentOS 5) does not understand
the --stringparam command line option, so we cannot add the
parameter definition unconditionally to the command line.  Work
it around by passing the parameter only when set.

Is it worth sidestepping the xmlto part entirely?  If we set this
directly in a .xsl file, it will work on older systems without any
effort.  Then we can default MAN_BASE_URL to something and let distro
packagers override it.

I tested with this in Documentation/manpage-base.xsl on a CentOS 5 box
and it builds fine, leaving no cruft in the man pages regarding the
man.base.url...

<!-- set a base URL for relative links -->
<xsl:param name="man.base.url.for.relative.links"
       >/path/to/git/docs</xsl:param>

Of course, the relative links looked just like they did in older
docbook releases:

       1. Everyday Git
          everyday.html

Is it worth the effort to have @@MAN_BASE_URL@@ in
Documentation/manpage-base.xsl or similar and replace it at build
time?

-- 
Todd        OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just because everything is different doesn't mean anything has
changed.
    -- Irene Peter