Junio C Hamano wrote: > Andreas Schwab <schwab@xxxxxxxxxxxxxx> writes: > >> Junio C Hamano <gitster@xxxxxxxxx> writes: >> >>> I think it depends on the likelihood that a distro has xmlto so old that >>> it does not understand --stringparam yet it uses stylesheet so new that >>> setting the parameter makes a positive difference (either it gives the >>> full URL or at least squelches the "You should define the parameter" >>> noise) in the output. >> >> openSUSE 11.2, for example. Its xmlto has a non-standard --xsltopts >> option that passes its argument down to xsltproc. > > Ok, as I said that I've been wrong before in this area ;-) > > I don't think I will have much time for git today, and it would be > appreciated if somebody can work on this and send a tested patch that > applies cleanly on top of 'maint' to implement the @@MAN_BASE_URL@@ > replacement from manpage-base.xsl.in to manpage-base.xsl as Todd suggested > earlier. Something like this perhaps? I tested it with 1.6.5.4 on Fedora 10, 12 and CentOS 5.4 but it could surely use more eyes and testing to ensure it works as it should and doesn't have unintended negative effects on make clean and such. This does set MAN_BASE_URL unconditionally, pointing to kernel.org. That way anyone building with recent DocBook and taking no new action will have something useful in the man page links. I noticed on Fedora 12 that email addresses get added to the NOTES section. For example, git-branch(1) has: Documentation by Junio C Hamano and the git-list <git@xxxxxxxxxxxxxxx[4]>. ... NOTES ... 4. git@xxxxxxxxxxxxxxx mailto:git@xxxxxxxxxxxxxxx That must be something new in DocBook, as it doesn't occur in the Fedora 10 builds. It's a little extraneous, but not harmful I guess. --- >8 --- From: Todd Zullinger <tmz@xxxxxxxxx> Date: Fri, 4 Dec 2009 12:53:21 -0500 Subject: [PATCH] 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@xxxxxxxxx> --- Documentation/.gitignore | 1 + Documentation/Makefile | 23 ++++++++++++----------- Documentation/manpage-base-url.xsl.in | 10 ++++++++++ 3 files changed, 23 insertions(+), 11 deletions(-) create mode 100644 Documentation/manpage-base-url.xsl.in diff --git a/Documentation/.gitignore b/Documentation/.gitignore index d8edd90..1c3a9fe 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -8,3 +8,4 @@ gitman.info howto-index.txt doc.dep cmds-*.txt +manpage-base-url.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index 1c9dfce..1c867fa 100644 --- 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 -# 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 = http://www.kernel.org/pub/software/scm/git/docs/ 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 @@ -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) manpage-base-url.xsl $(MAN_HTML): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ @@ -251,7 +249,10 @@ $(MAN_HTML): %.html : %.txt $(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 $< diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in new file mode 100644 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> -- 1.6.6.rc1 -- Todd OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The world keeps ending but new people too dumb to know it keep showing up as if the fun's just started. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html