Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-09-28 10:29:40

on Wed Sep 28 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:

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

It could be automated, of course, but it would be a lossy conversion.

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

Yes, but not *arbitrary* visual markup, or at least not arbitrarily
complex visual markup.

>> Any ideas about how to address these issues?
>
> Perhaps quickbook to reStructuredText is a feasible solution.
> Then all move to writing in reStructuredText, etc.

But then there's the issue of lossiness.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com