forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [18/34] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/ docs_0_80/howto/ docs_0_80/howt...
Date Thu, 09 Feb 2006 00:26:32 GMT
Added: forrest/site/docs_0_80/howto/howto-dev.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-dev.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-dev.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-dev.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,494 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 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 be a Forrest developer</title>
+
+    <abstract>
+      This How-To provides some tips and procedures for being a
+      Forrest developer.
+    </abstract>
+
+    <last-modified-content-date date="2005-08-22"/>
+  </header><body><section id="Intended Audience"><title>Intended Audience</title>
+<warning>
+This document is under initial development.
+</warning>
+    <p>
+      People who are ready to go beyond the basics of using Forrest.
+      This might be to utilise Forrest for your advanced needs, debugging,
+      creating a new plugin, enhancing an existing plugin, enhancing the core
+      capabilities, contributing such enhancements back to the Apache Forrest
+      project, etc. In all cases, this is what we mean by "developer".
+    </p>
+    <p>
+      Actually, users will also find that some parts of this document are
+      useful. For example, the section about debugging and the section about
+      editing content.
+    </p>
+    <p>
+      See also the companion document "How to be a committer".
+    </p>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>
+      This How-To provides some tips and procedures for being
+      an Apache Forrest developer. Ideally a developer would
+      also contribute back to the project, so these notes assume that.
+      Various key development tasks are used as worked examples.
+    </p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <ul>
+      <li>
+        You have achieved the basic level of using Forrest. You have Forrest
+        installed and can create a new site with 'forrest seed'.
+        You have followed at least the first parts of the 
+        <a href="site:v0.80//documentation/your-project">Using Forrest</a>
+        document.
+      </li>
+      <li>
+        You will enventually see that understanding of the Cocoon
+        <a href="site:v0.80//documentation/developers/sitemap-ref">sitemap</a>
+        is important. For the initial examples below, you can do without that.
+        However please explore the sitemap soon.
+      </li>
+    </ul>
+  </section><section id="Development techniques and scenarios"><title>Development techniques and scenarios</title>
+    <p>
+      Various scenarios are utilised to describe aspects of development.
+      Bear in mind that there are many
+      ways to do things. Each developer has different tools and habits,
+      and different operating systems are used. So you will need to glean
+      the principles and apply them to your own situation.
+    </p>
+
+    <p>
+      This document assumes that you intend to contribute some parts of
+      your work back to the project. Techniques for network-based collaborative
+      development are encouraged.
+    </p>
+
+    <section id="svn">
+      <title>Using Subversion</title>
+      <p>
+        The Subversion source control system is used for all ASF projects.
+        You can leverage this to ease your own development.
+      </p>
+
+      <p>
+        The "trunk" is where all new development and bugfixing happens.
+        We aim to keep the trunk usable at all times.
+      </p>
+
+      <p>
+        Each version release is a "branch", such as "forrest_07_branch".
+        Crucial bugfixes are also applied to the relevant release branch.
+      </p>
+
+      <p>
+        Branches are also used for developing
+        complex new code which would otherwise disrupt the trunk. When the new
+        work is suitable, then that branch is merged back to the trunk as soon
+        as possible.
+      </p>
+
+      <p>
+        To get started, see the
+        <a href="site:v0.80//documentation/developers/build">instructions</a>
+        for obtaining the Apache Forrest sources via SVN.
+      </p>
+
+      <section id="multiple">
+        <title>Multiple working copies</title>
+        <p>
+          Most developers would have a number of separate SVN working copies.
+          Hopefully you are brave enough to use the trunk for all your sites.
+          Sometimes that is not possible, for example when you are
+          co-operativley managing a site with other people who are not so
+          brave, so you need to use a specific release. However consider using
+          the SVN release branch, rather than the release archive (tar or zip).
+          This enables you to easily keep up with bugfixes. You can also easily
+          see what local changes that you have made by using 'svn status; svn diff'.
+        </p>
+        <p>
+          Here is one layout ...
+        </p>
+        <source xml:space="preserve">
+[localhost]$ ls /svn/asf
+forrest_07_branch
+forrest-trunk
+        </source>
+      </section>
+
+      <section id="svn-email">
+        <title>Watch email notifications for svn differences</title>
+        <p>
+          Either subscribe to the project's
+          <a href="site:mail-lists/forrest-svn">svn mailing list</a>
+          or monitor it via one of the mail archives. This enables you
+          to be immediately up-to-date with changes to the repositories.
+          The svn differences (diffs) are automatically sent whenever
+          a committer makes some changes.
+        </p>
+      </section>
+
+      <section id="tips-svn">
+        <title>Tips</title>
+        <ul>
+          <li>
+            Keep a copy of this book, or the online version, close at hand:
+            <a href="http://svnbook.red-bean.com/">Version Control with Subversion</a>
+            - the opensource SVN book.
+          </li>
+          <li>
+            See all available branches and other repositories:
+            <a href="http://svn.apache.org/repos/asf/forrest/">http://svn.apache.org/repos/asf/forrest/</a>
+          </li>
+          <li>
+            Use online repository browsers to quickly see past activity for
+            the files that you are working on:
+            <a href="http://svn.apache.org/viewcvs.cgi/forrest/trunk/">http://svn.apache.org/viewcvs.cgi/forrest/trunk/</a>
+          </li>
+          <li>
+            Use 'svn log foo.xsl' for a summary of recent activity and to
+            see dates and revision numbers for changes.
+          </li>
+        </ul>
+      </section>
+    </section>
+
+    <section id="edit">
+      <title>Editing content</title>
+      <p>
+        See the 
+        <a href="site:v0.80//documentation/faq/edit-content">FAQ</a>.
+        Basically any editor can
+        be used, because Forrest treats the editing of content as a separate
+        concern. Be sure to configure the editor to find local copies of DTDs.
+      </p>
+
+      <section id="code-style">
+        <title>Code style guidelines</title>
+        <p>
+          Consistent code makes everyone's life easier.
+          See the 
+          <a href="http://cocoon.apache.org/community/committer.html">Apache Cocoon tips</a>.
+          We don't get too hung up on style, but a few basic things are important.
+        </p>
+      </section>
+
+      <section id="whitespace">
+        <title>Whitespace</title>
+        <p>
+          For new file, use spaces instead of tabs (java files have four-space indentation,
+          xml files and other text files have two-space indentation).
+        </p>
+        <p>
+          Don't let your editor automatically change the whitespace for existing
+          files.
+        </p>
+        <p>
+          We know that many files in SVN do not have consistent whitespace.
+          This issue is continually being addressed. Please don't attempt
+          to rectify whitespace mixed up with other changes. This makes the
+          important changes difficult to see. Occasionally committers will
+          rectify whitespace for a set of files, when they know that no-one
+          else is working on that set.
+        </p>
+        <fixme author="open">
+          The issues of whitespace and line endings needs to be very clearly described.
+          See some
+          <a href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=112450886218545">mail discussion</a>
+          references.
+        </fixme>
+      </section>
+
+      <section id="line-length">
+        <title>Line length</title>
+        <p>
+          If each paragraph of an xml source document is one enourmous long
+          line, then it is extremely difficult to know the changes with the
+          SVN diffs. Developers and especially committers, need to be able to
+          efficiently review the changes. Fold long lines to a sensible
+          line-length (normally 80-characters wide but not more than 120 characters).
+        </p>
+      </section>
+
+      <section id="review">
+        <title>Use 'forrest run' for immediate gratification</title>
+        <p>
+          Edit content and immediately view it in the browser.
+          When you are satisifed, then do 'forrest site' to ensure that the
+          whole documentation set hangs together and there are no broken
+          references.
+        </p>
+        <p>
+          In the dynamic 'forrest run' mode, you will get some feedback
+          about some xml validation errors. However, it is better to treat
+          validation as a separate concern. Use an xml editor or command-line
+          tools such as "xmllint". As a last resort, you can use
+          'forrest validate-xdocs'.
+        </p>
+      </section>
+
+      <section id="tips-edit">
+        <title>Tips</title>
+
+        <ul>
+          <li>
+####
+          </li>
+        </ul>
+      </section>
+    </section>
+
+    <section id="debug">
+      <title>Debugging and profiling techniques</title>
+      <p>
+        This <a href="site:v0.80//documentation/faq/logs">FAQ</a>
+        describes the location of the Cocoon logfiles and their
+        configuration.
+      </p>
+
+      <section id="debug-cocoon-profiler">
+        <title>Using Cocoon sitemap profiler</title>
+        <p>
+          Cocoon provides a simple profiler to analyse itself.
+          This enables us to list the various sitemap pipelines and
+          components that are being used, how much time was used
+          by each, whether each component uses the Cocoon cache,
+          and show the actual xml data.
+        </p>
+        <p>
+          Note that the profiler is not used by default. To switch
+         it on, edit <code>main/webapp/sitemap.xmap</code> and search
+         for "profiler". Follow the instructions there to replace the
+          standard "map:pipe" components with the profiling pipes.
+        </p>
+        <p>
+          Now start your application as normal using 'forrest run'
+          and request localhost:8888/index.html three or four times
+          to populate the profiler with data.
+        </p>
+        <p>
+          Now request the special uri localhost:8888/cprofile.html
+          to see the results. Start at the "index.html" request,
+          then follow the processing. (If the table is empty, then
+          you either forgot to do some requests before looking for results,
+          or forgot to switch on the profiler in sitemap.)
+        </p>
+        <p>
+          NOTE: Do not forget to turn off the profiler in 
+          <code>main/webapp/sitemap.xmap</code> when finished.
+        </p>
+      </section>
+
+      <section id="debug-sitemap-exec">
+        <title>Using Cocoon sitemap execution logger</title>
+        <p>
+          In main/webapp/WEB-INF/xconf/forrest-core.xconf
+          search for "sitemap execution" and uncomment the component.
+          For each sitemap component that is executed, a message will go to
+          WEB-INF/logs/debug.log
+        </p>
+      </section>
+
+      <section id="debug-logtransformer">
+        <title>Using Cocoon LogTransformer</title>
+        <p>
+          LogTransformers can be inserted in the sitemaps. This will write
+          the sax events at that point into a named log file.
+          Here is an example (the logfile will be written relative to this
+          particular sitemap) ...
+        </p>
+      <source xml:space="preserve">
+&lt;map:match pattern="*.html"&gt;
+  &lt;map:generate src="sources/{1}.xml"/&gt;<strong>
+  &lt;map:transform type="log"&gt;
+    &lt;map:parameter name="logfile" value="my-1.log"/&gt;
+    &lt;map:parameter name="append" value="no"/&gt;
+  &lt;/map:transform&gt;</strong>
+  &lt;map:transform src="stylesheets/source-to-table.xsl"/&gt;
+  &lt;map:transform src="stylesheets/table-to-page.xsl"/&gt;<strong>
+  &lt;map:transform type="log"&gt;
+    &lt;map:parameter name="logfile" value="my-2.log"/&gt;
+    &lt;map:parameter name="append" value="no"/&gt;
+  &lt;/map:transform&gt;</strong>
+  &lt;map:transform src="stylesheets/page-to-html.xsl"/&gt;
+  &lt;map:serialize type="html"/&gt;
+&lt;/map:match&gt;
+</source>
+        <p>
+          Another use for this technique is when you are not sure which
+          path is being taken through the sitemap. Add various LogTransformers
+          with different filenames and see which one gets triggered.
+        </p>
+      </section>
+
+      <section id="debug-links">
+        <title>Finding broken internal links</title>
+        <p>
+          Do 'forrest site' to produce the whole documentation set.
+          Cocoon will report its progress and reveal any problems.
+          This <a href="site:v0.80//documentation/faq/build_msg_a">FAQ</a>
+          explains the messages that Cocoon sends to standard output.
+          Broken links are also reported to a special file, which also shows
+          the source file containing the break. The location
+          of this file is reported when Cocoon starts.
+        </p>
+        <p>
+          Broken links are also reported in 'forrest run' mode.
+          Use your mouse to point to each link. The browser status bar
+          will show "error:..." instead of the actual URL.
+        </p>
+        <p>
+          The most common cause is that the entry is missing in the site.xml
+          configuration file or the link in your source document is not
+          using the correct name for the "site:..." value.
+        </p>
+      </section>
+
+      <section id="tips-debug">
+        <title>Tips</title>
+        <ul>
+          <li>
+            Doing 'forrest -v' will provide verbose build messages to the
+            standard output.
+          </li>
+        </ul>
+      </section>
+    </section>
+
+    <section id="find">
+      <title>Finding the relevant sources</title>
+      <p>
+        You will need to be able to find which sources, sitemaps, stylesheets
+        are responsible for certain processing.
+      </p>
+      <section id="find-scenario-1">
+        <title>Scenario: How does i18n work</title>
+        <p>
+          We will do a search for "i18n" to start with, then refine that after
+          exploring some of the sources.
+        </p>
+        <p>
+          The UNIX tools find, grep, and sed are very powerful. We need a
+          helper script, otherwise 'find' is going to report matches for
+          the hidden .svn files and also files in /build/ directories.
+        </p>
+
+        <source xml:space="preserve">
+echo "sed '/\.svn/d;/\/build\//d;/\/work\//d'" &gt; ~/bin/exclude-find-svn
+chmod +x ~/bin/exclude-find-svn</source>
+        <p>
+          Now we will run find, use grep to search for the pattern in each
+          file and list the filenames. However, there is a stack of
+          forrest.properties files from the plugins, and there is i18n:text
+          being used in the viewHelper plugin, and some DTDs.
+          So weed them out ...
+        </p>
+
+        <source xml:space="preserve">
+cd /svn/asf/forrest-trunk
+find . -type f | xargs grep -l "i18n" | ~/bin/exclude-find-svn \
+ | grep -v "forrest.properties" | grep -v viewHelper | grep -v "\/schema\/"</source>
+
+        <p>
+          The list of files shows that there is an FAQ about i18n, there are
+          various sitemaps in main/webapp/, some stylesheets in
+          main/webapp/skins/common/ and pelt, some other stylesheets in
+          main/webapp/resources/stylesheets/ ... we will look at the sitemaps
+          first. Use grep to list the actual matches and the filenames.
+        </p>
+        <source xml:space="preserve">
+cd main/webapp
+grep i18n *.*</source>
+        <p>
+          Shows that five sitemaps are involved in some way. Always start with
+          sitemap.xamp and forrest.xmap as they do initial processing and
+          then delegate to other sitemaps. Open each file in your editor,
+          and search within for each "i18n" match. See that the xslt transformer 
+          is declared to use i18n, then further down the page the "skinit"
+          pipeline uses the i18n transformer only if i18n is switched on.
+        </p>
+      </section>
+
+      <section id="tips-find">
+        <title>Tips</title>
+        <ul>
+          <li>
+####
+          </li>
+        </ul>
+      </section>
+    </section>
+
+<!-- template
+    <section id="foo">
+      <title>Foo</title>
+      <p>
+####
+      </p>
+      <section id="foo-1">
+        <title>foo</title>
+        <p>
+####
+        </p>
+      </section>
+
+      <section id="tips-foo">
+        <title>Tips</title>
+        <ul>
+          <li>
+####
+          </li>
+        </ul>
+      </section>
+    </section>
+-->
+
+  </section><section id="Frequently Asked Questions"><title>Frequently Asked Questions</title><section><title>1 General issues</title><section><title>1.1 FAQ 1</title>
+          <p>
+####
+          </p>
+        </section></section><section><title>2 Other issues</title><section><title>2.1 FAQ 2.1</title>
+          <p>
+###
+          </p>
+        </section></section></section><section id="Tips"><title>Tips</title>
+    <p>
+      This is a collection of general tips that do not fit in the sections above. 
+    </p>
+
+    <section id="tip-howto">
+      <title>Explanations about howto topics on the mailing lists</title>
+
+      <p>
+        Often there are useful discussions on the mailing lists which explain
+        how to do certain tasks. If you don't have time to summarise that and
+        add to this howto document, then please consider just adding a tip
+        which links to the email discussion. Later someone else can summarise.
+      </p>
+    </section>
+  </section><section id="References"><title>References</title>
+    <p>
+      These are some other documents that are useful for developers.
+    </p>
+
+    <ul>
+      <li>
+###
+      </li>
+    </ul>
+  </section></body></document>
\ No newline at end of file

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

Added: forrest/site/docs_0_80/howto/howto-dispatcher-quickstart.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-dispatcher-quickstart.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-dispatcher-quickstart.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-dispatcher-quickstart.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2006 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><document><header>
+   <title>Dispatcher quickstart</title>
+    <version>0.2</version>
+    <last-modified-content-date date="2006-02-02"/>
+  </header><body><section id="Intended Audience"><title>Intended Audience</title>
+    <p>People who are helping to develop the Dispatcher.</p>
+    <warning> The "Dispatcher" (previously known as "Views") is new functionality which is 
+      still in development phase. That is why it is in the "whiteboard" section 
+      of Forrest. This document will also need to change to keep pace.
+      We are working at the moment on moving this plugin
+      from the whiteboard into the core plugins.
+    </warning>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>
+      This document will get you started. We will Dispatcher-enable an
+      existing site and show how to add/remove ready-made contacts.
+      Then we will discuss how add your own new contracts.
+    </p>
+    <p>
+      This document encourages developers to get involved with
+      fine-tuning and testing the dispatcher. Please help to
+      enhance the current core contracts so that people do not
+      need to re-invent the wheel.
+    </p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <ul>
+      <li>Using Forrest trunk of SVN (i.e. forrest-0.8-dev).
+        Must be after r373699, preferably head of trunk.
+      </li>
+      <li>Followed the installation instructions below.</li>
+      <li>You have an existing forrest site and want to try the
+        new Dispatcher. Otherwise create a 'forrest seed-sample' site.</li>
+    </ul>
+  </section><section id="Steps"><title>Steps</title>
+    <note> When developing with the dispatcher we assume you are using 'forrest 
+      run' and the following workflow "change files -&gt; refresh browser".<br/> 
+      Installing a mozilla browser and the 
+      <a href="site:forrestbar">Forrestbar</a> helps a lot with developing,
+      but is not necessary.
+    </note>
+
+    <section id="patch">
+      <title>Get ready</title>
+      <ul>
+        <li>Do 'svn update' or at least use r373699.</li>
+        <li>Apply the patch from https://issues.apache.org/jira/browse/FOR-796</li>
+        <li>Deploy both dispatcher plugins.</li>
+      </ul>
+      <source xml:space="preserve">
+cd whiteboard/plugins/org.apache.forrest.plugin.internal.dispatcher
+$FORREST_HOME/tools/ant/bin/ant local-deploy
+cd ../org.apache.forrest.themes.core
+$FORREST_HOME/tools/ant/bin/ant local-deploy
+      </source>
+    </section>
+
+    <section id="enable">
+      <title>Dispatcher-enable the existing site</title>
+      <ul>
+        <li>Add the new plugins to forrest.properties ...
+        ,org.apache.forrest.plugin.internal.dispatcher,org.apache.forrest.themes.core
+        </li>
+        <li>Deploy both dispatcher plugins with etc/structurer.sh</li>
+        <li>localhost:8888/index.html ... fantastic. See the default view.</li>
+      </ul>
+    </section>
+
+    <section id="another-theme">
+      <title>Use another theme</title>
+      <ul>
+        <li>Add project.theme=pelt to forrest.properties</li>
+        <li>Re-start 'forrest run'</li>
+        <li>localhost:8888/index.html ... See the new view.</li>
+      </ul>
+    </section>
+
+    <section id="our-structurer">
+      <title>Create our own structurer by copy-and-customise</title>
+      <p>
+        Copy the default structurer for the pelt theme and make local changes.
+      </p>
+      <note>
+        At this stage of rapid development of the Dispatcher, be sure to keep
+        your copy synchronised. Use 'diff' against the known svn version of
+        the core pelt.fv to track your local changes.
+        Also please consider contributing new contracts and changes to the
+        default structurers to the Forrest projects. That eases your local
+        version management and everyone will benefit.
+      </note>
+      <ul>
+        <li>Copy THEMER_PLUGIN/resources/themes/pelt.fv into your project at
+          PROJECT_HOME/src/documentation/resources/themes/pelt.fv
+          (create the new directory folder first).
+        </li>
+        <li>Re-start 'forrest run'</li>
+        <li>localhost:8888/index.html ... See the same view, now structured
+          by us.
+        </li>
+      </ul>
+      <p>
+        From here on there is no need to re-start 'forrest run'. Just edit
+        the structurer and see the effect.
+      </p>
+    </section>
+
+    <section id="remove-default-contract">
+      <title>Remove a default contract</title>
+      <ul>
+        <li>Remove one of the search boxes. Edit your pelt.fv and find the
+          "search-input" contract (there are two). Comment one out.
+        </li>
+      </ul>
+    </section>
+
+    <section id="add-default-contract">
+      <title>Add a default contract</title>
+      <p>
+        Forrest provides many default contracts. If you are using the
+        Forrestbar then choose "Devs =&gt; ls.contracts". Otherwise visit
+        localhost:8888/ls.contracts.html
+      </p>
+      <ul>
+        <li>
+          See the usage detail for your chosen contract via the abovementioned list.
+          e.g. "siteinfo-compliance-links"
+        </li>
+        <li>
+          Insert it at the appropriate point in your structurer. Note that it
+          will need to go inside the appropriate CSS hook, e.g.
+        <source xml:space="preserve">  ...
+  &lt;forrest:hook name="footer"&gt;
+    &lt;forrest:contract name="siteinfo-compliance-links"/&gt;
+    ...
+</source>
+        </li>
+      </ul>
+      <p>
+        Notice that you did not need to copy any other code to your project space.
+        Forrest finds the default contract in its core (the theme.core plugin).
+      </p>
+    </section>
+
+    <section id="add-project-contract">
+      <title>Add a new project contract</title>
+      <warning>
+        Carefully consider the purpose of your contracts. If they are useful
+        in a wider context, then they belong in plugins or the core of Forrest.
+        See below for further discussion on this important topic.
+      </warning>
+      <p>
+        Project-based contracts are defined in theme-specific and
+        output-format-specific directory structure, e.g.
+        PROJECT_HOME/src/documentation/resources/themes/THEME_NAME/OUTPUT_FORMAT/
+      </p>
+      <p>
+       Project-based contracts common to all themes go in
+        PROJECT_HOME/src/documentation/resources/themes/common/OUTPUT_FORMAT/
+      </p>
+      <p>
+        To get started quickly (it is not a project-based contract but a demo),
+        copy one of the default contracts. e.g. copy siteinfo-current-time.ft to become siteinfo-doodad.ft ...
+      </p>
+      <ul>
+        <li>
+          Copy THEMER_PLUGIN/resources/themes/common/html/siteinfo-current-time.ft
+          into your project at
+          PROJECT_HOME/src/documentation/resources/themes/common/html/siteinfo-doodad.ft
+          (create the new directory folders first).
+        </li>
+        <li>
+          Edit it to suit. Replace all occurrences of "siteinfo-current-time" with
+          "siteinfo-doodad" and make your other changes (e.g. the text and the
+          javascript function).
+        </li>
+        <li>
+          Declare your new contract in your structurer as done above for adding a
+          default contract.
+        </li>
+      </ul>
+      <p>
+        See a list of your project-based contracts and their usage notes via 
+        Forrestbar "Devs =&gt; ls.contracts.project". Otherwise visit
+        localhost:8888/ls.contracts.project.html
+      </p>
+    </section>
+
+<!--
+    <section id="newSection">
+      <title>newSection</title>
+      <ul>
+        <li></li>
+      </ul>
+    </section>
+-->
+
+<!--
+    <section id="notes">
+      <title>Notes</title>
+        <source><![CDATA[
+
+]]></source>
+    </section>
+-->
+
+    <section id="manage">
+      <title>Decide how to manage your contracts</title>
+<fixme author="crossley">
+Glean content from Ross' discussion:
+<a href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=113748831226697">Re: Dispatcher quickstart</a>.
+</fixme>
+    </section>
+  </section><section id="Further Reading"><title>Further Reading</title>
+    <p> Congratulations you are now able to work with the Dispatcher. From here 
+      we recommend to read the following How-Tos: </p>
+    <ul>
+      <li>
+        <a href="site:v0.80//howto/dispatcher/structurer">How to use the structurer</a>
+      </li>
+      <li>
+        <a href="site:v0.80//howto/dispatcher/structurer">Create your own contract 
+          implementation</a>
+      </li>
+    </ul>
+  </section><section id="Feedback"><title>Feedback</title>
+    <p> Please provide feedback about this document via the <a href="site:mail-lists">mailing lists</a>. </p>
+  </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/howto/howto-dispatcher-quickstart.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/howto-editcss.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-editcss.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-editcss.source.xml (added)
+++ forrest/site/docs_0_80/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_80/howto/howto-editcss.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/howto-forrest-from-maven.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-forrest-from-maven.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-forrest-from-maven.source.xml (added)
+++ forrest/site/docs_0_80/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_80/howto/howto-forrest-from-maven.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/howto-howto.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-howto.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-howto.source.xml (added)
+++ forrest/site/docs_0_80/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 ensure 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. Look at 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 document. 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-v20-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 at some time. 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_80/howto/howto-howto.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/howto-pdf-tab.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-pdf-tab.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-pdf-tab.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-pdf-tab.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,213 @@
+<?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 create a PDF document for each tab</title>
+  <abstract>This How-To describes the generation of a PDF document for each
+    group of documents that is defined by a tab. 
+  </abstract>
+  <last-modified-content-date date="2005-07-19"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+    <p>
+      Users who need to generate one printable document aggregated from a
+      group of documents.
+    </p>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>
+      By default Forrest generates a pdf file for each separate document of
+      your project.
+      As well you can create a pdf of the whole site. But sometimes it may
+      be necessary to generate a pdf file out of selected tab, i.e. only for
+      certain parts of the site.
+    </p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <ul>
+      <li>Understand how to create project-specific sitemaps by following the
+      <link href="site:v0.80//your-project">Using Forrest</link> document.</li>
+    </ul>
+  </section><section id="Steps"><title>Steps</title>
+    <p>The procedure outlined below will define a project
+      <code>sitemap.xmap</code> and create a new
+      <code>pdf-tab.xmap</code>.
+    </p>
+  <section id="sitemap">
+    <title>Create your project's main sitemap.xmap</title>
+    <p>
+      If you do not have already a sitemap then create a new empty one in your
+      <code>src/documentation</code> directory (or wherever
+      ${project.sitemap-dir} points to).
+    </p>
+  </section>
+
+  <section id="aggregator">
+    <title>Create another sitemap: pdf-tab.xmap</title>
+    <p>
+    Like before create an empty sitemap and name it pdf-tab.xmap.
+    </p>
+  </section>
+
+    <section id="mount">
+    <title>Edit project sitemap.xmap to mount pdf-tab.xmap</title>
+    <p>
+      Your sitemap should look something like this.
+    </p>
+    <source xml:space="preserve">
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+  &lt;map:pipelines&gt;
+    &lt;map:pipeline internal-only="false"&gt;
+      &lt;map:match pattern="**.xml"&gt;
+        &lt;!-- pdf-tab definitions --&gt;
+        &lt;map:match pattern="pdf-tab.xml"&gt;
+          &lt;map:mount uri-prefix="" src="pdf-tab.xmap"
+            check-reload="yes" /&gt;
+        &lt;/map:match&gt;
+        &lt;!-- end of pdf-tab definitions --&gt;
+      &lt;/map:match&gt;
+    &lt;/map:pipeline&gt;
+  &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+    </source>
+  </section>
+
+  <section id="edit-aggregator">
+    <title>Edit the file <code>pdf-tab.xmap</code></title>
+    <p>
+      The <code>&lt;map:match pattern="*.xml"&gt;</code> element
+      should look like the following:
+    </p>
+    <source xml:space="preserve">
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+  &lt;map:pipelines&gt;
+    &lt;map:pipeline internal-only="false"&gt;
+     &lt;map:match pattern="*.xml"&gt;
+	&lt;map:generate src="cocoon://abs-linkmap"/&gt;
+	  &lt;map:transform type="xpath"&gt;
+	  	&lt;map:parameter name="include" value="//*[@wholesite='true']"/&gt;
+		&lt;map:parameter name="exclude" value="//*[@wholesite='false']"/&gt;
+	  &lt;/map:transform&gt;
+	  &lt;map:transform src="resources/stylesheets/site2book.xsl" /&gt;
+	  &lt;map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl"&gt;
+	     &lt;map:parameter name="title"
+		value="{conf:project-name}: Still My Foo Site"/&gt;
+	     &lt;/map:transform&gt;
+	  &lt;map:transform type="cinclude"/&gt;
+	  &lt;map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/&gt;
+	  &lt;map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/&gt;
+	  &lt;map:serialize type="xml"/&gt;
+    &lt;/map:match&gt;    
+   &lt;/map:pipeline&gt;
+  &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+    </source>
+  </section>
+  <section id="edit-site">
+    <title>Edit your site.xml</title>
+     <note>
+        Do not use directories with "." in it. Replace them by "_"
+        e.g 1.2/ will not work in the aggregation. e.g. 1_2/ just works fine.
+    </note>
+    <p>
+      Add the following entry to your site.xml in the
+      <code>&lt;about&gt;</code> element
+    </p>
+    <source xml:space="preserve">... 
+&lt;whole_foosite href="pdf-tab.html" label="sub site" /&gt;
+    </source>
+    <p>
+      Your site.xml should look like this ...
+    </p>
+    <source xml:space="preserve">... 
+&lt;about label="About"&gt;
+  &lt;index label="Index" href="index.html" description="Welcome to MyProj"/&gt;
+  &lt;changes label="Changes" href="changes.html"
+    description="History of Changes" /&gt;
+  &lt;todo label="Todo" href="todo.html" description="Todo List" /&gt;
+  &lt;whole_foosite href="pdf-tab.html" label="pdf-tab" /&gt;
+&lt;/about&gt;
+...
+    </source>
+    <p>
+      This allows you to link to it via a
+      <code>&lt;link href="site:whole_foosite"&gt;</code>
+      reference. 
+    </p>
+	  <p>Add to every element that should be included in the pdf-tab.pdf
+      the attribute <code>wholesite="true"</code></p>
+	  <source xml:space="preserve">
+&lt;sample-wiki label="Wiki page" href="wiki-sample.html"
+  description="wiki-sample" wholesite="true"/&gt;
+	  </source>
+	  <note>This attribute will be inherited by all children of the element. 
+	 Do not use it in the parent element that contains the 
+	 <code>&lt;whole_foosite href="pdf-tab.html" label="pdf-tab" /&gt;</code> 
+	 as the child (will cause a <code>stack overflow</code> if you do)!!!
+	</note>
+  </section>
+  <section id="explain">
+    <title>Explanation of the operation</title>
+    <p>
+      Line 4 of our example
+      <br/>
+      <code>&lt;map:parameter name="include" value="//*[@wholesite='true']"/&gt;</code>
+      looks at your site.xml and will match every element containing the
+      <code>wholesite="true"</code> attribute. For example, to use the "samples"
+      tab ...
+    </p>
+    <source xml:space="preserve">
+...
+&lt;samples label="Samples" href="samples/" tab="samples" wholesite="true"&gt;
+...
+&lt;/samples&gt;
+...
+    </source>
+    <p>
+      It matches <strong>all</strong> of the elements that contain
+      <code>wholesite="true"</code>
+      (in our example <code>&lt;samples&gt;</code>
+      and its "children") for the content of the pdf file to be generated.
+    </p>
+    <source xml:space="preserve"> 
+&lt;samples label="Samples" href="samples/" tab="samples" wholesite="true"&gt;
+ &lt;sample2 label="Static content" href="sample2.html"      
+   description="More Samples" wholesite='false'/&gt;
+ &lt;sample-wiki label="Wiki page" href="wiki-sample.html"      
+   description="wiki-sample" /&gt;
+ &lt;sample-ihtml label="ihtml page" href="ihtml-sample.html"      
+   description="Test iHTML page" /&gt;
+&lt;/samples&gt;     	
+    </source>
+    <p>
+      This example shows that you can as well exclude site(s) from the aggregation 
+      by using the <code>wholesite="false"</code> attribute. This attribute will be as well inherited 
+      by all children of the element.
+    </p>
+    <p>
+      Line 8 defines the title of the pdf file by taking the content
+      of the project-name variable in
+      <code>skinconf.xml</code> and adding some funny text:
+      <br/>
+      <code>&lt;map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/&gt;</code>
+    </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
+      <link href="site:mail-lists">mailing lists</link>.
+    </p>
+    <p>
+      In the future, this ability will probably be incorporated into the
+      main Forrest process.
+    </p>
+  </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/howto/howto-pdf-tab.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/howto-structurer-contracts.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-structurer-contracts.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/howto-structurer-contracts.source.xml (added)
+++ forrest/site/docs_0_80/howto/howto-structurer-contracts.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,293 @@
+<?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 forrest:contract?</title>
+  <abstract>
+    This How-To will explain how we wrote the contracts for the dispatcher and hope afterwards you will be able to do the same.
+  </abstract>
+  <last-modified-content-date date="2005-07-17"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+<warning>
+The "Dispatcher" (aka "Views") is new functionality which is still in development phase. That is why it is in the
+"whiteboard" section of the Forrest distribution. This HowTo is a good start but still needs more work.
+</warning>
+    <p>
+      Devs and skin developer that wants to get started with forrest:contract development. 
+      To really understand this how-to you need basic and sometimes advanced understanding of 
+      the "old fashion" skin development process.
+    </p>
+    <note>
+       For the moment we will use a special seed template called seed-v2. We still 
+        need to fix issues of the dispatcher that it really can replace old 
+        fashion skins. Like performance, standalone contracts, other testing output/input formats - using POJO based 
+        processing will help solving this.  All this will ATM happen in the v2 seed-target till the dispatcher will 
+        be realesed to the stable plugins. So make regular updates of your forrest-trunk to keep track.
+    </note>
+    <warning>
+      The way we develope contracts will/may change with introduction of java based processing rather then xsl. Please keep this in mind
+        and help updating the documentation by sending patches. TIA. ;-)
+    </warning>
+  </section><section id="Purpose"><title>Purpose</title>
+    <p>
+      This setup guide will explain how to create a forrest:contract from scratch and 
+      how this forrest:contract work with the core parts of forrest.
+    </p>
+  </section><section id="Prerequisites"><title>Prerequisites</title>
+    <ul>
+      <li>
+        You have a ready-to-go new seed-v2 (v2) based on the dispatcher like described in <a href="site:howto/dispatcher/install">Install</a>.
+      </li>
+      <li>
+        Reading that how-to is as well a good idea to understand the used directory structure in this how-to.
+      </li>
+      <li>Installing a mozilla browser and the forrestbar helps a lot in developing.</li>
+    </ul>
+  </section><section id="Steps"><title>Steps</title>
+    <note>The following content is from many mails around the topic, this how-to tries to be the 
+      consolidation of this thread. It is mainly based on the thread "[RT] Why using views" - 
+      in comparison with "old fashion" skins - usecase i18n</note>
+    <p>
+      By working on the i18n integration for "pelt" we again encountered the reasons for using the dispatcher. ;-)
+      The maintenance problem was to change the captions of the skin features (contracts) to enable
+      support for i18n. The case is that the <code>site2xhtml.xsl</code> has a lot of repeating code. 
+    </p>
+    <p>
+      For example the "last-publish"-contract could be found 2 times in the code.  
+      This is not the only contract that was (is) doubled in the code. The problem with that is that 
+      we needed to search the code for each caption and senselessly repeat the following 
+      maintenance step of adding the &lt;i18n:text/&gt;-tags.
+    </p>
+    <source xml:space="preserve">
+
+- &lt;script language="JavaScript"
+- type="text/javascript"&gt;document.write("Published: " + document.lastModified);&lt;/script&gt;
+
++ &lt;script type="text/javascript"&gt;document.write("&lt;i18n:text &gt;Last
++ Published:&lt;/i18n:text&gt;&amp;#160;" + document.lastModified);
+
+    </source>
+    <section id="enhanceMaintenance">
+      <title>Enhance the maintenance</title>
+      <p>Now we can enhance the maintenance for the future and we give these code snippets 
+        contracts names (based on their functionality). This naming enables us to keep
+the contract separate from the position code itself. In xsl you would
+simply do:
+      </p>
+      <ol>
+        <li>replace the script by &lt;xsl:call-template name="siteinfo-last-published"/&gt;</li>
+        <li>and add:</li>
+      </ol>
+      
+      <source xml:space="preserve">&lt;xsl:template name="siteinfo-last-published"&gt;
+ &lt;script type="text/javascript"&gt;
+  document.write("&lt;i18n:text &gt;Last Published:&lt;/i18n:text&gt;&amp;#160;" + document.lastModified);
+ &lt;/script&gt;
+&lt;/xsl:template&gt;
+      </source>
+      <p>
+        This allows us in a next maintenance to just change the code of
+        &lt;xsl:template name="siteinfo-last-published"/&gt; and apply it in any position where
+        it is placed.  
+      </p>
+      <note>
+        Now this refactoring of the site2xhtml.xsl is exactly what we doing in creating contracts for the dispatcher.
+      </note>
+    </section>
+    <section id="blankContract">
+      <title>Explaining the blank forrest:contract</title>
+      <p>
+        To start a new forrest:contract you can copy the 'blank.ft' from
+        <code>org.apache.forrest.plugin.output.themer/resources/themes/common/html/blank.ft</code>. 
+      </p>
+      <p>
+        The 'blank.ft' is a simple xml file with the following code which you can use to base new contracts 
+        on:
+      </p>
+      <source xml:space="preserve">
+&lt;forrest:contract 
+  xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+  xmlns:forrest="http://apache.org/forrest/templates/1.0"
+  name="blank" type="nugget"&gt;
+  
+  &lt;!--NOTE: 
+    When using the blank template as c'n p master just search and replace 'blank' by the {contract-name}!--&gt;
+  
+  &lt;description&gt;
+    {contract-name} will output {contract-funtion}. This is just a blank contract, it will output *nothing*.
+  &lt;/description&gt;
+  &lt;usage&gt;&lt;![CDATA[&lt;forrest:contract name="blank"/&gt;]]&gt;&lt;/usage&gt;
+  &lt;forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0"
+    format="html" name="blank" inputFormat="xsl" body="false" head="false"&gt;
+    &lt;xsl:stylesheet version="1.1" 
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
+        &lt;!--
+          Add here the needed templates.
+          Remember to set the forrest:template @attributes!
+          --&gt;
+         &lt;!--
+        &lt;xsl:template name="blank-head"&gt;
+        &lt;/xsl:template&gt;
+        &lt;xsl:template name="blank-body"&gt;
+        &lt;/xsl:template&gt;
+        --&gt;
+    &lt;/xsl:stylesheet&gt;
+  &lt;/forrest:template&gt;
+&lt;/forrest:contract&gt;
+      </source>
+      <p>
+        The most important is the name of the contract <code>&lt;forrest:contract name="blank"/&gt;</code>. 
+        This name is the same as the file name of the contract (without file extension) <code>blank.ft</code>. 
+      </p>
+      <note>This is a <strong>naming convention</strong> that you need
+        to always meet. All @name attributes must be the file name of the contract without file extension.
+      </note>
+      <p>
+        The <code>&lt;description/&gt;</code> tag needs to be filled in with some information
+        that is explaining the contract to the webdesigner. The better explained the more efficient
+        for the webdesigner to pick the right contract.
+      </p>
+      <source xml:space="preserve">&lt;description&gt;
+  siteinfo-last-published-howto will output the last published date of the site with the help of jscript.
+&lt;/description&gt;
+      </source>
+      <p>
+        In the <code>&lt;usage/&gt;</code> tag we have to explain how the designer can use 
+        the contract in his structurer.
+      </p>
+      <source xml:space="preserve">&lt;usage&gt;&lt;![CDATA[&lt;forrest:contract name="siteinfo-last-published-howto"/&gt;]]&gt;&lt;/usage&gt;
+      </source>
+      <p>
+        <code>&lt;forrest:template name="blank" body="false" head="false"&gt; </code> 
+        That leads to the template attribute @body="true" and
+        @head="false". In html a contract can add content to the &lt;body/&gt; or/and
+        &lt;head/&gt; part of &lt;html/&gt;. These values need to be changed when adding an actual template.
+        Besides this, a xsl-template needs to indicate this in the naming. A template that adds content to the 
+        html body needs to end with "<code>-body</code>"!!!
+      </p>
+      <warning>
+        The last paragraph about &lt;forrest:template name="blank" body="false" head="false"&gt; is due to change. 
+        Please be aware that this part of the dispatcher is the main moving target right now!!!
+      </warning>
+      <note>
+        It is possible to use contracts in different in/output formats. 
+        We are focussing for now on format="html" as output and the inputFormat="xsl".
+      </note>
+      <p>
+        A &lt;forrest:template /&gt; has the child &lt;xsl:stylesheet/&gt; where we can create 
+        templates for the html-head and html-body. For adding content into the body of the final 
+        document change @body="true" and add:
+      </p>
+      <source xml:space="preserve">
+&lt;xsl:stylesheet version="1.1" 
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
+ &lt;!--Add here the needed templates--&gt;
+ &lt;xsl:template name="blank-body"/&gt;
+&lt;/xsl:stylesheet&gt;        
+      </source>
+    </section>
+    <section id="newContract">
+      <title>Create a new contract</title>
+      <note>
+        We use basic naming convention for contracts. Like
+        "naming does not say anything about layout position, but functionality of the contract".
+      </note>
+      <p> 
+        Now let us pick up the example we started with and create a "siteinfo-last-published-howto" contract.
+        Save the blank.ft to <code>{project.home}/src/documentation/resources/themes/common/html/siteinfo-last-published-howto.ft</code>.
+      </p>
+      <p>
+        Now the maintenance-optimized code (xpath="/html/body/*") was:
+      </p>
+      <source xml:space="preserve">
+&lt;xsl:template name="siteinfo-last-published"&gt;
+ &lt;script type="text/javascript"&gt;
+  document.write("&lt;i18n:text &gt;Last Published:&lt;/i18n:text&gt;&amp;#160;" + document.lastModified);
+ &lt;/script&gt;
+&lt;/xsl:template&gt;</source>
+      <p>
+        In this code we have to do the following steps to use it in our contract:
+      </p>
+      <ul>
+        <li>Search and replace "siteinfo-last-published" with "siteinfo-last-publish-howto-body"</li>
+        <li>Add a "debug string - " to the template</li>
+      </ul>
+      <p>
+        The contract after this steps should look like:
+      </p>
+      <source xml:space="preserve">
+&lt;xsl:template name="siteinfo-last-publish-howto-body"&gt;
+debug string - 
+ &lt;script type="text/javascript"&gt;
+  document.write("&lt;i18n:text &gt;Last Published:&lt;/i18n:text&gt;&amp;#160;" + document.lastModified);
+ &lt;/script&gt;
+&lt;/xsl:template&gt;</source>
+      <p>Now we have to do some last steps in the siteinfo-last-publish-howto.ft</p>
+      <ul>
+        <li>Search and replace "blank" with "siteinfo-last-publish-howto"</li>
+        <li>Add description and usage of the contract</li>
+        <li>Set @body="true"</li>
+        <li>Copy the maintenance optimized code to the contract.</li>
+      </ul>
+      <p>
+        As the result your code should look like this:
+      </p>
+      <source xml:space="preserve">&lt;forrest:contract xmlns:forrest="http://apache.org/forrest/templates/1.0"
+  name="siteinfo-last-published-howto" type="nugget"&gt;
+  &lt;description&gt;
+    siteinfo-last-published-howto will output the last published date of the site with the help of jscript.
+  &lt;/description&gt;
+  &lt;usage&gt;&lt;![CDATA[&lt;forrest:contract name="siteinfo-last-published-howto"/&gt;]]&gt;&lt;/usage&gt;
+  &lt;forrest:template 
+    xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+    xmlns:forrest="http://apache.org/forrest/templates/1.0"
+    format="html" name="siteinfo-last-published-howto" inputFormat="xsl" body="true" head="false"&gt;
+    &lt;xsl:stylesheet version="1.1" 
+        xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
+        &lt;xsl:template name="siteinfo-last-published-howto-body"&gt;
+          debug string - 
+          &lt;script type="text/javascript"&gt;document.write("&lt;i18n:text &gt;Last Published:&lt;/i18n:text&gt;&amp;#160;" + document.lastModified);&lt;/script&gt;
+        &lt;/xsl:template&gt;
+    &lt;/xsl:stylesheet&gt;
+  &lt;/forrest:template&gt;
+&lt;/forrest:contract&gt;
+      </source>
+    </section>
+    <section id="structurerContract">
+      <title>Activating the contract</title>
+      <p>
+        To see whether the new contract works we need to add it to our structurer.
+        The contract usage contains the contract-tag <code>&lt;forrest:contract name="siteinfo-last-published-howto"/&gt;</code>
+        Please see <a href="site:v0.80//howto/dispatcher/structurer">Getting started with the "structurer"</a> for more details.
+      </p>
+       <note>
+        Next to write are parameter-contracts with advanced features of the dispatcher. 
+      </note>
+    </section>
+  </section><section id="Further Reading"><title>Further Reading</title>
+    <p>
+      Congratulations you are now able to work with structurer contracts. 
+      From here we recommend to read the following How-To's (if not already done):
+    </p>
+    <ul>
+      <li><a href="site:v0.80//howto/dispatcher/structurer">Getting started with the "structurer"</a> </li>
+    </ul>
+  </section><section id="Feedback"><title>Feedback</title>
+    <p>
+      Please provide feedback about this document via the
+      <a href="site:mail-lists">mailing lists</a>.
+    </p>
+  </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/howto/howto-structurer-contracts.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message