Searching Forrest-built documentation

- Technically, Forrest can be thought of as a - Cocoon distribution that has been stripped down - and optimized for people with simple site publishing needs. Central to - Cocoon, and hence Forrest, is the sitemap. The sitemap + Technically, Forrest can be thought of as a + Cocoon distribution that has been stripped + down and optimized for people with simple site publishing needs. Central + to Cocoon, and hence Forrest, is the sitemap. The sitemap defines the site's URI space (what pages are available), and how each page - is constructed. Understanding the sitemap is the key to understanding + is constructed. Understanding the sitemap is the key to understanding Forrest.

- This document provides an overview of the special sitemap which - is used at the core of Apache Forrest. + This document provides an overview of the special sitemap which is used at + the core of Apache Forrest.

sitemap.xmap	sitemap.xmap +	Primary sitemap file, which delegates responsibility for serving certain URIs to the others (technically called sub-sitemaps). More about the structure of this file later.

Output pipelines

To recap, we now have a *.xml pipeline defined for each - page in the site, emitting standardized XML. These pipeline definitions + page in the site, emitting standardized XML. These pipeline definitions are located in various *.xmap files, notably forrest.xmap

@@ -328,15 +337,17 @@

PDF output - PDF is now generated via the org.apache.forrest.plugin.output.pdf plugin. + PDF is now generated via the org.apache.forrest.plugin.output.pdf + plugin.

Easiest case first; PDFs don't require menus or headers, so we can simply transform our intermediate format into XSL:FO, and from there - to PDF. This is done by the following matcher in + to PDF. This is done by the following matcher in output.xmap from the pdf plugin ...

- + 2 3 @@ -347,7 +358,8 @@ 8 9 10 - ]]> + ]]> +

The first line uses a matching regexp to break the URL into directory (.*?) and filename @@ -359,14 +371,18 @@
and finally apply the document-to-fo.xsl stylesheet, to generate XSL:FO XML.

Lastly, we generate a PDF using the fo2pdf serializer.

+ Lastly, we generate a PDF using the fo2pdf serializer. +

HTML output -

Generating HTML pages is more complicated, because we have to merge +

+ Generating HTML pages is more complicated, because we have to merge the page body with a menu and tabs, and then add a header and footer. - Here is the *.html matcher in - sitemap.xmap ...

+ Here is the *.html matcher in sitemap.xmap + ... +

<map:match pattern="*.html"> <map:aggregate element="site"> @@ -383,9 +399,9 @@

So index.html is formed from aggregating body-index.html and - menu-index.html and - tab-index.html and then applying the - site-to-xhtml.xsl stylesheet to the result. + menu-index.html and + tab-index.html and then applying + the site-to-xhtml.xsl stylesheet to the result.

There is a nearly identical matcher for HTML files in subdirectories: @@ -414,8 +430,11 @@ Intermediate pipelines

Page body -

Here is the matcher which generates the page body:

- + Here is the matcher which generates the page body: +

+ + 2 3 @@ -427,32 +446,38 @@ 9 10 11 - ]]> + ]]> +

In our matcher pattern, {1} will be the directory (if any) and {2} will be the filename.
First, we obtain XML content from a source pipeline
-
We then apply a custom-written +
+ We then apply a custom-written IdGeneratorTransformer, which ensures that every - <section> has an "id" attribute if one is not supplied, by generating one from the - <title> if necessary. For example, <idgen> will - transform:
+ <section> has an "id" attribute if one is not supplied, by + generating one from the <title> if necessary. For example, + <idgen> will transform: +
<section> <title>How to boil eggs</title> ... -
into:
+
+ into: +
<section id="How+to+boil+eggs"> <title>How to boil eggs</title> ... -
Later, the document-to-html.xsl stylesheet will create - an <a name> element for every section, allowing this section to - be referred to as index.html#How+to+boil+eggs.
-

+ Later, the document-to-html.xsl stylesheet will + create an <a name> element for every section, allowing this + section to be referred to as + index.html#How+to+boil+eggs. +

