[Boost-commit] svn:boost r85382 - trunk/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r85382 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2013-08-17 15:01:46

Author: danieljames
Date: 2013-08-17 15:01:46 EDT (Sat, 17 Aug 2013)
New Revision: 85382
URL: http://svn.boost.org/trac/boost/changeset/85382

Log:
Start to document quickbook 1.6 include.

Text files modified: 
   trunk/tools/quickbook/doc/block.qbk     |    13 +++++++++++--                           
   trunk/tools/quickbook/doc/structure.qbk |    37 +++++++++++++++++++++++++++++++++++++   
   2 files changed, 48 insertions(+), 2 deletions(-)

Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk	Sat Aug 17 15:01:27 2013	(r85381)
+++ trunk/tools/quickbook/doc/block.qbk	2013-08-17 15:01:46 EDT (Sat, 17 Aug 2013)	(r85382)
@@ -965,12 +965,18 @@
 [include someother.qbk]
 ```
 
-The included file will be processed as if it had been cut and pasted
+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
 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.
+
+[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. You can specify the id like this:
@@ -984,6 +990,9 @@
 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.
+
 [endsect] [/include]
 
 [#quickbook.ref.import]

Modified: trunk/tools/quickbook/doc/structure.qbk
==============================================================================
--- trunk/tools/quickbook/doc/structure.qbk	Sat Aug 17 15:01:27 2013	(r85381)
+++ trunk/tools/quickbook/doc/structure.qbk	2013-08-17 15:01:46 EDT (Sat, 17 Aug 2013)	(r85382)
@@ -144,6 +144,43 @@
 
 [endsect] [/attributes]
 
+[section:nesting Nesting quickbook documents]
+
+Docinfo blocks can only appear at the beginning of a quickbook file, so to
+create a more complicated document you need to use several quickbook files and
+use the [link quickbook.ref.include include tag] to nest them. For example, say
+you wish to create a book with an introduction and a chapter, you first create
+a file for the book:
+
+    [book Simple example
+    [quickbook 1.6]
+    ]
+
+    [include introduction.qbk]
+    [include chapter.qbk]
+
+[note Structuring a document like this was introduced in quickbook 1.6, so the
+`[quickbook 1.6]` docinfo field is required.]
+
+The appropriate document type for an introduction is `preface`, so
+the contents of `introduction.qbk` should be something like:
+
+    [preface Introduction
+    [quickbook 1.6]
+    ]
+
+    Write the introduction to the book here....
+
+And `chapter.qbk`:
+
+    [chapter A chapter
+    [quickbook 1.6]
+    ]
+
+    Chapter contents....
+
+[endsect] [/nesting]
+
 [endsect] [/docinfo]
 
 [#quickbook.ref.section]