Re: [Boost-docs] [Quickbook]

Subject: Re: [Boost-docs] [Quickbook]
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-06 11:12:29

On 6 October 2011 11:47, Beman Dawes <bdawes_at_[hidden]> wrote:
> In looking at .../tools/quickbook/doc/Jamfile.v2, I see:
>
>        <xsl:param>generate.section.toc.level=3
>        <xsl:param>chunk.section.depth=1
>        <xsl:param>chunk.first.sections=1
>        ...
>
> Googling for what these might mean turns up:
> http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
>
> Is that the best reference for these params?

Yes, they're docbook parameters.

> Why are they there? The output looks OK if they are commented out.

They control how the table of contents are generated, and how the
document is split up into html files (chunked). I added
'chunk.section.depth=1' so that the standalone quickbook documentation
would be chunked in a similar manner to the combined documentation.

> Should someone who is trying to learn how to use Quickbook (1) Learn
> DocBook first, or (2) Spend a few minutes reading about DocBook, but
> then only reference DocBook docs when needed, or (3) Ignore DocBook
> and look somewhere else for <xsl:param> docs, (4) some other approach?
> If the answer is (2), are there some specific DocBook features that a
> new QuickBook user should study?

It's best to just start with just quickbook at first and use the
default build. A basic understanding of docbook might help, but
shouldn't be necessary. To do more advanced stuff you need to know
docbook, but you can ignore it at first, and maybe continue to do so.

Quickbook docinfo isn't very well documented, so if you want to fully
understand that you currently need to look at the docbook
documentation, but that's not something that most people are concerned
with. Although I started writing some more documentation at:

https://svn.boost.org/svn/boost/branches/quickbook-dev/tools/quickbook/doc/structure.qbk

Btw. you might not be able to build the documentation on that branch
with quickbook from trunk. I've quite got a lot of changes that I'm
not going to add to trunk until after the next release.