|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r75842 - trunk/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-12-07 04:20:06
Author: danieljames
Date: 2011-12-07 04:20:04 EST (Wed, 07 Dec 2011)
New Revision: 75842
URL: http://svn.boost.org/trac/boost/changeset/75842
Log:
Quickbook: Add some of the old quickbook-dev docs.
- Link example.
- Extra Docinfo information.
- Quickbook 1.3 and 1.5
Added:
trunk/tools/quickbook/doc/structure.qbk (contents, props changed)
Text files modified:
trunk/tools/quickbook/doc/1_6.qbk | 39 ++++++++++++--
trunk/tools/quickbook/doc/block.qbk | 99 ++++++++++-----------------------------
trunk/tools/quickbook/doc/quickbook.qbk | 5 +
3 files changed, 60 insertions(+), 83 deletions(-)
Modified: trunk/tools/quickbook/doc/1_6.qbk
==============================================================================
--- trunk/tools/quickbook/doc/1_6.qbk (original)
+++ trunk/tools/quickbook/doc/1_6.qbk 2011-12-07 04:20:04 EST (Wed, 07 Dec 2011)
@@ -7,19 +7,42 @@
http://www.boost.org/LICENSE_1_0.txt)
]
-[chapter Quickbook 1.6
+[chapter Language Versions
[quickbook 1.6]
[compatibility-mode 1.5]
- [id quickbook.1_6]
+ [id quickbook.versions]
[source-mode teletype]
]
-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:
+[section:stable Stable Versions]
- [article Document
- [quickbook 1.6]
- ]
+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.
@@ -254,3 +277,5 @@
html.
[endsect]
+
+[endsect] [/ Quickbok 1.6]
\ No newline at end of file
Modified: trunk/tools/quickbook/doc/block.qbk
==============================================================================
--- trunk/tools/quickbook/doc/block.qbk (original)
+++ trunk/tools/quickbook/doc/block.qbk 2011-12-07 04:20:04 EST (Wed, 07 Dec 2011)
@@ -14,80 +14,6 @@
[source-mode teletype]
]
-[section Document]
-
-Every document must begin with a Document Info section, which should look
-like this:
-
-[pre'''
-[document-type The Document Title
- [quickbook 1.5]
- [version 1.0]
- [id the_document_name]
- [dirname the_document_dir]
- [copyright 2000 2002 2003 Joe Blow, Jane Doe]
- [purpose The document's reason for being]
- [category The document's category]
- [authors [Blow, Joe] [Doe, Jane]]
- [license The document's license]
- [source-mode source-type]
-]
-''']
-
-Where document-type is one of:
-
-* book
-* article
-* library
-* chapter
-* part
-* appendix
-* preface
-* qandadiv
-* qandaset
-* reference
-* set
-
-quickbook 1.5 declares the version of quickbook the document is written for.
-In its absence, version 1.1 is assumed.
-
-=version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=,
-=license=, =last-revision= and =source-mode= are optional information.
-
-=dirname=, =purpose= and =category= are boostbook attributes which are only
-valid for =library= documents. If you use them for other document types,
-quickbook will warn about them, but still use them, generating invalid markup,
-that's just ignored by the style sheets.
-
-=source-type= is a lowercase string setting the initial __source_mode__. If
-the =source-mode= field is omitted, a default value of =c++= will be used.
-
-[endsect] [/Document]
-
-[section Section]
-
-Starting a new section is accomplished with:
-
-[pre'''
-[section:id The Section Title]
-''']
-
-where /id/ is optional. id will be the filename of the generated section.
-If it is not present, "The Section Title" will be normalized and become the id.
-Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
-converted to underscore and all upper-case are converted to lower case.
-Thus: "The Section Title" will be normalized to "the_section_title".
-
-End a section with:
-
-[pre'''
-[endsect]
-''']
-
-Sections can nest, and that results in a hierarchy in the table of contents.
-
-[endsect] [/Section]
-
[section xinclude]
You can include another XML file with:
@@ -647,6 +573,31 @@
quickbook.syntax.phrase QuickBook phrase]. Arguments are separated by the
double dot [^".."] and terminated by the close parenthesis.
+Note that templates and template parameters can't be expanded
+everywhere, only where text is interpreted as a phrase. So they can't be
+expanded in places such as table titles and link's urls. If you want to
+use a template to generate a link based of the template parameter, you
+can't use a normal link and will need to use escaped docbook instead.
+Example:
+
+[teletype]
+```
+[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
+
+[boost_ticket 2035]
+```
+
+will expand to:
+
+[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
+
+[boost_ticket 2035]
+
+[caution Since quickbook doesn't understand the context where the
+parameter is being used, it will interpret it as quickbook markup, so
+when writing a template like this, you'll need to escape any meaningful
+punctuation.]
+
[heading Nullary Templates]
Nullary templates look and act like simple macros. Example:
Modified: trunk/tools/quickbook/doc/quickbook.qbk
==============================================================================
--- trunk/tools/quickbook/doc/quickbook.qbk (original)
+++ trunk/tools/quickbook/doc/quickbook.qbk 2011-12-07 04:20:04 EST (Wed, 07 Dec 2011)
@@ -57,8 +57,8 @@
[def __images__ [link quickbook.syntax.phrase.images Images]]
[def __cond__ [link quickbook.syntax.phrase.cond Conditional Generation]]
-[def __document__ [link quickbook.syntax.block.document Document]]
-[def __section__ [link quickbook.syntax.block.section Section]]
+[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]]
@@ -84,6 +84,7 @@
[include introduction.qbk]
[include change_log.qbk]
[include syntax.qbk]
+[include structure.qbk]
[include phrase.qbk]
[include block.qbk]
[include 1_6.qbk]
Added: trunk/tools/quickbook/doc/structure.qbk
==============================================================================
--- (empty file)
+++ trunk/tools/quickbook/doc/structure.qbk 2011-12-07 04:20:04 EST (Wed, 07 Dec 2011)
@@ -0,0 +1,192 @@
+[/
+ Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
+ Copyright 2010-2011 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 Document Structure
+ [quickbook 1.6]
+ [id quickbook.syntax.structure]
+ [source-mode teletype]
+]
+
+[/TODO: I started to write this in the syntax chapter, but it was too
+much information, will incorporate into this file.]
+[/
+To avoid breaking old documentation we support using different versions
+of the language, compatibility is not 100% but we try to avoid
+problematic changes. This documentation applies to the current version,
+`[quickbook 1.5]`.
+
+There is also some mention of the next version `[quickbook 1.6]`. While
+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]
+[section:docinfo Document Info]
+
+Every document must begin with a Document Info section, which looks something
+like this:
+
+[pre'''
+[article The Document Title
+ [quickbook 1.5]
+ [version 1.0]
+ [id the_document_name]
+ [copyright 2000 2002 2003 Joe Blow, Jane Doe]
+ [authors [Blow, Joe] [Doe, Jane]]
+ [license The document's license]
+ [source-mode c++]
+]
+''']
+
+`article` is the document type. There are several possible document types,
+most of these are based on docbook document elements. These are fully
+described in
+[@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:
+
+* [@http://www.docbook.org/tdg/en/html/book.html book]
+* [@http://www.docbook.org/tdg/en/html/article.html article]
+* [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
+* [@http://www.docbook.org/tdg/en/html/part.html part]
+* [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
+* [@http://www.docbook.org/tdg/en/html/preface.html preface]
+* [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
+* [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
+* [@http://www.docbook.org/tdg/en/html/reference.html reference]
+* [@http://www.docbook.org/tdg/en/html/set.html set]
+
+Boostbook also adds another document type [^[link boostbook.defining library]]
+for documenting software libraries.
+
+So the documentation for the 'foo' library might start:
+
+[pre'''
+[library Foo
+ [quickbook 1.5]
+ [id foo]
+ [version 1.0]
+]
+''']
+
+[section:attributes Document Info Attributes]
+
+The document info block has a few different types of attributes.
+They are all optional.
+
+[heading Quickbook specific meta data]
+
+[pre'''
+ [quickbook 1.5]
+''']
+
+The `quickbook` attribute declares the version of quickbook
+the document is written for.
+In its absence, version 1.1 is assumed. It's recommended that
+you use `[quickbook 1.5]` which is the version described here.
+
+[pre'''
+ [source-mode teletype]
+''']
+
+The `source-mode` attribute sets the initial __source_mode__. If
+it is omitted, the default value of =c++= will be used.
+
+[heading Boostbook/Docbook root element attributes]
+
+[pre'''
+[id foo]
+''']
+
+`id` specifies the id of the document element. If it isn't specified
+the id is automatically generated from the title. This id is also
+used to generate the nested ids.
+
+[pre'''
+[lang en]
+''']
+
+`lang` specifies the document language. This is used by docbook to
+localize the documentation. Note that Boostbook doesn't have any
+localization support so if you use it to generate the reference
+documentation it will be in English regardless.
+
+It should be a language code
+drawn from ISO 639 (perhaps extended with a country code drawn from
+ISO 3166, as en-US).
+
+[pre'''
+[dirname foo]
+''']
+
+`dirname` is used to specify the directory name of the library in the
+repository. This is a boostbook extension so it's only valid for
+`library` documentation blocks. It's used for some boostbook
+functionality, but for pure quickbook documentation has no practical
+effect.
+
+[heading Docbook Metadata]
+
+=version=, =copyright=, =authors=,
+=license=, =last-revision= and =bibliod= are optional information.
+
+[heading Boostbook Metadata]
+
+=purpose= and =category= are boostbook attributes which are only
+valid for =library= documents. If you use them for other document types,
+quickbook will warn about them, but still use them, generating invalid markup,
+that's just ignored by the style sheets.
+
+[endsect] [/attributes]
+
+[endsect] [/docinfo]
+
+[section:section Sections]
+
+Quickbook documents are structured using 'sections'. These are used
+to generate the table of contents, and, when generating html, to
+split the document into pages. This is optional but a good idea for
+all but the simplest of documents.
+
+A sectioned document might look like:
+
+[pre'''
+ [book Title
+ [quickbook 1.5]
+ ]
+
+ [section First Section]
+
+ [/...]
+
+ [endsect]
+
+ [section Second Section]
+
+ [/...]
+
+ [endsect]
+''']
+
+Sections start with the `section` tag, and end with the `[endsect]` tag.
+(`[/...]` is a comment, [link quickbook.syntax.comments described later]).
+
+Sections can be given an optional id:
+
+[pre'''
+[section:id The Section Title]
+''']
+
+`id` will be the filename of the generated section.
+If it is not present, "The Section Title" will be normalized and become the id.
+Valid characters are =a-Z=, =A-Z=, =0-9= and =_=. All non-valid characters are
+converted to underscore and all upper-case are converted to lower case.
+Thus: "The Section Title" will be normalized to "the_section_title".
+
+Sections can nest, and that results in a hierarchy in the table of contents.
+
+[endsect] [/Section]
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