Added: forrest/site/docs_0_100/skins.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/skins.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/skins.html (added) +++ forrest/site/docs_0_100/skins.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,475 @@ + + + + + + + +Default skins (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Default skins

+
+
+ This is documentation for development version v0.10-dev + (More)
+ +
+ + +

Introduction

+
+

+ Forrest supplies a collection of default skins which are configurable + and so should meet the needs of most projects. The aim is to provide + many capabilities so that extra skins are not needed. +

+

+ Note that the new Dispatcher capability will be a better solution. See + Status of Themes: Skins and Dispatcher. +

+
+ + +

Convention for choosing skin names

+
+

+ The skin names are based on playing with the word "skin". See our + technique for + choosing + skin names. A name with "-dev" extension signifies that it is under + development. There is no concept of versions of default skins. New skins + have new names. +

+
+ + +

Skin descriptions and examples

+
+ +

pelt

+

+ Uses CSS "div" and no HTML tables. +

+

+ Examples: Apache Forrest | + snapshot + +

+ +

tigris

+

+ This skin is based on version 1.1 of the + style.tigris.org project. (It + deliberately contravenes our skin naming convention.) +

+

+ Examples: snapshot + +

+ +

plain-dev

+

+ This is a very minimal skin to produce plain HTML documents. Such + capability might be useful to generate a collection of documents for + some off-line product's user help system. +

+

+ Examples: snapshot + +

+
+ + +

Old and deprecated skins

+
+

+ The following skins are retained for a little while longer, but are + deprecated, so please move to one of the other skins. +

+ +

forrest-site

+

+ This is the old skin that we have been dragging around since early + days. Uses HTML tables. +

+

+ Examples: Apache XML + +

+ +

krysalis-site

+

+ Uses HTML tables. +

+

+ Examples: +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/skins.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/status-themes.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/status-themes.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/status-themes.html (added) +++ forrest/site/docs_0_100/status-themes.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,412 @@ + + + + + + + +Status of Themes: Skins and Dispatcher (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Status of Themes: Skins and Dispatcher

+
+
+ This is documentation for development version v0.10-dev + (More)
+ +
+ + +

Skins

+
+

+ "Skins" is the term used to describe the current method for adding + navigation and menu information to the content of a page and applying a + consistent theme for layout, colours, etc. The + "pelt" skin is the only one that the + Forrest project is maintaining. It is configurable enough to meet many + purposes. The main configuration file for skins is the skinconf.xml + file. There is an ability for users to create their own skins, although + we have not encouraged that. +

+

+ For the Forrest-0.9 release, skins are still available and are still the + main mechanism. +

+
+ + +

Dispatcher

+
+

+ "Dispatcher" is the term used to describe a new method which aims to be + a more flexible and complete solution to build a reliable common + structure for documents, incorporate other content, and provide hooks + for applying themes. Themes get configured by structurer definitions (a + wee bit like the skinconf.xml). Although strong progress has been made, + it is still under development. We encourage developers to use Dispatcher + and contribute to its development. See its own documentation in the trunk whiteboard plugins. +

+
+ + +

Plan for future framework

+
+

+ The desired direction is to use xhtml2 as the internal format, move the + current "skins" into a plugin, and develop input plugins for xdoc and + html sources. This would enable any theme engine to be used, whether + that be Skins or Dispatcher or some other. +

+

+ See the development discussion: + Re: + status of skins and dispatcher. This is planned for immediately + following the 0.8 release. New developers please help. +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/status-themes.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/tab-index.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/tab-index.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/tab-index.html (added) +++ forrest/site/docs_0_100/tab-index.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,18 @@ + +0.90 (current)0.100-dev (under development)0.80 (past) Propchange: forrest/site/docs_0_100/tab-index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/upgrading_010.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/upgrading_010.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/upgrading_010.html (added) +++ forrest/site/docs_0_100/upgrading_010.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,485 @@ + + + + + + + +Upgrading to Apache Forrest 0.10-dev (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Upgrading to Apache Forrest 0.10-dev

+
+
+ This is documentation for development version v0.10-dev + (More)
+ +
+ + +

Introduction

+
+
+
Note
+
+ This is the development version of Apache Forrest. + Developers can obtain it from the Subversion + repository. + See the instructions for obtaining and Building + Forrest. + This Note will go away when the release candidate is packed. + Until then see the release notes in preparation (which extracts the + importance=high elements from the changes list). + In site-author + do http://localhost:8888/releaseNotes_current.txt + +
+
+

+ This page describes some changes to Apache Forrest that affect people + who are upgrading to the 0.10-dev 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. +

+

+ (If you are upgrading from a version prior to 0.9 then you will need to + see the notes for the previous upgrade.) +

+
+ + +

New Features

+
+

+ The following list shows some of the key new features. + See also the RELEASE-NOTES document that was provided with + the release package. For the full list + of changes, see the main change log and also + for each plugin. +

+
    + +
  • + Placeholder +
  • + +
+

+ Some new initial plugins are in the "whiteboard". See the entries in the + change log and see each plugin's + documentation and changes log. This includes the new Dispatcher. See + Status of Themes: Skins and Dispatcher. +

+
+ + +

Notes about documentation

+
+

+ After each release, the "Versioned Docs" are copied to form the new + "dev" set. Ideally the docs are then upgraded in readiness for the new + release. This has not been completed for recent releases. In particular + there are example snippets of sitemaps which have not yet been upgraded + to reflect the changes to the sitemaps and the separation of some core + stuff into plugins. See issues + FOR-546 and + FOR-922 and + others. +

+
+ + +

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

+
+ + +

Remove project sitemap if not necessary

+
+

+ It has come to our attention that some people have a + project sitemap + even though they are not using it. Such un-necessary sitemaps should be + removed to avoid maintenance issues. +

+

+ If you do use a project sitemap, then pay attention to the 0.8 upgrade + instructions "Forrest configuration simplification". +

+
+ + +

To be continued...

+
+

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

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/upgrading_010.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/validation.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/validation.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/validation.html (added) +++ forrest/site/docs_0_100/validation.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,795 @@ + + + + + + + +XML validation and entity resolution (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

XML validation and entity resolution

+

DTDs, catalogs and whatnot

+ + + +

Introduction

+
+

+ When a source document uses a DTD to define its structure, then various + abilities are enabled. Forrest handles the annoying side of this and + takes advantage of the benefits. +

+

+ The xml parser must locate the DTDs and other entities. Forrest uses the + XML Catalog Entity Resolver to associate DTD references with local + copies. +

+

+ Forrest also uses the XML Document Type Declaration to effect the + Content Aware Pipelines. Remember that you + are not required to use DTDs (for example Forrest can also respond to a + namespace) so RELAX NG or W3C XML Schema can be used. +

+

+ If you do use DTDs, then forrest is automatically configured to do XML + validation. +

+

+ This document explains both the validation and entity resolution aspects + of the Forrest XML framework. +

+
+ + +

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/main/webapp/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 'documentv20' 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-v20 entities are defined in a reusable 'module': + forrest/main/webapp/resources/schema/dtd/document-v20.mod + The + forrest/main/webapp/resources/schema/dtd/document-v20.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-v20.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">
+
+==================================================================== -->
+
+
+<!-- =============================================================== -->
+<!-- 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 V2.0//EN"
+"document-v20.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-v20.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-v20.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/main/webapp/resources/schema/catalog.xcat for the + document types that Forrest supplies. +

+

+ An additional system-wide catalog can be configured for use by + multiple forrest-based projects. See the "local-catalog" parameter in + main/webapp/WEB-INF/cocoon.xconf + +

+

+ Projects can augment this with their own catalog file located in + ${project.schema-dir}/catalog.xcat to use it you must + specify either the path (full or relative) to your + catalog.xcat in the + CatalogManager.properties file. If you provide a relative + path you must set the property relative-catalogs to + "yes". +

+

+ When Cocoon starts, it reads the + CatalogManager.properties file from your + project.classes-dir. This is usually + src/documentation/classes/ but you can change this in + forrest.properties. When you seed a new site using + forrest seed a sample catalog file is placed in the site + structure, you can use this as a template for your own files. +

+

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

+

+ 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-xdocs' our download file would validate along with all + the others. If something goes wrong, try running 'forrest -v + validate-xdocs' to see the error in more detail. +

+
+ + +

Debugging the Catalog Entity Resolver

+
+

+ If you suspect problems with your project catalog, then raise the + "verbosity" level in + src/documentation/classes/CatalogManager.properties and + re-start forrest. This should show your project catalogs being parsed + and loaded. +

+

+ However this configuration does not show your DTDs being resolved. So + raise the verbosity level in the central configuration at + main/webapp/WEB-INF/properties/core.properties and + re-start forrest. This also shows the main catalogs being loaded and + shows the resolving of every DTD and entity set. +

+

+ When a DTD is successfully resolved you should see the message: + Resolved public: + +

+

+ When debugging such issues, a network monitoring tool (e.g. + ngrep.sf.net) is useful to ensure that all resources are being locally + resolved and not wandering onto the network to find remote copies. +

+
+ + +

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 + main/webapp/resources/schema/relaxng directory. If you want + to know more about this, and perhaps extend it for your own use, then + see main/webapp/resources/schema/relaxng/README.txt and the + Ant targets in the various build.xml files. +

+
+ + +

Validation using Cocoon sitemap and the Cocoon Validation block

+
+

+ The content of pipelines can be validated at various points in the + Cocoon sitemaps using RELAX NG or W3C XML Schema. See + notes. +

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