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<>:
>> On 27/09/11 16:53, Dave Abrahams:
>>> on Tue Sep 27 2011, Mateusz Loskot<>:
>>>> 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.


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

I see your point now.

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