Re: [boost] Do we need BoostBook?

Subject: Re: [boost] Do we need BoostBook?
From: John Maddock (boost.regex_at_[hidden])
Date: 2014-12-06 07:12:23

> 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.

> 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!

 > 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?

> 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.

Of course if I'm online I tend to google rather than open up the local 
docs, but that doesn't always work.

John.