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/18 10:36:26 UTC
svn commit: r529915 [14/20] - in /forrest/site: ./ docs_0_70/
docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/
docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/
plan/ pluginDocs/ pluginDocs/plugins_0_70/ ...
Modified: forrest/site/docs_0_70/validation.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/validation.html?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
--- forrest/site/docs_0_70/validation.html (original)
+++ forrest/site/docs_0_70/validation.html Wed Apr 18 01:36:14 2007
@@ -3,7 +3,7 @@
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
-<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-version" content="0.9-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>XML Validation (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
@@ -87,7 +87,7 @@
|start Subtabs
+-->
<div id="level2tabs">
-<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
+<a class="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="unselected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="selected" href="../docs_0_70/index.html">0.70 (past)</a>
</div>
<!--+
|end Endtabs
@@ -100,7 +100,7 @@
|breadtrail
+-->
<div class="breadtrail">
-
+
</div>
<!--+
@@ -283,7 +283,7 @@
</div>
<div id="credit">
<hr>
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
@@ -313,7 +313,7 @@
<h1>XML Validation</h1>
<h3>DTDs, catalogs and whatnot</h3>
<div id="motd-area">
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -347,22 +347,22 @@
<h2 class="underlined_10">XML validation</h2>
<div class="section">
<p>
- By default, Forrest will validate your XML before generating
- HTML or a webapp from it, and fail if any XML files are not valid.
- Validation can be performed manually by doing
- '<span class="codefrag">forrest validate</span>' in the project root directory.
+ By default, Forrest will validate your XML before generating HTML or a
+ webapp from it, and fail if any XML files are not valid. Validation can
+ be performed manually by doing '<span class="codefrag">forrest validate</span>' in the
+ project root directory.
</p>
<p>
For an XML file to be valid, it <em>must</em> have a document type
- declaration at the top, indicating its content type. Hence by
- default, any Forrest-processed XML file that lacks a DOCTYPE
- declaration will cause the build to break.
+ declaration at the top, indicating its content type. Hence by default,
+ any Forrest-processed XML file that lacks a DOCTYPE declaration will
+ cause the build to break.
</p>
<p>
Despite the strict default behavior, Forrest is quite flexible about
- validation. Validation can be switched off for certain sections of a
- project. In validated sections, it is possible for projects to specify
- exactly what files they want (and don't want) validated. Forrest
+ validation. Validation can be switched off for certain sections of a
+ project. In validated sections, it is possible for projects to specify
+ exactly what files they want (and don't want) validated. Forrest
validation is controlled through a set of properties in
<span class="codefrag">forrest.properties</span>:
</p>
@@ -400,13 +400,12 @@
<div class="label">Note</div>
<div class="content">
The <span class="codefrag">failonerror</span> properties only work for files validated
- with Ant's <xmlvalidate> and not (yet) for those validated
- with <jing>, where <span class="codefrag">failonerror</span> defaults to
+ with Ant's <xmlvalidate> and not (yet) for those validated with
+ <jing>, where <span class="codefrag">failonerror</span> defaults to
<span class="codefrag">true</span>.
</div>
</div>
</div>
-
<a name="N10049"></a><a name="Validating+new+XML+types"></a>
<h2 class="underlined_10">Validating new XML types</h2>
@@ -414,24 +413,24 @@
<p>
Forrest provides an <a href="http://www.oasis-open.org/committees/entity/spec.html">OASIS Catalog</a>
[see <a href="http://xml.apache.org/commons/components/resolver/resolver-article.html">tutorial</a>]
- <span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span>
- as a means of associating public identifiers
- (e.g. <span class="codefrag">-//APACHE//DTD Documentation V1.1//EN</span> above) with DTDs.
- If you <a href="../docs_0_70/your-project.html#adding_new_content_type">add a new content type</a>, you
- should add the DTD to <span class="codefrag">${project.schema-dir}/dtd/</span> and add
- an entry to the <span class="codefrag">${project.schema-dir}/catalog.xcat</span> file. This
- section describes the details of this process.
+ <span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span> as a
+ means of associating public identifiers (e.g. <span class="codefrag">-//APACHE//DTD
+ Documentation V1.1//EN</span> above) with DTDs. If you
+ <a href="../docs_0_70/your-project.html#adding_new_content_type">add a new content type</a>,
+ you should add the DTD to <span class="codefrag">${project.schema-dir}/dtd/</span> and
+ add an entry to the <span class="codefrag">${project.schema-dir}/catalog.xcat</span>
+ file. This section describes the details of this process.
</p>
<a name="N1006A"></a><a name="Creating+or+extending+a+DTD"></a>
<h3 class="underlined_5">Creating or extending a DTD</h3>
<p>
- The main Forrest DTDs are designed to be modular and extensible, so
- it is fairly easy to create a new document type that is a superset
- of one from Forrest. This is what we'll demonstrate here, using our
- earlier <a href="../docs_0_70/your-project.html#adding_new_content_type">download format</a>
- as an example. Our download format adds a group of new elements to
- the standard 'documentv13' format. Our new elements are described
- by the following DTD:
+ The main Forrest DTDs are designed to be modular and extensible, so it
+ is fairly easy to create a new document type that is a superset of one
+ from Forrest. This is what we'll demonstrate here, using our earlier
+ <a href="../docs_0_70/your-project.html#adding_new_content_type">download format</a> as an
+ example. Our download format adds a group of new elements to the
+ standard 'documentv13' format. Our new elements are described by the
+ following DTD:
</p>
<pre class="code">
<!ELEMENT release (downloads)>
@@ -453,10 +452,10 @@
The
<span class="codefrag">forrest/main/webapp/resources/schema/dtd/document-v13.dtd</span>
file provides a full description and basic example of how to pull in
- modules. In our example, our DTD reuses modules
+ modules. In our example, our DTD reuses modules
<span class="codefrag">common-charents-v10.mod</span> and
- <span class="codefrag">document-v13.mod</span>. Here is the full DTD, with
- explanation to follow.
+ <span class="codefrag">document-v13.mod</span>. Here is the full DTD, with explanation
+ to follow.
</p>
<pre class="code">
<!-- ===================================================================
@@ -529,171 +528,168 @@
<!-- End of DTD -->
<!-- =============================================================== -->
</pre>
-<p>This custom DTD should be placed in your project resources
- directory at <span class="codefrag">src/documentation/resources/schema/dtd/</span>
+<p>
+ This custom DTD should be placed in your project resources directory
+ at <span class="codefrag">src/documentation/resources/schema/dtd/</span>
+
</p>
<p>
- The <!ENTITY % ... > blocks are so-called
+ The <!ENTITY % ... > blocks are so-called
<a href="http://www.xml.com/axml/target.html#dt-PERef">parameter
- entities</a>. They are like macros, whose content will be
- inserted when a parameter-entity reference, like
- <span class="codefrag">%common-charents;</span> or <span class="codefrag">%document;</span> is
- inserted.
+ entities</a>. They are like macros, whose content will be inserted
+ when a parameter-entity reference, like <span class="codefrag">%common-charents;</span>
+ or <span class="codefrag">%document;</span> is inserted.
</p>
<p>
In our DTD, we first pull in the 'common-charents' entity, which
- defines character symbol sets. We then define the 'document'
- entity. However, before the <span class="codefrag">%document;</span> PE reference, we
- first override the 'local.section' entity. This is a hook into
- document-v13.mod. By setting its value to '|release', we declare
- that our <release> element is to be allowed wherever "local
- sections" are used. There are five or so such hooks for different
- areas of the document; see document-v13.dtd for more details. We then
- import the %document; contents, and declare the rest of our DTD
- elements.
+ defines character symbol sets. We then define the 'document' entity.
+ However, before the <span class="codefrag">%document;</span> PE reference, we first
+ override the 'local.section' entity. This is a hook into
+ document-v13.mod. By setting its value to '|release', we declare that
+ our <release> element is to be allowed wherever "local sections"
+ are used. There are five or so such hooks for different areas of the
+ document; see document-v13.dtd for more details. We then import the
+ %document; contents, and declare the rest of our DTD elements.
</p>
<p>
- We now have a DTD for the 'download' document type.
+ We now have a DTD for the 'download' document type.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
-
+
<a href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
- 5: Customizing DocBook</a> of Norman Walsh's "DocBook: The
+ 5: Customizing DocBook</a> of Norman Walsh's "DocBook: The
Definitive Guide" gives a complete overview of the process of
customizing a DTD.
</div>
</div>
-<a name="N100B1"></a><a name="catalog"></a>
+<a name="N100B2"></a><a name="catalog"></a>
<h3 class="underlined_5">Associating DTDs with document types</h3>
<p>
- Recall that our DOCTYPE declaration for our download document type
- is:
+ Recall that our DOCTYPE declaration for our download document type is:
</p>
<pre class="code"><!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"download-v10.dtd">
</pre>
<p>
- We only care about the quoted section after <span class="codefrag">PUBLIC</span>, called
- the "public identifier", which globally identifies our document type.
- We cannot rely on the subsequent "system identifier" part
+ We only care about the quoted section after <span class="codefrag">PUBLIC</span>,
+ called the "public identifier", which globally identifies our document
+ type. We cannot rely on the subsequent "system identifier" part
("download-v10.dtd"), because as a relative reference it is liable to
- break. The solution Forrest uses is to ignore the system id, and rely
+ break. The solution Forrest uses is to ignore the system id, and rely
on a mapping from the public ID to a stable DTD location, via a
- Catalog file.</p>
+ Catalog file.
+ </p>
<div class="note">
<div class="label">Note</div>
<div class="content">
See <a href="http://xml.apache.org/commons/components/resolver/resolver-article.html">this article</a> for a good
introduction to catalogs and the Cocoon documentation
- <a href="http://cocoon.apache.org/2.1/userdocs/concepts/catalog.html">Entity resolution with catalogs</a>.
+ <a href="http://cocoon.apache.org/2.1/userdocs/concepts/catalog.html">Entity resolution with
+ catalogs</a>.
</div>
</div>
<p>
Forrest provides a standard catalog file at
- <span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span>
- for the document
- types that Forrest provides. Projects can augment this with their
- own catalog file located in
+ <span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span> for the
+ document types that Forrest provides. Projects can augment this with
+ their own catalog file located in
<span class="codefrag">${project.schema-dir}/catalog.xcat</span> to use it you must
- specify either the path (full or relative) to your
- <span class="codefrag">catalog.xcat</span> in the <span class="codefrag">CatalogManager.properties</span>
- file. If you provide a relative path you must set the property
- <span class="codefrag">relative-catalogs</span> to "yes".
- </p>
-<p>
- When Cocoon starts, it reads the <span class="codefrag">CatalogManager.properties</span> file from your
- <span class="codefrag">project.classes-dir</span>. This is usually src/documentation/classes/
- but you can change this in <span class="codefrag">forrest.properties</span>. When you seed
- a new site using <span class="codefrag">forrest seed-site</span> a sample catalog file
- is placed in the site structure, you can use this as a template for your
- own files.
+ specify either the path (full or relative) to your
+ <span class="codefrag">catalog.xcat</span> in the
+ <span class="codefrag">CatalogManager.properties</span> file. If you provide a relative
+ path you must set the property <span class="codefrag">relative-catalogs</span> to
+ "yes".
+ </p>
+<p>
+ When Cocoon starts, it reads the
+ <span class="codefrag">CatalogManager.properties</span> file from your
+ <span class="codefrag">project.classes-dir</span>. This is usually
+ src/documentation/classes/ but you can change this in
+ <span class="codefrag">forrest.properties</span>. When you seed a new site using
+ <span class="codefrag">forrest seed-site</span> a sample catalog file is placed in the
+ site structure, you can use this as a template for your own files.
</p>
<p>
Forrest uses the XML Catalog syntax by default, although the older
- plain-text
- format can also be used. Here is what the XML Catalog format looks
- like:
+ plain-text format can also be used. Here is what the XML Catalog
+ format looks like:
</p>
-<pre class="code"><?xml version="1.0"?>
+<pre class="code">
+<?xml version="1.0"?>
<!-- OASIS XML Catalog for Forrest -->
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<public publicId="-//Acme//DTD Download Documentation V1.0//EN"
uri="dtd/download-v10.dtd"/>
-</catalog></pre>
+</catalog>
+ </pre>
<p>
The format is described in <a href="http://www.oasis-open.org/committees/entity/spec.html">the
- spec</a>, and is fairly simple and very powerful.
- The "<span class="codefrag">public</span>" elements map
- a public identifier to a DTD (relative to the catalog file).
+ spec</a>, and is fairly simple and very powerful. The
+ "<span class="codefrag">public</span>" elements map a public identifier to a DTD
+ (relative to the catalog file).
</p>
<p>
- We now have a custom DTD and a catalog mapping which lets both
- Forrest and Cocoon
- locate the DTD. Now if we were to run <span class="codefrag">'forrest validate'</span>
- our download file would validate along with all the others. If
- something goes wrong, try running <span class="codefrag">'forrest -v validate'</span> to
- see the error in more detail. Remember to raise the "verbosity"
- level in <span class="codefrag">cocoon.xconf</span> if you suspect problems
- with your catalog.
+ We now have a custom DTD and a catalog mapping which lets both Forrest
+ and Cocoon locate the DTD. Now if we were to run <span class="codefrag">'forrest
+ validate'</span> our download file would validate along with all the
+ others. If something goes wrong, try running <span class="codefrag">'forrest -v
+ validate'</span> to see the error in more detail. Remember to raise
+ the "verbosity" level in <span class="codefrag">cocoon.xconf</span> if you suspect
+ problems with your catalog.
</p>
</div>
-
-<a name="N1010F"></a><a name="entities"></a>
+<a name="N10110"></a><a name="entities"></a>
<h2 class="underlined_10">Referring to entities</h2>
<div class="section">
<p>
Look at the source of this document
(<span class="codefrag">xdocs/docs/validation.xml</span>) and see how the entity set
- <span class="codefrag">"Numeric and Special Graphic"</span> is declared in the
- document type declaration.
+ <span class="codefrag">"Numeric and Special Graphic"</span> is declared in the document
+ type declaration.
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
-<td colspan="1" rowspan="1">ISOnum.pen</td>
- <td colspan="1" rowspan="1">&half;</td>
- <td colspan="1" rowspan="1">½</td>
+<td colspan="1" rowspan="1">ISOnum.pen</td>
+ <td colspan="1" rowspan="1">&half;</td>
+ <td colspan="1" rowspan="1">½</td>
</tr>
</table>
</div>
-
-<a name="N10134"></a><a name="Validating+in+an+XML+editor"></a>
+<a name="N10135"></a><a name="Validating+in+an+XML+editor"></a>
<h2 class="underlined_10">Validating in an XML editor</h2>
<div class="section">
<p>
- If you have an XML editor that understands SGML or XML catalogs, let
- it know where the Forrest catalog file is, and you will be able to
- validate any Forrest XML file, regardless of location, as you edit
- your files. See the
- <a href="../docs_0_70/catalog.html">configuration notes</a> your favourite
- editor.
+ If you have an XML editor that understands SGML or XML catalogs, let it
+ know where the Forrest catalog file is, and you will be able to validate
+ any Forrest XML file, regardless of location, as you edit your files.
+ See the <a href="../docs_0_70/catalog.html">configuration notes</a> your
+ favourite editor.
</p>
</div>
-
-<a name="N10142"></a><a name="relaxng"></a>
+<a name="N10143"></a><a name="relaxng"></a>
<h2 class="underlined_10">Validation using RELAX NG</h2>
<div class="section">
<p>
Other validation is also conducted during build-time using RELAX NG.
- This validates all of the important configuration files, both in
- Forrest itself and in your project. At the moment it processes all
- skinconf.xml files, all sitemap.xmap files, and all XSLT stylesheets.
+ This validates all of the important configuration files, both in Forrest
+ itself and in your project. At the moment it processes all skinconf.xml
+ files, all sitemap.xmap files, and all XSLT stylesheets.
</p>
<p>
The RNG grammars to do this are located in the
- <span class="codefrag">main/webapp/resources/schema/relaxng</span> directory.
- If you want to
- know more about this, and perhaps extend it for your own use, then
- see <span class="codefrag">main/webapp/resources/schema/relaxng/README.txt</span>
- and the Ant targets in the various build.xml files.
+ <span class="codefrag">main/webapp/resources/schema/relaxng</span> directory. If you want
+ to know more about this, and perhaps extend it for your own use, then
+ see <span class="codefrag">main/webapp/resources/schema/relaxng/README.txt</span> and the
+ Ant targets in the various build.xml files.
</p>
</div>
Modified: forrest/site/docs_0_70/validation.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/validation.pdf?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
Binary files - no diff available.
Modified: forrest/site/docs_0_70/views.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/views.html?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
--- forrest/site/docs_0_70/views.html (original)
+++ forrest/site/docs_0_70/views.html Wed Apr 18 01:36:14 2007
@@ -3,7 +3,7 @@
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
-<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-version" content="0.9-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>forrest:views concept (Draft -feature planed for 0.8) (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
@@ -87,7 +87,7 @@
|start Subtabs
+-->
<div id="level2tabs">
-<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
+<a class="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="unselected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="selected" href="../docs_0_70/index.html">0.70 (past)</a>
</div>
<!--+
|end Endtabs
@@ -100,7 +100,7 @@
|breadtrail
+-->
<div class="breadtrail">
-
+
</div>
<!--+
@@ -283,7 +283,7 @@
</div>
<div id="credit">
<hr>
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
@@ -312,7 +312,7 @@
</div>
<h1>forrest:views concept (Draft -feature planed for 0.8)</h1>
<div id="motd-area">
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -333,47 +333,52 @@
<div class="warning">
<div class="label">Warning</div>
-<div class="content">This document is heavily under development</div>
+<div class="content">
+ This document is heavily under development
+ </div>
</div>
<a name="N10010"></a><a name="introduction"></a>
<h2 class="underlined_10">Introduction</h2>
<div class="section">
<p>
- Like stated in the <a href="../docs_0_70/skins.html">Skin documentation
- file</a> the aim of the forrest skins is to provide
- many capabilities so that extra skins are not needed. Our experience showed that many forrest user
- had to create a new skin because the default skin did not offer the feature their wanted to use.
- That leaded us to develop a new concept of creating skins that would be easily extensible by a user.
+ Like stated in the <a href="../docs_0_70/skins.html">Skin
+ documentation file</a> the aim of the forrest skins is to provide many
+ capabilities so that extra skins are not needed. Our experience showed
+ that many forrest user had to create a new skin because the default skin
+ did not offer the feature their wanted to use. That leaded us to develop
+ a new concept of creating skins that would be easily extensible by a
+ user.
</p>
<p>
- The aim of the upcoming "forrest:views" skinning concept is to provide a flexible framework for creating
- site and page specific layout in different formats.
+ The aim of the upcoming "forrest:views" skinning concept is to provide a
+ flexible framework for creating site and page specific layout in
+ different formats.
</p>
</div>
-
<a name="N10021"></a><a name="background"></a>
<h2 class="underlined_10">Background</h2>
<div class="section">
<p>
- The problem with the forrest skins so far has been that "only" the design changed (html-skeleton),
- but still we had to write a completely new skin and implement all functionality.
- Another problem was that the functionality was not easy extensible by a user.
- Then we decided to support the a standard regarding naming conventions for css elements.
- This standard has been developed on the <a href="http://www.oscom.org/events/oscom4/proposals/skins">
- OSCOM website</a>, where you can find some more background informations.
+ The problem with the forrest skins so far has been that "only" the
+ design changed (html-skeleton), but still we had to write a completely
+ new skin and implement all functionality. Another problem was that the
+ functionality was not easy extensible by a user. Then we decided to
+ support the a standard regarding naming conventions for css elements.
+ This standard has been developed on the
+ <a href="http://www.oscom.org/events/oscom4/proposals/skins"> OSCOM
+ website</a>, where you can find some more background informations.
</p>
</div>
-
<a name="N1002F"></a><a name="nc-definition"></a>
<h2 class="underlined_10">Definition of naming conventions</h2>
<div class="section">
<p>
- "A naming convention is an attempt to systematize names in a field so
- they unambiguously convey similar information in a similar manner."
- <a href="http://www.wordiq.com/definition/Naming_convention">wordiq-definition</a>
+ "A naming convention is an attempt to systematize names in a field so
+ they unambiguously convey similar information in a similar manner."
+ <a href="http://www.wordiq.com/definition/Naming_convention">wordiq-definition</a>
</p>
</div>
@@ -382,9 +387,11 @@
<h2 class="underlined_10">leather-dev</h2>
<div class="section">
<p>
- That leaded to the development of the "leather-dev" skin which established a semantic container approach for div elements.
- The problems with leather-dev was pointed out on the mail
- <a href="http://marc.theaimsgroup.com/?l=forrest-dev%C2%A0m=111049344517653%C2%A0w=2">status on leather-dev?</a>
+ That leaded to the development of the "leather-dev" skin which
+ established a semantic container approach for div elements. The problems
+ with leather-dev was pointed out on the mail
+ <a href="http://marc.theaimsgroup.com/?l=forrest-dev%C2%A0m=111049344517653%C2%A0w=2">status
+ on leather-dev?</a>
</p>
</div>
Modified: forrest/site/docs_0_70/your-project.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/your-project.html?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
--- forrest/site/docs_0_70/your-project.html (original)
+++ forrest/site/docs_0_70/your-project.html Wed Apr 18 01:36:14 2007
@@ -3,7 +3,7 @@
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
-<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-version" content="0.9-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Using Forrest (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
@@ -87,7 +87,7 @@
|start Subtabs
+-->
<div id="level2tabs">
-<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
+<a class="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="unselected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="selected" href="../docs_0_70/index.html">0.70 (past)</a>
</div>
<!--+
|end Endtabs
@@ -100,7 +100,7 @@
|breadtrail
+-->
<div class="breadtrail">
-
+
</div>
<!--+
@@ -283,7 +283,7 @@
</div>
<div id="credit">
<hr>
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
@@ -313,7 +313,7 @@
<h1>Using Forrest</h1>
<h3>A tutorial on how to use Forrest in your own projects</h3>
<div id="motd-area">
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -426,38 +426,50 @@
<h2 class="underlined_10">Introduction</h2>
<div class="section">
<p>
- This tutorial will lead you through the process of installing Forrest, and using
- it to create a new project, or add Forrest-based docs to an existing project.
+ This tutorial will lead you through the process of installing Forrest,
+ and using it to create a new project, or add Forrest-based docs to an
+ existing project.
</p>
</div>
-
-
+
<a name="N1001A"></a><a name="installing"></a>
<h2 class="underlined_10">Installing Forrest</h2>
<div class="section">
<p>
-
-<a href="http://forrest.apache.org/mirrors.cgi">Download</a> the latest release
- of Forrest and follow the index.html in the top-level, or
- if you want to try the development version, then
- <a href="../docs_0_70/build.html">build Forrest</a> from source.
- </p>
+
+<a href="http://forrest.apache.org/mirrors.cgi">Download</a> the latest release of
+ Forrest and follow the index.html in the top-level, or if you want to
+ try the development version, then
+ <a href="../docs_0_70/build.html">build Forrest</a> from
+ source.
+ </p>
<a name="N1002B"></a><a name="Setting+up+the+Environment"></a>
<h3 class="underlined_5">Setting up the Environment</h3>
<p>
- After downloading and extracting forrest, you need to add environment variables.
- </p>
+ After downloading and extracting forrest, you need to add environment
+ variables.
+ </p>
<a name="N10034"></a><a name="In+Unix%2FLinux%3A"></a>
<h4>In Unix/Linux:</h4>
-<p class="instruction">change directory to the top-level of the forrest distribution and do ...</p>
-<p class="instruction">~/apache-forrest-0.7$ export FORREST_HOME=`pwd`</p>
-<p class="instruction">~/apache-forrest-0.7$ export PATH=$PATH:$FORREST_HOME/bin</p>
+<p class="instruction">
+ change directory to the top-level of the forrest distribution and do
+ ...
+ </p>
+<p class="instruction">
+ ~/apache-forrest-0.7$ export FORREST_HOME=`pwd`
+ </p>
+<p class="instruction">
+ ~/apache-forrest-0.7$ export PATH=$PATH:$FORREST_HOME/bin
+ </p>
<a name="N10046"></a><a name="Permanently+Setting+The+Environment+Variables+for+Linux%2FUnix"></a>
<h5>Permanently Setting The Environment Variables for Linux/Unix</h5>
-<p>Export only changes the variables during that terminal session for that
- user, this is useful for testing. To permanently add the variable edit either
- <span class="codefrag">/etc/bash.bashrc</span> (for all users) or <span class="codefrag">~/.bash_profile</span>
- (for individual users). Add these lines to the end of the file you edit:</p>
+<p>
+ Export only changes the variables during that terminal session for
+ that user, this is useful for testing. To permanently add the
+ variable edit either <span class="codefrag">/etc/bash.bashrc</span> (for all users)
+ or <span class="codefrag">~/.bash_profile</span> (for individual users). Add these
+ lines to the end of the file you edit:
+ </p>
<pre class="code">
FORREST_HOME=/full/path/to/forrest
export FORREST_HOME
@@ -467,26 +479,42 @@
</pre>
<a name="N1005B"></a><a name="Windows+2000"></a>
<h4>Windows 2000</h4>
-<p class="instruction">Go to "My Computer", "Properties", "Advanced", "Environment Variables"</p>
-<p class="instruction">add a new variable <span class="codefrag">FORREST_HOME</span> as <span class="codefrag">C:\full\path\to\apache-forrest-0.7</span>
+<p class="instruction">
+ Go to "My Computer", "Properties", "Advanced", "Environment
+ Variables"
+ </p>
+<p class="instruction">
+ add a new variable <span class="codefrag">FORREST_HOME</span> as
+ <span class="codefrag">C:\full\path\to\apache-forrest-0.7</span>
+
</p>
-<p class="instruction">edit <span class="codefrag">PATH</span> as <span class="codefrag">%PATH%;%FORREST_HOME%\bin</span>
+<p class="instruction">
+ edit <span class="codefrag">PATH</span> as <span class="codefrag">%PATH%;%FORREST_HOME%\bin</span>
+
</p>
-<a name="N10078"></a><a name="In+Windows+XP%3A"></a>
+<a name="N1007A"></a><a name="In+Windows+XP%3A"></a>
<h4>In Windows XP:</h4>
-<p class="instruction">Go to "My Computer", "Properties", "Advanced", "Environment Variables"</p>
-<p class="instruction">Create a New variable with name: FORREST_HOME value: C:\full\path\to\apache-forrest-0.7</p>
-<p class="instruction">Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current value.</p>
-</div>
-
-
-<a name="N1008D"></a><a name="The+%27forrest%27+Command"></a>
+<p class="instruction">
+ Go to "My Computer", "Properties", "Advanced", "Environment
+ Variables"
+ </p>
+<p class="instruction">
+ Create a New variable with name: FORREST_HOME value:
+ C:\full\path\to\apache-forrest-0.7
+ </p>
+<p class="instruction">
+ Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current
+ value.
+ </p>
+</div>
+
+<a name="N1008F"></a><a name="The+%27forrest%27+Command"></a>
<h2 class="underlined_10">The 'forrest' Command</h2>
<div class="section">
<p>
- To see what the 'forrest' command can do, type 'forrest -projecthelp'.
- The build targets that are marked with * are the commonly used ones.
- </p>
+ To see what the 'forrest' command can do, type 'forrest -projecthelp'.
+ The build targets that are marked with * are the commonly used ones.
+ </p>
<pre class="code">
Apache Forrest. Run 'forrest -projecthelp' to list options
@@ -532,15 +560,15 @@
Default target: site
</pre>
<p>
- As 'site' is the default target, just running 'forrest' without options will
- generate a "static HTML website". For example, typing 'forrest' in the
- top-level "forrest/site-author" directory would build Forrest's own website.
- But we're going to be building a new site for your project, so read on.
- </p>
+ As 'site' is the default target, just running 'forrest' without options
+ will generate a "static HTML website". For example, typing 'forrest' in
+ the top-level "forrest/site-author" directory would build Forrest's own
+ website. But we're going to be building a new site for your project, so
+ read on.
+ </p>
</div>
-
-<a name="N1009E"></a><a name="seeding_new"></a>
+<a name="N100A0"></a><a name="seeding_new"></a>
<h2 class="underlined_10">Seeding a new project</h2>
<div class="section">
<p>
@@ -548,9 +576,8 @@
documentation set to your project, which you can then customize.
</p>
<p>
- To try this out, create a completely new directory (outside the
- Forrest distribution), then change directory
- to it, and do 'forrest seed':
+ To try this out, create a completely new directory (outside the Forrest
+ distribution), then change directory to it, and do 'forrest seed':
</p>
<pre class="code">
[/home/me/forrest/my-test]$ forrest seed
@@ -613,7 +640,8 @@
<div class="label">Note</div>
<div class="content">
As you have probably noticed, we like to document things right in the
- script, on the theory that people only read online docs when desperate :)
+ script, on the theory that people only read online docs when desperate
+ :)
</div>
</div>
<p>
@@ -677,22 +705,22 @@
|-- status.xml
</pre>
<p>
- To render this to HTML, type 'forrest'. You should have a HTML site rendered
- into the <span class="codefrag">build/site</span> directory:
+ To render this to HTML, type 'forrest'. You should have a HTML site
+ rendered into the <span class="codefrag">build/site</span> directory:
</p>
<div id="" style="text-align: center;">
<img id="" class="figure" alt="New project" src="images/new-project.png" height="356" width="500"></div>
<p>
Practise with adding new content. Change to the directory
<span class="codefrag">src/documentation/content/xdocs</span> and copy the file
- <span class="codefrag">index.xml</span> to create <span class="codefrag">my-new-file.xml</span> as a
- new document. Edit it to change some text. Add an entry to
- <span class="codefrag">site.xml</span> by copying one of the other entries and
- changing it to suit. Now do 'forrest' to see the result.
+ <span class="codefrag">index.xml</span> to create <span class="codefrag">my-new-file.xml</span> as a new
+ document. Edit it to change some text. Add an entry to
+ <span class="codefrag">site.xml</span> by copying one of the other entries and changing
+ it to suit. Now do 'forrest' to see the result.
</p>
</div>
-<a name="N100D4"></a><a name="seeding_existing"></a>
+<a name="N100D6"></a><a name="seeding_existing"></a>
<h2 class="underlined_10">Seeding an existing project</h2>
<div class="section">
<p>
@@ -706,27 +734,28 @@
If your project already has XML documentation, it may be easier to tell
Forrest where the XML sources are, rather than rearrange your project
directories to accommodate Forrest. This can be done by editing
- <span class="codefrag">forrest.properties</span> (consult
- the <a href="#Changing_the_layout">Changing the layout</a>
- section for more details).
+ <span class="codefrag">forrest.properties</span> (consult the
+ <a href="#Changing_the_layout">Changing the layout</a> section for
+ more details).
</p>
</div>
-<a name="N100E8"></a><a name="customizing"></a>
+<a name="N100EA"></a><a name="customizing"></a>
<h2 class="underlined_10">Customizing your project</h2>
<div class="section">
<p>
- Having seeded a project with template docs, you will now want to customize it
- to your project's needs. Here we will deal with configuring the skin, and
- changing the project layout.
+ Having seeded a project with template docs, you will now want to
+ customize it to your project's needs. Here we will deal with configuring
+ the skin, and changing the project layout.
</p>
-<a name="N100F1"></a><a name="skinconf.xml"></a>
+<a name="N100F3"></a><a name="skinconf.xml"></a>
<h3 class="underlined_5">Configuring the Forrest skin: skinconf.xml</h3>
<p>
Most Forrest skins can be customized through a single XML file,
<span class="codefrag">src/documentation/skinconf.xml</span>, which looks like this:
</p>
<pre class="code">
+
<!--
Skin configuration file. This file contains details of your project,
which will be used to configure the chosen Forrest skin.
@@ -886,36 +915,36 @@
</credits>
</skinconfig>
-</pre>
+
+ </pre>
<p>
- Customise this file for your project. The <span class="codefrag">images/</span> directory
- mentioned in 'project-logo' and 'group-logo' elements corresponds to the
- <span class="codefrag">src/documentation/resources/images</span> directory
- (this mapping is done automatically by the sitemap).
+ Customise this file for your project. The <span class="codefrag">images/</span>
+ directory mentioned in 'project-logo' and 'group-logo' elements
+ corresponds to the <span class="codefrag">src/documentation/resources/images</span>
+ directory (this mapping is done automatically by the sitemap).
</p>
<p>
- Having edited this file (and ensured it is valid XML), re-run the 'forrest'
- command in the site root, and the site would be updated.
+ Having edited this file (and ensured it is valid XML), re-run the
+ 'forrest' command in the site root, and the site would be updated.
</p>
-<a name="N1010E"></a><a name="Changing_the_layout"></a>
+<a name="N10110"></a><a name="Changing_the_layout"></a>
<h3 class="underlined_5">Changing the layout: forrest.properties</h3>
<p>
- Forrest allows you to place files anywhere you want in your
- project, so long as you tell Forrest where you have placed the
- major file types.
+ Forrest allows you to place files anywhere you want in your project,
+ so long as you tell Forrest where you have placed the major file
+ types.
</p>
<p>
The <span class="codefrag">forrest.properties</span> file maps from your directory
- layout to Forrest's. If you generated your site with 'forrest seed', you
- will have one pre-written, with all the entries commented out.
+ layout to Forrest's. If you generated your site with 'forrest seed',
+ you will have one pre-written, with all the entries commented out.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
- You only need to un-comment entries if you are going to change them
- to something different.
- If you keep in synchronisation with the 'forrest seed' defaults,
- then it is easy to diff each time that you update.
+ You only need to un-comment entries if you are going to change them to
+ something different. If you keep in synchronisation with the 'forrest
+ seed' defaults, then it is easy to diff each time that you update.
</div>
</div>
<p>
@@ -942,21 +971,23 @@
#project.classes-dir=${project.content-dir}/classes
</pre>
<p>
- For example, if you wish to keep XML documentation in src/xdocs rather than
- <span class="codefrag">src/documentation/content/xdocs</span> simply change the
- definition for project.xdocs-dir
- </p>
+ For example, if you wish to keep XML documentation in src/xdocs rather
+ than <span class="codefrag">src/documentation/content/xdocs</span> simply change the
+ definition for project.xdocs-dir
+ </p>
<pre class="code">project.xdocs-dir=src/xdocs</pre>
<p>
- For example, to emulate the simple
- <a href="http://maven.apache.org/">Maven</a> format:
- </p>
-<div class="pre">
+ For example, to emulate the simple
+ <a href="http://maven.apache.org/">Maven</a> format:
+ </p>
+<pre class="code">
/xdocs
/xdocs/images
/xdocs/stylesheets
- </div>
-<p>Here are the required property definitions:</p>
+ </pre>
+<p>
+ Here are the required property definitions:
+ </p>
<pre class="code">
project.content-dir=xdocs
project.sitemap-dir=${project.content-dir}
@@ -968,17 +999,16 @@
<div class="note">
<div class="label">Note</div>
<div class="content">
- Internally, Forrest rearranges the specified directory into the default
- <span class="codefrag">src/documentation/content/xdocs</span> structure. In the layout above, we have
- overlapping directories, so you will end up with duplicate files. This small
- glitch doesn't usually cause problems; just always remember that all links
- are resolved through the sitemap.
- </div>
+ Internally, Forrest rearranges the specified directory into the
+ default <span class="codefrag">src/documentation/content/xdocs</span> structure. In the
+ layout above, we have overlapping directories, so you will end up with
+ duplicate files. This small glitch doesn't usually cause problems;
+ just always remember that all links are resolved through the sitemap.
+ </div>
</div>
</div>
-
-<a name="N1014D"></a><a name="adding_content"></a>
+<a name="N1014F"></a><a name="adding_content"></a>
<h2 class="underlined_10">Adding content</h2>
<div class="section">
<p>
@@ -986,71 +1016,72 @@
<span class="codefrag">src/documentation/content/xdocs</span>
</p>
-<a name="N10159"></a><a name="site.xml"></a>
+<a name="N1015B"></a><a name="site.xml"></a>
<h3 class="underlined_5">site.xml</h3>
<p>
- When adding a new xml document, you would add an entry to the project's
- <span class="codefrag">site.xml</span> file. This site.xml is like a site index, and is rendered as
- the vertical column of links in the default skin. Look at Forrest's own
- xdocs for an example. More detailed info about site.xml is provided in
- the document <a href="../docs_0_70/linking.html">Menus and Linking</a>.
+ When adding a new xml document, you would add an entry to the
+ project's <span class="codefrag">site.xml</span> file. This site.xml is like a site
+ index, and is rendered as the vertical column of links in the default
+ skin. Look at Forrest's own xdocs for an example. More detailed info
+ about site.xml is provided in the document
+ <a href="../docs_0_70/linking.html">Menus and Linking</a>.
</p>
-<a name="N1016A"></a><a name="tabs.xml"></a>
+<a name="N1016C"></a><a name="tabs.xml"></a>
<h3 class="underlined_5">tabs.xml</h3>
<p>
- The <span class="codefrag">tabs.xml</span> file is used to produce the 'tabs'.
- which enable users to quickly jump to sections of your site.
- See the
- <a href="../docs_0_70/linking.html#menu_generation">menu generation</a> documentation
- for more details, and again, consult Forrest's own docs for a usage
- example.
+ The <span class="codefrag">tabs.xml</span> file is used to produce the 'tabs'. which
+ enable users to quickly jump to sections of your site. See the
+ <a href="../docs_0_70/linking.html#menu_generation">menu generation</a>
+ documentation for more details, and again, consult Forrest's own docs
+ for a usage example.
</p>
<div id="" style="text-align: center;">
<img id="" class="figure" alt="Tabs" src="images/tabs.png"></div>
-<p>You can have one or two levels of tabs. The images above show a
- single level. However, you can create a second level that
- will only be displayed when its parent tab is selected. For example,
- the <span class="codefrag">tabs.xml</span> snippet below will display either one or
- two rows of tabs, depending on which of the top level tabs is selected.
- The first row will have two tabs: one labelled <span class="codefrag">How-Tos</span>
- and the other labelled <span class="codefrag">Apache XML Projects</span>. When the
- <span class="codefrag">How-Tos</span> tab is selected there will
- be no second row of tabs. However, when the <span class="codefrag">Apache XML
- Projects</span> tab is selected, a second row of tabs will be displayed
- below the first.</p>
+<p>
+ You can have one or two levels of tabs. The images above show a single
+ level. However, you can create a second level that will only be
+ displayed when its parent tab is selected. For example, the
+ <span class="codefrag">tabs.xml</span> snippet below will display either one or two
+ rows of tabs, depending on which of the top level tabs is selected.
+ The first row will have two tabs: one labelled <span class="codefrag">How-Tos</span>
+ and the other labelled <span class="codefrag">Apache XML Projects</span>. When the
+ <span class="codefrag">How-Tos</span> tab is selected there will be no second row of
+ tabs. However, when the <span class="codefrag">Apache XML Projects</span> tab is
+ selected, a second row of tabs will be displayed below the first.
+ </p>
<pre class="code">
+
<tab label="How-Tos" dir="community/howto/"/>
<tab label="Apache XML Projects" href="http://xml.apache.org">
<tab label="Forrest" href="http://forrest.apache.org/"/>
<tab label="Xerces" href="http://xml.apache.org/xerces"/>
</tab>
-</pre>
-<a name="N10195"></a><a name="images"></a>
+
+ </pre>
+<a name="N10197"></a><a name="images"></a>
<h3 class="underlined_5">Images</h3>
<p>
Images usually go in the <span class="codefrag">content/xdocs/images/</span> directory.
- The default sitemap
- maps this directory to <span class="codefrag">images/</span> so image tags will typically look
- like <span class="codefrag"><figure src="images/project-logo.png" alt="Project Logo"/></span>
+ The default sitemap maps this directory to <span class="codefrag">images/</span> so
+ image tags will typically look like <span class="codefrag"><figure
+ src="images/project-logo.png" alt="Project Logo"/></span>
</p>
</div>
-
-<a name="N101A9"></a><a name="sitemap.xmap"></a>
+<a name="N101AB"></a><a name="sitemap.xmap"></a>
<h2 class="underlined_10">Advanced customizations: sitemap.xmap</h2>
<div class="section">
<p>
- The Cocoon sitemap is a set of rules for generating content (HTML, PDFs etc)
- from XML sources. Forrest has a default sitemap, which is adequate for
- everyday sites. For example, the
- <a href="http://forrest.apache.org/">Forrest website</a> itself uses the
- default sitemap.
+ The Cocoon sitemap is a set of rules for generating content (HTML, PDFs
+ etc) from XML sources. Forrest has a default sitemap, which is adequate
+ for everyday sites. For example, the <a href="http://forrest.apache.org/">Forrest
+ website</a> itself uses the default sitemap.
</p>
<p>
- Sometimes, one needs to go beyond the default set of rules. This is where
- Forrest really shines, because its Cocoon backend allows virtually any
- processing pipeline to be defined. For example, one can:
+ Sometimes, one needs to go beyond the default set of rules. This is
+ where Forrest really shines, because its Cocoon backend allows virtually
+ any processing pipeline to be defined. For example, one can:
</p>
<ul>
@@ -1081,43 +1112,42 @@
</ul>
<p>
- The Forrest sitemaps are at
- <span class="codefrag">main/webapp/*.xmap</span>
+ The Forrest sitemaps are at <span class="codefrag">main/webapp/*.xmap</span>
</p>
<p>
You can add pre-processing sitemaps to your project
<span class="codefrag">src/documentation</span> directory (or wherever
<span class="codefrag">${project.sitemap-dir}</span> points to). Get a copy of a simple
- sitemap.xmap from a 'forrest seed site'. </p>
-<p>Any match that
- is not handled, passes through to be handled by the default Forrest
- sitemaps - obviously extremely powerful. The capability is described
- in
- "<a href="../docs_0_70/project-sitemap.html">Using project sitemaps</a>"
- and some worked examples are shown in the following sections here.
+ sitemap.xmap from a 'forrest seed site'.
+ </p>
+<p>
+ Any match that is not handled, passes through to be handled by the
+ default Forrest sitemaps - obviously extremely powerful. The capability
+ is described in "<a href="../docs_0_70/project-sitemap.html">Using project
+ sitemaps</a>" and some worked examples are shown in the following
+ sections here.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
- We advise you to spend time to understand the Apache Cocoon sitemap.
- See <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html">Cocoon sitemap</a>
- and <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Cocoon concepts</a>
- and related component documentation.
- The Forrest sitemap is broken into multiple files. The main one is
- <strong>sitemap.xmap</strong> which delegates to others. See the
- <a href="../docs_0_70/sitemap-ref.html">Sitemap Reference</a> for a tour of the
- default sitemap.
+ We advise you to spend time to understand the Apache Cocoon sitemap. See
+ <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html">Cocoon sitemap</a> and
+ <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Cocoon concepts</a> and related
+ component documentation. The Forrest sitemap is broken into multiple
+ files. The main one is <strong>sitemap.xmap</strong> which delegates to
+ others. See the <a href="../docs_0_70/sitemap-ref.html">Sitemap
+ Reference</a> for a tour of the default sitemap.
</div>
</div>
-<a name="N10211"></a><a name="adding_new_content_type"></a>
+<a name="N10213"></a><a name="adding_new_content_type"></a>
<h3 class="underlined_5">Example: Adding a new content type</h3>
<p>
- There are two methods for detecting types of documents
- and doing special handling. The more complete solution is
- <a href="#adding_new_content_type_2">described</a>
- in the advanced section below. However, this basic method
- is also worth understanding.
+ There are two methods for detecting types of documents and doing
+ special handling. The more complete solution is
+ <a href="#adding_new_content_type_2">described</a> in the
+ advanced section below. However, this basic method is also worth
+ understanding.
</p>
<p>
Follow this worked example. In a fresh directory do 'forrest seed'
@@ -1126,12 +1156,13 @@
<p>
An example scenario is that we have a specialised list of downloads
for a certain software package. It would be best to represent the
- download information in a custom XML format. This means that it
- will have its own document type declaration. We will need
- to detect this new document type via our project sitemap
- and also provide a mapping to a local copy of this DTD.
+ download information in a custom XML format. This means that it will
+ have its own document type declaration. We will need to detect this
+ new document type via our project sitemap and also provide a mapping
+ to a local copy of this DTD.
</p>
-<pre class="code"><?xml version="1.0" encoding="utf-8"?>
+<pre class="code">
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"dtd/download-v10.dtd">
<document>
@@ -1170,18 +1201,22 @@
<p>....</p>
</section>
</body>
-</document></pre>
-<p>This file called "<span class="codefrag">download.xml</span>" would be placed in
- your content directory (typically
+</document>
+ </pre>
+<p>
+ This file called "<span class="codefrag">download.xml</span>" would be placed in your
+ content directory (typically
<span class="codefrag">src/documentation/content/xdocs</span>) and an entry added to
<span class="codefrag">site.xml</span>
+
</p>
<p>
To handle these special tags, one would write a stylesheet to convert
- them to the intermediate Forrest xdocs structure. Here is such a stylesheet,
- called "<span class="codefrag">download2document.xsl</span>" ...
+ them to the intermediate Forrest xdocs structure. Here is such a
+ stylesheet, called "<span class="codefrag">download2document.xsl</span>" ...
</p>
-<pre class="code"><?xml version="1.0" encoding="utf-8"?>
+<pre class="code">
+<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet
version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
@@ -1213,104 +1248,110 @@
</xsl:template>
</xsl:stylesheet>
-</pre>
+
+ </pre>
<p>
- Place this file in the default stylesheets directory,
- <span class="codefrag">src/documentation/resources/stylesheets</span> (or wherever
- ${project.stylesheets-dir} points).
- </p>
+ Place this file in the default stylesheets directory,
+ <span class="codefrag">src/documentation/resources/stylesheets</span> (or wherever
+ ${project.stylesheets-dir} points).
+ </p>
<p>
- Now we will create a project sitemap to control the
- transformation of our custom xml
- structure into the Forrest intermediate xdocs structure.
- </p>
+ Now we will create a project sitemap to control the transformation of
+ our custom xml structure into the Forrest intermediate xdocs
+ structure.
+ </p>
<div class="note">
<div class="label">Note</div>
<div class="content">
- The <a href="../docs_0_70/sitemap-ref.html">Sitemap
- Reference</a> provides details about how the sitemap works.
- </div>
+ The <a href="../docs_0_70/sitemap-ref.html">Sitemap Reference</a>
+ provides details about how the sitemap works.
+ </div>
</div>
<p>
- Add the following match to the file
- <span class="codefrag">src/documentation/sitemap.xmap</span> ...
- </p>
-<pre class="code"><?xml version="1.0"?>
+ Add the following match to the file
+ <span class="codefrag">src/documentation/sitemap.xmap</span> ...
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
<map:pipeline>
...
<strong>
+
<map:match pattern="**download.xml">
<map:generate src="{properties:content.xdocs}{1}download.xml" />
<map:transform src="{properties:resources.stylesheets}/download2document.xsl" />
<map:serialize type="xml"/>
</map:match>
</strong>
+
</map:pipeline>
</map:pipelines>
</map:sitemap>
-</pre>
+
+ </pre>
<p>
- That will intercept the request for the body content, for only
- this specific "download" document, and will transform it into the
- intermediate Forrest "document" format. The normal Forrest machinery
- will handle the aggregation with navigation menus etc. and will
- apply the normal skin.
- </p>
-<a name="N1025D"></a><a name="new_dtd"></a>
+ That will intercept the request for the body content, for only this
+ specific "download" document, and will transform it into the
+ intermediate Forrest "document" format. The normal Forrest machinery
+ will handle the aggregation with navigation menus etc. and will apply
+ the normal skin.
+ </p>
+<a name="N10260"></a><a name="new_dtd"></a>
<h4>Registering a new DTD</h4>
<p>
- By default, Forrest requires that all XML files be valid, i.e.
- they must have a DOCTYPE declaration and associated DTD, and
- validate against it. Our new 'downloads' document type is no
- exception. The <a href="../docs_0_70/validation.html">XML
- Validation</a> document continues this example, showing how
- to register a new document type. Briefly, this involves:
- </p>
+ By default, Forrest requires that all XML files be valid, i.e. they
+ must have a DOCTYPE declaration and associated DTD, and validate
+ against it. Our new 'downloads' document type is no exception. The
+ <a href="../docs_0_70/validation.html">XML Validation</a> document
+ continues this example, showing how to register a new document type.
+ Briefly, this involves:
+ </p>
<ul>
-
+
<li>Create a new DTD or (in our case) extend an existing
one.</li>
-
+
<li>Place the new DTD in the
<span class="codefrag">${project.schema-dir}/dtd</span> directory.</li>
-
+
<li>Add an XML Catalog to enable a mapping from the
DOCTYPE public id to the relevant DTD file.</li>
-
+
<li>Tell the system about your catalog.</li>
-
+
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content">
- Please see <a href="../docs_0_70/validation.html">XML Validation</a>
- for the complete description for those steps.
- </div>
+ Please see <a href="../docs_0_70/validation.html">XML Validation</a>
+ for the complete description for those steps.
+ </div>
</div>
-<a name="N10285"></a><a name="adding_new_content_type_2"></a>
+<a name="N10288"></a><a name="adding_new_content_type_2"></a>
<h3 class="underlined_5">Example: Adding a new content type (advanced)</h3>
<p>
- The simple user sitemap in the previous example is fine for
- simple situations. For a complete solution to the "Download DTD"
- issue we need a more advanced sitemap which will do different
- processing depending on the type of the source document.
- </p>
+ The simple user sitemap in the previous example is fine for simple
+ situations. For a complete solution to the "Download DTD" issue we
+ need a more advanced sitemap which will do different processing
+ depending on the type of the source document.
+ </p>
<p>
- We need to digress and explain the powerful
- <a href="../docs_0_70/cap.html">SourceTypeAction (content aware pipelines)</a>.
- It is a Cocoon sitemap component that peeks at the top-part of
- a document to look for hints about the type of the document.
- It has four methods: document-declaration, document-element and
- namespace, processing-instruction, w3c-xml-schema.
- </p>
+ We need to digress and explain the powerful
+ <a href="../docs_0_70/cap.html">SourceTypeAction (content aware
+ pipelines)</a>. It is a Cocoon sitemap component that peeks at the
+ top-part of a document to look for hints about the type of the
+ document. It has four methods: document-declaration, document-element
+ and namespace, processing-instruction, w3c-xml-schema.
+ </p>
<p>
- Now to return to our specific example which uses SourceTypeAction
- to detect the Document Type Declaration. Let us show the sitemap
- and then explain it.
- </p>
-<pre class="code"><?xml version="1.0"?>
+ Now to return to our specific example which uses SourceTypeAction to
+ detect the Document Type Declaration. Let us show the sitemap and then
+ explain it.
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components>
@@ -1355,185 +1396,201 @@
</map:pipeline>
</map:pipelines>
</map:sitemap>
-</pre>
+
+ </pre>
<p>
- This is the type of processing that happens in the main
- <span class="codefrag">main/webapp/forrest.xmap</span> sitemap. We have
- added similar handling to our project sitemap. Basically, this
- uses the <a href="../docs_0_70/cap.html">SourceTypeAction (content aware pipelines)</a>
- to detect the doctype. The new document-v11.dtd needs to be also
- added to your project Catalog as
- <a href="#new_dtd">described above</a>.
- </p>
+ This is the type of processing that happens in the main
+ <span class="codefrag">main/webapp/forrest.xmap</span> sitemap. We have added similar
+ handling to our project sitemap. Basically, this uses the
+ <a href="../docs_0_70/cap.html">SourceTypeAction (content aware
+ pipelines)</a> to detect the doctype. The new document-v11.dtd
+ needs to be also added to your project Catalog as
+ <a href="#new_dtd">described above</a>.
+ </p>
<p>
- Note that any sitemap component must be declared before it
- can be used, because the project sitemap is the first sitemap
- to be consulted.
- </p>
-<a name="N102AE"></a><a name="integrating_rss"></a>
+ Note that any sitemap component must be declared before it can be
+ used, because the project sitemap is the first sitemap to be
+ consulted.
+ </p>
+<a name="N102B1"></a><a name="integrating_rss"></a>
<h3 class="underlined_5">Example: integrating external RSS content</h3>
-<p>Similar to the previous example, we can integrate RSS into our
- site simply by providing a match in our project sitemap.xmap ...
- </p>
-<pre class="code"><?xml version="1.0"?>
+<p>
+ Similar to the previous example, we can integrate RSS into our site
+ simply by providing a match in our project sitemap.xmap ...
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
- <map:pipeline>
- <strong>
+ <map:pipeline><strong>
+
<map:match pattern="**weblog.xml">
<map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/>
<map:transform src="{forrest:forrest.stylesheets}/rss2document.xsl"/>
<map:serialize type="xml"/>
</map:match>
</strong>
+
<map:match pattern=".......">
<!-- handle other project-specific matches -->
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>
-</pre>
-<p>You will probably want to copy the core Forrest
- <span class="codefrag">rss2document.xsl</span> to your project,
- customise it to your needs, and refer to it with
- <span class="codefrag">src="{properties:resources.stylesheets}/rss2document.xsl"</span>.
- Then of course you would add an entry to site.xml to link
- to weblog.html
- </p>
-</div>
-
-<a name="N102C9"></a><a name="skins"></a>
+ </pre>
+<p>
+ You will probably want to copy the core Forrest
+ <span class="codefrag">rss2document.xsl</span> to your project, customise it to your
+ needs, and refer to it with
+ <span class="codefrag">src="{properties:resources.stylesheets}/rss2document.xsl"</span>.
+ Then of course you would add an entry to site.xml to link to
+ weblog.html
+ </p>
+</div>
+
+<a name="N102CC"></a><a name="skins"></a>
<h2 class="underlined_10">Forrest skins</h2>
<div class="section">
<p>
- As Forrest separates content from presentation, we can plug in different
- "skins" to instantly change a site's look and feel. Forrest provides one
- primary skin, <span class="codefrag">pelt</span>, and some others in various
- states of development.
- To change the skin, edit the <span class="codefrag">forrest.properties</span> file
- to set <span class="codefrag">project.skin=leather-dev</span> or some other skin name.
- If running in dynamic mode you need to restart Forrest in order to see
- the new skin.
- </p>
+ As Forrest separates content from presentation, we can plug in different
+ "skins" to instantly change a site's look and feel. Forrest provides one
+ primary skin, <span class="codefrag">pelt</span>, and some others in various states of
+ development. To change the skin, edit the
+ <span class="codefrag">forrest.properties</span> file to set
+ <span class="codefrag">project.skin=leather-dev</span> or some other skin name. If
+ running in dynamic mode you need to restart Forrest in order to see the
+ new skin.
+ </p>
<div class="note">
<div class="label">Note</div>
<div class="content">
- Forrest supplies a collection of
- <a href="../docs_0_70/skins.html">default skins</a> which are configurable
- and so should meet the needs of most projects. The aim is to provide
- many capabilities so that extra skins are not needed.
- </div>
+ Forrest supplies a collection of <a href="../docs_0_70/skins.html">default
+ skins</a> which are configurable and so should meet the needs of most
+ projects. The aim is to provide many capabilities so that extra skins
+ are not needed.
+ </div>
</div>
-<a name="N102E2"></a><a name="skin-configuration"></a>
+<a name="N102E5"></a><a name="skin-configuration"></a>
<h3 class="underlined_5">Configuration of skins</h3>
<p>
All configuration is done via your project
- <span class="codefrag">src/documentation/skinconf.xml</span> file.
- It contains many comments to describe each capability.
- Please read those, there is no point repeating here.
- </p>
-<a name="N102EF"></a><a name="new_skin"></a>
+ <span class="codefrag">src/documentation/skinconf.xml</span> file. It contains many
+ comments to describe each capability. Please read those, there is no
+ point repeating here.
+ </p>
+<a name="N102F2"></a><a name="new_skin"></a>
<h3 class="underlined_5">Defining a new skin</h3>
-<p>Consider discussing your needs on the mailing lists. There may
- be planned enhancements to the core skins. Also consider contributing
+<p>
+ Consider discussing your needs on the mailing lists. There may be
+ planned enhancements to the core skins. Also consider contributing
your extensions to the core skins, rather than write your own skin.
Bear in mind that you could be creating an update and management
issue. Anyway, ...
- </p>
+ </p>
<p>
- Projects can define their own skin in the
- <span class="codefrag">src/documentation/skins</span> directory (or wherever
- <span class="codefrag">${project.skins-dir}</span> points). The default sitemap assumes a
- certain skin layout, so the easiest way to create a new skin is by
- copying an existing Forrest skin. For example, copy
- <span class="codefrag">main/webapp/skins/pelt</span>
- to your project area at
- <span class="codefrag">src/documentation/skins/my-fancy-skin</span> and add
- <span class="codefrag">project.skin=my-fancy-skin</span> to forrest.properties
- </p>
+ Projects can define their own skin in the
+ <span class="codefrag">src/documentation/skins</span> directory (or wherever
+ <span class="codefrag">${project.skins-dir}</span> points). The default sitemap assumes
+ a certain skin layout, so the easiest way to create a new skin is by
+ copying an existing Forrest skin. For example, copy
+ <span class="codefrag">main/webapp/skins/pelt</span> to your project area at
+ <span class="codefrag">src/documentation/skins/my-fancy-skin</span> and add
+ <span class="codefrag">project.skin=my-fancy-skin</span> to forrest.properties
+ </p>
<p>
- The two most interesting XSLT stylesheets involved are:
- </p>
+ The two most interesting XSLT stylesheets involved are:
+ </p>
<dl>
-
+
<dt>
<span class="codefrag">xslt/html/document2html.xsl</span>
</dt>
-
+
<dd>
This stylesheet is applied to individual Forrest xdocs XML files, and
converts them to HTML suitable for embedding in a larger HTML page.
</dd>
-
+
<dt>
<span class="codefrag">xslt/html/site2xhtml.xsl</span>
</dt>
-
+
<dd>
This stylesheet generates the final HTML file from an intermediate
'site' structure produced by the other stylesheets. It defines the general
layout, and adds the header and footer.
</dd>
-
+
</dl>
<p>
- Typically there is a lot of commonality between skins. XSLT
- provides an 'import' mechanism whereby one XSLT can extend another.
- Forrest XSLTs typically 'import' from a common base:
- </p>
+ Typically there is a lot of commonality between skins. XSLT provides
+ an 'import' mechanism whereby one XSLT can extend another. Forrest
+ XSLTs typically 'import' from a common base:
+ </p>
<pre class="code">
+
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:import href="../../../common/xslt/html/document2html.xsl"/>
- <strong>... overrides of default templates ...</strong>
-</xsl:stylesheet></pre>
-<p>In order to use this feature in your custom skins you must copy
- the common skin from the forrest distribution into your custom skins
- directory (from <span class="codefrag">main/webapp/skins/common</span>).
- This will protect your skin from changes in the Forrest common skin,
- but you must remember to update this skin in order to take advantage
- of new features added over time by the Forrest team.</p>
+ <strong>... overrides of default templates ...</strong>
+
+</xsl:stylesheet>
+ </pre>
+<p>
+ In order to use this feature in your custom skins you must copy the
+ common skin from the forrest distribution into your custom skins
+ directory (from <span class="codefrag">main/webapp/skins/common</span>). This will
+ protect your skin from changes in the Forrest common skin, but you
+ must remember to update this skin in order to take advantage of new
+ features added over time by the Forrest team.
+ </p>
<div class="note">
<div class="label">Note</div>
-<div class="content">The above paragraph means that if you do copy an existing skin
- as this section recomends you will also need to copy the common skin
- since all existing skins import the common skin.</div>
-</div>
-<p>This is particularly relevant for menu rendering (book2menu.xsl),
- where the common stylesheet does the 'logic' of which item is
- selected, and over-riding stylesheets define the presentation.</p>
+<div class="content">
+ The above paragraph means that if you do copy an existing skin as this
+ section recomends you will also need to copy the common skin since all
+ existing skins import the common skin.
+ </div>
+</div>
+<p>
+ This is particularly relevant for menu rendering (book2menu.xsl),
+ where the common stylesheet does the 'logic' of which item is
+ selected, and over-riding stylesheets define the presentation.
+ </p>
</div>
-
-<a name="N10336"></a><a name="webapp"></a>
+<a name="N10339"></a><a name="webapp"></a>
<h2 class="underlined_10">Interactive Forrest: faster turnaround when developing your docs</h2>
<div class="section">
<p>
- In comparison to simpler tools (like
- <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>) the Cocoon command-line mode
- (and hence Forrest command-line mode) is slow.
- As the <a href="../docs_0_70/dreams.html">dream list</a> notes, Forrest was
- originally intended to be used for
- dynamic sites, and the Cocoon crawler used only to create static
- snapshots for mirroring. This section describes how, by using
- a "live" Forrest webapp instance, the Forrest-based documentation
- development can be faster and easier than with comparable tools.
+ In comparison to simpler tools (like
+ <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>) the Cocoon command-line mode (and
+ hence Forrest command-line mode) is slow. As the
+ <a href="../docs_0_70/dreams.html">dream list</a> notes, Forrest was
+ originally intended to be used for dynamic sites, and the Cocoon crawler
+ used only to create static snapshots for mirroring. This section
+ describes how, by using a "live" Forrest webapp instance, the
+ Forrest-based documentation development can be faster and easier than
+ with comparable tools.
</p>
-<a name="N10347"></a><a name="forrest_run"></a>
+<a name="N1034A"></a><a name="forrest_run"></a>
<h3 class="underlined_5">Running as a webapp</h3>
<p>
- Type '<span class="codefrag">forrest run</span>' in your project root to start Forrest's
- built-in Jetty web server. Once it has started, point your browser at
- <a href="http://localhost:8888/">http://localhost:8888/</a>, which
- will show your website, rendered on demand as each link is followed.
+ Type '<span class="codefrag">forrest run</span>' in your project root to start
+ Forrest's built-in Jetty web server. Once it has started, point your
+ browser at
+ <a href="http://localhost:8888/">http://localhost:8888/</a>,
+ which will show your website, rendered on demand as each link is
+ followed.
</p>
-<p>(Alternatively, if you wish to run Forrest from within an existing
+<p>
+ (Alternatively, if you wish to run Forrest from within an existing
servlet container, type <span class="codefrag">forrest webapp</span> to build an open
webapp in <span class="codefrag">build/webapp/</span>)
</p>
-<a name="N10360"></a><a name="using_webapp"></a>
+<a name="N10363"></a><a name="using_webapp"></a>
<h4>Using the webapp</h4>
<p>
You can now edit the XML content in
@@ -1542,16 +1599,18 @@
</p>
</div>
-<a name="N1036F"></a><a name="invoking_from_ant"></a>
+<a name="N10372"></a><a name="invoking_from_ant"></a>
<h2 class="underlined_10">Invoking Forrest from Ant</h2>
<div class="section">
<p>
Ant has an
<a href="http://ant.apache.org/manual/CoreTasks/import.html"><import></a>
- task which can be used to invoke Forrest from Ant. All targets and properties
- are imported and can be used in your project build. Here is a simple example:
+ task which can be used to invoke Forrest from Ant. All targets and
+ properties are imported and can be used in your project build. Here is a
+ simple example:
</p>
<pre class="code">
+
<project name="myproject" default="hello">
<!-- FORREST_HOME must be set as an environment variable -->
<property environment="env"/>
@@ -1563,32 +1622,35 @@
<echo>something here</echo>
</target>
</project>
- </pre>
+
+ </pre>
<div class="warning">
<div class="label">Warning</div>
-<div class="content">There is a bug in the plugin download mechanism in
- Forrest 0.7 that may prevent
- your plugins being installed correctly when calling Forrest from ANT. You
- can work around this bug by either ensuring a version number is
- defined for the plugin in forrest.properties or by manually
- installing the required plugins.
+<div class="content">
+ There is a bug in the plugin download mechanism in Forrest 0.7 that may
+ prevent your plugins being installed correctly when calling Forrest from
+ ANT. You can work around this bug by either ensuring a version number is
+ defined for the plugin in forrest.properties or by manually installing
+ the required plugins.
</div>
</div>
-<p>Because you are using your own version
- of Ant to do Forrest's work, you will need to provide the
- supporting catalog entity resolver:
- '<span class="codefrag">cp forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</span>'
- </p>
-<p>Note: The technique described above requires Ant 1.6+ otherwise
- the <import>
- task will not be available for you to use. Forrest
- bundles the latest version of Ant, so you can invoke your project
- like this: '<span class="codefrag">forrest -f myproject.xml</span>'.
- This will not run the '<span class="codefrag">forrest</span>' command. It will just
- use Forrest's Ant and resolver to execute your buildfile.
+<p>
+ Because you are using your own version of Ant to do Forrest's work, you
+ will need to provide the supporting catalog entity resolver: '<span class="codefrag">cp
+ forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</span>'
+ </p>
+<p>
+ Note: The technique described above requires Ant 1.6+ otherwise the
+ <import> task will not be available for you to use. Forrest
+ bundles the latest version of Ant, so you can invoke your project like
+ this: '<span class="codefrag">forrest -f myproject.xml</span>'. This will not run the
+ '<span class="codefrag">forrest</span>' command. It will just use Forrest's Ant and
+ resolver to execute your buildfile.
</p>
<p>
- Another option is to use the Forrest Antlet from the Krysalis Project's <a href="http://antworks.sourceforge.net/importer/">Antworks Importer</a>.
+ Another option is to use the Forrest Antlet from the Krysalis Project's
+ <a href="http://antworks.sourceforge.net/importer/">Antworks
+ Importer</a>.
</p>
<p>
The <a href="../tools/forrestbot.html">Forrestbot</a> provides workstages
Modified: forrest/site/docs_0_70/your-project.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/your-project.pdf?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
Binary files - no diff available.
Modified: forrest/site/docs_0_80/body-index.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/body-index.html?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
--- forrest/site/docs_0_80/body-index.html (original)
+++ forrest/site/docs_0_80/body-index.html Wed Apr 18 01:36:14 2007
@@ -42,7 +42,7 @@
<p>
The documentation <a href="../linkmap.html">Table of Contents</a> provides a
- useful overview of the main documentation. <a href="../docs_0_80/faq.html#docs">This
+ useful overview of the main documentation. <a href="../docs_0_90/faq.html#docs">This
FAQ</a> explains that there is other documentation at the example forrest
seed site and that each plugin has its own documentation.
</p>