quickbook-manual.gold

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

        <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title>
        <para>
          Simple markup for formatting text, common in many applications, is now
          supported:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype=
<!--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>
        </para>
        <para>
          Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
          are much stricter
          <footnote>
            <para>
              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.
            </para>
          </footnote>
          .
        </para>
        <itemizedlist>
          <listitem>
            Simple markups cannot nest. You can combine a simple markup with a nestable
            markup.
          </listitem>
          <listitem>
            Simple markups cannot contain any other form of quickbook 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 block, 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
            block. We do not want the rest of the document to be rendered bold just
            because we forgot a trailing '*'. A single block is terminated by two
            end of lines or the close bracket: ']'.
          </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>
        <table frame="all"> <title>More Formatting Samples</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>
              <para>
                Markup
              </para>
              </entry><entry>
              <para>
                Result
              </para>
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
              <para>
                <literal>*Bold*</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">Bold</emphasis>
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*Is bold*</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">Is bold</emphasis>
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>* Not bold* *Not bold * * Not bold *</literal>
              </para>
              </entry><entry>
              <para>
                * Not bold* *Not bold * * Not bold *
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>This*Isn't*Bold (no bold)</literal>
              </para>
              </entry><entry>
              <para>
                This*Isn't*Bold (no bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>(*Bold Inside*) (parenthesis not bold)</literal>
              </para>
              </entry><entry>
              <para>
                (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*(Bold Outside)* (parenthesis bold)</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>3*4*5 = 60 (no bold)</literal>
              </para>
              </entry><entry>
              <para>
                3*4*5 = 60 (no bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>3 * 4 * 5 = 60 (no bold)</literal>
              </para>
              </entry><entry>
              <para>
                3 * 4 * 5 = 60 (no bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>3 *4* 5 = 60 (4 is bold)</literal>
              </para>
              </entry><entry>
              <para>
                3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*This is bold* this is not *but this is*</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">This is bold</emphasis> this is not <emphasis
                role="bold">but this is</emphasis>
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*This is bold*.</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">This is bold</emphasis>.
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*B*. (bold B)</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">B</emphasis>. (bold B)
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>['*Bold-Italic*]</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis>
              </para>
              </entry>
            </row>
            <row>
              <entry>
              <para>
                <literal>*side-by*/-side/</literal>
              </para>
              </entry><entry>
              <para>
                <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis>
              </para>
              </entry>
            </row>
          </tbody>
        </tgroup>
        </table>
        <para>
          As mentioned, simple markups cannot go past a single block. The text from
          &quot;have&quot; to &quot;full&quot; in the following paragraph will be
          rendered as bold:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.
<!--quickbook-escape-postfix--></programlisting>
        <para>
          Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir,
          yes sir, three bags full!</emphasis> One for the master, one for the dame,
          And one for the little boy who lives down the lane.
        </para>
        <para>
          But in the following paragraph, bold is not applied:
        </para>
        
<programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.
<!--quickbook-escape-postfix--></programlisting>
        <para>
          Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!
          One for the master, one for the dame, And one for the little boy who lives
          down the lane.
        </para>
      </section>
      <section id="quickbook.syntax.phrase.inline_code">
        <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></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><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it.
<!--quickbook-escape-postfix--></programlisting>
        <para>
          will generate:
        </para>
        <para>
          This text has inlined code <code><phrase role="keyword">int</phrase> <phrase
          role="identifier">main</phrase><phrase role="special">()</phrase> <phrase
          role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase
          role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code>
          in it. The code will be syntax highlighted.
        </para>
        <note>
          <para>
            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>.
          </para>
        </note>
      </section>
      <section id="quickbook.syntax.phrase.code_blocks">
        <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></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>