Hi!
I've been experimenting with Boost's documentation tools outside the
Boost tree and came across a couple of issues.
1. The stylesheets assume links are relative in a couple of places. This
makes it impossible to use absolute URLs to point to various stuff.
Specifically, I was attempting to use absolute URLs in the following
xsl:params,
boost.root
boost.libraries
html.stylesheet
navig.graphics.path
The attached relative-href.patch fixes this issue by checking whether a
URL is absolute before attempting to manipulate it as a relative link.
2. BoostBook stylesheets assume header files are in boost.root
directory. To document a candidate boost library, for instance, one
might prefer to have navigation links (more, libraries, people, etc.)
pointing at the main boost site, while having doxygen-generated
reference docs pointing somewhere else. Currently header files are
assumed to be in the same place as boost.root.
boost-header-root.patch introduces an additional xsl:param
boost.header.root that defaults to boost.root for backward compatibility.
3. The Boost logo that shows in BoostBook generated documentation has an
alt attribute of "boost.png (6897 bytes)" while the actual size of the
logo is currently 6308 bytes. I think it would be better if it simply
read "Boost Logo" or something like that. If this solution is deemed
acceptable, there's another patch that fixes that too.
I'd like to hear others' comments and whether I may commit any of the
proposed changes to CVS.
Best regards,
João
Index: tools/boostbook/xsl/relative-href.xsl
===================================================================
RCS file: /cvsroot/boost/boost/tools/boostbook/xsl/relative-href.xsl,v
retrieving revision 1.2
diff -u -r1.2 relative-href.xsl
--- tools/boostbook/xsl/relative-href.xsl 8 Oct 2004 23:03:02 -0000 1.2
+++ tools/boostbook/xsl/relative-href.xsl 4 Jan 2006 04:23:09 -0000
@@ -6,10 +6,51 @@
<!-- ==================================================================== -->
+<!-- Check if path is absolute before updating according to given context
+
+ No attempt is made to fully parse and validate absolute or relative URL.
+ Assuming an absolute url when $target begins with
+
+ [a-zA-Z+-.]*:
+
+ According to the RFC1808, the colon may also appear in a relative URL. To
+ workaround this limitation for a relative link containing colons (e.g.
+ this:that) one may use the alternatives below, instead.
+
+ ./this:that
+ this%3Athat
+-->
<xsl:template name="href.target.relative">
<xsl:param name="target"/>
<xsl:param name="context" select="."/>
+ <xsl:variable name="isabsolute">
+ <xsl:variable name="scheme1" select="substring-before($target, ':')"/>
+ <xsl:variable name="scheme2" select="translate($scheme1, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+-.', '')"/>
+ <xsl:if test="$scheme1 and not($scheme2)">1</xsl:if>
+ </xsl:variable>
+
+ <xsl:choose>
+
+ <xsl:when test="$isabsolute='1'">
+ <xsl:value-of select="$target"/>
+ </xsl:when>
+
+ <xsl:otherwise>
+ <xsl:call-template name="href.target.relative2">
+ <xsl:with-param name="target" select="$target"/>
+ <xsl:with-param name="context" select="$context"/>
+ </xsl:call-template>
+ </xsl:otherwise>
+
+ </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="href.target.relative2">
+ <xsl:param name="target"/>
+ <xsl:param name="context" select="."/>
+
<xsl:variable name="href.to.uri" select="$target"/>
<xsl:variable name="href.from.uri">
<xsl:call-template name="href.target.uri">
Index: tools/boostbook/xsl/docbook.xsl
===================================================================
RCS file: /cvsroot/boost/boost/tools/boostbook/xsl/docbook.xsl,v
retrieving revision 1.15
diff -u -r1.15 docbook.xsl
--- tools/boostbook/xsl/docbook.xsl 17 Nov 2005 20:40:05 -0000 1.15
+++ tools/boostbook/xsl/docbook.xsl 4 Jan 2006 04:23:09 -0000
@@ -12,6 +12,7 @@
<!-- The root of the Boost directory -->
<xsl:param name="boost.root" select="'../..'"/>
+ <xsl:param name="boost.header.root" select="$boost.root"/>
<!-- A space-separated list of libraries to include in the
output. If this list is empty, all libraries will be included. -->
@@ -90,7 +91,7 @@
<xsl:text>Header <</xsl:text>
<ulink>
<xsl:attribute name="url">
- <xsl:value-of select="$boost.root"/>
+ <xsl:value-of select="$boost.header.root"/>
<xsl:text>/</xsl:text>
<xsl:value-of select="@name"/>
</xsl:attribute>
Index: navbar.xsl
===================================================================
RCS file: /cvsroot/boost/boost/tools/boostbook/xsl/navbar.xsl,v
retrieving revision 1.4
diff -u -r1.4 navbar.xsl
--- navbar.xsl 8 Oct 2004 17:39:49 -0000 1.4
+++ navbar.xsl 4 Jan 2006 04:42:46 -0000
@@ -32,7 +32,7 @@
<xsl:param name = "boost.root" select = "'../..'"/>
<xsl:param name = "boost.image.src"
select = "concat($boost.root, '/boost.png')"/>
- <xsl:param name = "boost.image.alt" select = "'boost.png (6897 bytes)'"/>
+ <xsl:param name = "boost.image.alt" select = "'Boost Logo'"/>
<xsl:param name = "boost.image.w" select = "277"/>
<xsl:param name = "boost.image.h" select = "86"/>
<xsl:param name = "boost.libraries" select = "'libraries.html'"/>
