|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r85468 - in trunk/tools/quickbook/doc: . boost-doc-tools boost-doc-tools/images
From: dnljms_at_[hidden]
Date: 2013-08-25 15:09:41
Author: danieljames
Date: 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013)
New Revision: 85468
URL: http://svn.boost.org/trac/boost/changeset/85468
Log:
Start a more general intro to the documentation tools.
Mostly just the content from the wiki. I left out installing latex for now,
as it's a bit tricky, and rarely required.
Added:
trunk/tools/quickbook/doc/boost-doc-tools/
trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk (contents, props changed)
trunk/tools/quickbook/doc/boost-doc-tools/images/
trunk/tools/quickbook/doc/boost-doc-tools/images/documentation-toolchain.png (contents, props changed)
trunk/tools/quickbook/doc/boost-doc-tools/install.qbk (contents, props changed)
trunk/tools/quickbook/doc/boost-doc-tools/intro.qbk (contents, props changed)
trunk/tools/quickbook/doc/boost-doc-tools/pdfs.qbk (contents, props changed)
trunk/tools/quickbook/doc/doc-guide.qbk (contents, props changed)
Text files modified:
trunk/tools/quickbook/doc/Jamfile.v2 | 7 +
trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk | 8 +
trunk/tools/quickbook/doc/boost-doc-tools/install.qbk | 239 ++++++++++++++++++++++++++++++++++++++++
trunk/tools/quickbook/doc/boost-doc-tools/intro.qbk | 20 +++
trunk/tools/quickbook/doc/boost-doc-tools/pdfs.qbk | 24 ++++
trunk/tools/quickbook/doc/doc-guide.qbk | 5
6 files changed, 302 insertions(+), 1 deletions(-)
Modified: trunk/tools/quickbook/doc/Jamfile.v2
==============================================================================
--- trunk/tools/quickbook/doc/Jamfile.v2 Sun Aug 25 13:51:54 2013 (r85467)
+++ trunk/tools/quickbook/doc/Jamfile.v2 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -13,13 +13,18 @@
using boostbook ;
using quickbook ;
+# Targets for building individual parts for combined documentation.
xml quickbook : quickbook.qbk ;
+xml boost-doc-tools : boost-doc-tools/boost-doc-tools.qbk ;
+
+# Target for building the full documentation guide from quickbook.
+xml doc-guide : doc-guide.qbk ;
path-constant images : ../../../doc/src ;
boostbook standalone
:
- quickbook
+ doc-guide
:
<format>html:<xsl:param>boost.root=../../../..
<format>html:<xsl:param>img.src.path=../../../../doc/html/
Added: trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/boost-doc-tools/boost-doc-tools.qbk 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -0,0 +1,8 @@
+[quickbook 1.6]
+[part Introduction to the Boost documentation tools
+[id boost_doc_tools]
+]
+
+[include intro.qbk]
+[include install.qbk]
+[include pdfs.qbk]
Added: trunk/tools/quickbook/doc/boost-doc-tools/images/documentation-toolchain.png
==============================================================================
Binary file. No diff available.
Added: trunk/tools/quickbook/doc/boost-doc-tools/install.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/boost-doc-tools/install.qbk 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -0,0 +1,239 @@
+[chapter Installing Boostbook and Quickbook
+[id boost_doc_tools.install]
+[quickbook 1.5]
+[source-mode teletype]
+]
+
+[section:intro Introduction]
+
+This chapter describes how to install the basic documentation tools that make
+up the Boost documentation toolchain. This isn't enough for building the full
+Boost documentation, but it's enough to start using quickbook or boostbook.
+The basic requirements are:
+
+* Boost Build
+* `xsltproc`, which is a part of [@http://xmlsoft.org/XSLT/ `libxslt`].
+* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
+ stylesheets] - Note that sourceforge has organized these files so that
+ the documentation for the stylesheets is the first set of files
+ offered for download; you have to look farther down for the actual
+ stylesheets.
+* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD]
+
+Installing all of these parts can be quite tricky, so the next section
+contains recipies to set them up for [link install.recipies.windows Windows],
+[link install.recipies.mac OS X], [link install.recipies.debian Debian and Ubuntu].
+Other configurations are of course possible, but we've found these ones
+effective.
+
+They assume that you have already installed Boost.Build and are familiar with
+the basics of using it, see [@boost:/more/getting_started/index.html the
+getting started guide] for an introduction. It's generally a good idea to
+install Boost.Build from source, the prebuilt packages are often out of date.
+
+[endsect]
+
+[section:recipies Installation Recipies]
+
+[section:windows Windows]
+
+Since most of these command line tools were developed for Unix, and Unix style,
+platforms they are an awkward fit for windows and recipies requires more effort.
+This leads to two possible techniques, firstly install with cygwin which
+handles much of the complexity for you, but requires that you always use it
+from within Cygwin. The other is to manually install the toolchain for use from
+the windows command prompt. This gives a more integrated user experience but is
+quite fiddly to get right.
+
+[section:cygwin Cygwin Install]
+
+These instruction assume that cygwin has been installed to [^c:\\cygwin].
+
+Install these packages:
+
+* [^ Libs/libxml2]
+* [^ Libs/libxslt]
+* [^ Text/docbook-xml42]
+* [^ Text/docbook-xsl]
+* [^ Devel/gcc4-g++] (optional, if you don't have a compiler).
+* [^ Devel/doxygen] (optional, for generating reference documentation
+ from C++ source files).
+
+Now we need to configure Boost.Build to use these tools. This step is different
+depending on whether you're using Boost.Build built with cygwin, or for native
+windows. For cygwin you need to add to your `user-config.jam` file:
+
+ using xsltproc ;
+
+ using boostbook
+ : /usr/share/docbook-xsl
+ : /usr/share/xml/docbook/4.2
+ ;
+
+ using quickbook ;
+
+ # If you installed doxygen:
+ using doxygen ;
+
+When using a native (non-Cygwin) Boost.Build, you'll need to specify the
+windows paths to the various tools:
+
+ # Adjust this path to the location of your cygwin install.
+ CYGWIN_DIR = c:/cygwin ;
+
+ using xsltproc
+ : $(CYGWIN_DIR)/bin/xsltproc.exe ;
+
+ using boostbook
+ : $(CYGWIN_DIR)/usr/share/docbook-xsl
+ : $(CYGWIN_DIR)/usr/share/xml/docbook/4.2
+ ;
+
+ using quickbook ;
+
+ # If you installed doxygen:
+ using doxygen
+ : $(CYGWIN_DIR)/bin/doxygen.exe
+ ;
+
+[endsect] [/ cygwin ]
+
+[section:manual Manually installing windows native tools]
+
+In order to install the tools under windows, we need to create a directory
+structure somewhat similar to the unix filesystem. We're going to place this
+in [^c:\\boost-tools], if you want to put it elsewhere, just follow the
+instructions, adjusting the paths accordingly. This is also a good location
+to use as the prefix when installing Boost.Build.
+
+* Create directory for boost tools, say [^ c:\\boost-tools].
+* Create directory for binaries, [^ c:\\boost-tools\\bin].
+* Add the [^bin] directory to the path (e.g. in Xp, right click on 'My
+ Computer', click on 'Properties', then the 'Advanced' tab and click on
+ 'Environment variables' to open a dialog where you can edit the PATH
+ variable).
+
+Next you need to download several xml tools from
+[@http://www.zlatkovic.com/pub/libxml/ Igor Zlatkovic].
+You require: [^ iconv], [^ libxml2] and [^ libxslt], [^ zlib].
+Then unzip these into the [^c:\\boost-tools] directory.
+This should place the `xsltproc` exectuable in [^c:\\boost-tools\\bin].
+
+Next make a directory for xml processing files at [^ c:\\boost-tools\\xml].
+
+* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
+ stylesheets] from their
+ [@http://sourceforge.net/project/showfiles.php?group_id=21935&
+ package_id=16608 Sourceforge download page] to
+ [^ c:\\boost-tools\\xml\\docbook-xsl].
+* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD] to
+ [^ c:\\boost-tools\\xml\\docbook-xml].
+
+[^ user-config.jam] in the boost build search path,
+for most people this will be [^ C:\\Documents and Settings\\['username]].
+
+ BOOST_TOOLS_DIR = c:/boost-tools ;
+ using xsltproc
+ : $(BOOST_TOOLS_DIR)/bin/xsltproc.exe"
+ ;
+
+ using boostbook
+ : $(BOOST_TOOLS_DIR)/xml/docbook-xsl
+ : $(BOOST_TOOLS_DIR)/xml/docbook-xml
+ ;
+
+ using quickbook ;
+
+Also, if you wish to use doxygen to generate reference documentation from
+C++ source headers, you'll need to install it. You can download it from
+[@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc the doxygen
+website]. The installer should add the executable to your path, so you just
+need to add to your [^ user-config.jam]:
+
+ using doxygen ;
+
+[endsect] [/ manual ]
+
+[endsect] [/ windows ]
+
+[section:mac OS X]
+
+If you're using Snow Leopard (OS X 10.6) or later, then you should already have
+the xml tools installed, so you just need to install the docbook xml and xslt
+files. The easiest way to do that is probably to use macports, install them
+with:
+
+ sudo port install docbook-xml-4.2 docbook-xsl
+
+For earlier versions of OS X, you'll also need to install `libxslt` to get
+an up to date version of `xsltproc`:
+
+ sudo port install libxslt docbook-xml-4.2 docbook-xsl
+
+You can also install `doxygen`, for generating reference documentation from
+C++ source files:
+
+ sudo port install doxygen
+
+Boost.Build knows the default install location for macports, so all you need
+to add to your `user-config.jam` is an instruction to use them:
+
+ using boostbook ;
+ using quickbook ;
+
+ # If you've installed doxygen:
+ using doxygen ;
+
+[endsect] [/ mac]
+
+[section:debian Debian and Ubuntu]
+
+Installing on Debian and Ubuntu is pretty easy, just install the packages using
+`apt-get` (or an alternative, such as `aptitude`):
+
+ sudo apt-get install xsltproc docbook-xsl docbook-xml
+
+You can also install `doxygen`, for generating reference documentation from
+C++ source files:
+
+ sudo apt-get install doxygen
+
+Boost.Build should be to find these packages without an explicit path, so just
+add to your `user-config.jam`:
+
+ using boostbook ;
+ using quickbook ;
+
+ # If you've installed doxygen:
+ using doxygen ;
+
+[endsect] [/ debian]
+
+[endsect]
+
+[section:quickbook Pre-build quickbook]
+
+Boost.Build automatically builds Quickbook when required to build the
+documentation, but as it
+takes a little while to build you might prefer to build it in advance.
+To do this, in the command line type (replacing [^$BOOST_ROOT] with the
+root directory of boost):
+
+ cd $BOOST_ROOT/tools/quickbook
+ b2 dist-bin
+
+Or for windows:
+
+ cd $BOOST_ROOT\\tools\\quickbook
+ b2 dist-bin
+
+Change [^ using quickbook] in [^ user-config.jam] to (replacing [^
+$BOOST_ROOT] with the root directory of boost, as before):
+
+ using quickbook : $BOOST_ROOT/dist/bin/quickbook ;
+
+Windows:
+
+ using quickbook : $BOOST_ROOT\\dist\\bin\\quickbook ;
+
+[endsect] [/quickbook]
Added: trunk/tools/quickbook/doc/boost-doc-tools/intro.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/boost-doc-tools/intro.qbk 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -0,0 +1,20 @@
+[quickbook 1.6]
+[chapter Introduction
+[id boost_doc_tools.introduction]
+]
+
+Much of the boost documentation is generated using a collection of
+documentation tools which make it easier to write documentation in the
+boost style, and give a consistent look and feel. Setting up and
+configuring these tools can be tricky, but once everything is in place,
+it's mostly quite easy to use. There's no requirement to use any of
+this, but feedback on the documentation generated with these tools
+is generally positive.
+
+The diagram below illustrates the way the various documentation tools
+fit together. Note that you don't have to use all of this, and the
+process is automated using Boost.Build, but having a rough
+understanding of the build process will help understand the tools
+better.
+
+[$../../tools/quickbook/doc/boost-doc-tools/images/documentation-toolchain.png]
Added: trunk/tools/quickbook/doc/boost-doc-tools/pdfs.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/boost-doc-tools/pdfs.qbk 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -0,0 +1,24 @@
+[chapter Building PDFs
+[id boost_doc_tools.pdfs]
+[source-mode teletype]
+]
+
+To build pdf you will need an FO processor, we recommend using
+[@http://www.renderx.com/download/personal.html
+XEP Personal edition]. You will also need a Java virtual machine to run the FO
+processor on.
+
+You will then need to edit your [^user-config.jam] file to point to the
+location of the FO processor, for example:
+
+ using fop :
+ # path to invocation batch file:
+ C:/Progra~1/RenderX/xep/xep.bat
+ :
+ # path to Java installation, this is ignored if you're using XEP:
+ C:/PROGRA~1/Java/j2re1.4.2_12
+ ;
+
+You should now be able to build pdf docs via:
+
+ bjam pdf
Added: trunk/tools/quickbook/doc/doc-guide.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/tools/quickbook/doc/doc-guide.qbk 2013-08-25 15:09:41 EDT (Sun, 25 Aug 2013) (r85468)
@@ -0,0 +1,5 @@
+[quickbook 1.6]
+[book Boost Documentation Tools]
+
+[include boost-doc-tools/boost-doc-tools.qbk]
+[include quickbook.qbk]
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