We then expand XInclude elements.
and rewrite links..
and then finally apply the stylesheet that generates a fragment of @@ -462,8 +487,12 @@

Page menu -

In the sitemap.xmap file, the matcher generating HTML for the menu is:

- + In the sitemap.xmap file, the matcher generating HTML for + the menu is: +

+ + @@ -472,19 +501,26 @@ - ]]> -

We get XML from a "book" pipeline, - rewrite links, and apply the - book-to-menu.xsl stylesheet to generate HTML.

How the menu XML is actually generated (the *book-*.html pipeline) is - sufficiently complex to require a - section of its own.

+ ]]> + +

+ We get XML from a "book" pipeline, + rewrite links, and apply the + book-to-menu.xsl stylesheet to generate HTML. +

+ How the menu XML is actually generated (the *book-*.html pipeline) is + sufficiently complex to require a + section of its own. +

Page tabs -

Tab generation is quite tame compared to menus:

- + Tab generation is quite tame compared to menus: +

+ + @@ -493,48 +529,57 @@ - ]]> -

All the smarts are in the tab-to-menu.xsl stylesheet, which - needs to choose the correct tab based on the current path. Currently, - a "longest matching path" algorithm is implemented. See the - tab-to-menu.xsl stylesheet for details.

+ ]]> + +

+ All the smarts are in the tab-to-menu.xsl stylesheet, + which needs to choose the correct tab based on the current path. + Currently, a "longest matching path" algorithm is implemented. See the + tab-to-menu.xsl stylesheet for details. +

Resolving Resources - -

Many resources are resolved by the locationmap. This allow us to provide - many alternative locations for a file without cluttering up the - sitemap with multiple processing paths. We use a strict naming convention - to help make the sitemaps more readable. This is described in the - Locationmap - documentation.

+ Many resources are resolved by the locationmap. This allow us to provide + many alternative locations for a file without cluttering up the sitemap + with multiple processing paths. We use a strict naming convention to + help make the sitemaps more readable. This is described in the + Locationmap + documentation. +

Menu XML generation -

The "book" pipeline is defined in sitemap.xmapas:

- + The "book" pipeline is defined in sitemap.xmapas: +

+ + - ]]> -

Meaning that it is defined in the menu.xmap file. In there we find - the real definition, which is quite complicated, because there are three - supported menu systems (see menus and - linking). We will not go through the sitemap itself - (menu.xmap), but will instead describe the logical steps involved:

+ ]]> + +

+ Meaning that it is defined in the menu.xmap file. In there + we find the real definition, which is quite complicated, because there + are three supported menu systems (see menus + and linking). We will not go through the sitemap itself + (menu.xmap), but will instead describe the logical steps involved: +

Take site.xml and expand hrefs so that they are all root-relative.
Depending on the forrest.menu-scheme property, we - now apply one of the two algorithms for choosing a set of menu links +
+ Depending on the forrest.menu-scheme property, we now + apply one of the two algorithms for choosing a set of menu links (described in menu - generation):
+ generation): +
- -
  +
- For "@tab" menu generation, we first ensure each site.xml node has a tab attribute (inherited from a parent if necessary), and then pass through nodes whose tab attribute matches that of the @@ -542,10 +587,10 @@
  
  For example, say our current page's path is - community/howto/index.html. In + community/howto/index.html. In site.xml we look for the node with this - "href" and discover its "tab" attribute - value is "howtos". We then prune the + "href" and discover its "tab" + attribute value is "howtos". We then prune the site.xml-derived content to contain only nodes with tab="howtos".
  @@ -553,34 +598,38 @@ All this is done with XSLT, so the sitemap snippet does not reveal this complexity:
  - + - ]]> -
- -
  For "directory" menu generation, we simply use an + ]]> +
- + For "directory" menu generation, we simply use an XPathTransformer to include only pages in the - current page's directory, or below:
  - + + - ]]> + ]]> +
  - Here, the "{1}" is the directory part of the current - page. So if our current page is - community/howto/index.html then "{1}" will - be community/howto/ and the transformer will + Here, the "{1}" is the directory part of the + current page. So if our current page is + community/howto/index.html then "{1}" + will be community/howto/ and the transformer will include all nodes in that directory. -
  -
-
We now have a site.xml subset relevant to our current - page.
-

+ We now have a site.xml subset relevant to our current + page. +

The "href" nodes in this are then made relative to the current page.
The XML is then transformed into a legacy "book.xml" @@ -589,48 +638,51 @@ **book-*.html).

Link rewriting -

In numerous places in sitemap.xmap you will see the - "linkrewriter" transformer in action. For example:

- ]]> -

This statement is Cocoon's linking system in action. A full - description is provided in Menus and - Linking. Here we describe the implementation of linking.

+ In numerous places in sitemap.xmap you will see the + "linkrewriter" transformer in action. For example: +

+ +]]> + +

+ This statement is Cocoon's linking system in action. A full description + is provided in Menus and Linking. Here + we describe the implementation of linking. +

Cocoon foundations: Input Modules

The implementation of site: linking is heavily based on Cocoon Input Modules, a - little-known but quite powerful aspect of Cocoon. Input Modules are + little-known but quite powerful aspect of Cocoon. Input Modules are generic Components which simply allow you to look up a value with a - key. The value is generally dynamically generated, or obtained by + key. The value is generally dynamically generated, or obtained by querying an underlying data source.

In particular, Cocoon contains an XMLFileModule, which lets one look up the value of an XML node, by interpreting the key as - an XPath expression. Cocoon also has a + an XPath expression. Cocoon also has a SimpleMappingMetaModule, which allows the key to be rewritten before it is used to look up a value.

The idea for putting these together to rewrite "site:" links was described in this - thread. The idea is to write a Cocoon Transformer that - triggers on encountering <link - href="scheme:address">, and interprets the - scheme:address internal URI as - inputmodule:key. The transformer then uses the named + thread. The idea is to write a Cocoon Transformer that triggers + on encountering <link href="scheme:address">, and + interprets the scheme:address internal URI as + inputmodule:key. The transformer then uses the named InputModule to look up the key value. The scheme:address - URI is then rewritten with the found value. This transformer was - implemented as + URI is then rewritten with the found value. This transformer was + implemented as LinkRewriterTransformer, currently distributed as a "block" in Cocoon 2.1

Implementing "<code>site:</code>" rewriting

@@ -639,8 +691,11 @@

cocoon.xconf -

First, we declare all the input modules we will be needing:

- + First, we declare all the input modules we will be needing: +

+ +

-]]> +]]> +

linkmap will provide access to the contents of &s;; for example, linkmap:/site/about/index/@href would return the value "index.html".
site provides a "mask" over linkmap such that site:index expands - to linkmap:/site//index/@href -

linkmap:/site//index/@href

ext provides another "mask" over linkmap, such that ext:ant would - expand to linkmap:/site/external-refs//ant/@href -

linkmap:/site/external-refs//ant/@href

However at the moment, we have only declared the input modules. - They will be configured in sitemap.xmap as described in - the next section.

+ However at the moment, we have only declared the input modules. They + will be configured in sitemap.xmap as described in the + next section. +

sitemap.xmap

@@ -681,7 +736,8 @@ insert it into any pipelines which deal with user-editable XML content:

- + ... -]]> -

As you can see, our three input modules are configured as part of - the LinkRewriterTransformer's configuration.

+]]> + +

+ As you can see, our three input modules are configured as part of + the LinkRewriterTransformer's configuration. +

-
Most deeply nested, we have:
-
+ Most deeply nested, we have: +
+ + - ]]> -
The "{src}" text is expanded to the value of the + ]]> + +
+ The "{src}" text is expanded to the value of the "src" attribute in the "linkrewriter" - instance, namely "cocoon:/{1}linkmap-{2}.html" - Thus the linkmap module reads dynamically - generated XML specific to the current request.
-
-
One level out, we configure the "site" and + instance, namely "cocoon:/{1}linkmap-{2}.html" Thus + the linkmap module reads dynamically generated XML + specific to the current request. +
+ One level out, we configure the "site" and "ext" input modules, to map onto our dynamically - configured "linkmap" module.
-
-
Then at the outermost level, we configure the - "linkrewriter" transformer. First we tell it which - attributes to consider rewriting:
- linkmap" module. +
+ Then at the outermost level, we configure the + "linkrewriter" transformer. First we tell it which + attributes to consider rewriting: +
+ +href src - site ext]]> -
So, "href" and "src" attributes starting - with "site:" or "ext:" are rewritten.
- -
By nesting the "site" and "ext" input - modules in the "linkrewriter" configuration, we tell - "linkrewriter" to use these two input modules when - rewriting links.
-

