<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Document Structure</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
-<link rel="up" href="../../quickbook.html" title="Chapter 37. Quickbook 1.5">
+<link rel="up" href="../../quickbook.html" title="Chapter 41. Quickbook 1.6">
<link rel="prev" href="../syntax.html" title="Syntax Summary">
<link rel="next" href="phrase.html" title="Phrase Level Elements">
</head>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="quickbook.syntax.structure"></a>Document Structure</h2></div></div></div>
-<div class="toc"><dl>
+<div class="toc"><dl class="toc">
<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo">Document
Info</a></span></dt>
<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.section">Sections</a></span></dt>
<a name="quickbook.syntax.structure.docinfo"></a><a name="quickbook.ref.docinfo"></a><a class="link" href="structure.html#quickbook.syntax.structure.docinfo" title="Document Info">Document
Info</a>
</h3></div></div></div>
-<div class="toc"><dl><dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo.attributes">Document
- Info Attributes</a></span></dt></dl></div>
+<div class="toc"><dl class="toc">
+<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo.attributes">Document
+ Info Attributes</a></span></dt>
+<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo.nesting">Nesting
+ quickbook documents</a></span></dt>
+</dl></div>
<p>
Every document must begin with a Document Info section, which looks something
like this:
described in <a href="http://www.docbook.org/tdg/" target="_top">DocBook: The Definitive
Guide</a>:
</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a href="http://www.docbook.org/tdg/en/html/book.html" target="_top">book</a>
</li>
</p>
<h5>
<a name="quickbook.syntax.structure.docinfo.attributes.h0"></a>
- <span><a name="quickbook.syntax.structure.docinfo.attributes.quickbook_specific_meta_data"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.quickbook_specific_meta_data">Quickbook
+ <span
class="phrase"><a name="quickbook.syntax.structure.docinfo.attributes.quickbook_specific_meta_data"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.quickbook_specific_meta_data">Quickbook
specific meta data</a>
</h5>
-<pre class="programlisting">[quickbook 1.5]
+<pre class="programlisting">[quickbook 1.6]
</pre>
<p>
The <code class="computeroutput">quickbook</code> 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 <code class="computeroutput">[quickbook 1.5]</code> which is the version
+ recommended that you use <code class="computeroutput">[quickbook 1.6]</code> which is the version
described here.
</p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ 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 <code class="literal">compatibility-mode</code> attribute to generate similar
+ markup to the old version:
+ </p>
+<pre class="programlisting">[article Article that was original
+ written in quickbook 1.3
+[quickbook 1.6]
+[compatibility-mode 1.3]
+]
+</pre>
+<p>
+ This feature shouldn't be used for new documents, just for porting old
+ documents to the new version.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ Both the <code class="literal">quickbook</code> and <code class="literal">compatibility-mode</code>
+ 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.
+ </p>
<pre class="programlisting">[source-mode teletype]
</pre>
<p>
</p>
<h5>
<a name="quickbook.syntax.structure.docinfo.attributes.h1"></a>
- <span><a name="quickbook.syntax.structure.docinfo.attributes.boostbook_docbook_root_element_a"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.boostbook_docbook_root_element_a">Boostbook/Docbook
+ <span
class="phrase"><a name="quickbook.syntax.structure.docinfo.attributes.boostbook_docbook_root_element_a"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.boostbook_docbook_root_element_a">Boostbook/Docbook
root element attributes</a>
</h5>
<pre class="programlisting">[id foo]
</p>
<h5>
<a name="quickbook.syntax.structure.docinfo.attributes.h2"></a>
- <span><a name="quickbook.syntax.structure.docinfo.attributes.docbook_metadata"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.docbook_metadata">Docbook
+ <span
class="phrase"><a name="quickbook.syntax.structure.docinfo.attributes.docbook_metadata"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.docbook_metadata">Docbook
Metadata</a>
</h5>
<p>
</p>
<h5>
<a name="quickbook.syntax.structure.docinfo.attributes.h3"></a>
- <span><a name="quickbook.syntax.structure.docinfo.attributes.boostbook_metadata"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.boostbook_metadata">Boostbook
+ <span
class="phrase"><a name="quickbook.syntax.structure.docinfo.attributes.boostbook_metadata"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.boostbook_metadata">Boostbook
Metadata</a>
</h5>
<p>
style sheets.
</p>
</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="quickbook.syntax.structure.docinfo.nesting"></a><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.nesting" title="Nesting quickbook documents">Nesting
+ quickbook documents</a>
+</h4></div></div></div>
+<p>
+ 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 <a class="link" href="block.html#quickbook.ref.include">include tag</a>
+ 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:
+ </p>
+<pre class="programlisting">[book Simple example
+[quickbook 1.6]
+]
+
+[include introduction.qbk]
+[include chapter.qbk]
+</pre>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Structuring a document like this was introduced in quickbook 1.6, so
+ the <code class="computeroutput">[quickbook 1.6]</code> docinfo field is required.
+ </p></td></tr>
+</table></div>
+<p>
+ The appropriate document type for an introduction is <code class="computeroutput">preface</code>,
+ so the contents of <code class="computeroutput">introduction.qbk</code> should be something like:
+ </p>
+<pre class="programlisting">[preface Introduction
+[quickbook 1.6]
+]
+
+Write the introduction to the book here....
+</pre>
+<p>
+ And <code class="computeroutput">chapter.qbk</code>:
+ </p>
+<pre class="programlisting">[chapter A chapter
+[quickbook 1.6]
+]
+
+Chapter contents....
+</pre>
+</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
projects / platform / upstream / boost.git / blobdiff