[Boost-commit] svn:boost r85470 - in trunk/tools/quickbook: doc/boost-doc-tools examples examples/simple-boostbook examples/simple-quickbook

Subject: [Boost-commit] svn:boost r85470 - in trunk/tools/quickbook: doc/boost-doc-tools examples examples/simple-boostbook examples/simple-quickbook
From: dnljms_at_[hidden]
Date: 2013-08-25 15:10:31

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

Log:
First example of building documentation with boost build.

Added:
   trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk   (contents, props changed)
   trunk/tools/quickbook/examples/
   trunk/tools/quickbook/examples/simple-boostbook/
   trunk/tools/quickbook/examples/simple-boostbook/Jamfile.v2   (contents, props changed)
   trunk/tools/quickbook/examples/simple-boostbook/simple.xml   (contents, props changed)
   trunk/tools/quickbook/examples/simple-quickbook/
   trunk/tools/quickbook/examples/simple-quickbook/Jamfile.v2   (contents, props changed)
   trunk/tools/quickbook/examples/simple-quickbook/simple.qbk   (contents, props changed)
Text files modified: 
   trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk     |    90 ++++++++++++++++++++++++++++++++++++++++
   trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk |     1                                         
   trunk/tools/quickbook/examples/simple-boostbook/Jamfile.v2    |     5 ++                                      
   trunk/tools/quickbook/examples/simple-boostbook/simple.xml    |     7 +++                                     
   trunk/tools/quickbook/examples/simple-quickbook/Jamfile.v2    |     8 +++                                     
   trunk/tools/quickbook/examples/simple-quickbook/simple.qbk    |     5 ++                                      
   6 files changed, 116 insertions(+), 0 deletions(-)

Added: trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -0,0 +1,90 @@
+[chapter Building documentation using Boost Build
+[id boost_doc_tools.boost_build]
+[quickbook 1.6]
+[source-mode teletype]
+]
+
+This chapter is an introduction to building boostbook and quickbook
+documentation using Boost.Build. It assumes you're already a little
+familiar with using it.
+
+[section:simple Simple examples]
+
+Starting with the simplest of examples, in
+[@boost://tools/quickbook/examples/simple-boostbook/
+ `tools/quickbook/examples/simple-boostbook/`]
+you'll find the first example. This consists of a small boostbook file
+([@boost://tools/quickbook/examples/simple-boostbook/simple.xml
+ `tools/quickbook/examples/simple-boostbook/simple.xml`] and a Jamfile
+to build it, which looks like this:
+
+    using boostbook ;
+
+    boostbook simple : simple.xml :
+        <xsl:param>boost.root=../../../../..
+        ;
+
+The first line just tells Boost.Build that we'll be using the boostbook
+toolset:
+
+    using boostbook ;
+
+This isn't needed if you already have a `using boostbook` line in your
+`user-config.jam` file, but it's useful for other people who don't.
+
+Next we specify the build target:
+
+    boostbook simple : simple.xml :
+
+This says that we are creating a document called `simple` from the source
+file `simple.xml`. `simple` is just an identifier for Boost.Build, html
+documentation is built in a sub-directory called `html`.
+
+After that we write the build parameters:
+
+        <xsl:param>boost.root=../../../../..
+
+This is the bare minimum, it just tells boost build where the root of the
+boost tree is, so that it can link to things like css and image files which
+the documentation uses. Getting the value right is a bit tricky - it's
+relative to the build target, which is the `html` subdirectory. The full
+path from root will be: `tools/quickbook/examples/simple-boostbook/html`,
+which has five parts, so the root is five directories up.
+
+And finally there's a `;` to end the build target.
+
+To build this example, go to the directory in the command line, and run `b2`:
+
+    cd $BOOST_ROOT
+    cd tools/quickbook/examples/simple-boostbook
+    b2
+
+You do have to be in the correct directory, as Boost.Build always
+builds the documentation in a subdirectory of the current directory.
+Having done this the documentation should be at
+`tools/quickbook/examples/simple-boostbook/html/index.html`.
+
+Building quickbook is very similar, there's a corresponding example at
+[@boost://tools/quickbook/examples/simple-boostbook/
+ `tools/quickbook/examples/simple-boostbook/`].
+For that case, the Jamfile is:
+
+    using boostbook ;
+    using quickbook ;
+
+    xml simple-boostbook : simple.qbk ;
+
+    boostbook simple : simple-boostbook :
+        <xsl:param>boost.root=../../../../..
+        ;
+
+This time it specifies that it's using both `boostbook` and `quickbook`.
+Then there's a target to build the boostbook representation from quickbook:
+
+    xml simple-boostbook : simple.qbk ;
+
+And finally, the target to build the documentation is almost exactly the
+same, but instead of having a source file, the source is the boostbook
+xml generated from the quickbook file.
+
+[endsect] [/simple]

Modified: trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk
==============================================================================
--- trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk	Sun Aug 25 15:09:59 2013	(r85469)
+++ trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -6,3 +6,4 @@
 [include intro.qbk]
 [include install.qbk]
 [include pdfs.qbk]
+[include boost-build.qbk]

Added: trunk/tools/quickbook/examples/simple-boostbook/Jamfile.v2
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/simple-boostbook/Jamfile.v2	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -0,0 +1,5 @@
+using boostbook ;
+
+boostbook simple : simple.xml :
+    <xsl:param>boost.root=../../../../..
+    ;

Added: trunk/tools/quickbook/examples/simple-boostbook/simple.xml
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/simple-boostbook/simple.xml	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<article>
+    <title>Simple Example</title>
+    <para>Interesting stuff goes here.</para>
+</article>

Added: trunk/tools/quickbook/examples/simple-quickbook/Jamfile.v2
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/simple-quickbook/Jamfile.v2	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -0,0 +1,8 @@
+using boostbook ;
+using quickbook ;
+
+xml simple-boostbook : simple.qbk ;
+
+boostbook simple : simple-boostbook :
+    <xsl:param>boost.root=../../../../..
+    ;

Added: trunk/tools/quickbook/examples/simple-quickbook/simple.qbk
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/simple-quickbook/simple.qbk	2013-08-25 15:10:31 EDT (Sun, 25 Aug 2013)	(r85470)
@@ -0,0 +1,5 @@
+[article Simple Example
+    [quickbook 1.6]
+]
+
+Interesting stuff goes here.