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