Return-Path: Delivered-To: apmail-forrest-site-svn-archive@locus.apache.org Received: (qmail 94457 invoked from network); 10 May 2007 18:07:18 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 10 May 2007 18:07:18 -0000 Received: (qmail 23895 invoked by uid 500); 10 May 2007 18:07:25 -0000 Delivered-To: apmail-forrest-site-svn-archive@forrest.apache.org Received: (qmail 23863 invoked by uid 500); 10 May 2007 18:07:25 -0000 Mailing-List: contact site-svn-help@forrest.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@forrest.apache.org Delivered-To: mailing list site-svn@forrest.apache.org Received: (qmail 23839 invoked by uid 99); 10 May 2007 18:07:24 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 10 May 2007 11:07:24 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 10 May 2007 11:07:11 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id 750791A985D; Thu, 10 May 2007 11:06:26 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r536953 [10/14] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/bugzilla-patch/my-images/ docs_0_60/howto/multi/ docs_0_60/images/ docs_0_90/ docs_0_90/howto/ docs_0_90/howto/cvs-ssh/ docs_... Date: Thu, 10 May 2007 18:06:19 -0000 To: site-svn@forrest.apache.org From: thorsten@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070510180626.750791A985D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: forrest/site/docs_0_60/todo.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/todo.html?view=auto&rev=536953 ============================================================================== --- forrest/site/docs_0_60/todo.html (added) +++ forrest/site/docs_0_60/todo.html Thu May 10 11:06:09 2007 @@ -0,0 +1,465 @@ + + + + + + + +Todo List (v0.6) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + +
+
+  + +
+
+ + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
+PDF -icon
+ PDF +
+
Font size: +   +   +   +
+

Todo List

+
+ This is documentation for past version v0.6 + (More)
+
+ +
+ + +

high

+
+
    +
  • +[code] + + Please see our Jira + issue tracker for tasks to be done. + Note that the Todo list below is old. We need someone to move those + tasks over to the issue tracker. + → open
    • +
  • +[code] + Rework the menu generation system to make it more flexible. See thread + Fixing + menus + → open
    • +
  • +[code] + Define an 'object model' for Forrest sites, in the form of a Cocoon + pipeline, that defines + - The directory structure of a site + - Site metadata (what currently lives in skinconf.xml + gump.xml + stuff) + - Perhaps site.xml metadata for pages? + + This info can then be made public to the sitemap (via XMLFileModule + attributes) and the stylesheets (through + document(cocoon:/...) calls or inlined with source XML). + → open
    • +
  • +[code] + Finalise the project-definition DTDs, like status.xml and module.xml; + try to come up with a common format with others on community.at.apache.org. + → NKB
    • +
+
+ + + +

medium

+
+
    +
  • +[code] + Finish the RSS feed for status.xml. + Aggregate status.xml and project.xml to have all needed project data. + → NKB
    • +
  • +[docs] + Add stylesheets to render the enhanced status.xml file contents. + → open
    • +
  • +[code] + In skinconf.xml, change 'disable-search' to 'enable-search'. + → JT
    • +
  • +[code] + Enhance the initial forrest toolbar for Mozilla. + See email discussion draft forrest toolbar for Mozilla. + → NKB
    • +
  • +[code] + Fix things so docs can be edited in src/*, and have the changes appear + immediately in the webapp. Involves creating/using an InputModule for + passing 'forrest.skin' and other properties to the sitemap, so we can + avoid the @skin@ hack, and a bit of forrest.build.xml hacking. There + are some @tokens@ in a forrest-site CSS file that also need some sort + of in-place modification. Perhaps a @token@-to-value Transformer could + be the same ${variable}-to-value Transformer mentioned in the RT [3]. + → open
    • +
  • +[code] + Act on 'Entities in XML docs' RT. + I can implement Stefano's + suggested solution quite easily, but is such limited functionality + worth the cost of introducing a proprietary ${variable} syntax? Maybe.. + Best short-term alternative seems to be using the XNI XInclude + processor for pre-validation inclusion. + → open
    • +
  • +[docs] + A lot of the info on the website is outdated. + → open
    • +
  • +[docs] + Using metadata + from site.xml, it would at least be possible to indicate how old the + doc is, and perhaps indicate its relevance from a small controlled + vocabulary. + → open
    • +
  • +[design] + Develop a mechanism for supporting legacy URLs. + See email discussion - + redirects with static sites + → open
    • +
  • +[code] + Fix up and integrate the Forrest Maven plugin. + → open
    • +
+
+ + + +

low

+
+
    +
  • +[code] + Ensure that PHP-like stuff can be embedded easily in Forrest files and + document it. + → open
    • +
  • +[code] + Continue the development of the Libre facility - replacement for + */book.xml + → open
    • +
  • +[docs] + Start a community doc where we list tools such as "code". + → open
    • +
  • +[code] + Migrate to a decent schema language, primarily so that we can use + namespaces in XML docs, allowing things like XInclude, + in-line metadata, + in-line SVG, Jelly snippets, or anything else users can make a + Transformer for. + → open
    • +
  • +[code] + Streamline the process of adding support for new schemas. Ideally we'd + have an auto-download system, e.g. 'forrest-update docbook' would fetch + and install the Docbook DTDs, create catalog entries, sitemap mods etc. + → open
    • +
  • +[code] + Make a CSS Generator and a stylesheet to serialize it to text. + → NKB
    • +
  • +[docs] + Add a document about authoring in XML for beginners.. + → open
    • +
+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_60/todo.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/todo.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/todo.pdf?view=auto&rev=536953 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/todo.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_60/upgrading_06.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/upgrading_06.html?view=auto&rev=536953 ============================================================================== --- forrest/site/docs_0_60/upgrading_06.html (added) +++ forrest/site/docs_0_60/upgrading_06.html Thu May 10 11:06:09 2007 @@ -0,0 +1,748 @@ + + + + + + + +Upgrading to Apache Forrest 0.6 (v0.6) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + +
+
+  + +
+
+ + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
+PDF -icon
+ PDF +
+
Font size: +   +   +   +
+

Upgrading to Apache Forrest 0.6

+
+ This is documentation for past version v0.6 + (More)
+ + + +

Introduction

+
+

+ 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 + dev or + user + mailing lists. + As more experience is gained, this document will be updated. +

+
+ + + +

New Features

+
+

+ The following list shows some of the key new features for Forrest 0.6 +

+
    + +
  • Copyless, so now used in place.
    • + +
  • Project sitemaps take precedence.
    • + +
  • Now using Subversion (SVN) for source control.
    • + +
  • New skinconf capabilities and new external skinconf DTD.
    • + +
  • New skins use CSS instead of tables. Old skins deprecated.
    • + +
  • Forrestbot.
    • + +
+
+ + + +

Run a clean target after upgrade

+
+

To avoid any issue with old classes being loaded, run a + 'forrest clean' in your project directory, after you + upgraded to this version. +

+
+ + + +

General upgrade tips

+
+

+ Synchronise your project's skinconf.xml and forrest.properties files. +

+

+ Take advantage of the separation of concerns. In a new workspace, + create a fresh + 'forrest seed' 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. +

+
+ + + +

New location of $FORREST_HOME

+
+

+ 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 +

+
+ + + +

Copyless

+
+

+ 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. +

+

+ 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. +

+
+ + + +

Project sitemaps take precedence.

+
+

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.

+

+ If your old project did not use any customised *.xmap + files, then your upgrade process will be easy (you can safely skip this + section).

+

If your project did use custom *.xmaps, 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...

+

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 + copyless this no longer happens, instead + there is now an extension mechanism for the sitemap (as opposed to + a replacement mechanism).

+

When upgrading to Forrest 0.6 you need to copy customised matchers + in any of your projects *.xmap files into your projects + sitemap.xmap file. Any matchers in your project + *.xmap files that duplicate ones in Forrests own + *.xmaps can now be removed. This will ensure that future + enhancements to these matchers in Forrest will automatically be included + in your project.

+

Move your old sitemap out of the way, copy a default one from a fresh + 'forrest seed', and add the specific matches that you require.

+

The good news is that this process makes upgrading to future versions + of Forrest much simpler, because your project *.xmap 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.

+

