1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
3 <article id="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $" xmlns:xi="http://www.w3.org/2001/XInclude">
4 <title>Quickbook 1.4</title>
8 <firstname>Joel</firstname> <surname>de Guzman</surname>
11 <firstname>Eric</firstname> <surname>Niebler</surname>
15 <year>2002</year> <year>2004</year> <year>2006</year> <holder>Joel de Guzman,
18 <legalnotice id="quickbook.legal">
20 Distributed under the Boost Software License, Version 1.0. (See accompanying
21 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>)
25 <emphasis>WikiWiki</emphasis> style documentation tool
28 <section id="quickbook.intro">
29 <title><link linkend="quickbook.intro">Introduction</link></title>
32 <emphasis role="bold"><emphasis><quote>Why program by hand in five days what
33 you can spend five years of your life automating?</quote></emphasis></emphasis>
36 -- Terrence Parr, author ANTLR/PCCTS
40 Well, QuickBook started as a weekend hack. It was originally intended to be
41 a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
42 What is it? What you are viewing now, this documentation, is autogenerated
43 by QuickBook. These files were generated from one master:
47 <ulink url="../quickbook.qbk">quickbook.qbk</ulink>
51 Originally named QuickDoc, this funky tool that never dies evolved into a funkier
52 tool thanks to Eric Niebler who resurrected the project making it generate
53 <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
54 instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
55 documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
56 an SGML or XML based format for describing documentation.
59 QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
60 using simple rules and markup for simple formatting tasks. QuickBook extends
61 the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
62 files. A single QuickBook document can generate a fully linked set of nice
63 HTML and PostScript/PDF documents complete with images and syntax- colorized
72 generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
73 xml, to generate HTML, PostScript and PDF
78 simple markup to link to Doxygen-generated entities
83 macro system for simple text substitution
88 simple markup for italics, bold, preformatted, blurbs, code samples, tables,
89 URLs, anchors, images, etc.
94 automatic syntax coloring of code samples
104 <section id="quickbook.change_log">
105 <title><link linkend="quickbook.change_log">Change Log</link></title>
106 <bridgehead renderas="sect3" id="quickbook.change_log.h0">
107 <phrase id="quickbook.change_log.version_1_3"/><link linkend="quickbook.change_log.version_1_3">Version
113 Quickbook file inclusion [include].
118 Better xml output (pretty layout). Check out the generated XML.
123 Regression testing facility: to make sure your document will always be
124 compatible (full backward compatibility) regardless of changes to QuickBook.
129 Code cleanup and refactoring.
134 Allow phrase markup in the doc-info.
139 Preformatted code blocks via ``code`` (double ticks) allows code in tables
140 and lists, for example.
145 Quickbook versioning; allows full backward compatibility. You have to add
146 [quickbook 1.3] to the doc-info header to enable the new features. Without
147 this, QuickBook will assume that the document is a pre-1.3 document.
152 Better (intuitive) paragraph termination. Some markups may terminate a
154 <programlisting><phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase>
155 <phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
156 <phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
161 Fully qualified section and headers. Subsection names are concatenated
162 to the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
163 role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
164 role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
165 role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
170 Better &nbsp; and whitespace handling in code snippets.
175 [xinclude] fixes up the relative path to the target XML file when input_directory
176 is not the same as the output_directory.
181 Allow untitled tables.
186 Allow phrase markups in section titles.
191 Allow escaping back to QuickBook from code, code blocks and inline code.
196 Footnotes, with the [footnote This is the footnote] syntax.
201 Post-processor bug fix for escaped XML code that it does not recognize.
206 Replaceable, with the [~replacement] syntax.
216 Code changes to allow full recursion (i.e. Collectors and push/pop functions)
221 Various code cleanup/maintenance
231 [conceptref] for referencing BoostBook <concept> entities.
236 Allow escape of spaces. The escaped space is removed from the output. Syntax:
237 <code><phrase role="special">\</phrase> </code>.
242 Nested comments are now allowed.
247 Quickbook blocks can nest inside comments.
252 <link linkend="quickbook.syntax.block.import">Import</link> facility.
257 Callouts on imported code
262 Simple markups can now span a whole block.
267 <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>, <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
268 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
269 may now contain paragraphs.
274 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
275 and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
276 role="special">]</phrase></code> are now deprecated.
281 <section id="quickbook.syntax">
282 <title><link linkend="quickbook.syntax">Syntax Summary</link></title>
284 A QuickBook document is composed of one or more blocks. An example of a block
285 is the paragraph or a C++ code snippet. Some blocks have special mark-ups.
286 Blocks, except code snippets which have their own grammar (C++ or Python),
287 are composed of one or more phrases. A phrase can be a simple contiguous run
288 of characters. Phrases can have special mark-ups. Marked up phrases can recursively
289 contain other phrases, but cannot contain blocks. A terminal is a self contained
290 block-level or phrase-level element that does not nest anything.
293 Blocks, in general, are delimited by two end-of-lines (the block terminator).
294 Phrases in each block cannot contain a block terminator. This way, syntax errors
295 such as un-matched closing brackets do not go haywire and corrupt anything
298 <section id="quickbook.syntax.comments">
299 <title><link linkend="quickbook.syntax.comments">Comments</link></title>
301 Can be placed anywhere.
303 <programlisting><!--quickbook-escape-prefix-->[/ comment (no output generated) ]<!--quickbook-escape-postfix-->
305 <programlisting><!--quickbook-escape-prefix-->[/ comments can be nested [/ some more here] ]<!--quickbook-escape-postfix-->
307 <programlisting><!--quickbook-escape-prefix-->[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]<!--quickbook-escape-postfix-->
310 <section id="quickbook.syntax.phrase">
311 <title><link linkend="quickbook.syntax.phrase">Phrase Level Elements</link></title>
312 <section id="quickbook.syntax.phrase.font_styles">
313 <title><link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link></title>
314 <programlisting><!--quickbook-escape-prefix-->['italic], [*bold], [_underline], [^teletype], [-strikethrough]
315 <!--quickbook-escape-postfix--></programlisting>
320 <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
321 role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
322 role="strikethrough">strikethrough</emphasis>
325 Like all non-terminal phrase level elements, this can of course be nested:
327 <programlisting><!--quickbook-escape-prefix-->[*['bold-italic]]
328 <!--quickbook-escape-postfix--></programlisting>
333 <emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
336 <section id="quickbook.syntax.phrase.replaceable">
337 <title><link linkend="quickbook.syntax.phrase.replaceable">Replaceable</link></title>
339 When you want content that may or must be replaced by the user, use the
342 <programlisting><!--quickbook-escape-prefix-->[~replacement]
343 <!--quickbook-escape-postfix--></programlisting>
348 <replaceable>replacement</replaceable>
351 <section id="quickbook.syntax.phrase.quotations">
352 <title><link linkend="quickbook.syntax.phrase.quotations">Quotations</link></title>
353 <programlisting><!--quickbook-escape-prefix-->["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
354 <!--quickbook-escape-postfix--></programlisting>
359 <quote>A question that sometimes drives me hazy: am I or are the others
360 crazy?</quote>--Einstein
363 Note the proper left and right quote marks. Also, while you can simply
364 use ordinary quote marks like "quoted", our quotation, above,
365 will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
368 Like all phrase elements, quotations may be nested. Example:
370 <programlisting><!--quickbook-escape-prefix-->["Here's the rule for bargains: ["Do other men, for they would do you.] That's
371 the true business precept.]
372 <!--quickbook-escape-postfix--></programlisting>
377 <quote>Here's the rule for bargains: <quote>Do other men, for they would
378 do you.</quote> That's the true business precept.</quote>
381 <section id="quickbook.syntax.phrase.simple_formatting">
382 <title><link linkend="quickbook.syntax.phrase.simple_formatting">Simple formatting</link></title>
384 Simple markup for formatting text, common in many applications, is now
387 <programlisting><!--quickbook-escape-prefix-->/italic/, *bold*, _underline_, =teletype=
388 <!--quickbook-escape-postfix--></programlisting>
393 <emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
394 role="underline">underline</emphasis>, <literal>teletype</literal>
397 Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
398 are much stricter<footnote id="quickbook.syntax.phrase.simple_formatting.f0">
400 Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>,
401 for sharing these samples and teaching me these obscure formatting rules.
402 I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>,
403 being more or less a formal EBNF parser, can handle the context sensitivity
411 Simple markups cannot nest. You can combine a simple markup with a
417 Simple markups cannot contain any other form of quickbook markup.
422 A non-space character must follow the leading markup
427 A non-space character must precede the trailing markup
432 A space or a punctuation must follow the trailing markup
437 If the matching markup cannot be found within a block, the formatting
438 will not be applied. This is to ensure that un-matched formatting markups,
439 which can be a common mistake, does not corrupt anything past a single
440 block. We do not want the rest of the document to be rendered bold
441 just because we forgot a trailing '*'. A single block is terminated
442 by two end of lines or the close bracket: ']'.
447 A line starting with the star will be interpreted as an unordered list.
448 See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
453 <table frame="all" id="quickbook.syntax.phrase.simple_formatting.t0">
454 <title>More Formatting Samples</title>
474 <literal>*Bold*</literal>
479 <emphasis role="bold">Bold</emphasis>
486 <literal>*Is bold*</literal>
491 <emphasis role="bold">Is bold</emphasis>
498 <literal>* Not bold* *Not bold * * Not bold *</literal>
503 * Not bold* *Not bold * * Not bold *
510 <literal>This*Isn't*Bold (no bold)</literal>
515 This*Isn't*Bold (no bold)
522 <literal>(*Bold Inside*) (parenthesis not bold)</literal>
527 (<emphasis role="bold">Bold Inside</emphasis>) (parenthesis not
535 <literal>*(Bold Outside)* (parenthesis bold)</literal>
540 <emphasis role="bold">(Bold Outside)</emphasis> (parenthesis
548 <literal>3*4*5 = 60 (no bold)</literal>
560 <literal>3 * 4 * 5 = 60 (no bold)</literal>
565 3 * 4 * 5 = 60 (no bold)
572 <literal>3 *4* 5 = 60 (4 is bold)</literal>
577 3 <emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)
584 <literal>*This is bold* this is not *but this is*</literal>
589 <emphasis role="bold">This is bold</emphasis> this is not <emphasis
590 role="bold">but this is</emphasis>
597 <literal>*This is bold*.</literal>
602 <emphasis role="bold">This is bold</emphasis>.
609 <literal>*B*. (bold B)</literal>
614 <emphasis role="bold">B</emphasis>. (bold B)
621 <literal>['*Bold-Italic*]</literal>
626 <emphasis><emphasis role="bold">Bold-Italic</emphasis></emphasis>
633 <literal>*side-by*/-side/</literal>
638 <emphasis role="bold">side-by</emphasis><emphasis>-side</emphasis>
646 As mentioned, simple markups cannot go past a single block. The text from
647 "have" to "full" in the following paragraph will be
650 <programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
651 Yes sir, yes sir, three bags full!*
652 One for the master, one for the dame,
653 And one for the little boy who lives down the lane.
654 <!--quickbook-escape-postfix--></programlisting>
656 Baa baa black sheep, <emphasis role="bold">have you any wool? Yes sir,
657 yes sir, three bags full!</emphasis> One for the master, one for the dame,
658 And one for the little boy who lives down the lane.
661 But in the following paragraph, bold is not applied:
663 <programlisting><!--quickbook-escape-prefix-->Baa baa black sheep, *have you any wool?
664 Yes sir, yes sir, three bags full!
665 One for the master, one for the dame,
666 And one for the little boy who lives down the lane.
667 <!--quickbook-escape-postfix--></programlisting>
669 Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!
670 One for the master, one for the dame, And one for the little boy who lives
674 <section id="quickbook.syntax.phrase.inline_code">
675 <title><link linkend="quickbook.syntax.phrase.inline_code">Inline code</link></title>
677 Inlining code in paragraphs is quite common when writing C++ documentation.
678 We provide a very simple markup for this. For example, this:
680 <programlisting><!--quickbook-escape-prefix-->This text has inlined code `int main() { return 0; }` in it.
681 <!--quickbook-escape-postfix--></programlisting>
686 This text has inlined code <code><phrase role="keyword">int</phrase> <phrase
687 role="identifier">main</phrase><phrase role="special">()</phrase> <phrase
688 role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase
689 role="number">0</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase></code>
690 in it. The code will be syntax highlighted.
694 We simply enclose the code with the tick: <literal>"`"</literal>, not the
695 single quote: <code><phrase role="string">"'"</phrase></code>.
696 Note too that <literal>`some code`</literal> is preferred over <literal>[^some code]</literal>.
700 <section id="quickbook.syntax.phrase.code_blocks">
701 <title><link linkend="quickbook.syntax.phrase.code_blocks">Code blocks</link></title>
703 Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>).
704 However, such a simple syntax cannot be used as phrase elements in lists
705 (See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
706 lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
707 lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>),
708 etc. Inline code (see above) can. The problem is, inline code does not
709 allow formatting with newlines, spaces, and tabs. These are lost.
712 We provide a phrase level markup that is a mix between the two. By using
713 the double-tick, instead of the single-tick, we are telling QuickBook to
714 use preformatted blocks of code. Example:
717 #include <iostream>
721 std::cout << "Hello, World!" << std::endl;
730 <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
732 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
733 <phrase role="special">{</phrase>
734 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
735 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
736 <phrase role="special">}</phrase>
740 <section id="quickbook.syntax.phrase.source_mode">
741 <title><link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></title>
743 If a document contains more than one type of source code then the source
744 mode may be changed dynamically as the document is processed. All QuickBook
745 documents are initially in C++ mode by default, though an alternative initial
746 value may be set in the <link linkend="quickbook.syntax.block.document">Document</link>
750 To change the source mode, use the <literal>[source-mode]</literal> markup,
751 where <literal>source-mode</literal> is one of the supported modes. For
754 <programlisting><!--quickbook-escape-prefix-->Python's [python] `import` is rather like C++'s [c++] `#include`. A
755 C++ comment `// looks like this` whereas a Python comment [python]
757 <!--quickbook-escape-postfix--></programlisting>
762 Python's <code><phrase role="keyword">import</phrase></code> is rather
763 like C++'s <code><phrase role="preprocessor">#include</phrase></code>.
764 A C++ comment <code><phrase role="comment">// looks like this</phrase></code>
765 whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>.
767 <table frame="all" id="quickbook.syntax.phrase.source_mode.t0">
768 <title>Supported Source Modes</title>
793 <literal>[c++]</literal>
805 <literal>[python]</literal>
814 The source mode strings are lowercase.
818 <section id="quickbook.syntax.phrase.line_break">
819 <title><link linkend="quickbook.syntax.phrase.line_break">line-break</link></title>
820 <programlisting><!--quickbook-escape-prefix-->[br]
821 <!--quickbook-escape-postfix--></programlisting>
824 <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
825 role="special">]</phrase></code> is now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
826 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
827 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
828 may now contain paragraphs.
832 <section id="quickbook.syntax.phrase.anchors">
833 <title><link linkend="quickbook.syntax.phrase.anchors">Anchors</link></title>
834 <programlisting><!--quickbook-escape-prefix-->[#named_anchor]
835 <!--quickbook-escape-postfix--></programlisting>
837 A named anchor is a hook that can be referenced by a link elsewhere in
838 the document. You can then reference an anchor with <literal>[link named_anchor
839 Some link text]</literal>.
840 See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>,
841 <link linkend="quickbook.syntax.block.section">Section</link> and <link
842 linkend="quickbook.syntax.block.headings">Heading</link>.
845 <section id="quickbook.syntax.phrase.links">
846 <title><link linkend="quickbook.syntax.phrase.links">Links</link></title>
847 <programlisting><!--quickbook-escape-prefix-->[@http://www.boost.org this is [*boost's] website....]
848 <!--quickbook-escape-postfix--></programlisting>
853 <ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis>
857 URL links where the link text is the link itself is common. Example:
859 <programlisting><!--quickbook-escape-prefix-->see http://spirit.sourceforge.net/
860 <!--quickbook-escape-postfix--></programlisting>
862 so, when the text is absent in a link markup, the URL is assumed. Example:
864 <programlisting>see <!--quickbook-escape-prefix-->[@http://spirit.sourceforge.net/]<!--quickbook-escape-postfix-->
870 see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink>
873 <section id="quickbook.syntax.phrase.anchor_links">
874 <title><link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></title>
876 You can link within a document using:
878 <programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
879 <!--quickbook-escape-postfix--></programlisting>
881 See sections <link linkend="quickbook.syntax.block.section">Section</link>
882 and <link linkend="quickbook.syntax.block.headings">Heading</link> for
886 <section id="quickbook.syntax.phrase.refentry_links">
887 <title><link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></title>
889 In addition, you can link internally to an XML refentry like:
891 <programlisting><!--quickbook-escape-prefix-->[link xml.refentry The link text]
892 <!--quickbook-escape-postfix--></programlisting>
894 This gets converted into <literal><link linkend="xml.refentry">The
895 link text</link></literal>.
898 Like URLs, the link text is optional. If this is not present, the link
899 text will automatically be the refentry. Example:
901 <programlisting><!--quickbook-escape-prefix-->[link xml.refentry]
902 <!--quickbook-escape-postfix--></programlisting>
904 This gets converted into <literal><link linkend="xml.refentry">xml.refentry</link></literal>.
907 <section id="quickbook.syntax.phrase.code_links">
908 <title><link linkend="quickbook.syntax.phrase.code_links">Code Links</link></title>
910 If you want to link to a function, class, member, enum, concept or header
911 in the reference section, you can use:
913 <programlisting><!--quickbook-escape-prefix-->[funcref fully::qualified::function_name The link text]
914 [classref fully::qualified::class_name The link text]
915 [memberref fully::qualified::member_name The link text]
916 [enumref fully::qualified::enum_name The link text]
917 [macroref MACRO_NAME The link text]
918 [conceptref ConceptName The link text]
919 [headerref path/to/header.hpp The link text]
920 <!--quickbook-escape-postfix--></programlisting>
922 Again, the link text is optional. If this is not present, the link text
923 will automatically be the function, class, member, enum, macro, concept
926 <programlisting><!--quickbook-escape-prefix-->[classref boost::bar::baz]
927 <!--quickbook-escape-postfix--></programlisting>
929 would have "boost::bar::baz" as the link text.
932 <section id="quickbook.syntax.phrase.escape">
933 <title><link linkend="quickbook.syntax.phrase.escape">Escape</link></title>
935 The escape mark-up is used when we don't want to do any processing.
938 escape (no processing/formatting)
942 Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
943 or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
946 <emphasis role="bold">This is direct XML markup</emphasis>
950 <emphasis role="bold">This is direct XML markup</emphasis>
954 Be careful when using the escape. The text must conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink
955 url="http://www.docbook.org/">DocBook</ulink> syntax.
959 <section id="quickbook.syntax.phrase.single_char_escape">
960 <title><link linkend="quickbook.syntax.phrase.single_char_escape">Single
961 char escape</link></title>
963 The backslash may be used to escape a single punctuation character. The
964 punctuation immediately after the backslash is passed without any processing.
965 This is useful when we need to escape QuickBook punctuations such as <code><phrase
966 role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>.
967 For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal>
970 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
971 has a special meaning. It is used to generate line breaks.
975 <code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
976 and <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
977 role="special">]</phrase></code> are now deprecated. <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>,
978 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
979 and table cells (see <link linkend="quickbook.syntax.block.tables">Tables</link>)
980 may now contain paragraphs.
984 The escaped space: <code><phrase role="special">\</phrase> </code> also
985 has a special meaning. The escaped space is removed from the output.
988 <section id="quickbook.syntax.phrase.images">
989 <title><link linkend="quickbook.syntax.phrase.images">Images</link></title>
990 <programlisting><!--quickbook-escape-prefix-->[$image.jpg]
991 <!--quickbook-escape-postfix--></programlisting>
993 <section id="quickbook.syntax.phrase.footnotes">
994 <title><link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link></title>
996 As of version 1.3, QuickBook supports footnotes. Just put the text of the
997 footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase
998 role="special">]</phrase></code> block, and the text will be put at the
999 bottom of the current page. For example, this:
1001 <programlisting><!--quickbook-escape-prefix-->[footnote A sample footnote]
1002 <!--quickbook-escape-postfix--></programlisting>
1004 will generate this<footnote id="quickbook.syntax.phrase.footnotes.f0">
1010 <section id="quickbook.syntax.phrase.footnotes.macro_expansion">
1011 <title><link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro
1012 Expansion</link></title>
1013 <programlisting><!--quickbook-escape-prefix-->__a_macro_identifier__
1014 <!--quickbook-escape-postfix--></programlisting>
1016 See <link linkend="quickbook.syntax.block.macros">Macros</link> for details.
1019 <section id="quickbook.syntax.phrase.footnotes.template_expansion">
1020 <title><link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template
1021 Expansion</link></title>
1022 <programlisting><!--quickbook-escape-prefix-->[a_template_identifier]
1023 <!--quickbook-escape-postfix--></programlisting>
1025 See <link linkend="quickbook.syntax.block.templates">Templates</link>
1031 <section id="quickbook.syntax.block">
1032 <title><link linkend="quickbook.syntax.block">Block Level Elements</link></title>
1033 <section id="quickbook.syntax.block.document">
1034 <title><link linkend="quickbook.syntax.block.document">Document</link></title>
1036 Every document must begin with a Document Info section, which should look
1039 <programlisting><!--quickbook-escape-prefix-->[document-type The Document Title
1042 [id the_document_name]
1043 [dirname the_document_dir]
1044 [copyright 2000 2002 2003 Joe Blow, Jane Doe]
1045 [purpose The document's reason for being]
1046 [category The document's category]
1047 [authors [Blow, Joe], [Doe, Jane]]
1048 [license The document's license]
1049 [source-mode source-type]
1051 <!--quickbook-escape-postfix--></programlisting>
1053 Where document-type is one of:
1113 quickbook 1.3 declares the version of quickbook the document is written
1114 for. In its absence, version 1.1 is assumed.
1117 <literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
1118 <literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
1119 <literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
1120 and <literal>source-mode</literal> are optional information.
1123 <literal>source-type</literal> is a lowercase string setting the initial
1124 <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
1125 If the <literal>source-mode</literal> field is omitted, a default value
1126 of <literal>c++</literal> will be used.
1129 <section id="quickbook.syntax.block.section">
1130 <title><link linkend="quickbook.syntax.block.section">Section</link></title>
1132 Starting a new section is accomplished with:
1134 <programlisting><!--quickbook-escape-prefix-->[section:id The Section Title]
1135 <!--quickbook-escape-postfix--></programlisting>
1137 where <emphasis>id</emphasis> is optional. id will be the filename of the
1138 generated section. If it is not present, "The Section Title"
1139 will be normalized and become the id. Valid characters are <literal>a-Z</literal>,
1140 <literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
1141 All non-valid characters are converted to underscore and all upper-case
1142 are converted to lower case. Thus: "The Section Title" will be
1143 normalized to "the_section_title".
1148 <programlisting><!--quickbook-escape-prefix-->[endsect]
1149 <!--quickbook-escape-postfix--></programlisting>
1151 Sections can nest, and that results in a hierarchy in the table of contents.
1154 <section id="quickbook.syntax.block.xinclude">
1155 <title><link linkend="quickbook.syntax.block.xinclude">xinclude</link></title>
1157 You can include another XML file with:
1159 <programlisting><!--quickbook-escape-prefix-->[xinclude file.xml]
1160 <!--quickbook-escape-postfix--></programlisting>
1162 This is useful when file.xml has been generated by Doxygen and contains
1163 your reference section.
1166 <section id="quickbook.syntax.block.paragraphs">
1167 <title><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></title>
1169 Paragraphs start left-flushed and are terminated by two or more newlines.
1170 No markup is needed for paragraphs. QuickBook automatically detects paragraphs
1171 from the context. Block markups [section, endsect, h1, h2, h3, h4, h5,
1172 h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate
1176 <section id="quickbook.syntax.block.lists">
1177 <title><link linkend="quickbook.syntax.block.lists">Lists</link></title>
1178 <section id="quickbook.syntax.block.lists.ordered_lists">
1179 <title><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
1180 lists</link></title>
1181 <programlisting># One
1206 <section id="quickbook.syntax.block.lists.list_hierarchies">
1207 <title><link linkend="quickbook.syntax.block.lists.list_hierarchies">List
1208 Hierarchies</link></title>
1210 List hierarchies are supported. Example:
1212 <programlisting># One
1291 <section id="quickbook.syntax.block.lists.long_list_lines">
1292 <title><link linkend="quickbook.syntax.block.lists.long_list_lines">Long
1293 List Lines</link></title>
1295 Long lines will be wrapped appropriately. Example:
1297 <programlisting># A short item.
1298 # A very long item. A very long item. A very long item.
1299 A very long item. A very long item. A very long item.
1300 A very long item. A very long item. A very long item.
1301 A very long item. A very long item. A very long item.
1302 A very long item. A very long item. A very long item.
1313 A very long item. A very long item. A very long item. A very long
1314 item. A very long item. A very long item. A very long item. A very
1315 long item. A very long item. A very long item. A very long item.
1316 A very long item. A very long item. A very long item. A very long
1327 <section id="quickbook.syntax.block.lists.unordered_lists">
1328 <title><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
1329 lists</link></title>
1330 <programlisting><!--quickbook-escape-prefix-->* First
1333 <!--quickbook-escape-postfix--></programlisting>
1355 <section id="quickbook.syntax.block.lists.mixed_lists">
1356 <title><link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link></title>
1358 Mixed lists (ordered and unordered) are supported. Example:
1360 <programlisting><!--quickbook-escape-prefix--># One
1367 <!--quickbook-escape-postfix--></programlisting>
1413 <programlisting><!--quickbook-escape-prefix--># 1
1425 <!--quickbook-escape-postfix--></programlisting>
1503 <section id="quickbook.syntax.block.code">
1504 <title><link linkend="quickbook.syntax.block.code">Code</link></title>
1506 Preformatted code starts with a space or a tab. The code will be syntax
1507 highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
1510 <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
1512 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
1513 <phrase role="special">{</phrase>
1514 <phrase role="comment">// Sample code</phrase>
1515 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase>
1516 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
1517 <phrase role="special">}</phrase>
1519 <programlisting><phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase>
1521 <phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase>
1522 <phrase role="string">'''"Cooks" the input text for HTML.'''</phrase>
1524 <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>
1527 Macros that are already defined are expanded in source code. Example:
1529 <programlisting><!--quickbook-escape-prefix-->[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
1530 [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
1532 using __boost__::__array__;
1533 <!--quickbook-escape-postfix--></programlisting>
1537 <programlisting><phrase role="keyword">using</phrase> <ulink url="http://www.boost.org/libs/libraries.htm">boost</ulink><phrase role="special">::</phrase><ulink url="http://www.boost.org/doc/html/array/reference.html">array</ulink><phrase role="special">;</phrase>
1540 <section id="quickbook.syntax.block.escape_back">
1541 <title><link linkend="quickbook.syntax.block.escape_back">Escaping Back To
1542 QuickBook</link></title>
1544 Inside code, code blocks and inline code, QuickBook does not allow any
1545 markup to avoid conflicts with the target syntax (e.g. c++). In case you
1546 need to switch back to QuickBook markup inside code, you can do so using
1547 a language specific <emphasis>escape-back</emphasis> delimiter. In C++
1548 and Python, the delimiter is the double tick (back-quote): "``"
1549 and "``". Example:
1551 <programlisting><!--quickbook-escape-prefix-->void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
1554 <!--quickbook-escape-postfix--></programlisting>
1558 <programlisting><phrase role="keyword">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
1559 <phrase role="special">{</phrase>
1560 <phrase role="special">}</phrase>
1563 When escaping from code to QuickBook, only phrase level markups are allowed.
1564 Block level markups like lists, tables etc. are not allowed.
1567 <section id="quickbook.syntax.block.preformatted">
1568 <title><link linkend="quickbook.syntax.block.preformatted">Preformatted</link></title>
1570 Sometimes, you don't want some preformatted text to be parsed as C++. In
1571 such cases, use the <literal>[pre ... ]</literal> markup block.
1573 <programlisting><!--quickbook-escape-prefix-->[pre
1575 Some *preformatted* text Some *preformatted* text
1577 Some *preformatted* text Some *preformatted* text
1579 Some *preformatted* text Some *preformatted* text
1582 <!--quickbook-escape-postfix--></programlisting>
1584 Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
1585 level markup, pre (and Code) are the only ones that allow multiple newlines.
1586 The markup above will generate:
1588 <programlisting>Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
1590 Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
1592 Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
1596 Notice that unlike Code, phrase markup such as font style is still permitted
1597 inside <literal>pre</literal> blocks.
1600 <section id="quickbook.syntax.block.blockquote">
1601 <title><link linkend="quickbook.syntax.block.blockquote">Blockquote</link></title>
1602 <programlisting><!--quickbook-escape-prefix-->[:sometext...]<!--quickbook-escape-postfix-->
1606 Indents the paragraph. This applies to one paragraph only.
1610 <section id="quickbook.syntax.block.admonitions">
1611 <title><link linkend="quickbook.syntax.block.admonitions">Admonitions</link></title>
1612 <programlisting><!--quickbook-escape-prefix-->[note This is a note]
1614 [important This is important]
1615 [caution This is a caution]
1616 [warning This is a warning]
1617 <!--quickbook-escape-postfix--></programlisting>
1619 generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions:
1647 These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>.
1648 So, for example <literal>[information This is some information]</literal>
1649 is unlikely to produce the desired effect.
1652 <section id="quickbook.syntax.block.headings">
1653 <title><link linkend="quickbook.syntax.block.headings">Headings</link></title>
1654 <programlisting><!--quickbook-escape-prefix-->[h1 Heading 1]
1660 <!--quickbook-escape-postfix--></programlisting>
1661 <bridgehead renderas="sect1" id="quickbook.syntax.block.headings.h0">
1662 <phrase id="quickbook.syntax.block.headings.heading_1"/><link linkend="quickbook.syntax.block.headings.heading_1">Heading
1665 <bridgehead renderas="sect2" id="quickbook.syntax.block.headings.h1">
1666 <phrase id="quickbook.syntax.block.headings.heading_2"/><link linkend="quickbook.syntax.block.headings.heading_2">Heading
1669 <bridgehead renderas="sect3" id="quickbook.syntax.block.headings.h2">
1670 <phrase id="quickbook.syntax.block.headings.heading_3"/><link linkend="quickbook.syntax.block.headings.heading_3">Heading
1673 <bridgehead renderas="sect4" id="quickbook.syntax.block.headings.h3">
1674 <phrase id="quickbook.syntax.block.headings.heading_4"/><link linkend="quickbook.syntax.block.headings.heading_4">Heading
1677 <bridgehead renderas="sect5" id="quickbook.syntax.block.headings.h4">
1678 <phrase id="quickbook.syntax.block.headings.heading_5"/><link linkend="quickbook.syntax.block.headings.heading_5">Heading
1681 <bridgehead renderas="sect6" id="quickbook.syntax.block.headings.h5">
1682 <phrase id="quickbook.syntax.block.headings.heading_6"/><link linkend="quickbook.syntax.block.headings.heading_6">Heading
1686 Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
1687 names with <literal>name="section_id.normalized_header_text"</literal>
1688 (i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
1689 <literal>0-9</literal> and <literal>_</literal>. All non-valid characters
1690 are converted to underscore and all upper-case are converted to lower-case.
1691 For example: Heading 1 in section Section 2 will be normalized to <literal>section_2.heading_1</literal>).
1694 <programlisting><!--quickbook-escape-prefix-->[link section_id.normalized_header_text The link text]
1695 <!--quickbook-escape-postfix--></programlisting>
1697 to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
1698 links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
1702 <section id="quickbook.syntax.block.generic_heading">
1703 <title><link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link></title>
1705 In cases when you don't want to care about the heading level (1 to 6),
1706 you can use the <emphasis>Generic Heading</emphasis>:
1708 <programlisting><!--quickbook-escape-prefix-->[heading Heading]
1709 <!--quickbook-escape-postfix--></programlisting>
1711 The <emphasis>Generic Heading</emphasis> assumes the level, plus one, of
1712 the innermost section where it is placed. For example, if it is placed
1713 in the outermost section, then, it assumes <emphasis>h2</emphasis>.
1716 Headings are often used as an alternative to sections. It is used particularly
1717 if you do not want to start a new section. In many cases, however, headings
1718 in a particular section is just flat. Example:
1720 <programlisting><!--quickbook-escape-prefix-->[section A]
1725 <!--quickbook-escape-postfix--></programlisting>
1727 Here we use h2 assuming that section A is the outermost level. If it is
1728 placed in an inner level, you'll have to use h3, h4, etc. depending on
1729 where the section is. In general, it is the section level plus one. It
1730 is rather tedious, however, to scan the section level everytime. If you
1731 rewrite the example above as shown below, this will be automatic:
1733 <programlisting><!--quickbook-escape-prefix-->[section A]
1738 <!--quickbook-escape-postfix--></programlisting>
1740 They work well regardless where you place them. You can rearrange sections
1741 at will without any extra work to ensure correct heading levels. In fact,
1742 with <emphasis>section</emphasis> and <emphasis>heading</emphasis>, you
1743 have all you need. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> becomes
1744 redundant. <emphasis>h1</emphasis>..<emphasis>h6</emphasis> might be deprecated
1748 <section id="quickbook.syntax.block.macros">
1749 <title><link linkend="quickbook.syntax.block.macros">Macros</link></title>
1750 <programlisting><!--quickbook-escape-prefix-->[def macro_identifier some text]
1751 <!--quickbook-escape-postfix--></programlisting>
1753 When a macro is defined, the identifier replaces the text anywhere in the
1754 file, in paragraphs, in markups, etc. macro_identifier is a string of non-
1755 white space characters except ']'. A macro may not follow an alphabetic
1756 character or the underscore. The replacement text can be any phrase (even
1757 marked up). Example:
1759 <programlisting><!--quickbook-escape-prefix-->[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
1761 <!--quickbook-escape-postfix--></programlisting>
1763 Now everywhere the sf_logo is placed, the picture will be inlined.
1766 <inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&type=1"></imagedata></imageobject>
1768 <phrase>sflogo</phrase>
1770 </inlinemediaobject>
1774 It's a good idea to use macro identifiers that are distinguishable. For
1775 instance, in this document, macro identifiers have two leading and trailing
1776 underscores (e.g. <literal>__spirit__</literal>). The reason is to avoid unwanted
1781 Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>)
1782 They tend to change a lot. It is a good idea to place all links and images
1783 in one place near the top to make it easy to make changes. <emphasis role="bold">2</emphasis>)
1784 The syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal>
1785 than <literal>[@http://spirit.sourceforge.net Spirit]</literal>.
1790 <programlisting><!--quickbook-escape-prefix-->[def :-) [$theme/smiley.png]]
1791 [def __spirit__ [@http://spirit.sourceforge.net Spirit]]
1792 <!--quickbook-escape-postfix--></programlisting>
1794 (See <link linkend="quickbook.syntax.phrase.images">Images</link> and
1795 <link linkend="quickbook.syntax.phrase.links">Links</link>)
1798 Invoking these macros:
1800 <programlisting><!--quickbook-escape-prefix-->Hi __spirit__ :-)
1801 <!--quickbook-escape-postfix--></programlisting>
1806 Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata
1807 fileref="images/smiley.png"></imagedata></imageobject>
1809 <phrase>smiley</phrase>
1811 </inlinemediaobject>
1814 <section id="quickbook.syntax.block.predefined_macros">
1815 <title><link linkend="quickbook.syntax.block.predefined_macros">Predefined
1816 Macros</link></title>
1818 Quickbook has some predefined macros that you can already use.
1820 <table frame="all" id="quickbook.syntax.block.predefined_macros.t0">
1821 <title>Predefined Macros</title>
1885 Quickbook source filename
1890 quickbook_manual-1_4.quickbook
1898 <section id="quickbook.syntax.block.templates">
1899 <title><link linkend="quickbook.syntax.block.templates">Templates</link></title>
1901 Templates provide a more versatile text substitution mechanism. Templates
1902 come in handy when you need to create parameterizable, multi-line, boilerplate
1903 text that you specify once and expand many times. Templates accept one
1904 or more arguments. These arguments act like place-holders for text replacement.
1905 Unlike simple macros, which are limited to phrase level markup, templates
1906 can contain block level markup (e.g. paragraphs, code blocks and tables).
1911 <programlisting><!--quickbook-escape-prefix-->[template person[name age what]
1913 Hi, my name is [name]. I am [age] years old. I am a [what].
1916 <!--quickbook-escape-postfix--></programlisting>
1917 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h0">
1918 <phrase id="quickbook.syntax.block.templates.template_identifier"/><link
1919 linkend="quickbook.syntax.block.templates.template_identifier">Template
1923 Template identifiers can either consist of:
1928 An initial alphabetic character or the underscore, followed by zero
1929 or more alphanumeric characters or the underscore. This is similar
1930 to your typical C/C++ identifier.
1935 A single character punctuation (a non-alphanumeric printable character)
1939 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h1">
1940 <phrase id="quickbook.syntax.block.templates.formal_template_arguments"/><link
1941 linkend="quickbook.syntax.block.templates.formal_template_arguments">Formal
1942 Template Arguments</link>
1945 Template formal arguments are identifiers consisting of an initial alphabetic
1946 character or the underscore, followed by zero or more alphanumeric characters
1947 or the underscore. This is similar to your typical C/C++ identifier.
1950 A template formal argument temporarily hides a template of the same name
1951 at the point where the <link linkend="quickbook.syntax.block.templates.template_expansion">template
1952 is expanded</link>. Note that the body of the <literal>person</literal>
1953 template above refers to <literal>name</literal> <literal>age</literal>
1954 and <literal>what</literal> as <literal>[name]</literal> <literal>[age]</literal>
1955 and <literal>[what]</literal>. <literal>name</literal> <literal>age</literal>
1956 and <literal>what</literal> are actually templates that exist in the duration
1957 of the template call.
1959 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h2">
1960 <phrase id="quickbook.syntax.block.templates.template_body"/><link linkend="quickbook.syntax.block.templates.template_body">Template
1964 The template body can be just about any QuickBook block or phrase. There
1965 are actually two forms. Templates may be phrase or block level. Phrase
1966 templates are of the form:
1968 <programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN] replacement text... ]
1969 <!--quickbook-escape-postfix--></programlisting>
1971 Block templates are of the form:
1973 <programlisting><!--quickbook-escape-prefix-->[template sample[arg1 arg2...argN]
1976 <!--quickbook-escape-postfix--></programlisting>
1978 The basic rule is as follows: if a newline immediately follows the argument
1979 list, then it is a block template, otherwise, it is a phrase template.
1980 Phrase templates are typically expanded as part of phrases. Like macros,
1981 block level elements are not allowed in phrase templates.
1983 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h3">
1984 <phrase id="quickbook.syntax.block.templates.template_expansion"/><link
1985 linkend="quickbook.syntax.block.templates.template_expansion">Template
1989 You expand a template this way:
1991 <programlisting><!--quickbook-escape-prefix-->[template_identifier arg1..arg2..arg3]
1992 <!--quickbook-escape-postfix--></programlisting>
1994 At template expansion, you supply the actual arguments. The template will
1995 be expanded with your supplied arguments. Example:
1997 <programlisting><!--quickbook-escape-prefix-->[person James Bond..39..Spy]
1998 [person Santa Clause..87..Big Red Fatso]
1999 <!--quickbook-escape-postfix--></programlisting>
2001 Which will expand to:
2004 Hi, my name is James Bond. I am 39 years old. I am a Spy.
2007 Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
2011 A word of caution: Templates are recursive. A template can call another
2012 template or even itself, directly or indirectly. There are no control
2013 structures in QuickBook (yet) so this will always mean infinite recursion.
2014 QuickBook can detect this situation and report an error if recursion
2015 exceeds a certain limit.
2019 Each actual argument can be a word, a text fragment or just about any
2020 <link linkend="quickbook.syntax.phrase">QuickBook phrase</link>. Arguments
2021 are separated by the double dot <literal>".."</literal> and terminated
2022 by the close parenthesis.
2024 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h4">
2025 <phrase id="quickbook.syntax.block.templates.nullary_templates"/><link
2026 linkend="quickbook.syntax.block.templates.nullary_templates">Nullary Templates</link>
2029 Nullary templates look and act like simple macros. Example:
2031 <programlisting><!--quickbook-escape-prefix-->[template alpha[]'''&#945;''']
2032 [template beta[]'''&#946;''']
2033 <!--quickbook-escape-postfix--></programlisting>
2037 <programlisting><!--quickbook-escape-prefix-->Some squigles...[*[alpha][beta]]<!--quickbook-escape-postfix--></programlisting>
2042 Some squiggles...<emphasis role="bold">αβ</emphasis>
2045 The difference with macros are
2050 The explicit <link linkend="quickbook.syntax.block.templates.template_expansion">template
2051 expansion syntax</link>. This is an advantage because, now, we don't
2052 have to use obscure naming conventions like double underscores (e.g.
2053 __alpha__) to avoid unwanted macro replacement.
2058 The template is expanded at the point where it is invoked. A macro
2059 is expanded immediately at its point of declaration. This is subtle
2060 and can cause a slight difference in behavior especially if you refer
2061 to other macros and templates in the body.
2066 The empty brackets after the template identifier (<literal>alpha[]</literal>)
2067 indicates no arguments. If the template body does not look like a template
2068 argument list, we can elide the empty brackets. Example:
2070 <programlisting><!--quickbook-escape-prefix-->[template aristotle_quote Aristotle: [*['Education is the best provision
2071 for the journey to old age.]]]
2072 <!--quickbook-escape-postfix--></programlisting>
2076 <programlisting><!--quickbook-escape-prefix-->Here's a quote from [aristotle_quote].
2077 <!--quickbook-escape-postfix--></programlisting>
2082 Here's a quote from Aristotle: <emphasis role="bold"><emphasis>Education
2083 is the best provision for the journey to old age.</emphasis></emphasis>.
2086 The disadvantage is that you can't avoid the space between the template
2087 identifier, <code><phrase role="identifier">aristotle_quote</phrase></code>,
2088 and the template body "Aristotle...". This space will be part
2089 of the template body. If that space is unwanted, use empty brackets or
2090 use the space escape: "<code><phrase role="special">\</phrase> </code>".
2093 <programlisting><!--quickbook-escape-prefix-->[template tag\ _tag]
2094 <!--quickbook-escape-postfix--></programlisting>
2098 <programlisting><!--quickbook-escape-prefix-->`struct` x[tag];
2099 <!--quickbook-escape-postfix--></programlisting>
2104 <code><phrase role="keyword">struct</phrase></code> x_tag;
2107 You have a couple of ways to do it. I personally prefer the explicit empty
2110 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h5">
2111 <phrase id="quickbook.syntax.block.templates.simple_arguments"/><link linkend="quickbook.syntax.block.templates.simple_arguments">Simple
2115 As mentioned, arguments are separated by the double dot <literal>".."</literal>.
2116 If there are less arguments passed than expected, QuickBook attempts to
2117 break the last argument into two or more arguments following this logic:
2122 Break the last argument into two, at the first space found (<literal>'',
2123 '\n', \t' or '\r'</literal>).
2128 Repeat until there are enough arguments or if there are no more spaces
2129 found (in which case, an error is reported).
2136 <programlisting><!--quickbook-escape-prefix-->[template simple[a b c d] [a][b][c][d]]
2138 <!--quickbook-escape-postfix--></programlisting>
2146 "w x y z" is initially treated as a single argument because we
2147 didn't supply any <literal>".."</literal> separators. However,
2148 since <literal>simple</literal> expects 4 arguments, "w x y z"
2149 is broken down iteratively (applying the logic above) until we have "w",
2150 "x", "y" and "z".
2153 QuickBook only tries to get the arguments it needs. For example:
2155 <programlisting><!--quickbook-escape-prefix-->[simple w x y z trail]
2156 <!--quickbook-escape-postfix--></programlisting>
2164 The arguments being: "w", "x", "y" and "z
2168 It should be obvious now that for simple arguments with no spaces, we can
2169 get by without separating the arguments with <literal>".."</literal>
2170 separators. It is possible to combine <literal>".."</literal>
2171 separators with the argument passing simplification presented above. Example:
2173 <programlisting><!--quickbook-escape-prefix-->[simple what do you think ..m a n?]
2174 <!--quickbook-escape-postfix--></programlisting>
2179 what do you think man?
2181 <bridgehead renderas="sect5" id="quickbook.syntax.block.templates.h6">
2182 <phrase id="quickbook.syntax.block.templates.punctuation_templates"/><link
2183 linkend="quickbook.syntax.block.templates.punctuation_templates">Punctuation
2187 With templates, one of our objectives is to allow us to rewrite QuickBook
2188 in QuickBook (as a qbk library). For that to happen, we need to accommodate
2189 single character punctuation templates which are fairly common in QuickBook.
2190 You might have noticed that single character punctuations are allowed as
2191 <link linkend="quickbook.syntax.block.templates.template_identifier">template
2192 identifiers</link>. Example:
2194 <programlisting><!--quickbook-escape-prefix-->[template ![bar] <!--quickbook-escape-postfix--><hey><!--quickbook-escape-prefix-->[bar]<!--quickbook-escape-postfix--></hey><!--quickbook-escape-prefix-->]
2195 <!--quickbook-escape-postfix--></programlisting>
2197 Now, expanding this:
2199 <programlisting><!--quickbook-escape-prefix-->[!baz]
2200 <!--quickbook-escape-postfix--></programlisting>
2204 <programlisting><hey>baz</hey>
2207 <section id="quickbook.syntax.block.blurbs">
2208 <title><link linkend="quickbook.syntax.block.blurbs">Blurbs</link></title>
2209 <programlisting><!--quickbook-escape-prefix-->[blurb :-) [*An eye catching advertisement or note...]
2211 __spirit__ is an object-oriented recursive-descent parser generator framework
2212 implemented using template meta-programming techniques. Expression templates
2213 allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
2216 <!--quickbook-escape-postfix--></programlisting>
2220 <sidebar role="blurb">
2222 <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
2224 <phrase>smiley</phrase>
2226 </inlinemediaobject> <emphasis role="bold">An eye catching advertisement
2227 or note...</emphasis>
2230 <ulink url="http://spirit.sourceforge.net">Spirit</ulink> is an object-oriented
2231 recursive-descent parser generator framework implemented using template
2232 meta-programming techniques. Expression templates allow us to approximate
2233 the syntax of Extended Backus-Normal Form (EBNF) completely in C++.
2238 Prefer <link linkend="quickbook.syntax.block.admonitions">admonitions</link>
2239 wherever appropriate.
2243 <section id="quickbook.syntax.block.tables">
2244 <title><link linkend="quickbook.syntax.block.tables">Tables</link></title>
2245 <programlisting><!--quickbook-escape-prefix-->[table A Simple Table
2246 [[Heading 1] [Heading 2] [Heading 3]]
2247 [[R0-C0] [R0-C1] [R0-C2]]
2248 [[R1-C0] [R1-C1] [R1-C2]]
2249 [[R2-C0] [R2-C1] [R2-C2]]
2251 <!--quickbook-escape-postfix--></programlisting>
2255 <table frame="all" id="quickbook.syntax.block.tables.t0">
2256 <title>A Simple Table</title>
2333 The table title is optional. The first row of the table is automatically
2334 treated as the table header; that is, it is wrapped in <literal><thead>...</thead></literal>
2335 XML tags. Note that unlike the original QuickDoc, the columns are nested
2336 in [ cells... ]. The syntax is free-format and allows big cells to be formatted
2339 <programlisting><!--quickbook-escape-prefix-->[table Table with fat cells
2340 [[Heading 1] [Heading 2]]
2342 [Row 0, Col 0: a small cell]
2344 Row 0, Col 1: a big fat cell with paragraphs
2346 Boost provides free peer-reviewed portable C++ source libraries.
2348 We emphasize libraries that work well with the C++ Standard Library.
2349 Boost libraries are intended to be widely useful, and usable across
2350 a broad spectrum of applications. The Boost license encourages both
2351 commercial and non-commercial use.
2355 [Row 1, Col 0: a small cell]
2356 [Row 1, Col 1: a small cell]
2359 <!--quickbook-escape-postfix--></programlisting>
2363 <table frame="all" id="quickbook.syntax.block.tables.t1">
2364 <title>Table with fat cells</title>
2384 Row 0, Col 0: a small cell
2389 Row 0, Col 1: a big fat cell with paragraphs
2392 Boost provides free peer-reviewed portable C++ source libraries.
2395 We emphasize libraries that work well with the C++ Standard Library.
2396 Boost libraries are intended to be widely useful, and usable
2397 across a broad spectrum of applications. The Boost license encourages
2398 both commercial and non-commercial use.
2405 Row 1, Col 0: a small cell
2410 Row 1, Col 1: a small cell
2418 Here's how to have preformatted blocks of code in a table cell:
2420 <programlisting><!--quickbook-escape-prefix-->[table Table with code
2424 [<!--quickbook-escape-postfix-->``
2425 #include <iostream>
2429 std::cout << "Hello, World!" << std::endl;
2432 ``<!--quickbook-escape-prefix-->]
2435 <!--quickbook-escape-postfix--></programlisting>
2436 <table frame="all" id="quickbook.syntax.block.tables.t2">
2437 <title>Table with code</title>
2462 <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
2464 <phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
2465 <phrase role="special">{</phrase>
2466 <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
2467 <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
2468 <phrase role="special">}</phrase>
2477 <section id="quickbook.syntax.block.variable_lists">
2478 <title><link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link></title>
2479 <programlisting><!--quickbook-escape-prefix-->[variablelist A Variable List
2480 [[term 1] [The definition of term 1]]
2481 [[term 2] [The definition of term 2]]
2482 [[term 3] [The definition of term 3]]
2484 <!--quickbook-escape-postfix--></programlisting>
2489 <title>A Variable List</title>
2494 The definition of term 1
2502 The definition of term 2
2510 The definition of term 3
2516 The rules for variable lists are the same as for tables, except that only
2517 2 "columns" are allowed. The first column contains the terms,
2518 and the second column contains the definitions. Those familiar with HTML
2519 will recognize this as a "definition list".
2522 <section id="quickbook.syntax.block.include">
2523 <title><link linkend="quickbook.syntax.block.include">Include</link></title>
2525 You can include one QuickBook file from another. The syntax is simply:
2527 <programlisting><!--quickbook-escape-prefix-->[include someother.qbk]
2528 <!--quickbook-escape-postfix--></programlisting>
2530 The included file will be processed as if it had been cut and pasted into
2531 the current document, with the following exceptions:
2536 The __FILENAME__ predefined macro will reflect the name of the file currently being
2542 Any macros defined in the included file are scoped to that file.
2547 The <literal>[include]</literal> directive lets you specify a document
2548 id to use for the included file. When this id is not explicitly specified,
2549 the id defaults to the filename ("someother", in the example
2550 above). You can specify the id like this:
2552 <programlisting><!--quickbook-escape-prefix-->[include:someid someother.qbk]
2553 <!--quickbook-escape-postfix--></programlisting>
2555 All auto-generated anchors will use the document id as a unique prefix.
2556 So for instance, if there is a top section in someother.qbk named "Intro",
2557 the named anchor for that section will be "someid.intro", and
2558 you can link to it with <literal>[link someid.intro The Intro]</literal>.
2561 <section id="quickbook.syntax.block.import">
2562 <title><link linkend="quickbook.syntax.block.import">Import</link></title>
2564 When documenting code, you'd surely need to present code from actual source
2565 files. While it is possible to copy some code and paste them in your QuickBook
2566 file, doing so is error prone and the extracted code in the documentation
2567 tends to get out of sync with the actual code as the code evolves. The
2568 problem, as always, is that once documentation is written, the tendency
2569 is for the docs to languish in the archives without maintenance.
2572 QuickBook's import facility provides a nice solution.
2574 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h0">
2575 <phrase id="quickbook.syntax.block.import.example"/><link linkend="quickbook.syntax.block.import.example">Example</link>
2578 You can effortlessly import code snippets from source code into your QuickBook.
2579 The following illustrates how this is done:
2581 <programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp]
2584 <!--quickbook-escape-postfix--></programlisting>
2588 <programlisting><!--quickbook-escape-prefix-->[import ../test/stub.cpp]
2589 <!--quickbook-escape-postfix--></programlisting>
2591 collects specially marked-up code snippets from <ulink url="../../test/stub.cpp">stub.cpp</ulink>
2592 and places them in your QuickBook file as virtual templates. Each of the
2593 specially marked-up code snippets has a name (e.g. <code><phrase role="identifier">foo</phrase></code>
2594 and <code><phrase role="identifier">bar</phrase></code> in the example
2595 above). This shall be the template identifier for that particular code
2596 snippet. The second and third line above does the actual template expansion:
2598 <programlisting><!--quickbook-escape-prefix-->[foo]
2600 <!--quickbook-escape-postfix--></programlisting>
2605 This is the <emphasis role="bold"><emphasis>foo</emphasis></emphasis> function.
2608 This description can have paragraphs...
2623 And any quickbook block markup.
2626 <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo</phrase><phrase role="special">()</phrase>
2627 <phrase role="special">{</phrase>
2628 <phrase role="comment">// return 'em, foo man!</phrase>
2629 <phrase role="keyword">return</phrase> <phrase role="string">"foo"</phrase><phrase role="special">;</phrase>
2630 <phrase role="special">}</phrase>
2634 This is the <emphasis role="bold"><emphasis>bar</emphasis></emphasis> function
2637 <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">bar</phrase><phrase role="special">()</phrase>
2638 <phrase role="special">{</phrase>
2639 <phrase role="comment">// return 'em, bar man!</phrase>
2640 <phrase role="keyword">return</phrase> <phrase role="string">"bar"</phrase><phrase role="special">;</phrase>
2641 <phrase role="special">}</phrase>
2645 Some trailing text here
2647 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h1">
2648 <phrase id="quickbook.syntax.block.import.code_snippet_markup"/><link linkend="quickbook.syntax.block.import.code_snippet_markup">Code
2649 Snippet Markup</link>
2652 Note how the code snippets in <ulink url="../../test/stub.cpp">stub.cpp</ulink>
2653 get marked up. We use distinguishable comments following the form:
2655 <programlisting><phrase role="comment">//[id</phrase>
2656 <phrase role="identifier">some</phrase> <phrase role="identifier">code</phrase> <phrase role="identifier">here</phrase>
2657 <phrase role="comment">//]</phrase>
2660 The first comment line above initiates a named code-snippet. This prefix
2661 will not be visible in quickbook. The entire code-snippet in between <code><phrase
2662 role="comment">//[id</phrase></code> and <code><phrase role="comment">//]</phrase></code>
2663 will be inserted as a template in quickbook with name <emphasis><emphasis>id</emphasis></emphasis>.
2664 The comment <code><phrase role="comment">//]</phrase></code> ends a code-snippet
2665 This too will not be visible in quickbook.
2667 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h2">
2668 <phrase id="quickbook.syntax.block.import.special_comments"/><link linkend="quickbook.syntax.block.import.special_comments">Special
2672 Special comments of the form:
2674 <programlisting><phrase role="comment">//` some [*quickbook] markup here</phrase>
2679 <programlisting><phrase role="comment">/*` some [*quickbook] markup here */</phrase>
2682 will be parsed by QuickBook. This can contain quickbook <emphasis>blocks</emphasis>
2683 (e.g. sections, paragraphs, tables, etc). In the first case, the initial
2684 slash-slash, tick and white-space shall be ignored. In the second, the
2685 initial slash-star-tick and the final star-slash shall be ignored.
2687 <bridgehead renderas="sect5" id="quickbook.syntax.block.import.h3">
2688 <phrase id="quickbook.syntax.block.import.callouts"/><link linkend="quickbook.syntax.block.import.callouts">Callouts</link>
2691 Special comments of the form:
2693 <programlisting><phrase role="comment">/*< some [*quickbook] markup here >*/</phrase>
2696 will be regarded as callouts. These will be collected, numbered and rendered
2697 as a "callout bug" (a small icon with a number). After the whole
2698 snippet is parsed, the callout list is generated. See <ulink url="http://www.docbook.org/tdg/en/html/callout.html">Callouts</ulink>
2699 for details. Example:
2702 <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">foo_bar</phrase><phrase role="special">()</phrase> <co id="quickbook.syntax.block.import.c0" linkends="quickbook.syntax.block.import.c1" />
2703 <phrase role="special">{</phrase>
2704 <phrase role="keyword">return</phrase> <phrase role="string">"foo-bar"</phrase><phrase role="special">;</phrase> <co id="quickbook.syntax.block.import.c2" linkends="quickbook.syntax.block.import.c3" />
2705 <phrase role="special">}</phrase>
2709 <callout arearefs="quickbook.syntax.block.import.c0" id="quickbook.syntax.block.import.c1">
2711 The <emphasis>Mythical</emphasis> FooBar. See <ulink url="http://en.wikipedia.org/wiki/Foobar">Foobar
2715 <callout arearefs="quickbook.syntax.block.import.c2" id="quickbook.syntax.block.import.c3">
2717 return 'em, foo-bar man!
2722 Checkout <ulink url="../../test/stub.cpp">stub.cpp</ulink> to see the actual
2728 <section id="quickbook.install">
2729 <title><link linkend="quickbook.install">Installation and configuration</link></title>
2731 This section provides some guidelines on how to install and configure BoostBook
2732 and Quickbook under several operating systems.
2735 Before continuing, it is very important that you keep this in mind: if you
2736 try to build some documents and the process breaks due to misconfiguration,
2737 be absolutely sure to delete any <code><phrase role="identifier">bin</phrase></code>
2738 and <code><phrase role="identifier">bin</phrase><phrase role="special">.</phrase><phrase
2739 role="identifier">v2</phrase></code> directories generated by the build before
2740 trying again. Otherwise your configuration fixes will not take any effect.
2742 <section id="quickbook.install.windows">
2743 <title><link linkend="quickbook.install.windows">Windows 2000, XP, 2003, Vista</link></title>
2746 <emphasis>Section contributed by Julio M. Merino Vidal</emphasis>
2750 The following instructions apply to any Windows system based on Windows 2000,
2751 including Windows XP, Windows 2003 Server and Windows Vista. The paths shown
2752 below are taken from a Windows Vista machine; you will need to adjust them
2753 to match your system in case you are running an older version.
2758 First of all you need to have a copy of <code><phrase role="identifier">xsltproc</phrase></code>
2759 for Windows. There are many ways to get this tool, but to keep things
2760 simple, use the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary
2761 packages</ulink> made by Igor Zlatkovic. At the very least, you need
2762 to download the following packages: <code><phrase role="identifier">iconv</phrase></code>,
2763 <code><phrase role="identifier">zlib</phrase></code>, <code><phrase role="identifier">libxml2</phrase></code>
2764 and <code><phrase role="identifier">libxslt</phrase></code>.
2769 Unpack all these packages in the same directory so that you get unique
2770 <code><phrase role="identifier">bin</phrase></code>, <code><phrase role="identifier">include</phrase></code>
2771 and <code><phrase role="identifier">lib</phrase></code> directories within
2772 the hierarchy. These instructions use <code><phrase role="identifier">C</phrase><phrase
2773 role="special">:\</phrase><phrase role="identifier">Users</phrase><phrase
2774 role="special">\</phrase><phrase role="identifier">example</phrase><phrase
2775 role="special">\</phrase><phrase role="identifier">Documents</phrase><phrase
2776 role="special">\</phrase><phrase role="identifier">boost</phrase><phrase
2777 role="special">\</phrase><phrase role="identifier">xml</phrase></code>
2778 as the root for all files.
2783 From the command line, go to the <code><phrase role="identifier">bin</phrase></code>
2784 directory and launch <code><phrase role="identifier">xsltproc</phrase><phrase
2785 role="special">.</phrase><phrase role="identifier">exe</phrase></code>
2786 to ensure it works. You should get usage information on screen.
2791 Download <ulink url="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip">Docbook
2792 XML 4.2</ulink> and unpack it in the same directory used above. That
2793 is: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
2794 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
2795 role="identifier">example</phrase><phrase role="special">\</phrase><phrase
2796 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
2797 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
2798 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
2799 role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
2800 role="identifier">xml</phrase></code>.
2805 Download the latest <ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608">Docbook
2806 XSL</ulink> version and unpack it, again in the same directory used before.
2807 To make things easier, rename the directory created during the extraction
2808 to <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
2809 role="identifier">xsl</phrase></code> (bypassing the version name):
2810 <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
2811 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
2812 role="identifier">example</phrase><phrase role="special">\</phrase><phrase
2813 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
2814 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
2815 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
2816 role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
2817 role="identifier">xsl</phrase></code>.
2822 Add the following to your <code><phrase role="identifier">user</phrase><phrase
2823 role="special">-</phrase><phrase role="identifier">config</phrase><phrase
2824 role="special">.</phrase><phrase role="identifier">jam</phrase></code>
2825 file, which should live in your home directory (<code><phrase role="special">%</phrase><phrase
2826 role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase
2827 role="identifier">HOMEPATH</phrase><phrase role="special">%</phrase></code>).
2828 You must already have it somewhere or otherwise you could not be building
2829 Boost (i.e. missing tools configuration).
2833 <programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase>
2834 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</phrase>
2835 <phrase role="special">;</phrase>
2837 <phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase>
2838 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</phrase>
2839 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</phrase>
2840 <phrase role="special">;</phrase>
2843 The above steps are enough to get a functional BoostBook setup. Quickbook
2844 will be automatically built when needed. If you want to avoid these rebuilds:
2849 Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
2850 role="special">\</phrase><phrase role="identifier">tools</phrase><phrase
2851 role="special">\</phrase><phrase role="identifier">quickbook</phrase></code>).
2856 Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
2857 <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
2862 Copy the resulting <code><phrase role="identifier">quickbook</phrase><phrase
2863 role="special">.</phrase><phrase role="identifier">exe</phrase></code>
2864 binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
2865 role="special">\</phrase><phrase role="identifier">bin</phrase><phrase
2866 role="special">.</phrase><phrase role="identifier">v2</phrase></code>
2867 hierarchy) to a safe place. Following our previous example, you can install
2868 it into: <code><phrase role="identifier">C</phrase><phrase role="special">:\</phrase><phrase
2869 role="identifier">Users</phrase><phrase role="special">\</phrase><phrase
2870 role="identifier">example</phrase><phrase role="special">\</phrase><phrase
2871 role="identifier">Documents</phrase><phrase role="special">\</phrase><phrase
2872 role="identifier">boost</phrase><phrase role="special">\</phrase><phrase
2873 role="identifier">xml</phrase><phrase role="special">\</phrase><phrase
2874 role="identifier">bin</phrase></code>.
2879 Add the following to your <code><phrase role="identifier">user</phrase><phrase
2880 role="special">-</phrase><phrase role="identifier">config</phrase><phrase
2881 role="special">.</phrase><phrase role="identifier">jam</phrase></code>
2886 <programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
2887 <phrase role="special">:</phrase> <phrase role="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</phrase>
2888 <phrase role="special">;</phrase>
2891 <section id="quickbook.install.linux">
2892 <title><link linkend="quickbook.install.linux">Debian, Ubuntu</link></title>
2894 The following instructions apply to Debian and its derivatives. They are
2895 based on a Ubuntu Edgy install but should work on other Debian based systems.
2898 First install the <code><phrase role="identifier">bjam</phrase></code>,
2899 <code><phrase role="identifier">xsltproc</phrase></code>, <code><phrase role="identifier">docbook</phrase><phrase
2900 role="special">-</phrase><phrase role="identifier">xsl</phrase></code> and
2901 <code><phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase
2902 role="identifier">xml</phrase></code> packages. For example, using <code><phrase
2903 role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase></code>:
2905 <programlisting><phrase role="identifier">sudo</phrase> <phrase role="identifier">apt</phrase><phrase role="special">-</phrase><phrase role="identifier">get</phrase> <phrase role="identifier">install</phrase> <phrase role="identifier">xsltprc</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xsl</phrase> <phrase role="identifier">docbook</phrase><phrase role="special">-</phrase><phrase role="identifier">xml</phrase>
2908 If you're planning on building boost's documentation, you'll also need to
2909 install the <code><phrase role="identifier">doxygen</phrase></code> package
2913 Next, we need to configure Boost Build to compile BoostBook files. Add the
2914 following to your <code><phrase role="identifier">user</phrase><phrase role="special">-</phrase><phrase
2915 role="identifier">config</phrase><phrase role="special">.</phrase><phrase
2916 role="identifier">jam</phrase></code> file, which should be in your home
2917 directory. If you don't have one, create a file containing this text. For
2918 more information on setting up <code><phrase role="identifier">user</phrase><phrase
2919 role="special">-</phrase><phrase role="identifier">config</phrase><phrase
2920 role="special">.</phrase><phrase role="identifier">jam</phrase></code>, see
2921 the <ulink url="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">Boost
2922 Build documentation</ulink>.
2924 <programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">xsltproc</phrase> <phrase role="special">;</phrase>
2926 <phrase role="identifier">using</phrase> <phrase role="identifier">boostbook</phrase>
2927 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">stylesheet</phrase><phrase role="special">/</phrase><phrase role="identifier">nwalsh</phrase>
2928 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">share</phrase><phrase role="special">/</phrase><phrase role="identifier">xml</phrase><phrase role="special">/</phrase><phrase role="identifier">docbook</phrase><phrase role="special">/</phrase><phrase role="identifier">schema</phrase><phrase role="special">/</phrase><phrase role="identifier">dtd</phrase><phrase role="special">/</phrase><phrase role="number">4.2</phrase>
2929 <phrase role="special">;</phrase>
2931 <phrase role="comment"># Remove this line if you're not using doxygen</phrase>
2932 <phrase role="identifier">using</phrase> <phrase role="identifier">doxygen</phrase> <phrase role="special">;</phrase>
2935 The above steps are enough to get a functional BoostBook setup. Quickbook
2936 will be automatically built when needed. If you want to avoid these rebuilds:
2941 Go to Quickbook's source directory (<code><phrase role="identifier">BOOST_ROOT</phrase><phrase
2942 role="special">/</phrase><phrase role="identifier">tools</phrase><phrase
2943 role="special">/</phrase><phrase role="identifier">quickbook</phrase></code>).
2948 Build the utility by issuing <code><phrase role="identifier">bjam</phrase>
2949 <phrase role="special">--</phrase><phrase role="identifier">v2</phrase></code>.
2954 Copy the resulting <code><phrase role="identifier">quickbook</phrase></code>
2955 binary (located under the <code><phrase role="identifier">BOOST_ROOT</phrase><phrase
2956 role="special">/</phrase><phrase role="identifier">bin</phrase><phrase
2957 role="special">.</phrase><phrase role="identifier">v2</phrase></code>
2958 hierarchy) to a safe place. The traditional location is <code><phrase
2959 role="special">/</phrase><phrase role="identifier">usr</phrase><phrase
2960 role="special">/</phrase><phrase role="identifier">local</phrase><phrase
2961 role="special">/</phrase><phrase role="identifier">bin</phrase></code>.
2966 Add the following to your <code><phrase role="identifier">user</phrase><phrase
2967 role="special">-</phrase><phrase role="identifier">config</phrase><phrase
2968 role="special">.</phrase><phrase role="identifier">jam</phrase></code>
2969 file, using the full path of the quickbook executable:
2973 <programlisting><phrase role="identifier">using</phrase> <phrase role="identifier">quickbook</phrase>
2974 <phrase role="special">:</phrase> <phrase role="special">/</phrase><phrase role="identifier">usr</phrase><phrase role="special">/</phrase><phrase role="identifier">local</phrase><phrase role="special">/</phrase><phrase role="identifier">bin</phrase><phrase role="special">/</phrase><phrase role="identifier">quickbook</phrase>
2975 <phrase role="special">;</phrase>
2979 <section id="quickbook.editors">
2980 <title><link linkend="quickbook.editors">Editor Support</link></title>
2982 Editing quickbook files is usually done with text editors both simple and powerful.
2983 The following sections list the settings for some editors which can help make
2984 editing quickbook files a bit easier.
2986 <sidebar role="blurb">
2988 <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
2990 <phrase>note</phrase>
2992 </inlinemediaobject> You may submit your settings, tips, and suggestions to
2993 the authors, or through the <ulink url="https://lists.sourceforge.net/lists/listinfo/boost-">docs
2994 Boost Docs mailing list</ulink>.
2997 <section id="quickbook.editors.scite">
2998 <title><link linkend="quickbook.editors.scite">Scintilla Text Editor</link></title>
3001 <emphasis>Section contributed by Dean Michael Berris</emphasis>
3005 The Scintilla Text Editor (SciTE) is a free source code editor for Win32
3006 and X. It uses the SCIntilla source code editing component.
3008 <sidebar role="blurb">
3010 <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
3012 <phrase>tip</phrase>
3014 </inlinemediaobject> SciTE can be downloaded from <ulink url="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</ulink>
3018 You can use the following settings to highlight quickbook tags when editing
3021 <programlisting><!--quickbook-escape-prefix-->qbk=*.qbk
3025 indent.size.$(qbk)=4
3026 style.props.32=$(font.base)
3027 comment.stream.start.props=[/
3028 comment.stream.end.props=]
3029 comment.box.start.props=[/
3030 comment.box.middle.props=
3031 comment.box.end.props=]
3032 <!--quickbook-escape-postfix--></programlisting>
3033 <sidebar role="blurb">
3035 <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
3037 <phrase>note</phrase>
3039 </inlinemediaobject> Thanks to Rene Rivera for the above SciTE settings.
3044 <section id="quickbook.faq">
3045 <title><link linkend="quickbook.faq">Frequently Asked Questions</link></title>
3046 <bridgehead renderas="sect3" id="quickbook.faq.h0">
3047 <phrase id="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_"/><link
3048 linkend="quickbook.faq.can_i_use_quickbook_for_non_boost_documentation_">Can
3049 I use QuickBook for non-Boost documentation?</link>
3052 QuickBook can be used for non-Boost documentation with a little extra work.
3056 <emphasis>Faq contributed by Michael Marcin</emphasis>
3060 When building HTML documentation with BoostBook a Boost C++ Libraries header
3061 is added to the files. When using QuickBook to document projects outside of
3062 Boost this is not desirable. This behavior can be overridden at the BoostBook
3063 level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
3064 this can be achieved by adding parameters to the BoostBook target declaration.
3069 <programlisting>using quickbook ;
3071 xml my_doc : my_doc.qbk ;
3073 boostbook standalone
3077 <xsl:param>boost.image.src=images/my_project_logo.png
3078 <xsl:param>boost.image.alt="\"My Project\""
3079 <xsl:param>boost.image.w=100
3080 <xsl:param>boost.image.h=50
3081 <xsl:param>nav.layout=none
3085 <section id="quickbook.ref">
3086 <title><link linkend="quickbook.ref">Quick Reference</link></title>
3090 <table frame="all" id="quickbook.ref.t0">
3091 <title>Syntax Compendium</title>
3121 <literal>[/ some comment]</literal>
3126 <link linkend="quickbook.syntax.comments">Comments</link>
3133 <emphasis>italics</emphasis>
3138 <literal>['italics] or /italics/</literal>
3143 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
3144 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
3152 <emphasis role="bold">bold</emphasis>
3157 <literal>[*bold] or *bold*</literal>
3162 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
3163 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
3171 <emphasis role="underline">underline</emphasis>
3176 <literal>[_underline] or _underline_</literal>
3181 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
3182 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
3190 <literal>teletype</literal>
3195 <literal>[^teletype] or =teletype=</literal>
3200 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
3201 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
3209 <emphasis role="strikethrough">strikethrough</emphasis>
3214 <literal>[-strikethrough]</literal>
3219 <link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link>
3220 and <link linkend="quickbook.syntax.phrase.simple_formatting">Simple
3228 <replaceable>replaceable</replaceable>
3233 <literal>[~replaceable]</literal>
3238 <link linkend="quickbook.syntax.phrase.replaceable">Replaceble</link>
3250 <literal>[c++]</literal> or <literal>[python]</literal>
3255 <link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>
3267 <literal>`int main();`</literal>
3272 <link linkend="quickbook.syntax.phrase.inline_code">Inline code</link>
3284 <literal>``int main();``</literal>
3289 <link linkend="quickbook.syntax.block.code">Code</link>
3301 <literal>``from c++ to QuickBook``</literal>
3306 <link linkend="quickbook.syntax.block.escape_back">Escaping Back
3319 <literal>[br] or \n</literal>
3324 <link linkend="quickbook.syntax.phrase.line_break">line-break</link>
3325 <emphasis role="bold">DEPRECATED</emphasis>
3337 <literal>[#anchor]</literal>
3342 <link linkend="quickbook.syntax.phrase.anchors">Anchors</link>
3354 <literal>[@http://www.boost.org Boost]</literal>
3359 <link linkend="quickbook.syntax.phrase.links">Links</link>
3371 <literal>[link section.anchor Link text]</literal>
3376 <link linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link>
3388 <literal>[link xml.refentry Link text]</literal>
3393 <link linkend="quickbook.syntax.phrase.refentry_links">refentry links</link>
3405 <literal>[funcref fully::qualified::function_name Link text]</literal>
3410 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3411 member, enum, macro, concept or header links</link>
3423 <literal>[classref fully::qualified::class_name Link text]</literal>
3428 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3429 member, enum, macro, concept or header links</link>
3441 <literal>[memberref fully::qualified::member_name Link text]</literal>
3446 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3447 member, enum, macro, concept or header links</link>
3459 <literal>[enumref fully::qualified::enum_name Link text]</literal>
3464 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3465 member, enum, macro, concept or header links</link>
3477 <literal>[macroref MACRO_NAME Link text]</literal>
3482 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3483 member, enum, macro, concept or header links</link>
3495 <literal>[conceptref ConceptName Link text]</literal>
3500 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3501 member, enum, macro, concept or header links</link>
3513 <literal>[headerref path/to/header.hpp Link text]</literal>
3518 <link linkend="quickbook.syntax.phrase.code_links">function, class,
3519 member, enum, macro, concept or header links</link>
3531 <literal>'''escaped text (no processing/formatting)'''</literal>
3536 <link linkend="quickbook.syntax.phrase.escape">Escape</link>
3548 <literal>\c</literal>
3553 <link linkend="quickbook.syntax.phrase.single_char_escape">Single
3566 <literal>[$image.jpg]</literal>
3571 <link linkend="quickbook.syntax.phrase.images">Images</link>
3583 <literal>[section The Section Title]</literal>
3588 <link linkend="quickbook.syntax.block.section">Section</link>
3600 <literal>[endsect]</literal>
3605 <link linkend="quickbook.syntax.block.section">Section</link>
3617 No markup. Paragraphs start left-flushed and are terminated by two
3623 <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link>
3634 <programlisting><!--quickbook-escape-prefix--># one
3637 <!--quickbook-escape-postfix--></programlisting>
3641 <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
3653 <programlisting><!--quickbook-escape-prefix-->* one
3656 <!--quickbook-escape-postfix--></programlisting>
3660 <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
3673 No markup. Preformatted code starts with a space or a tab.
3678 <link linkend="quickbook.syntax.block.code">Code</link>
3690 <literal>[pre preformatted]</literal>
3695 <link linkend="quickbook.syntax.block.preformatted">Preformatted</link>
3707 <literal>[:sometext...]</literal>
3712 <link linkend="quickbook.syntax.block.blockquote">Blockquote</link>
3724 <literal>[h1 Heading 1]</literal>
3729 <link linkend="quickbook.syntax.block.headings">Heading</link>
3741 <literal>[h2 Heading 2]</literal>
3746 <link linkend="quickbook.syntax.block.headings">Heading</link>
3758 <literal>[h3 Heading 3]</literal>
3763 <link linkend="quickbook.syntax.block.headings">Heading</link>
3775 <literal>[h4 Heading 4]</literal>
3780 <link linkend="quickbook.syntax.block.headings">Heading</link>
3792 <literal>[h5 Heading 5]</literal>
3797 <link linkend="quickbook.syntax.block.headings">Heading</link>
3809 <literal>[h6 Heading 6]</literal>
3814 <link linkend="quickbook.syntax.block.headings">Heading</link>
3826 <literal>[def macro_identifier some text]</literal>
3831 <link linkend="quickbook.syntax.block.macros">Macros</link>
3843 <literal>[template[a b] [a] body [b]]</literal>
3848 <link linkend="quickbook.syntax.block.templates">Templates</link>
3860 <literal>[blurb advertisement or note...]</literal>
3865 <link linkend="quickbook.syntax.block.blurbs">Blurbs</link>
3877 <literal>[warning Warning text...]</literal>
3882 <link linkend="quickbook.syntax.block.admonitions">Admonitions</link>
3893 <programlisting><!--quickbook-escape-prefix-->[table Title
3897 <!--quickbook-escape-postfix--></programlisting>
3901 <link linkend="quickbook.syntax.block.tables">Tables</link>
3912 <programlisting><!--quickbook-escape-prefix-->[variablelist Title
3916 <!--quickbook-escape-postfix--></programlisting>
3920 <link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link>
3932 <literal>[include someother.qbk]</literal>
3937 <link linkend="quickbook.syntax.block.include">Include</link>
projects / ceph.git / blob