You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Andy Lewis <aj...@ascii27.net> on 2002/11/14 17:23:45 UTC
Documentation Format...
I've just recently joined the documentation list, and wanted to through out a couple of ideas.
First off, I have been using Cocoon since 1.3, and am currently developing a portal solution for
NASA using 2.1-dev. Part of that effort includes bringing other people her eup to speed on the
technology. I have to say that ,while the Cocoon documentation has ben improving steadily, it is
still a huge struggle to even point someone to the correct place.
I am not making these comments without suggesstions however, as my intent is to be constructive
here so please pardon any presumptiousness on my part. Cocoon is, as we know, extremely modular,
and becoming increasingly so. But documentation seems to be ither sparse, or scattered. I recall
the threads about how to organize it, and have seen some efforts down that path. But the first
thing that comes to mind is that if I want to know the details ofa particular input module or
transformer, I can't find it in a a single place. There is some reference material, and some
concept material, and some tutorial material, each introducing new technical information. Also I
have seen that, as the code evolves, docs get left behind. I would gues that part of this is
because there are multiple places to update. This brings me (at long last) to my suggestion. What
about a UNIX man page approach to technical docs? For each transformer, gerneator, inputmodule,
etc, have a sinlge man page type document with the technical details, samples if any, formats,
etc. This would help developers and users both have a single stop for such info. Of course this is
only one aspect of documentation. The project still needs concept documents, JavaDocs, tutorials,
etc. But as a basic level for technical information users need, I think it would make a
substantial difference.
Comments?
Thanks!
Andy Lewis
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
<snip/>
>
> +1. The code is organized logically into packages, why shouldn't the docs? :)
>
good point...mirroring the package structure would simply finding things....
>
> The current docs are "organized", in a sense, in that stuff that goes together is sort of
> globbed together, but I think the project would benefit from something more logically
> organized.
agreed...
>
> If I go to x.a.o/cocoon looking for help in getting Cocoon speaking to a database, do I look
> in How-To's, Tutorials, or FAQs? Or in the
> user-guide?
>
exactly the problem I've been running into...
>
> I've been of the opinion that PHP has the best documentation around, and that we should use
> them as a model for how to do things. Looking at the PHP documentation, you'll see that
> there's more to "documentation" than just "how to do things". There's a quick reference page,
> as well as a "manual". If PHP came in a box, that's what would be printed and included with
> it. I hate to say it, but if the current Cocoon
> documentation was converted to print and then thown in the box, the first thing I'd do would
> be throw it out :) All kidding aside, I think we should try to make our docs as
> professional as possible. Good docs make or break a project.
>
Exactly! PHP has done an excellent job here. You would think with all this XML stuff around we
could match it at least ;)
>
> Tony
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Tuesday 19 November 2002 18:12, Andy Lewis wrote:
>. . .
> I agree that DEVELOPER documentation should be in the source files. But not
> user documentation....
same here. The killer argument is that you don't want non-programmers to make
changes to java source files because they're changing the *user
documentation* of the component.
Also, a component might (often should ;-) be written in multiple java source
files, in which case having a separate XML doc file for the component as a
whole makes it clear where the documentation is.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> Bertrand Delacretaz wrote:
>> David Crossley wrote:
>> >. . .
>> > I wonder if we can extract some minimal information from
>> > javadoc tags and supplement that with an xml fragment in
>> > an accompanying file, to build a -manpage.xml
>> >. . .
>>
>> Good idea, I think relying solely on javadoc tags for reference docs would require including
>> too much docs in the code.
>
> We could use the "package.html", which sits beside each
> component, to add this supplemental description. In that way,
> the info gets automatically included into Javadocs as well.
> Some components are already doing this. So a side-benefit is
> that Javadocs are more useful too. See
> http://xml.apache.org/cocoon/apidocs/
> and choose a component that has something in the right-hand
> column. Note that these include the "Description" at the
> bottom of their page.
>
> --David
I think that would dilute both documentaiton conepts actually. That is great and useful for the
javadocs - but that is for developer docs, not user docs. And users shouldn't need to delve into
the javadocs...
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Bertrand Delacretaz wrote:
> David Crossley wrote:
> >. . .
> > I wonder if we can extract some minimal information from
> > javadoc tags and supplement that with an xml fragment in
> > an accompanying file, to build a -manpage.xml
> >. . .
>
> Good idea, I think relying solely on javadoc tags for reference docs would
> require including too much docs in the code.
We could use the "package.html", which sits beside each
component, to add this supplemental description. In that way,
the info gets automatically included into Javadocs as well.
Some components are already doing this. So a side-benefit is
that Javadocs are more useful too. See
http://xml.apache.org/cocoon/apidocs/
and choose a component that has something in the right-hand
column. Note that these include the "Description" at the
bottom of their page.
--David
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Bertrand Delacretaz wrote:
> On Monday 18 November 2002 10:41, David Crossley wrote:
>
>>. . .
>>I wonder if we can extract some minimal information from
>>javadoc tags and supplement that with an xml fragment in
>>an accompanying file, to build a -manpage.xml
>>. . .
>
>
> Good idea, I think relying solely on javadoc tags for reference docs would
> require including too much docs in the code.
+1 for the idea.
Javadocs = reference and contract
embedded man docs = description and usage
:-)
I'd probably think of putting the man stuff in the class header, so that
it shows in the Javadocs too.
A hack could be to include <div> tags in the html and use them as
semantical info to generate Forrest man pages from it (2c)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Monday 18 November 2002 10:41, David Crossley wrote:
>. . .
> I wonder if we can extract some minimal information from
> javadoc tags and supplement that with an xml fragment in
> an accompanying file, to build a -manpage.xml
>. . .
Good idea, I think relying solely on javadoc tags for reference docs would
require including too much docs in the code.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> On Monday 18 November 2002 12:42, Diana Shannon wrote:
>>. . .
>> However, remember SoC. Do we really want people (potential doc
>> contributors) without a lot of Java experience tweaking source files to add this reference
>> info?
>
> Good point - I agree 100%, but OTOH I think it makes sense to keep the components docs in the
> same directories as the component code, to emphasize their strong ties and make it clear to
> developers that they have to write/draft the reference docs.
>
definately agree.
> See David's proposal on this below, I think a combination of javadoc tags + standalone XML
> files will bring the most benefits at the least cost for these reference docs.
>
can't picture where tohe cross ties are...but but I'm fine with it...
> On Monday 18 November 2002 10:41, David Crossley wrote:
>> I wonder if we can extract some minimal information from
>> javadoc tags and supplement that with an xml fragment in
>> an accompanying file, to build a -manpage.xml
>
> maybe automatically including the (filtered) javadocs info from the source files into the
> -manpage.xml files is the way to go for reference docs.
I guess I'm not sure what info would be best ot put into the javadoc info versus the XML....
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Monday 18 November 2002 12:42, Diana Shannon wrote:
>. . .
> However, remember SoC. Do we really want people (potential doc
> contributors) without a lot of Java experience tweaking source files to
> add this reference info?
Good point - I agree 100%, but OTOH I think it makes sense to keep the
components docs in the same directories as the component code, to emphasize
their strong ties and make it clear to developers that they have to
write/draft the reference docs.
See David's proposal on this below, I think a combination of javadoc tags +
standalone XML files will bring the most benefits at the least cost for these
reference docs.
On Monday 18 November 2002 10:41, David Crossley wrote:
> I wonder if we can extract some minimal information from
> javadoc tags and supplement that with an xml fragment in
> an accompanying file, to build a -manpage.xml
maybe automatically including the (filtered) javadocs info from the source
files into the -manpage.xml files is the way to go for reference docs.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> Diana Shannon wrote:
<snip/>
>> In addition to generating a great set of reference docs, I assume we can pull snippets from it
>> for use in many other docs, correct?
>
> Yes, great idea.
I hope so...
>
>> However, remember SoC. Do we really want people (potential doc
>> contributors) without a lot of Java experience tweaking source files to add this reference
>> info?
>
> If they make an attempt to rectify some lack, and get it wrong,
> then the developers that are responsible for that particular code
> might leap into action.
yeah...but still...developer docs in the code, user docs outside the code.
>
> The tool that creates the reference documentation could generate
> a summary of all javadoc attributes that we could then run by
> the cocoon-dev list for quality control.
>
Again, what infor are we looking ot put into the javadocs? Shouldn't we try to figure out what the
man pages should contain first, then figure out the best way to track and maintain each piece? We
should be working backwards here from the end goal, not forwards from the tools we have.
> It will be committers who will apply the patches that are
> contributed, so at least one other person gets to review
> the work.
Which seems to create a documentation bottleneck actually. Do we really want to create a situation
where a developer needs to review technical documentaiton to make sure it does affect the code?
>
> These changes and capability will be going into the head
> of CVS first, so i do not see any problem.
>
> --David
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Diana Shannon wrote:
> David Crossley wrote:
>
> > It would be ideal to generate reference documentation
> > direct from Java source. As Berni says in these threads.
> > the big job is going through all the java source to
> > add the necessary javadoc tags and comments.
> >
> > This could always start small and gradually expand. We
> > seem to have more people interested in documentation
> > now and the cocoon-docs list, so i would like to see
> > Berni's work resurrected.
>
> I'm 100% in favor of using Berni's work.
>
> In addition to generating a great set of reference docs, I assume
> we can pull snippets from it for use in many other docs, correct?
Yes, great idea.
> However, remember SoC. Do we really want people (potential doc
> contributors) without a lot of Java experience tweaking source files
> to add this reference info?
If they make an attempt to rectify some lack, and get it wrong,
then the developers that are responsible for that particular code
might leap into action.
The tool that creates the reference documentation could generate
a summary of all javadoc attributes that we could then run by
the cocoon-dev list for quality control.
It will be committers who will apply the patches that are
contributed, so at least one other person gets to review
the work.
These changes and capability will be going into the head
of CVS first, so i do not see any problem.
--David
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Monday, November 18, 2002, at 04:41 AM, David Crossley wrote:
> It would be ideal to generate reference documentation
> direct from Java source. As Berni says in these threads.
> the big job is going through all the java source to
> add the necessary javadoc tags and comments.
>
> This could always start small and gradually expand. We
> seem to have more people interested in documentation
> now and the cocoon-docs list, so i would like to see
> Berni's work resurrected.
I'm 100% in favor of using Berni's work.
In addition to generating a great set of reference docs, I assume we can
pull snippets from it for use in many other docs, correct?
However, remember SoC. Do we really want people (potential doc
contributors) without a lot of Java experience tweaking source files to
add this reference info?
Diana
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Nicola Ken Barozzi wrote:
>
>
> Jeff Turner wrote:
> > Tony Collen wrote:
> >
> >>Bertrand Delacretaz wrote:
> >
> > ...
> >
> >>>This might mean restructuring much of the docs, trying to get obvious URLs
> >>>like
> >>>
> >>>docs/components/generators/FileGenerator.html
> >>>docs/components/serializers/PDFSerializer.html
> >>>
> >>>(and later)
> >>>docs/blocks/pdf/fop/FopPdfBlock.html
> >>>
> >>>
> >>
> >>+1. The code is organized logically into packages, why shouldn't the
> >>docs? :)
> >
> > ...
> >
> > How about using a tool like xdoclet or qdox to generate XML from @tags in
> > the Cocoon source?
> >
> > Lots of work.. Ant has got something like this prototyped in
> > proposal/xdocs.
>
> It has already be done by someone (sorry! don't remember who) some time
> ago. We have also had a discussion on it, but somehow the thing didn't
> finalize.
>
> If you have time, look in the cocoon-dev archives or in cocoon-related
> sites, you should find references there.
>
> IMHO technical documentation should definately be in the source files.
I remembered Bernhard Huber's excellent work on this, so
i went digging through MARC to find the old discussions.
There were various threads, here are some:
Reference Doc From Java Sources [Was Check Source]
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101226838012373
Re: Check Source
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101207176630450
It would be ideal to generate reference documentation
direct from Java source. As Berni says in these threads.
the big job is going through all the java source to
add the necessary javadoc tags and comments.
This could always start small and gradually expand. We
seem to have more people interested in documentation
now and the cocoon-docs list, so i would like to see
Berni's work resurrected.
I wonder if we can extract some minimal information from
javadoc tags and supplement that with an xml fragment in
an accompanying file, to build a -manpage.xml
--David
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andy Lewis wrote:
>>
>>Jeff Turner wrote:
>>
>>>On Fri, Nov 15, 2002 at 12:48:40PM -0600, Tony Collen wrote:
>>>
>>>
>>>>Bertrand Delacretaz wrote:
>>>
>>>...
>>>
>>>
>>>>>This might mean restructuring much of the docs, trying to get obvious URLs like
>>>>>
>>>>>docs/components/generators/FileGenerator.html
>>>>>docs/components/serializers/PDFSerializer.html
>>>>>
>>>>>(and later)
>>>>>docs/blocks/pdf/fop/FopPdfBlock.html
>>>>>
>>>>>
>>>>
>>>>+1. The code is organized logically into packages, why shouldn't the docs? :)
>>>
>>>...
>>>
>>>How about using a tool like xdoclet or qdox to generate XML from @tags in the Cocoon source?
>>>
>>>Lots of work.. Ant has got something like this prototyped in
>>>proposal/xdocs.
>>
>>It has already be done by someone (sorry! don't remember who) some time ago. We have also had
>>a discussion on it, but somehow the thing didn't finalize.
>>
>>If you have time, look in the cocoom-dev archives or in cocoon-related sites, you should find
>>references there.
>>
>>IMHO technical documentation should definately be in the source files.
>>
>
> I agree that DEVELOPER documentation should be in the source files. But not user documentation.
> What I suggested was for users. Javadocs for developers, with every bit of useful extension and
> enhancement that can be viably added, but having user docs in the code I disagree with.
Why?
When a developer writes a class, he has to be fully aware of how it will
be used, and what the contract is. In usual Java classes it's quite
easy, since the user of a class is a developer. In our case, the user
can also not be a Java developer, but a webapp assembler.
But who decides the parameters of the Component? Who gives it the
functionality? It's the person that makes the Java code, no?
So IMHO it's not about user VS developer, but technical VS more descriptive.
Do this then: take a Cocoon Component, and write the documentation in
the file and out of the file, as you think is best, and post it here.
So we can discuss on a real example, make changes to it, and get a
better picture. :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
>
>
> Jeff Turner wrote:
>> On Fri, Nov 15, 2002 at 12:48:40PM -0600, Tony Collen wrote:
>>
>>>Bertrand Delacretaz wrote:
>>
>> ...
>>
>>>>This might mean restructuring much of the docs, trying to get obvious URLs like
>>>>
>>>>docs/components/generators/FileGenerator.html
>>>>docs/components/serializers/PDFSerializer.html
>>>>
>>>>(and later)
>>>>docs/blocks/pdf/fop/FopPdfBlock.html
>>>>
>>>>
>>>
>>>+1. The code is organized logically into packages, why shouldn't the docs? :)
>>
>> ...
>>
>> How about using a tool like xdoclet or qdox to generate XML from @tags in the Cocoon source?
>>
>> Lots of work.. Ant has got something like this prototyped in
>> proposal/xdocs.
>
> It has already be done by someone (sorry! don't remember who) some time ago. We have also had
> a discussion on it, but somehow the thing didn't finalize.
>
> If you have time, look in the cocoom-dev archives or in cocoon-related sites, you should find
> references there.
>
> IMHO technical documentation should definately be in the source files.
>
I agree that DEVELOPER documentation should be in the source files. But not user documentation.
What I suggested was for users. Javadocs for developers, with every bit of useful extension and
enhancement that can be viably added, but having user docs in the code I disagree with.
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Sunday 17 November 2002 16:11, Bernhard Huber wrote:
>. . .
> see the suggetion of cocoon javadoc tags at the end
>. . .
+1 on using this to generate *reference* documentation for Cocoon components
(as opposed to tutorials and concept docs).
In
http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103729103630943&w=2
Andy Lewis suggest generating reference docs in unix man page format, I think
generating these manpage-like docs from javadoc tags makes sense.
-Bertrand
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Bernhard Huber wrote:
>
>>
>> I am *strongly* in favor of using special javadoc tags for the Cocoon
>> Components, and I want to make this a standard part in the new
>> Alexandria code documentation process.
>
> me, too
>
>>
>> Instead of xdoclet it can be very fast to use qdox:
>> http://qdox.sourceforge.net/
>>
>> The relevant Ant classes:
>> http://qdox.sourceforge.net/xref/com/thoughtworks/qdox/ant/index.html
>>
> okay, why do you favour qdox over xdoclet?
IIUC it's faster and easier to use.
And XDcolet has been a PITA in the last months to many projects that
have used it because of the changes it has gone through and problems in
its Gump runs IIRC, and some Avalon subprojects switched to qdox for
this reason.
Feel free to use anything you prefer though :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Bernhard Huber wrote:
> Nicola Ken Barrozzi wrote:
> > Bernhard Huber wrote:
> > <snip/>
> >
> > > Probably it's a lot of work change all sitemap component sources,
> > > and describe a coding standard for submitting only
> > > components sticking to the cocoon java doc tags.
> >
> > I am *strongly* in favor of using special javadoc tags for the Cocoon
> > Components, and I want to make this a standard part in the new
> > Alexandria code documentation process.
>
> me, too
>
> > Instead of xdoclet it can be very fast to use qdox:
> > http://qdox.sourceforge.net/
> >
> > The relevant Ant classes:
> > http://qdox.sourceforge.net/xref/com/thoughtworks/qdox/ant/index.html
>
>
> okay, why do you favour qdox over xdoclet?
>
> > This won't happen overnight, but if the system is in place I'm quite
> > sure that people will start moving the documentation in the sources.
> see the suggetion of cocoon javadoc tags at the end
>
> > Do you have time to give qdox a try for Cocoon?
>
> just at the weekend, but first finalize the javadoc tags
I think that this is the place where we got stuck the last
time this was proposed ... defining the set of javadoc attributes
to use. Berni did propose something, but the discussion did not
go far.
This time will be different. Berni has them defined down below.
Would it be possible to just get started using that set, limit
our work to just a couple of components, describe those well,
generate their reference documentation only, get the
infrastructure in place, review those docs and finalise the
set of javadoc tags. Then start to gradually add content to
the other components.
This was an idea in another cocoon-dev thread where we are
developing the RELAX NG grammar for the sitemap. I suggested
that we discuss each component in turn on the list to finalise
its parameters and usage. This way we all learn about the guts
of Cocoon, the whole thing gets polished, and we get good
reference docs at the end.
> > When we have it working, I'll make it part of the Alexandria stuff, so
> > that the documentation will be done by running Alexandria to generate
> > all code docs (xml javadocs, qdox docs, javasrc, xsldoc, etc), and then
> > Forrest for the final rendering and the site.
> okay
>
> regards bernhard
>
> *** Motivation
> Keeping java code, and documentation about java code together to deliver
> up-to date reference documentation. Using java doc tags will help
> generating reference documentation of Cocoon sitemap components.
>
> This document describes using well known javadoc tags for reference
> documentation. A bunch of new javadoc tags describes Cocoon specific
> reference documentation requirements.
>
> The processing modell described here uses javadoc tags at class-level,
> and method-level.
>
> Cocoon specific javadoc tags introduced are always prefixed by cocoon:.
> For example the cocoon javadoc tag describing the cocoon name of the
> FileGenerator defines its name as @cocoon:name file.
>
> *** Class Javadoc Tags
> The following javadoc tags used at class level.
>
> *** Supported Class Javadoc Tags
> Following well known javadoc tags are supported
>
> @version {version-info} -
> VersionControl information pasted to the generated document.
> @deprecated {deprecated-info} -
> Information why this Cocoon sitemap object is deprecated, additionally
> what kind of object to use.
> @since {Cocoon-Release-Version} -
> Information since which Cocoon version this Cocoon sitemap object is
> available.
> Cocoon Class Javadoc Tags
> Cocoon class level javadoc tags describes the Cocoon sitemap component
> attributes.
>
> @cocoon:name {name} -
> The default sitemap name of this Cocoon Sitemap component, eg
> @cocoon:name i18n, @cocoon:name xslt
> @cocoon:status [default|core|optional|scratchpad] -
> The status of the sitemap component for TraxTransformer @cocoon:status
> default, for I18N Transformer @cocoon:status core. This information
> should help sitemap designer to understand if it is "safe" to use this
> Cocoon sitemap component.
> Method Javadoc Tags
> The javadoc tags described now are applied on method level, overriding
> class level javadoc tags. . The naming of the tags are derived from the
> component interfaces which may, or must be implemented by a Cocoon
> sitemap component.
>
> *** Configurational Tags
> The following tags should be used for Cocoon sitemap components
> implementing Configurable, Parameterizable, or Contextualizable.
>
> @cocoon:config element="{name}" [parent="{name}"]
> type="{type-descriptor}" description="{text}" required="yes|no"
> [default="{default-value}], @cocoon:config attribute="{name}"
> element="{name}" type="{type-descriptor}" description="{text}"
> required="yes|no" [default="{default-value}] -
> Each @cocoon:config tag describes a single configuration element. e.g.:
> For I18N Transformer @cocoon:config element="catalogue-name"
> parent="none" type="string" description="basename of the message
> catalog" required="yes"
> @cocoon:parameter name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}] -
> Each @cocoon:parameter describes a single parameter entry of a parameter
> element
> @cocoon:context name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}] -
> Eache @cocoon:context describes a context entry of which the Cocoon
> sitemap components depends on.
> Setup Tags
> The following tags should be used for Cocoon sitemap components at the
> setup method.
>
> @cocoon:setup-src description="{text}" required="yes|no"
> [default="{default-value}"] -
> The javadoc tag @cocoon:setup-src describes the setup parameter src.
> @cocoon:setup-parameter name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}"] -
> The javadoc tag @cocoon:setup-parameter describes the setup parameter
> Parameters.
> @cocoon:request-parameter name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}"] -
> The javadoc tag @cocoon:request-parameter describes the request
> parameters of the setup parameter objectModel, retrieved via
> ObjectModelHelper.getRequest(objectModel).getParameter(name).
> @cocoon:request-attribute name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}"] -
> The javadoc tag @cocoon:request-attribute describes the request
> attributes of the setup parameter objectModel, retrieved via
> ObjectModelHelper.getRequest(objectModel).getAttribute(name).
> @cocoon:session-attribute name="{name}" type="{type-descriptor}"
> description="{text}" required="yes|no" [default="{default-value}"] -
> The javadoc tag @cocoon:session-attribute describes the session
> attributes of the setup parameter objectModel, retrieved via
> ObjectModelHelper.getRequest(objectModel).getSession(false).
>
> *** Samples
> The following section gives you some usage scenarios of the javadoc tags
> described above. It should help you to use the javadoc tags in the java
> sources, and should verify the useability, and completness of the
> javadoc tags.
>
> FileGenerator
> The FileGenerator shall define following javadoc tags
>
>
> /**
> * ....
> * @since Cocoon2.0
> * @cocoon:name file
> * @cocoon:status default
> */
> public class FileGenerator ...
> ...
> /**
> * Setup the file generator.
> *
> * @cocoon:setup-src
> * description="Specify the URI filename"
> * required="yes"
> * default-value="none"
> *
> */
> public void setup(SourceResolver resolver, Map objectModel, String
> src, Parameters par)
> throws ProcessingException, SAXException, IOException {
> ....
> }
> ...
>
>
>
>
> SessionAttributeGenerator
> The SessionAttributeGenerator shall define javadoc tags
>
>
> /**
> * ...
> * @since Cocoon2.0
> * @cocoon:name session-attr
> * @cocoon:status core
> */
> public class SessionAttributeGenerator ...
> /**
> * Setup the session-attr generator
> *
> * @cocoon:setup-src
> * description="May specify the session attribute name"
> * required="no"
> * default-value="none"
> * @cocoon:setup-parameter name="attr-name" type="String"
> * description="the session attribute name"
> * required="no"
> * default-value="generator src attribute value"
> * @cocoon:setup-parameter name="root-element" type="String"
> * description="The root element name of the generated XML"
> * required="no"
> * default-value="Root element name of session attribute value,
> if it
> * is a DOM object, or XMLizable.
> */
> public void setup(SourceResolver resolver, Map objectModel, String
> src, Parameters par)
> throws ProcessingException, SAXException, IOException {
> ....
> }
> ...
> }
>
>
>
>
> WildcardURIMatcher
> The WildcardURIMatcher shall define following javadoc tags
>
>
> /**
> * ...
> * @since Cocoon2.0
> * @cocoon:name wildcard
> * @cocoon:status default
> *
> * @cocoon:match-pattern type="Wildcard"
> * required="yes"
> * description="A wildcard pattern supporting '*' matching any
> character exception '/',
> * and '**' matching any character including '/'"
> * default-value="none"
> *
> * @cocoon:match-string type="String"
> * required="no"
> * description="The sitemap URI of the current request"
> * default-value="sitemap URI"
> */
> public class WildcardURIMatcher ...
> ...
> }
>
>
>
>
> DateSelector
> The DateSelector shall define following javadoc tags
>
>
> /**
> * ...
> * @since Cocoon2.1
> * @cocoon:name date
> * @cocoon:status scratchpad
> */
> public class DateSelector ...
> ...
> /**
> * Configure the DateSelector
> *
> * @cocoon:config element="before"
> * type="empty"
> * parent="map:selector"
> * description="Specifies a before selector"
> * required="no"
> * default="none"
> * @cocoon:config attribute="name"
> * type="String"
> * element="before"
> * description="A symbolic name of this selector"
> * @cocoon:config attribute="date"
> * type="String"
> * element="before"
> * description="A date value which should be matched by the
> dateformat attribute value"
> * required="yes"
> * default="none"
> * @cocoon:config attribute="dateformat"
> * type="Datepattern String"
> * element="before"
> * description="A datepattern matching date attribtue value"
> * required="no"
> * default="HH:mm:ss"
> * ...
> */
> public void configure(Configuration config) throws
> ConfigurationException {
> ...
> }
>
>
>
Re: Documentation Format...
Posted by Bernhard Huber <be...@a1.net>.
>
> I am *strongly* in favor of using special javadoc tags for the Cocoon
> Components, and I want to make this a standard part in the new
> Alexandria code documentation process.
me, too
>
> Instead of xdoclet it can be very fast to use qdox:
> http://qdox.sourceforge.net/
>
> The relevant Ant classes:
> http://qdox.sourceforge.net/xref/com/thoughtworks/qdox/ant/index.html
>
okay, why do you favour qdox over xdoclet?
> This won't happen overnight, but if the system is in place I'm quite
> sure that people will start moving the documentation in the sources.
see the suggetion of cocoon javadoc tags at the end
>
> Do you have time to give qdox a try for Cocoon?
just at the weekend, but first finalize the javadoc tags
>
> When we have it working, I'll make it part of the Alexandria stuff, so
> that the documentation will be done by running Alexandria to generate
> all code docs (xml javadocs, qdox docs, javasrc, xsldoc, etc), and then
> Forrest for the final rendering and the site.
okay
regards bernhard
*** Motivation
Keeping java code, and documentation about java code together to deliver
up-to date reference documentation. Using java doc tags will help
generating reference documentation of Cocoon sitemap components.
This document describes using well known javadoc tags for reference
documentation. A bunch of new javadoc tags describes Cocoon specific
reference documentation requirements.
The processing modell described here uses javadoc tags at class-level,
and method-level.
Cocoon specific javadoc tags introduced are always prefixed by cocoon:.
For example the cocoon javadoc tag describing the cocoon name of the
FileGenerator defines its name as @cocoon:name file.
*** Class Javadoc Tags
The following javadoc tags used at class level.
*** Supported Class Javadoc Tags
Following well known javadoc tags are supported
@version {version-info} -
VersionControl information pasted to the generated document.
@deprecated {deprecated-info} -
Information why this Cocoon sitemap object is deprecated, additionally
what kind of object to use.
@since {Cocoon-Release-Version} -
Information since which Cocoon version this Cocoon sitemap object is
available.
Cocoon Class Javadoc Tags
Cocoon class level javadoc tags describes the Cocoon sitemap component
attributes.
@cocoon:name {name} -
The default sitemap name of this Cocoon Sitemap component, eg
@cocoon:name i18n, @cocoon:name xslt
@cocoon:status [default|core|optional|scratchpad] -
The status of the sitemap component for TraxTransformer @cocoon:status
default, for I18N Transformer @cocoon:status core. This information
should help sitemap designer to understand if it is "safe" to use this
Cocoon sitemap component.
Method Javadoc Tags
The javadoc tags described now are applied on method level, overriding
class level javadoc tags. . The naming of the tags are derived from the
component interfaces which may, or must be implemented by a Cocoon
sitemap component.
*** Configurational Tags
The following tags should be used for Cocoon sitemap components
implementing Configurable, Parameterizable, or Contextualizable.
@cocoon:config element="{name}" [parent="{name}"]
type="{type-descriptor}" description="{text}" required="yes|no"
[default="{default-value}], @cocoon:config attribute="{name}"
element="{name}" type="{type-descriptor}" description="{text}"
required="yes|no" [default="{default-value}] -
Each @cocoon:config tag describes a single configuration element. e.g.:
For I18N Transformer @cocoon:config element="catalogue-name"
parent="none" type="string" description="basename of the message
catalog" required="yes"
@cocoon:parameter name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}] -
Each @cocoon:parameter describes a single parameter entry of a parameter
element
@cocoon:context name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}] -
Eache @cocoon:context describes a context entry of which the Cocoon
sitemap components depends on.
Setup Tags
The following tags should be used for Cocoon sitemap components at the
setup method.
@cocoon:setup-src description="{text}" required="yes|no"
[default="{default-value}"] -
The javadoc tag @cocoon:setup-src describes the setup parameter src.
@cocoon:setup-parameter name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:setup-parameter describes the setup parameter
Parameters.
@cocoon:request-parameter name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:request-parameter describes the request
parameters of the setup parameter objectModel, retrieved via
ObjectModelHelper.getRequest(objectModel).getParameter(name).
@cocoon:request-attribute name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:request-attribute describes the request
attributes of the setup parameter objectModel, retrieved via
ObjectModelHelper.getRequest(objectModel).getAttribute(name).
@cocoon:session-attribute name="{name}" type="{type-descriptor}"
description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:session-attribute describes the session
attributes of the setup parameter objectModel, retrieved via
ObjectModelHelper.getRequest(objectModel).getSession(false).
*** Samples
The following section gives you some usage scenarios of the javadoc tags
described above. It should help you to use the javadoc tags in the java
sources, and should verify the useability, and completness of the
javadoc tags.
FileGenerator
The FileGenerator shall define following javadoc tags
/**
* ....
* @since Cocoon2.0
* @cocoon:name file
* @cocoon:status default
*/
public class FileGenerator ...
...
/**
* Setup the file generator.
*
* @cocoon:setup-src
* description="Specify the URI filename"
* required="yes"
* default-value="none"
*
*/
public void setup(SourceResolver resolver, Map objectModel, String
src, Parameters par)
throws ProcessingException, SAXException, IOException {
....
}
...
SessionAttributeGenerator
The SessionAttributeGenerator shall define javadoc tags
/**
* ...
* @since Cocoon2.0
* @cocoon:name session-attr
* @cocoon:status core
*/
public class SessionAttributeGenerator ...
/**
* Setup the session-attr generator
*
* @cocoon:setup-src
* description="May specify the session attribute name"
* required="no"
* default-value="none"
* @cocoon:setup-parameter name="attr-name" type="String"
* description="the session attribute name"
* required="no"
* default-value="generator src attribute value"
* @cocoon:setup-parameter name="root-element" type="String"
* description="The root element name of the generated XML"
* required="no"
* default-value="Root element name of session attribute value,
if it
* is a DOM object, or XMLizable.
*/
public void setup(SourceResolver resolver, Map objectModel, String
src, Parameters par)
throws ProcessingException, SAXException, IOException {
....
}
...
}
WildcardURIMatcher
The WildcardURIMatcher shall define following javadoc tags
/**
* ...
* @since Cocoon2.0
* @cocoon:name wildcard
* @cocoon:status default
*
* @cocoon:match-pattern type="Wildcard"
* required="yes"
* description="A wildcard pattern supporting '*' matching any
character exception '/',
* and '**' matching any character including '/'"
* default-value="none"
*
* @cocoon:match-string type="String"
* required="no"
* description="The sitemap URI of the current request"
* default-value="sitemap URI"
*/
public class WildcardURIMatcher ...
...
}
DateSelector
The DateSelector shall define following javadoc tags
/**
* ...
* @since Cocoon2.1
* @cocoon:name date
* @cocoon:status scratchpad
*/
public class DateSelector ...
...
/**
* Configure the DateSelector
*
* @cocoon:config element="before"
* type="empty"
* parent="map:selector"
* description="Specifies a before selector"
* required="no"
* default="none"
* @cocoon:config attribute="name"
* type="String"
* element="before"
* description="A symbolic name of this selector"
* @cocoon:config attribute="date"
* type="String"
* element="before"
* description="A date value which should be matched by the
dateformat attribute value"
* required="yes"
* default="none"
* @cocoon:config attribute="dateformat"
* type="Datepattern String"
* element="before"
* description="A datepattern matching date attribtue value"
* required="no"
* default="HH:mm:ss"
* ...
*/
public void configure(Configuration config) throws
ConfigurationException {
...
}
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Bernhard Huber wrote:
> hi,
> i started the discussion, but never implemented it using xdoclet,
> you may find some useful description in
> http://members.a1.net/berni_huber/solutions/cocoon-javadoc-tags.html
Yeah :-)
> Probably it's a lot of work change all sitemap component sources,
> and describe a coding standard for submitting only
> components sticking to the cocoon java doc tags.
I am *strongly* in favor of using special javadoc tags for the Cocoon
Components, and I want to make this a standard part in the new
Alexandria code documentation process.
Instead of xdoclet it can be very fast to use qdox:
http://qdox.sourceforge.net/
The relevant Ant classes:
http://qdox.sourceforge.net/xref/com/thoughtworks/qdox/ant/index.html
This won't happen overnight, but if the system is in place I'm quite
sure that people will start moving the documentation in the sources.
Do you have time to give qdox a try for Cocoon?
When we have it working, I'll make it part of the Alexandria stuff, so
that the documentation will be done by running Alexandria to generate
all code docs (xml javadocs, qdox docs, javasrc, xsldoc, etc), and then
Forrest for the final rendering and the site.
:-D
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by Bernhard Huber <be...@a1.net>.
hi,
i started the discussion, but never implemented it using xdoclet,
you may find some useful description in
http://members.a1.net/berni_huber/solutions/cocoon-javadoc-tags.html
Probably it's a lot of work change all sitemap component sources,
and describe a coding standard for submitting only
components sticking to the cocoon java doc tags.
regards bernhard
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote:
> On Fri, Nov 15, 2002 at 12:48:40PM -0600, Tony Collen wrote:
>
>>Bertrand Delacretaz wrote:
>
> ...
>
>>>This might mean restructuring much of the docs, trying to get obvious URLs
>>>like
>>>
>>>docs/components/generators/FileGenerator.html
>>>docs/components/serializers/PDFSerializer.html
>>>
>>>(and later)
>>>docs/blocks/pdf/fop/FopPdfBlock.html
>>>
>>>
>>
>>+1. The code is organized logically into packages, why shouldn't the
>>docs? :)
>
> ...
>
> How about using a tool like xdoclet or qdox to generate XML from @tags in
> the Cocoon source?
>
> Lots of work.. Ant has got something like this prototyped in
> proposal/xdocs.
It has already be done by someone (sorry! don't remember who) some time
ago. We have also had a discussion on it, but somehow the thing didn't
finalize.
If you have time, look in the cocoom-dev archives or in cocoon-related
sites, you should find references there.
IMHO technical documentation should definately be in the source files.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by Jeff Turner <je...@apache.org>.
On Fri, Nov 15, 2002 at 12:48:40PM -0600, Tony Collen wrote:
> Bertrand Delacretaz wrote:
...
> >This might mean restructuring much of the docs, trying to get obvious URLs
> >like
> >
> > docs/components/generators/FileGenerator.html
> > docs/components/serializers/PDFSerializer.html
> >
> >(and later)
> > docs/blocks/pdf/fop/FopPdfBlock.html
> >
> >
>
> +1. The code is organized logically into packages, why shouldn't the
> docs? :)
...
How about using a tool like xdoclet or qdox to generate XML from @tags in
the Cocoon source?
Lots of work.. Ant has got something like this prototyped in
proposal/xdocs.
--Jeff
> Tony
>
>
Re: Documentation Format...
Posted by Tony Collen <tc...@hist.umn.edu>.
Bertrand Delacretaz wrote:
>On Thursday 14 November 2002 17:23, Andy Lewis wrote:
>
>
>>. . .
>>What about a UNIX man page
>>approach to technical docs? For each transformer, gerneator, inputmodule,
>>etc, have a sinlge man page type document with the technical details,
>>samples if any, formats, etc.
>>. . .
>>
>>
>
>Makes at lot of sense. As Cocoon uses many components, it makes sense for
>the reference docs to follow the pattern, even more once Blocks are here, as
>each Block will need its own modular documentation.
>
>I think a single FileGenerator page, for example, could include information
>for both users and developers, assuming a strict page structure (DTD) is
>adhered to. The "DTD" of unix man pages is certainly a good starting point
>for this.
>
>This might mean restructuring much of the docs, trying to get obvious URLs
>like
>
> docs/components/generators/FileGenerator.html
> docs/components/serializers/PDFSerializer.html
>
>(and later)
> docs/blocks/pdf/fop/FopPdfBlock.html
>
>
+1. The code is organized logically into packages, why shouldn't the
docs? :)
The current docs are "organized", in a sense, in that stuff that goes
together is sort of globbed together, but I think the project would
benefit from something more logically organized.
If I go to x.a.o/cocoon looking for help in getting Cocoon speaking to a
database, do I look in How-To's, Tutorials, or FAQs? Or in the
user-guide?
I've been of the opinion that PHP has the best documentation around, and
that we should use them as a model for how to do things. Looking at the
PHP documentation, you'll see that there's more to "documentation" than
just "how to do things". There's a quick reference page, as well as a
"manual". If PHP came in a box, that's what would be printed and
included with it. I hate to say it, but if the current Cocoon
documentation was converted to print and then thown in the box, the
first thing I'd do would be throw it out :) All kidding aside, I
think we should try to make our docs as professional as possible. Good
docs make or break a project.
Tony
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
It would be, without a doubt, a huge undertaking. But, the current documentation is not organized
in a "scalable" and "maintainble" way for developers and writers, there is no single clear place
or format to introduce complete documentation for componenet "X" once written (I could easily be
wrong on this one, but I haven't seen it), and as it stnads it is still very hard to find your way
around as a user.
<snip/>
> Makes at lot of sense. As Cocoon uses many components, it makes sense for the reference docs
> to follow the pattern, even more once Blocks are here, as each Block will need its own modular
> documentation.
>
exactly
> I think a single FileGenerator page, for example, could include information for both users and
> developers, assuming a strict page structure (DTD) is adhered to. The "DTD" of unix man pages
> is certainly a good starting point for this.
a clean doc type is certainy the corect starting point here
>
> This might mean restructuring much of the docs, trying to get obvious URLs like
>
> docs/components/generators/FileGenerator.html
> docs/components/serializers/PDFSerializer.html
>
> (and later)
> docs/blocks/pdf/fop/FopPdfBlock.html
>
I'm not sure if it would need to have that kind of heirarchical organization or not. I would hope
to eventually have a good interface for accessing them (a block no doubt) through Cocoon.
> etc...
>
> Problem is, do we have the resources for what could be a major restructuring of the docs,
> including DTD design? The fairly slow activity on the -docs list makes me a little wary of
> starting big documentation projects, as lack of resources might cause them to fail.
there are never resources for a big documentation project unless you are the government (which,
although I currently work for thme, I am not)
I would hope we could get soem decent feedback on DTD design by taking, say, one components, and
using it as an example. As far as resources for the restructuring, no, they propably aren't there
to make a compelte sweep through in a short time period. I would be including to instead start a
slow migration, in parallel to existing docs. Encourage new components and new versions of
compoenents to move to the man page model when they are updated. This is not a "sexy" part of the
project, so a big-bang approach won't be likley to succeed here. This will have to be slow,
methodical, and incremental or it simply won't happen. tell me if I am overly skeptical here.
>
> Would you or your team be able to contribute to this "docs refactoring" project?
I am not sure if I am in a position to speak for anyone other than myself. I will actively
contribute to the DTD, and once that is compelted, I should be able to conrbiute some time to
documenting components. I am trying to get to where I can donate a lot more to this project. I
also may be able to drum up some other volunteers...
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andy Lewis wrote:
> I've been hammered for the last couple of days - so I'm just now catching back up here, please
> bear with me...
>
>>On Friday, November 15, 2002, at 03:52 AM, Bertrand Delacretaz wrote:
>>
>
> <snip/>
>
>>>I think a single FileGenerator page, for example, could include information
>>>for both users and developers, assuming a strict page structure (DTD) is adhered to. The "DTD"
>>>of unix man pages is certainly a good starting point
>>>for this.
>>
>>I don't see how a strict DTD will really produce good doc content. I developed a howto dtd for
>>Forrest (based on document-v11) and ended up leaving many elements optional (based on good
>>advice from Steven and others). I think well-written guidelines and good examples (and
>>editing) are key.
>>
>
> I actually agree - a strict DTD isn't needed. I am far more interested in a general defination of
> what should be there - what sections, and what they should have. A guide to authors is probably
> more effective at this point, since not everyone can read DTDs well anyway
Anakia hasn't enforced a DTD, and we find ourselves with docs that tend
to leak into style rather than content.
A DTD, being a tool, has nothing to do with good doc content. It can be
used to produce more consistent output, remain focused on content rather
than style and so on, but can itself create no good doc content, of course.
>>>Problem is, do we have the resources for what could be a major
>>>restructuring
>>>of the docs, including DTD design? The fairly slow activity on the -docs list
>>>makes me a little wary of starting big documentation projects, as lack of
>>>resources might cause them to fail.
>>
>>Well, if the effort needed was granular enough, we might get more help/resources. It can be
>>really difficult to write a comprehensive doc about Cocoon because so many concepts/skills are
>>involved. If someone knows a lot about a specific topic (but not necessarily others), they
>>could contribute that content and then a more advanced user could weave them together into
>>meaningful tracks. If we can break it into small pieces, it might happen.
>
> Granular effort, and incremental progress. "Big Bang" projects are always higher risk than slow
> progress. So what if it takes severla releases to get all of it done? Done wel, each componenet
> documented will make a huge improvmeent in the ability of people to understnad and use the
> component. And I think there is a stronmg liklihood that there will be a "critical mass" point on
> this kind of effort where there will be a lot more help from componenet writers and developers and
> such...
+1 Witness the Wiki.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
I've been hammered for the last couple of days - so I'm just now catching back up here, please
bear with me...
>
> On Friday, November 15, 2002, at 03:52 AM, Bertrand Delacretaz wrote:
>
<snip/>
>>
>> I think a single FileGenerator page, for example, could include information
>> for both users and developers, assuming a strict page structure (DTD) is adhered to. The "DTD"
>> of unix man pages is certainly a good starting point
>> for this.
>
> I don't see how a strict DTD will really produce good doc content. I developed a howto dtd for
> Forrest (based on document-v11) and ended up leaving many elements optional (based on good
> advice from Steven and others). I think well-written guidelines and good examples (and
> editing) are key.
>
I actually agree - a strict DTD isn't needed. I am far more interested in a general defination of
what should be there - what sections, and what they should have. A guide to authors is probably
more effective at this point, since not everyone can read DTDs well anyway
>> Problem is, do we have the resources for what could be a major
>> restructuring
>> of the docs, including DTD design? The fairly slow activity on the -docs list
>> makes me a little wary of starting big documentation projects, as lack of
>> resources might cause them to fail.
>
> Well, if the effort needed was granular enough, we might get more help/resources. It can be
> really difficult to write a comprehensive doc about Cocoon because so many concepts/skills are
> involved. If someone knows a lot about a specific topic (but not necessarily others), they
> could contribute that content and then a more advanced user could weave them together into
> meaningful tracks. If we can break it into small pieces, it might happen.
>
Granular effort, and incremental progress. "Big Bang" projects are always higher risk than slow
progress. So what if it takes severla releases to get all of it done? Done wel, each componenet
documented will make a huge improvmeent in the ability of people to understnad and use the
component. And I think there is a stronmg liklihood that there will be a "critical mass" point on
this kind of effort where there will be a lot more help from componenet writers and developers and
such...
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format... (manpage prototype at the wiki)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 20 November 2002 19:32, Andy Lewis wrote:
>. . .Let me know what you think.
Looks good to me!
I only added some additional examples for the most common cases.
-Bertrand
Re: Documentation Format... (manpage prototype at the wiki)
Posted by Andy Lewis <aj...@ascii27.net>.
What you put up was a great start...I played with it a bit, added some stuff, moved stuff around,
took stuff back out, and ended up saving a modified version that isn't too different from your
original, but does have a couploe fo changes. Let me know what you think.
> On Wednesday 20 November 2002 17:59, Andy Lewis wrote:
>>. . .it seems to me the next step here would be to start
>> bouncing around the strucutre of a manpage - what sections, and what should be in them, etc.
>
> I created a first shot on the Wiki at
> http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage,
> feel free to comment/expand/modify it!
>
> All wiki pages are versioned so we can always compare the different versions as needed.
>
> The wiki main page at http://outerthought.net/wiki/Wiki.jsp explains how this works.
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format... (manpage prototype at the wiki)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 20 November 2002 17:59, Andy Lewis wrote:
>. . .it seems to me the next step here would be to start
> bouncing around the strucutre of a manpage - what sections, and what should
> be in them, etc.
I created a first shot on the Wiki at
http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage,
feel free to comment/expand/modify it!
All wiki pages are versioned so we can always compare the different versions
as needed.
The wiki main page at http://outerthought.net/wiki/Wiki.jsp explains how this
works.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> On Wednesday 20 November 2002 16:20, Andy Lewis wrote:
>>. . .
>> intersting...hm....what would go in the developer man page that wouldn't fit in the javadocs?
>>. . .
>
> Actually I don't know. We'll have to start with user manpages anyway, and it's no problem
> leaving the option open should we need it later.
>
> -Bertrand
Fair enough...ok..so...it seems to me the next step here would be to start bouncing around the
strucutre of a manpage - what sections, and what should be in them, etc.
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Wednesday 20 November 2002 16:20, Andy Lewis wrote:
>. . .
> intersting...hm....what would go in the developer man page that wouldn't
> fit in the javadocs?
>. . .
Actually I don't know. We'll have to start with user manpages anyway, and
it's no problem leaving the option open should we need it later.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> Bertrand Delacretaz wrote:
>> David Crossley wrote:
<snip/>
>> > The table that is at the top of example Wiki:FileGeneratorManPage would be extracted
>> > directly from the javadoc tags, and would be needed for both sets of manpages.
>>
>> Yes, sounds good, this is definitely info that can be provided by developers.
>>
>> > It is important to get that information and also the
>> > developer manpages done first, because they will form
>> > the basis for the user manpages. The former should be
>> > done by cocoon-dev and the latter can then be subsequently
>> > done by anyone.
I agree with pulling from the source code / javadocs anything that can be pulled. However I think
that documentation for the developer audience is much less important right now than for the users.
THe developers can realisticly be expected to delve in and read the code if they need to know.
That just isn't a realistic expectation for the users though.
>>
>> Do we agree on what "user" and "developer" manpages are?
>
> Well spotted. This is very important to define up-front.
Agreed...I think this should be defined in terms of the audience and the tasks and skills that
would be reasonably expected for each.>
>> For me:
>> "user" is targeted at people using a component without modifying its java code
>>
>> "developer" would be targeted at people working on the component's code.
>
Agreed here.
> And working on other components. I still do not understand how
> my own code interacts with the rest of the wonderful Cocoon beast.
>
> Your definition is a good start but not quite there.
>
But this isn't really the point of this level of documentaiton, though I sympathize with teh
challenge.
>> And I think in this view "user" pages are much more urgent, many exist already but would
>> benefit from being refactored into a well-structured set of manpages.
>
> Agreed.
Agreed - as stated above.
>
>> I don't think developers have been complaining about lack of docs (the code is well
>> structured and well written), but *users* are complaining often.
>
> I would complain if i was the type. I see serious lack
> and inconsistency. Even the javadocs are not very good.
>
then the first step here is to start improving the javadocs. Once you have good javadocs, then
worry aboutthe next level of developer documentation.
> Rather i tried to encourage reference docs the last time
> that Berni's proposal came up.
>
> I jumped straight in to open source as a Cocoon developer,
> intending to patch as i learned. The "Dive in and learn on
> the job" method has worked well. However, i was seriously
> confused at the beginning and still am. I need well-structured
> reliable developer documentation, even if is just the
> one line definition of the component and its usage table.
>
We do need this, but I still think the users are more important. I can go look at the code, and
figure out what I need to know. But it takes time, and I have people on the team who can't.
> Actually, i am looking forward to these ensuing discussions
> of each component and their parameters. Building the
> documentation is where we will learn most.
>
Yep...and we'll probably find a few things to fix too...
> --David
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Bertrand Delacretaz wrote:
> David Crossley wrote:
> >. . .
> > I do not agree with this. I think that we need certain information
> > required as javadoc tags in the code before we can create *any*
> > manpages, be they *-user or *-dev pages.
>
> Is there an easy way to enforce the presence of these javadoc tags
> in the code?
I do not know. Let us make one, if there is not.
I am expecting that the reference doc generation system
that Berni proposed would be able to also summarise the
codebase and report any lack. It is amazing how quickly people
attend to things when they see their listed in a table of
"author" versus "gold stars", or a nag email to cocoon-dev,
or something simple.
> > The table that is at the top of example Wiki:FileGeneratorManPage
> > would be extracted directly from the javadoc tags, and would be
> > needed for both sets of manpages.
>
> Yes, sounds good, this is definitely info that can be provided by developers.
>
> > It is important to get that information and also the
> > developer manpages done first, because they will form
> > the basis for the user manpages. The former should be
> > done by cocoon-dev and the latter can then be subsequently
> > done by anyone.
>
> Do we agree on what "user" and "developer" manpages are?
Well spotted. This is very important to define up-front.
> For me:
> "user" is targeted at people using a component without modifying its java code
>
> "developer" would be targeted at people working on the component's code.
And working on other components. I still do not understand how
my own code interacts with the rest of the wonderful Cocoon beast.
Your definition is a good start but not quite there.
> And I think in this view "user" pages are much more urgent, many exist
> already but would benefit from being refactored into a well-structured set of
> manpages.
Agreed.
> I don't think developers have been complaining about lack of docs (the code
> is well structured and well written), but *users* are complaining often.
I would complain if i was the type. I see serious lack
and inconsistency. Even the javadocs are not very good.
Rather i tried to encourage reference docs the last time
that Berni's proposal came up.
I jumped straight in to open source as a Cocoon developer,
intending to patch as i learned. The "Dive in and learn on
the job" method has worked well. However, i was seriously
confused at the beginning and still am. I need well-structured
reliable developer documentation, even if is just the
one line definition of the component and its usage table.
Actually, i am looking forward to these ensuing discussions
of each component and their parameters. Building the
documentation is where we will learn most.
--David
Re: Documentation Format... (better names than manpages)
Posted by Andy Lewis <aj...@ascii27.net>.
>
> On Thursday, November 21, 2002, at 11:40 AM, Bertrand Delacretaz wrote:
>
>> On Thursday 21 November 2002 17:20, Andy Lewis wrote:
>>> . . .
>>> User Reference Pages
>>> Developer Reference Pages
>>
>> +1
>
> This is fine with me. However, let's be consistent about URI space. Instead of
>
> xxx-manpage.xml
> xxx-userref.xml
> xxx-devref.xml
>
> didn't we decide previously [1] (with your valuable input, Bertrand) on
>
> userref-xxx.xml
> devref-xxx.xml
>
> So a full URI might be:
>
> xml.apache.org/cocoon/userref/userref-xxx.html
> xml.apache.org/cocooon/devref/devref-xxx.html
>
> This would be consistent with what we have already implemented with faqs, how-tos, tutorials,
> etc.
+1
>
> Diana
>
> [1] http://marc.theaimsgroup.com/?l=forrest-dev&m=102053149908865&w=2
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format... (better names than manpages)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Friday 22 November 2002 11:49, Diana Shannon wrote:
>. . .
> didn't we decide previously [1] (with your valuable input, Bertrand) on
>
> userref-xxx.xml
> devref-xxx.xml
>. . .
Well, at my old-fartish age one tends to forget ;-)
+1 of course.
I think we could start summarizing (at the wiki) this cool "user reference
pages" spec. I won't have time in the next few days (and I have yet to try
the HowToForrestTransition) but if someone feels like doing it...
-Bertrand
Re: Documentation Format... (better names than manpages)
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, November 21, 2002, at 11:40 AM, Bertrand Delacretaz wrote:
> On Thursday 21 November 2002 17:20, Andy Lewis wrote:
>> . . .
>> User Reference Pages
>> Developer Reference Pages
>
> +1
This is fine with me. However, let's be consistent about URI space.
Instead of
xxx-manpage.xml
xxx-userref.xml
xxx-devref.xml
didn't we decide previously [1] (with your valuable input, Bertrand) on
userref-xxx.xml
devref-xxx.xml
So a full URI might be:
xml.apache.org/cocoon/userref/userref-xxx.html
xml.apache.org/cocooon/devref/devref-xxx.html
This would be consistent with what we have already implemented with
faqs, how-tos, tutorials, etc.
Diana
[1] http://marc.theaimsgroup.com/?l=forrest-dev&m=102053149908865&w=2
Re: Documentation Format... (better names than manpages)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 21 November 2002 17:20, Andy Lewis wrote:
>. . .
> User Reference Pages
> Developer Reference Pages
+1
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> On Thursday 21 November 2002 12:00, Diana Shannon wrote:
>>. . .Can we agree on semantics? I don't like the term "manpages" because they
>> imply we're making actual manpages....
>
> You're right, as I said before there was some confusion about this already.
Definately...we need a common, accepted term here.
>
>> Given what we're discussing, I think it's more precise to use the terms:
>>
>> user reference guide
>> developer reference guide
>
> Could we say "pages" instead of "guide"?
>
> Up to now what I like the most from this discussion are the following ideas:
>
> -one page per component, contains the essential usage info, maybe refers to more extensive
> "articles" about the component
>
> -every page has the same outline (variants allowed according to component categories)
>
> -pages are easy to find based on name conventions, similar to unix where you know that typing
> "man SomeNiftyTool" gets you SomeNiftyTool's usage information.
>
> So talking of "pages" still makes sense to me.
pages also have the advantages of being expressly a more ganualr item. I think keeping it an
obviously small scope effort will make is mentally less daunting for those who will hopefully
write them. I'm in favor of pages as well. So:
User Reference Pages
Developer Reference Pages
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 21 November 2002 12:00, Diana Shannon wrote:
>. . .Can we agree on semantics? I don't like the term "manpages" because they
> imply we're making actual manpages....
You're right, as I said before there was some confusion about this already.
> Given what we're discussing, I think it's more precise to use the terms:
>
> user reference guide
> developer reference guide
Could we say "pages" instead of "guide"?
Up to now what I like the most from this discussion are the following ideas:
-one page per component, contains the essential usage info, maybe refers
to more extensive "articles" about the component
-every page has the same outline (variants allowed according to component
categories)
-pages are easy to find based on name conventions, similar to unix where you
know that typing "man SomeNiftyTool" gets you SomeNiftyTool's usage
information.
So talking of "pages" still makes sense to me.
-Bertrand
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, November 21, 2002, at 04:16 AM, Bertrand Delacretaz wrote:
> Do we agree on what "user" and "developer" manpages are?
>
> For me:
> "user" is targeted at people using a component without modifying its
> java code
>
> "developer" would be targeted at people working on the component's code.
Can we agree on semantics? I don't like the term "manpages" because they
imply we're making actual manpages. Also, we're blurring the concept of
manuals and reference guides.
Given what we're discussing, I think it's more precise to use the terms:
user reference guide
developer reference guide
Diana
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 21 November 2002 10:05, David Crossley wrote:
>. . .
> I do not agree with this. I think that we need certain information
> required as javadoc tags in the code before we can create *any*
> manpages, be they *-user or *-dev pages.
Is there an easy way to enforce the presence of these javadoc tags in the
code?
> The table that is at the top of example Wiki:FileGeneratorManPage
> would be extracted directly from the javadoc tags, and would be
> needed for both sets of manpages.
Yes, sounds good, this is definitely info that can be provided by developers.
> It is important to get that information and also the
> developer manpages done first, because they will form
> the basis for the user manpages. The former should be
> done by cocoon-dev and the latter can then be subsequently
> done by anyone.
Do we agree on what "user" and "developer" manpages are?
For me:
"user" is targeted at people using a component without modifying its java code
"developer" would be targeted at people working on the component's code.
And I think in this view "user" pages are much more urgent, many exist
already but would benefit from being refactored into a well-structured set of
manpages.
I don't think developers have been complaining about lack of docs (the code
is well structured and well written), but *users* are complaining often.
-Bertrand
Re: Documentation Format...
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Diana Shannon wrote:
>
> On Thursday, November 21, 2002, at 04:05 AM, David Crossley wrote:
>
>> I do not agree with this. I think that we need certain information
>> required as javadoc tags in the code before we can create *any*
>> manpages, be they *-user or *-dev pages.
>
>
> I agree with David's point here.
+1
That is the minimum base. Java classes have javadocs, but these are
Cocoon Components, and have a use that classic Javadocs don't capture.
Some components have the info in the class description, but the docs
don't report anything now.
Look here for example:
http://xml.apache.org/cocoon/userdocs/matchers/matchers.html
http://xml.apache.org/cocoon/userdocs/actions/actions.html
http://xml.apache.org/cocoon/userdocs/selectors/selectors.html
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Documentation Format... (user reference pages scenario)
Posted by Andy Lewis <aj...@ascii27.net>.
> On Thursday 21 November 2002 14:09, Nicola Ken Barozzi wrote:
>>. . .
>> > 2) Supplement this info with an xxx-manpage.xml file (or whatever, but
>>. . .
>> I'd use an html page, and possibly a javadoc-compatible one.
>>. . .
>
> I see your point, you're right that most people are reluctant to write docs in HTML. Validated
> XHTML would be better though, but it might be too much to ask.
>
>>. . .
>> As for xdoc format, Cocoon can convert the simple html to xdoc, so it shouldn't be a problem.
>>. . .
sdine this will become a primary source for exmaples, we should make sure that the format is one
we can leverage for aggregate examples likstings, and so on. XML or XHTML, as long as we can pull
out the relevant bits whenever we need to for something else.
>
> ok
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format... (user reference pages scenario)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 21 November 2002 14:09, Nicola Ken Barozzi wrote:
>. . .
> > 2) Supplement this info with an xxx-manpage.xml file (or whatever, but
>. . .
> I'd use an html page, and possibly a javadoc-compatible one.
>. . .
I see your point, you're right that most people are reluctant to write docs
in HTML. Validated XHTML would be better though, but it might be too much to
ask.
>. . .
> As for xdoc format, Cocoon can convert the simple html to xdoc, so it
> shouldn't be a problem.
>. . .
ok
-Bertrand
Re: Documentation Format... (user reference pages scenario)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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)
---------------------------------------------------------------------
Re: Documentation Format... (user reference pages scenario)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Hi Bernhard,
>. . .
> I'd like to give a solution, and refinement to your ideas:
<snip cause="agree"/>
>. . .
> The imaginative javadoc generator will use qdox, xdoclet, javadoc
> doclet, to generate xml from the original java source file.
>. . .
Yes. I will move the question of what to use for this to forrest-dev, as I
think it might be more relevant to Forrest than Cocoon.
-Bertrand
Re: Documentation Format... (user reference pages scenario)
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, November 21, 2002, at 05:29 PM, Bernhard Huber wrote:
> 2. Input-date from XYZ-manpage.xml, or XYZ-merging.xml
> Seperated xml document, describing the component more literally.
>
+1
Diana
Re: Documentation Format... (user reference pages scenario)
Posted by Bernhard Huber <be...@a1.net>.
hi,
>
> 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.)
>
okay
> 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.
>
I'd like to give a solution, and refinement to your ideas:
1. Input-data from java files XYZ.java
1.1 first sentence of javadoc ( ie. /** First sentence. .... */ class XY
... )
1.2 general tags having prefix of @cocoon, limited to the class
documentation: @cocoon:name, @cocoon:status
1.3 general javadoc tags in the class documentation: @version, @since,
@author
1.4 whole javadoc comment, of classdoc, (need to pass it to jtidy, to
transform it xhtml)
Note: I am not quite sure where we should allow writing @cocoon tags.
You may write it at classlevel, memberlevel, or methodlevel.
2. Input-date from XYZ-manpage.xml, or XYZ-merging.xml
Seperated xml document, describing the component more literally.
Thus assuming we have a javadoc generator, we might define following
pipeline:
<map:pipeline>
<map:match pattern="reference-doc/*">
<map:aggregate>
<map:part src="cocoon:/javadoc-{1}"/>
<!-- need to figure out how get the real dir-value of .... -->
<map:part src="src/java/...../{1}-manpage.xml"/>
</map:aggregate>
<map:transform src="stylesheets/reference-doc2document.xsl"/>
<map:serialize>
</map:match>
<map:match pattern="javadoc-{1}"/>
<map:generator type="javadoc" src="src/java/...../{1}.java"/>
<map:serialize/>
</map:match>
The imaginative javadoc generator will use qdox, xdoclet, javadoc
doclet, to generate xml from the original java source file.
What do you think?
Does anyone know if there is alread a java to xml tool available, or a
java DTD, or at least a javadoc DTD?
regards bernhard
Re: Documentation Format... (user reference pages scenario)
Posted by Andy Lewis <aj...@ascii27.net>.
> 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."
Re: Documentation Format... (user reference pages scenario)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
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.)
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.
-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
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, November 21, 2002, at 04:05 AM, David Crossley wrote:
> I do not agree with this. I think that we need certain information
> required as javadoc tags in the code before we can create *any*
> manpages, be they *-user or *-dev pages.
I agree with David's point here.
> The table that is at the top of example Wiki:FileGeneratorManPage
> would be extracted directly from the javadoc tags, and would be
> needed for both sets of manpages.
>
> It is important to get that information and also the
> developer manpages done first, because they will form
> the basis for the user manpages. The former should be
> done by cocoon-dev and the latter can then be subsequently
> done by anyone.
>
> Another important reason is that we need to get some
> system in place soon to ensure that developers do not
> continue to write code that has insufficient accompanying
> documentation.
As for Cocoon-specific tags, here's what Bernhard initially showed:
http://members.a1.net/berni_huber/solutions/cocoon-javadoc-tags.html
It also might be helpful for those who don't remember the initial
discussion to read:
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101934150206759&w=2
Diana
Re: Documentation Format...
Posted by David Crossley <cr...@indexgeo.com.au>.
Andy Lewis wrote:
> Bertrand Delacretaz wrote:
> >Andy Lewis wrote:
> >>. . .my intent with the man pages was user-level technical
> >>documentation...
> >
> > same here, but hearing other comments makes me think that we
> > might need TWO reference pages
> > (manpages) for some components, one for users (who use the
> > components) and one for developers
> > (who might want to modify or inherit them).
>
> intersting...hm....what would go in the developer man page that
> wouldn't fit in the javadocs?
>
> >
> > We might want to leave this open by first creating manpages named
> >
> > xxx-user-manpage.xml
> >
> > and leave
> >
> > xxx-dev-manpage.xml
> >
> > available for future use.
> >
> > -Bertrand
I do not agree with this. I think that we need certain information
required as javadoc tags in the code before we can create *any*
manpages, be they *-user or *-dev pages.
The table that is at the top of example Wiki:FileGeneratorManPage
would be extracted directly from the javadoc tags, and would be
needed for both sets of manpages.
It is important to get that information and also the
developer manpages done first, because they will form
the basis for the user manpages. The former should be
done by cocoon-dev and the latter can then be subsequently
done by anyone.
Another important reason is that we need to get some
system in place soon to ensure that developers do not
continue to write code that has insufficient accompanying
documentation.
--David
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
> On Tuesday 19 November 2002 18:07, Andy Lewis wrote:
>>. . .my intent with the man pages was user-level technical documentation...
>
> same here, but hearing other comments makes me think that we might need TWO reference pages
> (manpages) for some components, one for users (who use the components) and one for developers
> (who might want to modify or inherit them).
intersting...hm....what would go in the developer man page that wouldn't fit in the javadocs?
>
> We might want to leave this open by first creating manpages named
>
> xxx-user-manpage.xml
>
> and leave
>
> xxx-dev-manpage.xml
>
> available for future use.
>
> -Bertrand
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Tuesday 19 November 2002 18:07, Andy Lewis wrote:
>. . .my intent with the man pages was user-level technical documentation...
same here, but hearing other comments makes me think that we might need TWO
reference pages (manpages) for some components, one for users (who use the
components) and one for developers (who might want to modify or inherit them).
We might want to leave this open by first creating manpages named
xxx-user-manpage.xml
and leave
xxx-dev-manpage.xml
available for future use.
-Bertrand
Re: Documentation Format...
Posted by Andy Lewis <aj...@ascii27.net>.
>
> On Monday, November 18, 2002, at 02:45 AM, Bertrand Delacretaz wrote:
>
>>
>>> . . .
>>> Well, if the effort needed was granular enough, we might get more help/resources.
>>> . . .
>>
>> I think the concept of man pages (one page for each component)using javadocs
>> tags (as proposed by several people here) is a nice way of making the effort
>> more granular.
>
> Yes, but....., I don't consider it a panacea (cure-all) for docs. It's really a subset of
> granular info or topics that can be used by other docs. Because it's so tied to the code, it
> doesn't necessarily cover the range of topics needed by other docs.
>
> Diana
The use of javadoc tags or this is...well....I'm not sure. I think there is some stuf that goes in
the code, but my intent with the man pages was user-levle technical documentation. - such as what
apramters does this generator recognize, and what are valid values, or how shoudl the URI be
formatter, or what tags does a transformetr understand. User docs for each component. It certainly
won't solve all the documentation concerns, I agree, but it will provide a base level of reference
docs for users to work with. And it is vvery ganular, and should be easy to start, and there is a
very strong possibility of having the developers maintain it in a timely fashion.
--
"The heights of genius are only measurable by the depths of stupidity."
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Monday, November 18, 2002, at 02:45 AM, Bertrand Delacretaz wrote:
>
>> . . .
>> Well, if the effort needed was granular enough, we might get more
>> help/resources.
>> . . .
>
> I think the concept of man pages (one page for each component)using
> javadocs
> tags (as proposed by several people here) is a nice way of making the
> effort
> more granular.
Yes, but....., I don't consider it a panacea (cure-all) for docs. It's
really a subset of granular info or topics that can be used by other
docs. Because it's so tied to the code, it doesn't necessarily cover the
range of topics needed by other docs.
Diana
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Saturday 16 November 2002 13:20, Diana Shannon wrote:
>. . .
> I don't see how a strict DTD will really produce good doc content. I
> developed a howto dtd for Forrest (based on document-v11) and ended up
> leaving many elements optional (based on good advice from Steven and
> others). I think well-written guidelines and good examples (and editing)
> are key.
>. . .
You're right. My idea of a DTD was to go beyond "titled sections" as in the
current xdocs by using element names to define sections, to make sure every
"man page" has the required sections (like name,synopsis,description, etc.).
>. . .
> Well, if the effort needed was granular enough, we might get more
> help/resources.
>. . .
I think the concept of man pages (one page for each component)using javadocs
tags (as proposed by several people here) is a nice way of making the effort
more granular.
-Bertrand
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Friday, November 15, 2002, at 03:52 AM, Bertrand Delacretaz wrote:
>> . . .
>> What about a UNIX man page
>> approach to technical docs? For each transformer, gerneator,
>> inputmodule,
>> etc, have a sinlge man page type document with the technical details,
>> samples if any, formats, etc.
>> . . .
>
> Makes at lot of sense. As Cocoon uses many components, it makes sense
> for
> the reference docs to follow the pattern, even more once Blocks are
> here, as
> each Block will need its own modular documentation.
>
> I think a single FileGenerator page, for example, could include
> information
> for both users and developers, assuming a strict page structure (DTD) is
> adhered to. The "DTD" of unix man pages is certainly a good starting
> point
> for this.
I don't see how a strict DTD will really produce good doc content. I
developed a howto dtd for Forrest (based on document-v11) and ended up
leaving many elements optional (based on good advice from Steven and
others). I think well-written guidelines and good examples (and editing)
are key.
> Problem is, do we have the resources for what could be a major
> restructuring
> of the docs, including DTD design? The fairly slow activity on the
> -docs list
> makes me a little wary of starting big documentation projects, as lack
> of
> resources might cause them to fail.
Well, if the effort needed was granular enough, we might get more
help/resources. It can be really difficult to write a comprehensive doc
about Cocoon because so many concepts/skills are involved. If someone
knows a lot about a specific topic (but not necessarily others), they
could contribute that content and then a more advanced user could weave
them together into meaningful tracks. If we can break it into small
pieces, it might happen.
Diana
Re: Documentation Format...
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 14 November 2002 17:23, Andy Lewis wrote:
>. . .
> What about a UNIX man page
> approach to technical docs? For each transformer, gerneator, inputmodule,
> etc, have a sinlge man page type document with the technical details,
> samples if any, formats, etc.
>. . .
Makes at lot of sense. As Cocoon uses many components, it makes sense for
the reference docs to follow the pattern, even more once Blocks are here, as
each Block will need its own modular documentation.
I think a single FileGenerator page, for example, could include information
for both users and developers, assuming a strict page structure (DTD) is
adhered to. The "DTD" of unix man pages is certainly a good starting point
for this.
This might mean restructuring much of the docs, trying to get obvious URLs
like
docs/components/generators/FileGenerator.html
docs/components/serializers/PDFSerializer.html
(and later)
docs/blocks/pdf/fop/FopPdfBlock.html
etc...
Problem is, do we have the resources for what could be a major restructuring
of the docs, including DTD design? The fairly slow activity on the -docs list
makes me a little wary of starting big documentation projects, as lack of
resources might cause them to fail.
Would you or your team be able to contribute to this "docs refactoring"
project?
-Bertrand
Re: Documentation Format...
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, November 14, 2002, at 11:23 AM, Andy Lewis wrote:
>
> I've just recently joined the documentation list,
Welcome! Thanks for joining.
> and wanted to through out a couple of ideas.
> First off, I have been using Cocoon since 1.3, and am currently
> developing a portal solution for
> NASA using 2.1-dev.
I remember hearing about it. I also remember Stefano asking if you could
write up some kind of a doc (e.g. success story?) about it. Was that
ever possible, given your client?
> Part of that effort includes bringing other people her eup to speed on
> the
> technology. I have to say that ,while the Cocoon documentation has ben
> improving steadily, it is
> still a huge struggle to even point someone to the correct place.
I think almost everyone would agree with you. I also remember an earlier
post from you on cocoon-dev saying that "books are your friends".
Speaking **only** for myself, not the Cocoon project, I deliberately
chose not to reorganize the docs when I started working on the docs
(about six months ago). Several books were about to be released. I think
books are worth their "weight in gold". I knew, as one person with
limited time, that I could never do anything that would be as good. I
decided to use my limited committer/volunteer time to increase the pool
of authors. So I wrote up a bunch of guidelines to facilitate this and
have done a lot of "handholding" of new authors as they come forward. I
think we've all been waiting to do anything from a reorganizational
perspective until the Forrest transition occurs which may happen very
soon. If you have ever compared Cocoon's doc generation framework to
Forrest's, you'll understand why.
> I am not making these comments without suggesstions however, as my
> intent is to be constructive
> here so please pardon any presumptiousness on my part. Cocoon is, as we
> know, extremely modular,
> and becoming increasingly so. But documentation seems to be ither
> sparse, or scattered. I recall
> the threads about how to organize it, and have seen some efforts down
> that path. But the first
> thing that comes to mind is that if I want to know the details ofa
> particular input module or
> transformer, I can't find it in a a single place. There is some
> reference material, and some
> concept material, and some tutorial material, each introducing new
> technical information. Also I
> have seen that, as the code evolves, docs get left behind. I would gues
> that part of this is
> because there are multiple places to update. This brings me (at long
> last) to my suggestion. What
> about a UNIX man page approach to technical docs? For each transformer,
> gerneator, inputmodule,
> etc, have a sinlge man page type document with the technical details,
> samples if any, formats,
> etc. This would help developers and users both have a single stop for
> such info. Of course this is
> only one aspect of documentation. The project still needs concept
> documents, JavaDocs, tutorials,
> etc. But as a basic level for technical information users need, I think
> it would make a
> substantial difference.
I think some kind of granular approach to reorganizing docs would help.
That way, one could organize/present them to users the in many different
ways, not simply by user type, packages, etc. Many share your belief.
What we need is some kind of proposal or proof of concept, if someone
*really* wants to do this.
Diana