Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r85288 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2013-08-10 15:18:25

Next message: dsaritz_at_[hidden]: "[Boost-commit] svn:boost r85290 - in sandbox/gil/boost/gil/extension/io2: backends/detail backends/libtiff backends/wic detail devices"
Previous message: dnljms_at_[hidden]: "[Boost-commit] svn:boost r85289 - in trunk/tools/quickbook: src test"

Author: danieljames
Date: 2013-08-10 15:18:25 EDT (Sat, 10 Aug 2013)
New Revision: 85288
URL: http://svn.boost.org/trac/boost/changeset/85288

Log:
Split up the language version chapter.

Added:
   trunk/tools/quickbook/doc/1_7.qbk (contents, props changed)
   trunk/tools/quickbook/doc/language_versions.qbk (contents, props changed)
Text files modified:
   trunk/tools/quickbook/doc/1_6.qbk | 204 ---------------------------------------
   trunk/tools/quickbook/doc/1_7.qbk | 175 ++++++++++++++++++++++++++++++++++
   trunk/tools/quickbook/doc/language_versions.qbk | 46 +++++++++
   trunk/tools/quickbook/doc/quickbook.qbk | 3
   4 files changed, 224 insertions(+), 204 deletions(-)

Modified: trunk/tools/quickbook/doc/1_6.qbk
==============================================================================
--- trunk/tools/quickbook/doc/1_6.qbk Sat Aug 10 15:17:51 2013 (r85287)
+++ trunk/tools/quickbook/doc/1_6.qbk 2013-08-10 15:18:25 EDT (Sat, 10 Aug 2013) (r85288)
@@ -1,47 +1,12 @@
[/
     Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
- Copyright 2010-2011 Daniel James
+ Copyright 2010-2013 Daniel James

     Distributed under the Boost Software License, Version 1.0.
     (See accompanying file LICENSE_1_0.txt or copy at
     http://www.boost.org/LICENSE_1_0.txt)
]

-[chapter Language Versions
- [quickbook 1.7]
- [compatibility-mode 1.5]
- [id quickbook.versions]
- [source-mode teletype]
-]
-
-[section:stable Stable Versions]
-
-Since quickbook 1.3 the `quickbook` attribute in the document block selects
-which version of the language to use. Not all changes to quickbook are
-implemented using a version switch, it's mainly just the changes that change
-the way a document is interpreted or would break existing documentation.
-
-[heading Quickbook 1.3 and later]
-
-* Introduced quickbook language versioning.
-* In the documentation info, allow phrase markup in license and purpose
- attributes.
-* Fully qualified section and headers. Subsection names are concatenated to the
- ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`.
-
-[heading Quickbook 1.5 and later]
-
-* Ignore template argument separators inside square brackets.
-* Don't separate the final template argument if the `..` separator was
- used. i.e. never mix `..` and whitespace separators.
-* Statically scope templates and their arguments rather than dynamically
- scope them.
-* Give table ids, and let you set them.
-* Allow spaces between the `:` character and ids in elements which can
- have ids.
-
-[endsect]
-
[section:1_6 Quickbook 1.6]

Everything described in here may change depending on the feedback received.
@@ -338,170 +303,3 @@
[endsect]

[endsect] [/ Quickbok 1.6]
-
-[section:1_7 Quickbook 1.7]
-
-[section:context_error Error for elements used in incorrect context]
-
-Previously if you used an element in the wrong context it would just be
-unprocessed, which was surprising. People often didn't realise that their
-element hadn't been processed. So now it's an error.
-
-[endsect]
-
-[section:phrase_parse_error Error for invalid phrase elements]
-
-If the body of a phrase element didn't parse, it would be just used
-unprocessed. Now change it to be a hard error.
-
-[endsect]
-
-[section:source_mode Source mode for single entities]
-
-1.7 introduces a new `!` element type for setting the source mode of a single
-entity without changing the source mode otherwise. This can be used for
-code blocks and other elements. For example:
-
-```
-[!c++]
- void foo() {};
-
-[!python]``\`\`\`\ ``def foo():``\`\`\`\ ``
-```
-
-It can also be used to set the source mode for elements:
-
-```
-[!teletype][table
- [[code][meaning]]
- [[`+`][addition]]
-]
-```
-
-When used a section, it's only set for the section element, not the
-whole section.
-
-Currently it does support other syntactic entities such as paragraphs
-and lists. I'm not sure if it would be a good idea.
-
-[endsect]
-
-[section:callouts Callouts in code blocks]
-
-Currently callouts can only be used in code snippets. 1.7 add
-support in normal code blocks. The same syntax is used as in
-code snippets, the callout descriptions appear immediately
-after the code block.
-
-[endsect]
-
-[section:escaped_docinfo_attributes Escaped docbook in docinfo blocks]
-
-Quickbook docinfo attributes will probably never be as rich as docbook
-attributes so to allow more flexible markup, not supported by quickbook
-escaped docbook can be included in the docinfo block:
-
-```
-[article Some article
-[quickbook 1.7]
-'''<author>
- <firstname>John</firstname>
- <surname>Doe</surname>
- <email>john.doe_at_[hidden]</email>
-</author>'''
-]
-```
-
-The escaped docbook is always placed at the end of the docinfo block,
-so it shouldn't be assumed that it will interleave the markup. A mixture
-of quickbook and docbook attributes for the same information will not work
-well.
-
-[endsect] [/escaped_docinfo_attributes]
-
-[section:listparagraphs Pargraphs in lists]
-
-I'm still refining this, but paragraphs and block elements can now be used
-in lists:
-
-[pre
-* Para 1
-
- Para 2
- * Nested Para 1
-
- Nested Para 2
-
- Code block
- Para 3
-]
-
-generates:
-
-* Para 1
-
- Para 2
- * Nested Para 1
-
- Nested Para 2
-
- Code block
- Para 3
-
-The docbook markup that this generates is pretty bad, but seems to create okay
-html.
-
-[endsect]
-
-[section:templates_in_link_values Templates in link values]
-
-There's very premilinary support for calling templates in link values. A lot
-more work needs to be done, including:
-
-* Considering other places where templates could be called (e.g. images are
- quite tricky, as templates could get confused with attributes, should
- templates be callable from something like an element's id?).
-* Trimming spaces from the body of the template (which can cause surprising
- results).
-* Checking that the contents of the template are appropriate for the context.
- Possibly even using a different grammar.
-
-[endsect] [/templates_in_link_values]
-
-[section:list_markup_in_tables List Markup in Nested Blocks]
-
-Can now place list markup in nested blocks, e.g in tables, variables lists etc.
-Unfortunately indented code blocks are more tricky, because the contents of
-these blocks are often indented already. It seemed easier to just not support
-indented code blocks in this context than to try to work out sensible actions
-for the edges cases. If you want to use code blocks in this context, you should
-still be able to use explicit markup.
-
-[endsect]
-
-[section:phrase_block_templates Allow block elements in phrase templates]
-
-Block elements can now be used in phrase templates, but paragraphs breaks aren't
-allowed, so this is an error:
-
- [template paras[] Something or other.
-
- Second paragraph.]
-
-If a phrase template only contains block elements, then it's practically
-indistinguishable from a block template. So you'll get the same output from:
-
- [template foo[] [blurb Blah, blah, blah]]
-
-as:
-
- [template foo[]
- [blurb Blah, blah, blah]
- ]
-
-If a phrase template has phrase content mixed with block elements, it'll generate
-output as if it was expanded inline.
-
-[endsect]
-
-[endsect] [/ Quickbok 1.7]

Added: trunk/tools/quickbook/doc/1_7.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/1_7.qbk 2013-08-10 15:18:25 EDT (Sat, 10 Aug 2013) (r85288)
@@ -0,0 +1,175 @@
+[/
+ Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
+ Copyright 2012-2013 Daniel James
+
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:1_7 Quickbook 1.7]
+
+[section:context_error Error for elements used in incorrect context]
+
+Previously if you used an element in the wrong context it would just be
+unprocessed, which was surprising. People often didn't realise that their
+element hadn't been processed. So now it's an error.
+
+[endsect]
+
+[section:phrase_parse_error Error for invalid phrase elements]
+
+If the body of a phrase element didn't parse, it would be just used
+unprocessed. Now change it to be a hard error.
+
+[endsect]
+
+[section:source_mode Source mode for single entities]
+
+1.7 introduces a new `!` element type for setting the source mode of a single
+entity without changing the source mode otherwise. This can be used for
+code blocks and other elements. For example:
+
+```
+[!c++]
+ void foo() {};
+
+[!python]``\`\`\`\ ``def foo():``\`\`\`\ ``
+```
+
+It can also be used to set the source mode for elements:
+
+```
+[!teletype][table
+ [[code][meaning]]
+ [[`+`][addition]]
+]
+```
+
+When used a section, it's only set for the section element, not the
+whole section.
+
+Currently it does support other syntactic entities such as paragraphs
+and lists. I'm not sure if it would be a good idea.
+
+[endsect]
+
+[section:callouts Callouts in code blocks]
+
+Currently callouts can only be used in code snippets. 1.7 add
+support in normal code blocks. The same syntax is used as in
+code snippets, the callout descriptions appear immediately
+after the code block.
+
+[endsect]
+
+[section:escaped_docinfo_attributes Escaped docbook in docinfo blocks]
+
+Quickbook docinfo attributes will probably never be as rich as docbook
+attributes so to allow more flexible markup, not supported by quickbook
+escaped docbook can be included in the docinfo block:
+
+```
+[article Some article
+[quickbook 1.7]
+'''<author>
+ <firstname>John</firstname>
+ <surname>Doe</surname>
+ <email>john.doe_at_[hidden]</email>
+</author>'''
+]
+```
+
+The escaped docbook is always placed at the end of the docinfo block,
+so it shouldn't be assumed that it will interleave the markup. A mixture
+of quickbook and docbook attributes for the same information will not work
+well.
+
+[endsect] [/escaped_docinfo_attributes]
+
+[section:listparagraphs Pargraphs in lists]
+
+I'm still refining this, but paragraphs and block elements can now be used
+in lists:
+
+[pre
+* Para 1
+
+ Para 2
+ * Nested Para 1
+
+ Nested Para 2
+
+ Code block
+ Para 3
+]
+
+generates:
+
+* Para 1
+
+ Para 2
+ * Nested Para 1
+
+ Nested Para 2
+
+ Code block
+ Para 3
+
+The docbook markup that this generates is pretty bad, but seems to create okay
+html.
+
+[endsect]
+
+[section:templates_in_link_values Templates in link values]
+
+There's very premilinary support for calling templates in link values. A lot
+more work needs to be done, including:
+
+* Considering other places where templates could be called (e.g. images are
+ quite tricky, as templates could get confused with attributes, should
+ templates be callable from something like an element's id?).
+* Trimming spaces from the body of the template (which can cause surprising
+ results).
+* Checking that the contents of the template are appropriate for the context.
+ Possibly even using a different grammar.
+
+[endsect] [/templates_in_link_values]
+
+[section:list_markup_in_tables List Markup in Nested Blocks]
+
+Can now place list markup in nested blocks, e.g in tables, variables lists etc.
+Unfortunately indented code blocks are more tricky, because the contents of
+these blocks are often indented already. It seemed easier to just not support
+indented code blocks in this context than to try to work out sensible actions
+for the edges cases. If you want to use code blocks in this context, you should
+still be able to use explicit markup.
+
+[endsect]
+
+[section:phrase_block_templates Allow block elements in phrase templates]
+
+Block elements can now be used in phrase templates, but paragraphs breaks aren't
+allowed, so this is an error:
+
+ [template paras[] Something or other.
+
+ Second paragraph.]
+
+If a phrase template only contains block elements, then it's practically
+indistinguishable from a block template. So you'll get the same output from:
+
+ [template foo[] [blurb Blah, blah, blah]]
+
+as:
+
+ [template foo[]
+ [blurb Blah, blah, blah]
+ ]
+
+If a phrase template has phrase content mixed with block elements, it'll generate
+output as if it was expanded inline.
+
+[endsect]
+
+[endsect] [/ Quickbok 1.7]

Added: trunk/tools/quickbook/doc/language_versions.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/language_versions.qbk 2013-08-10 15:18:25 EDT (Sat, 10 Aug 2013) (r85288)
@@ -0,0 +1,46 @@
+[/
+ Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
+ Copyright 2010-2013 Daniel James
+
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[chapter Language Versions
+ [quickbook 1.7]
+ [compatibility-mode 1.5]
+ [id quickbook.versions]
+ [source-mode teletype]
+]
+
+[section:stable Stable Versions]
+
+Since quickbook 1.3 the `quickbook` attribute in the document block selects
+which version of the language to use. Not all changes to quickbook are
+implemented using a version switch, it's mainly just the changes that change
+the way a document is interpreted or would break existing documentation.
+
+[heading Quickbook 1.3 and later]
+
+* Introduced quickbook language versioning.
+* In the documentation info, allow phrase markup in license and purpose
+ attributes.
+* Fully qualified section and headers. Subsection names are concatenated to the
+ ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`.
+
+[heading Quickbook 1.5 and later]
+
+* Ignore template argument separators inside square brackets.
+* Don't separate the final template argument if the `..` separator was
+ used. i.e. never mix `..` and whitespace separators.
+* Statically scope templates and their arguments rather than dynamically
+ scope them.
+* Give table ids, and let you set them.
+* Allow spaces between the `:` character and ids in elements which can
+ have ids.
+
+[endsect]
+
+[include 1_6.qbk]
+[include 1_7.qbk]

Modified: trunk/tools/quickbook/doc/quickbook.qbk
==============================================================================
--- trunk/tools/quickbook/doc/quickbook.qbk Sat Aug 10 15:17:51 2013 (r85287)
+++ trunk/tools/quickbook/doc/quickbook.qbk 2013-08-10 15:18:25 EDT (Sat, 10 Aug 2013) (r85288)
@@ -87,8 +87,9 @@
[include structure.qbk]
[include phrase.qbk]
[include block.qbk]
+[include language_versions.qbk]
[include 1_6.qbk]
[include install.qbk]
[include editors.qbk]
[include faq.qbk]
-[include ref.qbk]
\ No newline at end of file
+[include ref.qbk]

Date view	Thread view	Subject view	Author view

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