forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [9/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/howto...
Date Thu, 09 Feb 2006 00:26:32 GMT
Added: forrest/site/docs_0_70/howto/howto-asf-mirror.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-asf-mirror.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-asf-mirror.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-asf-mirror.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,141 @@
+<?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>
+<warning>
+Due to issue
+<link href="http://issues.apache.org/jira/browse/FOR-555">FOR-555</link>
+the html comments that the CGI script depends upon are stripped before
+the output stage. You need to manually add those comments.
+This is fixed in forrest_07_branch of SVN.
+</warning>
+  </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">
+ &lt;about label="About"&gt;
+  &lt;index label="Index" href="index.html"/&gt;
+  &lt;license label="License" href="license.html"/&gt;
+  &lt;download label="Download" href="http://forrest.apache.org/mirrors.cgi"/&gt;
+  &lt;download_html href="mirrors.html"/&gt;&lt;!-- so the page is part of a tab --&gt;
+  ...</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">
+&lt;uris name="mirrors" follow-links="false"&gt;
+  &lt;uri type="append" src="mirrors.html"/&gt;
+&lt;/uris&gt;</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_70/howto/howto-asf-mirror.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-buildPlugin.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-buildPlugin.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-buildPlugin.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-buildPlugin.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,349 @@
+<?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 Build a Plugin</title>
+
+    <version>0.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
+      requried 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 requried
+      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.</p>
+      
+      <p class="instruction">Run the following set of commands:</p>
+      
+      <source xml:space="preserve">
+      cd [path_to_forrest]/plugins
+      ant seedPlugin
+      </source>      
+      
+      <p>The above ant target will ask you the name of the plugin 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>
+
+        <note>
+          For plugins intended to be held at forrest.apache.org please
+          adjust the skinconf.xml etc to be in accordance with the other
+          forrest plugins. See <a href="#hosted">notes</a> below.
+        </note>
+
+        <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.apapche.org</title>
+          <p>
+            After seeding a new plugin, copy the configuration from an
+            exisiting plugin (e.g. org.apache.forrest.plugin.input.projectInfo).
+            Copy src/documentation/skinconf.xml 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>
+      
+      <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.70//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>
+    
+    <section id="release">
+      <title>Releasing a Plugin</title>
+    
+      <section id="register">
+        <title>Register the Plugin with Apache Forrest</title>
+        <fixme author="rdg">Describe the plugins.xml file</fixme>
+        <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 your 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>
+    
+    <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 Infrastrucuture 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="rdg">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_70/howto/howto-buildPlugin.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-corner-images.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-corner-images.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-corner-images.source.xml (added)
+++ forrest/site/docs_0_70/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.70//your-project">Using Forrest</a> document
+       (topic "<a href="site:v0.70//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>&lt;color name=""/&gt;</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>&lt;color name=""/&gt;</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>&lt;color name=""/&gt;</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>&lt;colors&gt;</code>
+        ... <code>&lt;/colors&gt;</code> element with content commented-out:
+      </p>
+      <source xml:space="preserve">
+&lt;colors&gt;
+&lt;!-- These values are used for the generated CSS files. --&gt;
+
+&lt;!-- Krysalis --&gt;
+&lt;!--
+  &lt;color name="header"    value="#FFFFFF"/&gt;
+
+  &lt;color name="tab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/&gt;
+  &lt;color name="tab-unselected" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/&gt;
+  &lt;color name="subtab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/&gt;
+  &lt;color name="subtab-unselected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/&gt;
+
+...
+
+--&gt;
+
+&lt;/colors&gt;
+      </source>
+      <p>
+        To modify the colors of the corner images, you can either define
+        your own <code>&lt;color name=.../&gt;</code> elements or uncomment
+        one of the existing <code>&lt;color name=.../&gt;</code> elements
+        and adjust the color value to your needs.
+      </p>
+      <p>
+        <em>e.g.</em>
+      </p>
+      <source xml:space="preserve">
+&lt;color name="tab-selected" value="#FF0000"/&gt;
+      </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">
+&lt;!-- your skinconf.xml --&gt;
+...
+&lt;colors&gt;
+  &lt;color name="<em>foo</em>" value="#FF0000"/&gt;
+  &lt;color name="<em>secondfoo</em>" value="#00FF00"/&gt;
+  &lt;color name="<em>thirdfoo</em>" value="##00FF00"/&gt;
+&lt;/colors&gt;
+      </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_70/howto/howto-corner-images.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-custom-html-source.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-custom-html-source.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-custom-html-source.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-custom-html-source.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,705 @@
+<?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.70//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 &lt;map:pipelines&gt; 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>
+        (&lt;map:match pattern="**/*.html"&gt;).
+      </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">
+&lt;map:match pattern="**/*.html"&gt;
+    &lt;map:aggregate element="site"&gt;
+      &lt;map:part src="cocoon:/skinconf.xml"/&gt;
+      &lt;map:part src="cocoon:/build-info"/&gt;
+      &lt;map:part src="cocoon:/{1}/tab-{2}.html"/&gt;
+      &lt;map:part src="cocoon:/{1}/menu-{2}.html"/&gt;
+      &lt;map:part src="cocoon:/{1}/body-{2}.html"/&gt;
+    &lt;/map:aggregate&gt;
+    &lt;map:call resource="skinit"&gt;
+      &lt;map:parameter name="type" value="site2xhtml"/&gt;
+      &lt;map:parameter name="path" value="{0}"/&gt;
+    &lt;/map:call&gt;
+&lt;/map:match&gt;</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">&lt;map:part src="cocoon:/{1}/body-{2}.html"/&gt;</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">&lt;map:part src="cocoon:/{1}/body-{2}.html"/&gt;</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">&lt;map:part src="cocoon:/{1}/body-{2}.html"/&gt;</source>
+      <p>we get</p>
+      <source xml:space="preserve">&lt;map:part src="cocoon:/mytest/body-mybad.html"/&gt;</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">&lt;map:part src="cocoon:/mytest/body-mybad.html"/&gt;</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">
+&lt;map:select type="exists"&gt;
+   &lt;map:when test="{project:content.xdocs}mytests/mybad.ehtml"&gt;</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">&lt;map:generate src="cocoon:/{1}{2}.xml"/&gt;</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">&lt;map:generate src="cocoon:/{1}{2}.xml"/&gt;</source>
+      <p>
+        we get
+      </p>
+      <source xml:space="preserve">&lt;map:generate src="cocoon:/mytests/mybad.xml"/&gt;</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'&gt;</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">&lt;map:mount uri-prefix="" src="forrest.xmap" check-reload="yes" /&gt;</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">
+&lt;map:call resource="file-resolver"&gt;
+  &lt;map:parameter name="uri" value="mytests/mybad"/&gt;
+&lt;/map:call&gt;</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">
+          &lt;map:resource name="file-resolver"&gt;
+        </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>&lt;map:generate src="{project:content.xdocs}{uri}.html" type="html"/&gt;</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.70//howto/custom-html-source">When to customize</a>).
+        </li>
+        <li>
+            <code>&lt;map:transform src="{forrest:stylesheets}/html2document.xsl"/&gt;</code><br/>
+          Using the standard stylesheet 'html2document.xsl', this XHTML is 
+          transformed into Forrest standard document format.
+        </li>
+        <li>
+          <code>&lt;map:transform type="idgen"/&gt;</code><br/>
+          This step generates IDs required for navigation within the page.
+        </li>
+        <li>
+          <code>&lt;map:serialize type="xml-document"/&gt;</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">
+&lt;!--Custom Pipeline for my bad html-pages--&gt;        
+&lt;map:pipeline&gt;
+    &lt;map:match pattern="mytest/*.xml"&gt;
+
+    &lt;/map:match&gt;
+&lt;/map:pipeline&gt;</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">
+&lt;!--Custom Pipeline for my bad html-pages--&gt;        
+&lt;map:pipeline&gt;
+    &lt;map:match pattern="mytest/*.xml"&gt;
+      &lt;map:generate src="{project:content.xdocs}{uri}.html" type="html"/&gt;
+      &lt;map:transform src="{forrest:stylesheets}/html2document.xsl"/&gt;
+      &lt;map:transform type="idgen"/&gt;
+      &lt;map:serialize type="xml-document"/&gt;
+    &lt;/map:match&gt;
+&lt;/map:pipeline&gt;</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">
+&lt;!--Custom Pipeline for my bad html-pages--&gt;        
+&lt;map:pipeline&gt;
+    &lt;map:match pattern="mytest/*.xml"&gt;
+      &lt;map:generate src="{project:content.xdocs}{uri}.html" type="html" /&gt;
+      &lt;strong&gt;&lt;map:transform src="{forrest:stylesheets}/fixMyBadHTML.xsl"/&gt;&lt;/strong&gt;
+      &lt;map:transform src="{forrest:stylesheets}/html2document.xsl" /&gt;
+      &lt;map:transform type="idgen" /&gt;
+      &lt;map:serialize type="xml-document"/&gt;
+    &lt;/map:match&gt;
+&lt;/map:pipeline&gt;</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_70/howto/howto-custom-html-source.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-editcss.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-editcss.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-editcss.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-editcss.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,122 @@
+<?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 Forrest CSS 
+      WYSIWYG-style</title>
+    <abstract> This How-To shows how to use Mozilla 
+      Firebird and the free EditCSS-Plugin to 
+      customize your Forrest design in a 
+      WYSIWYG-way.</abstract>
+    <last-modified-content-date date="2004-11-05"/>
+  </header><body><section id="Intended Audience"><title>Intended Audience</title>
+    <p> Users who want to customize the Forrest look 
+      and feel or simply experiment with changing 
+      certain CSS-styles settings to see what 
+      happens.</p>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p> A major part of Forrest's look and feel is 
+      controlled by a few CSS style sheets. Since 
+      Forrest allows you to override these settings, 
+      changing the CSS is a quick and easy 
+      alternative to creating (and maintaining) a 
+      whole new skin.</p>
+    <p> You'll learn how to use free tools to change 
+      and experiment with styles in a WYSIWYG way, so 
+      that you can immediately see what effect 
+      changing a CSS property will have on the 
+      look and feel of your Forrest.</p>
+
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <p>To follow these instructions you will need:</p>
+    <ol>
+      <li>Browser-access to the Forrest-site you want 
+        to experiment with. Starting with a new 'forrest seed' site is
+        good for your first attempt.
+        <note>You can even 
+        experiment with Forrest's core skins CSS. Please send patches if
+        you enhance something.
+        </note> </li>
+      <li>The current version of the free Mozilla 
+        Firefox-Browser installed on your system. 
+        If you don't already use it, you can 
+        download it from <a href="http://www.mozilla.org/products/firefox/">http://www.mozilla.org/products/firefox/</a> 
+        </li>
+
+      <li>The Firefox-PlugIn EditCSS. It downloads 
+        and installs in just a few seconds from the 
+        Install-Link at <a href="http://editcss.mozdev.org/">http://editcss.mozdev.org/</a> 
+        <note>With standard security settings in 
+        place, Firefox will pop up a line at the top 
+        of the window because this site has by 
+        default no permission to install plugins on 
+        your computer. Click "Edit Options" and 
+        then "Allow" to change that, then click on 
+        the Install-link again. Don't forget to 
+        close and restart Firebird when the
+        installation is finished.</note> </li>
+      <li>A basic understanding of CSS and access to 
+        a good CSS-reference. Tutorials and 
+        Reference can be found at <a href="http://www.htmlhelp.com/reference/css/">http://www.htmlhelp.com/reference/css/</a>.</li>
+    </ol>
+  </section><section id="Steps"><title>Steps</title>
+
+    <section id="openForrest">
+      <title>Open your Forrest</title>
+      <p class="instruction">Start your Firefox 
+        Browser and open the Forrest you'd like to 
+        work on/play with.</p>
+      <p>The page you have pointed to will show up in 
+        Firefox's main window.</p>
+    </section>
+    <section id="OpenEditCSS">
+      <title>Open the EditCSS-Sidebar</title>
+
+      <p class="instruction">Select 
+        View-Sidebar-EditCSS from Firefox's main 
+        menu to open the EditCSS sidebar.</p>
+      <p>The EditCSS sidebar will show next to the 
+        main window and load all the styles from 
+        the main page.</p>
+    </section>
+    <section id="changeCSS">
+      <title>Change any CSS</title>
+      <p class="instruction">Change any style you'd 
+        like to experiment with or add new settings 
+        and styles of your choice by simply 
+        editing the text of the sidebar.</p>
+      <p>EditCSS pushes any change you make in the 
+        sidebar right back into the style-settings 
+        of the main window, so that effects will 
+        show right away.</p>
+
+      <note>On slow systems or when inserting big 
+        changes it might be a good idea to paste 
+        these from the clipboard to avoid a zillion 
+        updates to the main windows for every 
+        character you type.</note>
+    </section>
+    <section id="saveChanges">
+      <title>How to save changes?</title>
+      <p>Since it takes a few explanations to apply 
+        the changes to your Forrest, I've made 
+        this the topic of yet another HowTo called 
+        "Howto change and extend Forrest-CSS"</p>
+    </section>
+  </section><section id="Feedback and further development of this How-To"><title>Feedback and further development of this How-To</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_70/howto/howto-editcss.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-forrest-from-maven.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-forrest-from-maven.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-forrest-from-maven.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-forrest-from-maven.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,94 @@
+<?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 run Forrest from within Maven</title>
+
+    <abstract>This How-To describes how to run Forrest from within
+    Maven.</abstract>
+
+    <last-modified-content-date date="2004-11-12"/>
+  </header><body><section id="Intended Audience"><title>Intended Audience</title>
+    <p>Users who want to run Forrest from within Maven.</p>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>One may want to generate their project's documentation and/or website
+    using Forrest in lieu of Maven's site plugin.</p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <ul>
+      <li>Understand how to add goals to <a href="http://maven.apache.org/reference/user-guide.html#maven_xml">maven.xml</a>.</li>
+    </ul>
+  </section><section id="Steps"><title>Steps</title>
+    <p>The procedure outlined below describes how to add a goal to your
+    project's maven.xml that will invoke Forrest's <code>site</code>
+    target.</p>
+
+    <section id="set-maven-home">
+      <title>Set the FORREST_HOME environment variable</title>
+
+      <p>Make sure the FORREST_HOME environment variable points to your
+      Forrest home directory (i.e. the directory that contains
+      <code>forrest.build.xml</code>) (e.g. C:\opt\apache-forrest-0.7)</p>
+    </section>
+
+    <section id="define-ant-environment-prop">
+      <title>Initialize an Ant environment property at the top of
+      maven.xml</title>
+
+      <p>Paste the following line at the top of your maven.xml:</p>
+
+      <source xml:space="preserve">
+&lt;property environment="env" /&gt;
+      </source>
+    </section>
+
+    <section id="add-forrest-goal-to-maven-xml">
+      <title>Add forrest goal to maven.xml</title>
+
+      <p>Paste the following goal into your project's maven.xml:</p>
+
+      <source xml:space="preserve">
+&lt;goal name="forrest" description="runs Forrest"&gt;
+  &lt;property name="forrest.home" location="${env.FORREST_HOME}" /&gt;
+  &lt;property name="forrest.ant.home" location="${forrest.home}/tools/ant" /&gt;
+  &lt;java classname="org.apache.tools.ant.Main" fork="true" failonerror="true" maxmemory="128M"&gt;
+    &lt;classpath&gt;
+      &lt;fileset dir="${forrest.ant.home}/lib"&gt;
+        &lt;include name="*.jar" /&gt;
+      &lt;/fileset&gt;
+      &lt;pathelement path="${java.home}/../lib/tools.jar" /&gt;
+    &lt;/classpath&gt;
+    &lt;sysproperty key="ant.home" value="${forrest.ant.home}" /&gt;
+    &lt;sysproperty key="forrest.home" value="${forrest.home}" /&gt;
+    &lt;sysproperty key="basedir" value="${basedir}" /&gt;
+    &lt;sysproperty key="java.endorsed.dirs" value="${forrest.home}/lib/endorsed" /&gt;
+    &lt;arg line="-f ${forrest.home}/main/forrest.build.xml" /&gt;
+  &lt;/java&gt;
+&lt;/goal&gt;      
+      </source>
+
+      <p>It is necessary to fork a separate java process because Maven 1.0
+      embeds Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The
+      goal makes use of the copy of Ant 1.6 that is bundled with Forrest, so
+      it's not even necessary to have Ant 1.6 installed separately.</p>
+    </section>
+
+    <section>
+      <title>Alternative file</title>
+
+      <p>Under <code>$FORREST_HOME/tools/targets/maven.xml</code></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>.<!-- Original author: Ian Springer (ips AT apache DOT org) --></p>
+  </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/howto/howto-forrest-from-maven.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_70/howto/howto-howto.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/howto/howto-howto.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/howto/howto-howto.source.xml (added)
+++ forrest/site/docs_0_70/howto/howto-howto.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,192 @@
+<?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 write a How-To</title>
+
+    <version>0.3</version>
+
+    <abstract>This How-To describes the steps necessary to write a How-To
+    document. Writing documentation is a valuable way to give back to the
+    community.</abstract>
+
+    <last-modified-content-date date="2005-07-18"/>
+  </header><body><section id="Intended Audience"><title>Intended Audience</title>
+    <p>Users who are ready to share their knowledge and experiences with the
+    community.</p>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>These guidelines are based on successful how-to document structures
+    used by other open source projects with diverse author groups. Following
+    these tried and true guidelines will help to insure the effectiveness of
+    your work.</p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <p>How-To authors should have:</p>
+
+    <ul>
+      <li>A unique How-To topic, related to using Forrest, which fulfills a
+      specific need. Check out existing How-Tos to find a niche for your work.
+      Consider posting your idea for the How-To to user mailing list, to make
+      sure another author's draft is not already in process.</li>
+
+      <li>A sufficient ability in English to write the FAQ. However, we would
+      rather that you just make a start, as the community can help to
+      fine-tune the document.</li>
+      
+      <li>Copy this template document "howto-howto.xml" to be modified with
+      your own content as necessary.</li>
+
+      <li>An understanding of the How-To document structure. Just use this
+      template document and you will be safe.
+      Make sure you run '<code>forrest validate-xdocs</code>' before
+      contributing your document.</li>
+    </ul>
+
+    <note>See the <a href="site:howto-v13-dtd">DTD documentation</a>
+    which explains the document structure.</note>
+  </section><section id="Steps"><title>Steps</title>
+    <p>Here is how to proceed.</p>
+
+    <section id="overview">
+      <title>Write the Overview</title>
+
+      <p>An overview helps potential readers to determine quickly if a
+      particular How-To matches their interests or needs. In a few sentences,
+      summarize the main points of your How-To. Make sure to include any
+      critical definitions which will help readers evaluate the utility of
+      your How-To. Consider writing the overview last, after you have
+      completed all other sections.</p>
+    </section>
+
+    <section id="audience">
+      <title>Describe your Intended Audience</title>
+
+      <p>If your How-To is targetted at a specific audience, describe it here.
+      For example, potential readers will have different levels of skill using
+      Forrest. They will also bring different areas of expertise and
+      backgrounds to their How-To learning experience. When you clarify your
+      target audience up front, you will save all other readers time and
+      confusion.</p>
+    </section>
+
+    <section id="purpose">
+      <title>State the Purpose</title>
+
+      <p>State the purpose of your How-To. Explain how the reader will benefit
+      by reading it. Give your reader an incentive or two to continue.</p>
+    </section>
+
+    <section id="prerequisites">
+      <title>List any Prerequisites</title>
+
+      <p>Inform your reader about any required knowledge, configuration, or
+      resources they may need before stepping through your How-To. Assist them
+      in this preparation by linking to other useful resources on the Forrest
+      site or the web. Helping your readers to prepare increases the
+      likelihood that they will continue reading your How-To.</p>
+    </section>
+
+    <section id="steps">
+      <title>Describe the Steps of your How-To</title>
+
+      <p>In a precise, step-by-step approach, walk your reader through the
+      process. Make sure your reader can reproduce your intended result by
+      following your exact steps. Make the learning process efficient by
+      supplying sample code snippets or configuration details as
+      necessary.</p>
+    </section>
+
+    <section id="extension">
+      <title>Extend the Learning</title>
+
+      <p>Provide your reader with a few real-world examples of how the
+      techniques or capabilities gained from your How-To could be applied.
+      Reward the reader for successfully completing the How-To with a few
+      ideas about how it will pay off.</p>
+    </section>
+
+    <section id="summarize">
+      <title>Summarize the Entire Process</title>
+
+      <p>In a few sentences, remind the reader what they have just learned.
+      This helps to reinforce the main points of your How-To.</p>
+    </section>
+
+    <section id="tips">
+      <title>Additional Tips or FAQs</title>
+
+      <p>In some cases, step-by-step instructions simply aren't enough. Use
+      this section to pass on any other tips or frequently asked questions.
+      Anticipating the needs of your readers will increase the overall success
+      of your writing effort.</p>
+    </section>
+
+    <section id="references">
+      <title>References</title>
+
+      <p>Remember to acknowledge any third-party resources or individuals who
+      contributed to the development of your How-To. Consider providing links
+      for those motivated readers who want to learn more.</p>
+    </section>
+
+    <section id="contribute">
+      <title>Submit via the project issue tracker</title>
+
+      <p>Create an attachment for your How-To document, and submit it via the
+      project <a href="site:bugs">issue tracker</a>.</p>
+    </section>
+
+    <section id="feedback">
+      <title>Get some feedback</title>
+
+      <p>When the committers have added your document then it will be
+      available for everyone to to build upon and enhance. Feedback will
+      happen via the <a href="site:mail-lists">mailing lists</a>.</p>
+    </section>
+  </section><section id="Extension"><title>Extension</title>
+    <p>Solutions can be extended to cover many different problem domains. A
+    nearly unlimited number of potential How-To topics, from simple to
+    complex, are available right now, limited only by your imagination.</p>
+  </section><section id="Frequently Asked Questions"><title>Frequently Asked Questions</title><section><title>1 General issues</title><section><title>1.1 What is the difference between a How-To and a tutorial?</title>
+          <p>The goal of a How-To is to help the reader to accomplish a specific
+          task with clear and consise instructions. While tutorials may contain
+          How-To-like instructions and content, they also include additional
+          background and conceptual content to help teach their readers higher
+          order concepts along the way. How-Tos are concerned about filling an
+          immediate, short-term need. Tutorials often provide long-term
+          knowledge which can be applied across a range of needs.</p>
+        </section></section><section><title>2 Style issues</title><section><title>2.1 What spelling convention should I follow?</title>
+          <p>Use whatever spelling convention (American, British, etc.) that is
+          most intuitive to you.</p>
+        </section></section></section><section id="Tips"><title>Tips</title>
+    <section id="tip-dtd">
+      <title>How-To dtd</title>
+
+      <p>The document structure is likely to change soon. Please note that
+      this HOWTO page is likely to change as well.</p>
+    </section>
+  </section><section id="References"><title>References</title>
+    <p>This is not the first, nor will it be the last, How-To on writing
+    How-Tos. For other ideas and opinions on the matter, check out the
+    following sources.</p>
+
+    <ul>
+      <li>Joel D. Canfield's <a href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
+      to Write a How-To</a> on evolt.org.</li>
+
+      <li>The Linux Documentation Project's <a href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</a>
+      index page provides many excellent How-To documents to inspire your
+      efforts.</li>
+    </ul>
+  </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_70/howto/howto-howto.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message