1 files changed, 192 insertions, 0 deletions
diff --git a/tools/quickbook/doc/structure.qbk b/tools/quickbook/doc/structure.qbk
new file mode 100644
index 0000000000..80e812c2f1
--- /dev/null
+++ b/tools/quickbook/doc/structure.qbk
@@ -0,0 +1,192 @@
+[/
+    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.
+]
+
+[#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]
+]
+```
+
+[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.5]
+```
+
+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.5]` which is the version described here.
+
+```
+    [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]
+
+[endsect] [/docinfo]
+
+[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.syntax.comments described later]).
+
+Sections can be given an optional 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]