Default documentation settings
What is the value of chunk.section.depth used, for those Boost libraries whose documentation is supplied only in QBK form (not the generated HTML from the QBK)? It appears to be 1, i.e. my sections-within-sections are not broken into separate pages. If so, could we make the default xsl:paramchunk.section.depth=2? Glen
wow - wouldn't this affect ALL the documentation built with boost book in somewhat surprising ways? Couldn't you just override the boost book value in documentation for your own library? Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Default-documentation-settings-tp4667224p... Sent from the Boost - Dev mailing list archive at Nabble.com.
On Wed, Sep 3, 2014 at 11:11 AM, Robert Ramey
wow - wouldn't this affect ALL the documentation built with boost book in somewhat surprising ways?
I'm not suggesting changing the tooling defaults: I'm suggesting changing the default configuration used for http://www.boost.org/doc/libs/1_56_0/doc/html/libraries.html - and yes, it would affect all library documentation included there - but right now I know of no way to provide specific settings per library documentation. The only solution appears to be: Don't provide just a QBK to be part of the Boost HTML documentation, but generate the HTML (or the XML) from the QBK with your own settings, and provide that to the documentation generation process.
Couldn't you just override the boost book value in documentation for your own library?
I have my own custom settings used in my Jamfile.v2: https://github.com/boostorg/align/blob/master/doc/Jamfile.v2 - These are not used when the master HTML documentation is generated. Now I could generate the HTML using my own settings, and place the generated HTML in my doc/ and use that for the documentation, but that is less desirable. If there is no way to provide library-specific settings for the main HTML documentation, I'd be interested in changing the defaults used for all libraries if all the other authors were on board with sections of depth 2 being chunked instead of 1. Glen
Glen Fernandes wrote
If there is no way to provide library-specific settings for the main HTML documentation, I'd be interested in changing the defaults used for all libraries if all the other authors were on board with sections of depth 2 being chunked instead of 1.
I'm thinking it would be easier to find a way for each library to manage it's settings with overrides than try to get all libraries tweaked to work with some common settings. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Default-documentation-settings-tp4667224p... Sent from the Boost - Dev mailing list archive at Nabble.com.
On Wed, Sep 3, 2014 at 12:49 PM, Robert Ramey wrote:
I'm thinking it would be easier to find a way for each library to manage it's settings with overrides than try to get all libraries tweaked to work with some common settings.
Robert Ramey
While I don't know enough about Quickbook or Boostbook to know if it would be easier: it would certainly be more desirable if libraries can choose their own settings for simple things like section chunking or TOC creation. There are somewhat ugly workarounds, e.g. creating splitting the content into separate QBK files that are included in the main one, with these new files using an [article] header, but being able to just choose different parameters per library is certainly the cleaner approach. Glen
participants (2)
-
Glen Fernandes -
Robert Ramey