See Using project + sitemaps for more details.

+
+ + + +

Private skins might need changes to document2html.xsl

+
+

+ 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 + FOR-146. +

+
+ + + +

Various additions to skin configuration and new external DTD

+
+

+ Various capabilities have been added to the skinconfig. + See the new descriptions in the + 'forrest seed' site + src/documentation/skinconf.xml and synchronise yours. +

+

For example, to use different colors (e.g. the light blue of the old + krysalis skin), CSS colors can be specified in skinconf.xml +

+

+ There is now an external DTD which makes it much easier to keep your + skinconf.xml synchronised. +

+
+ + + +

forrest.antproxy.xml is obsolete in favor of Ant's <import> task

+
+

+ Projects that use forrest.antproxy.xml via an Ant build + task to invoke Forrest, will receive + an error message directing them to this document. + Please see the Invoking + Forrest from Ant documentation for instructions on how to use + the <import> task to integrate Forrest with your build system. +

+
+ + + +

Deprecation of .ehtml and .ihtml

+
+

+ 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 'forrest seed' there is a sample html source file. +

+
+ + + +

Deprecation of .cwiki filename extension to become .jspwiki

+
+

+ Use the .jspwiki filename extension rather than old .cwiki extension. + Clarifies that the purpose is the JSPWiki source format. +

+
+ + + +

New forrestbot

+
+

+ 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 forrestbot + documentation for instructions to create buildfiles that work + with the new forrestbot. +

+
+ + + +

New DTDs

+
+

+ 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. +

+

+ Updated the v2.0a DTDs to become v2.0 DTDs (forward incompatibility: + v1.2/1.3 docs are not forward-compatible as V2.0). +

+
+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
+
+
+ + + +

SystemIdentifiers for DTDs changed to forrest.apache.org

+
+

+ Everyone should still continue to use the + Catalog Entity Resolver + 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 + FOR-107. +

+

+ 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. +

+

+ 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 + Xalan bug 28341 + for DTD resolution via document() - please help to fix it. + Also see the + Cocoon FAQ. +

+
+ + + +

Projects can use a local CatalogManager.properties

+
+

+ 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'. +

+

+ If you do not add such a configuration file, then there will be a + harmless message on startup "CatalogManager.properties not found". +

+
+ + + +

Skins renamed and deleted

+
+

Skins now have a naming convention. The default skins are + described.

+

The old skin names are automatically mapped to the new names. You + should change your forrest.properties to use the new names.

+

The following skins were renamed (the old names still work, but may not in future releases).

+ + + + + + + + + + + + + + +
0.5 Name0.6 Name
krysalis-sitecrust
tigris-styletigris
+

The following skins were deleted (the old names still work, but may not in future releases).

+ + + + + + + + + + + + + + +
0.5 Name0.6 Alias
forrest-csscrust
avalon-tigristigris
+

The old "forrest-site" skin is retained for a little while longer, + but is deprecated, so please move to one of the other skins.

+
+ + + +

Wholesite.html/pdf

+
+

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.

+
+ + + +

To be continued...

+
+

...as more issues are discovered/remembered :) Please send feedback + to the + mailing list.

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_60/upgrading_06.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/upgrading_06.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/upgrading_06.pdf?view=auto&rev=536953 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/upgrading_06.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_60/validation.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/validation.html?view=auto&rev=536953 ============================================================================== --- forrest/site/docs_0_60/validation.html (added) +++ forrest/site/docs_0_60/validation.html Thu May 10 11:06:09 2007 @@ -0,0 +1,681 @@ + + + + + + + +XML Validation (v0.6) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + +
+
+  + +
+
+ + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
+PDF -icon
+ PDF +
+
Font size: +   +   +   +
+

XML Validation

+

DTDs, catalogs and whatnot

+
+ This is documentation for past version v0.6 + (More)
+ + + +

XML validation

+
+

+ 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 + 'forrest validate' in the project root directory. +

+

+ For an XML file to be valid, it must 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. +

+

+ 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 + forrest.properties: +

+
+##############
+# 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=
+
+

+ For example, to avoid validating + ${project.xdocs-dir}/slides.xml and everything inside the + ${project.xdocs-dir}/manual/ directory, add this to + forrest.properties: +

