Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/tools/quickbook/doc/quickbook.xml @ 45

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

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