[Boost-commit] svn:boost r68900 - branches/doc-tools-docs/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r68900 - branches/doc-tools-docs/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-02-14 20:18:27

Author: danieljames
Date: 2011-02-14 20:18:26 EST (Mon, 14 Feb 2011)
New Revision: 68900
URL: http://svn.boost.org/trac/boost/changeset/68900

Log:
Make the section documentation fit its new location better.
Text files modified: 
   branches/doc-tools-docs/tools/quickbook/doc/syntax.qbk |    40 +++++++++++++++++++++++++++++++---------
   1 files changed, 31 insertions(+), 9 deletions(-)

Modified: branches/doc-tools-docs/tools/quickbook/doc/syntax.qbk
==============================================================================
--- branches/doc-tools-docs/tools/quickbook/doc/syntax.qbk	(original)
+++ branches/doc-tools-docs/tools/quickbook/doc/syntax.qbk	2011-02-14 20:18:26 EST (Mon, 14 Feb 2011)
@@ -107,26 +107,48 @@
 
 [endsect] [/docinfo]
 
-[section Section]
+[section:section Sections]
 
-Starting a new section is accomplished with:
+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]
 ''']
 
-where /id/ is optional. id will be the filename of the generated section.
+`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".
 
-End a section with:
-
-[pre'''
-[endsect]
-''']
-
 Sections can nest, and that results in a hierarchy in the table of contents.
 
 [endsect] [/Section]