[/ 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 : 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 : boost.root=../../../../.. 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`.