quickbook-manual.gold

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

<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="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;Hello, World!&quot;</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
    <phrase role="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/</ulink>
        </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>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
          link text&lt;/link&gt;</literal>.
        </para>
        <para>
          Like URLs, the link text is optional. If this is not present, the link
          text will automatically be the refentry. Example:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[link xml.refentry]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</literal>.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.code_links">
        <title><link linkend="quickbook.syntax.phrase.code_links"> Code Links</link></title>
        <para>
          If you want to link to a function, class, member, enum, concept or header
          in the reference section, you can use:
        </para>
        
<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 &quot;boost::bar::baz&quot; as the link text.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.escape">
        <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title>
        <para>
          The escape mark-up is used when we don't want to do any processing.
        </para>
        
<programlisting>'''
escape (no processing/formatting)
'''
</programlisting>
        <para>
          Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
          or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
        </para>
        
<programlisting>'''
&lt;emphasis role=&quot;bold&quot;&gt;This is direct XML markup&lt;/emphasis&gt;
'''
</programlisting>
        <para>
          <emphasis role="bold">This is direct XML markup</emphasis>
        </para>
        <important>
          <para>
            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