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

Subject: [Boost-commit] svn:boost r72081 - branches/quickbook-dev/tools/quickbook/doc
From: dnljms_at_[hidden]
Date: 2011-05-22 11:36:08

Author: danieljames
Date: 2011-05-22 11:36:07 EDT (Sun, 22 May 2011)
New Revision: 72081
URL: http://svn.boost.org/trac/boost/changeset/72081

Log:
Quickbook: Trying to write a gentler intro to quickbook.
Text files modified: 
   branches/quickbook-dev/tools/quickbook/doc/structure.qbk |    14 +++++++                                 
   branches/quickbook-dev/tools/quickbook/doc/syntax.qbk    |    79 ++++++++++++++++++++++++++++----------- 
   2 files changed, 71 insertions(+), 22 deletions(-)

Modified: branches/quickbook-dev/tools/quickbook/doc/structure.qbk
==============================================================================
--- branches/quickbook-dev/tools/quickbook/doc/structure.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/structure.qbk	2011-05-22 11:36:07 EDT (Sun, 22 May 2011)
@@ -13,6 +13,20 @@
     [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

Modified: branches/quickbook-dev/tools/quickbook/doc/syntax.qbk
==============================================================================
--- branches/quickbook-dev/tools/quickbook/doc/syntax.qbk	(original)
+++ branches/quickbook-dev/tools/quickbook/doc/syntax.qbk	2011-05-22 11:36:07 EDT (Sun, 22 May 2011)
@@ -13,32 +13,67 @@
     [source-mode teletype]
 ]
 
-A simple quickbook document might look something like:
+Let's start with a simple quickbook document to give you an idea of what
+one looks like, and what it means. Later sections will describe the
+different parts in more detail:
 
-[pre'''
-    [book A sweet little horror story
+[/TODO: Callouts would really help here, need to look into implementing
+the required markup?]
+
+    [library An example library
         [quickbook 1.5]
-        [author Brown, Fredric]
     ]
+
+    Since this is just an example, there isn't anything to
+    document and this is mostly just /verbiage/.
+
+    Here's some predictable code:
+
+        #include <iostream>
+        
+        int main()
+        {
+            std::cout << "Hello standard example!\n";
+        }
+
+[template example_library[]
+
+[*TODO: display the title?]
+
+Since this is just an example, there isn't anything to
+document and this is mostly just /verbiage/.
+
+Here's some predictable code:
+
+    #include <iostream>
     
-    The last man on Earth sat alone in a room. There was a knock on
-    the door...
-''']
-
-The document starts with the
-[link quickbook.structure.docinfo document info block].
-This describes the type of the document, its title and document
-metadata. In this case just the version of quickbook to be used.
-
-This is then followed by one or more blocks. An example of
-a block is the paragraph or a C++ code snippet. In this example we just
-have a single paragraph. Some blocks have
-special mark-ups. Blocks, except code snippets which have their own
-grammar (C++ or Python), are composed of one or more phrases. A phrase
-can be a simple contiguous run of characters. Phrases can have special
-mark-ups. Marked up phrases can recursively contain other phrases, but
-cannot contain blocks. A terminal is a self contained block-level or
-phrase-level element that does not nest anything.
+    int main()
+    {
+        std::cout << "Hello standard example!\n";
+    }
+]
+
+This starts with the [link ref-docinfo document info block] in square
+brackets. `library` is the type of the document, followed by the title
+on the same line. After that comes the the document metadata. In this
+case, we just have the version of quickbook to be used. This
+documentation mostly describes the current version quickbook 1.5.
+
+This is then followed by two paragraphs, which are separated by blank
+lines. The slashes around the word 'verbiage' cause it to be displayed
+in italics. Then finally, there is a block of code which is indented to
+tell quickbook that it is a code block.
+
+This generates: [:[example_library]]
+
+[*TODO: Move the following to a more detailled section?]
+
+Some blocks have special mark-ups. Blocks, except code snippets which
+have their own grammar (C++ or Python), are composed of one or more
+phrases. A phrase can be a simple contiguous run of characters. Phrases
+can have special mark-ups. Marked up phrases can recursively contain
+other phrases, but cannot contain blocks. A terminal is a self contained
+block-level or phrase-level element that does not nest anything.
 
 Blocks, in general, are delimited by two end-of-lines (the block terminator).
 Phrases in each block cannot contain a block terminator. This way, syntax errors