|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r75845 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-12-07 04:21:12
Author: danieljames
Date: 2011-12-07 04:21:11 EST (Wed, 07 Dec 2011)
New Revision: 75845
URL: http://svn.boost.org/trac/boost/changeset/75845
Log:
Quickbook: Small documentation improvements.
- Use `heading` rather than `h3` in changelog.
- Improve code block documentation.
- Update line break info.
- I'm pretty sure quickbook isn't Turing complete.
- Not just C++ syntax highlight any more.
Text files modified:
trunk/tools/quickbook/doc/block.qbk | 2
trunk/tools/quickbook/doc/change_log.qbk | 14 +++++-----
trunk/tools/quickbook/doc/phrase.qbk | 47 ++++++++++++++++++++++++++++-----------
3 files changed, 42 insertions(+), 21 deletions(-)
Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk (original)
+++ trunk/tools/quickbook/doc/block.qbk 2011-12-07 04:21:11 EST (Wed, 07 Dec 2011)
@@ -256,7 +256,7 @@
[section Preformatted]
-Sometimes, you don't want some preformatted text to be parsed as C++. In such
+Sometimes, you don't want some preformatted text to be parsed as source code. In such
cases, use the [^\[pre ... \]] markup block.
```
Modified: trunk/tools/quickbook/doc/change_log.qbk
==============================================================================
--- trunk/tools/quickbook/doc/change_log.qbk (original)
+++ trunk/tools/quickbook/doc/change_log.qbk 2011-12-07 04:21:11 EST (Wed, 07 Dec 2011)
@@ -14,11 +14,11 @@
[source-mode teletype]
]
-[h3:version_1_1 Version 1.1 - Boost 1.33.0]
+[heading:version_1_1 Version 1.1 - Boost 1.33.0]
* First version to be included in boost.
-[h3:version_1_3 Version 1.3 - Boost 1.34.0 to 1.34.1]
+[heading:version_1_3 Version 1.3 - Boost 1.34.0 to 1.34.1]
* Quickbook file inclusion \[include\].
* Better xml output (pretty layout). Check out the generated XML.
@@ -49,7 +49,7 @@
* Post-processor bug fix for escaped XML code that it does not recognize.
* Replaceable, with the \[~replacement\] syntax.
-[h3:version_1_4 Version 1.4 - Boost 1.35.0 to 1.40.0]
+[heading:version_1_4 Version 1.4 - Boost 1.35.0 to 1.40.0]
* Generic Headers
* Code changes to allow full recursion (i.e. Collectors and push/pop functions)
@@ -70,7 +70,7 @@
* Searching of included and imported files in an extensible search path with
`--include-path` (`-I`) option.
-[h3:version_1_5 Version 1.5 - Boost 1.41.0 to 1.42.0]
+[heading:version_1_5 Version 1.5 - Boost 1.41.0 to 1.42.0]
* Support multiple copyright entrys in document info.
* Improved SVG support.
@@ -85,7 +85,7 @@
* Accept a space between `section:` and the section id.
* Support table ids.
-[h3 Version 1.5.1 - Boost 1.43.0]
+[heading Version 1.5.1 - Boost 1.43.0]
* Improve the post processor's list of block elements. `table`, `entry` and
`varlistentry` are treated as blocks. `replaceable` is treated as an inline
@@ -97,7 +97,7 @@
* Add command line flag to define macros at the command line,
e.g. `quickbook "-D__italic_foo__=/foo/"`.
-[h3 Version 1.5.2 - Boost 1.44.0]
+[heading Version 1.5.2 - Boost 1.44.0]
* Use the cygwin 1.7 API for better path handling.
* Improved boostbook generation:
@@ -127,7 +127,7 @@
* Correctly restore the quickbook version switch after including a file
with a different version.
-[h3 Version 1.5.3 - Boost 1.45.0]
+[heading Version 1.5.3 - Boost 1.45.0]
* Fix command line flag for defining macros.
* Fix a couple of issues with the code block parser:
Modified: trunk/tools/quickbook/doc/phrase.qbk
==============================================================================
--- trunk/tools/quickbook/doc/phrase.qbk (original)
+++ trunk/tools/quickbook/doc/phrase.qbk 2011-12-07 04:21:11 EST (Wed, 07 Dec 2011)
@@ -190,11 +190,11 @@
allow formatting with newlines, spaces, and tabs. These are lost.
We provide a phrase level markup that is a mix between the two. By using the
-double-tick, instead of the single-tick, we are telling QuickBook to use
-preformatted blocks of code. Example:
+double-tick or triple-tick, instead of the single-tick, we are telling QuickBook
+to use preformatted blocks of code. Example:
-[pre
-\`\`
+```
+``\`\` ``
#include <iostream>
int main()
@@ -202,11 +202,27 @@
std::cout << "Hello, World!" << std::endl;
return 0;
}
-\`\`
-]
+``\`\`\ ``
+```
+
+or:
+
+```
+``\`\`\` ``
+ #include <iostream>
+
+ int main()
+ {
+ std::cout << "Hello, World!" << std::endl;
+ return 0;
+ }
+``\`\`\` ``
+```
will generate:
+[c++]
+
``
#include <iostream>
@@ -217,6 +233,8 @@
}
``
+[teletype]
+
[endsect] [/Code blocks]
[section Source Mode]
@@ -254,16 +272,19 @@
[endsect] [/Source Mode]
+[#ref-line-break]
[section line-break]
```
[br]
```
-[warning `[br]` is now deprecated. __blurbs__, __admonitions__ and
-table cells (see __tables__) may now contain paragraphs.]
+[warning `[br]` generates invalid docbook. It seems to mostly work okay but
+there might be problems, especially when using an alternative docbook
+processor.]
+
+[endsect] [/Line break]
-[endsect]
[section Anchors]
```
@@ -278,7 +299,7 @@
quickbook documentation. Be careful to avoid clashes with anchors in
other sections.
-[endsect] [/Line break]
+[endsect] [/Anchors]
[section Links]
@@ -418,8 +439,8 @@
`\n` has a special meaning. It is used to generate line breaks.
-[warning `\n` and `[br]` are now deprecated. __blurbs__, __admonitions__
-and table cells (see __tables__) may now contain paragraphs.]
+[warning `\n` is now deprecated, use [link ref-line-break `[br]`]
+instead. Although, use it sparingly as it can generated invalid docbook]
The escaped space: `\ ` also has a special meaning. The escaped space is removed
from the output.
@@ -520,6 +541,6 @@
[? __to_be__ To be or not to be]
-Yes![footnote Conditional Generation makes quickbook turing complete.]
+Yes!
[endsect] [/Condition Generation]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk