diff options
Diffstat (limited to 'tools/quickbook/doc/block.qbk')
| -rw-r--r-- | tools/quickbook/doc/block.qbk | 1113 |
1 files changed, 1113 insertions, 0 deletions
diff --git a/tools/quickbook/doc/block.qbk b/tools/quickbook/doc/block.qbk new file mode 100644 index 0000000000..f9da265b77 --- /dev/null +++ b/tools/quickbook/doc/block.qbk @@ -0,0 +1,1113 @@ +[/ + Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler + Copyright 2010-2011 Daniel James + + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +] + +[chapter Block Level Elements + [quickbook 1.6] + [compatibility-mode 1.5] + [id quickbook.syntax.block] + [source-mode teletype] +] + +[section xinclude] + +You can include another XML file with: + +``` +[xinclude file.xml] +``` + +This is useful when file.xml has been generated by Doxygen and contains your +reference section. + +[endsect] [/xinclude] + +[section Paragraphs] + +Paragraphs start left-flushed and are terminated by two or more newlines. No +markup is needed for paragraphs. QuickBook automatically detects paragraphs from +the context. Block markups \[section, endsect, h1, h2, h3, h4, h5, h6, blurb, +(block-quote) ':', pre, def, table and include \] may also terminate a paragraph. + [/ <-- There's a space here. Don't remove. this is intentianal, for testing] +This is a new paragraph... + +[endsect] [/Paragraphs] + +[section Lists] +[section Ordered lists] + +[pre +# One +# Two +# Three +] + +will generate: + +# One +# Two +# Three + +[endsect] [/Ordered lists] +[section List Hierarchies] + +List hierarchies are supported. Example: + +[pre +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii +# Five +] + +will generate: + +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Fourth + # Four.a + # Four.a.i + # Four.a.ii +# Five + +[endsect] [/List Hierarchies] +[section Long List Lines] + +Long lines will be wrapped appropriately. Example: + +[pre +# A short item. +# A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. +# A short item. +] + +# A short item. +# A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. + A very long item. A very long item. A very long item. +# A short item. + +[endsect] [/Long list lines] +[section Unordered lists] + +``` +* First +* Second +* Third +``` + +will generate: + +* First +* Second +* Third + +[endsect] [/Unordered lists] +[section Mixed lists] + +Mixed lists (ordered and unordered) are supported. Example: + +``` +# One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four +``` + +will generate: + +# One +# Two +# Three + * Three.a + * Three.b + * Three.c +# Four + +And... + +``` +# 1 + * 1.a + # 1.a.1 + # 1.a.2 + * 1.b +# 2 + * 2.a + * 2.b + # 2.b.1 + # 2.b.2 + * 2.b.2.a + * 2.b.2.b +``` + +will generate: + +# 1 + * 1.a + # 1.a.1 + # 1.a.2 + * 1.b +# 2 + * 2.a + * 2.b + # 2.b.1 + # 2.b.2 + * 2.b.2.a + * 2.b.2.b + +[endsect] [/Mixed lists] +[endsect] [/Lists] + +[section Code] + +Preformatted code starts with a space or a tab. The code will be +syntax highlighted according to the current __source_mode__: + +[c++] + + #include <iostream> + + int main() + { + // Sample code + std::cout << "Hello, World\n"; + return 0; + } + +[python] + + import cgi + + def cookForHtml(text): + '''"Cooks" the input text for HTML.''' + + return cgi.escape(text) + +[teletype] + +Macros that are already defined are expanded in source code. Example: + +``` +[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] +[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] + + using __boost__::__array__; +``` + +Generates: + +[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]] +[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]] + + using __boost__::__array__; + +[endsect] [/Code] + +[section:escape_back Escaping Back To QuickBook] + +Inside code, code blocks and inline code, QuickBook does not allow any +markup to avoid conflicts with the target syntax (e.g. c++). In case you +need to switch back to QuickBook markup inside code, you can do so using a +language specific /escape-back/ delimiter. In C++ and Python, the delimiter +is the double tick (back-quote): "\`\`" and "\`\`". Example: + +``` +void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() +{ +} +``` + +Will generate: + + void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``() + { + } + +When escaping from code to QuickBook, only phrase level markups are +allowed. Block level markups like lists, tables etc. are not allowed. + +[endsect] [/Escaping back to quickbook] + +[section Preformatted] + +Sometimes, you don't want some preformatted text to be parsed as source code. In such +cases, use the [^\[pre ... \]] markup block. + +``` +[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] +``` + +Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level +markup, pre (and Code) are the only ones that allow multiple newlines. The +markup above will generate: + +[pre + +Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] + +Notice that unlike Code, phrase markup such as font style is still permitted +inside =pre= blocks. + +[endsect] [/Preformatted] + +[section Blockquote] + +[pre +'''[:sometext...]''' +] + +[:Indents the paragraph. This applies to one paragraph only.] + +[endsect] [/Blockquote] + +[section Admonitions] + +``` +[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] +``` + +generates __docbook__ admonitions: + +[note This is a note] +[tip This is a tip] +[important This is important] +[caution This is a caution] +[warning This is a warning] + +These are the only admonitions supported by __docbook__. So, +for example [^\[information This is some information\]] is unlikely +to produce the desired effect. + +[endsect] [/Admonitions] + +[section Headings] + +``` +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +``` + +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] + +Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with +normalized names with +[^name="document_id.section_id.normalized_header_text"] (i.e. valid +characters are =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are +converted to underscore and all upper-case are converted to lower-case. +For example: Heading 1 in section Section 2 will be normalized to +[^section_2.heading_1]). You can use: + +``` +[link document_id.section_id.normalized_header_text The link text] +``` + +to link to them. See __anchor_links__ and __section__ for more info. + +[endsect] [/Headings] + +[section Generic Heading] + +In cases when you don't want to care about the heading level (1 to 6), you +can use the /Generic Heading/: + +``` +[heading Heading] +``` + +The /Generic Heading/ assumes the level, plus one, of the innermost section +where it is placed. For example, if it is placed in the outermost section, +then, it assumes /h2/. + +Headings are often used as an alternative to sections. It is used +particularly if you do not want to start a new section. In many cases, +however, headings in a particular section is just flat. Example: + +``` +[section A] +[h2 X] +[h2 Y] +[h2 Z] +[endsect] +``` + +Here we use h2 assuming that section A is the outermost level. If it is +placed in an inner level, you'll have to use h3, h4, etc. depending on +where the section is. In general, it is the section level plus one. It is +rather tedious, however, to scan the section level everytime. If you +rewrite the example above as shown below, this will be automatic: + +``` +[section A] +[heading X] +[heading Y] +[heading Z] +[endsect] +``` + +They work well regardless where you place them. You can rearrange sections +at will without any extra work to ensure correct heading levels. In fact, +with /section/ and /heading/, you have all you need. /h1/../h6/ becomes +redundant. /h1/../h6/ might be deprecated in the future. + +[endsect] [/Generic Heading] + +[section Macros] + +``` +[def macro_identifier some text] +``` + +When a macro is defined, the identifier replaces the text anywhere in the +file, in paragraphs, in markups, etc. macro_identifier is a string of non- +white space characters except '\]'. A macro may not follow an alphabetic +character or the underscore. The replacement text can be any phrase (even +marked up). Example: + +``` +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo +``` + +Now everywhere the sf_logo is placed, the picture will be inlined. + +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo + +[tip It's a good idea to use macro identifiers that are distinguishable. +For instance, in this document, macro identifiers have two leading and +trailing underscores (e.g. [^\__spirit__]). The reason is to avoid +unwanted macro replacement.] + +Links (URLS) and images are good candidates for macros. *1*) They tend to +change a lot. It is a good idea to place all links and images in one place near the top +to make it easy to make changes. *2*) The syntax is not pretty. It's easier to read and +write, e.g. [^\__spirit__] than `[@http://spirit.sourceforge.net Spirit]`. + +Some more examples: + +``` +[def ``\:-)`` [$theme/smiley.png]] +[def ``\__spirit__`` [@http://spirit.sourceforge.net Spirit]] +``` + +(See __images__ and __links__) + +Invoking these macros: + +``` +Hi ``\__spirit__`` ``\:-)`` +``` + +will generate this: + +Hi __spirit__ :-) + +[endsect] [/Macros] + +[section Predefined Macros] + +Quickbook has some predefined macros that you can already use. + +[table Predefined Macros + [[Macro] [Meaning] [Example]] + [[[^\__DATE__]] [Today's date] [__DATE__]] + [[[^\__TIME__]] [The current time] [__TIME__]] + [[[^\__FILENAME__]][Quickbook source filename] [__FILENAME__]] +] + +[endsect] [/Predefined Macros] + +[section Templates] + +Templates provide a more versatile text substitution mechanism. Templates +come in handy when you need to create parameterizable, multi-line, +boilerplate text that you specify once and expand many times. Templates +accept one or more arguments. These arguments act like place-holders for +text replacement. Unlike simple macros, which are limited to phrase level +markup, templates can contain block level markup (e.g. paragraphs, code +blocks and tables). + +Example template: + +``` +[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] +``` + +[template person[name age what] + +Hi, my name is [name]. I am [age] years old. I am a [what]. + +] + +[heading Template Identifier] + +Template identifiers can either consist of: + +* An initial alphabetic character or the underscore, followed by + zero or more alphanumeric characters or the underscore. This is + similar to your typical C/C++ identifier. +* A single character punctuation (a non-alphanumeric printable character) + +[heading Formal Template Arguments] + +Template formal arguments are identifiers consisting of an initial +alphabetic character or the underscore, followed by zero or more +alphanumeric characters or the underscore. This is similar to your typical +C/C++ identifier. + +A template formal argument temporarily hides a template of the same name at +the point where the [link quickbook.syntax.block.templates.template_expansion +template is expanded]. Note that the body of the [^person] template above +refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and +[^\[what\]]. [^name] [^age] and [^what] are actually templates that exist +in the duration of the template call. + +[heading Template Body] + +The template body can be just about any QuickBook block or phrase. There +are actually two forms. Templates may be phrase or block level. Phrase +templates are of the form: + +``` +[template sample[arg1 arg2...argN] replacement text... ] +``` + +Block templates are of the form: + +``` +[template sample[arg1 arg2...argN] +replacement text... +] +``` + +The basic rule is as follows: if a newline immediately follows the argument +list, then it is a block template, otherwise, it is a phrase template. +Phrase templates are typically expanded as part of phrases. Like macros, +block level elements are not allowed in phrase templates. + +[heading Template Expansion] + +You expand a template this way: + +``` +[template_identifier arg1..arg2..arg3] +``` + +At template expansion, you supply the actual arguments. The template will +be expanded with your supplied arguments. Example: + +``` +[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] +``` + +Which will expand to: + +[person James Bond..39..Spy] +[person Santa Clause..87..Big Red Fatso] + +[caution A word of caution: Templates are recursive. A template can call +another template or even itself, directly or indirectly. There are no +control structures in QuickBook (yet) so this will always mean infinite +recursion. QuickBook can detect this situation and report an error if +recursion exceeds a certain limit.] + +Each actual argument can be a word, a text fragment or just about any [link +quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the +double dot [^".."] and terminated by the close parenthesis. + +Note that templates and template parameters can't be expanded +everywhere, only where text is interpreted as a phrase. So they can't be +expanded in places such as table titles and link's urls. If you want to +use a template to generate a link based of the template parameter, you +can't use a normal link and will need to use escaped docbook instead. +Example: + +[teletype] +``` +[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] + +[boost_ticket 2035] +``` + +will expand to: + +[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>'''] + +[boost_ticket 2035] + +[caution Since quickbook doesn't understand the context where the +parameter is being used, it will interpret it as quickbook markup, so +when writing a template like this, you'll need to escape any meaningful +punctuation.] + +[heading Nullary Templates] + +Nullary templates look and act like simple macros. Example: + +``` +[template alpha[]'''&#945;'''] +[template beta[]'''&#946;'''] +``` + +[template alpha[]'''α'''] +[template beta[]'''β'''] + +Expanding: + +```Some squigles...[*[alpha][beta]]``` + +We have: + +Some squiggles...[*[alpha][beta]] + +The difference with macros are + +* The explicit [link quickbook.syntax.block.templates.template_expansion + template expansion syntax]. This is an advantage because, now, we don't + have to use obscure naming conventions like double underscores (e.g. + \_\_alpha\_\_) to avoid unwanted + macro replacement. +* The template is expanded at the point where it is invoked. A macro is + expanded immediately at its point of declaration. This is subtle and + can cause a slight difference in behavior especially if you refer to + other macros and templates in the body. + +The empty brackets after the template identifier ([^alpha\[\]]) indicates no +arguments. If the template body does not look like a template argument list, we +can elide the empty brackets. Example: + +``` +[template aristotle_quote Aristotle: [*['Education is the best provision +for the journey to old age.]]] +``` + +[template aristotle_quote\ Aristotle: [*['Education is the best provision +for the journey to old age.]]] + +Expanding: + +``` +Here's a quote from [aristotle_quote]. +``` + +We have: + +Here's a quote from [aristotle_quote]. + +The disadvantage is that you can't avoid the space between the template +identifier, `aristotle_quote`, and the template body "Aristotle...". This space +will be part of the template body. If that space is unwanted, use empty +brackets or use the space escape: "`\ `". Example: + +``` +[template tag\ _tag] +``` + +[template tag\ _tag] + +Then expanding: + +``` +`struct` x[tag]; +``` + +We have: + +`struct` x[tag]; + +You have a couple of ways to do it. I personally prefer the explicit empty +brackets, though. + +[heading Simple Arguments] + +As mentioned, arguments are separated by the double dot [^".."]. Alternatively, +if the double dot isn't used and more than one argument is expected, QuickBook +uses whitespace to separate the arguments, following this logic: + +* Break the last argument into two, at the first space found ([^'', '\\n', + \\t' or '\\r']). +* Repeat until there are enough arguments or if there are no more spaces + found (in which case, an error is reported). + +For example: + +``` +[template simple[a b c d] [a][b][c][d]] +[simple w x y z] +``` + +will produce: + +[template simple[a b c d] [a][b][c][d]] +[simple w x y z] + +"w x y z" is initially treated as a single argument because we didn't +supply any [^".."] separators. However, since [^simple] expects 4 +arguments, "w x y z" is broken down iteratively (applying the logic above) +until we have "w", "x", "y" and "z". + +QuickBook only tries to get the arguments it needs. For example: + +``` +[simple w x y z trail] +``` + +will produce: + +[simple w x y z trail] + +The arguments being: "w", "x", "y" and "z trail". + +[caution The behavior described here is for QuickBook 1.5. In older versions you +could use both the double dot and whitespace as separators in the same template +call. If your document is marked up as an older version, it will use the old +behavior, which is described in the +[@http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments +QuickBook 1.4 documentation].] + +[heading Punctuation Templates] + +With templates, one of our objectives is to allow us to rewrite QuickBook +in QuickBook (as a qbk library). For that to happen, we need to accommodate +single character punctuation templates which are fairly common in +QuickBook. You might have noticed that single character punctuations are +allowed as [link quickbook.syntax.block.templates.template_identifier +template identifiers]. Example: + +``` +[template ![bar] <hey>[bar]</hey>] +``` + +Now, expanding this: + +``` +[!baz] +``` + +We will have: + +[pre +<hey>baz</hey> +] + +[endsect] [/Templates] + +[section Blurbs] + +``` +[blurb ``\:-)`` [*An eye catching advertisement or note...] + + __spirit__ is an object-oriented recursive-descent parser generator framework + implemented using template meta-programming techniques. Expression templates + allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) + completely in C++. +] +``` + +will generate this: + +[blurb :-) [*An eye catching advertisement or note...] + + __spirit__ is an object-oriented recursive-descent parser generator + framework implemented using template meta-programming techniques. Expression + templates allow us to approximate the syntax of Extended Backus-Normal Form + (EBNF) completely in C++. +] + +[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever +appropriate.] + +[endsect] [/Blurbs] + +[section Tables] + +``` +[table:id A Simple Table + [[Heading 1] [Heading 2] [Heading 3]] + [[R0-C0] [R0-C1] [R0-C2]] + [[R1-C0] [R1-C1] [R1-C2]] + [[R2-C0] [R2-C1] [R2-C2]] +] +``` + +will generate: + +[table:id A Simple Table + [[Heading 1] [Heading 2] [Heading 3]] + [[R0-C0] [R0-C1] [R0-C2]] + [[R1-C0] [R1-C1] [R1-C2]] + [[R2-C0] [R2-C1] [R2-C2]] +] + +The table title is optional. The first row of the table is automatically +treated as the table header; that is, it is wrapped in [^<thead>...</thead>] +XML tags. Note that unlike the original QuickDoc, the columns are nested in +[cells... ]. + +Giving tables an id is a new feature for quickbook 1.5 onwards. As with +sections, the id is optional. If the table has a title but no id, an id will +be generated from the title. The table above can be linked to using: + +``` +[link quickbook.syntax.block.tables.id link to table] +``` + +which will generate: + +[link quickbook.syntax.block.tables.id link to table] + +The syntax is free-format and allows big cells to be formatted +nicely. Example: + +``` +[table Table with fat cells + [[Heading 1] [Heading 2]] + [ + [Row 0, Col 0: a small cell] + [ + Row 0, Col 1: a big fat cell with paragraphs + + Boost provides free peer-reviewed portable C++ source libraries. + + We emphasize libraries that work well with the C++ Standard Library. + Boost libraries are intended to be widely useful, and usable across + a broad spectrum of applications. The Boost license encourages both + commercial and non-commercial use. + ] + ] + [ + [Row 1, Col 0: a small cell] + [Row 1, Col 1: a small cell] + ] +] +``` + +and thus: + +[table Table with fat cells + [[Heading 1] [Heading 2]] + [ + [Row 0, Col 0: a small cell] + [ + Row 0, Col 1: a big fat cell with paragraphs + + Boost provides free peer-reviewed portable C++ source libraries. + [/ <-- There's a space here. Don't remove. This is intentional, for testing] + We emphasize libraries that work well with the C++ Standard Library. + Boost libraries are intended to be widely useful, and usable across + a broad spectrum of applications. The Boost license encourages both + commercial and non-commercial use. + ] + ] + [ + [Row 1, Col 0: a small cell] + [Row 1, Col 1: a small cell] + ] +] + +Here's how to have preformatted blocks of code in a table cell: + +``` +[table Table with code + [[Comment] [Code]] + [ + [My first program] + [``\`\`\ `` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + ``\`\`\ ``] + ] +] +``` + +[table Table with code + [[Comment] [Code]] + [ + [My first program] + [`` + #include <iostream> + + int main() + { + std::cout << "Hello, World!" << std::endl; + return 0; + } + ``] + ] +] + +[endsect] [/Tables] + +[section Variable Lists] + +``` +[variablelist A Variable List + [[term 1] [The definition of term 1]] + [[term 2] [The definition of term 2]] + [[term 3] [ + The definition of term 3. + + Definitions may contain paragraphs. + ]] +] +``` + +will generate: + +[variablelist A Variable List + [[term 1] [The definition of term 1]] + [[term 2] [The definition of term 2]] + [[term 3] [ + The definition of term 3. + + Definitions may contain paragraphs. + ]] +] + +The rules for variable lists are the same as for tables, except that +only 2 "columns" are allowed. The first column contains the terms, and +the second column contains the definitions. Those familiar with HTML +will recognize this as a "definition list". + +[endsect] [/Variable Lists] + +[section Include] + +You can include one QuickBook file from another. The syntax is simply: + +``` +[include someother.qbk] +``` + +The included file will be processed as if it had been cut and pasted +into the current document, with the following exceptions: + +* The '''__FILENAME__''' predefined macro will reflect the name of the + file currently being processed. +* Any macros defined in the included file are scoped to that file. + +The [^\[include\]] directive lets you specify a document id to use for the +included file. When this id is not explicitly specified, the id defaults to +the filename ("someother", in the example above). You can specify the id +like this: + +``` +[include:someid someother.qbk] +``` + +All auto-generated anchors will use the document id as a unique prefix. So +for instance, if there is a top section in someother.qbk named "Intro", the +named anchor for that section will be "someid.intro", and you can link to +it with [^\[link someid.intro The Intro\]]. + +[endsect] [/Include] + +[section Import] + +When documenting code, you'd surely need to present code from actual source +files. While it is possible to copy some code and paste them in your QuickBook +file, doing so is error prone and the extracted code in the documentation tends +to get out of sync with the actual code as the code evolves. The problem, as +always, is that once documentation is written, the tendency is for the docs to +languish in the archives without maintenance. + +QuickBook's import facility provides a nice solution. + +[heading Example] + +You can effortlessly import code snippets from source code into your QuickBook. +The following illustrates how this is done: + +``` +[import ../test/stub.cpp] +[foo] +[bar] +``` + +The first line: + +``` +[import ../test/stub.cpp] +``` + +collects specially marked-up code snippets from +[@boost:/tools/quickbook/test/stub.cpp stub.cpp] +and places them in your QuickBook file as virtual templates. Each of the +specially marked-up code snippets has a name (e.g. `foo` and `bar` in the +example above). This shall be the template identifier for that particular code +snippet. The second and third line above does the actual template expansion: + +``` +[foo] +[bar] +``` + +And the result is: + +[import ../test/stub.cpp] +[foo] +[bar] + +[heading Code Snippet Markup] + +Note how the code snippets in [@boost:/tools/quickbook/test/stub.cpp stub.cpp] +get marked up. We use distinguishable comments following the form: + + //[id + some code here + //] + +The first comment line above initiates a named code-snippet. This prefix will +not be visible in quickbook. The entire code-snippet in between `//[id` and +`//]` will be inserted as a template in quickbook with name ['/id/]. The comment +`//]` ends a code-snippet This too will not be visible in quickbook. + +[heading Special Comments] + +Special comments of the form: + + //` some [*quickbook] markup here + +and: + + /*` some [*quickbook] markup here */ + +will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections, +paragraphs, tables, etc). In the first case, the initial slash-slash, tick and +white-space shall be ignored. In the second, the initial slash-star-tick and the +final star-slash shall be ignored. + +Special comments of the form: + + /*<- this C++ comment will be ignored ->*/ + +or + + /*<-*/ "this c++ code will be ignored" /*->*/ + +or + + //<- + private: + int some_member; + //-> + +can be used to inhibit code from passing through to quickbook. All text between +the delimeters will simply be ignored. + +Comments of this form: + + //=int main() {} + +or + + /*=foo()*/ + +will be displayed as code that isn't in comments. This allows you to +include some code in the snippet but not actually use it when +compiling your example. + +[heading Callouts] + +Special comments of the form: + + /*< some [*quickbook] markup here >*/ + +will be regarded as callouts. These will be collected, numbered and +rendered as a "callout bug" (a small icon with a number). After the +whole snippet is parsed, the callout list is generated. See +[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details. +Example: + +[foo_bar] + +This is the actual code: + + //[ foo_bar + std::string foo_bar() /*< The /Mythical/ FooBar. + See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/ + { + return "foo-bar"; /*< return 'em, foo-bar man! >*/ + } + //] + +The callouts bugs are placed exactly where the special callout comment +is situated. It can be anywhere in the code. The bugs can be rather +obtrusive, however. They get in the way of the clarity of the code. +Another special callout comment style is available: + + /*<< some [*quickbook] markup here >>*/ + +This is the line-oriented version of the callout. With this, the "bug" +is placed at the very left of the code block, away from the actual code. +By placing it at the far left, the code is rendered un-obscured. +Example: + +[class_] + +See the actual code here: [@boost:/tools/quickbook/test/stub.cpp] + +[endsect] [/Import] |