232 lines
7.6 KiB
Plaintext
232 lines
7.6 KiB
Plaintext
[/
|
|
Copyright 2013-2018 Daniel James
|
|
|
|
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)
|
|
]
|
|
|
|
[chapter Boostbook and Docbook build parameters
|
|
[id boost_doc_tools.parameters]
|
|
[quickbook 1.6]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
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
|
|
[@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/param.html
|
|
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
|
|
[@boost:tools/boostbook/xsl/ `tools/boostbook/xsl/`].
|
|
|
|
For a complete description of publishing using the DocBook XSL stylesheets,
|
|
see Bob Stayton's [@http://www.sagehill.net/book-description.html
|
|
DocBook XSL: The Complete Guide], while the BoostBook XSL stylesheets do
|
|
customise the documentation build in several places, it should all be
|
|
relevant.
|
|
|
|
[/TODO:
|
|
use.id.as.filename
|
|
boost.include.libraries
|
|
Look at fo.xsl
|
|
caramel
|
|
boost.section.class.add.id
|
|
boost.max.id.part.length
|
|
boost.syntax.highlight
|
|
]
|
|
|
|
[heading:chunk Chunking settings]
|
|
|
|
Chunking is process by which docbook splits a document in pages (or chunks).
|
|
These are the paramters we've found useful:
|
|
|
|
[variablelist
|
|
[[chunk.section.depth]
|
|
[Control the depth of nested sections that get included in a page.
|
|
Default value is `1`]]
|
|
[[chunk.first.sections]
|
|
[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:
|
|
|
|
* [@http://www.sagehill.net/docbookxsl/Chunking.html
|
|
Chunking into multiple files - DocBook XSL: The Complete Guide]
|
|
* [@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/chunking.html
|
|
DocBook Reference documentation]
|
|
|
|
[heading:toc Table of Contents settings]
|
|
|
|
DocBook table of contents generation is highly customisable, these are the
|
|
parameters we've found useful:
|
|
|
|
[variablelist
|
|
[[toc.section.depth]
|
|
[The depth of recursive sections that are included in the
|
|
table of contents]]
|
|
[[toc.max.dpeth]
|
|
[The maximum depth that should be included in the table of contents.
|
|
This includes all structural elements, such as parts, chapters etc.]]
|
|
[[generate.section.toc.level]
|
|
[The depth of sections that will have table of contents generated.]]
|
|
]
|
|
|
|
For more info:
|
|
|
|
* [@http://www.sagehill.net/docbookxsl/SectionNumbering.html
|
|
Chapter and section numbering - DocBook XSL: The Complete Guide]
|
|
* [@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/toc_index.html
|
|
DocBook Reference Documentation]
|
|
|
|
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.
|
|
|
|
[heading:link_locations Link Locations]
|
|
|
|
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.
|
|
|
|
[variablelist
|
|
[[boost.root]
|
|
[Path to root of boost (or module) from the destination directory]]
|
|
[[boost.url.prefix]
|
|
[Set this to URL of the Boost website, so that absolute links to
|
|
the website will be used.]]
|
|
[[boost.header.root]
|
|
[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.]]
|
|
]
|
|
|
|
[/The trickiest variable to get right is probably the `boost.root` variable,
|
|
this is the relative path from the genrated documentation to boost's root
|
|
directory. For a library with the path `libs/example`, the documentation
|
|
would typically be in the directory `libs/example/doc`. The HTML Documentation
|
|
would be generated in the directory `libs/example/doc/html`, and the relative
|
|
path to root from that directory is `../../../..`.]
|
|
|
|
[heading:image_link_locations Image Link Locations]
|
|
|
|
[variablelist
|
|
[[img.src.path]
|
|
[(Docbook parameter) Path that image links are relative to, from the
|
|
destination directory]]
|
|
[[boost.graphics.root]
|
|
[Path that contains the BoostBook graphic files, realitve to the
|
|
destination directory.]]
|
|
[/ Not sure if it's worth mentioning these docbook parameters:
|
|
[[admon.graphics.path]
|
|
[???]]
|
|
[[navig.graphics.path]
|
|
[???]]
|
|
[[callout.graphics.path]
|
|
[???]]
|
|
]
|
|
]
|
|
|
|
[heading:style Style Parameters]
|
|
|
|
[variablelist
|
|
[[boost.defaults]
|
|
[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.]]
|
|
[[html.stylesheet]
|
|
[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.]]
|
|
[/[admon.style]
|
|
[???]]
|
|
[/[admon.graphics]
|
|
[???]]
|
|
[/[navig.graphics]
|
|
[???]]
|
|
[/[navig.graphics.extension]
|
|
[???]]
|
|
]
|
|
|
|
[heading:navbar Navbar]
|
|
|
|
[variablelist
|
|
[[nav.layout]
|
|
[???]]
|
|
[[nav.border]
|
|
[???]]
|
|
[[nav.flow]
|
|
[???]]
|
|
[[boost.website]
|
|
[???]]
|
|
[[boost.image.src]
|
|
[???]]
|
|
[[boost.image.alt]
|
|
[???]]
|
|
[[boost.image.w]
|
|
[???]]
|
|
[[boost.image.h]
|
|
[???]]
|
|
[[boost.libraries]
|
|
[???]]
|
|
]
|
|
|
|
[heading:reference Reference Documentation Parameters]
|
|
|
|
[variablelist
|
|
[[boostbook.verbose]
|
|
[???]]
|
|
[[boost.compact.function]
|
|
[???]]
|
|
[[boost.short.result.type]
|
|
[???]]
|
|
[[boost.compact.enum]
|
|
[???]]
|
|
[[boost.compact.typedef]
|
|
[???]]
|
|
[[max-columns]
|
|
[???]]
|
|
[[tempalte.param.brief]
|
|
[???]]
|
|
]
|
|
|
|
[heading:mathjax MathJax parameters]
|
|
|
|
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`.
|
|
|