Re: [boost] Do we need BoostBook?

Subject: Re: [boost] Do we need BoostBook?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-12-08 05:34:43

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Vladimir Prus
> Sent: 08 December 2014 10:06
> To: boost_at_[hidden]
> Subject: Re: [boost] Do we need BoostBook?
> 
> On 12/08/2014 12:04 PM, John Maddock wrote:
> >>> 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.
> >
> > OK, my mistake, yes admonishments get transformed into tables, if this
> > is a problem I suggest you raise it with the Docbook guys - they've been
quite
> helpful to us in the past as I recall.
> 
> I'm fine with non-graphical admonishments (which are divs).
> 
> >>> 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.
> >
> > Are you sure?  It's always seemed to me that docbook (and associated
> > stylesheets) is rather well maintained, albeit they're under-resourced
> > (like everyone!)
> 
> It's subjective, so no, I'm not sure. But the fact that it uses tables
everywhere, is not
> mobile-friendly, and does not have modern navigation, speaks so.

It's possible, but I'm not sure that anyone would *want* to do more than look up
the odd factette on a mobile.  But it's certainly possible and if we can make is
better, we should do it.

Would anyone want Boost docs on a tablet as bedtime reading? (except in case of
serious insomnia ;-)

So I don't think that being tablet friendly is *terribly* important -
hyperlinking, search and indexing and completeness are much more important
design objectives and we are not doing too badly on these.

> If we think tablet use case is important, a single line in the generated HTML
will improve matters considerably (the meta viewport tag).

Provided this has no cost to the desktop user, perhaps we should try to add
this?

Paul

PS I note that the PDF reader in Windows 8.1 is so dumbed down that it makes
navigation of documents more than a few pages long almost impossible.  This
makes reading, say, Boost.Math an unpleasant experience, even with the side
pages on.