Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-09-27 15:53:36

on Tue Sep 27 2011, Mateusz Loskot <> wrote:

> On 27/09/11 01:09, Dean Michael Berris wrote:
>> On Tue, Sep 27, 2011 at 9:46 AM, Mateusz Loskot <mateusz_at_[hidden]>
>> wrote:
>>> Has anyone considered it?
>> I/we use it in cpp-netlib for both docs and the website.
> So, you write it in reStructuredText, right?
>>> Would it be valid to discuss Sphinx for Boost?
>> I for one would welcome discussion about it.
> The major problem I have with the current Boost documentation framework
> is too big diversity of documenting tools and workflows, lack of content
> writing uniformity, none or not ideal source-to-doc
> translation (e.g. Doxygen issues).

Exactly. And now you're proposing to increase the diversity... unless
you mean to rewrite all the existing docs.

> Remembering long way of documenting Boost.Geometry, I'm not 100% happy
> with the results. Perhaps it's only my opinion. I'm not going to
> ignite any fermentation. I'm just curious, if boostdoc/quickbook is
> really superior to, say, reStructuredText + Sphinx tandem.

The differences run deep. If it was a totally clear cut win for ReST,
I'd have pushed for its exclusive adoption years ago.

- quickbook is an extensible programming language; ReST is explicitly
  trying *not* to be programmable

- quickbook generates boostbook, which can represent rich semantic
  information. ReST can't very cleanly express arbitrary semantic or
  visual markup (bold-italic anyone?)

- quickbook is maintained by Boosters when they have the time, docbook
  is maintained externally

- quickbook takes a long time to compile, docbook is Python

- quickbook is not really used outside of Boost; docbook is used by

- there's no usable Emacs editing mode for quickbook; there is for ReST.


Any ideas about how to address these issues?

Dave Abrahams
BoostPro Computing

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC