Merge tools directory from trunk.

[SVN r72698]
2025-05-09 23:13:58 +00:00 · 2011-06-20 19:19:56 +00:00 · 2011-06-20 19:19:56 +00:00 · db78b906eb
commit db78b906eb
parent e5ef25c5b3 50743c43e2
12 changed files with 289 additions and 33 deletions
--- a/dtd/1.1/boost-no-inspect
+++ b/dtd/1.1/boost-no-inspect
@ -0,0 +1,4 @@
+Inspect complains that this directory is called '1.1', but that's the
+standard naming style for DTDs, and this needs to match the url of the
+DTD on the website. Any platform which has problems with this domain
+name probably won't be able to build the documentation anyway.
--- a/test/doxygen/Jamfile.v2
+++ b/test/doxygen/Jamfile.v2
@ -4,6 +4,7 @@
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

 import doxygen ;
+import os ;

 doxygen autodoc
    :
@ -12,6 +13,24 @@ doxygen autodoc
        <xsl:param>"boost.doxygen.reftitle=Example Reference"
    ;

+if [ os.name ] = NT
+{
+    actions compare
+    {
+        comp /A $(>[1]) $(>[2]) && echo "Stamped" >$(<)
+    }
+
+}
+else
+{
+    actions compare
+    {
+        diff -u -w $(>[1]) $(>[2]) && echo "Stamped" >$(<)
+    }
+}
+
+make check : autodoc.xml autodoc.gold : @compare ;
+
 boostbook standalone
    :
        example.xml
--- a/test/doxygen/autodoc.gold
+++ b/test/doxygen/autodoc.gold
@ -0,0 +1,24 @@
+<?xml version="1.0" standalone="yes"?>
+<library-reference id="example_reference"><title>Example Reference</title><header name="boost/example.hpp"><namespace name="example"><class name="example"><purpose>Documentation for class example. </purpose><class name="inner_class"><data-member name="x"><type>int</type></data-member></class><enum name="class_enum"><enumvalue name="enumerator"/></enum><data-member name="integer"><type>int</type></data-member><data-member name="mutable_integer" specifiers="mutable"><type>int</type></data-member><data-member name="const_integer"><type>const int</type></data-member><data-member name="static_integer" specifiers="static"><type>int</type></data-member><data-member name="static_const_integer" specifiers="static"><type>const int</type></data-member></class><struct name="example_template"><template>
+      <template-type-parameter name="TypeParameter"><purpose><para>A template parameter </para></purpose></template-type-parameter>
+      <template-nontype-parameter name="NonTypeParameter"><type>int</type><purpose><para>This is a non-type template parameter </para></purpose></template-nontype-parameter>
+      <template-type-parameter name="TypeParameterWithDefault"><default>int</default><purpose><para>This is a template parameter with a default argument </para></purpose></template-type-parameter>
+    </template><description><para>Test some doxygen markup</para><para>Embedded docbook list:</para><para> 
+ <orderedlist><listitem><simpara>1</simpara></listitem><listitem><simpara>2</simpara></listitem></orderedlist>
+ </para><para><emphasis>Special</emphasis> <emphasis role="bold">Bold</emphasis> <computeroutput>Typewriter</computeroutput> <emphasis>Italics</emphasis> <emphasis>emphasis</emphasis> <computeroutput>parameter</computeroutput> </para><para><itemizedlist>
+<listitem><para>Arg1 first argument. </para></listitem>
+<listitem><para>Arg2 second argument.</para></listitem>
+</itemizedlist>
+<itemizedlist>
+<listitem><para>First list item. </para></listitem>
+<listitem><para>Second list item</para></listitem>
+</itemizedlist>
+Line 1<sbr/>
+ Line 2</para><para><programlisting>     void foo() {}
+</programlisting></para><para>
+</para></description></struct><enum name="namespace_enum"><enumvalue name="enumerator"/></enum><data-member name="namespace_integer"><type>int</type></data-member><data-member name="namespace_static_integer" specifiers="static"><type>int</type></data-member><data-member name="namespace_const_integer"><type>const int</type></data-member><data-member name="namespace_static_const_integer" specifiers="static"><type>const int</type></data-member><function name="namespace_func"><type>int</type><parameter name="i"><paramtype>int</paramtype><description><para>A function parameter </para></description></parameter><parameter name="j"><paramtype>int</paramtype><description><para>Another </para></description></parameter><description><para>
+
+
+This is a test function. <classname alt="example::example">Link to class</classname> <classname alt="example::example_template">Link to class template</classname> <note><para>This is a note.</para></note>
+<para><emphasis role="bold">See Also:</emphasis><para><classname alt="example::example">example::example</classname> and <classname alt="example::example_template">example_template</classname> </para></para>
+</para></description><requires><para>i &gt; j</para></requires><returns><para>The answer </para></returns></function></namespace><macro name="EXAMPLE" kind="functionlike"><macro-parameter name="m"/><purpose>Documentation for macro example. </purpose></macro></header></library-reference>
--- a/test/doxygen/boost/example.hpp
+++ b/test/doxygen/boost/example.hpp
@ -89,11 +89,29 @@ namespace example
     *     void foo() {}
     * \endcode
     *
