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
Modified: branches/release/tools/boostbook/xsl/html-base.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 > 0)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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 > 1)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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 > 2)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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 > 3)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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 > 4)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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 > 5)">
+ page
+ </xsl:if>
+ <xsl:if test="not($boost.section.newpage.depth > 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>
==============================================================================
--- 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>