townforge/quickbook
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Quickbook: Use anchors for linking to syntax.

Browse Source 
Will make restructuring documentation easier.

[SVN r76972]
This commit is contained in:
Daniel James 2012-02-11 12:34:10 +00:00
parent d525c56f60
commit fe883c5b76
5 changed files with 98 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/block.qbk
View File

@ -14,6 +14,7 @@
[source-mode teletype]
]
[#quickbook.ref.xinclude]
[section:xinclude xinclude]
You can include another XML file with:
@ -27,6 +28,7 @@ reference section.
[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 @@ This is a new paragraph...
[endsect] [/paragraphs]
[#quickbook.ref.lists]
[section:lists Lists]
[#quickbook.ref.ordered_lists]
[section:ordered_lists Ordered lists]
[pre
@ -54,6 +58,7 @@ will generate:
# Three
[endsect] [/ordered_lists]
[#quickbook.ref.list_hierarchies]
[section:list_hierarchies List Hierarchies]
List hierarchies are supported. Example:
@ -87,6 +92,7 @@ will generate:
# 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 @@ Long lines will be wrapped appropriately. Example:
# A short item.
[endsect] [/long_list_lines]
[#quickbook.ref.unordered_lists]
[section:unordered_lists Unordered lists]
```
@ -125,6 +132,7 @@ will generate:
* 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 @@ will generate:
[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 @@ Generates:
[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 @@ allowed. Block level markups like lists, tables etc. are not allowed.
[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 @@ inside =pre= blocks.
[endsect] [/preformatted]
[#quickbook.ref.blockquote]
[section:blockquote Blockquote]
[pre
@ -300,6 +312,7 @@ inside =pre= blocks.
[endsect] [/blockquote]
[#quickbook.ref.admonitions]
[section:admonitions Admonitions]
```
@ -324,6 +337,7 @@ to produce the desired effect.
[endsect] [/admonitions]
[#quickbook.ref.headings]
[section:headings Headings]
```
@ -358,6 +372,7 @@ to link to them. See __anchor_links__ and __section__ for more info.
[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 @@ redundant. /h1/../h6/ might be deprecated in the future.
[endsect] [/generic_heading]
[#quickbook.ref.macros]
[section:macros Macros]
```
@ -457,6 +473,7 @@ Hi __spirit__ :-)
[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 @@ Quickbook has some predefined macros that you can already use.
[endsect] [/predefined_macros]
[#quickbook.ref.templates]
[section:templates Templates]
Templates provide a more versatile text substitution mechanism. Templates
@ -496,6 +514,7 @@ Hi, my name is [name]. I am [age] years old. I am a [what].
]
[#quickbook.ref.template_identifier]
[heading Template Identifier]
Template identifiers can either consist of:
@ -513,7 +532,7 @@ alphanumeric characters or the underscore. This is similar to your typical
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 @@ Some squiggles...[*[alpha][beta]]
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 @@ With templates, one of our objectives is to allow us to rewrite QuickBook
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 @@ We will have:
[endsect] [/templates]
[#quickbook.ref.blurbs]
[section:blurbs Blurbs]
```
@ -772,11 +792,12 @@ will generate this:
(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 @@ Here's how to have preformatted blocks of code in a table cell:
[endsect] [/tables]
[#quickbook.ref.variable_lists]
[section:variable_lists Variable Lists]
```
@ -934,6 +956,7 @@ will recognize this as a "definition list".
[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 @@ it with [^\[link someid.intro The Intro\]].
[endsect] [/include]
[#quickbook.ref.import]
[section:import Import]
When documenting code, you'd surely need to present code from actual source

24
doc/phrase.qbk
View File

@ -14,6 +14,7 @@
[source-mode teletype]
]
[#quickbook.ref.font_styles]
[section:font_styles Font Styles]
```
@ -36,6 +37,7 @@ will generate:
[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 @@ This will generate:
[endsect] [/replaceable]
[#quickbook.ref.quotations]
[section:quotations Quotations]
```
@ -78,6 +81,7 @@ That's the true business precept.]
[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 @@ And one for the little boy who lives down the lane.
[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 @@ single quote: `"'"`. Note too that [^\`some code\`] is preferred over
[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 @@ will generate:
[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 @@ C++ comment `// looks like this` whereas a Python comment [python]
[endsect] [/source_mode]
[#ref-line-break]
[#quickbook.ref.line_break]
[section:line_break line-break]
```
@ -285,6 +292,7 @@ processor.]
[endsect] [/line_break]
[#quickbook.ref.anchors]
[section:anchors Anchors]
```
@ -301,6 +309,7 @@ other sections.
[endsect] [/anchors]
[#quickbook.ref.links]
[section:links Links]
```
@ -341,6 +350,7 @@ Note that this is only available when using BoostBook, and only for links
[endsect] [/links]
[#quickbook.ref.anchor_links]
[section:anchor_links Anchor links]
You can link within a document using:
@ -353,6 +363,7 @@ See sections __section__ and __heading__ for more info.
[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 @@ This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].
[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 @@ would have "boost::bar::baz" as the link text.
[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 @@ __boostbook__/__docbook__ syntax.]
[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 @@ For example, how do you escape the triple quote? Simple: [^\\'\\'\\']
`\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 @@ from the output.
[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 @@ will generate:
[endsect] [/unicode_escape]
[#quickbook.ref.images]
[section:images Images]
```
@ -481,6 +497,7 @@ DocBook imagedata attributes]:
[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 @@ will generate this[footnote A sample footnote].
[endsect] [/footnotes]
[#quickbook.ref.macro_expansion]
[section:macro_expansion Macro Expansion]
```
@ -505,6 +523,7 @@ See __macros__ for details.
[endsect] [/macro_expansion]
[#quickbook.ref.template_expansion]
[section:template_expansion Template Expansion]
```
@ -515,6 +534,7 @@ See __templates__ for details.
[endsect] [/template_expansion]
[#quickbook.ref.cond]
[section:cond Conditional Generation]
Like C++ `#ifdef`, you can generate phrases depending on the presence of

82
doc/quickbook.qbk
View File

@ -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]

8
doc/structure.qbk
View File

@ -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 @@ quickbook allows you to use it now, it isn't recommended as it is
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 @@ So the documentation for the 'foo' library might start:
]
```
[#quickbook.ref.attributes]
[section:attributes Document Info Attributes]
The document info block has a few different types of attributes.
@ -145,6 +147,7 @@ that's just ignored by the style sheets.
[endsect] [/docinfo]
[#quickbook.ref.section]
[section:section Sections]
Quickbook documents are structured using 'sections'. These are used
@ -173,11 +176,12 @@ A sectioned document might look like:
```
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]
```

2
doc/syntax.qbk
View File

@ -28,6 +28,7 @@ Phrases in each block cannot contain a block terminator. This way, syntax errors
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 @@ Can be placed anywhere.
[/ for testing [*only ] ]
[endsect] [/comments]