Boost logo

Boost-Commit :

From: joel_at_[hidden]
Date: 2008-05-21 00:01:32


Author: djowel
Date: 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
New Revision: 45594
URL: http://svn.boost.org/trac/boost/changeset/45594

Log:
updated tests
Text files modified:
   trunk/tools/quickbook/test/code-block-1.gold | 3
   trunk/tools/quickbook/test/code-block-2.gold | 3
   trunk/tools/quickbook/test/import.gold | 6
   trunk/tools/quickbook/test/quickbook-manual.gold | 5076 +++++++++++++++++++--------------------
   trunk/tools/quickbook/test/templates.gold | 3
   5 files changed, 2510 insertions(+), 2581 deletions(-)

Modified: trunk/tools/quickbook/test/code-block-1.gold
==============================================================================
--- trunk/tools/quickbook/test/code-block-1.gold (original)
+++ trunk/tools/quickbook/test/code-block-1.gold 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
@@ -11,8 +11,7 @@
       A code block with proper indentation ;-)
     </para>
     
-<programlisting>
-<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
 
 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>

Modified: trunk/tools/quickbook/test/code-block-2.gold
==============================================================================
--- trunk/tools/quickbook/test/code-block-2.gold (original)
+++ trunk/tools/quickbook/test/code-block-2.gold 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
@@ -12,8 +12,7 @@
     </para>
     <para>
       
-<programlisting>
-<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
 
 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>

Modified: trunk/tools/quickbook/test/import.gold
==============================================================================
--- trunk/tools/quickbook/test/import.gold (original)
+++ trunk/tools/quickbook/test/import.gold 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
@@ -25,16 +25,12 @@
     </para>
     <para>
       
-<programlisting>
-<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase>
+<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
     <phrase role="comment">// return 'em, foo man!
 </phrase> <phrase role="keyword">return</phrase> <phrase role="string">&quot;foo&quot;</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase>
 </programlisting>
     </para>
- <para>
- <calloutlist></calloutlist>
- </para>
   </para>
 </article>

Modified: trunk/tools/quickbook/test/quickbook-manual.gold
==============================================================================
--- trunk/tools/quickbook/test/quickbook-manual.gold (original)
+++ trunk/tools/quickbook/test/quickbook-manual.gold 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
@@ -129,8 +129,7 @@
       <listitem>
         Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
         Example:
-<programlisting>
-<phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase>
+<programlisting><phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase>
 <phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
 <phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
       </listitem>
@@ -647,8 +646,7 @@
         </para>
         <para>
           
-<programlisting>
-<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
 
 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
@@ -740,105 +738,103 @@
 <!--quickbook-escape-postfix--></programlisting>
         <warning>
           <para>
- <para>
- <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
- role="special">]</phrase></code> is now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
- <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
- and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
- may now contain paragraphs.
- </para>
- </warning>
- </section>
- <section id="quickbook.syntax.phrase.anchors">
- <title><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></title>
-
+ <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
+ role="special">]</phrase></code> is now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
+ <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
+ and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
+ may now contain paragraphs.
+ </para>
+ </warning>
+ </section>
+ <section id="quickbook.syntax.phrase.anchors">
+ <title><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[#named_anchor]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- A named anchor is a hook that can be referenced by a link elsewhere in
- the document. You can then reference an anchor with <literal>[link named_anchor
+ <para>
+ A named anchor is a hook that can be referenced by a link elsewhere in
+ the document. You can then reference an anchor with <literal>[link named_anchor
 Some link text]</literal>.
- See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>,
- <link linkend="quickbook.syntax.block.section">Section</link> and <link
- linkend="quickbook.syntax.block.headings">Heading</link>.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.links">
- <title><link linkend="quickbook.syntax.phrase.links">Links</link></title>
-
+ See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>,
+ <link linkend="quickbook.syntax.block.section">Section</link> and <link
+ linkend="quickbook.syntax.block.headings">Heading</link>.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.links">
+ <title><link linkend="quickbook.syntax.phrase.links">Links</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[@http://www.boost.org this is [*boost's] website....]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis>
- website....</ulink>
- </para>
- <para>
- URL links where the link text is the link itself is common. Example:
- </para>
-
+ <para>
+ will generate:
+ </para>
+ <para>
+ <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis>
+ website....</ulink>
+ </para>
+ <para>
+ URL links where the link text is the link itself is common. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->see http://spirit.sourceforge.net/
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- so, when the text is absent in a link markup, the URL is assumed. Example:
- </para>
-
+ <para>
+ so, when the text is absent in a link markup, the URL is assumed. Example:
+ </para>
+
 <programlisting>see <!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net/]<!--quickbook-escape-postfix-->
 </programlisting>
- <para>
- will generate:
- </para>
- <para>
- see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/>
- </para>
- </section>
- <section id="quickbook.syntax.phrase.anchor_links">
- <title><link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></title>
- <para>
- You can link within a document using:
- </para>
-
+ <para>
+ will generate:
+ </para>
+ <para>
+ see <ulink url="
http://spirit.sourceforge.net/">http://spirit.sourceforge.net/>
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.anchor_links">
+ <title><link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></title>
+ <para>
+ You can link within a document using:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- See sections <link linkend="quickbook.syntax.block.section">Section</link>
- and <link linkend="quickbook.syntax.block.headings">Heading</link> for
- more info.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.refentry_links">
- <title><link linkend="quickbook.syntax.phrase.refentry_links">refentry
- links</link></title>
- <para>
- In addition, you can link internally to an XML refentry like:
- </para>
-
+ <para>
+ See sections <link linkend="quickbook.syntax.block.section">Section</link>
+ and <link linkend="quickbook.syntax.block.headings">Heading</link> for
+ more info.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.refentry_links">
+ <title><link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></title>
+ <para>
+ In addition, you can link internally to an XML refentry like:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
- link text&lt;/link&gt;</literal>.
- </para>
- <para>
- Like URLs, the link text is optional. If this is not present, the link
- text will automatically be the refentry. Example:
- </para>
-
+ <para>
+ This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
+ link text&lt;/link&gt;</literal>.
+ </para>
+ <para>
+ Like URLs, the link text is optional. If this is not present, the link
+ text will automatically be the refentry. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[link xml.refentry]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</literal>.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.code_links">
- <title><link linkend="quickbook.syntax.phrase.code_links"> Code Links</link></title>
- <para>
- If you want to link to a function, class, member, enum, concept or header
- in the reference section, you can use:
- </para>
-
+ <para>
+ This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</literal>.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.code_links">
+ <title><link linkend="quickbook.syntax.phrase.code_links"> Code Links</link></title>
+ <para>
+ If you want to link to a function, class, member, enum, concept or header
+ in the reference section, you can use:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[funcref fully::qualified::function_name The link text]
 [classref fully::qualified::class_name The link text]
 [memberref fully::qualified::member_name The link text]
@@ -847,135 +843,132 @@
 [conceptref ConceptName The link text]
 [headerref path/to/header.hpp The link text]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Again, the link text is optional. If this is not present, the link text
- will automatically be the function, class, member, enum, macro, concept
- or header. Example:
- </para>
-
+ <para>
+ Again, the link text is optional. If this is not present, the link text
+ will automatically be the function, class, member, enum, macro, concept
+ or header. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- would have &quot;boost::bar::baz&quot; as the link text.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.escape">
- <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title>
- <para>
- The escape mark-up is used when we don't want to do any processing.
- </para>
-
+ <para>
+ would have &quot;boost::bar::baz&quot; as the link text.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.escape">
+ <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title>
+ <para>
+ The escape mark-up is used when we don't want to do any processing.
+ </para>
+
 <programlisting>'''
 escape (no processing/formatting)
 '''
 </programlisting>
- <para>
- Escaping allows us to pass XML markup to <ulink url="
http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
- or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
- </para>
-
+ <para>
+ Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
+ or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
+ </para>
+
 <programlisting>'''
 &lt;emphasis role=&quot;bold&quot;&gt;This is direct XML markup&lt;/emphasis&gt;
 '''
 </programlisting>
+ <para>
+ <emphasis role="bold">This is direct XML markup</emphasis>
+ </para>
+ <important>
           <para>
- <emphasis role="bold">This is direct XML markup</emphasis>
- </para>
- <important>
- <para>
- Be careful when using the escape. The text must conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink
- url="http://www.docbook.org/">DocBook</ulink> syntax.
- </para>
- </important>
- </section>
- <section id="quickbook.syntax.phrase.single_char_escape">
- <title><link linkend="quickbook.syntax.phrase.single_char_escape">Single
- char escape</link></title>
- <para>
- The backslash may be used to escape a single punctuation character. The
- punctuation immediately after the backslash is passed without any processing.
- This is useful when we need to escape QuickBook punctuations such as
- <code><phrase role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>.
- For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal>
+ Be careful when using the escape. The text must conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink
+ url="http://www.docbook.org/">DocBook</ulink> syntax.
           </para>
+ </important>
+ </section>
+ <section id="quickbook.syntax.phrase.single_char_escape">
+ <title><link linkend="quickbook.syntax.phrase.single_char_escape">Single
+ char escape</link></title>
+ <para>
+ The backslash may be used to escape a single punctuation character. The
+ punctuation immediately after the backslash is passed without any processing.
+ This is useful when we need to escape QuickBook punctuations such as <code><phrase
+ role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>.
+ For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal>
+ </para>
+ <para>
+ <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
+ has a special meaning. It is used to generate line breaks.
+ </para>
+ <warning>
           <para>
             <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
- has a special meaning. It is used to generate line breaks.
+ and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
+ role="special">]</phrase></code> are now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
+ <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
+ and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
+ may now contain paragraphs.
           </para>
- <warning>
- <para>
- <para>
- <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
- and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
- role="special">]</phrase></code> are now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
- <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
- and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
- may now contain paragraphs.
- </para>
- </warning>
- <para>
- The escaped space: <code><phrase role="special">\</phrase> </code>
- also has a special meaning. The escaped space is removed from the output.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.images">
- <title><link linkend="quickbook.syntax.phrase.images">Images</link></title>
-
+ </warning>
+ <para>
+ The escaped space: <code><phrase role="special">\</phrase> </code> also
+ has a special meaning. The escaped space is removed from the output.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.images">
+ <title><link linkend="quickbook.syntax.phrase.images">Images</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[$image.jpg]
 <!--quickbook-escape-postfix--></programlisting>
- </section>
- <section id="quickbook.syntax.phrase.footnotes">
- <title><link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link></title>
- <para>
- As of version 1.3, QuickBook supports footnotes. Just put the text
- of the footnote in a <code><phrase role="special">[</phrase><phrase
- role="identifier">footnote</phrase><phrase role="special">]</phrase></code>
- block, and the text will be put at the bottom of the current page.
- For example, this:
- </para>
-
+ </section>
+ <section id="quickbook.syntax.phrase.footnotes">
+ <title><link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link></title>
+ <para>
+ As of version 1.3, QuickBook supports footnotes. Just put the text of the
+ footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase
+ role="special">]</phrase></code> block, and the text will be put at the
+ bottom of the current page. For example, this:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote]
 <!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate this
+ <footnote>
             <para>
- will generate this
- <footnote>
- <para>
- A sample footnote
- </para>
- </footnote>
- .
+ A sample footnote
             </para>
- <section id="quickbook.syntax.phrase.footnotes.macro_expansion">
- <title><link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro
- Expansion</link></title>
+ </footnote>
+ .
+ </para>
+ <section id="quickbook.syntax.phrase.footnotes.macro_expansion">
+ <title><link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro
+ Expansion</link></title>
 <programlisting><!--quickbook-escape-prefix-->__a_macro_identifier__
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- See <link linkend="quickbook.syntax.block.macros">Macros</link> for
- details.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.footnotes.template_expansion">
- <title><link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template
- Expansion</link></title>
+ <para>
+ See <link linkend="quickbook.syntax.block.macros">Macros</link> for details.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.footnotes.template_expansion">
+ <title><link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template
+ Expansion</link></title>
 <programlisting><!--quickbook-escape-prefix-->[a_template_identifier]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- See <link linkend="quickbook.syntax.block.templates">Templates</link>
- for details.
- </para>
- </section>
- </section>
+ <para>
+ See <link linkend="quickbook.syntax.block.templates">Templates</link>
+ for details.
+ </para>
         </section>
- <section id="quickbook.syntax.block">
- <title><link linkend="quickbook.syntax.block"> Block Level Elements</link></title>
- <section id="quickbook.syntax.block.document">
- <title><link linkend="quickbook.syntax.block.document">Document</link></title>
- <para>
- Every document must begin with a Document Info section, which should
- look like this:
- </para>
-
+ </section>
+ </section>
+ <section id="quickbook.syntax.block">
+ <title><link linkend="quickbook.syntax.block"> Block Level Elements</link></title>
+ <section id="quickbook.syntax.block.document">
+ <title><link linkend="quickbook.syntax.block.document">Document</link></title>
+ <para>
+ Every document must begin with a Document Info section, which should look
+ like this:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[document-type The Document Title
     [quickbook 1.3]
     [version 1.0]
@@ -989,146 +982,145 @@
     [source-mode source-type]
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Where document-type is one of:
- </para>
- <itemizedlist>
- <listitem>
- book
- </listitem>
- <listitem>
- article
- </listitem>
- <listitem>
- library
- </listitem>
- <listitem>
- chapter
- </listitem>
- <listitem>
- part
- </listitem>
- <listitem>
- appendix
- </listitem>
- <listitem>
- preface
- </listitem>
- <listitem>
- qandadiv
- </listitem>
- <listitem>
- qandaset
- </listitem>
- <listitem>
- reference
- </listitem>
- <listitem>
- set
- </listitem>
- </itemizedlist>
- <para>
- quickbook 1.3 declares the version of quickbook the document is written
- for. In its absence, version 1.1 is assumed.
- </para>
- <para>
- <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
- <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
- <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
- and <literal>source-mode</literal> are optional information.
- </para>
- <para>
- <literal>source-type</literal> is a lowercase string setting the initial
- <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
- If the <literal>source-mode</literal> field is omitted, a default value
- of <literal>c++</literal> will be used.
- </para>
- </section>
- <section id="quickbook.syntax.block.section">
- <title><link linkend="quickbook.syntax.block.section">Section</link></title>
- <para>
- Starting a new section is accomplished with:
- </para>
-
+ <para>
+ Where document-type is one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ book
+ </listitem>
+ <listitem>
+ article
+ </listitem>
+ <listitem>
+ library
+ </listitem>
+ <listitem>
+ chapter
+ </listitem>
+ <listitem>
+ part
+ </listitem>
+ <listitem>
+ appendix
+ </listitem>
+ <listitem>
+ preface
+ </listitem>
+ <listitem>
+ qandadiv
+ </listitem>
+ <listitem>
+ qandaset
+ </listitem>
+ <listitem>
+ reference
+ </listitem>
+ <listitem>
+ set
+ </listitem>
+ </itemizedlist>
+ <para>
+ quickbook 1.3 declares the version of quickbook the document is written
+ for. In its absence, version 1.1 is assumed.
+ </para>
+ <para>
+ <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
+ <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
+ <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
+ and <literal>source-mode</literal> are optional information.
+ </para>
+ <para>
+ <literal>source-type</literal> is a lowercase string setting the initial
+ <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
+ If the <literal>source-mode</literal> field is omitted, a default value
+ of <literal>c++</literal> will be used.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.section">
+ <title><link linkend="quickbook.syntax.block.section">Section</link></title>
+ <para>
+ Starting a new section is accomplished with:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[section:id The Section Title]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- where <emphasis>id</emphasis> is optional. id will be the filename
- of the generated section. If it is not present, &quot;The Section Title&quot;
- will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
- <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
- All non-valid characters are converted to underscore and all upper-case
- are converted to lower case. Thus: &quot;The Section Title&quot; will
- be normalized to &quot;the_section_title&quot;.
- </para>
- <para>
- End a section with:
- </para>
-
+ <para>
+ where <emphasis>id</emphasis> is optional. id will be the filename of the
+ generated section. If it is not present, &quot;The Section Title&quot;
+ will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
+ <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
+ All non-valid characters are converted to underscore and all upper-case
+ are converted to lower case. Thus: &quot;The Section Title&quot; will be
+ normalized to &quot;the_section_title&quot;.
+ </para>
+ <para>
+ End a section with:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[endsect]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Sections can nest, and that results in a hierarchy in the table of
- contents.
- </para>
- </section>
- <section id="quickbook.syntax.block.xinclude">
- <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title>
- <para>
- You can include another XML file with:
- </para>
-
+ <para>
+ Sections can nest, and that results in a hierarchy in the table of contents.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.xinclude">
+ <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title>
+ <para>
+ You can include another XML file with:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[xinclude file.xml]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- This is useful when file.xml has been generated by Doxygen and contains
- your reference section.
- </para>
- </section>
- <section id="quickbook.syntax.block.paragraphs">
- <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title>
- <para>
- Paragraphs start left-flushed and are terminated by two or more newlines.
- No markup is needed for paragraphs. QuickBook automatically detects
- paragraphs from the context. Block markups [section, endsect, h1, h2,
- h3, h4, h5, h6, blurb, (block-quote) ':', pre, def, table and include
- ] may also terminate a paragraph.
- </para>
- </section>
- <section id="quickbook.syntax.block.lists">
- <title><link linkend="quickbook.syntax.block.lists">Lists</link></title>
- <section id="quickbook.syntax.block.lists.ordered_lists">
- <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
- lists</link></title>
+ <para>
+ This is useful when file.xml has been generated by Doxygen and contains
+ your reference section.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.paragraphs">
+ <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title>
+ <para>
+ Paragraphs start left-flushed and are terminated by two or more newlines.
+ No markup is needed for paragraphs. QuickBook automatically detects paragraphs
+ from the context. Block markups [section, endsect, h1, h2, h3, h4, h5,
+ h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate
+ a paragraph.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.lists">
+ <title><link linkend="quickbook.syntax.block.lists">Lists</link></title>
+ <section id="quickbook.syntax.block.lists.ordered_lists">
+ <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
+ lists</link></title>
 <programlisting># One
 # Two
 # Three
 </programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
- <listitem>
- One
- </listitem>
- <listitem>
- Two
- </listitem>
- <listitem>
- Three
- </listitem>
- </orderedlist>
- </section>
- <section id="quickbook.syntax.block.lists.list_hierarchies">
- <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List
- Hierarchies</link></title>
- <para>
- List hierarchies are supported. Example:
- </para>
-
-<programlisting># One
-# Two
-# Three
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ One
+ </listitem>
+ <listitem>
+ Two
+ </listitem>
+ <listitem>
+ Three
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="quickbook.syntax.block.lists.list_hierarchies">
+ <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List
+ Hierarchies</link></title>
+ <para>
+ List hierarchies are supported. Example:
+ </para>
+
+<programlisting># One
+# Two
+# Three
     # Three.a
     # Three.b
     # Three.c
@@ -1138,58 +1130,58 @@
         # Four.a.ii
 # Five
 </programlisting>
- <para>
- will generate:
- </para>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ One
+ </listitem>
+ <listitem>
+ Two
+ </listitem>
+ <listitem>
+ Three
               <orderedlist>
                 <listitem>
- One
+ Three.a
                 </listitem>
                 <listitem>
- Two
+ Three.b
                 </listitem>
                 <listitem>
- Three
- <orderedlist>
- <listitem>
- Three.a
- </listitem>
- <listitem>
- Three.b
- </listitem>
- <listitem>
- Three.c
- </listitem>
- </orderedlist>
+ Three.c
                 </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ Fourth
+ <orderedlist>
                 <listitem>
- Fourth
+ Four.a
                   <orderedlist>
                     <listitem>
- Four.a
- <orderedlist>
- <listitem>
- Four.a.i
- </listitem>
- <listitem>
- Four.a.ii
- </listitem>
- </orderedlist>
+ Four.a.i
+ </listitem>
+ <listitem>
+ Four.a.ii
                     </listitem>
                   </orderedlist>
                 </listitem>
- <listitem>
- Five
- </listitem>
               </orderedlist>
- </section>
- <section id="quickbook.syntax.block.lists.long_list_lines">
- <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long
- List Lines</link></title>
- <para>
- Long lines will be wrapped appropriately. Example:
- </para>
-
+ </listitem>
+ <listitem>
+ Five
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="quickbook.syntax.block.lists.long_list_lines">
+ <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long
+ List Lines</link></title>
+ <para>
+ Long lines will be wrapped appropriately. Example:
+ </para>
+
 <programlisting># A short item.
 # A very long item. A very long item. A very long item.
   A very long item. A very long item. A very long item.
@@ -1198,51 +1190,49 @@
   A very long item. A very long item. A very long item.
 # A short item.
 </programlisting>
- <orderedlist>
- <listitem>
- A short item.
- </listitem>
- <listitem>
- A very long item. A very long item. A very long item. A very long
- item. A very long item. A very long item. A very long item. A very
- long item. A very long item. A very long item. A very long item.
- A very long item. A very long item. A very long item. A very long
- item.
- </listitem>
- <listitem>
- A short item.
- </listitem>
- </orderedlist>
- </section>
- <section id="quickbook.syntax.block.lists.unordered_lists">
- <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
- lists</link></title>
+ <orderedlist>
+ <listitem>
+ A short item.
+ </listitem>
+ <listitem>
+ A very long item. A very long item. A very long item. A very long item.
+ A very long item. A very long item. A very long item. A very long item.
+ A very long item. A very long item. A very long item. A very long item.
+ A very long item. A very long item. A very long item.
+ </listitem>
+ <listitem>
+ A short item.
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="quickbook.syntax.block.lists.unordered_lists">
+ <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
+ lists</link></title>
 <programlisting><!--quickbook-escape-prefix-->* First
 * Second
 * Third
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <itemizedlist>
- <listitem>
- First
- </listitem>
- <listitem>
- Second
- </listitem>
- <listitem>
- Third
- </listitem>
- </itemizedlist>
- </section>
- <section id="quickbook.syntax.block.lists.mixed_lists">
- <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed
- lists</link></title>
- <para>
- Mixed lists (ordered and unordered) are supported. Example:
- </para>
-
+ <para>
+ will generate:
+ </para>
+ <itemizedlist>
+ <listitem>
+ First
+ </listitem>
+ <listitem>
+ Second
+ </listitem>
+ <listitem>
+ Third
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="quickbook.syntax.block.lists.mixed_lists">
+ <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link></title>
+ <para>
+ Mixed lists (ordered and unordered) are supported. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix--># One
 # Two
 # Three
@@ -1251,38 +1241,38 @@
     * Three.c
 # Four
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
- <listitem>
- One
- </listitem>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ One
+ </listitem>
+ <listitem>
+ Two
+ </listitem>
+ <listitem>
+ Three
+ <itemizedlist>
                 <listitem>
- Two
+ Three.a
                 </listitem>
                 <listitem>
- Three
- <itemizedlist>
- <listitem>
- Three.a
- </listitem>
- <listitem>
- Three.b
- </listitem>
- <listitem>
- Three.c
- </listitem>
- </itemizedlist>
+ Three.b
                 </listitem>
                 <listitem>
- Four
+ Three.c
                 </listitem>
- </orderedlist>
- <para>
- And...
- </para>
-
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Four
+ </listitem>
+ </orderedlist>
+ <para>
+ And...
+ </para>
+
 <programlisting><!--quickbook-escape-prefix--># 1
     * 1.a
         # 1.a.1
@@ -1296,71 +1286,70 @@
             * 2.b.2.a
             * 2.b.2.b
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ 1
+ <itemizedlist>
                 <listitem>
- 1
- <itemizedlist>
+ 1.a
+ <orderedlist>
                     <listitem>
- 1.a
- <orderedlist>
- <listitem>
- 1.a.1
- </listitem>
- <listitem>
- 1.a.2
- </listitem>
- </orderedlist>
+ 1.a.1
                     </listitem>
                     <listitem>
- 1.b
+ 1.a.2
                     </listitem>
- </itemizedlist>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ 1.b
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ 2
+ <itemizedlist>
+ <listitem>
+ 2.a
                 </listitem>
                 <listitem>
- 2
- <itemizedlist>
+ 2.b
+ <orderedlist>
                     <listitem>
- 2.a
+ 2.b.1
                     </listitem>
                     <listitem>
- 2.b
- <orderedlist>
+ 2.b.2
+ <itemizedlist>
                         <listitem>
- 2.b.1
+ 2.b.2.a
                         </listitem>
                         <listitem>
- 2.b.2
- <itemizedlist>
- <listitem>
- 2.b.2.a
- </listitem>
- <listitem>
- 2.b.2.b
- </listitem>
- </itemizedlist>
+ 2.b.2.b
                         </listitem>
- </orderedlist>
+ </itemizedlist>
                     </listitem>
- </itemizedlist>
+ </orderedlist>
                 </listitem>
- </orderedlist>
- </section>
- </section>
- <section id="quickbook.syntax.block.code">
- <title><link linkend="quickbook.syntax.block.code">Code</link></title>
- <para>
- Preformatted code starts with a space or a tab. The code will be syntax
- highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
- Mode</link>:
- </para>
- <para>
- </para>
-
-<programlisting>
-<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+ <section id="quickbook.syntax.block.code">
+ <title><link linkend="quickbook.syntax.block.code">Code</link></title>
+ <para>
+ Preformatted code starts with a space or a tab. The code will be syntax
+ highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
+ Mode</link>:
+ </para>
+ <para>
+ </para>
+
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
 
 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
@@ -1369,73 +1358,70 @@
     <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase>
 </programlisting>
- <para>
- </para>
-
-<programlisting>
-<phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase>
+ <para>
+ </para>
+
+<programlisting><phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase>
 
 <phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase>
     <phrase role="string">'''&quot;Cooks&quot; the input text for HTML.'''</phrase>
 
     <phrase role="keyword">return</phrase> <phrase role="identifier">cgi</phrase><phrase role="special">.</phrase><phrase role="identifier">escape</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">)</phrase>
 </programlisting>
- <para>
- </para>
- <para>
- Macros that are already defined are expanded in source code. Example:
- </para>
-
+ <para>
+ </para>
+ <para>
+ Macros that are already defined are expanded in source code. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
 [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
 
     using __boost__::__array__;
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Generates:
- </para>
-
-<programlisting>
-<phrase role="keyword">using</phrase> <ulink url="http://www.boost.org/libs/libraries.htm">boost</ulink><phrase role="special">::</phrase><ulink url="http://www.boost.org/doc/html/array/reference.html">array</ulink><phrase role="special">;</phrase>
+ <para>
+ Generates:
+ </para>
+
+<programlisting><phrase role="keyword">using</phrase> <ulink url="http://www.boost.org/libs/libraries.htm">boost</ulink><phrase role="special">::</phrase><ulink url="http://www.boost.org/doc/html/array/reference.html">array</ulink><phrase role="special">;</phrase>
 </programlisting>
- </section>
- <section id="quickbook.syntax.block.escape_back">
- <title><link linkend="quickbook.syntax.block.escape_back"> Escaping Back
- To QuickBook</link></title>
- <para>
- Inside code, code blocks and inline code, QuickBook does not allow
- any markup to avoid conflicts with the target syntax (e.g. c++). In
- case you need to switch back to QuickBook markup inside code, you can
- do so using a language specific <emphasis>escape-back</emphasis> delimiter.
- In C++ and Python, the delimiter is the double tick (back-quote): &quot;``&quot;
- and &quot;``&quot;. Example:
- </para>
-
+ </section>
+ <section id="quickbook.syntax.block.escape_back">
+ <title><link linkend="quickbook.syntax.block.escape_back"> Escaping Back
+ To QuickBook</link></title>
+ <para>
+ Inside code, code blocks and inline code, QuickBook does not allow any
+ markup to avoid conflicts with the target syntax (e.g. c++). In case you
+ need to switch back to QuickBook markup inside code, you can do so using
+ a language specific <emphasis>escape-back</emphasis> delimiter. In C++
+ and Python, the delimiter is the double tick (back-quote): &quot;``&quot;
+ and &quot;``&quot;. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
 {
 }
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Will generate:
- </para>
-
-<programlisting>
-<phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
+ <para>
+ Will generate:
+ </para>
+
+<programlisting><phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
 <phrase role="special">}</phrase>
 </programlisting>
- <para>
- When escaping from code to QuickBook, only phrase level markups are
- allowed. Block level markups like lists, tables etc. are not allowed.
- </para>
- </section>
- <section id="quickbook.syntax.block.preformatted">
- <title><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></title>
- <para>
- Sometimes, you don't want some preformatted text to be parsed as C++.
- In such cases, use the <literal>[pre ... ]</literal> markup block.
- </para>
-
+ <para>
+ When escaping from code to QuickBook, only phrase level markups are allowed.
+ Block level markups like lists, tables etc. are not allowed.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.preformatted">
+ <title><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></title>
+ <para>
+ Sometimes, you don't want some preformatted text to be parsed as C++. In
+ such cases, use the <literal>[pre ... ]</literal> markup block.
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[pre
 
     Some *preformatted* text Some *preformatted* text
@@ -1446,12 +1432,12 @@
 
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Spaces, tabs and newlines are rendered as-is. Unlike all quickbook
- block level markup, pre (and Code) are the only ones that allow multiple
- newlines. The markup above will generate:
- </para>
-
+ <para>
+ Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
+ level markup, pre (and Code) are the only ones that allow multiple newlines.
+ The markup above will generate:
+ </para>
+
 <programlisting>Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
 
     Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
@@ -1459,71 +1445,70 @@
         Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
 
 </programlisting>
- <para>
- Notice that unlike Code, phrase markup such as font style is still
- permitted inside <literal>pre</literal> blocks.
- </para>
- </section>
- <section id="quickbook.syntax.block.blockquote">
- <title><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></title>
-
+ <para>
+ Notice that unlike Code, phrase markup such as font style is still permitted
+ inside <literal>pre</literal> blocks.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.blockquote">
+ <title><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix-->
 </programlisting>
- <blockquote>
- <para>
- <para>
- Indents the paragraph. This applies to one paragraph only.
- </para>
- </para>
- </blockquote>
- </section>
- <section id="quickbook.syntax.block.admonitions">
- <title><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></title>
-
+ <blockquote>
+ <para>
+ <para>
+ Indents the paragraph. This applies to one paragraph only.
+ </para>
+ </para>
+ </blockquote>
+ </section>
+ <section id="quickbook.syntax.block.admonitions">
+ <title><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[note This is a note]
 [tip This is a tip]
 [important This is important]
 [caution This is a caution]
 [warning This is a warning]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions:
- </para>
- <note>
- <para>
- This is a note
- </para>
- </note>
- <tip>
- <para>
- This is a tip
- </para>
- </tip>
- <important>
- <para>
- This is important
- </para>
- </important>
- <caution>
- <para>
- This is a caution
- </para>
- </caution>
- <warning>
- <para>
- <para>
- This is a warning
- </para>
- </warning>
- <para>
- These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>.
- So, for example <literal>[information This is some information]</literal>
- is unlikely to produce the desired effect.
- </para>
- </section>
- <section id="quickbook.syntax.block.headings">
- <title><link linkend="quickbook.syntax.block.headings">Headings</link></title>
-
+ <para>
+ generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions:
+ </para>
+ <note>
+ <para>
+ This is a note
+ </para>
+ </note>
+ <tip>
+ <para>
+ This is a tip
+ </para>
+ </tip>
+ <important>
+ <para>
+ This is important
+ </para>
+ </important>
+ <caution>
+ <para>
+ This is a caution
+ </para>
+ </caution>
+ <warning>
+ <para>
+ This is a warning
+ </para>
+ </warning>
+ <para>
+ These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>.
+ So, for example <literal>[information This is some information]</literal>
+ is unlikely to produce the desired effect.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.headings">
+ <title><link linkend="quickbook.syntax.block.headings">Headings</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[h1 Heading 1]
 [h2 Heading 2]
 [h3 Heading 3]
@@ -1531,577 +1516,564 @@
 [h5 Heading 5]
 [h6 Heading 6]
 <!--quickbook-escape-postfix--></programlisting>
- <anchor id="quickbook.syntax.block.headings.heading_1"/>
- <bridgehead renderas="sect1">
- <link linkend="quickbook.syntax.block.headings.heading_1">Heading
- 1</link>
- </bridgehead>
- <anchor id="quickbook.syntax.block.headings.heading_2"/>
- <bridgehead renderas="sect2">
- <link linkend="quickbook.syntax.block.headings.heading_2">Heading
- 2</link>
- </bridgehead>
- <anchor id="quickbook.syntax.block.headings.heading_3"/>
- <bridgehead renderas="sect3">
- <link linkend="quickbook.syntax.block.headings.heading_3">Heading
- 3</link>
- </bridgehead>
- <anchor id="quickbook.syntax.block.headings.heading_4"/>
- <bridgehead renderas="sect4">
- <link linkend="quickbook.syntax.block.headings.heading_4">Heading
- 4</link>
- </bridgehead>
- <anchor id="quickbook.syntax.block.headings.heading_5"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.headings.heading_5">Heading
- 5</link>
- </bridgehead>
- <anchor id="quickbook.syntax.block.headings.heading_6"/>
- <bridgehead renderas="sect6">
- <link linkend="quickbook.syntax.block.headings.heading_6">Heading
- 6</link>
- </bridgehead>
- <para>
- Headings 1-3 [h1 h2 and h3] will automatically have anchors with
- normalized names with <literal>name=&quot;section_id.normalized_header_text&quot;</literal>
- (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
- <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
- are converted to underscore and all upper-case are converted to lower-case.
- For example: Heading 1 in section Section 2 will be normalized to
- <literal>section_2.heading_1</literal>). You can use:
- </para>
-
+ <anchor id="quickbook.syntax.block.headings.heading_1"/>
+ <bridgehead renderas="sect1">
+ <link linkend="quickbook.syntax.block.headings.heading_1">Heading 1</link>
+ </bridgehead>
+ <anchor id="quickbook.syntax.block.headings.heading_2"/>
+ <bridgehead renderas="sect2">
+ <link linkend="quickbook.syntax.block.headings.heading_2">Heading 2</link>
+ </bridgehead>
+ <anchor id="quickbook.syntax.block.headings.heading_3"/>
+ <bridgehead renderas="sect3">
+ <link linkend="quickbook.syntax.block.headings.heading_3">Heading 3</link>
+ </bridgehead>
+ <anchor id="quickbook.syntax.block.headings.heading_4"/>
+ <bridgehead renderas="sect4">
+ <link linkend="quickbook.syntax.block.headings.heading_4">Heading 4</link>
+ </bridgehead>
+ <anchor id="quickbook.syntax.block.headings.heading_5"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.headings.heading_5">Heading 5</link>
+ </bridgehead>
+ <anchor id="quickbook.syntax.block.headings.heading_6"/>
+ <bridgehead renderas="sect6">
+ <link linkend="quickbook.syntax.block.headings.heading_6">Heading 6</link>
+ </bridgehead>
+ <para>
+ Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
+ names with <literal>name=&quot;section_id.normalized_header_text&quot;</literal>
+ (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
+ <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
+ are converted to underscore and all upper-case are converted to lower-case.
+ For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>).
+ You can use:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
- links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
- for more info.
- </para>
- </section>
- <section id="quickbook.syntax.block.generic_heading">
- <title><link linkend="quickbook.syntax.block.generic_heading">Generic
- Heading</link></title>
- <para>
- In cases when you don't want to care about the heading level (1 to
- 6), you can use the <emphasis>Generic Heading</emphasis>:
- </para>
-
+ <para>
+ to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
+ links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
+ for more info.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.generic_heading">
+ <title><link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link></title>
+ <para>
+ In cases when you don't want to care about the heading level (1 to 6),
+ you can use the <emphasis>Generic Heading</emphasis>:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[heading Heading]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- The <emphasis>Generic Heading</emphasis> assumes the level, plus
- one, of the innermost section where it is placed. For example, if
- it is placed in the outermost section, then, it assumes <emphasis>h2</emphasis>.
- </para>
- <para>
- Headings are often used as an alternative to sections. It is used
- particularly if you do not want to start a new section. In many cases,
- however, headings in a particular section is just flat. Example:
- </para>
-
+ <para>
+ The <emphasis>Generic Heading</emphasis> assumes the level, plus one, of
+ the innermost section where it is placed. For example, if it is placed
+ in the outermost section, then, it assumes <emphasis>h2</emphasis>.
+ </para>
+ <para>
+ Headings are often used as an alternative to sections. It is used particularly
+ if you do not want to start a new section. In many cases, however, headings
+ in a particular section is just flat. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[section A]
 [h2 X]
 [h2 Y]
 [h2 Z]
 [endsect]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Here we use h2 assuming that section A is the outermost level. If
- it is placed in an inner level, you'll have to use h3, h4, etc. depending
- on where the section is. In general, it is the section level plus
- one. It is rather tedious, however, to scan the section level everytime.
- If you rewrite the example above as shown below, this will be automatic:
- </para>
-
+ <para>
+ Here we use h2 assuming that section A is the outermost level. If it is
+ placed in an inner level, you'll have to use h3, h4, etc. depending on
+ where the section is. In general, it is the section level plus one. It
+ is rather tedious, however, to scan the section level everytime. If you
+ rewrite the example above as shown below, this will be automatic:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[section A]
 [heading X]
 [heading Y]
 [heading Z]
 [endsect]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- They work well regardless where you place them. You can rearrange
- sections at will without any extra work to ensure correct heading
- levels. In fact, with <emphasis>section</emphasis> and <emphasis>heading</emphasis>,
- you have all you need. <emphasis>h1</emphasis>..<emphasis>h6</emphasis>
- becomes redundant. <emphasis>h1</emphasis>..<emphasis>h6</emphasis>
- might be deprecated in the future.
- </para>
- </section>
- <section id="quickbook.syntax.block.macros">
- <title><link linkend="quickbook.syntax.block.macros">Macros</link></title>
-
+ <para>
+ They work well regardless where you place them. You can rearrange sections
+ at will without any extra work to ensure correct heading levels. In fact,
+ with <emphasis>section</emphasis> and <emphasis>heading</emphasis>, you
+ have all you need. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> becomes
+ redundant. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> might be deprecated
+ in the future.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.macros">
+ <title><link linkend="quickbook.syntax.block.macros">Macros</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[def macro_identifier some text]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- When a macro is defined, the identifier replaces the text anywhere
- in the file, in paragraphs, in markups, etc. macro_identifier is
- a string of non- white space characters except ']'. A macro may not
- follow an alphabetic character or the underscore. The replacement
- text can be any phrase (even marked up). Example:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
+ <para>
+ When a macro is defined, the identifier replaces the text anywhere in the
+ file, in paragraphs, in markups, etc. macro_identifier is a string of non-
+ white space characters except ']'. A macro may not follow an alphabetic
+ character or the underscore. The replacement text can be any phrase (even
+ marked up). Example:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
 sf_logo
 <!--quickbook-escape-postfix--></programlisting>
+ <para>
+ Now everywhere the sf_logo is placed, the picture will be inlined.
+ </para>
+ <para>
+ <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></imagedata></imageobject>
+ <textobject>
+ <phrase>sflogo</phrase>
+ </textobject>
+ </inlinemediaobject>
+ </para>
+ <tip>
+ <para>
+ It's a good idea to use macro identifiers that are distinguishable. For
+ instance, in this document, macro identifiers have two leading and trailing
+ underscores (e.g. <literal>__spirit__</literal>). The reason is to avoid unwanted
+ macro replacement.
+ </para>
+ </tip>
+ <para>
+ Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>)
+ They tend to change a lot. It is a good idea to place all links and images
+ in one place near the top to make it easy to make changes. <emphasis role="bold">2</emphasis>)
+ The syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal>
+ than <literal>[@http://spirit.sourceforge.net Spirit]</literal>.
+ </para>
+ <para>
+ Some more examples:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[def :-) [$theme/smiley.png]]
+[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ (See <link linkend="quickbook.syntax.phrase.images">Images</link> and
+ <link linkend="quickbook.syntax.phrase.links">Links</link>)
+ </para>
+ <para>
+ Invoking these macros:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->Hi __spirit__ :-)
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate this:
+ </para>
+ <para>
+ Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata
+ fileref="images/smiley.png"></imagedata></imageobject>
+ <textobject>
+ <phrase>smiley</phrase>
+ </textobject>
+ </inlinemediaobject>
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.predefined_macros">
+ <title><link linkend="quickbook.syntax.block.predefined_macros">Predefined
+ Macros</link></title>
+ <para>
+ Quickbook has some predefined macros that you can already use.
+ </para>
+ <table frame="all"> <title>Predefined Macros</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
               <para>
