Subject: [Boost-commit] svn:boost r51742 - branches/release/tools/quickbook/test
From: daniel_james_at_[hidden]
Date: 2009-03-12 17:50:34
Author: danieljames
Date: 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
New Revision: 51742
URL: http://svn.boost.org/trac/boost/changeset/51742
Log:
Fix properties on some quickbook files, which wasn't merged properly before.
Properties modified:
branches/release/tools/quickbook/test/code-block-1.gold (contents, props changed)
branches/release/tools/quickbook/test/code-block-1.quickbook (contents, props changed)
branches/release/tools/quickbook/test/code-block-2.gold (contents, props changed)
branches/release/tools/quickbook/test/code-block-2.quickbook (contents, props changed)
branches/release/tools/quickbook/test/code-snippet.gold (contents, props changed)
branches/release/tools/quickbook/test/code-snippet.quickbook (contents, props changed)
branches/release/tools/quickbook/test/escape.gold (contents, props changed)
branches/release/tools/quickbook/test/escape.quickbook (contents, props changed)
branches/release/tools/quickbook/test/import.gold (contents, props changed)
branches/release/tools/quickbook/test/import.quickbook (contents, props changed)
branches/release/tools/quickbook/test/link-side-by-side.gold (contents, props changed)
branches/release/tools/quickbook/test/link-side-by-side.quickbook (contents, props changed)
branches/release/tools/quickbook/test/preformatted.gold (contents, props changed)
branches/release/tools/quickbook/test/preformatted.quickbook (contents, props changed)
branches/release/tools/quickbook/test/quickbook-manual.gold (contents, props changed)
branches/release/tools/quickbook/test/quickbook-manual.quickbook (contents, props changed)
Text files modified:
branches/release/tools/quickbook/test/code-block-1.gold | 46
branches/release/tools/quickbook/test/code-block-1.quickbook | 32
branches/release/tools/quickbook/test/code-block-2.gold | 50
branches/release/tools/quickbook/test/code-block-2.quickbook | 36
branches/release/tools/quickbook/test/code-snippet.gold | 40
branches/release/tools/quickbook/test/code-snippet.quickbook | 20
branches/release/tools/quickbook/test/escape.gold | 34
branches/release/tools/quickbook/test/escape.quickbook | 26
branches/release/tools/quickbook/test/import.gold | 72
branches/release/tools/quickbook/test/import.quickbook | 12
branches/release/tools/quickbook/test/link-side-by-side.gold | 36
branches/release/tools/quickbook/test/link-side-by-side.quickbook | 26
branches/release/tools/quickbook/test/preformatted.gold | 58
branches/release/tools/quickbook/test/preformatted.quickbook | 44
branches/release/tools/quickbook/test/quickbook-manual.gold | 7402 ++++++++++++++++++++--------------------
branches/release/tools/quickbook/test/quickbook-manual.quickbook | 3962 ++++++++++----------
16 files changed, 5948 insertions(+), 5948 deletions(-)
Modified: branches/release/tools/quickbook/test/code-block-1.gold
==============================================================================
--- branches/release/tools/quickbook/test/code-block-1.gold (original)
+++ branches/release/tools/quickbook/test/code-block-1.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,23 +1,23 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="code_block_1" name="Code Block 1" dirname="code_block_1" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Code Block 1</title>
- <section id="code_block_1.a_code_block">
- <title>A code block</title>
- <para>
- A code block with proper indentation ;-)
- </para>
-
-<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
-
-<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
- <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase>
-</programlisting>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="code_block_1" name="Code Block 1" dirname="code_block_1" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Code Block 1</title>
+ <section id="code_block_1.a_code_block">
+ <title>A code block</title>
+ <para>
+ A code block with proper indentation ;-)
+ </para>
+
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
+
+<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
+ <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+</programlisting>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/code-block-1.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/code-block-1.quickbook (original)
+++ branches/release/tools/quickbook/test/code-block-1.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,16 +1,16 @@
-[article Code Block 1
-]
-
-[section A code block]
-
-A code block with proper indentation ;-)
-
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
-
-[endsect]
+[article Code Block 1
+]
+
+[section A code block]
+
+A code block with proper indentation ;-)
+
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+
+[endsect]
Modified: branches/release/tools/quickbook/test/code-block-2.gold
==============================================================================
--- branches/release/tools/quickbook/test/code-block-2.gold (original)
+++ branches/release/tools/quickbook/test/code-block-2.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,25 +1,25 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="code_block_2" name="Code Block 2" dirname="code_block_2" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Code Block 2</title>
- <section id="code_block_2.a_code_block">
- <title>A code block</title>
- <para>
- A code block with proper indentation ;-)
- </para>
- <para>
-
-<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
-
-<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
- <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase>
-</programlisting>
- </para>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="code_block_2" name="Code Block 2" dirname="code_block_2" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Code Block 2</title>
+ <section id="code_block_2.a_code_block">
+ <title>A code block</title>
+ <para>
+ A code block with proper indentation ;-)
+ </para>
+ <para>
+
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
+
+<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
+ <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+</programlisting>
+ </para>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/code-block-2.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/code-block-2.quickbook (original)
+++ branches/release/tools/quickbook/test/code-block-2.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,18 +1,18 @@
-[article Code Block 2
-]
-
-[section A code block]
-
-A code block with proper indentation ;-)
-
-``
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
-``
-
-[endsect]
+[article Code Block 2
+]
+
+[section A code block]
+
+A code block with proper indentation ;-)
+
+``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+``
+
+[endsect]
Modified: branches/release/tools/quickbook/test/code-snippet.gold
==============================================================================
--- branches/release/tools/quickbook/test/code-snippet.gold (original)
+++ branches/release/tools/quickbook/test/code-snippet.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,20 +1,20 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="code_snippets" name="Code Snippets" dirname="code_snippets" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Code Snippets</title>
- <section id="code_snippets.a_code_snippet">
- <title>A code snippet</title>
- <para>
- Code snippets inlined in text, as in <code><phrase role="keyword">namespace</phrase>
- <phrase role="identifier">quickbook</phrase> <phrase role="special">{</phrase>
- <phrase role="keyword">static</phrase> <phrase role="keyword">const</phrase>
- <phrase role="keyword">int</phrase> <phrase role="identifier">value</phrase>
- <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
- <phrase role="special">}</phrase></code>, should be properly formatted and
- not glued to the surrounding text.
- </para>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="code_snippets" name="Code Snippets" dirname="code_snippets" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Code Snippets</title>
+ <section id="code_snippets.a_code_snippet">
+ <title>A code snippet</title>
+ <para>
+ Code snippets inlined in text, as in <code><phrase role="keyword">namespace</phrase>
+ <phrase role="identifier">quickbook</phrase> <phrase role="special">{</phrase>
+ <phrase role="keyword">static</phrase> <phrase role="keyword">const</phrase>
+ <phrase role="keyword">int</phrase> <phrase role="identifier">value</phrase>
+ <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
+ <phrase role="special">}</phrase></code>, should be properly formatted and
+ not glued to the surrounding text.
+ </para>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/code-snippet.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/code-snippet.quickbook (original)
+++ branches/release/tools/quickbook/test/code-snippet.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,10 +1,10 @@
-[article Code Snippets
-]
-
-[section A code snippet]
-
-Code snippets inlined in text, as in `namespace quickbook { static const int
-value = 0; }`, should be properly formatted and not glued to the surrounding
-text.
-
-[endsect]
+[article Code Snippets
+]
+
+[section A code snippet]
+
+Code snippets inlined in text, as in `namespace quickbook { static const int
+value = 0; }`, should be properly formatted and not glued to the surrounding
+text.
+
+[endsect]
Modified: branches/release/tools/quickbook/test/escape.gold
==============================================================================
--- branches/release/tools/quickbook/test/escape.gold (original)
+++ branches/release/tools/quickbook/test/escape.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,17 +1,17 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="escape" name="Escape" dirname="escape" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Escape</title>
- <section id="escape.escape">
- <title>Escape</title>
- <para>
- <emphasis>Da do do do. Da da da da. That's all I have to say to you.</emphasis>
- </para>
- <para>
- This letter α should have a space either side of it.
- </para>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="escape" name="Escape" dirname="escape" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Escape</title>
+ <section id="escape.escape">
+ <title>Escape</title>
+ <para>
+ <emphasis>Da do do do. Da da da da. That's all I have to say to you.</emphasis>
+ </para>
+ <para>
+ This letter α should have a space either side of it.
+ </para>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/escape.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/escape.quickbook (original)
+++ branches/release/tools/quickbook/test/escape.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,13 +1,13 @@
-[article Escape
-]
-
-[section Escape]
-
-'''
-<emphasis>Da do do do. Da da da da. That's all I have to say to you.</emphasis>
-'''
-
-This letter '''α''' should have a space either side of it.
-
-[endsect]
-
+[article Escape
+]
+
+[section Escape]
+
+'''
+<emphasis>Da do do do. Da da da da. That's all I have to say to you.</emphasis>
+'''
+
+This letter '''α''' should have a space either side of it.
+
+[endsect]
+
Modified: branches/release/tools/quickbook/test/import.gold
==============================================================================
--- branches/release/tools/quickbook/test/import.gold (original)
+++ branches/release/tools/quickbook/test/import.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,36 +1,36 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="import" name="Import" dirname="import" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Import</title>
- <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">"foo"</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase>
-</programlisting>
- </para>
- </para>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="import" name="Import" dirname="import" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Import</title>
+ <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">"foo"</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+</programlisting>
+ </para>
+ </para>
+</article>
Modified: branches/release/tools/quickbook/test/import.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/import.quickbook (original)
+++ branches/release/tools/quickbook/test/import.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,6 +1,6 @@
-[article Import]
-
-[import stub.cpp]
-
-[foo]
-
+[article Import]
+
+[import stub.cpp]
+
+[foo]
+
Modified: branches/release/tools/quickbook/test/link-side-by-side.gold
==============================================================================
--- branches/release/tools/quickbook/test/link-side-by-side.gold (original)
+++ branches/release/tools/quickbook/test/link-side-by-side.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,18 +1,18 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="side_by_side_links" name="Side-by-side links" dirname="side_by_side_links"
-last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $" xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Side-by-side links</title>
- <section id="side_by_side_links.side_by_side_links">
- <title>Side-by-side links</title>
- <para>
- <link linkend="x">x</link> and <link linkend="y">y</link> are two distinct
- links, which should be separated by whitespace when they appear together as
- in <link linkend="x">x</link> <link linkend="y">y</link>. Also in <link linkend="x">x</link>
- <link linkend="y">y</link>, and in <link linkend="x">x</link> <link linkend="y">y</link>
- as well.
- </para>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="side_by_side_links" name="Side-by-side links" dirname="side_by_side_links"
+last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Side-by-side links</title>
+ <section id="side_by_side_links.side_by_side_links">
+ <title>Side-by-side links</title>
+ <para>
+ <link linkend="x">x</link> and <link linkend="y">y</link> are two distinct
+ links, which should be separated by whitespace when they appear together as
+ in <link linkend="x">x</link> <link linkend="y">y</link>. Also in <link linkend="x">x</link>
+ <link linkend="y">y</link>, and in <link linkend="x">x</link> <link linkend="y">y</link>
+ as well.
+ </para>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/link-side-by-side.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/link-side-by-side.quickbook (original)
+++ branches/release/tools/quickbook/test/link-side-by-side.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,13 +1,13 @@
-[article Side-by-side links
-]
-
-[section Side-by-side links]
-
-[link x] and [link y] are two distinct links, which should be separated by
-whitespace when they appear together as in [link x] [link y]. Also in [link x]
-[link y], and in
-[link x]
-[link y]
-as well.
-
-[endsect]
+[article Side-by-side links
+]
+
+[section Side-by-side links]
+
+[link x] and [link y] are two distinct links, which should be separated by
+whitespace when they appear together as in [link x] [link y]. Also in [link x]
+[link y], and in
+[link x]
+[link y]
+as well.
+
+[endsect]
Modified: branches/release/tools/quickbook/test/preformatted.gold
==============================================================================
--- branches/release/tools/quickbook/test/preformatted.gold (original)
+++ branches/release/tools/quickbook/test/preformatted.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,29 +1,29 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="preformatted" name="Preformatted" dirname="preformatted" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- </articleinfo>
- <title>Preformatted</title>
- <section id="preformatted.preformatted">
- <title>Preformatted</title>
- <para>
- Here's the ubiquitous <emphasis>Hello World</emphasis> program in C++.
- </para>
-
-<programlisting>#include <iostream>
-
-int main()
-{
- std::cout << "Hello, World!" << std::endl;
- return 0;
-}
-</programlisting>
- <para>
- The code should appear as a single block of code in a monospaced font and with
- no syntax highlighting. The fifth and sixth lines should appear indented to
- the right, aligning under <code><phrase role="identifier">main</phrase></code>,
- on line 3.
- </para>
- </section>
-</article>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="preformatted" name="Preformatted" dirname="preformatted" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ </articleinfo>
+ <title>Preformatted</title>
+ <section id="preformatted.preformatted">
+ <title>Preformatted</title>
+ <para>
+ Here's the ubiquitous <emphasis>Hello World</emphasis> program in C++.
+ </para>
+
+<programlisting>#include <iostream>
+
+int main()
+{
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+}
+</programlisting>
+ <para>
+ The code should appear as a single block of code in a monospaced font and with
+ no syntax highlighting. The fifth and sixth lines should appear indented to
+ the right, aligning under <code><phrase role="identifier">main</phrase></code>,
+ on line 3.
+ </para>
+ </section>
+</article>
Modified: branches/release/tools/quickbook/test/preformatted.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/preformatted.quickbook (original)
+++ branches/release/tools/quickbook/test/preformatted.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,22 +1,22 @@
-[article Preformatted
-]
-
-[section Preformatted]
-
-Here's the ubiquitous /Hello World/ program in C++.
-
-[pre
-#include <iostream>
-
-int main()
-{
- std::cout << "Hello, World!" << std::endl;
- return 0;
-}
-]
-
-The code should appear as a single block of code in a monospaced font and with
-no syntax highlighting. The fifth and sixth lines should appear indented to the
-right, aligning under `main`, on line 3.
-
-[endsect]
+[article Preformatted
+]
+
+[section Preformatted]
+
+Here's the ubiquitous /Hello World/ program in C++.
+
+[pre
+#include <iostream>
+
+int main()
+{
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+}
+]
+
+The code should appear as a single block of code in a monospaced font and with
+no syntax highlighting. The fifth and sixth lines should appear indented to the
+right, aligning under `main`, on line 3.
+
+[endsect]
Modified: branches/release/tools/quickbook/test/quickbook-manual.gold
==============================================================================
--- branches/release/tools/quickbook/test/quickbook-manual.gold (original)
+++ branches/release/tools/quickbook/test/quickbook-manual.gold 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,3701 +1,3701 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-<article id="quickbook" name="Quickbook" dirname="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
- xmlns:xi="http://www.w3.org/2001/XInclude">
- <articleinfo>
- <authorgroup>
- <author>
- <firstname>Joel</firstname> <surname>de Guzman</surname>
- </author>
- <author>
- <firstname>Eric</firstname> <surname>Niebler</surname>
- </author>
- </authorgroup>
- <copyright>
- <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman,
- Eric Niebler</holder>
- </copyright>
- <legalnotice>
- <para>
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)
- </para>
- </legalnotice>
- <articlepurpose>
- <emphasis>WikiWiki</emphasis> style documentation tool
- </articlepurpose>
- </articleinfo>
- <title>Quickbook 1.4</title>
- <section id="quickbook.intro">
- <title><link linkend="quickbook.intro"> Introduction</link></title>
- <blockquote>
- <para>
- <para>
- <emphasis role="bold"><emphasis><quote>Why program by hand in five days
- what you can spend five years of your life automating?</quote></emphasis></emphasis>
- </para>
- <para>
- -- Terrence Parr, author ANTLR/PCCTS
- </para>
- </para>
- </blockquote>
- <para>
- Well, QuickBook started as a weekend hack. It was originally intended to be
- a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
- What is it? What you are viewing now, this documentation, is autogenerated
- by QuickBook. These files were generated from one master:
- </para>
- <blockquote>
- <para>
- <para>
- <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
- </para>
- </para>
- </blockquote>
- <para>
- Originally named QuickDoc, this funky tool that never dies evolved into a funkier
- tool thanks to Eric Niebler who resurrected the project making it generate
- <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
- instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
- documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
- an SGML or XML based format for describing documentation.
- </para>
- <para>
- QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
- using simple rules and markup for simple formatting tasks. QuickBook extends
- the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
- files. A single QuickBook document can generate a fully linked set of nice
- HTML and PostScript/PDF documents complete with images and syntax- colorized
- source code.
- </para>
- <para>
- Features include:
- </para>
- <itemizedlist>
- <listitem>
- generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
- xml, to generate HTML, PostScript and PDF
- </listitem>
- <listitem>
- simple markup to link to Doxygen-generated entities
- </listitem>
- <listitem>
- macro system for simple text substitution
- </listitem>
- <listitem>
- simple markup for italics, bold, preformatted, blurbs, code samples, tables,
- URLs, anchors, images, etc.
- </listitem>
- <listitem>
- automatic syntax coloring of code samples
- </listitem>
- <listitem>
- CSS support
- </listitem>
- </itemizedlist>
- </section>
- <section id="quickbook.change_log">
- <title><link linkend="quickbook.change_log"> Change Log</link></title> <anchor
- id="quickbook.change_log.version_1_3"/>
- <bridgehead renderas="sect3">
- <link linkend="quickbook.change_log.version_1_3">Version 1.3</link>
- </bridgehead>
- <itemizedlist>
- <listitem>
- Quickbook file inclusion [include].
- </listitem>
- <listitem>
- Better xml output (pretty layout). Check out the generated XML.
- </listitem>
- <listitem>
- Regression testing facility: to make sure your document will always be compatible
- (full backward compatibility) regardless of changes to QuickBook.
- </listitem>
- <listitem>
- Code cleanup and refactoring.
- </listitem>
- <listitem>
- Allow phrase markup in the doc-info.
- </listitem>
- <listitem>
- Preformatted code blocks via ``code`` (double ticks) allows code in tables
- and lists, for example.
- </listitem>
- <listitem>
- Quickbook versioning; allows full backward compatibility. You have to add
- [quickbook 1.3] to the doc-info header to enable the new features. Without
- this, QuickBook will assume that the document is a pre-1.3 document.
- </listitem>
- <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>
-<phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
-<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
- </listitem>
- <listitem>
- Fully qualified section and headers. Subsection names are concatenated to
- the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
- role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
- role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
- role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
- </listitem>
- <listitem>
- Better &nbsp; and whitespace handling in code snippets.
- </listitem>
- <listitem>
- [xinclude] fixes up the relative path to the target XML file when input_directory
- is not the same as the output_directory.
- </listitem>
- <listitem>
- Allow untitled tables.
- </listitem>
- <listitem>
- Allow phrase markups in section titles.
- </listitem>
- <listitem>
- Allow escaping back to QuickBook from code, code blocks and inline code.
- </listitem>
- <listitem>
- Footnotes, with the [footnote This is the footnote] syntax.
- </listitem>
- <listitem>
- Post-processor bug fix for escaped XML code that it does not recognize.
- </listitem>
- <listitem>
- Replaceable, with the [~replacement] syntax.
- </listitem>
- <listitem>
- Generic Headers
- </listitem>
- <listitem>
- Code changes to allow full recursion (i.e. Collectors and push/pop functions)
- </listitem>
- <listitem>
- Various code cleanup/maintenance
- </listitem>
- <listitem>
- Templates!
- </listitem>
- <listitem>
- [conceptref] for referencing BoostBook <concept> entities.
- </listitem>
- <listitem>
- Allow escape of spaces. The escaped space is removed from the output. Syntax:
- <code><phrase role="special">\</phrase> </code>.
- </listitem>
- <listitem>
- Nested comments are now allowed.
- </listitem>
- <listitem>
- Quickbook blocks can nest inside comments.
- </listitem>
- <listitem>
- <link linkend="quickbook.syntax.block.import">Import</link> facility.
- </listitem>
- <listitem>
- Callouts on imported code
- </listitem>
- <listitem>
- Simple markups can now span a whole block.
- </listitem>
- <listitem>
- <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.
- </listitem>
- <listitem>
- <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.
- </listitem>
- </itemizedlist>
- </section>
- <section id="quickbook.syntax">
- <title><link linkend="quickbook.syntax"> Syntax Summary</link></title>
- <para>
- A QuickBook document is composed of one or more blocks. An example of a block
- is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
- Blocks, except code snippets which have their own grammar (C++ or Python),
- are composed of one or more phrases. A phrase can be a simple contiguous run
- of characters. Phrases can have special mark-ups. Marked up phrases can recursively
- contain other phrases, but cannot contain blocks. A terminal is a self contained
- block-level or phrase-level element that does not nest anything.
- </para>
- <para>
- Blocks, in general, are delimited by two end-of-lines (the block terminator).
- Phrases in each block cannot contain a block terminator. This way, syntax errors
- such as un-matched closing brackets do not go haywire and corrupt anything
- past a single block.
- </para>
- <section id="quickbook.syntax.comments">
- <title><link linkend="quickbook.syntax.comments">Comments</link></title>
- <para>
- Can be placed anywhere.
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix-->
-</programlisting>
-
-<programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix-->
-</programlisting>
-
-<programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix-->
-</programlisting>
- </section>
- <section id="quickbook.syntax.phrase">
- <title><link linkend="quickbook.syntax.phrase"> Phrase Level Elements</link></title>
- <section id="quickbook.syntax.phrase.font_styles">
- <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title>
-
-<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
- role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
- role="strikethrough">strikethrough</emphasis>
- </para>
- <para>
- Like all non-terminal phrase level elements, this can of course be nested:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
- </para>
- </section>
- <section id="quickbook.syntax.phrase.replaceable">
- <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title>
- <para>
- When you want content that may or must be replaced by the user, use the
- syntax:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[~replacement]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- This will generate:
- </para>
- <para>
- <replaceable>
- replacement
- </replaceable>
- </para>
- </section>
- <section id="quickbook.syntax.phrase.quotations">
- <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title>
-
-<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <quote>A question that sometimes drives me hazy: am I or are the others
- crazy?</quote>--Einstein
- </para>
- <para>
- Note the proper left and right quote marks. Also, while you can simply
- use ordinary quote marks like "quoted", our quotation, above,
- will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
- </para>
- <para>
- Like all phrase elements, quotations may be nested. Example:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's
-the true business precept.]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <quote>Here's the rule for bargains: <quote>Do other men, for they would
- do you.</quote> That's the true business precept.</quote>
- </para>
- </section>
- <section id="quickbook.syntax.phrase.simple_formatting">
- <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title>
- <para>
- Simple markup for formatting text, common in many applications, is now
- supported:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype=
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
- role="underline">underline</emphasis>, <literal>teletype</literal>
- </para>
- <para>
- Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
- are much stricter
- <footnote>
- <para>
- Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>,
- for sharing these samples and teaching me these obscure formatting
- rules. I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>,
- being more or less a formal EBNF parser, can handle the context sensitivity
- and ambiguity.
- </para>
- </footnote>
- .
- </para>
- <itemizedlist>
- <listitem>
- Simple markups cannot nest. You can combine a simple markup with a nestable
- markup.
- </listitem>
- <listitem>
- Simple markups cannot contain any other form of quickbook markup.
- </listitem>
- <listitem>
- A non-space character must follow the leading markup
- </listitem>
- <listitem>
- A non-space character must precede the trailing markup
- </listitem>
- <listitem>
- A space or a punctuation must follow the trailing markup
- </listitem>
- <listitem>
- If the matching markup cannot be found within a block, the formatting
- will not be applied. This is to ensure that un-matched formatting markups,
- which can be a common mistake, does not corrupt anything past a single
- block. We do not want the rest of the document to be rendered bold just
- because we forgot a trailing '*'. A single block is terminated by two
- end of lines or the close bracket: ']'.
- </listitem>
- <listitem>
- A line starting with the star will be interpreted as an unordered list.
- See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
- lists</link>.
- </listitem>
- </itemizedlist>
- <table frame="all"> <title>More Formatting Samples</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>
- Markup
- </para>
- </entry><entry>
- <para>
- Result
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- <literal>*Bold*</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">Bold</emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*Is bold*</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">Is bold</emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>* Not bold* *Not bold * * Not bold *</literal>
- </para>
- </entry><entry>
- <para>
- * Not bold* *Not bold * * Not bold *
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>This*Isn't*Bold (no bold)</literal>
- </para>
- </entry><entry>
- <para>
- This*Isn't*Bold (no bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>(*Bold Inside*) (parenthesis not bold)</literal>
- </para>
- </entry><entry>
- <para>
- (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*(Bold Outside)* (parenthesis bold)</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>3*4*5 = 60 (no bold)</literal>
- </para>
- </entry><entry>
- <para>
- 3*4*5 = 60 (no bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>3 * 4 * 5 = 60 (no bold)</literal>
- </para>
- </entry><entry>
- <para>
- 3 * 4 * 5 = 60 (no bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>3 *4* 5 = 60 (4 is bold)</literal>
- </para>
- </entry><entry>
- <para>
- 3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*This is bold* this is not *but this is*</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">This is bold</emphasis> this is not <emphasis
- role="bold">but this is</emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*This is bold*.</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">This is bold</emphasis>.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*B*. (bold B)</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">B</emphasis>. (bold B)
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>['*Bold-Italic*]</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>*side-by*/-side/</literal>
- </para>
- </entry><entry>
- <para>
- <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- As mentioned, simple markups cannot go past a single block. The text from
- "have" to "full" in the following paragraph will be
- rendered as bold:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!*
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir,
- yes sir, three bags full!</emphasis> One for the master, one for the dame,
- And one for the little boy who lives down the lane.
- </para>
- <para>
- But in the following paragraph, bold is not applied:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!
- One for the master, one for the dame, And one for the little boy who lives
- down the lane.
- </para>
- </section>
- <section id="quickbook.syntax.phrase.inline_code">
- <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></title>
- <para>
- Inlining code in paragraphs is quite common when writing C++ documentation.
- We provide a very simple markup for this. For example, this:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it.
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- This text has inlined code <code><phrase role="keyword">int</phrase> <phrase
- role="identifier">main</phrase><phrase role="special">()</phrase> <phrase
- role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase
- role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code>
- in it. The code will be syntax highlighted.
- </para>
- <note>
- <para>
- We simply enclose the code with the tick: <literal>"`"</literal>, not the
- single quote: <code><phrase role="string">"'"</phrase></code>.
- Note too that <literal>`some code`</literal> is preferred over <literal>[^some code]</literal>.
- </para>
- </note>
- </section>
- <section id="quickbook.syntax.phrase.code_blocks">
- <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></title>
- <para>
- Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>).
- However, such a simple syntax cannot be used as phrase elements in lists
- (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
- lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
- lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>),
- etc. Inline code (see above) can. The problem is, inline code does not
- allow formatting with newlines, spaces, and tabs. These are lost.
- </para>
- <para>
- We provide a phrase level markup that is a mix between the two. By using
- the double-tick, instead of the single-tick, we are telling QuickBook to
- use preformatted blocks of code. Example:
- </para>
-
-<programlisting>``
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
-``
-</programlisting>
- <para>
- will generate:
- </para>
- <para>
-
-<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
-
-<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
- <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase>
-</programlisting>
- </para>
- </section>
- <section id="quickbook.syntax.phrase.source_mode">
- <title><link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></title>
- <para>
- If a document contains more than one type of source code then the source
- mode may be changed dynamically as the document is processed. All QuickBook
- documents are initially in C++ mode by default, though an alternative initial
- value may be set in the <link linkend="quickbook.syntax.block.document">Document</link>
- section.
- </para>
- <para>
- To change the source mode, use the <literal>[source-mode]</literal> markup,
- where <literal>source-mode</literal> is one of the supported modes. For
- example, this:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->Python's [python] `import` is rather like C++'s [c++] `#include`. A
-C++ comment `// looks like this` whereas a Python comment [python]
-`# looks like this`.
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <para>
- Python's <code><phrase role="keyword">import</phrase></code> is rather
- like C++'s <code><phrase role="preprocessor">#include</phrase></code>.
- A C++ comment <code><phrase role="comment">// looks like this</phrase></code>
- whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>.
- </para>
- <table frame="all"> <title>Supported Source Modes</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>
- Mode
- </para>
- </entry><entry>
- <para>
- Source Mode Markup
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- C++
- </para>
- </entry><entry>
- <para>
- <literal>[c++]</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- Python
- </para>
- </entry><entry>
- <para>
- <literal>[python]</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <note>
- <para>
- The source mode strings are lowercase.
- </para>
- </note>
- </section>
- <section id="quickbook.syntax.phrase.line_break">
- <title><link linkend="quickbook.syntax.phrase.line_break">line-break</link></title>
-
-<programlisting><!--quickbook-escape-prefix-->[br]
-<!--quickbook-escape-postfix--></programlisting>
- <warning>
- <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>
-
-<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
-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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- This gets converted into <literal><link linkend="xml.refentry">The
- link text</link></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><link linkend="xml.refentry">xml.refentry</link></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]
-[enumref fully::qualified::enum_name The link text]
-[macroref MACRO_NAME The link text]
-[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>
-
-<programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- would have "boost::bar::baz" 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>
-
-<programlisting>'''
-<emphasis role="bold">This is direct XML markup</emphasis>
-'''
-</programlisting>
- <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>
- </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>
- 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>
-
-<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>
-
-<programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate this
- <footnote>
- <para>
- A sample footnote
- </para>
- </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>
-<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>
- </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]
- [id the_document_name]
- [dirname the_document_dir]
- [copyright 2000 2002 2003 Joe Blow, Jane Doe]
- [purpose The document's reason for being]
- [category The document's category]
- [authors [Blow, Joe], [Doe, Jane]]
- [license The document's license]
- [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>
-
-<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, "The Section Title"
- 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: "The Section Title" will be
- normalized to "the_section_title".
- </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>
-
-<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>
-<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
- # Three.a
- # Three.b
- # Three.c
-# Four
- # Four.a
- # Four.a.i
- # Four.a.ii
-# Five
-</programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
- <listitem>
- One
- </listitem>
- <listitem>
- Two
- </listitem>
- <listitem>
- Three
- <orderedlist>
- <listitem>
- Three.a
- </listitem>
- <listitem>
- Three.b
- </listitem>
- <listitem>
- Three.c
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- Fourth
- <orderedlist>
- <listitem>
- Four.a
- <orderedlist>
- <listitem>
- Four.a.i
- </listitem>
- <listitem>
- Four.a.ii
- </listitem>
- </orderedlist>
- </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>
-
-<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.
- 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 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>
-<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>
-
-<programlisting><!--quickbook-escape-prefix--># One
-# Two
-# Three
- * Three.a
- * Three.b
- * Three.c
-# Four
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
- <listitem>
- One
- </listitem>
- <listitem>
- Two
- </listitem>
- <listitem>
- Three
- <itemizedlist>
- <listitem>
- Three.a
- </listitem>
- <listitem>
- Three.b
- </listitem>
- <listitem>
- Three.c
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- Four
- </listitem>
- </orderedlist>
- <para>
- And...
- </para>
-
-<programlisting><!--quickbook-escape-prefix--># 1
- * 1.a
- # 1.a.1
- # 1.a.2
- * 1.b
-# 2
- * 2.a
- * 2.b
- # 2.b.1
- # 2.b.2
- * 2.b.2.a
- * 2.b.2.b
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- will generate:
- </para>
- <orderedlist>
- <listitem>
- 1
- <itemizedlist>
- <listitem>
- 1.a
- <orderedlist>
- <listitem>
- 1.a.1
- </listitem>
- <listitem>
- 1.a.2
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- 1.b
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- 2
- <itemizedlist>
- <listitem>
- 2.a
- </listitem>
- <listitem>
- 2.b
- <orderedlist>
- <listitem>
- 2.b.1
- </listitem>
- <listitem>
- 2.b.2
- <itemizedlist>
- <listitem>
- 2.b.2.a
- </listitem>
- <listitem>
- 2.b.2.b
- </listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
- </listitem>
- </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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
-
-<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
-<phrase role="special">{</phrase>
- <phrase role="comment">// Sample code
-</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase>
- <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>
-
-<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">'''"Cooks" 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>
-
-<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>
-</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): "``"
- and "``". 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>
-<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>
-
-<programlisting><!--quickbook-escape-prefix-->[pre
-
- Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
-]
-<!--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>
-
-<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
-
- 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>
-
-<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>
-
-<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>
- 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]
-[h4 Heading 4]
-[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="section_id.normalized_header_text"</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>
-
-<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>
-
-<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>
-
-<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>
-
-<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&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&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>
- 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).
- </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>
-
-<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ]
-<!--quickbook-escape-postfix--></programlisting>
- <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>
-
-<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>
-
-<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>".."</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[]'''&#945;''']
-[template beta[]'''&#946;''']
-<!--quickbook-escape-postfix--></programlisting>
- <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">αβ</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>
-
-<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 "Aristotle...". This space will be part
- of the template body. If that space is unwanted, use empty brackets or
- use the space escape: "<code><phrase role="special">\</phrase> </code>".
- Example:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[template tag\ _tag]
-<!--quickbook-escape-postfix--></programlisting>
- <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>".."</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>
- "w x y z" is initially treated as a single argument because we
- didn't supply any <literal>".."</literal> separators. However,
- since <literal>simple</literal> expects 4 arguments, "w x y z"
- is broken down iteratively (applying the logic above) until we have "w",
- "x", "y" and "z".
- </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: "w", "x", "y" and "z
- trail".
- </para>
- <para>
- It should be obvious now that for simple arguments with no spaces, we can
- get by without separating the arguments with <literal>".."</literal>
- separators. It is possible to combine <literal>".."</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--><hey><!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix--></hey><!--quickbook-escape-prefix-->]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- Now, expanding this:
- </para>
-
-<programlisting><!--quickbook-escape-prefix-->[!baz]
-<!--quickbook-escape-postfix--></programlisting>
- <para>
- We will have:
- </para>
-
-<programlisting><hey>baz</hey>
-</programlisting>
- </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
- implemented using template meta-programming techniques. Expression templates
- allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
- 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>
-
-<programlisting><!--quickbook-escape-prefix-->[table A Simple Table
- [[Heading 1] [Heading 2] [Heading 3]]
- [[R0-C0] [R0-C1] [R0-C2]]
- [[R1-C0] [R1-C1] [R1-C2]]
- [[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>
- 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><thead>...</thead></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]]
- [
- [Row 0, Col 0: a small cell]
- [
- Row 0, Col 1: a big fat cell with paragraphs
-
- Boost provides free peer-reviewed portable C++ source libraries.
-
- 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.
- ]
- ]
- [
- [Row 1, Col 0: a small cell]
- [Row 1, Col 1: a small cell]
- ]
-]
-<!--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>
- Row 1, Col 0: a small cell
- </para>
- </entry><entry>
- <para>
- 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]]
- [
- [My first program]
- [<!--quickbook-escape-postfix-->``
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
- ``<!--quickbook-escape-prefix-->]
- ]
-]
-<!--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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
-
-<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
- <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>
-
-<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 "columns" are allowed. The first column contains the terms,
- and the second column contains the definitions. Those familiar with HTML
- will recognize this as a "definition list".
- </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 ("someother", 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 "Intro",
- the named anchor for that section will be "someid.intro", 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>
-
-<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>
-
-<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">"foo"</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">"bar"</phrase><phrase role="special">;</phrase>
-<phrase role="special">}</phrase></programlisting>
- </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
-</phrase></programlisting>
- <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">/*< some [*quickbook] markup here >*/</phrase>
-</programlisting>
- <para>
- will be regarded as callouts. These will be collected, numbered and rendered
- as a "callout bug" (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">"foo-bar"</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>
- 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>
- <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&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">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</phrase>
- <phrase role="special">;</phrase>
-
-<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase>
- <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</phrase>
- <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</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>
- <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</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>
-</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>
-
-<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>
- <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">schema</phrase><phrase role="special">/</phrase><phrase role="identifier">dtd</phrase><phrase role="special">/</phrase><phrase role="number">4.2</phrase>
- <phrase role="special">;</phrase>
-
-<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>
- <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>
- <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>
-
-<programlisting><!--quickbook-escape-prefix-->qbk=*.qbk
-lexer.*.qbk=props
-use.tabs.$(qbk)=0
-tab.size.$(qbk)=4
-indent.size.$(qbk)=4
-style.props.32=$(font.base)
-comment.stream.start.props=[/
-comment.stream.end.props=]
-comment.box.start.props=[/
-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>
-
-<programlisting>using quickbook ;
-
-xml my_doc : my_doc.qbk ;
-
-boostbook standalone
- :
- my_doc
- :
- <xsl:param>boost.image.src<literal>images/my_project_logo.png
- <xsl:param>boost.image.alt</literal>"\"My Project\""
- <xsl:param>boost.image.w=100
- <xsl:param>boost.image.h=50
- <xsl:param>nav.layout=none
- ;
-</programlisting>
- </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>
- <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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article id="quickbook" name="Quickbook" dirname="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+ <articleinfo>
+ <authorgroup>
+ <author>
+ <firstname>Joel</firstname> <surname>de Guzman</surname>
+ </author>
+ <author>
+ <firstname>Eric</firstname> <surname>Niebler</surname>
+ </author>
+ </authorgroup>
+ <copyright>
+ <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman,
+ Eric Niebler</holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)
+ </para>
+ </legalnotice>
+ <articlepurpose>
+ <emphasis>WikiWiki</emphasis> style documentation tool
+ </articlepurpose>
+ </articleinfo>
+ <title>Quickbook 1.4</title>
+ <section id="quickbook.intro">
+ <title><link linkend="quickbook.intro"> Introduction</link></title>
+ <blockquote>
+ <para>
+ <para>
+ <emphasis role="bold"><emphasis><quote>Why program by hand in five days
+ what you can spend five years of your life automating?</quote></emphasis></emphasis>
+ </para>
+ <para>
+ -- Terrence Parr, author ANTLR/PCCTS
+ </para>
+ </para>
+ </blockquote>
+ <para>
+ Well, QuickBook started as a weekend hack. It was originally intended to be
+ a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
+ What is it? What you are viewing now, this documentation, is autogenerated
+ by QuickBook. These files were generated from one master:
+ </para>
+ <blockquote>
+ <para>
+ <para>
+ <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
+ </para>
+ </para>
+ </blockquote>
+ <para>
+ Originally named QuickDoc, this funky tool that never dies evolved into a funkier
+ tool thanks to Eric Niebler who resurrected the project making it generate
+ <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
+ instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
+ documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
+ an SGML or XML based format for describing documentation.
+ </para>
+ <para>
+ QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
+ using simple rules and markup for simple formatting tasks. QuickBook extends
+ the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
+ files. A single QuickBook document can generate a fully linked set of nice
+ HTML and PostScript/PDF documents complete with images and syntax- colorized
+ source code.
+ </para>
+ <para>
+ Features include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
+ xml, to generate HTML, PostScript and PDF
+ </listitem>
+ <listitem>
+ simple markup to link to Doxygen-generated entities
+ </listitem>
+ <listitem>
+ macro system for simple text substitution
+ </listitem>
+ <listitem>
+ simple markup for italics, bold, preformatted, blurbs, code samples, tables,
+ URLs, anchors, images, etc.
+ </listitem>
+ <listitem>
+ automatic syntax coloring of code samples
+ </listitem>
+ <listitem>
+ CSS support
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="quickbook.change_log">
+ <title><link linkend="quickbook.change_log"> Change Log</link></title> <anchor
+ id="quickbook.change_log.version_1_3"/>
+ <bridgehead renderas="sect3">
+ <link linkend="quickbook.change_log.version_1_3">Version 1.3</link>
+ </bridgehead>
+ <itemizedlist>
+ <listitem>
+ Quickbook file inclusion [include].
+ </listitem>
+ <listitem>
+ Better xml output (pretty layout). Check out the generated XML.
+ </listitem>
+ <listitem>
+ Regression testing facility: to make sure your document will always be compatible
+ (full backward compatibility) regardless of changes to QuickBook.
+ </listitem>
+ <listitem>
+ Code cleanup and refactoring.
+ </listitem>
+ <listitem>
+ Allow phrase markup in the doc-info.
+ </listitem>
+ <listitem>
+ Preformatted code blocks via ``code`` (double ticks) allows code in tables
+ and lists, for example.
+ </listitem>
+ <listitem>
+ Quickbook versioning; allows full backward compatibility. You have to add
+ [quickbook 1.3] to the doc-info header to enable the new features. Without
+ this, QuickBook will assume that the document is a pre-1.3 document.
+ </listitem>
+ <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>
+<phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
+<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
+ </listitem>
+ <listitem>
+ Fully qualified section and headers. Subsection names are concatenated to
+ the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
+ role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
+ </listitem>
+ <listitem>
+ Better &nbsp; and whitespace handling in code snippets.
+ </listitem>
+ <listitem>
+ [xinclude] fixes up the relative path to the target XML file when input_directory
+ is not the same as the output_directory.
+ </listitem>
+ <listitem>
+ Allow untitled tables.
+ </listitem>
+ <listitem>
+ Allow phrase markups in section titles.
+ </listitem>
+ <listitem>
+ Allow escaping back to QuickBook from code, code blocks and inline code.
+ </listitem>
+ <listitem>
+ Footnotes, with the [footnote This is the footnote] syntax.
+ </listitem>
+ <listitem>
+ Post-processor bug fix for escaped XML code that it does not recognize.
+ </listitem>
+ <listitem>
+ Replaceable, with the [~replacement] syntax.
+ </listitem>
+ <listitem>
+ Generic Headers
+ </listitem>
+ <listitem>
+ Code changes to allow full recursion (i.e. Collectors and push/pop functions)
+ </listitem>
+ <listitem>
+ Various code cleanup/maintenance
+ </listitem>
+ <listitem>
+ Templates!
+ </listitem>
+ <listitem>
+ [conceptref] for referencing BoostBook <concept> entities.
+ </listitem>
+ <listitem>
+ Allow escape of spaces. The escaped space is removed from the output. Syntax:
+ <code><phrase role="special">\</phrase> </code>.
+ </listitem>
+ <listitem>
+ Nested comments are now allowed.
+ </listitem>
+ <listitem>
+ Quickbook blocks can nest inside comments.
+ </listitem>
+ <listitem>
+ <link linkend="quickbook.syntax.block.import">Import</link> facility.
+ </listitem>
+ <listitem>
+ Callouts on imported code
+ </listitem>
+ <listitem>
+ Simple markups can now span a whole block.
+ </listitem>
+ <listitem>
+ <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.
+ </listitem>
+ <listitem>
+ <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.
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="quickbook.syntax">
+ <title><link linkend="quickbook.syntax"> Syntax Summary</link></title>
+ <para>
+ A QuickBook document is composed of one or more blocks. An example of a block
+ is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
+ Blocks, except code snippets which have their own grammar (C++ or Python),
+ are composed of one or more phrases. A phrase can be a simple contiguous run
+ of characters. Phrases can have special mark-ups. Marked up phrases can recursively
+ contain other phrases, but cannot contain blocks. A terminal is a self contained
+ block-level or phrase-level element that does not nest anything.
+ </para>
+ <para>
+ Blocks, in general, are delimited by two end-of-lines (the block terminator).
+ Phrases in each block cannot contain a block terminator. This way, syntax errors
+ such as un-matched closing brackets do not go haywire and corrupt anything
+ past a single block.
+ </para>
+ <section id="quickbook.syntax.comments">
+ <title><link linkend="quickbook.syntax.comments">Comments</link></title>
+ <para>
+ Can be placed anywhere.
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix-->
+</programlisting>
+
+<programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix-->
+</programlisting>
+
+<programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix-->
+</programlisting>
+ </section>
+ <section id="quickbook.syntax.phrase">
+ <title><link linkend="quickbook.syntax.phrase"> Phrase Level Elements</link></title>
+ <section id="quickbook.syntax.phrase.font_styles">
+ <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title>
+
+<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
+ role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
+ role="strikethrough">strikethrough</emphasis>
+ </para>
+ <para>
+ Like all non-terminal phrase level elements, this can of course be nested:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.replaceable">
+ <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title>
+ <para>
+ When you want content that may or must be replaced by the user, use the
+ syntax:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[~replacement]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ This will generate:
+ </para>
+ <para>
+ <replaceable>
+ replacement
+ </replaceable>
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.quotations">
+ <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title>
+
+<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ <quote>A question that sometimes drives me hazy: am I or are the others
+ crazy?</quote>--Einstein
+ </para>
+ <para>
+ Note the proper left and right quote marks. Also, while you can simply
+ use ordinary quote marks like "quoted", our quotation, above,
+ will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
+ </para>
+ <para>
+ Like all phrase elements, quotations may be nested. Example:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's
+the true business precept.]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ <quote>Here's the rule for bargains: <quote>Do other men, for they would
+ do you.</quote> That's the true business precept.</quote>
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.simple_formatting">
+ <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title>
+ <para>
+ Simple markup for formatting text, common in many applications, is now
+ supported:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype=
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
+ role="underline">underline</emphasis>, <literal>teletype</literal>
+ </para>
+ <para>
+ Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
+ are much stricter
+ <footnote>
+ <para>
+ Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>,
+ for sharing these samples and teaching me these obscure formatting
+ rules. I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>,
+ being more or less a formal EBNF parser, can handle the context sensitivity
+ and ambiguity.
+ </para>
+ </footnote>
+ .
+ </para>
+ <itemizedlist>
+ <listitem>
+ Simple markups cannot nest. You can combine a simple markup with a nestable
+ markup.
+ </listitem>
+ <listitem>
+ Simple markups cannot contain any other form of quickbook markup.
+ </listitem>
+ <listitem>
+ A non-space character must follow the leading markup
+ </listitem>
+ <listitem>
+ A non-space character must precede the trailing markup
+ </listitem>
+ <listitem>
+ A space or a punctuation must follow the trailing markup
+ </listitem>
+ <listitem>
+ If the matching markup cannot be found within a block, the formatting
+ will not be applied. This is to ensure that un-matched formatting markups,
+ which can be a common mistake, does not corrupt anything past a single
+ block. We do not want the rest of the document to be rendered bold just
+ because we forgot a trailing '*'. A single block is terminated by two
+ end of lines or the close bracket: ']'.
+ </listitem>
+ <listitem>
+ A line starting with the star will be interpreted as an unordered list.
+ See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
+ lists</link>.
+ </listitem>
+ </itemizedlist>
+ <table frame="all"> <title>More Formatting Samples</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Markup
+ </para>
+ </entry><entry>
+ <para>
+ Result
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>*Bold*</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">Bold</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*Is bold*</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">Is bold</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>* Not bold* *Not bold * * Not bold *</literal>
+ </para>
+ </entry><entry>
+ <para>
+ * Not bold* *Not bold * * Not bold *
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>This*Isn't*Bold (no bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ This*Isn't*Bold (no bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>(*Bold Inside*) (parenthesis not bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*(Bold Outside)* (parenthesis bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>3*4*5 = 60 (no bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ 3*4*5 = 60 (no bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>3 * 4 * 5 = 60 (no bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ 3 * 4 * 5 = 60 (no bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>3 *4* 5 = 60 (4 is bold)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ 3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*This is bold* this is not *but this is*</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">This is bold</emphasis> this is not <emphasis
+ role="bold">but this is</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*This is bold*.</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">This is bold</emphasis>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*B*. (bold B)</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">B</emphasis>. (bold B)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>['*Bold-Italic*]</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>*side-by*/-side/</literal>
+ </para>
+ </entry><entry>
+ <para>
+ <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ As mentioned, simple markups cannot go past a single block. The text from
+ "have" to "full" in the following paragraph will be
+ rendered as bold:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!*
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir,
+ yes sir, three bags full!</emphasis> One for the master, one for the dame,
+ And one for the little boy who lives down the lane.
+ </para>
+ <para>
+ But in the following paragraph, bold is not applied:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!
+ One for the master, one for the dame, And one for the little boy who lives
+ down the lane.
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.inline_code">
+ <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></title>
+ <para>
+ Inlining code in paragraphs is quite common when writing C++ documentation.
+ We provide a very simple markup for this. For example, this:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it.
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ This text has inlined code <code><phrase role="keyword">int</phrase> <phrase
+ role="identifier">main</phrase><phrase role="special">()</phrase> <phrase
+ role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase
+ role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code>
+ in it. The code will be syntax highlighted.
+ </para>
+ <note>
+ <para>
+ We simply enclose the code with the tick: <literal>"`"</literal>, not the
+ single quote: <code><phrase role="string">"'"</phrase></code>.
+ Note too that <literal>`some code`</literal> is preferred over <literal>[^some code]</literal>.
+ </para>
+ </note>
+ </section>
+ <section id="quickbook.syntax.phrase.code_blocks">
+ <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></title>
+ <para>
+ Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>).
+ However, such a simple syntax cannot be used as phrase elements in lists
+ (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
+ lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
+ lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>),
+ etc. Inline code (see above) can. The problem is, inline code does not
+ allow formatting with newlines, spaces, and tabs. These are lost.
+ </para>
+ <para>
+ We provide a phrase level markup that is a mix between the two. By using
+ the double-tick, instead of the single-tick, we are telling QuickBook to
+ use preformatted blocks of code. Example:
+ </para>
+
+<programlisting>``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+``
+</programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+
+<programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
+
+<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
+ <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+</programlisting>
+ </para>
+ </section>
+ <section id="quickbook.syntax.phrase.source_mode">
+ <title><link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></title>
+ <para>
+ If a document contains more than one type of source code then the source
+ mode may be changed dynamically as the document is processed. All QuickBook
+ documents are initially in C++ mode by default, though an alternative initial
+ value may be set in the <link linkend="quickbook.syntax.block.document">Document</link>
+ section.
+ </para>
+ <para>
+ To change the source mode, use the <literal>[source-mode]</literal> markup,
+ where <literal>source-mode</literal> is one of the supported modes. For
+ example, this:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->Python's [python] `import` is rather like C++'s [c++] `#include`. A
+C++ comment `// looks like this` whereas a Python comment [python]
+`# looks like this`.
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <para>
+ Python's <code><phrase role="keyword">import</phrase></code> is rather
+ like C++'s <code><phrase role="preprocessor">#include</phrase></code>.
+ A C++ comment <code><phrase role="comment">// looks like this</phrase></code>
+ whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>.
+ </para>
+ <table frame="all"> <title>Supported Source Modes</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>
+ Mode
+ </para>
+ </entry><entry>
+ <para>
+ Source Mode Markup
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ C++
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[c++]</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ Python
+ </para>
+ </entry><entry>
+ <para>
+ <literal>[python]</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>
+ The source mode strings are lowercase.
+ </para>
+ </note>
+ </section>
+ <section id="quickbook.syntax.phrase.line_break">
+ <title><link linkend="quickbook.syntax.phrase.line_break">line-break</link></title>
+
+<programlisting><!--quickbook-escape-prefix-->[br]
+<!--quickbook-escape-postfix--></programlisting>
+ <warning>
+ <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>
+
+<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
+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>
+
+<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>
+
+<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>
+
+<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>
+
+<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>
+
+<programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ This gets converted into <literal><link linkend="xml.refentry">The
+ link text</link></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><link linkend="xml.refentry">xml.refentry</link></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]
+[enumref fully::qualified::enum_name The link text]
+[macroref MACRO_NAME The link text]
+[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>
+
+<programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ would have "boost::bar::baz" 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>
+
+<programlisting>'''
+<emphasis role="bold">This is direct XML markup</emphasis>
+'''
+</programlisting>
+ <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>
+ </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>
+ 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>
+
+<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>
+
+<programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate this
+ <footnote>
+ <para>
+ A sample footnote
+ </para>
+ </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>
+<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>
+ </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]
+ [id the_document_name]
+ [dirname the_document_dir]
+ [copyright 2000 2002 2003 Joe Blow, Jane Doe]
+ [purpose The document's reason for being]
+ [category The document's category]
+ [authors [Blow, Joe], [Doe, Jane]]
+ [license The document's license]
+ [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>
+
+<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, "The Section Title"
+ 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: "The Section Title" will be
+ normalized to "the_section_title".
+ </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>
+
+<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>
+<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
+ # Three.a
+ # Three.b
+ # Three.c
+# Four
+ # Four.a
+ # Four.a.i
+ # Four.a.ii
+# Five
+</programlisting>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ One
+ </listitem>
+ <listitem>
+ Two
+ </listitem>
+ <listitem>
+ Three
+ <orderedlist>
+ <listitem>
+ Three.a
+ </listitem>
+ <listitem>
+ Three.b
+ </listitem>
+ <listitem>
+ Three.c
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ Fourth
+ <orderedlist>
+ <listitem>
+ Four.a
+ <orderedlist>
+ <listitem>
+ Four.a.i
+ </listitem>
+ <listitem>
+ Four.a.ii
+ </listitem>
+ </orderedlist>
+ </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>
+
+<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.
+ 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 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>
+<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>
+
+<programlisting><!--quickbook-escape-prefix--># One
+# Two
+# Three
+ * Three.a
+ * Three.b
+ * Three.c
+# Four
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ One
+ </listitem>
+ <listitem>
+ Two
+ </listitem>
+ <listitem>
+ Three
+ <itemizedlist>
+ <listitem>
+ Three.a
+ </listitem>
+ <listitem>
+ Three.b
+ </listitem>
+ <listitem>
+ Three.c
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ Four
+ </listitem>
+ </orderedlist>
+ <para>
+ And...
+ </para>
+
+<programlisting><!--quickbook-escape-prefix--># 1
+ * 1.a
+ # 1.a.1
+ # 1.a.2
+ * 1.b
+# 2
+ * 2.a
+ * 2.b
+ # 2.b.1
+ # 2.b.2
+ * 2.b.2.a
+ * 2.b.2.b
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ will generate:
+ </para>
+ <orderedlist>
+ <listitem>
+ 1
+ <itemizedlist>
+ <listitem>
+ 1.a
+ <orderedlist>
+ <listitem>
+ 1.a.1
+ </listitem>
+ <listitem>
+ 1.a.2
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ 1.b
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ 2
+ <itemizedlist>
+ <listitem>
+ 2.a
+ </listitem>
+ <listitem>
+ 2.b
+ <orderedlist>
+ <listitem>
+ 2.b.1
+ </listitem>
+ <listitem>
+ 2.b.2
+ <itemizedlist>
+ <listitem>
+ 2.b.2.a
+ </listitem>
+ <listitem>
+ 2.b.2.b
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
+
+<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
+<phrase role="special">{</phrase>
+ <phrase role="comment">// Sample code
+</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase>
+ <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>
+
+<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">'''"Cooks" 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>
+
+<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>
+</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): "``"
+ and "``". 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>
+<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>
+
+<programlisting><!--quickbook-escape-prefix-->[pre
+
+ Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+]
+<!--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>
+
+<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
+
+ 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>
+
+<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>
+
+<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>
+ 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]
+[h4 Heading 4]
+[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="section_id.normalized_header_text"</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>
+
+<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>
+
+<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>
+
+<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>
+
+<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&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&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>
+ 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).
+ </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>
+
+<programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ]
+<!--quickbook-escape-postfix--></programlisting>
+ <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>
+
+<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>
+
+<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>".."</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[]'''&#945;''']
+[template beta[]'''&#946;''']
+<!--quickbook-escape-postfix--></programlisting>
+ <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">αβ</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>
+
+<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 "Aristotle...". This space will be part
+ of the template body. If that space is unwanted, use empty brackets or
+ use the space escape: "<code><phrase role="special">\</phrase> </code>".
+ Example:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[template tag\ _tag]
+<!--quickbook-escape-postfix--></programlisting>
+ <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>".."</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>
+ "w x y z" is initially treated as a single argument because we
+ didn't supply any <literal>".."</literal> separators. However,
+ since <literal>simple</literal> expects 4 arguments, "w x y z"
+ is broken down iteratively (applying the logic above) until we have "w",
+ "x", "y" and "z".
+ </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: "w", "x", "y" and "z
+ trail".
+ </para>
+ <para>
+ It should be obvious now that for simple arguments with no spaces, we can
+ get by without separating the arguments with <literal>".."</literal>
+ separators. It is possible to combine <literal>".."</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--><hey><!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix--></hey><!--quickbook-escape-prefix-->]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ Now, expanding this:
+ </para>
+
+<programlisting><!--quickbook-escape-prefix-->[!baz]
+<!--quickbook-escape-postfix--></programlisting>
+ <para>
+ We will have:
+ </para>
+
+<programlisting><hey>baz</hey>
+</programlisting>
+ </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
+ implemented using template meta-programming techniques. Expression templates
+ allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
+ 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>
+
+<programlisting><!--quickbook-escape-prefix-->[table A Simple Table
+ [[Heading 1] [Heading 2] [Heading 3]]
+ [[R0-C0] [R0-C1] [R0-C2]]
+ [[R1-C0] [R1-C1] [R1-C2]]
+ [[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>
+ 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><thead>...</thead></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]]
+ [
+ [Row 0, Col 0: a small cell]
+ [
+ Row 0, Col 1: a big fat cell with paragraphs
+
+ Boost provides free peer-reviewed portable C++ source libraries.
+
+ 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.
+ ]
+ ]
+ [
+ [Row 1, Col 0: a small cell]
+ [Row 1, Col 1: a small cell]
+ ]
+]
+<!--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>
+ Row 1, Col 0: a small cell
+ </para>
+ </entry><entry>
+ <para>
+ 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]]
+ [
+ [My first program]
+ [<!--quickbook-escape-postfix-->``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+ ``<!--quickbook-escape-prefix-->]
+ ]
+]
+<!--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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
+
+<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"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
+ <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>
+
+<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 "columns" are allowed. The first column contains the terms,
+ and the second column contains the definitions. Those familiar with HTML
+ will recognize this as a "definition list".
+ </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 ("someother", 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 "Intro",
+ the named anchor for that section will be "someid.intro", 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>
+
+<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>
+
+<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">"foo"</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">"bar"</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase></programlisting>
+ </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
+</phrase></programlisting>
+ <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">/*< some [*quickbook] markup here >*/</phrase>
+</programlisting>
+ <para>
+ will be regarded as callouts. These will be collected, numbered and rendered
+ as a "callout bug" (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">"foo-bar"</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>
+ 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>
+ <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&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">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</phrase>
+ <phrase role="special">;</phrase>
+
+<phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase>
+ <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</phrase>
+ <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</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>
+ <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</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>
+</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>
+
+<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>
+ <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">schema</phrase><phrase role="special">/</phrase><phrase role="identifier">dtd</phrase><phrase role="special">/</phrase><phrase role="number">4.2</phrase>
+ <phrase role="special">;</phrase>
+
+<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>
+ <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>
+ <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>
+
+<programlisting><!--quickbook-escape-prefix-->qbk=*.qbk
+lexer.*.qbk=props
+use.tabs.$(qbk)=0
+tab.size.$(qbk)=4
+indent.size.$(qbk)=4
+style.props.32=$(font.base)
+comment.stream.start.props=[/
+comment.stream.end.props=]
+comment.box.start.props=[/
+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>
+
+<programlisting>using quickbook ;
+
+xml my_doc : my_doc.qbk ;
+
+boostbook standalone
+ :
+ my_doc
+ :
+ <xsl:param>boost.image.src<literal>images/my_project_logo.png
+ <xsl:param>boost.image.alt</literal>"\"My Project\""
+ <xsl:param>boost.image.w=100
+ <xsl:param>boost.image.h=50
+ <xsl:param>nav.layout=none
+ ;
+</programlisting>
+ </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>
+ <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>
+
+<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>
+
+<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>
+
+<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>
+
+<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>
Modified: branches/release/tools/quickbook/test/quickbook-manual.quickbook
==============================================================================
--- branches/release/tools/quickbook/test/quickbook-manual.quickbook (original)
+++ branches/release/tools/quickbook/test/quickbook-manual.quickbook 2009-03-12 17:50:30 EDT (Thu, 12 Mar 2009)
@@ -1,1981 +1,1981 @@
-[article Quickbook
- [quickbook 1.4]
- [version 1.4]
- [authors [de Guzman, Joel], [Niebler, Eric]]
- [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
- [purpose /WikiWiki/ style documentation tool]
- [license
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- [@http://www.boost.org/LICENSE_1_0.txt])
- ]
-]
-
-[/ QuickBook Document version 1.3 ]
-[/ Sept 24, 2002 ]
-[/ Sept 2, 2004 ]
-[/ Feb 14, 2005 ]
-[/ Sept 13, 2005 ]
-
-[/ Some links]
-
-[def __note__ [$images/note.png]]
-[def __alert__ [$images/alert.png]]
-[def __tip__ [$images/tip.png]]
-[def :-) [$images/smiley.png]]
-[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
-[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
-[def __docbook__ [@http://www.docbook.org/ DocBook]]
-
-[def __comments__ [link quickbook.syntax.comments Comments]]
-
-[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]]
-[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]]
-[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]]
-[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
-[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]]
-[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]]
-[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]]
-[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]]
-[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]]
-[def __links__ [link quickbook.syntax.phrase.links Links]]
-[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]]
-[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]]
-[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
-[def __escape__ [link quickbook.syntax.phrase.escape Escape]]
-[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
-[def __images__ [link quickbook.syntax.phrase.images Images]]
-
-[def __document__ [link quickbook.syntax.block.document Document]]
-[def __section__ [link quickbook.syntax.block.section Section]]
-[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]]
-[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]]
-[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
-[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
-[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
-[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
-[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
-[def __code__ [link quickbook.syntax.block.code Code]]
-[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
-[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]]
-[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]]
-[def __heading__ [link quickbook.syntax.block.headings Heading]]
-[def __macros__ [link quickbook.syntax.block.macros Macros]]
-[def __templates__ [link quickbook.syntax.block.templates Templates]]
-[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]]
-[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]]
-[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]]
-[def __tables__ [link quickbook.syntax.block.tables Tables]]
-[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]]
-[def __include__ [link quickbook.syntax.block.include Include]]
-[def __import__ [link quickbook.syntax.block.import Import]]
-
-[section:intro Introduction]
-
-[:[*['["Why program by hand in five days what you can spend five years of your
-life automating?]]]
-
--- Terrence Parr, author ANTLR/PCCTS
-]
-
-Well, QuickBook started as a weekend hack. It was originally intended to be a
-sample application using __spirit__. What is it? What you are viewing now, this
-documentation, is autogenerated by QuickBook. These files were generated from
-one master:
-
-[:[@../quickbook.qbk quickbook.qbk]]
-
-Originally named QuickDoc, this funky tool that never dies evolved into a
-funkier tool thanks to Eric Niebler who resurrected the project making it
-generate __boostbook__ instead of HTML. The __boostbook__ documentation format
-is an extension of __docbook__, an SGML or XML based format for describing
-documentation.
-
-QuickBook is a WikiWiki style documentation tool geared towards C++
-documentation using simple rules and markup for simple formatting tasks.
-QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
-simple text files. A single QuickBook document can generate a fully linked set
-of nice HTML and PostScript/PDF documents complete with images and syntax-
-colorized source code.
-
-Features include:
-
-* generate __boostbook__ xml, to generate HTML, PostScript and PDF
-* simple markup to link to Doxygen-generated entities
-* macro system for simple text substitution
-* simple markup for italics, bold, preformatted, blurbs, code samples,
- tables, URLs, anchors, images, etc.
-* automatic syntax coloring of code samples
-* CSS support
-
-[endsect]
-
-[section:change_log Change Log]
-
-[h3 Version 1.3]
-
-* Quickbook file inclusion \[include\].
-* Better xml output (pretty layout). Check out the generated XML.
-* Regression testing facility: to make sure your document will always be
- compatible (full backward compatibility) regardless of changes to
- QuickBook.
-* Code cleanup and refactoring.
-* Allow phrase markup in the doc-info.
-* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
- and lists, for example.
-* Quickbook versioning; allows full backward compatibility. You have to add
- \[quickbook 1.3\] to the doc-info header to enable the new features. Without
- this, QuickBook will assume that the document is a pre-1.3 document.
-* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
- Example:``
- [section x]
- blah...
- [endsect]``
-* Fully qualified section and headers. Subsection names are concatenated to the
- ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
-* Better and whitespace handling in code snippets.
-* \[xinclude\] fixes up the relative path to the target XML file when
- input_directory is not the same as the output_directory.
-* Allow untitled tables.
-* Allow phrase markups in section titles.
-* Allow escaping back to QuickBook from code, code blocks and inline code.
-* Footnotes, with the \[footnote This is the footnote\] syntax.
-* Post-processor bug fix for escaped XML code that it does not recognize.
-* Replaceable, with the \[~replacement\] syntax.
-* Generic Headers
-* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
-* Various code cleanup/maintenance
-* Templates!
-* \[conceptref\] for referencing BoostBook <concept> entities.
-* Allow escape of spaces. The escaped space is removed from the output. Syntax:
- `\ `.
-* Nested comments are now allowed.
-* Quickbook blocks can nest inside comments.
-* __import__ facility.
-* Callouts on imported code
-* Simple markups can now span a whole block.
-* __blurbs__, __admonitions__ and table cells (see __tables__) may now
- contain paragraphs.
-* `\n` and `[br]` are now deprecated.
-
-[endsect]
-
-[section:syntax Syntax Summary]
-
-A QuickBook document is composed of one or more blocks. An example of
-a block is the paragraph or a C++ code snippet. Some blocks have
-special mark-ups. Blocks, except code snippets which have their own
-grammar (C++ or Python), are composed of one or more phrases. A phrase
-can be a simple contiguous run of characters. Phrases can have special
-mark-ups. Marked up phrases can recursively contain other phrases, but
-cannot contain blocks. A terminal is a self contained block-level or
-phrase-level element that does not nest anything.
-
-Blocks, in general, are delimited by two end-of-lines (the block terminator).
-Phrases in each block cannot contain a block terminator. This way, syntax errors
-such as un-matched closing brackets do not go haywire and corrupt anything past
-a single block.
-
-[section Comments]
-
-Can be placed anywhere.
-
-[pre
-'''[/ comment (no output generated) ]'''
-]
-
-[/ for testing only... ]
-
-[pre
-'''[/ comments can be nested [/ some more here] ]'''
-]
-
-[/ for testing [/ only ] ]
-
-[pre
-'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
-]
-
-[/ for testing [*only ] ]
-
-[endsect]
-
-[section:phrase Phrase Level Elements]
-
-[section Font Styles]
-
-[pre'''
-['italic], [*bold], [_underline], [^teletype], [-strikethrough]
-''']
-
-will generate:
-
-['italic], [*bold], [_underline], [^teletype], [-strikethrough]
-
-Like all non-terminal phrase level elements, this can of course be nested:
-
-[pre'''
-[*['bold-italic]]
-''']
-
-will generate:
-
-[*['bold-italic]]
-
-[endsect]
-
-[section Replaceable]
-
-When you want content that may or must be replaced by the user, use the syntax:
-
-[pre'''
-[~replacement]
-''']
-
-This will generate:
-
-[~replacement]
-
-[endsect]
-
-[section Quotations]
-
-[pre'''
-["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
-''']
-
-will generate:
-
-["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
-
-Note the proper left and right quote marks. Also, while you can simply use
-ordinary quote marks like "quoted", our quotation, above, will generate correct
-DocBook quotations (e.g. <quote>quoted</quote>).
-
-Like all phrase elements, quotations may be nested. Example:
-
-[pre'''
-["Here's the rule for bargains: ["Do other men, for they would do you.] That's
-the true business precept.]
-''']
-
-will generate:
-
-["Here's the rule for bargains: ["Do other men, for they would do you.]
-That's the true business precept.]
-
-[endsect]
-[section Simple formatting]
-
-Simple markup for formatting text, common in many applications, is now supported:
-
-[pre'''
-/italic/, *bold*, _underline_, =teletype=
-''']
-
-will generate:
-
-/italic/, *bold*, _underline_, =teletype=
-
-Unlike QuickBook's standard formatting scheme, the rules for simpler
-alternatives are much stricter[footnote Thanks to David Barrett, author of
-[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing
-these samples and teaching me these obscure formatting rules. I wasn't sure
-at all if __spirit__, being more or less a formal EBNF parser, can handle
-the context sensitivity and ambiguity.].
-
-* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
-* Simple markups cannot contain any other form of quickbook markup.
-* A non-space character must follow the leading markup
-* A non-space character must precede the trailing markup
-* A space or a punctuation must follow the trailing markup
-* If the matching markup cannot be found within a block, the formatting
- will not be applied. This is to ensure that un-matched formatting markups,
- which can be a common mistake, does not corrupt anything past a single block.
- We do not want the rest of the document to be rendered bold just because we
- forgot a trailing '*'. A single block is terminated by two end of lines or
- the close bracket: ']'.
-* A line starting with the star will be interpreted as an unordered list.
- See __unordered_lists__.
-
-[table More Formatting Samples
- [[Markup] [Result]]
- [[[^'''*Bold*''']] [*Bold*]]
- [[[^'''*Is bold*''']] [*Is bold*]]
- [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]]
- [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]]
- [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]]
- [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]]
- [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]]
- [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]]
- [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]]
- [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]]
- [[[^'''*This is bold*.''']] [*This is bold*.]]
- [[[^'''*B*. (bold B)''']] [*B*. (bold B)]]
- [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]]
- [[[^'''*side-by*/-side/''']] [*side-by*/-side/]]
-]
-
-As mentioned, simple markups cannot go past a single block. The text
-from "have" to "full" in the following paragraph will be rendered as
-bold:
-
-[pre'''
-Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!*
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-''']
-
-Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!*
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-
-But in the following paragraph, bold is not applied:
-
-[pre'''
-Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-''']
-
-Baa baa black sheep, *have you any wool?
-Yes sir, yes sir, three bags full!
-One for the master, one for the dame,
-And one for the little boy who lives down the lane.
-
-[endsect]
-[section Inline code]
-
-Inlining code in paragraphs is quite common when writing C++ documentation. We
-provide a very simple markup for this. For example, this:
-
-[pre'''
-This text has inlined code `int main() { return 0; }` in it.
-''']
-
-will generate:
-
-This text has inlined code `int main() { return 0; }` in it. The code will be
-syntax highlighted.
-
-[note We simply enclose the code with the tick: [^'''"`"'''], not the
-single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over
-[^'''[^some code]''']. ]
-
-[endsect]
-[section Code blocks]
-
-Preformatted code simply starts with a space or a tab (See __code__).
-However, such a simple syntax cannot be used as phrase elements in lists
-(See __ordered_lists__ and __unordered_lists__), tables (See __tables__),
-etc. Inline code (see above) can. The problem is, inline code does not
-allow formatting with newlines, spaces, and tabs. These are lost.
-
-We provide a phrase level markup that is a mix between the two. By using the
-double-tick, instead of the single-tick, we are telling QuickBook to use
-preformatted blocks of code. Example:
-
-[pre
-\`\`
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
-\`\`
-]
-
-will generate:
-
-``
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
-``
-
-[endsect]
-[section Source Mode]
-
-If a document contains more than one type of source code then the source
-mode may be changed dynamically as the document is processed. All QuickBook
-documents are initially in C++ mode by default, though an alternative
-initial value may be set in the __document__ section.
-
-To change the source mode, use the [^\[source-mode\]] markup, where
-=source-mode= is one of the supported modes. For example, this:
-
-[pre'''
-Python's [python] `import` is rather like C++'s [c++] `#include`. A
-C++ comment `// looks like this` whereas a Python comment [python]
-`# looks like this`.
-''']
-
-will generate:
-
-Python's [python] `import` is rather like C++'s [c++] `#include`. A
-C++ comment `// looks like this` whereas a Python comment [python]
-`#looks like this`.
-
-[table Supported Source Modes
- [[Mode] [Source Mode Markup]]
- [[C++] [[^\[c++\]]]]
- [[Python] [[^\[python\]]]]
-]
-
-[note The source mode strings are lowercase.]
-
-[endsect]
-[section line-break]
-
-[pre'''
-[br]
-''']
-
-[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
-table cells (see __tables__) may now contain paragraphs.]
-
-[endsect]
-[section Anchors]
-
-[pre'''
-[#named_anchor]
-''']
-
-A named anchor is a hook that can be referenced by a link elsewhere in the
-document. You can then reference an anchor with [^'''[link named_anchor
-Some link text]''']. See __anchor_links__, __section__ and __heading__.
-
-[endsect]
-[section Links]
-
-[pre'''
-[@http://www.boost.org this is [*boost's] website....]
-''']
-
-will generate:
-
-[@http://www.boost.org this is [*boost's] website....]
-
-URL links where the link text is the link itself is common. Example:
-
-[pre'''
-see http://spirit.sourceforge.net/
-''']
-
-so, when the text is absent in a link markup, the URL is assumed. Example:
-
-[pre
-see '''[@http://spirit.sourceforge.net/]'''
-]
-
-will generate:
-
-see [@http://spirit.sourceforge.net/]
-
-[endsect]
-[section Anchor links]
-
-You can link within a document using:
-
-[pre'''
-[link section_id.normalized_header_text The link text]
-''']
-
-See sections __section__ and __heading__ for more info.
-
-[endsect]
-[section refentry links]
-
-In addition, you can link internally to an XML refentry like:
-
-[pre'''
-[link xml.refentry The link text]
-''']
-
-This gets converted into [^<link linkend="xml.refentry">The link text</link>].
-
-Like URLs, the link text is optional. If this is not present, the link text will
-automatically be the refentry. Example:
-
-[pre'''
-[link xml.refentry]
-''']
-
-This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].
-
-[endsect]
-[section:code_links Code Links]
-
-If you want to link to a function, class, member, enum, concept or header in the reference
-section, you can use:
-
-[pre'''
-[funcref fully::qualified::function_name The link text]
-[classref fully::qualified::class_name The link text]
-[memberref fully::qualified::member_name The link text]
-[enumref fully::qualified::enum_name The link text]
-[macroref MACRO_NAME The link text]
-[conceptref ConceptName The link text]
-[headerref path/to/header.hpp The link text]
-''']
-
-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:
-
-[pre'''
-[classref boost::bar::baz]
-''']
-
-would have "boost::bar::baz" as the link text.
-
-[endsect]
-[section Escape]
-
-The escape mark-up is used when we don't want to do any processing.
-
-[pre
-\'\'\'
-escape (no processing/formatting)
-\'\'\'
-]
-
-Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example:
-
-[pre
-\'\'\'
-<emphasis role="bold">This is direct XML markup</emphasis>
-\'\'\'
-]
-
-'''
-<emphasis role="bold">This is direct XML markup</emphasis>
-'''
-
-[important Be careful when using the escape. The text must conform to
-__boostbook__/__docbook__ syntax.]
-
-[endsect]
-[section Single char escape]
-
-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 `[` and `]`.
-For example, how do you escape the triple quote? Simple: [^\\'\\'\\']
-
-
-`\n` has a special meaning. It is used to generate line breaks.
-
-[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
-and table cells (see __tables__) may now contain paragraphs.]
-
-The escaped space: `\ ` also has a special meaning. The escaped space is removed
-from the output.
-
-[endsect]
-[section Images]
-
-[pre'''
-[$image.jpg]
-''']
-
-[endsect]
-[section Footnotes]
-
-As of version 1.3, QuickBook supports footnotes. Just put the text of the
-footnote in a `[footnote]` block, and the text will be put at the bottom
-of the current page. For example, this:
-
-[pre'''
-[footnote A sample footnote]
-''']
-
-will generate this[footnote A sample footnote].
-
-[section Macro Expansion]
-
-[pre'''
-__a_macro_identifier__
-''']
-
-See __macros__ for details.
-
-[endsect]
-
-[section Template Expansion]
-
-[pre'''
-[a_template_identifier]
-''']
-
-See __templates__ for details.
-
-[endsect]
-
-[endsect]
-[endsect]
-[section:block Block Level Elements]
-
-[section Document]
-
-Every document must begin with a Document Info section, which should look
-like this:
-
-[pre'''
-[document-type The Document Title
- [quickbook 1.3]
- [version 1.0]
- [id the_document_name]
- [dirname the_document_dir]
- [copyright 2000 2002 2003 Joe Blow, Jane Doe]
- [purpose The document's reason for being]
- [category The document's category]
- [authors [Blow, Joe], [Doe, Jane]]
- [license The document's license]
- [source-mode source-type]
-]
-''']
-
-Where document-type is one of:
-
-* book
-* article
-* library
-* chapter
-* part
-* appendix
-* preface
-* qandadiv
-* qandaset
-* reference
-* set
-
-quickbook 1.3 declares the version of quickbook the document is written for.
-In its absence, version 1.1 is assumed.
-
-=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
-=license=, =last-revision= and =source-mode= are optional information.
-
-=source-type= is a lowercase string setting the initial __source_mode__. If
-the =source-mode= field is omitted, a default value of =c++= will be used.
-
-[endsect]
-[section Section]
-
-Starting a new section is accomplished with:
-
-[pre'''
-[section:id The Section Title]
-''']
-
-where /id/ is optional. id will be the filename of the generated section.
-If it is not present, "The Section Title" will be normalized and become the id.
-Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
-converted to underscore and all upper-case are converted to lower case.
-Thus: "The Section Title" will be normalized to "the_section_title".
-
-End a section with:
-
-[pre'''
-[endsect]
-''']
-
-Sections can nest, and that results in a hierarchy in the table of contents.
-
-[endsect]
-[section xinclude]
-
-You can include another XML file with:
-
-[pre'''
-[xinclude file.xml]
-''']
-
-This is useful when file.xml has been generated by Doxygen and contains your
-reference section.
-
-[endsect]
-[section Paragraphs]
-
-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.
-
-[endsect]
-
-[section Lists]
-[section Ordered lists]
-
-[pre
-# One
-# Two
-# Three
-]
-
-will generate:
-
-# One
-# Two
-# Three
-
-[endsect]
-[section List Hierarchies]
-
-List hierarchies are supported. Example:
-
-[pre
-# One
-# Two
-# Three
- # Three.a
- # Three.b
- # Three.c
-# Four
- # Four.a
- # Four.a.i
- # Four.a.ii
-# Five
-]
-
-will generate:
-
-# One
-# Two
-# Three
- # Three.a
- # Three.b
- # Three.c
-# Fourth
- # Four.a
- # Four.a.i
- # Four.a.ii
-# Five
-
-[endsect]
-[section Long List Lines]
-
-Long lines will be wrapped appropriately. Example:
-
-[pre
-# 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.
- 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 short item.
-]
-
-# 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.
- 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 short item.
-
-[endsect]
-[section Unordered lists]
-
-[pre'''
-* First
-* Second
-* Third
-''']
-
-will generate:
-
-* First
-* Second
-* Third
-
-[endsect]
-[section Mixed lists]
-
-Mixed lists (ordered and unordered) are supported. Example:
-
-[pre'''
-# One
-# Two
-# Three
- * Three.a
- * Three.b
- * Three.c
-# Four
-''']
-
-will generate:
-
-# One
-# Two
-# Three
- * Three.a
- * Three.b
- * Three.c
-# Four
-
-And...
-
-[pre'''
-# 1
- * 1.a
- # 1.a.1
- # 1.a.2
- * 1.b
-# 2
- * 2.a
- * 2.b
- # 2.b.1
- # 2.b.2
- * 2.b.2.a
- * 2.b.2.b
-''']
-
-will generate:
-
-# 1
- * 1.a
- # 1.a.1
- # 1.a.2
- * 1.b
-# 2
- * 2.a
- * 2.b
- # 2.b.1
- # 2.b.2
- * 2.b.2.a
- * 2.b.2.b
-
-[endsect]
-[endsect]
-
-[section Code]
-
-Preformatted code starts with a space or a tab. The code will be
-syntax highlighted according to the current __source_mode__:
-
-[c++]
-
- #include <iostream>
-
- int main()
- {
- // Sample code
- std::cout << "Hello, World\n";
- return 0;
- }
-
-[python]
-
- import cgi
-
- def cookForHtml(text):
- '''"Cooks" the input text for HTML.'''
-
- return cgi.escape(text)
-
-[c++]
-
-Macros that are already defined are expanded in source code. Example:
-
-[pre'''
-[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__;
-''']
-
-Generates:
-
-[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__;
-
-[endsect]
-[section:escape_back Escaping Back To QuickBook]
-
-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 /escape-back/ delimiter. In C++ and Python, the delimiter
-is the double tick (back-quote): "\`\`" and "\`\`". Example:
-
-[pre'''
-void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
-{
-}
-''']
-
-Will generate:
-
- void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
- {
- }
-
-When escaping from code to QuickBook, only phrase level markups are
-allowed. Block level markups like lists, tables etc. are not allowed.
-
-[endsect]
-[section Preformatted]
-
-Sometimes, you don't want some preformatted text to be parsed as C++. In such
-cases, use the [^[pre ... \]] markup block.
-
-[pre'''
-[pre
-
- Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
-]
-''']
-
-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:
-
-[pre
-
-Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
- Some *preformatted* text Some *preformatted* text
-
-]
-
-Notice that unlike Code, phrase markup such as font style is still permitted
-inside =pre= blocks.
-
-[endsect]
-[section Blockquote]
-
-[pre
-'''[:sometext...]'''
-]
-
-[:Indents the paragraph. This applies to one paragraph only.]
-
-[endsect]
-[section Admonitions]
-
-[pre'''
-[note This is a note]
-[tip This is a tip]
-[important This is important]
-[caution This is a caution]
-[warning This is a warning]
-''']
-
-generates __docbook__ admonitions:
-
-[note This is a note]
-[tip This is a tip]
-[important This is important]
-[caution This is a caution]
-[warning This is a warning]
-
-These are the only admonitions supported by __docbook__. So,
-for example [^\[information This is some information\]] is unlikely
-to produce the desired effect.
-
-[endsect]
-[section Headings]
-
-[pre'''
-[h1 Heading 1]
-[h2 Heading 2]
-[h3 Heading 3]
-[h4 Heading 4]
-[h5 Heading 5]
-[h6 Heading 6]
-''']
-
-[h1 Heading 1]
-[h2 Heading 2]
-[h3 Heading 3]
-[h4 Heading 4]
-[h5 Heading 5]
-[h6 Heading 6]
-
-Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized
-names with [^name="section_id.normalized_header_text"] (i.e. valid characters are
-=a-z=, =A-Z=, =0-9= and =_=. 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 [^section_2.heading_1]). You can use:
-
-[pre'''
-[link section_id.normalized_header_text The link text]
-''']
-
-to link to them. See __anchor_links__ and __section__ for more info.
-
-[endsect]
-[section Generic Heading]
-
-In cases when you don't want to care about the heading level (1 to 6), you
-can use the /Generic Heading/:
-
-[pre'''
-[heading Heading]
-''']
-
-The /Generic Heading/ 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 /h2/.
-
-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:
-
-[pre'''
-[section A]
-[h2 X]
-[h2 Y]
-[h2 Z]
-[endsect]
-''']
-
-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:
-
-[pre'''
-[section A]
-[heading X]
-[heading Y]
-[heading Z]
-[endsect]
-''']
-
-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 /section/ and /heading/, you have all you need. /h1/../h6/ becomes
-redundant. /h1/../h6/ might be deprecated in the future.
-
-[endsect]
-[section Macros]
-
-[pre'''
-[def macro_identifier some text]
-''']
-
-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:
-
-[pre'''
-[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
-sf_logo
-''']
-
-Now everywhere the sf_logo is placed, the picture will be inlined.
-
-[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
-sf_logo
-
-[tip 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. [^'''__spirit__''']). The reason is to avoid
-unwanted macro replacement.]
-
-Links (URLS) and images are good candidates for macros. *1*) 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. *2*) The syntax is not pretty. It's easier to read and
-write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]'''].
-
-Some more examples:
-
-[pre'''
-[def :-) [$theme/smiley.png]]
-[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
-''']
-
-(See __images__ and __links__)
-
-Invoking these macros:
-
-[pre'''
-Hi __spirit__ :-)
-''']
-
-will generate this:
-
-Hi __spirit__ :-)
-
-[endsect]
-[section Predefined Macros]
-
-Quickbook has some predefined macros that you can already use.
-
-[table Predefined Macros
- [[Macro] [Meaning] [Example]]
- [['''__DATE__'''] [Today's date] [__DATE__]]
- [['''__TIME__'''] [The current time] [__TIME__]]
- [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]]
-]
-
-[endsect]
-[section Templates]
-
-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).
-
-Example template:
-
-[pre'''
-[template person[name age what]
-
-Hi, my name is [name]. I am [age] years old. I am a [what].
-
-]
-''']
-
-[template person[name age what]
-
-Hi, my name is [name]. I am [age] years old. I am a [what].
-
-]
-
-[heading Template Identifier]
-
-Template identifiers can either consist 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.
-* A single character punctuation (a non-alphanumeric printable character)
-
-[heading Formal Template Arguments]
-
-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.
-
-A template formal argument temporarily hides a template of the same name at
-the point where the [link quickbook.syntax.block.templates.template_expansion
-template is expanded]. Note that the body of the [^person] template above
-refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
-[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
-in the duration of the template call.
-
-[heading Template Body]
-
-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:
-
-[pre'''
-[template sample[arg1 arg2...argN] replacement text... ]
-''']
-
-Block templates are of the form:
-
-[pre'''
-[template sample[arg1 arg2...argN]
-replacement text...
-]
-''']
-
-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.
-
-[heading Template Expansion]
-
-You expand a template this way:
-
-[pre'''
-[template_identifier arg1..arg2..arg3]
-''']
-
-At template expansion, you supply the actual arguments. The template will
-be expanded with your supplied arguments. Example:
-
-[pre'''
-[person James Bond..39..Spy]
-[person Santa Clause..87..Big Red Fatso]
-''']
-
-Which will expand to:
-
-[person James Bond..39..Spy]
-[person Santa Clause..87..Big Red Fatso]
-
-[caution 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.]
-
-Each actual argument can be a word, a text fragment or just about any [link
-quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
-double dot [^".."] and terminated by the close parenthesis.
-
-[heading Nullary Templates]
-
-Nullary templates look and act like simple macros. Example:
-
-[pre'''
-[template alpha[]'''&#945;''']
-[template beta[]'''&#946;''']
-''']
-
-[template alpha[]'''α''']
-[template beta[]'''β''']
-
-Expanding:
-
-[pre'''Some squigles...[*[alpha][beta]]''']
-
-We have:
-
-Some squiggles...[*[alpha][beta]]
-
-The difference with macros are
-
-* The explicit [link quickbook.syntax.block.templates.template_expansion
- template expansion syntax]. 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.
-* 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.
-
-The empty brackets after the template identifier ([^alpha\[\]]) indicates no
-arguments. If the template body does not look like a template argument list, we
-can elide the empty brackets. Example:
-
-[pre'''
-[template aristotle_quote Aristotle: [*['Education is the best provision
-for the journey to old age.]]]
-''']
-
-[template aristotle_quote\ Aristotle: [*['Education is the best provision
-for the journey to old age.]]]
-
-Expanding:
-
-[pre'''
-Here's a quote from [aristotle_quote].
-''']
-
-We have:
-
-Here's a quote from [aristotle_quote].
-
-The disadvantage is that you can't avoid the space between the template
-identifier, `aristotle_quote`, and the template body "Aristotle...". This space
-will be part of the template body. If that space is unwanted, use empty
-brackets or use the space escape: "`\ `". Example:
-
-[pre'''
-[template tag\ _tag]
-''']
-
-[template tag\ _tag]
-
-Then expanding:
-
-[pre'''
-`struct` x[tag];
-''']
-
-We have:
-
-`struct` x[tag];
-
-You have a couple of ways to do it. I personally prefer the explicit empty
-brackets, though.
-
-[heading Simple Arguments]
-
-As mentioned, arguments are separated by the double dot [^".."]. If there
-are less arguments passed than expected, QuickBook attempts to break the
-last argument into two or more arguments following this logic:
-
-* Break the last argument into two, at the first space found ([^'', '\\n',
- \\t' or '\\r']).
-* Repeat until there are enough arguments or if there are no more spaces
- found (in which case, an error is reported).
-
-For example:
-
-[pre'''
-[template simple[a b c d] [a][b][c][d]]
-[simple w x y z]
-''']
-
-will produce:
-
-[template simple[a b c d] [a][b][c][d]]
-[simple w x y z]
-
-"w x y z" is initially treated as a single argument because we didn't
-supply any [^".."] separators. However, since [^simple] expects 4
-arguments, "w x y z" is broken down iteratively (applying the logic above)
-until we have "w", "x", "y" and "z".
-
-QuickBook only tries to get the arguments it needs. For example:
-
-[pre'''
-[simple w x y z trail]
-''']
-
-will produce:
-
-[simple w x y z trail]
-
-The arguments being: "w", "x", "y" and "z trail".
-
-It should be obvious now that for simple arguments with no spaces, we can
-get by without separating the arguments with [^".."] separators. It is
-possible to combine [^".."] separators with the argument passing
-simplification presented above. Example:
-
-[pre'''
-[simple what do you think ..m a n?]
-''']
-
-will produce:
-
-[simple what do you think ..m a n?]
-
-[heading Punctuation Templates]
-
-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 quickbook.syntax.block.templates.template_identifier
-template identifiers]. Example:
-
-[pre'''
-[template ![bar] '''<hey>'''[bar]'''</hey>''']
-''']
-
-Now, expanding this:
-
-[pre'''
-[!baz]
-''']
-
-We will have:
-
-[pre
-<hey>baz</hey>
-]
-
-[endsect]
-[section Blurbs]
-
-[pre'''
-[blurb :-) [*An eye catching advertisement or note...]
-
- __spirit__ 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++.
-]
-''']
-
-will generate this:
-
-[blurb :-) [*An eye catching advertisement or note...]
-
- __spirit__ 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++.
-]
-
-[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
-appropriate.]
-
-[endsect]
-[section Tables]
-
-[pre'''
-[table A Simple Table
- [[Heading 1] [Heading 2] [Heading 3]]
- [[R0-C0] [R0-C1] [R0-C2]]
- [[R1-C0] [R1-C1] [R1-C2]]
- [[R2-C0] [R2-C1] [R2-C2]]
-]
-''']
-
-will generate:
-
-[table A Simple Table
- [[Heading 1] [Heading 2] [Heading 3]]
- [[R0-C0] [R0-C1] [R0-C2]]
- [[R2-C0] [R2-C1] [R2-C2]]
- [[R3-C0] [R3-C1] [R3-C2]]
-]
-
-The table title is optional. The first row of the table is automatically
-treated as the table header; that is, it is wrapped in
-[^<thead>...</thead>] 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:
-
-[pre'''
-[table Table with fat cells
- [[Heading 1] [Heading 2]]
- [
- [Row 0, Col 0: a small cell]
- [
- Row 0, Col 1: a big fat cell with paragraphs
-
- Boost provides free peer-reviewed portable C++ source libraries.
-
- 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.
- ]
- ]
- [
- [Row 1, Col 0: a small cell]
- [Row 1, Col 1: a small cell]
- ]
-]
-''']
-
-and thus:
-
-[table Table with fat cells
- [[Heading 1] [Heading 2]]
- [
- [Row 0, Col 0: a small cell]
- [
- Row 0, Col 1: a big fat cell with paragraphs
-
- Boost provides free peer-reviewed portable C++ source libraries.
-
- 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.
- ]
- ]
- [
- [Row 1, Col 0: a small cell]
- [Row 1, Col 1: a small cell]
- ]
-]
-
-Here's how to have preformatted blocks of code in a table cell:
-
-[pre'''
-[table Table with code
- [[Comment] [Code]]
- [
- [My first program]
- ['''\`\`
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
- \`\`''']
- ]
-]
-''']
-
-[table Table with code
- [[Comment] [Code]]
- [
- [My first program]
- [``
- #include <iostream>
-
- int main()
- {
- std::cout << "Hello, World!" << std::endl;
- return 0;
- }
- ``]
- ]
-]
-
-[endsect]
-[section Variable Lists]
-
-[pre'''
-[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]]
-]
-''']
-
-will generate:
-
-[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]]
-]
-
-The rules for variable lists are the same as for tables, except that
-only 2 "columns" are allowed. The first column contains the terms, and
-the second column contains the definitions. Those familiar with HTML
-will recognize this as a "definition list".
-
-[endsect]
-[section Include]
-
-You can include one QuickBook file from another. The syntax is simply:
-
-[pre'''
-[include someother.qbk]
-''']
-
-The included file will be processed as if it had been cut and pasted
-into the current document, with the following exceptions:
-
-* The '''__FILENAME__''' predefined macro will reflect the name of the
- file currently being processed.
-* Any macros defined in the included file are scoped to that file.
-
-The [^\[include\]] 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 ("someother", in the example above). You can specify the id
-like this:
-
-[pre'''
-[include:someid someother.qbk]
-''']
-
-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 "Intro", the
-named anchor for that section will be "someid.intro", and you can link to
-it with [^\[link someid.intro The Intro\]].
-
-[endsect]
-
-[section Import]
-
-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.
-
-QuickBook's import facility provides a nice solution.
-
-[heading Example]
-
-You can effortlessly import code snippets from source code into your QuickBook.
-The following illustrates how this is done:
-
-[pre'''
-[import ../test/stub.cpp]
-[foo]
-[bar]
-''']
-
-The first line:
-
-[pre'''
-[import ../test/stub.cpp]
-''']
-
-collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp]
-and places them in your QuickBook file as virtual templates. Each of the
-specially marked-up code snippets has a name (e.g. `foo` and `bar` 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:
-
-[pre'''
-[foo]
-[bar]
-''']
-
-And the result is:
-
-[import ../test/stub.cpp]
-[foo]
-[bar]
-
-[heading Code Snippet Markup]
-
-Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We
-use distinguishable comments following the form:
-
- //[id
- some code here
- //]
-
-The first comment line above initiates a named code-snippet. This prefix will
-not be visible in quickbook. The entire code-snippet in between `//[id` and
-`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
-`//]` ends a code-snippet This too will not be visible in quickbook.
-
-[heading Special Comments]
-
-Special comments of the form:
-
- //` some [*quickbook] markup here
-
-and:
-
- /*` some [*quickbook] markup here */
-
-will be parsed by QuickBook. This can contain quickbook /blocks/ (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.
-
-[heading Callouts]
-
-Special comments of the form:
-
- /*< some [*quickbook] markup here >*/
-
-will be regarded as callouts. These will be collected, numbered and
-rendered as a "callout bug" (a small icon with a number). After the
-whole snippet is parsed, the callout list is generated. See
-[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
-Example:
-
-[foo_bar]
-
-Checkout [@../../test/stub.cpp stub.cpp] to see the actual code.
-
-[endsect]
-
-[endsect]
-[endsect]
-
-[section:install Installation and configuration]
-
-This section provides some guidelines on how to install and configure
-BoostBook and Quickbook under several operating systems.
-
-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 `bin` and `bin.v2` directories generated
-by the build before trying again. Otherwise your configuration fixes will
-not take any effect.
-
-[section:windows Windows 2000, XP, 2003, Vista]
-
-[python]
-
-[:['Section contributed by Julio M. Merino Vidal]]
-
-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.
-
-# First of all you need to have a copy of `xsltproc` for Windows. There
- are many ways to get this tool, but to keep things simple, use the
- [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
- Zlatkovic. At the very least, you need to download the following
- packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
-
-# Unpack all these packages in the same directory so that you get unique
- `bin`, `include` and `lib` directories within the hierarchy. These
- instructions use `C:\Users\example\Documents\boost\xml` as the root for
- all files.
-
-# From the command line, go to the `bin` directory and launch
- `xsltproc.exe` to ensure it works. You should get usage information on
- screen.
-
-# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
- 4.2] and unpack it in the same directory used above. That is:
- `C:\Users\example\Documents\boost\xml\docbook-xml`.
-
-# Download the latest
- [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
- Docbook XSL] version and unpack it, again in the same directory
- used before. To make things easier, rename the directory created
- during the extraction to `docbook-xsl` (bypassing the version name):
- `C:\Users\example\Documents\boost\xml\docbook-xsl`.
-
-# Add the following to your `user-config.jam` file, which should live in
- your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it
- somewhere or otherwise you could not be building Boost (i.e. missing
- tools configuration).
-
- using xsltproc
- : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
- ;
-
- using boostbook
- : "C:/Users/example/Documents/boost/xml/docbook-xsl"
- : "C:/Users/example/Documents/boost/xml/docbook-xml"
- ;
-
-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:
-
-# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
-
-# Build the utility by issuing `bjam --v2`.
-
-# Copy the resulting `quickbook.exe` binary (located under the
- `BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous
- example, you can install it into:
- `C:\Users\example\Documents\boost\xml\bin`.
-
-# Add the following to your `user-config.jam` file:
-
- using quickbook
- : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
- ;
-
-[endsect]
-
-[section:linux Debian, Ubuntu]
-
-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.
-
-First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
-For example, using `apt-get`:
-
- sudo apt-get install xsltprc docbook-xsl docbook-xml
-
-If you're planning on building boost's documentation, you'll also need to
-install the `doxygen` package as well.
-
-Next, we need to configure Boost Build to compile BoostBook files. Add the
-following to your `user-config.jam` 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 `user-config.jam`, see the
-[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
-Build documentation].
-
- using xsltproc ;
-
- using boostbook
- : /usr/share/xml/docbook/stylesheet/nwalsh
- : /usr/share/xml/docbook/schema/dtd/4.2
- ;
-
- # Remove this line if you're not using doxygen
- using doxygen ;
-
-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:
-
-# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
-
-# Build the utility by issuing `bjam --v2`.
-
-# Copy the resulting `quickbook` binary (located under the
- `BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is
- `/usr/local/bin`.
-
-# Add the following to your `user-config.jam` file, using the full path of the
- quickbook executable:
-
- using quickbook
- : /usr/local/bin/quickbook
- ;
-
-[endsect]
-[endsect] [/Installation and configuration]
-
-[section:editors Editor Support]
-
-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.
-
-[blurb __note__ You may submit your settings, tips, and suggestions to the
-authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
-docs Boost Docs mailing list].]
-
-[section:scite Scintilla Text Editor]
-
-[:['Section contributed by Dean Michael Berris]]
-
-The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
-It uses the SCIntilla source code editing component.
-
-[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]
-
-You can use the following settings to highlight quickbook tags when
-editing quickbook files.
-
-[pre'''
-qbk=*.qbk
-lexer.*.qbk=props
-use.tabs.$(qbk)=0
-tab.size.$(qbk)=4
-indent.size.$(qbk)=4
-style.props.32=$(font.base)
-comment.stream.start.props=[/
-comment.stream.end.props=]
-comment.box.start.props=[/
-comment.box.middle.props=
-comment.box.end.props=]
-''']
-
-[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.]
-
-[endsect] [/scite]
-[endsect] [/editors]
-
-[section:faq Frequently Asked Questions]
-
-[heading Can I use QuickBook for non-Boost documentation?]
-
-QuickBook can be used for non-Boost documentation with a little extra work.
-
-[:['Faq contributed by Michael Marcin]]
-
-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.
-
-For example:
-[pre
-using quickbook ;
-
-xml my_doc : my_doc.qbk ;
-
-boostbook standalone
- :
- my_doc
- :
- <xsl:param>boost.image.src=images/my_project_logo.png
- <xsl:param>boost.image.alt="\\"My Project\\""
- <xsl:param>boost.image.w=100
- <xsl:param>boost.image.h=50
- <xsl:param>nav.layout=none
- ;
-]
-
-[endsect] [/faq]
-
-[section:ref Quick Reference]
-
-[cpp]
-
-[template ordered_list_sample[]
-[pre'''
-# one
-# two
-# three
-''']
-]
-
-[template unordered_list_sample[]
-[pre'''
-* one
-* two
-* three
-''']
-]
-
-[template table_sample[]
-[pre'''
-[table Title
-[[a][b][c]]
-[[a][b][c]]
-]
-''']
-]
-
-[template var_list_sample[]
-[pre'''
-[variablelist Title
-[[a][b]]
-[[a][b]]
-]
-''']
-]
-
-
-[table Syntax Compendium
- [[To do this...] [Use this...] [See this...]]
- [[comment] [[^'''[/ some comment]''']] [__comments__]]
- [[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]]
- [[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]]
- [[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]]
- [[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]]
- [[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]]
- [[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]]
- [[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]]
- [[inline code] [[^'''`int main();`''']] [__inline_code__]]
- [[code block] [[^'''``int main();``''']] [__code__]]
- [[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]]
- [[line break] [[^'''[br] or \n''']] [__line_break__ *DEPRECATED*]]
- [[anchor] [[^'''[#anchor]''']] [__anchors__]]
- [[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]]
- [[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]]
- [[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]]
- [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]]
- [[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]]
- [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]]
- [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]]
- [[macro link] [[^'''[macroref MACRO_NAME Link text]''']] [__code_links__]]
- [[concept link] [[^'''[conceptref ConceptName Link text]''']] [__code_links__]]
- [[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]]
- [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]]
- [[single char escape] [[^\\c]] [__single_char_escape__]]
- [[images] [[^'''[$image.jpg]''']] [__images__]]
- [[begin section] [[^'''[section The Section Title]''']] [__section__]]
- [[end section] [[^'''[endsect]''']] [__section__]]
- [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]]
- [[ordered list] [[ordered_list_sample]] [__ordered_lists__]]
- [[unordered list] [[unordered_list_sample]] [__unordered_lists__]]
- [[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]]
- [[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]]
- [[block quote] [[^'''[:sometext...]''']] [__blockquote__]]
- [[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]]
- [[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]]
- [[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]]
- [[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]]
- [[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]]
- [[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]]
- [[macro] [[^'''[def macro_identifier some text]''']] [__macros__]]
- [[template] [[^'''[template[a b] [a] body [b]]''']] [__templates__]]
- [[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]]
- [[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]]
- [[table] [[table_sample]] [__tables__]]
- [[variablelist] [[var_list_sample]] [__variable_lists__]]
- [[include] [[^'''[include someother.qbk]''']] [__include__]]
-]
-
-[endsect]
+[article Quickbook
+ [quickbook 1.4]
+ [version 1.4]
+ [authors [de Guzman, Joel], [Niebler, Eric]]
+ [copyright 2002 2004 2006 Joel de Guzman, Eric Niebler]
+ [purpose /WikiWiki/ style documentation tool]
+ [license
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ [@http://www.boost.org/LICENSE_1_0.txt])
+ ]
+]
+
+[/ QuickBook Document version 1.3 ]
+[/ Sept 24, 2002 ]
+[/ Sept 2, 2004 ]
+[/ Feb 14, 2005 ]
+[/ Sept 13, 2005 ]
+
+[/ Some links]
+
+[def __note__ [$images/note.png]]
+[def __alert__ [$images/alert.png]]
+[def __tip__ [$images/tip.png]]
+[def :-) [$images/smiley.png]]
+[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
+[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
+[def __docbook__ [@http://www.docbook.org/ DocBook]]
+
+[def __comments__ [link quickbook.syntax.comments Comments]]
+
+[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]]
+[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]]
+[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]]
+[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
+[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]]
+[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]]
+[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]]
+[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]]
+[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]]
+[def __links__ [link quickbook.syntax.phrase.links Links]]
+[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]]
+[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]]
+[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
+[def __escape__ [link quickbook.syntax.phrase.escape Escape]]
+[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
+[def __images__ [link quickbook.syntax.phrase.images Images]]
+
+[def __document__ [link quickbook.syntax.block.document Document]]
+[def __section__ [link quickbook.syntax.block.section Section]]
+[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]]
+[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]]
+[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
+[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
+[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
+[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
+[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
+[def __code__ [link quickbook.syntax.block.code Code]]
+[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
+[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]]
+[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]]
+[def __heading__ [link quickbook.syntax.block.headings Heading]]
+[def __macros__ [link quickbook.syntax.block.macros Macros]]
+[def __templates__ [link quickbook.syntax.block.templates Templates]]
+[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]]
+[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]]
+[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]]
+[def __tables__ [link quickbook.syntax.block.tables Tables]]
+[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]]
+[def __include__ [link quickbook.syntax.block.include Include]]
+[def __import__ [link quickbook.syntax.block.import Import]]
+
+[section:intro Introduction]
+
+[:[*['["Why program by hand in five days what you can spend five years of your
+life automating?]]]
+
+-- Terrence Parr, author ANTLR/PCCTS
+]
+
+Well, QuickBook started as a weekend hack. It was originally intended to be a
+sample application using __spirit__. What is it? What you are viewing now, this
+documentation, is autogenerated by QuickBook. These files were generated from
+one master:
+
+[:[@../quickbook.qbk quickbook.qbk]]
+
+Originally named QuickDoc, this funky tool that never dies evolved into a
+funkier tool thanks to Eric Niebler who resurrected the project making it
+generate __boostbook__ instead of HTML. The __boostbook__ documentation format
+is an extension of __docbook__, an SGML or XML based format for describing
+documentation.
+
+QuickBook is a WikiWiki style documentation tool geared towards C++
+documentation using simple rules and markup for simple formatting tasks.
+QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are
+simple text files. A single QuickBook document can generate a fully linked set
+of nice HTML and PostScript/PDF documents complete with images and syntax-
+colorized source code.
+
+Features include:
+
+* generate __boostbook__ xml, to generate HTML, PostScript and PDF
+* simple markup to link to Doxygen-generated entities
+* macro system for simple text substitution
+* simple markup for italics, bold, preformatted, blurbs, code samples,
+ tables, URLs, anchors, images, etc.
+* automatic syntax coloring of code samples
+* CSS support
+
+[endsect]
+
+[section:change_log Change Log]
+
+[h3 Version 1.3]
+
+* Quickbook file inclusion \[include\].
+* Better xml output (pretty layout). Check out the generated XML.
+* Regression testing facility: to make sure your document will always be
+ compatible (full backward compatibility) regardless of changes to
+ QuickBook.
+* Code cleanup and refactoring.
+* Allow phrase markup in the doc-info.
+* Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
+ and lists, for example.
+* Quickbook versioning; allows full backward compatibility. You have to add
+ \[quickbook 1.3\] to the doc-info header to enable the new features. Without
+ this, QuickBook will assume that the document is a pre-1.3 document.
+* Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
+ Example:``
+ [section x]
+ blah...
+ [endsect]``
+* Fully qualified section and headers. Subsection names are concatenated to the
+ ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
+* Better and whitespace handling in code snippets.
+* \[xinclude\] fixes up the relative path to the target XML file when
+ input_directory is not the same as the output_directory.
+* Allow untitled tables.
+* Allow phrase markups in section titles.
+* Allow escaping back to QuickBook from code, code blocks and inline code.
+* Footnotes, with the \[footnote This is the footnote\] syntax.
+* Post-processor bug fix for escaped XML code that it does not recognize.
+* Replaceable, with the \[~replacement\] syntax.
+* Generic Headers
+* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
+* Various code cleanup/maintenance
+* Templates!
+* \[conceptref\] for referencing BoostBook <concept> entities.
+* Allow escape of spaces. The escaped space is removed from the output. Syntax:
+ `\ `.
+* Nested comments are now allowed.
+* Quickbook blocks can nest inside comments.
+* __import__ facility.
+* Callouts on imported code
+* Simple markups can now span a whole block.
+* __blurbs__, __admonitions__ and table cells (see __tables__) may now
+ contain paragraphs.
+* `\n` and `[br]` are now deprecated.
+
+[endsect]
+
+[section:syntax Syntax Summary]
+
+A QuickBook document is composed of one or more blocks. An example of
+a block is the paragraph or a C++ code snippet. Some blocks have
+special mark-ups. Blocks, except code snippets which have their own
+grammar (C++ or Python), are composed of one or more phrases. A phrase
+can be a simple contiguous run of characters. Phrases can have special
+mark-ups. Marked up phrases can recursively contain other phrases, but
+cannot contain blocks. A terminal is a self contained block-level or
+phrase-level element that does not nest anything.
+
+Blocks, in general, are delimited by two end-of-lines (the block terminator).
+Phrases in each block cannot contain a block terminator. This way, syntax errors
+such as un-matched closing brackets do not go haywire and corrupt anything past
+a single block.
+
+[section Comments]
+
+Can be placed anywhere.
+
+[pre
+'''[/ comment (no output generated) ]'''
+]
+
+[/ for testing only... ]
+
+[pre
+'''[/ comments can be nested [/ some more here] ]'''
+]
+
+[/ for testing [/ only ] ]
+
+[pre
+'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
+]
+
+[/ for testing [*only ] ]
+
+[endsect]
+
+[section:phrase Phrase Level Elements]
+
+[section Font Styles]
+
+[pre'''
+['italic], [*bold], [_underline], [^teletype], [-strikethrough]
+''']
+
+will generate:
+
+['italic], [*bold], [_underline], [^teletype], [-strikethrough]
+
+Like all non-terminal phrase level elements, this can of course be nested:
+
+[pre'''
+[*['bold-italic]]
+''']
+
+will generate:
+
+[*['bold-italic]]
+
+[endsect]
+
+[section Replaceable]
+
+When you want content that may or must be replaced by the user, use the syntax:
+
+[pre'''
+[~replacement]
+''']
+
+This will generate:
+
+[~replacement]
+
+[endsect]
+
+[section Quotations]
+
+[pre'''
+["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
+''']
+
+will generate:
+
+["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
+
+Note the proper left and right quote marks. Also, while you can simply use
+ordinary quote marks like "quoted", our quotation, above, will generate correct
+DocBook quotations (e.g. <quote>quoted</quote>).
+
+Like all phrase elements, quotations may be nested. Example:
+
+[pre'''
+["Here's the rule for bargains: ["Do other men, for they would do you.] That's
+the true business precept.]
+''']
+
+will generate:
+
+["Here's the rule for bargains: ["Do other men, for they would do you.]
+That's the true business precept.]
+
+[endsect]
+[section Simple formatting]
+
+Simple markup for formatting text, common in many applications, is now supported:
+
+[pre'''
+/italic/, *bold*, _underline_, =teletype=
+''']
+
+will generate:
+
+/italic/, *bold*, _underline_, =teletype=
+
+Unlike QuickBook's standard formatting scheme, the rules for simpler
+alternatives are much stricter[footnote Thanks to David Barrett, author of
+[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing
+these samples and teaching me these obscure formatting rules. I wasn't sure
+at all if __spirit__, being more or less a formal EBNF parser, can handle
+the context sensitivity and ambiguity.].
+
+* Simple markups cannot nest. You can combine a simple markup with a nestable markup.
+* Simple markups cannot contain any other form of quickbook markup.
+* A non-space character must follow the leading markup
+* A non-space character must precede the trailing markup
+* A space or a punctuation must follow the trailing markup
+* If the matching markup cannot be found within a block, the formatting
+ will not be applied. This is to ensure that un-matched formatting markups,
+ which can be a common mistake, does not corrupt anything past a single block.
+ We do not want the rest of the document to be rendered bold just because we
+ forgot a trailing '*'. A single block is terminated by two end of lines or
+ the close bracket: ']'.
+* A line starting with the star will be interpreted as an unordered list.
+ See __unordered_lists__.
+
+[table More Formatting Samples
+ [[Markup] [Result]]
+ [[[^'''*Bold*''']] [*Bold*]]
+ [[[^'''*Is bold*''']] [*Is bold*]]
+ [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]]
+ [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]]
+ [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]]
+ [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]]
+ [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]]
+ [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]]
+ [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]]
+ [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]]
+ [[[^'''*This is bold*.''']] [*This is bold*.]]
+ [[[^'''*B*. (bold B)''']] [*B*. (bold B)]]
+ [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]]
+ [[[^'''*side-by*/-side/''']] [*side-by*/-side/]]
+]
+
+As mentioned, simple markups cannot go past a single block. The text
+from "have" to "full" in the following paragraph will be rendered as
+bold:
+
+[pre'''
+Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!*
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+''']
+
+Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!*
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+
+But in the following paragraph, bold is not applied:
+
+[pre'''
+Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+''']
+
+Baa baa black sheep, *have you any wool?
+Yes sir, yes sir, three bags full!
+One for the master, one for the dame,
+And one for the little boy who lives down the lane.
+
+[endsect]
+[section Inline code]
+
+Inlining code in paragraphs is quite common when writing C++ documentation. We
+provide a very simple markup for this. For example, this:
+
+[pre'''
+This text has inlined code `int main() { return 0; }` in it.
+''']
+
+will generate:
+
+This text has inlined code `int main() { return 0; }` in it. The code will be
+syntax highlighted.
+
+[note We simply enclose the code with the tick: [^'''"`"'''], not the
+single quote: `"'"`. Note too that [^'''`some code`'''] is preferred over
+[^'''[^some code]''']. ]
+
+[endsect]
+[section Code blocks]
+
+Preformatted code simply starts with a space or a tab (See __code__).
+However, such a simple syntax cannot be used as phrase elements in lists
+(See __ordered_lists__ and __unordered_lists__), tables (See __tables__),
+etc. Inline code (see above) can. The problem is, inline code does not
+allow formatting with newlines, spaces, and tabs. These are lost.
+
+We provide a phrase level markup that is a mix between the two. By using the
+double-tick, instead of the single-tick, we are telling QuickBook to use
+preformatted blocks of code. Example:
+
+[pre
+\`\`
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+\`\`
+]
+
+will generate:
+
+``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+``
+
+[endsect]
+[section Source Mode]
+
+If a document contains more than one type of source code then the source
+mode may be changed dynamically as the document is processed. All QuickBook
+documents are initially in C++ mode by default, though an alternative
+initial value may be set in the __document__ section.
+
+To change the source mode, use the [^\[source-mode\]] markup, where
+=source-mode= is one of the supported modes. For example, this:
+
+[pre'''
+Python's [python] `import` is rather like C++'s [c++] `#include`. A
+C++ comment `// looks like this` whereas a Python comment [python]
+`# looks like this`.
+''']
+
+will generate:
+
+Python's [python] `import` is rather like C++'s [c++] `#include`. A
+C++ comment `// looks like this` whereas a Python comment [python]
+`#looks like this`.
+
+[table Supported Source Modes
+ [[Mode] [Source Mode Markup]]
+ [[C++] [[^\[c++\]]]]
+ [[Python] [[^\[python\]]]]
+]
+
+[note The source mode strings are lowercase.]
+
+[endsect]
+[section line-break]
+
+[pre'''
+[br]
+''']
+
+[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
+table cells (see __tables__) may now contain paragraphs.]
+
+[endsect]
+[section Anchors]
+
+[pre'''
+[#named_anchor]
+''']
+
+A named anchor is a hook that can be referenced by a link elsewhere in the
+document. You can then reference an anchor with [^'''[link named_anchor
+Some link text]''']. See __anchor_links__, __section__ and __heading__.
+
+[endsect]
+[section Links]
+
+[pre'''
+[@http://www.boost.org this is [*boost's] website....]
+''']
+
+will generate:
+
+[@http://www.boost.org this is [*boost's] website....]
+
+URL links where the link text is the link itself is common. Example:
+
+[pre'''
+see http://spirit.sourceforge.net/
+''']
+
+so, when the text is absent in a link markup, the URL is assumed. Example:
+
+[pre
+see '''[@http://spirit.sourceforge.net/]'''
+]
+
+will generate:
+
+see [@http://spirit.sourceforge.net/]
+
+[endsect]
+[section Anchor links]
+
+You can link within a document using:
+
+[pre'''
+[link section_id.normalized_header_text The link text]
+''']
+
+See sections __section__ and __heading__ for more info.
+
+[endsect]
+[section refentry links]
+
+In addition, you can link internally to an XML refentry like:
+
+[pre'''
+[link xml.refentry The link text]
+''']
+
+This gets converted into [^<link linkend="xml.refentry">The link text</link>].
+
+Like URLs, the link text is optional. If this is not present, the link text will
+automatically be the refentry. Example:
+
+[pre'''
+[link xml.refentry]
+''']
+
+This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].
+
+[endsect]
+[section:code_links Code Links]
+
+If you want to link to a function, class, member, enum, concept or header in the reference
+section, you can use:
+
+[pre'''
+[funcref fully::qualified::function_name The link text]
+[classref fully::qualified::class_name The link text]
+[memberref fully::qualified::member_name The link text]
+[enumref fully::qualified::enum_name The link text]
+[macroref MACRO_NAME The link text]
+[conceptref ConceptName The link text]
+[headerref path/to/header.hpp The link text]
+''']
+
+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:
+
+[pre'''
+[classref boost::bar::baz]
+''']
+
+would have "boost::bar::baz" as the link text.
+
+[endsect]
+[section Escape]
+
+The escape mark-up is used when we don't want to do any processing.
+
+[pre
+\'\'\'
+escape (no processing/formatting)
+\'\'\'
+]
+
+Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example:
+
+[pre
+\'\'\'
+<emphasis role="bold">This is direct XML markup</emphasis>
+\'\'\'
+]
+
+'''
+<emphasis role="bold">This is direct XML markup</emphasis>
+'''
+
+[important Be careful when using the escape. The text must conform to
+__boostbook__/__docbook__ syntax.]
+
+[endsect]
+[section Single char escape]
+
+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 `[` and `]`.
+For example, how do you escape the triple quote? Simple: [^\\'\\'\\']
+
+
+`\n` has a special meaning. It is used to generate line breaks.
+
+[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
+and table cells (see __tables__) may now contain paragraphs.]
+
+The escaped space: `\ ` also has a special meaning. The escaped space is removed
+from the output.
+
+[endsect]
+[section Images]
+
+[pre'''
+[$image.jpg]
+''']
+
+[endsect]
+[section Footnotes]
+
+As of version 1.3, QuickBook supports footnotes. Just put the text of the
+footnote in a `[footnote]` block, and the text will be put at the bottom
+of the current page. For example, this:
+
+[pre'''
+[footnote A sample footnote]
+''']
+
+will generate this[footnote A sample footnote].
+
+[section Macro Expansion]
+
+[pre'''
+__a_macro_identifier__
+''']
+
+See __macros__ for details.
+
+[endsect]
+
+[section Template Expansion]
+
+[pre'''
+[a_template_identifier]
+''']
+
+See __templates__ for details.
+
+[endsect]
+
+[endsect]
+[endsect]
+[section:block Block Level Elements]
+
+[section Document]
+
+Every document must begin with a Document Info section, which should look
+like this:
+
+[pre'''
+[document-type The Document Title
+ [quickbook 1.3]
+ [version 1.0]
+ [id the_document_name]
+ [dirname the_document_dir]
+ [copyright 2000 2002 2003 Joe Blow, Jane Doe]
+ [purpose The document's reason for being]
+ [category The document's category]
+ [authors [Blow, Joe], [Doe, Jane]]
+ [license The document's license]
+ [source-mode source-type]
+]
+''']
+
+Where document-type is one of:
+
+* book
+* article
+* library
+* chapter
+* part
+* appendix
+* preface
+* qandadiv
+* qandaset
+* reference
+* set
+
+quickbook 1.3 declares the version of quickbook the document is written for.
+In its absence, version 1.1 is assumed.
+
+=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
+=license=, =last-revision= and =source-mode= are optional information.
+
+=source-type= is a lowercase string setting the initial __source_mode__. If
+the =source-mode= field is omitted, a default value of =c++= will be used.
+
+[endsect]
+[section Section]
+
+Starting a new section is accomplished with:
+
+[pre'''
+[section:id The Section Title]
+''']
+
+where /id/ is optional. id will be the filename of the generated section.
+If it is not present, "The Section Title" will be normalized and become the id.
+Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
+converted to underscore and all upper-case are converted to lower case.
+Thus: "The Section Title" will be normalized to "the_section_title".
+
+End a section with:
+
+[pre'''
+[endsect]
+''']
+
+Sections can nest, and that results in a hierarchy in the table of contents.
+
+[endsect]
+[section xinclude]
+
+You can include another XML file with:
+
+[pre'''
+[xinclude file.xml]
+''']
+
+This is useful when file.xml has been generated by Doxygen and contains your
+reference section.
+
+[endsect]
+[section Paragraphs]
+
+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.
+
+[endsect]
+
+[section Lists]
+[section Ordered lists]
+
+[pre
+# One
+# Two
+# Three
+]
+
+will generate:
+
+# One
+# Two
+# Three
+
+[endsect]
+[section List Hierarchies]
+
+List hierarchies are supported. Example:
+
+[pre
+# One
+# Two
+# Three
+ # Three.a
+ # Three.b
+ # Three.c
+# Four
+ # Four.a
+ # Four.a.i
+ # Four.a.ii
+# Five
+]
+
+will generate:
+
+# One
+# Two
+# Three
+ # Three.a
+ # Three.b
+ # Three.c
+# Fourth
+ # Four.a
+ # Four.a.i
+ # Four.a.ii
+# Five
+
+[endsect]
+[section Long List Lines]
+
+Long lines will be wrapped appropriately. Example:
+
+[pre
+# 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.
+ 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 short item.
+]
+
+# 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.
+ 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 short item.
+
+[endsect]
+[section Unordered lists]
+
+[pre'''
+* First
+* Second
+* Third
+''']
+
+will generate:
+
+* First
+* Second
+* Third
+
+[endsect]
+[section Mixed lists]
+
+Mixed lists (ordered and unordered) are supported. Example:
+
+[pre'''
+# One
+# Two
+# Three
+ * Three.a
+ * Three.b
+ * Three.c
+# Four
+''']
+
+will generate:
+
+# One
+# Two
+# Three
+ * Three.a
+ * Three.b
+ * Three.c
+# Four
+
+And...
+
+[pre'''
+# 1
+ * 1.a
+ # 1.a.1
+ # 1.a.2
+ * 1.b
+# 2
+ * 2.a
+ * 2.b
+ # 2.b.1
+ # 2.b.2
+ * 2.b.2.a
+ * 2.b.2.b
+''']
+
+will generate:
+
+# 1
+ * 1.a
+ # 1.a.1
+ # 1.a.2
+ * 1.b
+# 2
+ * 2.a
+ * 2.b
+ # 2.b.1
+ # 2.b.2
+ * 2.b.2.a
+ * 2.b.2.b
+
+[endsect]
+[endsect]
+
+[section Code]
+
+Preformatted code starts with a space or a tab. The code will be
+syntax highlighted according to the current __source_mode__:
+
+[c++]
+
+ #include <iostream>
+
+ int main()
+ {
+ // Sample code
+ std::cout << "Hello, World\n";
+ return 0;
+ }
+
+[python]
+
+ import cgi
+
+ def cookForHtml(text):
+ '''"Cooks" the input text for HTML.'''
+
+ return cgi.escape(text)
+
+[c++]
+
+Macros that are already defined are expanded in source code. Example:
+
+[pre'''
+[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__;
+''']
+
+Generates:
+
+[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__;
+
+[endsect]
+[section:escape_back Escaping Back To QuickBook]
+
+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 /escape-back/ delimiter. In C++ and Python, the delimiter
+is the double tick (back-quote): "\`\`" and "\`\`". Example:
+
+[pre'''
+void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
+{
+}
+''']
+
+Will generate:
+
+ void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
+ {
+ }
+
+When escaping from code to QuickBook, only phrase level markups are
+allowed. Block level markups like lists, tables etc. are not allowed.
+
+[endsect]
+[section Preformatted]
+
+Sometimes, you don't want some preformatted text to be parsed as C++. In such
+cases, use the [^[pre ... \]] markup block.
+
+[pre'''
+[pre
+
+ Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+]
+''']
+
+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:
+
+[pre
+
+Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+ Some *preformatted* text Some *preformatted* text
+
+]
+
+Notice that unlike Code, phrase markup such as font style is still permitted
+inside =pre= blocks.
+
+[endsect]
+[section Blockquote]
+
+[pre
+'''[:sometext...]'''
+]
+
+[:Indents the paragraph. This applies to one paragraph only.]
+
+[endsect]
+[section Admonitions]
+
+[pre'''
+[note This is a note]
+[tip This is a tip]
+[important This is important]
+[caution This is a caution]
+[warning This is a warning]
+''']
+
+generates __docbook__ admonitions:
+
+[note This is a note]
+[tip This is a tip]
+[important This is important]
+[caution This is a caution]
+[warning This is a warning]
+
+These are the only admonitions supported by __docbook__. So,
+for example [^\[information This is some information\]] is unlikely
+to produce the desired effect.
+
+[endsect]
+[section Headings]
+
+[pre'''
+[h1 Heading 1]
+[h2 Heading 2]
+[h3 Heading 3]
+[h4 Heading 4]
+[h5 Heading 5]
+[h6 Heading 6]
+''']
+
+[h1 Heading 1]
+[h2 Heading 2]
+[h3 Heading 3]
+[h4 Heading 4]
+[h5 Heading 5]
+[h6 Heading 6]
+
+Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with normalized
+names with [^name="section_id.normalized_header_text"] (i.e. valid characters are
+=a-z=, =A-Z=, =0-9= and =_=. 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 [^section_2.heading_1]). You can use:
+
+[pre'''
+[link section_id.normalized_header_text The link text]
+''']
+
+to link to them. See __anchor_links__ and __section__ for more info.
+
+[endsect]
+[section Generic Heading]
+
+In cases when you don't want to care about the heading level (1 to 6), you
+can use the /Generic Heading/:
+
+[pre'''
+[heading Heading]
+''']
+
+The /Generic Heading/ 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 /h2/.
+
+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:
+
+[pre'''
+[section A]
+[h2 X]
+[h2 Y]
+[h2 Z]
+[endsect]
+''']
+
+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:
+
+[pre'''
+[section A]
+[heading X]
+[heading Y]
+[heading Z]
+[endsect]
+''']
+
+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 /section/ and /heading/, you have all you need. /h1/../h6/ becomes
+redundant. /h1/../h6/ might be deprecated in the future.
+
+[endsect]
+[section Macros]
+
+[pre'''
+[def macro_identifier some text]
+''']
+
+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:
+
+[pre'''
+[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
+sf_logo
+''']
+
+Now everywhere the sf_logo is placed, the picture will be inlined.
+
+[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
+sf_logo
+
+[tip 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. [^'''__spirit__''']). The reason is to avoid
+unwanted macro replacement.]
+
+Links (URLS) and images are good candidates for macros. *1*) 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. *2*) The syntax is not pretty. It's easier to read and
+write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]'''].
+
+Some more examples:
+
+[pre'''
+[def :-) [$theme/smiley.png]]
+[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
+''']
+
+(See __images__ and __links__)
+
+Invoking these macros:
+
+[pre'''
+Hi __spirit__ :-)
+''']
+
+will generate this:
+
+Hi __spirit__ :-)
+
+[endsect]
+[section Predefined Macros]
+
+Quickbook has some predefined macros that you can already use.
+
+[table Predefined Macros
+ [[Macro] [Meaning] [Example]]
+ [['''__DATE__'''] [Today's date] [__DATE__]]
+ [['''__TIME__'''] [The current time] [__TIME__]]
+ [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]]
+]
+
+[endsect]
+[section Templates]
+
+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).
+
+Example template:
+
+[pre'''
+[template person[name age what]
+
+Hi, my name is [name]. I am [age] years old. I am a [what].
+
+]
+''']
+
+[template person[name age what]
+
+Hi, my name is [name]. I am [age] years old. I am a [what].
+
+]
+
+[heading Template Identifier]
+
+Template identifiers can either consist 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.
+* A single character punctuation (a non-alphanumeric printable character)
+
+[heading Formal Template Arguments]
+
+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.
+
+A template formal argument temporarily hides a template of the same name at
+the point where the [link quickbook.syntax.block.templates.template_expansion
+template is expanded]. Note that the body of the [^person] template above
+refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
+[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
+in the duration of the template call.
+
+[heading Template Body]
+
+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:
+
+[pre'''
+[template sample[arg1 arg2...argN] replacement text... ]
+''']
+
+Block templates are of the form:
+
+[pre'''
+[template sample[arg1 arg2...argN]
+replacement text...
+]
+''']
+
+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.
+
+[heading Template Expansion]
+
+You expand a template this way:
+
+[pre'''
+[template_identifier arg1..arg2..arg3]
+''']
+
+At template expansion, you supply the actual arguments. The template will
+be expanded with your supplied arguments. Example:
+
+[pre'''
+[person James Bond..39..Spy]
+[person Santa Clause..87..Big Red Fatso]
+''']
+
+Which will expand to:
+
+[person James Bond..39..Spy]
+[person Santa Clause..87..Big Red Fatso]
+
+[caution 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.]
+
+Each actual argument can be a word, a text fragment or just about any [link
+quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
+double dot [^".."] and terminated by the close parenthesis.
+
+[heading Nullary Templates]
+
+Nullary templates look and act like simple macros. Example:
+
+[pre'''
+[template alpha[]'''&#945;''']
+[template beta[]'''&#946;''']
+''']
+
+[template alpha[]'''α''']
+[template beta[]'''β''']
+
+Expanding:
+
+[pre'''Some squigles...[*[alpha][beta]]''']
+
+We have:
+
+Some squiggles...[*[alpha][beta]]
+
+The difference with macros are
+
+* The explicit [link quickbook.syntax.block.templates.template_expansion
+ template expansion syntax]. 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.
+* 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.
+
+The empty brackets after the template identifier ([^alpha\[\]]) indicates no
+arguments. If the template body does not look like a template argument list, we
+can elide the empty brackets. Example:
+
+[pre'''
+[template aristotle_quote Aristotle: [*['Education is the best provision
+for the journey to old age.]]]
+''']
+
+[template aristotle_quote\ Aristotle: [*['Education is the best provision
+for the journey to old age.]]]
+
+Expanding:
+
+[pre'''
+Here's a quote from [aristotle_quote].
+''']
+
+We have:
+
+Here's a quote from [aristotle_quote].
+
+The disadvantage is that you can't avoid the space between the template
+identifier, `aristotle_quote`, and the template body "Aristotle...". This space
+will be part of the template body. If that space is unwanted, use empty
+brackets or use the space escape: "`\ `". Example:
+
+[pre'''
+[template tag\ _tag]
+''']
+
+[template tag\ _tag]
+
+Then expanding:
+
+[pre'''
+`struct` x[tag];
+''']
+
+We have:
+
+`struct` x[tag];
+
+You have a couple of ways to do it. I personally prefer the explicit empty
+brackets, though.
+
+[heading Simple Arguments]
+
+As mentioned, arguments are separated by the double dot [^".."]. If there
+are less arguments passed than expected, QuickBook attempts to break the
+last argument into two or more arguments following this logic:
+
+* Break the last argument into two, at the first space found ([^'', '\\n',
+ \\t' or '\\r']).
+* Repeat until there are enough arguments or if there are no more spaces
+ found (in which case, an error is reported).
+
+For example:
+
+[pre'''
+[template simple[a b c d] [a][b][c][d]]
+[simple w x y z]
+''']
+
+will produce:
+
+[template simple[a b c d] [a][b][c][d]]
+[simple w x y z]
+
+"w x y z" is initially treated as a single argument because we didn't
+supply any [^".."] separators. However, since [^simple] expects 4
+arguments, "w x y z" is broken down iteratively (applying the logic above)
+until we have "w", "x", "y" and "z".
+
+QuickBook only tries to get the arguments it needs. For example:
+
+[pre'''
+[simple w x y z trail]
+''']
+
+will produce:
+
+[simple w x y z trail]
+
+The arguments being: "w", "x", "y" and "z trail".
+
+It should be obvious now that for simple arguments with no spaces, we can
+get by without separating the arguments with [^".."] separators. It is
+possible to combine [^".."] separators with the argument passing
+simplification presented above. Example:
+
+[pre'''
+[simple what do you think ..m a n?]
+''']
+
+will produce:
+
+[simple what do you think ..m a n?]
+
+[heading Punctuation Templates]
+
+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 quickbook.syntax.block.templates.template_identifier
+template identifiers]. Example:
+
+[pre'''
+[template ![bar] '''<hey>'''[bar]'''</hey>''']
+''']
+
+Now, expanding this:
+
+[pre'''
+[!baz]
+''']
+
+We will have:
+
+[pre
+<hey>baz</hey>
+]
+
+[endsect]
+[section Blurbs]
+
+[pre'''
+[blurb :-) [*An eye catching advertisement or note...]
+
+ __spirit__ 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++.
+]
+''']
+
+will generate this:
+
+[blurb :-) [*An eye catching advertisement or note...]
+
+ __spirit__ 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++.
+]
+
+[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
+appropriate.]
+
+[endsect]
+[section Tables]
+
+[pre'''
+[table A Simple Table
+ [[Heading 1] [Heading 2] [Heading 3]]
+ [[R0-C0] [R0-C1] [R0-C2]]
+ [[R1-C0] [R1-C1] [R1-C2]]
+ [[R2-C0] [R2-C1] [R2-C2]]
+]
+''']
+
+will generate:
+
+[table A Simple Table
+ [[Heading 1] [Heading 2] [Heading 3]]
+ [[R0-C0] [R0-C1] [R0-C2]]
+ [[R2-C0] [R2-C1] [R2-C2]]
+ [[R3-C0] [R3-C1] [R3-C2]]
+]
+
+The table title is optional. The first row of the table is automatically
+treated as the table header; that is, it is wrapped in
+[^<thead>...</thead>] 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:
+
+[pre'''
+[table Table with fat cells
+ [[Heading 1] [Heading 2]]
+ [
+ [Row 0, Col 0: a small cell]
+ [
+ Row 0, Col 1: a big fat cell with paragraphs
+
+ Boost provides free peer-reviewed portable C++ source libraries.
+
+ 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.
+ ]
+ ]
+ [
+ [Row 1, Col 0: a small cell]
+ [Row 1, Col 1: a small cell]
+ ]
+]
+''']
+
+and thus:
+
+[table Table with fat cells
+ [[Heading 1] [Heading 2]]
+ [
+ [Row 0, Col 0: a small cell]
+ [
+ Row 0, Col 1: a big fat cell with paragraphs
+
+ Boost provides free peer-reviewed portable C++ source libraries.
+
+ 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.
+ ]
+ ]
+ [
+ [Row 1, Col 0: a small cell]
+ [Row 1, Col 1: a small cell]
+ ]
+]
+
+Here's how to have preformatted blocks of code in a table cell:
+
+[pre'''
+[table Table with code
+ [[Comment] [Code]]
+ [
+ [My first program]
+ ['''\`\`
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+ \`\`''']
+ ]
+]
+''']
+
+[table Table with code
+ [[Comment] [Code]]
+ [
+ [My first program]
+ [``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+ ``]
+ ]
+]
+
+[endsect]
+[section Variable Lists]
+
+[pre'''
+[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]]
+]
+''']
+
+will generate:
+
+[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]]
+]
+
+The rules for variable lists are the same as for tables, except that
+only 2 "columns" are allowed. The first column contains the terms, and
+the second column contains the definitions. Those familiar with HTML
+will recognize this as a "definition list".
+
+[endsect]
+[section Include]
+
+You can include one QuickBook file from another. The syntax is simply:
+
+[pre'''
+[include someother.qbk]
+''']
+
+The included file will be processed as if it had been cut and pasted
+into the current document, with the following exceptions:
+
+* The '''__FILENAME__''' predefined macro will reflect the name of the
+ file currently being processed.
+* Any macros defined in the included file are scoped to that file.
+
+The [^\[include\]] 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 ("someother", in the example above). You can specify the id
+like this:
+
+[pre'''
+[include:someid someother.qbk]
+''']
+
+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 "Intro", the
+named anchor for that section will be "someid.intro", and you can link to
+it with [^\[link someid.intro The Intro\]].
+
+[endsect]
+
+[section Import]
+
+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.
+
+QuickBook's import facility provides a nice solution.
+
+[heading Example]
+
+You can effortlessly import code snippets from source code into your QuickBook.
+The following illustrates how this is done:
+
+[pre'''
+[import ../test/stub.cpp]
+[foo]
+[bar]
+''']
+
+The first line:
+
+[pre'''
+[import ../test/stub.cpp]
+''']
+
+collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp]
+and places them in your QuickBook file as virtual templates. Each of the
+specially marked-up code snippets has a name (e.g. `foo` and `bar` 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:
+
+[pre'''
+[foo]
+[bar]
+''']
+
+And the result is:
+
+[import ../test/stub.cpp]
+[foo]
+[bar]
+
+[heading Code Snippet Markup]
+
+Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We
+use distinguishable comments following the form:
+
+ //[id
+ some code here
+ //]
+
+The first comment line above initiates a named code-snippet. This prefix will
+not be visible in quickbook. The entire code-snippet in between `//[id` and
+`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
+`//]` ends a code-snippet This too will not be visible in quickbook.
+
+[heading Special Comments]
+
+Special comments of the form:
+
+ //` some [*quickbook] markup here
+
+and:
+
+ /*` some [*quickbook] markup here */
+
+will be parsed by QuickBook. This can contain quickbook /blocks/ (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.
+
+[heading Callouts]
+
+Special comments of the form:
+
+ /*< some [*quickbook] markup here >*/
+
+will be regarded as callouts. These will be collected, numbered and
+rendered as a "callout bug" (a small icon with a number). After the
+whole snippet is parsed, the callout list is generated. See
+[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
+Example:
+
+[foo_bar]
+
+Checkout [@../../test/stub.cpp stub.cpp] to see the actual code.
+
+[endsect]
+
+[endsect]
+[endsect]
+
+[section:install Installation and configuration]
+
+This section provides some guidelines on how to install and configure
+BoostBook and Quickbook under several operating systems.
+
+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 `bin` and `bin.v2` directories generated
+by the build before trying again. Otherwise your configuration fixes will
+not take any effect.
+
+[section:windows Windows 2000, XP, 2003, Vista]
+
+[python]
+
+[:['Section contributed by Julio M. Merino Vidal]]
+
+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.
+
+# First of all you need to have a copy of `xsltproc` for Windows. There
+ are many ways to get this tool, but to keep things simple, use the
+ [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
+ Zlatkovic. At the very least, you need to download the following
+ packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
+
+# Unpack all these packages in the same directory so that you get unique
+ `bin`, `include` and `lib` directories within the hierarchy. These
+ instructions use `C:\Users\example\Documents\boost\xml` as the root for
+ all files.
+
+# From the command line, go to the `bin` directory and launch
+ `xsltproc.exe` to ensure it works. You should get usage information on
+ screen.
+
+# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
+ 4.2] and unpack it in the same directory used above. That is:
+ `C:\Users\example\Documents\boost\xml\docbook-xml`.
+
+# Download the latest
+ [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
+ Docbook XSL] version and unpack it, again in the same directory
+ used before. To make things easier, rename the directory created
+ during the extraction to `docbook-xsl` (bypassing the version name):
+ `C:\Users\example\Documents\boost\xml\docbook-xsl`.
+
+# Add the following to your `user-config.jam` file, which should live in
+ your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it
+ somewhere or otherwise you could not be building Boost (i.e. missing
+ tools configuration).
+
+ using xsltproc
+ : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
+ ;
+
+ using boostbook
+ : "C:/Users/example/Documents/boost/xml/docbook-xsl"
+ : "C:/Users/example/Documents/boost/xml/docbook-xml"
+ ;
+
+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:
+
+# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
+
+# Build the utility by issuing `bjam --v2`.
+
+# Copy the resulting `quickbook.exe` binary (located under the
+ `BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous
+ example, you can install it into:
+ `C:\Users\example\Documents\boost\xml\bin`.
+
+# Add the following to your `user-config.jam` file:
+
+ using quickbook
+ : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
+ ;
+
+[endsect]
+
+[section:linux Debian, Ubuntu]
+
+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.
+
+First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
+For example, using `apt-get`:
+
+ sudo apt-get install xsltprc docbook-xsl docbook-xml
+
+If you're planning on building boost's documentation, you'll also need to
+install the `doxygen` package as well.
+
+Next, we need to configure Boost Build to compile BoostBook files. Add the
+following to your `user-config.jam` 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 `user-config.jam`, see the
+[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
+Build documentation].
+
+ using xsltproc ;
+
+ using boostbook
+ : /usr/share/xml/docbook/stylesheet/nwalsh
+ : /usr/share/xml/docbook/schema/dtd/4.2
+ ;
+
+ # Remove this line if you're not using doxygen
+ using doxygen ;
+
+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:
+
+# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
+
+# Build the utility by issuing `bjam --v2`.
+
+# Copy the resulting `quickbook` binary (located under the
+ `BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is
+ `/usr/local/bin`.
+
+# Add the following to your `user-config.jam` file, using the full path of the
+ quickbook executable:
+
+ using quickbook
+ : /usr/local/bin/quickbook
+ ;
+
+[endsect]
+[endsect] [/Installation and configuration]
+
+[section:editors Editor Support]
+
+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.
+
+[blurb __note__ You may submit your settings, tips, and suggestions to the
+authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
+docs Boost Docs mailing list].]
+
+[section:scite Scintilla Text Editor]
+
+[:['Section contributed by Dean Michael Berris]]
+
+The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
+It uses the SCIntilla source code editing component.
+
+[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]
+
+You can use the following settings to highlight quickbook tags when
+editing quickbook files.
+
+[pre'''
+qbk=*.qbk
+lexer.*.qbk=props
+use.tabs.$(qbk)=0
+tab.size.$(qbk)=4
+indent.size.$(qbk)=4
+style.props.32=$(font.base)
+comment.stream.start.props=[/
+comment.stream.end.props=]
+comment.box.start.props=[/
+comment.box.middle.props=
+comment.box.end.props=]
+''']
+
+[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.]
+
+[endsect] [/scite]
+[endsect] [/editors]
+
+[section:faq Frequently Asked Questions]
+
+[heading Can I use QuickBook for non-Boost documentation?]
+
+QuickBook can be used for non-Boost documentation with a little extra work.
+
+[:['Faq contributed by Michael Marcin]]
+
+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.
+
+For example:
+[pre
+using quickbook ;
+
+xml my_doc : my_doc.qbk ;
+
+boostbook standalone
+ :
+ my_doc
+ :
+ <xsl:param>boost.image.src=images/my_project_logo.png
+ <xsl:param>boost.image.alt="\\"My Project\\""
+ <xsl:param>boost.image.w=100
+ <xsl:param>boost.image.h=50
+ <xsl:param>nav.layout=none
+ ;
+]
+
+[endsect] [/faq]
+
+[section:ref Quick Reference]
+
+[cpp]
+
+[template ordered_list_sample[]
+[pre'''
+# one
+# two
+# three
+''']
+]
+
+[template unordered_list_sample[]
+[pre'''
+* one
+* two
+* three
+''']
+]
+
+[template table_sample[]
+[pre'''
+[table Title
+[[a][b][c]]
+[[a][b][c]]
+]
+''']
+]
+
+[template var_list_sample[]
+[pre'''
+[variablelist Title
+[[a][b]]
+[[a][b]]
+]
+''']
+]
+
+
+[table Syntax Compendium
+ [[To do this...] [Use this...] [See this...]]
+ [[comment] [[^'''[/ some comment]''']] [__comments__]]
+ [[['italics]] [[^'''['italics] or /italics/''']] [__font_styles__ and __simple_formatting__]]
+ [[[*bold]] [[^'''[*bold] or *bold*''']] [__font_styles__ and __simple_formatting__]]
+ [[[_underline]] [[^'''[_underline] or _underline_''']] [__font_styles__ and __simple_formatting__]]
+ [[[^teletype]] [[^'''[^teletype] or =teletype=''']] [__font_styles__ and __simple_formatting__]]
+ [[[-strikethrough]] [[^'''[-strikethrough]''']] [__font_styles__ and __simple_formatting__]]
+ [[[~replaceable]] [[^'''[~replaceable]''']] [__replaceable__]]
+ [[source mode] [[^\[c++\]] or [^\[python\]]] [__source_mode__]]
+ [[inline code] [[^'''`int main();`''']] [__inline_code__]]
+ [[code block] [[^'''``int main();``''']] [__code__]]
+ [[code escape] [[^'''``from c++ to QuickBook``''']] [__escape_back__]]
+ [[line break] [[^'''[br] or \n''']] [__line_break__ *DEPRECATED*]]
+ [[anchor] [[^'''[#anchor]''']] [__anchors__]]
+ [[link] [[^'''[@http://www.boost.org Boost]''']] [__links__]]
+ [[anchor link] [[^'''[link section.anchor Link text]''']] [__anchor_links__]]
+ [[refentry link] [[^'''[link xml.refentry Link text]''']] [__refentry_links__]]
+ [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']] [__code_links__]]
+ [[class link] [[^'''[classref fully::qualified::class_name Link text]''']] [__code_links__]]
+ [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']] [__code_links__]]
+ [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']] [__code_links__]]
+ [[macro link] [[^'''[macroref MACRO_NAME Link text]''']] [__code_links__]]
+ [[concept link] [[^'''[conceptref ConceptName Link text]''']] [__code_links__]]
+ [[header link] [[^'''[headerref path/to/header.hpp Link text]''']] [__code_links__]]
+ [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']] [__escape__]]
+ [[single char escape] [[^\\c]] [__single_char_escape__]]
+ [[images] [[^'''[$image.jpg]''']] [__images__]]
+ [[begin section] [[^'''[section The Section Title]''']] [__section__]]
+ [[end section] [[^'''[endsect]''']] [__section__]]
+ [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.] [__paragraphs__]]
+ [[ordered list] [[ordered_list_sample]] [__ordered_lists__]]
+ [[unordered list] [[unordered_list_sample]] [__unordered_lists__]]
+ [[code] [No markup. Preformatted code starts with a space or a tab.] [__code__]]
+ [[preformatted] [[^'''[pre preformatted]''']] [__preformatted__]]
+ [[block quote] [[^'''[:sometext...]''']] [__blockquote__]]
+ [[heading 1] [[^'''[h1 Heading 1]''']] [__heading__]]
+ [[heading 2] [[^'''[h2 Heading 2]''']] [__heading__]]
+ [[heading 3] [[^'''[h3 Heading 3]''']] [__heading__]]
+ [[heading 4] [[^'''[h4 Heading 4]''']] [__heading__]]
+ [[heading 5] [[^'''[h5 Heading 5]''']] [__heading__]]
+ [[heading 6] [[^'''[h6 Heading 6]''']] [__heading__]]
+ [[macro] [[^'''[def macro_identifier some text]''']] [__macros__]]
+ [[template] [[^'''[template[a b] [a] body [b]]''']] [__templates__]]
+ [[blurb] [[^'''[blurb advertisement or note...]''']] [__blurbs__]]
+ [[admonition] [[^'''[warning Warning text...]''']] [__admonitions__]]
+ [[table] [[table_sample]] [__tables__]]
+ [[variablelist] [[var_list_sample]] [__variable_lists__]]
+ [[include] [[^'''[include someother.qbk]''']] [__include__]]
+]
+
+[endsect]