|
Back in the simple examples, you might remember how boost.root
was passed to the Boost.Build script:
boostbook simple : simple.xml :
<xsl:param>boost.root=../../../../..
;
There are many such XSL parameters that can be used, for example to split the documentation into a file for each section:
boostbook simple : simple.xml :
<xsl:param>boost.root=../../../../..
<xsl:param>chunk.section.depth=99
;
In this case, boost.root is a parameter for the BoostBook XSL
stylesheets, while chunk.section.depth is a parameter for the
DocBook XSL stylesheets. In this page are some of the parameters we've found
useful for generating documentation, but there are far more than can be listed
here. For DocBook XSL parameters, see the There are far more DocBook XSL
parameters than can be listed here, see the DocBook
XSL documentation for a full list. This also isn't a complete list
of BoostBook XSL parameters, if you wish to look into them in more detail,
the best source of information is the XSL source code at tools/boostbook/xsl/.
For a complete description of publishing using the DocBook XSL stylesheets, see Bob Stayton's DocBook XSL: The Complete Guide, while the BoostBook XSL stylesheets do customise the documentation build in several places, it should all be relevant.
Chunking is process by which docbook splits a document in pages (or chunks). These are the paramters we've found useful:
Control the depth of nested sections that get included in a page. Default
value is 1
By default the first chunk is included with it's parent, i.e. under
the table of contents. Set to 1 to create a page for the
chunk.
For more info, and many more paramters:
DocBook table of contents generation is highly customisable, these are the parameters we've found useful:
The depth of recursive sections that are included in the table of contents
The maximum depth that should be included in the table of contents. This includes all structural elements, such as parts, chapters etc.
The depth of sections that will have table of contents generated.
For more info:
BoostBook adds an extra parameter, boost.noexpand.chapter.toc,
to the DocBook parameters for generating the table of contents for a book.
This adjusts a book's table of contents so they don't show the contents of
chapters, regardless of the toc.max.depth parameter.
This is mainly used in the Boost.Math documentation but could be useful in large books so that the top level table of contents aren't overwhelmed by the individual chapeter contents.
When linking to other documentation Boost, differnet links need to be generated for different documentation styles. HTML documentation needs to use relative links, to that they'll work when the HTML is viewed offline. PDFs need to use absolute links to the website, so that they will work wherever the documentation is viewed.
Path to root of boost (or module) from the destination directory
Set this to URL of the Boost website, so that absolute links to the website will be used.
Set this to use a different root for links to headers. Can be used if the header files are not available in their normal location.
(Docbook parameter) Path that image links are relative to, from the destination directory
Path that contains the BoostBook graphic files, realitve to the destination directory.
This is used by the build system to tell BoostBook to use the standard paths in the Boost source tree, and the standard boost documentation heading when building documentation. You should never need to use it manually, as it doesn't make much sense outside of the Boost source tree. You can override the default parameters it sets if you don't like them.
Path from the generated documentation to the stylesheets. This defaults
to boostbook.css, or to a directory under boost.root
if boost.defaults is set to Boost. Override
this if you want to use your own stylesheet.
???
???
???
???
???
???
???
???
???
???
???
???
???
???
???
???
BoostBook has experimental support for MathJax, an open source JavaScript
script that is used to display mathematics in the browser. This is activated
by setting the boost.mathjax parameter to 1, and the location
can be set using boost.mathjax.script.