Bommels05/commons-xml
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add building of resolver docs to draft website build with Forrest.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@226027 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
crossley 2002-12-20 05:46:47 +00:00
parent 0d841981e6
commit 6dedce922b
10 changed files with 1822 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
build.xml
View File

@ -1,4 +1,7 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<!DOCTYPE project [
<!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
]>
<!-- <!--
Simplistic meta-build file to call various other xml-commons build files. Simplistic meta-build file to call various other xml-commons build files.
Currently merely uses <ant> to build all subprojects, then Currently merely uses <ant> to build all subprojects, then
@ -99,4 +102,5 @@ just creates a distribution out of all of them.
</ant> </ant>
</target> </target>
&forrest-targets;
</project> </project>

174
forrest-targets.ent Normal file
View File

@ -0,0 +1,174 @@
<!--
This build.xml snippet contains Forrest targets for Ant 1.5+. It checks that
the user has set ${forrest.home}, either in one of:
build.properties
project.properties
ant.properties
.ant.properties
or with the FORREST_HOME environment variable, and prints an informative error
message if not found.
Usage:
1) Copy this file to somewhere in your project.
2) Add the following to the top of your project's Ant build.xml script
(adjusting the path):
<!DOCTYPE project [
<!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
]>
3) Before the closing '</project>' in your build.xml, add this:
&forrest-targets;
This is like expanding a macro: it pulls in the contents of this file.
A minimal build.xml would thus be:
<!DOCTYPE project [
<!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
]>
<project default="site">
&forrest-targets;
</project>
-->
<target name="site" depends="forrest.init" description="Generates static HTML documentation">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="site"/>
</target>
<target name="webapp" depends="forrest.init" description="Generates an unpackaged webapp of the website">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="webapp"/>
</target>
<target name="war" depends="forrest.init" description="Generates a .war file containing the website">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="war"/>
</target>
<target name="validate" depends="forrest.init" description="Validates XML documentation files">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="validate"/>
</target>
<target name="forrest.init" depends="forrest.sethome, forrest.home.defined"/>
<target name="forrest.sethome" depends="forrest.loadenv,
forrest.checkenv, forrest.checkhome, forrest.check-build.properties,
forrest.check-project.properties, forrest.check-ant.properties,
forrest.check-.ant.properties"/>
<target name="forrest.loadenv" unless="forrest.home.present">
<property environment="env"/>
<echo level="verbose">Forrest: Got ${env.FORREST_HOME}</echo>
</target>
<target name="forrest.checkenv" if="env.FORREST_HOME">
<echo level="verbose">Found $FORREST_HOME..</echo>
<property name="forrest.home" location="${env.FORREST_HOME}"/>
<echo level="verbose">forrest.home set to ${forrest.home}</echo>
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
</target>
<target name="forrest.checkhome">
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
<available file="build.properties" type="file" property="build.properties.present"/>
<available file="project.properties" type="file" property="project.properties.present"/>
<available file="ant.properties" type="file" property="ant.properties.present"/>
<available file=".ant.properties" type="file" property=".ant.properties.present"/>
</target>
<!-- No we can't extract the commonalities below into an antcall'ed target,
because it wouldn't be able to set forrest.home -->
<target name="forrest.check-build.properties" unless="forrest.home.present"
if="build.properties.present">
<echo level="verbose">Forrest: Checking build.properties..</echo>
<loadproperties srcfile="build.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
</target>
<target name="forrest.check-project.properties" unless="forrest.home.present"
if="project.properties.present">
<echo level="verbose">Forrest: Checking project.properties..</echo>
<loadproperties srcfile="project.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
</target>
<target name="forrest.check-ant.properties" unless="forrest.home.present"
if="ant.properties.present">
<echo level="verbose">Forrest: Checking ant.properties..</echo>
<loadproperties srcfile="ant.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
</target>
<target name="forrest.check-.ant.properties" unless="forrest.home.present"
if=".ant.properties.present">
<echo level="verbose">Forrest: Checking .ant.properties..</echo>
<loadproperties srcfile=".ant.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir" property="forrest.home.present"/>
</target>
<target name="forrest.home.defined" depends="forrest.sethome" unless="forrest.home.present">
<property name="path" value="${user.home}/xml-forrest/build/dist/shbat"/>
<pathconvert targetos="windows" property="winpath">
<path>
<pathelement location="${path}"/>
</path>
</pathconvert>
<pathconvert targetos="unix" property="unixpath">
<path>
<pathelement
location="${path}"/>
</path>
</pathconvert>
<echo>
----------------------------------------------
To run this target, you need Forrest installed.
Please do the following:
export CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic
cvs checkout xml-forrest
cd xml-forrest
build (Windows)
./build.sh (Unix)
Then either:
- Set FORREST_HOME as the Forrest build instructions describe
- Create a build.properties, with the forrest.home property pointing to
the forrest shbat directory, eg:
forrest.home=${winpath} (Windows)
forrest.home=${unixpath} (Unix)
(adjusting the path according to where your xml-forrest is)
----------------------------------------------
</echo>
<fail message="Need to define $${forrest.home}"/>
</target>

2
forrest.properties
View File

@ -12,6 +12,7 @@
#project.skin=forrest-site #project.skin=forrest-site
#project.skin=avalon-tigris #project.skin=avalon-tigris
#project.debuglevel=ERROR
############## ##############
# layout properties # layout properties
@ -40,6 +41,7 @@
# A local catalog to supplement the default Forrest catalog # A local catalog to supplement the default Forrest catalog
#project.catalog=${project.schema-dir}/catalog #project.catalog=${project.schema-dir}/catalog
project.catalog=/usr/share/sgml/docbook/xmlcatalog
# The verbosity level for the entity resolver (1..10) # The verbosity level for the entity resolver (1..10)
#forrest.catalog.verbosity=1 #forrest.catalog.verbosity=1

7
java/docs/README.txt Normal file
View File

@ -0,0 +1,7 @@
2002-12-20
Until we decide the structure and handling of documents by Forrest
these documents are temporarily at
xml-commons/src/documentation/content/xdocs/components
Please keep in sync.

910
src/documentation/content/xdocs/components/resolver-article.xml Normal file
View File

@ -0,0 +1,910 @@
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>
<articleinfo>
<title>XML Entity and URI Resolvers</title>
<subtitle>Version 1.3</subtitle>
<pubdate>13 Nov 2002</pubdate>
<releaseinfo role="meta">$Id$
</releaseinfo>
<!--
<revhistory>
<revision>
<revnumber>1.3</revnumber>
<date>13 Nov 2002</date>
<authorinitials>ndw</authorinitials>
<revremark>New notes.
</revremark>
</revision>
<revision>
<revision>
<revnumber>1.2</revnumber>
<date>14 Jun 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Updated for the move to Apache. Added to the xml-commons project.
</revremark>
</revision>
<revision>
<revnumber>1.1</revnumber>
<date>05 Nov 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Updated with a few bug fixes, support for system properties, and a new
source code license.</revremark>
</revision>
<revision>
<revnumber>0.5</revnumber>
<date>01 Aug 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Updated to reflect more changes to the ER draft.</revremark>
</revision>
<revision>
<revnumber>0.4</revnumber>
<date>16 Jul 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Updated to reflect more changes to the ER draft.</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>12 Jun 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Updated to reflect recent changes to the ER draft.</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>27 Apr 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>First public draft.</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>20 Feb 2001</date>
<authorinitials>ndw</authorinitials>
<revremark>Initial draft.</revremark>
</revision>
</revhistory>
-->
<author><firstname>Norman</firstname><surname>Walsh</surname>
<affiliation>
<jobtitle>Staff Engineer</jobtitle>
<orgname>Sun Microsystems, XML Technology Center</orgname>
</affiliation>
<authorblurb>
<para>Sun Microsystems supports Norm's active participation in a
number of standards efforts worldwide, including the Technical
Architecture Group, XML Core, and XSL Working Groups of the World Wide
Web Consortium, the OASIS RELAX NG Committee,
the Entity Resolution Committee, for which he is the editor, and
the DocBook Technical Committee, which he chairs.</para>
</authorblurb>
</author>
<copyright>
<year>2001</year><year>2002</year>
<holder>Sun Microsystems, Inc.</holder>
</copyright>
<copyright><year>2000</year><holder>Arbortext, Inc.</holder></copyright>
</articleinfo>
<section><title>Finding Resources on the Net</title>
<para>It's very common for web resources to be related to other
resources: documents rely on DTDs and schemas, schemas are derived from
other schemas, stylesheets are often customizations of other
stylesheets, documents refer to the schemas and stylesheets with which
the expect to be processed, etc. These relationships are expressed
using URIs, most often URLs.</para>
<para>Relying on URLs to directly identify resources to be retrieved
often causes problems for end users:</para>
<orderedlist>
<listitem>
<para>If they're absolute URLs, they only work when you can reach
them<footnote><para>It is technically possible to use a proxy
to transparently cache remote resources, thus making the cached resources
available even when the real hosts are unreachable. In practice, this
requires more technical skill (and system administration access) than
many users have available. And I don't know of any such proxies that
can be configured to provide preferential caching to the specific resources
that are needed. Without such preferential treatment, its difficult to
be sure that the resources you need are actually in the cache.</para>
</footnote>. Relying on remote resources makes XML processing susceptible
to both planned and unplanned network downtime.
</para>
<para>The URL
<quote>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</quote>
isn't very useful if I'm on an airplane at 35,000 feet.</para>
</listitem>
<listitem>
<para>If they're relative URLs, they're only useful in the context where
the were initially created.
</para>
<para>The URL <quote>../../xml/dtd/docbookx.xml</quote> isn't useful
<emphasis>anywhere</emphasis> on my system. Neither, for that matter,
is <quote>/export/home/fred/docbook412/docbookx.xml</quote>.</para>
</listitem>
</orderedlist>
<para>One way to avoid these problems is to use an entity resolver
(a standard part of SAX) or a URI Resolver (a standard part of JAXP).
A resolver can examine the URIs of the resources being requested and
determine how best to satisfy those requests.</para>
<para>The best way to make this function in an interoperable way is to
define a standard format for mapping system identifiers and URIs. The
<ulink url="http://www.oasis-open.org/committees/entity/">OASIS Entity
Resolution Technical Committee</ulink> is defining an XML
representation for just such a mapping. These <quote>catalog files</quote>
can be used to map public and system identifiers and other URIs to
local files (or just other URIs).</para>
<section><title>Resolver Classes Version 1.1</title>
<para>The <ulink url="resolver-1.1.zip" role="linktable" xreflabel="Resolver
Classes">Resolver classes</ulink> that are described
in this article greatly simplify the task of using Catalog files
to perform entity resolution. Many users will want to simply use
these classes directly <quote>out of the box</quote> with their applications
(such as Xalan and Saxon), but developers may also be interested in
the
<ulink url="apidocs/index.html" role="linktable" xreflabel="JavaDoc API Documentation">JavaDoc
API Documentation</ulink>.
</para>
<section><title>Changes from Version 1.0</title>
<para>The most important change in this release is the availability of
both source and binary forms under a <ulink
url="copyright.html">generous license agreement</ulink>.</para>
<para>Other than that, there have been a number of minor bug fixes and the introduction
of system properties in addition to the <filename>CatalogManager.properties</filename>
file to <link linkend="ctrlresolver">control the resolver</link>.</para>
</section>
</section>
</section>
<section>
<title>What's Wrong with System Identifiers?</title>
<para>The problems associated with system identifiers (and URIs in general)
arise in several ways:</para>
<orderedlist>
<listitem><para>I have an XML document that I want to publish on the web or
include in the distribution of some piece of software. On my system, I keep
the doctype of the document in some local directory, so my doctype declaration
reads:</para>
<programlisting>&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"file:///n:/share/doctypes/docbook/xml/docbookx.dtd"></programlisting>
<para>As soon as I distribute this document, I immediately begin getting error
reports from customers who can't read the document because they don't have
DocBook installed at the location identified by the URI in my document.</para>
</listitem>
<listitem><para>Or I remember to change the URI before I publish the document:</para>
<programlisting>&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"></programlisting>
<para>And the next time I try to edit the document, <emphasis>I get errors</emphasis>
because I happen to be working on my laptop on a plane somewhere and can't
get to the net.</para>
</listitem>
<listitem><para>Just as often, I get tripped up this way: I'm working collaboratively
with a colleague. She's created initial drafts of some documents that I'm
supposed to review and edit. So I grab them and find that I can't open or
publish them because I don't have the same network connections she has or
I don't have my applications installed in the same place. And if I change the system
identifiers so they work on my system, she has the same problems when I send
them back to her.</para>
</listitem>
<listitem>
<para>These problems aren't limited to editing applications. If I write
a special stylesheet for formatting our collaborative document, it will
include some reference to the <quote>main</quote> stylesheet:</para>
<programlisting><![CDATA[<xsl:import href="/path/to/real/stylesheet.xsl"/>]]>
</programlisting>
<para>But this won't work on my colleague's machine because she has
the main stylesheet installed somewhere else.</para>
</listitem>
</orderedlist>
<para>Public identifiers offer an effective solution to this problem,
at least for documents. They provide global, unique names for entities
independent of their storage location. Unfortunately, public
identifiers aren't used very often because many users find that they
cannot rely on applications resolving them in an interoperable
manner.</para>
<para>For XSLT, XML Schemas, and other applications that rely on URIs
without providing a mechanism for associating public identifiers with
them, the situation is a little more irksome, but it can still be
addressed using a URI Resolver.</para>
</section>
<section>
<title>Naming Resources</title>
<para>In some contexts, it's more useful to refer to a resource by
name than by address. If I want the version 3.1 of the DocBook DTD,
or the 1911 edition of Webster's dictionary, or <citetitle>The
Declaration of Independence</citetitle>, that's what I want,
irrespective of its location on the net (or even if it's available on
the net). While it is possible to view a URL as an address, I don't
think that's the natural interpretation.</para>
<para>There are currently two ways that I might reasonably assign an
address-independent name to an object: public identifiers or <ulink
url="http://www.ietf.org/rfc/rfc2141.txt">Uniform Resource
Names</ulink> (URNs)<footnote><para>URIs that rely on the domain name
system to identify objects (in other words, all URLs) are addresses,
not names, even though the domain name provides a level of indirection
and the illusion of a stable name.</para>
</footnote>.</para>
<section>
<title>Public Identifiers</title>
<para>Public identifiers are part of <ulink url="http://www.w3.org/TR/REC-xml">XML
1.0</ulink>. They can occur in any form of external entity declaration. They
allow you to give a globally unique name to any entity. For example, the XML
version of DocBook V4.1.2 is identified with the following public identifier:</para>
<programlisting>-//OASIS//DTD DocBook XML V4.1.2//EN</programlisting>
<para>You'll see this identifier in the two doctype declarations I used earlier.
This identifier gives no indication of where the resource (the DTD) may be
found, but it does uniquely name the resource. That public identifier, now
and forever refers to the XML version of DocBook V4.1.2.</para>
</section>
<section>
<title>Uniform Resource Names</title>
<para>URNs are a form of URI. Like public identifiers, they give a location-neutral,
globally unique name to an entity. For example, OASIS might choose to identify
the XML version of DocBook V4.1.2 with the following URN:</para>
<programlisting>urn:oasis:names:specification:docbook:dtd:xml:4.1.2</programlisting>
<para>Like a public identifier, a URN can now and forever refer to a specific
entity in a location-independent manner.</para>
<section><title>The publicid URN Namespace</title>
<para>Public identifiers don't fit very well into the web architecture
(they are not, for example, always valid URIs). This problem can be
addressed by the <literal>publicid</literal> URN namespace defined by
<ulink url="http://www.ietf.org/rfc/rfc3151.txt">RFC 3151</ulink>.</para>
<para>This namespace allows public identifiers to be easily
represented as URNs. The OASIS XML Catalog specification accords
special status to URNs of this form so that catalog resolution occurs
in the expected way.</para>
</section>
</section>
</section>
<section>
<title>Resolving Names</title>
<para>Having extolled the virtues of location-independent names, it must be
said that a name isn't very useful if you can't find the thing it refers to.
In order to do that, you must have a name resolution mechanism that allows
you to determine what resource is referred to by a given name.</para>
<para>One important feature of this mechanism is that it can allow resources
to be distributed, so you don't have to go to <ulink url="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</ulink
> to get the XML version of DocBook V4.1.2, if you have a local copy.</para>
<para>There are a few possible resolution mechanisms:</para>
<itemizedlist>
<listitem><para>The application just <quote>knows</quote>. Sure, it sounds
a little silly, but this is currently the mechanism being used for namespaces.
Applications know what the semantics of namespaced elements are because they
recognize the namespace URI.</para>
</listitem>
<listitem><para>OASIS Catalog files provide a mechanism for mapping public
and system identifiers, allowing resolution to both local and distributed
resources. This is the resolution scheme we're going to consider for the balance
of this column.</para>
</listitem>
<listitem><para>Many other mechanisms are possible. There are already a few
for URNs, including at least one built on top of DNS, but they aren't widely
deployed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Catalog Files</title>
<para>Catalog files are straightforward text files that describe a mapping
from names to addresses. Here's a simple one:</para>
<example><title>An Example Catalog File</title>
<programlisting><![CDATA[<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<public publicId="-//OASIS//DTD XML DocBook V4.1.2//EN"
uri="docbook/xml/docbookx.dtd"/>
<system systemId="urn:x-oasis:docbook-xml-v4.1.2"
uri="docbook/xml/docbookx.dtd"/>
<delegatePublic publicIdStartString="-//Example//"
catalog="http://www.example.com/catalog"/>
</catalog>]]></programlisting>
</example>
<para>This file maps both the public identifier and the URN I mentioned earlier
to a local copy of DocBook on my system. If the doctype declaration uses the
public identifier for DocBook, <emphasis>I'll get DocBook</emphasis> regardless
of the (possibly bogus) system identifier! Likewise, my local copy of DocBook
will be used if the system identifier contains the DocBook URN.</para>
<para>The delegate entry instructs the resolver to use the catalog <quote><filename>http://www.example.com/catalog</filename></quote>
for any public identifier that begins with <quote>-//Example//</quote>.
The advantage of delegate in this case is that I don't have to parse that
catalog file unless I encounter a public identifier that I reasonably expect
to find there.</para>
</section>
<section>
<title>Understanding Catalog Files</title>
<para>The OASIS <ulink
url="http://www.oasis-open.org/committees/entity/">Entity Resolution
Technical Committee</ulink> is actively defining the next generation
XML-based catalog file format. When this work is finished, it is
expected to become the official XML Catalog format. In the meantime,
the existing OASIS <ulink
url="http://www.oasis-open.org/html/a401.htm">Technical Resolution
TR9401</ulink> format is the standard.</para>
<section id="xmlcatalogs"><title>OASIS XML Catalogs</title>
<para>OASIS XML Catalogs are being defined by the <ulink
url="http://www.oasis-open.org/committees/entity/">Entity Resolution
Technical Committee</ulink>. This article describes the 01 Aug 2001
draft. Note that this draft is labelled to reflect that it is
<quote>not an official committee work product and may not reflect the
consensus opinion of the committee.</quote></para>
<para>The document element for OASIS XML Catalogs is
<sgmltag>catalog</sgmltag>. The official namespace name for OASIS XML
Catalogs is
<quote><literal>urn:oasis:names:tc:entity:xmlns:xml:catalog</literal></quote>.</para>
<para>There are eight elements that can occur in an XML Catalog:
<sgmltag>group</sgmltag>,
<sgmltag>public</sgmltag>,
<sgmltag>system</sgmltag>,
<sgmltag>uri</sgmltag>,
<sgmltag>delegatePublic</sgmltag>,
<sgmltag>delegateSystem</sgmltag>,
<sgmltag>delegateURI</sgmltag>, and
<sgmltag>nextCatalog</sgmltag>:</para>
<variablelist>
<varlistentry id="catalog"><term><literal>&lt;catalog <replaceable>prefer="public|system"</replaceable> <replaceable>xml:base="uri-reference"</replaceable>&gt;</literal></term>
<listitem><para>The <sgmltag>catalog</sgmltag> element is the root of
an XML Catalog.</para>
<para>The <sgmltag class="attribute">prefer</sgmltag> setting
determines whether or not public identifiers specified in the catalog
are to be used in favor of system identifiers supplied in the
document. Suppose you have an entity in your document for which both a
public identifier and a system identifier has been specified, and the
catalog only contains a mapping for the public identifier (e.g., a
matching <sgmltag>public</sgmltag> catalog entry). If the current
value of <sgmltag class="attribute">prefer</sgmltag> is
<quote>public</quote>, the URI supplied in the matching
<sgmltag>public</sgmltag> catalog entry will be used. If it is
<quote>system</quote>, the system identifier in the document will be
used. (If the catalog contained a matching <sgmltag>system</sgmltag>
catalog entry giving a mapping for the system identifier, that mapping
would have been used, the public identifier would never have been
considered, and the setting of override would have been
irrelevant.)</para>
<para>Generally, the purpose of catalogs is to
override the system identifiers in XML documents, so
<sgmltag class="attribute">prefer</sgmltag> should
usually be <quote>public</quote> in your catalogs.</para>
<para>The <sgmltag class="attribute">xml:base</sgmltag> URI is used to
resolve relative URIs in the catalog as described in the
<ulink url="http://www.w3.org/TR/xmlbase">XML Base</ulink> specification.
</para>
</listitem>
</varlistentry>
<varlistentry id="group"><term><literal>&lt;group <replaceable>prefer="public|system"</replaceable> <replaceable>xml:base="uri-reference"</replaceable>&gt;</literal></term>
<listitem><para>The <sgmltag>group</sgmltag> element serves merely as
a wrapper around one or more other entries for the purpose of
establishing the preference and base URI settings for those
entries.</para>
</listitem>
</varlistentry>
<varlistentry id="public"><term><literal>&lt;public publicId="<replaceable>pubid</replaceable>" uri="<replaceable>systemuri</replaceable>"/&gt;</literal></term>
<listitem>
<para>Maps the public identifier <replaceable>pubid</replaceable> to the
system identifier <replaceable>systemuri</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry id="system"><term><literal>&lt;system systemId="<replaceable>sysid</replaceable>" uri="<replaceable>systemuri</replaceable>"/&gt;</literal></term>
<listitem>
<para>Maps the system identifier <replaceable>sysid</replaceable> to the
alternate system identifier <replaceable>systemuri</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry id="uri"><term><literal>&lt;uri name="<replaceable>uri</replaceable>" uri="<replaceable>alternateuri</replaceable>"/&gt;</literal></term>
<listitem>
<para>The <sgmltag>uri</sgmltag> entry maps a
<replaceable>uri</replaceable> to an
<replaceable>alternateuri</replaceable>. This mapping, as might be performed
by a JAXP URIResolver, for example, is independent of system and public
identifier resolution.</para>
</listitem>
</varlistentry>
<varlistentry id="delegate">
<term><literal>&lt;delegatePublic publicIdStartString="<replaceable>pubid-prefix</replaceable>" catalog="<replaceable>cataloguri</replaceable>"/&gt;</literal></term>
<term><literal>&lt;delegateSystem systemIdStartString="<replaceable>sysid-prefix</replaceable>" catalog="<replaceable>cataloguri</replaceable>"/&gt;</literal></term>
<term><literal>&lt;delegateURI uriStartString="<replaceable>uri-prefix</replaceable>" catalog="<replaceable>cataloguri</replaceable>"/&gt;</literal></term>
<listitem>
<para>The delegate entries specify that identifiers beginning with the
matching prefix should be resolved using the catalog specified by the
<replaceable>cataloguri</replaceable>. If multiple delegate entries
of the same kind match, they will each be searched, starting with the
longest prefix and continuing with the next longest to the
shortest.</para>
<para>The delegate entries differs from the
<sgmltag>nextCatalog</sgmltag> entry in the following way: alternate
catalogs referenced with a <sgmltag>nextCatalog</sgmltag> entry are parsed
and included in the current catalog. Delegated catalogs are only
considered, and consequently only loaded and parsed, if
necessary. Delegated catalogs are also used <emphasis>instead
of</emphasis> the current catalog, not as part of the current
catalog.</para>
</listitem>
</varlistentry>
<varlistentry id="rewrite"><term><literal>&lt;rewriteSystem systemIdStartString="<replaceable>sysid-prefix</replaceable>" rewritePrefix="<replaceable>new-prefix</replaceable>"/&gt;</literal></term>
<term><literal>&lt;rewriteURI uriStartString="<replaceable>uri-prefix</replaceable>" rewritePrefix="<replaceable>new-prefix</replaceable>"/&gt;</literal></term>
<listitem>
<para>Supports generalized rewriting of system identifiers and URIs. This
allows all of the URI references to a particular document (which might include
many different fragment identifiers) to be remapped to a different resource).
</para>
</listitem>
</varlistentry>
<varlistentry id="nextCatalog"><term><literal>&lt;nextCatalog catalog="<replaceable>cataloguri</replaceable>"/&gt;</literal></term>
<listitem>
<para>Adds the catalog file specified by the <replaceable>cataloguri</replaceable>
to the end of the current catalog. This allows one catalog to refer to another.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="tr9401catalogs"><title>OASIS TR9401 Catalogs</title>
<para>These catalogs are officially defined
by <ulink url="http://www.oasis-open.org/html/a401.htm">OASIS
Technical Resolution TR9401</ulink>.
</para>
<para>A Catalog is a text file that contains a sequence of entries. Of the
13 types of entries that are possible, only six are commonly applicable
in XML systems: BASE, CATALOG, OVERRIDE, DELEGATE, PUBLIC, and SYSTEM:</para>
<variablelist>
<varlistentry><term>BASE <replaceable>uri</replaceable></term>
<listitem>
<para>Catalog entries can contain relative URIs. The BASE entry changes the
base URI for subsequent relative URIs. The initial base URI is the URI of
the <emphasis>catalog</emphasis> file.</para>
<para>In <link linkend="xmlcatalogs">XML Catalogs</link>, this
functionality is provided by the closest applicable <sgmltag
class="attribute">xml:base</sgmltag> attribute, usually on the
surrounding <link linkend="catalog"><sgmltag>catalog</sgmltag></link>
or <link linkend="group"><sgmltag>group</sgmltag></link>
element.</para>
</listitem>
</varlistentry>
<varlistentry><term>CATALOG <replaceable>cataloguri</replaceable></term>
<listitem>
<para>This entry serves the same purpose as the
<link linkend="nextCatalog"><sgmltag>nextCatalog</sgmltag></link> entry
in <link linkend="xmlcatalogs">XML Catalogs</link>.</para>
</listitem>
</varlistentry>
<varlistentry><term>OVERRIDE <replaceable>YES|NO</replaceable></term>
<listitem>
<para>This entry enables or disables overriding of system identifiers
for subsequent entries in the catalog file.</para>
<para>In <link linkend="xmlcatalogs">XML Catalogs</link>, this
functionality is provided by the closest applicable <sgmltag
class="attribute">prefer</sgmltag> attribute on the
surrounding <link linkend="catalog"><sgmltag>catalog</sgmltag></link>
or <link linkend="group"><sgmltag>group</sgmltag></link>
element.</para>
<para>An override value of <quote>yes</quote> is equivalent to
<quote>prefer="public"</quote>.</para>
</listitem>
</varlistentry>
<varlistentry><term>DELEGATE <replaceable>pubid-prefix</replaceable> <replaceable>cataloguri</replaceable></term>
<listitem>
<para>This entry serves the same purpose as the
<link linkend="delegate"><sgmltag>delegate</sgmltag></link> entry
in <link linkend="xmlcatalogs">XML Catalogs</link>.</para>
</listitem>
</varlistentry>
<varlistentry><term>PUBLIC <replaceable>pubid</replaceable> <replaceable>systemuri</replaceable></term>
<listitem>
<para>This entry serves the same purpose as the
<link linkend="public"><sgmltag>public</sgmltag></link> entry
in <link linkend="xmlcatalogs">XML Catalogs</link>.</para>
</listitem>
</varlistentry>
<varlistentry><term>SYSTEM <replaceable>sysid</replaceable> <replaceable>systemuri</replaceable></term>
<listitem>
<para>This entry serves the same purpose as the
<link linkend="system"><sgmltag>system</sgmltag></link> entry
in <link linkend="xmlcatalogs">XML Catalogs</link>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section><title>XCatalogs</title>
<para>The Resolver classes also understand the XCatalog format supported
by Apache.</para>
</section>
<section><title>Resolution Semantics</title>
<para>Resolution is performed in roughly the following way:
</para>
<orderedlist>
<listitem><para>If a system entry matches the specified system identifier,
it is used.</para>
</listitem>
<listitem><para>If no system entry matches the specified system
identifier, but a rewrite entry matches, it is used.</para>
</listitem>
<listitem><para>If a public entry matches the specified public identifier
and either <sgmltag class="attribute">prefer</sgmltag>
is public or no system identifier is provided,
it is used.</para>
</listitem>
<listitem><para>If no exact match was found, but
it matches one or more of the partial identifiers specified in delegate
entries, the delegated catalogs are searched for a matching identifier.
</para>
</listitem>
</orderedlist>
<para>For a more detailed description of resolution semantics, including
the treatment of multiple catalog files and the complete rules for
delegation, consult the
<ulink url="http://www.oasis-open.org/committees/entity/spec.html">XML
Catalog standard</ulink>.</para>
</section>
</section>
<section id='ctrlresolver'>
<title>Controlling the Catalog Resolver</title>
<para>The Resolver classes uses either Java system properties or a
standard Java properties file to establish an initial environment. The
property file, if it is used, must be called
<filename>CatalogManager.properties</filename> and must be
somewhere on your <envar>CLASSPATH</envar>. The following properties
are supported:</para>
<variablelist>
<varlistentry><term>System property <literal>xml.catalog.files</literal>;
CatalogManager property <literal>catalogs</literal></term>
<listitem><para>A semicolon-delimited list of catalog files. These are the
catalog files that are initially consulted for resolution.</para>
<para>Unless you are incorporating the resolver classes into your own
applications, and subsequently establishing an initial set of catalog
files through some other means, at least one file must be specified,
or all resolution will fail.
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.prefer</literal>;
CatalogManager property <literal>prefer</literal></term>
<listitem><para>The initial prefer setting, either <literal>public</literal>
or <literal>system</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.verbosity</literal>;
CatalogManager property <literal>verbosity</literal></term>
<listitem><para>An indication of how much status/debugging information
you want to receive. The value is a number; the larger the number, the more
information you will receive. A setting of 0 turns off all status information.
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.staticCatalog</literal>;
CatalogManager property <literal>static-catalog</literal></term>
<listitem><para>In the course of processing, an application may parse
several XML documents. If you are using the built-in
<classname>CatalogResolver</classname>, this option controls whether or
not a new instance of the resolver is constructed for each parse.
For performance reasons, using a value of <literal>yes</literal>, indicating
that a static catalog should be used for all parsing, is probably best.
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.allowPI</literal>;
CatalogManager property <literal>allow-oasis-xml-catalog-pi</literal></term>
<listitem><para>This setting allows you to toggle whether or not the
resolver classes obey the <sgmltag class="xmlpi">oasis-xml-catalog</sgmltag>
processing instruction.
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.className</literal>;
CatalogManager property <literal>catalog-class-name</literal></term>
<listitem><para>If you're using the convenience classes
<literal>org.apache.xml.resolver.tools.*</literal>), this setting
allows you to specify an alternate class name to use for the underlying
catalog.
</para>
</listitem>
</varlistentry>
<varlistentry><term>CatalogManager property <literal>relative-catalogs</literal></term>
<listitem><para>If <literal>relative-catalogs</literal> is <literal>yes</literal>,
relative catalogs in the <literal>catalogs</literal> property will be left relative;
otherwise they will be made absolute
with respect to the base URI of the <filename>CatalogManager.properties</filename>
file. This setting has no effect on catalogs loaded from the
<literal>xml.catalogs.files</literal> system property (which are always returned
unchanged).
</para>
</listitem>
</varlistentry>
<varlistentry><term>System property <literal>xml.catalog.ignoreMissing</literal></term>
<listitem><para>By default, the resolver will issue warning messages if it
cannot find a <filename>CatalogManager.properties</filename> file, or if resources
are missing in that file. However if <emphasis>either</emphasis>
<literal>xml.catalog.ignoreMissing</literal> is <literal>yes</literal>, or
catalog files are specified with the
<literal>xml.catalog.catalogs</literal> system property, this warning will
be suppressed.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>My <filename>CatalogManager.properties</filename> file looks like
this:</para>
<example><title>Example CatalogManager.properties File</title>
<programlisting>#CatalogManager.properties
verbosity=1
relative-catalogs=yes
# Always use semicolons in this list
catalogs=./xcatalog;/share/doctypes/catalog;/share/doctypes/xcatalog
prefer=public
static-catalog=yes
allow-oasis-xml-catalog-pi=yes
catalog-class-name=org.apache.xml.resolver.Resolver
</programlisting>
</example>
</section>
<section>
<title>Using Catalogs with Popular Applications</title>
<para>A number of popular applications provide easy access to catalog
resolution:</para>
<variablelist>
<varlistentry><term>Xalan</term>
<listitem><para>Recent development versions of Xalan include new command-line
switches for setting the resolvers. You can use them directly with
the <literal>org.apache.xml.resolver.tools</literal> classes:</para>
<screen>
-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver
-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver
</screen>
</listitem>
</varlistentry>
<varlistentry><term>Saxon</term>
<listitem><para>Similarly, Saxon supports command-line access to the
resolvers:</para>
<screen>
-x org.apache.xml.resolver.tools.ResolvingXMLReader
-y org.apache.xml.resolver.tools.ResolvingXMLReader
-r org.apache.xml.resolver.tools.CatalogResolver
</screen>
<para>The <parameter>-x</parameter> class is used to read source documents,
the <parameter>-y</parameter> class is used to read stylesheets.</para>
</listitem>
</varlistentry>
<varlistentry><term>XP</term>
<listitem><para>To use XP, simply use the included
<literal>org.apache.xml.xp.xml.sax.Driver</literal> class instead of
the default XP driver.
</para></listitem>
</varlistentry>
<varlistentry><term>XT</term>
<listitem><para>Similarly, for XT, use the
<literal>org.apache.xml.xt.xsl.sax.Driver</literal> class.
</para></listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Adding Catalog Support to Your Applications</title>
<para>If you work with Java applications using a parser that supports
the SAX1 <literal>Parser</literal> interface or the SAX2
<literal>XMLReader</literal> interface, adding Catalog support to your
applications is a snap. The SAX interfaces
include an <literal>entityResolver</literal> hook designed to provide
an application with an opportunity to do this sort of indirection. The
Resolver classes implements the full
OASIS Catalog semantics and provide an appropriate class that
implements the SAX <literal>entityResolver</literal> interface.</para>
<para>All you have to do is setup a
<literal>org.apache.xml.resolver.tools.CatalogResolver</literal>
on your parser's <literal>entityResolver</literal> hook. The code listing
in <xref linkend="ex1"/> demonstrates how straightforward this is:</para>
<example id="ex1">
<title>Adding a CatalogResolver to Your Parser</title>
<programlisting>import org.apache.xml.resolver.tools.CatalogResolver;
...
CatalogResolver cr = new CatalogResolver();
...
yourParser.setEntityResolver(cr)
</programlisting>
</example>
<para>The system catalogs are loaded from the
<filename>CatalogManager.properties</filename> file on your
<envar>CLASSPATH</envar>.
(For all the
gory details about these classes, consult <ulink url="apidocs/index.html">the
API documentation</ulink>.) You can explicitly parse your own catalogs (perhaps
taken from command line arguments or a Preferences dialog) instead of or in
addition to the system catalogs.</para>
</section>
<section>
<title>Catalogs In Action</title>
<para>The Resolver distribution includes a couple of test programs,
<command>resolver</command> and <command>xparse</command>,
that you can use to see how this all works.</para>
<section>
<title>Using <command>resolver</command></title>
<para>The <command>resolver</command> application simply performs a
catalog lookup and returns the result. Given the following catalog:</para>
<example id="ex.catalog.xml"><title>An Example XML Catalog File</title>
<programlisting><![CDATA[<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<public publicId="-//Example//DTD Example V1.0//EN"
uri="example.dtd"/>
</catalog>]]></programlisting>
</example>
<para>A demonstration of public identifier resolution can be achieved
like this:</para>
<example id="ex.resolver"><title>Resolving Identifiers</title>
<screen>$ java org.apache.xml.resolver.apps.resolver -d 2 -c example/catalog.xml \
-p "-//Example//DTD Example V1.0//EN" public
Loading catalog: ./catalog
Loading catalog: /share/doctypes/catalog
Resolve PUBLIC (publicid, systemid):
public id: -//Example//DTD Example V1.0//EN
Loading catalog: file:/share/doctypes/entities.cat
Loading catalog: /share/doctypes/xcatalog
Loading catalog: example/catalog.xml
Result: file:/share/documents/articles/sun/2001/01-resolver/example/example.dtd
</screen>
</example>
</section>
<section>
<title>Using <command>xparse</command></title>
<para>The
<command>xparse</command> command simply sets up a catalog resolver
and then parses a document. Any external entities encountered during
the parse are resolved appropriately using the catalogs
provided.</para>
<para>In order to use the program, you must have the
<filename>resolver.jar</filename> file on your
<envar>CLASSPATH</envar> and you must be using <ulink
url="http://java.sun.com/xml/">JAXP</ulink>. In the examples that
follow, I've already got these files on my
<envar>CLASSPATH</envar>.</para>
<para>The file we'll be parsing is shown in <xref linkend="ex.example.xml"/>.
</para>
<example id="ex.example.xml"><title>An xparse Example File</title>
<programlisting><![CDATA[<!DOCTYPE example PUBLIC "-//Example//DTD Example V1.0//EN"
"file:///dev/this/does/not/exist/example.dtd">
<example>
<p>This is just a trivial example.</p>
</example>]]></programlisting>
</example>
<para>First let's look at what happens if you try to parse this
document without any catalogs. For this example, I deleted the
<literal>catalogs</literal> entry on my
<filename>CatalogManager.properties</filename> file. As expected,
the parse fails:</para>
<example id="ex.nocat.sh"><title>Parsing Without a Catalog</title>
<screen>$ java org.apache.xml.resolver.apps.xparse -d 2 example.xml
Attempting validating, namespace-aware parse
Fatal error:example.xml:2:External entity not found:
"file:///dev/this/does/not/exist/example.dtd".
Parse failed with 1 error and no warnings.</screen>
</example>
<para>With an appropriate catalog file, we can map the public identifier
to a local copy of the DTD. We could have mapped the system identifier
instead (or as well), but the public identifier is probably more stable.
</para>
<para>Using a command-line option to specify the catalog, I can now
successfully parse the document:</para>
<example id="ex.withcat.sh"><title>Parsing With a Catalog</title>
<screen>$ java org.apache.xml.resolver.apps.xparse -d 2 -c catalog.xml example.xml
Loading catalog: catalog.xml
Attempting validating, namespace-aware parse
Resolved public: -//Example//DTD Example V1.0//EN
file:/share/documents/articles/sun/2001/01-resolver/example/example.dtd
Parse succeeded (0.32) with no errors and no warnings.
</screen>
</example>
<para>The additional messages in each of these examples arise as a
consequence of the debugging option, <replaceable>-d 2</replaceable>.
In practice, you can make resolution silent.</para>
</section>
</section>
<section>
<title>May All Your Names Resolve Successfully!</title>
<para>We hope that these classes become a standard part of your
toolkit. Incorporating this code allows you to utilize public
identifiers in XML documents with the confidence that you will be
able to move those documents from one system to another and around the
Web.</para>
</section>
</article>

74
src/documentation/content/xdocs/components/resolver-release-notes.xml Normal file
View File

@ -0,0 +1,74 @@
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
<title>org.apache.xml.resolver Release Notes</title>
<subtitle>Version 1.1 CVS</subtitle>
<pubdate>13 Nov 2002</pubdate>
<releaseinfo role="meta">$Id$
</releaseinfo>
<author><firstname>Norman</firstname><surname>Walsh</surname>
<affiliation>
<jobtitle>Staff Engineer</jobtitle>
<orgname>Sun Microsystems, XML Technology Center</orgname>
</affiliation>
<authorblurb>
<para>Sun Microsystems supports Norm's active participation in a
number of standards efforts worldwide, including the Technical
Architecture Group, XML Core, and XSL Working Groups of the World Wide
Web Consortium, the OASIS RELAX NG Committee,
the Entity Resolution Committee, for which he is the editor, and
the DocBook Technical Committee, which he chairs.</para>
</authorblurb>
</author>
<copyright>
<year>2002</year>
<holder>Sun Microsystems, Inc.</holder>
</copyright>
</articleinfo>
<para>This document offers a brief summary of what has changed in the
Resolver package since the 1.0 release. I expect it'll be updated a few times
before the next release.</para>
<section>
<title>The <classname>CatalogManager</classname> Is No Longer Static</title>
<para>The most pervasive change is that the <classname>CatalogManager</classname>
class is no longer static. It's now possible to instantiate several catalog
managers and each manager can manage several catalogs.</para>
<para>There is still a single static instance of the
<classname>CatalogManager</classname>, available via
<methodname>getStaticManager()</methodname>. This is used by default
if no other catalog manager is instantiated and used. It behaves as
the old static one used to.</para>
</section>
<section>
<title>System Catalogs Are Always Loaded</title>
<para>In the previous version, the system catalogs were not loaded if
a private catalog was requested. That has changed; the system catalogs are now
always loaded.</para>
<para>If you want to avoid loading any system catalogs, establish your own
<classname>CatalogManager</classname> and use the
<methodname>setCatalogsFiles()</methodname> method to assure that no system
catalogs are available.</para>
</section>
<section>
<title>Tests/Examples Available</title>
<para>There are several tests in the <filename>tests/resolver</filename> directory
that demonstrate how different instantiations can be used.</para>
</section>
</article>

12
src/documentation/content/xdocs/components/resolver.xml
View File

@ -11,14 +11,22 @@
<anchor id="overview"/> <anchor id="overview"/>
<section> <section>
<title>Overview</title> <title>Overview</title>
<p>See the current set of resolver docs java/docs/resolver.html <p>See the current set of resolver docs ...
See the current /java/docs/releasenotes.html. <code>xml-commons/java/docs/resolver.xml</code>
and <code>xml-commons/java/docs/release-notes.xml</code>
</p> </p>
<fixme author="curcuru">Need to either update existing resolver docs to <fixme author="curcuru">Need to either update existing resolver docs to
use forrest or provide a stylesheet to translate it (it uses Docbook since use forrest or provide a stylesheet to translate it (it uses Docbook since
ndw used that). Also need to either move docs or provide correct links ndw used that). Also need to either move docs or provide correct links
to the resolver-specific docs. to the resolver-specific docs.
</fixme> </fixme>
<p>
Here is experimental (2002-12-20) rendering of those docs with Forrest and DocBook XSL ...
</p>
<ul>
<li><link href="resolver-article.html">resolver-article.html</link></li>
<li><link href="resolver-release-notes.html">resolver-release-notes.html</link></li>
</ul>
</section> </section>

34
src/documentation/content/xdocs/howto-forrest.xml
View File

@ -60,16 +60,40 @@ mozilla file:///usr/local/cvs/xml-commons/build/site/index.html
]]></source> ]]></source>
</section> </section>
<section>
<title>Other notes</title>
<p>
As defined in <code>forrest.properties</code> the OASIS Catalog for DocBook
is expected to be found at
<code>project.catalog=/usr/share/sgml/docbook/xmlcatalog</code> which will be
fine for some UNIX systems.
</p>
<p>
A temporary sitemap has been added at
<code>src/documentation/sitemap.xmap</code> of which we only use a small
portion. This portion has been marked with comments.
</p>
<p>
There is a hard-coded path in the sitemap to the DocBook XSL stylesheets.
</p>
</section>
<section> <section>
<title>Still to do</title> <title>Still to do</title>
<ul> <ul>
<li>Ensure okay by the xml-commons team. <li>Ask the '<code>forrestbot</code>' to build the xml-commons site.
See temporary demo at See <link href="http://forrestbot.cocoondev.org/">http://forrestbot.cocoondev.org/"></link>
<link href="http://cvs.apache.org/~crossley/commons/">http://cvs.apache.org/~crossley/commons/</link>
</li> </li>
<li>Synchronise changes with any to README.html until we are in production</li> <li>
Decide how to build the website and combine the needs of the separate
components. See the isses listed on the
<link href="todo.html">To Do List</link>
</li>
<li>Synchronise changes with any from README.html until we are in production</li>
<li>Commit the HTML/PDF result to xml-site/targets CVS</li> <li>Commit the HTML/PDF result to xml-site/targets CVS</li>
<li>Add link to xml.apache.org/index.html</li> <li>Add link from xml.apache.org/index.html to xml-commons</li>
<li>Later get Forrest to automatically build our website by extracting sources <li>Later get Forrest to automatically build our website by extracting sources
from CVS. This will later be done as a batch process, along with other Apache from CVS. This will later be done as a batch process, along with other Apache
websites. For the time being, an xml-commons committer needs to manually do it. websites. For the time being, an xml-commons committer needs to manually do it.

581
src/documentation/sitemap.xmap Normal file
View File

@ -0,0 +1,581 @@
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<!-- =========================== Components ================================ -->
<map:components>
<map:generators default="file">
<map:generator name="file" src="org.apache.cocoon.generation.FileGenerator" label="content"/>
<map:generator name="directory" src="org.apache.cocoon.generation.DirectoryGenerator" label="content"/>
<map:generator name="html" src="org.apache.cocoon.generation.HTMLGenerator" label="content"/>
<map:generator name="libre" src="org.apache.forrest.yer.use.cocoon.HierarchyGenerator" label="content"/>
<map:generator name="nekodtd" src="org.apache.forrest.components.generator.XNIConfigurableFileGenerator" label="content"/>
<!-- FIXME: Change this once better view handling is implemented -->
<map:generator name="file-nolabel" src="org.apache.cocoon.generation.FileGenerator"/>
</map:generators>
<map:transformers default="xslt">
<!--
<map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer">
<use-request-parameters>false</use-request-parameters>
<use-browser-capabilities-db>false</use-browser-capabilities-db>
</map:transformer>
-->
<map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer"
logger="sitemap.transformer.xsltc"
pool-max="32" pool-min="8" pool-grow="2">
<use-request-parameters>false</use-request-parameters>
<use-browser-capabilities-db>false</use-browser-capabilities-db>
<use-deli>false</use-deli>
<!-- transformer-factory>com.icl.saxon.TransformerFactoryImpl</transformer-factory -->
<!-- transformer-factory>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</transformer-factory -->
</map:transformer>
</map:transformers>
<map:readers default="resource">
<map:reader name="resource" src="org.apache.cocoon.reading.ResourceReader"/>
</map:readers>
<map:serializers default="html">
<map:serializer name="html" mime-type="text/html" src="org.apache.cocoon.serialization.HTMLSerializer">
<doctype-public>-//W3C//DTD HTML 4.01 Transitional//EN</doctype-public>
<encoding>ISO-8859-1</encoding>
</map:serializer>
<map:serializer name="xml" mime-type="text/xml" src="org.apache.cocoon.serialization.XMLSerializer">
<encoding>ISO-8859-1</encoding>
</map:serializer>
<map:serializer name="rss091" mime-type="text/xml" src="org.apache.cocoon.serialization.XMLSerializer">
<doctype-public>-//Netscape Communications//DTD RSS 0.91//EN</doctype-public>
<doctype-system>http://my.netscape.com/publish/formats/rss-0.91.dtd</doctype-system>
<encoding>ISO-8859-1</encoding>
</map:serializer>
<map:serializer name="fo2pdf"
src="org.apache.cocoon.serialization.FOPSerializer"
mime-type="application/pdf"/>
<map:serializer name="links" src="org.apache.cocoon.serialization.LinkSerializer">
<encoding>ISO-8859-1</encoding>
</map:serializer>
<map:serializer name="svg2jpeg" mime-type="image/jpeg" src="org.apache.cocoon.serialization.SVGSerializer">
<parameter name="quality" type="float" value="1.0"/>
</map:serializer>
<map:serializer name="svg2png" mime-type="image/png" src="org.apache.cocoon.serialization.SVGSerializer"/>
</map:serializers>
<map:matchers default="wildcard">
<map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcher"/>
</map:matchers>
<!--
<map:selectors default="skin-parameter">
<map:selector name="request-parameter" logger="sitemap.selector.request-parameter"
src="org.apache.cocoon.selection.RequestParameterSelector">
<parameter-name>skin</parameter-name>
</map:selector>
<map:selector name="style-parameter" logger="sitemap.selector.request-parameter"
src="org.apache.cocoon.selection.RequestParameterSelector">
<parameter-name>style</parameter-name>
</map:selector>
</map:selectors>
-->
<map:actions>
<!-- <map:action logger="sitemap.action.request" name="request" src="org.apache.cocoon.acting.RequestParamAction"/> -->
<map:action logger="sitemap.action.resource-exists" name="resource-exists" src="org.apache.cocoon.acting.ResourceExistsAction"/>
<map:action logger="sitemap.action.sourcetype" name="sourcetype" src="org.apache.forrest.components.sourcetype.SourceTypeAction">
<sourcetype name="document-v11">
<document-declaration public-id="-//APACHE//DTD Documentation V1.1//EN"/>
</sourcetype>
<sourcetype name="howto-v10">
<document-declaration public-id="-//APACHE//DTD How-to V1.0//EN"/>
</sourcetype>
</map:action>
</map:actions>
<map:selectors>
<map:selector logger="sitemap.selector.parameter" name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/>
</map:selectors>
<!--
The different pipeline implementations
-->
<map:pipelines default="caching">
<map:pipeline name="caching" src="org.apache.cocoon.components.pipeline.impl.CachingProcessingPipeline"/>
<map:pipeline name="noncaching" src="org.apache.cocoon.components.pipeline.impl.NonCachingProcessingPipeline"/>
<!-- The following two can be used for profiling:
<map:pipeline name="profile-caching" src="org.apache.cocoon.components.profiler.ProfilingCachingProcessingPipeline"/>
<map:pipeline name="profile-noncaching" src="org.apache.cocoon.components.profiler.ProfilingNonCachingProcessingPipeline"/>
-->
</map:pipelines>
</map:components>
<!-- =========================== Views =================================== -->
<map:views>
<map:view name="content" from-label="content">
<map:serialize type="xml"/>
</map:view>
<map:view name="links" from-position="last">
<map:transform src="library/xslt/filterlinks.xsl"/>
<map:serialize type="links"/>
</map:view>
</map:views>
<map:resources>
<map:resource name="skinit">
<map:transform src="skins/{forrest:skin}/xslt/html/{type}.xsl">
<map:parameter name="isfaq" value="{isfaq}"/>
<map:parameter name="nopdf" value="{nopdf}"/>
<map:parameter name="path" value="{path}"/>
<!-- Can set an alternative project skinconfig here
<map:parameter name="config-file" value="../../../../skinconf.xml"/>
-->
</map:transform>
<map:serialize/>
</map:resource>
<map:resource name="book">
<map:generate src="content/xdocs/{../1}book.xml"/>
<map:call resource="skinit">
<map:parameter name="type" value="book2menu"/>
<map:parameter name="path" value="{path}"/>
</map:call>
</map:resource>
<map:resource name="skin-read">
<map:read src="skins/{forrest:skin}/{path}" mime-type="{mime-type}"/>
</map:resource>
<!-- Checks the document type of the resource passed in the "src" parameter
and converts it to document if necessary -->
<map:resource name="transform-to-document">
<map:act type="sourcetype" src="{src}">
<map:select type="parameter">
<map:parameter name="parameter-selector-test" value="{sourcetype}"/>
<map:when test="howto-v10">
<map:transform src="library/xslt/howto2document.xsl" label="content"/>
</map:when>
<map:otherwise/>
</map:select>
</map:act>
</map:resource>
</map:resources>
<!-- =========================== Pipelines ================================= -->
<map:pipelines>
<!-- Pipeline that manages the internal URI space
For the external URI space manager, see the next pipeline. -->
<map:pipeline internal-only="true">
<map:match pattern="**tab-**.xml">
<map:generate src="content/xdocs/tabs.xml"/>
<map:call resource="skinit">
<map:parameter name="type" value="tab2menu"/>
<map:parameter name="path" value="{2}"/>
</map:call>
</map:match>
<map:match pattern="**book-**/*.xml">
<map:call resource="book">
<map:parameter name="path" value="{2}/{3}.xml"/>
</map:call>
</map:match>
<map:match pattern="**book-**.xml">
<map:call resource="book">
<map:parameter name="path" value="{2}.xml"/>
</map:call>
</map:match>
<map:match pattern="body-todo.xml">
<map:generate type="file-nolabel" src="status.xml"/>
<map:transform src="library/xslt/todo2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="/todo.xml"/>
</map:call>
</map:match>
<map:match pattern="body-changes.xml">
<map:generate type="file-nolabel" src="status.xml"/>
<map:transform src="library/xslt/changes2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="/changes.xml"/>
</map:call>
</map:match>
<map:match pattern="body-**/faq.xml">
<map:generate type="file-nolabel" src="content/xdocs/{1}/faq.xml"/>
<map:transform src="library/xslt/faq2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="{1}/faq.xml"/>
<map:parameter name="isfaq" value="true"/>
</map:call>
</map:match>
<map:match pattern="body-faq.xml">
<map:generate type="file-nolabel" src="content/xdocs/faq.xml"/>
<map:transform src="library/xslt/faq2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="faq.xml"/>
<map:parameter name="isfaq" value="true"/>
</map:call>
</map:match>
<!-- Redirect requests for community/ (eg in the trail) to the home page -->
<map:match pattern="community/index.html">
<map:redirect-to uri="../index.html"/>
</map:match>
<!-- index pages for contribution categories -->
<map:match pattern="body-community/*/index.xml">
<map:generate src="content/xdocs/community/{1}/index.xml"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="community/{1}/index"/>
</map:call>
</map:match>
<!-- no special transformation, yet, for revision pages -->
<map:match pattern="body-community**revision-*.xml">
<map:generate src="content/xdocs/community{1}revision-{2}.xml"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="community/{1}/revision-{2}"/>
</map:call>
</map:match>
<!-- all contribution docs -->
<map:match pattern="body-community/*/*/**.xml">
<map:aggregate element="all" >
<map:part src="content/xdocs/community/{1}/{2}/{3}.xml"/>
<map:part src="cocoon:/revisions-community/{1}/{2}/{3}" />
</map:aggregate>
<map:transform src="library/xslt/{1}2document.xsl" label="content"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="community/{1}/{2}/{3}.xml"/>
</map:call>
</map:match>
<!-- revisions only implemented for community pages -->
<map:match pattern="revisions-community/*/*/**">
<map:generate type="directory" src="content/xdocs/community/{1}/{2}">
<map:parameter name="dateFormat" value="yyyy-MM-dd hh:mm" />
</map:generate>
<map:transform src="library/xslt/directory2revisions.xsl" label="content" >
<map:parameter name="use-request-parameters" value="true"/>
<map:parameter name="page" value="{3}"/>
</map:transform>
<map:serialize type="xml" />
</map:match>
<!-- Generate the "doclist" - list of all documentation
The first match generates each book.xml and adds a new attribute "uri".
The second match aggregates each book.xml into a doclist and
then converts it to a document.
-->
<map:match pattern="doclist/content/xdocs/**book.xml">
<map:generate src="content/xdocs/{1}book.xml"/>
<map:transform src="library/xslt/doclist.xsl">
<map:parameter name="uri" value="{1}"/>
</map:transform>
<map:serialize type="xml"/>
</map:match>
<map:match pattern="body-doclist.xml">
<map:aggregate element="doclist">
<map:part src="cocoon:/doclist/content/xdocs/book.xml"/>
<map:part src="cocoon:/doclist/content/xdocs/community/howto/book.xml"/>
</map:aggregate>
<map:transform src="library/xslt/doclist2document.xsl"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="doclist.xml"/>
<map:parameter name="nopdf" value="true"/>
</map:call>
</map:match>
<!-- HTML DTD Documentation generation pipeline, makes use of NekoDTD tool -->
<map:match pattern="body-**.dtdx.xml">
<map:generate type="nekodtd" src="resources/schema/dtd/{1}.dtd">
<map:parameter name="config-class" value="org.cyberneko.dtd.DTDConfiguration" />
</map:generate>
<map:transform src="library/xslt/dtdx2flat.xsl"/>
<map:transform src="library/xslt/flat2document.xsl"/>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="isfaq" value="true"/>
<map:parameter name="path" value="{1}.dtdx.xml"/>
</map:call>
</map:match>
<!-- Generates body HTML for files in subdirs -->
<map:match pattern="body-**/*.xml">
<map:generate src="content/xdocs/{1}/{2}.xml"/>
<map:call resource="transform-to-document">
<map:parameter name="src" value="content/xdocs/{1}/{2}.xml"/>
</map:call>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="{1}/{2}.xml"/>
</map:call>
</map:match>
<!-- Generates body HTML for root-level files -->
<map:match pattern="body-**.xml">
<map:generate src="content/xdocs/{1}.xml"/>
<map:call resource="transform-to-document">
<map:parameter name="src" value="content/xdocs/{1}.xml"/>
</map:call>
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="{1}.xml"/>
</map:call>
</map:match>
</map:pipeline>
<map:pipeline internal-only="false">
<!-- ====================== editor ============================== -->
<map:match pattern="edit**">
<map:mount uri-prefix="edit" src="editor.xmap" check-reload="yes"/>
</map:match>
<!-- ================== External URI-space ========================= -->
<map:match pattern="">
<map:redirect-to uri="{context:context}/index.html"/>
</map:match>
<map:match pattern="**">
<!-- if the file is present verbatim as content, give that to the user... -->
<map:act type="resource-exists">
<map:parameter name="url" value="content/{1}"/>
<map:read src="content/{../1}"/>
</map:act>
<!-- ... otherwise try to generate it using these rules. -->
<map:match pattern="apachestats">
<map:generate type="html"
src="http://www.apache.org/~rubys/stats/xml.apache.org/">
<map:parameter name="xpath"
value="/html/body//a[contains(@href,'.xml')]"/>
</map:generate>
<map:serialize type="xml"/>
</map:match>
<!-- 2002-12-14 copied default Forrest sitemap.xamp and added this match -->
<!-- xml-commons start -->
<map:match pattern="**/resolver-*.html">
<map:generate src="content/xdocs/{1}/resolver-{2}.xml"/>
<!-- wild assumption for the moment, sorry -->
<map:transform src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
<map:serialize/>
</map:match>
<!-- xml-commons end -->
<map:match pattern="*.html">
<map:aggregate element="site">
<map:part src="cocoon:/book-{1}.xml"/>
<map:part src="cocoon:/tab-{1}.xml"/>
<map:part src="cocoon:/body-{1}.xml" label="content"/>
</map:aggregate>
<map:call resource="skinit">
<map:parameter name="type" value="site2xhtml"/>
<map:parameter name="path" value="{0}"/>
</map:call>
</map:match>
<map:match pattern="**/*.html">
<map:aggregate element="site">
<map:part src="cocoon:/{1}/book-{1}/{2}.xml"/>
<map:part src="cocoon:/{1}/tab-{1}/{2}.xml"/>
<map:part src="cocoon:/body-{1}/{2}.xml" label="content"/>
</map:aggregate>
<map:call resource="skinit">
<map:parameter name="type" value="site2xhtml"/>
<map:parameter name="path" value="{0}"/>
</map:call>
</map:match>
<map:match pattern="*.dtdx.pdf">
<map:generate type="nekodtd" src="resources/schema/dtd/{1}.dtd">
<map:parameter name="config-class" value="org.cyberneko.dtd.DTDConfiguration" />
</map:generate>
<map:transform src="library/xslt/dtdx2flat.xsl"/>
<map:transform src="library/xslt/flat2document.xsl"/>
<map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="**/*.dtdx.pdf">
<map:generate type="nekodtd" src="resources/schema/dtd/{2}.dtd">
<map:parameter name="config-class" value="org.cyberneko.dtd.DTDConfiguration" />
</map:generate>
<map:transform src="library/xslt/dtdx2flat.xsl"/>
<map:transform src="library/xslt/flat2document.xsl"/>
<map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="changes.pdf">
<map:generate type="file-nolabel" src="status.xml"/>
<map:transform src="library/xslt/changes2document.xsl" label="content"/>
<map:transform src="skins/forrest-site/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="changes.rss">
<map:generate type="file-nolabel" src="status.xml"/>
<map:transform src="library/xslt/changes2rss.xsl" label="content"/>
<map:serialize type="rss091"/>
</map:match>
<map:match pattern="todo.pdf">
<map:generate type="file-nolabel" src="status.xml"/>
<map:transform src="library/xslt/todo2document.xsl" label="content"/>
<map:transform src="skins/forrest-site/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="faq.pdf">
<map:generate type="file-nolabel" src="content/xdocs/faq.xml"/>
<map:transform src="library/xslt/faq2document.xsl" label="content"/>
<map:transform src="skins/forrest-site/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<map:match pattern="**.pdf">
<map:generate src="content/xdocs/{1}.xml"/>
<map:call resource="transform-to-document">
<map:parameter name="src" value="content/xdocs/{1}.xml"/>
</map:call>
<map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl"/>
<map:serialize type="fo2pdf"/>
</map:match>
<!-- ================ Directory redirects =========================== -->
<!-- Redirect any request for a directory to the directory's index.html file -->
<map:match pattern="**/">
<map:redirect-to uri="{context:context}/{1}/index.html"/>
</map:match>
<!-- ================ Libre =========================== -->
<map:match pattern="libre">
<map:generate type="libre" src="content/xdocs" >
<map:parameter name="depth" value="-1" />
</map:generate>
<map:serialize type="xml"/>
</map:match>
<!-- ================ Static =========================== -->
<map:match pattern="skin/**.js">
<map:call resource="skin-read">
<map:parameter name="path" value="scripts/{1}.js"/>
<map:parameter name="mime-type" value="application/javascript"/>
</map:call>
</map:match>
<map:match pattern="**/skin/**.js">
<map:call resource="skin-read">
<map:parameter name="path" value="scripts/{2}.js"/>
<map:parameter name="mime-type" value="application/javascript"/>
</map:call>
</map:match>
<map:match pattern="**.js">
<map:read src="resources/scripts/{1}.js" mime-type="application/javascript"/>
</map:match>
<map:match pattern="skin/**.css">
<map:call resource="skin-read">
<map:parameter name="path" value="css/{1}.css"/>
<map:parameter name="mime-type" value="text/css"/>
</map:call>
</map:match>
<map:match pattern="**/skin/**.css">
<map:call resource="skin-read">
<map:parameter name="path" value="css/{2}.css"/>
<map:parameter name="mime-type" value="text/css"/>
</map:call>
</map:match>
<map:match pattern="**.css">
<map:read src="resources/css/{1}.css" mime-type="text/css"/>
</map:match>
<map:match pattern="skin/images/**.*">
<map:call resource="skin-read">
<map:parameter name="path" value="images/{1}.{2}"/>
<map:parameter name="mime-type" value="image/{2}"/>
</map:call>
</map:match>
<!-- WARNING: You are strongly advised not to make use of this target, as it
leads to browsers having to cache multiple copies of the images, one per
directory. See the forrest-site skin XSLTs for an example of how to make
all image references use the 'skin/images/**.*' rule above -->
<map:match pattern="**/skin/images/**.*">
<map:call resource="skin-read">
<map:parameter name="path" value="images/{2}.{3}"/>
<map:parameter name="mime-type" value="image/{3}"/>
</map:call>
</map:match>
<!-- DS: handles images local to a contributor directory -->
<map:match pattern="**my-images/**.*">
<map:read src="content/xdocs/{1}my-images/{2}.{3}" mime-type="image/{3}"/>
</map:match>
<map:match pattern="images/**.*">
<map:read src="resources/images/{1}.{2}" mime-type="image/{2}"/>
</map:match>
<!-- WARNING: See above: this target should not be made use of -->
<map:match pattern="**/images/**.*">
<map:read src="resources/images/{2}.{3}" mime-type="image/{3}"/>
</map:match>
<map:match pattern="**favicon.ico">
<map:call resource="skin-read">
<map:parameter name="path" value="images/favicon.ico"/>
<map:parameter name="mime-type" value="image/x-ico"/>
</map:call>
</map:match>
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>

37
status.xml
View File

@ -23,11 +23,25 @@
<link href="http://nagoya.apache.org/eyebrowse/ReadMsg?listName=commons-dev@xml.apache.org&amp;msgNo=39">making TCK-compliant API's common</link> <link href="http://nagoya.apache.org/eyebrowse/ReadMsg?listName=commons-dev@xml.apache.org&amp;msgNo=39">making TCK-compliant API's common</link>
(Actually is neilg,ilene) (Actually is neilg,ilene)
</action> </action>
<action context="build" dev="open">
Establish efficient distribution mirrors
and change the download link on the xml-commons website. See doc
<link href="http://cvs.apache.org/~bodewig/mirror.html">Making your downloads mirrorable</link>
</action>
<action context="docs" dev="open">
Fix broken links in resolver-article.xml ... only three, but important
ones: download, copyright, and apidocs.
</action>
<action context="build" dev="open"> <action context="build" dev="open">
Decide how to build separate distributable docs for each "component", Decide how to build separate distributable docs for each "component",
and how they will also be published to xml-commons website. Best if and how they will also be published to xml-commons website
xdocs content can remain in /java with their code. See email: (since resolver, which, etc. will get shipped as individual components,
even though they live in the same project).
Best if xdocs content can remain in /java with their code.
See email:
<link href="http://marc.theaimsgroup.com/?l=xml-commons-dev&amp;m=103736060229424">draft website for xml-commons using Forrest</link> <link href="http://marc.theaimsgroup.com/?l=xml-commons-dev&amp;m=103736060229424">draft website for xml-commons using Forrest</link>
and
<link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=103967656107408">a website with separate distributable components</link>
</action> </action>
</actions> </actions>
<actions priority="medium"> <actions priority="medium">
@ -63,13 +77,24 @@
<changes> <changes>
<!-- Add new releases here --> <!-- Add new releases here -->
<release version="0.3" date="2002-11-19"> <release version="0.4" date="2002-12-20">
<action type="add" context="docs" dev="curcuru"> <action type="add" context="docs" dev="curcuru">
Note that this release number is only really the release number of the Note that this release number is only really the release number of the
forrestized-docs, not of the individual components or code. forrestized-docs, not of the individual components or code.
### Fixme: figure out how to use this part of forrest on an individual </action>
component kind of basis (since resolver, which, etc. will get shipped <action type="add" context="docs" dev="crossley">
as individual components, even thought they live in the same project). Added experimental building of the Resolver component docs using
DocBook DTDs and XSL.
</action>
<action type="add" context="docs" dev="crossley">
Added some ToDo items and noted some issues in
<link href="howto-forrest.html">How-to Forrest</link>.
</action>
</release>
<release version="0.3" date="2002-11-19">
<action type="add" context="docs" dev="curcuru">
Added some content as overview for each component.
Added some ToDo items.
</action> </action>
</release> </release>
<release version="0.2" date="2002-11-16"> <release version="0.2" date="2002-11-16">