Re: [boost] Do we need BoostBook?

Subject: Re: [boost] Do we need BoostBook?
From: Vladimir Prus (vladimir_at_[hidden])
Date: 2014-12-08 02:47:33

John,

On 12/06/2014 03:12 PM, John Maddock wrote:
>> I've noticed that Boost.Build documentation, created with BoostBook,
>> explicitly sets a small, and IMO unreadable, font, so I went
>> to fix that, and some other things, as shown at:
>>
>>      http://goo.gl/VWYh2P
>
> The font and size is set with our stylesheets, nothing to do with Boostbook/docbook.

Right, and I had no problem changing that - and it's live at, for example:

                
if anybody wants to comment on the style itself.

>> However, after a few easy tweaks, I'm stuck at the fact that
>> BoostBook/DocBook produces fairly old-fashioned HTML. For example,
>> the Boost logo at top is actually a table,
>
> We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago
> and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only.
Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

>  > and the "tip" block is also a
>> table, which makes tweaking the layout with CSS
>> quite a bit more complex. Also, some of the conceptually trivial things,
>> like putting some front matter in index.html,
>> appear to require XSLT customization.
>
> I think that's this XSL param: http://docbook.sourceforge.net/release/xsl/current/doc/html/chunk.first.sections.html
>
> When "false" the first section ends up in the index page (right after the index), or maybe you meant something else?

Thanks, I did not know about this option, and it's an improvement from my point of view, and I've enabled it for Boost.Build.

The original question was about adding some front-matter that would not be present in TOC, and I've ended up abusing the
'dedication' element for it.

>> As heretic as it sounds, do we get any benefits from BoostBook? It's a
>> complex vocabulary, with complex toolchain,
>> and while PDF generation sounded nice 10 years ago, printing HTML into
>> PDF is a viable option these days - and nobody
>> would want to print entire Boost documentation anyway?
>
> Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML.
> BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the
> left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it.

-- 
Vladimir Prus
CodeSourcery / Mentor Embedded
http://vladimirprus.com