[Boost-commit] svn:boost r67889 - trunk/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r67889 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-01-09 16:15:14

Author: danieljames
Date: 2011-01-09 16:15:12 EST (Sun, 09 Jan 2011)
New Revision: 67889
URL: http://svn.boost.org/trac/boost/changeset/67889

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

Modified: trunk/tools/quickbook/doc/syntax.qbk
==============================================================================
--- trunk/tools/quickbook/doc/syntax.qbk	(original)
+++ trunk/tools/quickbook/doc/syntax.qbk	2011-01-09 16:15:12 EST (Sun, 09 Jan 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]