Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/tools/quickbook/test/quickbook-manual.gold @ 50

Last change on this file since 50 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 80.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
3<article id="quickbook" name="Quickbook" dirname="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
4 xmlns:xi="http://www.w3.org/2001/XInclude">
5  <articleinfo>
6    <author>
7      <firstname>Joel</firstname> <surname>de Guzman</surname>
8    </author>
9    <author>
10      <firstname>Eric</firstname> <surname>Niebler</surname>
11    </author>
12    <copyright>
13      <year>2002</year> <year>2004</year> <holder>Joel de Guzman, Eric Niebler</holder>
14    </copyright>
15    <legalnotice>
16      <para>
17        Distributed under the Boost Software License, Version 1.0. (See accompanying
18        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>)
19      </para>
20    </legalnotice>
21    <articlepurpose>
22      <emphasis>WikiWiki</emphasis> style documentation tool
23    </articlepurpose>
24  </articleinfo>
25  <title>Quickbook 1.3</title>
26  <section id="quickbook.intro">
27    <title> Introduction</title>
28    <blockquote>
29      <para>
30        <emphasis role="bold"><emphasis><quote>Why program by hand in five days what
31        you can spend five years of your life automating?</quote></emphasis></emphasis><sbr/>
32        <sbr/> -- Terrence Parr, author ANTLR/PCCTS
33      </para>
34    </blockquote>
35    <para>
36      Well, QuickBook started as a weekend hack. It was originally intended to be
37      a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
38      What is it? What you are viewing now, this documentation, is autogenerated
39      by QuickBook. These files were generated from one master:
40    </para>
41    <blockquote>
42      <para>
43        <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
44      </para>
45    </blockquote>
46    <para>
47      Originally named QuickDoc, this funky tool that never dies evolved into a funkier
48      tool thanks to Eric Niebler who resurrected the project making it generate
49      <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
50      instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
51      documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
52      an SGML or XML based format for describing documentation.
53    </para>
54    <para>
55      QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
56      using simple rules and markup for simple formatting tasks. QuickBook extends
57      the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
58      files. A single QuickBook document can generate a fully linked set of nice
59      HTML and PostScript/PDF documents complete with images and syntax- colorized
60      source code.
61    </para>
62    <para>
63      Features include:
64    </para>
65    <itemizedlist>
66      <listitem>
67        generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
68        xml, to generate HTML, PostScript and PDF
69      </listitem>
70      <listitem>
71        simple markup to link to Doxygen-generated entities
72      </listitem>
73      <listitem>
74        macro system for simple text substitution
75      </listitem>
76      <listitem>
77        simple markup for italics, bold, preformatted, blurbs, code samples, tables,
78        URLs, anchors, images, etc.
79      </listitem>
80      <listitem>
81        automatic syntax coloring of code samples
82      </listitem>
83      <listitem>
84        CSS support
85      </listitem>
86    </itemizedlist>
87  </section>
88  <section id="quickbook.change_log">
89    <title> Change Log</title> <anchor id="quickbook.change_log.version_1_3" />
90    <bridgehead renderas="sect3">
91      Version 1.3
92    </bridgehead>
93    <itemizedlist>
94      <listitem>
95        Quickbook file inclusion [include].
96      </listitem>
97      <listitem>
98        Better xml output (pretty layout). Check out the generated XML.
99      </listitem>
100      <listitem>
101        Regression testing facility: to make sure your document will always be compatible
102        (full backward compatibility) regardless of changes to QuickBook.
103      </listitem>
104      <listitem>
105        Code cleanup and refactoring.
106      </listitem>
107      <listitem>
108        Allow phrase markup in the doc-info.
109      </listitem>
110      <listitem>
111        Preformatted code blocks via ``code`` (double ticks) allows code in tables
112        and lists, for example.
113      </listitem>
114      <listitem>
115        Quickbook versioning; allows full backward compatibility. You have to add
116        [quickbook 1.3] to the doc-info header to enable the new features. Without
117        this, QuickBook will assume that the document is a pre-1.3 document.
118      </listitem>
119      <listitem>
120        Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
121        Example:
122<programlisting>
123<phrase role="special">[</phrase><phrase role="identifier">section</phrase>&nbsp;<phrase role="identifier">x</phrase><phrase role="special">]</phrase>
124<phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
125<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
126      </listitem>
127      <listitem>
128        Fully qualified section and headers. Subsection names are concatenated to
129        the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
130        role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
131        role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
132        role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
133      </listitem>
134      <listitem>
135        Better &amp;nbsp; and whitespace handling in code snippets.
136      </listitem>
137      <listitem>
138        [xinclude] fixes up the relative path to the target XML file when input_directory
139        is not the same as the output_directory.
140      </listitem>
141      <listitem>
142        Allow untitled tables.
143      </listitem>
144      <listitem>
145        Allow phrase markups in section titles.
146      </listitem>
147      <listitem>
148        Allow escaping back to QuickBook from code, code blocks and inline code.
149      </listitem>
150      <listitem>
151        Footnotes, with the [footnote This is the footnote] syntax.
152      </listitem>
153      <listitem>
154        Post-processor bug fix for escaped XML code that it does not recognize.
155      </listitem>
156      <listitem>
157        Replaceable, with the [~replacement] syntax.
158      </listitem>
159    </itemizedlist>
160  </section>
161  <section id="quickbook.syntax">
162    <title> Syntax Summary</title>
163    <para>
164      A QuickBook document is composed of one or more blocks. An example of a block
165      is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
166      Blocks, except code snippets which have their own grammar (C++ or Python),
167      are composed of one or more phrases. A phrase can be a simple contiguous run
168      of characters. Phrases can have special mark-ups. Marked up phrases can recursively
169      contain other phrases, but cannot contain blocks. A terminal is a self contained
170      block-level or phrase-level element that does not nest anything.
171    </para>
172    <para>
173      Blocks, in general, are delimited by two end-of-lines (the block terminator).
174      Phrases in each block cannot contain a block terminator. This way, syntax errors
175      such as un-matched closing brackets do not go haywire and corrupt anything
176      past a single block.
177    </para>
178    <section id="quickbook.syntax.comments">
179      <title>Comments</title>
180      <para>
181        Can be placed anywhere.
182      </para>
183     
184<programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix-->
185</programlisting>
186    </section>
187    <section id="quickbook.syntax.phrase">
188      <title> Phrase Level Elements</title>
189      <section id="quickbook.syntax.phrase.font_styles">
190        <title>Font Styles</title>
191<programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough]
192<!--quickbook-escape-postfix--></programlisting>
193        <para>
194          will generate:
195        </para>
196        <para>
197          <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
198          role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
199          role="strikethrough">strikethrough</emphasis>
200        </para>
201        <para>
202          Like all non-terminal phrase level elements, this can of course be nested:
203        </para>
204       
205<programlisting><!--quickbook-escape-prefix-->[*['bold-italic]]
206<!--quickbook-escape-postfix--></programlisting>
207        <para>
208          will generate:
209        </para>
210        <para>
211          <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
212        </para>
213      </section>
214      <section id="quickbook.syntax.phrase.replaceable">
215        <title>Replaceable</title>
216        <para>
217          When you want content that may or must be replaced by the user, use the
218          syntax:
219        </para>
220       
221<programlisting><!--quickbook-escape-prefix-->[~replacement]
222<!--quickbook-escape-postfix--></programlisting>
223        <para>
224          This will generate:
225        </para>
226        <para>
227          <replaceable>
228            replacement
229          </replaceable>
230        </para>
231      </section>
232      <section id="quickbook.syntax.phrase.quotations">
233        <title>Quotations</title>
234<programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
235<!--quickbook-escape-postfix--></programlisting>
236        <para>
237          will generate:
238        </para>
239        <para>
240          <quote>A question that sometimes drives me hazy: am I or are the others
241          crazy?</quote>--Einstein
242        </para>
243        <para>
244          Note the proper left and right quote marks. Also, while you can simply
245          use ordinary quote marks like &quot;quoted&quot;, our quotation, above,
246          will generate correct DocBook quotations (e.g. &lt;quote&gt;quoted&lt;/quote&gt;).
247        </para>
248        <para>
249          Like all phrase elements, quotations may be nested. Example:
250        </para>
251       
252<programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's
253the true business precept.]
254<!--quickbook-escape-postfix--></programlisting>
255        <para>
256          will generate:
257        </para>
258        <para>
259          <quote>Here's the rule for bargains: <quote>Do other men, for they would
260          do you.</quote> That's the true business precept.</quote>
261        </para>
262      </section>
263      <section id="quickbook.syntax.phrase.simple_formatting">
264        <title>Simple formatting</title>
265        <para>
266          Simple markup for formatting text, common in many applications, is now
267          supported:
268        </para>
269       
270<programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype=
271<!--quickbook-escape-postfix--></programlisting>
272        <para>
273          will generate:
274        </para>
275        <para>
276          <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
277          role="underline">underline</emphasis>, <literal>teletype</literal>
278        </para>
279        <para>
280          Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
281          are much stricter.
282        </para>
283        <itemizedlist>
284          <listitem>
285            Simple markups cannot nest. You can combine a simple markup with a nestable
286            markup.
287          </listitem>
288          <listitem>
289            A non-space character must follow the leading markup
290          </listitem>
291          <listitem>
292            A non-space character must precede the trailing markup
293          </listitem>
294          <listitem>
295            A space or a punctuation must follow the trailing markup
296          </listitem>
297          <listitem>
298            If the matching markup cannot be found within a line, the formatting
299            will not be applied. This is to ensure that un-matched formatting markups,
300            which can be a common mistake, does not corrupt anything past a single
301            line. We do not want the rest of the document to be rendered bold just
302            because we forgot a trailing '*'.
303          </listitem>
304          <listitem>
305            A line starting with the star will be interpreted as an unordered list.
306            See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
307            lists</link>.
308          </listitem>
309        </itemizedlist>
310        <informaltable frame="all">
311          <bridgehead renderas="sect4">
312            <phrase role="table-title">More Formatting Samples</phrase>
313          </bridgehead>
314          <tgroup cols="2">
315            <thead>
316              <row>
317                <entry>Markup</entry><entry>Result</entry>
318              </row>
319            </thead>
320            <tbody>
321              <row>
322                <entry><literal>
323<!--quickbook-escape-prefix-->*Bold*<!--quickbook-escape-postfix-->
324                </literal></entry><entry><emphasis role="bold">Bold</emphasis></entry>
325              </row>
326              <row>
327                <entry><literal>
328<!--quickbook-escape-prefix-->*Is bold*<!--quickbook-escape-postfix-->
329                </literal></entry><entry><emphasis role="bold">Is bold</emphasis></entry>
330              </row>
331              <row>
332                <entry><literal>
333<!--quickbook-escape-prefix-->* Not bold* *Not bold * * Not bold *<!--quickbook-escape-postfix-->
334                </literal></entry><entry>* Not bold* *Not bold * * Not bold *</entry>
335              </row>
336              <row>
337                <entry><literal>
338<!--quickbook-escape-prefix-->This*Isn't*Bold (no bold)<!--quickbook-escape-postfix-->
339                </literal></entry><entry>This*Isn't*Bold (no bold)</entry>
340              </row>
341              <row>
342                <entry><literal>
343<!--quickbook-escape-prefix-->(*Bold Inside*) (parenthesis not bold)<!--quickbook-escape-postfix-->
344                </literal></entry><entry>(<emphasis role="bold">Bold Inside</emphasis>)
345                (parenthesis not bold)</entry>
346              </row>
347              <row>
348                <entry><literal>
349<!--quickbook-escape-prefix-->*(Bold Outside)* (parenthesis bold)<!--quickbook-escape-postfix-->
350                </literal></entry><entry><emphasis role="bold">(Bold Outside)</emphasis>
351                (parenthesis bold)</entry>
352              </row>
353              <row>
354                <entry><literal>
355<!--quickbook-escape-prefix-->3*4*5 = 60 (no bold)<!--quickbook-escape-postfix-->
356                </literal></entry><entry>3*4*5 = 60 (no bold)</entry>
357              </row>
358              <row>
359                <entry><literal>
360<!--quickbook-escape-prefix-->3 * 4 * 5 = 60 (no bold)<!--quickbook-escape-postfix-->
361                </literal></entry><entry>3 * 4 * 5 = 60 (no bold)</entry>
362              </row>
363              <row>
364                <entry><literal>
365<!--quickbook-escape-prefix-->3 *4* 5 = 60 (4 is bold)<!--quickbook-escape-postfix-->
366                </literal></entry><entry>3 <emphasis role="bold">4</emphasis> 5 =
367                60 (4 is bold)</entry>
368              </row>
369              <row>
370                <entry><literal>
371<!--quickbook-escape-prefix-->*This is bold* this is not *but this is*<!--quickbook-escape-postfix-->
372                </literal></entry><entry><emphasis role="bold">This is bold</emphasis>
373                this is not <emphasis role="bold">but this is</emphasis></entry>
374              </row>
375              <row>
376                <entry><literal>
377<!--quickbook-escape-prefix-->*This is bold*.<!--quickbook-escape-postfix-->
378                </literal></entry><entry><emphasis role="bold">This is bold</emphasis>.</entry>
379              </row>
380              <row>
381                <entry><literal>
382<!--quickbook-escape-prefix-->*B*. (bold B)<!--quickbook-escape-postfix-->
383                </literal></entry><entry><emphasis role="bold">B</emphasis>. (bold
384                B)</entry>
385              </row>
386              <row>
387                <entry><literal>
388<!--quickbook-escape-prefix-->['*Bold-Italic*]<!--quickbook-escape-postfix-->
389                </literal></entry><entry><emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis></entry>
390              </row>
391            </tbody>
392          </tgroup>
393        </informaltable>
394        <informaltable frame="all">
395          <?dbhtml table-width="74%" ?>
396          <tgroup cols="1">
397            <tbody>
398              <row>
399                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
400                <textobject>
401                  <phrase>note</phrase>
402                </textobject>
403                </inlinemediaobject> Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>,
404                for sharing these samples and teaching me these obscure formatting
405                rules. I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>,
406                being more or less a formal EBNF parser, can handle the context sensitivity
407                and ambiguity.</entry>
408              </row>
409            </tbody>
410          </tgroup>
411        </informaltable>
412      </section>
413      <section id="quickbook.syntax.phrase.inline_code">
414        <title>Inline code</title>
415        <para>
416          Inlining code in paragraphs is quite common when writing C++ documentation.
417          We provide a very simple markup for this. For example, this:
418        </para>
419       
420<programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it.
421<!--quickbook-escape-postfix--></programlisting>
422        <para>
423          will generate:
424        </para>
425        <para>
426          This text has inlined code <code><phrase role="keyword">int</phrase>&nbsp;<phrase
427          role="identifier">main</phrase><phrase role="special">()</phrase>&nbsp;<phrase
428          role="special">{</phrase>&nbsp;<phrase role="keyword">return</phrase>&nbsp;<phrase
429          role="number">0</phrase><phrase role="special">;</phrase>&nbsp;<phrase
430          role="special">}</phrase></code> in it. The code will be syntax highlighted.
431        </para>
432        <informaltable frame="all">
433          <?dbhtml table-width="74%" ?>
434          <tgroup cols="1">
435            <tbody>
436              <row>
437                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
438                <textobject>
439                  <phrase>note</phrase>
440                </textobject>
441                </inlinemediaobject> Note that we simply enclose the code with the
442                tick: <literal>
443<!--quickbook-escape-prefix-->"`"<!--quickbook-escape-postfix-->
444                </literal>, not the single quote: <code><phrase role="string">&quot;'&quot;</phrase></code>.
445                Note too that <literal>
446<!--quickbook-escape-prefix-->`some code`<!--quickbook-escape-postfix-->
447                </literal> is preferred over <literal>
448<!--quickbook-escape-prefix-->[^some code]<!--quickbook-escape-postfix-->
449                </literal>. </entry>
450              </row>
451            </tbody>
452          </tgroup>
453        </informaltable>
454      </section>
455      <section id="quickbook.syntax.phrase.code_blocks">
456        <title>Code blocks</title>
457        <para>
458          Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>).
459          However, such a simple syntax cannot be used as phrase elements in lists
460          (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
461          lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
462          lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>),
463          etc. Inline code (see above) can. The problem is, inline code does not
464          allow formatting with newlines, spaces, and tabs. These are lost.
465        </para>
466        <para>
467          We provide a phrase level markup that is a mix between the two. By using
468          the double-tick, instead of the single-tick, we are telling QuickBook to
469          use preformatted blocks of code. Example:
470        </para>
471       
472<programlisting>``
473    #include &lt;iostream&gt;
474
475    int main()
476    {
477        std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
478        return 0;
479    }
480``
481</programlisting>
482        <para>
483          will generate:
484        </para>
485        <para>
486         
487<programlisting>
488<phrase role="preprocessor">#include</phrase>&nbsp;<phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
489
490<phrase role="keyword">int</phrase>&nbsp;<phrase role="identifier">main</phrase><phrase role="special">()</phrase>
491<phrase role="special">{</phrase>
492    <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="string">&quot;Hello, World!&quot;</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
493    <phrase role="keyword">return</phrase>&nbsp;<phrase role="number">0</phrase><phrase role="special">;</phrase>
494<phrase role="special">}</phrase>
495</programlisting>
496        </para>
497      </section>
498      <section id="quickbook.syntax.phrase.source_mode">
499        <title>Source Mode</title>
500        <para>
501          If a document contains more than one type of source code then the source
502          mode may be changed dynamically as the document is processed. All QuickBook
503          documents are initially in C++ mode by default, though an alternative initial
504          value may be set in the <link linkend="quickbook.syntax.block.document">Document</link>
505          section.
506        </para>
507        <para>
508          To change the source mode, use the <literal>[source-mode]</literal> markup,
509          where <literal>source-mode</literal> is one of the supported modes. For
510          example, this:
511        </para>
512       
513<programlisting><!--quickbook-escape-prefix-->Python's [python] `import` is rather like C++'s [c++] `#include`. A
514C++ comment `// looks like this` whereas a Python comment [python]
515`# looks like this`.
516<!--quickbook-escape-postfix--></programlisting>
517        <para>
518          will generate:
519        </para>
520        <para>
521          Python's <code><phrase role="keyword">import</phrase></code> is rather
522          like C++'s <code><phrase role="preprocessor">#include</phrase></code>.
523          A C++ comment <code><phrase role="comment">// looks like this</phrase></code>
524          whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>.
525        </para>
526        <informaltable frame="all">
527          <bridgehead renderas="sect4">
528            <phrase role="table-title">Supported Source Modes</phrase>
529          </bridgehead>
530          <tgroup cols="2">
531            <thead>
532              <row>
533                <entry>Mode</entry><entry>Source Mode Markup</entry>
534              </row>
535            </thead>
536            <tbody>
537              <row>
538                <entry>C++</entry><entry><literal>[c++]</literal></entry>
539              </row>
540              <row>
541                <entry>Python</entry><entry><literal>[python]</literal></entry>
542              </row>
543            </tbody>
544          </tgroup>
545        </informaltable>
546        <informaltable frame="all">
547          <?dbhtml table-width="74%" ?>
548          <tgroup cols="1">
549            <tbody>
550              <row>
551                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
552                <textobject>
553                  <phrase>note</phrase>
554                </textobject>
555                </inlinemediaobject> The source mode strings are lowercase.</entry>
556              </row>
557            </tbody>
558          </tgroup>
559        </informaltable>
560      </section>
561      <section id="quickbook.syntax.phrase.line_break">
562        <title>line-break</title>
563<programlisting><!--quickbook-escape-prefix-->[br]
564<!--quickbook-escape-postfix--></programlisting>
565        <informaltable frame="all">
566          <?dbhtml table-width="74%" ?>
567          <tgroup cols="1">
568            <tbody>
569              <row>
570                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
571                <textobject>
572                  <phrase>note</phrase>
573                </textobject>
574                </inlinemediaobject> Note that <code><phrase role="special">\</phrase><phrase
575                role="identifier">n</phrase></code> is now preferred over <code><phrase
576                role="special">[</phrase><phrase role="identifier">br</phrase><phrase
577                role="special">]</phrase></code>.</entry>
578              </row>
579            </tbody>
580          </tgroup>
581        </informaltable>
582      </section>
583      <section id="quickbook.syntax.phrase.anchors">
584        <title>Anchors</title>
585<programlisting><!--quickbook-escape-prefix-->[#named_anchor]
586<!--quickbook-escape-postfix--></programlisting>
587        <para>
588          A named anchor is a hook that can be referenced by a link elsewhere in
589          the document. You can then reference an anchor with <literal>
590<!--quickbook-escape-prefix-->[link named_anchor
591Some link text]<!--quickbook-escape-postfix-->
592          </literal>. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
593          links</link>, <link linkend="quickbook.syntax.block.section">Section</link>
594          and <link linkend="quickbook.syntax.block.headings">Heading</link>.
595        </para>
596      </section>
597      <section id="quickbook.syntax.phrase.links">
598        <title>Links</title>
599<programlisting><!--quickbook-escape-prefix-->[@http://www.boost.org this is [*boost's] website....]
600<!--quickbook-escape-postfix--></programlisting>
601        <para>
602          will generate:
603        </para>
604        <para>
605          <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis>
606          website....</ulink>
607        </para>
608        <para>
609          URL links where the link text is the link itself is common. Example:
610        </para>
611       
612<programlisting><!--quickbook-escape-prefix-->see http://spirit.sourceforge.net/
613<!--quickbook-escape-postfix--></programlisting>
614        <para>
615          so, when the text is absent in a link markup, the URL is assumed. Example:
616        </para>
617       
618<programlisting>see <!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net/]<!--quickbook-escape-postfix-->
619</programlisting>
620        <para>
621          will generate:
622        </para>
623        <para>
624          see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink>
625        </para>
626      </section>
627      <section id="quickbook.syntax.phrase.anchor_links">
628        <title>Anchor links</title>
629        <para>
630          You can link within a document using:
631        </para>
632       
633<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
634<!--quickbook-escape-postfix--></programlisting>
635        <para>
636          See sections <link linkend="quickbook.syntax.block.section">Section</link>
637          and <link linkend="quickbook.syntax.block.headings">Heading</link> for
638          more info.
639        </para>
640      </section>
641      <section id="quickbook.syntax.phrase.refentry_links">
642        <title>refentry links</title>
643        <para>
644          In addition, you can link internally to an XML refentry like:
645        </para>
646       
647<programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text]
648<!--quickbook-escape-postfix--></programlisting>
649        <para>
650          This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;The
651          link text&lt;/link&gt;</literal>.
652        </para>
653        <para>
654          Like URLs, the link text is optional. If this is not present, the link
655          text will automatically be the refentry. Example:
656        </para>
657       
658<programlisting><!--quickbook-escape-prefix-->[link xml.refentry]
659<!--quickbook-escape-postfix--></programlisting>
660        <para>
661          This gets converted into <literal>&lt;link linkend=&quot;xml.refentry&quot;&gt;xml.refentry&lt;/link&gt;</literal>.
662        </para>
663      </section>
664      <section id="quickbook.syntax.phrase.code_links">
665        <title> Code Links</title>
666        <para>
667          If you want to link to a function, class, member, enum or header in the
668          reference section, you can use:
669        </para>
670       
671<programlisting><!--quickbook-escape-prefix-->[funcref fully::qualified::function_name The link text]
672[classref fully::qualified::class_name The link text]
673[memberref fully::qualified::member_name The link text]
674[enumref fully::qualified::enum_name The link text]
675[headerref path/to/header.hpp The link text]
676<!--quickbook-escape-postfix--></programlisting>
677        <para>
678          Again, the link text is optional. If this is not present, the link text
679          will automatically be the function, class, member or enum. Example:
680        </para>
681       
682<programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz]
683<!--quickbook-escape-postfix--></programlisting>
684        <para>
685          would have &quot;boost::bar::baz&quot; as the link text.
686        </para>
687      </section>
688      <section id="quickbook.syntax.phrase.escape">
689        <title>Escape</title>
690        <para>
691          The escape mark-up is used when we don't want to do any processing.
692        </para>
693       
694<programlisting>'''
695escape (no processing/formatting)
696'''
697</programlisting>
698        <para>
699          Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
700          or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
701        </para>
702       
703<programlisting>'''
704&lt;emphasis role=&quot;bold&quot;&gt;This is direct XML markup&lt;/emphasis&gt;
705'''
706</programlisting>
707        <para>
708         
709<!--quickbook-escape-prefix--><emphasis role="bold">This is direct XML markup</emphasis>
710<!--quickbook-escape-postfix-->
711        </para>
712        <informaltable frame="all">
713          <?dbhtml table-width="74%" ?>
714          <tgroup cols="1">
715            <tbody>
716              <row>
717                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/alert.png"></imagedata></imageobject>
718                <textobject>
719                  <phrase>alert</phrase>
720                </textobject>
721                </inlinemediaobject> Be careful when using the escape. The text must
722                conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink
723                url="http://www.docbook.org/">DocBook</ulink> syntax.</entry>
724              </row>
725            </tbody>
726          </tgroup>
727        </informaltable>
728      </section>
729      <section id="quickbook.syntax.phrase.single_char_escape">
730        <title>Single char escape</title>
731        <para>
732          The backslash may be used to escape a single punctuation character. The
733          punctuation immediately after the backslash is passed without any processing.
734          This is useful when we need to escape QuickBook punctuations such as <code><phrase
735          role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>.
736          For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal>
737        </para>
738        <para>
739          <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
740          has a special meaning. It is used to generate line breaks. Note that <code><phrase
741          role="special">\</phrase><phrase role="identifier">n</phrase></code> is
742          now preferred over <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
743          role="special">]</phrase></code>.
744        </para>
745      </section>
746      <section id="quickbook.syntax.phrase.images">
747        <title>Images</title>
748<programlisting><!--quickbook-escape-prefix-->[$image.jpg]
749<!--quickbook-escape-postfix--></programlisting>
750      </section>
751      <section id="quickbook.syntax.phrase.footnotes">
752        <title>Footnotes</title>
753        <para>
754          As of version 1.3, QuickBook supports footnotes. Just put the text of the
755          footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase
756          role="special">]</phrase></code> block, and the text will be put at the
757          bottom of the current page. For example, this:
758        </para>
759       
760<programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote]
761<!--quickbook-escape-postfix--></programlisting>
762        <para>
763          will generate this
764          <footnote>
765            <para>
766              A sample footnote
767            </para>
768          </footnote>
769          .
770        </para>
771      </section>
772    </section>
773    <section id="quickbook.syntax.block">
774      <title> Block Level Elements</title>
775      <section id="quickbook.syntax.block.document">
776        <title>Document</title>
777        <para>
778          Every document must begin with a Document Info section, which should look
779          like this:
780        </para>
781       
782<programlisting><!--quickbook-escape-prefix-->[document-type The Document Title
783    [quickbook 1.3]
784    [version 1.0]
785    [id the_document_name]
786    [dirname the_document_dir]
787    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
788    [purpose The document's reason for being]
789    [category The document's category]
790    [authors [Blow, Joe], [Doe, Jane]]
791    [license The document's license]
792    [source-mode source-type]
793]
794<!--quickbook-escape-postfix--></programlisting>
795        <para>
796          Where document-type is one of:
797        </para>
798        <itemizedlist>
799          <listitem>
800            book
801          </listitem>
802          <listitem>
803            article
804          </listitem>
805          <listitem>
806            library
807          </listitem>
808          <listitem>
809            chapter
810          </listitem>
811          <listitem>
812            part
813          </listitem>
814          <listitem>
815            appendix
816          </listitem>
817          <listitem>
818            preface
819          </listitem>
820          <listitem>
821            qandadiv
822          </listitem>
823          <listitem>
824            qandaset
825          </listitem>
826          <listitem>
827            reference
828          </listitem>
829          <listitem>
830            set
831          </listitem>
832        </itemizedlist>
833        <para>
834          quickbook 1.3 declares the version of quickbook the document is written
835          for. In its absence, version 1.1 is assumed.
836        </para>
837        <para>
838          <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
839          <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
840          <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
841          and <literal>source-mode</literal> are optional information.
842        </para>
843        <para>
844          <literal>source-type</literal> is a lowercase string setting the initial
845          <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
846          If the <literal>source-mode</literal> field is omitted, a default value
847          of <literal>c++</literal> will be used.
848        </para>
849      </section>
850      <section id="quickbook.syntax.block.section">
851        <title>Section</title>
852        <para>
853          Starting a new section is accomplished with:
854        </para>
855       
856<programlisting><!--quickbook-escape-prefix-->[section:id The Section Title]
857<!--quickbook-escape-postfix--></programlisting>
858        <para>
859          where <emphasis>id</emphasis> is optional. id will be the filename of the
860          generated section. If it is not present, &quot;The Section Title&quot;
861          will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
862          <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
863          All non-valid characters are converted to underscore and all upper-case
864          are converted to lower case. Thus: &quot;The Section Title&quot; will be
865          normalized to &quot;the_section_title&quot;.
866        </para>
867        <para>
868          End a section with:
869        </para>
870       
871<programlisting><!--quickbook-escape-prefix-->[endsect]
872<!--quickbook-escape-postfix--></programlisting>
873        <para>
874          Sections can nest, and that results in a hierarchy in the table of contents.
875        </para>
876      </section>
877      <section id="quickbook.syntax.block.xinclude">
878        <title>xinclude</title>
879        <para>
880          You can include another XML file with:
881        </para>
882       
883<programlisting><!--quickbook-escape-prefix-->[xinclude file.xml]
884<!--quickbook-escape-postfix--></programlisting>
885        <para>
886          This is useful when file.xml has been generated by Doxygen and contains
887          your reference section.
888        </para>
889      </section>
890      <section id="quickbook.syntax.block.paragraphs">
891        <title>Paragraphs</title>
892        <para>
893          Paragraphs start left-flushed and are terminated by two or more newlines.
894          No markup is needed for paragraphs. QuickBook automatically detects paragraphs
895          from the context. Block markups [section, endsect, h1, h2, h3, h4, h5,
896          h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate
897          a paragraph.
898        </para>
899      </section>
900      <section id="quickbook.syntax.block.lists">
901        <title>Lists</title>
902        <section id="quickbook.syntax.block.lists.ordered_lists">
903          <title>Ordered lists</title>
904<programlisting># One
905# Two
906# Three
907</programlisting>
908          <para>
909            will generate:
910          </para>
911          <orderedlist>
912            <listitem>
913              One
914            </listitem>
915            <listitem>
916              Two
917            </listitem>
918            <listitem>
919              Three
920            </listitem>
921          </orderedlist>
922        </section>
923        <section id="quickbook.syntax.block.lists.list_hierarchies">
924          <title>List Hierarchies</title>
925          <para>
926            List hierarchies are supported. Example:
927          </para>
928         
929<programlisting># One
930# Two
931# Three
932    # Three.a
933    # Three.b
934    # Three.c
935# Four
936    # Four.a
937        # Four.a.i
938        # Four.a.ii
939# Five
940</programlisting>
941          <para>
942            will generate:
943          </para>
944          <orderedlist>
945            <listitem>
946              One
947            </listitem>
948            <listitem>
949              Two
950            </listitem>
951            <listitem>
952              Three
953              <orderedlist>
954                <listitem>
955                  Three.a
956                </listitem>
957                <listitem>
958                  Three.b
959                </listitem>
960                <listitem>
961                  Three.c
962                </listitem>
963              </orderedlist>
964            </listitem>
965            <listitem>
966              Fourth
967              <orderedlist>
968                <listitem>
969                  Four.a
970                  <orderedlist>
971                    <listitem>
972                      Four.a.i
973                    </listitem>
974                    <listitem>
975                      Four.a.ii
976                    </listitem>
977                  </orderedlist>
978                </listitem>
979              </orderedlist>
980            </listitem>
981            <listitem>
982              Five
983            </listitem>
984          </orderedlist>
985        </section>
986        <section id="quickbook.syntax.block.lists.long_list_lines">
987          <title>Long List Lines</title>
988          <para>
989            Long lines will be wrapped appropriately. Example:
990          </para>
991         
992<programlisting># A short item.
993# A very long item. A very long item. A very long item.
994  A very long item. A very long item. A very long item.
995  A very long item. A very long item. A very long item.
996  A very long item. A very long item. A very long item.
997  A very long item. A very long item. A very long item.
998# A short item.
999</programlisting>
1000          <orderedlist>
1001            <listitem>
1002              A short item.
1003            </listitem>
1004            <listitem>
1005              A very long item. A very long item. A very long item. A very long item.
1006              A very long item. A very long item. A very long item. A very long item.
1007              A very long item. A very long item. A very long item. A very long item.
1008              A very long item. A very long item. A very long item.
1009            </listitem>
1010            <listitem>
1011              A short item.
1012            </listitem>
1013          </orderedlist>
1014        </section>
1015        <section id="quickbook.syntax.block.lists.unordered_lists">
1016          <title>Unordered lists</title>
1017<programlisting><!--quickbook-escape-prefix-->* First
1018* Second
1019* Third
1020<!--quickbook-escape-postfix--></programlisting>
1021          <para>
1022            will generate:
1023          </para>
1024          <itemizedlist>
1025            <listitem>
1026              First
1027            </listitem>
1028            <listitem>
1029              Second
1030            </listitem>
1031            <listitem>
1032              Third
1033            </listitem>
1034          </itemizedlist>
1035        </section>
1036        <section id="quickbook.syntax.block.lists.mixed_lists">
1037          <title>Mixed lists</title>
1038          <para>
1039            Mixed lists (ordered and unordered) are supported. Example:
1040          </para>
1041         
1042<programlisting><!--quickbook-escape-prefix--># One
1043# Two
1044# Three
1045    * Three.a
1046    * Three.b
1047    * Three.c
1048# Four
1049<!--quickbook-escape-postfix--></programlisting>
1050          <para>
1051            will generate:
1052          </para>
1053          <orderedlist>
1054            <listitem>
1055              One
1056            </listitem>
1057            <listitem>
1058              Two
1059            </listitem>
1060            <listitem>
1061              Three
1062              <itemizedlist>
1063                <listitem>
1064                  Three.a
1065                </listitem>
1066                <listitem>
1067                  Three.b
1068                </listitem>
1069                <listitem>
1070                  Three.c
1071                </listitem>
1072              </itemizedlist>
1073            </listitem>
1074            <listitem>
1075              Four
1076            </listitem>
1077          </orderedlist>
1078          <para>
1079            And...
1080          </para>
1081         
1082<programlisting><!--quickbook-escape-prefix--># 1
1083    * 1.a
1084        # 1.a.1
1085        # 1.a.2
1086    * 1.b
1087# 2
1088    * 2.a
1089    * 2.b
1090        # 2.b.1
1091        # 2.b.2
1092            * 2.b.2.a
1093            * 2.b.2.b
1094<!--quickbook-escape-postfix--></programlisting>
1095          <para>
1096            will generate:
1097          </para>
1098          <orderedlist>
1099            <listitem>
1100              1
1101              <itemizedlist>
1102                <listitem>
1103                  1.a
1104                  <orderedlist>
1105                    <listitem>
1106                      1.a.1
1107                    </listitem>
1108                    <listitem>
1109                      1.a.2
1110                    </listitem>
1111                  </orderedlist>
1112                </listitem>
1113                <listitem>
1114                  1.b
1115                </listitem>
1116              </itemizedlist>
1117            </listitem>
1118            <listitem>
1119              2
1120              <itemizedlist>
1121                <listitem>
1122                  2.a
1123                </listitem>
1124                <listitem>
1125                  2.b
1126                  <orderedlist>
1127                    <listitem>
1128                      2.b.1
1129                    </listitem>
1130                    <listitem>
1131                      2.b.2
1132                      <itemizedlist>
1133                        <listitem>
1134                          2.b.2.a
1135                        </listitem>
1136                        <listitem>
1137                          2.b.2.b
1138                        </listitem>
1139                      </itemizedlist>
1140                    </listitem>
1141                  </orderedlist>
1142                </listitem>
1143              </itemizedlist>
1144            </listitem>
1145          </orderedlist>
1146        </section>
1147      </section>
1148      <section id="quickbook.syntax.block.code">
1149        <title>Code</title>
1150        <para>
1151          Preformatted code starts with a space or a tab. The code will be syntax
1152          highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
1153          Mode</link>:
1154        </para>
1155        <para>
1156        </para>
1157       
1158<programlisting>
1159<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
1160
1161<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
1162<phrase role="special">{</phrase>
1163    <phrase role="comment">// Sample code
1164</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>
1165    <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
1166<phrase role="special">}</phrase>
1167</programlisting>
1168        <para>
1169        </para>
1170       
1171<programlisting>
1172<phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase>
1173
1174<phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase>
1175    <phrase role="string">'''&quot;Cooks&quot; the input text for HTML.'''</phrase>
1176
1177    <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>
1178</programlisting>
1179        <para>
1180          Macros that are already defined are expanded in source code. Example:
1181        </para>
1182       
1183<programlisting><!--quickbook-escape-prefix-->[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
1184[def __quickbook__ [@index.html quickbook]]
1185
1186    using __quickbook__::__syntax_highlight__;
1187<!--quickbook-escape-postfix--></programlisting>
1188        <para>
1189          Generates:
1190        </para>
1191       
1192<programlisting>
1193<phrase role="identifier">using</phrase> <ulink url="index.html">quickbook</ulink><phrase role="special">::</phrase><ulink url="quickbook/highlight.html">syntax_highlight</ulink><phrase role="special">;</phrase>
1194</programlisting>
1195      </section>
1196      <section id="quickbook.syntax.block.escape_back">
1197        <title> Escaping Back To QuickBook</title>
1198        <para>
1199          Inside code, code blocks and inline code, QuickBook does not allow any
1200          markup to avoid conflicts with the target syntax (e.g. c++). In case you
1201          need to switch back to QuickBook markup inside code, you can do so using
1202          a language specific <emphasis>escape-back</emphasis> delimiter. In C++
1203          and Python, the delimiter is the double tick (back-quote): &quot;``&quot;
1204          and &quot;``&quot;. Example:
1205        </para>
1206       
1207<programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
1208{
1209}
1210<!--quickbook-escape-postfix--></programlisting>
1211        <para>
1212          Will generate:
1213        </para>
1214       
1215<programlisting>
1216<phrase role="identifier">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
1217<phrase role="special">{</phrase>
1218<phrase role="special">}</phrase>
1219</programlisting>
1220        <para>
1221          When escaping from code to QuickBook, only phrase level markups are allowed.
1222          Block level markups like lists, tables etc. are not allowed.
1223        </para>
1224      </section>
1225      <section id="quickbook.syntax.block.preformatted">
1226        <title>Preformatted</title>
1227        <para>
1228          Sometimes, you don't want some preformatted text to be parsed as C++. In
1229          such cases, use the <literal>[pre ... ]</literal> markup block.
1230        </para>
1231       
1232<programlisting><!--quickbook-escape-prefix-->[pre
1233
1234    Some *preformatted* text                    Some *preformatted* text
1235
1236        Some *preformatted* text            Some *preformatted* text
1237
1238            Some *preformatted* text    Some *preformatted* text
1239
1240]
1241<!--quickbook-escape-postfix--></programlisting>
1242        <para>
1243          Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
1244          level markup, pre (and Code) are the only ones that allow multiple newlines.
1245          The markup above will generate:
1246        </para>
1247       
1248<programlisting>Some <emphasis role="bold">preformatted</emphasis> text                    Some <emphasis role="bold">preformatted</emphasis> text
1249
1250    Some <emphasis role="bold">preformatted</emphasis> text            Some <emphasis role="bold">preformatted</emphasis> text
1251
1252        Some <emphasis role="bold">preformatted</emphasis> text    Some <emphasis role="bold">preformatted</emphasis> text
1253
1254</programlisting>
1255        <para>
1256          Notice that unlike Code, phrase markup such as font style is still permitted
1257          inside <literal>pre</literal> blocks.
1258        </para>
1259      </section>
1260      <section id="quickbook.syntax.block.blockquote">
1261        <title>Blockquote</title>
1262<programlisting><!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix-->
1263</programlisting>
1264        <blockquote>
1265          <para>
1266            Indents the paragraph. This applies to one paragraph only.
1267          </para>
1268        </blockquote>
1269      </section>
1270      <section id="quickbook.syntax.block.admonitions">
1271        <title>Admonitions</title>
1272<programlisting><!--quickbook-escape-prefix-->[note This is a note]
1273[tip This is a tip]
1274[important This is important]
1275[caution This is a caution]
1276[warning This is a warning]
1277<!--quickbook-escape-postfix--></programlisting>
1278        <para>
1279          generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions:
1280        </para>
1281        <note>
1282          <para>
1283            This is a note
1284          </para>
1285        </note>
1286        <tip>
1287          <para>
1288            This is a tip
1289          </para>
1290        </tip>
1291        <important>
1292          <para>
1293            This is important
1294          </para>
1295        </important>
1296        <caution>
1297          <para>
1298            This is a caution
1299          </para>
1300        </caution>
1301        <warning>
1302          <para>
1303            This is a warning
1304          </para>
1305        </warning>
1306        <para>
1307          These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>.
1308          So, for example <literal>[information This is some information]</literal>
1309          is unlikely to produce the desired effect.
1310        </para>
1311      </section>
1312      <section id="quickbook.syntax.block.headings">
1313        <title>Headings</title>
1314<programlisting><!--quickbook-escape-prefix-->[h1 Heading 1]
1315[h2 Heading 2]
1316[h3 Heading 3]
1317[h4 Heading 4]
1318[h5 Heading 5]
1319[h6 Heading 6]
1320<!--quickbook-escape-postfix--></programlisting>
1321        <anchor id="quickbook.syntax.block.headings.heading_1" />
1322        <bridgehead renderas="sect1">
1323          Heading 1
1324        </bridgehead>
1325        <anchor id="quickbook.syntax.block.headings.heading_2" />
1326        <bridgehead renderas="sect2">
1327          Heading 2
1328        </bridgehead>
1329        <anchor id="quickbook.syntax.block.headings.heading_3" />
1330        <bridgehead renderas="sect3">
1331          Heading 3
1332        </bridgehead>
1333        <anchor id="quickbook.syntax.block.headings.heading_4" />
1334        <bridgehead renderas="sect4">
1335          Heading 4
1336        </bridgehead>
1337        <anchor id="quickbook.syntax.block.headings.heading_5" />
1338        <bridgehead renderas="sect5">
1339          Heading 5
1340        </bridgehead>
1341        <anchor id="quickbook.syntax.block.headings.heading_6" />
1342        <bridgehead renderas="sect6">
1343          Heading 6
1344        </bridgehead>
1345        <para>
1346          Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
1347          names with <literal>name=&quot;section_id.normalized_header_text&quot;</literal>
1348          (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
1349          <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
1350          are converted to underscore and all upper-case are converted to lower-case.
1351          For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>).
1352          You can use:
1353        </para>
1354       
1355<programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
1356<!--quickbook-escape-postfix--></programlisting>
1357        <para>
1358          to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
1359          links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
1360          for more info.
1361        </para>
1362      </section>
1363      <section id="quickbook.syntax.block.macros">
1364        <title>Macros</title>
1365<programlisting><!--quickbook-escape-prefix-->[def macro_identifier some text]
1366<!--quickbook-escape-postfix--></programlisting>
1367        <para>
1368          When a macro is defined, the identifier replaces the text anywhere in the
1369          file, in paragraphs, in markups, etc. macro_identifier is a string of non-white
1370          space characters except ']' while the replacement text can be any phrase
1371          (even marked up). Example:
1372        </para>
1373       
1374<programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1]]
1375sf_logo
1376<!--quickbook-escape-postfix--></programlisting>
1377        <para>
1378          Now everywhere the sf_logo is placed, the picture will be inlined.
1379        </para>
1380        <para>
1381          <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></imagedata></imageobject>
1382          <textobject>
1383            <phrase>sflogo</phrase>
1384          </textobject>
1385          </inlinemediaobject>
1386        </para>
1387        <informaltable frame="all">
1388          <?dbhtml table-width="74%" ?>
1389          <tgroup cols="1">
1390            <tbody>
1391              <row>
1392                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
1393                <textobject>
1394                  <phrase>tip</phrase>
1395                </textobject>
1396                </inlinemediaobject> It's a good idea to use macro identifiers that
1397                are distinguishable. For instance, in this document, macro identifiers
1398                have two leading and trailing underscores (e.g. <literal>
1399<!--quickbook-escape-prefix-->__spirit__<!--quickbook-escape-postfix-->
1400                </literal>). The reason is to avoid unwanted macro replacement.</entry>
1401              </row>
1402            </tbody>
1403          </tgroup>
1404        </informaltable>
1405        <para>
1406          Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>)
1407          They tend to change a lot. It is a good idea to place all links and images
1408          in one place near the top to make it easy to make changes. <emphasis role="bold">2</emphasis>)
1409          The syntax is not pretty. It's easier to read and write, e.g. <literal>
1410<!--quickbook-escape-prefix-->__spirit__<!--quickbook-escape-postfix-->
1411          </literal> than <literal>
1412<!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net Spirit]<!--quickbook-escape-postfix-->
1413          </literal>.
1414        </para>
1415        <para>
1416          Some more examples:
1417        </para>
1418       
1419<programlisting><!--quickbook-escape-prefix-->[def :-)            [$theme/smiley.png]]
1420[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
1421<!--quickbook-escape-postfix--></programlisting>
1422        <para>
1423          (See <link linkend="quickbook.syntax.phrase.images">Images</link> and
1424          <link linkend="quickbook.syntax.phrase.links">Links</link>)
1425        </para>
1426        <para>
1427          Invoking these macros:
1428        </para>
1429       
1430<programlisting><!--quickbook-escape-prefix-->Hi __spirit__  :-)
1431<!--quickbook-escape-postfix--></programlisting>
1432        <para>
1433          will generate this:
1434        </para>
1435        <para>
1436          Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink>&nbsp;<inlinemediaobject><imageobject><imagedata
1437          fileref="images/smiley.png"></imagedata></imageobject>
1438          <textobject>
1439            <phrase>smiley</phrase>
1440          </textobject>
1441          </inlinemediaobject>
1442        </para>
1443      </section>
1444      <section id="quickbook.syntax.block.predefined_macros">
1445        <title>Predefined Macros</title>
1446        <para>
1447          Quickbook has some predefined macros that you can already use.
1448        </para>
1449        <informaltable frame="all">
1450          <bridgehead renderas="sect4">
1451            <phrase role="table-title">Predefined Macros</phrase>
1452          </bridgehead>
1453          <tgroup cols="3">
1454            <thead>
1455              <row>
1456                <entry>Macro</entry><entry>Meaning</entry><entry>Example</entry>
1457              </row>
1458            </thead>
1459            <tbody>
1460              <row>
1461                <entry>
1462<!--quickbook-escape-prefix-->__DATE__<!--quickbook-escape-postfix-->
1463                </entry><entry>Today's date</entry><entry>2000-Dec-20</entry>
1464              </row>
1465              <row>
1466                <entry>
1467<!--quickbook-escape-prefix-->__TIME__<!--quickbook-escape-postfix-->
1468                </entry><entry>The current time</entry><entry>12:00:00 PM</entry>
1469              </row>
1470              <row>
1471                <entry>
1472<!--quickbook-escape-prefix-->__FILENAME__<!--quickbook-escape-postfix-->
1473                </entry><entry>Quickbook source filename</entry><entry>NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE</entry>
1474              </row>
1475            </tbody>
1476          </tgroup>
1477        </informaltable>
1478      </section>
1479      <section id="quickbook.syntax.block.blurbs">
1480        <title>Blurbs</title>
1481<programlisting><!--quickbook-escape-prefix-->[blurb :-) [*An eye catching advertisement or note...]\n\n
1482    __spirit__ is an object-oriented recursive-descent parser generator framework
1483    implemented using template meta-programming techniques. Expression templates
1484    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
1485    completely in C++.
1486]
1487<!--quickbook-escape-postfix--></programlisting>
1488        <para>
1489          will generate this:
1490        </para>
1491        <informaltable frame="all">
1492          <?dbhtml table-width="74%" ?>
1493          <tgroup cols="1">
1494            <tbody>
1495              <row>
1496                <entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
1497                <textobject>
1498                  <phrase>smiley</phrase>
1499                </textobject>
1500                </inlinemediaobject>&nbsp;<emphasis role="bold">An eye catching advertisement
1501                or note...</emphasis><sbr/> <sbr/> <ulink url="http://spirit.sourceforge.net">Spirit</ulink>
1502                is an object-oriented recursive-descent parser generator framework
1503                implemented using template meta-programming techniques. Expression
1504                templates allow us to approximate the syntax of Extended Backus-Normal
1505                Form (EBNF) completely in C++. </entry>
1506              </row>
1507            </tbody>
1508          </tgroup>
1509        </informaltable>
1510      </section>
1511      <section id="quickbook.syntax.block.tables">
1512        <title>Tables</title>
1513<programlisting><!--quickbook-escape-prefix-->[table A Simple Table
1514    [[Heading 1] [Heading 2] [Heading 3]]
1515    [[R0-C0]     [R0-C1]     [R0-C2]]
1516    [[R1-C0]     [R1-C1]     [R1-C2]]
1517    [[R2-C0]     [R2-C1]     [R2-C2]]
1518]
1519<!--quickbook-escape-postfix--></programlisting>
1520        <para>
1521          will generate:
1522        </para>
1523        <informaltable frame="all">
1524          <bridgehead renderas="sect4">
1525            <phrase role="table-title">A Simple Table</phrase>
1526          </bridgehead>
1527          <tgroup cols="3">
1528            <thead>
1529              <row>
1530                <entry>Heading 1</entry><entry>Heading 2</entry><entry>Heading 3</entry>
1531              </row>
1532            </thead>
1533            <tbody>
1534              <row>
1535                <entry>R0-C0</entry><entry>R0-C1</entry><entry>R0-C2</entry>
1536              </row>
1537              <row>
1538                <entry>R2-C0</entry><entry>R2-C1</entry><entry>R2-C2</entry>
1539              </row>
1540              <row>
1541                <entry>R3-C0</entry><entry>R3-C1</entry><entry>R3-C2</entry>
1542              </row>
1543            </tbody>
1544          </tgroup>
1545        </informaltable>
1546        <para>
1547          The table title is optional. The first row of the table is automatically
1548          treated as the table header; that is, it is wrapped in <literal>&lt;thead&gt;...&lt;/thead&gt;</literal>
1549          XML tags. Note that unlike the original QuickDoc, the columns are nested
1550          in [ cells... ]. The syntax is free-format and allows big cells to be formatted
1551          nicely. Example:
1552        </para>
1553       
1554<programlisting><!--quickbook-escape-prefix-->[table Table with fat cells
1555    [[Heading 1] [Heading 2]]
1556    [
1557        [Row 0, Col 0: a small cell]
1558        [
1559            Row 0, Col 1:
1560            A very big cell...A very big cell...A very big cell...
1561            A very big cell...A very big cell...A very big cell...
1562            A very big cell...A very big cell...A very big cell...
1563        ]
1564    ]
1565    [
1566        [Row 1, Col 0: a small cell]
1567        [Row 1, Col 1: a small cell]
1568    ]
1569]
1570<!--quickbook-escape-postfix--></programlisting>
1571        <para>
1572          and thus:
1573        </para>
1574        <informaltable frame="all">
1575          <bridgehead renderas="sect4">
1576            <phrase role="table-title">Table with fat cells</phrase>
1577          </bridgehead>
1578          <tgroup cols="2">
1579            <thead>
1580              <row>
1581                <entry>Heading 1</entry><entry>Heading 2</entry>
1582              </row>
1583            </thead>
1584            <tbody>
1585              <row>
1586                <entry>Row 0, Col 0: a small cell</entry><entry> Row 0, Col 1: A
1587                very big cell...A very big cell...A very big cell... A very big cell...A
1588                very big cell...A very big cell... A very big cell...A very big cell...A
1589                very big cell... </entry>
1590              </row>
1591              <row>
1592                <entry>Row 1, Col 0: a small cell</entry><entry>Row 1, Col 1: a small
1593                cell</entry>
1594              </row>
1595            </tbody>
1596          </tgroup>
1597        </informaltable>
1598        <para>
1599          Here's how to have preformatted blocks of code in a table cell:
1600        </para>
1601       
1602<programlisting><!--quickbook-escape-prefix-->[table Table with code
1603    [[Comment] [Code]]
1604    [
1605        [My first program]
1606        [<!--quickbook-escape-postfix-->``
1607            #include &lt;iostream&gt;
1608
1609            int main()
1610            {
1611                std::cout &lt;&lt; &quot;Hello, World!&quot; &lt;&lt; std::endl;
1612                return 0;
1613            }
1614        ``<!--quickbook-escape-prefix-->]
1615    ]
1616]
1617<!--quickbook-escape-postfix--></programlisting>
1618        <informaltable frame="all">
1619          <bridgehead renderas="sect4">
1620            <phrase role="table-title">Table with code</phrase>
1621          </bridgehead>
1622          <tgroup cols="2">
1623            <thead>
1624              <row>
1625                <entry>Comment</entry><entry>Code</entry>
1626              </row>
1627            </thead>
1628            <tbody>
1629              <row>
1630                <entry>My first program</entry><entry>
1631<programlisting>
1632<phrase role="comment">#include &lt;iostream&gt;
1633</phrase>
1634<phrase role="identifier">int</phrase>&nbsp;<phrase role="identifier">main</phrase><phrase role="special">()</phrase>
1635<phrase role="special">{</phrase>
1636    <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="string">&quot;Hello, World!&quot;</phrase>&nbsp;<phrase role="special">&lt;&lt;</phrase>&nbsp;<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
1637    <phrase role="keyword">return</phrase>&nbsp;<phrase role="number">0</phrase><phrase role="special">;</phrase>
1638<phrase role="special">}</phrase>
1639</programlisting>
1640                </entry>
1641              </row>
1642            </tbody>
1643          </tgroup>
1644        </informaltable>
1645      </section>
1646      <section id="quickbook.syntax.block.variable_lists">
1647        <title>Variable Lists</title>
1648<programlisting><!--quickbook-escape-prefix-->[variablelist A Variable List
1649    [[term 1] [The definition of term 1]]
1650    [[term 2] [The definition of term 2]]
1651    [[term 3] [The definition of term 3]]
1652]
1653<!--quickbook-escape-postfix--></programlisting>
1654        <para>
1655          will generate:
1656        </para>
1657        <variablelist>
1658          <title>A Variable List</title> <varlistentry><term>term 1</term>
1659          <listitem>
1660            The definition of term 1
1661          </listitem>
1662          </varlistentry> <varlistentry><term>term 2</term>
1663          <listitem>
1664            The definition of term 2
1665          </listitem>
1666          </varlistentry> <varlistentry><term>term 3</term>
1667          <listitem>
1668            The definition of term 3
1669          </listitem>
1670          </varlistentry>
1671        </variablelist>
1672        <para>
1673          The rules for variable lists are the same as for tables, except that only
1674          2 &quot;columns&quot; are allowed. The first column contains the terms,
1675          and the second column contains the definitions. Those familiar with HTML
1676          will recognize this as a &quot;definition list&quot;.
1677        </para>
1678      </section>
1679      <section id="quickbook.syntax.block.include">
1680        <title>Include</title>
1681        <para>
1682          You can include one QuickBook file from another. The syntax is simply:
1683        </para>
1684       
1685<programlisting><!--quickbook-escape-prefix-->[include someother.qbk]
1686<!--quickbook-escape-postfix--></programlisting>
1687        <para>
1688          The included file will be processed as if it had be cut and pasted into
1689          the current document, with the following exceptions:
1690        </para>
1691        <itemizedlist>
1692          <listitem>
1693            The
1694<!--quickbook-escape-prefix-->__FILENAME__<!--quickbook-escape-postfix-->
1695            predefined macro will reflect the name of the file currently being processed.
1696          </listitem>
1697          <listitem>
1698            Any macros defined in the included file are scoped to that file.
1699          </listitem>
1700        </itemizedlist>
1701        <para>
1702          As the number of included QuickBook files grows, so too does the likelihood
1703          of two sections having the same name. Since QuickBook generates an anchor
1704          for each section based on the section name, it is possible to end up with
1705          two identically named anchors, leading to link ambiguities. To resolve
1706          these ambiguities, the <literal>[include]</literal> directive lets you
1707          specify a document id to use for the included file. You can use it like
1708          this:
1709        </para>
1710       
1711<programlisting><!--quickbook-escape-prefix-->[include:someid someother.qbk]
1712<!--quickbook-escape-postfix--></programlisting>
1713        <para>
1714          When using this form, all auto-generated anchors will use &quot;someid&quot;
1715          as a unique prefix. So for instance, if there is a section in someother.qbk
1716          named &quot;Intro&quot;, the named anchor for that section will be &quot;someid.intro&quot;,
1717          and you can link to it with <literal>[link someid.intro The Intro]</literal>.
1718        </para>
1719      </section>
1720    </section>
1721  </section>
1722  <section id="quickbook.ref">
1723    <title> Quick Reference</title>
1724    <informaltable frame="all">
1725      <bridgehead renderas="sect4">
1726        <phrase role="table-title">Syntax Compendium</phrase>
1727      </bridgehead>
1728      <tgroup cols="3">
1729        <thead>
1730          <row>
1731            <entry>To do this...</entry><entry>Use this...</entry><entry>See this...</entry>
1732          </row>
1733        </thead>
1734        <tbody>
1735          <row>
1736            <entry>comment</entry><entry><literal>
1737<!--quickbook-escape-prefix-->[/ some comment]<!--quickbook-escape-postfix-->
1738            </literal></entry><entry><link linkend="quickbook.syntax.comments">Comments</link></entry>
1739          </row>
1740          <row>
1741            <entry><emphasis>italics</emphasis></entry><entry><literal>
1742<!--quickbook-escape-prefix-->['italics] or /italics/<!--quickbook-escape-postfix-->
1743            </literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
1744            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
1745            Simple formatting</link></entry>
1746          </row>
1747          <row>
1748            <entry><emphasis role="bold">bold</emphasis></entry><entry><literal>
1749<!--quickbook-escape-prefix-->[*bold] or *bold*<!--quickbook-escape-postfix-->
1750            </literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
1751            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
1752            Simple formatting</link></entry>
1753          </row>
1754          <row>
1755            <entry><emphasis role="underline">underline</emphasis></entry><entry><literal>
1756<!--quickbook-escape-prefix-->[_underline] or _underline_<!--quickbook-escape-postfix-->
1757            </literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
1758            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
1759            Simple formatting</link></entry>
1760          </row>
1761          <row>
1762            <entry><literal>teletype</literal></entry><entry><literal>
1763<!--quickbook-escape-prefix-->[^teletype] or =teletype=<!--quickbook-escape-postfix-->
1764            </literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
1765            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
1766            Simple formatting</link></entry>
1767          </row>
1768          <row>
1769            <entry><emphasis role="strikethrough">strikethrough</emphasis></entry><entry><literal>
1770<!--quickbook-escape-prefix-->[-strikethrough]<!--quickbook-escape-postfix-->
1771            </literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
1772            Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
1773            Simple formatting</link></entry>
1774          </row>
1775          <row>
1776            <entry>
1777            <replaceable>
1778              replaceable
1779            </replaceable>
1780            </entry><entry><literal>
1781<!--quickbook-escape-prefix-->[~replaceable]<!--quickbook-escape-postfix-->
1782            </literal></entry><entry><link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link></entry>
1783          </row>
1784          <row>
1785            <entry>source mode</entry><entry><literal>[c++]</literal> or <literal>[python]</literal></entry><entry><link
1786            linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></entry>
1787          </row>
1788          <row>
1789            <entry>inline code</entry><entry><literal>
1790<!--quickbook-escape-prefix-->`int main();`<!--quickbook-escape-postfix-->
1791            </literal></entry><entry><link linkend="quickbook.syntax.phrase.inline_code">Inline
1792            code</link></entry>
1793          </row>
1794          <row>
1795            <entry>code block</entry><entry><literal>
1796<!--quickbook-escape-prefix-->``int main();``<!--quickbook-escape-postfix-->
1797            </literal></entry><entry><link linkend="quickbook.syntax.block.code">Code</link></entry>
1798          </row>
1799          <row>
1800            <entry>code escape</entry><entry><literal>
1801<!--quickbook-escape-prefix-->``from c++ to QuickBook``<!--quickbook-escape-postfix-->
1802            </literal></entry><entry><link linkend="quickbook.syntax.block.escape_back">Escaping
1803            Back To QuickBook</link></entry>
1804          </row>
1805          <row>
1806            <entry>line break</entry><entry><literal>
1807<!--quickbook-escape-prefix-->[br] or \n<!--quickbook-escape-postfix-->
1808            </literal></entry><entry><link linkend="quickbook.syntax.phrase.line_break">line-break</link></entry>
1809          </row>
1810          <row>
1811            <entry>anchor</entry><entry><literal>
1812<!--quickbook-escape-prefix-->[#anchor]<!--quickbook-escape-postfix-->
1813            </literal></entry><entry><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></entry>
1814          </row>
1815          <row>
1816            <entry>link</entry><entry><literal>
1817<!--quickbook-escape-prefix-->[@http://www.boost.org Boost]<!--quickbook-escape-postfix-->
1818            </literal></entry><entry><link linkend="quickbook.syntax.phrase.links">Links</link></entry>
1819          </row>
1820          <row>
1821            <entry>anchor link</entry><entry><literal>
1822<!--quickbook-escape-prefix-->[link section.anchor Link text]<!--quickbook-escape-postfix-->
1823            </literal></entry><entry><link linkend="quickbook.syntax.phrase.anchor_links">Anchor
1824            links</link></entry>
1825          </row>
1826          <row>
1827            <entry>refentry link</entry><entry><literal>
1828<!--quickbook-escape-prefix-->[link xml.refentry Link text]<!--quickbook-escape-postfix-->
1829            </literal></entry><entry><link linkend="quickbook.syntax.phrase.refentry_links">refentry
1830            links</link></entry>
1831          </row>
1832          <row>
1833            <entry>function link</entry><entry><literal>
1834<!--quickbook-escape-prefix-->[funcref fully::qualified::function_name Link text]<!--quickbook-escape-postfix-->
1835            </literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
1836            class, member, enum or header links</link></entry>
1837          </row>
1838          <row>
1839            <entry>class link</entry><entry><literal>
1840<!--quickbook-escape-prefix-->[classref fully::qualified::class_name Link text]<!--quickbook-escape-postfix-->
1841            </literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
1842            class, member, enum or header links</link></entry>
1843          </row>
1844          <row>
1845            <entry>member link</entry><entry><literal>
1846<!--quickbook-escape-prefix-->[memberref fully::qualified::member_name Link text]<!--quickbook-escape-postfix-->
1847            </literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
1848            class, member, enum or header links</link></entry>
1849          </row>
1850          <row>
1851            <entry>enum link</entry><entry><literal>
1852<!--quickbook-escape-prefix-->[enumref fully::qualified::enum_name Link text]<!--quickbook-escape-postfix-->
1853            </literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
1854            class, member, enum or header links</link></entry>
1855          </row>
1856          <row>
1857            <entry>header link</entry><entry><literal>
1858<!--quickbook-escape-prefix-->[headerref path/to/header.hpp Link text]<!--quickbook-escape-postfix-->
1859            </literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
1860            class, member, enum or header links</link></entry>
1861          </row>
1862          <row>
1863            <entry>escape</entry><entry><literal>'''escaped text (no processing/formatting)'''</literal></entry><entry><link
1864            linkend="quickbook.syntax.phrase.escape">Escape</link></entry>
1865          </row>
1866          <row>
1867            <entry>single char escape</entry><entry><literal>\c</literal></entry><entry><link
1868            linkend="quickbook.syntax.phrase.single_char_escape">Single char escape</link></entry>
1869          </row>
1870          <row>
1871            <entry>images</entry><entry><literal>
1872<!--quickbook-escape-prefix-->[$image.jpg]<!--quickbook-escape-postfix-->
1873            </literal></entry><entry><link linkend="quickbook.syntax.phrase.images">Images</link></entry>
1874          </row>
1875          <row>
1876            <entry>begin section</entry><entry><literal>
1877<!--quickbook-escape-prefix-->[section The Section Title]<!--quickbook-escape-postfix-->
1878            </literal></entry><entry><link linkend="quickbook.syntax.block.section">Section</link></entry>
1879          </row>
1880          <row>
1881            <entry>end section</entry><entry><literal>
1882<!--quickbook-escape-prefix-->[endsect]<!--quickbook-escape-postfix-->
1883            </literal></entry><entry><link linkend="quickbook.syntax.block.section">Section</link></entry>
1884          </row>
1885          <row>
1886            <entry>paragraph</entry><entry>No markup. Paragraphs start left-flushed
1887            and are terminated by two or more newlines.</entry><entry><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></entry>
1888          </row>
1889          <row>
1890            <entry>ordered list</entry><entry><literal># one<sbr/> # two<sbr/> #
1891            three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
1892            lists</link></entry>
1893          </row>
1894          <row>
1895            <entry>unordered list</entry><entry><literal>* one<sbr/> * two<sbr/>
1896            * three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
1897            lists</link></entry>
1898          </row>
1899          <row>
1900            <entry>code</entry><entry>No markup. Preformatted code starts with a
1901            space or a tab.</entry><entry><link linkend="quickbook.syntax.block.code">Code</link></entry>
1902          </row>
1903          <row>
1904            <entry>preformatted</entry><entry><literal>
1905<!--quickbook-escape-prefix-->[pre preformatted]<!--quickbook-escape-postfix-->
1906            </literal></entry><entry><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></entry>
1907          </row>
1908          <row>
1909            <entry>block quote</entry><entry><literal>
1910<!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix-->
1911            </literal></entry><entry><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></entry>
1912          </row>
1913          <row>
1914            <entry>heading 1</entry><entry><literal>
1915<!--quickbook-escape-prefix-->[h1 Heading 1]<!--quickbook-escape-postfix-->
1916            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1917          </row>
1918          <row>
1919            <entry>heading 2</entry><entry><literal>
1920<!--quickbook-escape-prefix-->[h2 Heading 2]<!--quickbook-escape-postfix-->
1921            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1922          </row>
1923          <row>
1924            <entry>heading 3</entry><entry><literal>
1925<!--quickbook-escape-prefix-->[h3 Heading 3]<!--quickbook-escape-postfix-->
1926            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1927          </row>
1928          <row>
1929            <entry>heading 4</entry><entry><literal>
1930<!--quickbook-escape-prefix-->[h4 Heading 4]<!--quickbook-escape-postfix-->
1931            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1932          </row>
1933          <row>
1934            <entry>heading 5</entry><entry><literal>
1935<!--quickbook-escape-prefix-->[h5 Heading 5]<!--quickbook-escape-postfix-->
1936            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1937          </row>
1938          <row>
1939            <entry>heading 6</entry><entry><literal>
1940<!--quickbook-escape-prefix-->[h6 Heading 6]<!--quickbook-escape-postfix-->
1941            </literal></entry><entry><link linkend="quickbook.syntax.block.headings">Heading</link></entry>
1942          </row>
1943          <row>
1944            <entry>macro</entry><entry><literal>
1945<!--quickbook-escape-prefix-->[def macro_identifier some text]<!--quickbook-escape-postfix-->
1946            </literal></entry><entry><link linkend="quickbook.syntax.block.macros">Macros</link></entry>
1947          </row>
1948          <row>
1949            <entry>blurb</entry><entry><literal>
1950<!--quickbook-escape-prefix-->[blurb advertisement or note...]<!--quickbook-escape-postfix-->
1951            </literal></entry><entry><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></entry>
1952          </row>
1953          <row>
1954            <entry>admonition</entry><entry><literal>
1955<!--quickbook-escape-prefix-->[warning Warning text...]<!--quickbook-escape-postfix-->
1956            </literal></entry><entry><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></entry>
1957          </row>
1958          <row>
1959            <entry>table</entry><entry><literal>[table Title<sbr/> [[a][b][c]]<sbr/>
1960            [[a][b][c]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.tables">Tables</link></entry>
1961          </row>
1962          <row>
1963            <entry>variablelist</entry><entry><literal>[variablelist Title<sbr/>
1964            [[a][b]]<sbr/> [[a][b]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.variable_lists">Variable
1965            Lists</link></entry>
1966          </row>
1967          <row>
1968            <entry>include</entry><entry><literal>
1969<!--quickbook-escape-prefix-->[include someother.qbk]<!--quickbook-escape-postfix-->
1970            </literal></entry><entry><link linkend="quickbook.syntax.block.include">Include</link></entry>
1971          </row>
1972        </tbody>
1973      </tgroup>
1974    </informaltable>
1975  </section>
1976</article>
Note: See TracBrowser for help on using the repository browser.