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.