1[/ 2 Copyright 2013-2018 Daniel James 3 4 Distributed under the Boost Software License, Version 1.0. 5 (See accompanying file LICENSE_1_0.txt or copy at 6 http://www.boost.org/LICENSE_1_0.txt) 7] 8 9[chapter Boostbook and Docbook build parameters 10[id boost_doc_tools.parameters] 11[quickbook 1.6] 12[source-mode teletype] 13] 14 15Back in the simple examples, you might remember how `boost.root` was passed 16to the Boost.Build script: 17 18 boostbook simple : simple.xml : 19 <xsl:param>boost.root=../../../../.. 20 ; 21 22There are many such XSL parameters that can be used, for example to 23split the documentation into a file for each section: 24 25 boostbook simple : simple.xml : 26 <xsl:param>boost.root=../../../../.. 27 <xsl:param>chunk.section.depth=99 28 ; 29 30In this case, `boost.root` is a parameter for the BoostBook XSL stylesheets, 31while `chunk.section.depth` is a parameter for the DocBook XSL stylesheets. 32In this page are some of the parameters we've found useful for generating 33documentation, but there are far more than can be listed here. 34For DocBook XSL parameters, see the 35There are far more DocBook XSL parameters than can be listed here, see the 36[@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/param.html 37DocBook XSL documentation] for a full list. This also isn't a complete list 38of BoostBook XSL parameters, if you wish to look into them in more detail, 39the best source of information is the XSL source code at 40[@boost:tools/boostbook/xsl/ `tools/boostbook/xsl/`]. 41 42For a complete description of publishing using the DocBook XSL stylesheets, 43see Bob Stayton's [@http://www.sagehill.net/book-description.html 44DocBook XSL: The Complete Guide], while the BoostBook XSL stylesheets do 45customise the documentation build in several places, it should all be 46relevant. 47 48[/TODO: 49 use.id.as.filename 50 boost.include.libraries 51 Look at fo.xsl 52 caramel 53 boost.section.class.add.id 54 boost.max.id.part.length 55 boost.syntax.highlight 56] 57 58[heading:chunk Chunking settings] 59 60Chunking is process by which docbook splits a document in pages (or chunks). 61These are the paramters we've found useful: 62 63[variablelist 64 [[chunk.section.depth] 65 [Control the depth of nested sections that get included in a page. 66 Default value is `1`]] 67 [[chunk.first.sections] 68 [By default the first chunk is included with it's parent, i.e. 69 under the table of contents. Set to `1` to create a page for 70 the chunk.]] 71] 72 73For more info, and many more paramters: 74 75* [@http://www.sagehill.net/docbookxsl/Chunking.html 76 Chunking into multiple files - DocBook XSL: The Complete Guide] 77* [@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/chunking.html 78 DocBook Reference documentation] 79 80[heading:toc Table of Contents settings] 81 82DocBook table of contents generation is highly customisable, these are the 83parameters we've found useful: 84 85[variablelist 86 [[toc.section.depth] 87 [The depth of recursive sections that are included in the 88 table of contents]] 89 [[toc.max.dpeth] 90 [The maximum depth that should be included in the table of contents. 91 This includes all structural elements, such as parts, chapters etc.]] 92 [[generate.section.toc.level] 93 [The depth of sections that will have table of contents generated.]] 94] 95 96For more info: 97 98* [@http://www.sagehill.net/docbookxsl/SectionNumbering.html 99 Chapter and section numbering - DocBook XSL: The Complete Guide] 100* [@http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/toc_index.html 101 DocBook Reference Documentation] 102 103BoostBook adds an extra parameter, `boost.noexpand.chapter.toc`, to the DocBook 104parameters for generating the table of contents for a book. This adjusts a 105book's table of contents so they don't show the contents of chapters, 106regardless of the `toc.max.depth` parameter. 107 108This is mainly used in the Boost.Math documentation but could be useful in 109large books so that the top level table of contents aren't overwhelmed by 110the individual chapeter contents. 111 112[heading:link_locations Link Locations] 113 114When linking to other documentation Boost, differnet links need to be 115generated for different documentation styles. HTML documentation needs to use 116relative links, to that they'll work when the HTML is viewed offline. 117PDFs need to use absolute links to the website, so that they will work wherever 118the documentation is viewed. 119 120[variablelist 121 [[boost.root] 122 [Path to root of boost (or module) from the destination directory]] 123 [[boost.url.prefix] 124 [Set this to URL of the Boost website, so that absolute links to 125 the website will be used.]] 126 [[boost.header.root] 127 [Set this to use a different root for links to headers. 128 Can be used if the header files are not available in their 129 normal location.]] 130] 131 132[/The trickiest variable to get right is probably the `boost.root` variable, 133this is the relative path from the genrated documentation to boost's root 134directory. For a library with the path `libs/example`, the documentation 135would typically be in the directory `libs/example/doc`. The HTML Documentation 136would be generated in the directory `libs/example/doc/html`, and the relative 137path to root from that directory is `../../../..`.] 138 139[heading:image_link_locations Image Link Locations] 140 141[variablelist 142 [[img.src.path] 143 [(Docbook parameter) Path that image links are relative to, from the 144 destination directory]] 145 [[boost.graphics.root] 146 [Path that contains the BoostBook graphic files, realitve to the 147 destination directory.]] 148 [/ Not sure if it's worth mentioning these docbook parameters: 149 [[admon.graphics.path] 150 [???]] 151 [[navig.graphics.path] 152 [???]] 153 [[callout.graphics.path] 154 [???]] 155 ] 156] 157 158[heading:style Style Parameters] 159 160[variablelist 161 [[boost.defaults] 162 [This is used by the build system to tell BoostBook to use 163 the standard paths in the Boost source tree, and the standard 164 boost documentation heading when building documentation. 165 You should never need to use it manually, as it doesn't make 166 much sense outside of the Boost source tree. You can override 167 the default parameters it sets if you don't like them.]] 168 [[html.stylesheet] 169 [Path from the generated documentation to the stylesheets. 170 This defaults to `boostbook.css`, or to a directory under `boost.root` 171 if `boost.defaults` is set to `Boost`. Override this if you want 172 to use your own stylesheet.]] 173 [/[admon.style] 174 [???]] 175 [/[admon.graphics] 176 [???]] 177 [/[navig.graphics] 178 [???]] 179 [/[navig.graphics.extension] 180 [???]] 181] 182 183[heading:navbar Navbar] 184 185[variablelist 186 [[nav.layout] 187 [???]] 188 [[nav.border] 189 [???]] 190 [[nav.flow] 191 [???]] 192 [[boost.website] 193 [???]] 194 [[boost.image.src] 195 [???]] 196 [[boost.image.alt] 197 [???]] 198 [[boost.image.w] 199 [???]] 200 [[boost.image.h] 201 [???]] 202 [[boost.libraries] 203 [???]] 204] 205 206[heading:reference Reference Documentation Parameters] 207 208[variablelist 209 [[boostbook.verbose] 210 [???]] 211 [[boost.compact.function] 212 [???]] 213 [[boost.short.result.type] 214 [???]] 215 [[boost.compact.enum] 216 [???]] 217 [[boost.compact.typedef] 218 [???]] 219 [[max-columns] 220 [???]] 221 [[tempalte.param.brief] 222 [???]] 223] 224 225[heading:mathjax MathJax parameters] 226 227BoostBook has experimental support for MathJax, an open source JavaScript 228script that is used to display mathematics in the browser. This is activated 229by setting the `boost.mathjax` parameter to 1, and the location can be set 230using `boost.mathjax.script`. 231 232