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

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

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

Log:
Add explicit ids to heading documentation.

Text files modified: 
   trunk/tools/quickbook/doc/block.qbk |    23 +++++++++++++++++++++--                 
   1 files changed, 21 insertions(+), 2 deletions(-)

Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk	Tue Aug 20 04:56:56 2013	(r85404)
+++ trunk/tools/quickbook/doc/block.qbk	2013-08-20 04:57:13 EDT (Tue, 20 Aug 2013)	(r85405)
@@ -356,7 +356,23 @@
 [h5 Heading 5]
 [h6 Heading 6]
 
-Headings will automatically have anchors with normalized names with
+You can specify an id for a heading:
+
+```
+[h1:heading_id A heading to link to]
+```
+
+To link to it, you'll need to include the enclosing section's id:
+
+```
+[link document_id.section_id.heading_id The link text]
+```
+
+Although you can preceed a heading by an [link quickbook.ref.anchors anchor]
+if you wish to use a location independent link.
+
+If a heading doesn't have an id, one will be automatically generated
+with a normalized name with
 [^name="document_id.section_id.normalized_header_text"] (i.e. 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.
@@ -369,6 +385,9 @@
 
 to link to them. See __anchor_links__ and __section__ for more info.
 
+[note Specifying heading ids is a quickbook 1.6 feature, earlier
+      versions don't support them.]
+
 [endsect] [/headings]
 
 [#quickbook.ref.generic_heading]
@@ -392,7 +411,7 @@
 ```
 [section A]
 [h2 X]
-[h2 Y]
+[h2:link_id Y]
 [h2 Z]
 [endsect]
 ```