You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by David Crossley <cr...@indexgeo.com.au> on 2002/08/18 10:09:13 UTC
Re: [PATCH] acorn.xml: bootstrapping new projects
Thanks for the "acorn" idea (love the metaphor) and the patch.
We will look into it ASAP. I have it running on my system.
More below ...
Jeff Turner wrote:
> Marc Portier wrote:
> ...
> > On this very topic, my analysis at this stage would be:
> > There is currently too much coupling between the forrest
> > build.xml and the generation of the docs.
>
> Yep :) There's no separation between "building Forrest" and "building a
> website's docs with Forrest". Consequently, anyone wanting to use Forrest
> has to first dig through build.xml to separate the forresty bits from the
> build system.
Did you see the document "forrestbot.html"? I did not need to
tweak anything in build.xml ... the bot works beautifully for me.
While i established it on my system today, i added a new document
as a concise overview.
You are right - the separation between "Forrest" and "Forrest's job"
has been a hard one to make clear. Your comments have spurred more
action there, thanks.
Your acorn idea is a good one that seems to complement the
"forrestbot" and would assist Forrest uptake. We will await
a little discussion during the week to build upon it.
--David
> > The correct steps would be
> > - decide on forrest in your project
> > - get forrest from cvs
> > - build forrest (so the main build target of forrest should
> > not build its own docs!)
> > - have your project refer to forrest for building YOUR docs
> > The start with forrest and modify to your own project is not
> > an option to get you started, it is pretty much a
> > requirement to ever get somewhere.
>
> I agree.
>
> In penance for wrongfully maligning a worthy project, I went ahead and
> implemented a script that builds the docs with Forrest in whichever
> project it's part of. It uses xml-forrest as a static resource, eg in
> /usr/local/forrest, that you download and build once. Forrest's 16mb is
> far too much to duplicate across multiple projects.
>
> It's called acorn.xml to suggest the idea of something that can bootstrap
> a 'forrest'. Acorns have to grow wherever they're dropped. Thus if you
> run acorn.xml in an empty directory, it creates a skeleton Forrest layout
> and builds that. If the directory contains an existing Forrest doc
> structure (eg it's in xml-forrest/ itself), it will build those docs.
>
> The script will also (optionally) download Forrest from CVS, and build
> it. The idea is that you literally don't need anything more than Ant and
> acorn.xml to start using Forrest. Copy it somewhere, define
> 'forrest.home' to /usr/local/forrest or wherever, and type 'ant -f
> acorn.xml', and a while later you'll have Forrest installed, built, a new
> doc structure created and generated docs for that project.
>
> --Jeff
Re: using ForrestBot (SOLVED)
Posted by David Crossley <cr...@indexgeo.com.au>.
Jeff Turner wrote:
<snip/>
> > $ vi acornbot.conf.xml
> > slide in:
> > <?xml version="1.0" encoding="ISO-8859-1"?>
> > <forrest-config>
> > <defaults />
> > <project name="acorn-test">
> > <prepare>
> > <skin name="forrest-site"/>
> > </prepare>
> > <get-src type="local-copy">
> > <project-dir name="../acorn-test" />
> ^^^^^^^^^^^^
>
> That was the line I was missing. Added it and everything is now fine.
I did not need that line because i had a <defaults>
section with <project-dir name="." />
I will tweak the your-project.xml doc to have a complete
minimal example, rather than just the <project> snippet.
--David
> Attached is a patch for your-project.xml.
>
> Thanks for your and David's help :)
No problem.
--David
Re: using ForrestBot (SOLVED)
Posted by Jeff Turner <je...@apache.org>.
On Mon, Aug 19, 2002 at 05:12:14PM +0200, Marc Portier wrote:
> Jeff,
>
> not fully understanding what you see (and missing the tgz)
Oops, forgot to attach. But..
...
> $ vi acornbot.conf.xml
> slide in:
> <?xml version="1.0" encoding="ISO-8859-1"?>
> <forrest-config>
> <defaults />
> <project name="acorn-test">
> <prepare>
> <skin name="forrest-site"/>
> </prepare>
> <get-src type="local-copy">
> <project-dir name="../acorn-test" />
^^^^^^^^^^^^
That was the line I was missing. Added it and everything is now fine.
Attached is a patch for your-project.xml.
Thanks for your and David's help :)
--Jeff
RE: using ForrestBot (Was: [PATCH] acorn.xml: bootstrapping new projects)
Posted by Marc Portier <mp...@outerthought.org>.
Jeff,
not fully understanding what you see (and missing the tgz)
I just tried this from scratch:
(assuming current working dir ==
root-of-your-xml-forrest-cvs-sandbox)
$ cvs update -dP
$ mkdir ../acorn-test
$ pushd ../acorn-test
$ cp [path-to-it]/acorn.xml .
$ ant -f acorn.xml -Dforrest.home=../xml-forrest
create-xdocs create-status
$ popd
$ vi acornbot.conf.xml
slide in:
<?xml version="1.0" encoding="ISO-8859-1"?>
<forrest-config>
<defaults />
<project name="acorn-test">
<prepare>
<skin name="forrest-site"/>
</prepare>
<get-src type="local-copy">
<project-dir name="../acorn-test" />
<content-dir name="../acorn-test/src/documentation"/>
</get-src>
<generate>
<debuglevel name="ERROR" />
</generate>
<deploy type="local-copy">
<destination name="../acorn-test/forrest-docs/" />
</deploy>
</project>
</forrest-config>
$ ./build.sh
bot -Dbot.forrestbot.xconf=acornbot.conf.xml -Dtemplate.echo
=true
and this works fine.
<snip />
trying to grasp what you tried:
>
> Aha.. hehe.. ahahaha.. Houston, you have a problem.. :)
>
> Are you using Forrest's docs in a different
> directory to test Forrestbot? Then
> it will be using files from xml-forrest/ and
> you'd never be able to tell the
> difference :)
>
naah,
we use forrestbot to build loads of other things:
50% from the list at
http://outerthought.net/forrest/live-sites.html
i.e. http://outerthought.net/ and http://www.xmlbelux.be/
are built using the bot...
so we _can_ tell the difference :-)
(and you see it _is_ used for other sites then
xml.apache.org, that one not even.)
> I used acorn.xml to generate a basic,
> known-to-build, doc setup. If I swap the
> acorn-generated content for
> xml-forrest/src/documentation, then it all builds
> fine with forrestbot.
>
as would the opposite, provided that you tell the bot where
to find the acorn-generated content
please check your-botconf.xml
(mind for gets-src.local-copy the content-dir is not
evaluated as relative to the project-dir, should it?)
if you can't find something wrong:
- run with -Dtemplate.echo=true
- attach the ./build/bot/work.[your-project-name].log and
the conf in your next message
HTH,
-marc=
Re: using ForrestBot (Was: [PATCH] acorn.xml: bootstrapping new projects)
Posted by Jeff Turner <je...@apache.org>.
Thanks for the helping debug this.
On Mon, Aug 19, 2002 at 02:04:18PM +1000, David Crossley wrote:
> Jeff Turner wrote:
> > David Crossley wrote:
> > ERROR 2002-08-18 20:55:57.978 [sitemap ] (): Error while processing pipeline at file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./sitemap.xmap:135:17
> > org.apache.cocoon.ProcessingException: Failed to execute pipeline.: org.apache.cocoon.ResourceNotFoundException: Resource not found.: org.apache.excalibur.source.SourceNotFoundException: Resource not found file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./content/xdocs/your-project.xml
...
>
> It sounds like some separate issues. Your ForrestBot is
> building the main Forrest project doco here.
Indeed it is (after examining build/bot/projects/...).
> When you copied the forrestbot.conf.xml to testproj.conf.xml
> did you remove the old <project>+ entries and put your own?
Yep.
> Another possibility - if /home/jeff/testproj/testproj.conf.xml
> path is wrong, then it will use $FORREST_HOME/forrestbot.conf.xml
> and build the main project doco.
It's correct:
jeff@expresso:~$ ls /home/jeff/testproj
acorn.xml src status.xml testproj.conf.xml
> Aha. I just noticed something that may be the cause.
> If you do not do a 'build clean' before running forrestbot
> then it just re-runs the previous build. So if you had
> done a plain './build.sh bot' then forrestbot would try to
> build the default Forrest doco. If you immediately follow
> that with building your own project:
> ./build.sh bot -Dbot.forrestbot.xconf=$HOME/yourproject.conf.xml
> then forrestbot does not build your project but repeats the
> default build.
That's good to know, but I was playing safe and doing 'rm -r build' between
builds anyway. Confirmed again today.
> Also, it seems that your xml-forrest CVS is not up-to-date.
> The doc your-project.html is certainly linked from changes.html
> and it should be there at xdocs/your-project.xml
> Does the normal "./build.sh clean docs" work for you?
Aha.. hehe.. ahahaha.. Houston, you have a problem.. :)
Are you using Forrest's docs in a different directory to test Forrestbot? Then
it will be using files from xml-forrest/ and you'd never be able to tell the
difference :)
I used acorn.xml to generate a basic, known-to-build, doc setup. If I swap the
acorn-generated content for xml-forrest/src/documentation, then it all builds
fine with forrestbot.
Attached is a .tgz of the context I'm trying to build with Forrestbot, that
should show up the problem.
--Jeff
> --David
>
RE: using ForrestBot (Was: [PATCH] acorn.xml: bootstrapping newprojects)
Posted by Marc Portier <mp...@outerthought.org>.
> -----Original Message-----
> From: David Crossley [mailto:crossley@indexgeo.com.au]
<snip />
> Aha. I just noticed something that may be the cause.
> If you do not do a 'build clean' before running forrestbot
> then it just re-runs the previous build. So if you had
> done a plain './build.sh bot' then forrestbot would try to
> build the default Forrest doco. If you immediately follow
> that with building your own project:
> ./build.sh
bot -Dbot.forrestbot.xconf=$HOME/yourproject.conf.xml
> then forrestbot does not build your project but repeats
the
> default build.
great observation, this is due to the fact that the bot-conf
is in fact basis for a real ant build file to be generated
the way we use this forrestbot this calls for the target
bot.conf2build to always removing the work.build.xml and
default.parameters.xml. This will ensure that the <style>
task will always generate a new one.
normal dependency checking inside the style task can fail in
this case:
edit conf1 and conf2 (timestamp0)
use bot on conf1 --> generates required build and paremeter
file (timestamp1)
use bot on conf2 --> style thinks that build and parameter
files do not need to be rebuilt (ts0 < ts1)
quick fix is to just always force generation of the required
files
fixing now...
-marc=
using ForrestBot (Was: [PATCH] acorn.xml: bootstrapping new
projects)
Posted by David Crossley <cr...@indexgeo.com.au>.
Jeff Turner wrote:
> David Crossley wrote:
> > Did you see the document "forrestbot.html"? I did not need to
> > tweak anything in build.xml ... the bot works beautifully for me.
> > While i established it on my system today, i added a new document
> > as a concise overview.
>
> I saw forrestbot, and thought it looked cool, but more relevant for when one
> wants to update a live website, rather than just build local project docs.
>
> Thanks for writing the overview. It's exactly this last 5% that people need.
> Probably I'm just doing something stupid, but it didn't work for me. I followed
> the instructions in your-project.xml, and when I ran:
>
> ./build.sh bot
> -Dbot.forrestbot.xconf=/home/jeff/testproj/testproj.conf.xml
> -Dtemplate.echo=true
>
> in my xml-forrest (clean build/)
>
> URI: changes.html
> getting links: . [broken link]--> images/group-logo.gif
> [broken link]--> images/project-logo.gif
> [broken link]--> images/add.jpg
> ERROR 2002-08-18 20:55:57.978 [sitemap ] (): Error while processing pipeline at file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./sitemap.xmap:135:17
> org.apache.cocoon.ProcessingException: Failed to execute pipeline.: org.apache.cocoon.ResourceNotFoundException: Resource not found.: org.apache.excalibur.source.SourceNotFoundException: Resource not found file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./content/xdocs/your-project.xml
>
> Which is bizarre, since your-project.xml certainly isn't mentioned anywhere in
> my test project. However, running just './build.sh bot' worked fine, so I'm
> sure it's something minor.
It sounds like some separate issues. Your ForrestBot is
building the main Forrest project doco here.
When you copied the forrestbot.conf.xml to testproj.conf.xml
did you remove the old <project>+ entries and put your own?
Another possibility - if /home/jeff/testproj/testproj.conf.xml
path is wrong, then it will use $FORREST_HOME/forrestbot.conf.xml
and build the main project doco.
Aha. I just noticed something that may be the cause.
If you do not do a 'build clean' before running forrestbot
then it just re-runs the previous build. So if you had
done a plain './build.sh bot' then forrestbot would try to
build the default Forrest doco. If you immediately follow
that with building your own project:
./build.sh bot -Dbot.forrestbot.xconf=$HOME/yourproject.conf.xml
then forrestbot does not build your project but repeats the
default build.
Also, it seems that your xml-forrest CVS is not up-to-date.
The doc your-project.html is certainly linked from changes.html
and it should be there at xdocs/your-project.xml
Does the normal "./build.sh clean docs" work for you?
--David
Re: [PATCH] acorn.xml: bootstrapping new projects
Posted by Jeff Turner <je...@apache.org>.
On Sun, Aug 18, 2002 at 06:09:13PM +1000, David Crossley wrote:
> Thanks for the "acorn" idea (love the metaphor) and the patch.
> We will look into it ASAP. I have it running on my system.
>
> More below ...
>
> Jeff Turner wrote:
> > Marc Portier wrote:
> > ...
> > > On this very topic, my analysis at this stage would be:
> > > There is currently too much coupling between the forrest
> > > build.xml and the generation of the docs.
> >
> > Yep :) There's no separation between "building Forrest" and "building a
> > website's docs with Forrest". Consequently, anyone wanting to use Forrest
> > has to first dig through build.xml to separate the forresty bits from the
> > build system.
>
> Did you see the document "forrestbot.html"? I did not need to
> tweak anything in build.xml ... the bot works beautifully for me.
> While i established it on my system today, i added a new document
> as a concise overview.
I saw forrestbot, and thought it looked cool, but more relevant for when one
wants to update a live website, rather than just build local project docs.
Thanks for writing the overview. It's exactly this last 5% that people need.
Probably I'm just doing something stupid, but it didn't work for me. I followed
the instructions in your-project.xml, and when I ran:
./build.sh bot
-Dbot.forrestbot.xconf=/home/jeff/testproj/testproj.conf.xml
-Dtemplate.echo=true
in my xml-forrest (clean build/)
URI: changes.html
getting links: . [broken link]--> images/group-logo.gif
[broken link]--> images/project-logo.gif
[broken link]--> images/add.jpg
ERROR 2002-08-18 20:55:57.978 [sitemap ] (): Error while processing pipeline at file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./sitemap.xmap:135:17
org.apache.cocoon.ProcessingException: Failed to execute pipeline.: org.apache.cocoon.ResourceNotFoundException: Resource not found.: org.apache.excalibur.source.SourceNotFoundException: Resource not found file:/old/home/jeff/homeoverflow/apache/xml/xml-forrest/build/bot/projects/myproj-local/context/./content/xdocs/your-project.xml
Which is bizarre, since your-project.xml certainly isn't mentioned anywhere in
my test project. However, running just './build.sh bot' worked fine, so I'm
sure it's something minor.
--Jeff
RE: [PATCH] acorn.xml: bootstrapping new projects
Posted by Marc Portier <mp...@outerthought.org>.
> -----Original Message-----
> From: David Crossley [mailto:crossley@indexgeo.com.au]
>
> Thanks for the "acorn" idea (love the metaphor)
> and the patch.
+1
> We will look into it ASAP. I have it running on my system.
>
me too.
<snip />
>
> Your acorn idea is a good one that seems to complement the
> "forrestbot" and would assist Forrest uptake. We
> will await
> a little discussion during the week to build upon it.
acorn sure fills a gap today, and as such should be in
there. (there is some possible confusion with the
forrestbot: the current advocated way, but documentation and
a future better design of the build should solve that)
acorn however is not (IMHO) sufficiently making the real
separation (as discussed) we need, so having this should not
take attention away from still making the build-redesign
that offers that.
acorn would still deserve a future inside forrest (IMHO
again) 1. it could evolve into some easy-install mechanism
for forrest. 2. the build-template idea should inspire one
of the real things forrest can do for you (next to building
your docs)
just my 2c.
-marc=