You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-svn@forrest.apache.org by cr...@apache.org on 2007/04/10 06:44:05 UTC
svn commit: r527020 [15/20] - in /forrest/site: ./ docs_0_80/
docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/
plan/ pluginDocs/plugins_0_70/ pluginDocs/plugins_0_80/ procedures/
procedures/release/ skins/ tools/
Modified: forrest/site/howto-dev.html
URL: http://svn.apache.org/viewvc/forrest/site/howto-dev.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/howto-dev.html (original)
+++ forrest/site/howto-dev.html Mon Apr 9 21:44:00 2007
@@ -232,8 +232,8 @@
</div>
<h1>How to be a Forrest developer</h1>
<div class="abstract">
- This How-To provides some tips and procedures for being a
- Forrest developer.
+ This How-To provides some tips and procedures for being a Forrest
+ developer.
</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -392,15 +392,15 @@
<div class="warning">
<div class="label">Warning</div>
<div class="content">
-This document is under initial development.
-</div>
+ This document is under initial development.
+ </div>
</div>
<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".
+ 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
@@ -412,18 +412,19 @@
<h2 class="underlined_10">Purpose</h2>
<div class="section">
<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.
+ 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>
<p>
- This document is intended to be an introduction to developing in Forrest, specifically,
- for those developers without a strong Cocoon background. Some key concepts in Forrest
- like sitemaps, pipelines, and locationmaps can be challenging enough to understand without
- also struggling with the fundamental development chores of debugging, extension methods, etc.
- The goal of this document is to reduce the steep learning curve by providing answers to
- some really practical Forrest development questions.
+ This document is intended to be an introduction to developing in Forrest,
+ specifically, for those developers without a strong Cocoon background.
+ Some key concepts in Forrest like sitemaps, pipelines, and locationmaps
+ can be challenging enough to understand without also struggling with the
+ fundamental development chores of debugging, extension methods, etc. The
+ goal of this document is to reduce the steep learning curve by providing
+ answers to some really practical Forrest development questions.
</p>
</div>
<a name="N10029"></a><a name="Prerequisites"></a>
@@ -452,23 +453,23 @@
<h2 class="underlined_10">Development techniques and scenarios</h2>
<div class="section">
<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.
+ 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
+ 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>
<a name="N1004A"></a><a name="dev-environment"></a>
<h3 class="underlined_5">Development environment</h3>
<p>
There is no *proper* dev environment. It really depends on your personal
- preferences. In an opensource project there is huge variety of environments.
- This makes it quite a challenge to keep sources consistent (see discussion below).
+ preferences. In an opensource project there is huge variety of
+ environments. This makes it quite a challenge to keep sources consistent
+ (see discussion below).
</p>
<p>
Some people use vi or emacs, others use graphical editors, others use
@@ -476,45 +477,44 @@
</p>
<p>
Ensure to <a href="docs_0_80/catalog.html">configure</a> your xml editor to take
- advantage of the local sets of DTDs provided by Forrest. This also explains how
- to use xml validators such as 'xmllint'. If your editor of choice doesn't
- validate XML, then most XML validation issues can be discovered using
- <span class="codefrag">forrest validate-xdocs</span>
+ advantage of the local sets of DTDs provided by Forrest. This also
+ explains how to use xml validators such as 'xmllint'. If your editor of
+ choice doesn't validate XML, then most XML validation issues can be
+ discovered using <span class="codefrag">forrest validate-xdocs</span>
</p>
<p>
- There really isn't much Java code in Forrest, but a Java Development Environment
- such as Eclipse or any text editor of your choice will work just fine.
- If you point Eclipse at the Forrest build file it will make life easy for you.
+ There really isn't much Java code in Forrest, but a Java Development
+ Environment such as Eclipse or any text editor of your choice will work
+ just fine. If you point Eclipse at the Forrest build file it will make
+ life easy for you.
</p>
<a name="N10064"></a><a name="svn"></a>
<h3 class="underlined_5">Using Subversion</h3>
<p>
- The Subversion source control system is used for all ASF projects.
- You can leverage this to ease your own development.
+ 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.
+ 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.
+ 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.
+ 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="docs_0_80/howto/../build.html">instructions</a>
- for obtaining the Apache Forrest sources via SVN.
+ To get started, see the <a href="docs_0_80/howto/../build.html">instructions</a> for
+ obtaining the Apache Forrest sources via SVN.
</p>
<p>
- Whether you use the svn command-line client or a fancy client,
- then you still need to make sure you know how to operate SVN properly.
+ Whether you use the svn command-line client or a fancy client, then you
+ still need to make sure you know how to operate SVN properly.
<a href="http://svnbook.red-bean.com/">http://svnbook.red-bean.com</a>
is a must.
</p>
@@ -524,11 +524,11 @@
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'.
+ 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 ...
@@ -542,16 +542,17 @@
<h4>Watch email notifications for svn differences</h4>
<p>
Either subscribe to the project's
- <a href="mail-lists.html#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.
+ <a href="mail-lists.html#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>
<a name="N100A3"></a><a name="svn-find-break"></a>
<h4>Updating svn backwards to find where something broke</h4>
-<p>Sometimes the addition of new features will break something. Often
- it is difficult to find where the break occurred and what caused it.
+<p>
+ Sometimes the addition of new features will break something. Often it
+ is difficult to find where the break occurred and what caused it.
Updating your svn backwards will enable this.
</p>
<p>
@@ -581,7 +582,9 @@
</pre>
<a name="N100B4"></a><a name="svn-merge"></a>
<h4>Reverting Changes using SVN Merge</h4>
-<p>Two examples of using SVN Merge.</p>
+<p>
+ Two examples of using SVN Merge.
+ </p>
<pre class="code">
$ svn merge -r 400:300 /site-author/content/xdocs/index.xml /site-author/content/xdocs/index.xml
@@ -591,12 +594,18 @@
... then commit as usual.
</pre>
-<p> More information can be found at <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common use-cases for merging</a> section of the Red Bean SVN Book.</p>
+<p>
+ More information can be found at
+ <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">Common
+ use-cases for merging</a> section of the Red Bean SVN Book.
+ </p>
<a name="N100C9"></a><a name="svn-patch"></a>
<h4>Creating patches</h4>
-<p>See
- <a href="contrib.html#patch">instructions</a> for creating and contributing patches.
- Make sure to do three things before creating the patch:</p>
+<p>
+ See <a href="contrib.html#patch">instructions</a> for creating and
+ contributing patches. Make sure to do three things before creating the
+ patch:
+ </p>
<ul>
<li>Do 'svn update' to be in sync with the repository in case someone else changed your files in SVN.</li>
@@ -606,7 +615,8 @@
<li>Do 'svn diff' to ensure that changes are what you expect.</li>
</ul>
-<p>After creating the patch, open it with a text editor and review it.
+<p>
+ After creating the patch, open it with a text editor and review it.
</p>
<a name="N100E6"></a><a name="tips-svn"></a>
<h4>Tips</h4>
@@ -621,14 +631,12 @@
<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>
@@ -637,66 +645,66 @@
</li>
</ul>
-<a name="N10109"></a><a name="edit"></a>
+<a name="N10107"></a><a name="edit"></a>
<h3 class="underlined_5">Editing content</h3>
<p>
- See the
- <a href="docs_0_80/faq.html#edit-content">FAQ</a>.
- Basically any editor can
- be used, because Forrest treats the editing of content as a separate
+ See the <a href="docs_0_80/faq.html#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>
-<a name="N10116"></a><a name="code-style"></a>
+<a name="N10114"></a><a name="code-style"></a>
<h4>Code style guidelines</h4>
<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 those few basic things are important.
- However we know that coding style is mixed, so just follow the same style
- as that which exists in the file you are editing. We can occasionally clean up later.
+ 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 those few
+ basic things are important. However we know that coding style is
+ mixed, so just follow the same style as that which exists in the file
+ you are editing. We can occasionally clean up later.
</p>
<p>
- Don't change anything that is not necessary. Remember that people need to be
- able to read the differences on the svn@forrest mailing list.
+ Don't change anything that is not necessary. Remember that people need
+ to be able to read the differences on the svn@forrest mailing list.
</p>
-<a name="N10127"></a><a name="whitespace"></a>
+<a name="N10125"></a><a name="whitespace"></a>
<h4>Whitespace</h4>
<p>
- For new files, use spaces instead of tabs (java files have four-space indentation,
- xml files and other text files have two-space indentation).
+ For new files, 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.
+ 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>
<div class="fixme">
<div class="label">Fixme (open)</div>
<div class="content">
- 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.
+ 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.
</div>
</div>
-<a name="N1013F"></a><a name="line-length"></a>
+<a name="N1013D"></a><a name="line-length"></a>
<h4>Line length</h4>
<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
+ 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).
+ line-length (normally 80-characters wide but not more than 120
+ characters).
</p>
-<a name="N10149"></a><a name="review"></a>
+<a name="N10147"></a><a name="review"></a>
<h4>Use 'forrest run' for immediate gratification</h4>
<p>
Edit documentation content and immediately view it in the browser.
@@ -705,13 +713,12 @@
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'.
+ 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>
-<a name="N10156"></a><a name="tips-edit"></a>
+<a name="N10154"></a><a name="tips-edit"></a>
<h4>Tips</h4>
<ul>
@@ -720,10 +727,11 @@
</li>
</ul>
-<a name="N10164"></a><a name="sitemap"></a>
+<a name="N10162"></a><a name="sitemap"></a>
<h3 class="underlined_5">Understanding the Cocoon sitemap</h3>
<p>
- The Cocoon sitemap is essential for Forrest developers. See some introductions ....
+ The Cocoon sitemap is essential for Forrest developers. See some
+ introductions ....
</p>
<ul>
@@ -746,186 +754,195 @@
<a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#Protocols">Cocoon protocols</a>, i.e. cocoon:/ and
cocoon:// and context:// and resource:// etc. and the
<a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#file-url">file://</a>
-
</li>
</ul>
-<a name="N1019B"></a><a name="debug"></a>
+<a name="N10198"></a><a name="debug"></a>
<h3 class="underlined_5">Debugging and profiling techniques</h3>
-<a name="N101A1"></a><a name="debug-logfiles"></a>
+<a name="N1019E"></a><a name="debug-logfiles"></a>
<h4>View logfiles</h4>
<p>
- The log files in WEB-INF/logs are indispensible when it comes
- to debugging sitemaps. While ERRORs will generally always print in the log files,
- while you're debugging something you may find it useful to also customize log output in
- the "logkit.xconf" in webapp/WEB-INF and raise the level of some loggers to WARN.
- </p>
+ The log files in WEB-INF/logs are indispensible when it comes to
+ debugging sitemaps. While ERRORs will generally always print in the
+ log files, while you're debugging something you may find it useful to
+ also customize log output in the "logkit.xconf" in webapp/WEB-INF and
+ raise the level of some loggers to WARN.
+ </p>
<p>
- This <a href="docs_0_80/faq.html#logs">FAQ</a>
- describes the location of the Cocoon logfiles and their
- configuration.
+ This <a href="docs_0_80/faq.html#logs">FAQ</a> describes the location of the
+ Cocoon logfiles and their configuration.
</p>
-<a name="N101B2"></a><a name="debug-modes"></a>
+<a name="N101AF"></a><a name="debug-modes"></a>
<h4>Cocoon Running Modes</h4>
<p>
- Cocoon startup reads additional properties from various files.
- This enables some different properties to be used for production or development.
- By default, Forrest uses Cocoon in running mode "dev".
- So it first reads from <span class="codefrag">main/webapp/WEB-INF/properties/core.properties</span>
- then from
+ Cocoon startup reads additional properties from various files. This
+ enables some different properties to be used for production or
+ development. By default, Forrest uses Cocoon in running mode "dev". So
+ it first reads from
+ <span class="codefrag">main/webapp/WEB-INF/properties/core.properties</span> then from
<span class="codefrag">main/webapp/WEB-INF/properties/dev/core.properties</span>
</p>
<p>
- To use a different mode, say "prod" for production, add to the
+ To use a different mode, say "prod" for production, add to the
forrest.jvmargs in your forrest.properties file:
<span class="codefrag">-Dorg.apache.cocoon.mode=prod</span> and provide the relevant
- properties in a matching "prod" sub-directory of
+ properties in a matching "prod" sub-directory of
<span class="codefrag">main/webapp/WEB-INF/properties</span>
</p>
-<a name="N101CB"></a><a name="debug-intermediate"></a>
+<a name="N101C8"></a><a name="debug-intermediate"></a>
<h4>View intermediate processing</h4>
<p>
Perhaps the easiest way to "debug" Forrest is to be aware of all the
processing steps between taking in the source and outputting the end
result. When you know these you can do 'forrest run' and request the
intermediate documents, such as "http://localhost:8888/body-index.xml"
- which will return the intermediate processing of the body of the document.
+ which will return the intermediate processing of the body of the
+ document.
</p>
<p>
- The techniques described below help you to be aware of the intermediate processing steps.
+ The techniques described below help you to be aware of the
+ intermediate processing steps.
</p>
-<a name="N101D8"></a><a name="debug-cocoon-profiler"></a>
+<a name="N101D5"></a><a name="debug-cocoon-profiler"></a>
<h4>Using Cocoon sitemap profiler</h4>
<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.
+ 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 <span class="codefrag">main/webapp/sitemap.xmap</span> and search
- for "profiler". Follow the instructions there to replace the
- standard "map:pipe" components with the profiling pipes.
+ Note that the profiler is not used by default. To switch it on, edit
+ <span class="codefrag">main/webapp/sitemap.xmap</span> 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.
+ 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.)
+ 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
+ NOTE: Do not forget to turn off the profiler in
<span class="codefrag">main/webapp/sitemap.xmap</span> when finished.
</p>
-<a name="N101F4"></a><a name="debug-sitemap-exec"></a>
+<a name="N101F1"></a><a name="debug-sitemap-exec"></a>
<h4>Using Cocoon sitemap execution logger</h4>
<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
+ 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>
-<a name="N101FE"></a><a name="debug-logtransformer"></a>
+<a name="N101FB"></a><a name="debug-logtransformer"></a>
<h4>Using Cocoon LogTransformer</h4>
<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) ...
+ 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>
<pre class="code">
+
<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>
-</pre>
+
+ </pre>
<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.
+ 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>
-<a name="N10215"></a><a name="debug-validation"></a>
+<a name="N10212"></a><a name="debug-validation"></a>
<h4>Using Cocoon Validation Transformers</h4>
<p>
Validating Transformers can be inserted in the sitemaps to validate
- the xml stream at that stage.
- Enables RELAX NG validation and W3C XML Schema validation using
- Jing and Xerces.
+ the xml stream at that stage. Enables RELAX NG validation and W3C XML
+ Schema validation using Jing and Xerces.
</p>
<p>
- The Validation Block is already added to Forrest and configured.
- To use it simply add entries to your sitemap like this:
+ The Validation Block is already added to Forrest and configured. To
+ use it simply add entries to your sitemap like this:
</p>
<pre class="code">
+
...
<map:transform type="validation-report"
src="{forrest:forrest.context}/resources/schema/relaxng/unstable/any.rng"/>
...
-</pre>
-<p>See
- <a href="http://marc.theaimsgroup.com/?t=112541971900003">Pier's note to cocoon-dev</a> and
- Cocoon documentation:
- <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/684.html">ValidatingTransformer</a> and
+ </pre>
+<p>
+ See <a href="http://marc.theaimsgroup.com/?t=112541971900003">Pier's
+ note to cocoon-dev</a> and Cocoon documentation:
+ <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/684.html">ValidatingTransformer</a>
+ and
<a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/691.html">ValidationReportTransformer</a>.
</p>
-<a name="N10235"></a><a name="debug-java"></a>
+<a name="N10232"></a><a name="debug-java"></a>
<h4>Java code</h4>
-<p>There are two ways to debug your java code. The first is through embedded
- logging, the second is by tracing the codes execution.</p>
<p>
- You may find <span class="codefrag">getLogger().debug()</span> useful for
- understanding the processing that goes on. You can then open the page that will
- use the selected code and use the log files mentioned above to look for
+ There are two ways to debug your java code. The first is through
+ embedded logging, the second is by tracing the codes execution.
+ </p>
+<p>
+ You may find <span class="codefrag">getLogger().debug()</span> useful for understanding
+ the processing that goes on. You can then open the page that will use
+ the selected code and use the log files mentioned above to look for
the information message.
</p>
-<p>To step through the java code you need to run forrest with Java debugging turned
- on. The <span class="codefrag">forrest.jvmargs</span>code> property in the <span class="codefrag">forrest.properties</span>
- file can be used to start forrest in debug mode on a specific port. For example:</p>
+<p>
+ To step through the java code you need to run forrest with Java
+ debugging turned on. The <span class="codefrag">forrest.jvmargs</span>code> property in
+ the <span class="codefrag">forrest.properties</span> file can be used to start forrest
+ in debug mode on a specific port. For example:
+ </p>
<pre class="code">forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</pre>
-<a name="N10252"></a><a name="debug-links"></a>
+<a name="N1024F"></a><a name="debug-links"></a>
<h4>Finding broken internal links</h4>
<p>
- Do 'forrest site' to produce the whole documentation set.
- Cocoon will report its progress and reveal any problems.
- This <a href="docs_0_80/faq.html#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.
+ Do 'forrest site' to produce the whole documentation set. Cocoon will
+ report its progress and reveal any problems. This
+ <a href="docs_0_80/faq.html#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.
+ 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.
+ configuration file or the link in your source document is not using
+ the correct name for the "site:..." value.
</p>
-<a name="N10266"></a><a name="tips-debug"></a>
+<a name="N10263"></a><a name="tips-debug"></a>
<h4>Tips</h4>
<ul>
@@ -938,68 +955,74 @@
<div class="note">
<div class="label">Note</div>
<div class="content">
- The next two sections describe the configuration of profiling tools but they are not
- integrated with the IDE. If you can figure out how to properly configure them for
- integrated operation with the IDE, please provide a documentation patch.
+ The next two sections describe the configuration of profiling tools but
+ they are not integrated with the IDE. If you can figure out how to
+ properly configure them for integrated operation with the IDE, please
+ provide a documentation patch.
</div>
</div>
-<a name="N10276"></a><a name="profile-yourkit"></a>
+<a name="N10273"></a><a name="profile-yourkit"></a>
<h4>Profiling Forrest with YourKit</h4>
<p>
- Assuming you have the YourKit software installed you simply need to do two things to
- profile a particular Forrest Project. First, you need to add *YourKit Home*\bin\win32 to
- your PATH environment variable - where *YourKit Home* is the installation directory of that
- software. Next you need to add the following to your forrest.properties file for the project.
+ Assuming you have the YourKit software installed you simply need to do
+ two things to profile a particular Forrest Project. First, you need to
+ add *YourKit Home*\bin\win32 to your PATH environment variable - where
+ *YourKit Home* is the installation directory of that software. Next
+ you need to add the following to your forrest.properties file for the
+ project.
</p>
<pre class="code">forrest.jvmargs=-agentlib:yjpagent</pre>
<p>
- You are now all set, simply type 'forrest run', then open up YourKit and select "Connect
- to locally running profiled application...". If you don't see the types of objects that you
- expected, check the current filters - YourKit seems to filter out org.apache.* namespaces by
- default.
+ You are now all set, simply type 'forrest run', then open up YourKit
+ and select "Connect to locally running profiled application...". If
+ you don't see the types of objects that you expected, check the
+ current filters - YourKit seems to filter out org.apache.* namespaces
+ by default.
</p>
-<a name="N10287"></a><a name="profile-netbeans"></a>
+<a name="N10284"></a><a name="profile-netbeans"></a>
<h4>Profiling Forrest with Netbeans</h4>
<p>
- Assuming you have the Netbeans IDE installed, you simply need to do a couple things to
- profile a particular Forrest Project. First, you need to add
- *Netbeans Home*\profiler1\lib\deployed\jdk142\windows to your path. Obviously, this needs
- to be slightly modified for a Unix machine. Now, you need to add the following line to your
- forrest.properties file for the project (replacing *NetbeansHome* with the path to your install).
+ Assuming you have the Netbeans IDE installed, you simply need to do a
+ couple things to profile a particular Forrest Project. First, you need
+ to add *Netbeans Home*\profiler1\lib\deployed\jdk142\windows to your
+ path. Obviously, this needs to be slightly modified for a Unix
+ machine. Now, you need to add the following line to your
+ forrest.properties file for the project (replacing *NetbeansHome* with
+ the path to your install).
</p>
<pre class="code">forrest.jvmargs=-agentpath:C:\*NetbeansHome*\\profiler1\\lib\\deployed\\jdk15\\windows\\
profilerinterface.dll=\C:\\*NetbeansHome*\\profiler1\\lib\\,5140</pre>
<p>
- You are now all set, simply type 'forrest run', then open up the Netbeans IDE with your Forrest
- project. Click Profile->Attach Profiler and make selections appropriate to what you are trying
- to achieve.
+ You are now all set, simply type 'forrest run', then open up the
+ Netbeans IDE with your Forrest project. Click Profile->Attach Profiler
+ and make selections appropriate to what you are trying to achieve.
</p>
-<a name="N10299"></a><a name="find"></a>
+<a name="N10296"></a><a name="find"></a>
<h3 class="underlined_5">Finding the relevant sources</h3>
<p>
You will need to be able to find which sources, sitemaps, stylesheets
are responsible for certain processing.
</p>
-<a name="N102A2"></a><a name="find-scenario-1"></a>
+<a name="N1029F"></a><a name="find-scenario-1"></a>
<h4>Scenario: How does i18n work</h4>
<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.
+ 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>
<pre class="code">
echo "sed '/\.svn/d;/\/build\//d;/\/work\//d'" > ~/bin/exclude-find-svn
chmod +x ~/bin/exclude-find-svn</pre>
<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
+ 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 ...
+ being used in the viewHelper plugin, and some DTDs. So weed them out
+ ...
</p>
<pre class="code">
cd /svn/asf/forrest-trunk
@@ -1017,13 +1040,13 @@
grep i18n *.*</pre>
<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.
+ 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>
-<a name="N102C4"></a><a name="tips-find"></a>
+<a name="N102C1"></a><a name="tips-find"></a>
<h4>Tips</h4>
<ul>
@@ -1033,40 +1056,41 @@
</ul>
</div>
-<a name="N102D4"></a><a name="Frequently Asked Questions"></a>
+<a name="N102D1"></a><a name="Frequently Asked Questions"></a>
<h2 class="underlined_10">Frequently Asked Questions</h2>
<div class="section">
-<a name="N102D8"></a><a name="1+General+issues"></a>
+<a name="N102D5"></a><a name="1+General+issues"></a>
<h3 class="underlined_5">1 General issues</h3>
-<a name="N102DC"></a><a name="1.1+FAQ+1"></a>
+<a name="N102D9"></a><a name="1.1+FAQ+1"></a>
<h4>1.1 FAQ 1</h4>
<p>
-####
+ ####
</p>
-<a name="N102E4"></a><a name="2+Other+issues"></a>
+<a name="N102E1"></a><a name="2+Other+issues"></a>
<h3 class="underlined_5">2 Other issues</h3>
-<a name="N102E8"></a><a name="2.1+FAQ+2.1"></a>
+<a name="N102E5"></a><a name="2.1+FAQ+2.1"></a>
<h4>2.1 FAQ 2.1</h4>
<p>
-###
+ ###
</p>
</div>
-<a name="N102F0"></a><a name="Tips"></a>
+<a name="N102ED"></a><a name="Tips"></a>
<h2 class="underlined_10">Tips</h2>
<div class="section">
<p>
- This is a collection of general tips that do not fit in the sections above.
+ This is a collection of general tips that do not fit in the sections
+ above.
</p>
-<a name="N102F8"></a><a name="tip-howto"></a>
+<a name="N102F5"></a><a name="tip-howto"></a>
<h3 class="underlined_5">Explanations about howto topics on the mailing lists</h3>
<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.
+ add to this howto document, then please consider just adding a tip which
+ links to the email discussion. Later someone else can summarise.
</p>
</div>
-<a name="N10302"></a><a name="References"></a>
+<a name="N102FF"></a><a name="References"></a>
<h2 class="underlined_10">References</h2>
<div class="section">
<p>
Modified: forrest/site/howto-dev.pdf
URL: http://svn.apache.org/viewvc/forrest/site/howto-dev.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.
Modified: forrest/site/howto-howto.html
URL: http://svn.apache.org/viewvc/forrest/site/howto-howto.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/howto-howto.html (original)
+++ forrest/site/howto-howto.html Mon Apr 9 21:44:00 2007
@@ -231,9 +231,10 @@
<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>How to write a How-To</h1>
-<div class="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.</div>
+<div class="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.
+ </div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
@@ -323,37 +324,40 @@
<a name="N10013"></a><a name="Intended Audience"></a>
<h2 class="underlined_10">Intended Audience</h2>
<div class="section">
-<p>Users who are ready to share their knowledge and experiences with the
- community.</p>
+<p>
+ Users who are ready to share their knowledge and experiences with the
+ community.
+ </p>
</div>
<a name="N1001B"></a><a name="Purpose"></a>
<h2 class="underlined_10">Purpose</h2>
<div class="section">
-<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>
+<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>
</div>
<a name="N10023"></a><a name="Prerequisites"></a>
<h2 class="underlined_10">Prerequisites</h2>
<div class="section">
-<p>How-To authors should have:</p>
+<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.
@@ -363,85 +367,112 @@
</ul>
<div class="note">
<div class="label">Note</div>
-<div class="content">See the <a href="docs_0_80/../dtdx/howto-v20.dtdx.html">DTD documentation</a>
- which explains the document structure.</div>
+<div class="content">
+ See the <a href="docs_0_80/../dtdx/howto-v20.dtdx.html">DTD documentation</a> which explains
+ the document structure.
+ </div>
</div>
</div>
<a name="N10044"></a><a name="Steps"></a>
<h2 class="underlined_10">Steps</h2>
<div class="section">
-<p>Here is how to proceed.</p>
+<p>
+ Here is how to proceed.
+ </p>
<a name="N1004C"></a><a name="overview"></a>
<h3 class="underlined_5">Write the Overview</h3>
-<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>
+<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>
<a name="N10056"></a><a name="audience"></a>
<h3 class="underlined_5">Describe your Intended Audience</h3>
-<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>
+<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>
<a name="N10060"></a><a name="purpose"></a>
<h3 class="underlined_5">State the Purpose</h3>
-<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>
+<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>
<a name="N1006A"></a><a name="prerequisites"></a>
<h3 class="underlined_5">List any Prerequisites</h3>
-<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>
+<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>
<a name="N10074"></a><a name="steps"></a>
<h3 class="underlined_5">Describe the Steps of your How-To</h3>
-<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>
+<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>
<a name="N1007E"></a><a name="extension"></a>
<h3 class="underlined_5">Extend the Learning</h3>
-<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>
+<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>
<a name="N10088"></a><a name="summarize"></a>
<h3 class="underlined_5">Summarize the Entire Process</h3>
-<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>
+<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>
<a name="N10092"></a><a name="tips"></a>
<h3 class="underlined_5">Additional Tips or FAQs</h3>
-<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>
+<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>
<a name="N1009C"></a><a name="references"></a>
<h3 class="underlined_5">References</h3>
-<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>
+<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>
<a name="N100A6"></a><a name="contribute"></a>
<h3 class="underlined_5">Submit via the project issue tracker</h3>
-<p>Create an attachment for your How-To document, and submit it via the
- project <a href="issues.html">issue tracker</a>.</p>
+<p>
+ Create an attachment for your How-To document, and submit it via the
+ project <a href="issues.html">issue tracker</a>.
+ </p>
<a name="N100B4"></a><a name="feedback"></a>
<h3 class="underlined_5">Get some feedback</h3>
-<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="mail-lists.html">mailing lists</a>.</p>
+<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="mail-lists.html">mailing lists</a>.
+ </p>
</div>
<a name="N100C2"></a><a name="Extension"></a>
<h2 class="underlined_10">Extension</h2>
<div class="section">
-<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>
+<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>
</div>
<a name="N100CA"></a><a name="Frequently Asked Questions"></a>
<h2 class="underlined_10">Frequently Asked Questions</h2>
@@ -450,39 +481,46 @@
<h3 class="underlined_5">1 General issues</h3>
<a name="N100D2"></a><a name="1.1+What+is+the+difference+between+a+How-To+and+a+tutorial%3F"></a>
<h4>1.1 What is the difference between a How-To and a tutorial?</h4>
-<p>The goal of a How-To is to help the reader to accomplish a specific
- task with clear and consise instructions. While tutorials may contain
- How-To-like instructions and content, they also include additional
- background and conceptual content to help teach their readers higher
- order concepts along the way. How-Tos are concerned about filling an
- immediate, short-term need. Tutorials often provide long-term
- knowledge which can be applied across a range of needs.</p>
+<p>
+ The goal of a How-To is to help the reader to accomplish a specific
+ task with clear and consise instructions. While tutorials may
+ contain How-To-like instructions and content, they also include
+ additional background and conceptual content to help teach their
+ readers higher order concepts along the way. How-Tos are concerned
+ about filling an immediate, short-term need. Tutorials often provide
+ long-term knowledge which can be applied across a range of needs.
+ </p>
<a name="N100DA"></a><a name="2+Style+issues"></a>
<h3 class="underlined_5">2 Style issues</h3>
<a name="N100DE"></a><a name="2.1+What+spelling+convention+should+I+follow%3F"></a>
<h4>2.1 What spelling convention should I follow?</h4>
-<p>Use whatever spelling convention (American, British, etc.) that is
- most intuitive to you.</p>
+<p>
+ Use whatever spelling convention (American, British, etc.) that is
+ most intuitive to you.
+ </p>
</div>
<a name="N100E6"></a><a name="Tips"></a>
<h2 class="underlined_10">Tips</h2>
<div class="section">
<a name="N100EB"></a><a name="tip-dtd"></a>
<h3 class="underlined_5">How-To dtd</h3>
-<p>The document structure is likely to change at some time. Please note that
- this HOWTO page is likely to change as well.</p>
+<p>
+ The document structure is likely to change at some time. Please note
+ that this HOWTO page is likely to change as well.
+ </p>
</div>
<a name="N100F5"></a><a name="References"></a>
<h2 class="underlined_10">References</h2>
<div class="section">
-<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>
+<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
Modified: forrest/site/howto-howto.pdf
URL: http://svn.apache.org/viewvc/forrest/site/howto-howto.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.
Modified: forrest/site/index.html
URL: http://svn.apache.org/viewvc/forrest/site/index.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/index.html (original)
+++ forrest/site/index.html Mon Apr 9 21:44:00 2007
@@ -193,13 +193,12 @@
</div>
<h1>Welcome to Apache Forrest</h1>
<div class="abstract">
- Apache Forrest is a publishing framework that transforms
- input from various sources into a unified presentation
- in one or more output formats. The modular and extensible
- plugin architecture is based on Apache Cocoon and relevant
- standards, which separates presentation from content.
- Forrest can generate static documents, or be used as a
- dynamic server, or be deployed by its automated facility.
+ Apache Forrest is a publishing framework that transforms input from
+ various sources into a unified presentation in one or more output formats.
+ The modular and extensible plugin architecture is based on Apache Cocoon
+ and relevant standards, which separates presentation from content. Forrest
+ can generate static documents, or be used as a dynamic server, or be
+ deployed by its automated facility.
</div>
<div id="motd-area">
23 June 2005 Forrest-0.7 released: Features an architecture for plugins
@@ -223,28 +222,25 @@
<p>
The Apache Forrest project uses the opensource
- <a href="license.html">Apache License 2.0</a>
- and adheres to
+ <a href="license.html">Apache License 2.0</a> and adheres to
<a href="guidelines.html#way">open development</a> ideals.
</p>
-
-
+
<div class="note">
<div class="label">Note</div>
<div class="content">
- Please realise that Forrest is still pre-1.0 release version.
- It is certainly usable for those who are prepared to move with it.
- See more notes about <a href="#status">status</a> below.
- </div>
+ Please realise that Forrest is still pre-1.0 release version. It is
+ certainly usable for those who are prepared to move with it. See more
+ notes about <a href="#status">status</a> below.
+ </div>
</div>
-
<a name="N10022"></a><a name="Explanation+and+features"></a>
<h2 class="underlined_10">Explanation and features</h2>
<div class="section">
<p>
- Forrest is designed with the new user in mind. Much effort has gone
- into making the process of generating a new site <strong>easy</strong> and
+ Forrest is designed with the new user in mind. Much effort has gone into
+ making the process of generating a new site <strong>easy</strong> and
<strong>simple</strong>:
</p>
<ul>
@@ -261,7 +257,6 @@
<strong>Step 3</strong>: Do <span class="codefrag">'forrest run'</span> then use
the web browser to immediately review
changes at <span class="codefrag">http://localhost:8888/</span>
-
</li>
<li>
@@ -282,12 +277,12 @@
<div class="content">
The first time you run Forrest it may attempt to retrieve some plugins
from the Internet (it depends on which distribution of Forrest you have
- installed). In some cases this will happen whenever a new plugin is specified,
- in other cases, for example when you have installed all plugins locally
- or have checked out the full source tree, the plugins will be retrieved
- from your local installation. In all cases once a plugin has been installed
- locally there is no need for Forrest to access the Internet.
- For more information see the
+ installed). In some cases this will happen whenever a new plugin is
+ specified, in other cases, for example when you have installed all
+ plugins locally or have checked out the full source tree, the plugins
+ will be retrieved from your local installation. In all cases once a
+ plugin has been installed locally there is no need for Forrest to access
+ the Internet. For more information see the
<a href="pluginDocs/index.html">plugins documentation</a>.
</div>
</div>
@@ -295,23 +290,22 @@
Forrest's focus on low "startup cost" makes it ideal for rapid
development of small sites, where time and budget constraints do not
allow time-wasting HTML experiments. Of course, that same methodology
- can scale up to large projects.
- Your development team does not need Java experience, or even XML skills,
- to use Forrest. The framework lets you concentrate on content and design.
- </p>
-<p>
- By <strong>separating content from
- presentation</strong>, providing <strong>content templates</strong>
- and <strong>pre-written skins</strong>, Forrest is unequalled at enabling
- content producers to get their message out fast. This separation of
- concerns makes Forrest excellent
- to publish <strong>project documentation</strong> (notably software projects),
- <strong>intranets</strong>, and <strong>home pages</strong>,
- and anything else you can think of.
+ can scale up to large projects. Your development team does not need Java
+ experience, or even XML skills, to use Forrest. The framework lets you
+ concentrate on content and design.
+ </p>
+<p>
+ By <strong>separating content from presentation</strong>, providing
+ <strong>content templates</strong> and <strong>pre-written
+ skins</strong>, Forrest is unequalled at enabling content producers to
+ get their message out fast. This separation of concerns makes Forrest
+ excellent to publish <strong>project documentation</strong> (notably
+ software projects), <strong>intranets</strong>, and <strong>home
+ pages</strong>, and anything else you can think of.
</p>
<p>
- Forrest is far from a quick and dirty solution however. Forrest is
- built on the world's leading XML application framework,
+ Forrest is far from a quick and dirty solution however. Forrest is built
+ on the world's leading XML application framework,
<a href="http://cocoon.apache.org/2.1/">Apache Cocoon</a>, which provides advanced
users with extremely powerful publishing capabilities.
</p>
@@ -319,7 +313,8 @@
<li>Multiple task-specific source XML formats can be used
(<a href="howto-howto.html">How-To</a>,
- <a href="docs_0_70/faq.html"><acronym title="Frequently Asked Questions">FAQ</acronym></a>,
+ <a href="docs_0_70/faq.html">
+ <acronym title="Frequently Asked Questions">FAQ</acronym></a>,
<a href="docs_0_70/changes.html">changelogs</a> and
<a href="docs_0_70/todo.html">todo lists</a> supported natively).
Source formats include: Apache xdocs xml format, plain html
@@ -356,65 +351,63 @@
</ul>
<p>
- Unique amongst comparable documentation tools, Forrest generates
- sites that can run both <strong>interactively</strong> as a dynamic
- web application, or as statically rendered pages.
- </p>
-<p>
- This provides a path for site growth: start off small and static, and
- if dynamic features (user login, forms processing, runtime data, site
- search etc) are one day needed, these can be accommodated by switching
- to webapp mode.
- </p>
-<p>
- Running as a webapp has a major advantage during development:
- content can be written, and
- then the rendered output viewed almost instantly in a web browser.
- This <a href="docs_0_70/your-project.html#webapp">webapp technique</a>
- enables Forrest's edit/review cycle to be faster than command-line
- transformation tools.
- </p>
+ Unique amongst comparable documentation tools, Forrest generates sites
+ that can run both <strong>interactively</strong> as a dynamic web
+ application, or as statically rendered pages.
+ </p>
+<p>
+ This provides a path for site growth: start off small and static, and if
+ dynamic features (user login, forms processing, runtime data, site
+ search etc) are one day needed, these can be accommodated by switching
+ to webapp mode.
+ </p>
+<p>
+ Running as a webapp has a major advantage during development: content
+ can be written, and then the rendered output viewed almost instantly in
+ a web browser. This <a href="docs_0_70/your-project.html#webapp">webapp
+ technique</a> enables Forrest's edit/review cycle to be faster than
+ command-line transformation tools.
+ </p>
</div>
-
<a name="N100D5"></a><a name="status"></a>
<h2 class="underlined_10">History and project status</h2>
<div class="section">
-<p>Apache Forrest was started in January 2002, with the major use-case being to
- create a consistent and efficient
- <a href="http://xml.apache.org/">xml.apache.org</a> group of project
- websites with a
- uniform, lightweight, easy-to-navigate layout and structure. In
- addition, Forrest was to be a Sourceforge-like project management
- tool, complementing <a href="http://gump.apache.org/">Apache Gump</a> (hence
- the name 'Forrest').
- </p>
-<p>
- The focus shifted for Apache Forrest to primarily be a generic documentation
- tool capable of meeting many needs. Certain relevant project management
- facilities are being added.
- </p>
-<p>Apache Forrest is currently progressing rapidly through a series of 0.x
- releases. It is certainly usable now (despite not yet being version 1.x).
- See the growing list of
- <a href="live-sites.html">example sites</a> including
- many Apache sites.
+<p>
+ Apache Forrest was started in January 2002, with the major use-case
+ being to create a consistent and efficient
+ <a href="http://xml.apache.org/">xml.apache.org</a> group of
+ project websites with a uniform, lightweight, easy-to-navigate layout
+ and structure. In addition, Forrest was to be a Sourceforge-like project
+ management tool, complementing <a href="http://gump.apache.org/">Apache Gump</a>
+ (hence the name 'Forrest').
+ </p>
+<p>
+ The focus shifted for Apache Forrest to primarily be a generic
+ documentation tool capable of meeting many needs. Certain relevant
+ project management facilities are being added.
+ </p>
+<p>
+ Apache Forrest is currently progressing rapidly through a series of 0.x
+ releases. It is certainly usable now (despite not yet being version
+ 1.x). See the growing list of <a href="live-sites.html">example
+ sites</a> including many Apache sites.
</p>
<p>
In general, prior to 1.0, ensuring quality of design will be considered
- more important than retaining backwards-compatibility. Users
+ more important than retaining backwards-compatibility. Users
(particularly those with custom sitemaps and skins) should be aware that
this is evolving software, and read the release notes carefully before
- upgrading. That said, we appreciate the commitment in time that
- adopters make, and will not make capricious or undocumented
+ upgrading. That said, we appreciate the commitment in time that adopters
+ make, and will not make capricious or undocumented
backwards-incompatible changes.
</p>
<p>
Documentation on the Apache Forrest website exists for various versions
- including the latest release, the current development, and past releases.
- All versions of Forrest include their own copy of the documentation.
- There is also documentation for each plugin and the forrest seed site
- contains further examples and documentation (see
+ including the latest release, the current development, and past
+ releases. All versions of Forrest include their own copy of the
+ documentation. There is also documentation for each plugin and the
+ forrest seed site contains further examples and documentation (see
<a href="docs_0_80/faq.html#docs">FAQ</a>).
</p>
</div>
@@ -422,12 +415,13 @@
<a name="N100FB"></a><a name="news"></a>
<h2 class="underlined_10">News and events</h2>
<div class="section">
-<p>See the <a href="events.html">events</a> list for more detail.
+<p>
+ See the <a href="events.html">events</a> list for more detail.
</p>
<ul>
<li>
- <!--
+<!--
<link href="http://apachecon.com/">
<img src="http://apache.org/images/ac2005eu_135x50.gif"
alt="ApacheCon Europe 2005" width="135" height="50"/>
@@ -440,7 +434,6 @@
See our <link href="site:events">events</link> list for the schedule
of Forrest meetings at ApacheCon.
-->
-
</li>
<li>Apache Forrest 0.7 was released on 2005-06-23.
@@ -451,17 +444,17 @@
</ul>
</div>
-<a name="N10116"></a><a name="help"></a>
+<a name="N10114"></a><a name="help"></a>
<h2 class="underlined_10">Help Wanted!</h2>
<div class="section">
<p>
- Apache Forrest is fairly new, and is in need of developers.
- If you know (or want to learn) any of XML, Ant, HTML, XSLT, or CSS,
- then you are qualified to help.
+ Apache Forrest is fairly new, and is in need of developers. If you know
+ (or want to learn) any of XML, Ant, HTML, XSLT, or CSS, then you are
+ qualified to help.
</p>
<p>
- As with all Apache projects, Forrest is a meritocracy; the more you
- put in, the more you get to define the project's future. See the
+ As with all Apache projects, Forrest is a meritocracy; the more you put
+ in, the more you get to define the project's future. See the
<a href="contrib.html">"contributing"</a> page for more
information.
</p>
Modified: forrest/site/issues.html
URL: http://svn.apache.org/viewvc/forrest/site/issues.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/issues.html (original)
+++ forrest/site/issues.html Mon Apr 9 21:44:00 2007
@@ -255,214 +255,205 @@
</li>
</ul>
</div>
-
-
+
<a name="N1000D"></a><a name="intro"></a>
<h2 class="underlined_10">Introduction</h2>
<div class="section">
<p>
- The Apache Forrest uses an issue tracker call Jira. All of the project
- contributions should go there (not to the mailing list). This enables us to
- keep track of contributions and to classify and manage the issues.
- </p>
+ The Apache Forrest uses an issue tracker call Jira. All of the project
+ contributions should go there (not to the mailing list). This enables us
+ to keep track of contributions and to classify and manage the issues.
+ </p>
<p>
-
+
<a href="http://issues.apache.org/jira/browse/FOR">http://issues.apache.org/jira/browse/FOR</a>
- is the main entry point which provides access to enter, view, search, and
- add additional comments to issues. There are some additional search
- <a href="#filters">filters</a> provided below.
- </p>
-<p>
- You need to set up an account there before you can create new issues or
- add comments to existing issues.
- Anyone can register as a user and report issues.
- See <a href="#guide">guidelines</a> below.
- </p>
-<p>
- Note that the issue tracker is not a discussion or user help forum.
- Please discuss issues about using Forrest on the user or dev mailing list.
- </p>
+ is the main entry point which provides access to enter, view, search,
+ and add additional comments to issues. There are some additional search
+ <a href="#filters">filters</a> provided below.
+ </p>
+<p>
+ You need to set up an account there before you can create new issues or
+ add comments to existing issues. Anyone can register as a user and
+ report issues. See <a href="#guide">guidelines</a> below.
+ </p>
+<p>
+ Note that the issue tracker is not a discussion or user help forum.
+ Please discuss issues about using Forrest on the user or dev mailing
+ list.
+ </p>
</div>
-
-
+
<a name="N1002C"></a><a name="guide"></a>
<h2 class="underlined_10">Guidelines and hints for reporting issues</h2>
<div class="section">
<ul>
-
+
<li>Ensure that an issue does not already exist.</li>
-
+
<li>Use Jira's powerful "Find Issues" ability. Set the Project and
Status fields. See the Help about boolean queries in the Query field.
</li>
-
+
<li>Follow the prompts below each entry field.</li>
-
+
<li>If you don't know the answer to a particular question, then
leave the field blank.</li>
-
+
<li>Add a concise initial Description, then add more Comments later to
further describe the issue.</li>
-
+
<li>Other people will follow up and enhance your description and
classifications.</li>
-
+
<li>If details about your computing environment are relevant
(e.g. Java version or operating system) then add them to a Comment.</li>
-
+
<li>If you are going to also add a patch, then select "Patch available".
(Reporters of issues can add this later via "Edit issue".)
Follow the instructions about "Grant license" and ensure that you are
able to do so.</li>
-
+
</ul>
<a name="N1004D"></a><a name="priority"></a>
<h3 class="underlined_5">Special fields: Priority (a.k.a. Severity)</h3>
<p>
- The Priority is the severity according to the issue reporter. This will
- be a guideline to the development team to identify the most urgent
- issues. It is not a guarantee that a Critical issue will be resolved
- before a Major issue.
- </p>
+ The Priority is the severity according to the issue reporter. This
+ will be a guideline to the development team to identify the most
+ urgent issues. It is not a guarantee that a Critical issue will be
+ resolved before a Major issue.
+ </p>
<p>
- Follow the Jira help icon to see the definition of the options.
- </p>
+ Follow the Jira help icon to see the definition of the options.
+ </p>
<a name="N1005A"></a><a name="urgency"></a>
<h3 class="underlined_5">Special fields: Urgency</h3>
<p>
- The project team will classify this according to their urgency. The aim is
- to be able to see at a glance which issues should be attended to, so that
- developers can operate efficiently and so that the product can be released
- as soon as possible. Some issues hinder the project, so need to be identified.
- </p>
+ The project team will classify this according to their urgency. The
+ aim is to be able to see at a glance which issues should be attended
+ to, so that developers can operate efficiently and so that the product
+ can be released as soon as possible. Some issues hinder the project,
+ so need to be identified.
+ </p>
<div class="fixme">
<div class="label">Fixme (open)</div>
<div class="content">
-Not sure about the project's use of the "Urgency" field.
-See issue <a href="http://issues.apache.org/jira/browse/FOR-853">FOR-853</a>
-
+ Not sure about the project's use of the "Urgency" field. See issue
+ <a href="http://issues.apache.org/jira/browse/FOR-853">FOR-853</a>
+
</div>
</div>
<p>
- We use the following definition of the options.
- </p>
+ We use the following definition of the options.
+ </p>
<ul>
-
+
<li>
None: The default. Not yet classified.
</li>
-
+
<li>
Blocker: Prevents other developers from working; or critical issue with functionality;
or holds up the implementation of other functionality.
Cannot release until it is fixed. Will be fixed ASAP.
</li>
-
+
<li>
Urgent: Is a key new feature; or affects many users. Will be fixed before the next
release.
</li>
-
+
<li>
Normal: If this issue scratches the itch of any particular developer, then
they should help to solve it and provide a patch.
</li>
-
+
<li>
Low: If this issue bothers you, then fix it because it is not a high priority
for the project.
</li>
-
+
</ul>
<a name="N10081"></a><a name="permissions"></a>
<h3 class="underlined_5">Permissions</h3>
<ul>
-
+
<li>
Anyone: Browse, Find, View.
</li>
-
+
<li>
jira-users: People who have registered as a user of the ASF Jira.
Create, Edit, Comment, Attach, Vote, Watch.
The reporter can also Close.
</li>
-
+
<li>
forrest-developers: People who are Forrest committers.
Resolve, Close, Delete issues, Delete coments, Link, Assign, Schedule Fix Version, Administer Project.
</li>
-
+
<li>
Some committers are global adminstrators: Edit user details, Add users to groups, Configure.
</li>
-
+
</ul>
</div>
-
-
+
<a name="N10098"></a><a name="filters"></a>
<h2 class="underlined_10">Some search filters</h2>
<div class="section">
<p>
- Various general searches are available from the
- <a href="http://issues.apache.org/jira/browse/FOR">front page</a>,
- e.g. "open issues classified by component", or "Added recently".
- The following are some special filters.
- </p>
+ Various general searches are available from the
+ <a href="http://issues.apache.org/jira/browse/FOR">front page</a>, e.g.
+ "open issues classified by component", or "Added recently". The
+ following are some special filters.
+ </p>
<ul>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310472">FOR-open-with-patch</a>
- Committers need to visit this regularly and deal with the patches.
</li>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310820">FOR-roadmap-dev</a>
- Open issues that are scheduled to be investigated.
</li>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310476">FOR-unresolved-with-attachment</a>
- Issues that have demonstrations of problems, but no solution or patch.
Of course it will include FOR-open-with-patch.
(Note that this filter searches for the string "attach" so will not find all.)
</li>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310043">FOR-unscheduled</a>
- Issues that have not yet been scheduled to be fixed for a certain version.
</li>
-
+
</ul>
<div class="fixme">
<div class="label">Fixme (open)</div>
<div class="content">
-Not sure about the project's use of the "Urgency" field.
-</div>
+ Not sure about the project's use of the "Urgency" field.
+ </div>
</div>
<ul>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310473">FOR-urgency-blocker</a>
- Issues that the project considers to be Blockers.
</li>
-
-<li>
+<li>
<a href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12310475">FOR-urgency-urgent</a>
- Issues that the project considers to be Urgent.
</li>
-
+
</ul>
</div>
-
-
+
</div>
<!--+
|end content
Modified: forrest/site/license.html
URL: http://svn.apache.org/viewvc/forrest/site/license.html?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/license.html (original)
+++ forrest/site/license.html Mon Apr 9 21:44:00 2007
@@ -192,18 +192,18 @@
<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>Apache License</h1>
-
+
<p>
- The Forrest distribution is licensed according to the liberal
- Apache License. See the files in the top-level of the Forrest
- distribution called LICENSE.txt (copy shown below) and NOTICE.txt
- and see licenses for accompanying products in the "lib" directories
- of the Forrest core and plugins.
- See full explanation and FAQs regarding the
- <a href="http://www.apache.org/licenses/">Apache License</a>.
- </p>
-
+ The Forrest distribution is licensed according to the liberal Apache
+ License. See the files in the top-level of the Forrest distribution called
+ LICENSE.txt (copy shown below) and NOTICE.txt and see licenses for
+ accompanying products in the "lib" directories of the Forrest core and
+ plugins. See full explanation and FAQs regarding the
+ <a href="http://www.apache.org/licenses/">Apache License</a>.
+ </p>
+
<pre class="code">
+
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
@@ -405,8 +405,9 @@
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.
-</pre>
+ </pre>
+
</div>
<!--+
|end content
Modified: forrest/site/license.pdf
URL: http://svn.apache.org/viewvc/forrest/site/license.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.