- Now everywhere the sf_logo is placed, the picture will be inlined.
+ Macro
               </para>
+ </entry><entry>
               <para>
- <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></imagedata></imageobject>
- <textobject>
- <phrase>sflogo</phrase>
- </textobject>
- </inlinemediaobject>
- </para>
- <tip>
- <para>
- It's a good idea to use macro identifiers that are distinguishable.
- For instance, in this document, macro identifiers have two leading
- and trailing underscores (e.g. <literal>__spirit__</literal>). The reason
- is to avoid unwanted macro replacement.
- </para>
- </tip>
- <para>
- Links (URLS) and images are good candidates for macros. <emphasis
- role="bold">1</emphasis>) They tend to change a lot. It is a good
- idea to place all links and images in one place near the top to make
- it easy to make changes. <emphasis role="bold">2</emphasis>) The
- syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal>
- than <literal>[@http://spirit.sourceforge.net Spirit]</literal>.
+ Meaning
               </para>
+ </entry><entry>
               <para>
- Some more examples:
+ Example
               </para>
-
-<programlisting><!--quickbook-escape-prefix-->[def :-) [$theme/smiley.png]]
-[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
-<!--quickbook-escape-postfix--></programlisting>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
               <para>
- (See <link linkend="quickbook.syntax.phrase.images">Images</link>
- and <link linkend="quickbook.syntax.phrase.links">Links</link>)
+ __DATE__
               </para>
+ </entry><entry>
               <para>
- Invoking these macros:
+ Today's date
               </para>
-
-<programlisting><!--quickbook-escape-prefix-->Hi __spirit__ :-)
-<!--quickbook-escape-postfix--></programlisting>
+ </entry><entry>
+ <para>
+ 2000-Dec-20
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ __TIME__
+ </para>
+ </entry><entry>
+ <para>
+ The current time
+ </para>
+ </entry><entry>
+ <para>
+ 12:00:00 PM
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
               <para>
- will generate this:
+ __FILENAME__
               </para>
+ </entry><entry>
               <para>
- Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata
- fileref="images/smiley.png"></imagedata></imageobject>
- <textobject>
- <phrase>smiley</phrase>
- </textobject>
- </inlinemediaobject>
- </para>
- </section>
- <section id="quickbook.syntax.block.predefined_macros">
- <title><link linkend="quickbook.syntax.block.predefined_macros">Predefined
- Macros</link></title>
- <para>
- Quickbook has some predefined macros that you can already use.
- </para>
- <table frame="all"> <title>Predefined Macros</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- <para>
- Macro
- </para>
- </entry><entry>
- <para>
- Meaning
- </para>
- </entry><entry>
- <para>
- Example
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- __DATE__
- </para>
- </entry><entry>
- <para>
- Today's date
- </para>
- </entry><entry>
- <para>
- 2000-Dec-20
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- __TIME__
- </para>
- </entry><entry>
- <para>
- The current time
- </para>
- </entry><entry>
- <para>
- 12:00:00 PM
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- __FILENAME__
- </para>
- </entry><entry>
- <para>
- Quickbook source filename
- </para>
- </entry><entry>
- <para>
- NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="quickbook.syntax.block.templates">
- <title><link linkend="quickbook.syntax.block.templates">Templates</link></title>
- <para>
- Templates provide a more versatile text substitution mechanism. Templates
- come in handy when you need to create parameterizable, multi-line,
- boilerplate text that you specify once and expand many times. Templates
- accept one or more arguments. These arguments act like place-holders
- for text replacement. Unlike simple macros, which are limited to
- phrase level markup, templates can contain block level markup (e.g.
- paragraphs, code blocks and tables).
+ Quickbook source filename
               </para>
+ </entry><entry>
               <para>
- Example template:
+ NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE
               </para>
-
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section id="quickbook.syntax.block.templates">
+ <title><link linkend="quickbook.syntax.block.templates">Templates</link></title>
+ <para>
+ Templates provide a more versatile text substitution mechanism. Templates
+ come in handy when you need to create parameterizable, multi-line, boilerplate
+ text that you specify once and expand many times. Templates accept one
+ or more arguments. These arguments act like place-holders for text replacement.
+ Unlike simple macros, which are limited to phrase level markup, templates
+ can contain block level markup (e.g. paragraphs, code blocks and tables).
+ </para>
+ <para>
+ Example template:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template person[name age what]
 
 Hi, my name is [name]. I am [age] years old. I am a [what].
 
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <anchor id="quickbook.syntax.block.templates.template_identifier"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.template_identifier">Template
- Identifier</link>
- </bridgehead>
- <para>
- Template identifiers can either consist of:
- </para>
- <itemizedlist>
- <listitem>
- An initial alphabetic character or the underscore, followed by
- zero or more alphanumeric characters or the underscore. This is
- similar to your typical C/C++ identifier.
- </listitem>
- <listitem>
- A single character punctuation (a non-alphanumeric printable character)
- </listitem>
- </itemizedlist>
- <anchor id="quickbook.syntax.block.templates.formal_template_arguments"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.formal_template_arguments">Formal
- Template Arguments</link>
- </bridgehead>
- <para>
- Template formal arguments are identifiers consisting of an initial
- alphabetic character or the underscore, followed by zero or more
- alphanumeric characters or the underscore. This is similar to your
- typical C/C++ identifier.
- </para>
- <para>
- A template formal argument temporarily hides a template of the same
- name at the point where the <link linkend="quickbook.syntax.block.templates.template_expansion">template
- is expanded</link>. Note that the body of the <literal>person</literal>
- template above refers to <literal>name</literal> <literal>age</literal>
- and <literal>what</literal> as <literal>[name]</literal> <literal>[age]</literal>
- and <literal>[what]</literal>. <literal>name</literal> <literal>age</literal>
- and <literal>what</literal> are actually templates that exist in
- the duration of the template call.
- </para>
- <anchor id="quickbook.syntax.block.templates.template_body"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.template_body">Template
- Body</link>
- </bridgehead>
- <para>
- The template body can be just about any QuickBook block or phrase.
- There are actually two forms. Templates may be phrase or block level.
- Phrase templates are of the form:
- </para>
-
+ <anchor id="quickbook.syntax.block.templates.template_identifier"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.template_identifier">Template
+ Identifier</link>
+ </bridgehead>
+ <para>
+ Template identifiers can either consist of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ An initial alphabetic character or the underscore, followed by zero or
+ more alphanumeric characters or the underscore. This is similar to your
+ typical C/C++ identifier.
+ </listitem>
+ <listitem>
+ A single character punctuation (a non-alphanumeric printable character)
+ </listitem>
+ </itemizedlist>
+ <anchor id="quickbook.syntax.block.templates.formal_template_arguments"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.formal_template_arguments">Formal
+ Template Arguments</link>
+ </bridgehead>
+ <para>
+ Template formal arguments are identifiers consisting of an initial alphabetic
+ character or the underscore, followed by zero or more alphanumeric characters
+ or the underscore. This is similar to your typical C/C++ identifier.
+ </para>
+ <para>
+ A template formal argument temporarily hides a template of the same name
+ at the point where the <link linkend="quickbook.syntax.block.templates.template_expansion">template
+ is expanded</link>. Note that the body of the <literal>person</literal>
+ template above refers to <literal>name</literal> <literal>age</literal>
+ and <literal>what</literal> as <literal>[name]</literal> <literal>[age]</literal>
+ and <literal>[what]</literal>. <literal>name</literal> <literal>age</literal>
+ and <literal>what</literal> are actually templates that exist in the duration
+ of the template call.
+ </para>
+ <anchor id="quickbook.syntax.block.templates.template_body"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.template_body">Template
+ Body</link>
+ </bridgehead>
+ <para>
+ The template body can be just about any QuickBook block or phrase. There
+ are actually two forms. Templates may be phrase or block level. Phrase
+ templates are of the form:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Block templates are of the form:
- </para>
-
+ <para>
+ Block templates are of the form:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN]
 replacement text...
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- The basic rule is as follows: if a newline immediately follows the
- argument list, then it is a block template, otherwise, it is a phrase
- template. Phrase templates are typically expanded as part of phrases.
- Like macros, block level elements are not allowed in phrase templates.
- </para>
- <anchor id="quickbook.syntax.block.templates.template_expansion"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.template_expansion">Template
- Expansion</link>
- </bridgehead>
- <para>
- You expand a template this way:
- </para>
-
+ <para>
+ The basic rule is as follows: if a newline immediately follows the argument
+ list, then it is a block template, otherwise, it is a phrase template.
+ Phrase templates are typically expanded as part of phrases. Like macros,
+ block level elements are not allowed in phrase templates.
+ </para>
+ <anchor id="quickbook.syntax.block.templates.template_expansion"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.template_expansion">Template
+ Expansion</link>
+ </bridgehead>
+ <para>
+ You expand a template this way:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template_identifier arg1..arg2..arg3]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- At template expansion, you supply the actual arguments. The template
- will be expanded with your supplied arguments. Example:
- </para>
-
+ <para>
+ At template expansion, you supply the actual arguments. The template will
+ be expanded with your supplied arguments. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[person James Bond..39..Spy]
 [person Santa Clause..87..Big Red Fatso]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Which will expand to:
- </para>
- <para>
- <para>
- Hi, my name is James Bond. I am 39 years old. I am a Spy.
- </para>
- <para>
- Hi, my name is Santa Clause. I am 87 years old. I am a Big Red
- Fatso.
- </para>
- </para>
- <caution>
- <para>
- A word of caution: Templates are recursive. A template can call
- another template or even itself, directly or indirectly. There
- are no control structures in QuickBook (yet) so this will always
- mean infinite recursion. QuickBook can detect this situation and
- report an error if recursion exceeds a certain limit.
- </para>
- </caution>
- <para>
- Each actual argument can be a word, a text fragment or just about
- any <link linkend="quickbook.syntax.phrase">QuickBook phrase</link>.
- Arguments are separated by the double dot <literal>&quot;..&quot;</literal>
- and terminated by the close parenthesis.
- </para>
- <anchor id="quickbook.syntax.block.templates.nullary_templates"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.nullary_templates">Nullary
- Templates</link>
- </bridgehead>
- <para>
- Nullary templates look and act like simple macros. Example:
- </para>
-
+ <para>
+ Which will expand to:
+ </para>
+ <para>
+ <para>
+ Hi, my name is James Bond. I am 39 years old. I am a Spy.
+ </para>
+ <para>
+ Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
+ </para>
+ </para>
+ <caution>
+ <para>
+ A word of caution: Templates are recursive. A template can call another
+ template or even itself, directly or indirectly. There are no control
+ structures in QuickBook (yet) so this will always mean infinite recursion.
+ QuickBook can detect this situation and report an error if recursion
+ exceeds a certain limit.
+ </para>
+ </caution>
+ <para>
+ Each actual argument can be a word, a text fragment or just about any
+ <link linkend="quickbook.syntax.phrase">QuickBook phrase</link>. Arguments
+ are separated by the double dot <literal>&quot;..&quot;</literal> and terminated
+ by the close parenthesis.
+ </para>
+ <anchor id="quickbook.syntax.block.templates.nullary_templates"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.nullary_templates">Nullary
+ Templates</link>
+ </bridgehead>
+ <para>
+ Nullary templates look and act like simple macros. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template alpha[]&apos;&apos;&apos;&amp;#945;&apos;&apos;&apos;]
 [template beta[]&apos;&apos;&apos;&amp;#946;&apos;&apos;&apos;]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Expanding:
- </para>
-
+ <para>
+ Expanding:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->Some squigles...[*[alpha][beta]]<!--quickbook-escape-postfix--></programlisting>
- <para>
- We have:
- </para>
- <para>
- Some squiggles...<emphasis role="bold">&#945;&#946;</emphasis>
- </para>
- <para>
- The difference with macros are
- </para>
- <itemizedlist>
- <listitem>
- The explicit <link linkend="quickbook.syntax.block.templates.template_expansion">template
- expansion syntax</link>. This is an advantage because, now, we
- don't have to use obscure naming conventions like double underscores
- (e.g. __alpha__) to avoid unwanted macro replacement.
- </listitem>
- <listitem>
- The template is expanded at the point where it is invoked. A macro
- is expanded immediately at its point of declaration. This is subtle
- and can cause a slight difference in behavior especially if you
- refer to other macros and templates in the body.
- </listitem>
- </itemizedlist>
- <para>
- The empty brackets after the template identifier (<literal>alpha[]</literal>)
- indicates no arguments. If the template body does not look like a
- template argument list, we can elide the empty brackets. Example:
- </para>
-
+ <para>
+ We have:
+ </para>
+ <para>
+ Some squiggles...<emphasis role="bold">&#945;&#946;</emphasis>
+ </para>
+ <para>
+ The difference with macros are
+ </para>
+ <itemizedlist>
+ <listitem>
+ The explicit <link linkend="quickbook.syntax.block.templates.template_expansion">template
+ expansion syntax</link>. This is an advantage because, now, we don't
+ have to use obscure naming conventions like double underscores (e.g.
+ __alpha__) to avoid unwanted macro replacement.
+ </listitem>
+ <listitem>
+ The template is expanded at the point where it is invoked. A macro is
+ expanded immediately at its point of declaration. This is subtle and
+ can cause a slight difference in behavior especially if you refer to
+ other macros and templates in the body.
+ </listitem>
+ </itemizedlist>
+ <para>
+ The empty brackets after the template identifier (<literal>alpha[]</literal>)
+ indicates no arguments. If the template body does not look like a template
+ argument list, we can elide the empty brackets. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template aristotle_quote Aristotle: [*['Education is the best provision
 for the journey to old age.]]]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Expanding:
- </para>
-
+ <para>
+ Expanding:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->Here's a quote from [aristotle_quote].
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- We have:
- </para>
- <para>
- Here's a quote from Aristotle: <emphasis role="bold"><emphasis>Education
- is the best provision for the journey to old age.</emphasis></emphasis>.
- </para>
- <para>
- The disadvantage is that you can't avoid the space between the template
- identifier, <code><phrase role="identifier">aristotle_quote</phrase></code>,
- and the template body &quot;Aristotle...&quot;. This space will be
- part of the template body. If that space is unwanted, use empty brackets
- or use the space escape: &quot;<code><phrase role="special">\</phrase>
- </code>&quot;. Example:
- </para>
-
+ <para>
+ We have:
+ </para>
+ <para>
+ Here's a quote from Aristotle: <emphasis role="bold"><emphasis>Education
+ is the best provision for the journey to old age.</emphasis></emphasis>.
+ </para>
+ <para>
+ The disadvantage is that you can't avoid the space between the template
+ identifier, <code><phrase role="identifier">aristotle_quote</phrase></code>,
+ and the template body &quot;Aristotle...&quot;. This space will be part
+ of the template body. If that space is unwanted, use empty brackets or
+ use the space escape: &quot;<code><phrase role="special">\</phrase> </code>&quot;.
+ Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template tag\ _tag]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Then expanding:
- </para>
-
+ <para>
+ Then expanding:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->`struct` x[tag];
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- We have:
- </para>
- <para>
- <code><phrase role="keyword">struct</phrase></code> x_tag;
- </para>
- <para>
- You have a couple of ways to do it. I personally prefer the explicit
- empty brackets, though.
- </para>
- <anchor id="quickbook.syntax.block.templates.simple_arguments"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.simple_arguments">Simple
- Arguments</link>
- </bridgehead>
- <para>
- As mentioned, arguments are separated by the double dot <literal>&quot;..&quot;</literal>.
- If there are less arguments passed than expected, QuickBook attempts
- to break the last argument into two or more arguments following this
- logic:
- </para>
- <itemizedlist>
- <listitem>
- Break the last argument into two, at the first space found (<literal>'',
- '\n', \t' or '\r'</literal>).
- </listitem>
- <listitem>
- Repeat until there are enough arguments or if there are no more
- spaces found (in which case, an error is reported).
- </listitem>
- </itemizedlist>
- <para>
- For example:
- </para>
-
+ <para>
+ We have:
+ </para>
+ <para>
+ <code><phrase role="keyword">struct</phrase></code> x_tag;
+ </para>
+ <para>
+ You have a couple of ways to do it. I personally prefer the explicit empty
+ brackets, though.
+ </para>
+ <anchor id="quickbook.syntax.block.templates.simple_arguments"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.simple_arguments">Simple
+ Arguments</link>
+ </bridgehead>
+ <para>
+ As mentioned, arguments are separated by the double dot <literal>&quot;..&quot;</literal>.
+ If there are less arguments passed than expected, QuickBook attempts to
+ break the last argument into two or more arguments following this logic:
+ </para>
+ <itemizedlist>
+ <listitem>
+ Break the last argument into two, at the first space found (<literal>'',
+ '\n', \t' or '\r'</literal>).
+ </listitem>
+ <listitem>
+ Repeat until there are enough arguments or if there are no more spaces
+ found (in which case, an error is reported).
+ </listitem>
+ </itemizedlist>
+ <para>
+ For example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template simple[a b c d] [a][b][c][d]]
 [simple w x y z]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will produce:
- </para>
- <para>
- wxyz
- </para>
- <para>
- &quot;w x y z&quot; is initially treated as a single argument because
- we didn't supply any <literal>&quot;..&quot;</literal> separators.
- However, since <literal>simple</literal> expects 4 arguments, &quot;w
- x y z&quot; is broken down iteratively (applying the logic above)
- until we have &quot;w&quot;, &quot;x&quot;, &quot;y&quot; and &quot;z&quot;.
- </para>
- <para>
- QuickBook only tries to get the arguments it needs. For example:
- </para>
-
+ <para>
+ will produce:
+ </para>
+ <para>
+ wxyz
+ </para>
+ <para>
+ &quot;w x y z&quot; is initially treated as a single argument because we
+ didn't supply any <literal>&quot;..&quot;</literal> separators. However,
+ since <literal>simple</literal> expects 4 arguments, &quot;w x y z&quot;
+ is broken down iteratively (applying the logic above) until we have &quot;w&quot;,
+ &quot;x&quot;, &quot;y&quot; and &quot;z&quot;.
+ </para>
+ <para>
+ QuickBook only tries to get the arguments it needs. For example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[simple w x y z trail]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will produce:
- </para>
- <para>
- wxyz trail
- </para>
- <para>
- The arguments being: &quot;w&quot;, &quot;x&quot;, &quot;y&quot;
- and &quot;z trail&quot;.
- </para>
- <para>
- It should be obvious now that for simple arguments with no spaces,
- we can get by without separating the arguments with <literal>&quot;..&quot;</literal>
- separators. It is possible to combine <literal>&quot;..&quot;</literal>
- separators with the argument passing simplification presented above.
- Example:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[simple what do you think ..m a n?]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will produce:
- </para>
- <para>
- what do you think man?
- </para>
- <anchor id="quickbook.syntax.block.templates.punctuation_templates"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.templates.punctuation_templates">Punctuation
- Templates</link>
- </bridgehead>
- <para>
- With templates, one of our objectives is to allow us to rewrite QuickBook
- in QuickBook (as a qbk library). For that to happen, we need to accommodate
- single character punctuation templates which are fairly common in
- QuickBook. You might have noticed that single character punctuations
- are allowed as <link linkend="quickbook.syntax.block.templates.template_identifier">template
- identifiers</link>. Example:
- </para>
-
+ <para>
+ will produce:
+ </para>
+ <para>
+ wxyz trail
+ </para>
+ <para>
+ The arguments being: &quot;w&quot;, &quot;x&quot;, &quot;y&quot; and &quot;z
+ trail&quot;.
+ </para>
+ <para>
+ It should be obvious now that for simple arguments with no spaces, we can
+ get by without separating the arguments with <literal>&quot;..&quot;</literal>
+ separators. It is possible to combine <literal>&quot;..&quot;</literal>
+ separators with the argument passing simplification presented above. Example:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[simple what do you think ..m a n?]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will produce:
+ </para>
+ <para>
+ what do you think man?
+ </para>
+ <anchor id="quickbook.syntax.block.templates.punctuation_templates"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.templates.punctuation_templates">Punctuation
+ Templates</link>
+ </bridgehead>
+ <para>
+ With templates, one of our objectives is to allow us to rewrite QuickBook
+ in QuickBook (as a qbk library). For that to happen, we need to accommodate
+ single character punctuation templates which are fairly common in QuickBook.
+ You might have noticed that single character punctuations are allowed as
+ <link linkend="quickbook.syntax.block.templates.template_identifier">template
+ identifiers</link>. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[template ![bar] <!--quickbook-escape-postfix-->&lt;hey&gt;<!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix-->&lt;/hey&gt;<!--quickbook-escape-prefix-->]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- Now, expanding this:
- </para>
-
+ <para>
+ Now, expanding this:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[!baz]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- We will have:
- </para>
-
+ <para>
+ We will have:
+ </para>
+
 <programlisting>&lt;hey&gt;baz&lt;/hey&gt;
 </programlisting>
- </section>
- <section id="quickbook.syntax.block.blurbs">
- <title><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></title>
-
+ </section>
+ <section id="quickbook.syntax.block.blurbs">
+ <title><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[blurb :-) [*An eye catching advertisement or note...]
 
     __spirit__ is an object-oriented recursive-descent parser generator framework
@@ -2110,35 +2082,35 @@
     completely in C++.
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate this:
- </para>
- <sidebar role="blurb">
- <para>
- <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
- <textobject>
- <phrase>smiley</phrase>
- </textobject>
- </inlinemediaobject> <emphasis role="bold">An eye catching advertisement
- or note...</emphasis>
- </para>
- <para>
- <ulink url="http://spirit.sourceforge.net">Spirit</ulink> is an object-oriented
- recursive-descent parser generator framework implemented using template
- meta-programming techniques. Expression templates allow us to approximate
- the syntax of Extended Backus-Normal Form (EBNF) completely in C++.
- </para>
- </sidebar>
- <note>
- <para>
- Prefer <link linkend="quickbook.syntax.block.admonitions">admonitions</link>
- wherever appropriate.
- </para>
- </note>
- </section>
- <section id="quickbook.syntax.block.tables">
- <title><link linkend="quickbook.syntax.block.tables">Tables</link></title>
-
+ <para>
+ will generate this:
+ </para>
+ <sidebar role="blurb">
+ <para>
+ <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
+ <textobject>
+ <phrase>smiley</phrase>
+ </textobject>
+ </inlinemediaobject> <emphasis role="bold">An eye catching advertisement
+ or note...</emphasis>
+ </para>
+ <para>
+ <ulink url="http://spirit.sourceforge.net">Spirit</ulink> is an object-oriented
+ recursive-descent parser generator framework implemented using template
+ meta-programming techniques. Expression templates allow us to approximate
+ the syntax of Extended Backus-Normal Form (EBNF) completely in C++.
+ </para>
+ </sidebar>
+ <note>
+ <para>
+ Prefer <link linkend="quickbook.syntax.block.admonitions">admonitions</link>
+ wherever appropriate.
+ </para>
+ </note>
+ </section>
+ <section id="quickbook.syntax.block.tables">
+ <title><link linkend="quickbook.syntax.block.tables">Tables</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[table A Simple Table
     [[Heading 1] [Heading 2] [Heading 3]]
     [[R0-C0] [R0-C1] [R0-C2]]
@@ -2146,85 +2118,85 @@
     [[R2-C0] [R2-C1] [R2-C2]]
 ]
 <!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <table frame="all"> <title>A Simple Table</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Heading 1
+ </para>
+ </entry><entry>
+ <para>
+ Heading 2
+ </para>
+ </entry><entry>
+ <para>
+ Heading 3
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ R0-C0
+ </para>
+ </entry><entry>
+ <para>
+ R0-C1
+ </para>
+ </entry><entry>
+ <para>
+ R0-C2
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
               <para>
- will generate:
+ R2-C0
               </para>
- <table frame="all"> <title>A Simple Table</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- <para>
- Heading 1
- </para>
- </entry><entry>
- <para>
- Heading 2
- </para>
- </entry><entry>
- <para>
- Heading 3
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- R0-C0
- </para>
- </entry><entry>
- <para>
- R0-C1
- </para>
- </entry><entry>
- <para>
- R0-C2
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- R2-C0
- </para>
- </entry><entry>
- <para>
- R2-C1
- </para>
- </entry><entry>
- <para>
- R2-C2
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- R3-C0
- </para>
- </entry><entry>
- <para>
- R3-C1
- </para>
- </entry><entry>
- <para>
- R3-C2
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- The table title is optional. The first row of the table is automatically
- treated as the table header; that is, it is wrapped in <literal>&lt;thead&gt;...&lt;/thead&gt;</literal>
- XML tags. Note that unlike the original QuickDoc, the columns are
- nested in [ cells... ]. The syntax is free-format and allows big
- cells to be formatted nicely. Example:
+ </entry><entry>
+ <para>
+ R2-C1
+ </para>
+ </entry><entry>
+ <para>
+ R2-C2
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ R3-C0
+ </para>
+ </entry><entry>
+ <para>
+ R3-C1
+ </para>
+ </entry><entry>
+ <para>
+ R3-C2
               </para>
-
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ The table title is optional. The first row of the table is automatically
+ treated as the table header; that is, it is wrapped in <literal>&lt;thead&gt;...&lt;/thead&gt;</literal>
+ XML tags. Note that unlike the original QuickDoc, the columns are nested
+ in [ cells... ]. The syntax is free-format and allows big cells to be formatted
+ nicely. Example:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[table Table with fat cells
     [[Heading 1] [Heading 2]]
     [
@@ -2246,63 +2218,63 @@
     ]
 ]
 <!--quickbook-escape-postfix--></programlisting>
+ <para>
+ and thus:
+ </para>
+ <table frame="all"> <title>Table with fat cells</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Heading 1
+ </para>
+ </entry><entry>
+ <para>
+ Heading 2
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ Row 0, Col 0: a small cell
+ </para>
+ </entry><entry>
+ <para>
+ Row 0, Col 1: a big fat cell with paragraphs
+ </para>
+ <para>
+ Boost provides free peer-reviewed portable C++ source libraries.
+ </para>
+ <para>
+ We emphasize libraries that work well with the C++ Standard Library.
+ Boost libraries are intended to be widely useful, and usable across
+ a broad spectrum of applications. The Boost license encourages both
+ commercial and non-commercial use.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
               <para>
- and thus:
+ Row 1, Col 0: a small cell
               </para>
- <table frame="all"> <title>Table with fat cells</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>
- Heading 1
- </para>
- </entry><entry>
- <para>
- Heading 2
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- Row 0, Col 0: a small cell
- </para>
- </entry><entry>
- <para>
- Row 0, Col 1: a big fat cell with paragraphs
- </para>
- <para>
- Boost provides free peer-reviewed portable C++ source libraries.
- </para>
- <para>
- We emphasize libraries that work well with the C++ Standard
- Library. Boost libraries are intended to be widely useful,
- and usable across a broad spectrum of applications. The Boost
- license encourages both commercial and non-commercial use.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- Row 1, Col 0: a small cell
- </para>
- </entry><entry>
- <para>
- Row 1, Col 1: a small cell
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ </entry><entry>
               <para>
- Here's how to have preformatted blocks of code in a table cell:
+ Row 1, Col 1: a small cell
               </para>
-
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Here's how to have preformatted blocks of code in a table cell:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[table Table with code
     [[Comment] [Code]]
     [
@@ -2319,32 +2291,31 @@
     ]
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <table frame="all"> <title>Table with code</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>
- Comment
- </para>
- </entry><entry>
- <para>
- Code
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- My first program
- </para>
- </entry><entry>
- <para>
-
-<programlisting>
-<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+ <table frame="all"> <title>Table with code</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Comment
+ </para>
+ </entry><entry>
+ <para>
+ Code
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ My first program
+ </para>
+ </entry><entry>
+ <para>
+
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
 
 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
@@ -2352,381 +2323,361 @@
     <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase>
 </programlisting>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section id="quickbook.syntax.block.variable_lists">
- <title><link linkend="quickbook.syntax.block.variable_lists">Variable
- Lists</link></title>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section id="quickbook.syntax.block.variable_lists">
+ <title><link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link></title>
+
 <programlisting><!--quickbook-escape-prefix-->[variablelist A Variable List
     [[term 1] [The definition of term 1]]
     [[term 2] [The definition of term 2]]
     [[term 3] [The definition of term 3]]
 ]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <variablelist>
- <title>A Variable List</title> <varlistentry><term>term 1</term>
- <listitem>
- <para>
- The definition of term 1
- </para>
- </listitem>
- </varlistentry> <varlistentry><term>term 2</term>
- <listitem>
- <para>
- The definition of term 2
- </para>
- </listitem>
- </varlistentry> <varlistentry><term>term 3</term>
- <listitem>
- <para>
- The definition of term 3
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The rules for variable lists are the same as for tables, except that
- only 2 &quot;columns&quot; are allowed. The first column contains
- the terms, and the second column contains the definitions. Those
- familiar with HTML will recognize this as a &quot;definition list&quot;.
- </para>
- </section>
- <section id="quickbook.syntax.block.include">
- <title><link linkend="quickbook.syntax.block.include">Include</link></title>
- <para>
- You can include one QuickBook file from another. The syntax is simply:
- </para>
-
+ <para>
+ will generate:
+ </para>
+ <variablelist>
+ <title>A Variable List</title> <varlistentry><term>term 1</term>
+ <listitem>
+ <para>
+ The definition of term 1
+ </para>
+ </listitem>
+ </varlistentry> <varlistentry><term>term 2</term>
+ <listitem>
+ <para>
+ The definition of term 2
+ </para>
+ </listitem>
+ </varlistentry> <varlistentry><term>term 3</term>
+ <listitem>
+ <para>
+ The definition of term 3
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The rules for variable lists are the same as for tables, except that only
+ 2 &quot;columns&quot; are allowed. The first column contains the terms,
+ and the second column contains the definitions. Those familiar with HTML
+ will recognize this as a &quot;definition list&quot;.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.include">
+ <title><link linkend="quickbook.syntax.block.include">Include</link></title>
+ <para>
+ You can include one QuickBook file from another. The syntax is simply:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[include someother.qbk]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- The included file will be processed as if it had been cut and pasted
- into the current document, with the following exceptions:
- </para>
- <itemizedlist>
- <listitem>
- The __FILENAME__ predefined macro will reflect the name of the file currently
- being processed.
- </listitem>
- <listitem>
- Any macros defined in the included file are scoped to that file.
- </listitem>
- </itemizedlist>
- <para>
- The <literal>[include]</literal> directive lets you specify a document
- id to use for the included file. When this id is not explicitly specified,
- the id defaults to the filename (&quot;someother&quot;, in the example
- above). You can specify the id like this:
- </para>
-
+ <para>
+ The included file will be processed as if it had been cut and pasted into
+ the current document, with the following exceptions:
+ </para>
+ <itemizedlist>
+ <listitem>
+ The __FILENAME__ predefined macro will reflect the name of the file currently being
+ processed.
+ </listitem>
+ <listitem>
+ Any macros defined in the included file are scoped to that file.
+ </listitem>
+ </itemizedlist>
+ <para>
+ The <literal>[include]</literal> directive lets you specify a document
+ id to use for the included file. When this id is not explicitly specified,
+ the id defaults to the filename (&quot;someother&quot;, in the example
+ above). You can specify the id like this:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[include:someid someother.qbk]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- All auto-generated anchors will use the document id as a unique prefix.
- So for instance, if there is a top section in someother.qbk named
- &quot;Intro&quot;, the named anchor for that section will be &quot;someid.intro&quot;,
- and you can link to it with <literal>[link someid.intro The Intro]</literal>.
- </para>
- </section>
- <section id="quickbook.syntax.block.import">
- <title><link linkend="quickbook.syntax.block.import">Import</link></title>
- <para>
- When documenting code, you'd surely need to present code from actual
- source files. While it is possible to copy some code and paste them
- in your QuickBook file, doing so is error prone and the extracted
- code in the documentation tends to get out of sync with the actual
- code as the code evolves. The problem, as always, is that once documentation
- is written, the tendency is for the docs to languish in the archives
- without maintenance.
- </para>
- <para>
- QuickBook's import facility provides a nice solution.
- </para>
- <anchor id="quickbook.syntax.block.import.example"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.import.example">Example</link>
- </bridgehead>
- <para>
- You can effortlessly import code snippets from source code into your
- QuickBook. The following illustrates how this is done:
- </para>
-
+ <para>
+ All auto-generated anchors will use the document id as a unique prefix.
+ So for instance, if there is a top section in someother.qbk named &quot;Intro&quot;,
+ the named anchor for that section will be &quot;someid.intro&quot;, and
+ you can link to it with <literal>[link someid.intro The Intro]</literal>.
+ </para>
+ </section>
+ <section id="quickbook.syntax.block.import">
+ <title><link linkend="quickbook.syntax.block.import">Import</link></title>
+ <para>
+ When documenting code, you'd surely need to present code from actual source
+ files. While it is possible to copy some code and paste them in your QuickBook
+ file, doing so is error prone and the extracted code in the documentation
+ tends to get out of sync with the actual code as the code evolves. The
+ problem, as always, is that once documentation is written, the tendency
+ is for the docs to languish in the archives without maintenance.
+ </para>
+ <para>
+ QuickBook's import facility provides a nice solution.
+ </para>
+ <anchor id="quickbook.syntax.block.import.example"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.import.example">Example</link>
+ </bridgehead>
+ <para>
+ You can effortlessly import code snippets from source code into your QuickBook.
+ The following illustrates how this is done:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp]
 [foo]
 [bar]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- The first line:
