forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527010 [12/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_...
Date Tue, 10 Apr 2007 03:48:57 GMT
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-buildPlugin.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-buildPlugin.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-buildPlugin.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-buildPlugin.xml Mon Apr  9 20:48:52 2007
@@ -19,346 +19,379 @@
 <howto>
   <header>
     <title>How to Build a Plugin</title>
-
     <version>0.3.0</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>
-
+    <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="2006-04-23" />
   </header>
-
   <audience title="Intended Audience">
-    <p>Users needing to add additional input formats or output formats or
-    to change the operation of the Forrest internals.</p>
-       
-    <warning>Please make sure that you are using forrest 0.8 or above if you want use 
-    plugins. Forrest 0.6 will not work!!!</warning>
+    <p>
+      Users needing to add additional input formats or output formats or to
+      change the operation of the Forrest internals.
+    </p>
+    <warning>
+      Please make sure that you are using forrest 0.8 or above if you want use
+      plugins. Forrest 0.6 will not work!!!
+    </warning>
   </audience>
-
   <purpose title="Purpose">
-    <p>This How-To will illustrate how to build a plugin, publish a plugin
-    and configure a Forrest project to use their plugin.</p>
+    <p>
+      This How-To will illustrate how to build a plugin, publish a plugin and
+      configure a Forrest project to use their plugin.
+    </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
-    <p>Plugin developers should have:</p>
-    
+    <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>
+        <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>
   </prerequisites>
-
   <steps title="Steps">
-    <p>Here is how to proceed.</p>
-
+    <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>
-      
+      <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 Forrest's '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, i.e.
-        $FORREST_HOME/tools/ant/bin/ant
-      </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 the building of your plugins will go across
-        the network to get the DTDs on every xml parse. Be aware that Forrest
-        might be relying on some Ant features in its version.
+        <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 Forrest's '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, i.e. $FORREST_HOME/tools/ant/bin/ant
+      </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 the building of your plugins will go across the
+        network to get the DTDs on every xml parse. Be aware that Forrest might
+        be relying on some Ant features in its version.
       </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>
-      
+      <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>
       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> 
-      
-      <p>You can also build your plugins from a location outside of the Forrest directory
-      structure, for example from within your own project.
-	      If you don't already have one, create a plugins directory, for example:</p>
+      </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>
+      <p>
+        You can also build your plugins from a location outside of the Forrest
+        directory structure, for example from within your own project. If you
+        don't already have one, create a plugins directory, for example:
+      </p>
       <source>
       cd $PROJECT_HOME
       mkdir plugins
       </source>
-      <p> Then copy $FORREST_HOME/whiteboard/plugins/build.xml to $PROJECT_HOME/plugins.
-      There are a couple of changes you now need to make to the newly copied
-      build.xml file. Open up 'build.xml' for editing. You can change the project
-      name value to something more suitable.Find the property name for
-      forrest.plugins.dir and change the location to read</p> <source>location="."</source>
-      <p class="instruction">So, revised commands for $PROJECT_HOME/plugins:</p>
+      <p>
+        Then copy $FORREST_HOME/whiteboard/plugins/build.xml to
+        $PROJECT_HOME/plugins. There are a couple of changes you now need to
+        make to the newly copied build.xml file. Open up 'build.xml' for
+        editing. You can change the project name value to something more
+        suitable.Find the property name for forrest.plugins.dir and change the
+        location to read
+      </p>
+      <source>location="."</source>
+      <p class="instruction">
+        So, revised commands for $PROJECT_HOME/plugins:
+      </p>
       <source>
       cd [path_to_project_home]/plugins
       ant seedPlugin
-      </source>     
-      <p>See 
-      <a href="site:plugins/infrastructure">Plugin
-      Infrastructure</a> for more information about the plugin
-      directory structure and configuration files.</p>
-    
+      </source>
+      <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>
-        
+        <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>
+          <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>
+          <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>
+          <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>
+          <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 
+            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: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>
-      
+      <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: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:forrest.plugins}/PLUGIN_NAME</code> instead of <code>{realpath:/}</code>.
+        <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:forrest.plugins}/PLUGIN_NAME</code> instead of
+          <code>{realpath:/}</code>.
+        </p>
+        <p>
+          See the examples below for more details.
         </p>
-        <p>See the examples below for more details.</p>
       </section>
     </section>
-    
     <section id="resources">
       <title>Create the Necessary Resource Files</title>
-      <fixme author="open">Discuss the XSL files and other such resources</fixme>
+      <fixme author="open">
+        Discuss the XSL files and other such resources
+      </fixme>
       <section id="dtd-catalog">
         <title>Entity catalog for DTDs and other resources</title>
-        <p>If the plugin uses non-core DTDs and other entities, then add them to  the
-          <code>resources/schema</code> directory and configure a catalog.xcat file.
-          The best way to do this is to copy an example from another plugin (e.g.
-          "listLocations" has a simple example; "glossary" has a more complex example)
-          and edit it to suit.</p>
+        <p>
+          If the plugin uses non-core DTDs and other entities, then add them to
+          the <code>resources/schema</code> directory and configure a
+          catalog.xcat file. The best way to do this is to copy an example from
+          another plugin (e.g. "listLocations" has a simple example; "glossary"
+          has a more complex example) and edit it to suit.
+        </p>
       </section>
     </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>
+      <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>
-      
+      <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>$FORREST_HOME/tools/ant/bin/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>When you make changes to the plugin while doing its development,
-        then you need to do the local-deploy again for those changes to have effect.</p>
-
-        <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>
+        <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>$FORREST_HOME/tools/ant/bin/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>
+          When you make changes to the plugin while doing its development, then
+          you need to do the local-deploy again for those changes to have
+          effect.
+        </p>
+        <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>
+        <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>
-        
+        <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>
@@ -368,82 +401,91 @@
           are deployed to the forrest website.
         </p>
         <p>
-          Each plugin has a build.xml file which defines its version information.
-          Please keep that synchronised with the plugins.xml files.
+          Each plugin has a build.xml file which defines its version
+          information. Please keep that synchronised with the plugins.xml files.
           Later
           <a href="http://issues.apache.org/jira/browse/FOR-533">FOR-533</a>
-           will generate this from the various build.xml files.
+          will generate this from the various build.xml files.
         </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 ...
+          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 plugin's descriptors 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>
+          <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 plugin's descriptors 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 ...
+          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
+          <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
+          <li>Edit the skinconf.xml to ensure that all version numbers are
              "0.8-dev", e.g. the MOTD.</li>
-           <li>Edit the plugin's descriptors to ensure that the "forrestVersion" is
+          <li>Edit the plugin's descriptors 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.
+          <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>
     <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>
-        
+      <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>
+        <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, resources  and tiles 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><![CDATA[
+        <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, resources and tiles 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>
+<![CDATA[
     <match pattern="resolvePluginContract.*.**">
       <select type="exists">
         <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.theme}/{1}/{2}.ft" />
@@ -461,59 +503,69 @@
         <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.theme}/html/{1}.vt.xml" />
         <location src="{forrest:forrest.plugins}/PLUGIN_NAME/resources/themes/{properties:dispatcher.fallback.theme}/html/{1}.vt.xml" />
       </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 matches to the default locationmap
-        which is generated when you seed a new plugin, but for now it must be done manually.</p>
+    </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 matches 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>
+        <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>
+      <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>
+      <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>
   </steps>
 </howto>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-collaborativeEditing.html
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-collaborativeEditing.html?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-collaborativeEditing.html (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-collaborativeEditing.html Mon Apr  9 20:48:52 2007
@@ -20,99 +20,129 @@
 <howto>
   <header>
     <title>How to Participate in Forrest Tuesday Events</title>
-
     <version>0.1</version>
-
     <abstract></abstract>
-
     <last-modified-content-date date="2005-07-18" />
   </header>
-
   <audience title="Intended Audience">
-    <p>Developers wanting to participate in the collaborative meetings known as
-    "Forrest Tuesday". Users interested in what goes on at these events.</p>
-    
-    <warning>This is a document written whilst testing the Gobby software. It is
-    included here for reference only. Gobby is not currently the preferred choice
-    of communication media for Forrest Tuesdays, we still use IRC at this time.</warning>
+    <p>
+      Developers wanting to participate in the collaborative meetings known as
+      "Forrest Tuesday". Users interested in what goes on at these events.
+    </p>
+    <warning>
+      This is a document written whilst testing the Gobby software. It is
+      included here for reference only. Gobby is not currently the preferred
+      choice of communication media for Forrest Tuesdays, we still use IRC at
+      this time.
+    </warning>
   </audience>
-
   <purpose title="Purpose">
-    <p> On the first Tuesday of each month we have a 24-hour get-together using the dev mailing list, Internet Relay Chat (IRC), and other collaborative tools, to work on Forrest development and get to know each other.</p>
     <p>
-  We exploring the use of a <a href="http://gobby.0x539.de">Gobby</a>, a collaborative editor, to assist in focused development tasks. This HowTo will show you how.
-  </p>
-
-    <p>ForrestTuesday starts at 06:00 UTC (6am Greenwich Mean Time in London) and lasts for 24 hours.</p>
+      On the first Tuesday of each month we have a 24-hour get-together using
+      the dev mailing list, Internet Relay Chat (IRC), and other collaborative
+      tools, to work on Forrest development and get to know each other.
+    </p>
+    <p>
+      We exploring the use of a <a href="http://gobby.0x539.de">Gobby</a>, a
+      collaborative editor, to assist in focused development tasks. This HowTo
+      will show you how.
+    </p>
+    <p>
+      ForrestTuesday starts at 06:00 UTC (6am Greenwich Mean Time in London) and
+      lasts for 24 hours.
+    </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
-    <p>You will not need anything more than knowledge of how to
-    install software on your computer. You will also need an Internet connection
-    to participate in the meetings.</p>
+    <p>
+      You will not need anything more than knowledge of how to install software
+      on your computer. You will also need an Internet connection to participate
+      in the meetings.
+    </p>
   </prerequisites>
-
   <steps title="Steps">
-
     <section id="preparation">
       <title>Perparing for Participation</title>
       <section id="gobby">
         <title>What is Gobby?</title>
         <p>
-      From the <a href="http://gobby.0x539.de">Gobby web site</a>:
-      </p>
+          From the <a href="http://gobby.0x539.de">Gobby web site</a>:
+        </p>
         <p>
-          <em>
-      Gobby is a free collaborative editor based on libobby, a library which provides synced document buffers. It supports multiple documents in one session and a multi-user chat. It runs on Microsoft Windows, Mac OS X, Linux and other Unix-like platforms.
-      </em>
+          <em> Gobby is a free collaborative editor based on libobby, a library
+          which provides synced document buffers. It supports multiple documents
+          in one session and a multi-user chat. It runs on Microsoft Windows,
+          Mac OS X, Linux and other Unix-like platforms. </em>
         </p>
         <p>
-      You can see some of its <a href="http://gobby.0x539.de/features.html">features</a>. People interested in the technical details of how Gobby works should read <a href="http://darcs.0x539.de/trac/obby/cgi-bin/trac.cgi/wiki/ObbyInternals">this document</a>.
-      </p>
+          You can see some of its
+          <a href="http://gobby.0x539.de/features.html">features</a>. People
+          interested in the technical details of how Gobby works should read
+          <a href="http://darcs.0x539.de/trac/obby/cgi-bin/trac.cgi/wiki/ObbyInternals">this
+          document</a>.
+        </p>
       </section>
-
       <section id="software">
         <title>Installing Required Software</title>
-        <p class="instruction">Download Gooby from Gobby's web site (http://gobby.0x539.de/download.html). If you use one of the popular Linux distributions, chances are that Gobby is already available as a binary package for you. Debian/Ubuntu users, for instance, can simply <code>apt-get install gobby</code>.
+        <p class="instruction">
+          Download Gooby from Gobby's web site
+          (http://gobby.0x539.de/download.html). If you use one of the popular
+          Linux distributions, chances are that Gobby is already available as a
+          binary package for you. Debian/Ubuntu users, for instance, can simply
+          <code>apt-get install gobby</code>.
         </p>
       </section>
       <section id="session">
         <title>Creating a Collaborative Session</title>
         <p>
-        When you first fire up Gobby, you will be presented with a blank screen with a toolbar on the top. Click on "Create Session" to host a session. If you need to join an existing session, click "Join session" instead.
+          When you first fire up Gobby, you will be presented with a blank
+          screen with a toolbar on the top. Click on "Create Session" to host a
+          session. If you need to join an existing session, click "Join session"
+          instead.
         </p>
         <p>
-        To create a session, you need a computer connected to the Internet and you need to know its IP address. On Linux, this can be obtained with a <code>ifconfig -a</code>. On windows, try doing <code>ipcongfig /all</code>. For most cases, leaving the port values at default should be sufficient. Once you have specified the IP address and the name of the session, click "Create".
+          To create a session, you need a computer connected to the Internet and
+          you need to know its IP address. On Linux, this can be obtained with a
+          <code>ifconfig -a</code>. On windows, try doing <code>ipcongfig
+          /all</code>. For most cases, leaving the port values at default should
+          be sufficient. Once you have specified the IP address and the name of
+          the session, click "Create".
+        </p>
+        <p>
+          There is an early version of a server available for Gobby. This allows
+          you to run a (semi-)permanent server. It is currently only available
+          for linux.
         </p>
-        <p>There is an early version of a server available for Gobby. This 
-        allows you to run a (semi-)permanent server. It is currently only 
-        available for linux.</p>
       </section>
     </section>
-
     <section id="participation">
       <title>Participating in a Forrest Tuesday event</title>
       <section id="login">
         <title>Logging in to the session</title>
         <p>
-        To join a Gobby session, click on "Join session" on the toolbar. You will need to know the IP address of the machine the session is being hosted at. In the "Name" field, just put in your name. Choose a color (which you can change later) and click OK.  You will
-        then be prompted for the session password before joining.</p>
-        <p>When you first enter the Gobby session, if a document is already open,
-      you will be informed the document exists but that you are not currently
-      subscribed to it.  There will be a "Subscribe" button below this notice that
-      will give you access to the document once clicked.  Documents that are 
-      created or opened during the session will also need to be subscribed to
-      in a similar manner.</p>
+          To join a Gobby session, click on "Join session" on the toolbar. You
+          will need to know the IP address of the machine the session is being
+          hosted at. In the "Name" field, just put in your name. Choose a color
+          (which you can change later) and click OK. You will then be prompted
+          for the session password before joining.
+        </p>
+        <p>
+          When you first enter the Gobby session, if a document is already open,
+          you will be informed the document exists but that you are not
+          currently subscribed to it. There will be a "Subscribe" button below
+          this notice that will give you access to the document once clicked.
+          Documents that are created or opened during the session will also need
+          to be subscribed to in a similar manner.
+        </p>
       </section>
-
       <section id="discussion">
         <title>Using Chat for Discussion</title>
-        <p>Gobby has a chat session at the bottom of the window. This can be
-        used to discuss what needs to be done and who is going to be doing it.
-        Here is an (edited) chat session log from when this document was
-        written.</p>
-
-        <source><![CDATA[
+        <p>
+          Gobby has a chat session at the bottom of the window. This can be used
+          to discuss what needs to be done and who is going to be doing it. Here
+          is an (edited) chat session log from when this document was written.
+        </p>
+        <source>
+<![CDATA[
 [22:24:16] <addi> we should also make note about the preferences
 [22:24:40] <addi> in the editor
 [22:25:02] <addi> tab width, tab spaces, etc
@@ -120,80 +150,93 @@
 [22:25:39] <diwaker> I am
 [22:25:58] <diwaker> under FAQ
 [22:26:07] <addi> ok
-        ]]></source>
-
+        ]]>
+        </source>
         <source>
-        <![CDATA[
+<![CDATA[
 [22:26:38] <Ross> Note that the last sections of this document are cut and paste from the how-to-howto
 [22:26:46] <Ross> feel free to delete irrelevant content
 ]]>
         </source>
-
-        <source><![CDATA[
+        <source>
+<![CDATA[
 [22:29:52] <Ross> Do either of you have a problem with me putting some
 [22:30:04] <Ross> of the content from the chat log in section <section id="discussion">
 [22:30:18] <addi> nope, fine with me
-        ]]></source>
-
-        <source><![CDATA[
+        ]]>
+        </source>
+        <source>
+<![CDATA[
 [22:41:47] <diwaker> hey do we have a blockquote/cite element in the v20 dtd?
 [22:42:01] <diwaker> i can't seem to find one
 [22:42:26] <diwaker> tip: the text entry widget has history (if you press Up, you can see earlier messages)
 [22:46:07] <Ross> There is no blockquote.cite element
 [22:46:24] <Ross> there may be a class in the CSS (<p class="cite"> or similar)
-        ]]></source>
+        ]]>
+        </source>
       </section>
-
       <section id="authoring">
         <title>Using Gobby for Collaborative Authoring</title>
         <p>
-      Gobby uses colors to identify the edits being done by participants. In order to make it easier to follow whats going on, its a good idea to choose visibly distinct colors. While joining a session, if you choose a color thats already in use by someone else, Gobby will refuse to connect to the session. Just choose some color that gets you in, because you can always change your color later on while a session is in progress (see "Set Color" under the "User" menu item).
-      </p>
-        <warning>If you close a document it closes for everyone, and remote users
-      are not given the option to save any changes. So think carefully
-      before closing anything. Generally speaking you should not close a 
-      document without asking all participants first.</warning>
+          Gobby uses colors to identify the edits being done by participants. In
+          order to make it easier to follow whats going on, its a good idea to
+          choose visibly distinct colors. While joining a session, if you choose
+          a color thats already in use by someone else, Gobby will refuse to
+          connect to the session. Just choose some color that gets you in,
+          because you can always change your color later on while a session is
+          in progress (see "Set Color" under the "User" menu item).
+        </p>
+        <warning>
+          If you close a document it closes for everyone, and remote users are
+          not given the option to save any changes. So think carefully before
+          closing anything. Generally speaking you should not close a document
+          without asking all participants first.
+        </warning>
       </section>
     </section>
-
     <section id="wrapup">
       <title>Wrapping up</title>
-
       <section id="closingSession">
         <title>Closing the Session</title>
-        <p>To close, or leave a session, simply click on the "Quit Session"
-        button in the toolbar. Be sure to save the files before doing so,
-        especially if you "own" the file.</p>
-
-        <p>Note that the host must be careful not to quit the session until
-        all participants ahve finished their work. It is a good idea to use
-        chat to ensure everyone is done, alternatively, you could leave the
-        session open until everyone else has quit.</p>
-        
-        <warning>With the current version of Gobby (0.2.2) if any user leaves
-        a session the document is closed in all remaining users sessions. Any
-        unsaved changes are lost. Do not leave a session without agreeing
-        to do so with all other participants.</warning>
+        <p>
+          To close, or leave a session, simply click on the "Quit Session"
+          button in the toolbar. Be sure to save the files before doing so,
+          especially if you "own" the file.
+        </p>
+        <p>
+          Note that the host must be careful not to quit the session until all
+          participants ahve finished their work. It is a good idea to use chat
+          to ensure everyone is done, alternatively, you could leave the session
+          open until everyone else has quit.
+        </p>
+        <warning>
+          With the current version of Gobby (0.2.2) if any user leaves a session
+          the document is closed in all remaining users sessions. Any unsaved
+          changes are lost. Do not leave a session without agreeing to do so
+          with all other participants.
+        </warning>
       </section>
-
       <section id="logs">
         <title>Recording the logs</title>
         <note>
-        At this point, we're not very sure if Gobby stores the chat logs somewhere on disk (we were not able to locate them). If you know the location of the logs, please let us know.
+          At this point, we're not very sure if Gobby stores the chat logs
+          somewhere on disk (we were not able to locate them). If you know the
+          location of the logs, please let us know.
         </note>
       </section>
-
       <section id="commit">
         <title>Committing Documents to SVN</title>
-        <p>Any user can save a copy of a file being edited locally. However,
-        it is recomended that someone be nominated as the person responsible
-        for committing the file to SVN at the end of the session.</p>
         <p>
-        As mentioned before, the person responsible for committing should make sure that the document is properly formatted before committing.
+          Any user can save a copy of a file being edited locally. However, it
+          is recomended that someone be nominated as the person responsible for
+          committing the file to SVN at the end of the session.
+        </p>
+        <p>
+          As mentioned before, the person responsible for committing should make
+          sure that the document is properly formatted before committing.
         </p>
       </section>
     </section>
-
   </steps>
 <!--
   <extension title="Extension">
@@ -209,71 +252,88 @@
       <faq id="faq-difference">
         <question>What is the difference between a How-To and a
         tutorial?</question>
-
         <answer>
-          <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>
+          <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>
         </answer>
       </faq>
     </faqsection>
-
     <faqsection id="faq-style">
       <title>Style issues</title>
       <faq id="coding">
         <question>What coding convention should I follow?</question>
         <answer>
           <p>
-      Gobby is a good collaborative editor, but not a very good editor. It allows minimalistic configuration flexibility for editing. For Gobby sessions, it is sufficient to choose a convention and stick with it. For instance, using 4 spaces for a tab indent, and using spaces to fill up the tabs -- this can be done through the "Preferences" item under the "Edit" menu.
-      </p>
+            Gobby is a good collaborative editor, but not a very good editor. It
+            allows minimalistic configuration flexibility for editing. For Gobby
+            sessions, it is sufficient to choose a convention and stick with it.
+            For instance, using 4 spaces for a tab indent, and using spaces to
+            fill up the tabs -- this can be done through the "Preferences" item
+            under the "Edit" menu.
+          </p>
           <p>
-      The nominated committer should make sure that the document is properly formatted before committing to SVN.
-      </p>
-          <note>The current version of Gobby is 0.2.2, hopefully the editor will 
-      improve.</note>
+            The nominated committer should make sure that the document is
+            properly formatted before committing to SVN.
+          </p>
+          <note>
+            The current version of Gobby is 0.2.2, hopefully the editor will
+            improve.
+          </note>
         </answer>
       </faq>
       <faq id="spelling">
         <question>What spelling convention should I follow?</question>
-
         <answer>
-          <p>Use whatever spelling convention (American, British, etc.) that is
-          most intuitive to you.</p>
+          <p>
+            Use whatever spelling convention (American, British, etc.) that is
+            most intuitive to you.
+          </p>
         </answer>
       </faq>
     </faqsection>
   </faqs>
-
   <tips title="Tips">
     <section id="tip-jotlive">
       <title>Collaborative Note Taking</title>
       <p>
-        <a href="http://www.jotlive.com">JotLive</a> is a nice little web-app for taking notes collaboratively. Its almost like Gobby (each user has a different color, you can see the edits in <em>real time</em>), except that its web based. From the same folks who did <a href="http://jot.com">Jotspot</a>.
-    </p>
+        <a href="http://www.jotlive.com">JotLive</a> is a nice little web-app
+        for taking notes collaboratively. Its almost like Gobby (each user has a
+        different color, you can see the edits in <em>real time</em>), except
+        that its web based. From the same folks who did
+        <a href="http://jot.com">Jotspot</a>.
+      </p>
     </section>
     <section id="editing-tips">
       <title>Editing Tips</title>
       <section>
         <title>Is Anyone Editing?</title>
-        <p>A quick way to see if someone is currently working on a document is
-        to look at the revision number in the status bar. This number will 
-        increase by one with each keypress.</p>
+        <p>
+          A quick way to see if someone is currently working on a document is to
+          look at the revision number in the status bar. This number will
+          increase by one with each keypress.
+        </p>
       </section>
     </section>
     <section id="chat-tips">
       <title>Chat Tips</title>
       <section>
         <title>History</title>
-        <p>The text entry widget (where you type for chat) can show you an editable history
-        of your previous entries by hitting the up arrow on your keyboard.  This functions
-        much like the up arrow key in a Linux terminal.</p>
+        <p>
+          The text entry widget (where you type for chat) can show you an
+          editable history of your previous entries by hitting the up arrow on
+          your keyboard. This functions much like the up arrow key in a Linux
+          terminal.
+        </p>
       </section>
     </section>
-    <!--
+<!--
      <section id="tip-dtd">
       <title>How-To dtd</title>
 
@@ -290,5 +350,3 @@
   </references>
 -->
 </howto>
-
-

Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-corner-images.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-corner-images.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-corner-images.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-corner-images.xml Mon Apr  9 20:48:52 2007
@@ -16,37 +16,33 @@
   limitations under the License.
 -->
 <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "http://forrest.apache.org/dtd/howto-v20.dtd">
-
 <howto>
- <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>
-
+  <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>
   <audience title="Intended Audience">
     <p>
-      Users who want to change the colors of the corner images in the
-      output html documents.
+      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.
+      This explanation is also useful for skin developers to understand the
+      corner image generation process.
     </p>
   </audience>
-  
   <purpose title="Purpose">
     <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.
+      <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>
   </purpose>
-
   <prerequisites title="Prerequisites">
     <ul>
       <li>Understand how to use the skinconf.xml file to change the appearance
@@ -56,19 +52,18 @@
        (topic "<a href="site:your-project/skins">Forrest skins</a>").</li>
     </ul>
   </prerequisites>
-
   <steps title="Steps">
     <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
+      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:
+        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>
 /*Example from screen.css of pelt*/
@@ -84,8 +79,8 @@
 ...
       </source>
       <p>
-        The naming follows a contract which is described below. In general,
-        the naming looks like:
+        The naming follows a contract which is described below. In general, the
+        naming looks like:
       </p>
       <source>
 images/{$name}-{$v-orientation}-{$h-orientation}-{$size}-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}
@@ -98,8 +93,8 @@
         (<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.
+        <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:
@@ -108,93 +103,78 @@
         <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>
+          <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><code>rc.svg.xslt</code>: handles rounded corners
             </li>
-            <li>
-              <code>dc.svg.xslt</code>: handles diagonal 45-degree corners
+            <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>
+          </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>
+          <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>
+          <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>
+          <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>
+          <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>
+          <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>
+          <br/><em>e.g.</em><code>searchbox</code></dd>
       </dl>
-      <p>The corner images are made by generating a dymanic <a 
-        href="/skin/images/rc-t-r-50-1body-2menu-3menu.svg">svg image</a> to 
-        add the colors and size. Then this svg is serialize to <a 
-        href="/skin/images/rc-t-r-50-1body-2menu-3menu.png">the png image</a> 
-        via the <a 
+      <p>
+        The corner images are made by generating a dymanic
+        <a 
+        href="/skin/images/rc-t-r-50-1body-2menu-3menu.svg">svg
+        image</a> to add the colors and size. Then this svg is serialize to
+        <a 
+        href="/skin/images/rc-t-r-50-1body-2menu-3menu.png">the png
+        image</a> via the
+        <a 
         href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/serialization/SVGSerializer.html">org.apache.cocoon.serialization.SVGSerializer</a>
-        (see <a href="http://cocoon.apache.org/2.1/userdocs/svg-serializer.html">docs</a>).
+        (see
+        <a href="http://cocoon.apache.org/2.1/userdocs/svg-serializer.html">docs</a>).
       </p>
-      <fixme author="thorsten">The following link is for pure debugging 
-        reason. <a 
-        href="/skin/images/rc-t-r-50-1body-2menu-3menu.test.png">test png 
-        image</a> - this image is taken from the svg pipe instead of directly 
-        generating it. </fixme>
+      <fixme author="thorsten">
+        The following link is for pure debugging reason.
+        <a 
+        href="/skin/images/rc-t-r-50-1body-2menu-3menu.test.png">test
+        png image</a> - this image is taken from the svg pipe instead of
+        directly generating it.
+      </fixme>
     </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>).
+        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:
+        Starting about line 155 you find a <code>&lt;colors&gt;</code> ...
+        <code>&lt;/colors&gt;</code> element with content commented-out:
       </p>
       <source>
 &lt;colors&gt;
@@ -216,10 +196,10 @@
 &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.
+        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>
@@ -228,8 +208,9 @@
 &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>.
+        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>
@@ -242,16 +223,15 @@
       </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>).
+        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.
+        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:
@@ -276,14 +256,13 @@
 &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?
+        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>
   </steps>
-
   <feedback title="Feedback">
     <p>
       Please provide feedback about this document via the



Mime
View raw message