Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-07 21:41:32

On 07/10/11 21:04, Dave Abrahams wrote:
> on Fri Oct 07 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:
>> The very first question that came to my mind, what is wrong with C++?
>> Why documentations in scripting world can be clean, friendly,
>> usable and pretty?
> 
> I don't think this is a C++-vs-scripting thing.  However, we generally
> have a lot more to document and hold ourselves to a much higher standard
> of rigor than most people writing in scripting languages.

Yes, the importance of rigor is...important.

>> Looking at slides 30-37, I'm wondering...why Boost documentation
>> looks and feels more like a scientific paper than a handbook.
>> The handbooks are for mortals. The scientific paper are not.
>> The Boost is developed by immortals, so let them use scientific paper.
>> The Boost is for use mostly by mortals who need handbook, but not
>> scientific paper, about Boost.
>>
>> If Boost documentation (and website) aims the slides 30-37, it will be
>> a rockstar documentation.
>>
>> Is it possible at all?
> 
> Yes, it's possible.  Are you familiar with
> https://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Objectives?
> That could be revived.  Matias Capeletto was the driving force, IIRC.

I found it long time ago, forgot and haven't come back since.

The objectives are aligned to what we've discussed so far.
The idea is feels big. I think it would improve a lot if
we could implement the unification for use and processing
of Doxygen in Boost.

BTW, DocBook seems mandatory
https://svn.boost.org/trac/boost/wiki/DocsOrganization#DocsfilesOrganization

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