[Boost-commit] svn:boost r72079 - branches/quickbook-dev/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r72079 - branches/quickbook-dev/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-05-22 11:35:10

Author: danieljames
Date: 2011-05-22 11:35:09 EDT (Sun, 22 May 2011)
New Revision: 72079
URL: http://svn.boost.org/trac/boost/changeset/72079

Log:
Quickbook: separate structure from syntax.

The structure information will get more complex with differences
between 1.5 and 1.6, and full attribute documentation. The syntax
section could be expanded to be a more useful introduction and to link
to the various parts of the reference documentation.
Added:
   branches/quickbook-dev/tools/quickbook/doc/structure.qbk
      - copied, changed from r72078, /branches/quickbook-dev/tools/quickbook/doc/syntax.qbk
Text files modified: 
   branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk |     5                                         
   branches/quickbook-dev/tools/quickbook/doc/structure.qbk |    60 -------------                           
   branches/quickbook-dev/tools/quickbook/doc/syntax.qbk    |   168 --------------------------------------- 
   3 files changed, 7 insertions(+), 226 deletions(-)

Modified: branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk
==============================================================================
--- branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk	2011-05-22 11:35:09 EDT (Sun, 22 May 2011)
@@ -41,8 +41,8 @@
 [def __images__             [link quickbook.phrase.images Images]]
 [def __cond__               [link quickbook.phrase.cond Conditional Generation]]
 
-[def __document__           [link quickbook.syntax.docinfo Document]]
-[def __section__            [link quickbook.syntax.section Section]]
+[def __document__           [link quickbook.structure.docinfo Document]]
+[def __section__            [link quickbook.structure.section Section]]
 [def __xinclude__           [link quickbook.block.xinclude  xinclude]]
 [def __paragraphs__         [link quickbook.block.paragraphs Paragraphs]]
 [def __ordered_lists__      [link quickbook.block.lists.ordered_lists Ordered lists]]
@@ -68,6 +68,7 @@
 [include intro.qbk]
 [include change_log.qbk]
 [include syntax.qbk]
+[include structure.qbk]
 [include phrase.qbk]
 [include block.qbk]
 [include install.qbk]

Copied: branches/quickbook-dev/tools/quickbook/doc/structure.qbk (from r72078, /branches/quickbook-dev/tools/quickbook/doc/syntax.qbk)
==============================================================================
--- /branches/quickbook-dev/tools/quickbook/doc/syntax.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/structure.qbk	2011-05-22 11:35:09 EDT (Sun, 22 May 2011)
@@ -7,44 +7,12 @@
     [@http://www.boost.org/LICENSE_1_0.txt])
 ]
 
-[chapter Syntax Summary
+[chapter Document Structure
     [quickbook 1.5]
-    [id quickbook.syntax]
+    [id quickbook.structure]
     [source-mode teletype]
 ]
 
-A simple quickbook document might look something like:
-
-[pre'''
-    [book A sweet little horror story
-        [quickbook 1.5]
-        [author Brown, Fredric]
-    ]
-    
-    The last man on Earth sat alone in a room. There was a knock on
-    the door...
-''']
-
-The document starts with the
-[link quickbook.syntax.docinfo document info block].
-This describes the type of the document, it's title and document
-metadata. In this case just the version of quickbook to be used.
-
-This is then followed by one or more blocks. An example of
-a block is the paragraph or a C++ code snippet. In this example we just
-have a single paragraph. Some blocks have
-special mark-ups. Blocks, except code snippets which have their own
-grammar (C++ or Python), are composed of one or more phrases. A phrase
-can be a simple contiguous run of characters. Phrases can have special
-mark-ups. Marked up phrases can recursively contain other phrases, but
-cannot contain blocks. A terminal is a self contained block-level or
-phrase-level element that does not nest anything.
-
-Blocks, in general, are delimited by two end-of-lines (the block terminator).
-Phrases in each block cannot contain a block terminator. This way, syntax errors
-such as un-matched closing brackets do not go haywire and corrupt anything past
-a single block.
-
 [section:docinfo Document Info]
 
 Every document must begin with a Document Info section, which looks something
@@ -208,27 +176,3 @@
 Sections can nest, and that results in a hierarchy in the table of contents.
 
 [endsect] [/Section]
-
-[section Comments]
-
-Can be placed anywhere.
-
-[pre
-'''[/ comment (no output generated) ]'''
-]
-
-[/ for testing only... ]
-
-[pre
-'''[/ comments can be nested [/ some more here] ]'''
-]
-
-[/ for testing [/ only ] ]
-
-[pre
-'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
-]
-
-[/ for testing [*only ] ]
-
-[endsect] [/Comments]

Modified: branches/quickbook-dev/tools/quickbook/doc/syntax.qbk
==============================================================================
--- branches/quickbook-dev/tools/quickbook/doc/syntax.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/syntax.qbk	2011-05-22 11:35:09 EDT (Sun, 22 May 2011)
@@ -7,7 +7,7 @@
     [@http://www.boost.org/LICENSE_1_0.txt])
 ]
 
-[chapter Syntax Summary
+[chapter Basic Syntax
     [quickbook 1.5]
     [id quickbook.syntax]
     [source-mode teletype]
@@ -26,7 +26,7 @@
 ''']
 
 The document starts with the
-[link quickbook.syntax.docinfo document info block].
+[link quickbook.structure.docinfo document info block].
 This describes the type of the document, it's title and document
 metadata. In this case just the version of quickbook to be used.
 
@@ -45,170 +45,6 @@
 such as un-matched closing brackets do not go haywire and corrupt anything past
 a single block.
 
-[section:docinfo Document Info]
-
-Every document must begin with a Document Info section, which looks something
-like this:
-
-[pre'''
-[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:
-
-[pre'''
-[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]
-
-[pre'''
-    [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.
-
-[pre'''
-    [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]
-
-[pre'''
-[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.
-
-[pre'''
-[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).
-
-[pre'''
-[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:
-
-[pre'''
-    [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:
-
-[pre'''
-[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]
-
 [section Comments]
 
 Can be placed anywhere.