+     * \tparam TypeParameter A template parameter
+     * \tparam NonTypeParameter This is a non-type template parameter
+     * \tparam TypeParameterWithDefault This is a template parameter with a default argument
     */

    template <typename TypeParameter, int NonTypeParameter,
        typename TypeParameterWithDefault = int>
    struct example_template {};
+
+    /**
+     * \param i A function parameter
+     * \param j Another
+     * \return The answer
+     * \pre i > j
+     *
+     * This is a test function.
+     * \ref example::example "Link to class"
+     * \ref example_template "Link to class template"
+     * \note This is a note.
+     *
+     * \see example::example and example_template
+     */
+    int namespace_func(int i, int j);
 }

 #define EXAMPLE(m) The macro
--- a/test/more/tests/libs/array.gold
+++ b/test/more/tests/libs/array.gold
@ -149,7 +149,9 @@
  <phrase role="comment">// <link linkend="id35-bb">modifiers</link></phrase>
  <phrase role="keyword">void</phrase> <link linkend="id36-bb"><phrase role="identifier">swap</phrase></link><phrase role="special">(</phrase><link linkend="boost.array">array</link><phrase role="special">&lt;</phrase><phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="identifier">N</phrase><phrase role="special">&gt;</phrase><phrase role="special">&amp;</phrase><phrase role="special">)</phrase><phrase role="special">;</phrase>
  <phrase role="keyword">void</phrase> <link linkend="id37-bb"><phrase role="identifier">assign</phrase></link><phrase role="special">(</phrase><phrase role="keyword">const</phrase> <phrase role="identifier">T</phrase><phrase role="special">&amp;</phrase><phrase role="special">)</phrase><phrase role="special">;</phrase>
-  <phrase role="identifier">T</phrase> elems[N]<phrase role="special">;</phrase>
+
+  <phrase role="comment">// public data members</phrase>
+  <phrase role="identifier">T</phrase> <phrase role="identifier">elems[N]</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase><phrase role="special">;</phrase>

 <phrase role="comment">// <link linkend="id38-bb">specialized algorithms</link></phrase>
--- a/test/more/tests/misc/processing.gold
+++ b/test/more/tests/misc/processing.gold
@ -0,0 +1,5 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<book xmlns:xi="http://www.w3.org/2001/XInclude" id="test" lang="en">
+  <title>Test processing instructions</title>
+  <para><?dbtimestamp format="Y-m-d H:M:S"?></para>
+</book>
--- a/test/more/tests/misc/processing.xml
+++ b/test/more/tests/misc/processing.xml
@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2011 Daniel James.
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+-->
+<!DOCTYPE boostbook PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<boostbook id="test" xmlns:xi="http://www.w3.org/2001/XInclude"
+           last-revision="$Date: 2010-10-30 15:29:27 +0100 (Sat, 30 Oct 2010) $"
+           lang="en">
+  <title>Test processing instructions</title>
+  <para><?dbtimestamp format="Y-m-d H:M:S"?></para>
+</boostbook>
+
+
--- a/xsl/docbook.xsl
+++ b/xsl/docbook.xsl
@ -382,6 +382,10 @@ Error: XSL template 'link-or-anchor' called with invalid link-type '<xsl:value-o
    </xsl:element>
  </xsl:template>

