[Boost-commit] svn:boost r51043 - in trunk/tools/documentation: . src

Subject: [Boost-commit] svn:boost r51043 - in trunk/tools/documentation: . src
From: daniel_james_at_[hidden]
Date: 2009-02-05 19:04:59

Author: danieljames
Date: 2009-02-05 19:04:59 EST (Thu, 05 Feb 2009)
New Revision: 51043
URL: http://svn.boost.org/trac/boost/changeset/51043

Log:
Very rough outline of how the documentation tools documentation might
look.
Added:
   trunk/tools/documentation/
   trunk/tools/documentation/Jamfile.v2   (contents, props changed)
   trunk/tools/documentation/src/
   trunk/tools/documentation/src/docs.xml   (contents, props changed)
   trunk/tools/documentation/src/intro.qbk   (contents, props changed)

Added: trunk/tools/documentation/Jamfile.v2
==============================================================================
--- (empty file)
+++ trunk/tools/documentation/Jamfile.v2	2009-02-05 19:04:59 EST (Thu, 05 Feb 2009)
@@ -0,0 +1,47 @@
+project tools/documentation ;
+
+xml intro : src/intro.qbk ;
+boostbook standalone
+    :
+    intro
+    :
+        # Path for links to Boost:
+        <xsl:param>boost.root=../../..
+        # Path for libraries index:
+        <xsl:param>boost.libraries=../../../libs/libraries.htm
+        # Use the main Boost stylesheet:
+        <xsl:param>html.stylesheet=../../../doc/html/boostbook.css
+        
+        # Some general style settings:
+        <xsl:param>table.footnote.number.format=1
+        <xsl:param>footnote.number.format=1
+
+        # HTML options first:
+        # Use graphics not text for navigation:
+        <xsl:param>navig.graphics=1
+        # How far down we chunk nested sections, basically all of them:
+        <xsl:param>chunk.section.depth=1
+        # Don't put the first section on the same page as the TOC:
+        <xsl:param>chunk.first.sections=0
+        # How far down sections get TOC's
+        <xsl:param>toc.section.depth=1
+    ;
+
+# Build the documentation combined with the boostbook and quickbook
+# documentation. This clashes with the standalone documentation.
+
+boostbook combined
+    :
+    src/docs.xml
+    :
+    <dependency>intro
+    <implicit-dependency>intro
+    <dependency>../quickbook/doc//quickbook
+    <implicit-dependency>../quickbook/doc//quickbook
+
+    <xsl:param>boost.root=../../..
+    <xsl:param>boost.libraries=../../../libs/libraries.htm
+    <xsl:param>html.stylesheet=../../../doc/html/boostbook.css
+    ;
+
+explicit combined ;

Added: trunk/tools/documentation/src/docs.xml
==============================================================================
--- (empty file)
+++ trunk/tools/documentation/src/docs.xml	2009-02-05 19:04:59 EST (Thu, 05 Feb 2009)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE boostbook PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+
+<!-- The rough plan is that this documentation, plus the tools documentation
+  will combine to make a, hopefully, coherent guide to the boost documentation
+  tools. This will probably be part of the main combined documentation, but
+  this can be used to build the subset to get an idea of how it might look
+  -->
+
+<boostbook xmlns:xi="http://www.w3.org/2001/XInclude"
+           last-revision="$Date$">
+  <title>The Boost Documentation Tools</title>
+
+  <xi:include href="intro.xml"/>
+  <xi:include href="quickbook.xml"/>
+  <xi:include href="../../boostbook/doc/boostbook.xml"/>
+</boostbook>
+
+

Added: trunk/tools/documentation/src/intro.qbk
==============================================================================
--- (empty file)
+++ trunk/tools/documentation/src/intro.qbk	2009-02-05 19:04:59 EST (Thu, 05 Feb 2009)
@@ -0,0 +1,67 @@
+[article Introduction to the Boost Documentation Tools
+    [quickbook 1.4]
+    [id doc-intro]
+    [license
+        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])
+    ]
+]
+
+[/ Very quick and rough outline of how this can be structured.
+   Feel free to change.
+   The individual sections will probably be put into separate quickbook
+   files. ]
+
+[section:docs Boost Documentation]
+
+* Explain that boost documentation can be generated in any manner
+  * Link to [@../../../more/writingdoc/index.html the current documentation
+    guidelines] - maybe incorporate them in this document, but I think
+    that might be wrong as this will be predominantly about the
+    quickbook\/boostbook toolset.
+  * Mention some of the other tools used (python docutils, any other?).
+* Advantages of our toolset.
+
+[endsect]
+
+[section:tools Boost Tools]
+
+* John's diagram from
+  [@https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted
+  the wiki page].
+
+For each tool:
+
+* A brief description.
+* Example, or link to an example.
+* Link to documentation.
+
+[endsect]
+
+[section:installation Installation]
+
+[section:recipies Recipies]
+
+* Based on
+  [@https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted
+  the wiki page].
+
+[endsect]
+
+[section:prebuild Pre-build quickbook]
+[endsect]
+
+[section:pdf Building PDFs]
+
+This will probably be separate from the installation recipies as it seems to
+be mostly the same for all platforms.
+
+[endsect]
+
+[endsect]
+
+[/ Further sections:
+
+  * Library file layout + jamfiles
+]