Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r76972 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2012-02-11 07:34:11

Author: danieljames
Date: 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
New Revision: 76972

Quickbook: Use anchors for linking to syntax.

Will make restructuring documentation easier.
Text files modified:
   trunk/tools/quickbook/doc/block.qbk | 32 +++++++++++++-
   trunk/tools/quickbook/doc/phrase.qbk | 24 ++++++++++
   trunk/tools/quickbook/doc/quickbook.qbk | 82 ++++++++++++++++++++--------------------
   trunk/tools/quickbook/doc/structure.qbk | 8 ++
   trunk/tools/quickbook/doc/syntax.qbk | 2
   5 files changed, 98 insertions(+), 50 deletions(-)

Modified: trunk/tools/quickbook/doc/block.qbk
--- trunk/tools/quickbook/doc/block.qbk (original)
+++ trunk/tools/quickbook/doc/block.qbk 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
@@ -14,6 +14,7 @@
     [source-mode teletype]
 [section:xinclude xinclude]
 You can include another XML file with:
@@ -27,6 +28,7 @@
 [endsect] [/xinclude]
 [section:paragraphs Paragraphs]
 Paragraphs start left-flushed and are terminated by two or more newlines. No
@@ -38,7 +40,9 @@
 [endsect] [/paragraphs]
 [section:lists Lists]
 [section:ordered_lists Ordered lists]
@@ -54,6 +58,7 @@
 # Three
 [endsect] [/ordered_lists]
 [section:list_hierarchies List Hierarchies]
 List hierarchies are supported. Example:
@@ -87,6 +92,7 @@
 # Five
 [endsect] [/list_hierarchies]
 [section:long_list_lines Long List Lines]
 Long lines will be wrapped appropriately. Example:
@@ -110,6 +116,7 @@
 # A short item.
 [endsect] [/long_list_lines]
 [section:unordered_lists Unordered lists]
@@ -125,6 +132,7 @@
 * Third
 [endsect] [/unordered_lists]
 [section:mixed_lists Mixed lists]
 Mixed lists (ordered and unordered) are supported. Example:
@@ -184,6 +192,7 @@
 [endsect] [/mixed_lists]
 [endsect] [/lists]
 [section:code Code]
 Preformatted code starts with a space or a tab. The code will be
@@ -229,6 +238,7 @@
 [endsect] [/code]
 [section:escape_back Escaping Back To QuickBook]
 Inside code, code blocks and inline code, QuickBook does not allow any
@@ -254,6 +264,7 @@
 [endsect] [/escaping_back_to_quickbook]
 [section:preformatted Preformatted]
 Sometimes, you don't want some preformatted text to be parsed as source code. In such
@@ -290,6 +301,7 @@
 [endsect] [/preformatted]
 [section:blockquote Blockquote]
@@ -300,6 +312,7 @@
 [endsect] [/blockquote]
 [section:admonitions Admonitions]
@@ -324,6 +337,7 @@
 [endsect] [/admonitions]
 [section:headings Headings]
@@ -358,6 +372,7 @@
 [endsect] [/headings]
 [section:generic_heading Generic Heading]
 In cases when you don't want to care about the heading level (1 to 6), you
@@ -404,6 +419,7 @@
 [endsect] [/generic_heading]
 [section:macros Macros]
@@ -457,6 +473,7 @@
 [endsect] [/macros]
 [section:predefined_macros Predefined Macros]
 Quickbook has some predefined macros that you can already use.
@@ -470,6 +487,7 @@
 [endsect] [/predefined_macros]
 [section:templates Templates]
 Templates provide a more versatile text substitution mechanism. Templates
@@ -496,6 +514,7 @@
 [heading Template Identifier]
 Template identifiers can either consist of:
@@ -513,7 +532,7 @@
 C/C++ identifier.
 A template formal argument temporarily hides a template of the same name at
-the point where the [link quickbook.syntax.block.templates.template_expansion
+the point where the [link quickbook.ref.template_expansion
 template is expanded]. Note that the body of the [^person] template above
 refers to [^name] [^age] and [^what] as [^\[name\]] [^\[age\]] and
 [^\[what\]]. [^name] [^age] and [^what] are actually templates that exist
@@ -620,7 +639,7 @@
 The difference with macros are
-* The explicit [link quickbook.syntax.block.templates.template_expansion
+* The explicit [link quickbook.ref.template_expansion
   template expansion syntax]. This is an advantage because, now, we don't
   have to use obscure naming conventions like double underscores (e.g.
   \_\_alpha\_\_) to avoid unwanted
@@ -729,7 +748,7 @@
 in QuickBook (as a qbk library). For that to happen, we need to accommodate
 single character punctuation templates which are fairly common in
 QuickBook. You might have noticed that single character punctuations are
-allowed as [link quickbook.syntax.block.templates.template_identifier
+allowed as [link quickbook.ref.template_identifier
 template identifiers]. Example:
@@ -750,6 +769,7 @@
 [endsect] [/templates]
 [section:blurbs Blurbs]
@@ -772,11 +792,12 @@
     (EBNF) completely in C++.
-[note Prefer [link quickbook.syntax.block.admonitions admonitions] wherever
+[note Prefer [link quickbook.ref.admonitions admonitions] wherever
 [endsect] [/blurbs]
 [section:tables Tables]
@@ -901,6 +922,7 @@
 [endsect] [/tables]
 [section:variable_lists Variable Lists]
@@ -934,6 +956,7 @@
 [endsect] [/variable_lists]
 [section:include Include]
 You can include one QuickBook file from another. The syntax is simply:
@@ -965,6 +988,7 @@
 [endsect] [/include]
 [section:import Import]
 When documenting code, you'd surely need to present code from actual source

Modified: trunk/tools/quickbook/doc/phrase.qbk
--- trunk/tools/quickbook/doc/phrase.qbk (original)
+++ trunk/tools/quickbook/doc/phrase.qbk 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
@@ -14,6 +14,7 @@
     [source-mode teletype]
 [section:font_styles Font Styles]
@@ -36,6 +37,7 @@
 [endsect] [/font_styles]
 [section:replaceable Replaceable]
 When you want content that may or must be replaced by the user, use the syntax:
@@ -50,6 +52,7 @@
 [endsect] [/replaceable]
 [section:quotations Quotations]
@@ -78,6 +81,7 @@
 [endsect] [/quotations]
 [section:simple_formatting Simple formatting]
 Simple markup for formatting text, common in many applications, is now supported:
@@ -161,6 +165,7 @@
 [endsect] [/simple_formatting]
 [section:inline_code Inline code]
 Inlining code in paragraphs is quite common when writing C++ documentation. We
@@ -181,6 +186,7 @@
 [endsect] [/inline_code]
 [section:code_blocks Code blocks]
 Preformatted code simply starts with a space or a tab (See __code__).
@@ -237,6 +243,7 @@
 [endsect] [/code_blocks]
 [section:source_mode Source Mode]
 If a document contains more than one type of source code then the source
@@ -272,7 +279,7 @@
 [endsect] [/source_mode]
 [section:line_break line-break]
@@ -285,6 +292,7 @@
 [endsect] [/line_break]
 [section:anchors Anchors]
@@ -301,6 +309,7 @@
 [endsect] [/anchors]
 [section:links Links]
@@ -341,6 +350,7 @@
 [endsect] [/links]
 [section:anchor_links Anchor links]
 You can link within a document using:
@@ -353,6 +363,7 @@
 [endsect] [/anchor_links]
 [section:refentry_links refentry links]
 In addition, you can link internally to an XML refentry like:
@@ -374,6 +385,7 @@
 [endsect] [/refentry_links]
 [section:code_links Code Links]
 If you want to link to a function, class, member, enum, concept, global, or header in
@@ -402,6 +414,7 @@
 [endsect] [/code_links]
 [section:escape Escape]
 The escape mark-up is used when we don't want to do any processing.
@@ -429,6 +442,7 @@
 [endsect] [/escape]
 [section:single_char_escape Single char escape]
 The backslash may be used to escape a single punctuation character. The
@@ -439,7 +453,7 @@
 `\n` has a special meaning. It is used to generate line breaks.
-[warning `\n` is now deprecated, use [link ref-line-break `[br]`]
+[warning `\n` is now deprecated, use [link quickbook.ref.line_break `[br]`]
 instead. Although, use it sparingly as it can generated invalid docbook]
 The escaped space: `\ ` also has a special meaning. The escaped space is removed
@@ -447,6 +461,7 @@
 [endsect] [/single_char_escape]
 [section:unicode_escape Unicode escape]
 You can enter any 16-bit unicode character by using `\u` followed by its 4 digit
@@ -465,6 +480,7 @@
 [endsect] [/unicode_escape]
 [section:images Images]
@@ -481,6 +497,7 @@
 [endsect] [/images]
 [section:footnotes Footnotes]
 As of version 1.3, QuickBook supports footnotes. Just put the text of the
@@ -495,6 +512,7 @@
 [endsect] [/footnotes]
 [section:macro_expansion Macro Expansion]
@@ -505,6 +523,7 @@
 [endsect] [/macro_expansion]
 [section:template_expansion Template Expansion]
@@ -515,6 +534,7 @@
 [endsect] [/template_expansion]
 [section:cond Conditional Generation]
 Like C++ `#ifdef`, you can generate phrases depending on the presence of

Modified: trunk/tools/quickbook/doc/quickbook.qbk
--- trunk/tools/quickbook/doc/quickbook.qbk (original)
+++ trunk/tools/quickbook/doc/quickbook.qbk 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
@@ -37,49 +37,49 @@
 [def __boostbook__ [@ BoostBook]]
 [def __docbook__ [@ DocBook]]
-[def __comments__ [link quickbook.syntax.comments Comments]]
+[def __comments__ [link quickbook.ref.comments Comments]]
-[def __font_styles__ [link quickbook.syntax.phrase.font_styles Font Styles]]
-[def __quotations__ [link quickbook.syntax.phrase.quotations Quotations]]
-[def __replaceable__ [link quickbook.syntax.phrase.replaceable Replaceble]]
-[def __simple_formatting__ [link quickbook.syntax.phrase.simple_formatting Simple formatting]]
-[def __inline_code__ [link quickbook.syntax.phrase.inline_code Inline code]]
-[def __code_blocks__ [link quickbook.syntax.phrase.code_blocks Code blocks]]
-[def __source_mode__ [link quickbook.syntax.phrase.source_mode Source Mode]]
-[def __line_break__ [link quickbook.syntax.phrase.line_break line-break]]
-[def __anchors__ [link quickbook.syntax.phrase.anchors Anchors]]
-[def __links__ [link quickbook.syntax.phrase.links Links]]
-[def __anchor_links__ [link quickbook.syntax.phrase.anchor_links Anchor links]]
-[def __refentry_links__ [link quickbook.syntax.phrase.refentry_links refentry links]]
-[def __code_links__ [link quickbook.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
-[def __escape__ [link quickbook.syntax.phrase.escape Escape]]
-[def __single_char_escape__ [link quickbook.syntax.phrase.single_char_escape Single char escape]]
-[def __images__ [link quickbook.syntax.phrase.images Images]]
-[def __cond__ [link quickbook.syntax.phrase.cond Conditional Generation]]
+[def __font_styles__ [link quickbook.ref.font_styles Font Styles]]
+[def __quotations__ [link quickbook.ref.quotations Quotations]]
+[def __replaceable__ [link quickbook.ref.replaceable Replaceble]]
+[def __simple_formatting__ [link quickbook.ref.simple_formatting Simple formatting]]
+[def __inline_code__ [link quickbook.ref.inline_code Inline code]]
+[def __code_blocks__ [link quickbook.ref.code_blocks Code blocks]]
+[def __source_mode__ [link quickbook.ref.source_mode Source Mode]]
+[def __line_break__ [link quickbook.ref.line_break line-break]]
+[def __anchors__ [link quickbook.ref.anchors Anchors]]
+[def __links__ [link quickbook.ref.links Links]]
+[def __anchor_links__ [link quickbook.ref.anchor_links Anchor links]]
+[def __refentry_links__ [link quickbook.ref.refentry_links refentry links]]
+[def __code_links__ [link quickbook.ref.code_links function, class, member, enum, macro, concept or header links]]
+[def __escape__ [link quickbook.ref.escape Escape]]
+[def __single_char_escape__ [link quickbook.ref.single_char_escape Single char escape]]
+[def __images__ [link quickbook.ref.images Images]]
+[def __cond__ [link quickbook.ref.cond Conditional Generation]]
-[def __document__ [link quickbook.syntax.structure.docinfo Document]]
-[def __section__ [link quickbook.syntax.structure.section Section]]
-[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]]
-[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]]
-[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
-[def __list_hierarchies__ [link quickbook.syntax.block.lists.list_hierarchies List Hierarchies]]
-[def __long_list_lines__ [link quickbook.syntax.block.lists.long_list_lines Long List Lines]]
-[def __unordered_lists__ [link quickbook.syntax.block.lists.unordered_lists Unordered lists]]
-[def __mixed_lists__ [link quickbook.syntax.block.lists.mixed_lists Mixed lists]]
-[def __code__ [link quickbook.syntax.block.code Code]]
-[def __escape_back__ [link quickbook.syntax.block.escape_back Escaping Back To QuickBook]]
-[def __preformatted__ [link quickbook.syntax.block.preformatted Preformatted]]
-[def __blockquote__ [link quickbook.syntax.block.blockquote Blockquote]]
-[def __heading__ [link quickbook.syntax.block.headings Heading]]
-[def __macros__ [link quickbook.syntax.block.macros Macros]]
-[def __templates__ [link quickbook.syntax.block.templates Templates]]
-[def __predefined_macros__ [link quickbook.syntax.block.predefined_macros Predefined Macros]]
-[def __blurbs__ [link quickbook.syntax.block.blurbs Blurbs]]
-[def __admonitions__ [link quickbook.syntax.block.admonitions Admonitions]]
-[def __tables__ [link quickbook.syntax.block.tables Tables]]
-[def __variable_lists__ [link quickbook.syntax.block.variable_lists Variable Lists]]
-[def __include__ [link quickbook.syntax.block.include Include]]
-[def __import__ [link quickbook.syntax.block.import Import]]
+[def __document__ [link quickbook.ref.docinfo Document]]
+[def __section__ [link quickbook.ref.section Section]]
+[def __xinclude__ [link quickbook.ref.xinclude xinclude]]
+[def __paragraphs__ [link quickbook.ref.paragraphs Paragraphs]]
+[def __ordered_lists__ [link quickbook.ref.ordered_lists Ordered lists]]
+[def __list_hierarchies__ [link quickbook.ref.list_hierarchies List Hierarchies]]
+[def __long_list_lines__ [link quickbook.ref.long_list_lines Long List Lines]]
+[def __unordered_lists__ [link quickbook.ref.unordered_lists Unordered lists]]
+[def __mixed_lists__ [link quickbook.ref.mixed_lists Mixed lists]]
+[def __code__ [link quickbook.ref.code Code]]
+[def __escape_back__ [link quickbook.ref.escape_back Escaping Back To QuickBook]]
+[def __preformatted__ [link quickbook.ref.preformatted Preformatted]]
+[def __blockquote__ [link quickbook.ref.blockquote Blockquote]]
+[def __heading__ [link quickbook.ref.headings Heading]]
+[def __macros__ [link quickbook.ref.macros Macros]]
+[def __templates__ [link quickbook.ref.templates Templates]]
+[def __predefined_macros__ [link quickbook.ref.predefined_macros Predefined Macros]]
+[def __blurbs__ [link quickbook.ref.blurbs Blurbs]]
+[def __admonitions__ [link quickbook.ref.admonitions Admonitions]]
+[def __tables__ [link quickbook.ref.tables Tables]]
+[def __variable_lists__ [link quickbook.ref.variable_lists Variable Lists]]
+[def __include__ [link quickbook.ref.include Include]]
+[def __import__ [link quickbook.ref.import Import]]
 [include introduction.qbk]
 [include change_log.qbk]

Modified: trunk/tools/quickbook/doc/structure.qbk
--- trunk/tools/quickbook/doc/structure.qbk (original)
+++ trunk/tools/quickbook/doc/structure.qbk 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
@@ -7,6 +7,7 @@
 [chapter Document Structure
     [quickbook 1.6]
     [id quickbook.syntax.structure]
@@ -26,7 +27,7 @@
 currently a work in progress and subject to change.
 [section:docinfo Document Info]
 Every document must begin with a Document Info section, which looks something
@@ -73,6 +74,7 @@
 [section:attributes Document Info Attributes]
 The document info block has a few different types of attributes.
@@ -145,6 +147,7 @@
 [endsect] [/docinfo]
 [section:section Sections]
 Quickbook documents are structured using 'sections'. These are used
@@ -173,11 +176,12 @@
 Sections start with the `section` tag, and end with the `[endsect]` tag.
-(`[/...]` is a comment, [link quickbook.syntax.comments described later]).
+(`[/...]` is a comment, [link quickbook.ref.comments described later]).
 Sections can be given an optional id:
 [section:id The Section Title]

Modified: trunk/tools/quickbook/doc/syntax.qbk
--- trunk/tools/quickbook/doc/syntax.qbk (original)
+++ trunk/tools/quickbook/doc/syntax.qbk 2012-02-11 07:34:10 EST (Sat, 11 Feb 2012)
@@ -28,6 +28,7 @@
 such as un-matched closing brackets do not go haywire and corrupt anything past
 a single block.
 [section:comments Comments]
 Can be placed anywhere.
@@ -51,4 +52,3 @@
 [/ for testing [*only ] ]
 [endsect] [/comments]

Boost-Commit list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at