<?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>
    <author>
      <firstname>Joel</firstname> <surname>de Guzman</surname>
    </author>
    <author>
      <firstname>Eric</firstname> <surname>Niebler</surname>
    </author>
    <copyright>
      <year>2002</year> <year>2004</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</ulink>)
      </para>
    </legalnotice>
    <articlepurpose>
      <emphasis>WikiWiki</emphasis> style documentation tool
    </articlepurpose>
  </articleinfo>
  <title>quickbook 1.3</title>
  <section id="quickbook.intro">
    <title> Introduction</title>
    <blockquote>
      <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><sbr/>
        <sbr/> -- Terrence Parr, author ANTLR/PCCTS
      </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>
        <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
      </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> Change Log</title> <anchor id="quickbook.change_log.version_1_3" />
    <bridgehead renderas="sect3">
      Version 1.3
    </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>&nbsp;<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 &amp;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>
    </itemizedlist>
  </section>
  <section id="quickbook.syntax">
    <title> Syntax Summary</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>Comments</title>
      <para>
        Can be placed anywhere.
      </para>
      
<programlisting>[/ comment (no output generated) ]
</programlisting>
    </section>
    <section id="quickbook.syntax.phrase">
      <title> Phrase Level Elements</title>
      <section id="quickbook.syntax.phrase.font_styles">
        <title>Font Styles</title> 