- </para>
-
+ <para>
+ The first line:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- collects specially marked-up code snippets from <ulink url="../../test/stub.cpp">stub.cpp</ulink>
- and places them in your QuickBook file as virtual templates. Each
- of the specially marked-up code snippets has a name (e.g. <code><phrase
- role="identifier">foo</phrase></code> and <code><phrase role="identifier">bar</phrase></code>
- in the example above). This shall be the template identifier for
- that particular code snippet. The second and third line above does
- the actual template expansion:
- </para>
-
+ <para>
+ collects specially marked-up code snippets from <ulink url="../../test/stub.cpp">stub.cpp</ulink>
+ and places them in your QuickBook file as virtual templates. Each of the
+ specially marked-up code snippets has a name (e.g. <code><phrase role="identifier">foo</phrase></code>
+ and <code><phrase role="identifier">bar</phrase></code> in the example
+ above). This shall be the template identifier for that particular code
+ snippet. The second and third line above does the actual template expansion:
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->[foo]
 [bar]
 <!--quickbook-escape-postfix--></programlisting>
- <para>
- And the result is:
- </para>
- <para>
- <para>
- This is the <emphasis role="bold"><emphasis>foo</emphasis></emphasis>
- function.
- </para>
- <para>
- This description can have paragraphs...
- </para>
- <itemizedlist>
- <listitem>
- lists
- </listitem>
- <listitem>
- etc.
- </listitem>
- </itemizedlist>
- <para>
- And any quickbook block markup.
- </para>
- <para>
-
-<programlisting>
-<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase>
-<phrase role="special">{</phrase>
- <phrase role="comment">// return 'em, foo man!
-</phrase> <phrase role="keyword">return</phrase> <phrase role="string">&quot;foo&quot;</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase>
-</programlisting>
- </para>
- <para>
- <calloutlist></calloutlist>
- </para>
- <para>
- This is the <emphasis role="bold"><emphasis>bar</emphasis></emphasis>
- function
- </para>
- <para>
-
-<programlisting>
-<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">bar</phrase><phrase role="special">()</phrase>
-<phrase role="special">{</phrase>
- <phrase role="comment">// return 'em, bar man!
-</phrase> <phrase role="keyword">return</phrase> <phrase role="string">&quot;bar&quot;</phrase><phrase role="special">;</phrase>
+ <para>
+ And the result is:
+ </para>
+ <para>
+ <para>
+ This is the <emphasis role="bold"><emphasis>foo</emphasis></emphasis>
+ function.
+ </para>
+ <para>
+ This description can have paragraphs...
+ </para>
+ <itemizedlist>
+ <listitem>
+ lists
+ </listitem>
+ <listitem>
+ etc.
+ </listitem>
+ </itemizedlist>
+ <para>
+ And any quickbook block markup.
+ </para>
+ <para>
+
+<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase>
+<phrase role="special">{</phrase>
+ <phrase role="comment">// return 'em, foo man!
+</phrase> <phrase role="keyword">return</phrase> <phrase role="string">&quot;foo&quot;</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+</programlisting>
+ </para>
+ <para>
+ This is the <emphasis role="bold"><emphasis>bar</emphasis></emphasis>
+ function
+ </para>
+ <para>
+
+<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">bar</phrase><phrase role="special">()</phrase>
+<phrase role="special">{</phrase>
+ <phrase role="comment">// return 'em, bar man!
+</phrase> <phrase role="keyword">return</phrase> <phrase role="string">&quot;bar&quot;</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase></programlisting>
- </para>
- <para>
- Some trailing text here <calloutlist></calloutlist>
- </para>
- </para>
- <anchor id="quickbook.syntax.block.import.code_snippet_markup"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.import.code_snippet_markup">Code
- Snippet Markup</link>
- </bridgehead>
- <para>
- Note how the code snippets in <ulink url="../../test/stub.cpp">stub.cpp</ulink>
- get marked up. We use distinguishable comments following the form:
- </para>
-
-<programlisting>
-<phrase role="comment">//[id
+ </para>
+ <para>
+ Some trailing text here
+ </para>
+ </para>
+ <anchor id="quickbook.syntax.block.import.code_snippet_markup"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.import.code_snippet_markup">Code
+ Snippet Markup</link>
+ </bridgehead>
+ <para>
+ Note how the code snippets in <ulink url="../../test/stub.cpp">stub.cpp</ulink>
+ get marked up. We use distinguishable comments following the form:
+ </para>
+
+<programlisting><phrase role="comment">//[id
 </phrase><phrase role="identifier">some</phrase> <phrase role="identifier">code</phrase> <phrase role="identifier">here</phrase>
 <phrase role="comment">//]
 </phrase></programlisting>
- <para>
- The first comment line above initiates a named code-snippet. This
- prefix will not be visible in quickbook. The entire code-snippet
- in between <code><phrase role="comment">//[id</phrase></code> and
- <code><phrase role="comment">//]</phrase></code> will be inserted
- as a template in quickbook with name <emphasis><emphasis>id</emphasis></emphasis>.
- The comment <code><phrase role="comment">//]</phrase></code> ends
- a code-snippet This too will not be visible in quickbook.
- </para>
- <anchor id="quickbook.syntax.block.import.special_comments"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.import.special_comments">Special
- Comments</link>
- </bridgehead>
- <para>
- Special comments of the form:
- </para>
-
-<programlisting>
-<phrase role="comment">//` some [*quickbook] markup here
+ <para>
+ The first comment line above initiates a named code-snippet. This prefix
+ will not be visible in quickbook. The entire code-snippet in between <code><phrase
+ role="comment">//[id</phrase></code> and <code><phrase role="comment">//]</phrase></code>
+ will be inserted as a template in quickbook with name <emphasis><emphasis>id</emphasis></emphasis>.
+ The comment <code><phrase role="comment">//]</phrase></code> ends a code-snippet
+ This too will not be visible in quickbook.
+ </para>
+ <anchor id="quickbook.syntax.block.import.special_comments"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.import.special_comments">Special
+ Comments</link>
+ </bridgehead>
+ <para>
+ Special comments of the form:
+ </para>
+
+<programlisting><phrase role="comment">//` some [*quickbook] markup here
 </phrase></programlisting>
- <para>
- and:
- </para>
-
-<programlisting>
-<phrase role="comment">/*` some [*quickbook] markup here */</phrase>
+ <para>
+ and:
+ </para>
+
+<programlisting><phrase role="comment">/*` some [*quickbook] markup here */</phrase>
 </programlisting>
- <para>
- will be parsed by QuickBook. This can contain quickbook <emphasis>blocks</emphasis>
- (e.g. sections, paragraphs, tables, etc). In the first case, the
- initial slash-slash, tick and white-space shall be ignored. In the
- second, the initial slash-star-tick and the final star-slash shall
- be ignored.
- </para>
- <anchor id="quickbook.syntax.block.import.callouts"/>
- <bridgehead renderas="sect5">
- <link linkend="quickbook.syntax.block.import.callouts">Callouts</link>
- </bridgehead>
- <para>
- Special comments of the form:
- </para>
-
-<programlisting>
-<phrase role="comment">/*&lt; some [*quickbook] markup here &gt;*/</phrase>
+ <para>
+ will be parsed by QuickBook. This can contain quickbook <emphasis>blocks</emphasis>
+ (e.g. sections, paragraphs, tables, etc). In the first case, the initial
+ slash-slash, tick and white-space shall be ignored. In the second, the
+ initial slash-star-tick and the final star-slash shall be ignored.
+ </para>
+ <anchor id="quickbook.syntax.block.import.callouts"/>
+ <bridgehead renderas="sect5">
+ <link linkend="quickbook.syntax.block.import.callouts">Callouts</link>
+ </bridgehead>
+ <para>
+ Special comments of the form:
+ </para>
+
+<programlisting><phrase role="comment">/*&lt; some [*quickbook] markup here &gt;*/</phrase>
 </programlisting>
- <para>
- will be regarded as callouts. These will be collected, numbered and
- rendered as a &quot;callout bug&quot; (a small icon with a number).
- After the whole snippet is parsed, the callout list is generated.
- See <ulink url="http://www.docbook.org/tdg/en/html/callout.html">Callouts</ulink>
- for details. Example:
- </para>
- <para>
- <para>
-
-<programlisting>
-<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo_bar</phrase><phrase role="special">()</phrase> <!--quickbook-escape-prefix--><phrase role="callout_bug"><co id="quickbook0co" linkends="quickbook0" /></phrase><!--quickbook-escape-postfix-->
+ <para>
+ will be regarded as callouts. These will be collected, numbered and rendered
+ as a &quot;callout bug&quot; (a small icon with a number). After the whole
+ snippet is parsed, the callout list is generated. See <ulink url="http://www.docbook.org/tdg/en/html/callout.html">Callouts</ulink>
+ for details. Example:
+ </para>
+ <para>
+ <para>
+
+<programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo_bar</phrase><phrase role="special">()</phrase> <!--quickbook-escape-prefix--><phrase role="callout_bug"><co id="quickbook0co" linkends="quickbook0" /></phrase><!--quickbook-escape-postfix-->
 <phrase role="special">{</phrase>
     <phrase role="keyword">return</phrase> <phrase role="string">&quot;foo-bar&quot;</phrase><phrase role="special">;</phrase> <!--quickbook-escape-prefix--><phrase role="callout_bug"><co id="quickbook1co" linkends="quickbook1" /></phrase><!--quickbook-escape-postfix-->
 <phrase role="special">}</phrase>
 </programlisting>
- </para>
- <para>
- <calloutlist><callout arearefs="quickbook0co" id="quickbook0"><para> The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar
- for details</ulink> </para></callout><callout arearefs="quickbook1co" id="quickbook1"><para> return 'em, foo-bar man! </para></callout></calloutlist>
- </para>
- </para>
- <para>
- Checkout <ulink url="../../test/stub.cpp">stub.cpp</ulink> to see
- the actual code.
- </para>
- </section>
- </section>
- </section>
- <section id="quickbook.install">
- <title><link linkend="quickbook.install"> Installation and configuration</link></title>
+ </para>
           <para>
- This section provides some guidelines on how to install and configure
- BoostBook and Quickbook under several operating systems.
+ <calloutlist><callout arearefs="quickbook0co" id="quickbook0"><para> The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar
+ for details</ulink> </para></callout><callout arearefs="quickbook1co" id="quickbook1"><para> return 'em, foo-bar man! </para></callout></calloutlist>
           </para>
+ </para>
+ <para>
+ Checkout <ulink url="../../test/stub.cpp">stub.cpp</ulink> to see the actual
+ code.
+ </para>
+ </section>
+ </section>
+ </section>
+ <section id="quickbook.install">
+ <title><link linkend="quickbook.install"> Installation and configuration</link></title>
+ <para>
+ This section provides some guidelines on how to install and configure BoostBook
+ and Quickbook under several operating systems.
+ </para>
+ <para>
+ Before continuing, it is very important that you keep this in mind: if you
+ try to build some documents and the process breaks due to misconfiguration,
+ be absolutely sure to delete any <code><phrase role="identifier">bin</phrase></code>
+ and <code><phrase role="identifier">bin</phrase><phrase role="special">.</phrase><phrase
+ role="identifier">v2</phrase></code> directories generated by the build before
+ trying again. Otherwise your configuration fixes will not take any effect.
+ </para>
+ <section id="quickbook.install.windows">
+ <title><link linkend="quickbook.install.windows"> Windows 2000, XP, 2003, Vista</link></title>
+ <para>
+ </para>
+ <blockquote>
+ <para>
           <para>
- Before continuing, it is very important that you keep this in mind: if
- you try to build some documents and the process breaks due to misconfiguration,
- be absolutely sure to delete any <code><phrase role="identifier">bin</phrase></code>
- and <code><phrase role="identifier">bin</phrase><phrase role="special">.</phrase><phrase
- role="identifier">v2</phrase></code> directories generated by the build
- before trying again. Otherwise your configuration fixes will not take
- any effect.
- </para>
- <section id="quickbook.install.windows">
- <title><link linkend="quickbook.install.windows"> Windows 2000, XP, 2003,
- Vista</link></title>
- <para>
- </para>
- <blockquote>
- <para>
- <para>
- <emphasis>Section contributed by Julio M. Merino Vidal</emphasis>
- </para>
- </para>
- </blockquote>
- <para>
- The following instructions apply to any Windows system based on Windows
- 2000, including Windows XP, Windows 2003 Server and Windows Vista.
- The paths shown below are taken from a Windows Vista machine; you will
- need to adjust them to match your system in case you are running an
- older version.
- </para>
- <orderedlist>
- <listitem>
- First of all you need to have a copy of <code><phrase role="identifier">xsltproc</phrase></code>
- for Windows. There are many ways to get this tool, but to keep things
- simple, use the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary
- packages</ulink> made by Igor Zlatkovic. At the very least, you need
- to download the following packages: <code><phrase role="identifier">iconv</phrase></code>,
- <code><phrase role="identifier">zlib</phrase></code>, <code><phrase
- role="identifier">libxml2</phrase></code> and <code><phrase role="identifier">libxslt</phrase></code>.
- </listitem>
- <listitem>
- Unpack all these packages in the same directory so that you get unique
- <code><phrase role="identifier">bin</phrase></code>, <code><phrase
- role="identifier">include</phrase></code> and <code><phrase role="identifier">lib</phrase></code>
- directories within the hierarchy. These instructions use <code><phrase
- role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
- role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
- role="identifier">example</phrase><phrase role="special">\</phrase><phrase
- role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
- role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
- role="identifier">xml</phrase></code> as the root for all files.
- </listitem>
- <listitem>
- From the command line, go to the <code><phrase role="identifier">bin</phrase></code>
- directory and launch <code><phrase role="identifier">xsltproc</phrase><phrase
- role="special">.</phrase><phrase role="identifier">exe</phrase></code>
- to ensure it works. You should get usage information on screen.
- </listitem>
- <listitem>
- Download <ulink url="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook
- XML 4.2</ulink> and unpack it in the same directory used above. That
- is: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
- role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
- role="identifier">example</phrase><phrase role="special">\</phrase><phrase
- role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
- role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
- role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
- role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
- role="identifier">xml</phrase></code>.
- </listitem>
- <listitem>
- Download the latest <ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935&amp;package_id=16608">Docbook
- XSL</ulink> version and unpack it, again in the same directory used
- before. To make things easier, rename the directory created during
- the extraction to <code><phrase role="identifier">docbook</phrase><phrase
- role="special">-</phrase><phrase role="identifier">xsl</phrase></code>
- (bypassing the version name): <code><phrase role="identifier">C</phrase><phrase
- role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase
- role="special">\</phrase><phrase role="identifier">example</phrase><phrase
- role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase
- role="special">\</phrase><phrase role="identifier">boost</phrase><phrase
- role="special">\</phrase><phrase role="identifier">xml</phrase><phrase
- role="special">\</phrase><phrase role="identifier">docbook</phrase><phrase
- role="special">-</phrase><phrase role="identifier">xsl</phrase></code>.
- </listitem>
- <listitem>
- Add the following to your <code><phrase role="identifier">user</phrase><phrase
- role="special">-</phrase><phrase role="identifier">config</phrase><phrase
- role="special">.</phrase><phrase role="identifier">jam</phrase></code>
- file, which should live in your home directory (<code><phrase role="special">%</phrase><phrase
- role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase
- role="identifier">HOMEPATH</phrase><phrase role="special">%</phrase></code>).
- You must already have it somewhere or otherwise you could not be
- building Boost (i.e. missing tools configuration).
- </listitem>
- </orderedlist>
-
-<programlisting>
-<phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase>
+ <emphasis>Section contributed by Julio M. Merino Vidal</emphasis>
+ </para>
+ </para>
+ </blockquote>
+ <para>
+ The following instructions apply to any Windows system based on Windows 2000,
+ including Windows XP, Windows 2003 Server and Windows Vista. The paths shown
+ below are taken from a Windows Vista machine; you will need to adjust them
+ to match your system in case you are running an older version.
+ </para>
+ <orderedlist>
+ <listitem>
+ First of all you need to have a copy of <code><phrase role="identifier">xsltproc</phrase></code>
+ for Windows. There are many ways to get this tool, but to keep things simple,
+ use the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary packages</ulink>
+ made by Igor Zlatkovic. At the very least, you need to download the following
+ packages: <code><phrase role="identifier">iconv</phrase></code>, <code><phrase
+ role="identifier">zlib</phrase></code>, <code><phrase role="identifier">libxml2</phrase></code>
+ and <code><phrase role="identifier">libxslt</phrase></code>.
+ </listitem>
+ <listitem>
+ Unpack all these packages in the same directory so that you get unique
+ <code><phrase role="identifier">bin</phrase></code>, <code><phrase role="identifier">include</phrase></code>
+ and <code><phrase role="identifier">lib</phrase></code> directories within
+ the hierarchy. These instructions use <code><phrase role="identifier">C</phrase><phrase
+ role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">example</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">boost</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">xml</phrase></code>
+ as the root for all files.
+ </listitem>
+ <listitem>
+ From the command line, go to the <code><phrase role="identifier">bin</phrase></code>
+ directory and launch <code><phrase role="identifier">xsltproc</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">exe</phrase></code>
+ to ensure it works. You should get usage information on screen.
+ </listitem>
+ <listitem>
+ Download <ulink url="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook
+ XML 4.2</ulink> and unpack it in the same directory used above. That is:
+ <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
+ role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">example</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
+ role="identifier">xml</phrase></code>.
+ </listitem>
+ <listitem>
+ Download the latest <ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935&amp;package_id=16608">Docbook
+ XSL</ulink> version and unpack it, again in the same directory used before.
+ To make things easier, rename the directory created during the extraction
+ to <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
+ role="identifier">xsl</phrase></code> (bypassing the version name): <code><phrase
+ role="identifier">C</phrase><phrase role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">example</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">boost</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">xml</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">docbook</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">xsl</phrase></code>.
+ </listitem>
+ <listitem>
+ Add the following to your <code><phrase role="identifier">user</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">config</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">jam</phrase></code>
+ file, which should live in your home directory (<code><phrase role="special">%</phrase><phrase
+ role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase
+ role="identifier">HOMEPATH</phrase><phrase role="special">%</phrase></code>).
+ You must already have it somewhere or otherwise you could not be building
+ Boost (i.e. missing tools configuration).
+ </listitem>
+ </orderedlist>
+
+<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase>
     <phrase role="special">:</phrase> <phrase role="string">&quot;C:/Users/example/Documents/boost/xml/bin/xsltproc.exe&quot;</phrase>
     <phrase role="special">;</phrase>
 
@@ -2735,90 +2686,84 @@
     <phrase role="special">:</phrase> <phrase role="string">&quot;C:/Users/example/Documents/boost/xml/docbook-xml&quot;</phrase>
     <phrase role="special">;</phrase>
 </programlisting>
- <para>
- The above steps are enough to get a functional BoostBook setup. Quickbook
- will be automatically built when needed. If you want to avoid these
- rebuilds:
- </para>
- <orderedlist>
- <listitem>
- Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
- role="special">\</phrase><phrase role="identifier">tools</phrase><phrase
- role="special">\</phrase><phrase role="identifier">quickbook</phrase></code>).
- </listitem>
- <listitem>
- Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
- <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
- </listitem>
- <listitem>
- Copy the resulting <code><phrase role="identifier">quickbook</phrase><phrase
- role="special">.</phrase><phrase role="identifier">exe</phrase></code>
- binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
- role="special">\</phrase><phrase role="identifier">bin</phrase><phrase
- role="special">.</phrase><phrase role="identifier">v2</phrase></code>
- hierarchy) to a safe place. Following our previous example, you can
- install it into: <code><phrase role="identifier">C</phrase><phrase
- role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase
- role="special">\</phrase><phrase role="identifier">example</phrase><phrase
- role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase
- role="special">\</phrase><phrase role="identifier">boost</phrase><phrase
- role="special">\</phrase><phrase role="identifier">xml</phrase><phrase
- role="special">\</phrase><phrase role="identifier">bin</phrase></code>.
- </listitem>
- <listitem>
- Add the following to your <code><phrase role="identifier">user</phrase><phrase
- role="special">-</phrase><phrase role="identifier">config</phrase><phrase
- role="special">.</phrase><phrase role="identifier">jam</phrase></code>
- file:
- </listitem>
- </orderedlist>
-
-<programlisting>
-<phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
+ <para>
+ The above steps are enough to get a functional BoostBook setup. Quickbook
+ will be automatically built when needed. If you want to avoid these rebuilds:
+ </para>
+ <orderedlist>
+ <listitem>
+ Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">tools</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">quickbook</phrase></code>).
+ </listitem>
+ <listitem>
+ Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
+ <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
+ </listitem>
+ <listitem>
+ Copy the resulting <code><phrase role="identifier">quickbook</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">exe</phrase></code>
+ binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
+ role="special">\</phrase><phrase role="identifier">bin</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">v2</phrase></code> hierarchy)
+ to a safe place. Following our previous example, you can install it into:
+ <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
+ role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">example</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
+ role="identifier">bin</phrase></code>.
+ </listitem>
+ <listitem>
+ Add the following to your <code><phrase role="identifier">user</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">config</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">jam</phrase></code>
+ file:
+ </listitem>
+ </orderedlist>
+
+<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
     <phrase role="special">:</phrase> <phrase role="string">&quot;C:/Users/example/Documents/boost/xml/bin/quickbook.exe&quot;</phrase>
     <phrase role="special">;</phrase>
 </programlisting>
- </section>
- <section id="quickbook.install.linux">
- <title><link linkend="quickbook.install.linux"> Debian, Ubuntu</link></title>
- <para>
- The following instructions apply to Debian and its derivatives. They
- are based on a Ubuntu Edgy install but should work on other Debian
- based systems.
- </para>
- <para>
- First install the <code><phrase role="identifier">bjam</phrase></code>,
- <code><phrase role="identifier">xsltproc</phrase></code>, <code><phrase
- role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
- role="identifier">xsl</phrase></code> and <code><phrase role="identifier">docbook</phrase><phrase
- role="special">-</phrase><phrase role="identifier">xml</phrase></code>
- packages. For example, using <code><phrase role="identifier">apt</phrase><phrase
- role="special">-</phrase><phrase role="identifier">get</phrase></code>:
- </para>
-
-<programlisting>
-<phrase role="identifier">sudo</phrase> <phrase role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase> <phrase role="identifier">install</phrase> <phrase role="identifier">xsltprc</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xsl</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xml</phrase>
+ </section>
+ <section id="quickbook.install.linux">
+ <title><link linkend="quickbook.install.linux"> Debian, Ubuntu</link></title>
+ <para>
+ The following instructions apply to Debian and its derivatives. They are
+ based on a Ubuntu Edgy install but should work on other Debian based systems.
+ </para>
+ <para>
+ First install the <code><phrase role="identifier">bjam</phrase></code>,
+ <code><phrase role="identifier">xsltproc</phrase></code>, <code><phrase role="identifier">docbook</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">xsl</phrase></code> and
+ <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
+ role="identifier">xml</phrase></code> packages. For example, using <code><phrase
+ role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase></code>:
+ </para>
+
+<programlisting><phrase role="identifier">sudo</phrase> <phrase role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase> <phrase role="identifier">install</phrase> <phrase role="identifier">xsltprc</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xsl</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xml</phrase>
 </programlisting>
- <para>
- If you're planning on building boost's documentation, you'll also need
- to install the <code><phrase role="identifier">doxygen</phrase></code>
- package as well.
- </para>
- <para>
- Next, we need to configure Boost Build to compile BoostBook files.
- Add the following to your <code><phrase role="identifier">user</phrase><phrase
- role="special">-</phrase><phrase role="identifier">config</phrase><phrase
- role="special">.</phrase><phrase role="identifier">jam</phrase></code>
- file, which should be in your home directory. If you don't have one,
- create a file containing this text. For more information on setting
- up <code><phrase role="identifier">user</phrase><phrase role="special">-</phrase><phrase
- role="identifier">config</phrase><phrase role="special">.</phrase><phrase
- role="identifier">jam</phrase></code>, see the <ulink url="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost
- Build documentation</ulink>.
- </para>
-
-<programlisting>
-<phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> <phrase role="special">;</phrase>
+ <para>
+ If you're planning on building boost's documentation, you'll also need to
+ install the <code><phrase role="identifier">doxygen</phrase></code> package
+ as well.
+ </para>
+ <para>
+ Next, we need to configure Boost Build to compile BoostBook files. Add the
+ following to your <code><phrase role="identifier">user</phrase><phrase role="special">-</phrase><phrase
+ role="identifier">config</phrase><phrase role="special">.</phrase><phrase
+ role="identifier">jam</phrase></code> file, which should be in your home
+ directory. If you don't have one, create a file containing this text. For
+ more information on setting up <code><phrase role="identifier">user</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">config</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">jam</phrase></code>, see
+ the <ulink url="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost
+ Build documentation</ulink>.
+ </para>
+
+<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> <phrase role="special">;</phrase>
 
 <phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase>
     <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">stylesheet</phrase><phrase role="special">/</phrase><phrase role="identifier">nwalsh</phrase>
@@ -2828,91 +2773,89 @@
 <phrase role="comment"># Remove this line if you're not using doxygen
 </phrase><phrase role="identifier">using</phrase> <phrase role="identifier">doxygen</phrase> <phrase role="special">;</phrase>
 </programlisting>
- <para>
- The above steps are enough to get a functional BoostBook setup. Quickbook
- will be automatically built when needed. If you want to avoid these
- rebuilds:
- </para>
- <orderedlist>
- <listitem>
- Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
- role="special">/</phrase><phrase role="identifier">tools</phrase><phrase
- role="special">/</phrase><phrase role="identifier">quickbook</phrase></code>).
- </listitem>
- <listitem>
- Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
- <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
- </listitem>
- <listitem>
- Copy the resulting <code><phrase role="identifier">quickbook</phrase></code>
- binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
- role="special">/</phrase><phrase role="identifier">bin</phrase><phrase
- role="special">.</phrase><phrase role="identifier">v2</phrase></code>
- hierarchy) to a safe place. The traditional location is <code><phrase
- role="special">/</phrase><phrase role="identifier">usr</phrase><phrase
- role="special">/</phrase><phrase role="identifier">local</phrase><phrase
- role="special">/</phrase><phrase role="identifier">bin</phrase></code>.
- </listitem>
- <listitem>
- Add the following to your <code><phrase role="identifier">user</phrase><phrase
- role="special">-</phrase><phrase role="identifier">config</phrase><phrase
- role="special">.</phrase><phrase role="identifier">jam</phrase></code>
- file, using the full path of the quickbook executable:
- </listitem>
- </orderedlist>
-
-<programlisting>
-<phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
+ <para>
+ The above steps are enough to get a functional BoostBook setup. Quickbook
+ will be automatically built when needed. If you want to avoid these rebuilds:
+ </para>
+ <orderedlist>
+ <listitem>
+ Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
+ role="special">/</phrase><phrase role="identifier">tools</phrase><phrase
+ role="special">/</phrase><phrase role="identifier">quickbook</phrase></code>).
+ </listitem>
+ <listitem>
+ Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
+ <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
+ </listitem>
+ <listitem>
+ Copy the resulting <code><phrase role="identifier">quickbook</phrase></code>
+ binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
+ role="special">/</phrase><phrase role="identifier">bin</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">v2</phrase></code> hierarchy)
+ to a safe place. The traditional location is <code><phrase role="special">/</phrase><phrase
+ role="identifier">usr</phrase><phrase role="special">/</phrase><phrase
+ role="identifier">local</phrase><phrase role="special">/</phrase><phrase
+ role="identifier">bin</phrase></code>.
+ </listitem>
+ <listitem>
+ Add the following to your <code><phrase role="identifier">user</phrase><phrase
+ role="special">-</phrase><phrase role="identifier">config</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">jam</phrase></code>
+ file, using the full path of the quickbook executable:
+ </listitem>
+ </orderedlist>
+
+<programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
     <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">local</phrase><phrase role="special">/</phrase><phrase role="identifier">bin</phrase><phrase role="special">/</phrase><phrase role="identifier">quickbook</phrase>
     <phrase role="special">;</phrase>
 </programlisting>
- </section>
- </section>
- <section id="quickbook.editors">
- <title><link linkend="quickbook.editors"> Editor Support</link></title>
+ </section>
+ </section>
+ <section id="quickbook.editors">
+ <title><link linkend="quickbook.editors"> Editor Support</link></title>
+ <para>
+ Editing quickbook files is usually done with text editors both simple and powerful.
+ The following sections list the settings for some editors which can help make
+ editing quickbook files a bit easier.
+ </para>
+ <sidebar role="blurb">
+ <para>
+ <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
+ <textobject>
+ <phrase>note</phrase>
+ </textobject>
+ </inlinemediaobject> You may submit your settings, tips, and suggestions to
+ the authors, or through the <ulink url="https://lists.sourceforge.net/lists/listinfo/boost-">docs
+ Boost Docs mailing list</ulink>.
+ </para>
+ </sidebar>
+ <section id="quickbook.editors.scite">
+ <title><link linkend="quickbook.editors.scite"> Scintilla Text Editor</link></title>
+ <blockquote>
+ <para>
           <para>
- Editing quickbook files is usually done with text editors both simple
- and powerful. The following sections list the settings for some editors
- which can help make editing quickbook files a bit easier.
- </para>
- <sidebar role="blurb">
- <para>
- <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
- <textobject>
- <phrase>note</phrase>
- </textobject>
- </inlinemediaobject> You may submit your settings, tips, and suggestions
- to the authors, or through the <ulink url="https://lists.sourceforge.net/lists/listinfo/boost-">docs
- Boost Docs mailing list</ulink>.
- </para>
- </sidebar>
- <section id="quickbook.editors.scite">
- <title><link linkend="quickbook.editors.scite"> Scintilla Text Editor</link></title>
- <blockquote>
- <para>
- <para>
- <emphasis>Section contributed by Dean Michael Berris</emphasis>
- </para>
- </para>
- </blockquote>
- <para>
- The Scintilla Text Editor (SciTE) is a free source code editor for
- Win32 and X. It uses the SCIntilla source code editing component.
- </para>
- <sidebar role="blurb">
- <para>
- <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
- <textobject>
- <phrase>tip</phrase>
- </textobject>
- </inlinemediaobject> SciTE can be downloaded from <ulink url="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html>
- </para>
- </sidebar>
- <para>
- You can use the following settings to highlight quickbook tags when
- editing quickbook files.
- </para>
-
+ <emphasis>Section contributed by Dean Michael Berris</emphasis>
+ </para>
+ </para>
+ </blockquote>
+ <para>
+ The Scintilla Text Editor (SciTE) is a free source code editor for Win32
+ and X. It uses the SCIntilla source code editing component.
+ </para>
+ <sidebar role="blurb">
+ <para>
+ <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
+ <textobject>
+ <phrase>tip</phrase>
+ </textobject>
+ </inlinemediaobject> SciTE can be downloaded from <ulink url="
http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html>
+ </para>
+ </sidebar>
+ <para>
+ You can use the following settings to highlight quickbook tags when editing
+ quickbook files.
+ </para>
+
 <programlisting><!--quickbook-escape-prefix-->qbk=*.qbk
 lexer.*.qbk=props
 use.tabs.$(qbk)=0
@@ -2925,47 +2868,45 @@
 comment.box.middle.props=
 comment.box.end.props=]
 <!--quickbook-escape-postfix--></programlisting>
- <sidebar role="blurb">
- <para>
- <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
- <textobject>
- <phrase>note</phrase>
- </textobject>
- </inlinemediaobject> Thanks to Rene Rivera for the above SciTE settings.
- </para>
- </sidebar>
- </section>
- </section>
- <section id="quickbook.faq">
- <title><link linkend="quickbook.faq"> Frequently Asked Questions</link></title>
- <anchor id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/>
- <bridgehead renderas="sect3">
- <link linkend="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">Can
- I use QuickBook for non-Boost documentation?</link>
- </bridgehead>
- <para>
- QuickBook can be used for non-Boost documentation with a little extra
- work.
- </para>
- <blockquote>
- <para>
- <para>
- <emphasis>Faq contributed by Michael Marcin</emphasis>
- </para>
- </para>
- </blockquote>
- <para>
- When building HTML documentation with BoostBook a Boost C++ Libraries
- header is added to the files. When using QuickBook to document projects
- outside of Boost this is not desirable. This behavior can be overridden
- at the BoostBook level by specifying some XSLT options. When using Boost
- Build version 2 (BBv2) this can be achieved by adding parameters to the
- BoostBook target declaration.
- </para>
- <para>
- For example:
- </para>
-
+ <sidebar role="blurb">
+ <para>
+ <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
+ <textobject>
+ <phrase>note</phrase>
+ </textobject>
+ </inlinemediaobject> Thanks to Rene Rivera for the above SciTE settings.
+ </para>
+ </sidebar>
+ </section>
+ </section>
+ <section id="quickbook.faq">
+ <title><link linkend="quickbook.faq"> Frequently Asked Questions</link></title>
+ <anchor id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/>
+ <bridgehead renderas="sect3">
+ <link linkend="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">Can
+ I use QuickBook for non-Boost documentation?</link>
+ </bridgehead>
+ <para>
+ QuickBook can be used for non-Boost documentation with a little extra work.
+ </para>
+ <blockquote>
+ <para>
+ <para>
+ <emphasis>Faq contributed by Michael Marcin</emphasis>
+ </para>
+ </para>
+ </blockquote>
+ <para>
+ When building HTML documentation with BoostBook a Boost C++ Libraries header
+ is added to the files. When using QuickBook to document projects outside of
+ Boost this is not desirable. This behavior can be overridden at the BoostBook
+ level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
+ this can be achieved by adding parameters to the BoostBook target declaration.
+ </para>
+ <para>
+ For example:
+ </para>
+
 <programlisting>using quickbook ;
 
 xml my_doc : my_doc.qbk ;
@@ -2981,785 +2922,780 @@
         &lt;xsl:param&gt;nav.layout=none
     ;
 </programlisting>
- </section>
- <section id="quickbook.ref">
- <title><link linkend="quickbook.ref"> Quick Reference</link></title>
+ </section>
+ <section id="quickbook.ref">
+ <title><link linkend="quickbook.ref"> Quick Reference</link></title>
+ <para>
+ [cpp]
+ </para>
+ <table frame="all"> <title>Syntax Compendium</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ To do this...
+ </para>
+ </entry><entry>
+ <para>
+ Use this...
+ </para>
+ </entry><entry>
+ <para>
+ See this...
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ comment
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[/ some comment]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.comments">Comments</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <emphasis>italics</emphasis>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>['italics] or /italics/</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
+ and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
+ formatting</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <emphasis role="bold">bold</emphasis>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[*bold] or *bold*</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
+ and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
+ formatting</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <emphasis role="underline">underline</emphasis>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[_underline] or _underline_</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
+ and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
+ formatting</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>teletype</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[^teletype] or =teletype=</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
+ and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
+ formatting</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <emphasis role="strikethrough">strikethrough</emphasis>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[-strikethrough]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
+ and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
+ formatting</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <replaceable>
+ replaceable
+ </replaceable>
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[~replaceable]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ source mode
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[c++]</literal> or <literal>[python]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ inline code
+ </para>
+ </entry><entry>
+ <para>
+ <literal>`int main();`</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.inline_code">Inline code</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ code block
+ </para>
+ </entry><entry>
+ <para>
+ <literal>``int main();``</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.code">Code</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ code escape
+ </para>
+ </entry><entry>
+ <para>
+ <literal>``from c++ to QuickBook``</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.escape_back">Escaping Back To QuickBook</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ line break
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[br] or \n</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.line_break">line-break</link>
+ <emphasis role="bold">DEPRECATED</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ anchor
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[#anchor]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.anchors">Anchors</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[@
http://www.boost.org Boost]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.links">Links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ anchor link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[link section.anchor Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ refentry link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[link xml.refentry Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ function link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[funcref fully::qualified::function_name Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ class link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[classref fully::qualified::class_name Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ member link
+ </para>
+ </entry><entry>
           <para>
- [cpp]
+ <literal>[memberref fully::qualified::member_name Link text]</literal>
           </para>
- <table frame="all"> <title>Syntax Compendium</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- <para>
- To do this...
- </para>
- </entry><entry>
- <para>
- Use this...
- </para>
- </entry><entry>
- <para>
- See this...
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- comment
- </para>
- </entry><entry>
- <para>
- <literal>[/ some comment]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.comments">Comments</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <emphasis>italics</emphasis>
- </para>
- </entry><entry>
- <para>
- <literal>['italics] or /italics/</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
- and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
- formatting</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <emphasis role="bold">bold</emphasis>
- </para>
- </entry><entry>
- <para>
- <literal>[*bold] or *bold*</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
- and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
- formatting</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <emphasis role="underline">underline</emphasis>
- </para>
- </entry><entry>
- <para>
- <literal>[_underline] or _underline_</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
- and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
- formatting</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>teletype</literal>
- </para>
- </entry><entry>
- <para>
- <literal>[^teletype] or =teletype=</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
- and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
- formatting</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <emphasis role="strikethrough">strikethrough</emphasis>
- </para>
- </entry><entry>
- <para>
- <literal>[-strikethrough]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
- and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
- formatting</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <replaceable>
- replaceable
- </replaceable>
- </para>
- </entry><entry>
- <para>
- <literal>[~replaceable]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- source mode
- </para>
- </entry><entry>
- <para>
- <literal>[c++]</literal> or <literal>[python]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- inline code
- </para>
- </entry><entry>
- <para>
- <literal>`int main();`</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.inline_code">Inline code</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- code block
- </para>
- </entry><entry>
- <para>
- <literal>``int main();``</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.code">Code</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- code escape
- </para>
- </entry><entry>
- <para>
- <literal>``from c++ to QuickBook``</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.escape_back">Escaping Back
- To QuickBook</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- line break
- </para>
- </entry><entry>
- <para>
- <literal>[br] or \n</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.line_break">line-break</link>
- <emphasis role="bold">DEPRECATED</emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- anchor
- </para>
- </entry><entry>
- <para>
- <literal>[#anchor]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.anchors">Anchors</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- link
- </para>
- </entry><entry>
- <para>
- <literal>[@http://www.boost.org Boost]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.links">Links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- anchor link
- </para>
- </entry><entry>
- <para>
- <literal>[link section.anchor Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- refentry link
- </para>
- </entry><entry>
- <para>
- <literal>[link xml.refentry Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.refentry_links">refentry
- links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- function link
- </para>
- </entry><entry>
- <para>
- <literal>[funcref fully::qualified::function_name Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- class link
- </para>
- </entry><entry>
- <para>
- <literal>[classref fully::qualified::class_name Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- member link
- </para>
- </entry><entry>
- <para>
- <literal>[memberref fully::qualified::member_name Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- enum link
- </para>
- </entry><entry>
- <para>
- <literal>[enumref fully::qualified::enum_name Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- macro link
- </para>
- </entry><entry>
- <para>
- <literal>[macroref MACRO_NAME Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- concept link
- </para>
- </entry><entry>
- <para>
- <literal>[conceptref ConceptName Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- header link
- </para>
- </entry><entry>
- <para>
- <literal>[headerref path/to/header.hpp Link text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.code_links">function, class,
- member, enum, macro, concept or header links</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- escape
- </para>
- </entry><entry>
- <para>
- <literal>'''escaped text (no processing/formatting)'''</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.escape">Escape</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- single char escape
- </para>
- </entry><entry>
- <para>
- <literal>\c</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.single_char_escape">Single
- char escape</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- images
- </para>
- </entry><entry>
- <para>
- <literal>[$image.jpg]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.phrase.images">Images</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- begin section
- </para>
- </entry><entry>
- <para>
- <literal>[section The Section Title]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.section">Section</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- end section
- </para>
- </entry><entry>
- <para>
- <literal>[endsect]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.section">Section</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- paragraph
- </para>
- </entry><entry>
- <para>
- No markup. Paragraphs start left-flushed and are terminated by
- two or more newlines.
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- ordered list
- </para>
- </entry><entry>
- <para>
-
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ enum link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[enumref fully::qualified::enum_name Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ macro link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[macroref MACRO_NAME Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ concept link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[conceptref ConceptName Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ header link
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[headerref path/to/header.hpp Link text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.code_links">function, class, member,
+ enum, macro, concept or header links</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ escape
+ </para>
+ </entry><entry>
+ <para>
+ <literal>'''escaped text (no processing/formatting)'''</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.escape">Escape</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ single char escape
+ </para>
+ </entry><entry>
+ <para>
+ <literal>\c</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.single_char_escape">Single char
+ escape</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ images
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[$image.jpg]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.phrase.images">Images</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ begin section
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[section The Section Title]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.section">Section</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ end section
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[endsect]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.section">Section</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ paragraph
+ </para>
+ </entry><entry>
+ <para>
+ No markup. Paragraphs start left-flushed and are terminated by two or
+ more newlines.
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ ordered list
+ </para>
+ </entry><entry>
+ <para>
+
 <programlisting><!--quickbook-escape-prefix--># one
 # two
 # three
 <!--quickbook-escape-postfix--></programlisting>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
- lists</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- unordered list
- </para>
- </entry><entry>
- <para>
-
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered lists</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ unordered list
+ </para>
+ </entry><entry>
+ <para>
+
 <programlisting><!--quickbook-escape-prefix-->* one
 * two
 * three
 <!--quickbook-escape-postfix--></programlisting>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
- lists</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- code
- </para>
- </entry><entry>
- <para>
- No markup. Preformatted code starts with a space or a tab.
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.code">Code</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- preformatted
- </para>
- </entry><entry>
- <para>
- <literal>[pre preformatted]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.preformatted">Preformatted</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- block quote
- </para>
- </entry><entry>
- <para>
- <literal>[:sometext...]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.blockquote">Blockquote</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 1
- </para>
- </entry><entry>
- <para>
- <literal>[h1 Heading 1]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 2
- </para>
- </entry><entry>
- <para>
- <literal>[h2 Heading 2]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 3
- </para>
- </entry><entry>
- <para>
- <literal>[h3 Heading 3]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 4
- </para>
- </entry><entry>
- <para>
- <literal>[h4 Heading 4]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 5
- </para>
- </entry><entry>
- <para>
- <literal>[h5 Heading 5]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- heading 6
- </para>
- </entry><entry>
- <para>
- <literal>[h6 Heading 6]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.headings">Heading</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- macro
- </para>
- </entry><entry>
- <para>
- <literal>[def macro_identifier some text]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.macros">Macros</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- template
- </para>
- </entry><entry>
- <para>
- <literal>[template[a b] [a] body [b]]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.templates">Templates</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- blurb
- </para>
- </entry><entry>
- <para>
- <literal>[blurb advertisement or note...]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- admonition
- </para>
- </entry><entry>
- <para>
- <literal>[warning Warning text...]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- table
- </para>
- </entry><entry>
- <para>
-
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
+ lists</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ code
+ </para>
+ </entry><entry>
+ <para>
+ No markup. Preformatted code starts with a space or a tab.
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.code">Code</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ preformatted
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[pre preformatted]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.preformatted">Preformatted</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ block quote
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[:sometext...]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.blockquote">Blockquote</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 1
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h1 Heading 1]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 2
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h2 Heading 2]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 3
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h3 Heading 3]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 4
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h4 Heading 4]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 5
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h5 Heading 5]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ heading 6
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[h6 Heading 6]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.headings">Heading</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ macro
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[def macro_identifier some text]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.macros">Macros</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ template
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[template[a b] [a] body [b]]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.templates">Templates</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ blurb
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[blurb advertisement or note...]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ admonition
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[warning Warning text...]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ table
+ </para>
+ </entry><entry>
+ <para>
+
 <programlisting><!--quickbook-escape-prefix-->[table Title
 [[a][b][c]]
 [[a][b][c]]
 ]
 <!--quickbook-escape-postfix--></programlisting>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.tables">Tables</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- variablelist
- </para>
- </entry><entry>
- <para>
-
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.tables">Tables</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ variablelist
+ </para>
+ </entry><entry>
+ <para>
+
 <programlisting><!--quickbook-escape-prefix-->[variablelist Title
 [[a][b]]
 [[a][b]]
 ]
 <!--quickbook-escape-postfix--></programlisting>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.variable_lists">Variable
- Lists</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- include
- </para>
- </entry><entry>
- <para>
- <literal>[include someother.qbk]</literal>
- </para>
- </entry><entry>
- <para>
- <link linkend="quickbook.syntax.block.include">Include</link>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </article>
-
\ No newline at end of file
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ include
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[include someother.qbk]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <link linkend="quickbook.syntax.block.include">Include</link>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</article>

Modified: trunk/tools/quickbook/test/templates.gold
==============================================================================
--- trunk/tools/quickbook/test/templates.gold (original)
+++ trunk/tools/quickbook/test/templates.gold 2008-05-21 00:01:31 EDT (Wed, 21 May 2008)
@@ -47,8 +47,7 @@
     </para>
     <para>
       
-<programlisting>
-<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
+<programlisting><phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
 <phrase role="special">{</phrase>
     <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> &quot;Hello, World&quot; <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
 <phrase role="special">}</phrase>


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