Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: forrest-dev@xml.apache.org
Date: Sun, 6 Jul 2003 12:11:39 +1000
From: Jeff Turner <jefft@apache.org>
To: forrest-dev@xml.apache.org
Subject: Re: a few more newbie questions
Message-ID: <20030706021139.GD672@expresso.localdomain>
Mail-Followup-To: forrest-dev@xml.apache.org
References: <Pine.LNX.4.44.0307051707430.21443-100000@localhost.localdomain>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <Pine.LNX.4.44.0307051707430.21443-100000@localhost.localdomain>
User-Agent: Mutt/1.5.4i

On Sat, Jul 05, 2003 at 05:24:50PM -0400, Robert P. J. Day wrote:
> 
> 1) as i'm still getting used to the file and directory structure
>    of a newly-seeded forrest project, it's sometimes difficult
>    to remember which file to look at to configure a particular
>    feature.  there's the top-level forrest.properties and
>    statux.xml files i've checked out so far, and further down,
>    there's the directories content, resources and skins, and
>    under skins we have skinconf.xml and ... whew.

Here's a bit of an overview:

There are only two 'Forrest' configuration files:

 - forrest.properties configures Forrest itself (forrest.* properties)
   and some aspects of the project (project.* properties).
 - src/documentation/skinconf.xml: This configures the current skin.

status.xml is really 'content', and can be removed if you don't need
changes/todo pages.

In src/documentation/, you'll find:

 - content/xdocs/, containing XML content (will be transformed)
 - content/{* - xdocs}, containing content that is copied across as-is
   (optional)
 - resources/images/, containing images
 - resources/{* - images}, containing genuine 'resources' like
   stylesheets, XML DTDs, grammars etc (optional).
 - skins/, containing any custom project skins (optional).
 - *.xmap, overridden sitemap files (optional)

The main bit of cruft is that images are in 'resources', not 'content'.

>    i realize i can, if i want, simplify things via forrest.properties,
>    but i'm loathe to do that until i understand the rationale
>    for the current layout.  is there, somewhere, an explanation
>    for this layout?  i suspect it's just because i don't know
>    enough about what i can do with forrest that i don't appreciate
>    the hierarchy.  yet.

In the next version of Forrest we do hope to simplify things a bit.

> 2) what's happens if you seed an already populated directory?
>    from a previous posting, there are some changes in the CVS
>    tree.  so what if i download the CVS tree, then go to the
>    top of my current project, and type "forrest seed".  the
>    idea would be to overwrite any older files with the newer
>    ones but, of course, i'd want to preserve any that i'd already
>    modified.

There may be a bit of understanding here.  There is (usually) nothing in
your site that ties it to a specific Forrest version.  So there's no need
to re-run 'forrest seed' when a new version of Forrest comes along.

Anyway, 'forrest seed' won't run if it detects that the directory is
already populated, to stop people overwriting their work.  There is an
option to 'force' things if you really want to.

>    what's the advice on applying a newer CVS download to an
>    existing project?  or does that question make any sense?
>    and am i just asking for trouble?

Have you overridden any sitemap files?  Do you have any
src/documentation/*.xmap files?

If not, you shouldn't need to do anything; just run 'forrest' (or better
yet, 'forrest run') and the new Forrest should build your old site.

> 3) is there an aesthetic reason for the tabs to be, by default,
>    on the right hand side for the avalon-tigris skin?  it seems a
>    bit odd, and inconsistent with the other default skins, but
>    that's just nitpicking.

The Avalon people wrote that skin, so I don't know.  Our most tweakable
skin is currently 'forrest-css'.


--Jeff


> more later.
> 
> rday 
> 
> --
> 
> Robert P. J. Day
> Eno River Technologies
> Unix, Linux and Open Source training
> Waterloo, Ontario
> 
> www.enoriver.com
>