You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2007/04/10 05:48:57 UTC
svn commit: r527010 [4/26] - in /forrest/trunk/site-author/content: ./
skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/
xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/
xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_0...
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-corner-images.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-corner-images.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-corner-images.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-corner-images.xml Mon Apr 9 20:48:52 2007
@@ -16,37 +16,33 @@
limitations under the License.
-->
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "http://forrest.apache.org/dtd/howto-v20.dtd">
-
<howto>
- <header>
- <title>How to modify the color of generated corner images</title>
- <abstract>
- This How-To describes how to modify the corner images that appear in
- the menu and tabs of the skins.
- </abstract>
- <last-modified-content-date date="2004-11-05"/>
- </header>
-
+ <header>
+ <title>How to modify the color of generated corner images</title>
+ <abstract>
+ This How-To describes how to modify the corner images that appear in the
+ menu and tabs of the skins.
+ </abstract>
+ <last-modified-content-date date="2004-11-05"/>
+ </header>
<audience title="Intended Audience">
<p>
- Users who want to change the colors of the corner images in the
- output html documents.
+ Users who want to change the colors of the corner images in the output
+ html documents.
</p>
<p>
- This explanation is also useful for skin developers to understand
- the corner image generation process.
+ This explanation is also useful for skin developers to understand the
+ corner image generation process.
</p>
</audience>
-
<purpose title="Purpose">
<p>
Forrest renders the corner images through
- <a href="http://www.w3.org/TR/SVG/">Scalable Vector Graphics (SVG)</a>.
- It may be necessary to change the color of
- the corner images to be suitable for your own skin colors.
+ <a href="http://www.w3.org/TR/SVG/">Scalable Vector Graphics (SVG)</a>. It
+ may be necessary to change the color of the corner images to be suitable
+ for your own skin colors.
</p>
</purpose>
-
<prerequisites title="Prerequisites">
<ul>
<li>Understand how to use the skinconf.xml file to change the appearance
@@ -56,19 +52,18 @@
(topic "<a href="site:v0.70//your-project/skins">Forrest skins</a>").</li>
</ul>
</prerequisites>
-
<steps title="Steps">
<p>
The procedure outlined below provides an understanding of how corner
- images are named (the contract) and then shows how to define new
- colors for these images by modifying the
+ images are named (the contract) and then shows how to define new colors
+ for these images by modifying the
<code>src/documentation/skinconf.xml</code> of a project.
</p>
<section id="css-files">
<title>Understand how corner images are named (the contract)</title>
<p>
- The corner images are referenced in some .css files of the
- above-named skins; for example, in screen.css of the pelt skin:
+ The corner images are referenced in some .css files of the above-named
+ skins; for example, in screen.css of the pelt skin:
</p>
<source>
/*Example from screen.css of pelt*/
@@ -84,8 +79,8 @@
...
</source>
<p>
- The naming follows a contract which is described below. In general,
- the naming looks like:
+ The naming follows a contract which is described below. In general, the
+ naming looks like:
</p>
<source>
images/{$name}-{$v-orientation}-{$h-orientation}-{$size}-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}
@@ -98,8 +93,8 @@
(<code>-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}</code>)
identifies the coloring of each portion of the image. The input
parameter for the second part comes from the color profile of
- <code>src/documentation/skinconf.xml</code>. The second part is
- easily identifiable through the numbering 1-2-3.
+ <code>src/documentation/skinconf.xml</code>. The second part is easily
+ identifiable through the numbering 1-2-3.
</p>
<p>
Let us get into details:
@@ -108,80 +103,58 @@
<dt><code>images</code></dt>
<dd>
Path to the xslt that creates the corner.
- <br/>
- <code>images/ = {$FORREST_HOME}/main/webapp/skins/common/images/</code>
- </dd>
+ <br/><code>images/ = {$FORREST_HOME}/main/webapp/skins/common/images/</code></dd>
<dt><code>{$name}</code></dt>
<dd>
In the common skin there are two XSLT files ready for use:
<ul>
- <li>
- <code>rc.svg.xslt</code>: handles rounded corners
+ <li><code>rc.svg.xslt</code>: handles rounded corners
</li>
- <li>
- <code>dc.svg.xslt</code>: handles diagonal 45-degree corners
+ <li><code>dc.svg.xslt</code>: handles diagonal 45-degree corners
</li>
- </ul>
- <code>name = [rc|dc]</code>
- <br/>
- <em>e.g.</em> <code>rc</code>
- </dd>
+ </ul><code>name = [rc|dc]</code>
+ <br/><em>e.g.</em><code>rc</code></dd>
<dt><code>{$v-orientation}</code></dt>
<dd>
Vertical orientation of the corner images (top or bottom).
- <br/>
- <code>v-orientation = [t|b]</code>
- <br/>
- <em>e.g.</em> <code>t</code>
- </dd>
+ <br/><code>v-orientation = [t|b]</code>
+ <br/><em>e.g.</em><code>t</code></dd>
<dt><code>{$h-orientation}</code></dt>
<dd>
Horizontal orientation of the corner images (left or right).
- <br/>
- <code>h-orientation = [l|r]</code>
- <br/>
- <em>e.g.</em> <code>r</code>
- </dd>
+ <br/><code>h-orientation = [l|r]</code>
+ <br/><em>e.g.</em><code>r</code></dd>
<dt><code>{$size}</code></dt>
<dd>
Pixels size of the width <strong>and</strong> height of the corner image.
- <br/>
- <code>size=x</code>
- <br/>
- <em>e.g.</em> <code>5</code>
- </dd>
+ <br/><code>size=x</code>
+ <br/><em>e.g.</em><code>5</code></dd>
<dt><code>{$backgroundColor}</code></dt>
<dd>
Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
attribute will be applied).
- <br/>
- <em>e.g.</em> <code>header</code>
- </dd>
+ <br/><em>e.g.</em><code>header</code></dd>
<dt><code>{$strokeColor}</code></dt>
<dd>
Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
attribute will be applied).
- <br/>
- <em>e.g.</em> <code>searchbox</code>
- </dd>
+ <br/><em>e.g.</em><code>searchbox</code></dd>
<dt><code>{$foregroundColor}</code></dt>
<dd>
Any <code><color name=""/></code> element in the <code>skinconf.xml</code> (the <code>value="{$color}"</code>
attribute will be applied).
- <br/>
- <em>e.g.</em> <code>searchbox</code>
- </dd>
+ <br/><em>e.g.</em><code>searchbox</code></dd>
</dl>
</section>
<section id="skinconfig">
<title>Modifying the skinconf.xml of your project</title>
<p>
- modifying the <code>skinconf.xml</code> of your project (by
- default you find it at <code>[project-dir]/src/documentation/</code>).
+ modifying the <code>skinconf.xml</code> of your project (by default you
+ find it at <code>[project-dir]/src/documentation/</code>).
</p>
<p>
- Starting about line 155 you find a <code><colors></code>
- ... <code></colors></code> element with content commented-out:
+ Starting about line 155 you find a <code><colors></code> ...
+ <code></colors></code> element with content commented-out:
</p>
<source>
<colors>
@@ -203,10 +176,10 @@
</colors>
</source>
<p>
- To modify the colors of the corner images, you can either define
- your own <code><color name=.../></code> elements or uncomment
- one of the existing <code><color name=.../></code> elements
- and adjust the color value to your needs.
+ To modify the colors of the corner images, you can either define your
+ own <code><color name=.../></code> elements or uncomment one of
+ the existing <code><color name=.../></code> elements and adjust
+ the color value to your needs.
</p>
<p>
<em>e.g.</em>
@@ -215,8 +188,9 @@
<color name="tab-selected" value="#FF0000"/>
</source>
<p>
- This affects all corner images whose <code>{$backgroundColor}</code>, <code>{$strokeColor}</code> or
- <code>{$foregroundColor}</code> is set to <code>tab-selected</code>.
+ This affects all corner images whose <code>{$backgroundColor}</code>,
+ <code>{$strokeColor}</code> or <code>{$foregroundColor}</code> is set to
+ <code>tab-selected</code>.
<br/>
For example, in <code>screen.css</code> (of the "pelt" skin) you find:
</p>
@@ -229,16 +203,15 @@
</source>
<p>
Now the stroke color (<code>-2tab-selected</code>) and the foreground
- color (<code>-3tab-selected</code>) are set to red (remember: we
- defined <code>#FF0000</code> as the "color" value of
- <code>tab-selected</code>).
+ color (<code>-3tab-selected</code>) are set to red (remember: we defined
+ <code>#FF0000</code> as the "color" value of <code>tab-selected</code>).
</p>
</section>
<section id="css_modify">
<title>Modifying .css files</title>
<p>
- In addition to the modification of <code>skinconf.xml</code>
- you can also modify the respective .css file of your skin.
+ In addition to the modification of <code>skinconf.xml</code> you can
+ also modify the respective .css file of your skin.
</p>
<p>
Here's another example:
@@ -263,14 +236,13 @@
</colors>
</source>
<p>
- Here we have created our own color tags (in the .css file) and
- defined the respective values for them (in <code>skinconf.xml</code>).
- Now you have color images with a red background and a green
- foreground. Horrible, isn't it?
+ Here we have created our own color tags (in the .css file) and defined
+ the respective values for them (in <code>skinconf.xml</code>). Now you
+ have color images with a red background and a green foreground.
+ Horrible, isn't it?
</p>
</section>
</steps>
-
<feedback title="Feedback">
<p>
Please provide feedback about this document via the
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-custom-html-source.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-custom-html-source.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-custom-html-source.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-custom-html-source.xml Mon Apr 9 20:48:52 2007
@@ -24,26 +24,24 @@
</abstract>
<last-modified-content-date date="2005-03-23" />
</header>
-
<audience title="Intended Audience">
<p>
- Users who want to integrate HTML-pages that require custom
- adjustments and everybody who wants to learn more about Forrest's
- pipelines in general.
+ Users who want to integrate HTML-pages that require custom adjustments and
+ everybody who wants to learn more about Forrest's pipelines in general.
</p>
</audience>
-
<purpose title="Purpose">
<p>
- Integrating legacy HTML pages is a common task when migrating
- existing websites to Forrest. This document explains how to implement
- custom processing which is required when Forrest's standard pipeline
- for html does not suffice.
+ Integrating legacy HTML pages is a common task when migrating existing
+ websites to Forrest. This document explains how to implement custom
+ processing which is required when Forrest's standard pipeline for html
+ does not suffice.
</p>
</purpose>
-
<prerequisites title="Prerequisites">
- <p>To follow these instructions you will need:</p>
+ <p>
+ To follow these instructions you will need:
+ </p>
<ol>
<li>
Know how to use a
@@ -70,149 +68,116 @@
</li>
</ol>
</prerequisites>
-
<steps title="Understanding the HTML-Pipeline">
<p>
- The first part of this howto explains the html pipeline, so as to
- provide the background to enable you to add additional processing
- for legacy html documents. If you already know how pipelines work,
- then skip to the section about
- <a href="#custom">Customizing the html pipeline</a>.
+ The first part of this howto explains the html pipeline, so as to provide
+ the background to enable you to add additional processing for legacy html
+ documents. If you already know how pipelines work, then skip to the
+ section about <a href="#custom">Customizing the html pipeline</a>.
</p>
-
<section id="example">
<title>Driven by Example</title>
<p>
- The best way to learn about Forrest pipelines is follow
- the processing of an imaginary request through the forrest
- machinery.
+ The best way to learn about Forrest pipelines is follow the processing
+ of an imaginary request through the forrest machinery.
</p>
<p>
- So let's see what happens, when a client asks Forrest to
- serve the document
+ So let's see what happens, when a client asks Forrest to serve the
+ document
<br />
'http://some.domain.org/mytest/mybad.html'.
</p>
</section>
-
<section id="sitemap">
<title>Finding the Sitemap</title>
-
<p>
- Like all applications based on Apache Cocoon, each request for
- a given document is processed by searching a sitemap for a
- matching processing pipeline. With Forrest, this core sitemap
- is found in the file
+ Like all applications based on Apache Cocoon, each request for a given
+ document is processed by searching a sitemap for a matching processing
+ pipeline. With Forrest, this core sitemap is found in the file
'main/webapp/sitemap.xmap' in Forrest's program directory.
</p>
-
<p class="instruction">
- Open the file 'main/webapp/sitemap.xmap' in Forrest's
- program directory with a text editor of your choice.
+ Open the file 'main/webapp/sitemap.xmap' in Forrest's program directory
+ with a text editor of your choice.
</p>
<note>
- Any simple text editor will suffice, since the XML in
- this file is quite simple in structure and easy to read.
+ Any simple text editor will suffice, since the XML in this file is quite
+ simple in structure and easy to read.
</note>
-
<p>
- To help you to easily follow the next steps, we have added
- comments and anchors to 'sitemap.xmap',
- so that you can quickly jump to all relevant sections
- and read them more easily.
+ To help you to easily follow the next steps, we have added comments and
+ anchors to 'sitemap.xmap', so that you can quickly jump to all relevant
+ sections and read them more easily.
</p>
-
<p class="instruction">
- Follow this link to the
- <a href="sitemap.xmap.html#Start+of+Sitemap">
- start of the Sitemap.
- </a>
+ Follow this link to the <a href="sitemap.xmap.html#Start+of+Sitemap">
+ start of the Sitemap. </a>
</p>
-
<p>
- As the comment explains, this sitemap is the starting point
- for all requests. So even if there are other sitemaps
- (which we will see later on), we always start looking for a
- matching pattern right here.
+ As the comment explains, this sitemap is the starting point for all
+ requests. So even if there are other sitemaps (which we will see later
+ on), we always start looking for a matching pattern right here.
</p>
</section>
-
<section id="pipelines">
<title>Find the Beginning of the Pipelines Section</title>
-
<p>
- Modular as everything else in Cocoon, Forrest's sitemap
- starts with a long list of declarations for all the
- components used later on. We can safely ignore these at
- the moment.
+ Modular as everything else in Cocoon, Forrest's sitemap starts with a
+ long list of declarations for all the components used later on. We can
+ safely ignore these at the moment.
</p>
<p class="instruction">
- So let's skip right to the start of the
- Pipelines-Section. Search for <map:pipelines> or
- follow this link to the
- <a href="sitemap.xmap.html#Start+of+Pipelines">
- beginning of the pipelines-element
- </a>
+ So let's skip right to the start of the Pipelines-Section. Search for
+ <map:pipelines> or follow this link to the
+ <a href="sitemap.xmap.html#Start+of+Pipelines"> beginning of the
+ pipelines-element </a>
</p>
-
<p>
- Within the pipelines-element you will find a long list
- of pipeline-Elements (no trailing 's'), each one of them defining a
+ Within the pipelines-element you will find a long list of
+ pipeline-Elements (no trailing 's'), each one of them defining a
processing pipeline within Forrest.
</p>
-
<p>
- When handling a request, Forrest will check the
- Pipelines from top to bottom until it encounters a
- Pipeline that will take care of our request.
+ When handling a request, Forrest will check the Pipelines from top to
+ bottom until it encounters a Pipeline that will take care of our
+ request.
</p>
</section>
-
<section id="matches">
<title>Looking for a Match</title>
-
<p>
- Like all Cocoon applications, Forrest knows which
- pipeline to use for processing a certain request by
- looking at the entry criteria for each pipeline it comes
- across. These can be a match against a given pattern,
- the test if a certain files exists or one of many other
- possible tests that Cocoon supports.
+ Like all Cocoon applications, Forrest knows which pipeline to use for
+ processing a certain request by looking at the entry criteria for each
+ pipeline it comes across. These can be a match against a given pattern,
+ the test if a certain files exists or one of many other possible tests
+ that Cocoon supports.
</p>
-
<p class="instruction">
- To better know what we are talking about, let's follow
- Forrest down the list to the
- <a href="sitemap.xmap.html#Test+for+First+Pipeline">
- Test for the First Pipeline
- </a>.
+ To better know what we are talking about, let's follow Forrest down the
+ list to the <a href="sitemap.xmap.html#Test+for+First+Pipeline"> Test
+ for the First Pipeline </a>.
</p>
-
<p>
- Here you can see that very specialized matches need to occur
- early in the sitemap. The
- requested file (and pathname) is compared to a pattern
- '*.xlex' that would match if our request ended with
- '.xlex' and had no pathname. Since it doesn't, we don't
- have a match and need to keep looking.
+ Here you can see that very specialized matches need to occur early in
+ the sitemap. The requested file (and pathname) is compared to a pattern
+ '*.xlex' that would match if our request ended with '.xlex' and had no
+ pathname. Since it doesn't, we don't have a match and need to keep
+ looking.
</p>
-
<p class="instruction">
Skip forward until we find the
- <a href="sitemap.xmap.html#First+Match+for+%22**%2F*.html%22">
- First Match for "**/*.html"
- </a>
- (<map:match pattern="**/*.html">).
+ <a href="sitemap.xmap.html#First+Match+for+%22**%2F*.html%22"> First
+ Match for "**/*.html" </a> (<map:match pattern="**/*.html">).
</p>
</section>
-
<section id="html-pipeline">
<title>Processing in the '**/*.html' Pipeline</title>
- <p>
- Let's take a quick look at this pipeline to understand
- what's happening here:
+ <p>
+ Let's take a quick look at this pipeline to understand what's happening
+ here:
</p>
-<source><![CDATA[
+ <source>
+<![CDATA[
<map:match pattern="**/*.html">
<map:aggregate element="site">
<map:part src="cocoon:/skinconf.xml"/>
@@ -225,62 +190,61 @@
<map:parameter name="type" value="site2xhtml"/>
<map:parameter name="path" value="{0}"/>
</map:call>
-</map:match>]]></source>
- <p>
- In the first part of this pipeline, the
- aggregate-element assembles information required to build
- a Forrest page with menu and tabs from different sources.
- Then the call to the skinit-resource picks up the
- aggregated info and generates a page in the
- style of the current skin. That's easy, isn't it?
- </p>
- <p>
- Well, the complex part begins, when we take a closer look at
- the sources of the aggregation.
- </p>
- <source><![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]></source>
- <p>
- This mysterious element is most easily explained as a
- secondary request to the Forrest system.
- </p>
+</map:match>]]>
+ </source>
<p>
- The 'cocoon:'-part is called a pseudo-protocol and tells the
- processor to ask Forrest for the resource named behind
- the colon, process that request and feed the output as input
- back into our pipeline.
- (The 'pseudo' goes back to the fact that unlike
- 'http' or 'ftp', which are real protocols, you can use cocoon:
- only within the cocoon environments as only they will know what to
- do with it.)
+ In the first part of this pipeline, the aggregate-element assembles
+ information required to build a Forrest page with menu and tabs from
+ different sources. Then the call to the skinit-resource picks up the
+ aggregated info and generates a page in the style of the current skin.
+ That's easy, isn't it?
</p>
<p>
- So even though we have already seen the end of our pipeline
- (the skinning), we still don't know, what goes into the skinning and
- where it comes from. To find out, we have to look at the sources
+ Well, the complex part begins, when we take a closer look at the sources
of the aggregation.
</p>
+ <source>
+<![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]>
+ </source>
+ <p>
+ This mysterious element is most easily explained as a secondary request
+ to the Forrest system.
+ </p>
+ <p>
+ The 'cocoon:'-part is called a pseudo-protocol and tells the processor
+ to ask Forrest for the resource named behind the colon, process that
+ request and feed the output as input back into our pipeline. (The
+ 'pseudo' goes back to the fact that unlike 'http' or 'ftp', which are
+ real protocols, you can use cocoon: only within the cocoon environments
+ as only they will know what to do with it.)
+ </p>
+ <p>
+ So even though we have already seen the end of our pipeline (the
+ skinning), we still don't know, what goes into the skinning and where it
+ comes from. To find out, we have to look at the sources of the
+ aggregation.
+ </p>
</section>
-
<section id="protocols">
<title>Following the Pseudo-Protocols</title>
<p>
- To find out what goes into our aggregation, we'll need to look
- at the pipeline that is called by
+ To find out what goes into our aggregation, we'll need to look at the
+ pipeline that is called by
</p>
- <source><![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]></source>
- <p>
- To do that, it's always a good idea to write down what this
- call actually looks like when all the variables are replaced by real
- values.
- A safe way to do that is to look at the matcher to start with,
- build a list of the numbered variables and their meaning in the
- current context and then assemble the actual expression(s) from it.
- </p>
-
- <p>In our example the matcher pattern
- <code>**/*.html</code> is applied to the request-name
- <code>mytest/mybad.html</code>, so we have three variables
- altogether:
+ <source>
+<![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]>
+ </source>
+ <p>
+ To do that, it's always a good idea to write down what this call
+ actually looks like when all the variables are replaced by real values.
+ A safe way to do that is to look at the matcher to start with, build a
+ list of the numbered variables and their meaning in the current context
+ and then assemble the actual expression(s) from it.
+ </p>
+ <p>
+ In our example the matcher pattern <code>**/*.html</code> is applied to
+ the request-name <code>mytest/mybad.html</code>, so we have three
+ variables altogether:
</p>
<table>
<tr>
@@ -299,82 +263,93 @@
<td>the second match</td>
</tr>
</table>
- <p>If we insert that into </p>
- <source><![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]></source>
- <p>we get</p>
- <source><![CDATA[<map:part src="cocoon:/mytest/body-mybad.html"/>]]></source>
<p>
- As you can easily tell, we are suddenly calling for a whole
- new document. Let's see where that takes us:
+ If we insert that into
+ </p>
+ <source>
+<![CDATA[<map:part src="cocoon:/{1}/body-{2}.html"/>]]>
+ </source>
+ <p>
+ we get
+ </p>
+ <source>
+<![CDATA[<map:part src="cocoon:/mytest/body-mybad.html"/>]]>
+ </source>
+ <p>
+ As you can easily tell, we are suddenly calling for a whole new
+ document. Let's see where that takes us:
</p>
</section>
<section id="call">
<title>Second Call for Content</title>
<p>
- Processing of cocoon-calls is not much different from
- normal requests by a client. When you launch a call like
+ Processing of cocoon-calls is not much different from normal requests by
+ a client. When you launch a call like
</p>
- <source><![CDATA[<map:part src="cocoon:/mytest/body-mybad.html"/>]]></source>
+ <source>
+<![CDATA[<map:part src="cocoon:/mytest/body-mybad.html"/>]]>
+ </source>
<p>
- Forrest will once again start searching its main sitemap
- from the beginning and look for a pipeline to match that call.
+ Forrest will once again start searching its main sitemap from the
+ beginning and look for a pipeline to match that call.
</p>
-
<p class="instruction">
- Search for '**body-*.html' from the beginning of the
- sitemap or jump to the
- <a href="sitemap.xmap.html#First+Match+for+%27**body-*.html%27">First Match for '**body-*.html'</a>
- to see where we find our next match.
+ Search for '**body-*.html' from the beginning of the sitemap or jump to
+ the
+ <a href="sitemap.xmap.html#First+Match+for+%27**body-*.html%27">First
+ Match for '**body-*.html'</a> to see where we find our next match.
</p>
</section>
<section id="match-1">
<title>First Match for '**body-*.html'</title>
- <p>
- Our first match is different to the previous ones because
- there is a second condition placed inside the matcher.
- Doing the replacements
- </p>
-<source><![CDATA[
+ <p>
+ Our first match is different to the previous ones because there is a
+ second condition placed inside the matcher. Doing the replacements
+ </p>
+ <source>
+<![CDATA[
<map:select type="exists">
- <map:when test="{properties:content.xdocs}mytests/mybad.ehtml">]]></source>
- <p>
- we quickly discover that there can't be a file of
- that name in the project-directory.
- <br />
- (The variable '{properties:content.xdocs}' is always replaced with
- the name of your project directory that you can change
- in the 'forrest.properties'-file.)
- </p>
- <p>
- So we have a pipeline, but it doesn't do anything.
- In this case Forrest will simply keep looking for
- the next match further down.
- </p>
+ <map:when test="{properties:content.xdocs}mytests/mybad.ehtml">]]>
+ </source>
+ <p>
+ we quickly discover that there can't be a file of that name in the
+ project-directory.
+ <br />
+ (The variable '{properties:content.xdocs}' is always replaced with the
+ name of your project directory that you can change in the
+ 'forrest.properties'-file.)
+ </p>
+ <p>
+ So we have a pipeline, but it doesn't do anything. In this case Forrest
+ will simply keep looking for the next match further down.
+ </p>
</section>
<section id="match-2">
<title>Second Match for '**body-*.html'</title>
<p class="instruction">
- Continue searching downwards for '**body-*.html' in the
- sitemap-file or jump directly to the
- <a href="sitemap.xmap.html#Second+Match+for+%27**body-*.html%27">Second Match for '**body-*.html'</a>.
+ Continue searching downwards for '**body-*.html' in the sitemap-file or
+ jump directly to the
+ <a href="sitemap.xmap.html#Second+Match+for+%27**body-*.html%27">Second
+ Match for '**body-*.html'</a>.
</p>
<p>
- Looking at the pipeline that handles the request, we see that
- the cocoon-protocol is once again invoked
- </p>
- <source><![CDATA[<map:generate src="cocoon:/{1}{2}.xml"/>]]></source>
+ Looking at the pipeline that handles the request, we see that the
+ cocoon-protocol is once again invoked
+ </p>
+ <source>
+<![CDATA[<map:generate src="cocoon:/{1}{2}.xml"/>]]>
+ </source>
<p>
this time as a direct generator of input for our pipeline.
</p>
<p>
- So once again we ask Forrest to process a request for content.
- To know what matcher to look for, let's first expand the variables:
+ So once again we ask Forrest to process a request for content. To know
+ what matcher to look for, let's first expand the variables:
</p>
<p>
- In our example the matcher pattern
- <code>**body-*.html</code> is applied to the request-name
- <code>mytest/body-mybad.html</code>.
- Which means that we have three variables altogether:
+ In our example the matcher pattern <code>**body-*.html</code> is applied
+ to the request-name <code>mytest/body-mybad.html</code>. Which means
+ that we have three variables altogether:
</p>
<table>
<tr>
@@ -396,11 +371,15 @@
<p>
If we insert that into
</p>
- <source><![CDATA[<map:generate src="cocoon:/{1}{2}.xml"/>]]></source>
+ <source>
+<![CDATA[<map:generate src="cocoon:/{1}{2}.xml"/>]]>
+ </source>
<p>
we get
</p>
- <source><![CDATA[<map:generate src="cocoon:/mytests/mybad.xml"/>]]></source>
+ <source>
+<![CDATA[<map:generate src="cocoon:/mytests/mybad.xml"/>]]>
+ </source>
</section>
<section id="match-3">
<title>Third Call for Content</title>
@@ -414,60 +393,57 @@
which is the standard handling for all xml-requests.
</p>
<p>
- Since our request fulfils none of the secondary criteria in
- this pipeline, it falls right through to the map:mount-element
- at the end:
- </p>
- <source><![CDATA[<map:mount uri-prefix="" src="forrest.xmap" check-reload="yes" />]]></source>
+ Since our request fulfils none of the secondary criteria in this
+ pipeline, it falls right through to the map:mount-element at the end:
+ </p>
+ <source>
+<![CDATA[<map:mount uri-prefix="" src="forrest.xmap" check-reload="yes" />]]>
+ </source>
<p>
- which makes Forrest load and process a secondary sitemap,
- the file 'forrest.xmap' in the same directory.
+ which makes Forrest load and process a secondary sitemap, the file
+ 'forrest.xmap' in the same directory.
</p>
<p class="instruction">
- Open the file 'forrest.xmap' and continue the search for a
- matching pattern.
+ Open the file 'forrest.xmap' and continue the search for a matching
+ pattern.
</p>
<p>
- Our search leads us to the
- <a href="forrest.xmap.html#Second+Match+for+%27**.xml%27">
- Second Match for '**.xml'
- </a>,
- a pipeline designed to handle internationalisation if that
- feature is configured. Since it is not, all it does is
- call the file-resolver-resource with the full pathname of
- our file but no extension.
+ Our search leads us to the
+ <a href="forrest.xmap.html#Second+Match+for+%27**.xml%27"> Second Match
+ for '**.xml' </a>, a pipeline designed to handle internationalisation if
+ that feature is configured. Since it is not, all it does is call the
+ file-resolver-resource with the full pathname of our file but no
+ extension.
</p>
-<source><![CDATA[
+ <source>
+<![CDATA[
<map:call resource="file-resolver">
<map:parameter name="uri" value="mytests/mybad"/>
-</map:call>]]></source>
+</map:call>]]>
+ </source>
</section>
<section id="file">
<title>Introducing the File-Resolver</title>
<p class="instruction">
- To find out more about the working of the file-resolver,
- search for the definition of the
+ To find out more about the working of the file-resolver, search for the
+ definition of the
<a href="forrest.xmap.html#Definition+of+File-Resolver-Resource">
- <map:resource name="file-resolver">
- </a>
- higher up in the file.
+ <map:resource name="file-resolver"> </a> higher up in the file.
</p>
<p>
- Here you will find a pipeline that tests for the existence of
- the file with different extensions. '.html' is second in this
- list and leads to the processing steps shown below:
+ Here you will find a pipeline that tests for the existence of the file
+ with different extensions. '.html' is second in this list and leads to
+ the processing steps shown below:
</p>
</section>
-
<section id="process-html">
<title>html-Default Processing</title>
<p>
- The default processing of html-files consists of four
- processing steps:
+ The default processing of html-files consists of four processing steps:
</p>
<ol>
- <li>
- <code><map:generate src="{properties:content.xdocs}{uri}.html" type="html"/></code><br/>
+ <li><code><map:generate src="{properties:content.xdocs}{uri}.html" type="html"/></code>
+ <br/>
Using the html-generator, Forrest reads the html-document
from file and uses JTidy to clean up and convert it to xml
(which is required for all processing in cocoon pipelines).
@@ -476,52 +452,50 @@
elements. We'll deal with those later (see
<a href="site:v0.70//howto/custom-html-source">When to customize</a>).
</li>
- <li>
- <code><map:transform src="{forrest:forrest.stylesheets}/html2document.xsl"/></code><br/>
+ <li><code><map:transform src="{forrest:forrest.stylesheets}/html2document.xsl"/></code>
+ <br/>
Using the standard stylesheet 'html2document.xsl', this XHTML is
transformed into Forrest standard document format.
</li>
- <li>
- <code><map:transform type="idgen"/></code><br/>
+ <li><code><map:transform type="idgen"/></code>
+ <br/>
This step generates IDs required for navigation within the page.
</li>
- <li>
- <code><map:serialize type="xml-document"/></code><br/>
+ <li><code><map:serialize type="xml-document"/></code>
+ <br/>
Finally the document is serialized as XML and returned to the
calling pipeline.
</li>
</ol>
<p>
- As a result, we now hand back the content of the html-document
- in Forrest standard document format to the calling pipeline
+ As a result, we now hand back the content of the html-document in
+ Forrest standard document format to the calling pipeline
</p>
<note>
- To look at the output of this pipeline you can simply
- point you browser to 'http://localhost:8888/mytest/mybad.xml'
- (assuming that you are currently running Forrest on your
- machine and there is an html-page of that name).
+ To look at the output of this pipeline you can simply point you browser
+ to 'http://localhost:8888/mytest/mybad.xml' (assuming that you are
+ currently running Forrest on your machine and there is an html-page of
+ that name).
</note>
</section>
<section id="body">
<title>Returning to the '**body-*.html'-Pipeline</title>
<p>
On returning into the
- <a href="sitemap.xmap.html#Returning+to+the+%27**body-*.html%27+Pipeline">'**body-*.html' pipeline</a>,
- procesing continues with the next components in this pipeline:
+ <a href="sitemap.xmap.html#Returning+to+the+%27**body-*.html%27+Pipeline">'**body-*.html'
+ pipeline</a>, procesing continues with the next components in this
+ pipeline:
</p>
<ul>
- <li>
- <strong>idgen</strong> will generate unique IDs for all elements
+ <li><strong>idgen</strong> will generate unique IDs for all elements
that need to be referenced within a page (mainly headlines).
</li>
- <li>
- <strong>xinclude</strong> would process any xinclude statements
+ <li><strong>xinclude</strong> would process any xinclude statements
in the source.
Since HTML does not support this mechanism, nothing happens
in our example.
</li>
- <li>
- <strong>linkrewriter</strong> adjusts links between pages
+ <li><strong>linkrewriter</strong> adjusts links between pages
so that they will still work in the final Forrest output
directory structure. It also resolves any special Forrest links.
</li>
@@ -535,56 +509,50 @@
</li>
</ul>
<note>
- To look at the output of this pipeline you can simply
- point you browser to 'http://localhost:8888/mytest/body-mybad.html'
- (assuming that you are currently running Forrest on your machine
- and there is an html-page of that name).
+ To look at the output of this pipeline you can simply point you browser
+ to 'http://localhost:8888/mytest/body-mybad.html' (assuming that you are
+ currently running Forrest on your machine and there is an html-page of
+ that name).
</note>
</section>
-
<section id="aggregate">
<title>Returning to the '**/*.html'-Pipeline</title>
<p>
- At the end of this pipeline, processing returns the results into
- the aggregation section of the
- <a href="#html-pipeline">'**/*.html' Pipeline</a>,
- merges it with other data, skins and serializes for presentation
- in the requesting client.
+ At the end of this pipeline, processing returns the results into the
+ aggregation section of the <a href="#html-pipeline">'**/*.html'
+ Pipeline</a>, merges it with other data, skins and serializes for
+ presentation in the requesting client.
</p>
</section>
-
<section id="custom">
<title>Customizing the html pipeline</title>
<p>
In this last part of this document, we will show how to customize the
HTML-pipeline to add your additional steps to the default processing.
</p>
-
<section id="when">
<title>When to customize?</title>
-
<p>
- The html-Pipeline in Forrest is designed to be able to also
- integrate legacy html-Pages in a Forrest project. In doing so,
- it will fix common markup errors and convert html to Forrest's
- intermediate document format.
+ The html-Pipeline in Forrest is designed to be able to also integrate
+ legacy html-Pages in a Forrest project. In doing so, it will fix
+ common markup errors and convert html to Forrest's intermediate
+ document format.
</p>
<p>
Due to the nature of html as presentational markup, there is no way
- this automated process can identify elements in your pages that
- are not required or even unwanted in the Forrest environment.
+ this automated process can identify elements in your pages that are
+ not required or even unwanted in the Forrest environment.
</p>
<p>
A good example are pages from sites where the navigational elements
- (menus, tabs etc.) are embedded in the html of each page.
- Since Forrest can't know what is an unwanted menu and what belongs
- to the page body that you want to keep, you will need to customize
- the process to remove elements that are not needed. If you don't,
- then you will see the original page from your legacy website,
- menu and all, embedded in your new Forrest site.
+ (menus, tabs etc.) are embedded in the html of each page. Since
+ Forrest can't know what is an unwanted menu and what belongs to the
+ page body that you want to keep, you will need to customize the
+ process to remove elements that are not needed. If you don't, then you
+ will see the original page from your legacy website, menu and all,
+ embedded in your new Forrest site.
</p>
</section>
-
<section id="how">
<title>How to customize?</title>
<p>
@@ -594,77 +562,76 @@
</p>
<p>
This project sitemap is located in the file
- 'src/documentation/sitemap.xmap' in your Forrest project directory
- and will be created automatically when you seed a new project.
- At this point it contains only one
+ 'src/documentation/sitemap.xmap' in your Forrest project directory and
+ will be created automatically when you seed a new project. At this
+ point it contains only one
<a href="project_sitemap.xmap.html#Example+pipeline+for+%27**custom.xml%27">
pipeline for handling the '**custom.xml'-pattern</a> as an example.
</p>
<p>
To add your own custom processing, edit the file and add a new
- pipeline to the project sitemap. Since the project sitemap is
- loaded into the main sitemap
- <a href="sitemap.xmap.html#Insertion+Point+for+Project+Sitemap">
- right at the top</a>, your pipeline intercepts practically all
- of Forrest's standard pipelines.
+ pipeline to the project sitemap. Since the project sitemap is loaded
+ into the main sitemap
+ <a href="sitemap.xmap.html#Insertion+Point+for+Project+Sitemap"> right
+ at the top</a>, your pipeline intercepts practically all of Forrest's
+ standard pipelines.
</p>
</section>
-
<section id="what">
<title>What to intercept?</title>
<p>
Where to intercept standard processing is really a matter of your
- choice. A good rule is to replace as little standard handling
- as possible so that future changes in the Forrest architecture are
- less likely to break your application.
+ choice. A good rule is to replace as little standard handling as
+ possible so that future changes in the Forrest architecture are less
+ likely to break your application.
</p>
<p>
- In our case all we need to do is add a transformation that
- removes all the unwanted elements. The best place to do this
- would be right after the generator has converted our document to
- xhtml.
+ In our case all we need to do is add a transformation that removes all
+ the unwanted elements. The best place to do this would be right after
+ the generator has converted our document to xhtml.
</p>
<p>
- However, since we can only replace a complete pipeline,
- we'll create a new pipeline that intercepts **.xml for our pages,
- copy the steps the original processor is doing and add a
- transformation of our own to it.
+ However, since we can only replace a complete pipeline, we'll create a
+ new pipeline that intercepts **.xml for our pages, copy the steps the
+ original processor is doing and add a transformation of our own to it.
</p>
</section>
<section id="intercept">
<title>Intercept pattern</title>
<p>
- Take great care when intercepting very basic pipelines.
- Instead of designing our custom pipeline to match the
- original **.xml pattern, try to narrow your matcher down to
- something that will only match your pages.
+ Take great care when intercepting very basic pipelines. Instead of
+ designing our custom pipeline to match the original **.xml pattern,
+ try to narrow your matcher down to something that will only match your
+ pages.
</p>
<p>
- If all your pages are located in a directory called mytest,
- then use a matcher like '/mytest/*.xml' to avoid highjacking
- the processing for all the other requests.
+ If all your pages are located in a directory called mytest, then use a
+ matcher like '/mytest/*.xml' to avoid highjacking the processing for
+ all the other requests.
</p>
<p class="instruction">
- Add a new pipeline in your project sitemap and set the matcher
- to '/mytest/*.xml'.
+ Add a new pipeline in your project sitemap and set the matcher to
+ '/mytest/*.xml'.
</p>
<p>
The new pipeline should look like this and does nothing so far.
</p>
-<source><![CDATA[
+ <source>
+<![CDATA[
<!--Custom Pipeline for my bad html-pages-->
<map:pipeline>
<map:match pattern="mytest/*.xml">
</map:match>
-</map:pipeline>]]></source>
+</map:pipeline>]]>
+ </source>
<p class="instruction">
- Open the 'forrest.xmap', navigate to the file-resolver-section,
- copy the four lines for handling *.html files and paste them into
- your new pipeline.
+ Open the 'forrest.xmap', navigate to the file-resolver-section, copy
+ the four lines for handling *.html files and paste them into your new
+ pipeline.
</p>
-
-<source><![CDATA[
+ <source>
+<![CDATA[
<!--Custom Pipeline for my bad html-pages-->
<map:pipeline>
<map:match pattern="mytest/*.xml">
@@ -673,24 +640,26 @@
<map:transform type="idgen"/>
<map:serialize type="xml-document"/>
</map:match>
-</map:pipeline>]]></source>
+</map:pipeline>]]>
+ </source>
<p>
Your custom pipeline will now behave exactly like the standard
- html-handler. Now all that is left to be done is creating the
- custom transformation and adding it the pipeline.
+ html-handler. Now all that is left to be done is creating the custom
+ transformation and adding it the pipeline.
</p>
<p class="instruction">
- Design and test a new XSL-Transformation that removes the
- unwanted elements and save it in your project's stylesheet
- directory, usually src/documentation/resources/stylesheets
- (defined in project.stylesheets-dir of forrest.properties),
- which is central storage for all stylesheets in a project.
+ Design and test a new XSL-Transformation that removes the unwanted
+ elements and save it in your project's stylesheet directory, usually
+ src/documentation/resources/stylesheets (defined in
+ project.stylesheets-dir of forrest.properties), which is central
+ storage for all stylesheets in a project.
</p>
<p class="instruction">
Add the new transformation as a new line, straight after the
- generator, and save the changes.
+ generator, and save the changes.
</p>
-<source><![CDATA[
+ <source>
+<![CDATA[
<!--Custom Pipeline for my bad html-pages-->
<map:pipeline>
<map:match pattern="mytest/*.xml">
@@ -700,19 +669,18 @@
<map:transform type="idgen" />
<map:serialize type="xml-document"/>
</map:match>
-</map:pipeline>]]></source>
+</map:pipeline>]]>
+ </source>
<p>
- Done! You have just added your own custom-processing.
- Don't forget to view the pages to verify that it is working
- properly.
- </p>
+ Done! You have just added your own custom-processing. Don't forget to
+ view the pages to verify that it is working properly.
+ </p>
<note>
- Our pipeline does not exactly do what the original pipeline does.
- To make things easier, we omitted the internationalization part
- in our pipeline. So if you need to create multi-language sites,
- make sure that you adjust your pipeline accordingly.
+ Our pipeline does not exactly do what the original pipeline does. To
+ make things easier, we omitted the internationalization part in our
+ pipeline. So if you need to create multi-language sites, make sure
+ that you adjust your pipeline accordingly.
</note>
-
</section>
</section>
</steps>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml Mon Apr 9 20:48:52 2007
@@ -20,63 +20,60 @@
<header>
<title>How to customize Forrest CSS
WYSIWYG-style</title>
- <abstract> This How-To shows how to use Mozilla
- Firebird and the free EditCSS-Plugin to
- customize your Forrest design in a
- WYSIWYG-way.</abstract>
+ <abstract>
+ This How-To shows how to use Mozilla Firebird and the free EditCSS-Plugin
+ to customize your Forrest design in a WYSIWYG-way.
+ </abstract>
<last-modified-content-date date="2004-11-05"/>
</header>
-
<audience title="Intended Audience">
- <p> Users who want to customize the Forrest look
- and feel or simply experiment with changing
- certain CSS-styles settings to see what
- happens.</p>
+ <p>
+ Users who want to customize the Forrest look and feel or simply experiment
+ with changing certain CSS-styles settings to see what happens.
+ </p>
</audience>
<purpose title="Purpose">
- <p> A major part of Forrest's look and feel is
- controlled by a few CSS style sheets. Since
- Forrest allows you to override these settings,
- changing the CSS is a quick and easy
- alternative to creating (and maintaining) a
- whole new skin.</p>
- <p> You'll learn how to use free tools to change
- and experiment with styles in a WYSIWYG way, so
- that you can immediately see what effect
- changing a CSS property will have on the
- look and feel of your Forrest.</p>
-
+ <p>
+ A major part of Forrest's look and feel is controlled by a few CSS style
+ sheets. Since Forrest allows you to override these settings, changing the
+ CSS is a quick and easy alternative to creating (and maintaining) a whole
+ new skin.
+ </p>
+ <p>
+ You'll learn how to use free tools to change and experiment with styles in
+ a WYSIWYG way, so that you can immediately see what effect changing a CSS
+ property will have on the look and feel of your Forrest.
+ </p>
</purpose>
<prerequisites title="Prerequisites">
- <p>To follow these instructions you will need:</p>
+ <p>
+ To follow these instructions you will need:
+ </p>
<ol>
<li>Browser-access to the Forrest-site you want
to experiment with. Starting with a new 'forrest seed' site is
good for your first attempt.
- <note>You can even
- experiment with Forrest's core skins CSS. Please send patches if
- you enhance something.
- </note> </li>
+ <note>
+ You can even experiment with Forrest's core skins CSS. Please send
+ patches if you enhance something.
+ </note></li>
<li>The current version of the free Mozilla
Firefox-Browser installed on your system.
If you don't already use it, you can
download it from <a
- href="http://www.mozilla.org/products/firefox/">http://www.mozilla.org/products/firefox/</a>
- </li>
-
+ href="http://www.mozilla.org/products/firefox/">http://www.mozilla.org/products/firefox/</a></li>
<li>The Firefox-PlugIn EditCSS. It downloads
and installs in just a few seconds from the
Install-Link at <a
- href="http://editcss.mozdev.org/">http://editcss.mozdev.org/</a>
- <note>With standard security settings in
- place, Firefox will pop up a line at the top
- of the window because this site has by
- default no permission to install plugins on
- your computer. Click "Edit Options" and
- then "Allow" to change that, then click on
- the Install-link again. Don't forget to
- close and restart Firebird when the
- installation is finished.</note> </li>
+ href="http://editcss.mozdev.org/">http://editcss.mozdev.org/</a>
+ <note>
+ With standard security settings in place, Firefox will pop up a line
+ at the top of the window because this site has by default no
+ permission to install plugins on your computer. Click "Edit Options"
+ and then "Allow" to change that, then click on the Install-link again.
+ Don't forget to close and restart Firebird when the installation is
+ finished.
+ </note></li>
<li>A basic understanding of CSS and access to
a good CSS-reference. Tutorials and
Reference can be found at <a
@@ -84,55 +81,57 @@
</ol>
</prerequisites>
<steps title="Steps">
-
<section id="openForrest">
<title>Open your Forrest</title>
- <p class="instruction">Start your Firefox
- Browser and open the Forrest you'd like to
- work on/play with.</p>
- <p>The page you have pointed to will show up in
- Firefox's main window.</p>
+ <p class="instruction">
+ Start your Firefox Browser and open the Forrest you'd like to work
+ on/play with.
+ </p>
+ <p>
+ The page you have pointed to will show up in Firefox's main window.
+ </p>
</section>
<section id="OpenEditCSS">
<title>Open the EditCSS-Sidebar</title>
-
- <p class="instruction">Select
- View-Sidebar-EditCSS from Firefox's main
- menu to open the EditCSS sidebar.</p>
- <p>The EditCSS sidebar will show next to the
- main window and load all the styles from
- the main page.</p>
+ <p class="instruction">
+ Select View-Sidebar-EditCSS from Firefox's main menu to open the EditCSS
+ sidebar.
+ </p>
+ <p>
+ The EditCSS sidebar will show next to the main window and load all the
+ styles from the main page.
+ </p>
</section>
<section id="changeCSS">
<title>Change any CSS</title>
- <p class="instruction">Change any style you'd
- like to experiment with or add new settings
- and styles of your choice by simply
- editing the text of the sidebar.</p>
- <p>EditCSS pushes any change you make in the
- sidebar right back into the style-settings
- of the main window, so that effects will
- show right away.</p>
-
- <note>On slow systems or when inserting big
- changes it might be a good idea to paste
- these from the clipboard to avoid a zillion
- updates to the main windows for every
- character you type.</note>
+ <p class="instruction">
+ Change any style you'd like to experiment with or add new settings and
+ styles of your choice by simply editing the text of the sidebar.
+ </p>
+ <p>
+ EditCSS pushes any change you make in the sidebar right back into the
+ style-settings of the main window, so that effects will show right away.
+ </p>
+ <note>
+ On slow systems or when inserting big changes it might be a good idea to
+ paste these from the clipboard to avoid a zillion updates to the main
+ windows for every character you type.
+ </note>
</section>
<section id="saveChanges">
<title>How to save changes?</title>
- <p>Since it takes a few explanations to apply
- the changes to your Forrest, I've made
- this the topic of yet another HowTo called
- "Howto change and extend Forrest-CSS"</p>
+ <p>
+ Since it takes a few explanations to apply the changes to your Forrest,
+ I've made this the topic of yet another HowTo called "Howto change and
+ extend Forrest-CSS"
+ </p>
</section>
</steps>
-
<feedback
title="Feedback and further development of this How-To">
- <p> Please provide feedback about this document via
- the <a href="site:mail-lists">mailing
- lists</a>. </p>
+ <p>
+ Please provide feedback about this document via the
+ <a href="site:mail-lists">mailing lists</a>.
+ </p>
</feedback>
</howto>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml Mon Apr 9 20:48:52 2007
@@ -20,58 +20,56 @@
<howto>
<header>
<title>How to run Forrest from within Maven</title>
-
- <abstract>This How-To describes how to run Forrest from within
- Maven.</abstract>
-
+ <abstract>
+ This How-To describes how to run Forrest from within Maven.
+ </abstract>
<last-modified-content-date date="2004-11-12" />
</header>
-
<audience title="Intended Audience">
- <p>Users who want to run Forrest from within Maven.</p>
+ <p>
+ Users who want to run Forrest from within Maven.
+ </p>
</audience>
-
<purpose title="Purpose">
- <p>One may want to generate their project's documentation and/or website
- using Forrest in lieu of Maven's site plugin.</p>
+ <p>
+ One may want to generate their project's documentation and/or website
+ using Forrest in lieu of Maven's site plugin.
+ </p>
</purpose>
-
<prerequisites title="Prerequisites">
<ul>
<li>Understand how to add goals to <a
href="http://maven.apache.org/reference/user-guide.html#maven_xml">maven.xml</a>.</li>
</ul>
</prerequisites>
-
<steps title="Steps">
- <p>The procedure outlined below describes how to add a goal to your
- project's maven.xml that will invoke Forrest's <code>site</code>
- target.</p>
-
+ <p>
+ The procedure outlined below describes how to add a goal to your project's
+ maven.xml that will invoke Forrest's <code>site</code> target.
+ </p>
<section id="set-maven-home">
<title>Set the FORREST_HOME environment variable</title>
-
- <p>Make sure the FORREST_HOME environment variable points to your
- Forrest home directory (i.e. the directory that contains
- <code>forrest.build.xml</code>) (e.g. C:\opt\apache-forrest-0.7)</p>
+ <p>
+ Make sure the FORREST_HOME environment variable points to your Forrest
+ home directory (i.e. the directory that contains
+ <code>forrest.build.xml</code>) (e.g. C:\opt\apache-forrest-0.7)
+ </p>
</section>
-
<section id="define-ant-environment-prop">
<title>Initialize an Ant environment property at the top of
maven.xml</title>
-
- <p>Paste the following line at the top of your maven.xml:</p>
-
+ <p>
+ Paste the following line at the top of your maven.xml:
+ </p>
<source>
<property environment="env" />
</source>
</section>
-
<section id="add-forrest-goal-to-maven-xml">
<title>Add forrest goal to maven.xml</title>
-
- <p>Paste the following goal into your project's maven.xml:</p>
-
+ <p>
+ Paste the following goal into your project's maven.xml:
+ </p>
<source>
<goal name="forrest" description="runs Forrest">
<property name="forrest.home" location="${env.FORREST_HOME}" />
@@ -91,22 +89,26 @@
</java>
</goal>
</source>
-
- <p>It is necessary to fork a separate java process because Maven 1.0
- embeds Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The
- goal makes use of the copy of Ant 1.6 that is bundled with Forrest, so
- it's not even necessary to have Ant 1.6 installed separately.</p>
+ <p>
+ It is necessary to fork a separate java process because Maven 1.0 embeds
+ Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The goal
+ makes use of the copy of Ant 1.6 that is bundled with Forrest, so it's
+ not even necessary to have Ant 1.6 installed separately.
+ </p>
</section>
-
<section>
<title>Alternative file</title>
-
- <p>Under <code>$FORREST_HOME/tools/targets/maven.xml</code></p>
+ <p>
+ Under <code>$FORREST_HOME/tools/targets/maven.xml</code>
+ </p>
</section>
</steps>
-
<feedback title="Feedback">
- <p>Please provide feedback about this document via the <a
- href="site:mail-lists">mailing lists</a>.<!-- Original author: Ian Springer (ips AT apache DOT org) --></p>
+ <p>
+ Please provide feedback about this document via the
+ <a
+ href="site:mail-lists">mailing lists</a>.
+<!-- Original author: Ian Springer (ips AT apache DOT org) -->
+ </p>
</feedback>
</howto>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml Mon Apr 9 20:48:52 2007
@@ -16,48 +16,47 @@
limitations under the License.
-->
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.2//EN" "http://forrest.apache.org/dtd/howto-v12.dtd">
-
<howto>
- <header>
- <title>How to deploy your site with the forrestbot via a cron job</title>
- <abstract>
- This How-To describes the deployment of a forrest documentation with the help of the forrestbot.
- This deployment task will then be automated via a cron tab.
- </abstract>
- <last-modified-content-date date="2004-07-19"/>
- </header>
-
+ <header>
+ <title>How to deploy your site with the forrestbot via a cron job</title>
+ <abstract>
+ This How-To describes the deployment of a forrest documentation with the
+ help of the forrestbot. This deployment task will then be automated via a
+ cron tab.
+ </abstract>
+ <last-modified-content-date date="2004-07-19"/>
+ </header>
<audience title="Intended Audience">
<p>
- Users who need to deploy a forrest documentation on a regular basis and want to automate this task.
+ Users who need to deploy a forrest documentation on a regular basis and
+ want to automate this task.
</p>
</audience>
-
<purpose title="Purpose">
<p>
- If you are administrate a forrest documentation and have to deploy it on a regular basis
- the process is sometimes quite time consuming. One feature of forrest is the forrestbot.
- This bot can build the documentation and later on deploy it to a server of your choice.
- You will learn how to use this forrestbot and how to mae programmed deployments.
+ If you are administrate a forrest documentation and have to deploy it on a
+ regular basis the process is sometimes quite time consuming. One feature
+ of forrest is the forrestbot. This bot can build the documentation and
+ later on deploy it to a server of your choice. You will learn how to use
+ this forrestbot and how to mae programmed deployments.
</p>
</purpose>
-
<prerequisites title="Prerequisites">
<ul>
<li>Understand how the forrestbot works in following the
<link href="site:forrestbot">Forrestbot</link> document.</li>
</ul>
</prerequisites>
-
<steps title="Steps">
- <section id="sitemap">
- <title>Create your project's main sitemap.xmap</title>
- <p>
- In the <link href="site:forrestbot">Forrestbot</link> document you have seen an example
- of a buildfile for a cvs source. We will now use a local source.
- </p>
- <source>
- <![CDATA[<project name="mysampleproject" default="main" >
+ <section id="sitemap">
+ <title>Create your project's main sitemap.xmap</title>
+ <p>
+ In the <link href="site:forrestbot">Forrestbot</link> document you have
+ seen an example of a buildfile for a cvs source. We will now use a local
+ source.
+ </p>
+ <source>
+<![CDATA[<project name="mysampleproject" default="main" >
<property name="notify.email.host" value="smtp.myhost.com"/>
<property name="notify.email.to" value="me@domain.com"/>
<property name="notify.administrator" value="Your Name <me@domain.com>"/>
@@ -73,12 +72,9 @@
<property environment="env"/>
<import file="${env.FORREST_HOME}/../forrestbot/core/forrestbot.xml"/>
</project> ]]>
- </source>
- </section>
-
-
+ </source>
+ </section>
</steps>
-
<feedback title="Feedback and further development of this How-To">
<p>
Please provide feedback about this document via the
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml Mon Apr 9 20:48:52 2007
@@ -20,161 +20,159 @@
<howto>
<header>
<title>How to write a How-To</title>
-
<version>0.3</version>
-
- <abstract>This How-To describes the steps necessary to write a How-To
- document. Writing documentation is a valuable way to give back to the
- community.</abstract>
-
+ <abstract>
+ This How-To describes the steps necessary to write a How-To document.
+ Writing documentation is a valuable way to give back to the community.
+ </abstract>
<last-modified-content-date date="2005-07-18" />
</header>
-
<audience title="Intended Audience">
- <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>
</audience>
-
<purpose title="Purpose">
- <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 insure 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 insure the effectiveness of your
+ work.
+ </p>
</purpose>
-
<prerequisites title="Prerequisites">
- <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. Check out 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 FAQ. However, we would
rather that you just make a start, as the community can help to
fine-tune the document.</li>
-
<li>Copy this template document "howto-howto.xml" to be modified with
your own content as necessary.</li>
-
<li>An understanding of the How-To document structure. Just use this
template document and you will be safe.
Make sure you run '<code>forrest validate-xdocs</code>' before
contributing your document.</li>
</ul>
-
- <note>See the <a href="site:howto-v13-dtd">DTD documentation</a>
- which explains the document structure.</note>
+ <note>
+ See the <a href="site:howto-v13-dtd">DTD documentation</a> which explains
+ the document structure.
+ </note>
</prerequisites>
-
<steps title="Steps">
- <p>Here is how to proceed.</p>
-
+ <p>
+ Here is how to proceed.
+ </p>
<section id="overview">
<title>Write the Overview</title>
-
- <p>An overview helps potential readers to determine quickly if a
- particular How-To matches their interests or needs. In a few sentences,
- summarize the main points of your How-To. Make sure to include any
- critical definitions which will help readers evaluate the utility of
- your How-To. Consider writing the overview last, after you have
- completed all other sections.</p>
+ <p>
+ An overview helps potential readers to determine quickly if a particular
+ How-To matches their interests or needs. In a few sentences, summarize
+ the main points of your How-To. Make sure to include any critical
+ definitions which will help readers evaluate the utility of your How-To.
+ Consider writing the overview last, after you have completed all other
+ sections.
+ </p>
</section>
-
<section id="audience">
<title>Describe your Intended Audience</title>
-
- <p>If your How-To is targetted at a specific audience, describe it here.
- For example, potential readers will have different levels of skill using
- Forrest. They will also bring different areas of expertise and
- backgrounds to their How-To learning experience. When you clarify your
- target audience up front, you will save all other readers time and
- confusion.</p>
+ <p>
+ If your How-To is targetted at a specific audience, describe it here.
+ For example, potential readers will have different levels of skill using
+ Forrest. They will also bring different areas of expertise and
+ backgrounds to their How-To learning experience. When you clarify your
+ target audience up front, you will save all other readers time and
+ confusion.
+ </p>
</section>
-
<section id="purpose">
<title>State the Purpose</title>
-
- <p>State the purpose of your How-To. Explain how the reader will benefit
- by reading it. Give your reader an incentive or two to continue.</p>
+ <p>
+ State the purpose of your How-To. Explain how the reader will benefit by
+ reading it. Give your reader an incentive or two to continue.
+ </p>
</section>
-
<section id="prerequisites">
<title>List any Prerequisites</title>
-
- <p>Inform your reader about any required knowledge, configuration, or
- resources they may need before stepping through your How-To. Assist them
- in this preparation by linking to other useful resources on the Forrest
- site or the web. Helping your readers to prepare increases the
- likelihood that they will continue reading your How-To.</p>
+ <p>
+ Inform your reader about any required knowledge, configuration, or
+ resources they may need before stepping through your How-To. Assist them
+ in this preparation by linking to other useful resources on the Forrest
+ site or the web. Helping your readers to prepare increases the
+ likelihood that they will continue reading your How-To.
+ </p>
</section>
-
<section id="steps">
<title>Describe the Steps of your How-To</title>
-
- <p>In a precise, step-by-step approach, walk your reader through the
- process. Make sure your reader can reproduce your intended result by
- following your exact steps. Make the learning process efficient by
- supplying sample code snippets or configuration details as
- necessary.</p>
+ <p>
+ In a precise, step-by-step approach, walk your reader through the
+ process. Make sure your reader can reproduce your intended result by
+ following your exact steps. Make the learning process efficient by
+ supplying sample code snippets or configuration details as necessary.
+ </p>
</section>
-
<section id="extension">
<title>Extend the Learning</title>
-
- <p>Provide your reader with a few real-world examples of how the
- techniques or capabilities gained from your How-To could be applied.
- Reward the reader for successfully completing the How-To with a few
- ideas about how it will pay off.</p>
+ <p>
+ Provide your reader with a few real-world examples of how the techniques
+ or capabilities gained from your How-To could be applied. Reward the
+ reader for successfully completing the How-To with a few ideas about how
+ it will pay off.
+ </p>
</section>
-
<section id="summarize">
<title>Summarize the Entire Process</title>
-
- <p>In a few sentences, remind the reader what they have just learned.
- This helps to reinforce the main points of your How-To.</p>
+ <p>
+ In a few sentences, remind the reader what they have just learned. This
+ helps to reinforce the main points of your How-To.
+ </p>
</section>
-
<section id="tips">
<title>Additional Tips or FAQs</title>
-
- <p>In some cases, step-by-step instructions simply aren't enough. Use
- this section to pass on any other tips or frequently asked questions.
- Anticipating the needs of your readers will increase the overall success
- of your writing effort.</p>
+ <p>
+ In some cases, step-by-step instructions simply aren't enough. Use this
+ section to pass on any other tips or frequently asked questions.
+ Anticipating the needs of your readers will increase the overall success
+ of your writing effort.
+ </p>
</section>
-
<section id="references">
<title>References</title>
-
- <p>Remember to acknowledge any third-party resources or individuals who
- contributed to the development of your How-To. Consider providing links
- for those motivated readers who want to learn more.</p>
+ <p>
+ Remember to acknowledge any third-party resources or individuals who
+ contributed to the development of your How-To. Consider providing links
+ for those motivated readers who want to learn more.
+ </p>
</section>
-
<section id="contribute">
<title>Submit via the project issue tracker</title>
-
- <p>Create an attachment for your How-To document, and submit it via the
- project <a href="site:bugs">issue tracker</a>.</p>
+ <p>
+ Create an attachment for your How-To document, and submit it via the
+ project <a href="site:bugs">issue tracker</a>.
+ </p>
</section>
-
<section id="feedback">
<title>Get some feedback</title>
-
- <p>When the committers have added your document then it will be
- available for everyone to to build upon and enhance. Feedback will
- happen via the <a href="site:mail-lists">mailing lists</a>.</p>
+ <p>
+ When the committers have added your document then it will be available
+ for everyone to to build upon and enhance. Feedback will happen via the
+ <a href="site:mail-lists">mailing lists</a>.
+ </p>
</section>
</steps>
-
<extension title="Extension">
- <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>
</extension>
-
<faqs id="faqs">
<title>Frequently Asked Questions</title>
<faqsection id="faq-general">
@@ -182,51 +180,51 @@
<faq id="faq-difference">
<question>What is the difference between a How-To and a
tutorial?</question>
-
<answer>
- <p>The goal of a How-To is to help the reader to accomplish a specific
- task with clear and consise instructions. While tutorials may contain
- How-To-like instructions and content, they also include additional
- background and conceptual content to help teach their readers higher
- order concepts along the way. How-Tos are concerned about filling an
- immediate, short-term need. Tutorials often provide long-term
- knowledge which can be applied across a range of needs.</p>
+ <p>
+ The goal of a How-To is to help the reader to accomplish a specific
+ task with clear and consise instructions. While tutorials may
+ contain How-To-like instructions and content, they also include
+ additional background and conceptual content to help teach their
+ readers higher order concepts along the way. How-Tos are concerned
+ about filling an immediate, short-term need. Tutorials often provide
+ long-term knowledge which can be applied across a range of needs.
+ </p>
</answer>
</faq>
</faqsection>
-
<faqsection id="faq-style">
<title>Style issues</title>
<faq id="spelling">
<question>What spelling convention should I follow?</question>
-
<answer>
- <p>Use whatever spelling convention (American, British, etc.) that is
- most intuitive to you.</p>
+ <p>
+ Use whatever spelling convention (American, British, etc.) that is
+ most intuitive to you.
+ </p>
</answer>
</faq>
</faqsection>
</faqs>
-
<tips title="Tips">
<section id="tip-dtd">
<title>How-To dtd</title>
-
- <p>The document structure is likely to change soon. Please note that
- this HOWTO page is likely to change as well.</p>
+ <p>
+ The document structure is likely to change soon. Please note that this
+ HOWTO page is likely to change as well.
+ </p>
</section>
</tips>
-
<references title="References">
- <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