incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Betz <mb...@roguewave.com>
Subject RE: stdcxx documentation format
Date Tue, 06 Sep 2005 15:38:39 GMT
Martin,

Doxygen does all the same kind of linking we do in our reference guides, and
then some. The output, too, is very configurable, with the exception on the
look and feel, which was a problem for us in terms of fitting in with our
other product documentation, but would not matter to the open source
community. I think putting the documentation in source code comments is a
lovely idea, but I am pretty sure Alessio does not have a good understanding
of how big a task he is proposing.

Marc

-----Original Message-----
From: Martin Sebor [mailto:sebor@roguewave.com] 
Sent: Tuesday, September 06, 2005 8:23 AM
To: stdcxx-dev@incubator.apache.org
Cc: Marc Betz
Subject: Re: stdcxx documentation format


[responding to stdcxx-dev@incubator.apache.org]

Alessio Marchetti wrote:
> Martin Sebor wrote:
> 
>>
>>> As far as the presentation I will easily be able to use a pretty
>>> standard stylesheet at first, then I could customize it to match the 
>>> Apache look&feel.
>>
>>
>>
>> Excellent!
>>
>> Martin
>>
>>
> 
> Now I'm thinking about the process that the documentation creation
> should follow.
> 
> I have in mind two different processes for the reference guide and for
> the other docs (User Guide, FAQ, Technical notes, Help for people 
> wanting to contribute to the project, etc.).

There are a couple of projects in use at Apache: Forrest and Maven. I
haven't used either but I believe a lot of the Web pages around here are
generated by Forrest.

> 
> While the other docs are best single-sourced from XML content 
> (DocBook,
> as most open -- and closed --- source projects are converting to it 
> right now), the reference guide (until the days of literate programming 
> will come...) is better implemented with a Doxygen-like process, that 
> is: put the documentation in the source code.
> 
> I'm sure this is the best way to proceed, because it will 
> substantially
> increase the probability to have updated documentation.
> 
> In this scenario, the existing UG will be migrated to DocBook (with
> Marc's scripts or with new ones), while the existing RG will be 
> copy&paste'd (I suppose I will volounteer to do it...) into the sources.
> 
> What do you think?

Going the Doxygen route is definitely very appealing for new code, but
converting the existing sources would be a huge amount of work.

The Class Reference is in a pretty good shape with tables, cross references,
etc. How easily could we preserve all that? How hard to read and maintain
would it make the sources?

I guess I need to look at some existing projects that use Doxygen
extensively to get a better feel for what it can do (my experience with
Doxygen is limited to that of a user of the final product). Do you have any
pointers? If you'd like to put together a prototype of a few non-trivial
pages that would be even better.

FWIW, I've started using simple Doxygen-style documentation in the new test
suite driver. The idea is to start with it as the guinea pig before making a
decision on the library. Any help here is also welcome :)

Martin

Mime
View raw message