Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r73448 - in branches/release/tools/boostbook: . test/doxygen test/doxygen/boost xsl xsl/doxygen
From: dnljms_at_[hidden]
Date: 2011-07-30 13:02:38


Author: danieljames
Date: 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
New Revision: 73448
URL: http://svn.boost.org/trac/boost/changeset/73448

Log:
Boostbook: Merge from trunk to release.

- Support for doxygen warnings tags. Fixes #5740.
- Autoindex support (johnmaddock).
- Support for sections starting on new pages (johnmaddock).

Properties modified:
   branches/release/tools/boostbook/ (props changed)
Text files modified:
   branches/release/tools/boostbook/test/doxygen/autodoc.gold | 3
   branches/release/tools/boostbook/test/doxygen/boost/example.hpp | 2
   branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl | 10 +++
   branches/release/tools/boostbook/xsl/fo.xsl | 116 +++++++++++++++++++++++++++++++++++----
   branches/release/tools/boostbook/xsl/html-base.xsl | 4 +
   5 files changed, 120 insertions(+), 15 deletions(-)

Modified: branches/release/tools/boostbook/test/doxygen/autodoc.gold
==============================================================================
--- branches/release/tools/boostbook/test/doxygen/autodoc.gold (original)
+++ branches/release/tools/boostbook/test/doxygen/autodoc.gold 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
@@ -3,7 +3,8 @@
       <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>
+ </template><description><para>Test some doxygen markup</para><para><warning><para>This is just an example.</para></warning>
+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>

Modified: branches/release/tools/boostbook/test/doxygen/boost/example.hpp
==============================================================================
--- branches/release/tools/boostbook/test/doxygen/boost/example.hpp (original)
+++ branches/release/tools/boostbook/test/doxygen/boost/example.hpp 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
@@ -68,6 +68,8 @@
     /**
      * Test some doxygen markup
      *
+ * \warning This is just an example.
+ *
      * Embedded docbook list:
      *
      * \xmlonly

Modified: branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl (original)
+++ branches/release/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
@@ -1276,7 +1276,9 @@
                   not (@kind='return') and
                   not (@kind='post') and
                   not (@kind='attention') and
- not (@kind='see')">
+ not (@kind='see') and
+ not (@kind='warning')
+ ">
       <xsl:apply-templates mode="passthrough"/>
     </xsl:if>
   </xsl:template>
@@ -1287,6 +1289,12 @@
     </note>
   </xsl:template>
 
+ <xsl:template match="para/simplesect[@kind='warning']" mode="passthrough">
+ <warning>
+ <xsl:apply-templates mode="passthrough"/>
+ </warning>
+ </xsl:template>
+
   <xsl:template match="para/simplesect[@kind='par']" mode="passthrough">
     <formalpara>
       <xsl:apply-templates mode="passthrough"/>

Modified: branches/release/tools/boostbook/xsl/fo.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/fo.xsl (original)
+++ branches/release/tools/boostbook/xsl/fo.xsl 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
@@ -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 @@
 <xsl:param name="callout.graphics.path">http://svn.boost.org/svn/boost/trunk/doc/src/images/callouts/>
 <xsl:param name="img.src.path">
http://svn.boost.org/svn/boost/trunk/doc/html/>
 
-<!-- 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>
 

Modified: branches/release/tools/boostbook/xsl/html-base.xsl
==============================================================================
--- branches/release/tools/boostbook/xsl/html-base.xsl (original)
+++ branches/release/tools/boostbook/xsl/html-base.xsl 2011-07-30 13:02:37 EDT (Sat, 30 Jul 2011)
@@ -317,4 +317,8 @@
     </xsl:choose>
 </xsl:template>
 
+<xsl:template match="itemizedlist[@role = 'index']" mode="class.value">
+ <xsl:value-of select="'index'"/>
+</xsl:template>
+
 </xsl:stylesheet>


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk