Re: stdcxx documentation format

[Martin Sebor <se...@roguewave.com>]

[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