Fwd: simplifying the generation of Incubator website

[Leo Simons <ma...@leosimons.com>]

----- Forwarded message from David Crossley <cr...@apache.org> -----

From: David Crossley <cr...@apache.org>
Date: Fri, 4 Nov 2005 17:31:58 +1100
Subject: simplifying the generation of Incubator website
To: general@incubator.apache.org
Reply-To: general@incubator.apache.org
List-Id: <general.incubator.apache.org>

I would like to try again to make it easier to build the
Incubator website.

Next week i will ugrade the configuration to use the current
release of Forrest (Incubator is one behind). Along with
creating a better procedure document, might make it easier.

I also want to have a discussion about why we are using
Forrest and whether something else might be more relevant,
or if continuing with Forrest then how to improve.

First a digression about the content ...

The website could use a lot more instructions. Some
procedural documentation is incorrect, out-of-date,
misleading, non-existent. The current pages could also be
enhanced and corrected. 

The source content is in html format at "site-author"
directory. Please edit it and view the html document directly
in your web browser. Looks okay? Then do your normal svn
procedure 'svn diff, svn commit' etc. Done.

Later someone will build the documents with Forrest.
That is probably me, but can be any other committer with
Forrest installed.

Yes we would all love to have the better infrastructure
for generating, staging, and publishing all project sites
using whatever software they like. However that is not
happening yet. See the site-dev list.

                  ---oOo---

Now on to the issues with using Forrest.

Yes we know that it is a little cumbersome and needs to be
installed. I am concerned that this might be contributing
to the hold-up with editing the docs.

Not trying to make excuses, but Forrest is pre-1.0 so it
should be expected to be a little difficult. Anyway, lets
try to either find out what can be improved or look at using
something else.

Incubator started before i joined, so can someone tell what
was the reason for choosing Forrest. It is a publishing
framework, and perhaps the simple needs of Incubator do not
warrant its use.

One beauty is that the content can be edited as simple html
docs, rather than an xml format.

My guess about the stumbling block for some people is the
need to check the final result into svn. Also the need to
copy files from build/site into site-publish and then do 
svn add or svn remove files. I think that we can get
Cocoon to generate the files directly into site-publish
directory if that helps.

Another trouble is that for just changing one little document,
then Cocoon needs to generate everything. Sorry not much we
can do about that at this stage. There is a trick which i will
document. There is also "local forrestbot" which i will
explain after the upgrade.

Can people define any other issues? Probably best to keep
specific stuff until i have upgraded to 0.7 next week.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org


----- End forwarded message -----

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: simplifying the generation of Incubator website

[David Crossley <cr...@apache.org>]

Leo Simons wrote:
> David Crossley wrote:
> > 
> > My guess about the stumbling block for some people is the
> > need to check the final result into svn. Also the need to
> > copy files from build/site into site-publish and then do 
> > svn add or svn remove files. I think that we can get
> > Cocoon to generate the files directly into site-publish
> > directory if that helps.
> 
> This is not the stumbling block. Most people working on the site
> know how to use anakia just fine, which has pretty much the same
> workflow, except you type 'ant', not 'forrest site'.

Actually that is a big difference in workflow.
By default forrest will generate the docs into
the build/site directory. Following the message
that you quoted, i changed this default so that
it becomes the same a Anakia's workflow, i.e.
generate the docs directly into the "site-publish"
directory, i.e. overwite the docs that are under
svn control and then do 'svn diff; svn commit'.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: simplifying the generation of Incubator website

[Leo Simons <ma...@leosimons.com>]

I missed this originally...Noel told me to go respond anyway...

  http://mail-archives.apache.org/mod_mbox/incubator-general/200512.mbox/%3cNBBBJGEAGJAKLIDBKJOPOEOAFIAC.noel@devtech.com%3e

David Crossley wrote on Fri, 4 Nov 2005 17:31:58 +1100:
<snip/>
> Now on to the issues with using Forrest.
> 
> Yes we know that it is a little cumbersome and needs to be
> installed. I am concerned that this might be contributing
> to the hold-up with editing the docs.

I think so.

> Not trying to make excuses, but Forrest is pre-1.0 so it
> should be expected to be a little difficult. Anyway, lets
> try to either find out what can be improved or look at using
> something else.
> 
> Incubator started before i joined, so can someone tell what
> was the reason for choosing Forrest.

I think it came down to Nicola Ken doing the work and using
Forrest because well, he liked it. Eg:

  http://mail-archives.apache.org/mod_mbox/incubator-general/200210.mbox/browser

before that there was talk on the reorg@ list, which I think
I unsubscribed from before that talk happened.

> It is a publishing
> framework, and perhaps the simple needs of Incubator do not
> warrant its use.

It seems like that.

> One beauty is that the content can be edited as simple html
> docs, rather than an xml format.
> 
> My guess about the stumbling block for some people is the
> need to check the final result into svn. Also the need to
> copy files from build/site into site-publish and then do 
> svn add or svn remove files. I think that we can get
> Cocoon to generate the files directly into site-publish
> directory if that helps.

This is not the stumbling block. Most people working on the site
know how to use anakia just fine, which has pretty much the same
workflow, except you type 'ant', not 'forrest site'.

> Another trouble is that for just changing one little document,
> then Cocoon needs to generate everything. Sorry not much we
> can do about that at this stage. There is a trick which i will
> document. There is also "local forrestbot" which i will
> explain after the upgrade.
> 
> Can people define any other issues? Probably best to keep
> specific stuff until i have upgraded to 0.7 next week.

The answer to why people might not've responded was because it
says so right there to wait with that until some upgraded finishes.
Anyway, a little later some answers to that question were formulated
several times in this thread:

  http://mail-archives.apache.org/mod_mbox/incubator-general/200512.mbox/%3c20051227140218.GA60941@bali.sjc.webweaving.org%3e

I think this also clearly shows why people keep talking about forrest
on this list -- there's forrest developers asking for it.

- LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org