Google Git
Sign in
apache / forrest / forrest_08_release_site / . / docs_0_70 / validation.html
blob: c162327113ead2c97193b7d5ec1fb7aeafee6247 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>XML Validation (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Welcome</a>
</li>
<li>
<a class="unselected" href="../contrib.html">Developers</a>
</li>
<li class="current">
<a class="selected" href="../versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="../tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs">
<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.70</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_70/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/faq.html">FAQs</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/todo.html">Todo</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/your-project.html">Using Forrest</a>
</div>
<div class="menupage">
<div class="menupagetitle">XML Validation</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/searching.html">Searching</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skins.html">Default Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skin-package.html">Skin Packages</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/views.html">Views-dev</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/forrest-contract.html">Our Contract</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/compliance.html">Standards Compliance</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
<div id="menu_1.1.14" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-howto.html">Write a How-to</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-pdf-tab.html">Create tab PDF</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-corner-images.html">CSS corner SVG</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14.10', '../skin/')" id="menu_1.1.14.10Title" class="menutitle">Multipage HowTo</div>
<div id="menu_1.1.14.10" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step3.html">Step 3</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.14.11', '../skin/')" id="menu_1.1.14.11Title" class="menutitle">Views</div>
<div id="menu_1.1.14.11" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-install.html">Install views</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-dsl.html">forrest:view DSL</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-contracts.html">contract implementations</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
<div id="menu_1.1.15" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/build.html">Building Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/catalog.html">Using DTD Catalogs</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/cap.html">Sourcetype Action</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/upgrading_07.html">Upgrading to 0.7</a>
</div>
<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.17" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.17.1', '../skin/')" id="menu_1.1.17.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.17.1" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/dtd-docs.html">Overview</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.17.2', '../skin/')" id="menu_1.1.17.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.17.2" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/document-v13.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.html">document-v20</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">Older Docs</div>
<div id="menu_1.1.18" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/primer.html">Forrest Primer</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for current version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="validation.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>XML Validation</h1>
<h3>DTDs, catalogs and whatnot</h3>
<div id="motd-area">
This is documentation for current version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#xml_validation">XML validation</a>
</li>
<li>
<a href="#Validating+new+XML+types">Validating new XML types</a>
<ul class="minitoc">
<li>
<a href="#Creating+or+extending+a+DTD">Creating or extending a DTD</a>
</li>
<li>
<a href="#catalog">Associating DTDs with document types</a>
</li>
</ul>
</li>
<li>
<a href="#entities">Referring to entities</a>
</li>
<li>
<a href="#Validating+in+an+XML+editor">Validating in an XML editor</a>
</li>
<li>
<a href="#relaxng">Validation using RELAX NG</a>
</li>
</ul>
</div>
<a name="N10010"></a><a name="xml_validation"></a>
<h2 class="underlined_10">XML validation</h2>
<div class="section">
<p>
By default, Forrest will validate your XML before generating
HTML or a webapp from it, and fail if any XML files are not valid.
Validation can be performed manually by doing
'<span class="codefrag">forrest validate</span>' in the project root directory.
</p>
<p>
For an XML file to be valid, it <em>must</em> have a document type
declaration at the top, indicating its content type. Hence by
default, any Forrest-processed XML file that lacks a DOCTYPE
declaration will cause the build to break.
</p>
<p>
Despite the strict default behavior, Forrest is quite flexible about
validation. Validation can be switched off for certain sections of a
project. In validated sections, it is possible for projects to specify
exactly what files they want (and don't want) validated. Forrest
validation is controlled through a set of properties in
<span class="codefrag">forrest.properties</span>:
</p>
<pre class="code">
##############
# validation properties
# This set of properties determine if validation is performed
# Values are inherited unless overridden.
# e.g. if forrest.validate=false then all others are false unless set to true.
#forrest.validate=true
#forrest.validate.xdocs=${forrest.validate}
#forrest.validate.skinconf=${forrest.validate}
#forrest.validate.sitemap=${forrest.validate}
#forrest.validate.stylesheets=${forrest.validate}
#forrest.validate.skins=${forrest.validate}
#forrest.validate.skins.stylesheets=${forrest.validate.skins}
# *.failonerror=(true|false) - stop when an XML file is invalid
#forrest.validate.failonerror=true
# *.excludes=(pattern) - comma-separated list of path patterns to not validate
# e.g.
#forrest.validate.xdocs.excludes=samples/subdir/**, samples/faq.xml
#forrest.validate.xdocs.excludes=
</pre>
<p>
For example, to avoid validating
<span class="codefrag">${project.xdocs-dir}</span>/slides.xml and everything inside the
<span class="codefrag">${project.xdocs-dir}/manual/</span> directory, add this to
<span class="codefrag">forrest.properties</span>:
</p>
<pre class="code">forrest.validate.xdocs.excludes=slides.xml, manual/**</pre>
<div class="note">
<div class="label">Note</div>
<div class="content">
The <span class="codefrag">failonerror</span> properties only work for files validated
with Ant's &lt;xmlvalidate&gt; and not (yet) for those validated
with &lt;jing&gt;, where <span class="codefrag">failonerror</span> defaults to
<span class="codefrag">true</span>.
</div>
</div>
</div>
<a name="N10049"></a><a name="Validating+new+XML+types"></a>
<h2 class="underlined_10">Validating new XML types</h2>
<div class="section">
<p>
Forrest provides an <a href="http://www.oasis-open.org/committees/entity/spec.html">OASIS Catalog</a>
[see <a href="http://xml.apache.org/commons/components/resolver/resolver-article.html">tutorial</a>]
<span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span>
as a means of associating public identifiers
(e.g. <span class="codefrag">-//APACHE//DTD Documentation V1.1//EN</span> above) with DTDs.
If you <a href="../docs_0_70/your-project.html#adding_new_content_type">add a new content type</a>, you
should add the DTD to <span class="codefrag">${project.schema-dir}/dtd/</span> and add
an entry to the <span class="codefrag">${project.schema-dir}/catalog.xcat</span> file. This
section describes the details of this process.
</p>
<a name="N1006A"></a><a name="Creating+or+extending+a+DTD"></a>
<h3 class="underlined_5">Creating or extending a DTD</h3>
<p>
The main Forrest DTDs are designed to be modular and extensible, so
it is fairly easy to create a new document type that is a superset
of one from Forrest. This is what we'll demonstrate here, using our
earlier <a href="../docs_0_70/your-project.html#adding_new_content_type">download format</a>
as an example. Our download format adds a group of new elements to
the standard 'documentv13' format. Our new elements are described
by the following DTD:
</p>
<pre class="code">
&lt;!ELEMENT release (downloads)&gt;
&lt;!ATTLIST release
version CDATA #REQUIRED
date CDATA #REQUIRED&gt;
&lt;!ELEMENT downloads (file*)&gt;
&lt;!ELEMENT file EMPTY&gt;
&lt;!ATTLIST file
url CDATA #REQUIRED
name CDATA #REQUIRED
size CDATA #IMPLIED&gt;
</pre>
<p>
The document-v13 entities are defined in a reusable 'module':
<span class="codefrag">forrest/main/webapp/resources/schema/dtd/document-v13.mod</span>
The
<span class="codefrag">forrest/main/webapp/resources/schema/dtd/document-v13.dtd</span>
file provides a full description and basic example of how to pull in
modules. In our example, our DTD reuses modules
<span class="codefrag">common-charents-v10.mod</span> and
<span class="codefrag">document-v13.mod</span>. Here is the full DTD, with
explanation to follow.
</p>
<pre class="code">
&lt;!-- ===================================================================
Download Doc format
PURPOSE:
This DTD provides simple extensions on the Apache DocumentV11 format to link
to a set of downloadable files.
TYPICAL INVOCATION:
&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"download-v10.dtd"&gt;
COPYRIGHT:
Copyright 2002-2005 The Apache Software Foundation or its licensors,
as applicable.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
==================================================================== --&gt;
&lt;!-- =============================================================== --&gt;
&lt;!-- Include the Common ISO Character Entity Sets --&gt;
&lt;!-- =============================================================== --&gt;
&lt;!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod"&gt;
%common-charents;
&lt;!-- =============================================================== --&gt;
&lt;!-- Document --&gt;
&lt;!-- =============================================================== --&gt;
&lt;!ENTITY % document PUBLIC "-//APACHE//ENTITIES Documentation V1.3//EN"
"document-v13.mod"&gt;
&lt;!-- Override this entity so that 'release' is allowed below 'section' --&gt;
&lt;!ENTITY % local.sections "|release"&gt;
%document;
&lt;!ELEMENT release (downloads)&gt;
&lt;!ATTLIST release
version CDATA #REQUIRED
date CDATA #REQUIRED&gt;
&lt;!ELEMENT downloads (file*)&gt;
&lt;!ELEMENT file EMPTY&gt;
&lt;!ATTLIST file
url CDATA #REQUIRED
name CDATA #REQUIRED
size CDATA #IMPLIED&gt;
&lt;!-- =============================================================== --&gt;
&lt;!-- End of DTD --&gt;
&lt;!-- =============================================================== --&gt;
</pre>
<p>This custom DTD should be placed in your project resources
directory at <span class="codefrag">src/documentation/resources/schema/dtd/</span>
</p>
<p>
The &lt;!ENTITY % ... &gt; blocks are so-called
<a href="http://www.xml.com/axml/target.html#dt-PERef">parameter
entities</a>. They are like macros, whose content will be
inserted when a parameter-entity reference, like
<span class="codefrag">%common-charents;</span> or <span class="codefrag">%document;</span> is
inserted.
</p>
<p>
In our DTD, we first pull in the 'common-charents' entity, which
defines character symbol sets. We then define the 'document'
entity. However, before the <span class="codefrag">%document;</span> PE reference, we
first override the 'local.section' entity. This is a hook into
document-v13.mod. By setting its value to '|release', we declare
that our &lt;release&gt; element is to be allowed wherever "local
sections" are used. There are five or so such hooks for different
areas of the document; see document-v13.dtd for more details. We then
import the %document; contents, and declare the rest of our DTD
elements.
</p>
<p>
We now have a DTD for the 'download' document type.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
<a href="http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html">Chapter
5: Customizing DocBook</a> of Norman Walsh's "DocBook: The
Definitive Guide" gives a complete overview of the process of
customizing a DTD.
</div>
</div>
<a name="N100B1"></a><a name="catalog"></a>
<h3 class="underlined_5">Associating DTDs with document types</h3>
<p>
Recall that our DOCTYPE declaration for our download document type
is:
</p>
<pre class="code">&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"download-v10.dtd"&gt;
</pre>
<p>
We only care about the quoted section after <span class="codefrag">PUBLIC</span>, called
the "public identifier", which globally identifies our document type.
We cannot rely on the subsequent "system identifier" part
("download-v10.dtd"), because as a relative reference it is liable to
break. The solution Forrest uses is to ignore the system id, and rely
on a mapping from the public ID to a stable DTD location, via a
Catalog file.</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
See <a href="http://xml.apache.org/commons/components/resolver/resolver-article.html">this article</a> for a good
introduction to catalogs and the Cocoon documentation
<a href="http://cocoon.apache.org/2.1/userdocs/concepts/catalog.html">Entity resolution with catalogs</a>.
</div>
</div>
<p>
Forrest provides a standard catalog file at
<span class="codefrag">forrest/main/webapp/resources/schema/catalog.xcat</span>
for the document
types that Forrest provides. Projects can augment this with their
own catalog file located in
<span class="codefrag">${project.schema-dir}/catalog.xcat</span> to use it you must
specify either the path (full or relative) to your
<span class="codefrag">catalog.xcat</span> in the <span class="codefrag">CatalogManager.properties</span>
file. If you provide a relative path you must set the property
<span class="codefrag">relative-catalogs</span> to "yes".
</p>
<p>
When Cocoon starts, it reads the <span class="codefrag">CatalogManager.properties</span> file from your
<span class="codefrag">project.classes-dir</span>. This is usually src/documentation/classes/
but you can change this in <span class="codefrag">forrest.properties</span>. When you seed
a new site using <span class="codefrag">forrest seed-site</span> a sample catalog file
is placed in the site structure, you can use this as a template for your
own files.
</p>
<p>
Forrest uses the XML Catalog syntax by default, although the older
plain-text
format can also be used. Here is what the XML Catalog format looks
like:
</p>
<pre class="code">&lt;?xml version="1.0"?&gt;
&lt;!-- OASIS XML Catalog for Forrest --&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
&lt;public publicId="-//Acme//DTD Download Documentation V1.0//EN"
uri="dtd/download-v10.dtd"/&gt;
&lt;/catalog&gt;</pre>
<p>
The format is described in <a href="http://www.oasis-open.org/committees/entity/spec.html">the
spec</a>, and is fairly simple and very powerful.
The "<span class="codefrag">public</span>" elements map
a public identifier to a DTD (relative to the catalog file).
</p>
<p>
We now have a custom DTD and a catalog mapping which lets both
Forrest and Cocoon
locate the DTD. Now if we were to run <span class="codefrag">'forrest validate'</span>
our download file would validate along with all the others. If
something goes wrong, try running <span class="codefrag">'forrest -v validate'</span> to
see the error in more detail. Remember to raise the "verbosity"
level in <span class="codefrag">cocoon.xconf</span> if you suspect problems
with your catalog.
</p>
</div>
<a name="N1010F"></a><a name="entities"></a>
<h2 class="underlined_10">Referring to entities</h2>
<div class="section">
<p>
Look at the source of this document
(<span class="codefrag">xdocs/docs/validation.xml</span>) and see how the entity set
<span class="codefrag">"Numeric and Special Graphic"</span> is declared in the
document type declaration.
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<td colspan="1" rowspan="1">ISOnum.pen</td>
<td colspan="1" rowspan="1">&amp;half;</td>
<td colspan="1" rowspan="1">&frac12;</td>
</tr>
</table>
</div>
<a name="N10134"></a><a name="Validating+in+an+XML+editor"></a>
<h2 class="underlined_10">Validating in an XML editor</h2>
<div class="section">
<p>
If you have an XML editor that understands SGML or XML catalogs, let
it know where the Forrest catalog file is, and you will be able to
validate any Forrest XML file, regardless of location, as you edit
your files. See the
<a href="../docs_0_70/catalog.html">configuration notes</a> your favourite
editor.
</p>
</div>
<a name="N10142"></a><a name="relaxng"></a>
<h2 class="underlined_10">Validation using RELAX NG</h2>
<div class="section">
<p>
Other validation is also conducted during build-time using RELAX NG.
This validates all of the important configuration files, both in
Forrest itself and in your project. At the moment it processes all
skinconf.xml files, all sitemap.xmap files, and all XSLT stylesheets.
</p>
<p>
The RNG grammars to do this are located in the
<span class="codefrag">main/webapp/resources/schema/relaxng</span> directory.
If you want to
know more about this, and perhaps extend it for your own use, then
see <span class="codefrag">main/webapp/resources/schema/relaxng/README.txt</span>
and the Ant targets in the various build.xml files.
</p>
</div>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>