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>
Todd Zullinger committed
Dec 4, 2009 at 12:53 UTC
50d9bbba92c9dd5611a1bb592fc42463212413ad
3 files changed
+23
-11
Documentation/.gitignore
+1
@@ -8,3 +8,4 @@ gitman.info
8
howto-index.txt
9
doc.dep
10
cmds-*.txt
11
+manpage-base-url.xsl
Documentation/Makefile
+12
-11
@@ -104,18 +104,15 @@ XMLTO_EXTRA += -m manpage-suppress-sp.xsl
104
endif
105
106
# Newer DocBook stylesheet emits warning cruft in the output when
107
-# this is not set, and if set it shows an absolute link. We can
108
-# use MAN_BASE_URL=http://www.kernel.org/pub/software/scm/git/docs/
109
-# but distros may want to set it to /usr/share/doc/git-core/docs/ or
110
-# something like that.
107
+# this is not set, and if set it shows an absolute link. Older
108
+# stylesheets simply ignore this parameter.
109
#
112
-# As older stylesheets simply ignore this parameter, it ought to be
113
-# safe to set it to empty string when the base URL is not specified,
114
-# but unfortunately we cannot do so unconditionally because at least
115
-# xmlto 0.0.18 is reported to lack --stringparam option.
116
-ifdef MAN_BASE_URL
117
-XMLTO_EXTRA += --stringparam man.base.url.for.relative.links=$(MAN_BASE_URL)
110
+# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/
111
+# or similar.
112
+ifndef MAN_BASE_URL
113
+MAN_BASE_URL = file://$(htmldir)/
114
endif
115
+XMLTO_EXTRA += -m manpage-base-url.xsl
116
117
# If your target system uses GNU groff, it may try to render
118
# apostrophes as a "pretty" apostrophe using unicode. This breaks
@@ -244,6 +241,7 @@ clean:
241
$(RM) howto-index.txt howto/*.html doc.dep
242
$(RM) technical/api-*.html technical/api-index.txt
243
$(RM) $(cmds_txt) *.made
244
+ $(RM) manpage-base-url.xsl
245
246
$(MAN_HTML): %.html : %.txt
247
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
@@ -251,7 +249,10 @@ $(MAN_HTML): %.html : %.txt
249
$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
250
mv $@+ $@
251
254
-%.1 %.5 %.7 : %.xml
252
+manpage-base-url.xsl: manpage-base-url.xsl.in
253
+ sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
254
+
255
+%.1 %.5 %.7 : %.xml manpage-base-url.xsl
256
$(QUIET_XMLTO)$(RM) $@ && \
257
xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
258
Documentation/manpage-base-url.xsl.in
new
+10
@@ -0,0 +1,10 @@
1
+<!-- manpage-base-url.xsl:
2
+ special settings for manpages rendered from newer docbook -->
3
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4
+ version="1.0">
5
+
6
+<!-- set a base URL for relative links -->
7
+<xsl:param name="man.base.url.for.relative.links"
8
+ >@@MAN_BASE_URL@@</xsl:param>
9
+
10
+</xsl:stylesheet>