site ext

+ So, "href" and "src" attributes + starting with "site:" or "ext:" are + rewritten. +

+ By nesting the "site" and "ext" input + modules in the "linkrewriter" configuration, we + tell "linkrewriter" to use these two input modules + when rewriting links. +

The end result is that, for example, the source XML for the community/body-index.html page has its links rewritten @@ -764,13 +832,14 @@ Dynamically generating a linkmap

Why do we need this "linkmap" pipeline generating dynamic XML from - &s;, instead of just using &s; directly? The reasons are described + &s;, instead of just using &s; directly? The reasons are described in the linkmap RT: we need to concatenate @hrefs and add dot-dots to the paths, depending on which - directory the linkee is in. This is done with the following + directory the linkee is in. This is done with the following pipelines in linkmap.xmap ...

- + @@ -787,9 +856,11 @@ - ]]> -

You can try these URIs out directly on a live Forrest to see what - is going on (for example, Forrest's own + ]]> + +

+ You can try these URIs out directly on a live Forrest to see what is + going on (for example, Forrest's own abs-linkmap).

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/skin-package.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/skin-package.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/skin-package.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/skin-package.xml Mon Apr 9 20:48:52 2007 @@ -18,61 +18,50 @@ -

Skin packaging, provision, and use Automated distributed skin packages

Overview

-Skins are standard zip archives with a *.zip extension. -This enables them to be unpacked and installed automatically. + Skins are standard zip archives with a *.zip extension. This enables + them to be unpacked and installed automatically.

-To publish a skin: + To publish a skin:

- - + 1 - forrest package-skin The skin package will be made in the skin dir, next to the custom skin. 2 - place the file in a directory on a web server 3 - ask forrest-dev to add the url and the skin name to the list of skins - -

-To use a custom skin with automatic download: + To use a custom skin with automatic download:

- - + 1 - set the skin property in forrest.properties to the name of the skin 2 - forrest install-skin 3 - forrest -

-Currently there are two test skins: "testskin" and "testskin2" + Currently there are two test skins: "testskin" and "testskin2"

-To see the names of the remote skins: + To see the names of the remote skins:

- -forrest available-skins + forrest available-skins

Notes

-The skin will get blown away by the next 'build clean' in forrest. -But that is okay because it is so quick to go get another copy. Also it -may be preferable to get a fresh copy. If the user wanted to keep -the skin and perhaps enhance it, then they can copy it to their project. + The skin will get blown away by the next 'build clean' in forrest. But + that is okay because it is so quick to go get another copy. Also it may + be preferable to get a fresh copy. If the user wanted to keep the skin + and perhaps enhance it, then they can copy it to their project.

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/skins.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/skins.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/skins.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/skins.xml Mon Apr 9 20:48:52 2007 @@ -29,91 +29,82 @@ many capabilities so that extra skins are not needed.

- Note that the new Dispatcher capability will be a better solution. - See Status of Themes: Skins and Dispatcher. + Note that the new Dispatcher capability will be a better solution. See + Status of Themes: Skins and Dispatcher.

Convention for choosing skin names

The skin names are based on playing with the word "skin". See our technique for - choosing skin names. - A name with "-dev" extension signifies that it is under development. - There is no concept of versions of default skins. - New skins have new names. + choosing + skin names. A name with "-dev" extension signifies that it is under + development. There is no concept of versions of default skins. New skins + have new names.

Skin descriptions and examples -

pelt

Uses CSS "div" and no HTML tables.

Examples: - Apache Forrest | +

+ Examples: Apache Forrest | Apache Lenya

tigris

- This skin is based on version 1.1 of the - style.tigris.org project. - (It deliberately contravenes our skin naming convention.) + This skin is based on version 1.1 of the + style.tigris.org project. (It + deliberately contravenes our skin naming convention.)

Examples: - Core Computer Security Group +

+ Examples: Core Computer Security + Group

plain-dev

- This is a very minimal skin to produce plain HTML documents. - Such capability might be useful to generate a collection of - documents for some off-line product's user help system. -

- -

Examples: - snapshot + This is a very minimal skin to produce plain HTML documents. Such + capability might be useful to generate a collection of documents for + some off-line product's user help system. +

+ Examples: snapshot

Old and deprecated skins

The following skins are retained for a little while longer, but are deprecated, so please move to one of the other skins.

forrest-site

This is the old skin that we have been dragging around since early days. Uses HTML tables.

Examples: - Apache XML +

+ Examples: Apache XML

krysalis-site

Uses HTML tables.

- -

Examples: +

+ Examples:

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/status-themes.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/status-themes.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/status-themes.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/status-themes.xml Mon Apr 9 20:48:52 2007 @@ -24,39 +24,50 @@

Skins -

"Skins" is the term used to describe the current method for adding - navigation and menu information to the content of a page and applying a - consistent theme for layout, colours, etc. The "pelt" skin is the only one that the Forrest - project is maintaining. It is configurable enough to meet many - purposes. The main configuration file for skins is the skinconf.xml - file. There is - an ability for users to create their own skins, although we have not - encouraged that.

For the Forrest-0.8 release, skins are still available and are still the main mechanism. - No effort has been made to enhance skins.

+ "Skins" is the term used to describe the current method for adding + navigation and menu information to the content of a page and applying a + consistent theme for layout, colours, etc. The + "pelt" skin is the only one that the + Forrest project is maintaining. It is configurable enough to meet many + purposes. The main configuration file for skins is the skinconf.xml + file. There is an ability for users to create their own skins, although + we have not encouraged that. +

+ For the Forrest-0.8 release, skins are still available and are still the + main mechanism. No effort has been made to enhance skins. +

Dispatcher -

"Dispatcher" is the term used to describe a new method which aims to - be a more flexible and complete solution to build a reliable common - structure for documents, incorporate other content, and provide hooks - for applying themes. Themes get configured by structurer definitions - (a wee bit like the skinconf.xml). Although strong progress has been - made, it is still under development. We encourage developers to use - Dispatcher and contribute to its development. See the + "Dispatcher" is the term used to describe a new method which aims to be + a more flexible and complete solution to build a reliable common + structure for documents, incorporate other content, and provide hooks + for applying themes. Themes get configured by structurer definitions (a + wee bit like the skinconf.xml). Although strong progress has been made, + it is still under development. We encourage developers to use Dispatcher + and contribute to its development. See the + - plugin documentation for more information.

+ plugin documentation for more information. +

Plan for future framework -

The desired direction is to use xhtml2 as the internal format, move the current "skins" - into a plugin, and develop input plugins for xdoc and html sources. This would enable - any theme engine to be used, whether that be Skins or Dispatcher or some other. +

+ The desired direction is to use xhtml2 as the internal format, move the + current "skins" into a plugin, and develop input plugins for xdoc and + html sources. This would enable any theme engine to be used, whether + that be Skins or Dispatcher or some other.

See the development discussion: - Re: status of skins and dispatcher. - This is planned for immediately following the 0.8 release. New developers please help. +

+ See the development discussion: + Re: + status of skins and dispatcher. This is planned for immediately + following the 0.8 release. New developers please help.

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/tab-index.fv URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/tab-index.fv?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/tab-index.fv (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/tab-index.fv Mon Apr 9 20:48:52 2007 @@ -17,7 +17,7 @@ --> - + @@ -27,4 +27,4 @@ - \ No newline at end of file + Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/upgrading_08.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/upgrading_08.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/upgrading_08.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/upgrading_08.xml Mon Apr 9 20:48:52 2007 @@ -16,78 +16,85 @@ limitations under the License. --> - -

- Upgrading to Apache Forrest 0.8-dev -

- + +

+ Upgrading to Apache Forrest 0.8-dev +

Introduction - -This is the development version of Apache Forrest which can -be obtained from the Subversion repository or from a code snapshot. -See the notes for obtaining and Building Forrest. - -

- This page describes some changes to Apache Forrest that affect people who are - upgrading to the 0.8 version. - If you have other issues, then please discuss on either the - dev or - user - mailing lists. - As more experience is gained, this document will be updated. + + This is the development version of Apache Forrest which + can be obtained from the Subversion repository or from a code snapshot. + See the notes for obtaining and Building + Forrest. + +

+ This page describes some changes to Apache Forrest that affect people + who are upgrading to the 0.8 version. If you have other issues, then + please discuss on either the + dev or + user mailing lists. As more + experience is gained, this document will be updated.

- (If you are upgrading from a version prior to 0.7 then you will need - to see the notes for the previous upgrade.) + (If you are upgrading from a version prior to 0.7 then you will need to + see the notes for the previous upgrade.)

New Features

- The following list shows some of the key new features. - For the full list of changes, see the main - change log and also for each plugin. + The following list shows some of the key new features. For the full list + of changes, see the main change log and also + for each plugin.

Locationmaps.

Many new initial plugins are in the "whiteboard". See the entries in the - change log and see each plugin's documentation and changes log. - This includes the new Dispatcher. - See Status of Themes: Skins and Dispatcher. +

+ Many new initial plugins are in the "whiteboard". See the entries in the + change log and see each plugin's + documentation and changes log. This includes the new Dispatcher. See + Status of Themes: Skins and Dispatcher.

Locationmaps -

The Locationmaps define the mapping from requests to locations - which enables content and resources to be located at various different sources. -

Adding a default locationmap to your project is not required, but is advisable. - Sooner or later you will use it. Having a default one also reduces the verbosity - of the log files. Copy one from a fresh 'forrest seed' to - PROJECT_HOME/src/documentation/content/locationmap.xml -

- If you do use locationmaps and an entry for a specific request is - missing Forrest generates a confusing error message. Please ask on our - mailing lists for help in debugging your problem (hint, turn on locationmap - debugging in [FORREST_HOME]/main/webapp/WEB-INF/logkit.xconf, restart Forrest, - request the broken pages and visit [SITE_HOM]/build/webapp/logs/locationmap.xml). - This issue will be fixed in the next version of Forrest. +

+ The Locationmaps define the mapping from + requests to locations which enables content and resources to be located + at various different sources. +

+ Adding a default locationmap to your project is not required, but is + advisable. Sooner or later you will use it. Having a default one also + reduces the verbosity of the log files. Copy one from a fresh 'forrest + seed' to + PROJECT_HOME/src/documentation/content/locationmap.xml +

+ + If you do use locationmaps and an entry for a specific request is + missing Forrest generates a confusing error message. Please ask on our + mailing lists for help in debugging your problem (hint, turn on + locationmap debugging in + [FORREST_HOME]/main/webapp/WEB-INF/logkit.xconf, restart Forrest, + request the broken pages and visit + [SITE_HOM]/build/webapp/logs/locationmap.xml). This issue will be fixed + in the next version of Forrest. +

Forrest configuration simplification

- FOR-920 Merging the - defaults and - project modules to the new - properties module. You can use it like {properties:forrest.home} -

In all custom code (e.g. project sitemaps or plugins) you need to do the following:

- + FOR-920 Merging the defaults and + project modules to the new properties module. + You can use it like {properties:forrest.home} +

+ In all custom code (e.g. project sitemaps or plugins) you need to do the + following: +

find: {defaults: and replace with @@ -102,92 +109,89 @@ {properties:

Run a clean target after upgrade

- Do 'forrest clean-work' in each of your projects. This also removes - the old Cocoon disk cache. + Do 'forrest clean-work' in each of your projects. This also removes the + old Cocoon disk cache.

New filename convention for stylesheets

- There is now a filenaming convention for stylesheets (e.g. document-to-html.xsl). - This assists with automating the location of such resources. - See Locationmap. -

For the default use of Forrest, this makes no difference. However, if - you have developed your own skin then you will need to do some filename changes, e.g. - 'cd skins/my-skin/xslt/html; mv tab2menu.xsl tab-to-menu.xsl' (do each of book2menu.xsl document2html.xsl site2xhtml.xsl tab2menu.xsl). - It is advisable to follow this naming convention for your other resources, - which will mean that you can utilise the locationmap. + There is now a filenaming convention for stylesheets (e.g. + document-to-html.xsl). This assists with automating the location of such + resources. See Locationmap. +

+ For the default use of Forrest, this makes no difference. However, if + you have developed your own skin then you will need to do some filename + changes, e.g. 'cd skins/my-skin/xslt/html; mv tab2menu.xsl + tab-to-menu.xsl' (do each of book2menu.xsl document2html.xsl + site2xhtml.xsl tab2menu.xsl). It is advisable to follow this naming + convention for your other resources, which will mean that you can + utilise the locationmap.

Notes about documentation -

After each release, the "Versioned Docs" are copied to form the new "dev" set. - Ideally the docs are then upgraded in readiness for the new release. - This has not been completed for the 0.8 release. In particular there are - example snippets of sitemaps which have not yet been upgraded to reflect the changes to the sitemaps and the separation of some core stuff into plugins. - See issues - FOR-546 - and - FOR-922 - and others. +

+ After each release, the "Versioned Docs" are copied to form the new + "dev" set. Ideally the docs are then upgraded in readiness for the new + release. This has not been completed for the 0.8 release. In particular + there are example snippets of sitemaps which have not yet been upgraded + to reflect the changes to the sitemaps and the separation of some core + stuff into plugins. See issues + FOR-546 and + FOR-922 and + others.

Notes about Cocoon version

- The last time that we upgraded our packaged version of Cocoon trunk - was using their SVN r351990 on 2005-12-08. Since then a number of things + The last time that we upgraded our packaged version of Cocoon trunk was + using their SVN r351990 on 2005-12-08. Since then a number of things have happened to cause us to fall out of synchronisation with Cocoon. - There is various discussion about this in the Forrest and Cocoon dev mail archives. + There is various discussion about this in the Forrest and Cocoon dev + mail archives.

If you use your own version of Cocoon, then you will know about the - upgrade notes in the $FORREST_HOME/etc/cocoon_upgrade directory. - You might be able to advance a bit beyond the SVN revision, but not much. + upgrade notes in the $FORREST_HOME/etc/cocoon_upgrade directory. You + might be able to advance a bit beyond the SVN revision, but not much. Please help to rectify this situation.

Whitespace and indenting of xml files with xmlformat

All xml type files have been formatted using xmlformat. You can apply - this to your own work if necessary by using the same configuration - as the Forrest project. - See notes at FOR-644. + this to your own work if necessary by using the same configuration as + the Forrest project. See notes at + FOR-644.

General upgrade tips

- Synchronise your project's skinconf.xml and forrest.properties files. + Synchronise your project's skinconf.xml and forrest.properties files.

- Take advantage of the separation of concerns. In a new workspace, - create a fresh - 'forrest seed' site, then tweak its forrest.properties - and skinconf.xml until it reflects your old site. - When it is ready, replace your project's skinconf.xml and - forrest.properties files. - Any remaining issues would concern other aspects of your configuration, - such as site.xml and your actual content. + Take advantage of the separation of concerns. In a new workspace, create + a fresh 'forrest seed' site, then tweak its + forrest.properties and skinconf.xml until it reflects your old site. + When it is ready, replace your project's skinconf.xml and + forrest.properties files. Any remaining issues would concern other + aspects of your configuration, such as site.xml and your actual content.

To be continued... -

...as more issues are discovered/remembered :) Please send feedback - to the - mailing list.

+ ...as more issues are discovered/remembered :) Please send feedback to + the mailing list. +