forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r529910 [19/22] - in /forrest/site: docs_0_90/ docs_0_90/howto/ docs_0_90/howto/cvs-ssh/ docs_0_90/howto/multi/ docs_0_90/images/ pluginDocs/plugins_0_90/
Date Wed, 18 Apr 2007 08:11:05 GMT
Added: forrest/site/docs_0_90/validation.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/validation.html?view=auto&rev=529910
==============================================================================
--- forrest/site/docs_0_90/validation.html (added)
+++ forrest/site/docs_0_90/validation.html Wed Apr 18 01:10:58 2007
@@ -0,0 +1,794 @@
+<!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.9-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>XML validation and entity resolution (v0.9-dev)</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="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a
class="selected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a
class="unselected" href="../docs_0_70/index.html">0.70 (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.90-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_90/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install
Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/build.html" title="Build and install the current               
     unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/upgrading_09.html">Upgrading to 0.9</a>
+</div>
+<div class="menuitem">
+<a href="">Use Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize
Forrest</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-pdf-tab.html" title="Generate one pdf-document for all
pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate
Forrest with tools</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend
Forrest</div>
+<div id="menu_1.1.3.7" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding
Documentation</div>
+<div id="menu_1.1.3.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../howto-howto.html" title="Instructions for writing                 a new howto-document">Write
a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage
HowTo</div>
+<div id="menu_1.1.3.9.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.5', '../skin/')" id="menu_selected_1.1.5Title"
class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Background</div>
+<div id="menu_selected_1.1.5" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_90/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/cap.html">Sourcetype Action</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">XML validation and entity resolution</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference
docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD
documentation</div>
+<div id="menu_1.1.8.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.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc
samples</div>
+<div id="menu_1.1.8.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.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older
Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+        This is documentation for development version v0.9-dev
+       (<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 and entity resolution</h1>
+<h3>DTDs, catalogs and whatnot</h3>
+<div id="motd-area">
+        This is documentation for development version v0.9-dev
+       (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#intro">Introduction</a>
+</li>
+<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="#debug-catalog">Debugging the Catalog Entity Resolver</a>
+</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>
+<li>
+<a href="#sitemap">Validation using Cocoon sitemap and the Cocoon Validation block</a>
+</li>
+</ul>
+</div>
+    
+<a name="N10010"></a><a name="intro"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+        When a source document uses a DTD to define its structure, then various
+        abilities are enabled. Forrest handles the annoying side of this and
+        takes advantage of the benefits.
+      </p>
+<p>
+        The xml parser must locate the DTDs and other entities. Forrest uses the
+        XML Catalog Entity Resolver to associate DTD references with local
+        copies.
+      </p>
+<p>
+        Forrest also uses the XML Document Type Declaration to effect the
+        <a href="../docs_0_90/cap.html">Content Aware Pipelines</a>. Remember
that you
+        are not required to use DTDs (for example Forrest can also respond to a
+        namespace) so RELAX NG or W3c XML Schema can be used.
+      </p>
+<p>
+        If you do use DTDs, then forrest is automatically configured to do XML
+        validation.
+      </p>
+<p>
+        This document explains both the validation and entity resolution aspects
+        of the Forrest XML framework.
+      </p>
+</div>
+    
+<a name="N1002A"></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="N10063"></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_90/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="N10084"></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_90/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;
+
+==================================================================== --&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="N100CC"></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 supplies.
+        </p>
+<p>
+          An additional system-wide catalog can be configured for use by
+          multiple forrest-based projects. See the "local-catalog" parameter in
+          <span class="codefrag">main/webapp/WEB-INF/xconf/forrest-core.xconf</span>
+        
+</p>
+<p>
+          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</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-xdocs'</span> our download file would validate along with all
+          the others. If something goes wrong, try running <span class="codefrag">'forrest
-v
+          validate-xdocs'</span> to see the error in more detail.
+        </p>
+</div>
+    
+<a name="N10130"></a><a name="debug-catalog"></a>
+<h2 class="underlined_10">Debugging the Catalog Entity Resolver</h2>
+<div class="section">
+<p>
+        If you suspect problems with your project catalog, then raise the
+        "verbosity" level in
+        <span class="codefrag">src/documentation/classes/CatalogManager.properties</span>
and
+        re-start forrest. This should show your project catalogs being parsed
+        and loaded.
+      </p>
+<p>
+        However this configuration does not show your DTDs being resolved. So
+        raise the verbosity level in the central configuration at
+        <span class="codefrag">main/webapp/WEB-INF/properties/dev/core.properties</span>
and
+        re-start forrest. This also shows the main catalogs being loaded and
+        shows the resolving of every DTD and entity set.
+      </p>
+<p>
+        When a DTD is successfully resolved you should see the message:
+        <span class="codefrag">Resolved public:</span>
+      
+</p>
+<p>
+        When debugging such issues, a network monitoring tool (e.g.
+        ngrep.sf.net) is useful to ensure that all resources are being locally
+        resolved and not wandering onto the network to find remote copies.
+      </p>
+</div>
+    
+<a name="N1014C"></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="N10171"></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_90/catalog.html">configuration notes</a> your
+        favourite editor.
+      </p>
+</div>
+    
+<a name="N1017F"></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>
+    
+<a name="N10192"></a><a name="sitemap"></a>
+<h2 class="underlined_10">Validation using Cocoon sitemap and the Cocoon Validation
block</h2>
+<div class="section">
+<p>
+        The content of pipelines can be validated at various points in the
+        Cocoon sitemaps using RELAX NG or W3C XML Schema. See
+        <a href="../howto-dev.html#debug-validation">notes</a>.
+      </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>

Propchange: forrest/site/docs_0_90/validation.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_90/validation.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/validation.pdf?view=auto&rev=529910
==============================================================================
Binary file - no diff available.

Propchange: forrest/site/docs_0_90/validation.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf



Mime
View raw message