quickbook-manual.gold

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

                  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">&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>
        </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): &quot;``&quot;
          and &quot;``&quot;. Example:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
{
}
<!--quickbook-escape-postfix--></programlisting>
        <para>
          Will generate:
        </para>
        
<programlisting><phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
<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=&quot;section_id.normalized_header_text&quot;</literal>
          (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
          <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
          are converted to underscore and all upper-case are converted to lower-case.
          For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>).
          You can use:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
          links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
          for more info.
        </para>
      </section>
      <section id="quickbook.syntax.block.generic_heading">
        <title><link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link></title>
        <para>
          In cases when you don't want to care about the heading level (1 to 6),
          you can use the <emphasis>Generic Heading</emphasis>:
        </para>
        
<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 ex