merge RC_1_32_0 fixes

[SVN r26333]

doc/boostbook.xml

@@ -317,6 +317,16 @@ using boostbook : DOCBOOK_XSL_DIR
       name). If the right <command>doxygen</command> executable can be
       found via the path, this parameter can be omitted.</para>
       
+      <important>
+        <para>The relative order of declarations in 
+        <filename>user-config.jam</filename> / <filename>site-config.jam</filename>
+        files is significant. In particular, <literal>using doxygen</literal> 
+        line should come <emphasis>after</emphasis> the
+        <literal>using boostbook</literal> declaration.
+        </para>
+      </important>
+      
+
       <para>Generating of documentation from source files using
       Doxygen requires two steps. The first step involves identifying
       the source files so that Doxygen can process them. The second
@@ -348,6 +358,21 @@ boostbook any : any.doxygen ;</programlisting>
         <listitem><simpara>Further transformations may generate HTML, FO, PDF, etc. from <filename>any.docbook</filename>.</simpara></listitem>
       </orderedlist>
     </section>
+
+    <section id="boostbook.troubleshooting">
+      <title>Troubleshooting</title>
+    
+      <para>The Boost documentation tools are still in their early phase of 
+      development, and some things don't work as seamlessly as we would like 
+      them to, yet. In particular, error messages can be somewhat 
+      uninformative at times. If you find yourself in the situation when 
+      you have double checked everything, and yet things still don't work as 
+      expected, consider helping the tools by deleting 
+      <literal>bin.v2</literal> build directory.
+      </para>
+ 
+    </section>
+
   </chapter>
     
   <xi:include href="documenting.xml"/>

xsl/chunk-common.xsl

@@ -85,21 +85,27 @@
             <xsl:value-of select="."/>
         </xsl:when>
         <xsl:otherwise>
-            <xsl:variable name="target_uri">
-                <xsl:call-template name="relative-uri">
-                    <xsl:with-param name="destdir">
-                        <xsl:call-template name="dbhtml-dir">
-                            <xsl:with-param name="context" select=".."/>
-                        </xsl:call-template>
-                    </xsl:with-param>
-                </xsl:call-template>
-            </xsl:variable>
             <xsl:call-template name="href.target.relative">
-                <xsl:with-param name="target" select="$target_uri"/>
+                <xsl:with-param name="target" select="."/>
                 <xsl:with-param name="context" select=".."/>
             </xsl:call-template>
         </xsl:otherwise>
     </xsl:choose>
 </xsl:template>
 
+
+<xsl:template match="@url">
+    <xsl:choose>
+        <xsl:when test="contains(., ':')">
+            <xsl:value-of select="."/>
+        </xsl:when>
+        <xsl:otherwise>
+            <xsl:text>XXX</xsl:text>
+            <xsl:value-of select="."/>
+            <xsl:text>XXX</xsl:text>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+
 </xsl:stylesheet>

xsl/html.xsl

@@ -11,6 +11,7 @@
   <xsl:import href="docbook-layout.xsl"/>
   <xsl:import href="navbar.xsl"/>
   <xsl:import href="admon.xsl"/>
+  <xsl:import href="xref.xsl"/>
   <xsl:import href="relative-href.xsl"/>
 
   <xsl:param name="html.stylesheet" select="'boostbook.css'"/>

xsl/xref.xsl

@@ -0,0 +1,70 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:suwl="http://nwalsh.com/xslt/ext/com.nwalsh.saxon.UnwrapLinks"
+                exclude-result-prefixes="suwl"
+                version="1.0">
+
+<!-- Import the HTML chunking stylesheet -->
+<xsl:import
+    href="http://docbook.sourceforge.net/release/xsl/current/html/xref.xsl"/>
+
+
+<xsl:template name="adjust-url">
+    <xsl:param name="target"/>
+    <xsl:param name="context" select="."/>
+
+    <xsl:choose>
+        <xsl:when test="contains($target, ':')">
+          <xsl:value-of select="$target"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:call-template name="href.target.relative">
+            <xsl:with-param name="target" select="$target"/>
+          </xsl:call-template>
+        </xsl:otherwise>
+    </xsl:choose>
+
+</xsl:template>
+
+
+<xsl:template match="ulink" name="ulink">
+  <xsl:variable name="link">
+    <a>
+      <xsl:if test="@id">
+        <xsl:attribute name="name">
+          <xsl:value-of select="@id"/>
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:attribute name="href">
+        <xsl:call-template name="adjust-url">
+          <xsl:with-param name="target" select="@url"/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:if test="$ulink.target != ''">
+        <xsl:attribute name="target">
+          <xsl:value-of select="$ulink.target"/>
+        </xsl:attribute>
+      </xsl:if>
+      <xsl:choose>
+        <xsl:when test="count(child::node())=0">
+          <xsl:value-of select="@url"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:apply-templates/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </a>
+  </xsl:variable>
+
+  <xsl:choose>
+    <xsl:when test="function-available('suwl:unwrapLinks')">
+      <xsl:copy-of select="suwl:unwrapLinks($link)"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:copy-of select="$link"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+</xsl:stylesheet>