From 3cbbb6bf2fa03b4dcd6bce604a359623da86b676 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Sat, 13 Oct 2007 23:18:35 +0000 Subject: [PATCH] Merge with the offending files removed. [SVN r39995] --- block.hpp | 2 +- code_snippet.hpp | 5 +- detail/markups.hpp | 20 +- doc/html/index.html | 2 +- doc/html/quickbook/editors/kde_support.html | 38 +- doc/html/quickbook/faq.html | 2 +- doc/html/quickbook/ref.html | 2 +- doc/html/quickbook/syntax/block.html | 170 +- doc/html/quickbook/syntax/phrase.html | 88 +- doc/quickbook.qbk | 10 +- test/code-block-1.gold | 2 +- test/code-block-2.gold | 2 +- test/import.gold | 2 +- test/preformatted.gold | 2 +- test/quickbook-manual.gold | 5024 ++++++++++--------- test/templates.gold | 2 +- 16 files changed, 2656 insertions(+), 2717 deletions(-) diff --git a/block.hpp b/block.hpp index 5a70ea9..aba5489 100644 --- a/block.hpp +++ b/block.hpp @@ -386,7 +386,7 @@ namespace quickbook ; paragraph_end = - '[' >> space >> paragraph_end_markups | eol >> eol + '[' >> space >> paragraph_end_markups >> hard_space | eol >> eol ; paragraph = diff --git a/code_snippet.hpp b/code_snippet.hpp index 89dc64d..44d1cb2 100644 --- a/code_snippet.hpp +++ b/code_snippet.hpp @@ -72,7 +72,10 @@ namespace quickbook *blank_p >> "//<-" >> (*(anychar_p - "//->")) >> "//->" >> *blank_p >> eol_p - | "/*<-" + | "/*<-*/" + >> (*(anychar_p - "/*->*/")) + >> "/*->*/" + | "/*<-" >> (*(anychar_p - "->*/")) >> "->*/" ; diff --git a/detail/markups.hpp b/detail/markups.hpp index 809af74..0038948 100644 --- a/detail/markups.hpp +++ b/detail/markups.hpp @@ -35,16 +35,16 @@ namespace quickbook { namespace /*unnamed*/ const char* blockquote_post = ""; const char* preformatted_pre = ""; const char* preformatted_post = ""; - const char* warning_pre = ""; - const char* warning_post = ""; - const char* caution_pre = ""; - const char* caution_post = ""; - const char* important_pre = ""; - const char* important_post = ""; - const char* note_pre = ""; - const char* note_post = ""; - const char* tip_pre = ""; - const char* tip_post = ""; + const char* warning_pre = ""; + const char* warning_post = ""; + const char* caution_pre = ""; + const char* caution_post = ""; + const char* important_pre = ""; + const char* important_post = ""; + const char* note_pre = ""; + const char* note_post = ""; + const char* tip_pre = ""; + const char* tip_post = ""; const char* list_item_pre = "\n"; const char* list_item_post = "\n"; const char* bold_pre_ = ""; diff --git a/doc/html/index.html b/doc/html/index.html index 5746432..c115c5c 100755 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -70,7 +70,7 @@ - +

Last revised: August 01, 2007 at 23:43:11 GMT

Last revised: September 24, 2007 at 06:00:48 GMT
diff --git a/doc/html/quickbook/editors/kde_support.html b/doc/html/quickbook/editors/kde_support.html index 00a161b..13f91f7 100644 --- a/doc/html/quickbook/editors/kde_support.html +++ b/doc/html/quickbook/editors/kde_support.html @@ -26,7 +26,7 @@

KDE Support

- + boost::hs::quickbook

@@ -51,7 +51,7 @@ html generated from this .qbk file

-

Table 7. Code examples

+

Table 7. Code examples

@@ -140,7 +140,7 @@

- + Code Folding

@@ -150,7 +150,7 @@ region can be folded or unfolded independently.

- + Auto Comment / Uncomment

@@ -161,7 +161,7 @@ while being in it.

- + Styles reference

@@ -398,7 +398,7 @@

- + About boost::hs

@@ -414,18 +414,12 @@ [Note] Note - -

-

-

- boost::hs::cpp support QuickBook code import comments style! -

-

-

- +

+ boost::hs::cpp support QuickBook code import comments style! +

- + Installing boost::hs

@@ -442,15 +436,9 @@ [Note] Note - -

-

-

- A copy of boost::hs::quickbook and boost::hs::cpp is available in boost/tools/quickbook/extra/katepart. -

-

-

- +

+ A copy of boost::hs::quickbook and boost::hs::cpp is available in boost/tools/quickbook/extra/katepart. +

In order to install it you must copy the content in the folder katepart/syntax/ to the appropriate katepart syntax diff --git a/doc/html/quickbook/faq.html b/doc/html/quickbook/faq.html index 475e161..a5fc1e2 100644 --- a/doc/html/quickbook/faq.html +++ b/doc/html/quickbook/faq.html @@ -26,7 +26,7 @@

Frequently Asked Questions

- + Can I use QuickBook for non-Boost documentation?

diff --git a/doc/html/quickbook/ref.html b/doc/html/quickbook/ref.html index 9b03033..9daaf66 100755 --- a/doc/html/quickbook/ref.html +++ b/doc/html/quickbook/ref.html @@ -28,7 +28,7 @@ [cpp]

-

Table 8. Syntax Compendium

+

Table 8. Syntax Compendium

diff --git a/doc/html/quickbook/syntax/block.html b/doc/html/quickbook/syntax/block.html index 1c08129..b1ef961 100644 --- a/doc/html/quickbook/syntax/block.html +++ b/doc/html/quickbook/syntax/block.html @@ -587,75 +587,45 @@ - +
[Note] Note
-

-

-

- This is a note -

-

-

-

+ This is a note +

- +
[Tip] Tip
-

-

-

- This is a tip -

-

-

-

+ This is a tip +

- +
[Important] Important
-

-

-

- This is important -

-

-

-

+ This is important +

- +
[Caution] Caution
-

-

-

- This is a caution -

-

-

-

+ This is a caution +

- +
[Warning] Warning
-

-

-

- This is a warning -

-

-

-

+ This is a warning +

These are the only admonitions supported by DocBook. @@ -674,27 +644,27 @@ [h6 Heading 6]

- + Heading 1

- + Heading 2

- + Heading 3

- + Heading 4

- + Heading 5
- + Heading 6

@@ -787,18 +757,12 @@ sf_logo [Tip] 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. -

-

-

- +

+ 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) @@ -838,7 +802,7 @@ sf_logo Quickbook has some predefined macros that you can already use.

-

Table 3. Predefined Macros

+

Table 3. Predefined Macros

@@ -876,7 +840,7 @@ sf_logo @@ -893,7 +857,7 @@ sf_logo @@ -939,7 +903,7 @@ Hi, my name is [name]. I am [age] years old. I am a [what]. ]
- + Template Identifier
@@ -957,7 +921,7 @@ Hi, my name is [name]. I am [age] years old. I am a [what].
- + Formal Template Arguments
@@ -977,7 +941,7 @@ Hi, my name is [name]. I am [age] years old. I am a [what]. of the template call.

