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="[EMAIL PROTECTED]"/> </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="[EMAIL PROTECTED]"/> </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 - | [EMAIL PROTECTED] - +--> - <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="[EMAIL PROTECTED]"/> </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="[EMAIL PROTECTED]"/> </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 | [EMAIL PROTECTED] +--> <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>