DocBook toolchain: Disable auto toc for just one section's children?
My documentation has a reference section whose children are themselves sections automatically generated by a doxygen->xml->xslt->QuickBook chain. I want an automatically generated table of contents, but when I turn that on I get hundreds of entries for all of the individual classes and functions in the reference. Is there a way to disable just the child sections of my Reference section? Perhaps marking the section somehow and passing an xsl:param in the Jamfile or something? This would really help to put that last bit of polish on these docs. I noticed that Boost.Asio docs had the same problem, so the author just disabled the auto-toc and created a very small, manual one. Not the same. Ideas?
On 6/4/17 5:41 PM, Vinnie Falco via Boost wrote:
My documentation has a reference section whose children are themselves sections automatically generated by a doxygen->xml->xslt->QuickBook chain.
I want an automatically generated table of contents, but when I turn that on I get hundreds of entries for all of the individual classes and functions in the reference.
Is there a way to disable just the child sections of my Reference section? Perhaps marking the section somehow and passing an xsl:param in the Jamfile or something? This would really help to put that last bit of polish on these docs.
I noticed that Boost.Asio docs had the same problem, so the author just disabled the auto-toc and created a very small, manual one. Not the same.
This probably the simplest
Ideas?
There are some parameters which can be set when processing the boost/doc book. toc.section.depth This and related settings can be found here: http://www.sagehill.net/docbookxsl/index.html But as far as I know have to be set for the whole document. This didn't work for me because the desired depth varies depending on which chapter I'm considering. So the way I do it is by inserting <?dbhtml stop-chunking?> into the boost book xml. This is known as a "processing instruction". I don't know how one would do this with quickbook. Robert Ramey
On Sun, Jun 4, 2017 at 9:33 PM, Robert Ramey via Boost <boost@lists.boost.org> wrote:
Is there a way to disable just the child sections of my Reference section?
After a few hours of fumbling, I found a way: [block'''<reference id="hidden"><title>This Page Intentionally Left Blank 1/2</title>'''] [section:ref This Page Intentionally Left Blank 2/2] [include reference.qbk] [endsect] [block'''</reference>'''] Sections in reference.qbk no longer show up in auto-generated toc at any depth! But if you visit one of those reference pages and press "Up" in the navigation, you get those blank pages. I can live with that. It looks like this: http://vinniefalco.github.io/stage/beast/v49/ And here's the corresponding link to the doxygen-generated reference (I know you love those) http://vinniefalco.github.io/stage/beast/v49/beast/quickref.html
On Sun, Jun 4, 2017 at 9:33 PM, Robert Ramey via Boost <boost@lists.boost.org> wrote:
<?dbhtml stop-chunking?> ...I don't know how one would do this with quickbook.
I think this would work: [section title] [block'''<?dbhtml stop-chunking?>'''] But chunking is not the problem, I want to disable the generated table of contents for one section only.
On 05/06/2017 13:44, Vinnie Falco via Boost wrote:
On Sun, Jun 4, 2017 at 9:33 PM, Robert Ramey via Boost <boost@lists.boost.org> wrote:
<?dbhtml stop-chunking?> ...I don't know how one would do this with quickbook. I think this would work:
[section title] [block'''<?dbhtml stop-chunking?>''']
But chunking is not the problem, I want to disable the generated table of contents for one section only.
There's a lot of useful information on this here: http://www.sagehill.net/docbookxsl/TOCcontrol.html If the doxygen->docbook toolchain generates something other than sections (I think the default toolchain generates refentry's?) then it looks like you can do this with xsl params, but from your original message, I suspect you're using something else to convert to docbook/quickbook? Otherwise see the section on that page entitled "Keeping selected titles out of the TOC" - unfortunately this requires a custom XSLT layer. John. --- This email has been checked for viruses by AVG. http://www.avg.com
On Mon, Jun 5, 2017 at 9:42 AM, John Maddock via Boost <boost@lists.boost.org> wrote:
Otherwise see the section on that page entitled "Keeping selected titles out of the TOC" - unfortunately this requires a custom XSLT layer.
Thanks. I'm using a Jamfile with a boostbook target: https://github.com/vinniefalco/Beast/blob/master/doc/Jamfile#L74 How do I set up the custom XSLT layer? A few examples allude to custom .xsl files but I have not yet found instructions on how to get those files into the build.
participants (3)
-
John Maddock -
Robert Ramey -
Vinnie Falco