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> > <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"> + <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"> + + + </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: + <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button"> + <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button"> + <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 <xmlvalidate> and not (yet) for those validated with + <jing>, 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"> +<!ELEMENT release (downloads)> +<!ATTLIST release +version CDATA #REQUIRED +date CDATA #REQUIRED> + +<!ELEMENT downloads (file*)> + +<!ELEMENT file EMPTY> +<!ATTLIST file +url CDATA #REQUIRED +name CDATA #REQUIRED +size CDATA #IMPLIED> + </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"> +<!-- =================================================================== + +Download Doc format + +PURPOSE: +This DTD provides simple extensions on the Apache DocumentV11 format to link +to a set of downloadable files. + +TYPICAL INVOCATION: + +<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN" +"download-v10.dtd"> + +==================================================================== --> + + +<!-- =============================================================== --> +<!-- Include the Common ISO Character Entity Sets --> +<!-- =============================================================== --> + +<!ENTITY % common-charents PUBLIC +"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN" +"common-charents-v10.mod"> +%common-charents; + +<!-- =============================================================== --> +<!-- Document --> +<!-- =============================================================== --> + +<!ENTITY % document PUBLIC "-//APACHE//ENTITIES Documentation V1.3//EN" +"document-v13.mod"> + +<!-- Override this entity so that 'release' is allowed below 'section' --> +<!ENTITY % local.sections "|release"> + +%document; + +<!ELEMENT release (downloads)> +<!ATTLIST release +version CDATA #REQUIRED +date CDATA #REQUIRED> + +<!ELEMENT downloads (file*)> + +<!ELEMENT file EMPTY> +<!ATTLIST file +url CDATA #REQUIRED +name CDATA #REQUIRED +size CDATA #IMPLIED> + +<!-- =============================================================== --> +<!-- End of DTD --> +<!-- =============================================================== --> + </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 <!ENTITY % ... > 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 <release> 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"><!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN" + "download-v10.dtd"> + </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"> +<?xml version="1.0"?> +<!-- OASIS XML Catalog for Forrest --> +<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> + <public publicId="-//Acme//DTD Download Documentation V1.0//EN" + uri="dtd/download-v10.dtd"/> +</catalog> + </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">&half;</td> + <td colspan="1" rowspan="1">½</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"> </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 © + 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