Re: Sphinx integration
Dave Abrahams <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <[email protected]> |
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<[email protected]> 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