You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Reinhard Poetz <re...@apache.org> on 2004/12/27 17:43:41 UTC
Remove current docs in trunk
Reinhard Poetz wrote:
> H.vanderLinden@MI.unimaas.nl wrote:
>
>>> let's start in trunk! remove the old docs (they are still in 2.1) and
>>> let's write new ones or selectivly copy old docs over.
>>
>>
>>
>> OK, but there must be a way to mark off the old docs as either "added" or
>> "deprecated" to know when you're finished looking at the old docs.
>
>
> a wiki page should be good enough.
I propose to remove the docs in trunk. I don't think they are syncronized with
2.1 and IMO there is no reasons to have them twice. It's also a chance to
rewrite and restructure our documentation.
At http://wiki.apache.org/cocoon/22NewDocuments you find a list of all documents
in 2.1. Using this list we can move each document selectivly over to trunk.
If anybody objects I will remove the old docs in trunk on Sunday and set up the
sekelton of new ones using Forrest 0.6.
One question to the Forrest specialists: What is a future-proof document type
that can be edited with a *common* WYSIWIG editor like the HTML editor that
comes with Mozilla and that works with Forrest 0.6?
--
Reinhard
Re: Integrating auto-generated docs
Posted by Reinhard Poetz <re...@apache.org>.
David Crossley wrote:
> Reinhard Poetz wrote:
>
>>Some of us started with generating docs out of Java sources (sitemap
>>components). I have to admit that I have no experience with this process
>>but I would like to integrate these reference docs into the new
>>documentation.
>
>
> There is a rough explanation at
> http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html
>
> What you refer to as "reference docs" below, are what you see now
> on the website at /userdocs/$component/
>
>
>>The problem is, how can I configure Forrest to use an
>>unknown number of docs and generate the menu *automatically*:
>
>
> The Cocoon SitemapTask that generates those reference docs already
> generates the book.xml files, which is the way Cocoon's forrest
> uses to generate the navigation panels. Using book.xml is an old way
> but it still works fine.
>
> Anyway, my point is, that this is already being automatically generated.
ok. have to get familiar with combining site.xml and book.xml. thank you!
--
Reinhard
Re: Integrating auto-generated docs
Posted by David Crossley <cr...@apache.org>.
Reinhard Poetz wrote:
>
> Some of us started with generating docs out of Java sources (sitemap
> components). I have to admit that I have no experience with this process
> but I would like to integrate these reference docs into the new
> documentation.
There is a rough explanation at
http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html
What you refer to as "reference docs" below, are what you see now
on the website at /userdocs/$component/
> The problem is, how can I configure Forrest to use an
> unknown number of docs and generate the menu *automatically*:
The Cocoon SitemapTask that generates those reference docs already
generates the book.xml files, which is the way Cocoon's forrest
uses to generate the navigation panels. Using book.xml is an old way
but it still works fine.
Anyway, my point is, that this is already being automatically generated.
--David
> +-+ new documentation
> +-- getting started
> +-- tutorial
> +-+ reference docs
> +-+ generators
> +-- File Generator
> +-- JXTemplateGenerator
> +-- ...
> +-- transformers
> +-- ...
>
> The only way I can think of is a hack using XML entities in site.xml and
> auto-generating the content of files, that these entities are pointing to.
> Or is there some better ("official supported") way of doing this?
>
> --
> Reinhard
Integrating auto-generated docs
Posted by Reinhard Poetz <re...@apache.org>.
Some of us started with generating docs out of Java sources (sitemap
components). I have to admit that I have no experience with this process but I
would like to integrate these reference docs into the new documentation. The
problem is, how can I configure Forrest to use an unknown number of docs and
generate the menu *automatically*:
+-+ new documentation
+-- getting started
+-- tutorial
+-+ reference docs
+-+ generators
+-- File Generator
+-- JXTemplateGenerator
+-- ...
+-- transformers
+-- ...
The only way I can think of is a hack using XML entities in site.xml and
auto-generating the content of files, that these entities are pointing to. Or is
there some better ("official supported") way of doing this?
--
Reinhard
Re: Remove current docs in trunk
Posted by Reinhard Poetz <re...@apache.org>.
David Crossley wrote:
> Reinhard Poetz wrote:
>
>>David Crossley wrote:
>>
>>>Reinhard Poetz wrote:
>>
<snip/>
>>Is a Forrest 0.6.1
>>release, that contains all necessary changes, possible?
>
>
> Yes, we could do that. So far, we have added a few things to help
> with the integration of forrest into the Cocoon build system.
> There may be more changes required, so i would really appreciate
> the help of Ant build experts to solve the problems early.
As soon as those problems are solved, a patch release of Forrest would be nice.
>
>>For now I can live without having the docs build integrated into the global
>>Cocoon build.
>
>
> Not quite sure what you mean. That is the way we use Forrest,
> calling its ant targets from the global Cocoon build.
>
> We run 'build docs' which prepares some other documentation,
> such as the installing/jars.xml and the sitemap component docs,
> then call forrest.
>
> Perhaps you mean that, as a workaround, we can run 'build docs'
> let it fail, then run 'forrest' in the top-level cocoon directory.
Yep. Until the Ant problems are solved, people can simply use "forrest".
--
Reinhard
Re: Remove current docs in trunk
Posted by David Crossley <cr...@apache.org>.
Reinhard Poetz wrote:
> David Crossley wrote:
> >Reinhard Poetz wrote:
> [snip]
> >>and set up the sekelton of new ones using Forrest 0.6.
> >
> >The Cocoon build system needs some work to enable that.
> >There are issues with clashes of Ant target names, e.g. webapp
> >and variable names, e.g. $version.
> >
> >Use the forrest_06_branch rather than the 0.6 release.
> >There are some changes to help with the above issue.
> >The other option is to use the current Forrest trunk.
> >... not sure what to recommend.
> >
> >Anyway, i will commit my changes so far to get forrest-0.6
> >closer to working.
>
> I'd rather avoid using a non-released Forrest version because this makes it
> easier for more users to join this documentation effort.
I agree' lets use the forrest_06_branch.
> Is a Forrest 0.6.1
> release, that contains all necessary changes, possible?
Yes, we could do that. So far, we have added a few things to help
with the integration of forrest into the Cocoon build system.
There may be more changes required, so i would really appreciate
the help of Ant build experts to solve the problems early.
> For now I can live without having the docs build integrated into the global
> Cocoon build.
Not quite sure what you mean. That is the way we use Forrest,
calling its ant targets from the global Cocoon build.
We run 'build docs' which prepares some other documentation,
such as the installing/jars.xml and the sitemap component docs,
then call forrest.
Perhaps you mean that, as a workaround, we can run 'build docs'
let it fail, then run 'forrest' in the top-level cocoon directory.
--David
Re: Remove current docs in trunk
Posted by Reinhard Poetz <re...@apache.org>.
David Crossley wrote:
> Reinhard Poetz wrote:
>
>>I propose to remove the docs in trunk. I don't think they are syncronized
>>with 2.1 and IMO there is no reasons to have them twice. It's also a chance
>>to rewrite and restructure our documentation.
>
>
> Careful. They are *not* synchronised.
Thank you for checking this!
We will lose edits that people
> have only made to the 2.2 docs and not made the same edits to the 2.1 docs.
> Or the changes are prehaps only relevant to cocoon-2.2
>
> I did a quick analysis ...
>
> diff -rq cocoon/src/documentation cocoon-2_1_X/src/documentation \
> | grep -v "\.svn" | wc -l
> ... only 47 files differ, so the job is not too big.
>
> There are some docs only in 2.1 and no new docs
> only in 2.2 trunk, so that aspect is fine.
>
> diff -r -b -x "\.svn" \
> cocoon/src/documentation cocoon-2_1_X/src/documentation \
>
>>docs-diff.txt
>
>
> The main differences ...
> * Composable => Serviceable (2.2 has the changes)
> * Some other document changes need sync, e.g. image-reader.xml
I added another column "2.1-2.2 comparison" at the wiki page where document
reviewer can describe the differences.
>
>>At http://wiki.apache.org/cocoon/22NewDocuments you find a list of all
>>documents in 2.1. Using this list we can move each document selectivly over
>>to trunk.
>>
>>If anybody objects I will remove the old docs in trunk on Sunday
>
>
> See above.
Ok. So I won't remove the docs for the first. Maybe somebody can build the
2.2-docs as Nicola suggested (the skin that produces plain HTML) and put them on
some public web space.
>>and set up the sekelton of new ones using Forrest 0.6.
>
>
> The Cocoon build system needs some work to enable that.
> There are issues with clashes of Ant target names, e.g. webapp
> and variable names, e.g. $version.
>
> Use the forrest_06_branch rather than the 0.6 release.
> There are some changes to help with the above issue.
> The other option is to use the current Forrest trunk.
> ... not sure what to recommend.
>
> Anyway, i will commit my changes so far to get forrest-0.6
> closer to working.
I'd rather avoid using a non-released Forrest version because this makes it
easier for more users to join this documentation effort. Is a Forrest 0.6.1
release, that contains all necessary changes, possible?
For now I can live without having the docs build integrated into the global
Cocoon build.
--
Reinhard
Re: trunk build docs using forrest_06_branch
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> David Crossley wrote:
> > The build of Cocoon's static docs in trunk is now using
> > the forrest_06_branch.
>
> Oh, i forgot to mention.
>
> cd /svn/asf/cocoon-trunk
> forrest run
> http://localhost:8888/
> edit docs on the filesystem and see the effect.
>
> There is one catch. Normally you would edit the xdocs/* at
> their source. However, Cocoon 'build docs' is pre-processing
> the xdocs and copying them to build/cocoon.../documents/xdocs/
> so that is where 'forrest run' is operating.
>
> For convenience you can temporarily change that in
> forrest.properties (project.xdocs-dir) to use the source docs
> directly.
Those instructions are still valid, but Forrest has been
disconnected by the 'build docs', so now you need to do
cd /svn/asf/cocoon-trunk
./build.sh docs
forrest
... see the result in build/cocoon-2.2.0-dev/site
--David
Re: trunk build docs using forrest_06_branch
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> The build of Cocoon's static docs in trunk is now using
> the forrest_06_branch.
Oh, i forgot to mention.
cd /svn/asf/cocoon-trunk
forrest run
http://localhost:8888/
edit docs on the filesystem and see the effect.
There is one catch. Normally you would edit the xdocs/* at
their source. However, Cocoon 'build docs' is pre-processing
the xdocs and copying them to build/cocoon.../documents/xdocs/
so that is where 'forrest run' is operating.
For convenience you can temporarily change that in
forrest.properties (project.xdocs-dir) to use the source docs
directly.
--David
trunk build docs using forrest_06_branch (Was: Remove current docs in trunk)
Posted by David Crossley <cr...@apache.org>.
The build of Cocoon's static docs in trunk is now using
the forrest_06_branch.
svn co http://svn.apache.org/repos/asf/forrest/branches/forrest_06_branch
cd forrest_06_branch
./build.sh
export FORREST_HOME=`pwd`/src/core
export PATH=$PATH:$FORREST_HOME/bin
cd /usr/local/svn/cocoon-trunk
./build docs
... and see the result in build/cocoon-2.2.0-dev/site/
(Edit forrest.properties first to disable xml validation of xdocs
as there is a strange problem with xml entities being injected
into some of the xdocs which contain tab-characters in their source,
maybe by Cocoon's SitemapTask.)
The 'build docs' uses the new default skin called "pelt" which uses
CSS rather than the old skin which used html tables for layout.
The colours, heading style, etc. can be tweaked in the
src/documentation/skinconf.xml
If there are no objections, then in the new year i will upgrade
the cocoon-2_1_X branch and the cocoon-site top-level to both
use forrest-0.6 too.
--David
David Crossley wrote:
> David Crossley wrote:
> > Reinhard Poetz wrote:
> > [snip]
> > > and set up the sekelton of new ones using Forrest 0.6.
> >
> > The Cocoon build system needs some work to enable that.
> > There are issues with clashes of Ant target names, e.g. webapp
> > and variable names, e.g. $version.
> >
> > Use the forrest_06_branch rather than the 0.6 release.
> > There are some changes to help with the above issue.
> > The other option is to use the current Forrest trunk.
> > ... not sure what to recommend.
> >
> > Anyway, i will commit my changes so far to get forrest-0.6
> > closer to working.
>
> I committed those changes to use forrest_06_branch.
> There are changes to skinconf.xml which can come later.
>
> However, './build.sh docs' still has some problems.
> I am no Ant build expert, so could use some help.
> It seems to complain about using the wrong Ant or missing
> jars or something.
>
> The whole section of the Cocoon build where it calls forrest
> could be tidied up later, as it seems overly complex.
> Anyway, at the moment i just want to get it to run forrest
> then we can come back and tidy the rest of it up.
>
> --David
Re: Remove current docs in trunk
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> Reinhard Poetz wrote:
> [snip]
> > and set up the sekelton of new ones using Forrest 0.6.
>
> The Cocoon build system needs some work to enable that.
> There are issues with clashes of Ant target names, e.g. webapp
> and variable names, e.g. $version.
>
> Use the forrest_06_branch rather than the 0.6 release.
> There are some changes to help with the above issue.
> The other option is to use the current Forrest trunk.
> ... not sure what to recommend.
>
> Anyway, i will commit my changes so far to get forrest-0.6
> closer to working.
I committed those changes to use forrest_06_branch.
There are changes to skinconf.xml which can come later.
However, './build.sh docs' still has some problems.
I am no Ant build expert, so could use some help.
It seems to complain about using the wrong Ant or missing
jars or something.
The whole section of the Cocoon build where it calls forrest
could be tidied up later, as it seems overly complex.
Anyway, at the moment i just want to get it to run forrest
then we can come back and tidy the rest of it up.
--David
Re: Remove current docs in trunk
Posted by David Crossley <cr...@apache.org>.
Reinhard Poetz wrote:
>
> I propose to remove the docs in trunk. I don't think they are syncronized
> with 2.1 and IMO there is no reasons to have them twice. It's also a chance
> to rewrite and restructure our documentation.
Careful. They are *not* synchronised. We will lose edits that people
have only made to the 2.2 docs and not made the same edits to the 2.1 docs.
Or the changes are prehaps only relevant to cocoon-2.2
I did a quick analysis ...
diff -rq cocoon/src/documentation cocoon-2_1_X/src/documentation \
| grep -v "\.svn" | wc -l
... only 47 files differ, so the job is not too big.
There are some docs only in 2.1 and no new docs
only in 2.2 trunk, so that aspect is fine.
diff -r -b -x "\.svn" \
cocoon/src/documentation cocoon-2_1_X/src/documentation \
> docs-diff.txt
The main differences ...
* Composable => Serviceable (2.2 has the changes)
* Some other document changes need sync, e.g. image-reader.xml
> At http://wiki.apache.org/cocoon/22NewDocuments you find a list of all
> documents in 2.1. Using this list we can move each document selectivly over
> to trunk.
>
> If anybody objects I will remove the old docs in trunk on Sunday
See above.
> and set up the sekelton of new ones using Forrest 0.6.
The Cocoon build system needs some work to enable that.
There are issues with clashes of Ant target names, e.g. webapp
and variable names, e.g. $version.
Use the forrest_06_branch rather than the 0.6 release.
There are some changes to help with the above issue.
The other option is to use the current Forrest trunk.
... not sure what to recommend.
Anyway, i will commit my changes so far to get forrest-0.6
closer to working.
--David
> One question to the Forrest specialists: What is a future-proof document
> type that can be edited with a *common* WYSIWIG editor like the HTML editor
> that comes with Mozilla and that works with Forrest 0.6?
>
> --
> Reinhard
Re: Remove current docs in trunk
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Reinhard Poetz wrote:
...
> One question to the Forrest specialists: What is a future-proof document
> type that can be edited with a *common* WYSIWIG editor like the HTML
> editor that comes with Mozilla and that works with Forrest 0.6?
Plain HTML.
We pass it through jtidy before using it.
Also, there is a special skin called plain-dev. If you tell forrest to
use that skin, it outputs all the site in plain html, that can be used
instead of the original formats as the input format. I used it to
convert the Incubator docs to html.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------