quickbook-manual.gold

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

    [quickbook 1.3]
    [version 1.0]
    [id the_document_name]
    [dirname the_document_dir]
    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
    [purpose The document's reason for being]
    [category The document's category]
    [authors [Blow, Joe], [Doe, Jane]]
    [license The document's license]
    [source-mode source-type]
]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          Where document-type is one of:
        </para>
        <itemizedlist>
          <listitem>
            book
          </listitem>
          <listitem>
            article
          </listitem>
          <listitem>
            library
          </listitem>
          <listitem>
            chapter
          </listitem>
          <listitem>
            part
          </listitem>
          <listitem>
            appendix
          </listitem>
          <listitem>
            preface
          </listitem>
          <listitem>
            qandadiv
          </listitem>
          <listitem>
            qandaset
          </listitem>
          <listitem>
            reference
          </listitem>
          <listitem>
            set
          </listitem>
        </itemizedlist>
        <para>
          quickbook 1.3 declares the version of quickbook the document is written
          for. In its absence, version 1.1 is assumed.
        </para>
        <para>
          <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
          <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
          <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
          and <literal>source-mode</literal> are optional information.
        </para>
        <para>
          <literal>source-type</literal> is a lowercase string setting the initial
          <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
          If the <literal>source-mode</literal> field is omitted, a default value
          of <literal>c++</literal> will be used.
        </para>
      </section>
      <section id="quickbook.syntax.block.section">
        <title><link linkend="quickbook.syntax.block.section">Section</link></title>
        <para>
          Starting a new section is accomplished with:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[section:id The Section Title]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          where <emphasis>id</emphasis> is optional. id will be the filename of the
          generated section. If it is not present, &quot;The Section Title&quot;
          will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
          <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
          All non-valid characters are converted to underscore and all upper-case
          are converted to lower case. Thus: &quot;The Section Title&quot; will be
          normalized to &quot;the_section_title&quot;.
        </para>
        <para>
          End a section with:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[endsect]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          Sections can nest, and that results in a hierarchy in the table of contents.
        </para>
      </section>
      <section id="quickbook.syntax.block.xinclude">
        <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title>
        <para>
          You can include another XML file with:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[xinclude file.xml]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          This is useful when file.xml has been generated by Doxygen and contains
          your reference section.
        </para>
      </section>
      <section id="quickbook.syntax.block.paragraphs">
        <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title>
        <para>
          Paragraphs start left-flushed and are terminated by two or more newlines.
          No markup is needed for paragraphs. QuickBook automatically detects paragraphs
          from the context. Block markups [section, endsect, h1, h2, h3, h4, h5,
          h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate
          a paragraph.
        </para>
      </section>
      <section id="quickbook.syntax.block.lists">
        <title><link linkend="quickbook.syntax.block.lists">Lists</link></title>
        <section id="quickbook.syntax.block.lists.ordered_lists">
          <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
          lists</link></title> 
<programlisting># One
# Two
# Three
</programlisting>
          <para>
            will generate:
          </para>
          <orderedlist>
            <listitem>
              One
            </listitem>
            <listitem>
              Two
            </listitem>
            <listitem>
              Three
            </listitem>
          </orderedlist>
        </section>
        <section id="quickbook.syntax.block.lists.list_hierarchies">
          <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List
          Hierarchies</link></title>
          <para>
            List hierarchies are supported. Example:
          </para>
          
<programlisting># One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Four
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five
</programlisting>
          <para>
            will generate:
          </para>
          <orderedlist>
            <listitem>
              One
            </listitem>
            <listitem>
              Two
            </listitem>
            <listitem>
              Three
              <orderedlist>
                <listitem>
                  Three.a
                </listitem>
                <listitem>
                  Three.b
                </listitem>
                <listitem>
                  Three.c
                </listitem>
              </orderedlist>
            </listitem>
            <listitem>
              Fourth
              <orderedlist>
                <listitem>
                  Four.a
                  <orderedlist>
                    <listitem>
                      Four.a.i
                    </listitem>
                    <listitem>
                      Four.a.ii
                    </listitem>
                  </orderedlist>
                </listitem>
              </orderedlist>
            </listitem>
            <listitem>
              Five
            </listitem>
          </orderedlist>
        </section>
        <section id="quickbook.syntax.block.lists.long_list_lines">
          <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long
          List Lines</link></title>
          <para>
            Long lines will be wrapped appropriately. Example:
          </para>
          
<programlisting># A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.
</programlisting>
          <orderedlist>
            <listitem>
              A short item.
            </listitem>
            <listitem>
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item.
            </listitem>
            <listitem>
              A short item.
            </listitem>
          </orderedlist>
        </section>
        <section id="quickbook.syntax.block.lists.unordered_lists">
          <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
          lists</link></title> 
<programlisting><!--quickbook-escape-prefix-->* First
* Second
* Third
<!--quickbook-escape-postfix--></programlisting>
          <para>
            will generate:
          </para>
          <itemizedlist>
            <listitem>
              First
            </listitem>
            <listitem>
              Second
            </listitem>
            <listitem>
              Third
            </listitem>
          </itemizedlist>
        </section>
        <section id="quickbook.syntax.block.lists.mixed_lists">
          <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link></title>
          <para>
            Mixed lists (ordered and unordered) are supported. Example:
          </para>
          
<programlisting><!--quickbook-escape-prefix--># One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four
<!--quickbook-escape-postfix--></programlisting>
          <para>
            will generate:
          </para>
          <orderedlist>
            <listitem>
              One
            </listitem>
            <listitem>
              Two
            </listitem>
            <listitem>
              Three
              <itemizedlist>
                <listitem>
                  Three.a
                </listitem>
                <listitem>
                  Three.b
                </listitem>
                <listitem>
                  Three.c
                </listitem>
              </itemizedlist>
            </listitem>
            <listitem>
              Four
            </listitem>
          </orderedlist>
          <para>
            And...
          </para>
          
<programlisting><!--quickbook-escape-prefix--># 1
    * 1.a
        # 1.a.1
        # 1.a.2
    * 1.b
# 2
    * 2.a
    * 2.b
        # 2.b.1
        # 2.b.2
            * 2.b.2.a
            * 2.b.2.b
<!--quickbook-escape-postfix--></programlisting>
          <para>
            will generate:
          </para>
          <orderedlist>
            <listitem>
              1
              <itemizedlist>
                <listitem>