Re: [Proposal] review of sitemap component documentation

[Reinhard Poetz <re...@apache.org>]

David Crossley wrote:
> The current User Guide documentation has one document
> for each Sitemap Component, e.g.
> http://cocoon.apache.org/2.1/userdocs/generators/file-generator.html
> 
> Each main document has a shell with some content
> in src/documentation/xdocs/userdocs/*
> 
> During the 'build docs' a "SitemapTask' is called.
> This scans the java code and extracts certain javadoc-like
> tags and appends this information to the top of each
> shell document to produce the "Description" and "Info"
> sections.
> 
> We need to consistently review both the shell documents
> and the javadoc-like tags in the code. While we are
> in there, the actual javadoc comments and tags could
> also be reviewed.
> 
> I propose to create a planning document to co-ordinate
> this effort. It would be a table which lists each sitemap
> component and whether each aspect has been reviewed.
> The columns are not yet determined, but they would
> be things like: shell doc present, shell doc suitable,
> javadoc tags present, javadoc tags suitable, etc.
> 
> Then i, and others, can gradually work through the list
> and get each document/tags up-to-date. If we cannot
> readily determine the info, then we would ask pertinent
> questions on the dev list. If that doesn't help then
> we can dig in the 'svn log' to find the culprits.
> 
> This is something that i have been wanting to do for
> ages and with the recent brouhaha about documentation,
> i thought it finally time to get started. It is going
> to be a long road.
> 
> If no-one says stop, then i will just commence soon.

Go for it!

We also have to consider that we have more independant blocks very soon, means 
that we have the goal that each block can be released seperatly and IMO it 
should provide its own docs.

This seems to be the simple part. More difficult is providing a complete 
documentation consisting of Cocoon core and all blocks automatically ...

-- 
Reinhard

Re: [Proposal] review of sitemap component documentation

[Reinhard Poetz <re...@apache.org>]

Thorsten Scherler wrote:
> Reinhard Poetz escribió:
> <snip/>
> 
>> We also have to consider that we have more independant blocks very 
>> soon, means that we have the goal that each block can be released 
>> seperatly and IMO it should provide its own docs.
> 
> <snip/>
> 
> Hello Reinhard,
> 
> you may want to have a look in the new plugin system of 
> http://forrest.apache.org.
> 
> The idea behind it is to keep plugins that containing their own 
> documentation. Maybe you can use some of this ideas for the blocks.
> 
> ...or maybe cocoon can adopt the idea of plugins for blocks. ;-)


Thank you. Learning more about Maven and Forrest plugins are on my todo list 
before I continue with BlockBuilder/Deployer development.

-- 
Reinhard

Re: [Proposal] review of sitemap component documentation

[Thorsten Scherler <th...@apache.org>]

Reinhard Poetz escribió:
<snip/>
> We also have to consider that we have more independant blocks very soon, 
> means that we have the goal that each block can be released seperatly 
> and IMO it should provide its own docs.
<snip/>

Hello Reinhard,

you may want to have a look in the new plugin system of 
http://forrest.apache.org.

The idea behind it is to keep plugins that containing their own 
documentation. Maybe you can use some of this ideas for the blocks.

...or maybe cocoon can adopt the idea of plugins for blocks. ;-)

regards
-- 
thorsten

"Together we stand, divided we fall"
Hey you (Pink Floyd)

Re: [Proposal] review of sitemap component documentation

[David Crossley <cr...@apache.org>]

Bertrand Delacretaz wrote:
> David Crossley a écrit :
> 
>> ...That is why i was asking if anyone was going
>> to say: stop, we need to throw away or redesign that
>> excellent SitemapTask to cope with separate bloack docs....
> 
> <nitpicking>
> Just one small thing: the name SitemapTask says little about what this 
> does, as I understand you're working on it, it might be good to rename 
> it to something more meaningful. SitemapComponentDocTask maybe.
> </nitpicking>

This task has dual purposes.

1) Generate component documentation.
2) Add sitemap entries during the build process.

The tools/targets/webapp-build.xml has this
commented-out and so does tools/src/blocks-build.xsl
So perhaps it is not used for purpose #2 anymore.
If so, then yes, we should rename it as you suggest.

--David

Re: [Proposal] review of sitemap component documentation

[Bertrand Delacretaz <bd...@apache.org>]

Le 24 nov. 04, à 08:48, David Crossley a écrit :

> ...That is why i was asking if anyone was going
> to say: stop, we need to throw away or redesign that
> excellent SitemapTask to cope with separate bloack docs....

<nitpicking>
Just one small thing: the name SitemapTask says little about what this 
does, as I understand you're working on it, it might be good to rename 
it to something more meaningful. SitemapComponentDocTask maybe.
</nitpicking>

-Bertrand

Re: [Proposal] review of sitemap component documentation

[Reinhard Poetz <re...@apache.org>]

David Crossley wrote:
> Reinhard Poetz wrote:
> 
>>
>> Go for it!
>>
>> We also have to consider that we have more independant blocks very 
>> soon, means that we have the goal that each block can be released 
>> seperatly and IMO it should provide its own docs.
>>
>> This seems to be the simple part. More difficult is providing a 
>> complete documentation consisting of Cocoon core and all blocks 
>> automatically ...
> 
> 
> Yeah, i thought a little about that wrinkle while
> devising that proposal. Don't know what the answer
> is yet. That is why i was asking if anyone was going
> to say: stop, we need to throw away or redesign that
> excellent SitemapTask to cope with separate bloack docs.
> 
> Anyway, i think that reviewing the content of the
> current sitemap components docs is still worthwhile.

Don't want to stop you and I don't think that having more independant blocks is 
a problem for the sitemapTask.

I just wanted to share my thoughts that popped while I was writing my reply to 
Sylvain's mail on sitemap-buildins.xconf proposal.

                                   - o -

Back to the documentation problem: The situation is that docs will be spread 
over many different places. IMO a Cocoon 2.2 distribution will contain Cocoon 
core and a number of selected blocks (pdf, ojb, ...). This distribution, which 
will be a binary distribution again, will contain docs for core and all its 
blocks. We should have some automated mechanism to provide *one* documentation. 
Maybe this is an Ant task that does copies all docs to one destination and 
patches some forrest configuration files. Just a RT ...

-- 
Reinhard

Re: [Proposal] review of sitemap component documentation

[Ralph Goers <Ra...@dslextreme.com>]

David Crossley wrote:

> Reinhard Poetz wrote:
>
>>
>> Go for it!
>>
>> We also have to consider that we have more independant blocks very 
>> soon, means that we have the goal that each block can be released 
>> seperatly and IMO it should provide its own docs.
>>
>> This seems to be the simple part. More difficult is providing a 
>> complete documentation consisting of Cocoon core and all blocks 
>> automatically ...
>
>
> Yeah, i thought a little about that wrinkle while
> devising that proposal. Don't know what the answer
> is yet. That is why i was asking if anyone was going
> to say: stop, we need to throw away or redesign that
> excellent SitemapTask to cope with separate bloack docs.
>
> Anyway, i think that reviewing the content of the
> current sitemap components docs is still worthwhile.
>
1. I don't believe the independent blocks will occur until 2.2 is 
released.  I believe 2.1 still has a long life ahead of it and making 
the documentation better needs to start there.
2. Even after separating the blocks, presumably none of the work to 
clean up the javadoc will be wasted.

Re: [Proposal] review of sitemap component documentation

[David Crossley <cr...@apache.org>]

Reinhard Poetz wrote:
> 
> Go for it!
> 
> We also have to consider that we have more independant blocks very soon, 
> means that we have the goal that each block can be released seperatly 
> and IMO it should provide its own docs.
> 
> This seems to be the simple part. More difficult is providing a complete 
> documentation consisting of Cocoon core and all blocks automatically ...

Yeah, i thought a little about that wrinkle while
devising that proposal. Don't know what the answer
is yet. That is why i was asking if anyone was going
to say: stop, we need to throw away or redesign that
excellent SitemapTask to cope with separate bloack docs.

Anyway, i think that reviewing the content of the
current sitemap components docs is still worthwhile.

--David