Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-09-28 09:24:20

On 27/09/11 16:53, Dave Abrahams wrote:
> 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:
>>>> 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.

This is the the real issue here, indeed. I had a wild idea of rewriting,
but I've realised it is not really possible due to manpower constraints.

>> 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.

I see.

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

It can express visual markup, unless I don't understand it.

> Any ideas about how to address these issues?

Perhaps quickbook to reStructuredText is a feasible solution.
Then all move to writing in reStructuredText, etc.

Best regards,

Mateusz Loskot,
Charter Member of OSGeo,
Member of ACCU,

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