<programlisting>['italic], [*bold], [_underline], [^teletype], [-strikethrough]
</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>[*['bold-italic]]
</programlisting>
        <para>
          will generate:
        </para>
        <para>
          <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.quotations">
        <title>Quotations</title> 
<programlisting>["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
</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 &quot;quoted&quot;, our quotation, above,
          will generate correct DocBook quotations (e.g. &lt;quote&gt;quoted&lt;/quote&gt;).
        </para>
        <para>
          Like all phrase elements, quotations may be nested. Example:
        </para>
        
<programlisting>["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]
</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>Simple formatting</title>
        <para>
          Simple markup for formatting text, common in many applications, is now
          supported:
        </para>
        
<programlisting>/italic/, *bold*, _underline_, =teletype=
</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.
        </para>
        <itemizedlist>
          <listitem>
            Simple markups cannot nest. You can combine a simple markup with a nestable
            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 line, 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
            line. We do not want the rest of the document to be rendered bold just
            because we forgot a trailing '*'.
          </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>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">More Formatting Samples</phrase>
          </bridgehead>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Markup</entry><entry>Result</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><literal>*Bold*</literal></entry><entry><emphasis role="bold">Bold</emphasis></entry>
              </row>
              <row>
                <entry><literal>*Is bold*</literal></entry><entry><emphasis role="bold">Is
                bold</emphasis></entry>
              </row>
              <row>
                <entry><literal>* Not bold* *Not bold * * Not bold *</literal></entry><entry>*
                Not bold* *Not bold * * Not bold *</entry>
              </row>
              <row>
                <entry><literal>This*Isn't*Bold (no bold)</literal></entry><entry>This*Isn't*Bold
                (no bold)</entry>
              </row>
              <row>
                <entry><literal>(*Bold Inside*) (parenthesis not bold)</literal></entry><entry>(<emphasis
                role="bold">Bold Inside</emphasis>) (parenthesis not bold)</entry>
              </row>
              <row>
                <entry><literal>*(Bold Outside)* (parenthesis bold)</literal></entry><entry><emphasis
                role="bold">(Bold Outside)</emphasis> (parenthesis bold)</entry>
              </row>
              <row>
                <entry><literal>3*4*5 = 60 (no bold)</literal></entry><entry>3*4*5
                = 60 (no bold)</entry>
              </row>
              <row>
                <entry><literal>3 * 4 * 5 = 60 (no bold)</literal></entry><entry>3
                * 4 * 5 = 60 (no bold)</entry>
              </row>
              <row>
                <entry><literal>3 *4* 5 = 60 (4 is bold)</literal></entry><entry>3
                <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)</entry>
              </row>
              <row>
                <entry><literal>*This is bold* this is not *but this is*</literal></entry><entry><emphasis
                role="bold">This is bold</emphasis> this is not <emphasis role="bold">but
                this is</emphasis></entry>
              </row>
              <row>
                <entry><literal>*This is bold*.</literal></entry><entry><emphasis
                role="bold">This is bold</emphasis>.</entry>
              </row>
              <row>
                <entry><literal>*B*. (bold B)</literal></entry><entry><emphasis role="bold">B</emphasis>.
                (bold B)</entry>
              </row>
              <row>
                <entry><literal>['*Bold-Italic*]</literal></entry><entry><emphasis><emphasis
                role="bold">Bold-Italic</emphasis></emphasis></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
                <textobject>
                  <phrase>note</phrase>
                </textobject>
                </inlinemediaobject> 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.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.phrase.inline_code">
        <title>Inline code</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>This text has inlined code `int main() { return 0; }` in it.
</programlisting>
        <para>
          will generate:
        </para>
        <para>
          This text has inlined code <code><phrase role="keyword">int</phrase>&nbsp;<phrase
          role="identifier">main</phrase><phrase role="special">()</phrase>&nbsp;<phrase
          role="special">{</phrase>&nbsp;<phrase role="keyword">return</phrase>&nbsp;<phrase
          role="number">0</phrase><phrase role="special">;</phrase>&nbsp;<phrase
          role="special">}</phrase></code> in it. The code will be syntax highlighted.
        </para>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
                <textobject>
                  <phrase>note</phrase>
                </textobject>
                </inlinemediaobject> Note that we simply enclose the code with the
                tick: <literal>"`"</literal>, not the single quote: <code><phrase
                role="string">&quot;'&quot;</phrase></code>. Note too that <literal>`some
                code`</literal> is preferred over <literal>[^some code]</literal>.
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.phrase.code_blocks">
        <title>Code blocks</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 &lt;iostream&gt;

    int main()
    {
        std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
        return 0;
    }
``
</programlisting>
        <para>
          will generate:
        </para>
        <para>
          
<programlisting>
<phrase role="preprocessor">#include</phrase>&nbsp;<phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>

<phrase role="keyword">int</phrase>&nbsp;<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>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="string">&quot;Hello, World!&quot;</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
    <phrase role="keyword">return</phrase>&nbsp;<phrase role="number">0</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase>
</programlisting>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.source_mode">
        <title>Source Mode</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>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`.
</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>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">Supported Source Modes</phrase>
          </bridgehead>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Mode</entry><entry>Source Mode Markup</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>C++</entry><entry><literal>[c++]</literal></entry>
              </row>
              <row>
                <entry>Python</entry><entry><literal>[python]</literal></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
                <textobject>
                  <phrase>note</phrase>
                </textobject>
                </inlinemediaobject> The source mode strings are lowercase.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.phrase.line_break">
        <title>line-break</title> 
<programlisting>[br]
</programlisting>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
                <textobject>
                  <phrase>note</phrase>
                </textobject>
                </inlinemediaobject> Note that <code><phrase role="special">\</phrase><phrase
                role="identifier">n</phrase></code> is now preferred over <code><phrase
                role="special">[</phrase><phrase role="identifier">br</phrase><phrase
                role="special">]</phrase></code>.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.phrase.anchors">
        <title>Anchors</title> 
<programlisting>[#named_anchor]
</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>Links</title> 
<programlisting>[@http://www.boost.org this is [*boost's] website....]
</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>see http://spirit.sourceforge.net/
</programlisting>
        <para>
          so, when the text is absent in a link markup, the URL is assumed. Example:
        </para>
        
<programlisting>see [@http://spirit.sourceforge.net/]
</programlisting>
        <para>
          will generate:
        </para>
        <para>
          see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.anchor_links">
        <title>Anchor links</title>
        <para>
          You can link within a document using:
        </para>
        
<programlisting>[link section_id.normalized_header_text The link text]
</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>refentry links</title>
        <para>
          In addition, you can link internally to an XML refentry like:
        </para>
        
<programlisting>[link xml.refentry The link text]
</programlisting>
        <para>
          This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
          link text&lt;/link&gt;</literal>.
        </para>
        <para>
          Like URLs, the link text is optional. If this is not present, the link
          text will automatically be the refentry. Example:
        </para>
        
<programlisting>[link xml.refentry]
</programlisting>
        <para>
          This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</literal>.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.code_links">
        <title> Code Links</title>
        <para>
          If you want to link to a function, class, member, enum or header in the
          reference section, you can use:
        </para>
        
<programlisting>[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]
[headerref path/to/header.hpp The link text]
</programlisting>
        <para>
          Again, the link text is optional. If this is not present, the link text
          will automatically be the function, class, member or enum. Example:
        </para>
        
<programlisting>[classref boost::bar::baz]
</programlisting>
        <para>
          would have &quot;boost::bar::baz&quot; as the link text.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.escape">
        <title>Escape</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>'''
&lt;emphasis role=&quot;bold&quot;&gt;This is direct XML markup&lt;/emphasis&gt;
'''
</programlisting>
        <para>
          <emphasis role="bold">This is direct XML markup</emphasis>
        </para>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/alert.png"></imagedata></imageobject>
                <textobject>
                  <phrase>alert</phrase>
                </textobject>
                </inlinemediaobject> 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.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.phrase.single_char_escape">
        <title>Single char escape</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. Note that <code><phrase
          role="special">\</phrase><phrase role="identifier">n</phrase></code> is
          now preferred over <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
          role="special">]</phrase></code>.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.images">
        <title>Images</title> 
<programlisting>[$image.jpg]
</programlisting>
      </section>
      <section id="quickbook.syntax.phrase.footnotes">
        <title>Footnotes</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>[footnote A sample footnote]
</programlisting>
        <para>
          will generate this
          <footnote>
            <para>
              A sample footnote
            </para>
          </footnote>
          .
        </para>
      </section>
    </section>
    <section id="quickbook.syntax.block">
      <title> Block Level Elements</title>
      <section id="quickbook.syntax.block.document">
        <title>Document</title>
        <para>
          Every document must begin with a Document Info section, which should look
          like this:
        </para>
        
<programlisting>[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]
]
</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>Section</title>
        <para>
          Starting a new section is accomplished with:
        </para>
        
<programlisting>[section:id The Section Title]
</programlisting>
        <para>
          where <emphasis>id</emphasis> is optional. id will be the filename of the
          generated section. If it is not present, &quot;The Section Title&quot;
          will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
          <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
          All non-valid characters are converted to underscore and all upper-case
          are converted to lower case. Thus: &quot;The Section Title&quot; will be
          normalized to &quot;the_section_title&quot;.
        </para>
        <para>
          End a section with:
        </para>
        
<programlisting>[endsect]
</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>xinclude</title>
        <para>
          You can include another XML file with:
        </para>
        
<programlisting>[xinclude file.xml]
</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>Paragraphs</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>Lists</title>
        <section id="quickbook.syntax.block.lists.ordered_lists">
          <title>Ordered lists</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>List Hierarchies</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>Long List Lines</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>Unordered lists</title> 
<programlisting>* First
* Second
* Third
</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>Mixed lists</title>
          <para>
            Mixed lists (ordered and unordered) are supported. Example:
          </para>
          
<programlisting># One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four
</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># 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
</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>Code</title>
        <para>
          Preformatted code starts with a space or a tab. The code will be syntax
          highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
          Mode</link>:
        </para>
        <para>
        </para>
        
<programlisting>
<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>

<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
<phrase role="special">{</phrase>
    <phrase role="comment">// Sample code
</phrase>    <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;Hello, World\n&quot;</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">'''&quot;Cooks&quot; the input text for HTML.'''</phrase>

    <phrase role="keyword">return</phrase> <phrase role="identifier">cgi</phrase><phrase role="special">.</phrase><phrase role="identifier">escape</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">)</phrase>
</programlisting>
        <para>
          Macros that are already defined are expanded in source code. Example:
        </para>
        
<programlisting>[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
[def __quickbook__ [@index.html quickbook]]

    using __quickbook__::__syntax_highlight__;
</programlisting>
        <para>
          Generates:
        </para>
        
<programlisting>
<phrase role="identifier">using</phrase> <ulink url="index.html">quickbook</ulink><phrase role="special">::</phrase><ulink url="quickbook/highlight.html">syntax_highlight</ulink><phrase role="special">;</phrase>
</programlisting>
      </section>
      <section id="quickbook.syntax.block.escape_back">
        <title> Escaping Back To QuickBook</title>
        <para>
          Inside code, code blocks and inline code, QuickBook does not allow any
          markup to avoid conflicts with the target syntax (e.g. c++). In case you
          need to switch back to QuickBook markup inside code, you can do so using
          a language specific <emphasis>escape-back</emphasis> delimiter. In C++
          and Python, the delimiter is the double tick (back-quote): &quot;``&quot;
          and &quot;``&quot;. Example:
        </para>
        
<programlisting>void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
</programlisting>
        <para>
          Will generate:
        </para>
        
<programlisting>
<phrase role="identifier">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>Preformatted</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>[pre

    Some *preformatted* text                    Some *preformatted* text

        Some *preformatted* text            Some *preformatted* text

            Some *preformatted* text    Some *preformatted* text

]
</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>Blockquote</title> 
<programlisting>[:sometext...]
</programlisting>
        <blockquote>
          <para>
            Indents the paragraph. This applies to one paragraph only.
          </para>
        </blockquote>
      </section>
      <section id="quickbook.syntax.block.admonitions">
        <title>Admonitions</title> 
<programlisting>[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]
</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>Headings</title> 
<programlisting>[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
</programlisting>
        <anchor id="quickbook.syntax.block.headings.heading_1" />
        <bridgehead renderas="sect1">
          Heading 1
        </bridgehead>
        <anchor id="quickbook.syntax.block.headings.heading_2" />
        <bridgehead renderas="sect2">
          Heading 2
        </bridgehead>
        <anchor id="quickbook.syntax.block.headings.heading_3" />
        <bridgehead renderas="sect3">
          Heading 3
        </bridgehead>
        <anchor id="quickbook.syntax.block.headings.heading_4" />
        <bridgehead renderas="sect4">
          Heading 4
        </bridgehead>
        <anchor id="quickbook.syntax.block.headings.heading_5" />
        <bridgehead renderas="sect5">
          Heading 5
        </bridgehead>
        <anchor id="quickbook.syntax.block.headings.heading_6" />
        <bridgehead renderas="sect6">
          Heading 6
        </bridgehead>
        <para>
          Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
          names with <literal>name=&quot;section_id.normalized_header_text&quot;</literal>
          (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
          <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
          are converted to underscore and all upper-case are converted to lower-case.
          For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>).
          You can use:
        </para>
        
<programlisting>[link section_id.normalized_header_text The link text]
</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.macros">
        <title>Macros</title> 
<programlisting>[def macro_identifier some text]
</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 ']' while the replacement text can be any phrase
          (even marked up). Example:
        </para>
        
<programlisting>[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
sf_logo
</programlisting>
        <para>
          Now everywhere the sf_logo is placed, the picture will be inlined.
        </para>
        <para>
          <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></imagedata></imageobject>
          <textobject>
            <phrase>sflogo</phrase>
          </textobject>
          </inlinemediaobject>
        </para>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
                <textobject>
                  <phrase>tip</phrase>
                </textobject>
                </inlinemediaobject> 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.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        <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>[def :-)            [$theme/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
</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>Hi __spirit__  :-)
</programlisting>
        <para>
          will generate this:
        </para>
        <para>
          Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink>&nbsp;<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>Predefined Macros</title>
        <para>
          Quickbook has some predefined macros that you can already use.
        </para>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">Predefined Macros</phrase>
          </bridgehead>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>Macro</entry><entry>Meaning</entry><entry>Example</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>__DATE__</entry><entry>Today's date</entry><entry>2000-Dec-20</entry>
              </row>
              <row>
                <entry>__TIME__</entry><entry>The current time</entry><entry>12:00:00
                PM</entry>
              </row>
              <row>
                <entry>__FILENAME__</entry><entry>Quickbook source filename</entry><entry>NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.block.blurbs">
        <title>Blurbs</title> 
<programlisting>[blurb :-) [*An eye catching advertisement or note...]\n\n
    __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++.
]
</programlisting>
        <para>
          will generate this:
        </para>
        <informaltable frame="all">
          <?dbhtml table-width="74%" ?>
          <tgroup cols="1">
            <tbody>
              <row>
                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
                <textobject>
                  <phrase>smiley</phrase>
                </textobject>
                </inlinemediaobject>&nbsp;<emphasis role="bold">An eye catching advertisement
                or note...</emphasis><sbr/> <sbr/> <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++. </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.block.tables">
        <title>Tables</title> 
<programlisting>[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]]
]
</programlisting>
        <para>
          will generate:
        </para>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">A Simple Table</phrase>
          </bridgehead>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>Heading 1</entry><entry>Heading 2</entry><entry>Heading 3</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>R0-C0</entry><entry>R0-C1</entry><entry>R0-C2</entry>
              </row>
              <row>
                <entry>R2-C0</entry><entry>R2-C1</entry><entry>R2-C2</entry>
              </row>
              <row>
                <entry>R3-C0</entry><entry>R3-C1</entry><entry>R3-C2</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        <para>
          The table title is optional. The first row of the table is automatically
          treated as the table header; that is, it is wrapped in <literal>&lt;thead&gt;...&lt;/thead&gt;</literal>
          XML tags. Note that unlike the original QuickDoc, the columns are nested
          in [ cells... ]. The syntax is free-format and allows big cells to be formatted
          nicely. Example:
        </para>
        
<programlisting>[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1:
            A very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
            A very big cell...A very big cell...A very big cell...
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]
</programlisting>
        <para>
          and thus:
        </para>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">Table with fat cells</phrase>
          </bridgehead>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Heading 1</entry><entry>Heading 2</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>Row 0, Col 0: a small cell</entry><entry> Row 0, Col 1: A
                very big cell...A very big cell...A very big cell... A very big cell...A
                very big cell...A very big cell... A very big cell...A very big cell...A
                very big cell... </entry>
              </row>
              <row>
                <entry>Row 1, Col 0: a small cell</entry><entry>Row 1, Col 1: a small
                cell</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
        <para>
          Here's how to have preformatted blocks of code in a table cell:
        </para>
        
<programlisting>[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        [``
            #include &lt;iostream&gt;

            int main()
            {
                std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
                return 0;
            }
        ``]
    ]
]
</programlisting>
        <informaltable frame="all">
          <bridgehead renderas="sect4">
            <phrase role="table-title">Table with code</phrase>
          </bridgehead>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Comment</entry><entry>Code</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>My first program</entry><entry>
<programlisting>
<phrase role="comment">#include &lt;iostream&gt;
</phrase>
<phrase role="identifier">int</phrase>&nbsp;<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>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="string">&quot;Hello, World!&quot;</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
    <phrase role="keyword">return</phrase>&nbsp;<phrase role="number">0</phrase><phrase role="special">;</phrase>
<phrase role="special">}</phrase>
</programlisting>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
      <section id="quickbook.syntax.block.variable_lists">
        <title>Variable Lists</title> 
<programlisting>[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]]
]
</programlisting>
        <para>
          will generate:
        </para>
        <variablelist>
          <title>A Variable List</title> <varlistentry><term>term 1</term>
          <listitem>
            The definition of term 1
          </listitem>
          </varlistentry> <varlistentry><term>term 2</term>
          <listitem>
            The definition of term 2
          </listitem>
          </varlistentry> <varlistentry><term>term 3</term>
          <listitem>
            The definition of term 3
          </listitem>
          </varlistentry>
        </variablelist>
        <para>
          The rules for variable lists are the same as for tables, except that only
          2 &quot;columns&quot; are allowed. The first column contains the terms,
          and the second column contains the definitions. Those familiar with HTML
          will recognize this as a &quot;definition list&quot;.
        </para>
      </section>
      <section id="quickbook.syntax.block.include">
        <title>Include</title>
        <para>
          You can include one QuickBook file from another. The syntax is simply:
        </para>
        
<programlisting>[include someother.qbk]
</programlisting>
        <para>
          The included file will be processed as if it had be 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>
          As the number of included QuickBook files grows, so too does the likelihood
          of two sections having the same name. Since QuickBook generates an anchor
          for each section based on the section name, it is possible to end up with
          two identically named anchors, leading to link ambiguities. To resolve
          these ambiguities, the <literal>[include]</literal> directive lets you
          specify a document id to use for the included file. You can use it like
          this:
        </para>
        
<programlisting>[include:someid someother.qbk]
</programlisting>
        <para>
          When using this form, all auto-generated anchors will use &quot;someid&quot;
          as a unique prefix. So for instance, if there is a section in someother.qbk
          named &quot;Intro&quot;, the named anchor for that section will be &quot;someid.intro&quot;,
          and you can link to it with <literal>[link someid.intro The Intro]</literal>.
        </para>
      </section>
    </section>
  </section>
  <section id="quickbook.ref">
    <title> Quick Reference</title>
    <informaltable frame="all">
      <bridgehead renderas="sect4">
        <phrase role="table-title">Syntax Compendium</phrase>
      </bridgehead>
      <tgroup cols="3">
        <thead>
          <row>
            <entry>To do this...</entry><entry>Use this...</entry><entry>See this...</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>comment</entry><entry><literal>[/ some comment]</literal></entry><entry><link
            linkend="quickbook.syntax.comments">Comments</link></entry>
          </row>
          <row>
            <entry><emphasis>italics</emphasis></entry><entry><literal>['italics]
            or /italics/</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
            Simple formatting</link></entry>
          </row>
          <row>
            <entry><emphasis role="bold">bold</emphasis></entry><entry><literal>[*bold]
            or *bold*</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
            Simple formatting</link></entry>
          </row>
          <row>
            <entry><emphasis role="underline">underline</emphasis></entry><entry><literal>[_underline]
            or _underline_</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
            Simple formatting</link></entry>
          </row>
          <row>
            <entry><literal>teletype</literal></entry><entry><literal>[^teletype]
            or =teletype=</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
            Simple formatting</link></entry>
          </row>
          <row>
            <entry><emphasis role="strikethrough">strikethrough</emphasis></entry><entry><literal>[-strikethrough]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> and
            <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
            Simple formatting</link></entry>
          </row>
          <row>
            <entry>source mode</entry><entry><literal>[c++]</literal> or <literal>[python]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></entry>
          </row>
          <row>
            <entry>inline code</entry><entry><literal>`int main();`</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.inline_code">Inline code</link></entry>
          </row>
          <row>
            <entry>code block</entry><entry><literal>``int main();``</literal></entry><entry><link
            linkend="quickbook.syntax.block.code">Code</link></entry>
          </row>
          <row>
            <entry>code escape</entry><entry><literal>``from c++ to QuickBook``</literal></entry><entry><link
            linkend="quickbook.syntax.block.escape_back">Escaping Back To QuickBook</link></entry>
          </row>
          <row>
            <entry>line break</entry><entry><literal>[br] or \n</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.line_break">line-break</link></entry>
          </row>
          <row>
            <entry>anchor</entry><entry><literal>[#anchor]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.anchors">Anchors</link></entry>
          </row>
          <row>
            <entry>link</entry><entry><literal>[@http://www.boost.org Boost]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.links">Links</link></entry>
          </row>
          <row>
            <entry>anchor link</entry><entry><literal>[link section.anchor Link text]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></entry>
          </row>
          <row>
            <entry>refentry link</entry><entry><literal>[link xml.refentry Link text]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></entry>
          </row>
          <row>
            <entry>function link</entry><entry><literal>[funcref fully::qualified::function_name
            Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
            class, member, enum or header links</link></entry>
          </row>
          <row>
            <entry>class link</entry><entry><literal>[classref fully::qualified::class_name
            Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
            class, member, enum or header links</link></entry>
          </row>
          <row>
            <entry>member link</entry><entry><literal>[memberref fully::qualified::member_name
            Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
            class, member, enum or header links</link></entry>
          </row>
          <row>
            <entry>enum link</entry><entry><literal>[enumref fully::qualified::enum_name
            Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
            class, member, enum or header links</link></entry>
          </row>
          <row>
            <entry>header link</entry><entry><literal>[headerref path/to/header.hpp
            Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
            class, member, enum or header links</link></entry>
          </row>
          <row>
            <entry>escape</entry><entry><literal>'''escaped text (no processing/formatting)'''</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.escape">Escape</link></entry>
          </row>
          <row>
            <entry>single char escape</entry><entry><literal>\c</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.single_char_escape">Single char escape</link></entry>
          </row>
          <row>
            <entry>images</entry><entry><literal>[$image.jpg]</literal></entry><entry><link
            linkend="quickbook.syntax.phrase.images">Images</link></entry>
          </row>
          <row>
            <entry>begin section</entry><entry><literal>[section The Section Title]</literal></entry><entry><link
            linkend="quickbook.syntax.block.section">Section</link></entry>
          </row>
          <row>
            <entry>end section</entry><entry><literal>[endsect]</literal></entry><entry><link
            linkend="quickbook.syntax.block.section">Section</link></entry>
          </row>
          <row>
            <entry>paragraph</entry><entry>No markup. Paragraphs start left-flushed
            and are terminated by two or more newlines.</entry><entry><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></entry>
          </row>
          <row>
            <entry>ordered list</entry><entry><literal># one<sbr/> # two<sbr/> #
            three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
            lists</link></entry>
          </row>
          <row>
            <entry>unordered list</entry><entry><literal>* one<sbr/> * two<sbr/>
            * three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
            lists</link></entry>
          </row>
          <row>
            <entry>code</entry><entry>No markup. Preformatted code starts with a
            space or a tab.</entry><entry><link linkend="quickbook.syntax.block.code">Code</link></entry>
          </row>
          <row>
            <entry>preformatted</entry><entry><literal>[pre preformatted]</literal></entry><entry><link
            linkend="quickbook.syntax.block.preformatted">Preformatted</link></entry>
          </row>
          <row>
            <entry>block quote</entry><entry><literal>[:sometext...]</literal></entry><entry><link
            linkend="quickbook.syntax.block.blockquote">Blockquote</link></entry>
          </row>
          <row>
            <entry>heading 1</entry><entry><literal>[h1 Heading 1]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>heading 2</entry><entry><literal>[h2 Heading 2]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>heading 3</entry><entry><literal>[h3 Heading 3]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>heading 4</entry><entry><literal>[h4 Heading 4]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>heading 5</entry><entry><literal>[h5 Heading 5]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>heading 6</entry><entry><literal>[h6 Heading 6]</literal></entry><entry><link
            linkend="quickbook.syntax.block.headings">Heading</link></entry>
          </row>
          <row>
            <entry>macro</entry><entry><literal>[def macro_identifier some text]</literal></entry><entry><link
            linkend="quickbook.syntax.block.macros">Macros</link></entry>
          </row>
          <row>
            <entry>blurb</entry><entry><literal>[blurb advertisement or note...]</literal></entry><entry><link
            linkend="quickbook.syntax.block.blurbs">Blurbs</link></entry>
          </row>
          <row>
            <entry>admonition</entry><entry><literal>[warning Warning text...]</literal></entry><entry><link
            linkend="quickbook.syntax.block.admonitions">Admonitions</link></entry>
          </row>
          <row>
            <entry>table</entry><entry><literal>[table Title<sbr/> [[a][b][c]]<sbr/>
            [[a][b][c]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.tables">Tables</link></entry>
          </row>
          <row>
            <entry>variablelist</entry><entry><literal>[variablelist Title<sbr/>
            [[a][b]]<sbr/> [[a][b]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.variable_lists">Variable
            Lists</link></entry>
          </row>
          <row>
            <entry>include</entry><entry><literal>[include someother.qbk]</literal></entry><entry><link
            linkend="quickbook.syntax.block.include">Include</link></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
</article>
