[Boost-commit] svn:boost r75363 - branches/quickbook-dev/tools/quickbook/doc

Subject: [Boost-commit] svn:boost r75363 - branches/quickbook-dev/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-11-06 17:23:49

Author: danieljames
Date: 2011-11-06 17:23:48 EST (Sun, 06 Nov 2011)
New Revision: 75363
URL: http://svn.boost.org/trac/boost/changeset/75363

Log:
Quickbook: Start to document 1.6
Added:
   branches/quickbook-dev/tools/quickbook/doc/1_6.qbk   (contents, props changed)
Text files modified: 
   branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk |     2 ++                                      
   1 files changed, 2 insertions(+), 0 deletions(-)

Added: branches/quickbook-dev/tools/quickbook/doc/1_6.qbk
==============================================================================
--- (empty file)
+++ branches/quickbook-dev/tools/quickbook/doc/1_6.qbk	2011-11-06 17:23:48 EST (Sun, 06 Nov 2011)
@@ -0,0 +1,189 @@
+[section:1_6 Quickbook 1.6]
+
+New features and changes to the language are being introduced for quickbook 1.6. These
+can be used now by adding the `[quickbook 1.6]` tag to your document's docinfo:
+
+    [article Document
+    [quickbook 1.6]
+    ]
+
+Everything described in here may change depending on the feedback received.
+
+[section:docinfo Includes with docinfo]
+
+In quickbook 1.5 if you include a file which starts with a docinfo block, it's
+ignored and the file is expanded in place. In quickbook 1.6 it's treated as a
+document nested in the current position. So if it has an 'article' docinfo block,
+boostbook 'article' tags are used.
+
+It also mostly generates the same markup as if the file was converted separately -
+so for example, the same ids are generated, the document is processed using the
+language version specified in the docinfo block. If no language is specified it
+uses the default (1.1) not the version of the document that included it. This
+might seem surprising, but is requried so that quickbook will convert it the same
+way as if it was converted separately.
+
+So for the most part, includes with a docinfo are like an `xinclude`, apart from
+a couple of differences. Templates and macros defined in the parent document are
+used in the included document, and the id generator rewrites ids that clash
+between multiple documents.
+
+If an included document doesn't have a docinfo block, it's just included as
+before.
+
+[endsect] [/docinfo]
+
+[section:scope Scoping templates and macros]
+
+A long standing quickbook bug is that macros are scoped by file, but templates
+aren't. So you can define templates in a separate file and include them, but not
+macros. This has been fixed so that templates defined in one file won't 'leak'
+into another.
+
+But this means there's no way to define templates in a separate file - a useful
+feature. To do this the `import` element has been adapted to also support
+quickbook files. If a quickbook file is imported, the templates and macros
+defined in it are added to the current scope, but nothing else contained in that
+file is used. This could be used to create template and macro library files.
+This matches the existing semantics of importing code snippets.
+
+When importing templates, they're bound to the language version of the file
+they were defined in. This means that if you import them into a file with
+a different version it won't change the way they're interpreted. Although,
+as we'll see [link compatibility later], the generated boostbook is slightly
+different.
+
+[endsect] [/scope]
+
+[section:include Including C++ and python files]
+
+As `import` now supports quickbook files, `include` also supports source files.
+It includes any quickbook contained in comments outside of code snippets.
+Code snippets in the file are available to be expanded within the file but
+are scoped to the file. In exactly the same manner as when templates and macros
+are scoped in an included quickbook file.
+
+[endsect] [/include]
+
+[section:ids Id Generation]
+
+Id generation in quickbook 1.5 is a bit buggy, but that can't be fixed without a
+version switch as it will break existing documents. For example in quickbook 1.5
+when you include a quickbook file, it stops using the explicit id from the
+documentation info and generates a new id from the document title to use instead.
+
+The id generator in quickbook 1.6 has been improved in some other ways to. When
+generating ids from section titles, table titles etc. it always uses the
+quickbook source rather than the generated boostbook to generate the id. It then
+cleans up the id slightly, trimming leading and trailing underscores and replacing
+multiple underscores with a single underscore. Then if the newly generated part
+of the id is longer than 32 characters it truncates it.
+
+While the new id generator generally creates better ids, it's more likely to
+generate duplicates so quickbook needs to handle duplicates better. When there
+are multiple identical ids, quickbook chooses one to use based on a priority
+list - anchors are preferred, then explicit document and section ids, then other
+explicit ids, followed by the generated ids. Then any other explicit ids in the
+document have numbers added to avoid duplicates - first the explicit ids in the
+order they appear and then the generated ids. A generated id which accidentally
+clashes with an explicit id should never change the explicit id.
+
+Older language versions still generate the same ids they always have, with the
+exception of duplicate ids which are handled using the new mechanism - this
+is not a breaking change since duplicate ids can't be linked to.
+
+[endsect] [/ids]
+
+[#compatibility]
+[section:compatibility Compatibility Mode]
+
+As mentioned before, changing the id generator will break links in documents
+written using an old language version. So to ease the transition a
+'compatibility mode' is used, this just requires an extra attribute in the
+docinfo, for example if you're converting a 1.5 document to 1.6:
+
+    [article Document
+    [quickbook 1.6]
+    [compatibility-mode 1.5]
+    ]
+
+This means the document will be parsed as 1.6, using all the new features, but
+ids (and possibly other markup) will generated as they were for a 1.5 document.
+
+Compatibility mode is also implicitly used when generating templates written
+in a different language version to the current document. So the template is
+parsed in the version it was written for, but generates boostbook that's
+compatible with the current document.
+
+[endsect] [/compatibility]
+
+[section:heading_ids Explicit Heading Ids]
+
+Headings can now be given explicit ids:
+
+    [heading:id A heading with an explicit id]
+
+[endsect] [/heading_ids]
+
+[section:escapes Punctuation changes]
+
+In 1.6, quickbook is more consistent about how it parses punctuation.
+Escapes are now supported in links, anchors, table titles, image
+attributes etc. The flip side of this is that quickbook is now stricter
+about unescaped brackets. They can still be used, but need to match up,
+otherwise there's an error.
+
+Since quickbook now matches up square brackets it will fix some
+mis-parses. For example `[*[bold]]` used to parse as [*\[bold]\] - note
+that the closing square bracket isn't bold, now it parses as
+[*\[bold\]]. In this case it's just a subtle visual difference, but it
+could cause odd problems, for example when nested in a table cell.
+
+Also, unescaped square brackets aren't allowed in a table title now. If
+there are any it ends the title. So this is now an empty table:
+
+    [table Empty]
+
+While an open bracket will be treated as the start of the table rows:
+
+    [table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]
+
+I'm not sure if this is the best course as it doesn't allow for any
+markup or templates in the table title in the future. But the problem is
+that if they are allowed in the title it might be ambiguous where the
+title ends and the cells begin.
+
+[endsect] [/escapes]
+
+[section:xmlbase XML base]
+
+A problem when using `xi:include` tags in escaped boostbook is that you
+typically don't know which directory the boostbook file will be in, so
+it's impossible to use relative links. This can be fixed by adding an
+`xml:base` attribute to the document tag. To do this use the new
+`xmlbase` attribute in your document's docinfo block. For example to
+make escaped `xi:include`s be relative to the directory of the file:
+
+    [library Library documentation
+    [quickbook 1.6]
+    [xmlbase .]
+    ]
+
+Any paths in `xinclude` elements will be rewritten accordingly. Note that
+most documents won't need this, and probably shouldn't use it. Only use it
+if you're totally sure that you will need it.
+
+[endsect] [/xmlbase]
+
+[section:elements New Elements]
+
+New elements in 1.6 (to be documented later):
+
+* `block`
+* `ordered_list`
+* `itemized_list`
+* `role`
+
+[endsect]
+
+[endsect] [/1_6]
\ No newline at end of file

Modified: branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk
==============================================================================
--- branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/quickbook.qbk	2011-11-06 17:23:48 EST (Sun, 06 Nov 2011)
@@ -2017,6 +2017,8 @@
 
 [endsect] [/Syntax Summary]
 
+[include 1_6.qbk]
+
 [section:install Installation and configuration]
 
 This section provides some guidelines on how to install and configure