+  <xsl:template match="processing-instruction()">
+    <xsl:copy/>
+  </xsl:template>
+
  <xsl:template match="code">
    <computeroutput>
      <xsl:apply-templates mode="annotation"/>
--- a/xsl/doxygen/doxygen2boostbook.xsl
+++ b/xsl/doxygen/doxygen2boostbook.xsl
@ -566,6 +566,7 @@
  <xsl:template match="param" mode="template">
    <xsl:choose>
      <xsl:when test="string(type)='class' or string(type)='typename'">
+        <xsl:variable name="name" select="normalize-space(string(declname))"/>
        <template-type-parameter>
          <xsl:attribute name="name">
            <xsl:value-of select="normalize-space(string(declname))"/>
@ -576,6 +577,13 @@
                mode="passthrough"/>
            </default>
          </xsl:if>
+          <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+            <xsl:if test="string(parameternamelist/parametername)=$name">
+              <purpose>
+                <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+              </purpose>
+            </xsl:if>
+          </xsl:for-each>
        </template-type-parameter>
      </xsl:when>
      <!-- Doxygen 1.5.8 generates odd xml for template type parameters.
@ -583,8 +591,11 @@
      <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:variable name="name">
            <xsl:value-of select="normalize-space(substring-after(string(type), ' '))"/>
+          </xsl:variable>
+          <xsl:attribute name="name">
+            <xsl:value-of select="$name"/>
          </xsl:attribute>
          <xsl:if test="defval">
            <default>
@ -592,12 +603,22 @@
                mode="passthrough"/>
            </default>
          </xsl:if>
+          <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+            <xsl:if test="string(parameternamelist/parametername)=$name">
+              <purpose>
+                <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+              </purpose>
+            </xsl:if>
+          </xsl:for-each>
        </template-type-parameter>
      </xsl:when>
      <xsl:otherwise>
        <template-nontype-parameter>
-          <xsl:attribute name="name">
+          <xsl:variable name="name">
            <xsl:value-of select="normalize-space(string(declname))"/>
+          </xsl:variable>
+          <xsl:attribute name="name">
+            <xsl:value-of select="$name"/>
          </xsl:attribute>
          <type>
            <xsl:apply-templates select="type"/>
@ -608,6 +629,13 @@
                mode="passthrough"/>
            </default>
          </xsl:if>
+          <xsl:for-each select="../../detaileddescription//parameterlist[@kind='templateparam']/parameteritem">
+            <xsl:if test="string(parameternamelist/parametername)=$name">
+              <purpose>
+                <xsl:apply-templates select="parameterdescription/para" mode="passthrough"/>
+              </purpose>
+            </xsl:if>
+          </xsl:for-each>
        </template-nontype-parameter>
      </xsl:otherwise>
    </xsl:choose>
@ -1009,12 +1037,6 @@
          mode="function-clauses"/>
      </throws>
    </xsl:if>
-    <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"/>
-      </notes>
-    </xsl:if>
  </xsl:template>

  <!-- Handle free functions -->
@ -1254,17 +1276,32 @@
                  not (@kind='return') and 
                  not (@kind='post') and
                  not (@kind='attention') and
-                  not (@kind='note')">
+                  not (@kind='see')">
      <xsl:apply-templates mode="passthrough"/>
    </xsl:if>
  </xsl:template>

+  <xsl:template match="para/simplesect[@kind='note' or @kind='attention']" mode="passthrough">
+    <note>
+      <xsl:apply-templates mode="passthrough"/>
+    </note>
+  </xsl:template>
+
  <xsl:template match="para/simplesect[@kind='par']" mode="passthrough">
    <formalpara>
      <xsl:apply-templates mode="passthrough"/>
    </formalpara>
  </xsl:template>

+  <xsl:template match="para/simplesect[@kind='see']" mode="passthrough">
+    <para>
+      <emphasis role="bold">
+        <xsl:text>See Also:</xsl:text>
+      </emphasis>
+      <xsl:apply-templates mode="passthrough"/>
+    </para>
+  </xsl:template>
+
  <xsl:template match="simplesectsep" mode="passthrough">
    <xsl:apply-templates mode="passthrough"/>
  </xsl:template>
@ -1315,7 +1352,20 @@
  <!-- Ignore ref elements for now, as there is a lot of documentation which
       will have incorrect ref elements at the moment -->
  <xsl:template match="ref" mode="passthrough">
-    <xsl:apply-templates mode="passthrough"/>
+    <xsl:variable name="as-class" select="key('compounds-by-id', @refid)[@kind='class' or @kind='struct']"/>
+    <xsl:choose>
+      <xsl:when test="$as-class">
+        <classname>
+          <xsl:attribute name="alt">
+            <xsl:value-of select="$as-class/compoundname/text()"/>
+          </xsl:attribute>
+          <xsl:value-of select="text()"/>
+        </classname>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:apply-templates mode="passthrough"/>
+      </xsl:otherwise>
+    </xsl:choose>
  </xsl:template>

  <!-- Handle function clauses -->
@ -1335,9 +1385,6 @@
        <xsl:apply-templates mode="passthrough"/>
      </postconditions>
    </xsl:if>
-    <xsl:if test="@kind='note' or @kind='attention'">
-      <xsl:apply-templates mode="passthrough"/>
-    </xsl:if>
  </xsl:template>

  <xsl:template match="parameterlist" mode="function-clauses">
@ -1353,8 +1400,8 @@
            </classname>
            <xsl:text> </xsl:text>
            <xsl:apply-templates 
