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

Subject: [Boost-commit] svn:boost r85407 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2013-08-20 04:57:49

Author: danieljames
Date: 2013-08-20 04:57:49 EDT (Tue, 20 Aug 2013)
New Revision: 85407
URL: http://svn.boost.org/trac/boost/changeset/85407

Log:
Add new elements in 1.6 to the main documentation.

Text files modified: 
   trunk/tools/quickbook/doc/1_6.qbk    |    67 ++------------------------------------- 
   trunk/tools/quickbook/doc/block.qbk  |    54 ++++++++++++++++++++++++++++++++        
   trunk/tools/quickbook/doc/phrase.qbk |    26 +++++++++++++++                         
   3 files changed, 85 insertions(+), 62 deletions(-)

Modified: trunk/tools/quickbook/doc/1_6.qbk
==============================================================================
--- trunk/tools/quickbook/doc/1_6.qbk	Tue Aug 20 04:57:29 2013	(r85406)
+++ trunk/tools/quickbook/doc/1_6.qbk	2013-08-20 04:57:49 EDT (Tue, 20 Aug 2013)	(r85407)
@@ -237,69 +237,12 @@
 
 [section:elements New Elements]
 
-[section:block `block`]
+New elements added in quickbook 1.6:
 
-`block` is a block element that just marks its contents as a block,
-so that they aren't wrapped in paragraph tags. The main use is
-for escaped docbook block tags, such as:
+* [link quickbook.ref.block `block`]
+* [link quickbook.ref.list_tags `ordered_list` and `itemized_list`]
+* [link quickbook.ref.role `role`]
 
-    [template chapter[title]
-    [block'''<chapter><title>'''[title]'''</title>''']
-    ]
-
-    [template chapterend
-    [block'''</chapter>''']
-    ]
-
-    [chapter An example chapter]
-
-    Content
-
-    [chapterend]
-
-Without the `block` element, the `chapter` and `chapterend` templates
-would be wrapped in paragraph tags.
-
-[note In this example, the template body has to start with a newline so that
-the template will be interpreted in block mode.]
-
-[endsect]
-
-[section:lists `ordered_list` and `itemized_list`]
-
-These are used as an alternative to the normal wiki-style markup for
-lists. They make it easier to nest lists inside other elements, and
-nest elements inside lists. The markup is similar to a single level
-table:
-
-    [ordered_list [item1][item2]]
-
-is equivalent to:
-
-    # item1
-    # item2
-
-[endsect]
-
-[section:role `role`]
-
-`role` is a phrase element used to mark up the text in the eventual html
-with an a class. For example:
-
-    [role red Text content]
-
-Will generate the docbook:
-
-    <phrase role="red">Text content</phrase>
-
-Which will generate html along the lines of:
-
-    <span class="red">Text content</span>
-
-And then you can use css to style this however you wish.
-
-[endsect]
-
-[endsect]
+[endsect] [/ elements]
 
 [endsect] [/ Quickbok 1.6]

Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk	Tue Aug 20 04:57:29 2013	(r85406)
+++ trunk/tools/quickbook/doc/block.qbk	2013-08-20 04:57:49 EDT (Tue, 20 Aug 2013)	(r85407)
@@ -222,6 +222,31 @@
             * 2.b.2.b
 
 [endsect] [/mixed_lists]
+
+[#quickbook.ref.list_tags]
+[section:list_tags Explicit list tags]
+
+Sometimes the wiki-style list markup can be tricky to use, especially
+if you wish to include more complicated markup with the list. So in
+quickbook 1.6, an alternative way to mark up lists introduced:
+
+    [ordered_list [item1][item2]]
+
+is equivalent to:
+
+    # item1
+    # item2
+
+And:
+
+    [itemized_list [item1][item2]]
+
+is equivalent to:
+
+    * item1
+    * item2
+
+[endsect] [/list_tags]
 [endsect] [/lists]
 
 [#quickbook.ref.code]
@@ -1254,3 +1279,32 @@
 [@boost:/tools/quickbook/test/stub.cpp tools/quickbook/test/stub.cpp]
 
 [endsect] [/import]
+
+[#quickbook.ref.block]
+[section:block Plain blocks]
+
+`block` is a plain block element, that doesn't wrap its contents
+in any docbook or boostbook tags. This can be useful when using
+escaped docbook block tags, such as:
+
+    [template chapter[title]
+    [block'''<chapter><title>'''[title]'''</title>''']
+    ]
+
+    [template chapterend
+    [block'''</chapter>''']
+    ]
+
+    [chapter An example chapter]
+
+    Content
+
+    [chapterend]
+
+Without the `block` element, the `chapter` and `chapterend` templates
+would be wrapped in paragraph tags.
+
+[note In this example, the template body has to start with a newline so that
+the template will be interpreted in block mode.]
+
+[endsect] [/block]

Modified: trunk/tools/quickbook/doc/phrase.qbk
==============================================================================
--- trunk/tools/quickbook/doc/phrase.qbk	Tue Aug 20 04:57:29 2013	(r85406)
+++ trunk/tools/quickbook/doc/phrase.qbk	2013-08-20 04:57:49 EDT (Tue, 20 Aug 2013)	(r85407)
@@ -165,6 +165,32 @@
 
 [endsect] [/simple_formatting]
 
+[#quickbook.ref.role]
+[section:role Role]
+
+Sometime the basic formatting options aren't enough, and you wish
+to use CSS to style the generated html. For these cases you can
+use the `role` phase element. For example:
+
+    [role red Text content]
+
+Will generate the docbook:
+
+    <phrase role="red">Text content</phrase>
+
+Which will generate html along the lines of:
+
+    <span class="red">Text content</span>
+
+And then you can use css to style this however you wish.
+
+[note When generating other formats such as pdfs, your css is not going to
+      apply, so this will appear as normal, unstyled text. The docbook
+      =role= attribute is meant to be used as a more general mechanism, so
+      you might be able to take advantage of it by some other means.]
+
+[endsect] [/role]
+
 [#quickbook.ref.inline_code]
 [section:inline_code Inline code]