Documentation: Avoid use of xmlto --stringparam

The --stringparam option is not available on older xmlto versions.
Instead, set man.base.url.for.relative.links via a .xsl file.  Older
docbook versions will ignore this without causing grief to users of
older xmlto versions.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index d8edd904065fbc4bd06365ce378f57d4cd8f9f0d..1c3a9fead579a9b52037f1bbe245998db8a2f40b 100644 (file)
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -8,3 +8,4 @@ gitman.info
 howto-index.txt
 doc.dep
 cmds-*.txt
 howto-index.txt
 doc.dep
 cmds-*.txt

+manpage-base-url.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 1c9dfcea5addb91c3025f8f23eb9364e3bccd054..037220f544abb5fe9c3a98c313bdb10208a79166 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -104,18 +104,15 @@ XMLTO_EXTRA += -m manpage-suppress-sp.xsl
 endif
 
 # Newer DocBook stylesheet emits warning cruft in the output when
 endif
 
 # Newer DocBook stylesheet emits warning cruft in the output when

-# this is not set, and if set it shows an absolute link.  We can
-# use MAN_BASE_URL=http://www.kernel.org/pub/software/scm/git/docs/
-# but distros may want to set it to /usr/share/doc/git-core/docs/ or
-# something like that.
+# this is not set, and if set it shows an absolute link.  Older
+# stylesheets simply ignore this parameter.

 #
 #

-# As older stylesheets simply ignore this parameter, it ought to be
-# safe to set it to empty string when the base URL is not specified,
-# but unfortunately we cannot do so unconditionally because at least
-# xmlto 0.0.18 is reported to lack --stringparam option.
-ifdef MAN_BASE_URL
-XMLTO_EXTRA += --stringparam man.base.url.for.relative.links=$(MAN_BASE_URL)
+# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/
+# or similar.
+ifndef MAN_BASE_URL
+MAN_BASE_URL = file://$(htmldir)/

 endif
 endif

+XMLTO_EXTRA += -m manpage-base-url.xsl

 
 # If your target system uses GNU groff, it may try to render
 # apostrophes as a "pretty" apostrophe using unicode.  This breaks
 
 # If your target system uses GNU groff, it may try to render
 # apostrophes as a "pretty" apostrophe using unicode.  This breaks


@@ -244,6 +241,7 @@ clean:
        $(RM) howto-index.txt howto/*.html doc.dep
        $(RM) technical/api-*.html technical/api-index.txt
        $(RM) $(cmds_txt) *.made
        $(RM) howto-index.txt howto/*.html doc.dep
        $(RM) technical/api-*.html technical/api-index.txt
        $(RM) $(cmds_txt) *.made

+       $(RM) manpage-base-url.xsl

 
 $(MAN_HTML): %.html : %.txt
        $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 
 $(MAN_HTML): %.html : %.txt
        $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \


@@ -251,7 +249,10 @@ $(MAN_HTML): %.html : %.txt
                $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
        mv $@+ $@
 
                $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
        mv $@+ $@
 

-%.1 %.5 %.7 : %.xml
+manpage-base-url.xsl: manpage-base-url.xsl.in
+       sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
+
+%.1 %.5 %.7 : %.xml manpage-base-url.xsl

        $(QUIET_XMLTO)$(RM) $@ && \
        xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
        $(QUIET_XMLTO)$(RM) $@ && \
        xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 

diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in
new file mode 100644 (file)
index 0000000..e800904
--- /dev/null
+++ b/Documentation/manpage-base-url.xsl.in
@@ -0,0 +1,10 @@
+<!-- manpage-base-url.xsl:
+     special settings for manpages rendered from newer docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+               version="1.0">
+
+<!-- set a base URL for relative links -->
+<xsl:param name="man.base.url.for.relative.links"
+       >@@MAN_BASE_URL@@</xsl:param>
+
+</xsl:stylesheet>