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]
* 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]
[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.
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]
```
[section A]
[h2 X]
-[h2 Y]
+[h2:link_id Y]
[h2 Z]
[endsect]
```
[include someother.qbk]
```
-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 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,
+use [link quickbook.ref.import import] instead.]
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:
+included file. You can specify the id like this:
```
[include:someid someother.qbk]
named anchor for that section will be "someid.intro", and you can link to
it with [^\[link someid.intro The Intro\]].
+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
languish in the archives without maintenance.
QuickBook's import facility provides a nice solution.
+]
[heading Example]
[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]
projects / platform / upstream / boost.git / blobdiff