boost/tools/quickbook/doc/structure.qbk - nest-cam/4320010/boost - Git at Google

 [/
     Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
     Copyright 2010-2011 Daniel James

     Distributed under the Boost Software License, Version 1.0.
     (See accompanying file LICENSE_1_0.txt or copy at
     [@http://www.boost.org/LICENSE_1_0.txt])
 ]

 [chapter Document Structure
     [quickbook 1.6]
     [id quickbook.syntax.structure]
     [source-mode teletype]
 ]

 [/TODO: I started to write this in the syntax chapter, but it was too
 much information, will incorporate into this file.]
 [/
 To avoid breaking old documentation we support using different versions
 of the language, compatibility is not 100% but we try to avoid
 problematic changes. This documentation applies to the current version,
 `[quickbook 1.5]`.

 There is also some mention of the next version `[quickbook 1.6]`. While
 quickbook allows you to use it now, it isn't recommended as it is
 currently a work in progress and subject to change.
 ]

 [#quickbook.ref.docinfo]
 [section:docinfo Document Info]

 Every document must begin with a Document Info section, which looks something
 like this:

 ```
 [article The Document Title
     [quickbook 1.5]
     [version 1.0]
     [id the_document_name]
     [copyright 2000 2002 2003 Joe Blow, Jane Doe]
     [authors [Blow, Joe] [Doe, Jane]]
     [license The document's license]
     [source-mode c++]
 ]
 ```

 `article` is the document type. There are several possible document types,
 most of these are based on docbook document elements. These are fully
 described in
 [@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:

 * [@http://www.docbook.org/tdg/en/html/book.html book]
 * [@http://www.docbook.org/tdg/en/html/article.html article]
 * [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
 * [@http://www.docbook.org/tdg/en/html/part.html part]
 * [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
 * [@http://www.docbook.org/tdg/en/html/preface.html preface]
 * [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
 * [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
 * [@http://www.docbook.org/tdg/en/html/reference.html reference]
 * [@http://www.docbook.org/tdg/en/html/set.html set]

 Boostbook also adds another document type [^[link boostbook.defining library]]
 for documenting software libraries.

 So the documentation for the 'foo' library might start:

 ```
 [library Foo
     [quickbook 1.5]
     [id foo]
     [version 1.0]
 ]
 ```

 [#quickbook.ref.attributes]
 [section:attributes Document Info Attributes]

 The document info block has a few different types of attributes.
 They are all optional.

 [heading Quickbook specific meta data]

 ```
     [quickbook 1.6]
 ```

 The `quickbook` 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 `[quickbook 1.6]` which is the version described here.

 [note

 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 =compatibility-mode=
 attribute to generate similar markup to the old version:

 ```
 [article Article that was original
          written in quickbook 1.3
 [quickbook 1.6]
 [compatibility-mode 1.3]
 ]
 ```

 This feature shouldn't be used for new documents, just for
 porting old documents to the new version.
 ]

 Both the =quickbook= and =compatibility-mode= 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.

 ```
     [source-mode teletype]
 ```

 The `source-mode` attribute sets the initial __source_mode__. If
 it is omitted, the default value of =c++= will be used.

 [heading Boostbook/Docbook root element attributes]

 ```
 [id foo]
 ```

 `id` specifies the id of the document element. If it isn't specified
 the id is automatically generated from the title. This id is also
 used to generate the nested ids.

 ```
 [lang en]
 ```

 `lang` specifies the document language. This is used by docbook to
 localize the documentation. Note that Boostbook doesn't have any
 localization support so if you use it to generate the reference
 documentation it will be in English regardless.

 It should be a language code
 drawn from ISO 639 (perhaps extended with a country code drawn from
 ISO 3166, as en-US).

 ```
 [dirname foo]
 ```

 `dirname` is used to specify the directory name of the library in the
 repository. This is a boostbook extension so it's only valid for
 `library` documentation blocks.  It's used for some boostbook
 functionality, but for pure quickbook documentation has no practical
 effect.

 [heading Docbook Metadata]

 =version=, =copyright=, =authors=,
 =license=, =last-revision= and =bibliod= are optional information.

 [heading Boostbook Metadata]

 =purpose= and =category= are boostbook attributes which are only
 valid for =library= documents. If you use them for other document types,
 quickbook will warn about them, but still use them, generating invalid markup,
 that's just ignored by the style sheets.

 [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]
 [section:section Sections]

 Quickbook documents are structured using 'sections'. These are used
 to generate the table of contents, and, when generating html, to
 split the document into pages. This is optional but a good idea for
 all but the simplest of documents.

 A sectioned document might look like:

 ```
     [book Title
         [quickbook 1.5]
     ]

     [section First Section]

     [/...]

     [endsect]

     [section Second Section]

     [/...]

     [endsect]
 ```

 Sections start with the `section` tag, and end with the `[endsect]` tag.
 (`[/...]` is a comment, [link quickbook.ref.comments described later]).

 Sections can be given an optional id:

 ```
 [#quickbook.ref.id]
 [section:id The Section Title]
 ```

 `id` will be the filename of the generated section.
 If it is not present, "The Section Title" will be normalized and become the id.
 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.
 Thus: "The Section Title" will be normalized to "the_section_title".

 Sections can nest, and that results in a hierarchy in the table of contents.

 [endsect] [/Section]
	[/
	Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
	Copyright 2010-2011 Daniel James

	Distributed under the Boost Software License, Version 1.0.
	(See accompanying file LICENSE_1_0.txt or copy at
	[@http://www.boost.org/LICENSE_1_0.txt])
	]

	[chapter Document Structure
	[quickbook 1.6]
	[id quickbook.syntax.structure]
	[source-mode teletype]
	]

	[/TODO: I started to write this in the syntax chapter, but it was too
	much information, will incorporate into this file.]
	[/
	To avoid breaking old documentation we support using different versions
	of the language, compatibility is not 100% but we try to avoid
	problematic changes. This documentation applies to the current version,
	`[quickbook 1.5]`.

	There is also some mention of the next version `[quickbook 1.6]`. While
	quickbook allows you to use it now, it isn't recommended as it is
	currently a work in progress and subject to change.
	]

	[#quickbook.ref.docinfo]
	[section:docinfo Document Info]

	Every document must begin with a Document Info section, which looks something
	like this:

	```
	[article The Document Title
	[quickbook 1.5]
	[version 1.0]
	[id the_document_name]
	[copyright 2000 2002 2003 Joe Blow, Jane Doe]
	[authors [Blow, Joe] [Doe, Jane]]
	[license The document's license]
	[source-mode c++]
	]
	```

	`article` is the document type. There are several possible document types,
	most of these are based on docbook document elements. These are fully
	described in
	[@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:

	* [@http://www.docbook.org/tdg/en/html/book.html book]
	* [@http://www.docbook.org/tdg/en/html/article.html article]
	* [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
	* [@http://www.docbook.org/tdg/en/html/part.html part]
	* [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
	* [@http://www.docbook.org/tdg/en/html/preface.html preface]
	* [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
	* [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
	* [@http://www.docbook.org/tdg/en/html/reference.html reference]
	* [@http://www.docbook.org/tdg/en/html/set.html set]

	Boostbook also adds another document type [^[link boostbook.defining library]]
	for documenting software libraries.

	So the documentation for the 'foo' library might start:

	```
	[library Foo
	[quickbook 1.5]
	[id foo]
	[version 1.0]
	]
	```

	[#quickbook.ref.attributes]
	[section:attributes Document Info Attributes]

	The document info block has a few different types of attributes.
	They are all optional.

	[heading Quickbook specific meta data]

	```
	[quickbook 1.6]
	```

	The `quickbook` 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 `[quickbook 1.6]` which is the version described here.

	[note

	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 =compatibility-mode=
	attribute to generate similar markup to the old version:

	```
	[article Article that was original
	written in quickbook 1.3
	[quickbook 1.6]
	[compatibility-mode 1.3]
	]
	```

	This feature shouldn't be used for new documents, just for
	porting old documents to the new version.
	]

	Both the =quickbook= and =compatibility-mode= 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.

	```
	[source-mode teletype]
	```

	The `source-mode` attribute sets the initial __source_mode__. If
	it is omitted, the default value of =c++= will be used.

	[heading Boostbook/Docbook root element attributes]

	```
	[id foo]
	```

	`id` specifies the id of the document element. If it isn't specified
	the id is automatically generated from the title. This id is also
	used to generate the nested ids.

	```
	[lang en]
	```

	`lang` specifies the document language. This is used by docbook to
	localize the documentation. Note that Boostbook doesn't have any
	localization support so if you use it to generate the reference
	documentation it will be in English regardless.

	It should be a language code
	drawn from ISO 639 (perhaps extended with a country code drawn from
	ISO 3166, as en-US).

	```
	[dirname foo]
	```

	`dirname` is used to specify the directory name of the library in the
	repository. This is a boostbook extension so it's only valid for
	`library` documentation blocks. It's used for some boostbook
	functionality, but for pure quickbook documentation has no practical
	effect.

	[heading Docbook Metadata]

	=version=, =copyright=, =authors=,
	=license=, =last-revision= and =bibliod= are optional information.

	[heading Boostbook Metadata]

	=purpose= and =category= are boostbook attributes which are only
	valid for =library= documents. If you use them for other document types,
	quickbook will warn about them, but still use them, generating invalid markup,
	that's just ignored by the style sheets.

	[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]
	[section:section Sections]

	Quickbook documents are structured using 'sections'. These are used
	to generate the table of contents, and, when generating html, to
	split the document into pages. This is optional but a good idea for
	all but the simplest of documents.

	A sectioned document might look like:

	```
	[book Title
	[quickbook 1.5]
	]

	[section First Section]

	[/...]

	[endsect]

	[section Second Section]

	[/...]

	[endsect]
	```

	Sections start with the `section` tag, and end with the `[endsect]` tag.
	(`[/...]` is a comment, [link quickbook.ref.comments described later]).

	Sections can be given an optional id:

	```
	[#quickbook.ref.id]
	[section:id The Section Title]
	```

	`id` will be the filename of the generated section.
	If it is not present, "The Section Title" will be normalized and become the id.
	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.
	Thus: "The Section Title" will be normalized to "the_section_title".

	Sections can nest, and that results in a hierarchy in the table of contents.

	[endsect] [/Section]