- + Template Body
@@ -1002,7 +966,7 @@ replacement text... block level elements are not allowed in phrase templates.

- + Template Expansion
@@ -1038,19 +1002,13 @@ replacement text... - +

- 2007-Aug-02 + 2007-Sep-24

- 07:43:11 AM + 02:00:48 PM

[Caution] 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. -

-

-

-

+ 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 @@ -1059,7 +1017,7 @@ replacement text... by the close parenthesis.

- + Nullary Templates
@@ -1142,7 +1100,7 @@ for the journey to old age.]]] brackets, though.

- + Simple Arguments
@@ -1210,7 +1168,7 @@ for the journey to old age.]]] what do you think man?

- + Punctuation Templates
@@ -1266,16 +1224,10 @@ for the journey to old age.]]] [Note] Note - -

-

-

- Prefer admonitions - wherever appropriate. -

-

-

- +

+ Prefer admonitions + wherever appropriate. +

@@ -1292,7 +1244,7 @@ for the journey to old age.]]] will generate:

-

Table 4. A Simple Table

+

Table 4. A Simple Table

@@ -1403,7 +1355,7 @@ for the journey to old age.]]] and thus:

-

Table 5. Table with fat cells

+

Table 5. Table with fat cells

@@ -1478,7 +1430,7 @@ for the journey to old age.]]] ]
-

Table 6. Table with code

+

Table 6. Table with code

@@ -1618,7 +1570,7 @@ for the journey to old age.]]] QuickBook's import facility provides a nice solution.

- + Example

@@ -1724,7 +1676,7 @@ for the journey to old age.]]]

- + Code Snippet Markup
@@ -1745,7 +1697,7 @@ for the journey to old age.]]] This too will not be visible in quickbook.

- + Special Comments
@@ -1771,23 +1723,29 @@ for the journey to old age.]]] Special comments of the form: 

