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

Subject: [Boost-commit] svn:boost r68894 - branches/doc-tools-docs/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-02-14 20:15:10

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

Log:
Add a description of using a quickbook template to generate a link.
Text files modified: 
   branches/doc-tools-docs/tools/quickbook/doc/Jamfile.v2 |     2 +-                                      
   branches/doc-tools-docs/tools/quickbook/doc/block.qbk  |    25 +++++++++++++++++++++++++               
   2 files changed, 26 insertions(+), 1 deletions(-)

Modified: branches/doc-tools-docs/tools/quickbook/doc/Jamfile.v2
==============================================================================
--- branches/doc-tools-docs/tools/quickbook/doc/Jamfile.v2	(original)
+++ branches/doc-tools-docs/tools/quickbook/doc/Jamfile.v2	2011-02-14 20:15:09 EST (Mon, 14 Feb 2011)
@@ -10,7 +10,7 @@
 
 project boost/quickbook/doc ;
 
-import boostbook : boostbook ;
+using boostbook ;
 using quickbook ;
 
 xml quickbook : quickbook.qbk ;

Modified: branches/doc-tools-docs/tools/quickbook/doc/block.qbk
==============================================================================
--- branches/doc-tools-docs/tools/quickbook/doc/block.qbk	(original)
+++ branches/doc-tools-docs/tools/quickbook/doc/block.qbk	2011-02-14 20:15:09 EST (Mon, 14 Feb 2011)
@@ -642,6 +642,31 @@
 quickbook.phrase QuickBook phrase]. Arguments are separated by the
 double dot [^".."] and terminated by the close parenthesis.
 
+Note that templates and template parameters can't be expanded
+everywhere, only where text is interpreted as a phrase. So they can't be
+expanded in places such as table titles and link's urls. If you want to
+use a template to generate a link based of the template parameter, you
+can't use a normal link and will need to use escaped docbook instead.
+Example:
+
+[teletype]
+```
+[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
+
+[boost_ticket 2035]
+```
+
+will expand to:
+
+[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
+
+[boost_ticket 2035]
+
+[caution Since quickbook doesn't understand the context where the
+parameter is being used, it will interpret it as quickbook markup, so
+when writing a template like this, you'll need to escape any meaningful
+punctuation.]
+
 [heading Nullary Templates]
 
 Nullary templates look and act like simple macros. Example: