Re: [boost] Do we need BoostBook?

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] 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 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 +44 (0) 1539 561830