You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by up...@apache.org on 2003/12/30 22:51:52 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/offline configuration.xml ant.xml cli.xml index.xml
upayavira 2003/12/30 13:51:52
Modified: src/documentation/xdocs/userdocs/offline ant.xml cli.xml
index.xml
Added: src/documentation/xdocs/userdocs/offline configuration.xml
Log:
Docs for the Cocoon Ant task, and related changes
Revision Changes Path
1.4 +57 -21 cocoon-2.1/src/documentation/xdocs/userdocs/offline/ant.xml
Index: ant.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/offline/ant.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ant.xml 12 Oct 2003 13:04:49 -0000 1.3
+++ ant.xml 30 Dec 2003 21:51:52 -0000 1.4
@@ -4,7 +4,7 @@
<document>
<header>
<title>Offline Page Generation with Apache Ant</title>
- <version>0.9</version>
+ <version>1.0</version>
<type>Technical document</type>
<authors><person name="Upayavira" email="upayavira@apache.org"/>
</authors>
@@ -12,33 +12,69 @@
</header>
<body>
<s1 title="Overview">
- <p>Apache Ant can be used to start Cocoon in its Offline mode. Whilst a specific
- Cocoon Ant task is planned, at present it can be invoked by starting the
- command line interface using a standard Java task.
+ <p>Apache Ant can be used to start Cocoon in its Offline mode. A specific Ant
+ task is available, allowing the user to embed the Cocoon configuration
+ information into Ant's build script.
</p>
</s1>
+ <s1 title="Configuring the Ant task">
+ <p>The main configuration for the task is to specify a <code>cocoon.context</code> property which points to the
+ Cocoon webapp from which the pages or site are to be generated.</p>
+ <p>From this property, a classpath can be created. By default, this should point to <code>WEB-INF/classes</code>
+ and all jar files in <code>WEB-INF/lib</code>. Futher classpaths can be added if they are needed.</p>
+ <p>The taskdef requires this classpath in order to invoke the Ant task, and the task itself needs the classpath in
+ order to invoke Cocoon.</p>
+ <p>Beyond these configurations, the rest are the same as is used by the <link href="cli.html">Command Line interface</link>,
+ and is detailed on the <link href="configuration.html">configuration</link> page.</p>
+ </s1>
<s1 title="Sample Ant Task">
- <p>A sample Ant task would be as follows:</p>
+ <p>A sample ant build file is shown below. This sample shows only that which is required to configure the
+ Ant task. For further details of configuring Cocoon, see the <link href="configuration.html">configuration</link>
+ page.</p>
<source>
<![CDATA[
-<java classname="org.apache.cocoon.Main" fork="true"
-dir="${build.context}"
- failonerror="true" maxmemory="128m">
- <arg value="-xcli.xconf"/>
- <arg value="index.html"/>
- <classpath>
- <path refid="classpath"/>
- <fileset dir="${build.dir}">
- <include name="*.jar"/>
- </fileset>
- <pathelement location="${tools.jar}"/>
- <pathelement location="${build.context}/WEB-INF/classes"/>
- </classpath>
- </java>
+<?xml version="1.0"?>
+<project default="cocoon" basedir=".">
+
+ <property name="cocoon.context" value="../cocoon/build/webapp"/>
+ <path id="cocoon.classpath">
+ <dirset dir="${cocoon.context}/WEB-INF/classes"/>
+ <fileset dir="${cocoon.context}/WEB-INF/lib" includes="*.jar"/>
+ </path>
+
+ <taskdef name="cocoon" classname="org.apache.cocoon.CocoonTask" classpathref="cocoon.classpath"/>
+
+ <target name="cocoon">
+ <cocoon verbose="true"
+ classpathref="cocoon.classpath"
+ follow-links="true"
+ precompile-only="false"
+ confirm-extensions="false"
+ context-dir="${cocoon.context}"
+ config-file="WEB-INF/cocoon.xconf"
+ work-dir="build/work"
+ dest-dir="build/dest"
+ default-filename="index.html"
+ accept="*/*">
+
+ <broken-links type="xml"
+ file="brokenlinks.xml"
+ generate="false"
+ extension=".error"/>
+
+ <logging log-kit="${cocoon.context}/WEB-INF/logkit.xconf" logger="cli" level="DEBUG" />
+
+ <uris name="site" follow-links="true">
+ <uri type="append"
+ src-prefix=""
+ src="index.html"
+ dest="${cocoon.context}/build/dest/"/>
+ </uris>
+ </cocoon>
+ </target>
+</project>
]]> </source>
- <p>This makes use of the Cocoon Command Line Interface's xconf configuration file. See
- <link href="cli.html">command line</link> page for details about how to use this file.</p>
</s1>
</body>
</document>
1.4 +3 -261 cocoon-2.1/src/documentation/xdocs/userdocs/offline/cli.xml
Index: cli.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/offline/cli.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- cli.xml 12 Oct 2003 13:04:49 -0000 1.3
+++ cli.xml 30 Dec 2003 21:51:52 -0000 1.4
@@ -4,7 +4,7 @@
<document>
<header>
<title>Offline Page Generation with the Command Line Interface</title>
- <version>0.9</version>
+ <version>1.0</version>
<type>Technical document</type>
<authors><person name="Upayavira" email="upayavira@apache.org"/>
</authors>
@@ -36,266 +36,8 @@
<s2 title="Using an Xconf file">
<p>To start the CLI using an xconf file, on Unix do <code>./cocoon.sh cli -x <xconf file></code>
or on Windows: <code>cocoon cli -x <xconf file></code>.</p>
- <p>A sample xconf file, with comments describing each option, is included below.</p>
- <source>
-<![CDATA[
-<?xml version="1.0"?>
-
-<!--+
- | This is the Apache Cocoon command line configuration file.
- | Here you give the command line interface details of where
- | to find various aspects of your Cocoon installation.
- |
- | If you wish, you can also use this file to specify the URIs
- | that you wish to generate.
- |
- | The current configuration information in this file is for
- | building the Cocoon documentation. Therefore, all links here
- | are relative to the build context dir, which, in the build.xml
- | file, is set to ${build.context}
- |
- | Options:
- | verbose: increase amount of information presented
- | to standard output (default: false)
- | follow-links: whether linked pages should also be
- | generated (default: true)
- | precompile-only: precompile sitemaps and XSP pages, but
- | do not generate any pages (default: false)
- | confirm-extensions: check the mime type for the generated page
- | and adjust filename and links extensions
- | to match the mime type
- | (e.g. text/html->.html)
- |
- | Note: Whilst using an xconf file to configure the Cocoon
- | Command Line gives access to more features, the use of
- | command line parameters is more stable, as there are
- | currently plans to improve the xconf format to allow
- | greater flexibility. If you require a stable and
- | consistent method for accessing the CLI, it is recommended
- | that you use the command line parameters to configure
- | the CLI.</note>
- |
- +-->
-
-<cocoon verbose="true"
- follow-links="true"
- precompile-only="false"
- confirm-extensions="true">
-
- <!--+
- | The context directory is usually the webapp directory
- | containing the sitemap.xmap file.
- |
- | The config file is the cocoon.xconf file.
- |
- | The work directory is used by Cocoon to store temporary
- | files and cache files.
- |
- | The destination directory is where generated pages will
- | be written (assuming the 'simple' mapper is used, see
- | below)
- +-->
- <context-dir>build/webapp</context-dir>
- <config-file>WEB-INF/cocoon.xconf</config-file>
- <work-dir>build/work</work-dir>
- <dest-dir>build/dest</dest-dir>
-
- <!--+
- | Broken link reporting options:
- | Report into a text file, one link per line:
- | <broken-links type="text" report="filename"/>
- | Report into an XML file:
- | <broken-links type="xml" report="filename"/>
- | Ignore broken links (default):
- | <broken-links type="none"/>
- |
- | Two attributes to this node specify whether a page should
- | be generated when an error has occured. 'generate' specifies
- | whether a page should be generated (default: true) and
- | extension specifies an extension that should be appended
- | to the generated page's filename (default: none)
- |
- | Using this, a quick scan through the destination directory
- | will show broken links, by their filename extension.
- +-->
- <broken-links type="xml"
- file="brokenlinks.xml"
- generate="false"
- extension=".error"/>
-
- <!--+
- | Load classes at startup. This is necessary for generating
- | from sites that use SQL databases and JDBC.
- | The <load-class> element can be repeated if multiple classes
- | are needed.
- +-->
- <!--
- <load-class>org.firebirdsql.jdbc.Driver</load-class>
- -->
-
- <!--+
- | Configures logging.
- | The 'log-kit' parameter specifies the location of the log kit
- | configuration file (usually called logkit.xconf.
- |
- | Logger specifies the logging category (for all logging prior
- | to other Cocoon logging categories taking over)
- |
- | Available log levels are:
- | DEBUG: prints all level of log messages.
- | INFO: prints all level of log messages except DEBUG
- | ones.
- | WARN: prints all level of log messages except DEBUG
- | and INFO ones.
- | ERROR: prints all level of log messages except DEBUG,
- | INFO and WARN ones.
- | FATAL_ERROR: prints only log messages of this level
- +-->
- <logging log-kit="build/webapp/WEB-INF/logkit.xconf" logger="cli" level="DEBUG" />
-
- <!--+
- | Specifies the filename to be appended to URIs that
- | refer to a directory (i.e. end with a forward slash).
- +-->
- <default-filename>index.html</default-filename>
-
- <!--+
- | Specifies a user agent string to the sitemap when
- | generating the site.
- +-->
- <!--
- <user-agent>xxx</user-agent>
- -->
-
- <!--+
- | Specifies an accept string to the sitemap when generating
- | the site.
- +-->
- <accept>*/*</accept>
-
- <!--+
- | Specifies which URIs should be included or excluded, according
- | to wildcard patterns.
- |
- | By default, all URIs are included. If both include and exclude
- | patterns are specified, a URI is first checked against the
- | include patterns, and then against the exclude patterns.
- |
- | Multiple patterns can be given, using muliple include or exclude
- | nodes.
- |
- | The order of the elements is not significant, as only the first
- | successful match of each category is used.
- |
- | Currently, only the complete source URI can be matched (including
- | any URI prefix). Future plans include destination URI matching
- | and regexp matching. If you have requirements for these, contact
- | dev@cocoon.apache.org.
- +-->
- <include pattern="**"/>
- <exclude pattern="docs/apidocs/**"/>
-
-<!-- <include-links extension=".html"/>-->
-
- <!--+
- | <uri> nodes specify the URIs that should be generated, and
- | where required, what should be done with the generated pages.
- |
- | Append: append the generated page's URI to the end of the
- | source URI:
- |
- | <uri type="append" src-prefix="documents/" src="index.html"
- | dest="build/dest/"/>
- |
- | Replace: Completely ignore the generated page's URI - just
- | use the destination URI:
- |
- | <uri type="replace" src-prefix="documents/" src="index.html"
- | dest="build/dest/docs.html"/>
- |
- | Insert: Insert generated page's URI into the destination
- | URI at the point marked with a * (example uses fictional
- | zip protocol)
- |
- | <uri type="insert" src-prefix="documents/" src="index.html"
- | dest="zip://*.zip/page.html"/>
- |
- | If in any of these scenarios, the dest attribute is omitted,
- | the value provided globally using the <dest-dir> node will
- | be used.
- +-->
-
- <uri type="replace"
- src-prefix="samples/"
- src="hello-world/hello.html"
- dest="build/dest/hello-world.html"/>
-
- <!--+
- | <uri> nodes can be grouped together in a <uris> node. This
- | enables a group of URIs to share properties. The following
- | properties can be set for a group of URIs:
- | * follow-links: should pages be crawled for links
- | * confirm-extensions: should file extensions be checked
- | for the correct mime type
- | * src-prefix: all source URIs should be
- | pre-pended with this prefix before
- | generation. The prefix is not
- | included when calculating the
- | destination URI
- | * dest: the base destination URI to be
- | shared by all pages in this group
- | * type: the method to be used to calculate
- | the destination URI. See above
- | section on <uri> node for details.
- |
- | Each <uris> node can have a name attribute. When a name
- | attribute has been specified, the -n switch on the command
- | line can be used to tell Cocoon to only process the URIs
- | within this URI group. When no -n switch is given, all
- | <uris> nodes are processed. Thus, one xconf file can be
- | used to manage multiple sites.
- +-->
- <uris name="docs" follow-links="true">
- <uri type="append" src-prefix="docs/" src="index.html"
- dest="build/dest/" />
- </uris>
-
- <uris name="samples" follow-links="false"
- confirm-extensions="true"
- src-prefix="samples/"
- dest="build/dest/examples/"
- type="append"
- >
- <uri src=""/>
- <uri src="hello-world/"/>
- <uri src="hello-world/hello.html"/>
- <uri src="hello-world/hello.xml"/>
- </uris>
-
- <!--+
- | File containing URIs (plain text, one per
- | line).
- +-->
- <!--
- <uri-file></uri-file>
- -->
-
-</cocoon>
-]]>
- </source>
- <s3 title="Broken Link Handling">
- <p>The xconf method allows for more sophisticated broken link handling. The
- user can select to have broken links reported to a file, this file being
- either text or XML.</p>
- <p>When this file is plain text, it will have one link URI per line.</p>
- <p>When this file is in XML, it will detail a message explaining the reason
- for the broken link, as well as the URI of the link.</p>
- <p>It is also possible to specify whether an error page should be generated
- in the place of the broken page (based upon the configured
- <code><map:handle-errors></code> code in the sitemap). If required,
- an extension can be appended to the original file's URI to signify that
- it is an error page (e.g. <code>.error</code>).</p>
- </s3>
+ <p>For a sample xconf file, with comments describing each option, see the
+ <link href="configuration.html">configuration</link> page.</p>
</s2>
<s2 title="Command Line Parameters">
<p>You can get a listing of the available parameters on unix with
1.4 +15 -2 cocoon-2.1/src/documentation/xdocs/userdocs/offline/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/offline/index.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index.xml 12 Oct 2003 13:04:49 -0000 1.3
+++ index.xml 30 Dec 2003 21:51:52 -0000 1.4
@@ -4,7 +4,7 @@
<document>
<header>
<title>Offline Page Generation</title>
- <version>0.9</version>
+ <version>1.0</version>
<type>Technical document</type>
<authors><person name="Upayavira" email="upayavira@apache.org"/>
</authors>
@@ -22,7 +22,7 @@
<p>At present, this can be done in three ways:</p>
<ul>
<li><link href="cli.html">Command Line Interface</link></li>
- <li><link href="ant.html">Using Ant</link></li>
+ <li><link href="ant.html">Using Ant Task</link></li>
<li><link href="bean.html">Cocoon Bean</link></li>
</ul>
<p>This document explains the general concepts that are shared by all of these approaches.
@@ -185,6 +185,19 @@
page, it is considered 'broken'.</p>
<p>Exactly what is done when a broken link is found depends upon the method used to evoke
Cocoon. See related pages for specific details.</p>
+ <s2 title="Broken Link Handling using xconf Configuration method">
+ <p>The xconf method allows for more sophisticated broken link handling. The
+ user can select to have broken links reported to a file, this file being
+ either text or XML.</p>
+ <p>When this file is plain text, it will have one link URI per line.</p>
+ <p>When this file is in XML, it will detail a message explaining the reason
+ for the broken link, as well as the URI of the link.</p>
+ <p>It is also possible to specify whether an error page should be generated
+ in the place of the broken page (based upon the configured
+ <code><map:handle-errors></code> code in the sitemap). If required,
+ an extension can be appended to the original file's URI to signify that
+ it is an error page (e.g. <code>.error</code>).</p>
+ </s2>
</s1>
<s1 title="Precompiling XSPs">
<p>When used offline, Cocoon can precompile XSP pages. If no URIs are specified, it will scan all directories
1.1 cocoon-2.1/src/documentation/xdocs/userdocs/offline/configuration.xml
Index: configuration.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Configuration of Cocoon for Offline Use</title>
<version>1.0</version>
<type>Technical document</type>
<authors><person name="Upayavira" email="upayavira@apache.org"/>
</authors>
<abstract>This document explains how to configure Cocoon for offline page and site generation.</abstract>
</header>
<body>
<s1 title="Overview">
<p>This page details the {{xconf}} configuration format for configuring Cocoon's offline
page and site generation capabilities.</p>
<p>This page gives details of how configure Cocoon. Details of the concepts behind
offline page generation are given on the offline generation
<link href="index.html">overview</link> page.</p>
</s1>
<s1 title="The xconf Configuration Format">
<p>The {{xconf}} configuration format can be used both within the Cocoon
<link href="cli.html">Command Line Interface</link> and within the
<link href="ant.html">Cocoon Ant Task</link>.</p>
</s1>
<s1 title="Sample xconf File">
<p>Below is a sample XConf file. The details of the file are detailed as comments within
this sample itself.</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<!--+
| This is an Apache Cocoon command line configuration file.
| Here you give the command line interface details of where
| to find various aspects of your Cocoon installation.
|
| If you wish, you can also use this file to specify the URIs
| that you wish to generate.
|
| The current configuration information in this file is for
| building the Cocoon documentation. Therefore, all links here
| are relative to the build context dir, which, in the build.xml
| file, is set to ${build.context}
|
| Options:
| verbose: increase amount of information presented
| to standard output (default: false)
| follow-links: whether linked pages should also be
| generated (default: true)
| precompile-only: precompile sitemaps and XSP pages, but
| do not generate any pages (default: false)
| confirm-extensions: check the mime type for the generated page
| and adjust filename and links extensions
| to match the mime type
| (e.g. text/html->.html)
| context-dir: The context directory is usually the webapp
| directory containing the sitemap.xmap file.
| config-file: The config file is the cocoon.xconf file,
| usually found within the WEB-INF folder
| work-dir: The work directory is used by Cocoon to
| store temporary files and cache files.
| dest-dir: The destination directory is where generated
| pages will be written (assuming the 'simple'
| mapper is used, see below)
|
+-->
<cocoon verbose="true"
follow-links="true"
precompile-only="false"
confirm-extensions="true"
context-dir="build/webapp/xconf"
config-file="WEB-INF/cocoon.xconf"
work-dir="build/work"
dest-dir="build/dest">
<!--+
| Broken link reporting options:
| Report into a text file, one link per line:
| <broken-links type="text" report="filename"/>
| Report into an XML file:
| <broken-links type="xml" report="filename"/>
| Ignore broken links (default):
| <broken-links type="none"/>
|
| Two attributes to this node specify whether a page should
| be generated when an error has occured. 'generate' specifies
| whether a page should be generated (default: true) and
| extension specifies an extension that should be appended
| to the generated page's filename (default: none)
|
| Using this, a quick scan through the destination directory
| will show broken links, by their filename extension.
+-->
<broken-links type="xml"
file="brokenlinks.xml"
generate="false"
extension=".error"/>
<!--+
| Load classes at startup. This is necessary for generating
| from sites that use SQL databases and JDBC.
| The <load-class> element can be repeated if multiple classes
| are needed.
+-->
<!--
<load-class>org.firebirdsql.jdbc.Driver</load-class>
-->
<!--+
| Configures logging.
| The 'log-kit' parameter specifies the location of the log kit
| configuration file (usually called logkit.xconf.
|
| Logger specifies the logging category (for all logging prior
| to other Cocoon logging categories taking over)
|
| Available log levels are:
| DEBUG: prints all level of log messages.
| INFO: prints all level of log messages except DEBUG
| ones.
| WARN: prints all level of log messages except DEBUG
| and INFO ones.
| ERROR: prints all level of log messages except DEBUG,
| INFO and WARN ones.
| FATAL_ERROR: prints only log messages of this level
+-->
<logging log-kit="build/webapp/WEB-INF/logkit.xconf" logger="cli" level="DEBUG" />
<!--+
| Specifies the filename to be appended to URIs that
| refer to a directory (i.e. end with a forward slash).
+-->
<default-filename>index.html</default-filename>
<!--+
| Specifies a user agent string to the sitemap when
| generating the site.
+-->
<!--
<user-agent>xxx</user-agent>
-->
<!--+
| Specifies an accept string to the sitemap when generating
| the site.
+-->
<accept>*/*</accept>
<!--+
| Specifies which URIs should be included or excluded, according
| to wildcard patterns.
|
| By default, all URIs are included. If both include and exclude
| patterns are specified, a URI is first checked against the
| include patterns, and then against the exclude patterns.
|
| Multiple patterns can be given, using muliple include or exclude
| nodes.
|
| The order of the elements is not significant, as only the first
| successful match of each category is used.
|
| Currently, only the complete source URI can be matched (including
| any URI prefix). Future plans include destination URI matching
| and regexp matching. If you have requirements for these, contact
| dev@cocoon.apache.org.
+-->
<include pattern="**"/>
<exclude pattern="docs/apidocs/**"/>
<!-- <include-links extension=".html"/>-->
<!--+
| <uri> nodes specify the URIs that should be generated, and
| where required, what should be done with the generated pages.
|
| Append: append the generated page's URI to the end of the
| source URI:
|
| <uri type="append" src-prefix="documents/" src="index.html"
| dest="build/dest/"/>
|
| Replace: Completely ignore the generated page's URI - just
| use the destination URI:
|
| <uri type="replace" src-prefix="documents/" src="index.html"
| dest="build/dest/docs.html"/>
|
| Insert: Insert generated page's URI into the destination
| URI at the point marked with a * (example uses fictional
| zip protocol)
|
| <uri type="insert" src-prefix="documents/" src="index.html"
| dest="zip://*.zip/page.html"/>
|
| If in any of these scenarios, the dest attribute is omitted,
| the value provided globally using the <dest-dir> node will
| be used.
+-->
<uri type="replace"
src-prefix="samples/"
src="hello-world/hello.html"
dest="build/dest/hello-world.html"/>
<!--+
| <uri> nodes can be grouped together in a <uris> node. This
| enables a group of URIs to share properties. The following
| properties can be set for a group of URIs:
| * follow-links: should pages be crawled for links
| * confirm-extensions: should file extensions be checked
| for the correct mime type
| * src-prefix: all source URIs should be
| pre-pended with this prefix before
| generation. The prefix is not
| included when calculating the
| destination URI
| * dest: the base destination URI to be
| shared by all pages in this group
| * type: the method to be used to calculate
| the destination URI. See above
| section on <uri> node for details.
|
| Each <uris> node can have a name attribute. When a name
| attribute has been specified, the -n switch on the command
| line can be used to tell Cocoon to only process the URIs
| within this URI group. When no -n switch is given, all
| <uris> nodes are processed. Thus, one xconf file can be
| used to manage multiple sites.
+-->
<uris name="docs" follow-links="true">
<uri type="append" src-prefix="docs/" src="index.html"
dest="build/dest/" />
</uris>
<uris name="samples" follow-links="false"
confirm-extensions="true"
src-prefix="samples/"
dest="build/dest/examples/"
type="append"
>
<uri src=""/>
<uri src="hello-world/"/>
<uri src="hello-world/hello.html"/>
<uri src="hello-world/hello.xml"/>
</uris>
<!--+
| File containing URIs (plain text, one per
| line).
+-->
<!--
<uri-file></uri-file>
-->
</cocoon>
]]>
</source>
</s1>
</body>
</document>