[/
    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`.

