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]>
> > 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,
Do we have a body of people with experience using Sphinx? Looks fine but new to
> 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 https://readthedocs.org/ 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 acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk