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 2004/09/07 06:21:36 UTC
svn commit: rev 43447 - forrest/trunk/src/documentation/content/xdocs/docs
Author: crossley
Date: Mon Sep 6 21:21:36 2004
New Revision: 43447
Modified:
forrest/trunk/src/documentation/content/xdocs/docs/your-project.xml
Log:
Start to enhance this doc to demonstrate new method of project sitemaps.
Add warning that it is not yet complete.
Modified: forrest/trunk/src/documentation/content/xdocs/docs/your-project.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/docs/your-project.xml (original)
+++ forrest/trunk/src/documentation/content/xdocs/docs/your-project.xml Mon Sep 6 21:21:36 2004
@@ -596,7 +596,7 @@
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
- <link href="ext:forrest">Forrest website</link> itself just uses the
+ <link href="ext:forrest">Forrest website</link> itself uses the
default sitemap.
</p>
<p>
@@ -605,7 +605,7 @@
processing pipeline to be defined. For example, one can:
</p>
<ul>
- <li>Transform custom XML content types with XSLT stylesheets</li>
+ <li>Transform custom XML content types with XSLT stylesheets.</li>
<li>Generate PNG or JPEG images from
<link href="http://www.w3.org/TR/SVG/">SVG</link> XML files.
(<strong>Note:</strong> Forrest's sitemap now does this natively.)</li>
@@ -613,23 +613,32 @@
(<strong>Note:</strong> See issues.xmap for an example.)</li>
<li>Merge XML sources via aggregation, or make content from large XML
sources available as "virtual" files.
- (<strong>Note:</strong> Forrest's default sitemap defines a whole-site HTML
- and PDF, available as <code>wholesite.html</code> and <code>wholesite.pdf</code>.)</li>
+ (<strong>Note:</strong> Forrest makes extensive use of aggregation
+ in the default sitemaps. It also defines a whole-site HTML
+ and PDF, available as the standard names <code>wholesite.html</code>
+ and <code>wholesite.pdf</code>.)</li>
<li>Read content from exotic sources like
<link href="http://www.rpbourret.com/xml/XMLDBLinks.htm">XML
- databases</link></li>
+ databases</link>.</li>
<li>Integrate any of <link href="ext:cocoon">Cocoon's</link> vast array
of capabilities. The possibilities are best appreciated by
downloading the latest Cocoon distribution and playing with the
samples.</li>
</ul>
<p>
- If your site defines its own sitemap, it must perform all the operations of
- the Forrest default. Simply copy the relevant sitemaps
- that you wish to over-ride, from Forrest sitemaps at
- <code>forrest/src/core/context/*.xmap</code> into your
+ The Forrest sitemaps are at
+ <code>forrest/src/core/context/*.xmap</code>
+ </p>
+
+ <p>
+ You can add pre-processing sitemaps to your project
<code>src/documentation</code> directory (or wherever
- <code>${project.sitemap-dir}</code> points to).
+ <code>${project.sitemap-dir}</code> points to). Any match that
+ is not handled, passes through to be handled by the default Forrest
+ sitemaps - obviously extremely powerful. The capability is described
+ in
+ "<link href="site:project-sitemap">Using project sitemaps</link>"
+ and a worked example is shown in the next section below.
</p>
<p>
The sitemap syntax is described in the
@@ -642,9 +651,16 @@
<section id="adding_new_content_type">
<title>Example: Adding a new content type</title>
<p>
+ Follow this worked example. In a fresh directory do 'forrest seed'
+ then follow the steps described in this section.
+ </p>
+ <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:
+ 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>
<source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
@@ -736,10 +752,16 @@
${project.stylesheets-dir} points).
</p>
<p>
- Now the sitemap needs to be modified to transform our custom xml
- structure into the xdocs structure. We need to register our new
+ Now we will create a project sitemap to control the
+ transformation of our custom xml
+ structure into the Forrest intermediate xdocs structure.
+ We need to register our new
DTD and associate a transformation with it.
</p>
+<warning>
+This section of the document is currently being enhanced to reflect the
+new "<link href="site:project-sitemap">Using project sitemaps</link>" method.
+</warning>
<note>
The <link href="site:sitemap-ref">Sitemap
Reference</link> provides details on how the sitemap works, and
@@ -832,40 +854,39 @@
<title>Forrest skins</title>
<p>
As Forrest separates content from presentation, we can plug in different
- "skins" to instantly change a site's look & feel. Forrest provides one
- primary skin, <code>forrest-site</code>, and a handful of others in various
+ "skins" to instantly change a site's look and feel. Forrest provides one
+ primary skin, <code>pelt</code>, and some others in various
states of development.
</p>
<p>
To change the skin, edit the <code>forrest.properties</code> file, and
change the following entry to the name of the new skin.
</p>
- <source>project.skin=forrest-site</source>
+ <source>project.skin=my-fancy-skin</source>
<!--
<note>
The mechanism for defining which skin to use will change in the future from
Ant @token@ values to Cocoon input module values.
</note>
-->
+ <note>
+ Forrest supplies a collection of
+ <link href="site:skins">default skins</link> 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.
+ </note>
<section id="new_skin">
<title>Defining a new skin</title>
<p>
- Projects can define their own skin, in the
+ Projects can define their own skin in the
<code>src/documentation/skins</code> directory (or wherever
<code>${project.skins-dir}</code> 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
- <code>forrest/src/core/context/skins/tigris-style</code>
+ <code>forrest/src/core/context/skins/pelt</code>
to your project area at
- <code>src/documentation/skins/myskin</code> and add
- <code>project.skin=myskin</code> to forrest.properties
- </p>
- <p>
- In addition, when using a project-specific skin it is a good idea to
- also use a project-specific sitemap. This is to protect your skin
- from changes in the Forrest default sitemap. While the sitemap-skin
- contract (expressed as XSLT parameters) is now fairly stable, this
- should not be relied on.
+ <code>src/documentation/skins/my-fancy-skin</code> and add
+ <code>project.skin=my-fancy-skin</code> to forrest.properties
</p>
<p>
The two most interesting XSLT stylesheets involved are:
@@ -898,7 +919,7 @@
<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 (see <code>forrest/src/core/context/skins/common</code>).
+ directory (from <code>forrest/src/core/context/skins/common</code>).
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>