forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [6/34] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/ docs_0_80/howto/ docs_0_80/howto...
Date Thu, 09 Feb 2006 00:26:32 GMT
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



Mime
View raw message