Merge various documentation changes.

Merged revisions 51323-51324,51680,52082-52083,52237,52321,52326,52344 via svnmerge from 
https://svn.boost.org/svn/boost/trunk

........
  r51323 | danieljames | 2009-02-18 21:24:36 +0000 (Wed, 18 Feb 2009) | 1 line
  
  More information in error messages in the doxygen2boostbook script.
........
  r51324 | danieljames | 2009-02-18 21:25:12 +0000 (Wed, 18 Feb 2009) | 1 line
  
  Deal with top level enums from doxygen.
........
  r51680 | danieljames | 2009-03-10 08:09:14 +0000 (Tue, 10 Mar 2009) | 1 line
  
  Try to support inbodydescription in doxygen xml.
........
  r52082 | danieljames | 2009-03-31 20:43:13 +0100 (Tue, 31 Mar 2009) | 1 line
  
  Support global variable reference in boostbook.
........
  r52083 | danieljames | 2009-03-31 20:43:35 +0100 (Tue, 31 Mar 2009) | 2 lines
  
  Support reference for variables that are both static and mutable in
  boostbook.
........
  r52237 | danieljames | 2009-04-07 20:26:18 +0100 (Tue, 07 Apr 2009) | 7 lines
  
  Fix calculate_relative_path
  
  When outdir == "." calculate_relative_path was counting that dot as a
  directory and adding an extra ".." to the result. So only count parts
  that don't equal ".".
  
  Refs #2921
........
  r52321 | danieljames | 2009-04-11 08:55:00 +0100 (Sat, 11 Apr 2009) | 5 lines
  
  Partially revert [51323].
  
  It added partial support for protected and private attributes and friend
  functions. But since it isn't complete support it was doing more harm
  than good.
........
  r52326 | danieljames | 2009-04-11 13:38:30 +0100 (Sat, 11 Apr 2009) | 1 line
  
  Workaround buggy doxygen output. Refs #2937
........
  r52344 | danieljames | 2009-04-12 11:06:24 +0100 (Sun, 12 Apr 2009) | 1 line
  
  Add a test document for doxygen integration.
........


[SVN r52345]

test/doxygen/Jamfile.v2

@@ -0,0 +1,19 @@
+import doxygen ;
+
+doxygen autodoc
+    :
+        [ glob boost/*.hpp ]
+    :
+        <xsl:param>"boost.doxygen.reftitle=Example Reference"
+    ;
+
+boostbook standalone
+    :
+        example.xml
+    :
+        <xsl:param>boost.root=../../../../..
+        <xsl:param>boost.libraries=../../../../../libs/libraries.htm
+        <xsl:param>html.stylesheet=../../../../../doc/html/boostbook.css
+        
+        <dependency>autodoc
+    ;

test/doxygen/boost/example.hpp

@@ -0,0 +1,49 @@
+int global_integer;
+static int global_static_integer;
+const int global_const_integer;
+static const int global_static_const_integer;
+enum global_enum { enumerator };
+
+namespace example
+{
+    int namespace_integer;
+    static int namespace_static_integer;
+    const int namespace_const_integer;
+    static const int namespace_static_const_integer;
+    enum namespace_enum { enumerator };
+
+    class example
+    {
+    public:
+        int integer;
+        static int static_integer;
+        mutable int mutable_integer;
+        const int const_integer;
+        static mutable int static_mutable_integer;
+        static const int static_const_integer;
+
+        enum class_enum { enumerator };
+    protected:
+        int protected_integer;
+        static int protected_static_integer;
+        mutable int protected_mutable_integer;
+        const int protected_const_integer;
+        static mutable int protected_static_mutable_integer;
+        static const int protected_static_const_integer;
+
+        enum protected_class_enum { enumerator };
+    private:
+        int private_integer;
+        static int private_static_integer;
+        mutable int private_mutable_integer;
+        const int private_const_integer;
+        static mutable int private_static_mutable_integer;
+        static const int private_static_const_integer;
+
+        enum private_class_enum { enumerator };
+    };
+    
+    template <typename TypeParameter, int NonTypeParameter,
+        typename TypeParameterWithDefault = int>
+    struct example_template {};
+}

test/doxygen/example.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<library id="example" name="Example" dirname="example" xmlns:xi="http://www.w3.org/2001/XInclude">
+<title>Example</title>
+<xi:include href="autodoc.xml" />
+</library>

xsl/doxygen/doxygen2boostbook.xsl

@@ -51,7 +51,24 @@
   <xsl:key name="compounds-by-id" match="compounddef" use="@id"/>
   <xsl:key name="members-by-id" match="memberdef" use="@id" />
 
-  <xsl:strip-space elements="briefdescription detaileddescription"/>
+  <xsl:strip-space elements="briefdescription detaileddescription inbodydescription"/>
+
+  <xsl:template name="kind-error-message">
+    <xsl:param name="message"/>
+
+    <xsl:variable name="location" select=".//location[1]" />
+    <xsl:variable name="name" select="./name" />
+
+    <xsl:message>
+      <xsl:if test="$location">
+        <xsl:value-of select="concat($location/@file, ':', $location/@line, ': ')" />
+      </xsl:if>
+      <xsl:value-of select="concat($message, ' with kind=', @kind)" />
+      <xsl:if test="$name">
+        <xsl:value-of select="concat(' (name=', $name, ') ')" />
+      </xsl:if>
+    </xsl:message>
+  </xsl:template>
 
   <!-- translate-name: given a string, return a string suitable for use as a refid -->
   <xsl:template name="translate-name">
@@ -101,6 +118,7 @@
            tell us what is \internal and what isn't. -->
       <xsl:when test="contains(detaileddescription/para, 'INTERNAL ONLY')"/>
       <xsl:when test="contains(briefdescription/para, 'INTERNAL ONLY')"/>
+      <xsl:when test="contains(inbodydescription/para, 'INTERNAL ONLY')"/>
 
       <xsl:when test="@kind='file'">
         <xsl:call-template name="file"/>
@@ -131,9 +149,9 @@
         </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:message>
+        <xsl:call-template name="kind-error-message">
-Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
+          <xsl:with-param name="message" select="'Cannot handle compounddef'"/>
-        </xsl:message>
+        </xsl:call-template>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -242,6 +260,7 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
 
         <xsl:apply-templates select="briefdescription" mode="passthrough"/>
         <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+        <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
         <xsl:apply-templates/>
       </xsl:element>
     </xsl:if>
@@ -267,6 +286,7 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
         
         <xsl:apply-templates select="briefdescription" mode="passthrough"/>
         <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+        <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
       </enum>
     </xsl:if>
   </xsl:template>
@@ -285,6 +305,7 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
 
       <xsl:apply-templates select="briefdescription" mode="passthrough"/>
       <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+      <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
     </enumvalue>
   </xsl:template>
 
@@ -343,9 +364,10 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
           </xsl:call-template>
         </xsl:attribute>
         
-        <xsl:if test="briefdescription/*|detaileddescription/*">
+        <xsl:if test="briefdescription/*|detaileddescription/*|inbodydescription/*">
           <xsl:apply-templates select="briefdescription/*" mode="passthrough"/>
           <xsl:apply-templates select="detaileddescription/*" mode="passthrough"/>
+          <xsl:apply-templates select="inbdoydescription/*" mode="passthrough"/>
         </xsl:if>
         
         <xsl:apply-templates mode="toplevel">
@@ -436,6 +458,7 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
            tell us what is \internal and what isn't. -->
       <xsl:when test="contains(detaileddescription/para, 'INTERNAL ONLY')"/>
       <xsl:when test="contains(briefdescription/para, 'INTERNAL ONLY')"/>
+      <xsl:when test="contains(inbodydescription/para, 'INTERNAL ONLY')"/>
 
       <xsl:when test="@kind='define'">
         <macro>
@@ -459,6 +482,7 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
 
           <xsl:apply-templates select="briefdescription" mode="passthrough"/>
           <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+          <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
         </macro>
       </xsl:when>
 
@@ -470,9 +494,18 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
         <xsl:call-template name="typedef" />
       </xsl:when>
 
+      <xsl:when test="@kind='variable'">
+        <xsl:call-template name="variable" />
+      </xsl:when>
+
+      <xsl:when test="@kind='enum'">
+        <xsl:call-template name="enum" />
+      </xsl:when>
+
       <xsl:otherwise>
-        <xsl:message>Cannot handle toplevel memberdef element with
+        <xsl:call-template name="kind-error-message">
-        kind=<xsl:value-of select="@kind"/></xsl:message>
+          <xsl:with-param name="message" select="'Cannot handle toplevel memberdef element'"/>
+        </xsl:call-template>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -530,6 +563,22 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
           </xsl:if>
         </template-type-parameter>
       </xsl:when>
+      <!-- Doxygen 1.5.8 generates odd xml for template type parameters.
+           This deals with that -->
+      <xsl:when test="not(declname) and
+        (starts-with(string(type), 'class ') or starts-with(string(type), 'typename '))">
+        <template-type-parameter>
+          <xsl:attribute name="name">
+            <xsl:value-of select="normalize-space(substring-after(string(type), ' '))"/>
+          </xsl:attribute>
+          <xsl:if test="defval">
+            <default>
+              <xsl:apply-templates select="defval/*|defval/text()" 
+                mode="passthrough"/>
+            </default>
+          </xsl:if>
+        </template-type-parameter>
+      </xsl:when>
       <xsl:otherwise>
         <template-nontype-parameter>
           <xsl:attribute name="name">
@@ -699,9 +748,9 @@ Cannot handle compounddef with kind=<xsl:value-of select="@kind"/>
         </xsl:apply-templates>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:message>
+        <xsl:call-template name="kind-error-message">
-Cannot handle sectiondef with kind=<xsl:value-of select="@kind"/>      
+          <xsl:with-param name="message" select="'Cannot handle sectiondef'"/>
-        </xsl:message>
+        </xsl:call-template>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -718,6 +767,7 @@ Cannot handle sectiondef with kind=<xsl:value-of select="@kind"/>
            tell us what is \internal and what isn't. -->
       <xsl:when test="contains(detaileddescription/para, 'INTERNAL ONLY')"/>
       <xsl:when test="contains(briefdescription/para, 'INTERNAL ONLY')"/>
+      <xsl:when test="contains(inbodydescription/para, 'INTERNAL ONLY')"/>
 
       <xsl:when test="@kind='typedef'">
         <xsl:call-template name="typedef">
@@ -783,9 +833,9 @@ Cannot handle sectiondef with kind=<xsl:value-of select="@kind"/>
         </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
-        <xsl:message>
+        <xsl:call-template name="kind-error-message">
-Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
+          <xsl:with-param name="message" select="'Cannot handle memberdef element'"/>
-        </xsl:message>
+        </xsl:call-template>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
@@ -805,6 +855,7 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
         
         <xsl:apply-templates select="briefdescription" mode="passthrough"/>
         <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+        <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
         
         <type><xsl:apply-templates select="type"/></type>
       </typedef>
@@ -843,7 +894,7 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
         <xsl:value-of select="normalize-space(declname/text())"/>
       </xsl:variable>
 
-      <xsl:apply-templates select="../detaileddescription//parameterlist[attribute::kind='param']/*"
+      <xsl:apply-templates select="../*[self::detaileddescription or self::inbodydescription]//parameterlist[attribute::kind='param']/*"
         mode="parameter.description">
         <xsl:with-param name="name">
           <xsl:value-of select="$name"/>
@@ -893,24 +944,25 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
     <!-- The description -->
     <xsl:apply-templates select="briefdescription" mode="passthrough"/>
     <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+    <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
       
     <xsl:apply-templates 
-      select="detaileddescription/para/simplesect[@kind='pre']"
+      select="*[self::detaileddescription or self::inbodydescription]/para/simplesect[@kind='pre']"
       mode="function-clauses"/>
     <xsl:apply-templates 
-      select="detaileddescription/para/simplesect[@kind='post']"
+      select="*[self::detaileddescription or self::inbodydescription]/para/simplesect[@kind='post']"
       mode="function-clauses"/>
     <xsl:apply-templates 
-      select="detaileddescription/para/simplesect[@kind='return']"
+      select="*[self::detaileddescription or self::inbodydescription]/para/simplesect[@kind='return']"
       mode="function-clauses"/>
-    <xsl:if test="detaileddescription/para/parameterlist[@kind='exception']">
+    <xsl:if test="*[self::detaileddescription or self::inbodydescription]/para/parameterlist[@kind='exception']">
       <throws>
         <xsl:apply-templates 
-          select="detaileddescription/para/parameterlist[@kind='exception']"
+          select="*[self::detaileddescription or self::inbodydescription]/para/parameterlist[@kind='exception']"
           mode="function-clauses"/>
       </throws>
     </xsl:if>
-    <xsl:variable name="notes" select="detaileddescription/para/simplesect[@kind='note' or @kind='attention']"/>
+    <xsl:variable name="notes" select="*[self::detaileddescription or self::inbodydescription]/para/simplesect[@kind='note' or @kind='attention']"/>
     <xsl:if test="count($notes) &gt; 0"> 
       <notes>
         <xsl:apply-templates select="$notes" mode="function-clauses"/>
@@ -1107,11 +1159,14 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
       </xsl:attribute>
 
       <!-- Specifiers -->
-      <xsl:if test="@static = 'yes'">
+      <xsl:variable name="specifiers">
-        <xsl:attribute name="specifiers">static</xsl:attribute>
+        <xsl:if test="@static = 'yes'"><xsl:text> static</xsl:text></xsl:if>
-      </xsl:if>
+        <xsl:if test="@mutable = 'yes'"><xsl:text> mutable</xsl:text></xsl:if>
-      <xsl:if test="@mutable = 'yes'">
+      </xsl:variable>
-        <xsl:attribute name="specifiers">mutable</xsl:attribute>
+      <xsl:if test="normalize-space($specifiers)">
+        <xsl:attribute name="specifiers">
+          <xsl:value-of select="normalize-space($specifiers)"/>
+        </xsl:attribute>
       </xsl:if>
 
       <type>
@@ -1120,6 +1175,7 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
 
       <xsl:apply-templates select="briefdescription" mode="passthrough"/>
       <xsl:apply-templates select="detaileddescription" mode="passthrough"/>
+      <xsl:apply-templates select="inbodydescription" mode="passthrough"/>
     </data-member>
     </xsl:if>
   </xsl:template>
@@ -1182,6 +1238,14 @@ Cannot handle memberdef element with kind=<xsl:value-of select="@kind"/>
     </xsl:if>
   </xsl:template>
 
+  <xsl:template match="inbodydescription" mode="passthrough">
+    <xsl:if test="text()|*">
+      <description>
+        <xsl:apply-templates mode="passthrough"/>
+      </description>
+    </xsl:if>
+  </xsl:template>
+
   <!-- Handle function clauses -->
   <xsl:template match="simplesect" mode="function-clauses">
     <xsl:if test="@kind='pre'">