Re: [Boost-docs] [Quickbook] Different rendering in Chrome [FIXED]

Subject: Re: [Boost-docs] [Quickbook] Different rendering in Chrome [FIXED]
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-06-09 12:13:51

>> > However, if we could all agree on how they should look, and the
>> > conditions for breaking, then it appears this can be achieved with XSL
>> > property sets, see for example:
>> > http://docbook.sourceforge.net/release/xsl/current/doc/fo/section.leve
>> > l1.properties.html
>>
>> Could it be paramaterised? (so that we wouldn't have to agree)
>
> And there are 6 (5 useful?) of these for different levels of sections, and 
> one might reasonably want
> 1 and 2 to start on new page, but not minor sections 3,4,5 ...
>
> Note - If you use many smallish sections to improve the targeting of the 
> index terms (in html, an
> index entry only takes you to the html page - and the page might be quite 
> long so you might have to
> use find within the page to locate the index term), you may want not to 
> start each section with a
> new page.
>
> So quite useful to parameterize?

OK, patch attached.

Creates a new xsl:param: "boost.section.newpage.depth" which acts much like 
chunk.section.depth but on PDF rather than HTML output.  Defaults to 1 (put 
top level sections on new page only).  A more detailed description is in the 
patch - is there anywhere to document Boost-specific xsl:param's BTW?

OK to commit?

I note that there are still issues with Doxygen generated reference docs. 
In particular "Synopsis" block titles are rendered in a much larger font 
that should be used - often larger than the title of the enclosing section 
:-(  This is particularly noticeable in the PDF builds, but is true of the 
HTML docs as well.

Seem's like the problem is that the reference docs use a mixture of section, 
refentry, synopsis and refsect2 blocks.  Unfortunately, our ability to 
format these consistently is nothing like our ability to control nested 
sections.  Would we lose anything if we replaced all these different blocks 
with nested sections throughout?

Cheers, John.