Added: forrest/site/docs_0_70/build.source.xml
URL:
http://svn.apache.org/viewcvs/forrest/site/docs_0_70/build.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/build.source.xml (added)
+++ forrest/site/docs_0_70/build.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"http://forrest.apache.org/dtd/document-v12.dtd";>
+<document>
+ <header>
+ <title>Building Forrest</title>
+ </header>
+ <body>
+ <section id="getting_from_source">
+ <title>Getting the Forrest source</title>
+ <section>
+ <title>Step-by-step Subversion (SVN) instructions</title>
+ <note>If you are behind a proxy, see
+ <link
href="http://subversion.tigris.org/project_faq.html#proxy";>this
FAQ</link>.</note>
+ <ol>
+ <li>Make sure you have a recent release of a
+ <link href="http://subversion.tigris.org/";>Subversion</link>
+ client installed and properly configured.</li>
+ <li>Read the ASF notes about source repositories and
+ <link href="http://www.apache.org/dev/version-control.html";>version
control</link>.
+ </li>
+ <li>At a command prompt, enter
+ '<code>svn co http://svn.apache.org/repos/asf/forrest/trunk
forrest</code>'
+ (committers should replace <code>http</code> with
<code>https</code>).</li>
+ <li>This will create a directory called "<code>forrest</code>" where
the Forrest source will be stored.</li>
+ </ol>
+ <p>Whenever you want to update your Forrest source tree to the current
+ version, change to the top-level
+"<code>forrest</code>" directory and invoke '<code>svn update</code>'.</p>
+ <p>To see what changes you've made, invoke '<code>svn
status</code>'</p>
+ <p>SVN is really powerful. See
+ <link href="http://svnbook.red-bean.com/";>Version Control with
Subversion</link> - the opensource SVN book.
+ </p>
+ </section>
+
+ <section id="snapshot">
+ <title>Using source snapshots</title>
+ <p>It is preferable to use SVN, but if you cannot for some reason, then
+ <link href="ext:forrest/download">source snapshots</link> are
available
+ (automatically packed every six hours).
+ </p>
+ </section>
+ </section>
+
+ <section id="building">
+ <title>Building and installing Forrest</title>
+<note>
+This document applies to the current 0.7 release version.
+See other instructions for the current development
+<link href="http://forrest.apache.org/docs/dev/build.html";>0.8-dev</link>
version.
+</note>
+ <p>
+ To build Forrest, change directory to '<code>forrest/main</code>', and
+ then type '<code>build</code>' on Windows or '<code>./build.sh</code>'
on
+ Unix. (Requires Java 1.4)
+ If everything is successful, you should see a message similar to:
+ </p>
+ <source xml:space="preserve">
+ *-----------------------------------------------------------------
+ | Installation notice
+ *-----------------------------------------------------------------
+ | You have built the X.Y-dev version of Forrest.
+ | Please set the environment variable FORREST_HOME point to
+ | /svn/forrest
+ | It is recommended to add
+ | unix: $FORREST_HOME/bin: to your $PATH
+ | win: %FORREST_HOME%\bin; to your %PATH%
+ | Then do 'forrest -projecthelp' to list options for the 'forrest' command
+ | More help at http://forrest.apache.org/
+ *-----------------------------------------------------------------
+ </source>
+ <p>
+ As the message says, you need to add the distribution's
<code>bin/</code>
+ ("binary") directory to your PATH variable, so the
<code>'forrest'</code>
+ command is available everywhere:
+ </p>
+ <source xml:space="preserve">
+[~]$ cd /path/to/svn/forrest
+[/svn/forrest]$ export FORREST_HOME=`pwd`
+[/svn/forrest]$ export PATH=$PATH:$FORREST_HOME/bin
+ </source>
+ <warning>
+ After updating the Forrest source from SVN, if there have been certain
types of
+ updates (e.g. Java sources, supporting libraries, build system, etc.)
you will
+ need to clean and build forrest again. Do 'cd forrest/main; build
clean; build".
+ </warning>
+ </section>
+
+ <section id="run">
+ <title>Run Forrest, run!</title>
+ <p>
+ Forrest is now ready to go. To view and edit the local copy of
+ Forrest core documentation, cd to site-author and do
+ '<code>forrest run</code>' to see
+ the local webapp using the bundled Jetty server. Edit something in
+ content/xdocs/*.xml see the immediate effect.
+ </p>
+ <p>
+ The document <link href="site:v0.70//your-project">Using Forrest</link>
is
+ your next step.</p>
+ </section>
+
+</body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_70/build.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_70/cap.source.xml
URL:
http://svn.apache.org/viewcvs/forrest/site/docs_0_70/cap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/cap.source.xml (added)
+++ forrest/site/docs_0_70/cap.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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.
+--><!-- vi: set et sw=2 ts=2 tw=75: --><!DOCTYPE document PUBLIC
"-//APACHE//DTD Documentation V1.3//EN"
"http://forrest.apache.org/dtd/document-v13.dtd";>
+<document>
+ <header>
+ <title>SourceTypeAction (content aware pipelines)</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>SourceTypeAction assigns a "type" (a string) to an XML file. This is
+ done based on information occuring in the header of the XML file, up
to the
+ document (root) element. This type is then returned to the sitemap as a
+ variable with the name 'sourcetype'. If no matching sourcetype could
be be
+ found, null is returned and thus the contents of the action element
will not be
+ executed.</p>
+ <p>SourceTypeAction works by pull-parsing the document and collecting
+ information such as the Public Id, the processing instructions, the
document
+ element local name and namespace, and the xsi:schemaLocation and
+ xsi:noNamespaceSchemaLocation attributes. This information is then
compared
+ with the rules described in the configuration of the
SourceTypeAction.</p>
+ </section>
+ <section>
+ <title>Configuration</title>
+ <p>The action should be declared and configured in the map:actions
+ section of your sitemap. Example:</p>
+ <source xml:space="preserve"><![CDATA[<map:sitemap
xmlns:map="http://apache.org/cocoon/sitemap/1.0";>
+ <map:components>
+ <...>]]>
+ <strong><![CDATA[<map:actions>
+ <map:action name="sourcetype"
+ src="org.apache.forrest.sourcetype.SourceTypeAction">
+ <sourcetype name="download-v1.0">
+ <document-declaration
+ public-id="-//Acme//DTD Download Documentation V1.0//EN" />
+ </sourcetype>
+ </map:action>
+ </map:actions>]]></strong><![CDATA[
+ </map:components>
+ <...>
+</map:sitemap>]]></source>
+ <p>There are other examples in <code>main/webapp/forrest.xmap</code></p>
+ <p>Each sourcetype-tag declares a source type. Inside the sourcetype-tag
+ a number of rules can be defined, described below. The sourcetypes
will be
+ checked in the same order as they are defined in the configuration,
the first
+ sourcetype of which all rules match will be used.</p>
+ <p>These are the available rules:</p>
+ <dl>
+ <dt>document-declaration</dt>
+ <dd>This rule checks the public ID. It takes one attribute
+ <code>public-id</code>.</dd>
+ <dt>document-element</dt>
+ <dd>This rule checks the local name and/or namespace of the document
+ element. These are specified with the attributes
<code>local-name</code> and
+ <code>namespace</code>. At least one of these two is required.</dd>
+ <dt>processing-instruction</dt>
+ <dd>This rule checks a processing instruction. It can take two
+ attributes: <code>target</code> and <code>data</code>. The target
attribute is
+ always required, the data attribute is optional.</dd>
+ <dt>w3c-xml-schema</dt>
+ <dd>This rule checks the value of the xsi:schemaLocation and
+ xsi:noNamespaceSchemaLocation attributes on the document element.
These are
+ specified with the attributes <code>schema-location</code> and
+ <code>no-namespace-schema-location</code>.</dd>
+ </dl>
+ <p>
+ Perhaps you need other methods. Please enhance the source at
+ <code>main/java/org/apache/forrest/sourcetype</code>
+ </p>
+ </section>
+ <section>
+ <title>Usage</title>
+ <p>The source of which the sourcetype must be defined must be specified
+ using the 'src' attribute on the map:act element.</p>
+ <source xml:space="preserve"><![CDATA[<map:act type="sourcetype"
src="{1}">
+...
+</map:act>]]></source>
+ <p>See a real-life example in the advanced section of the
+ <link href="your-project.html#adding_new_content_type_2">Using
Forrest</link>
+ document.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_70/cap.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_70/catalog.source.xml
URL:
http://svn.apache.org/viewcvs/forrest/site/docs_0_70/catalog.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_70/catalog.source.xml (added)
+++ forrest/site/docs_0_70/catalog.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ 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.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"http://forrest.apache.org/dtd/document-v12.dtd";>
+<document>
+ <header>
+ <title>Using Catalog Entity Resolver for local DTDs</title>
+ </header>
+ <body>
+ <section id="overview">
+ <title>Overview</title>
+ <p>
+ This is a collection of notes for configuring the Catalog Entity
+ Resolver with your favourite XML tools (validating parsers and
+ editors).
+ </p>
+ <p>
+ All XML documents declare their ruleset - the Document Type Definition
+ (DTD). When Forrest processes the documents, it uses the Resolver to
+ find Forrest's local copies of the DTDs, rather than trundling out
+ onto the network.
+ </p>
+ <p>
+ Many Java-based XML tools already have an entity resolver, probably
+ the same one that Forrest uses. Many non-Java tools also have an
+ entity resolver. To use these tools with documents based on the
+ Forrest DTDs, you need to configure the tools.
+ </p>
+ <note>
+ The information provided here is not intended to endorse any
+ particular tool.
+ </note>
+ <p>
+ If you have any other configuration tips for a particular tool, then
+ please send them to the forrest-dev mailing list.
+ </p>
+ </section>
+
+ <section id="config">
+ <title>General configuration notes</title>
+ <p>
+ The Forrest DTDs and supporting resources are in the Forrest
+ distribution at <code>main/webapp/resources/schema/</code>
+ </p>
+ <p>
+ Usually all that is required is to direct your tool to the "catalog"
+ supplied by Forrest at either:
+ <code>$FORREST_HOME/main/webapp/resources/schema/catalog.xcat</code>
+ (for XML Catalog) or
+ <code>$FORREST_HOME/main/webapp/resources/schema/catalog</code>
+ (for TR 9401 Catalog).
+ </p>
+ </section>
+
+ <section id="tools">
+ <title>Configuring specific tools</title>
+
+ <section id="system">
+ <title>Operating system catalog</title>
+ <p>
+ Some operating systems already provide a system-wide catalog that
+ is used by many tools. This is usually located at
+ <code>/etc/xml/catalog</code> or at
+ <code>/usr/share/sgml/catalog</code> files.
+ </p>
+ <p>
+ For an XML Catalog, add this line:
+ </p>
+ <source xml:space="preserve"><![CDATA[
+<nextCatalog
+catalog="/usr/local/svn/forrest/main/webapp/resources/schema/catalog.xcat"/>
+ ]]></source>
+ <p>
+ For a TR 9401 Catalog, add this line:
+ </p>
+ <source xml:space="preserve"><![CDATA[
+CATALOG \
+"/usr/local/svn/forrest/main/webapp/resources/schema/catalog"
+ ]]></source>
+ <p>
+ Actually you probably do not want to touch that system catalog,
+ so rather create your own catalog file in your home directory
+ which refers to both the Forrest catalog and your system catalog.
+ </p>
+ </section>
+
+ <section id="xmllint">
+ <title>xmllint validating parser</title>
+ <p>
+ "xmllint" is part of the "libxml2" package.
+ It is very fast and powerful, with are many facilities. It can
+ validate whole directories of files at once.
+ Set the SGML_CATALOG_FILES environment variable.
+ </p>
+ <source xml:space="preserve">
+export SGML_CATALOG_FILES=$SGML_CATALOG_FILES:\
+$FORREST_HOME/main/webapp/resources/schema/catalog
+xmllint --valid --catalogs --noout mydoc.xml
+ </source>
+ </section>
+
+ <section id="vim">
+ <title>Vim</title>
+ <p>
+ The following .vimrc entries are useful:
+ </p>
+ <source xml:space="preserve">
+au FileType xml set efm=%A%f:%l:\ %.%#error:\ %m,%-Z%p^,%-C%.%#
+au FileType xml set makeprg=xmllint\ --noout\ --valid\ --catalogs\ %
+ </source>
+ </section>
+
+ <section id="emacs">
+ <title>Emacs</title>
+ <p>See
+ <link href="http://www.thaiopensource.com/nxml-mode/";>nXML mode</link>
+ and
+ <link href="http://www.dpawson.co.uk/relaxng/nxml/";>FAQ</link>.
+ </p>
+ </section>
+
+ <section id="onsgmls">
+ <title>onsgmls validating parser</title>
+ <p>
+ "onsgmls" is part of the "Open SP" package.
+ You need to also tell it where to find an "SGML declaration".
+ The easiest way is to create your own little "my-catalog" file,
+ containing this:
+ </p>
+ <source xml:space="preserve">
+SGMLDECL "/usr/share/sgml/xml.dcl"
+CATALOG \
+"/usr/local/svn/forrest/main/webapp/resources/schema/catalog"
+ </source>
+ <p>
+ Then point the parser at it:
+ </p>
+ <source xml:space="preserve">
+onsgmls -c path/to/my-catalog -wall -wxml -s mydoc.xml
+ </source>
+ </section>
+
+ <section id="jedit">
+ <title>jEdit - Open Source programmer's text editor</title>
+ <source xml:space="preserve"><![CDATA[
+Select the menu:
+Utilities > Global Options > Plugins:XML > Catalogs
+Select the "+" button, and use the "File System Browser"
+to specify the TR9401 Catalog file:
+"forrest/main/webapp/resources/schema/catalog"
+ ]]></source>
+ <source xml:space="preserve"><![CDATA[
+On version 4.2. Select the menu:
+Plugins > Plugins Options > Plugins:XML > Catalogs
+Select the "+" button, and use the "File System Browser"
+to specify the TR9401 Catalog file:
+"forrest/main/webapp/resources/schema/catalog"
+ ]]></source>
+ </section>
+
+ <section id="oxygenxml">
+ <title>oXygen XML Editor</title>
+ <source xml:space="preserve"><![CDATA[
+Select the menu:
+Options > Preferences > XML Catalog
+Specify the XML Catalog file:
+"forrest/main/webapp/resources/schema/catalog.xcat"
+ ]]></source>
+ </section>
+
+ <section id="xmlspy">
+ <title>xmlspy</title>
+ <source xml:space="preserve"><![CDATA[
+Add the following entry to the file CustomCatalog.xml
+(located in XMLSpy install directory):
+
+<nextCatalog
+catalog="file://localhost/C:/apache/forrest/main/webapp/
+resources/schema/catalog.xcat"/>
+ ]]></source>
+ </section>
+
+ <section id="xxe">
+ <title>XMLmind XML Editor (XXE)</title>
+ <section>
+ <title>XXE v2.5p2 or older</title>
+ <source xml:space="preserve"><![CDATA[
+Select the menu:
+Options > Options > Schema > Add File
+Specify the XML Catalog file:
+"forrest/main/webapp/resources/schema/catalog.xcat"
+ ]]></source>
+ </section>
+ <section>
+ <title>XXE v2.5p3+</title>
+ <p>XXE supports catalogs by automatic detection via configuration
files.
+ Download the <fork
href="http://www.splike.com/howtos/xxe_forrest.html";>XXE
+ Forrest Config</fork> files from splike.com; this also add support
for WYSIWYG
+ editing of forrest documents.
+ Note: This configuration suite has recently been added to the
+ Forrest scratchpad.
+ </p>
+ </section>
+ </section>
+ </section>
+
+ <section id="info">
+ <title>Further information and resources</title>
+ <p>
+ Forrest and Cocoon use the
+ <link href="http://xml.apache.org/commons/components/resolver/";>Catalog
+ Entity Resolver</link>
+ that is provided by the
+ <link href="http://xml.apache.org/commons/";>Apache XML Commons</link>
+ project. The resolver is packaged with the Forrest distribution at
+ <code>lib/core/xml-commons-resolver-x.y.jar</code>
+ </p>
+ <p>
+ Other Forrest documentation has some notes about configuring the
+ entity resolver for your own DTDs. See
+ <link href="site:v0.70//validation">XML Validation</link>.
+ </p>
+ <p>
+ Cocoon has extensive documentation about the entity resolver. See
+ <link href="ext:cocoon/catalogs">Entity resolution with
catalogs</link>.
+ </p>
+ </section>
+</body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_70/catalog.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
