You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/04/11 17:12:22 UTC
svn commit: r160902 [22/28] - in forrest/site/0.6: ./ docs/ docs/images/
dtd/ entity/ howto/ images/ skin/ skin/css/ skin/images/ skin/scripts/ skins/
Added: forrest/site/0.6/docs/upgrading_05.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/upgrading_05.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/docs/upgrading_05.html (added)
+++ forrest/site/0.6/docs/upgrading_05.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,555 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Upgrading to Forrest 0.5 (v0.6)</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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">O.6 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../howto/index.html">0.6 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-selected" href="../docs/your-project.html">Core</a> | <a class="base-selected" href="../docs/forrestbot.html">ForrestBot</a> | <a class="base-selected" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.10" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.11', '../skin/')" id="menu_selected_1.1.11Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Upgrading</div>
+<div id="menu_selected_1.1.11" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Upgrading to 0.5</div>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">SubProjects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Reference docs</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.3.1', '../skin/')" id="menu_1.3.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/wiki-sample.html">JSPWiki Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/oowriter.html">OpenOffice.Org Writer</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Older Docs</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="upgrading_05.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>Upgrading to Forrest 0.5</h1>
+<div id="motd-area">
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Introduction">Introduction</a>
+</li>
+<li>
+<a href="#New+Features">New Features</a>
+</li>
+<li>
+<a href="#Upgrading+the+sitemap">Upgrading the sitemap</a>
+</li>
+<li>
+<a href="#Version-specific+sitemaps">Version-specific sitemaps</a>
+</li>
+<li>
+<a href="#Excluding+URLs%3A+filterlinks.xsl+removed+and+cli.xconf+added">Excluding URLs: filterlinks.xsl removed and cli.xconf added</a>
+</li>
+<li>
+<a href="#Skin+invocation+changes">Skin invocation changes</a>
+</li>
+<li>
+<a href="#Upgrading+skinconf.xml">Upgrading skinconf.xml</a>
+</li>
+<li>
+<a href="#Upgrading+forrest.properties">Upgrading forrest.properties</a>
+</li>
+<li>
+<a href="#Run+a+clean+target+after+upgrade">Run a clean target after upgrade</a>
+</li>
+<li>
+<a href="#SVGs+should+omit+DOCTYPE+declarations">SVGs should omit DOCTYPE declarations</a>
+</li>
+<li>
+<a href="#To+be+continued...">To be continued...</a>
+</li>
+</ul>
+</div>
+
+<a name="N10010"></a><a name="Introduction"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+ This page describes changes to Forrest that affect people who are
+ upgrading from 0.4 and earlier to the 0.5 version.
+ Please post your upgrade experiences to the
+ <a href="../mail-lists.html#forrest-dev">forrest-dev mailing list</a>.
+ As more experience is gained, this document will be updated.
+ </p>
+</div>
+
+
+<a name="N1001E"></a><a name="New+Features"></a>
+<h2 class="underlined_10">New Features</h2>
+<div class="section">
+<p>This new version includes many changes, as it as been under
+ development for seven months (in part, awaiting the Cocoon 2.1 release).
+ The following list shows some of the key new features for Forrest 0.5
+ (for the full list of changes, see the
+ <a href="../changes.html">change log</a>).
+ </p>
+<ul>
+
+<li>Significantly faster (100% - 300%) command-line rendering</li>
+
+<li>Docbook support. The DTDs are shipped. Document types are
+ automatically detected by the sitemap and there is a basic stylesheet
+ which converts DocBook documents to intermediate forrest document-v12
+ for standard rendering. For rendering as full DocBook, see
+ <a href="../faq.html#docbook">this FAQ entry</a>.
+ </li>
+
+
+<li>Configuration of URLs to ignore with cli.xconf configuration.</li>
+
+
+<li>Skin enhancements.</li>
+
+
+<li>The document-v12 DTDs are added. You can still use the old
+ document-v11 DTDs if you would rather. However it is easy to upgrade
+ - just change the document type declarations in you project's xdocs
+ and run '<span class="codefrag">forrest validate-xdocs</span>'.</li>
+
+
+<li>Automated handling of documents in Wiki syntax. See the
+ fresh-site example which are generated when you
+ '<span class="codefrag">forrest seed</span>' a new project.</li>
+
+
+<li>The '<span class="codefrag">forrest backcopy</span>' target copies all
+ types of content that you may have edited under the webapp while
+ doing a '<span class="codefrag">forrest run</span>'.</li>
+
+
+<li>Flag for email obfuscation.</li>
+
+
+<li>Support for raw un-processed content. See
+ <a href="../faq.html#link_raw">this FAQ entry</a>.
+ </li>
+
+
+<li>Element <span class="codefrag"><abstract></span> is now rendered in the
+ HTML output.</li>
+
+
+<li>Images scale properly in PDF output. See also
+ <a href="../faq.html#pdf_images">this FAQ entry</a>.
+ </li>
+
+
+<li>Configurable table-of-content depth with new 'toc' element in
+ the <span class="codefrag">skinconf.xml</span> configuration.</li>
+
+</ul>
+</div>
+
+<a name="N10071"></a><a name="Upgrading+the+sitemap"></a>
+<h2 class="underlined_10">Upgrading the sitemap</h2>
+<div class="section">
+<p>
+ In brief, Forrest 0.5 is <em>mostly</em> backwards-compatible for sites that do not define a custom sitemap.
+ Between 0.4 and 0.5, the Forrest sitemap was completely rewritten. Instead of a single sitemap.xmap doing
+ everything, a 'driver' sitemap.xmap now delegates to a number of mounted subsitemaps handling different functional
+ areas. The new sitemap is fully described in the <a href="../docs/sitemap-ref.html">Sitemap Reference</a>.
+ </p>
+<p>Users that have overridden and augmented the Forrest 0.4 sitemap.xmap
+ (run '<span class="codefrag">forrest overrides</span>' to see if your project has)
+ will need to:</p>
+<ol>
+
+<li>Move their overridden sitemap (<span class="codefrag">src/documentation/sitemap.xmap</span>) out the way</li>
+
+<li>Copy the new sitemap, $FORREST_HOME/context/sitemap.xmap, to <span class="codefrag">src/documentation</span>
+</li>
+
+<li>Reapply your customizations to the new sitemap.xmap. Customizations can be determined by comparing your modified
+ sitemap.xmap with
+ <a class="external" href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/conf/sitemap.xmap?rev=1.66&only_with_tag=FORREST_04">original
+ Forrest 0.4 sitemap</a>.</li>
+
+</ol>
+</div>
+
+
+<a name="N1009D"></a><a name="Version-specific+sitemaps"></a>
+<h2 class="underlined_10">Version-specific sitemaps</h2>
+<div class="section">
+<p>Forrest 0.5 now supports <em>version-specific sitemaps</em>. Ie., if your project's overridden sitemap is
+ called <span class="codefrag">sitemap-0.5.xmap</span>, then this sitemap will be used in preference to
+ <span class="codefrag">sitemap.xmap</span>, or any other sitemap-*.xmap variants.</p>
+<p>So if, for example, one has:</p>
+<pre class="code">
+ src/documentation/sitemap.xmap
+ src/documentation/sitemap-0.5.xmap
+ </pre>
+<p>Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use sitemap-0.5.xmap. This means users don't
+ need to all upgrade to 0.5 at once.</p>
+<p>As Forrest 0.5 has been split into multiple sitemaps, this version-specific behaviour is triggered for any
+ *-0.5.xmap file. For example, if one has:</p>
+<pre class="code">
+ src/documentation/sitemap.xmap
+ src/documentation/forrest-0.5.xmap
+ </pre>
+<p>Then Forrest 0.4 will use sitemap.xmap, and Forrest 0.5 will use Forrest's own sitemap.xmap, plus the
+ user-defined forrest-0.5.xmap file.</p>
+<p>The same system prevents future compatibility problems, so Forrest 0.5 should continue to work when future
+ (incompatible) sitemaps are present:</p>
+<pre class="code">
+ src/documentation/sitemap.xmap
+ src/documentation/sitemap-0.5.xmap
+ src/documentation/sitemap-0.6.xmap
+ src/documentation/sitemap-0.7.xmap
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">If your <span class="codefrag">forrest.properties</span> defines the
+ <span class="codefrag">forrest.validate.sitemap.{includes,excludes}</span> properties, these will have to be updated to prevent
+ validation of sitemaps from unused versions. If undefined, Forrest will only validate sitemaps from the
+ current version.</div>
+</div>
+</div>
+
+<a name="N100D4"></a><a name="Excluding+URLs%3A+filterlinks.xsl+removed+and+cli.xconf+added"></a>
+<h2 class="underlined_10">Excluding URLs: filterlinks.xsl removed and cli.xconf added</h2>
+<div class="section">
+<p>In Forrest 0.4 certain URLs could be excluded from command-line
+ processing by overriding and editing
+ <span class="codefrag">filterlinks.xsl</span> and so excluding the link nodes.
+ </p>
+<p>Forrest 0.5 uses the re-written command-line from Cocoon 2.1.1 which,
+ apart from being much faster,
+ <strong>does not use filterlinks.xsl</strong>. Instead, patterns for
+ command-line inclusion and exclusion can be specified in cli.xconf,
+ as described in
+ <a href="../faq.html#ignoring_javadocs">this FAQ entry</a>. There is
+ already a default cli.xconf but you can over-ride that with your own if
+ needed by copying <span class="codefrag">resources/conf/cli.xconf</span> from the Forrest
+ distribution into your project's top-level directory.
+ </p>
+</div>
+
+
+<a name="N100EE"></a><a name="Skin+invocation+changes"></a>
+<h2 class="underlined_10">Skin invocation changes</h2>
+<div class="section">
+<p>Users with custom skins <em>may</em> need to update them, depending on what use they make of passed-in XSLT
+ parameters. If your custom skin does not appear to work with 0.5, look in Forrest's <span class="codefrag">sitemap.xmap</span>
+ for occurrences of <span class="codefrag">{forrest:skin}</span>, and check that the callee (your XSLT) is expecting what the
+ caller (the sitemap) is passing it. Forrest skins can be used as a reference.</p>
+</div>
+
+
+<a name="N10101"></a><a name="Upgrading+skinconf.xml"></a>
+<h2 class="underlined_10">Upgrading skinconf.xml</h2>
+<div class="section">
+<p>Look at the
+ <a class="external" href="http://cvs.apache.org/viewcvs/xml-forrest/src/resources/fresh-site/src/documentation/skinconf.xml.diff?r1=1.7%3AFORREST_04&r2=1.15%3AFORREST_05&diff_format=h">differences
+ for the sample skinconf.xml</a> as a guide.
+ You will need to update the internal DTD and add several new elements.
+ </p>
+</div>
+
+
+<a name="N1010F"></a><a name="Upgrading+forrest.properties"></a>
+<h2 class="underlined_10">Upgrading forrest.properties</h2>
+<div class="section">
+<p>Look at the
+ <a class="external" href="http://cvs.apache.org/viewcvs/xml-forrest/src/resources/fresh-site/forrest.properties.diff?r1=1.20%3AFORREST_04&r2=1.32%3AFORREST_05&diff_format=h">differences
+ for the sample forrest.properties</a> as a guide. Note that
+ project.sitemap has changed to project.sitemap-dir and note that
+ cli.xconf now controls some settings that were previously controlled
+ by forrest.properties, such as project.start-uri
+ </p>
+</div>
+
+
+<a name="N1011D"></a><a name="Run+a+clean+target+after+upgrade"></a>
+<h2 class="underlined_10">Run a clean target after upgrade</h2>
+<div class="section">
+<p>To avoid any issue with old classes being loaded, run a
+ '<span class="codefrag">forrest clean</span>' just after you upgraded to this version.</p>
+</div>
+
+
+<a name="N1012A"></a><a name="SVGs+should+omit+DOCTYPE+declarations"></a>
+<h2 class="underlined_10">SVGs should omit DOCTYPE declarations</h2>
+<div class="section">
+<div class="frame fixme">
+<div class="label">Fixme (forrest-dev)</div>
+<div class="content">Is this note still relevant?</div>
+</div>
+<p>In Forrest 0.5, sites that render SVGs may encounter ClassCastExceptions:</p>
+<pre class="code">
+javax.xml.transform.TransformerException: java.lang.ClassCastException
+ at org.apache.xalan.transformer.TransformerImpl.transformNode(TransformerImpl.java:1326)
+ at org.apache.xalan.transformer.TransformerImpl.run(TransformerImpl.java:3329)
+...</pre>
+<p>There appears to be a bug in Cocoon 2.1.1's SVG component where the DTD associated with SVGs cannot be
+ resolved. The workaround is to edit your <span class="codefrag">src/documentation/resources/images/*.svg</span> files, and
+ comment out the <strong><!DOCTYPE ... ></strong> declaration.</p>
+</div>
+
+
+<a name="N10145"></a><a name="To+be+continued..."></a>
+<h2 class="underlined_10">To be continued...</h2>
+<div class="section">
+<p>..as more issues are discovered/remembered :) Please send feedback to the
+ <a href="../mail-lists.html#forrest-dev">mailing list</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-2004 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.6/docs/upgrading_05.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/docs/upgrading_05.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/upgrading_05.pdf?view=auto&rev=160902
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.6/docs/upgrading_05.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.6/docs/upgrading_06.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/upgrading_06.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/docs/upgrading_06.html (added)
+++ forrest/site/0.6/docs/upgrading_06.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,735 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Upgrading to Apache Forrest 0.6 (v0.6)</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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">O.6 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../howto/index.html">0.6 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-selected" href="../docs/your-project.html">Core</a> | <a class="base-selected" href="../docs/forrestbot.html">ForrestBot</a> | <a class="base-selected" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.10" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.11', '../skin/')" id="menu_selected_1.1.11Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Upgrading</div>
+<div id="menu_selected_1.1.11" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Upgrading to 0.6</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_05.html">Upgrading to 0.5</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">SubProjects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Reference docs</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.3.1', '../skin/')" id="menu_1.3.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/wiki-sample.html">JSPWiki Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/oowriter.html">OpenOffice.Org Writer</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Older Docs</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="upgrading_06.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>Upgrading to Apache Forrest 0.6</h1>
+<div id="motd-area">
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#introduction">Introduction</a>
+</li>
+<li>
+<a href="#new">New Features</a>
+</li>
+<li>
+<a href="#clean">Run a clean target after upgrade</a>
+</li>
+<li>
+<a href="#sync">General upgrade tips</a>
+</li>
+<li>
+<a href="#home">New location of $FORREST_HOME</a>
+</li>
+<li>
+<a href="#copyless">Copyless</a>
+</li>
+<li>
+<a href="#sitemap">Project sitemaps take precedence.</a>
+</li>
+<li>
+<a href="#skin-config-1">Private skins might need changes to document2html.xsl</a>
+</li>
+<li>
+<a href="#skin-config-2">Various additions to skin configuration and new external DTD</a>
+</li>
+<li>
+<a href="#antproxy">forrest.antproxy.xml is obsolete in favor of Ant's <import> task</a>
+</li>
+<li>
+<a href="#ehtml">Deprecation of .ehtml and .ihtml</a>
+</li>
+<li>
+<a href="#jspwiki">Deprecation of .cwiki filename extension to become .jspwiki</a>
+</li>
+<li>
+<a href="#forrestbot">New forrestbot</a>
+</li>
+<li>
+<a href="#dtd">New DTDs</a>
+</li>
+<li>
+<a href="#catalog">SystemIdentifiers for DTDs changed to forrest.apache.org</a>
+</li>
+<li>
+<a href="#local-catalog">Projects can use a local CatalogManager.properties</a>
+</li>
+<li>
+<a href="#skin-names">Skins renamed and deleted</a>
+</li>
+<li>
+<a href="#wholesite">Wholesite.html/pdf</a>
+</li>
+<li>
+<a href="#To+be+continued...">To be continued...</a>
+</li>
+</ul>
+</div>
+
+<a name="N1000D"></a><a name="introduction"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+ This page describes changes to Apache Forrest that affect people who are
+ upgrading to the 0.6 version.
+ If you have other issues, then please discuss on either the
+ <a href="../mail-lists.html#forrest-dev">dev</a> or
+ <a href="../mail-lists.html#forrest-user">user</a>
+ mailing lists.
+ As more experience is gained, this document will be updated.
+ </p>
+<p>
+ (If you are upgrading from a version prior to 0.5 then you may want
+ to see the notes for the <a href="../docs/upgrading_05.html">previous</a>
+ upgrade. However you should be fine with the notes from this 0.6 document.)
+ </p>
+</div>
+
+
+<a name="N10026"></a><a name="new"></a>
+<h2 class="underlined_10">New Features</h2>
+<div class="section">
+<p>
+ The following list shows some of the key new features for Forrest 0.6
+ (for the full list of changes, see the
+ <a href="../changes.html">change log</a>).
+ </p>
+<ul>
+
+<li>Copyless, so now used in place.</li>
+
+<li>Project sitemaps take precedence.</li>
+
+<li>Now using Subversion (SVN) for source control.</li>
+
+<li>New skinconf capabilities and new external skinconf DTD.</li>
+
+<li>New skins use CSS instead of tables. Old skins deprecated.</li>
+
+<li>Forrestbot.</li>
+
+</ul>
+</div>
+
+
+<a name="N10049"></a><a name="clean"></a>
+<h2 class="underlined_10">Run a clean target after upgrade</h2>
+<div class="section">
+<p>To avoid any issue with old classes being loaded, run a
+ '<span class="codefrag">forrest clean</span>' in your project directory, after you
+ upgraded to this version.
+ </p>
+</div>
+
+
+<a name="N10056"></a><a name="sync"></a>
+<h2 class="underlined_10">General upgrade tips</h2>
+<div class="section">
+<p>
+ Synchronise your project's skinconf.xml and forrest.properties files.
+ </p>
+<p>
+ Take advantage of the separation of concerns. In a new workspace,
+ create a fresh
+ '<span class="codefrag">forrest seed</span>' site, then tweak its forrest.properties
+ and skinconf.xml until it reflects your old site.
+ When it is ready, replace your project's skinconf.xml and
+ forrest.properties files.
+ Any remaining issues would concern other aspects of your configuration,
+ such as site.xml and your actual content.
+ </p>
+</div>
+
+
+<a name="N10066"></a><a name="home"></a>
+<h2 class="underlined_10">New location of $FORREST_HOME</h2>
+<div class="section">
+<p>
+ To use the new Forrest, run 'build.sh' or 'build.bat' as normal,
+ then change the FORREST_HOME environment variable to point to
+ forrest/src/core instead of the old forrest-0.5 location
+ (.../build/dist/shbat). Also make sure PATH gets updated to use the new
+ $FORREST_HOME/bin
+ </p>
+</div>
+
+
+<a name="N10070"></a><a name="copyless"></a>
+<h2 class="underlined_10">Copyless</h2>
+<div class="section">
+<p>
+ In essence, Forrest does not create a dist anymore, and uses
+ itself in place. No more useless copying to a separate build space,
+ no more backcopying of your changes, all is used live.
+ </p>
+<p>
+ It improves the build process a lot. Development turnaround time is
+ excellent. You can even tweak the main forrest core stylesheets and
+ see changes immediately.
+ </p>
+</div>
+
+
+<a name="N1007D"></a><a name="sitemap"></a>
+<h2 class="underlined_10">Project sitemaps take precedence.</h2>
+<div class="section">
+<p>With Forrest 0.6 it is now possible for projects to "plugin"
+ to our sitemaps, without needing to copy the main sitemaps and keep
+ them synchonised. This will enable hassle-free update to
+ future Forrest versions.</p>
+<p>
+ If your old project did not use any customised <span class="codefrag">*.xmap</span>
+ files, then your upgrade process will be easy (you can safely skip this
+ section).</p>
+<p>If your project did use custom <span class="codefrag">*.xmaps</span>, with matchers for
+ special circumstances (for example special doctypes that you
+ were handling) then you will need to be prepared to make some changes.
+ Hopefully with the new functionality of Forrest, you can do away with
+ your customisations altogether and just use the Forrest default
+ sitemaps. Try that first. If not, then read on...</p>
+<p>Prior to 0.6 it was possible to replace *any* of the xmaps by placing
+ your own versions in your project directory, these were then copied over
+ to replace
+ the Forrest ones at build time. However, with the move to
+ <a href="#copyless">copyless</a> this no longer happens, instead
+ there is now an extension mechanism for the sitemap (as opposed to
+ a replacement mechanism).</p>
+<p>When upgrading to Forrest 0.6 you need to copy customised matchers
+ in any of your projects <span class="codefrag">*.xmap</span> files into your projects
+ <span class="codefrag">sitemap.xmap</span> file. Any matchers in your project
+ <span class="codefrag">*.xmap</span> files that duplicate ones in Forrests own
+ <span class="codefrag">*.xmaps</span> can now be removed. This will ensure that future
+ enhancements to these matchers in Forrest will automatically be included
+ in your project.</p>
+<p>The good news is that this process makes upgrading to future versions
+ of Forrest much simpler, because your project <span class="codefrag">*.xmap</span> files will
+ contain only your customisations. As a result there will no longer be a
+ need to merge your custom xmaps with the updated ones in upcoming versions of
+ Forrest.</p>
+<p>See <a href="../docs/project-sitemap.html">Using project
+ sitemaps</a> for more details.</p>
+</div>
+
+
+<a name="N100B6"></a><a name="skin-config-1"></a>
+<h2 class="underlined_10">Private skins might need changes to document2html.xsl</h2>
+<div class="section">
+<p>
+ Moved all references to //skinconfig out of the document2html.xsl
+ into the site2xhtml.xsl file. If you have your own skins that were
+ referencing "$config" or "//skinconfig" in the document2html.xsl
+ then you need to make similar changes.
+ For further information, see Issue
+ <a class="external" href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-146">FOR-146</a>.
+ </p>
+</div>
+
+
+<a name="N100C4"></a><a name="skin-config-2"></a>
+<h2 class="underlined_10">Various additions to skin configuration and new external DTD</h2>
+<div class="section">
+<p>
+ Various capabilities have been added to the skinconfig.
+ See the new descriptions in the
+ '<span class="codefrag">forrest seed</span>' site
+ <span class="codefrag">src/documentation/skinconf.xml</span> and synchronise yours.
+ </p>
+<p>For example, to use different colors (e.g. the light blue of the old
+ krysalis skin), CSS colors can be specified in skinconf.xml
+ </p>
+<p>
+ There is now an external DTD which makes it much easier to keep your
+ skinconf.xml synchronised.
+ </p>
+</div>
+
+
+<a name="N100DA"></a><a name="antproxy"></a>
+<h2 class="underlined_10">forrest.antproxy.xml is obsolete in favor of Ant's <import> task</h2>
+<div class="section">
+<p>
+ Projects that use <span class="codefrag">forrest.antproxy.xml</span> via an Ant build
+ task to invoke Forrest, will receive
+ an error message directing them to this document.
+ Please see the <a href="../docs/your-project.html#invoking_from_ant">Invoking
+ Forrest from Ant</a> documentation for instructions on how to use
+ the <import> task to integrate Forrest with your build system.
+ </p>
+</div>
+
+
+<a name="N100EB"></a><a name="ehtml"></a>
+<h2 class="underlined_10">Deprecation of .ehtml and .ihtml</h2>
+<div class="section">
+<p>
+ The .ehtml input file format has been deprecated and will likely be
+ removed in the next release.
+ Please convert all .ehtml files to .html files.
+ If you do '<span class="codefrag">forrest seed</span>' there is a sample html source file.
+ </p>
+</div>
+
+
+<a name="N100F8"></a><a name="jspwiki"></a>
+<h2 class="underlined_10">Deprecation of .cwiki filename extension to become .jspwiki</h2>
+<div class="section">
+<p>
+ Use the .jspwiki filename extension rather than old .cwiki extension.
+ Clarifies that the purpose is the JSPWiki source format.
+ </p>
+</div>
+
+
+<a name="N10102"></a><a name="forrestbot"></a>
+<h2 class="underlined_10">New forrestbot</h2>
+<div class="section">
+<p>
+ The forrestbot and the forrestbot web interface have been completely
+ rewritten. There is no
+ direct way to convert old configurations to new configurations.
+ Please see the <a href="../docs/forrestbot.html">forrestbot
+ documentation</a> for instructions to create buildfiles that work
+ with the new forrestbot.
+ </p>
+</div>
+
+
+<a name="N10110"></a><a name="dtd"></a>
+<h2 class="underlined_10">New DTDs</h2>
+<div class="section">
+<p>
+ Updated all v1.2 DTDs to become v1.3 DTDs (forward compatibility:
+ v1.2 docs will work fine as V1.3). The main change is the addition
+ of a @class attribute to every element, which enables the "extra-css"
+ section in the skinconf to be put to good use.
+ </p>
+<p>
+ Updated the v2.0a DTDs to become v2.0 DTDs (forward incompatibility:
+ v1.2/1.3 docs are not forward-compatible as V2.0).
+ </p>
+<pre class="code">
+Changes from V1.2 to V1.3
+=========================
+document - Addition of class attribute all elements
+faq - Addition of class attribute all elements
+changes - Addition of class attribute all elements
+howto - Addition of class attribute all elements
+todo - Addition of class attribute all elements
+
+Changes from V2.0a to V2.0
+==========================
+document - Addition of class attribute, all elements
+ - Addition of label attribute to note and
+ warning elements (consistent with v1.2/1.3)
+faq - Class attribute, all elements
+changes - New DTD
+howto - New DTD
+todo - New DTD
+
+Changes from V1.3 to V2.0
+=========================
+document - Renamed <link> to <a>
+ - Removed <fork> and <jump>.
+faq - Renamed <part> to <faqsection>
+ - @title attribute on <faqs> is now a nested
+ <title> element
+ - Same changes as in document between 1.3 and 2.0
+changes - Same changes as in document between 1.3 and 2.0
+howto - Same changes as in document between 1.3 and 2.0
+todo - Same changes as in document between 1.3 and 2.0
+</pre>
+</div>
+
+
+<a name="N10121"></a><a name="catalog"></a>
+<h2 class="underlined_10">SystemIdentifiers for DTDs changed to forrest.apache.org</h2>
+<div class="section">
+<p>
+ Everyone should still continue to use the
+ <a href="../docs/catalog.html">Catalog Entity Resolver</a>
+ and that certainly still operates at the core of Forrest using the
+ well-defined PublicIdentifiers.
+ However, some impoverished XML tools do not, so they need to be able
+ to get the DTDs from the website. Some other tools rely on the System
+ Identifier rather than the Public Identifer. See Forrest Issue
+ <a class="external" href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-107">FOR-107</a>.
+ </p>
+<p>
+ In previous versions of Forrest, and maybe in your application if
+ you copied the fresh-site xdocs, there were inconsistent
+ SystemIdentifiers. Some used local filenames, others used
+ apache.org/forrest/dtd/ URIs. In v0.6 we changed to use
+ System Identifiers at forrest.apache.org/dtd/ as resource URLs.
+ You do not need to change them because you are using the entity
+ resolver, but to remain consistent, it probably is best.
+ </p>
+<p>
+ Beware if you have a catalog where the mapping is not declared properly.
+ The Catalog Entity Resolver will miss the local mapping and happily
+ go to the network to get the DTDs. That would cause Forrest to appear
+ to be slow for you, yet it will still operate properly. While we are
+ on that topic, if you use the XSLT document() function - there is a
+ <a class="external" href="http://issues.apache.org/bugzilla/show_bug.cgi?id=28341">Xalan bug 28341</a>
+ for DTD resolution via document() - please help to fix it.
+ Also see the
+ <a class="external" href="http://cocoon.apache.org/2.1/faq/faq-xslt.html">Cocoon FAQ</a>.
+ </p>
+</div>
+
+
+<a name="N10141"></a><a name="local-catalog"></a>
+<h2 class="underlined_10">Projects can use a local CatalogManager.properties</h2>
+<div class="section">
+<p>
+ You can add a local CatalogManager.properties to your
+ project.classes-dir (usually src/documentation/classes/)
+ to define your additional catalogs for DTDs and other entities.
+ Copy a default file from a fresh 'forrest seed site'.
+ </p>
+<p>
+ If you do not add such a configuration file, then there will be a
+ harmless message on startup "CatalogManager.properties not found".
+ </p>
+</div>
+
+
+<a name="N1014E"></a><a name="skin-names"></a>
+<h2 class="underlined_10">Skins renamed and deleted</h2>
+<div class="section">
+<p>Skins now have a naming convention. The default skins are
+ <a href="skins.html">described</a>.</p>
+<p>The old skin names are automatically mapped to the new names. You
+ should change your forrest.properties to use the new names.</p>
+<p>The following skins were renamed (the old names still work, but may not in future releases).</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+<th colspan="1" rowspan="1">0.5 Name</th><th colspan="1" rowspan="1">0.6 Name</th>
+</tr>
+
+<tr>
+<td colspan="1" rowspan="1">krysalis-site</td><td colspan="1" rowspan="1">crust</td>
+</tr>
+
+<tr>
+<td colspan="1" rowspan="1">tigris-style</td><td colspan="1" rowspan="1">tigris</td>
+</tr>
+
+</table>
+<p>The following skins were deleted (the old names still work, but may not in future releases).</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+<th colspan="1" rowspan="1">0.5 Name</th><th colspan="1" rowspan="1">0.6 Alias</th>
+</tr>
+
+<tr>
+<td colspan="1" rowspan="1">forrest-css</td><td colspan="1" rowspan="1">crust</td>
+</tr>
+
+<tr>
+<td colspan="1" rowspan="1">avalon-tigris</td><td colspan="1" rowspan="1">tigris</td>
+</tr>
+
+</table>
+<p>The old "forrest-site" skin is retained for a little while longer,
+ but is deprecated, so please move to one of the other skins.</p>
+</div>
+
+
+<a name="N101AA"></a><a name="wholesite"></a>
+<h2 class="underlined_10">Wholesite.html/pdf</h2>
+<div class="section">
+<p>Instead of using names "site.html/pdf" to create an aggregate page
+ of your entire site, use "wholesite.html/pdf". The old names are still
+ supported for backwards compatibility but they may not be in the
+ future.</p>
+</div>
+
+
+<a name="N101B4"></a><a name="To+be+continued..."></a>
+<h2 class="underlined_10">To be continued...</h2>
+<div class="section">
+<p>...as more issues are discovered/remembered :) Please send feedback
+ to the
+ <a href="../mail-lists.html#forrest-dev">mailing list</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-2004 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.6/docs/upgrading_06.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/docs/upgrading_06.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/upgrading_06.pdf?view=auto&rev=160902
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.6/docs/upgrading_06.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.6/docs/validation.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/validation.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/docs/validation.html (added)
+++ forrest/site/0.6/docs/validation.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,662 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>XML Validation (v0.6)</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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">O.6 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../howto/index.html">0.6 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-selected" href="../docs/your-project.html">Core</a> | <a class="base-selected" href="../docs/forrestbot.html">ForrestBot</a> | <a class="base-selected" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">XML Validation</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.10" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.11', '../skin/')" id="menu_1.1.11Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.11" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_05.html">Upgrading to 0.5</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">SubProjects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Reference docs</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.3.1', '../skin/')" id="menu_1.3.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/wiki-sample.html">JSPWiki Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/oowriter.html">OpenOffice.Org Writer</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Older Docs</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |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</h1>
+<h3>DTDs, catalogs and whatnot</h3>
+<div id="motd-area">
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">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="frame 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="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 class="external" href="http://www.oasis-open.org/committees/entity/spec.html">OASIS Catalog</a>
+ [see <a class="external" href="http://xml.apache.org/commons/components/resolver/resolver-article.html">tutorial</a>]
+ <span class="codefrag">forrest/src/core/context/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/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/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/src/core/context/resources/schema/dtd/document-v13.mod</span>
+ The
+ <span class="codefrag">forrest/src/core/context/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">
+
+COPYRIGHT:
+ Copyright 2002-2004 The Apache Software Foundation
+
+ 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.
+
+==================================================================== -->
+
+
+<!-- =============================================================== -->
+<!-- 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 class="external" 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="frame note">
+<div class="label">Note</div>
+<div class="content">
+
+<a class="external" 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"><!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="frame note">
+<div class="label">Note</div>
+<div class="content">
+ See <a class="external" 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 class="external" 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/src/core/context/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>
+
+</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 class="external" 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>
+ Next specify the full path to your <span class="codefrag">catalog.xcat</span> in the
+ <span class="codefrag">src/documentation/classes/CatalogManager.properties</span> file.
+ Cocoon needs this file when it starts to run. A template file is
+ provided in the "fresh-site" when you do the
+ '<span class="codefrag">forrest seed</span>' to commence a new project.
+ </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="N10103"></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="N10128"></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/catalog.html">configuration notes</a> your favourite
+ editor.
+ </p>
+</div>
+
+
+<a name="N10136"></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">src/core/context/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">src/core/context/resources/schema/relaxng/README.txt</span>
+ and the Ant targets in the various build.xml files.
+ </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-2004 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.6/docs/validation.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/docs/validation.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/validation.pdf?view=auto&rev=160902
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.6/docs/validation.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf