You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2006/02/09 01:26:32 UTC
svn commit: r376128 [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...
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&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">
+<map:match pattern="*.html">
+ <map:generate src="sources/{1}.xml"/><strong>
+ <map:transform type="log">
+ <map:parameter name="logfile" value="my-1.log"/>
+ <map:parameter name="append" value="no"/>
+ </map:transform></strong>
+ <map:transform src="stylesheets/source-to-table.xsl"/>
+ <map:transform src="stylesheets/table-to-page.xsl"/><strong>
+ <map:transform type="log">
+ <map:parameter name="logfile" value="my-2.log"/>
+ <map:parameter name="append" value="no"/>
+ </map:transform></strong>
+ <map:transform src="stylesheets/page-to-html.xsl"/>
+ <map:serialize type="html"/>
+</map:match>
+</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'" > ~/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 -> 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 => 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"> ...
+ <forrest:hook name="footer">
+ <forrest:contract name="siteinfo-compliance-links"/>
+ ...
+</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 => 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&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">
+<property environment="env" />
+ </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">
+<goal name="forrest" description="runs Forrest">
+ <property name="forrest.home" location="${env.FORREST_HOME}" />
+ <property name="forrest.ant.home" location="${forrest.home}/tools/ant" />
+ <java classname="org.apache.tools.ant.Main" fork="true" failonerror="true" maxmemory="128M">
+ <classpath>
+ <fileset dir="${forrest.ant.home}/lib">
+ <include name="*.jar" />
+ </fileset>
+ <pathelement path="${java.home}/../lib/tools.jar" />
+ </classpath>
+ <sysproperty key="ant.home" value="${forrest.ant.home}" />
+ <sysproperty key="forrest.home" value="${forrest.home}" />
+ <sysproperty key="basedir" value="${basedir}" />
+ <sysproperty key="java.endorsed.dirs" value="${forrest.home}/lib/endorsed" />
+ <arg line="-f ${forrest.home}/main/forrest.build.xml" />
+ </java>
+</goal>
+ </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">
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline internal-only="false">
+ <map:match pattern="**.xml">
+ <!-- pdf-tab definitions -->
+ <map:match pattern="pdf-tab.xml">
+ <map:mount uri-prefix="" src="pdf-tab.xmap"
+ check-reload="yes" />
+ </map:match>
+ <!-- end of pdf-tab definitions -->
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+ </source>
+ </section>
+
+ <section id="edit-aggregator">
+ <title>Edit the file <code>pdf-tab.xmap</code></title>
+ <p>
+ The <code><map:match pattern="*.xml"></code> element
+ should look like the following:
+ </p>
+ <source xml:space="preserve">
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline internal-only="false">
+ <map:match pattern="*.xml">
+ <map:generate src="cocoon://abs-linkmap"/>
+ <map:transform type="xpath">
+ <map:parameter name="include" value="//*[@wholesite='true']"/>
+ <map:parameter name="exclude" value="//*[@wholesite='false']"/>
+ </map:transform>
+ <map:transform src="resources/stylesheets/site2book.xsl" />
+ <map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl">
+ <map:parameter name="title"
+ value="{conf:project-name}: Still My Foo Site"/>
+ </map:transform>
+ <map:transform type="cinclude"/>
+ <map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/>
+ <map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/>
+ <map:serialize type="xml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+ </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><about></code> element
+ </p>
+ <source xml:space="preserve">...
+<whole_foosite href="pdf-tab.html" label="sub site" />
+ </source>
+ <p>
+ Your site.xml should look like this ...
+ </p>
+ <source xml:space="preserve">...
+<about label="About">
+ <index label="Index" href="index.html" description="Welcome to MyProj"/>
+ <changes label="Changes" href="changes.html"
+ description="History of Changes" />
+ <todo label="Todo" href="todo.html" description="Todo List" />
+ <whole_foosite href="pdf-tab.html" label="pdf-tab" />
+</about>
+...
+ </source>
+ <p>
+ This allows you to link to it via a
+ <code><link href="site:whole_foosite"></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">
+<sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" wholesite="true"/>
+ </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><whole_foosite href="pdf-tab.html" label="pdf-tab" /></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><map:parameter name="include" value="//*[@wholesite='true']"/></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">
+...
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+...
+</samples>
+...
+ </source>
+ <p>
+ It matches <strong>all</strong> of the elements that contain
+ <code>wholesite="true"</code>
+ (in our example <code><samples></code>
+ and its "children") for the content of the pdf file to be generated.
+ </p>
+ <source xml:space="preserve">
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+ <sample2 label="Static content" href="sample2.html"
+ description="More Samples" wholesite='false'/>
+ <sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" />
+ <sample-ihtml label="ihtml page" href="ihtml-sample.html"
+ description="Test iHTML page" />
+</samples>
+ </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><map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/></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 <i18n:text/>-tags.
+ </p>
+ <source xml:space="preserve">
+
+- <script language="JavaScript"
+- type="text/javascript">document.write("Published: " + document.lastModified);</script>
+
++ <script type="text/javascript">document.write("<i18n:text >Last
++ Published:</i18n:text>&#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 <xsl:call-template name="siteinfo-last-published"/></li>
+ <li>and add:</li>
+ </ol>
+
+ <source xml:space="preserve"><xsl:template name="siteinfo-last-published">
+ <script type="text/javascript">
+ document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
+ </script>
+</xsl:template>
+ </source>
+ <p>
+ This allows us in a next maintenance to just change the code of
+ <xsl:template name="siteinfo-last-published"/> 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">
+<forrest:contract
+ xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+ xmlns:forrest="http://apache.org/forrest/templates/1.0"
+ name="blank" type="nugget">
+
+ <!--NOTE:
+ When using the blank template as c'n p master just search and replace 'blank' by the {contract-name}!-->
+
+ <description>
+ {contract-name} will output {contract-funtion}. This is just a blank contract, it will output *nothing*.
+ </description>
+ <usage><![CDATA[<forrest:contract name="blank"/>]]></usage>
+ <forrest:template xmlns:forrest="http://apache.org/forrest/templates/1.0"
+ format="html" name="blank" inputFormat="xsl" body="false" head="false">
+ <xsl:stylesheet version="1.1"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <!--
+ Add here the needed templates.
+ Remember to set the forrest:template @attributes!
+ -->
+ <!--
+ <xsl:template name="blank-head">
+ </xsl:template>
+ <xsl:template name="blank-body">
+ </xsl:template>
+ -->
+ </xsl:stylesheet>
+ </forrest:template>
+</forrest:contract>
+ </source>
+ <p>
+ The most important is the name of the contract <code><forrest:contract name="blank"/></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><description/></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"><description>
+ siteinfo-last-published-howto will output the last published date of the site with the help of jscript.
+</description>
+ </source>
+ <p>
+ In the <code><usage/></code> tag we have to explain how the designer can use
+ the contract in his structurer.
+ </p>
+ <source xml:space="preserve"><usage><![CDATA[<forrest:contract name="siteinfo-last-published-howto"/>]]></usage>
+ </source>
+ <p>
+ <code><forrest:template name="blank" body="false" head="false"> </code>
+ That leads to the template attribute @body="true" and
+ @head="false". In html a contract can add content to the <body/> or/and
+ <head/> part of <html/>. 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 <forrest:template name="blank" body="false" head="false"> 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 <forrest:template /> has the child <xsl:stylesheet/> 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">
+<xsl:stylesheet version="1.1"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <!--Add here the needed templates-->
+ <xsl:template name="blank-body"/>
+</xsl:stylesheet>
+ </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">
+<xsl:template name="siteinfo-last-published">
+ <script type="text/javascript">
+ document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
+ </script>
+</xsl:template></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">
+<xsl:template name="siteinfo-last-publish-howto-body">
+debug string -
+ <script type="text/javascript">
+ document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);
+ </script>
+</xsl:template></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"><forrest:contract xmlns:forrest="http://apache.org/forrest/templates/1.0"
+ name="siteinfo-last-published-howto" type="nugget">
+ <description>
+ siteinfo-last-published-howto will output the last published date of the site with the help of jscript.
+ </description>
+ <usage><![CDATA[<forrest:contract name="siteinfo-last-published-howto"/>]]></usage>
+ <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">
+ <xsl:stylesheet version="1.1"
+ xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <xsl:template name="siteinfo-last-published-howto-body">
+ debug string -
+ <script type="text/javascript">document.write("<i18n:text >Last Published:</i18n:text>&#160;" + document.lastModified);</script>
+ </xsl:template>
+ </xsl:stylesheet>
+ </forrest:template>
+</forrest:contract>
+ </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><forrest:contract name="siteinfo-last-published-howto"/></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