Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-09-29 12:11:35

On 28/09/11 11:29, Dave Abrahams wrote:
> on Wed Sep 28 2011, Mateusz Loskot<mateusz-AT-loskot.net>:
>> On 27/09/11 16:53, Dave Abrahams:
>>> on Tue Sep 27 2011, Mateusz Loskot<mateusz-AT-loskot.net>:
>>>> On 27/09/11 01:09, Dean Michael Berris:
>>>>> On Tue, Sep 27, 2011 at 9:46 AM, Mateusz Loskot<mateusz_at_[hidden]>:
>>>>>>
>>>>>> 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.

Indeed.

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

Understood.

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

I see your point now.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org