You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Jeff Turner <je...@apache.org> on 2003/03/23 10:23:57 UTC
[Proposal] Use CVS Forrest, Forrestbot for docs
Hi,
If you:
- Fetch the latest CVS Forrest, or to be safe:
cvs up -D "2003-03-23 07:02:00 GMT"
- Go to src/documentation/, and rename sitemap.xmap.forrest05 to
sitemap.xmap
Then typing 'forrest' produces this site, without errors:
http://cvs.apache.org/~jefft/cocoon/site/
(I've left out the PDFs as they would take forever to upload.)
I've also added Cocoon to the Forrestbot run, regenerating every 4 hours:
http://forrestbot.cocoondev.org/sites/cocoon-site/index.html
However as the Forrestbot doesn't provide an opportunity to copy
sitemap.xmap.forrest05 to sitemap.xmap, the FAQs and some .txt links are
broken.
So how about we:
- Rename sitemap.xmap.forrest05 to sitemap.xmap in CVS, thus making the
Forrestbot output "committable".
- (optional) Fix the Cocoon 'build docs' target to read its sitemap from
another file, so the old doc generation process still works
- Switch on Forrestbot's commit facility, so any committer can
regenerate and commit the updated HTML/PDF from the web interface.
This way, people doing serious doc generation can obtain a Forrest
snapshot, and everyone else can rely on the Forresbot to view updates
(updates can be triggered manually), and potentially commit the results.
Sound decent?
--Jeff
Re: [Proposal] Use CVS Forrest, Forrestbot for docs (Forrest CVS tag)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Dimanche, 23 mars 2003, à 15:00 Europe/Zurich, Jeff Turner a écrit :
> ...
> We could easily put up a snapshot for people to download, and have a
> "rolling tag" in CVS, marking the version of Forrest suitable for
> Cocoon.
> The situation to avoid is where various committers use various versions
> of Forrest, with varying results.
+1 on this, something like a COCOON_DOCS_2_1 tag set on the Forrest CVS.
I think the tag name should change with each Cocoon release so as to be
able to regenerate the docs of old Cocoon releases if needed.
Requiring Cocoon to use only released versions of Forrest would be too
limitating IMHO. I know we shouldn't be "building on sand* but due to
the cyclic dependency between Cocoon and Forrest we cannot have both
waiting on each other's release.
-Bertrand
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Jeff Turner <je...@apache.org>.
On Sun, Mar 23, 2003 at 12:49:51PM +0000, Andrew Savory wrote:
>
>
> On Sun, 23 Mar 2003, Jeff Turner wrote:
>
> > - Fetch the latest CVS Forrest, or to be safe:
> > cvs up -D "2003-03-23 07:02:00 GMT"
> > - Go to src/documentation/, and rename sitemap.xmap.forrest05 to
> > sitemap.xmap
>
> <snip lots of cool stuff>
>
> The only problem I see is Stefano's suggestion that we use only "released"
> code within Cocoon. I guess that should apply to documentation generation
> too. Any chance Forrest "2003-03-23 07:02:00 GMT" could be rushed out the
> door as a release? ;-)
We could easily put up a snapshot for people to download, and have a
"rolling tag" in CVS, marking the version of Forrest suitable for Cocoon.
The situation to avoid is where various committers use various versions
of Forrest, with varying results.
--Jeff
> Andrew.
>
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Diana Shannon <sh...@apache.org>.
On Sunday, March 23, 2003, at 07:49 AM, Andrew Savory wrote:
> The only problem I see is Stefano's suggestion that we use only
> "released"
> code within Cocoon. I guess that should apply to documentation
> generation
> too. Any chance Forrest "2003-03-23 07:02:00 GMT" could be rushed out
> the
> door as a release? ;-)
FYI: once we update our doc-v10 files, we won't need a Forrest 0.5.
Diana
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Andrew Savory <an...@luminas.co.uk>.
On Sun, 23 Mar 2003, Jeff Turner wrote:
> - Fetch the latest CVS Forrest, or to be safe:
> cvs up -D "2003-03-23 07:02:00 GMT"
> - Go to src/documentation/, and rename sitemap.xmap.forrest05 to
> sitemap.xmap
<snip lots of cool stuff>
The only problem I see is Stefano's suggestion that we use only "released"
code within Cocoon. I guess that should apply to documentation generation
too. Any chance Forrest "2003-03-23 07:02:00 GMT" could be rushed out the
door as a release? ;-)
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Jeff Turner wrote:
<snip/>
>
> I've also added Cocoon to the Forrestbot run, regenerating every 4 hours:
>
> http://forrestbot.cocoondev.org/sites/cocoon-site/index.html
Brilliant ... run Forrest, run.
> However as the Forrestbot doesn't provide an opportunity to copy
> sitemap.xmap.forrest05 to sitemap.xmap, the FAQs and some .txt links are
> broken.
>
> So how about we:
> - Rename sitemap.xmap.forrest05 to sitemap.xmap in CVS, thus making the
> Forrestbot output "committable".
> - (optional) Fix the Cocoon 'build docs' target to read its sitemap from
> another file, so the old doc generation process still works
I think that this is a must. Step by step. Cocoon can then
continue to build its own docs as well. Next we can move
Cocoon to using document-v11 DTD and stylesheets.
> - Switch on Forrestbot's commit facility, so any committer can
> regenerate and commit the updated HTML/PDF from the web interface.
That would finally give us quick turnaround to
publish the website. That is a milestone. Of course
we have a bit of polishing to do yet, but that is why
we have the staging server at cocoondev.org
> This way, people doing serious doc generation can obtain a Forrest
> snapshot, and everyone else can rely on the Forresbot to view updates
> (updates can be triggered manually), and potentially commit the results.
Yes i think that this is the simple build solution that
we are looking for. Cocoon can still build its own docs
via the webapp etc. and even apply its own style (or sync
with Forrest) and Forrest can also build Cocoon docs.
> Sound decent?
Yes. Thanks Jeff for cutting through with such brilliant
solutions and thanks to all of us for getting this far.
--David
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Jeff Turner wrote:
> Diana Shannon wrote:
> > Jeff Turner wrote:
> > >
> > >Yes, this is certainly something Forrest should tackle. I have a
> > >half-written RT on an implementation somewhere.. Right now though, I
> > >just want to establish what functionality the old doc system provides
> > >that Forrest doesn't. Sounds like FAQs and jars.html is all?
It does not work with Cocoon's webapp or 'build docs' either.
I think that there are two reasons for the missing jars.html
Since the recent build re-factoring, the check-jars target
is not integrated into the build. The target does still work
and will generate the jars.xml table for the core jars.
It looks like it needs some modifications to handle the
jars in blocks too.
I have listed it as an issue in the Cocoon todo.xml file.
But it is still an issue for Forrest because it is generated
only via Cocoon's normal build.
--David
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Jeff Turner <je...@apache.org>.
On Sun, Mar 23, 2003 at 10:30:15AM -0500, Diana Shannon wrote:
>
> On Sunday, March 23, 2003, at 10:21 AM, Jeff Turner wrote:
> >
> >Yes, this is certainly something Forrest should tackle. I have a
> >half-written RT on an implementation somewhere.. Right now though, I
> >just want to establish what functionality the old doc system provides
> >that Forrest doesn't. Sounds like FAQs and jars.html is all?
>
> No.
>
> Docs has its own todo list
> http://cvs.apache.org/~jefft/cocoon/site/plan/todo-doc.html
>
> Docs has its own changes list
> http://cvs.apache.org/~jefft/cocoon/site/plan/changes-doc.html
Both fixed:
http://forrestbot.cocoondev.org/sites/cocoon-site/plan/changes-doc.html
http://forrestbot.cocoondev.org/sites/cocoon-site/plan/todo-doc.html
> We have a TOC page (perhaps obsolete with all Forrest offers)
> http://xml.apache.org/cocoon/doclist.html
Not obsolete - I'll add it to sitemap.xmap.forrest05 tomorrow.
It looks like the replacement of @tokens@ is the only outstanding issue.
If anyone spots anything else, please report..
--Jeff
>
> Diana
>
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Diana Shannon <sh...@apache.org>.
On Sunday, March 23, 2003, at 10:21 AM, Jeff Turner wrote:
>
> Yes, this is certainly something Forrest should tackle. I have a
> half-written RT on an implementation somewhere.. Right now though, I
> just want to establish what functionality the old doc system provides
> that Forrest doesn't. Sounds like FAQs and jars.html is all?
No.
Docs has its own todo list
http://cvs.apache.org/~jefft/cocoon/site/plan/todo-doc.html
Docs has its own changes list
http://cvs.apache.org/~jefft/cocoon/site/plan/changes-doc.html
We have a TOC page (perhaps obsolete with all Forrest offers)
http://xml.apache.org/cocoon/doclist.html
Diana
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Jeff Turner <je...@apache.org>.
On Sun, Mar 23, 2003 at 09:54:53AM -0500, Diana Shannon wrote:
>
> On Sunday, March 23, 2003, at 08:49 AM, Jeff Turner wrote:
>
> >>
> >>>- Switch on Forrestbot's commit facility, so any committer can
> >>> regenerate and commit the updated HTML/PDF from the web interface.
> >>
> >>+100 -- but we have a bit to do (jars pages, faqs, and redirects)
> >>before
> >>it becomes the web site.
> >
> >Whereabouts does Cocoon need redirects? Should redirects be done with
> >.htaccess files or <meta> refreshes? If .htaccess, they could exist
> >in xml-site without Forrest interfering.
>
> I think most, though not all, redirects should be committer-
> configurable/accessible. That is, when doc URI space changes, the person
> introducing the change needs the ability to indicate a redirect is
> required. This has happened a lot over the past year.
>
> Isn't a single redirect config xml file (with old URI and new URI) that
> is parsed to create a single .htaccess file more efficient/maintainable
> than individual pages with <meta> refreshes?
Yes, this is certainly something Forrest should tackle. I have a
half-written RT on an implementation somewhere.. Right now though, I
just want to establish what functionality the old doc system provides
that Forrest doesn't. Sounds like FAQs and jars.html is all?
--Jeff
>
> Diana
>
>
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Diana Shannon <sh...@apache.org>.
On Sunday, March 23, 2003, at 08:49 AM, Jeff Turner wrote:
>>
>>> - Switch on Forrestbot's commit facility, so any committer can
>>> regenerate and commit the updated HTML/PDF from the web interface.
>>
>> +100 -- but we have a bit to do (jars pages, faqs, and redirects)
>> before
>> it becomes the web site.
>
> Whereabouts does Cocoon need redirects? Should redirects be done with
> .htaccess
> files or <meta> refreshes? If .htaccess, they could exist in xml-site
> without Forrest interfering.
I think most, though not all, redirects should be committer-
configurable/accessible. That is, when doc URI space changes, the person
introducing the change needs the ability to indicate a redirect is
required. This has happened a lot over the past year.
Isn't a single redirect config xml file (with old URI and new URI) that
is parsed to create a single .htaccess file more efficient/maintainable
than individual pages with <meta> refreshes?
Diana
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Jeff Turner <je...@apache.org>.
On Sun, Mar 23, 2003 at 07:25:53AM -0500, Diana Shannon wrote:
>
> On Sunday, March 23, 2003, at 04:23 AM, Jeff Turner wrote:
>
> <snip />
> >
> >I've also added Cocoon to the Forrestbot run, regenerating every 4
> >hours:
> >
> >http://forrestbot.cocoondev.org/sites/cocoon-site/index.html
>
> Freedom!!
:)
> >However as the Forrestbot doesn't provide an opportunity to copy
> >sitemap.xmap.forrest05 to sitemap.xmap, the FAQs and some .txt links are
> >broken.
> >
> >So how about we:
> > - Rename sitemap.xmap.forrest05 to sitemap.xmap in CVS, thus making the
> > Forrestbot output "committable".
>
> Why can't we have our own sitemap for Forrest-specific docs. Will a
> separate sitemap still work with forrestbot? If not, when? For example,
> the faqs and jars pages need their own custom matches which could be
> added in a snap. I can't see why we need to depend on the Forrest
> project for these additions.
Ah - I didn't notice the jars page is blank. Yes, projects can provide
their own sitemap, and Forrest (and the Forrestbot) will use them. The
sitemap.xmap.forrest05 file is a Forrest sitemap, modified to map faq/**
to the FAQ-handling subsitemap:
<map:match pattern="faq/**body-*.xml">
<map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
</map:match>
faq.xmap converts from faq-v10 to faq-v11 to document-v11 to HTML. In
Cocoon's case, it should be overridden to also apply
stylesheets/faqcommon.xsl
The jars.xml preprocessing is more tricky. In the short term, it would
be easy enough to write a jars2document.xsl stylesheet and apply it in
sitemap.xmap. Longer term, Forrest should perhaps add a facility for
calling Ant preprocessing targets. I'll take that up on forrest-dev.
Any other Cocoon-specific filetypes that I've missed?
> > - (optional) Fix the Cocoon 'build docs' target to read its sitemap
> >from
> > another file, so the old doc generation process still works
>
> This **must** continue to work until we've transitioned.
>
> > - Switch on Forrestbot's commit facility, so any committer can
> > regenerate and commit the updated HTML/PDF from the web interface.
>
> +100 -- but we have a bit to do (jars pages, faqs, and redirects) before
> it becomes the web site.
Whereabouts does Cocoon need redirects? Should redirects be done with .htaccess
files or <meta> refreshes? If .htaccess, they could exist in xml-site
without Forrest interfering.
--Jeff
> Diana
>
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Dimanche, 23 mars 2003, à 10:23 Europe/Zurich, Jeff Turner a écrit :
> Hi,
>
> If you:
>
> - Fetch the latest CVS Forrest, or to be safe:
> cvs up -D "2003-03-23 07:02:00 GMT"
> - Go to src/documentation/, and rename sitemap.xmap.forrest05 to
> sitemap.xmap
>
> Then typing 'forrest' produces this site, without errors:
>
> http://cvs.apache.org/~jefft/cocoon/site/
wow!
> ...Sound decent?
just great.
Making the website update quicker and easier is a great step forward,
thanks!
-Bertrand
Re: [Proposal] Use CVS Forrest, Forrestbot for docs
Posted by Diana Shannon <sh...@apache.org>.
On Sunday, March 23, 2003, at 04:23 AM, Jeff Turner wrote:
<snip />
>
> I've also added Cocoon to the Forrestbot run, regenerating every 4
> hours:
>
> http://forrestbot.cocoondev.org/sites/cocoon-site/index.html
Freedom!!
> However as the Forrestbot doesn't provide an opportunity to copy
> sitemap.xmap.forrest05 to sitemap.xmap, the FAQs and some .txt links are
> broken.
>
> So how about we:
> - Rename sitemap.xmap.forrest05 to sitemap.xmap in CVS, thus making the
> Forrestbot output "committable".
Why can't we have our own sitemap for Forrest-specific docs. Will a
separate sitemap still work with forrestbot? If not, when? For example,
the faqs and jars pages need their own custom matches which could be
added in a snap. I can't see why we need to depend on the Forrest
project for these additions.
> - (optional) Fix the Cocoon 'build docs' target to read its sitemap
> from
> another file, so the old doc generation process still works
This **must** continue to work until we've transitioned.
> - Switch on Forrestbot's commit facility, so any committer can
> regenerate and commit the updated HTML/PDF from the web interface.
+100 -- but we have a bit to do (jars pages, faqs, and redirects) before
it becomes the web site.
> This way, people doing serious doc generation can obtain a Forrest
> snapshot, and everyone else can rely on the Forresbot to view updates
> (updates can be triggered manually), and potentially commit the results.
>
> Sound decent?
Thanks Jeff and David.
Diana