Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-04 21:05:54

On 03/10/11 15:04, Dave Abrahams wrote:
> 
> on Sun Oct 02 2011, Edward Diener <eldiener-AT-tropicsoft.com> wrote:
> 
>> On 10/2/2011 6:03 PM, Dave Abrahams wrote:
>>>
>>
>>> on Thu Sep 29 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>>>
>>>> On 28/09/11 17:09, John Maddock wrote:
>>>>>>> Perhaps quickbook to reStructuredText is a feasible solution.
>>>>
>>>>>>> Then all move to writing in reStructuredText, etc.
>>>>>>
>>>>>> But then there's the issue of lossiness.
>>>>>
>>>>> And lets not forget that some of us really like quickbook ;-)
>>>>
>>>> I do like quickbook too.
>>>> Although may intention was to discuss the workflow of documenting Boost,
>>>> I think I have identified what is the biggest pain to me: Doxygen
>>>> integration in BoostBook.
>>>>
>>>> Doxygen is widely used C++ code documenting tool.
>>>> Fortunately or unfortunately, it is also used by many Boost authors.
>>>>
>>>> Doxygen does not support many of the terms/concepts/elements used across
>>>> Boost libraries. It is also becasue it is almost impossible to document
>>>> them well at source code levels.
>>>> However, things like "concept and model" exist at source code level,
>>>    do not?---------------------------------^
>>
>> Doxygen generally deals with C++ constructs, and there is no C++
>> construct called "concept" or "model". 
> 
> Yes I know.  I was suggesting that Mateusz left out a couple of words
> above.  Otherwise it seems not to gibe with reality.

I hope I have clarified the gaps in my previous response.

>> If concepts had been voted into C++0x, then no doubt doxygen would
>> have considered documenting it as a C++ construct.
>>
>> Conversely there is no limit in doxygen to documenting whatever you
>> want as free-from doxygen documentation and so you could document
>> concepts' in doxygen if you wanted to do so in whatever format you
>> like. There are a number of techniques for this but probably the
>> easiest is to just add such documentation to a @file documentation,
>> and it will show up in the final output.
> 
> But what's the advantage in that over, say, just using quickbook,
> boostbook, or any of the other non-automatic tools for that part of the
> documentation?

One of important Doxygen features is it extracts and interlinks C++
names/symbols (with or without attached documentation).
BoostBook could use this interlinking capability and generate the
relations we lack currently:
- concepts
- models
- template parameters to concepts as type requirements

I think this interlinking is one of most important features that is
missing from the docs in current form.

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