|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r85409 - in branches/release/tools/quickbook: . doc
From: dnljms_at_[hidden]
Date: 2013-08-20 13:22:58
Author: danieljames
Date: 2013-08-20 13:22:58 EDT (Tue, 20 Aug 2013)
New Revision: 85409
URL: http://svn.boost.org/trac/boost/changeset/85409
Log:
Merge quickbook to release.
Just documentation changes for 1.6.
Properties modified:
branches/release/tools/quickbook/ (props changed)
Text files modified:
branches/release/tools/quickbook/doc/1_6.qbk | 67 +-------------
branches/release/tools/quickbook/doc/block.qbk | 182 ++++++++++++++++++++++++++++++++++++++-
branches/release/tools/quickbook/doc/phrase.qbk | 26 +++++
branches/release/tools/quickbook/doc/structure.qbk | 28 +++++
4 files changed, 231 insertions(+), 72 deletions(-)
Modified: branches/release/tools/quickbook/doc/1_6.qbk
==============================================================================
--- branches/release/tools/quickbook/doc/1_6.qbk Tue Aug 20 05:03:29 2013 (r85408)
+++ branches/release/tools/quickbook/doc/1_6.qbk 2013-08-20 13:22:58 EDT (Tue, 20 Aug 2013) (r85409)
@@ -237,69 +237,12 @@
[section:elements New Elements]
-[section:block `block`]
+New elements added in quickbook 1.6:
-`block` is a block element that just marks its contents as a block,
-so that they aren't wrapped in paragraph tags. The main use is
-for escaped docbook block tags, such as:
+* [link quickbook.ref.block `block`]
+* [link quickbook.ref.list_tags `ordered_list` and `itemized_list`]
+* [link quickbook.ref.role `role`]
- [template chapter[title]
- [block'''<chapter><title>'''[title]'''</title>''']
- ]
-
- [template chapterend
- [block'''</chapter>''']
- ]
-
- [chapter An example chapter]
-
- Content
-
- [chapterend]
-
-Without the `block` element, the `chapter` and `chapterend` templates
-would be wrapped in paragraph tags.
-
-[note In this example, the template body has to start with a newline so that
-the template will be interpreted in block mode.]
-
-[endsect]
-
-[section:lists `ordered_list` and `itemized_list`]
-
-These are used as an alternative to the normal wiki-style markup for
-lists. They make it easier to nest lists inside other elements, and
-nest elements inside lists. The markup is similar to a single level
-table:
-
- [ordered_list [item1][item2]]
-
-is equivalent to:
-
- # item1
- # item2
-
-[endsect]
-
-[section:role `role`]
-
-`role` is a phrase element used to mark up the text in the eventual html
-with an a class. For example:
-
- [role red Text content]
-
-Will generate the docbook:
-
- <phrase role="red">Text content</phrase>
-
-Which will generate html along the lines of:
-
- <span class="red">Text content</span>
-
-And then you can use css to style this however you wish.
-
-[endsect]
-
-[endsect]
+[endsect] [/ elements]
[endsect] [/ Quickbok 1.6]
Modified: branches/release/tools/quickbook/doc/block.qbk
==============================================================================
--- branches/release/tools/quickbook/doc/block.qbk Tue Aug 20 05:03:29 2013 (r85408)
+++ branches/release/tools/quickbook/doc/block.qbk 2013-08-20 13:22:58 EDT (Tue, 20 Aug 2013) (r85409)
@@ -26,6 +26,38 @@
This is useful when file.xml has been generated by Doxygen and contains your
reference section.
+=xinclude= paths are normally used unchanged in the generated documentation,
+which will not work if you wish them to be relative to the current quickbook
+file. Quickbook can add a =xml:base= attribute to the boostbook documentation
+to specify where =xinclude= files should be found. For example, if you wish
+them to be relative to the current quickbook file:
+
+ [article Article with xincludes
+ [quickbook 1.6]
+ [xmlbase .]
+ ]
+
+ [xinclude file.xml]
+
+Now the xinclude should work if =file.xml= is in the same directory as the
+quickbook file. Although it might not work if you distribute the generated
+files (as their relative directories can change).
+
+Say the article is generated in a sub-directory, by running something like:
+
+ quickbook article.qbk --output-file=output/article.xml
+
+This will generate a boostbook root tag:
+
+ <article id="article_with_xincludes"
+ last-revision="$Date: 2013/08/20 08:26:48 $"
+ xml:base=".."
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+Because =xml:base= is set to =..=, the xml processor will know to look in
+the parent directory to find =file.xml=, which it comes across the
+=xi:include= tag.
+
[endsect] [/xinclude]
[#quickbook.ref.paragraphs]
@@ -190,6 +222,31 @@
* 2.b.2.b
[endsect] [/mixed_lists]
+
+[#quickbook.ref.list_tags]
+[section:list_tags Explicit list tags]
+
+Sometimes the wiki-style list markup can be tricky to use, especially
+if you wish to include more complicated markup with the list. So in
+quickbook 1.6, an alternative way to mark up lists introduced:
+
+ [ordered_list [item1][item2]]
+
+is equivalent to:
+
+ # item1
+ # item2
+
+And:
+
+ [itemized_list [item1][item2]]
+
+is equivalent to:
+
+ * item1
+ * item2
+
+[endsect] [/list_tags]
[endsect] [/lists]
[#quickbook.ref.code]
@@ -356,8 +413,23 @@
[h5 Heading 5]
[h6 Heading 6]
-Headings 1-3 \[h1 h2 and h3\] will automatically have anchors with
-normalized names with
+You can specify an id for a heading:
+
+```
+[h1:heading_id A heading to link to]
+```
+
+To link to it, you'll need to include the enclosing section's id:
+
+```
+[link document_id.section_id.heading_id The link text]
+```
+
+Although you can preceed a heading by an [link quickbook.ref.anchors anchor]
+if you wish to use a location independent link.
+
+If a heading doesn't have an id, one will be automatically generated
+with a normalized name with
[^name="document_id.section_id.normalized_header_text"] (i.e. valid
characters are =a-z=, =A-Z=, =0-9= and =_=. All non-valid characters are
converted to underscore and all upper-case are converted to lower-case.
@@ -370,6 +442,9 @@
to link to them. See __anchor_links__ and __section__ for more info.
+[note Specifying heading ids is a quickbook 1.6 feature, earlier
+ versions don't support them.]
+
[endsect] [/headings]
[#quickbook.ref.generic_heading]
@@ -393,7 +468,7 @@
```
[section A]
[h2 X]
-[h2 Y]
+[h2:link_id Y]
[h2 Z]
[endsect]
```
@@ -965,14 +1040,18 @@
[include someother.qbk]
```
-If the included file has a [link quickbook.ref.docinfo docinfo block] then it
-will create a nested document. Otherwise the included file will be processed
-as if it had been cut and pasted
+In quickbook 1.6 and later, if the included file has a
+[link quickbook.ref.docinfo docinfo block] then it will create a nested
+document. This will be processed as a standalone document, although any macros
+or templates from the enclosing file will still be defined.
+
+Otherwise 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 or templates defined in the included file are scoped to that file.
+* Any macros or templates defined in the included file are scoped to that file,
+ i.e. they are not added to the enclosing file.
[note In quickbook 1.5 and earlier templates weren't scoped in included files.
If you want to use templates or macros from a file in quickbook 1.6,
@@ -993,11 +1072,67 @@
If the included file has a docinfo block, an id specified in an [^\[include\]]
directive will overwrite it.
+You can also include C, C++ and python source files. This will include any
+quickbook blocks in the file that aren't inside of named code snippets. See
+the [link quickbook.ref.import Import section] for syntax details. For example,
+say you included this file:
+
+ /**
+ * Hello world example
+ */
+
+ // In this comment, the backtick indicates that this is a
+ // quickbook source block that will be included.
+
+ /*`
+ First include the appropriate header: [hello_includes]
+ Then write your main function: [hello_main]
+ */
+
+ // This defines a code snippet, the syntax is
+ // described in the import section. It's available
+ // in the whole of this source file, not just after
+ // its definition.
+
+ //[hello_includes
+ #include <iostream>
+ //]
+
+ //[hello_main
+ int main() {
+ std::cout << "Hello, trivial example" << std::endl;
+ }
+ //]
+
+It will generate:
+
+ First include the appropriate header:
+
+ #include <iostream>
+
+ Then write your main function:
+
+ int main() {
+ std::cout << "Hello, trivial example" << std::endl;
+ }
+
[endsect] [/include]
[#quickbook.ref.import]
[section:import Import]
+In quickbook 1.6 and later if you wish to use a template, macro or code
+snippet from a file, you need to import it. This will not include any
+of the content from that file, but will pull templates, macros and code
+snippets into the current file's scope.
+
+With quickbook files, this allows you to create template and macro
+libraries. For python (indicated by the `.py` extension), C or
+C++ files this allows you to include code snippets from source files,
+so that your code examples can be kept up to date and fully tested.
+
+[/ Old justification text, might move this into a new section:
+
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
@@ -1006,6 +1141,7 @@
languish in the archives without maintenance.
QuickBook's import facility provides a nice solution.
+]
[heading Example]
@@ -1139,6 +1275,36 @@
[class_]
-See the actual code here: [@boost:/tools/quickbook/test/stub.cpp]
+See the actual code here:
+[@boost:/tools/quickbook/test/stub.cpp tools/quickbook/test/stub.cpp]
[endsect] [/import]
+
+[#quickbook.ref.block]
+[section:block Plain blocks]
+
+`block` is a plain block element, that doesn't wrap its contents
+in any docbook or boostbook tags. This can be useful when using
+escaped docbook block tags, such as:
+
+ [template chapter[title]
+ [block'''<chapter><title>'''[title]'''</title>''']
+ ]
+
+ [template chapterend
+ [block'''</chapter>''']
+ ]
+
+ [chapter An example chapter]
+
+ Content
+
+ [chapterend]
+
+Without the `block` element, the `chapter` and `chapterend` templates
+would be wrapped in paragraph tags.
+
+[note In this example, the template body has to start with a newline so that
+the template will be interpreted in block mode.]
+
+[endsect] [/block]
Modified: branches/release/tools/quickbook/doc/phrase.qbk
==============================================================================
--- branches/release/tools/quickbook/doc/phrase.qbk Tue Aug 20 05:03:29 2013 (r85408)
+++ branches/release/tools/quickbook/doc/phrase.qbk 2013-08-20 13:22:58 EDT (Tue, 20 Aug 2013) (r85409)
@@ -165,6 +165,32 @@
[endsect] [/simple_formatting]
+[#quickbook.ref.role]
+[section:role Role]
+
+Sometime the basic formatting options aren't enough, and you wish
+to use CSS to style the generated html. For these cases you can
+use the `role` phase element. For example:
+
+ [role red Text content]
+
+Will generate the docbook:
+
+ <phrase role="red">Text content</phrase>
+
+Which will generate html along the lines of:
+
+ <span class="red">Text content</span>
+
+And then you can use css to style this however you wish.
+
+[note When generating other formats such as pdfs, your css is not going to
+ apply, so this will appear as normal, unstyled text. The docbook
+ =role= attribute is meant to be used as a more general mechanism, so
+ you might be able to take advantage of it by some other means.]
+
+[endsect] [/role]
+
[#quickbook.ref.inline_code]
[section:inline_code Inline code]
Modified: branches/release/tools/quickbook/doc/structure.qbk
==============================================================================
--- branches/release/tools/quickbook/doc/structure.qbk Tue Aug 20 05:03:29 2013 (r85408)
+++ branches/release/tools/quickbook/doc/structure.qbk 2013-08-20 13:22:58 EDT (Tue, 20 Aug 2013) (r85409)
@@ -82,13 +82,37 @@
[heading Quickbook specific meta data]
```
- [quickbook 1.5]
+ [quickbook 1.6]
```
The `quickbook` attribute declares the version of quickbook
the document is written for.
In its absence, version 1.1 is assumed. It's recommended that
-you use `[quickbook 1.5]` which is the version described here.
+you use `[quickbook 1.6]` which is the version described here.
+
+[note
+
+The quickbook version also makes some changes to the markup
+that's generated. Most notably, the ids that are automatically
+for headers and sections are different in later versions. To
+minimise disruption, you can use the =compatibility-mode=
+attribute to generate similar markup to the old version:
+
+```
+[article Article that was original
+ written in quickbook 1.3
+[quickbook 1.6]
+[compatibility-mode 1.3]
+]
+```
+
+This feature shouldn't be used for new documents, just for
+porting old documents to the new version.
+]
+
+Both the =quickbook= and =compatibility-mode= tags can be used
+at the start of the file, before the document info block, and
+also in files that don't have a document info block.
```
[source-mode teletype]
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