Added: forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html?rev=1068306&view=auto ============================================================================== --- forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html (added) +++ forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,515 @@ + + + + + + + +Plugin Infrastructure (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Plugin Infrastructure

+
+
+ This is documentation for development version v0.10-dev + (More)
+ +
+ + +

Overview

+
+

+ Forrest can be extended with the addition of plugins. This document + describes what a plugin is and outlines the plugin infrastructure so + that you can start building your own Forrest extensions. +

+
+ + +

What is a Forrest Plugin?

+
+

+ A Forrest plugin is a set of resources and configuration files that + extend the functionality of Forrest. They will typically consist of a + sitemap, zero or more stylesheets and zero or more schemas. +

+

+ The plugins sitemap is mounted by Forrest's sitemap after the project + specific sitemap but before the Forrest default matchers. This allows a + plugin to override/extend default Forrest behaviour. By adopting a + plugin model we can keep the core of Forrest tightly focused on the + basic functionality, whilst still facilitating extensions to suit + individual projects needs. +

+ +

Types of Plugin

+

+ There are three types of plugin, input, + output and internal. Each plugin has a + specific role to play and extends a different part of Forrest: +

+
+                            internal plugins
+                       (site.xml, abs-linkmap etc.)
+                                   |
+                                  \|/
+                                   .
+          input format --> intermediate format --> output format 
+                        .                       .
+                       /|\                     /|\
+                        |                       |
+                   input plugin            output plugin
+                     (**.xml)         (**.html, **.pdf etc.) 
+
+ +

Input Plugins

+

+ Input plugins provide a new source format. For example, the + OpenOffice.org plugin extends Forrest to allow the use of + OpenOffice.org Application file formats. +

+

+ An input plugin provides an input.xmap file. This + provides the source matchers (i.e. **.xml), it is mounted in + forrest.xmap before the default forrest **.xml behaviour and + therefore can override that default behaviour but it will not + interfere with any internal Forrest infrastructure matches, or any + other plugins infrastructure matches. +

+

+ An input plugin may also provide a resources.xmap file. + This can be used to match additional resources that are not stored + in XML files, for example, javascript files. +

+ +

Output Plugins

+

+ Output plugins provide a new output format. For example, the s5 + plugin extends Forrest to produce HTML slides from Forrest + documents. +

+

+ An output plugin provides an output.xmap file. This + provides the relevant output matchers (i.e. **.html, **.pdf, + **.slides), it is mounted before any of the default matchers for + Forrest and so can override this default behaviour. +

+ +

Internal Plugins

+

+ Internal plugins are for advanced use only. They provide ways of + extending or overriding Forrest's internal operations. For example, + the IMSManifest plugin allows Forrest projects to use an IMS + Manifest file instead of a site.xml and tabs.xml configuration + files. +

+

+ Internal plugins provide an internal.xmap file. This + provides the infrastructure matchers (i.e. site.xml, faq.xml, + issues.xml), and will be mounted before *any* of the Forrest + matches. This sitemap can override any behaviour within Forrest and + so developers of these plugins must be especially careful with the + construction of their matchers, since they will be processed before + any other matchers and consequently can easily break existing + functionality. You must only do a <map:generate ...> if you + are certain you are going to process the full result. +

+ +

Naming Conventions

+

+ Technically you can name a plugin anything you like with one small + restriction (see below). However, we do have some naming conventions + that we recomend you follow. This is to minimise the chances of + collision between plugins from different developers. +

+

+ The name should be structured like a java package name, and should + include a relevant reverse domain name. For example: +

+
org.apache.forrest.plugin.PLUGIN_TYPE.PLUGIN_NAME
+
net.sf.forrestPlugins.PLUGIN_TYPE.PLUGIN_NAME
+

+ Where PLUGIN_TYPE is either "internal", "input" or + "output" and PLUGIN_NAME" is a suitable name chosen by + yourself. +

+
+
Warning
+
+ Plugin names cannot have a '-' character in them. This character is + used to indicate the start of a version number when defining a plugin + to be used. See Using Plugins for + more information. +
+
+ +

An Example Plugin

+

+ In order to fully understand the applicability of Forrest Plugins we + will consider an extension to the way in which Forrest defines the + structure of the site. By default Forrest uses a site.xml file to + define navigation through the site and a tabs.xml file to define the + tabs across the top of the page. But what if we want to use a + different file to describe site structure? For example, what if we + want to use an IMS Manifest file from the SCORM content package + standards (http://www.adlnet.org/). +

+

+ An IMS Manifest file describes the structure of a site. It is also + possible to define a set of rules for extracting tab information from + such a file. Consequently, it is possible to use an IMSManifest file + to create Forrest's site.xml and tabs.xml files. The advantage would + be that we can then use SCORM compliant content objects within + Forrest. +

+

+ Unfortunately, IMS Manifests are much more complex than site.xml and + tabs.xml files. Therefore, not all users will want to use them. Adding + the functionality as an optional plugin seems to be the ideal + solution. +

+
+ + +

What Does a Forrest Plugin Look Like?

+
+

+ Plugins will need to conform to a specified directory structure. This + mirrors the default forrest directory structure: +

+
+[plugin_name]
+  |
+  |-- plugin control files (xmap etc.)
+  |
+  |-- conf
+  |   |
+  |   `-- cocoon and component config files (e.g. *.xconf, jtidy)
+  |
+  |-- resources
+      |
+      |-- schema
+      |   |
+      |   |-- catalog.xcat
+      |   |
+      |   `-- dtd (DTDs etc.)
+      |
+      `-- stylesheets (XSLs etc.)
+
+ +

The IMS Manifest Plugin

+

+ If we consider the IMS Manifest Plugin described above, we see that we + will need the following files and directory structure: +

+
+org.apache.forrest.plugin.internal.IMSManifest
+  |
+  |-- sitemap.xmap
+  |
+  |-- resources
+      |
+      |-- stylesheets
+                    |
+                    |- imsmanifest2site.xsl
+                    |- imsmanifest2tabs.xsl
+                    |- pathutils.xsl
+                    |- repositoryUtils.xsl
+
+

+ The sitemap.xmap file will override the default behaviour for the + navigation generation matchers in Forrest, for example, it contains a + matcher as follows: +

+
+
+<map:match pattern="abs-menulinks">
+  <map:select type="exists">
+    <map:when test="{properties:content.xdocs}imsmanifest.xml">
+       <map:generate src="{properties:content.xdocs}imsmanifest.xml" />
+       <map:transform src="resources/stylesheets/imsmanifest2site.xsl"/>
+       <map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" />
+       <map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" />
+     <map:serialize type="xml"/>
+   </map:when>
+   <map:when test="{properties:content.xdocs}site.xml">
+      <map:generate src="{properties:content.xdocs}site.xml" />
+      <map:transform src="{forrest:forrest.stylesheets}/absolutize-linkmap.xsl" />
+      <map:transform src="{forrest:forrest.stylesheets}/site2site-normalizetabs.xsl" />
+      <map:transform src="{forrest:forrest.stylesheets}/normalizehrefs.xsl"/>
+    <map:serialize type="xml"/>
+  </map:when>
+  </map:select>
+</map:match>
+
+        
+
+
Note
+
+ Note that this matcher will default to the behaviour provided by + Forrest if there is no imsmanifest.xml file present in the project. At + present it is necessary to copy this default behaviour from the + original Forrest *.xmap files. We hope to improve on this in the + future. +
+
+
+ + +

How does Installation work?

+
+

+ See the Using Plugins for an overview + of how the plugin installation system works and the places and order + that will be searched. +

+

+ When Forrest installs a plugin it downloads a zip of the plugin code and + extracts it into the plugins directory of Forrest and an + entry is made in a temporary sitemap that manages plugins for your + content object. For example, installing the IMSManifest plugin described + above will result in the following entry being added to the this + temporary sitemap: +

+
+
+<map:select type="exists">
+  <map:when test="output.xmap">
+    <map:mount uri-prefix="" 
+      src="sitemap.xmap" 
+      check-reload="yes" 
+      pass-through="true"/>
+  </map:when>
+</map:select>
+  
+      
+

+ To be more accurate, the entries are made in one of three temporary + sitemaps, input.xmap, output.xmap and resources.xmap. These temporary + sitemaps are rebuilt each time the content object is built or run, thus + we are always guarenteed of having the right plugins installed. +

+
+ + +

Further Reading

+
+

+ If you want to build a plugin you might like to start with our + HowTo on Building Plugins. +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/pluginDocs/plugins_0_100/pluginInfrastructure.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/pluginDocs/plugins_0_100/usingPlugins.html URL: http://svn.apache.org/viewvc/forrest/site/pluginDocs/plugins_0_100/usingPlugins.html?rev=1068306&view=auto ============================================================================== --- forrest/site/pluginDocs/plugins_0_100/usingPlugins.html (added) +++ forrest/site/pluginDocs/plugins_0_100/usingPlugins.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,533 @@ + + + + + + + +Extending Forrest with Plugins (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Extending Forrest with Plugins

+ + + +

Overview

+
+

+ Forrest provides the core functionality for generating documentation in + various output formats from a range of input formats. However, it does + not end there. Forrest can be extended through the addition of plugins. + This document serves as an introduction to the Forrest plugin mechanism. +

+ +

What plugins are available?

+

+ You can run the command forrest available-plugins to get + a list of the known plugins for Forrest. +

+

+ If you would like to have your own plugin added to this list then + contact the developer mailing list. +

+
+ + +

How is a Plugin Installed?

+
+ +

List of Plugins Needed by the Project

+

+ If a site requires one or more plugins then the site designer will + have to list them in the project.required.plugins + property in the projects forrest.properties file. When + Forrest builds the site it will automatically discover the plugins and + install them. In otherwords, the user needs do nothing. +

+

+ For example, +

+
+project.required.plugins=org.apache.forrest.plugin.output.pdf,
+  org.apache.forrest.plugin.input.simplifiedDocbook
+

+ (note that that is all in one line with no spaces) + will cause Forrest to load the plugins called + "org.apache.forrest.plugin.output.pdf" and + "org.apache.forrest.plugin.input.simplifiedDocbook". +

+
+
Note
+
+ By default a new forrest project has that property configured to + include some plugins. Currently there is only one to generate PDF + output from your source documents. +
+
+ +

What Version of Plugins will be used ?

+

+ In the absence of a version number for the plugin (as is the case in + the example above) the most recent version that is applicabe to your + release of Forrest will be used. This may result in unexpected + behaviour if a new version of the plugin has been released that is + incompatible with your current site. To force Forrest into using a + specific version of a plugin you should add "-VERSION_NUMBER" to the + end of the plugin name. For example, to force forrest to use the version 0.2 + of the "output.pdf" plugin you would use + org.apache.forrest.plugin.output.pdf-0.2. If + you define a version of the plugin that does not exist then it will + fall back to using the most recent version available. This feature is + useful when developing a new site as you can quickly force a plugin + upgrade by deleting all installed plugins (use the command 'ant + cleanPlugins'). However, this might result in the installation of an + in-development plugin, therefore in a production environment you + should always specify a known working version. +

+ +

Where does Forrest look for Plugins sources?

+ +

Overview

+

+ This is fairly complex, so here is a simple overview. If you want to + know the details you need to read the rest of this section. For most + people this overview will be sufficient. +

+

+ Forrest will try and retrieve a plugin from local source files + first, if that fails it will look on a remote distribution server. + Once it finds a copy of the plugin it will deploy it to the local + Forrest instance and use it from there. +

+

+ The local directories that will be searched are defined in the + project.required.plugins.src property, which is defined + in the forrest.properties file. By default this is set + to + ${forrest.home}/plugins,${forrest.home}/whiteboard/plugins, + which means that these two directories will be searched for plugins. +

+

+ If you have a collection of local plugins the directory in which they are located + must be added this property. For example, if your local plugins are in /export/forrest_plugins + this property should be something like: + project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins + +

+

+ You can add this line to your projects + forrest.properties file. However, it may be more + convenient to add it to a forrest.properties file in + your users home directory. +

+

+ Forrest uses a fall back mecanism to find the plugins to install for a + project. +

+

+ For an unversionned plugin, Forrest tries to get it from : +

+
    + +
  1. different local sources directories (project.required.plugins.src property)
  2. + +
  3. if not found : the remote site in the forrest version directory
  4. + +
  5. if not found : the remote site (with no forrest version directory)
  6. + +
+

+ For a versionned plugin, Forrest tries to get : +

+
    + +
  1. the versionned plugin from different local sources directories (project.required.plugins.src property)
  2. + +
  3. if not found : the versionned plugin from the remote site in the forrest version directory
  4. + +
  5. if not found : the unversionned plugin in different local sources directory (project.required.plugins.src property again)
  6. + +
  7. if not found : the unversionned plugin from the remote site in the forrest version directory
  8. + +
  9. if not found : the remote site (with no forrest version directory)
  10. + +
+

+ By default, forrest looks into the two following directories to find + plugins sources : ${forrest.home}/plugins and + ${forrest.home}/whiteboard/plugins. It is possible to add + other sources locations by specifying the + project.required.plugins.src property in the projects + forrest.properties file. +

+

+ For example, +

+
project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins
+

+ will add the project specific directory + ${project.home}/plugins to the list of directories to + search in. +

+

+ If sources are not found, forrest will try to get them from the Web. + Forrest knows the plugins description with plugins + descriptors files in which plugins are described as follows : +

+
+<plugin name="org.apache.forrest.plugin.output.pdf"
+  type="output"
+  author="Apache Forrest Project"
+  website="http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.output.pdf"
+  url="http://forrest.apache.org/plugins/"
+  version="0.2">
+  <description>
+    Enable Forrest documents to be output in PDF format.
+  </description>
+  <forrestVersion>0.8</forrestVersion>
+</plugin>
+        
+

+ The url to download the different plugins is indicated in this file. +

+

+ By default, forrest gets the two following plugins descriptors files : + http://forrest.apache.org/plugins/plugins.xml and + http://forrest.apache.org/plugins/whiteboard-plugins.xml. + It is possible to add other plugins descriptors files by specifying + the forrest.plugins.descriptors property in the projects + forrest.properties file. +

+

+ For example, +

+
forrest.plugins.descriptors=http://forrest.apache.org/plugins/plugins.xml,http://forrest.apache.org/plugins/whiteboard-plugins.xml,file:///${project.home}/plugins/plugins.xml
+

+ will add the project specific plugins descriptors file + file:///${project.home}/plugins/plugins.xml to the list + of descriptors. +

+
+ + +

Editing plugins sources to enhance functionality

+
+
+
Note
+
+ Of course, developers would need the sources. They are available via + SVN. Alternatively, see your + $FORREST_HOME/build/plugins/ directory. Copy them somewhere for your + development and set the project.required.plugins.src property as described + above. The SVN method is preferred. +
+
+
+
Note
+
+ Until issue + FOR-388 is + fixed to enable the use of plugins in-place, any change to sources + requires you to either restart forrest or to manually deploy the plugin + locally with "ant local-deploy". See Further reading for "How to build a + Plugin". It is worth noting that if your changes are to Java files you + will always have to restart Forrest to ensure the class loader loads + your new classes. +
+
+

+ If you need to add specific behaviour to an existing plugin, you should + first consider whether your changes will be of use to all users of the + plugin or not. If they are of general use then you can edit the plugin + source files in their original location (i.e. not in the build + directory). Once you have completed your changes please + prepare a patch and submit it for + inclusion in code base. +

+

+ If your changes are specific to your own use of the plugin you can + create a local copy of the plugin for this. However, we strongly advise + against this since you will need to manually update your plugin each + time a new release of the original is made. In the vast majority of + cases local enhancements to a plugin wil be of use to the wider + communtiy. Please donate back to the project and help keep it vibrant + and useful. See the Further Reading section at the end of this document + for links to documents with more information. +

+
+ + +

Upgrading from a Version of Forrest Without Plugins

+
+

+ The plugin functionality was introduced in version 0.7 of Forrest. At + this time some of the functionality previously in Forrest was extracted + into a plugin. However, we have not broken backward compatability with + earlier versions. In the absence of a + project.required.plugins property in the projects + forrest.properties file all plugins that contain + functionality previously part of Forrest itself will be loaded + automatically. Unless you intend to use new functionality provided by a + plugin you will not need to make any changes to your project. +

+

+ If you do require additional plugin functionality, be sure to include + all required plugins in the project.required.plugins + property in the project's forrest.properties. You can view + main/webapp/default-forrest.properties to see the names of + plugins that provide previously core functionality. +

+

+ It is also worth noting that there is a small performance improvement if + you remove plugins that are not in use. Therefore, if you do not use one + or more of the plugins named in the + project.required.plugins property of + main/webapp/default-forrest.properties it is recomended + that you override this value in your project's + forrest.properties file. +

+
+ + +

Avoiding Plugin Conflicts

+
+

+ Clashes between plugins can occur. For example, the simplified-docbook + and full docbook plugins may try and process the same files. In this + instance the one that is mounted first will take precedence. Plugins are + mounted in the order they appear in the + project.required.plugins property, therefore the mounting + order and therefore processing precedence is under user control. +

+
+ + +

Further Reading

+ + +
+ +
 
+
+ + + Propchange: forrest/site/pluginDocs/plugins_0_100/usingPlugins.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/trash/docs_0_50/upgrading_05.html URL: http://svn.apache.org/viewvc/forrest/site/trash/docs_0_50/upgrading_05.html?rev=1068306&view=auto ============================================================================== --- forrest/site/trash/docs_0_50/upgrading_05.html (added) +++ forrest/site/trash/docs_0_50/upgrading_05.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,530 @@ + + + + + + + +Upgrading to Forrest 0.5 + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Upgrading to Forrest 0.5

+ + + +

Introduction

+
+

+ This page describes changes to Forrest that affect people who are + upgrading from 0.4 and earlier to the 0.5 version. Please post your + upgrade experiences to the + forrest-dev mailing + list. As more experience is gained, this document will be + updated. +

+
+ + +

New Features

+
+

+ This new version includes many changes, as it as been under development + for seven months (in part, awaiting the Cocoon 2.1 release). The + following list shows some of the key new features for Forrest 0.5 (for + the full list of changes, see the + change log). +

+
    + +
  • Significantly faster (100% - 300%) command-line rendering
  • + +
  • Docbook support. The DTDs are shipped. Document types are + automatically detected by the sitemap and there is a basic stylesheet + which converts DocBook documents to intermediate forrest document-v12 + for standard rendering. For rendering as full DocBook, see + this FAQ entry. +
  • + +
  • Configuration of URLs to ignore with cli.xconf configuration.
  • + +
  • Skin enhancements.
  • + +
  • The document-v12 DTDs are added. You can still use the old + document-v11 DTDs if you would rather. However it is easy to upgrade + - just change the document type declarations in you project's xdocs + and run 'forrest validate-xdocs'.
  • + +
  • Automated handling of documents in Wiki syntax. See the + fresh-site example which are generated when you + 'forrest seed' a new project.
  • + +
  • The 'forrest backcopy' target copies all + types of content that you may have edited under the webapp while + doing a 'forrest run'.
  • + +
  • Flag for email obfuscation.
  • + +
  • Support for raw un-processed content. See + this FAQ entry. +
  • + +
  • Element <abstract> is now rendered in the + HTML output.
  • + +
  • Images scale properly in PDF output. See also + this FAQ entry. +
  • + +
  • Configurable table-of-content depth with new 'toc' element in + the skinconf.xml configuration.
  • + +
+
+ + +

Upgrading the sitemap

+
+

+ In brief, Forrest 0.5 is mostly backwards-compatible for sites + that do not define a custom sitemap. Between 0.4 and 0.5, the Forrest + sitemap was completely rewritten. Instead of a single sitemap.xmap doing + everything, a 'driver' sitemap.xmap now delegates to a number of mounted + subsitemaps handling different functional areas. The new sitemap is + fully described in the Sitemap + Reference. +

+

+ Users that have overridden and augmented the Forrest 0.4 sitemap.xmap + (run 'forrest overrides' to see if your project has) will + need to: +

+
    + +
  1. Move their overridden sitemap (src/documentation/sitemap.xmap) out the way
  2. + +
  3. Copy the new sitemap, $FORREST_HOME/context/sitemap.xmap, to src/documentation +
  4. + +
  5. Reapply your customizations to the new sitemap.xmap. Customizations can be determined by comparing your modified + sitemap.xmap with + original + Forrest 0.4 sitemap.
  6. + +
+
+ + +

Version-specific sitemaps

+
+

+ Forrest 0.5 now supports version-specific sitemaps. Ie., if + your project's overridden sitemap is called + sitemap-0.5.xmap, then this sitemap will be used in + preference to sitemap.xmap, or any other sitemap-*.xmap + variants. +

+

+ So if, for example, one has: +

+
+        src/documentation/sitemap.xmap
+        src/documentation/sitemap-0.5.xmap
+      
+

+ Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use + sitemap-0.5.xmap. This means users don't need to all upgrade to 0.5 at + once. +

+

+ As Forrest 0.5 has been split into multiple sitemaps, this + version-specific behaviour is triggered for any *-0.5.xmap file. For + example, if one has: +

+
+        src/documentation/sitemap.xmap
+        src/documentation/forrest-0.5.xmap
+      
+

+ Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use + Forrest's own sitemap.xmap, plus the user-defined forrest-0.5.xmap file. +

+

+ The same system prevents future compatibility problems, so Forrest 0.5 + should continue to work when future (incompatible) sitemaps are present: +

+
+        src/documentation/sitemap.xmap
+        src/documentation/sitemap-0.5.xmap
+        src/documentation/sitemap-0.6.xmap
+        src/documentation/sitemap-0.7.xmap
+      
+
+
Note
+
+ If your forrest.properties defines the + forrest.validate.sitemap.{includes,excludes} properties, + these will have to be updated to prevent validation of sitemaps from + unused versions. If undefined, Forrest will only validate sitemaps from + the current version. +
+
+
+ + +

Excluding URLs: filterlinks.xsl removed and cli.xconf added

+
+

+ In Forrest 0.4 certain URLs could be excluded from command-line + processing by overriding and editing filterlinks.xsl and so + excluding the link nodes. +

+

+ Forrest 0.5 uses the re-written command-line from Cocoon 2.1.1 which, + apart from being much faster, does not use + filterlinks.xsl. Instead, patterns for command-line inclusion + and exclusion can be specified in cli.xconf, as described in + this FAQ entry. There is + already a default cli.xconf but you can over-ride that with your own if + needed by copying resources/conf/cli.xconf from the Forrest + distribution into your project's top-level directory. +

+
+ + +

Skin invocation changes

+
+

+ Users with custom skins may need to update them, depending on + what use they make of passed-in XSLT parameters. If your custom skin + does not appear to work with 0.5, look in Forrest's + sitemap.xmap for occurrences of + {forrest:forrest.skin}, and check that the callee (your + XSLT) is expecting what the caller (the sitemap) is passing it. Forrest + skins can be used as a reference. +

+
+ + +

Upgrading skinconf.xml

+
+

+ Look at the + differences + for the sample skinconf.xml as a guide. You will need to update + the internal DTD and add several new elements. +

+
+ + +

Upgrading forrest.properties

+
+

+ Look at the + differences + for the sample forrest.properties as a guide. Note that + project.sitemap has changed to project.sitemap-dir and note that + cli.xconf now controls some settings that were previously controlled by + forrest.properties, such as project.start-uri +

+
+ + +

Run a clean target after upgrade

+
+

+ To avoid any issue with old classes being loaded, run a 'forrest + clean' just after you upgraded to this version. +

+
+ + +

SVGs should omit DOCTYPE declarations

+
+
+
Fixme (forrest-dev)
+
+ Is this note still relevant? +
+
+

+ In Forrest 0.5, sites that render SVGs may encounter + ClassCastExceptions: +

+
+javax.xml.transform.TransformerException: java.lang.ClassCastException
+    at org.apache.xalan.transformer.TransformerImpl.transformNode(TransformerImpl.java:1326)
+    at org.apache.xalan.transformer.TransformerImpl.run(TransformerImpl.java:3329)
+...
+

+ There appears to be a bug in Cocoon 2.1.1's SVG component where the DTD + associated with SVGs cannot be resolved. The workaround is to edit your + src/documentation/resources/images/*.svg files, and comment + out the <!DOCTYPE ... > declaration. +

+
+ + +

To be continued...

+
+

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

+
+ + + version 1.8 +
+ +
 
+
+ + + Propchange: forrest/site/trash/docs_0_50/upgrading_05.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/trash/docs_0_70/upgrading_07.html URL: http://svn.apache.org/viewvc/forrest/site/trash/docs_0_70/upgrading_07.html?rev=1068306&view=auto ============================================================================== --- forrest/site/trash/docs_0_70/upgrading_07.html (added) +++ forrest/site/trash/docs_0_70/upgrading_07.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,439 @@ + + + + + + + +Upgrading to Apache Forrest 0.7 + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Upgrading to Apache Forrest 0.7

+ + + +

Introduction

+
+

+ This page describes some changes to Apache Forrest that affect people + who are upgrading to the 0.7 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.6 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 change log). +

+
    + +
  • Plugin architecture
  • + +
  • Java 1.4
  • + +
+

+ As usual, do a "forrest seed site" in a new directory and compare the + forrest.properties and skinconf.xml with that of your project. +

+
+ + +

Run a clean target after upgrade

+
+

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

+
+ + +

New location of $FORREST_HOME

+
+

+ $FORREST_HOME is now the top-level of the distribution. Also make sure + $PATH gets updated to use the new $FORREST_HOME/bin +

+
+ + +

Java 1.4 (or newer) is required

+
+

+ Java 1.4 (or newer) is required, starting with this Forrest 0.7 version. + For further information, see + FAQ. +

+
+ + +

General upgrade tips

+
+

+ 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. +

+
+ + +

Plugin architecture

+
+

+ See Plugin Infrastructure and + Extending Forrest with Plugins and for + developing new plugins see How + to Build a Plugin. See the list of + current plugins and their + documentation. +

+

+ Note that other experimental plugins can be found in the + "whiteboard/plugins" directory. +

+
+ + +

Configure plugins

+
+

+ Some functionality has been moved out of the forrest core and into + plugins. You will need to declare any plugins that are used by your + project, e.g. if you use projectInfo (status, changes, todo) and PDF + output, then declare the following in forrest.properties +

+
+project.required.plugins=org.apache.forrest.plugin.input.projectInfo,org.apache.forrest.plugin.output.pdf
+      
+
+ + +

Including raw un-processed content

+
+

+ The method for including "raw un-processed content" has changed. +

+

+ In 0.6 version, the raw content was placed in the + src/documentation/content/ directory and potential sub-directories. In + the generated site, these links would automatically function. Any linked + file with .html extension was not processed and not adorned with Forrest + skin and navigation menus. +

+

+ It was also possible to place HTML content in the xdocs directory where + it would be copied across if it was linked from the main content. +

+

+ In 0.7 version, any file that is linked to, needs to be placed in the + content/xdocs/ directory structure. Any linked file with .html extension + is now processed and is adorned with Forrest skin and navigation menus. +

+

+ If you you wish to emulate the behaviour of 0.6 and earlier then you + must add the following to your project sitemap. +

+
+<map:match pattern="**.html">
+ <map:select type="exists">
+  <map:when test="{properties:content}{0}">
+    <map:read src="{properties:content}/{0}" mime-type="text/html"/>
+    <!--
+      Use this instead if you want JTidy to clean up your HTML
+      <map:generate type="html" src="{properties:content}/{0}" />
+      <map:serialize type="html"/>
+    -->
+  </map:when>
+  <map:when test="{properties:content.xdocs}{0}">
+    <map:read src="{properties:content.xdocs}/{0}" mime-type="text/html"/>
+    <!--
+      Use this instead if you want JTidy to clean up your HTML
+      <map:generate type="html" src="{properties:content.xdocs}/{0}" />
+      <map:serialize type="html"/>
+    -->
+  </map:when>
+ </map:select>
+</map:match>
+        
+

+ If you need to include files that are not linked to, then place them in + the src/documentation/content/ directories as with the 0.6 version. +

+
+ + +

To be continued...

+
+

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

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/trash/docs_0_70/upgrading_07.html ------------------------------------------------------------------------------ svn:eol-style = native