forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: [Fwd: RefDoc - Neutral XML Document Format Input/Current State]
Date Mon, 01 Aug 2005 11:22:22 GMT
Ross Gardler wrote:
> Bertrand is mentoring a GSoC project called RefDoc over at Cocoon. I'm
> listed as a co-mentor, but my involvement is only really to help
> Bertrand pick up the slack whilst he is busy. This is Bertrands project,
> not mine. Having said that, I think this is very useful for Forrest as
> well.
> 
> The project is intended to make Cocoon applications self documenting by
> adding javadoc like comments to the relevant files.
...

This is a perfect use-case for Forrest, with the preprocessing plugin I
talked about at ApacheConEU. We'll see how he manages it and then work
from there.

You can point him to our whiteboard where there is already something to
look at... or maybe it's better to not do it as what is there sucks a
bit ;-)

> Issue #2:
> Of course simple having to index so many different metadata keys might
> be annoying and they should perhaps all be changed to one 'id' or
> 'name' field. I feel this should be done.

Same thought here... only writing real code will make us understand what
is best.

> Issue #3:
> I figured that the layout of the neutral XML would be similar to how a
> javadoc document is arranged with the name and packge followed by a
> description and then examples/methods/variables followed finally by
> details and perhaps codeblocks. This may be too similar to javadoc,
> however and I'd like input on formatting decisions.

The more similar to Javadoc, the better. It's tried and tested, people
are used to it and it can be transformed well in a helpset.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message