Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-docs@xml.apache.org
Message-ID: <3DDCDAEC.2010300@apache.org>
Date: Thu, 21 Nov 2002 14:09:00 +0100
From: Nicola Ken Barozzi <nicolaken@apache.org>
Reply-To: nicolaken@apache.org
Organization: Apache Software Foundation
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.1) Gecko/20020826
MIME-Version: 1.0
To: cocoon-docs@xml.apache.org
Subject: Re: Documentation Format... (user reference pages scenario)
References: <CF37EA74-FD44-11D6-9DF3-0030653FE818@apache.org>
 <20021121125556.3C7FD23CD8@dj.codeconsult.ch>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit


Bertrand Delacretaz wrote:
> 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 
> 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.)

+0 (I'm not checking the details, +1 for the concept)

> 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.

I'd use an html page, and possibly a javadoc-compatible one.
This way we can have the page inserted also in the javadocs, and doc 
writers will find it easier to write.

As for xdoc format, Cocoon can convert the simple html to xdoc, so it 
shouldn't be a problem.

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

+1

> 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.

+1

> -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
> 


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