Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: unknown (hermes.apache.org: local policy)
Date: Thu, 10 Mar 2005 17:18:08 +1100
From: David Crossley <crossley@apache.org>
To: dev@cocoon.apache.org
Subject: Re: [docs] "docs" Ant target
Message-ID: <20050310061808.GA6678@igg.indexgeo.com.au>
References: <4225BCD6.7060806@apache.org>
 <20050302205804.GA5709@igg.indexgeo.com.au> <42262E1D.70109@apache.org>
 <20050303062333.GA554@igpb.indexgeo.com> <4226C49C.8040305@apache.org>
 <20050304010942.GA2462@igpb.indexgeo.com> <42281BAA.9070101@apache.org>
 <20050309053450.GA5256@igg.indexgeo.com.au> <422F32C2.6080806@apache.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <422F32C2.6080806@apache.org>
User-Agent: Mutt/1.4i

Reinhard Poetz wrote:
> David Crossley wrote:
> >I will not have much time to help with the docs re-organisation,
> >but i will do what i can.
> 
> If you can help me to understand what the docs target does I'm more than 
> happy :-)

I will try. Please ask specific questions on that. I have provided
general descriptions in email earlier in this thread and
http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html
and of course one could follow the maze in tools/targets/docs-build.xml

> >Here is a list of the changes that i have made to the forrestbot
> >configuration.
> >
> >For those that didn't know about it, there is a demonstration
> >Forrestbot which automatically builds the documentation every
> >six hours. Cocoon committers can also trigger it manually.
> >http://brutus.apache.org:36366/forrestbot-webapp/
> >
> >cocoon-block-portal
> >-------------------
> >This was called "cocoon-doco-portal" which used sources from
> >http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/portal-block
> >Now it has been renamed to "cocoon-block-portal" and uses sources from
> >http://svn.apache.org/repos/asf/cocoon/trunk/src/blocks/portal/documentation
> >
> >Is each block going to have a separate forrest configuration?
> 
> The configurations will differ only in skinconf.xml - everything else, 
> except the content, will be the same.

Sure. I meant to say: Will every block get a separate forrest workspace?
And how does that equate to the website? Will each block have a separate
directory at cocoon.apache.org? Also how will the "docs via cocoon webapp"
be handled (see [*] below)?

> >cocoon-doco-global
> >------------------
> >This uses sources from
> >http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/global
> >This is the new whiteboard docs for the top-level Cocoon website.
> 
> Upayavira is working on the migration - as soon as he is finished, we will 
> move them over to cocoon/site/src
> 
> >cocoon-site
> >-----------
> >This uses sources from
> >http://svn.apache.org/repos/asf/cocoon/site
> >This is the current docs for the top-level Cocoon website.
> >
> >Is "cocoon-doco-global' supposed to replace this?
> 
> yes, see above
> 
> >cocoon-trunk
> >------------
> >This was the documentation for trunk 2.2 docs. I don't want to remove
> >the forrestbot configuration for this, because it was a huge effort to
> >get it to build. We might need some of this configuration for the new
> >"cocoon-2-2" docs when it is building the "userdocs" again.
> >The forrestbot builds have been disabled.
> 
> ok
> 
> >cocoon-2-2
> >----------
> >This was called "cocoon-doco-2-2" which used sources from
> >http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/2.2
> >Now it has been renamed to "cocoon-2-2" and uses sources from
> >http://svn.apache.org/repos/asf/cocoon/trunk/src/documentation
> >which replaced the original content.
> 
> ok
>
> >--------------------------------
> >
> >People can still build each site locally (need forrest-0.6+ installed).
> >e.g. cd trunk/src/blocks/portal/documentation; forrest
> >e.g. cd trunk/src/documentation; forrest
> >
> >Reinhard, when you are back, we can try to fix the building of the
> >"userdocs" and installing/jars.html in "cocoon-2-2" ...
> 
> back again, was skiing in the Alps (one of the few things in life, that 
> makes more fun than Cocoon ;-) )

Lucky you, more than one joy.

> Well, I'm trying to figure out, what to do with the docs that are built in 
> a pre-processing step or independently. So far I found:
> 
>  - Javadocs
>  - Sitemap components docs
>  - Jar files overview
> 
> Is this the complete list or am I missing something?

That is all. Of course the "Sitemap components docs" has "core"
components and components from blocks.

> The question now is, how shall I implement this. I would write an Ant 
> script that does it this way:
> 
> - 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.

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.


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?

> 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

[*]
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.

--David