cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: [docs] "docs" Ant target
Date Thu, 10 Mar 2005 06:46:15 GMT
David Crossley wrote:
> Reinhard Poetz wrote:
>>- copy trunk/src/documentation over to trunk/build/templ-docs
>>- create sitemap component docs and put them into
>>  trunk/build/templ-docs/src/documentation/content/xdocs/userdocs
>>- create the JAR files document and copy it into the xdocs dir
>>- create the Javadocs and put them in the xdocs dir
>>- use the "exec" task to run forrest on the temporary directory and
>>  generate the docs
>>
>>I think this shouldn't be too difficult. Does this sound reasonable?
> 
> 
> That seems to be the same as what was happening already. The "build docs"
> was copying all of the source xml to build/... then the jars.xml was generated,
> then the SitemapTask read the *.java and appended info to /userdocs/*.xml
> So perhaps all that is needed is to fix the pathnames in docs-build.xml
> and trunk/forrest.properties to reflect the new location of the docs.
> (Actually i am not sure why that needed to change.)
> 
> We separated the 'forrest' command from the Cocoon build, because the
> Cocoon build system was getting so complex. So the procedure was to
> do 'build docs' then do 'forrest' at the top-level cocoon/trunk/
> If you can get it to happen using the "exec" Ant task, then fine.

ok, will give it a try. My goal is that people can still use "forrest only" to 
build the docs. If they use the "build docs" command, they get the API docs (see 
below) in addition. This will also be the target that has to be called by 
forrestbot.


> The generated Javadocs don't need to go into the xdocs source directory.
> They are a separate thing that get copied manually into the cocoon/site
> SVN repository. By the way, the 2.1 javadocs on the website are probably
> way past due for an update.

ok

> Perhaps we should step back a bit and assess the situation. It seems
> a cumbersome process to double-handle all of the source docs, just to
> add some specially-generated docs. Would it help to put these special
> docs into a completely separate workspace?

I don't like this duplicaton process either. Well, as far as I understand, the 
reasons for this is that we want to style the docs using the common skin and not 
something different. The question is, do we really need the sitemap-component 
docs (some kind of API documentation) in this common style? I'd say no. They are 
similar to javadocs and nobody has ever complained about not having the tightly 
integrated in our website. (I don't want to say that I wouldn't like seeing all 
docs in the common style but it's not worth doing the huge amount of work to get 
it done.)

Maybe  we can agree on this: Generated documentation is linked from our 
documenation but is not integrated in our common style:

http://cocoon.apache.org/2.2/apidocs/
http://cocoon.apache.org/2.2/sitemap-components/
http://cocoon.apache.org/2.2/jars/

This would make thinks much easier. WDOT?

>>The only thing that I have to figure out is how to integrate book.xml into 
>>site.xml-driven pages. Does anybody know this or shall I ask on dev@forrest?
> 
> 
> Ask at Forrest. Here are some references you have probably already seen:
> http://forrest.apache.org/faq.html#generating_menus
> http://forrest.apache.org/docs/linking.html#book-menu-selection

thank you

> [*]
> The other thing to bear in mind, and this was one of the big hold-ups
> in the past with improving the docs, is that all of the docs are also
> generated via the Cocoon webapp ... 'cocoon.sh servlet'. They use old
> stylesheets that are probably dependent on an old version of xdocs DTD.
> I don't have any answer to that.

I don't think we need this anymore. "forrest webapp" is more than a replacement 
for people who want to see the docs "live".


-- 
Reinhard Pötz           Independant Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------

Mime
View raw message