You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2006/02/09 01:26:32 UTC
svn commit: r376128 [17/34] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/
docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/
docs_0_80/ docs_0_80/howto/ docs_0_80/howt...
Added: forrest/site/docs_0_80/howto/forrest.xmap.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/forrest.xmap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/forrest.xmap.source.xml (added)
+++ forrest/site/docs_0_80/howto/forrest.xmap.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,306 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><document><header> <!-- <meta content="HTML Tidy, see www.w3.org" name="generator"/> --> <title>Annotated forrest.xmap</title></header><body><section><title>forrest.xmap</title><pre>
+<?xml version="1.0"?>
+<!-- ===============================================
+Pipelines defining all Source XML types Forrest can handle.
+Converts from arbitrary formats to standard Forrest doc-v12 XML.
+
+First, determines if a simple format file exists.
+Candidates are: .html .ihtml .txt .sxw .jspwiki
+
+Otherwise, the default *.xml handling is used. The XML's DTD type is
+discovered using the SourceTypeAction, and an appropriate transformation
+applied. Thus to add new XML types, just define a new <sourcetype>
+and an appropriate <map:when> handler.
+
+Generates : Source XML, Body HTML for *.ehtml
+Example URL: http://localhost:8888/index.xml
+Used by : *.html and *.pdf pipelines in sitemap.xmap
+Uses : content/xdocs/**.xml
+
+$Revision: 1.8 $
+==================================================== -->
+
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:components>
+ <map:generators default="file">
+ <map:generator name="html" src="org.apache.cocoon.generation.HTMLGenerator">
+ <jtidy-config>WEB-INF/jtidy.properties</jtidy-config>
+ </map:generator>
+ <map:generator name="text2xml" logger="sitemap.generator.textgenerator"
+ src="org.apache.cocoon.generation.TextGenerator">
+ <parameter name="localizable" value="true"/>
+ </map:generator>
+ <map:generator name="exception"
+ src="org.apache.cocoon.generation.ParseExceptionGenerator"/>
+
+ </map:generators>
+ <map:serializers default="html"/>
+ <map:matchers default="wildcard"/>
+
+ <map:transformers default="xslt">
+ <map:transformer name="pattern"
+ src="org.apache.cocoon.transformation.PatternTransformer"
+ logger="sitemap.transformer.pattern">
+ <parameter name="groups" value="true"/>
+ </map:transformer>
+ <map:transformer name="lexer"
+ src="org.apache.cocoon.transformation.LexicalTransformer"
+ logger="sitemap.transformer.lexer">
+ <parameter name="localizable" value="true"/>
+ </map:transformer>
+ <map:transformer name="parser"
+ src="org.apache.cocoon.transformation.ParserTransformer"
+ logger="sitemap.transformer.parser">
+ <parameter name="flatten" value="true"/>
+ <parameter name="recovery" value="true"/>
+ <parameter name="localizable" value="true"/>
+ </map:transformer>
+
+ <map:transformer name="extparser"
+ src="org.apache.cocoon.transformation.ExtendedParserTransformer"
+ logger="sitemap.transformer.extendedparser">
+ </map:transformer>
+ </map:transformers>
+
+ <map:actions>
+ <map:action logger="sitemap.action.sourcetype" name="sourcetype" src="org.apache.forrest.sourcetype.SourceTypeAction">
+ <sourcetype name="document-v10">
+ <document-declaration public-id="-//APACHE//DTD Documentation V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="howto-v10">
+ <document-declaration public-id="-//APACHE//DTD How-to V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="todo-v10">
+ <document-declaration public-id="-//APACHE//DTD Todo V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="changes-v10">
+ <document-declaration public-id="-//APACHE//DTD Changes V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="document-v11">
+ <document-declaration public-id="-//APACHE//DTD Documentation V1.1//EN" />
+ </sourcetype>
+ <sourcetype name="howto-v11">
+ <document-declaration public-id="-//APACHE//DTD How-to V1.1//EN" />
+ </sourcetype>
+ <sourcetype name="todo-v11">
+ <document-declaration public-id="-//APACHE//DTD Todo V1.1//EN" />
+ </sourcetype>
+ <sourcetype name="changes-v11">
+ <document-declaration public-id="-//APACHE//DTD Changes V1.1//EN" />
+ </sourcetype>
+ <sourcetype name="todo-v12">
+ <document-declaration public-id="-//APACHE//DTD Todo V1.2//EN" />
+ </sourcetype>
+ <sourcetype name="changes-v12">
+ <document-declaration public-id="-//APACHE//DTD Changes V1.2//EN" />
+ </sourcetype>
+ <sourcetype name="howto-v12">
+ <document-declaration public-id="-//APACHE//DTD How-to V1.2//EN" />
+ </sourcetype>
+ <sourcetype name="todo-v13">
+ <document-declaration public-id="-//APACHE//DTD Todo V1.3//EN" />
+ </sourcetype>
+ <sourcetype name="changes-v13">
+ <document-declaration public-id="-//APACHE//DTD Changes V1.3//EN" />
+ </sourcetype>
+ <sourcetype name="howto-v13">
+ <document-declaration public-id="-//APACHE//DTD How-to V1.3//EN" />
+ </sourcetype>
+ <sourcetype name="document-v20a">
+ <document-declaration public-id="-//APACHE//DTD Documentation V2.0a//EN" />
+ </sourcetype>
+ <sourcetype name="document-v20">
+ <document-declaration public-id="-//APACHE//DTD Documentation V2.0//EN" />
+ </sourcetype>
+ <sourcetype name="todo-v20">
+ <document-declaration public-id="-//APACHE//DTD Todo V2.0//EN" />
+ </sourcetype>
+ <sourcetype name="changes-v20">
+ <document-declaration public-id="-//APACHE//DTD Changes V2.0//EN" />
+ </sourcetype>
+ <sourcetype name="howto-v20">
+ <document-declaration public-id="-//APACHE//DTD How-to V2.0//EN" />
+ </sourcetype>
+ </map:action>
+ <map:action logger="sitemap.action.locale" name="locale" src="org.apache.cocoon.acting.LocaleAction">
+ </map:action>
+ </map:actions>
+ <map:selectors default="parameter">
+ <map:selector logger="sitemap.selector.parameter" name="parameter" src="org.apache.cocoon.selection.ParameterSelector" />
+ <map:selector logger="sitemap.selector.exception" name="exception"
+ src="org.apache.cocoon.selection.ExceptionSelector">
+ <exception name="syntax" class="net.sourceforge.chaperon.process.ParseException"/>
+ <exception class="java.lang.Throwable" unroll="true"/>
+ </map:selector>
+ <map:selector logger="sitemap.selector.config" name="config" src="org.apache.cocoon.selection.SimpleSelector" />
+ </map:selectors>
+ </map:components>
+
+ <map:resources>
+ <map:resource name="transform-to-document">
+ <map:act type="sourcetype" src="{src}">
+ <map:select type="parameter">
+ <map:parameter name="parameter-selector-test" value="{sourcetype}" />
+
+ <map:when test="document-v10">
+ <!-- FIXME (JJP): This should use the v12 now-->
+ <map:transform src="{forrest:stylesheets}/docv10todocv11.xsl" />
+ </map:when>
+
+ <map:when test="document-v20a">
+ <map:transform src="{forrest:stylesheets}/docv20todocv12.xsl" />
+ </map:when>
+
+ <map:when test="document-v20">
+ <map:transform src="{forrest:stylesheets}/docv20todocv13.xsl" />
+ </map:when>
+
+ <map:when test="howto-v10">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+
+ <map:when test="howto-v11">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+ <map:when test="howto-v12">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+ <map:when test="howto-v13">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+ <map:when test="howto-v20">
+ <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+ </map:when>
+
+ <map:when test="todo-v10">
+ <map:transform src="{forrest:stylesheets}/todo2document.xsl" />
+ </map:when>
+
+ <map:when test="todo-v11">
+ <map:transform src="{forrest:stylesheets}/todo2document.xsl" />
+ </map:when>
+
+ <map:when test="todo-v12">
+ <map:transform src="{forrest:stylesheets}/todo2document.xsl" />
+ </map:when>
+
+ <map:when test="todo-v13">
+ <map:transform src="{forrest:stylesheets}/todo2document.xsl" />
+ </map:when>
+
+ <map:when test="todo-v20">
+ <map:transform src="{forrest:stylesheets}/todo2document.xsl" />
+ </map:when>
+
+ <map:when test="changes-v10">
+ <map:transform src="{forrest:stylesheets}/changesv10tochangesv11.xsl" />
+ <map:transform src="{forrest:stylesheets}/changes2document.xsl" />
+ </map:when>
+
+ <map:when test="changes-v11">
+ <map:transform src="{forrest:stylesheets}/changes2document.xsl" />
+ </map:when>
+
+ <map:when test="changes-v12">
+ <map:transform src="{forrest:stylesheets}/changes2document.xsl" />
+ </map:when>
+
+ <map:when test="changes-v13">
+ <map:transform src="{forrest:stylesheets}/changes2document.xsl" />
+ </map:when>
+
+ <map:when test="changes-v20">
+ <map:transform src="{forrest:stylesheets}/changes2document.xsl" />
+ </map:when>
+ <map:otherwise />
+ </map:select>
+ </map:act>
+ </map:resource>
+</pre><section><title>Definition of File-Resolver-Resource</title><pre>
+ <map:resource name="file-resolver">
+ <map:select type="exists">
+ <map:when test="{project:content.xdocs}{uri}.ihtml">
+ <map:generate src="{project:content.xdocs}{uri}.ihtml" type="html" />
+ <map:transform src="{forrest:stylesheets}/html2document.xsl" />
+ <map:transform type="idgen" />
+ <map:serialize type="xml-document"/>
+ </map:when>
+ <map:when test="{project:content.xdocs}{uri}.html">
+ <map:generate src="{project:content.xdocs}{uri}.html" type="html" />
+ <map:transform src="{forrest:stylesheets}/html2document.xsl" />
+ <map:transform type="idgen" />
+ <map:serialize type="xml-document"/>
+ </map:when>
+ <map:when test="{project:content.xdocs}{uri}.txt">
+ <map:match type="regexp" pattern="^(.*?)([^/]*).xml$">
+ <map:generate type="text2xml" src="{project:content.xdocs}{1}{2}.txt" />
+ <map:transform src="{forrest:stylesheets}/text2document.xsl">
+ <map:parameter name="filename" value="{2}" />
+ </map:transform>
+ <map:serialize type="xml-document"/>
+ </map:match>
+ </map:when>
+ <map:otherwise>
+
+ <map:select type="exists">
+ <map:when test="{project:temp-dir}/input.xmap">
+ <map:mount uri-prefix=""
+ src="{project:temp-dir}/input.xmap"
+ check-reload="yes"
+ pass-through="true"/>
+ </map:when>
+ </map:select>
+
+ <map:generate src="{project:content.xdocs}{uri}.xml" />
+ <map:call resource="transform-to-document">
+ <map:parameter name="src" value="{project:content.xdocs}{uri}.xml" />
+ </map:call>
+ <map:serialize type="xml-document"/>
+ </map:otherwise>
+ </map:select>
+ </map:resource>
+ </map:resources>
+
+ <map:pipelines>
+ <map:pipeline>
+
+ <!-- ============================================================ -->
+ <!-- INTERMEDIATE FORMATS -->
+ <!-- ============================================================ -->
+
+ <map:match pattern="**body-*.html">
+ <map:select type="exists">
+ <map:when test="{project:content.xdocs}{1}{2}.ehtml">
+ <map:generate src="{project:content.xdocs}{1}{2}.ehtml" />
+ <map:transform src="{forrest:stylesheets}/html2htmlbody.xsl" />
+ <map:serialize type="xml" />
+ </map:when>
+ </map:select>
+ </map:match>
+
+ <!-- ============================================================ -->
+ <!-- SOURCE FORMATS -->
+ <!-- ============================================================ -->
+</pre></section><section><title>Second Match for '**.xml'</title><pre>
+ <map:match pattern="**.xml">
+ <map:select type="config">
+ <map:parameter name="value" value="{defaults:i18n}"/>
+ <map:when test="true">
+ <map:act type="locale">
+ <map:call resource="file-resolver">
+ <map:parameter name="uri" value="{../1}_{language}"/>
+ </map:call>
+ </map:act>
+ </map:when>
+ <map:otherwise>
+ <map:call resource="file-resolver">
+ <map:parameter name="uri" value="{1}"/>
+ </map:call>
+ </map:otherwise>
+ </map:select>
+ </map:match>
+
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+</pre></section></section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/howto/forrest.xmap.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/howto/howto-asf-mirror.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-asf-mirror.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-asf-mirror.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-asf-mirror.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>Generate an ASF mirrors page using interactive web form</title>
+
+ <abstract>Include html form elements
+ into a forrest-generated html page. For example, this enables building
+ automated download mirror pages for ASF project websites.
+ </abstract>
+
+ <last-modified-content-date date="2005-04-20"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <ul>
+ <li>Any Apache project that uses Forrest to generate their website
+ will need to have a mirrors page.</li>
+ <li>Also anyone interested in the use of embedding html form
+ elements into a generated Forrest page.</li>
+ </ul>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>All Apache projects use dynamically generated download pages
+ which determine the closest mirror and provide an interactive list of
+ the current alternative mirrors.
+ This HowTo describes the procedure to generate the template page
+ that is utilised by the mirrors.cgi script.
+ </p>
+ <p>The mirrors.cgi and mirrors.html are "extra" documents,
+ i.e. have no links from anywhere in the site. So we explain
+ how to process additional files.
+ </p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <ul>
+ <li>Followed the documentation about
+ <link href="http://www.apache.org/~bodewig/mirror.html">Making your
+ downloads mirrorable</link> and
+ <link href="http://www.apache.org/dev/mirrors.html">Apache Mirroring Information</link>
+ .
+ </li>
+ <li>Established your ASF distribution space as described.</li>
+ <li>Already building your project website with Forrest.</li>
+ </ul>
+ </section><section id="Steps"><title>Steps</title>
+ <section id="cgi">
+ <title>Add the mirrors.cgi as a raw file</title>
+ <p>As explained in the mirrors document, there will be a two-line CGI
+ wrapper script at the top-level of your website called
+ <code>mirrors.cgi</code></p>
+ <p>Utilising the Forrest concept of raw un-processed content,
+ add the file as <code>src/documentation/mirrors.cgi</code>
+ (copy the Forrest project's
+ <link href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/mirrors.cgi">mirrors.cgi</link>)
+ </p>
+ </section>
+
+ <section id="html">
+ <title>Add the mirrors.html to xdocs directory</title>
+ <p>This file contains the html content of your mirror page, including
+ the html form elements which drive the mirror selection. It also
+ contains the specific tokens that are interpreted by the mirrors.cgi
+ script to add the list of mirrors and select the closest.
+ </p>
+ <p>
+ Add the file as <code>src/documentation/xdocs/mirrors.html</code>
+ (Use the Forrest project's
+ <link href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/mirrors.html">mirrors.html</link>
+ as a template and edit it to suit.)
+ </p>
+ <p>
+ Note that the special tokens (e.g. [if-any http] [for http]) need to
+ be encompassed by xml comments.
+ </p>
+ </section>
+
+ <section id="menu">
+ <title>Add a menu entry for Download</title>
+ <p>Add an entry to your site.xml navigation. For example ...
+ </p>
+ <source xml:space="preserve">
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
+ <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
+ ...</source>
+ </section>
+
+ <section id="link">
+ <title>Cause the mirrors.html to be processed as an extra file</title>
+ <p>Forrest gathers the links that are to be crawled, by reading site.xml
+ and by finding any other internal links in the actual documents.
+ There is no link to mirrors.html because it is an extra file that needs
+ to be generated and skinned, but not linked in any way.
+ </p>
+ <p>The Cocoon command-line interface
+ (<link href="http://cocoon.apache.org/2.1/userdocs/offline/">CLI</link>)
+ to the rescue. Add an entry to your project's cli.xconf by copying the
+ default one from
+ <code>$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</code> to your
+ <code>src/documentation/conf/</code> directory (or wherever
+ ${forrest.conf-dir} points). Add the following entry ...
+ </p>
+ <source xml:space="preserve">
+<uris name="mirrors" follow-links="false">
+ <uri type="append" src="mirrors.html"/>
+</uris></source>
+ </section>
+
+ <section id="forrest">
+ <title>Run 'forrest' to build your site</title>
+ <p>
+ That is all that you need to do, Forrest will take care of it from
+ there. Run the '<code>forrest</code>' command. The mirrors.html page
+ will be generated with the skin applied.
+ </p>
+<note>
+Due to Issue
+<link href="http://issues.apache.org/jira/browse/FOR-480">FOR-480</link>,
+the generated mirror.html will end up in forrest/main/site/mirrors.html
+rather than in the project's build directory.
+</note>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/howto/howto-asf-mirror.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/howto/howto-buildPlugin.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-buildPlugin.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-buildPlugin.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-buildPlugin.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,467 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2006 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to Build a Plugin</title>
+
+ <version>0.2.1</version>
+
+ <abstract>This How-To describes the steps necessary to build a plugin for
+ Forrest. Forrest uses plugins to add new input formats, output formats
+ and to change its default behaviour. Since plugins are downloaded when
+ needed and can be hosted at any location, plugin code can be developed
+ independently of Apache Forrest. This how-to describes each of the major
+ steps in creating a plugin and then works through some examples of
+ plugin creation in order to illustrate the materials.</abstract>
+
+ <last-modified-content-date date="2005-04-12"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <p>Users needing to add additional input formats or output formats or
+ to change the operation of the Forrest internals.</p>
+
+ <warning>The Plugin Infrastructure is still at an early stage of design
+ and implementation, consequently this How-To <em>may</em> be out of date
+ and/or incomplete. If you are having problems with any of the steps
+ described, please ask for help on the developers mailing list (and then
+ provide patches for this document).</warning>
+ <warning>Please make sure that you are using forrest 0.7 if you want use
+ plugins. Forrest 0.6 will not work!!!</warning>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>This How-To will illustrate how to build a plugin, publish a plugin
+ and configure a Forrest project to use their plugin.</p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <p>Plugin developers should have:</p>
+
+ <ul>
+ <li>a basic knowledge of XML, XSLT and Cocoon pipelines</li>
+ <li>a clear use-case for extending Forrest</li>
+ <li>read
+ <a href="site:plugins/infrastructure">Plugin Infrastructure</a>
+ </li>
+ <li>verified with the Apache Forrest developer community that the
+ required functionality does not already exist</li>
+ </ul>
+ </section><section id="Steps"><title>Steps</title>
+ <p>Here is how to proceed.</p>
+
+ <section id="typeOfPlugin">
+ <title>Type of Plugin</title>
+
+ <p>There are three types of plugin, each with a clear purpose, you
+ must first decide which
+ <a href="site:plugins/infrastructure">type of plugin</a>
+ you need to build.</p>
+
+ </section>
+
+ <section id="ant">
+ <title>Make ant available on the command-line</title>
+ <p>
+ The following instructions rely heavily on
+ <a href="http://ant.apache.org/">Apache Ant</a>
+ to automate some steps in the process. Since ant
+ is distributed as part of Forrest, all you need to do
+ is add the ant executable directory to your system path. The
+ name of this directory is <code>tools/ant/bin</code>
+ in your Forrest program directory.
+ (Alternatively you can prefix all calls to ant in
+ the following instructions with the full path of the ant binary directory.)
+ Also clear the ANT_HOME environment variable.
+ </p>
+ <p>
+ If instead you really want to use your own version of Ant,
+ then you will need to copy
+ forrest/lib/core/xml-commons-resolver.jar
+ to $ANT_HOME/lib directory, otherwise your plugins will go across
+ the network to get the DTDs on every parse.
+ </p>
+ </section>
+
+ <section id="seed">
+ <title>Seed a New Plugin</title>
+ <p>Regardless of the type of plugin you are building, the directory
+ structure is almost identical, as are most of the required
+ configuration files. In this How-To we will assume that you are creating a
+ plugin in the Forrest source tree. All plugins are developed in the
+ <code>forrest/plugins</code> directory or the
+ <code>forrest/whiteboard/plugins</code> directory.</p>
+
+ <p class="instruction">Run the following set of commands:</p>
+
+ <source xml:space="preserve">
+ cd [path_to_forrest]/whiteboard/plugins
+ ant seedPlugin
+ </source>
+
+ <p>The above ant target will ask you the name of the plugin and some
+ additional information such as a brief description and will
+ build a minimal plugin directory structure and configuration. You will
+ need to customise these files to build your plugin.</p>
+
+ <note>Although you can name your project anything you like we do have
+ some <a href="site:plugins/infrastructure">naming
+ conventions</a> that we recommend you follow. Plugins intended to be
+ held at forrest.apache.org must follow the naming convention.</note>
+
+ <note>If you plan on building your plugin elsewhere you can copy the
+ <code>build.xml</code> build file to your own plugin work directory and
+ use it there.</note>
+
+ <p>See
+ <a href="site:plugins/infrastructure">Plugin
+ Infrastructure</a> for more information about the plugin
+ directory structure and configuration files.</p>
+
+ <section id="edit-template">
+ <title>Edit the Plugin Template</title>
+ <p>You now have a skeleton plugin project. However, it doesn't do
+ anything useful yet. Now is a good time to edit some of the files
+ provided.</p>
+
+ <p>Here are some general notes:</p>
+
+ <section id="status">
+ <title>status.xml</title>
+ <p>This file is used to track changes to the plugin
+ project and to manage lists of things that still need to be done.
+ At this stage you should correct the <code>person</code> entry
+ near the top of the file. It is also a good idea to add a few key
+ milestones in the task list towards the bottom of the file.</p>
+
+ <p>As you work on the plugin you should record all major changes in
+ this file so that it can then be used as a changelog for your
+ plugin.</p>
+ </section>
+
+ <section id="forrest-properties">
+ <title>forrest.properties</title>
+
+ <p>This file defines many configuration parameters for Forrest. It
+ does not need to be customised in most cases. However, see
+ for more details.</p>
+ </section>
+
+ <section id="skinconf">
+ <title>src/documentation/skinconf.xml</title>
+ <p>This configures the skin for your plugins documentation. There
+ are some items that need to be configured in here, for example, the
+ copyright information. The file is heavily commented so probably
+ best to read through it, changing what you need to.</p>
+ </section>
+
+ <section id="doc">
+ <title>Documentation</title>
+ <p>It is also a good idea to start writing the documentation at this
+ stage. The above process created a very simple plugin documentation
+ site for you. All you have to do is add the content.</p>
+ </section>
+
+ <section id="hosted">
+ <title>Style notes for plugins hosted at forrest.apache.org</title>
+ <p>
+ After seeding a new plugin, copy the configuration from an
+ existing plugin (e.g. org.apache.forrest.plugin.input.projectInfo).
+ Copy src/documentation/skinconf.xml (and edit to suit) and
+ src/documentation/content/xdocs/images/project-logo.gif
+ </p>
+ </section>
+ </section>
+ </section>
+
+ <section id="edit-sitemap">
+ <title>Edit the Plugin sitemap file(s)</title>
+ <p>The plugin <code>xmap</code> file is a Cocoon sitemap that is mounted
+ at a strategic place in the Forrest pipeline. It is in this file
+ that you will instruct Forrest how to operate. An input plugin
+ must provide a <code>input.xmap</code> file, an output plugin
+ must provide a <code>output.xmap</code> file, whilst an internal
+ plugin provides a <code>internal.xmap</code> file. In addition, an
+ input plugin may provide a <code>resources.xmap</code> file to
+ allow the plugin to handle items such as JavaScript files.</p>
+
+ <note>All input plugins should allow the original source to be retrieved
+ by requesting the document with a <code>*.source.xml</code> extension. So
+ you should ensure that you provide such a match.</note>
+
+ <p>It is beyond the scope of this How-To to give details about how to
+ build your plugins XMap. See the
+ <a href="site:v0.80//documentation/developers/sitemap-ref">Sitemap Reference</a> for general
+ information. See also
+ <a href="site:plugins/infrastructure">Plugin Infrastructure</a>
+ for some hints and tips on creating plugin sitemaps. In addition, as with
+ all development work on Forrest, you will find
+ the <a href="site:mail-lists/forrest-dev">developer mailing list</a>
+ a very good resource (check the archives before posting, please).</p>
+
+ <section id="components">
+ <title>Components, Actions and Resources</title>
+ <p>If your plugin uses any components (i.e. generators, transformers or
+ serializers), actions or resources they must
+ be defined in either the xmap for this plugin or one of its parents. The parents
+ of an <code>input.xmap</code> are <code>sitemap.xmap</code> and
+ <code>forrest.xmap</code>, whilst the parent of both
+ <code>output.xmap</code> and <code>internal.xmap</code> are
+ <code>sitemap.xmap</code></p>
+ <p>If you want to use the realpath where the sitemap.xmap of your plugin
+ resides then you need to use
+ <code>{forrest:plugins}/PLUGIN_NAME</code> instead of <code>{realpath:/}</code>.
+ </p>
+ <p>See the examples below for more details.</p>
+ </section>
+ </section>
+
+ <section id="resources">
+ <title>Create the Necessary Resource Files</title>
+ <fixme author="rdg">Discuss the XSL files and other such resources</fixme>
+ </section>
+
+ <section id="samples">
+ <title>Create Samples in the Documentation</title>
+ <p>Plugin documentation should provide (as a minimum) an
+ index page that provides an overview and a set of samples that demonstrate
+ the functionality of the plugin. Typically these samples will be
+ provided in a <code>samples</code> subdirectory in the plugin
+ documentation and will be referenced from both <code>site.xml</code>
+ and <code>tabs.xml</code> configuration files.</p>
+
+ <p>Try to provide a sample for all the major functions of your plugin
+ and document any configuration that is available.</p>
+ </section>
+
+ <section id="test">
+ <title>Testing a Plugin</title>
+
+ <p>Since your documentation for the plugin illustrates all of its
+ functionality, you can use that site for testing the plugin. However, you
+ must first deploy in your local install of Forrest. Each plugin contains
+ a buildfile that includes a <code>test</code> target. This target, by
+ default, builds the documentation for your plugin.</p>
+
+ <p class="instruction">Run the command <code>ant test</code> in
+ the plugins directory.</p>
+
+ <p>Of course, the build should complete without errors.</p>
+
+ <note>You can also use <code>forrest run</code> to interactively examine
+ your documentation (point your browser at
+ <a href="http://localhost:8888">http://localhost:8888</a>).</note>
+
+ <p>It is also a really good idea to build proper tests for your
+ plugins using a suitable testing framework, for example,
+ <a href="http://webtest.canoo.com/">WebTest</a>. We recommend that you
+ extend the <code>test</code> target in your plugins build file because
+ this target is also used when performing integration tests on Forrest.
+ In addition, we recommend that you use the samples in your documentation
+ for your tests, this way you are documenting your plugin at the same time
+ as writing your tests.</p>
+
+ <p>Ensure that your sitemaps are robust and handle matches for files
+ in sub-directories, as well as those at the root level.</p>
+
+ <section>
+ <title>Testing During Development</title>
+ <p>In the current plugin system plugins are not used from their
+ src directories, they must first be deployed locally. To do this
+ run the command <code>ant local-deploy</code>.</p>
+
+ <note>The test target will do this deployment automatically for you.
+ You need only run it manually if you wish to test the plugin whilst
+ editing content in a live Forrest instance.</note>
+
+ <p>In most cases you can locally deploy a plugin without having to
+ restart Forrest. However, if your plugin changes any configuration
+ files in the <code>conf</code> directory you will, most likely, have
+ to restart Forrest to see these changes.</p>
+ </section>
+ </section>
+
+ <section id="release">
+ <title>Releasing a Plugin</title>
+
+ <section id="register">
+ <title>Register the Plugin with Apache Forrest</title>
+ <fixme author="rdg">Describe making a request of Forrest devs for
+ inclusion</fixme>
+ </section>
+
+ <section id="deploy">
+ <title>Deploying the Plugin</title>
+ <p>To deploy the plugin so that others can use it, it must be made
+ available as a zip from the URL indicated in the
+ <code>plugins.xml</code> file. The plugins build file provides targets
+ to assist with this task.</p>
+
+ <p class="instruction">To deploy a plugin simply run the command
+ <code>ant deploy</code> from within the plugin directory.</p>
+
+ <p>This command will, by default, deploy to the Apache Forrest web site.
+ In order to do this you need commit access to Forrest. If you want to
+ deploy your plugin to a different location you
+ can build the zip of your plugin with <code>ant dist</code>
+ and then copy the zip file from <code>build/dist</code> to wherever
+ you intend to host the plugin.</p>
+
+ <note>Running this command on any plugin will also deploy any
+ changes to the <code>plugins.xml</code> file. If you are deploying to
+ your own website you will have to request changes to the
+ <code>plugins.xml</code> and ask the Forrest committers to publish the new
+ document.</note>
+
+ <warning>Running the <code>deploy</code> or <code>dist</code> targets
+ will always run the <code>test</code> target first. This is to ensure
+ that you only deploy working plugins. This adds a little time to
+ the deploy cycle, but we feel the peace of mind is worth it.</warning>
+
+ </section>
+
+ <section id="descriptor">
+ <title>Managing the plugins descriptors</title>
+ <p>
+ The files plugins/plugins.xml and whiteboard/plugins/plugins.xml are
+ the "Plugins Descriptor" files. Each plugin is described with its
+ name, purpose, location, and version information. These descriptors
+ are deployed to the forrest website so that your application can
+ manage its plugins.
+ </p>
+ <p>
+ The Apache Forrest committers manage these files in SVN and publish
+ them as needed. Here are some notes.
+ </p>
+ <p>
+ When a plugin gains new functionality, then it will be dependent on
+ a more recent version of Forrest. Deploy the plugin one final time
+ before implementing the new work. For example, if current release
+ is 0.7 then ...
+ </p>
+ <ul>
+ <li>Review the docs and ensure any version numbers in text are "0.7"</li>
+ <li>Edit the skinconf.xml to ensure that all version numbers are "0.7", e.g. the MOTD.</li>
+ <li>Edit the plugins descriptor to ensure that the "forrestVersion" is 0.7 and that the "version" is appropriate. </li>
+ <li>Ensure that the "website" parameter includes "pluginDocs/plugins_0_70"</li>
+ <li>Edit status.xml to set the release date. Ensure that the changes notes are complete.</li>
+ </ul>
+ <p>
+ Now the plugin gains functionality that binds it to 0.8-dev
+ (e.g. converted to use locationmap) so ...
+ </p>
+ <ul>
+ <li>Review the docs and ensure any version numbers in text are
+ "0.8"</li>
+ <li>Edit the skinconf.xml to ensure that all version numbers are
+ "0.8-dev", e.g. the MOTD.</li>
+ <li>Edit the plugins descriptor to ensure that the "forrestVersion" is
+ 0.8 and that the "version" is incremented. </li>
+ <li>Ensure that the "website" parameter includes "pluginDocs/plugins_0_80"</li>
+ <li>Edit status.xml to add a new section and set the release date.
+ Start adding changes notes.</li>
+ </ul>
+ </section>
+ </section>
+
+ <section id="experimental">
+ <title>Experimental Functionality</title>
+ <warning>This section describes functionality that is considered experimental.
+ This functionality may be defective and is not part of the official release at
+ this time, use at your own risk. If you do choose to use this functionality then
+ we recomend that you join the Forrest dev list in order to keep abreast of the
+ changes as they occur.</warning>
+
+ <note>For an example of each of these features in use see the
+ <code>org.apache.forrest.internal.NoteTaking</code> plugin.</note>
+
+ <section>
+ <title>Locationmap</title>
+
+ <p>Plugins can use the Forrest locationmap to expose resources to your
+ project and other plgins. To use this functionality add your
+ <code>locationmap.xml</code> file to the root of the plugin directory.</p>
+
+ <p>We have an <a href="http://issues.apache.org/jira/browse/FOR-200">issue</a>
+ for the status of locationmap development.</p>
+ </section>
+
+ <section>
+ <title>Dispatcher</title>
+ <p>Dispatcher (previous codename Forrest Views) is the collective name for the various pieces of functionality
+ that are intended to replace skins in the future. They allow for a much more
+ configurable system of defining the contents and look and feel of a site.</p>
+
+ <p>Plugins can expose contracts for use in structurer files used within
+ Dispatcher-based sites. In order to do this you should develop your contracts
+ as normal and place them in <code>PLUGIN_HOME/resources/themes</code>. However,
+ this, by itself, is not sufficient to export your contracts. You will also need to
+ add the following match to your plugin's <code>locationmap.xml</code> file:</p>
+
+ <source xml:space="preserve">
+ <match pattern="resolvePluginContract.*.**">
+ <select type="exists">
+ <location src="{forrest:plugins}/PLUGIN_NAME/resources/themes/{project:theme}/{1}/{2}.ft" />
+ </select>
+ </match>
+ </source>
+
+ <p>Of course, you should replace <code>PLUGIN_NAME</code> with the name of
+ your plugin.</p>
+
+ <p>Once Dispatcher becomes stable we will add this match to the default locationmap
+ which is generated when you seed a new plugin, but for now it must be done manually.</p>
+ </section>
+
+ <section>
+ <title>Plugin Properties</title>
+ <p>Plugins can define properties that each project can over-ride.
+ For more information see the issue below.</p>
+
+ <p>We have an <a href="http://issues.apache.org/jira/browse/FOR-588">issue</a>
+ for the status of this new configuration system.</p>
+ </section>
+ </section>
+
+ <section id="examples">
+ <title>Examples</title>
+ <p>This section will provide some example plugins to help illustrate the
+ steps discussed above.</p>
+ <section id="input">
+ <title>Input Plugin</title>
+ <fixme author="RDG">Discuss OpenOffice.org plugin here</fixme>
+ </section>
+
+ <section id="output">
+ <title>Output Plugin</title>
+ <fixme author="RDG">Discuss s5 plugin here</fixme>
+ </section>
+
+ <section id="internal">
+ <title>Internal Plugin</title>
+ <fixme author="RDG">Discuss IMSManifest plugin here</fixme>
+ </section>
+ </section>
+
+ <section id="extension">
+ <title>Further Reading</title>
+
+ <ul>
+ <li><a href="site:plugins/infrastructure">Plugin Infrastructure Documentation</a> for Developers</li>
+ <li><a href="site:plugins">Plugins Documentation</a> for users</li>
+ </ul>
+ </section>
+
+ <section id="summarise">
+ <title>Summarise the Entire Process</title>
+
+ <fixme author="open">In a few sentences, remind the reader what they have just learned.
+ This helps to reinforce the main points of your How-To.</fixme>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/howto/howto-buildPlugin.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/howto/howto-corner-images.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-corner-images.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-corner-images.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-corner-images.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to modify the color of generated corner images</title>
+ <abstract>
+ This How-To describes how to modify the corner images that appear in
+ the menu and tabs of the skins.
+ </abstract>
+ <last-modified-content-date date="2004-11-05"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <p>
+ Users who want to change the colors of the corner images in the
+ output html documents.
+ </p>
+ <p>
+ This explanation is also useful for skin developers to understand
+ the corner image generation process.
+ </p>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>
+ Forrest renders the corner images through
+ <a href="http://www.w3.org/TR/SVG/">Scalable Vector Graphics (SVG)</a>.
+ It may be necessary to change the color of
+ the corner images to be suitable for your own skin colors.
+ </p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <ul>
+ <li>Understand how to use the skinconf.xml file to change the appearance
+ of the output documents.</li>
+ <li>Understand how to create or modify skins by following the
+ <a href="site:v0.80//your-project">Using Forrest</a> document
+ (topic "<a href="site:v0.80//your-project/skins">Forrest skins</a>").</li>
+ </ul>
+ </section><section id="Steps"><title>Steps</title>
+ <p>
+ The procedure outlined below provides an understanding of how corner
+ images are named (the contract) and then shows how to define new
+ colors for these images by modifying the
+ <code>src/documentation/skinconf.xml</code> of a project.
+ </p>
+ <section id="css-files">
+ <title>Understand how corner images are named (the contract)</title>
+ <p>
+ The corner images are referenced in some .css files of the
+ above-named skins; for example, in screen.css of the pelt skin:
+ </p>
+ <source xml:space="preserve">
+/*Example from screen.css of pelt*/
+...
+/**
+* Round corner
+*/
+#roundtop {
+ background-image: url(images/rc-t-r-15-1body-2menu-3menu.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+...
+ </source>
+ <p>
+ The naming follows a contract which is described below. In general,
+ the naming looks like:
+ </p>
+ <source xml:space="preserve">
+images/{$name}-{$v-orientation}-{$h-orientation}-{$size}-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}
+ </source>
+ <p>
+ The first part
+ (<code>images/{$name}-{$v-orientation}-{$h-orientation}-{$size}</code>)
+ identifies which images is used and how big (width x height) it should
+ be. The second part\
+ (<code>-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}</code>)
+ identifies the coloring of each portion of the image. The input
+ parameter for the second part comes from the color profile of
+ <code>src/documentation/skinconf.xml</code>. The second part is
+ easily identifiable through the numbering 1-2-3.
+ </p>
+ <p>
+ Let us get into details:
+ </p>
+ <dl>
+ <dt><code>images</code></dt>
+ <dd>
+ Path to the xslt that creates the corner.
+ <br/>
+ <code>images/ = {$FORREST_HOME}/main/webapp/skins/common/images/</code>
+ </dd>
+ <dt><code>{$name}</code></dt>
+ <dd>
+ In the common skin there are two XSLT files ready for use:
+ <ul>
+ <li>
+ <code>rc.svg.xslt</code>: handles rounded corners
+ </li>
+ <li>
+ <code>dc.svg.xslt</code>: handles diagonal 45-degree corners
+ </li>
+ </ul>
+ <code>name = [rc|dc]</code>
+ <br/>
+ <em>e.g.</em> <code>rc</code>
+ </dd>
+ <dt><code>{$v-orientation}</code></dt>
+ <dd>
+ Vertical orientation of the corner images (top or bottom).
+ <br/>
+ <code>v-orientation = [t|b]</code>
+ <br/>
+ <em>e.g.</em> <code>t</code>
+ </dd>
+ <dt><code>{$h-orientation}</code></dt>
+ <dd>
+ Horizontal orientation of the corner images (left or right).
+ <br/>
+ <code>h-orientation = [l|r]</code>
+ <br/>
+ <em>e.g.</em> <code>r</code>
+ </dd>
+ <dt><code>{$size}</code></dt>
+ <dd>
+ Pixels size of the width <strong>and</strong> height of the corner image.
+ <br/>
+ <code>size=x</code>
+ <br/>
+ <em>e.g.</em> <code>5</code>
+ </dd>
+ <dt><code>{$backgroundColor}</code></dt>
+ <dd>
+ Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
+ attribute will be applied).
+ <br/>
+ <em>e.g.</em> <code>header</code>
+ </dd>
+ <dt><code>{$strokeColor}</code></dt>
+ <dd>
+ Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
+ attribute will be applied).
+ <br/>
+ <em>e.g.</em> <code>searchbox</code>
+ </dd>
+ <dt><code>{$foregroundColor}</code></dt>
+ <dd>
+ Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
+ attribute will be applied).
+ <br/>
+ <em>e.g.</em> <code>searchbox</code>
+ </dd>
+ </dl>
+ </section>
+ <section id="skinconfig">
+ <title>Modifying the skinconf.xml of your project</title>
+ <p>
+ modifying the <code>skinconf.xml</code> of your project (by
+ default you find it at <code>[project-dir]/src/documentation/</code>).
+ </p>
+ <p>
+ Starting about line 155 you find a <code><colors></code>
+ ... <code></colors></code> element with content commented-out:
+ </p>
+ <source xml:space="preserve">
+<colors>
+<!-- These values are used for the generated CSS files. -->
+
+<!-- Krysalis -->
+<!--
+ <color name="header" value="#FFFFFF"/>
+
+ <color name="tab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/>
+ <color name="tab-unselected" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/>
+ <color name="subtab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/>
+ <color name="subtab-unselected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/>
+
+...
+
+-->
+
+</colors>
+ </source>
+ <p>
+ To modify the colors of the corner images, you can either define
+ your own <code><color name=.../></code> elements or uncomment
+ one of the existing <code><color name=.../></code> elements
+ and adjust the color value to your needs.
+ </p>
+ <p>
+ <em>e.g.</em>
+ </p>
+ <source xml:space="preserve">
+<color name="tab-selected" value="#FF0000"/>
+ </source>
+ <p>
+ This affects all corner images whose <code>{$backgroundColor}</code>, <code>{$strokeColor}</code> or
+ <code>{$foregroundColor}</code> is set to <code>tab-selected</code>.
+ <br/>
+ For example, in <code>screen.css</code> (of the "pelt" skin) you find:
+ </p>
+ <source xml:space="preserve">
+#roundbottomsmall {
+ background-image: url(images/rc-b-r-5-1header-2tab-selected-3tab-selected.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+ </source>
+ <p>
+ Now the stroke color (<code>-2tab-selected</code>) and the foreground
+ color (<code>-3tab-selected</code>) are set to red (remember: we
+ defined <code>#FF0000</code> as the "color" value of
+ <code>tab-selected</code>).
+ </p>
+ </section>
+ <section id="css_modify">
+ <title>Modifying .css files</title>
+ <p>
+ In addition to the modification of <code>skinconf.xml</code>
+ you can also modify the respective .css file of your skin.
+ </p>
+ <p>
+ Here's another example:
+ </p>
+ <source xml:space="preserve">
+/*your .css file*/
+...
+#roundbottomsmall {
+ background-image: url(images/rc-b-r-5-1<em>foo</em>-2<em>secondfoo</em>-3<em>thirdfoo</em>.png);
+ background-repeat: no-repeat;
+ background-position: top right;
+}
+...
+ </source>
+ <source xml:space="preserve">
+<!-- your skinconf.xml -->
+...
+<colors>
+ <color name="<em>foo</em>" value="#FF0000"/>
+ <color name="<em>secondfoo</em>" value="#00FF00"/>
+ <color name="<em>thirdfoo</em>" value="##00FF00"/>
+</colors>
+ </source>
+ <p>
+ Here we have created our own color tags (in the .css file) and
+ defined the respective values for them (in <code>skinconf.xml</code>).
+ Now you have color images with a red background and a green
+ foreground. Horrible, isn't it?
+ </p>
+ </section>
+ </section><section id="Feedback"><title>Feedback</title>
+ <p>
+ Please provide feedback about this document via the
+ <a href="site:mail-lists">mailing lists</a>.
+ </p>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/howto/howto-corner-images.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/howto/howto-custom-html-source.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-custom-html-source.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-custom-html-source.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-custom-html-source.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,707 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to customize processing of html source</title>
+ <abstract>
+ Explains how to do additional processing of html source documents.
+ </abstract>
+ <last-modified-content-date date="2005-03-23"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <p>
+ Users who want to integrate HTML-pages that require custom
+ adjustments and everybody who wants to learn more about Forrest's
+ pipelines in general.
+ </p>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>
+ Integrating legacy HTML pages is a common task when migrating
+ existing websites to Forrest. This document explains how to implement
+ custom processing which is required when Forrest's standard pipeline
+ for html does not suffice.
+ </p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <p>To follow these instructions you will need:</p>
+ <ol>
+ <li>
+ Know how to use a
+ <a href="site:v0.80//project-sitemap">project sitemap</a>.
+ </li>
+ <li>
+ A basic understanding of coocons pipelines and their
+ components. You should know about matchers, generators,
+ transformers and serializers and have a rough idea how they work
+ together in a pipeline ( A good place to start learning about Cocoon is <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">
+ Understanding Apache Cocoon</a>).
+ </li>
+ <li>
+ If you want to follow the examples right through your
+ Forrest, a current version of Forrest installed on your
+ system and read-access to Forrest's program directory is
+ necessary.
+ </li>
+ <li>
+ If you plan on creating your own custom processing for
+ html-pages, you'll also need write access to your
+ project directory.
+ </li>
+ </ol>
+ </section><section id="Understanding the HTML-Pipeline"><title>Understanding the HTML-Pipeline</title>
+ <p>
+ The first part of this howto explains the html pipeline, so as to
+ provide the background to enable you to add additional processing
+ for legacy html documents. If you already know how pipelines work,
+ then skip to the section about
+ <a href="#custom">Customizing the html pipeline</a>.
+ </p>
+
+ <section id="example">
+ <title>Driven by Example</title>
+ <p>
+ The best way to learn about Forrest pipelines is follow
+ the processing of an imaginary request through the forrest
+ machinery.
+ </p>
+ <p>
+ So let's see what happens, when a client asks Forrest to
+ serve the document
+ <br/>
+ 'http://some.domain.org/mytest/mybad.html'.
+ </p>
+ </section>
+
+ <section id="sitemap">
+ <title>Finding the Sitemap</title>
+
+ <p>
+ Like all applications based on Apache Cocoon, each request for
+ a given document is processed by searching a sitemap for a
+ matching processing pipeline. With Forrest, this core sitemap
+ is found in the file
+ 'main/webapp/sitemap.xmap' in Forrest's program directory.
+ </p>
+
+ <p class="instruction">
+ Open the file 'main/webapp/sitemap.xmap' in Forrest's
+ program directory with a text editor of your choice.
+ </p>
+ <note>
+ Any simple text editor will suffice, since the XML in
+ this file is quite simple in structure and easy to read.
+ </note>
+
+ <p>
+ To help you to easily follow the next steps, we have added
+ comments and anchors to 'sitemap.xmap',
+ so that you can quickly jump to all relevant sections
+ and read them more easily.
+ </p>
+
+ <p class="instruction">
+ Follow this link to the
+ <a href="sitemap.xmap.html#Start+of+Sitemap">
+ start of the Sitemap.
+ </a>
+ </p>
+
+ <p>
+ As the comment explains, this sitemap is the starting point
+ for all requests. So even if there are other sitemaps
+ (which we will see later on), we always start looking for a
+ matching pattern right here.
+ </p>
+ </section>
+
+ <section id="pipelines">
+ <title>Find the Beginning of the Pipelines Section</title>
+
+ <p>
+ Modular as everything else in Cocoon, Forrest's sitemap
+ starts with a long list of declarations for all the
+ components used later on. We can safely ignore these at
+ the moment.
+ </p>
+ <p class="instruction">
+ So let's skip right to the start of the
+ Pipelines-Section. Search for <map:pipelines> or
+ follow this link to the
+ <a href="sitemap.xmap.html#Start+of+Pipelines">
+ beginning of the pipelines-element
+ </a>
+ </p>
+
+ <p>
+ Within the pipelines-element you will find a long list
+ of pipeline-Elements (no trailing 's'), each one of them defining a
+ processing pipeline within Forrest.
+ </p>
+
+ <p>
+ When handling a request, Forrest will check the
+ Pipelines from top to bottom until it encounters a
+ Pipeline that will take care of our request.
+ </p>
+ </section>
+
+ <section id="matches">
+ <title>Looking for a Match</title>
+
+ <p>
+ Like all Cocoon applications, Forrest knows which
+ pipeline to use for processing a certain request by
+ looking at the entry criteria for each pipeline it comes
+ across. These can be a match against a given pattern,
+ the test if a certain files exists or one of many other
+ possible tests that Cocoon supports.
+ </p>
+
+ <p class="instruction">
+ To better know what we are talking about, let's follow
+ Forrest down the list to the
+ <a href="sitemap.xmap.html#Test+for+First+Pipeline">
+ Test for the First Pipeline
+ </a>.
+ </p>
+
+ <p>
+ Here you can see that very specialized matches need to occur
+ early in the sitemap. The
+ requested file (and pathname) is compared to a pattern
+ '*.xlex' that would match if our request ended with
+ '.xlex' and had no pathname. Since it doesn't, we don't
+ have a match and need to keep looking.
+ </p>
+
+ <p class="instruction">
+ Skip forward until we find the
+ <a href="sitemap.xmap.html#First+Match+for+%22**%2F*.html%22">
+ First Match for "**/*.html"
+ </a>
+ (<map:match pattern="**/*.html">).
+ </p>
+ </section>
+
+ <section id="html-pipeline">
+ <title>Processing in the '**/*.html' Pipeline</title>
+ <p>
+ Let's take a quick look at this pipeline to understand
+ what's happening here:
+ </p>
+<source xml:space="preserve">
+<map:match pattern="**/*.html">
+ <map:aggregate element="site">
+ <map:part src="cocoon:/skinconf.xml"/>
+ <map:part src="cocoon:/build-info"/>
+ <map:part src="cocoon:/{1}/tab-{2}.html"/>
+ <map:part src="cocoon:/{1}/menu-{2}.html"/>
+ <map:part src="cocoon:/{1}/body-{2}.html"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ <map:parameter name="path" value="{0}"/>
+ </map:call>
+</map:match></source>
+ <p>
+ In the first part of this pipeline, the
+ aggregate-element assembles information required to build
+ a Forrest page with menu and tabs from different sources.
+ Then the call to the skinit-resource picks up the
+ aggregated info and generates a page in the
+ style of the current skin. That's easy, isn't it?
+ </p>
+ <p>
+ Well, the complex part begins, when we take a closer look at
+ the sources of the aggregation.
+ </p>
+ <source xml:space="preserve"><map:part src="cocoon:/{1}/body-{2}.html"/></source>
+ <p>
+ This mysterious element is most easily explained as a
+ secondary request to the Forrest system.
+ </p>
+ <p>
+ The 'cocoon:'-part is called a pseudo-protocol and tells the
+ processor to ask Forrest for the resource named behind
+ the colon, process that request and feed the output as input
+ back into our pipeline.
+ (The 'pseudo' goes back to the fact that unlike
+ 'http' or 'ftp', which are real protocols, you can use cocoon:
+ only within the cocoon environments as only they will know what to
+ do with it.)
+ </p>
+ <p>
+ So even though we have already seen the end of our pipeline
+ (the skinning), we still don't know, what goes into the skinning and
+ where it comes from. To find out, we have to look at the sources
+ of the aggregation.
+ </p>
+ </section>
+
+ <section id="protocols">
+ <title>Following the Pseudo-Protocols</title>
+ <p>
+ To find out what goes into our aggregation, we'll need to look
+ at the pipeline that is called by
+ </p>
+ <source xml:space="preserve"><map:part src="cocoon:/{1}/body-{2}.html"/></source>
+ <p>
+ To do that, it's always a good idea to write down what this
+ call actually looks like when all the variables are replaced by real
+ values.
+ A safe way to do that is to look at the matcher to start with,
+ build a list of the numbered variables and their meaning in the
+ current context and then assemble the actual expression(s) from it.
+ </p>
+
+ <p>In our example the matcher pattern
+ <code>**/*.html</code> is applied to the request-name
+ <code>mytest/mybad.html</code>, so we have three variables
+ altogether:
+ </p>
+ <table>
+ <tr>
+ <td colspan="1" rowspan="1">%0</td>
+ <td colspan="1" rowspan="1">mytest/mybad.html</td>
+ <td colspan="1" rowspan="1">the whole pathname</td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">%1</td>
+ <td colspan="1" rowspan="1">mytest/</td>
+ <td colspan="1" rowspan="1">the first match</td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">%2</td>
+ <td colspan="1" rowspan="1">mybad</td>
+ <td colspan="1" rowspan="1">the second match</td>
+ </tr>
+ </table>
+ <p>If we insert that into </p>
+ <source xml:space="preserve"><map:part src="cocoon:/{1}/body-{2}.html"/></source>
+ <p>we get</p>
+ <source xml:space="preserve"><map:part src="cocoon:/mytest/body-mybad.html"/></source>
+ <p>
+ As you can easily tell, we are suddenly calling for a whole
+ new document. Let's see where that takes us:
+ </p>
+ </section>
+ <section id="call">
+ <title>Second Call for Content</title>
+ <p>
+ Processing of cocoon-calls is not much different from
+ normal requests by a client. When you launch a call like
+ </p>
+ <source xml:space="preserve"><map:part src="cocoon:/mytest/body-mybad.html"/></source>
+ <p>
+ Forrest will once again start searching its main sitemap
+ from the beginning and look for a pipeline to match that call.
+ </p>
+
+ <p class="instruction">
+ Search for '**body-*.html' from the beginning of the
+ sitemap or jump to the
+ <a href="sitemap.xmap.html#First+Match+for+%27**body-*.html%27">First Match for '**body-*.html'</a>
+ to see where we find our next match.
+ </p>
+ </section>
+ <section id="match-1">
+ <title>First Match for '**body-*.html'</title>
+ <p>
+ Our first match is different to the previous ones because
+ there is a second condition placed inside the matcher.
+ Doing the replacements
+ </p>
+<source xml:space="preserve">
+<map:select type="exists">
+ <map:when test="{project:content.xdocs}mytests/mybad.ehtml"></source>
+ <p>
+ we quickly discover that there can't be a file of
+ that name in the project-directory.
+ <br/>
+ (The variable '{project:content.xdocs}' is always replaced with
+ the name of your project directory that you can change
+ in the 'forrest.properties'-file.)
+ </p>
+ <p>
+ So we have a pipeline, but it doesn't do anything.
+ In this case Forrest will simply keep looking for
+ the next match further down.
+ </p>
+ </section>
+ <section id="match-2">
+ <title>Second Match for '**body-*.html'</title>
+ <p class="instruction">
+ Continue searching downwards for '**body-*.html' in the
+ sitemap-file or jump directly to the
+ <a href="sitemap.xmap.html#Second+Match+for+%27**body-*.html%27">Second Match for '**body-*.html'</a>.
+ </p>
+ <p>
+ Looking at the pipeline that handles the request, we see that
+ the cocoon-protocol is once again invoked
+ </p>
+ <source xml:space="preserve"><map:generate src="cocoon:/{1}{2}.xml"/></source>
+ <p>
+ this time as a direct generator of input for our pipeline.
+ </p>
+ <p>
+ So once again we ask Forrest to process a request for content.
+ To know what matcher to look for, let's first expand the variables:
+ </p>
+ <p>
+ In our example the matcher pattern
+ <code>**body-*.html</code> is applied to the request-name
+ <code>mytest/body-mybad.html</code>.
+ Which means that we have three variables altogether:
+ </p>
+ <table>
+ <tr>
+ <td colspan="1" rowspan="1">%0</td>
+ <td colspan="1" rowspan="1">mytest/body-mybad.html</td>
+ <td colspan="1" rowspan="1">the whole pathname</td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">%1</td>
+ <td colspan="1" rowspan="1">mytests/</td>
+ <td colspan="1" rowspan="1">the first match</td>
+ </tr>
+ <tr>
+ <td colspan="1" rowspan="1">%2</td>
+ <td colspan="1" rowspan="1">mybad</td>
+ <td colspan="1" rowspan="1">the second match</td>
+ </tr>
+ </table>
+ <p>
+ If we insert that into
+ </p>
+ <source xml:space="preserve"><map:generate src="cocoon:/{1}{2}.xml"/></source>
+ <p>
+ we get
+ </p>
+ <source xml:space="preserve"><map:generate src="cocoon:/mytests/mybad.xml"/></source>
+ </section>
+ <section id="match-3">
+ <title>Third Call for Content</title>
+ <p class="instruction">
+ So let's scan the main sitemap looking for a match for
+ '/mytests/mybad.xml'.
+ </p>
+ <p>
+ We find it in the pattern
+ <a href="sitemap.xmap.html#First+Match+for+%27**.xml%27">'**.xml'></a>,
+ which is the standard handling for all xml-requests.
+ </p>
+ <p>
+ Since our request fulfils none of the secondary criteria in
+ this pipeline, it falls right through to the map:mount-element
+ at the end:
+ </p>
+ <source xml:space="preserve"><map:mount uri-prefix="" src="forrest.xmap" check-reload="yes" /></source>
+ <p>
+ which makes Forrest load and process a secondary sitemap,
+ the file 'forrest.xmap' in the same directory.
+ </p>
+ <p class="instruction">
+ Open the file 'forrest.xmap' and continue the search for a
+ matching pattern.
+ </p>
+ <p>
+ Our search leads us to the
+ <a href="forrest.xmap.html#Second+Match+for+%27**.xml%27">
+ Second Match for '**.xml'
+ </a>,
+ a pipeline designed to handle internationalisation if that
+ feature is configured. Since it is not, all it does is
+ call the file-resolver-resource with the full pathname of
+ our file but no extension.
+ </p>
+<source xml:space="preserve">
+<map:call resource="file-resolver">
+ <map:parameter name="uri" value="mytests/mybad"/>
+</map:call></source>
+ </section>
+ <section id="file">
+ <title>Introducing the File-Resolver</title>
+ <p class="instruction">
+ To find out more about the working of the file-resolver,
+ search for the definition of the
+ <a href="forrest.xmap.html#Definition+of+File-Resolver-Resource">
+ <map:resource name="file-resolver">
+ </a>
+ higher up in the file.
+ </p>
+ <p>
+ Here you will find a pipeline that tests for the existence of
+ the file with different extensions. '.html' is second in this
+ list and leads to the processing steps shown below:
+ </p>
+ </section>
+
+ <section id="process-html">
+ <title>html-Default Processing</title>
+ <p>
+ The default processing of html-files consists of four
+ processing steps:
+ </p>
+ <ol>
+ <li>
+ <code><map:generate src="{project:content.xdocs}{uri}.html" type="html"/></code><br/>
+ Using the html-generator, Forrest reads the html-document
+ from file and uses JTidy to clean up and convert it to xml
+ (which is required for all processing in cocoon pipelines).
+ At the output of this transformer we will have a valid
+ XHTML-document althought it might still contain some unwanted
+ elements. We'll deal with those later (see
+ <a href="site:v0.80//howto/custom-html-source">When to customize</a>).
+ </li>
+ <li>
+ <code><map:transform src="{forrest:stylesheets}/html2document.xsl"/></code><br/>
+ Using the standard stylesheet 'html2document.xsl', this XHTML is
+ transformed into Forrest standard document format.
+ </li>
+ <li>
+ <code><map:transform type="idgen"/></code><br/>
+ This step generates IDs required for navigation within the page.
+ </li>
+ <li>
+ <code><map:serialize type="xml-document"/></code><br/>
+ Finally the document is serialized as XML and returned to the
+ calling pipeline.
+ </li>
+ </ol>
+ <p>
+ As a result, we now hand back the content of the html-document
+ in Forrest standard document format to the calling pipeline
+ </p>
+ <note>
+ To look at the output of this pipeline you can simply
+ point you browser to 'http://localhost:8888/mytest/mybad.xml'
+ (assuming that you are currently running Forrest on your
+ machine and there is an html-page of that name).
+ </note>
+ </section>
+ <section id="body">
+ <title>Returning to the '**body-*.html'-Pipeline</title>
+ <p>
+ On returning into the
+ <a href="sitemap.xmap.html#Returning+to+the+%27**body-*.html%27+Pipeline">'**body-*.html' pipeline</a>,
+ procesing continues with the next components in this pipeline:
+ </p>
+ <ul>
+ <li>
+ <strong>idgen</strong> will generate unique IDs for all elements
+ that need to be referenced within a page (mainly headlines).
+ </li>
+ <li>
+ <strong>xinclude</strong> would process any xinclude statements
+ in the source.
+ Since HTML does not support this mechanism, nothing happens
+ in our example.
+ </li>
+ <li>
+ <strong>linkrewriter</strong> adjusts links between pages
+ so that they will still work in the final Forrest output
+ directory structure. It also resolves any special Forrest links.
+ </li>
+ <li>
+ The final transformation, as the name suggests, will take
+ care of reporting broken site-links.
+ </li>
+ <li>
+ The call to 'skinit' prepares the page body for presentation
+ within the selected skin.
+ </li>
+ </ul>
+ <note>
+ To look at the output of this pipeline you can simply
+ point you browser to 'http://localhost:8888/mytest/body-mybad.html'
+ (assuming that you are currently running Forrest on your machine
+ and there is an html-page of that name).
+ </note>
+ </section>
+
+ <section id="aggregate">
+ <title>Returning to the '**/*.html'-Pipeline</title>
+ <p>
+ At the end of this pipeline, processing returns the results into
+ the aggregation section of the
+ <a href="#html-pipeline">'**/*.html' Pipeline</a>,
+ merges it with other data, skins and serializes for presentation
+ in the requesting client.
+ </p>
+ </section>
+
+ <section id="custom">
+ <title>Customizing the html pipeline</title>
+ <p>
+ In this last part of this document, we will show how to customize the
+ HTML-pipeline to add your additional steps to the default processing.
+ </p>
+
+ <section id="when">
+ <title>When to customize?</title>
+
+ <p>
+ The html-Pipeline in Forrest is designed to be able to also
+ integrate legacy html-Pages in a Forrest project. In doing so,
+ it will fix common markup errors and convert html to Forrest's
+ intermediate document format.
+ </p>
+ <p>
+ Due to the nature of html as presentational markup, there is no way
+ this automated process can identify elements in your pages that
+ are not required or even unwanted in the Forrest environment.
+ </p>
+ <p>
+ A good example are pages from sites where the navigational elements
+ (menus, tabs etc.) are embedded in the html of each page.
+ Since Forrest can't know what is an unwanted menu and what belongs
+ to the page body that you want to keep, you will need to customize
+ the process to remove elements that are not needed. If you don't,
+ then you will see the original page from your legacy website,
+ menu and all, embedded in your new Forrest site.
+ </p>
+ </section>
+
+ <section id="how">
+ <title>How to customize?</title>
+ <p>
+ To add your own custom processing for a group of pages, you will
+ create a project sitemap with pipelines that process documents
+ according to your specifications.
+ </p>
+ <p>
+ This project sitemap is located in the file
+ 'src/documentation/sitemap.xmap' in your Forrest project directory
+ and will be created automatically when you seed a new project.
+ At this point it contains only one
+ <a href="project_sitemap.xmap.html#Example+pipeline+for+%27**custom.xml%27">
+ pipeline for handling the '**custom.xml'-pattern</a> as an example.
+ </p>
+ <p>
+ To add your own custom processing, edit the file and add a new
+ pipeline to the project sitemap. Since the project sitemap is
+ loaded into the main sitemap
+ <a href="sitemap.xmap.html#Insertion+Point+for+Project+Sitemap">
+ right at the top</a>, your pipeline intercepts practically all
+ of Forrest's standard pipelines.
+ </p>
+ </section>
+
+ <section id="what">
+ <title>What to intercept?</title>
+ <p>
+ Where to intercept standard processing is really a matter of your
+ choice. A good rule is to replace as little standard handling
+ as possible so that future changes in the Forrest architecture are
+ less likely to break your application.
+ </p>
+ <p>
+ In our case all we need to do is add a transformation that
+ removes all the unwanted elements. The best place to do this
+ would be right after the generator has converted our document to
+ xhtml.
+ </p>
+ <p>
+ However, since we can only replace a complete pipeline,
+ we'll create a new pipeline that intercepts **.xml for our pages,
+ copy the steps the original processor is doing and add a
+ transformation of our own to it.
+ </p>
+ </section>
+ <section id="intercept">
+ <title>Intercept pattern</title>
+ <p>
+ Take great care when intercepting very basic pipelines.
+ Instead of designing our custom pipeline to match the
+ original **.xml pattern, try to narrow your matcher down to
+ something that will only match your pages.
+ </p>
+ <p>
+ If all your pages are located in a directory called mytest,
+ then use a matcher like '/mytest/*.xml' to avoid highjacking
+ the processing for all the other requests.
+ </p>
+ <p class="instruction">
+ Add a new pipeline in your project sitemap and set the matcher
+ to '/mytest/*.xml'.
+ </p>
+ <p>
+ The new pipeline should look like this and does nothing so far.
+ </p>
+<source xml:space="preserve">
+<!--Custom Pipeline for my bad html-pages-->
+<map:pipeline>
+ <map:match pattern="mytest/*.xml">
+
+ </map:match>
+</map:pipeline></source>
+ <p class="instruction">
+ Open the 'forrest.xmap', navigate to the file-resolver-section,
+ copy the four lines for handling *.html files and paste them into
+ your new pipeline.
+ </p>
+
+<source xml:space="preserve">
+<!--Custom Pipeline for my bad html-pages-->
+<map:pipeline>
+ <map:match pattern="mytest/*.xml">
+ <map:generate src="{project:content.xdocs}{uri}.html" type="html"/>
+ <map:transform src="{forrest:stylesheets}/html2document.xsl"/>
+ <map:transform type="idgen"/>
+ <map:serialize type="xml-document"/>
+ </map:match>
+</map:pipeline></source>
+ <p>
+ Your custom pipeline will now behave exactly like the standard
+ html-handler. Now all that is left to be done is creating the
+ custom transformation and adding it the pipeline.
+ </p>
+ <p class="instruction">
+ Design and test a new XSL-Transformation that removes the
+ unwanted elements and save it in your project's stylesheet
+ directory, usually src/documentation/resources/stylesheets
+ (defined in project.stylesheets-dir of forrest.properties),
+ which is central storage for all stylesheets in a project.
+ </p>
+ <p class="instruction">
+ Add the new transformation as a new line, straight after the
+ generator, and save the changes.
+ </p>
+<source xml:space="preserve">
+<!--Custom Pipeline for my bad html-pages-->
+<map:pipeline>
+ <map:match pattern="mytest/*.xml">
+ <map:generate src="{project:content.xdocs}{uri}.html" type="html" />
+ <strong>
+ <map:transform src="{project:resources.stylesheets}/fixMyBadHTML.xsl"/>
+ </strong>
+ <map:transform src="{forrest:stylesheets}/html2document.xsl" />
+ <map:transform type="idgen" />
+ <map:serialize type="xml-document"/>
+ </map:match>
+</map:pipeline></source>
+ <p>
+ Done! You have just added your own custom-processing.
+ Don't forget to view the pages to verify that it is working
+ properly.
+ </p>
+ <note>
+ Our pipeline does not exactly do what the original pipeline does.
+ To make things easier, we omitted the internationalization part
+ in our pipeline. So if you need to create multi-language sites,
+ make sure that you adjust your pipeline accordingly.
+ </note>
+
+ </section>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/howto/howto-custom-html-source.source.xml
------------------------------------------------------------------------------
svn:eol-style = native