> 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.
>
This was something I'm not sure I had even read, so this was definately good to
see.
> So how about creating our user reference pages according to the following
> scenario?
>
> 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.)
>
agreed. What I don't see though is wher eit annotates the effect the compoent
has one sitemap
variables. I have seen more than one case on the list where a very useful but
undocumented bit of
data was avaaible as a sitemap variable after a component. After looking that
the proposed javadoc
extensions, I would say this would most consistently be done as additional
Cocoon javaddoc tags.
> 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.
>
definately. But the name should probalby be more like "xxx-userref.xml" instad
of "xxx-manpage.xml"
> This is stored in the same directory as the component and xxx is the same as
> the java class
> name ("FileGenerator-manpage.xml").
>
agreed.
> 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.
>
again, agreed. A good trigger.
> 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.
>
so far so good...
> - 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.
DEFINATELY!
>
> -Bertrand
>
>
>
>>>From Diana's email:
> [1]
>> http://members.a1.net/berni_huber/solutions/cocoon-javadoc-tags.html
>>
>
> [2]
>> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101934150206759&w=2
--
"The heights of genius are only measurable by the depths of stupidity."
