Re: [ANNOUNCE] Git 1.6.5.4

From: Todd Zullinger <tmz@pobox.com>
Date: Dec 3, 2009, 22:00 UTC
Message-ID: <20091203220020.GS23717@inocybe.localdomain>
In-Reply-To: <7vfx7r4we7.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

Show 23 quoted lines

> This is what I plan to use.
>
> -- >8 ---
> From: Junio C Hamano <gitster@pobox.com>
> 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