Boost logo

Boost :

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

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Daniel Pfeifer
> Sent: 07 December 2014 00:48
> To: Boost Developers List
> Subject: Re: [boost] Do we need BoostBook?
> On Sat, Dec 6, 2014 at 7:54 AM, Vladimir Prus <vladimir_at_[hidden]>
> wrote:
> > On 12/06/2014 02:41 AM, Robert Ramey wrote:
> >
> >> Vladimir Prus-3 wrote
> >>
> >>> 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?
> >>>
> >>> Thoughts?
> >>>
> >>
> >> Usage of BoostBook/DocBook isn't required by Boost. Library writers
> >> are free to use any system they want to produce HTML documentation.
> >>
> >> Maybe the question you might want to ask is ... Should QuickBook be
> >> altered to produce html directly?
> >>
> >
> > QuickBook, likewise, is not required. So the question I really want to ask
> > is what
> > people's opinion about best documentation solution in 2014. It's
> > intentionally
> > open-ended.

> I held back that comment because I avoided to sound heretic, but since you
> started the topic:
> Today, I would pick Sphinx as a documentation system. While I prefer
> Asciidoc over ReStructuredText as markup, Sphinx wins hands down because of
> I think the whole documentation of Boost should be hosted by ReadTheDocs.
> By doing so, the documentation will be built remotely as HTML, PDF and Epub
> for all releases, triggered by a push to git. It looks nice on the desktop,
> on paper, and on phones.

OK - is that an offer to show how a Boost library in Quickbook can be
re-factored in this system?

I presume we can have *Live* Code snippets, indexing, Doxygen, graphics,
equations, etc.

Do we have a body of people with experience using Sphinx? Looks fine but new to
me :-(

> Printing is not such an issue any longer.

It's still nice to be able to print a single page? (especially from ones
handheld device to a nearby cloud printer).

> My issue is that the current Boost documentation is unreadable on handheld

I dispute this - I've just tried Boost.Math both HTML and PDF on a Moto G and
while I wouldn't want to read too much, and navigation isn't wonderful, you can
get to a page and read it to check on a detail, and view the pictures. I've
also read the html and pdf version on an iPad and it is possible.

Are you considering the *size* of the documentation? All the examples I've
scanned in seem fairly small compared to many Boost
libraries. I think the issue of size is a reason for disagreements about the
best choice of documentation preparation systems. Above a few pages (when you
can scan the whole lot), finding what you want to know becomes a serious problem
- and one that we (including Google) haven't really cracked yet. So we need to
give users all the help we can with hyperlinking and indexing.


Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 (0) 1539 561830

Boost list run by bdawes at, gregod at, cpdaniel at, john at