-/*<-- this will be ignored -->*/
+/*<- 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.

- + Callouts

diff --git a/doc/html/quickbook/syntax/phrase.html b/doc/html/quickbook/syntax/phrase.html index 0c0ce98..74e4d8b 100644 --- a/doc/html/quickbook/syntax/phrase.html +++ b/doc/html/quickbook/syntax/phrase.html @@ -412,17 +412,11 @@ And one for the little boy who lives down the lane.

- +
[Note] Note
-

-

-

- We simply enclose the code with the tick: "`", not - the single quote: "'". - Note too that `some code` is preferred over [^some code]. -

-

-

-

+ We simply enclose the code with the tick: "`", not the + single quote: "'". + Note too that `some code` is preferred over [^some code]. +

@@ -501,7 +495,7 @@ C++ comment `// looks like this` whereas a Python comment [python] whereas a Python comment #looks like this.

-

Table 2. Supported Source Modes

+

Table 2. Supported Source Modes

@@ -552,15 +546,9 @@ C++ comment `// looks like this` whereas a Python comment [python] - +
[Note] Note
-

-

-

- The source mode strings are lowercase. -

-

-

-

+ The source mode strings are lowercase. +

@@ -573,18 +561,12 @@ C++ comment `// looks like this` whereas a Python comment [python] [Warning] Warning - -

-

-

- [br] is now deprecated. Blurbs, - Admonitions - and table cells (see Tables) - may now contain paragraphs. -

-

-

- +

+ [br] is now deprecated. Blurbs, + Admonitions + and table cells (see Tables) + may now contain paragraphs. +

@@ -717,15 +699,9 @@ escape (no processing/formatting) [Important] Important - -

-

-

- Be careful when using the escape. The text must conform to BoostBook/DocBook syntax. -

-

-

- +

+ Be careful when using the escape. The text must conform to BoostBook/DocBook syntax. +

@@ -748,19 +724,13 @@ escape (no processing/formatting) [Warning] Warning - -

-

-

- \n - and [br] are now deprecated. Blurbs, - Admonitions - and table cells (see Tables) - may now contain paragraphs. -

-

-

- +

+ \n + and [br] are now deprecated. Blurbs, + Admonitions + and table cells (see Tables) + may now contain paragraphs. +

The escaped space: \ also @@ -791,7 +761,7 @@ escape (no processing/formatting)

will generate this - [2] + [2] .

@@ -844,7 +814,7 @@ escape (no processing/formatting)

Yes! - [3] + [3]

@@ -856,10 +826,10 @@ escape (no processing/formatting) being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity.

-

[2] +

[2] A sample footnote

-

[3] +

[3] Conditional Generation makes quickbook turing complete.

diff --git a/doc/quickbook.qbk b/doc/quickbook.qbk index 0ad3039..df8052a 100755 --- a/doc/quickbook.qbk +++ b/doc/quickbook.qbk @@ -1705,14 +1705,18 @@ final star-slash shall be ignored. Special comments of the form: - /*<-- this will be ignored -->*/ + /*<- 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. diff --git a/test/code-block-1.gold b/test/code-block-1.gold index 878f6b3..6db940a 100644 --- a/test/code-block-1.gold +++ b/test/code-block-1.gold @@ -10,7 +10,7 @@ A code block with proper indentation ;-) - + #include <iostream> diff --git a/test/code-block-2.gold b/test/code-block-2.gold index b0fbc45..aa3facf 100644 --- a/test/code-block-2.gold +++ b/test/code-block-2.gold @@ -11,7 +11,7 @@ A code block with proper indentation ;-) - + #include <iostream> diff --git a/test/import.gold b/test/import.gold index 0facb60..87988a6 100644 --- a/test/import.gold +++ b/test/import.gold @@ -24,7 +24,7 @@ And any quickbook block markup. - + std::string foo() { diff --git a/test/preformatted.gold b/test/preformatted.gold index f17ab76..30f9acb 100644 --- a/test/preformatted.gold +++ b/test/preformatted.gold @@ -10,7 +10,7 @@ Here's the ubiquitous Hello World program in C++. - + #include <iostream> int main() diff --git a/test/quickbook-manual.gold b/test/quickbook-manual.gold index c29060b..7c3cb4c 100644 --- a/test/quickbook-manual.gold +++ b/test/quickbook-manual.gold @@ -609,11 +609,9 @@ And one for the little boy who lives down the lane. - - We simply enclose the code with the tick: "`", not - the single quote: "'". - Note too that `some code` is preferred over [^some code]. - + We simply enclose the code with the tick: "`", not the + single quote: "'". + Note too that `some code` is preferred over [^some code]. @@ -731,9 +729,7 @@ C++ comment `// looks like this` whereas a Python comment [python] - - The source mode strings are lowercase. - + The source mode strings are lowercase. @@ -751,98 +747,98 @@ C++ comment `// looks like this` whereas a Python comment [python] and table cells (see Tables) may now contain paragraphs. - - - -
- <link linkend="quickbook.syntax.phrase.anchors">Anchors</link> - + +
+
+ <link linkend="quickbook.syntax.phrase.anchors">Anchors</link> + [#named_anchor] - - A named anchor is a hook that can be referenced by a link elsewhere in - the document. You can then reference an anchor with [link named_anchor + + A named anchor is a hook that can be referenced by a link elsewhere in + the document. You can then reference an anchor with [link named_anchor Some link text]. - See Anchor links, - Section and Heading. - -
- + - + - + - + -
- <link linkend="quickbook.syntax.phrase.escape">Escape</link> - - The escape mark-up is used when we don't want to do any processing. - - + + would have "boost::bar::baz" as the link text. + +
+
+ <link linkend="quickbook.syntax.phrase.escape">Escape</link> + + The escape mark-up is used when we don't want to do any processing. + + ''' escape (no processing/formatting) ''' - - Escaping allows us to pass XML markup to BoostBook - or DocBook. For example: - - + + Escaping allows us to pass XML markup to BoostBook + or DocBook. For example: + + ''' <emphasis role="bold">This is direct XML markup</emphasis> ''' - - This is direct XML markup - - + This is direct XML markup + + Be careful when using the escape. The text must conform to BoostBook/DocBook syntax. - - -
-
- <link linkend="quickbook.syntax.phrase.single_char_escape">Single - char escape</link> - - The backslash may be used to escape a single punctuation character. The - punctuation immediately after the backslash is passed without any processing. - This is useful when we need to escape QuickBook punctuations such as [ and ]. - For example, how do you escape the triple quote? Simple: \'\'\' - - - \n - has a special meaning. It is used to generate line breaks. - - + +
+
+ <link linkend="quickbook.syntax.phrase.single_char_escape">Single + char escape</link> - - \n - and [br] are now deprecated. Blurbs, - Admonitions - and table cells (see Tables) - may now contain paragraphs. - + The backslash may be used to escape a single punctuation character. The + punctuation immediately after the backslash is passed without any processing. + This is useful when we need to escape QuickBook punctuations such as + [ and ]. + For example, how do you escape the triple quote? Simple: \'\'\' - - - The escaped space: \ also - has a special meaning. The escaped space is removed from the output. - -
-
- <link linkend="quickbook.syntax.phrase.images">Images</link> - + + \n + has a special meaning. It is used to generate line breaks. + + + + + \n + and [br] are now deprecated. Blurbs, + Admonitions + and table cells (see Tables) + may now contain paragraphs. + + + + The escaped space: \ + also has a special meaning. The escaped space is removed from the output. + +
+
+ <link linkend="quickbook.syntax.phrase.images">Images</link> + [$image.jpg] -
-
- <link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link> - - As of version 1.3, QuickBook supports footnotes. Just put the text of the - footnote in a [footnote] block, and the text will be put at the - bottom of the current page. For example, this: - - +
+
+ <link linkend="quickbook.syntax.phrase.footnotes">Footnotes</link> + + As of version 1.3, QuickBook supports footnotes. Just put the text + of the footnote in a [footnote] + block, and the text will be put at the bottom of the current page. + For example, this: + + [footnote A sample footnote] - - will generate this - - A sample footnote + will generate this + + + A sample footnote + + + . - - . - -
- <link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro - Expansion</link> +
+ <link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro + Expansion</link> __a_macro_identifier__ - - See Macros for details. - -
-
- <link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template - Expansion</link> + + See Macros for + details. + +
+
+ <link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template + Expansion</link> [a_template_identifier] - - See Templates - for details. - + + See Templates + for details. + +
+
- - -
- <link linkend="quickbook.syntax.block"> Block Level Elements</link> -
- <link linkend="quickbook.syntax.block.document">Document</link> - - Every document must begin with a Document Info section, which should look - like this: - - +
+ <link linkend="quickbook.syntax.block"> Block Level Elements</link> +
+ <link linkend="quickbook.syntax.block.document">Document</link> + + Every document must begin with a Document Info section, which should + look like this: + + [document-type The Document Title [quickbook 1.3] [version 1.0] @@ -994,142 +989,143 @@ escape (no processing/formatting) [source-mode source-type] ] - - Where document-type is one of: - - - - book - - - article - - - library - - - chapter - - - part - - - appendix - - - preface - - - qandadiv - - - qandaset - - - reference - - - set - - - - quickbook 1.3 declares the version of quickbook the document is written - for. In its absence, version 1.1 is assumed. - - - version, id, dirname, - copyright, purpose, category, - authors, license, last-revision - and source-mode are optional information. - - - source-type is a lowercase string setting the initial - Source Mode. - If the source-mode field is omitted, a default value - of c++ will be used. - -
-
- <link linkend="quickbook.syntax.block.section">Section</link> - - Starting a new section is accomplished with: - - + + Where document-type is one of: + + + + book + + + article + + + library + + + chapter + + + part + + + appendix + + + preface + + + qandadiv + + + qandaset + + + reference + + + set + + + + quickbook 1.3 declares the version of quickbook the document is written + for. In its absence, version 1.1 is assumed. + + + version, id, dirname, + copyright, purpose, category, + authors, license, last-revision + and source-mode are optional information. + + + source-type is a lowercase string setting the initial + Source Mode. + If the source-mode field is omitted, a default value + of c++ will be used. + +
+
+ <link linkend="quickbook.syntax.block.section">Section</link> + + Starting a new section is accomplished with: + + [section:id The Section Title] - - where id is optional. id will be the filename of the - generated section. If it is not present, "The Section Title" - will be normalized and become the id. 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. Thus: "The Section Title" will be - normalized to "the_section_title". - - - End a section with: - - + + where id is optional. id will be the filename + of the generated section. If it is not present, "The Section Title" + will be normalized and become the id. 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. Thus: "The Section Title" will + be normalized to "the_section_title". + + + End a section with: + + [endsect] - - Sections can nest, and that results in a hierarchy in the table of contents. - -
-
- <link linkend="quickbook.syntax.block.xinclude">xinclude</link> - - You can include another XML file with: - - + + Sections can nest, and that results in a hierarchy in the table of + contents. + +
+
+ <link linkend="quickbook.syntax.block.xinclude">xinclude</link> + + 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. - -
-
- <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link> - - 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. - -
-
- <link linkend="quickbook.syntax.block.lists">Lists</link> -
- <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered - lists</link> + + This is useful when file.xml has been generated by Doxygen and contains + your reference section. + +
+
+ <link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link> + + 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. + +
+
+ <link linkend="quickbook.syntax.block.lists">Lists</link> +
+ <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered + lists</link> # One # Two # Three - - will generate: - - - - One - - - Two - - - Three - - -
-
- <link linkend="quickbook.syntax.block.lists.list_hierarchies">List - Hierarchies</link> - - List hierarchies are supported. Example: - - + + will generate: + + + + One + + + Two + + + Three + + +
+
+ <link linkend="quickbook.syntax.block.lists.list_hierarchies">List + Hierarchies</link> + + List hierarchies are supported. Example: + + # One # Two # Three @@ -1142,58 +1138,58 @@ escape (no processing/formatting) # Four.a.ii # Five - - will generate: - - - - One - - - Two - - - Three + + will generate: + - Three.a + One - Three.b + Two - Three.c - - - - - Fourth - - - Four.a + Three - Four.a.i + Three.a - Four.a.ii + Three.b + + + Three.c + + Fourth + + + Four.a + + + Four.a.i + + + Four.a.ii + + + + + + + Five + - - - Five - - -
-
- <link linkend="quickbook.syntax.block.lists.long_list_lines">Long - List Lines</link> - - Long lines will be wrapped appropriately. Example: - - +
+
+ <link linkend="quickbook.syntax.block.lists.long_list_lines">Long + List Lines</link> + + Long lines will be wrapped appropriately. Example: + + # 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. @@ -1202,49 +1198,51 @@ escape (no processing/formatting) 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. - - -
-
- <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered - lists</link> + + + 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. + + +
+
+ <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered + lists</link> * First * Second * Third - - will generate: - - - - First - - - Second - - - Third - - -
-
- <link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed lists</link> - - Mixed lists (ordered and unordered) are supported. Example: - - + + will generate: + + + + First + + + Second + + + Third + + +
+
+ <link linkend="quickbook.syntax.block.lists.mixed_lists">Mixed + lists</link> + + Mixed lists (ordered and unordered) are supported. Example: + + # One # Two # Three @@ -1253,38 +1251,38 @@ escape (no processing/formatting) * Three.c # Four - - will generate: - - - - One - - - Two - - - Three - + + will generate: + + - Three.a + One - Three.b + Two - Three.c + Three + + + Three.a + + + Three.b + + + Three.c + + - - - - Four - - - - And... - - + + Four + + + + And... + + # 1 * 1.a # 1.a.1 @@ -1298,69 +1296,69 @@ escape (no processing/formatting) * 2.b.2.a * 2.b.2.b - - will generate: - - - - 1 - + + will generate: + + - 1.a - + 1 + - 1.a.1 - - - 1.a.2 - - - - - 1.b - - - - - 2 - - - 2.a - - - 2.b - - - 2.b.1 - - - 2.b.2 - + 1.a + - 2.b.2.a + 1.a.1 - 2.b.2.b + 1.a.2 - + - + + 1.b + + - - - -
-
-
- <link linkend="quickbook.syntax.block.code">Code</link> - - Preformatted code starts with a space or a tab. The code will be syntax - highlighted according to the current Source - Mode: - - - - + + 2 + + + 2.a + + + 2.b + + + 2.b.1 + + + 2.b.2 + + + 2.b.2.a + + + 2.b.2.b + + + + + + + + +
+
+
+ <link linkend="quickbook.syntax.block.code">Code</link> + + Preformatted code starts with a space or a tab. The code will be syntax + highlighted according to the current Source + Mode: + + + + #include <iostream> @@ -1371,9 +1369,9 @@ escape (no processing/formatting) return 0; } - - - + + + import cgi @@ -1382,62 +1380,62 @@ escape (no processing/formatting) return cgi.escape(text) - - - - Macros that are already defined are expanded in source code. Example: - - + + + + 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: - - + + Generates: + + using boost::array; -
-
- <link linkend="quickbook.syntax.block.escape_back"> Escaping Back - To QuickBook</link> - - 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: - - +
+
+ <link linkend="quickbook.syntax.block.escape_back"> Escaping Back + To QuickBook</link> + + 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: - - + + Will generate: + + void foo() { } - - When escaping from code to QuickBook, only phrase level markups are allowed. - Block level markups like lists, tables etc. are not allowed. - -
-
- <link linkend="quickbook.syntax.block.preformatted">Preformatted</link> - - Sometimes, you don't want some preformatted text to be parsed as C++. In - such cases, use the [pre ... ] markup block. - - + + When escaping from code to QuickBook, only phrase level markups are + allowed. Block level markups like lists, tables etc. are not allowed. + +
+
+ <link linkend="quickbook.syntax.block.preformatted">Preformatted</link> + + Sometimes, you don't want some preformatted text to be parsed as C++. + In such cases, use the [pre ... ] markup block. + + [pre Some *preformatted* text Some *preformatted* text @@ -1448,12 +1446,12 @@ escape (no processing/formatting) ] - - 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: - - + + 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: + + Some preformatted text Some preformatted text Some preformatted text Some preformatted text @@ -1461,80 +1459,71 @@ escape (no processing/formatting) Some preformatted text Some preformatted text - - Notice that unlike Code, phrase markup such as font style is still permitted - inside pre blocks. - -
-
- <link linkend="quickbook.syntax.block.blockquote">Blockquote</link> - + + Notice that unlike Code, phrase markup such as font style is still + permitted inside pre blocks. + +
+
+ <link linkend="quickbook.syntax.block.blockquote">Blockquote</link> + [:sometext...] -
- - - Indents the paragraph. This applies to one paragraph only. - - -
-
-
- <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> - +
+ + + Indents the paragraph. This applies to one paragraph only. + + +
+
+
+ <link linkend="quickbook.syntax.block.admonitions">Admonitions</link> + [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: - - - - This is a note + generates DocBook admonitions: - - - - - - This is a tip - - - - - - - This is important - - - - - - - This is a caution - - - - - - - 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. - -
-
- <link linkend="quickbook.syntax.block.headings">Headings</link> - + + + This is a note + + + + + This is a tip + + + + + This is important + + + + + This is a caution + + + + + + 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. + +
+
+ <link linkend="quickbook.syntax.block.headings">Headings</link> + [h1 Heading 1] [h2 Heading 2] [h3 Heading 3] @@ -1542,568 +1531,577 @@ escape (no processing/formatting) [h5 Heading 5] [h6 Heading 6] - - - Heading 1 - - - - Heading 2 - - - - Heading 3 - - - - Heading 4 - - - - Heading 5 - - - - Heading 6 - - - Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized - names with name="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: - - + + + Heading + 1 + + + + Heading + 2 + + + + Heading + 3 + + + + Heading + 4 + + + + Heading + 5 + + + + Heading + 6 + + + Headings 1-3 [h1 h2 and h3] will automatically have anchors with + normalized names with name="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 section_id.normalized_header_text The link text] - - to link to them. See Anchor - links and Section - for more info. - -
-
- <link linkend="quickbook.syntax.block.generic_heading">Generic Heading</link> - - In cases when you don't want to care about the heading level (1 to 6), - you can use the Generic Heading: - - + + to link to them. See Anchor + links and Section + for more info. + +
+
+ <link linkend="quickbook.syntax.block.generic_heading">Generic + Heading</link> + + 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: - - + + 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: - - + + 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. - -
-
- <link linkend="quickbook.syntax.block.macros">Macros</link> - + + 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. + +
+
+ <link linkend="quickbook.syntax.block.macros">Macros</link> + [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: - - + + 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. - - - - - sflogo - - - - - - - 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: - - + + Now everywhere the sf_logo is placed, the picture will be inlined. + + + + + sflogo + + + + + + 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: - - + + (See Images + and Links) + + + Invoking these macros: + + Hi __spirit__ :-) - - will generate this: - - - Hi Spirit - - smiley - - - -
-
- <link linkend="quickbook.syntax.block.predefined_macros">Predefined - Macros</link> - - Quickbook has some predefined macros that you can already use. - - Predefined Macros - - - - - Macro + will generate this: - - Meaning + Hi Spirit + + smiley + + - + +
+ <link linkend="quickbook.syntax.block.predefined_macros">Predefined + Macros</link> - Example + Quickbook has some predefined macros that you can already use. - - -
- - - +
Predefined Macros + + + + + + Macro + + + + Meaning + + + + Example + + + + + + + + + __DATE__ + + + + Today's date + + + + 2000-Dec-20 + + + + + + + __TIME__ + + + + The current time + + + + 12:00:00 PM + + + + + + + __FILENAME__ + + + + Quickbook source filename + + + + NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE + + + + + +
+
+
+ <link linkend="quickbook.syntax.block.templates">Templates</link> - __DATE__ + 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). - - Today's date + Example template: - - - 2000-Dec-20 - - - - - - - __TIME__ - - - - The current time - - - - 12:00:00 PM - - - - - - - __FILENAME__ - - - - Quickbook source filename - - - - NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE - - - - - - -
-
- <link linkend="quickbook.syntax.block.templates">Templates</link> - - 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 - 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) - - - - - 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 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. - - - - 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 + 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) + + + + + 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 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. + + + + 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: - - + + 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. - - - - Template - Expansion - - - You expand a template this way: - - + + 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. + + + + 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: - - + + 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: - - - - Hi, my name is James Bond. I am 39 years old. I am a Spy. - - - Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso. - - - - - - 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 - QuickBook phrase. Arguments - are separated by the double dot ".." and terminated - by the close parenthesis. - - - - Nullary - Templates - - - Nullary templates look and act like simple macros. Example: - - + + Which will expand to: + + + + Hi, my name is James Bond. I am 39 years old. I am a Spy. + + + Hi, my name is Santa Clause. I am 87 years old. I am a Big Red + Fatso. + + + + + 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 QuickBook phrase. + Arguments are separated by the double dot ".." + and terminated by the close parenthesis. + + + + Nullary + Templates + + + Nullary templates look and act like simple macros. Example: + + [template alpha[]'''&#945;'''] [template beta[]'''&#946;'''] - - Expanding: - - + + Expanding: + + Some squigles...[*[alpha][beta]] - - We have: - - - Some squiggles...αβ - - - The difference with macros are - - - - The explicit 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: - - + + We have: + + + Some squiggles...αβ + + + The difference with macros are + + + + The explicit 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.]]] - - Expanding: - - + + Expanding: + + Here's a quote from [aristotle_quote]. - - We have: - - - Here's a quote from Aristotle: Education - is the best provision for the journey to old age.. - - - 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: - - + + We have: + + + Here's a quote from Aristotle: Education + is the best provision for the journey to old age.. + + + 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] - - Then expanding: - - + + 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. - - - - Simple - Arguments - - - As mentioned, arguments are separated by the double dot "..". - If there are less arguments passed than expected, QuickBook attempts to - break the last argument into two or more 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: - - + + We have: + + + struct x_tag; + + + You have a couple of ways to do it. I personally prefer the explicit + empty brackets, though. + + + + Simple + Arguments + + + As mentioned, arguments are separated by the double dot "..". + If there are less arguments passed than expected, QuickBook attempts + to break the last argument into two or more 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: - - - wxyz - - - "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: - - + + will produce: + + + wxyz + + + "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: - - - wxyz trail - - - The arguments being: "w", "x", "y" and "z - trail". - - - It should be obvious now that for simple arguments with no spaces, we can - get by without separating the arguments with ".." - separators. It is possible to combine ".." - separators with the argument passing simplification presented above. Example: - - + + will produce: + + + wxyz trail + + + The arguments being: "w", "x", "y" + and "z trail". + + + It should be obvious now that for simple arguments with no spaces, + we can get by without separating the arguments with ".." + separators. It is possible to combine ".." + separators with the argument passing simplification presented above. + Example: + + [simple what do you think ..m a n?] - - will produce: - - - what do you think man? - - - - 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 - template - identifiers. Example: - - + + will produce: + + + what do you think man? + + + + 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 template + identifiers. Example: + + [template ![bar] <hey>[bar]</hey>] - - Now, expanding this: - - + + Now, expanding this: + + [!baz] - - We will have: - - + + We will have: + + <hey>baz</hey> -
-
- <link linkend="quickbook.syntax.block.blurbs">Blurbs</link> - +
+
+ <link linkend="quickbook.syntax.block.blurbs">Blurbs</link> + [blurb :-) [*An eye catching advertisement or note...] __spirit__ is an object-oriented recursive-descent parser generator framework @@ -2112,37 +2110,35 @@ for the journey to old age.]]] completely in C++. ] - - will generate this: - - - - - - smiley - - 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++. - - - - - - Prefer admonitions - wherever appropriate. - - - -
-
- <link linkend="quickbook.syntax.block.tables">Tables</link> - + + will generate this: + + + + + + smiley + + 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++. + + + + + Prefer admonitions + wherever appropriate. + + +
+
+ <link linkend="quickbook.syntax.block.tables">Tables</link> + [table A Simple Table [[Heading 1] [Heading 2] [Heading 3]] [[R0-C0] [R0-C1] [R0-C2]] @@ -2150,85 +2146,85 @@ for the journey to old age.]]] [[R2-C0] [R2-C1] [R2-C2]] ] - - will generate: - - A Simple Table - - - - - Heading 1 + will generate: - +
A Simple Table + + + + + + Heading 1 + + + + Heading 2 + + + + Heading 3 + + + + + + + + + R0-C0 + + + + R0-C1 + + + + R0-C2 + + + + + + + R2-C0 + + + + R2-C1 + + + + R2-C2 + + + + + + + R3-C0 + + + + R3-C1 + + + + R3-C2 + + + + + +
- Heading 2 + 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... ]. The syntax is free-format and allows big + cells to be formatted nicely. Example: - - - Heading 3 - - - - - - - - - R0-C0 - - - - R0-C1 - - - - R0-C2 - - - - - - - R2-C0 - - - - R2-C1 - - - - R2-C2 - - - - - - - R3-C0 - - - - R3-C1 - - - - R3-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... ]. The syntax is free-format and allows big cells to be formatted - nicely. Example: - - + [table Table with fat cells [[Heading 1] [Heading 2]] [ @@ -2250,63 +2246,63 @@ for the journey to old age.]]] ] ] - - and thus: - - Table with fat cells - - - - - Heading 1 + and thus: - +
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 + + + + + +
- Heading 2 + Here's how to have preformatted blocks of code in a table cell: - - - - - - - - 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 - - - - - - - - Here's how to have preformatted blocks of code in a table cell: - - + [table Table with code [[Comment] [Code]] [ @@ -2323,30 +2319,30 @@ for the journey to old age.]]] ] ] - Table with code - - - - - - Comment - - - - Code - - - - - - - - - My first program - - - - +
Table with code + + + + + + Comment + + + + Code + + + + + + + + + My first program + + + + #include <iostream> @@ -2356,158 +2352,160 @@ for the journey to old age.]]] return 0; } - - - - - -
-
-
- <link linkend="quickbook.syntax.block.variable_lists">Variable Lists</link> - + + + + + + +
+
+ <link linkend="quickbook.syntax.block.variable_lists">Variable + Lists</link> [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]] ] - - will generate: - - - A Variable List term 1 - - - The definition of term 1 - - - term 2 - - - The definition of term 2 - - - term 3 - - - The definition of term 3 - - - - - - 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". - -
-
- <link linkend="quickbook.syntax.block.include">Include</link> - - You can include one QuickBook file from another. The syntax is simply: - - + + will generate: + + + A Variable List term 1 + + + The definition of term 1 + + + term 2 + + + The definition of term 2 + + + term 3 + + + The definition of term 3 + + + + + + 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". + +
+
+ <link linkend="quickbook.syntax.block.include">Include</link> + + 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: - - + + 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]. - -
-
- <link linkend="quickbook.syntax.block.import">Import</link> - - 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. - - - - Example - - - You can effortlessly import code snippets from source code into your QuickBook. - The following illustrates how this is done: - - + + 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]. + +
+
+ <link linkend="quickbook.syntax.block.import">Import</link> + + 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. + + + + 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: - - + + The first line: + + [import ../test/stub.cpp] - - collects specially marked-up code snippets from 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: - - + + collects specially marked-up code snippets from 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: - - - - This is the foo - function. - - - This description can have paragraphs... - - - - lists - - - etc. - - - - And any quickbook block markup. - - - + + And the result is: + + + + This is the foo + function. + + + This description can have paragraphs... + + + + lists + + + etc. + + + + And any quickbook block markup. + + + std::string foo() { @@ -2515,211 +2513,218 @@ for the journey to old age.]]] return "foo"; } - - - - - - This is the bar - function - - - + + + + + + This is the bar + function + + + std::string bar() { // return 'em, bar man! return "bar"; } - - - Some trailing text here - - - - - Code - Snippet Markup - - - Note how the code snippets in stub.cpp - get marked up. We use distinguishable comments following the form: - - + + + Some trailing text here + + + + + Code + Snippet Markup + + + Note how the code snippets in 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. - - - - Special - Comments - - - Special comments of the form: - - + + 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. + + + + Special + Comments + + + Special comments of the form: + + //` some [*quickbook] markup here - - and: - - + + 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. - - - - Callouts - - - Special comments of the form: - - + + 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. + + + + 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 Callouts - for details. Example: - - - - + + 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 Callouts + for details. Example: + + + + std::string foo_bar() { return "foo-bar"; } + + + The Mythical FooBar. See Foobar + for details return 'em, foo-bar man! + + + + Checkout stub.cpp to see + the actual code. + +
+
+
+
+ <link linkend="quickbook.install"> Installation and configuration</link> + + This section provides some guidelines on how to install and configure + BoostBook and Quickbook under several operating systems. - The Mythical FooBar. See Foobar - for details return 'em, foo-bar man! + Before continuing, it is very important that you keep this in mind: if + you try to build some documents and the process breaks due to misconfiguration, + be absolutely sure to delete any bin + and bin.v2 directories generated by the build + before trying again. Otherwise your configuration fixes will not take + any effect. - - - Checkout stub.cpp to see the actual - code. - -
-
- -
- <link linkend="quickbook.install"> Installation and configuration</link> - - This section provides some guidelines on how to install and configure BoostBook - and Quickbook under several operating systems. - - - Before continuing, it is very important that you keep this in mind: if you - try to build some documents and the process breaks due to misconfiguration, - be absolutely sure to delete any bin - and bin.v2 directories generated by the build before - trying again. Otherwise your configuration fixes will not take any effect. - -
- <link linkend="quickbook.install.windows"> Windows 2000, XP, 2003, Vista</link> - - -
- - - Section contributed by Julio M. Merino Vidal - - -
- - The following instructions apply to any Windows system based on Windows 2000, - including Windows XP, Windows 2003 Server and Windows Vista. The paths shown - below are taken from a Windows Vista machine; you will need to adjust them - to match your system in case you are running an older version. - - - - First of all you need to have a copy of xsltproc - for Windows. There are many ways to get this tool, but to keep things simple, - use the binary packages - made by Igor Zlatkovic. At the very least, you need to download the following - packages: iconv, zlib, libxml2 - and libxslt. - - - Unpack all these packages in the same directory so that you get unique - bin, include - and lib directories within - the hierarchy. These instructions use C:\Users\example\Documents\boost\xml - as the root for all files. - - - From the command line, go to the bin - directory and launch xsltproc.exe - to ensure it works. You should get usage information on screen. - - - Download Docbook - XML 4.2 and unpack it in the same directory used above. That is: - C:\Users\example\Documents\boost\xml\docbook-xml. - - - Download the latest Docbook - XSL version and unpack it, again in the same directory used before. - To make things easier, rename the directory created during the extraction - to docbook-xsl (bypassing the version name): C:\Users\example\Documents\boost\xml\docbook-xsl. - - - Add the following to your user-config.jam - file, which should live in your home directory (%HOMEDRIVE%%HOMEPATH%). - You must already have it somewhere or otherwise you could not be building - Boost (i.e. missing tools configuration). - - - +
+ <link linkend="quickbook.install.windows"> Windows 2000, XP, 2003, + Vista</link> + + +
+ + + Section contributed by Julio M. Merino Vidal + + +
+ + The following instructions apply to any Windows system based on Windows + 2000, including Windows XP, Windows 2003 Server and Windows Vista. + The paths shown below are taken from a Windows Vista machine; you will + need to adjust them to match your system in case you are running an + older version. + + + + First of all you need to have a copy of xsltproc + for Windows. There are many ways to get this tool, but to keep things + simple, use the binary + packages made by Igor Zlatkovic. At the very least, you need + to download the following packages: iconv, + zlib, libxml2 and libxslt. + + + Unpack all these packages in the same directory so that you get unique + bin, include and lib + directories within the hierarchy. These instructions use C:\Users\example\Documents\boost\xml as the root for all files. + + + From the command line, go to the bin + directory and launch xsltproc.exe + to ensure it works. You should get usage information on screen. + + + Download Docbook + XML 4.2 and unpack it in the same directory used above. That + is: C:\Users\example\Documents\boost\xml\docbook-xml. + + + Download the latest Docbook + XSL version and unpack it, again in the same directory used + before. To make things easier, rename the directory created during + the extraction to docbook-xsl + (bypassing the version name): C:\Users\example\Documents\boost\xml\docbook-xsl. + + + Add the following to your user-config.jam + file, which should live in your home directory (%HOMEDRIVE%%HOMEPATH%). + You must already have it somewhere or otherwise you could not be + building Boost (i.e. missing tools configuration). + + + using xsltproc : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" @@ -2730,85 +2735,88 @@ for the journey to old age.]]] : "C:/Users/example/Documents/boost/xml/docbook-xml" ; - - The above steps are enough to get a functional BoostBook setup. Quickbook - will be automatically built when needed. If you want to avoid these rebuilds: - - - - Go to Quickbook's source directory (BOOST_ROOT\tools\quickbook). - - - Build the utility by issuing bjam - --v2. - - - Copy the resulting quickbook.exe - binary (located under the BOOST_ROOT\bin.v2 hierarchy) - to a safe place. Following our previous example, you can install it into: - C:\Users\example\Documents\boost\xml\bin. - - - Add the following to your user-config.jam - file: - - - + + The above steps are enough to get a functional BoostBook setup. Quickbook + will be automatically built when needed. If you want to avoid these + rebuilds: + + + + Go to Quickbook's source directory (BOOST_ROOT\tools\quickbook). + + + Build the utility by issuing bjam + --v2. + + + Copy the resulting quickbook.exe + binary (located under the BOOST_ROOT\bin.v2 + hierarchy) to a safe place. Following our previous example, you can + install it into: C:\Users\example\Documents\boost\xml\bin. + + + Add the following to your user-config.jam + file: + + + using quickbook : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" ; -
-
- <link linkend="quickbook.install.linux"> Debian, Ubuntu</link> - - The following instructions apply to Debian and its derivatives. They are - based on a Ubuntu Edgy install but should work on other Debian based systems. - - - First install the bjam, - xsltproc, docbook-xsl and - docbook-xml packages. For example, using apt-get: - - +
+
+ <link linkend="quickbook.install.linux"> Debian, Ubuntu</link> + + The following instructions apply to Debian and its derivatives. They + are based on a Ubuntu Edgy install but should work on other Debian + based systems. + + + First install the bjam, + xsltproc, docbook-xsl and docbook-xml + packages. For example, using apt-get: + + sudo apt-get install xsltprc docbook-xsl docbook-xml - - If you're planning on building boost's documentation, you'll also need to - install the doxygen package - as well. - - - Next, we need to configure Boost Build to compile BoostBook files. Add the - following to your user-config.jam file, which should be in your home - directory. If you don't have one, create a file containing this text. For - more information on setting up user-config.jam, see - the Boost - Build documentation. - - + + If you're planning on building boost's documentation, you'll also need + to install the doxygen + package as well. + + + Next, we need to configure Boost Build to compile BoostBook files. + Add the following to your user-config.jam + file, which should be in your home directory. If you don't have one, + create a file containing this text. For more information on setting + up user-config.jam, see the Boost + Build documentation. + + using xsltproc ; @@ -2820,90 +2828,91 @@ for the journey to old age.]]] # Remove this line if you're not using doxygen using doxygen ; - - The above steps are enough to get a functional BoostBook setup. Quickbook - will be automatically built when needed. If you want to avoid these rebuilds: - - - - Go to Quickbook's source directory (BOOST_ROOT/tools/quickbook). - - - Build the utility by issuing bjam - --v2. - - - Copy the resulting quickbook - binary (located under the BOOST_ROOT/bin.v2 hierarchy) - to a safe place. The traditional location is /usr/local/bin. - - - Add the following to your user-config.jam - file, using the full path of the quickbook executable: - - - + + The above steps are enough to get a functional BoostBook setup. Quickbook + will be automatically built when needed. If you want to avoid these + rebuilds: + + + + Go to Quickbook's source directory (BOOST_ROOT/tools/quickbook). + + + Build the utility by issuing bjam + --v2. + + + Copy the resulting quickbook + binary (located under the BOOST_ROOT/bin.v2 + hierarchy) to a safe place. The traditional location is /usr/local/bin. + + + Add the following to your user-config.jam + file, using the full path of the quickbook executable: + + + using quickbook : /usr/local/bin/quickbook ; -
-
-
- <link linkend="quickbook.editors"> Editor Support</link> - - Editing quickbook files is usually done with text editors both simple and powerful. - The following sections list the settings for some editors which can help make - editing quickbook files a bit easier. - - - - - - note - - You may submit your settings, tips, and suggestions to - the authors, or through the docs - Boost Docs mailing list. - - -
- <link linkend="quickbook.editors.scite"> Scintilla Text Editor</link> -
- +
+
+
+ <link linkend="quickbook.editors"> Editor Support</link> - Section contributed by Dean Michael Berris + Editing quickbook files is usually done with text editors both simple + and powerful. The following sections list the settings for some editors + which can help make editing quickbook files a bit easier. - - - - The Scintilla Text Editor (SciTE) is a free source code editor for Win32 - and X. It uses the SCIntilla source code editing component. - - - - - - tip - - SciTE can be downloaded from http://www.scintilla.org/SciTE.html - - - - You can use the following settings to highlight quickbook tags when editing - quickbook files. - - + + + + + note + + You may submit your settings, tips, and suggestions + to the authors, or through the docs + Boost Docs mailing list. + + +
+ <link linkend="quickbook.editors.scite"> Scintilla Text Editor</link> +
+ + + Section contributed by Dean Michael Berris + + +
+ + The Scintilla Text Editor (SciTE) is a free source code editor for + Win32 and X. It uses the SCIntilla source code editing component. + + + + + + tip + + SciTE can be downloaded from http://www.scintilla.org/SciTE.html + + + + You can use the following settings to highlight quickbook tags when + editing quickbook files. + + qbk=*.qbk lexer.*.qbk=props use.tabs.$(qbk)=0 @@ -2916,45 +2925,47 @@ comment.box.start.props=[/ comment.box.middle.props= comment.box.end.props=] - - - - - note - - Thanks to Rene Rivera for the above SciTE settings. - - -
-
-
- <link linkend="quickbook.faq"> Frequently Asked Questions</link> - - - Can - I use QuickBook for non-Boost documentation? - - - QuickBook can be used for non-Boost documentation with a little extra work. - -
- - - Faq contributed by Michael Marcin - - -
- - When building HTML documentation with BoostBook a Boost C++ Libraries header - is added to the files. When using QuickBook to document projects outside of - Boost this is not desirable. This behavior can be overridden at the BoostBook - level by specifying some XSLT options. When using Boost Build version 2 (BBv2) - this can be achieved by adding parameters to the BoostBook target declaration. - - - For example: - - + + + + + note + + Thanks to Rene Rivera for the above SciTE settings. + + +
+
+
+ <link linkend="quickbook.faq"> Frequently Asked Questions</link> + + + Can + I use QuickBook for non-Boost documentation? + + + QuickBook can be used for non-Boost documentation with a little extra + work. + +
+ + + Faq contributed by Michael Marcin + + +
+ + When building HTML documentation with BoostBook a Boost C++ Libraries + header is added to the files. When using QuickBook to document projects + outside of Boost this is not desirable. This behavior can be overridden + at the BoostBook level by specifying some XSLT options. When using Boost + Build version 2 (BBv2) this can be achieved by adding parameters to the + BoostBook target declaration. + + + For example: + + using quickbook ; xml my_doc : my_doc.qbk ; @@ -2970,780 +2981,785 @@ boostbook standalone <xsl:param>nav.layout=none ; -
-
- <link linkend="quickbook.ref"> Quick Reference</link> - - [cpp] - - Syntax Compendium - - - - - - To do this... - - - - Use this... - - - - See this... - - - - - - - - - comment - - - - [/ some comment] - - - - Comments - - - - - - - italics - - - - ['italics] or /italics/ - - - - Font Styles - and Simple - formatting - - - - - - - bold - - - - [*bold] or *bold* - - - - Font Styles - and Simple - formatting - - - - - - - underline - - - - [_underline] or _underline_ - - - - Font Styles - and Simple - formatting - - - - - - - teletype - - - - [^teletype] or =teletype= - - - - Font Styles - and Simple - formatting - - - - - - - strikethrough - - - - [-strikethrough] - - - - Font Styles - and Simple - formatting - - - - - - - - replaceable - - - - - [~replaceable] - - - - Replaceble - - - - - - - source mode - - - - [c++] or [python] - - - - Source Mode - - - - - - - inline code - - - - `int main();` - - - - Inline code - - - - - - - code block - - - - ``int main();`` - - - - Code - - - - - - - code escape - - - - ``from c++ to QuickBook`` - - - - Escaping Back To QuickBook - - - - - - - line break - - - - [br] or \n - - - - line-break - DEPRECATED - - - - - - - anchor - - - - [#anchor] - - - - Anchors - - - - - - - link - - - - [@http://www.boost.org Boost] - - - - Links - - - - - - - anchor link - - - - [link section.anchor Link text] - - - - Anchor links - - - - - - - refentry link - - - - [link xml.refentry Link text] - - - - refentry links - - - - - - - function link - - - - [funcref fully::qualified::function_name Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - class link - - - - [classref fully::qualified::class_name Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - member link - - - - [memberref fully::qualified::member_name Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - enum link - - - - [enumref fully::qualified::enum_name Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - macro link - - - - [macroref MACRO_NAME Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - concept link - - - - [conceptref ConceptName Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - header link - - - - [headerref path/to/header.hpp Link text] - - - - function, class, member, - enum, macro, concept or header links - - - - - - - escape - - - - '''escaped text (no processing/formatting)''' - - - - Escape - - - - - - - single char escape - - - - \c - - - - Single char - escape - - - - - - - images - - - - [$image.jpg] - - - - Images - - - - - - - begin section - - - - [section The Section Title] - - - - Section - - - - - - - end section - - - - [endsect] - - - - Section - - - - - - - paragraph - - - - No markup. Paragraphs start left-flushed and are terminated by two or - more newlines. - - - - Paragraphs - - - - - - - ordered list - - - - + +
+ <link linkend="quickbook.ref"> Quick Reference</link> + + [cpp] + +
Syntax Compendium + + + + + + To do this... + + + + Use this... + + + + See this... + + + + + + + + + comment + + + + [/ some comment] + + + + Comments + + + + + + + italics + + + + ['italics] or /italics/ + + + + Font Styles + and Simple + formatting + + + + + + + bold + + + + [*bold] or *bold* + + + + Font Styles + and Simple + formatting + + + + + + + underline + + + + [_underline] or _underline_ + + + + Font Styles + and Simple + formatting + + + + + + + teletype + + + + [^teletype] or =teletype= + + + + Font Styles + and Simple + formatting + + + + + + + strikethrough + + + + [-strikethrough] + + + + Font Styles + and Simple + formatting + + + + + + + + replaceable + + + + + [~replaceable] + + + + Replaceble + + + + + + + source mode + + + + [c++] or [python] + + + + Source Mode + + + + + + + inline code + + + + `int main();` + + + + Inline code + + + + + + + code block + + + + ``int main();`` + + + + Code + + + + + + + code escape + + + + ``from c++ to QuickBook`` + + + + Escaping Back + To QuickBook + + + + + + + line break + + + + [br] or \n + + + + line-break + DEPRECATED + + + + + + + anchor + + + + [#anchor] + + + + Anchors + + + + + + + link + + + + [@http://www.boost.org Boost] + + + + Links + + + + + + + anchor link + + + + [link section.anchor Link text] + + + + Anchor links + + + + + + + refentry link + + + + [link xml.refentry Link text] + + + + refentry + links + + + + + + + function link + + + + [funcref fully::qualified::function_name Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + class link + + + + [classref fully::qualified::class_name Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + member link + + + + [memberref fully::qualified::member_name Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + enum link + + + + [enumref fully::qualified::enum_name Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + macro link + + + + [macroref MACRO_NAME Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + concept link + + + + [conceptref ConceptName Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + header link + + + + [headerref path/to/header.hpp Link text] + + + + function, class, + member, enum, macro, concept or header links + + + + + + + escape + + + + '''escaped text (no processing/formatting)''' + + + + Escape + + + + + + + single char escape + + + + \c + + + + Single + char escape + + + + + + + images + + + + [$image.jpg] + + + + Images + + + + + + + begin section + + + + [section The Section Title] + + + + Section + + + + + + + end section + + + + [endsect] + + + + Section + + + + + + + paragraph + + + + No markup. Paragraphs start left-flushed and are terminated by + two or more newlines. + + + + Paragraphs + + + + + + + ordered list + + + + # one # two # three - - - - Ordered lists - - - - - - - unordered list - - - - + + + + Ordered + lists + + + + + + + unordered list + + + + * one * two * three - - - - Unordered - lists - - - - - - - code - - - - No markup. Preformatted code starts with a space or a tab. - - - - Code - - - - - - - preformatted - - - - [pre preformatted] - - - - Preformatted - - - - - - - block quote - - - - [:sometext...] - - - - Blockquote - - - - - - - heading 1 - - - - [h1 Heading 1] - - - - Heading - - - - - - - heading 2 - - - - [h2 Heading 2] - - - - Heading - - - - - - - heading 3 - - - - [h3 Heading 3] - - - - Heading - - - - - - - heading 4 - - - - [h4 Heading 4] - - - - Heading - - - - - - - heading 5 - - - - [h5 Heading 5] - - - - Heading - - - - - - - heading 6 - - - - [h6 Heading 6] - - - - Heading - - - - - - - macro - - - - [def macro_identifier some text] - - - - Macros - - - - - - - template - - - - [template[a b] [a] body [b]] - - - - Templates - - - - - - - blurb - - - - [blurb advertisement or note...] - - - - Blurbs - - - - - - - admonition - - - - [warning Warning text...] - - - - Admonitions - - - - - - - table - - - - + + + + Unordered + lists + + + + + + + code + + + + No markup. Preformatted code starts with a space or a tab. + + + + Code + + + + + + + preformatted + + + + [pre preformatted] + + + + Preformatted + + + + + + + block quote + + + + [:sometext...] + + + + Blockquote + + + + + + + heading 1 + + + + [h1 Heading 1] + + + + Heading + + + + + + + heading 2 + + + + [h2 Heading 2] + + + + Heading + + + + + + + heading 3 + + + + [h3 Heading 3] + + + + Heading + + + + + + + heading 4 + + + + [h4 Heading 4] + + + + Heading + + + + + + + heading 5 + + + + [h5 Heading 5] + + + + Heading + + + + + + + heading 6 + + + + [h6 Heading 6] + + + + Heading + + + + + + + macro + + + + [def macro_identifier some text] + + + + Macros + + + + + + + template + + + + [template[a b] [a] body [b]] + + + + Templates + + + + + + + blurb + + + + [blurb advertisement or note...] + + + + Blurbs + + + + + + + admonition + + + + [warning Warning text...] + + + + Admonitions + + + + + + + table + + + + [table Title [[a][b][c]] [[a][b][c]] ] - - - - Tables - - - - - - - variablelist - - - - + + + + Tables + + + + + + + variablelist + + + + [variablelist Title [[a][b]] [[a][b]] ] - - - - Variable Lists - - - - - - - include - - - - [include someother.qbk] - - - - Include - - - - - -
-
- + + + + Variable + Lists + + + + + + + include + + + + [include someother.qbk] + + + + Include + + + + + + + + + \ No newline at end of file diff --git a/test/templates.gold b/test/templates.gold index 352bb89..d6323ba 100644 --- a/test/templates.gold +++ b/test/templates.gold @@ -46,7 +46,7 @@ wxyz wxyz trail - + int main() {