upayavira 2003/11/07 07:01:54
Modified: . cli.xconf
Log:
Improving docs, explaining some newer options
Revision Changes Path
1.8 +71 -16 cocoon-2.1/cli.xconf
Index: cli.xconf
===================================================================
RCS file: /home/cvs/cocoon-2.1/cli.xconf,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- cli.xconf 26 Sep 2003 17:08:08 -0000 1.7
+++ cli.xconf 7 Nov 2003 15:01:54 -0000 1.8
@@ -1,5 +1,4 @@
<?xml version="1.0"?>
-
<!--+
| This is the Apache Cocoon command line configuration file.
| Here you give the command line interface details of where
@@ -59,6 +58,15 @@
<config-file>WEB-INF/cocoon.xconf</config-file>
<work-dir>build/work</work-dir>
<dest-dir>build/dest</dest-dir>
+
+ <!--+
+ | A checksum file can be used to store checksums for pages
+ | as they are generated. When the site is next generated,
+ | files will not be written if their checksum has not changes.
+ | This means that it will be easier to detect which files
+ | need to be uploaded to a server, using the timestamp.
+ +-->
+ <!-- <checksums-uri>build/work/checksums</checksums-uri>-->
<!--+
| Broken link reporting options:
@@ -122,21 +130,48 @@
<!--+
| Specifies a user agent string to the sitemap when
| generating the site.
+ |
+ | A generic term for a web browser is "user agent". Any
+ | user agent, when connecting to a web server, will provide
+ | a string to identify itself (e.g. as Internet Explorer or
+ | Mozilla). It is possible to have Cocoon serve different
+ | content depending upon the user agent string provided by
+ | the browser. If your site does this, then you may want to
+ | use this <user-agent> entry to provide a 'fake' user agent
+ | to Cocoon, so that it generates the correct version of your
+ | site.
+ |
+ | For most sites, this can be ignored.
+-->
<!--
- <user-agent>xxx</user-agent>
+ <user-agent>Cocoon Command Line Environment 2.1</user-agent>
-->
<!--+
| Specifies an accept string to the sitemap when generating
| the site.
+ | User agents can specify to an HTTP server what types of content
+ | (by mime-type) they are able to receive. E.g. a browser may be
+ | able to handle jpegs, but not pngs. The HTTP accept header
+ | allows the server to take the browser's capabilities into account,
+ | and only send back content that it can handle.
+ |
+ | For most sites, this can be ignored.
+-->
+
<accept>*/*</accept>
<!--+
| Specifies which URIs should be included or excluded, according
| to wildcard patterns.
|
+ | These includes/excludes are only relevant when you are following
+ | links. A link URI must match an include pattern (if one is given)
+ | and not match an exclude pattern, if it is to be followed by
+ | Cocoon. It can be useful, for example, where there are links in
+ | your site to pages that are not generated by Cocoon, such as
+ | references to api-documentation.
+ |
| 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.
@@ -152,44 +187,66 @@
| and regexp matching. If you have requirements for these, contact
| [EMAIL PROTECTED]
+-->
+
<include pattern="**"/>
<exclude pattern="docs/apidocs/**"/>
-<!-- <include-links extension=".html"/>-->
+ <!-- <include-links extension=".html"/>-->
<!--+
| <uri> nodes specify the URIs that should be generated, and
| where required, what should be done with the generated pages.
+ | They describe the way the URI of the generated file is created
+ | from the source page's URI. There are three ways that a generated
+ | file URI can be created: append, replace and insert.
|
- | Append: append the generated page's URI to the end of the
+ +----------------------------------------------------------------
+ |
+ | 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
+ | This means that
+ | (1) the "documents/index.html" page is generated
+ | (2) the file will be written to "build/dest/documents/index.html"
+ |
+ +----------------------------------------------------------------
+ |
+ | 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"/>
+ |
+ | This means that
+ | (1) the "documents/index.html" page is generated
+ | (2) the result is written to "build/dest/docs.html"
+ | (3) this works only for "single" pages - and not when links
+ | are followed
|
- | Insert: Insert generated page's URI into the destination
+ +----------------------------------------------------------------
+ | 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,
+ | This means that
+ |
+ |
+ | In any of these scenarios, if the dest attribute is omitted,
| the value provided globally using the <dest-dir> node will
- | be used.
+ | be used instead.
+-->
<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
@@ -215,6 +272,7 @@
| <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/" />
@@ -222,23 +280,20 @@
<uris name="samples"
follow-links="false"
- confirm-extensions="true"
src-prefix="samples/"
dest="build/dest/examples/"
type="append"
>
- <uri src=""/>
<uri src="hello-world/hello.html"/>
<uri src="hello-world/hello.xml"/>
</uris>
<!--+
- | File containing URIs (plain text, one per
- | line).
+ | File containing URIs (plain text, one per line).
+-->
<!--
- <uri-file></uri-file>
+ <uri-file>uris.txt</uri-file>
-->
-
</cocoon>
+
