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<mateusz-AT-loskot.net>  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, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org