+
forrest.validate.xdocs.excludes=slides.xml, manual/**
+
+
Note
+
+ The failonerror properties only work for files validated + with Ant's <xmlvalidate> and not (yet) for those validated + with <jing>, where failonerror defaults to + true. +
+
+
+ + + +

Validating new XML types

+
+

+ Forrest provides an OASIS Catalog + [see tutorial] + forrest/src/core/context/resources/schema/catalog.xcat + as a means of associating public identifiers + (e.g. -//APACHE//DTD Documentation V1.1//EN above) with DTDs. + If you add a new content type, you + should add the DTD to ${project.schema-dir}/dtd/ and add + an entry to the ${project.schema-dir}/catalog.xcat file. This + section describes the details of this process. +

+ +

Creating or extending a DTD

+

+ 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 download format + 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: +

+
+<!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>
+
+

+ The document-v13 entities are defined in a reusable 'module': + forrest/src/core/context/resources/schema/dtd/document-v13.mod + The + forrest/src/core/context/resources/schema/dtd/document-v13.dtd + file provides a full description and basic example of how to pull in + modules. In our example, our DTD reuses modules + common-charents-v10.mod and + document-v13.mod. Here is the full DTD, with + explanation to follow. +

+
+<!-- ===================================================================
+
+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-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+==================================================================== -->
+
+
+<!-- =============================================================== -->
+<!-- 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 -->
+<!-- =============================================================== -->
+
+

This custom DTD should be placed in your project resources + directory at src/documentation/resources/schema/dtd/ +

+

+ The <!ENTITY % ... > blocks are so-called + parameter + entities. They are like macros, whose content will be + inserted when a parameter-entity reference, like + %common-charents; or %document; is + inserted. +

+

+ 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 %document; 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. +

+

+ We now have a DTD for the 'download' document type. +

+
+
Note
+
+ +Chapter + 5: Customizing DocBook of Norman Walsh's "DocBook: The + Definitive Guide" gives a complete overview of the process of + customizing a DTD. +
+
+ +

Associating DTDs with document types

+

+ Recall that our DOCTYPE declaration for our download document type + is: +

+
<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+          "download-v10.dtd">
+
+

+ We only care about the quoted section after PUBLIC, 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.

+
+
Note
+
+ See this article for a good + introduction to catalogs and the Cocoon documentation + Entity resolution with catalogs. +
+
+

+ Forrest provides a standard catalog file at + forrest/src/core/context/resources/schema/catalog.xcat + for the document + types that Forrest provides. Projects can augment this with their + own catalog file located in + ${project.schema-dir}/catalog.xcat + +

+

+ 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: +

+
<?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>
+

+ The format is described in the + spec, and is fairly simple and very powerful. + The "public" elements map + a public identifier to a DTD (relative to the catalog file). +

+

+ Next specify the full path to your catalog.xcat in the + src/documentation/classes/CatalogManager.properties file. + Cocoon needs this file when it starts to run. A template file is + provided in the "fresh-site" when you do the + 'forrest seed' to commence a new project. +

+

+ 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 'forrest validate' + our download file would validate along with all the others. If + something goes wrong, try running 'forrest -v validate' to + see the error in more detail. Remember to raise the "verbosity" + level in cocoon.xconf if you suspect problems + with your catalog. +

+
+ + + +

Referring to entities

+
+

+ Look at the source of this document + (xdocs/docs/validation.xml) and see how the entity set + "Numeric and Special Graphic" is declared in the + document type declaration. +

+ + + + + + + + + + +
ISOnum.pen&half;½
+
+ + + +

Validating in an XML editor

+
+

+ 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 + configuration notes your favourite + editor. +

+
+ + + +

Validation using RELAX NG

+
+

+ 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. +

+

+ The RNG grammars to do this are located in the + src/core/context/resources/schema/relaxng directory. + If you want to + know more about this, and perhaps extend it for your own use, then + see src/core/context/resources/schema/relaxng/README.txt + and the Ant targets in the various build.xml files. +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_60/validation.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_60/validation.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/validation.pdf?view=auto&rev=536953 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_60/validation.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf