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

Subject: [Boost-commit] svn:boost r85406 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2013-08-20 04:57:29

Author: danieljames
Date: 2013-08-20 04:57:29 EDT (Tue, 20 Aug 2013)
New Revision: 85406
URL: http://svn.boost.org/trac/boost/changeset/85406

Log:
Add note about xmlbase.

Text files modified: 
   trunk/tools/quickbook/doc/block.qbk |    32 ++++++++++++++++++++++++++++++++        
   1 files changed, 32 insertions(+), 0 deletions(-)

Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk	Tue Aug 20 04:57:13 2013	(r85405)
+++ trunk/tools/quickbook/doc/block.qbk	2013-08-20 04:57:29 EDT (Tue, 20 Aug 2013)	(r85406)
@@ -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]