Re: [boost] Do we need BoostBook?

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
> https://readthedocs.org/.
> 
> 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
devices!

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

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]