|
|
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
URL: http://svn.boost.org/trac/boost/changeset/76972
Log:
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]
]
+[#quickbook.ref.xinclude]
[section:xinclude xinclude]
You can include another XML file with:
@@ -27,6 +28,7 @@
[endsect] [/xinclude]
+[#quickbook.ref.paragraphs]
[section:paragraphs Paragraphs]
Paragraphs start left-flushed and are terminated by two or more newlines. No
@@ -38,7 +40,9 @@
[endsect] [/paragraphs]
+[#quickbook.ref.lists]
[section:lists Lists]
+[#quickbook.ref.ordered_lists]
[section:ordered_lists Ordered lists]
[pre
@@ -54,6 +58,7 @@
# Three
[endsect] [/ordered_lists]
+[#quickbook.ref.list_hierarchies]
[section:list_hierarchies List Hierarchies]
List hierarchies are supported. Example:
@@ -87,6 +92,7 @@
# Five
[endsect] [/list_hierarchies]
+[#quickbook.ref.long_list_lines]
[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]
+[#quickbook.ref.unordered_lists]
[section:unordered_lists Unordered lists]
```
@@ -125,6 +132,7 @@
* Third
[endsect] [/unordered_lists]
+[#quickbook.ref.mixed_lists]
[section:mixed_lists Mixed lists]
Mixed lists (ordered and unordered) are supported. Example:
@@ -184,6 +192,7 @@
[endsect] [/mixed_lists]
[endsect] [/lists]
+[#quickbook.ref.code]
[section:code Code]
Preformatted code starts with a space or a tab. The code will be
@@ -229,6 +238,7 @@
[endsect] [/code]
+[#quickbook.ref.escape_back]
[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]
+[#quickbook.ref.preformatted]
[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]
+[#quickbook.ref.blockquote]
[section:blockquote Blockquote]
[pre
@@ -300,6 +312,7 @@
[endsect] [/blockquote]
+[#quickbook.ref.admonitions]
[section:admonitions Admonitions]
```
@@ -324,6 +337,7 @@
[endsect] [/admonitions]
+[#quickbook.ref.headings]
[section:headings Headings]
```
@@ -358,6 +372,7 @@
[endsect] [/headings]
+[#quickbook.ref.generic_heading]
[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]
+[#quickbook.ref.macros]
[section:macros Macros]
```
@@ -457,6 +473,7 @@
[endsect] [/macros]
+[#quickbook.ref.predefined_macros]
[section:predefined_macros Predefined Macros]
Quickbook has some predefined macros that you can already use.
@@ -470,6 +487,7 @@
[endsect] [/predefined_macros]
+[#quickbook.ref.templates]
[section:templates Templates]
Templates provide a more versatile text substitution mechanism. Templates
@@ -496,6 +514,7 @@
]
+[#quickbook.ref.template_identifier]
[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]
+[#quickbook.ref.blurbs]
[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
appropriate.]
[endsect] [/blurbs]
+[#quickbook.ref.tables]
[section:tables Tables]
```
@@ -901,6 +922,7 @@
[endsect] [/tables]
+[#quickbook.ref.variable_lists]
[section:variable_lists Variable Lists]
```
@@ -934,6 +956,7 @@
[endsect] [/variable_lists]
+[#quickbook.ref.include]
[section:include Include]
You can include one QuickBook file from another. The syntax is simply:
@@ -965,6 +988,7 @@
[endsect] [/include]
+[#quickbook.ref.import]
[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]
]
+[#quickbook.ref.font_styles]
[section:font_styles Font Styles]
```
@@ -36,6 +37,7 @@
[endsect] [/font_styles]
+[#quickbook.ref.replaceable]
[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]
+[#quickbook.ref.quotations]
[section:quotations Quotations]
```
@@ -78,6 +81,7 @@
[endsect] [/quotations]
+[#quickbook.ref.simple_formatting]
[section:simple_formatting Simple formatting]
Simple markup for formatting text, common in many applications, is now supported:
@@ -161,6 +165,7 @@
[endsect] [/simple_formatting]
+[#quickbook.ref.inline_code]
[section:inline_code Inline code]
Inlining code in paragraphs is quite common when writing C++ documentation. We
@@ -181,6 +186,7 @@
[endsect] [/inline_code]
+[#quickbook.ref.code_blocks]
[section:code_blocks Code blocks]
Preformatted code simply starts with a space or a tab (See __code__).
@@ -237,6 +243,7 @@
[endsect] [/code_blocks]
+[#quickbook.ref.source_mode]
[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]
-[#ref-line-break]
+[#quickbook.ref.line_break]
[section:line_break line-break]
```
@@ -285,6 +292,7 @@
[endsect] [/line_break]
+[#quickbook.ref.anchors]
[section:anchors Anchors]
```
@@ -301,6 +309,7 @@
[endsect] [/anchors]
+[#quickbook.ref.links]
[section:links Links]
```
@@ -341,6 +350,7 @@
[endsect] [/links]
+[#quickbook.ref.anchor_links]
[section:anchor_links Anchor links]
You can link within a document using:
@@ -353,6 +363,7 @@
[endsect] [/anchor_links]
+[#quickbook.ref.refentry_links]
[section:refentry_links refentry links]
In addition, you can link internally to an XML refentry like:
@@ -374,6 +385,7 @@
[endsect] [/refentry_links]
+[#quickbook.ref.code_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]
+[#quickbook.ref.escape]
[section:escape Escape]
The escape mark-up is used when we don't want to do any processing.
@@ -429,6 +442,7 @@
[endsect] [/escape]
+[#quickbook.ref.single_char_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]
+[#quickbook.ref.unicode_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]
+[#quickbook.ref.images]
[section:images Images]
```
@@ -481,6 +497,7 @@
[endsect] [/images]
+[#quickbook.ref.footnotes]
[section:footnotes Footnotes]
As of version 1.3, QuickBook supports footnotes. Just put the text of the
@@ -495,6 +512,7 @@
[endsect] [/footnotes]
+[#quickbook.ref.macro_expansion]
[section:macro_expansion Macro Expansion]
```
@@ -505,6 +523,7 @@
[endsect] [/macro_expansion]
+[#quickbook.ref.template_expansion]
[section:template_expansion Template Expansion]
```
@@ -515,6 +534,7 @@
[endsect] [/template_expansion]
+[#quickbook.ref.cond]
[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__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
[def __docbook__ [@http://www.docbook.org/ 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 @@
[@http://www.boost.org/LICENSE_1_0.txt])
]
+[#quickbook.ref.structure]
[chapter Document Structure
[quickbook 1.6]
[id quickbook.syntax.structure]
@@ -26,7 +27,7 @@
currently a work in progress and subject to change.
]
-[#ref-docinfo]
+[#quickbook.ref.docinfo]
[section:docinfo Document Info]
Every document must begin with a Document Info section, which looks something
@@ -73,6 +74,7 @@
]
```
+[#quickbook.ref.attributes]
[section:attributes Document Info Attributes]
The document info block has a few different types of attributes.
@@ -145,6 +147,7 @@
[endsect] [/docinfo]
+[#quickbook.ref.section]
[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:
```
+[#quickbook.ref.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.
+[#quickbook.ref.comments]
[section:comments Comments]
Can be placed anywhere.
@@ -51,4 +52,3 @@
[/ for testing [*only ] ]
[endsect] [/comments]
-
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk