documentation (ToC) question
When using Quickbook/BoostBook, how can a section ToC have two levels instead of just one? That is, if we have [library Boost.Core] [section:addressof addressof] [section Header 1] [section Synopsis] [section Example] [section Header 2] [section Synopsis] [section Example] how can the ToC of [section:addressof] show the Synopsis and Example nested within Header 1 and Header 2? I have tried various combinations of generate.section.toc.level, toc.max.depth, toc.section.depth, but nothing seems to produce the result I want.
On 10 June 2014 11:08, Peter Dimov <lists@pdimov.com> wrote:
When using Quickbook/BoostBook, how can a section ToC have two levels instead of just one?
That is, if we have
[library Boost.Core] [section:addressof addressof] [section Header 1] [section Synopsis] [section Example] [section Header 2] [section Synopsis] [section Example]
how can the ToC of [section:addressof] show the Synopsis and Example nested within Header 1 and Header 2?
I have tried various combinations of generate.section.toc.level, toc.max.depth, toc.section.depth, but nothing seems to produce the result I want.
I don't know of the top of my head, but the Boost.Core documentation is currently built as part of the combined documentation which means that it can't use its own settings in the boostbook to html translation stage. We'll have to change that if you want to customise these things.
Daniel James wrote:
I don't know of the top of my head, but the Boost.Core documentation is currently built as part of the combined documentation which means that it can't use its own settings in the boostbook to html translation stage. We'll have to change that if you want to customise these things.
I don't insist on customising them - it's just that the local Jamfile.v2 already had the options and I wanted to change the ToC appearance, but couldn't figure out how. It wouldn't matter if the docs are part of the combined documentation. Is the combined documentation for develop or master currently live somewhere? If section ToCs can't have more than one level, I think that it'd be better to flatten the structure and not nest the sections the way I've structured them.
On 10 June 2014 11:47, Peter Dimov <lists@pdimov.com> wrote:
Is the combined documentation for develop or master currently live somewhere?
They would normally be here: http://www.boost.org/doc/libs/develop/ http://www.boost.org/doc/libs/master/ But the last build failed, so there won't be anything until I manage to do a successful run. Hopefully later today.
I don't know of the top of my head, but the Boost.Core documentation is currently built as part of the combined documentation which means that it can't use its own settings in the boostbook to html translation stage. We'll have to change that if you want to customise these things.
I don't insist on customising them - it's just that the local Jamfile.v2 already had the options and I wanted to change the ToC appearance, but couldn't figure out how. It wouldn't matter if the docs are part of the combined documentation.
Is the combined documentation for develop or master currently live somewhere?
If section ToCs can't have more than one level, I think that it'd be better to flatten the structure and not nest the sections the way I've structured them.
I believe toc.max.depth is the param you want, for example like this: http://www.boost.org/doc/libs/1_55_0/libs/math/doc/html/dist.html See http://docbook.sourceforge.net/release/xsl/current/doc/html/toc_index.html for all the TOC options. HTH, John.
John Maddock wrote:
I believe toc.max.depth is the param you want, for example like this: http://www.boost.org/doc/libs/1_55_0/libs/math/doc/html/dist.html
No, that's not quite what I wanted. toc.max.depth controls the depth of the master ToC, and that's quite fine; what I wanted was to control the depth of the section ToC. For example, here http://beta.boost.org/doc/libs/1_55_0/doc/html/atomic/thread_coordination.ht... there's a section ToC right after "Thread coordination using Boost.Atomic", and I wanted nested sections to appear inside, indented, as they do in the master ToC.
On Tuesday 10 June 2014 15:03:13 Peter Dimov wrote:
John Maddock wrote:
I believe toc.max.depth is the param you want, for example like this: http://www.boost.org/doc/libs/1_55_0/libs/math/doc/html/dist.html
No, that's not quite what I wanted. toc.max.depth controls the depth of the master ToC, and that's quite fine; what I wanted was to control the depth of the section ToC. For example, here
http://beta.boost.org/doc/libs/1_55_0/doc/html/atomic/thread_coordination.ht ml
there's a section ToC right after "Thread coordination using Boost.Atomic", and I wanted nested sections to appear inside, indented, as they do in the master ToC.
I think you can achieve that if you make each sub-library docs as a separate document, not a part included into the whole Boost.Core document. You'll have to compile each sub-library docs separately in the Jamfile. This way it was done in Boost.Utility before we moved the components from there. Naturally, you'll need to generate the root Boost.Core page from a separate QuickBook document, and insert links to the sub-library docs in it. I suspect, this won't work well with PDF.
On 10 June 2014 13:11, Andrey Semashev <andrey.semashev@gmail.com> wrote:
I think you can achieve that if you make each sub-library docs as a separate document, not a part included into the whole Boost.Core document. You'll have to compile each sub-library docs separately in the Jamfile. This way it was done in Boost.Utility before we moved the components from there.
If you're achieving your result by creating separate documents, you can possibly get the same effect in a single document by structuring it as a 'book' or 'part' or something similar. This requires writing boostbook or using a quickbook 1.6 document. If it has the 'book' type, it can include 'library' and 'chapter' documentation in it, and docbook will format them in a pretty similar manner to if they're standalone. You can see this in the quickbook documentation. Especially on the feature/doc-tools-documentation where 'doc-guide.qbk' is a book that includes two parts. You can see it at: http://boostorg.github.io/quickbook/doc/html/index.html An alternative is to use escaped boostbook to get a similar effect, as they do in the math documentation. Unfortunately, it's tricky for libraries in the combined documentation, as document type 'library' converts to 'chapter' in docbook, and it's invalid to include anything but sections in a chapter. You might be able to get away with it, but there's always the possibility of problems with invalid markup. There's a little bit of documentation here: http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/syntax/structure.htm...
participants (4)
-
Andrey Semashev -
Daniel James -
John Maddock -
Peter Dimov