-              select="parameterdescription/para/text()
-                      |parameterdescription/para/*"
+              select=".//parameterdescription/para/text()
+                      |.//parameterdescription/para/*"
              mode="passthrough"/>
          </xsl:otherwise>
        </xsl:choose>
--- a/xsl/fo.xsl
+++ b/xsl/fo.xsl
@ -18,7 +18,109 @@
  <xsl:param name="make.year.ranges" select="1"/>
  <xsl:param name="ulink.show" select="0"/>

-  <!-- The question and answer templates are copied here from the
+   
+  <!--
+  The following code sets which sections start new pages in the PDF document flow.
+  
+  The parameter "boost.section.newpage.depth" set how far down the hierarchy the
+  page breaks go.  Defaults to 1 (the same as html chunking), in which case only 
+  top level sections start a new page, set to a higher value to force nested sections
+  onto new pages as well.
+  
+  For top level sections (level 1), we use "break-before" which forces the very first
+  section onto a separate page from the TOC.
+  
+  For nested sections (level 2 and greater) we use "break-after" which keeps nested
+  sections together with their enclosing section (rationale: the enclosing section
+  often has nothing but a title, and no content except the nested sections, and we 
+  don't want a page break right after a section title!).
+  
+  For reference sections, we turn page breaks *off* by setting "refentry.pagebreak" to 0.
+  This is for the same reason we use "break-after" for nested sections - we want reference 
+  entries to be on the same page as the title and synopsis which encloses them.  Ideally
+  we'd use "break-after" here too, but I can't find an easy to to fix that.
+  
+  Finally note that TOC's and Indexes don't get page breaks forced after them.
+  Again there's no easy fix here, *except* for the top level TOC which gets a page break
+  after it thanks to the "break-before" on level 1 sections.  Unfortunately this means
+  there's no break after the last section and before the first Index, *unless* the
+  final section has nested sections which may then trigger one!
+  
+  We could fix all this by cut-and-pasting the relevant XSL from the stylesheets to here
+  and making sure everything uses "break-after", but whether it's worth it is questionable...?
+  
+  -->
+   
+  <xsl:param name="boost.section.newpage.depth" select="1"/>
+  <xsl:param name="refentry.pagebreak" select="0"/>
+
+   <xsl:attribute-set name="section.level1.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-before">
+         <xsl:if test="($boost.section.newpage.depth &gt; 0)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 0)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <xsl:attribute-set name="section.level2.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-after">
+         <xsl:if test="($boost.section.newpage.depth &gt; 1)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 1)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <xsl:attribute-set name="section.level3.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-after">
+         <xsl:if test="($boost.section.newpage.depth &gt; 2)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 2)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <xsl:attribute-set name="section.level4.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-after">
+         <xsl:if test="($boost.section.newpage.depth &gt; 3)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 3)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <xsl:attribute-set name="section.level5.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-after">
+         <xsl:if test="($boost.section.newpage.depth &gt; 4)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 4)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <xsl:attribute-set name="section.level6.properties" use-attribute-sets="section.properties">
+      <xsl:attribute name="break-after">
+         <xsl:if test="($boost.section.newpage.depth &gt; 5)">
+            page
+         </xsl:if>
+         <xsl:if test="not($boost.section.newpage.depth &gt; 5)">
+            auto
+         </xsl:if>
+      </xsl:attribute>
+   </xsl:attribute-set>
+
+   <!-- The question and answer templates are copied here from the
       1.61.3 DocBook XSL stylesheets so that we can eliminate the emission
       of id attributes in the emitted fo:list-item-label elements. FOP
       0.20.5 has problems with these id attributes, and they are otherwise
@ -289,17 +391,5 @@ General default options go here:
 <xsl:param name="callout.graphics.path">http://svn.boost.org/svn/boost/trunk/doc/src/images/callouts/</xsl:param>
 <xsl:param name="img.src.path">http://svn.boost.org/svn/boost/trunk/doc/html/</xsl:param>

-<!-- Ideally we would use this to force top level sections
-     to start on a new page, unfortunately this causes rather
-     unfortunate page breaks in some Doxygen-generated
-     documentation which uses <refentry> and <synopsis>
-     sections :-(
-
-<xsl:attribute-set name="section.level1.properties">
-  <xsl:attribute name="break-before">page</xsl:attribute>
-</xsl:attribute-set>
-
-->
-  
 </xsl:stylesheet>

--- a/xsl/reference.xsl
+++ b/xsl/reference.xsl
@ -160,13 +160,19 @@
    <xsl:param name="prefix"/>
    <xsl:apply-templates mode="comment">
      <xsl:with-param name="wrap"
-                      select="$wrap and count(*) = 0 and count(text()) = 1"/>
+                      select="$wrap and count(text()|*) = 1"/>
      <xsl:with-param name="prefix" select="$prefix"/>
    </xsl:apply-templates>
  </xsl:template>

  <xsl:template match="simpara|para" mode="comment">
-    <xsl:apply-templates select="text()|*" mode="comment"/>
+    <xsl:param name="wrap" select="false()"/>
+    <xsl:param name="prefix"/>
+    <xsl:apply-templates select="text()|*" mode="comment">
+      <xsl:with-param name="wrap"
+                      select="$wrap and count(text()|*) = 1"/>
+      <xsl:with-param name="prefix" select="$prefix"/>
+    </xsl:apply-templates>
  </xsl:template>

  <xsl:template match="text()" mode="comment">
--- a/xsl/template.xsl
+++ b/xsl/template.xsl
@ -285,11 +285,30 @@

      <!-- Display the comment -->
      <xsl:if test="$parameter/purpose">
+        <xsl:variable name="param-text">
+          <!-- Display the parameter -->
+          <xsl:call-template name="template.parameter">
+            <xsl:with-param name="parameter" select="$parameter"/>
+            <xsl:with-param name="is-last" select="not($rest)"/>
+            <xsl:with-param name="highlight" select="false()"/>
+          </xsl:call-template>
+        </xsl:variable>
        <xsl:call-template name="highlight-comment">
          <xsl:with-param name="text">
            <xsl:text>  // </xsl:text>
-            <xsl:apply-templates 
-              select="$parameter/purpose/*|$parameter/purpose/text()"/>
+            <xsl:apply-templates
+              select="$parameter/purpose/*|$parameter/purpose/text()" mode="comment">
+              <xsl:with-param name="wrap" select="true()"/>
+              <xsl:with-param name="prefix">
+                <xsl:call-template name="indent">
+                  <xsl:with-param name="indentation" select="$indentation + string-length($param-text)"/>
+                </xsl:call-template>
+                <xsl:if test="$rest">
+                  <xsl:text>  </xsl:text>
+                </xsl:if>
+                <xsl:text>  // </xsl:text>
+              </xsl:with-param>
+            </xsl:apply-templates>
          </xsl:with-param>
        </xsl:call-template>
      </xsl:if>