From ddca4f710b23df650a8f163f5b618c73e056be23 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Thu, 6 Oct 2011 22:10:28 +0000 Subject: [PATCH] Quickbook: Merge from trunk. - Qualify footnote and callout ids. - Close open sections at end of document. - New markup for anchors in headers. - Clean up some whitespace in generated xml. - Fix double addition of anchor ids. - A couple of doc changes from Beman. [SVN r74769] --- doc/quickbook.qbk | 14 +- src/actions.cpp | 80 +++-- src/doc_info_actions.cpp | 14 + src/post_process.cpp | 13 +- src/quickbook.cpp | 6 +- test/Jamfile.v2 | 1 + test/anchor.gold | 23 +- test/blocks.gold | 15 +- test/callouts.gold | 130 +++++++- test/callouts.quickbook | 25 ++ test/code-block-1.gold | 1 - test/code-block-2.gold | 1 - test/code-block-3.gold | 2 - test/code-block-3.quickbook | 2 +- test/code-block-cpp.gold | 4 +- test/code-block-python.gold | 2 +- test/code-block-teletype.gold | 1 - test/code-block.gold | 10 +- test/doc-info/source-mode-1.4.gold | 5 - test/doc-info/source-mode-1.5.gold | 7 - test/doc-info/source-mode-1.6.gold | 7 - test/heading_1_1.gold | 8 +- test/heading_1_3.gold | 11 +- test/heading_1_5.gold | 78 +++++ test/heading_1_6.gold | 12 +- test/identifier_1_5.gold | 462 +++++++++++++-------------- test/identifier_1_6.gold | 463 ++++++++++++++-------------- test/import.gold | 50 ++- test/import.quickbook | 1 + test/preformatted.gold | 1 - test/quickbook-manual.gold | 195 +++--------- test/section_1_5-unclosed.gold | 10 + test/section_1_5-unclosed.quickbook | 5 + test/snippets/pass_thru.gold | 3 - test/template-section.gold | 3 +- test/templates.gold | 3 - test/unicode-escape.gold | 5 +- test/utf-8-bom.gold | 4 +- test/utf-8.gold | 4 +- 39 files changed, 928 insertions(+), 753 deletions(-) create mode 100644 test/heading_1_5.gold create mode 100644 test/section_1_5-unclosed.gold create mode 100644 test/section_1_5-unclosed.quickbook diff --git a/doc/quickbook.qbk b/doc/quickbook.qbk index 7b9184d..7b11c5b 100644 --- a/doc/quickbook.qbk +++ b/doc/quickbook.qbk @@ -90,6 +90,12 @@ generate __boostbook__ instead of HTML. The __boostbook__ documentation format is an extension of __docbook__, an SGML or XML based format for describing documentation. +[tip You don't need to know anything about __boostbook__ or __docbook__ +to use QuickBook. A basic understanding of __docbook__ might help, but +shouldn't be necessary. For really advanced stuff you will need to know +__docbook__, but you can ignore it at first, and maybe continue to do so. +] + QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks. QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are @@ -297,6 +303,10 @@ Boost 1.46.1: [heading Version 1.5.6 - Boost 1.48] * Xml encode escaped punctuation (eg. `\<` is correctly encodes to \<). +* Rename duplicate generated ids. +* Close open sections at end of document (still warns about them). +* New anchor markup for headers, will hopefully generate better pdfs. +* Remove some whitespace around code from post processed output. [endsect] [/Change log] @@ -2180,12 +2190,12 @@ case, check out [@http://www.pkgsrc.org pkgsrc]. [endsect] [/ macosx] -[section:windows Windows 2000, XP, 2003, Vista] +[section:windows Windows 2000, XP, 2003, Vista, 7] [:['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 +2000, including Windows XP, Windows 2003 Server, Windows Vista, and Windows 7. 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. diff --git a/src/actions.cpp b/src/actions.cpp index f761312..d7618f0 100644 --- a/src/actions.cpp +++ b/src/actions.cpp @@ -59,9 +59,7 @@ namespace quickbook it != end; ++it) { tgt << ""; } @@ -280,7 +278,9 @@ namespace quickbook value_consumer values = phrase; actions.phrase << "" << values.consume().get_boostbook() << ""; @@ -318,16 +318,32 @@ namespace quickbook } namespace { - void write_bridgehead(collector& out, int level, - std::string const& str, std::string const& id, std::string const& linkend) + void write_bridgehead(quickbook::actions& actions, int level, + std::string const& str, std::string const& id, bool self_link) { - out << ""; - if(!linkend.empty()) out << ""; - out << str; - if(!linkend.empty()) out << ""; - out << ""; + if (self_link && !id.empty()) + { + actions.out << ""; + actions.out << ""; + actions.out << ""; + actions.out << str; + actions.out << ""; + actions.out << ""; + } + else + { + actions.out << ""; + actions.out << str; + actions.out << ""; + } } } @@ -358,14 +374,17 @@ namespace quickbook level = heading_list.get_tag() - block_tags::heading1 + 1; } - std::string linkend; + write_anchors(actions, actions.out); if (!generic && qbk_version_n < 103) // version 1.2 and below { - add_anchor(actions, + std::string anchor = actions.ids.add( actions.section_id + '.' + detail::make_identifier(content.get_boostbook()), id_generator::generated_heading); + + write_bridgehead(actions, level, + content.get_boostbook(), anchor, false); } else { @@ -383,20 +402,14 @@ namespace quickbook content.get_boostbook() ); - linkend = add_anchor(actions, + std::string anchor = actions.ids.add( fully_qualified_id(actions.doc_id, actions.qualified_section_id, id), - category); - } + category);; - write_anchors(actions, actions.out); - write_bridgehead(actions.out, level, - content.get_boostbook(), - actions.ids.add( - fully_qualified_id(actions.doc_id, - actions.qualified_section_id, "h"), - id_generator::numbered), - linkend); + write_bridgehead(actions, level, + content.get_boostbook(), anchor, true); + } } void simple_phrase_action::operator()(char mark) const @@ -1258,17 +1271,16 @@ namespace quickbook } unsigned int size = symbol->params.size(); + std::string callout_base_id = + fully_qualified_id(actions.doc_id, + actions.qualified_section_id, "c"); for(unsigned int i = 0; i < size; ++i) { - std::string callout_id1 = - actions.ids.add( - actions.doc_id + ".c", - id_generator::numbered); - std::string callout_id2 = - actions.ids.add( - actions.doc_id + ".c", - id_generator::numbered); + std::string callout_id1 = actions.ids.add( + callout_base_id, id_generator::numbered); + std::string callout_id2 = actions.ids.add( + callout_base_id, id_generator::numbered); std::string code; code += " 0) { + out << ""; + --actions.section_level; + } + + actions.qualified_section_id.clear(); + } + // We've finished generating our output. Here's what we'll do // *after* everything else. out << "\n\n\n"; diff --git a/src/post_process.cpp b/src/post_process.cpp index 3c77351..fac6c13 100644 --- a/src/post_process.cpp +++ b/src/post_process.cpp @@ -32,9 +32,14 @@ namespace quickbook column = current_indent; } - void break_line() + void trim_spaces() { out.erase(out.find_last_not_of(' ')+1); // trim trailing spaces + } + + void break_line() + { + trim_spaces(); out += '\n'; indent(); } @@ -338,13 +343,16 @@ namespace quickbook void do_code(iter_type f, iter_type l) const { - state.out += '\n'; + state.printer_.trim_spaces(); + if (state.out[state.out.size() - 1] != '\n') + state.out += '\n'; // print the string taking care of line // ending CR/LF platform issues for (iter_type i = f; i != l; ++i) { if (*i == '\n') { + state.printer_.trim_spaces(); state.out += '\n'; ++i; if (i != l && *i != '\r') @@ -352,6 +360,7 @@ namespace quickbook } else if (*i == '\r') { + state.printer_.trim_spaces(); state.out += '\n'; ++i; if (i != l && *i != '\n') diff --git a/src/quickbook.cpp b/src/quickbook.cpp index 73c311c..ab52489 100644 --- a/src/quickbook.cpp +++ b/src/quickbook.cpp @@ -35,7 +35,7 @@ #pragma warning(disable:4355) #endif -#define QUICKBOOK_VERSION "Quickbook Version 1.5.6 (release)" +#define QUICKBOOK_VERSION "Quickbook Version 1.5.6" namespace quickbook { @@ -116,10 +116,6 @@ namespace quickbook actions& actor) { bool r = parse_file(filein_, actor); - if (actor.section_level != 0) - detail::outwarn(filein_) - << "Warning missing [endsect] detected at end of file." - << std::endl; if(actor.error_count) { diff --git a/test/Jamfile.v2 b/test/Jamfile.v2 index 3ea40c3..3e6686d 100644 --- a/test/Jamfile.v2 +++ b/test/Jamfile.v2 @@ -46,6 +46,7 @@ test-suite quickbook.test : [ quickbook-test include_1_6-2 ] [ quickbook-test section_1_4 ] [ quickbook-test section_1_5 ] + [ quickbook-test section_1_5-unclosed ] [ quickbook-test heading_1_1 ] [ quickbook-test heading_1_3 ] [ quickbook-test heading_1_6 ] diff --git a/test/anchor.gold b/test/anchor.gold index 18ef867..ab7453c 100644 --- a/test/anchor.gold +++ b/test/anchor.gold @@ -9,26 +9,29 @@ A paragraph containing several anchors. We want to make sure they appear in the correct place. - - This + This heading shouldn't pick up the previous anchor - + - This + This heading should pick up the previous anchor - + - And this one + And + this one - + - Also this one + Also + this one - - + + Finally this diff --git a/test/blocks.gold b/test/blocks.gold index cae4d70..2d7370b 100644 --- a/test/blocks.gold +++ b/test/blocks.gold @@ -2,9 +2,9 @@
- Various blocks + Various blocks - Blockquotes + Blockquotes Here's a blockquote: @@ -25,9 +25,8 @@ Blockquote second paragraph. - - Admonitions + Admonitions @@ -62,17 +61,17 @@ Warning second paragraph. - - Blurb + Blurb Blurb - + - Inline blocks + Inline + blocks
diff --git a/test/callouts.gold b/test/callouts.gold index f816ed0..51bef92 100644 --- a/test/callouts.gold +++ b/test/callouts.gold @@ -10,7 +10,6 @@ Now we can define a function that simulates an ordinary six-sided die. - int roll_die() { boost::uniform_int<> dist(1, 6); } @@ -28,7 +27,6 @@ Example 2: - int roll_die() { boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); } @@ -48,7 +46,6 @@ Example 3: - int roll_die() { boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); } @@ -68,7 +65,6 @@ Example 3 (again!): - int roll_die() { boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); } @@ -88,7 +84,6 @@ Example 4: - int roll_die() { boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); boost::uniform_int<> dist(1, 6); @@ -114,7 +109,6 @@ - boost::uniform_int<> dist(1, 6); @@ -130,4 +124,128 @@ +
+ <link linkend="callout_tests.test_section">Try callouts in a section</link> + + Example 1: + + + Now we can define a function that simulates an ordinary six-sided die. + + +int roll_die() { + boost::uniform_int<> dist(1, 6); +} + + + + + + + create a uniform_int distribution + + + + + Example 2: + + +int roll_die() { + boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); +} + + + + + + + + test + + + + + + Example 3: + + +int roll_die() { + boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); +} + + + + + + + + test + + + + + + Example 3 (again!): + + +int roll_die() { + boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); +} + + + + + + + + test + + + + + + Example 4: + + +int roll_die() { + boost::variate_generator<boost::mt19937&, boost::uniform_int<> > die(gen, dist); +boost::uniform_int<> dist(1, 6); +} + + + + + + + callout 1 + + + + + callout 2 + + + + + create a uniform_int distribution + + + + +boost::uniform_int<> dist(1, 6); + + + + + + callout 2 + + + + + create a uniform_int distribution + + + +
diff --git a/test/callouts.quickbook b/test/callouts.quickbook index 0d1a47a..b17e904 100644 --- a/test/callouts.quickbook +++ b/test/callouts.quickbook @@ -24,3 +24,28 @@ Example 4: [example4] [example4a] + +[section:test_section Try callouts in a section] + +Example 1: + +[example1] + +Example 2: + +[example2] + +Example 3: + +[example3] + +Example 3 (again!): + +[example3] + +Example 4: + +[example4] +[example4a] + +[endsect] \ No newline at end of file diff --git a/test/code-block-1.gold b/test/code-block-1.gold index 032eafe..7ee1588 100644 --- a/test/code-block-1.gold +++ b/test/code-block-1.gold @@ -8,7 +8,6 @@ A code block with proper indentation ;-) - #include <iostream> int main() diff --git a/test/code-block-2.gold b/test/code-block-2.gold index ef60bd7..d42c1a7 100644 --- a/test/code-block-2.gold +++ b/test/code-block-2.gold @@ -9,7 +9,6 @@ A code block with proper indentation ;-) - #include <iostream> int main() diff --git a/test/code-block-3.gold b/test/code-block-3.gold index 3c8d8bf..308b86e 100644 --- a/test/code-block-3.gold +++ b/test/code-block-3.gold @@ -6,7 +6,6 @@
Python code block - print "\xfabln\xeck" @@ -17,7 +16,6 @@ This isn't valid C++ but I think we should accept it; - [cpp] std::cout<<"\xfabln\xeck"<<"\n"; diff --git a/test/code-block-3.quickbook b/test/code-block-3.quickbook index 7994698..54c4bf5 100644 --- a/test/code-block-3.quickbook +++ b/test/code-block-3.quickbook @@ -13,7 +13,7 @@ This isn't valid C++ but I think we should accept it; -[cpp] +[c++] `` std::cout<<"\xfabln\xeck"<<"\n"; `` diff --git a/test/code-block-cpp.gold b/test/code-block-cpp.gold index 793bf65..be33bfd 100644 --- a/test/code-block-cpp.gold +++ b/test/code-block-cpp.gold @@ -2,7 +2,7 @@
- C++ Code Blocks + C++ Code Blocks // No escape /* No escape */ /* No escape @@ -17,13 +17,11 @@ A badly formed comment: - /* Oh dear A badly formed comment with an escape: - /* Oh dear bold
diff --git a/test/code-block-python.gold b/test/code-block-python.gold index ec6c845..239d147 100644 --- a/test/code-block-python.gold +++ b/test/code-block-python.gold @@ -2,7 +2,7 @@
- Python Code Blocks + Python Code Blocks # No escape # Escape: bold # Escape: underlineitalic diff --git a/test/code-block-teletype.gold b/test/code-block-teletype.gold index 35ed79f..e36fb11 100644 --- a/test/code-block-teletype.gold +++ b/test/code-block-teletype.gold @@ -5,7 +5,6 @@ Code Block Teletype 1
<link linkend="code_block_teletype_1.a_code_block">A code block</link> - Just some plain text. With some quickbook thrown in? diff --git a/test/code-block.gold b/test/code-block.gold index 2f10c0d..8ca2281 100644 --- a/test/code-block.gold +++ b/test/code-block.gold @@ -6,13 +6,11 @@ In a paragraph. Still in a paragraph. - In a code block. Back in a paragraph. - Code block line 1. Code block line 2. Code block line 3. @@ -20,21 +18,17 @@ Code block line 2. Paragraph. - Code block with no trailing blank lines. Paragraph. - - Code blocks - separated by comment + Code + blocks separated by comment - First code block. - Second code block. [/ Comment in second code block] Still second code block. diff --git a/test/doc-info/source-mode-1.4.gold b/test/doc-info/source-mode-1.4.gold index c105559..f7fea9a 100644 --- a/test/doc-info/source-mode-1.4.gold +++ b/test/doc-info/source-mode-1.4.gold @@ -16,23 +16,18 @@ - int main() {} - def foo(): - def foo(x): - int main() {} - int main() {}
diff --git a/test/doc-info/source-mode-1.5.gold b/test/doc-info/source-mode-1.5.gold index e10aee2..340c5d2 100644 --- a/test/doc-info/source-mode-1.5.gold +++ b/test/doc-info/source-mode-1.5.gold @@ -15,31 +15,24 @@ - This shouldn't be highlighted. - int main() {} - int main() {} - def foo(): - def foo(x): - This shouldn't be highlighted - This shouldn't be highlighted. diff --git a/test/doc-info/source-mode-1.6.gold b/test/doc-info/source-mode-1.6.gold index 05ae525..6e28096 100644 --- a/test/doc-info/source-mode-1.6.gold +++ b/test/doc-info/source-mode-1.6.gold @@ -15,31 +15,24 @@ - This shouldn't be highlighted. - int main() {} - This shouldn't be highlighted. - def foo(): - This shouldn't be highlighted. - This shouldn't be highlighted - This shouldn't be highlighted. diff --git a/test/heading_1_1.gold b/test/heading_1_1.gold index bee638f..b920b37 100644 --- a/test/heading_1_1.gold +++ b/test/heading_1_1.gold @@ -2,13 +2,13 @@
- Heading 1.1 - + Heading 1.1 + First heading
- Section - + Section + Second heading
diff --git a/test/heading_1_3.gold b/test/heading_1_3.gold index f6fc2c3..f883a60 100644 --- a/test/heading_1_3.gold +++ b/test/heading_1_3.gold @@ -1,23 +1,22 @@
- <link linkend="quickbook.change_log">Change Log</link> + <link linkend="quickbook.change_log">Change Log</link> - Version 1.3 + Version + 1.3 @@ -300,13 +300,10 @@ Can be placed anywhere. - [/ comment (no output generated) ] - [/ comments can be nested [/ some more here] ] - [/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]
@@ -314,7 +311,6 @@ <link linkend="quickbook.syntax.phrase">Phrase Level Elements</link>
<link linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> - ['italic], [*bold], [_underline], [^teletype], [-strikethrough] @@ -328,7 +324,6 @@ Like all non-terminal phrase level elements, this can of course be nested: - [*['bold-italic]] @@ -344,7 +339,6 @@ When you want content that may or must be replaced by the user, use the syntax: - [~replacement] @@ -356,7 +350,6 @@
<link linkend="quickbook.syntax.phrase.quotations">Quotations</link> - ["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein @@ -374,7 +367,6 @@ Like all phrase elements, quotations may be nested. Example: - ["Here's the rule for bargains: ["Do other men, for they would do you.] That's the true business precept.] @@ -392,7 +384,6 @@ the true business precept.] Simple markup for formatting text, common in many applications, is now supported: - /italic/, *bold*, _underline_, =teletype= @@ -404,7 +395,7 @@ the true business precept.] Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives - are much stricter + are much stricter Thanks to David Barrett, author of Qwiki, for sharing these samples and teaching me these obscure formatting rules. @@ -656,7 +647,6 @@ the true business precept.] "have" to "full" in the following paragraph will be rendered as bold: - Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!* One for the master, one for the dame, @@ -670,7 +660,6 @@ And one for the little boy who lives down the lane. But in the following paragraph, bold is not applied: - Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! One for the master, one for the dame, @@ -688,7 +677,6 @@ And one for the little boy who lives down the lane. Inlining code in paragraphs is quite common when writing C++ documentation. We provide a very simple markup for this. For example, this: - This text has inlined code `int main() { return 0; }` in it. @@ -725,7 +713,6 @@ And one for the little boy who lives down the lane. the double-tick, instead of the single-tick, we are telling QuickBook to use preformatted blocks of code. Example: - `` #include <iostream> @@ -740,7 +727,6 @@ And one for the little boy who lives down the lane. will generate: - #include <iostream> int main() @@ -765,7 +751,6 @@ And one for the little boy who lives down the lane. where source-mode is one of the supported modes. For example, this: - Python's [python] `import` is rather like C++'s [c++] `#include`. A C++ comment `// looks like this` whereas a Python comment [python] `# looks like this`. @@ -832,7 +817,6 @@ C++ comment `// looks like this` whereas a Python comment [python]
<link linkend="quickbook.syntax.phrase.line_break">line-break</link> - [br] @@ -847,7 +831,6 @@ C++ comment `// looks like this` whereas a Python comment [python]
<link linkend="quickbook.syntax.phrase.anchors">Anchors</link> - [#named_anchor] @@ -861,7 +844,6 @@ Some link text].
<link linkend="quickbook.syntax.phrase.images">Images</link> - [$image.jpg]
@@ -1026,11 +998,10 @@ escape (no processing/formatting) role="special">] block, and the text will be put at the bottom of the current page. For example, this: - [footnote A sample footnote] - will generate this + will generate this A sample footnote @@ -1038,7 +1009,7 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.phrase.footnotes.macro_expansion">Macro - Expansion</link> + Expansion __a_macro_identifier__ @@ -1047,7 +1018,7 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.phrase.footnotes.template_expansion">Template - Expansion</link> + Expansion [a_template_identifier] @@ -1065,7 +1036,6 @@ escape (no processing/formatting) 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] @@ -1161,7 +1131,6 @@ escape (no processing/formatting) Starting a new section is accomplished with: - [section:id The Section Title] @@ -1176,7 +1145,6 @@ escape (no processing/formatting) End a section with: - [endsect] @@ -1188,7 +1156,6 @@ escape (no processing/formatting) You can include another XML file with: - [xinclude file.xml] @@ -1210,7 +1177,7 @@ escape (no processing/formatting) <link linkend="quickbook.syntax.block.lists">Lists</link>
<link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered - lists</link> + lists # One # Two # Three @@ -1242,7 +1209,6 @@ escape (no processing/formatting) List hierarchies are supported. Example: - # One # Two # Three @@ -1328,7 +1294,6 @@ escape (no processing/formatting) 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. @@ -1361,7 +1326,7 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered - lists</link> + lists * First * Second * Third @@ -1392,7 +1357,6 @@ escape (no processing/formatting) Mixed lists (ordered and unordered) are supported. Example: - # One # Two # Three @@ -1446,7 +1410,6 @@ escape (no processing/formatting) And... - # 1 * 1.a # 1.a.1 @@ -1544,7 +1507,6 @@ escape (no processing/formatting) highlighted according to the current Source Mode: - #include <iostream> int main() @@ -1554,7 +1516,6 @@ escape (no processing/formatting) return 0; } - import cgi def cookForHtml(text): @@ -1565,7 +1526,6 @@ escape (no processing/formatting) 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]] @@ -1574,7 +1534,6 @@ escape (no processing/formatting) Generates: - using boost::array;
@@ -1589,7 +1548,6 @@ escape (no processing/formatting) 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]``() { } @@ -1597,7 +1555,6 @@ escape (no processing/formatting) Will generate: - void foo() { } @@ -1613,7 +1570,6 @@ escape (no processing/formatting) 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 @@ -1629,7 +1585,6 @@ escape (no processing/formatting) 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 @@ -1644,7 +1599,6 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.block.blockquote">Blockquote</link> - [:sometext...]
@@ -1655,7 +1609,6 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.block.admonitions">Admonitions</link> - [note This is a note] [tip This is a tip] [important This is important] @@ -1698,7 +1651,6 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.block.headings">Headings</link> - [h1 Heading 1] [h2 Heading 2] [h3 Heading 3] @@ -1706,29 +1658,29 @@ escape (no processing/formatting) [h5 Heading 5] [h6 Heading 6] - - Heading 1 + Heading + 1 - - Heading 2 + Heading + 2 - - Heading 3 + Heading + 3 - - Heading 4 + Heading + 4 - - Heading 5 + Heading + 5 - - Heading 6 + Heading + 6 Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized @@ -1739,7 +1691,6 @@ escape (no processing/formatting) 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] @@ -1754,7 +1705,6 @@ escape (no processing/formatting) In cases when you don't want to care about the heading level (1 to 6), you can use the Generic Heading: - [heading Heading] @@ -1767,7 +1717,6 @@ escape (no processing/formatting) 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] @@ -1781,7 +1730,6 @@ escape (no processing/formatting) 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] @@ -1799,7 +1747,6 @@ escape (no processing/formatting)
<link linkend="quickbook.syntax.block.macros">Macros</link> - [def macro_identifier some text] @@ -1809,7 +1756,6 @@ escape (no processing/formatting) 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 @@ -1841,7 +1787,6 @@ sf_logo Some more examples: - [def :-) [$theme/smiley.png]] [def __spirit__ [@http://spirit.sourceforge.net Spirit]] @@ -1852,7 +1797,6 @@ sf_logo Invoking these macros: - Hi __spirit__ :-) @@ -1964,16 +1908,15 @@ sf_logo Example template: - [template person[name age what] Hi, my name is [name]. I am [age] years old. I am a [what]. ] - - Template + Template Identifier @@ -1993,9 +1936,9 @@ Hi, my name is [name]. I am [age] years old. I am a [what]. - - Formal + Formal Template Arguments @@ -2013,9 +1956,8 @@ Hi, my name is [name]. I am [age] years old. I am a [what]. and what are actually templates that exist in the duration of the template call. - - Template + Template Body @@ -2023,13 +1965,11 @@ Hi, my name is [name]. I am [age] years old. I am a [what]. 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... ] @@ -2040,22 +1980,20 @@ replacement text... Phrase templates are typically expanded as part of phrases. Like macros, block level elements are not allowed in phrase templates. - - Template + 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] @@ -2083,22 +2021,19 @@ replacement text... are separated by the double dot ".." and terminated by the close parenthesis. - - Nullary - Templates + Nullary Templates Nullary templates look and act like simple macros. Example: - [template alpha[]'''&#945;'''] [template beta[]'''&#946;'''] Expanding: - Some squigles...[*[alpha][beta]] We have: @@ -2132,14 +2067,12 @@ replacement text... 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: - Here's a quote from [aristotle_quote]. @@ -2157,13 +2090,11 @@ for the journey to old age.]]] use the space escape: "\ ". Example: - [template tag\ _tag] Then expanding: - `struct` x[tag]; @@ -2176,9 +2107,8 @@ for the journey to old age.]]] You have a couple of ways to do it. I personally prefer the explicit empty brackets, though. - - Simple + Simple Arguments @@ -2203,7 +2133,6 @@ for the journey to old age.]]] For example: - [template simple[a b c d] [a][b][c][d]] [simple w x y z] @@ -2223,7 +2152,6 @@ for the journey to old age.]]] QuickBook only tries to get the arguments it needs. For example: - [simple w x y z trail] @@ -2242,7 +2170,6 @@ for the journey to old age.]]] separators. It is possible to combine ".." separators with the argument passing simplification presented above. Example: - [simple what do you think ..m a n?] @@ -2251,9 +2178,9 @@ for the journey to old age.]]] what do you think man? - - Punctuation + Punctuation Templates @@ -2264,25 +2191,21 @@ for the journey to old age.]]] template identifiers. Example: - [template ![bar] <hey>[bar]</hey>] Now, expanding this: - [!baz] We will have: - <hey>baz</hey>
<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 @@ -2319,7 +2242,6 @@ for the journey to old age.]]]
<link linkend="quickbook.syntax.block.tables">Tables</link> - [table A Simple Table [[Heading 1] [Heading 2] [Heading 3]] [[R0-C0] [R0-C1] [R0-C2]] @@ -2414,7 +2336,6 @@ for the journey to old age.]]] 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]] [ @@ -2496,7 +2417,6 @@ for the journey to old age.]]] Here's how to have preformatted blocks of code in a table cell: - [table Table with code [[Comment] [Code]] [ @@ -2539,7 +2459,6 @@ for the journey to old age.]]] - #include <iostream> int main() @@ -2557,7 +2476,6 @@ for the journey to old age.]]]
<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]] @@ -2606,7 +2524,6 @@ for the journey to old age.]]] You can include one QuickBook file from another. The syntax is simply: - [include someother.qbk] @@ -2632,7 +2549,6 @@ for the journey to old age.]]] the id defaults to the filename ("someother", in the example above). You can specify the id like this: - [include:someid someother.qbk] @@ -2655,15 +2571,13 @@ for the journey to old age.]]] QuickBook's import facility provides a nice solution. - - Example + 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] @@ -2671,7 +2585,6 @@ for the journey to old age.]]] The first line: - [import ../test/stub.cpp] @@ -2682,7 +2595,6 @@ for the journey to old age.]]] 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] @@ -2711,7 +2623,6 @@ for the journey to old age.]]] And any quickbook block markup. - std::string foo() { // return 'em, foo man! @@ -2723,7 +2634,6 @@ for the journey to old age.]]] This is the bar function - std::string bar() { // return 'em, bar man! @@ -2733,16 +2643,14 @@ for the journey to old age.]]] Some trailing text here - - Code + 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 //] @@ -2755,21 +2663,18 @@ for the journey to old age.]]] The comment //] ends a code-snippet This too will not be visible in quickbook. - - Special + Special Comments Special comments of the form: - //` some [*quickbook] markup here and: - /*` some [*quickbook] markup here */ @@ -2778,14 +2683,12 @@ for the journey to old age.]]] 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 + Callouts Special comments of the form: - /*< some [*quickbook] markup here >*/ @@ -2795,21 +2698,20 @@ for the journey to old age.]]] for details. Example: - -std::string foo_bar() +std::string foo_bar() { - return "foo-bar"; + return "foo-bar"; } - + The Mythical FooBar. See Foobar for details - + return 'em, foo-bar man! @@ -2927,7 +2829,6 @@ for the journey to old age.]]] - using xsltproc : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" ; @@ -2981,7 +2882,6 @@ for the journey to old age.]]] - using quickbook : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" ; @@ -3001,7 +2901,6 @@ for the journey to old age.]]] role="identifier">xml packages. For example, using apt-get: - sudo apt-get install xsltprc docbook-xsl docbook-xml @@ -3021,7 +2920,6 @@ for the journey to old age.]]] the Boost Build documentation. - using xsltproc ; using boostbook @@ -3071,7 +2969,6 @@ for the journey to old age.]]] - using quickbook : /usr/local/bin/quickbook ; @@ -3120,7 +3017,6 @@ for the journey to old age.]]] You can use the following settings to highlight quickbook tags when editing quickbook files. - qbk=*.qbk lexer.*.qbk=props use.tabs.$(qbk)=0 @@ -3146,9 +3042,9 @@ comment.box.end.props=]
<link linkend="quickbook.faq">Frequently Asked Questions</link> - - Can + Can I use QuickBook for non-Boost documentation? @@ -3169,7 +3065,6 @@ comment.box.end.props=] For example: - using quickbook ; xml my_doc : my_doc.qbk ; @@ -3735,7 +3630,6 @@ boostbook standalone - # one # two # three @@ -3755,7 +3649,6 @@ boostbook standalone - * one * two * three @@ -3996,7 +3889,6 @@ boostbook standalone - [table Title [[a][b][c]] [[a][b][c]] @@ -4016,7 +3908,6 @@ boostbook standalone - [variablelist Title [[a][b]] [[a][b]] diff --git a/test/section_1_5-unclosed.gold b/test/section_1_5-unclosed.gold new file mode 100644 index 0000000..b86c556 --- /dev/null +++ b/test/section_1_5-unclosed.gold @@ -0,0 +1,10 @@ + + +
+ Unclosed section +
+ <link linkend="unclosed_section.unclosed">Unclosed Section should be closed + with a warning</link> +
+
diff --git a/test/section_1_5-unclosed.quickbook b/test/section_1_5-unclosed.quickbook new file mode 100644 index 0000000..49b70f4 --- /dev/null +++ b/test/section_1_5-unclosed.quickbook @@ -0,0 +1,5 @@ +[article Unclosed section +[quickbook 1.5] +] + +[section:unclosed Unclosed Section should be closed with a warning] \ No newline at end of file diff --git a/test/snippets/pass_thru.gold b/test/snippets/pass_thru.gold index 9889c91..91597d7 100644 --- a/test/snippets/pass_thru.gold +++ b/test/snippets/pass_thru.gold @@ -4,7 +4,6 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> Pass thru test - /*============================================================================= Copyright (c) 2011 Daniel James @@ -15,7 +14,6 @@ - struct Foo{ Foo(); @@ -31,7 +29,6 @@ - def foo: print('foo') diff --git a/test/template-section.gold b/test/template-section.gold index 1b56834..af270ac 100644 --- a/test/template-section.gold +++ b/test/template-section.gold @@ -11,9 +11,8 @@ Hello. - - Just + Just to test id generation diff --git a/test/templates.gold b/test/templates.gold index 9a40d34..46bcb50 100644 --- a/test/templates.gold +++ b/test/templates.gold @@ -36,7 +36,6 @@ wxyz wxyz trail - int main() { std::cout << "Hello, World" << std::endl; @@ -143,7 +142,6 @@ - int main() {} @@ -176,7 +174,6 @@ - int main() {} diff --git a/test/unicode-escape.gold b/test/unicode-escape.gold index 1fe21d3..c2a8859 100644 --- a/test/unicode-escape.gold +++ b/test/unicode-escape.gold @@ -1,9 +1,10 @@
- UTF-8 test + UTF-8 test - Iñtërnâtiônàlizætiøn + Iñtërnâtiônàlizætiøn diff --git a/test/utf-8-bom.gold b/test/utf-8-bom.gold index 77cead1..088b314 100644 --- a/test/utf-8-bom.gold +++ b/test/utf-8-bom.gold @@ -1,9 +1,9 @@
- UTF-8 test + UTF-8 test - Iñtërnâtiônàlizætiøn + Iñtërnâtiônàlizætiøn diff --git a/test/utf-8.gold b/test/utf-8.gold index 77cead1..088b314 100644 --- a/test/utf-8.gold +++ b/test/utf-8.gold @@ -1,9 +1,9 @@
- UTF-8 test + UTF-8 test - Iñtërnâtiônàlizætiøn + Iñtërnâtiônàlizætiøn