1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Document Structure</title> 6<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../../quickbook.html" title="Chapter 50. Quickbook 1.7"> 10<link rel="prev" href="../syntax.html" title="Syntax Summary"> 11<link rel="next" href="phrase.html" title="Phrase Level Elements"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 16<td align="center"><a href="../../../../index.html">Home</a></td> 17<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="../syntax.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="phrase.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="quickbook.syntax.structure"></a>Document Structure</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo">Document 31 Info</a></span></dt> 32<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.section">Sections</a></span></dt> 33</dl></div> 34<div class="section"> 35<div class="titlepage"><div><div><h3 class="title"> 36<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 37 Info</a> 38</h3></div></div></div> 39<div class="toc"><dl class="toc"> 40<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo.attributes">Document 41 Info Attributes</a></span></dt> 42<dt><span class="section"><a href="structure.html#quickbook.syntax.structure.docinfo.nesting">Nesting 43 quickbook documents</a></span></dt> 44</dl></div> 45<p> 46 Every document must begin with a Document Info section, which looks something 47 like this: 48 </p> 49<pre class="programlisting">[article The Document Title 50 [quickbook 1.7] 51 [version 1.0] 52 [id the_document_name] 53 [copyright 2000 2002 2003 Joe Blow, Jane Doe] 54 [authors [Blow, Joe] [Doe, Jane]] 55 [license The document's license] 56 [source-mode c++] 57] 58</pre> 59<p> 60 <code class="computeroutput">article</code> is the document type. There are several possible document 61 types, most of these are based on docbook document elements. These are fully 62 described in <a href="http://www.docbook.org/tdg/" target="_top">DocBook: The Definitive 63 Guide</a>: 64 </p> 65<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 66<li class="listitem"> 67 <a href="http://www.docbook.org/tdg/en/html/book.html" target="_top">book</a> 68 </li> 69<li class="listitem"> 70 <a href="http://www.docbook.org/tdg/en/html/article.html" target="_top">article</a> 71 </li> 72<li class="listitem"> 73 <a href="http://www.docbook.org/tdg/en/html/chapter.html" target="_top">chapter</a> 74 </li> 75<li class="listitem"> 76 <a href="http://www.docbook.org/tdg/en/html/part.html" target="_top">part</a> 77 </li> 78<li class="listitem"> 79 <a href="http://www.docbook.org/tdg/en/html/appendix.html" target="_top">appendix</a> 80 </li> 81<li class="listitem"> 82 <a href="http://www.docbook.org/tdg/en/html/preface.html" target="_top">preface</a> 83 </li> 84<li class="listitem"> 85 <a href="http://www.docbook.org/tdg/en/html/qandadiv.html" target="_top">qandadiv</a> 86 </li> 87<li class="listitem"> 88 <a href="http://www.docbook.org/tdg/en/html/qandaset.html" target="_top">qandaset</a> 89 </li> 90<li class="listitem"> 91 <a href="http://www.docbook.org/tdg/en/html/reference.html" target="_top">reference</a> 92 </li> 93<li class="listitem"> 94 <a href="http://www.docbook.org/tdg/en/html/set.html" target="_top">set</a> 95 </li> 96</ul></div> 97<p> 98 Boostbook also adds another document type <code class="literal"><a class="link" href="../../boostbook/documenting.html#boostbook.defining" title="Defining a BoostBook library">library</a></code> 99 for documenting software libraries. 100 </p> 101<p> 102 So the documentation for the 'foo' library might start: 103 </p> 104<pre class="programlisting">[library Foo 105 [quickbook 1.7] 106 [id foo] 107 [version 1.0] 108] 109</pre> 110<div class="section"> 111<div class="titlepage"><div><div><h4 class="title"> 112<a name="quickbook.syntax.structure.docinfo.attributes"></a><a name="quickbook.ref.attributes"></a><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes" title="Document Info Attributes">Document 113 Info Attributes</a> 114</h4></div></div></div> 115<p> 116 The document info block has a few different types of attributes. They are 117 all optional. 118 </p> 119<h5> 120<a name="quickbook.syntax.structure.docinfo.attributes.h0"></a> 121 <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 122 specific meta data</a> 123 </h5> 124<pre class="programlisting">[quickbook 1.7] 125</pre> 126<p> 127 The <code class="computeroutput">quickbook</code> attribute declares the version of quickbook 128 the document is written for. In its absence, version 1.1 is assumed. It's 129 recommended that you use <code class="computeroutput">[quickbook 1.7]</code> which is the version 130 described here. 131 </p> 132<div class="note"><table border="0" summary="Note"> 133<tr> 134<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td> 135<th align="left">Note</th> 136</tr> 137<tr><td align="left" valign="top"> 138<p> 139 The quickbook version also makes some changes to the markup that's generated. 140 Most notably, the ids that are automatically for headers and sections 141 are different in later versions. To minimise disruption, you can use 142 the <code class="literal">compatibility-mode</code> attribute to generate similar 143 markup to the old version: 144 </p> 145<pre class="programlisting">[article Article that was original 146 written in quickbook 1.3 147[quickbook 1.7] 148[compatibility-mode 1.3] 149] 150</pre> 151<p> 152 This feature shouldn't be used for new documents, just for porting old 153 documents to the new version. 154 </p> 155</td></tr> 156</table></div> 157<p> 158 Both the <code class="literal">quickbook</code> and <code class="literal">compatibility-mode</code> 159 tags can be used at the start of the file, before the document info block, 160 and also in files that don't have a document info block. 161 </p> 162<pre class="programlisting">[source-mode teletype] 163</pre> 164<p> 165 The <code class="computeroutput">source-mode</code> attribute sets the initial <a class="link" href="phrase.html#quickbook.ref.source_mode">Source 166 Mode</a>. If it is omitted, the default value of <code class="literal">c++</code> 167 will be used. 168 </p> 169<h5> 170<a name="quickbook.syntax.structure.docinfo.attributes.h1"></a> 171 <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 172 root element attributes</a> 173 </h5> 174<pre class="programlisting">[id foo] 175</pre> 176<p> 177 <code class="computeroutput">id</code> specifies the id of the document element. If it isn't specified 178 the id is automatically generated from the title. This id is also used 179 to generate the nested ids. 180 </p> 181<pre class="programlisting">[lang en] 182</pre> 183<p> 184 <code class="computeroutput">lang</code> specifies the document language. This is used by docbook 185 to localize the documentation. Note that Boostbook doesn't have any localization 186 support so if you use it to generate the reference documentation it will 187 be in English regardless. 188 </p> 189<p> 190 It should be a language code drawn from ISO 639 (perhaps extended with 191 a country code drawn from ISO 3166, as en-US). 192 </p> 193<pre class="programlisting">[dirname foo] 194</pre> 195<p> 196 <code class="computeroutput">dirname</code> is used to specify the directory name of the library 197 in the repository. This is a boostbook extension so it's only valid for 198 <code class="computeroutput">library</code> documentation blocks. It's used for some boostbook 199 functionality, but for pure quickbook documentation has no practical effect. 200 </p> 201<h5> 202<a name="quickbook.syntax.structure.docinfo.attributes.h2"></a> 203 <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 204 Metadata</a> 205 </h5> 206<p> 207 <code class="literal">version</code>, <code class="literal">copyright</code>, <code class="literal">authors</code>, 208 <code class="literal">license</code>, <code class="literal">last-revision</code> and <code class="literal">bibliod</code> 209 are optional information. 210 </p> 211<h5> 212<a name="quickbook.syntax.structure.docinfo.attributes.h3"></a> 213 <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 214 Metadata</a> 215 </h5> 216<p> 217 <code class="literal">purpose</code> and <code class="literal">category</code> are boostbook 218 attributes which are only valid for <code class="literal">library</code> documents. 219 If you use them for other document types, quickbook will warn about them, 220 but still use them, generating invalid markup, that's just ignored by the 221 style sheets. 222 </p> 223<h5> 224<a name="quickbook.syntax.structure.docinfo.attributes.h4"></a> 225 <span class="phrase"><a name="quickbook.syntax.structure.docinfo.attributes.escaped-docbook"></a></span><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.attributes.escaped-docbook">Escaped 226 Docbook</a> 227 </h5> 228<p> 229 From quickbook 1.7 onwards, <a class="link" href="phrase.html#quickbook.ref.escape">escaped 230 boostbook or docbook</a> can be included in a docinfo block: 231 </p> 232<pre class="programlisting">[article Some article 233[quickbook 1.7] 234'''<author> 235 <firstname>John</firstname> 236 <surname>Doe</surname> 237 <email>john.doe@example.com</email> 238</author>''' 239] 240</pre> 241<p> 242 The escaped docbook is always placed at the end of the docinfo block, so 243 it shouldn't be assumed that it will interleave with markup generated from 244 quickbook. A mixture of quickbook and docbook attributes for the same information 245 will not work well. 246 </p> 247</div> 248<div class="section"> 249<div class="titlepage"><div><div><h4 class="title"> 250<a name="quickbook.syntax.structure.docinfo.nesting"></a><a class="link" href="structure.html#quickbook.syntax.structure.docinfo.nesting" title="Nesting quickbook documents">Nesting 251 quickbook documents</a> 252</h4></div></div></div> 253<p> 254 Docinfo blocks can only appear at the beginning of a quickbook file, so 255 to create a more complicated document you need to use several quickbook 256 files and use the <a class="link" href="block.html#quickbook.ref.include">include tag</a> 257 to nest them. For example, say you wish to create a book with an introduction 258 and a chapter, you first create a file for the book: 259 </p> 260<pre class="programlisting">[book Simple example 261[quickbook 1.7] 262] 263 264[include introduction.qbk] 265[include chapter.qbk] 266</pre> 267<div class="note"><table border="0" summary="Note"> 268<tr> 269<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td> 270<th align="left">Note</th> 271</tr> 272<tr><td align="left" valign="top"><p> 273 Structuring a document like this was introduced in quickbook 1.6, so 274 a <code class="computeroutput">[quickbook 1.6]</code> or later docinfo field is required. 275 </p></td></tr> 276</table></div> 277<p> 278 The appropriate document type for an introduction is <code class="computeroutput">preface</code>, 279 so the contents of <code class="computeroutput">introduction.qbk</code> should be something like: 280 </p> 281<pre class="programlisting">[preface Introduction 282[quickbook 1.7] 283] 284 285Write the introduction to the book here.... 286</pre> 287<p> 288 And <code class="computeroutput">chapter.qbk</code>: 289 </p> 290<pre class="programlisting">[chapter A chapter 291[quickbook 1.7] 292] 293 294Chapter contents.... 295</pre> 296</div> 297</div> 298<div class="section"> 299<div class="titlepage"><div><div><h3 class="title"> 300<a name="quickbook.syntax.structure.section"></a><a name="quickbook.ref.section"></a><a class="link" href="structure.html#quickbook.syntax.structure.section" title="Sections">Sections</a> 301</h3></div></div></div> 302<p> 303 Quickbook documents are structured using 'sections'. These are used to generate 304 the table of contents, and, when generating html, to split the document into 305 pages. This is optional but a good idea for all but the simplest of documents. 306 </p> 307<p> 308 A sectioned document might look like: 309 </p> 310<pre class="programlisting">[book Title 311 [quickbook 1.5] 312] 313 314[section First Section] 315 316[/...] 317 318[endsect] 319 320[section Second Section] 321 322[/...] 323 324[endsect] 325</pre> 326<p> 327 Sections start with the <code class="computeroutput">section</code> tag, and end with the <code class="computeroutput">[endsect]</code> 328 tag. (<code class="computeroutput">[/...]</code> is a comment, <a class="link" href="../syntax.html#quickbook.ref.comments">described 329 later</a>). 330 </p> 331<p> 332 Sections can be given an optional id: 333 </p> 334<pre class="programlisting">[#quickbook.ref.id] 335[section:id The Section Title] 336</pre> 337<p> 338 <code class="computeroutput">id</code> will be the filename of the generated section. If it is not 339 present, "The Section Title" will be normalized and become the 340 id. Valid characters are <code class="literal">a-Z</code>, <code class="literal">A-Z</code>, 341 <code class="literal">0-9</code> and <code class="literal">_</code>. All non-valid characters 342 are converted to underscore and all upper-case are converted to lower case. 343 Thus: "The Section Title" will be normalized to "the_section_title". 344 </p> 345<p> 346 The end of the section can also have an optional id, this is just used to 347 check that it matches the opening of the section. 348 </p> 349<pre class="programlisting">[section:matching Section with an id] 350 351[/...] 352 353[endsect:matching] 354</pre> 355<p> 356 It won't match a generated id, only one that's explicitly specified, so this 357 will be an error, even if quickbook generates the id <code class="computeroutput">generated</code> 358 for the section: 359 </p> 360<pre class="programlisting">[section Generated] 361 362[/...] 363 364[endsect:generated] 365</pre> 366<p> 367 Sections can nest, and that results in a hierarchy in the table of contents. 368 </p> 369</div> 370</div> 371<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 372<td align="left"></td> 373<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman, 374 Eric Niebler<br>Copyright © 2010-2017 Daniel James<p> 375 Distributed under the Boost Software License, Version 1.0. (See accompanying 376 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 377 </p> 378</div></td> 379</tr></table> 380<hr> 381<div class="spirit-nav"> 382<a accesskey="p" href="../syntax.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="phrase.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 383</div> 384</body> 385</html> 386
