quickbook-manual.gold

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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<article id="quickbook" name="Quickbook" dirname="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
 xmlns:xi="http://www.w3.org/2001/XInclude">
  <articleinfo>
    <authorgroup>
    <author>
      <firstname>Joel</firstname> <surname>de Guzman</surname>
    </author>
    <author>
      <firstname>Eric</firstname> <surname>Niebler</surname>
    </author>
    </authorgroup>
    <copyright>
      <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman,
      Eric Niebler</holder>
    </copyright>
    <legalnotice>
      <para>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)
      </para>
    </legalnotice>
    <articlepurpose>
      <emphasis>WikiWiki</emphasis> style documentation tool
    </articlepurpose>
  </articleinfo>
  <title>Quickbook 1.4</title>
  <section id="quickbook.intro">
    <title><link linkend="quickbook.intro"> Introduction</link></title>
    <blockquote>
      <para>
        <para>
          <emphasis role="bold"><emphasis><quote>Why program by hand in five days
          what you can spend five years of your life automating?</quote></emphasis></emphasis>
        </para>
        <para>
          -- Terrence Parr, author ANTLR/PCCTS
        </para>
      </para>
    </blockquote>
    <para>
      Well, QuickBook started as a weekend hack. It was originally intended to be
      a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
      What is it? What you are viewing now, this documentation, is autogenerated
      by QuickBook. These files were generated from one master:
    </para>
    <blockquote>
      <para>
        <para>
          <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
        </para>
      </para>
    </blockquote>
    <para>
      Originally named QuickDoc, this funky tool that never dies evolved into a funkier
      tool thanks to Eric Niebler who resurrected the project making it generate
      <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
      instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
      documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
      an SGML or XML based format for describing documentation.
    </para>
    <para>
      QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
      using simple rules and markup for simple formatting tasks. QuickBook extends
      the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
      files. A single QuickBook document can generate a fully linked set of nice
      HTML and PostScript/PDF documents complete with images and syntax- colorized
      source code.
    </para>
    <para>
      Features include:
    </para>
    <itemizedlist>
      <listitem>
        generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
        xml, to generate HTML, PostScript and PDF
      </listitem>
      <listitem>
        simple markup to link to Doxygen-generated entities
      </listitem>
      <listitem>
        macro system for simple text substitution
      </listitem>
      <listitem>
        simple markup for italics, bold, preformatted, blurbs, code samples, tables,
        URLs, anchors, images, etc.
      </listitem>
      <listitem>
        automatic syntax coloring of code samples
      </listitem>
      <listitem>
        CSS support
      </listitem>
    </itemizedlist>
  </section>
  <section id="quickbook.change_log">
    <title><link linkend="quickbook.change_log"> Change Log</link></title> <anchor
    id="quickbook.change_log.version_1_3"/>
    <bridgehead renderas="sect3">
      <link linkend="quickbook.change_log.version_1_3">Version 1.3</link>
    </bridgehead>
    <itemizedlist>
      <listitem>
        Quickbook file inclusion [include].
      </listitem>
      <listitem>
        Better xml output (pretty layout). Check out the generated XML.
      </listitem>
      <listitem>
        Regression testing facility: to make sure your document will always be compatible
        (full backward compatibility) regardless of changes to QuickBook.
      </listitem>
      <listitem>
        Code cleanup and refactoring.
      </listitem>
      <listitem>
        Allow phrase markup in the doc-info.
      </listitem>
      <listitem>
        Preformatted code blocks via ``code`` (double ticks) allows code in tables
        and lists, for example.
      </listitem>
      <listitem>
        Quickbook versioning; allows full backward compatibility. You have to add
        [quickbook 1.3] to the doc-info header to enable the new features. Without
        this, QuickBook will assume that the document is a pre-1.3 document.
      </listitem>
      <listitem>
        Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
        Example:
<programlisting><phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase>
<phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
      </listitem>
      <listitem>
        Fully qualified section and headers. Subsection names are concatenated to
        the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
        role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
        role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
        role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
      </listitem>
      <listitem>
        Better &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>
      <listitem>
        Post-processor bug fix for escaped XML code that it does not recognize.
      </listitem>
      <listitem>
        Replaceable, with the [~replacement] syntax.
      </listitem>
      <listitem>
        Generic Headers
      </listitem>
      <listitem>
        Code changes to allow full recursion (i.e. Collectors and push/pop functions)
      </listitem>
      <listitem>
        Various code cleanup/maintenance
      </listitem>
      <listitem>
        Templates!
      </listitem>
      <listitem>
        [conceptref] for referencing BoostBook &lt;concept&gt; entities.
      </listitem>
      <listitem>
        Allow escape of spaces. The escaped space is removed from the output. Syntax:
        <code><phrase role="special">\</phrase> </code>.
      </listitem>
      <listitem>
        Nested comments are now allowed.
      </listitem>
      <listitem>
        Quickbook blocks can nest inside comments.
      </listitem>
      <listitem>
        <link linkend="quickbook.syntax.block.import">Import</link> facility.
      </listitem>
      <listitem>
        Callouts on imported code
      </listitem>
      <listitem>
        Simple markups can now span a whole block.
      </listitem>
      <listitem>
        <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
        and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
        may now contain paragraphs.
      </listitem>
      <listitem>
        <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
        and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
        role="special">]</phrase></code> are now deprecated.
      </listitem>
    </itemizedlist>
  </section>
  <section id="quickbook.syntax">
    <title><link linkend="quickbook.syntax"> Syntax Summary</link></title>
    <para>
      A QuickBook document is composed of one or more blocks. An example of a block
      is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
      Blocks, except code snippets which have their own grammar (C++ or Python),
      are composed of one or more phrases. A phrase can be a simple contiguous run
      of characters. Phrases can have special mark-ups. Marked up phrases can recursively
      contain other phrases, but cannot contain blocks. A terminal is a self contained
      block-level or phrase-level element that does not nest anything.
    </para>
    <para>
      Blocks, in general, are delimited by two end-of-lines (the block terminator).
      Phrases in each block cannot contain a block terminator. This way, syntax errors
      such as un-matched closing brackets do not go haywire and corrupt anything
      past a single block.
    </para>
    <section id="quickbook.syntax.comments">
      <title><link linkend="quickbook.syntax.comments">Comments</link></title>
      <para>
        Can be placed anywhere.
      </para>
      
<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix-->
</programlisting>
      
<programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix-->
</programlisting>
      
<programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix-->
</programlisting>
    </section>
    <section id="quickbook.syntax.phrase">
      <title><link linkend="quickbook.syntax.phrase"> Phrase Level Elements</link></title>
      <section id="quickbook.syntax.phrase.font_styles">
        <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title>
        
<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          will generate:
        </para>
        <para>
          <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
          role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
          role="strikethrough">strikethrough</emphasis>
        </para>
        <para>
          Like all non-terminal phrase level elements, this can of course be nested:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          will generate:
        </para>
        <para>
          <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.replaceable">
        <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title>
        <para>
          When you want content that may or must be replaced by the user, use the
          syntax:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->[~replacement]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          This will generate:
        </para>
        <para>
          <replaceable>
            replacement
          </replaceable>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.quotations">
        <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title>
        
<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
<!--quickbook-escape-postfix--></programlisting>
        <para>
          will generate:
        </para>
        <para>
          <quote>A question that sometimes drives me hazy: am I or are the others
          crazy?</quote>--Einstein
        </para>
        <para>
          Note the proper left and right quote marks. Also, while you can simply
          use ordinary quote marks like &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><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]
<!--quickbook-escape-postfix--></programlisting>
        <para>
          will generate:
        </para>
        <para>
          <quote>Here's the rule for bargains: <quote>Do other men, for they would
          do you.</quote> That's the true business precept.</quote>
        </para>
      </section>
      <section id="quickbook.syntax.phrase.simple_formatting">