cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <>
Subject Re: Documentation Format... (user reference pages scenario)
Date Thu, 21 Nov 2002 12:55:55 GMT
On Thursday 21 November 2002 12:31, Diana Shannon wrote:
> ...It also might be helpful for those who don't remember the initial
> discussion to read:...

Thanks for reminding us (myself at least ;-), it makes it much clearer what 
javadoc tags can bring to the reference docs generation process. And I was 
wrong, they are definitely *very* useful.

So how about creating our user reference pages according to the following 

1) Add at least the following javadoc tags to the java source code of 
existing components:

- @cocoon:name [1]
- @cocoon:status [1]
- All "configuration tags" from [1]
- All "setup tags" from [1]
- A "short user-level description" tag?
- A "component category" tag? (Generator, Transformer, etc.)

2) Supplement this info with an xxx-manpage.xml file (or whatever, but need a 
standard name) in xdocs format, that can contain usage examples and 
additional information, similar in concept to package.html for java packages.

This is stored in the same directory as the component and xxx is the same as 
the java class name ("FileGenerator-manpage.xml").

An empty xxx-manpage.xml causes only the content of the javadoc tags 
to be published, but the file is required to decide which components are 
included in the user reference docs. We don't want a user reference page for 
every java class in the source code tree.

3) Implement a Cocoon/Forrest pipeline to publish user reference pages from 
these tags and XML doc files. 

As I understand Bernhard has this covered, but I don't know the details. If 
we can get these javadoc tags in XML form in a pipeline, it would be easy to 
merge them with the xxx-manpage.xml file.

 - o -

I think this scenario makes the effort very granular and allows us to let the 
component developers write the technical details while others can write the 
examples and narrative. Way to go IMHO.


>From Diana's email:


View raw message