joerg 2003/06/21 04:48:00
Modified: src/documentation/xdocs/userdocs/generators
directory-generator.xml
Log:
updated the documentation (file size + caching)
Revision Changes Path
1.3 +71 -61
cocoon-2.0/src/documentation/xdocs/userdocs/generators/directory-generator.xml
Index: directory-generator.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.0/src/documentation/xdocs/userdocs/generators/directory-generator.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- directory-generator.xml 31 May 2003 01:25:04 -0000 1.2
+++ directory-generator.xml 21 Jun 2003 11:48:00 -0000 1.3
@@ -2,95 +2,105 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
- <header>
- <title>Directory Generator</title>
- <version>0.9</version>
- <type>Technical document</type>
- <authors>
- <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
- </authors>
- <abstract>This document describes the directory generator of
Cocoon.</abstract>
- </header>
- <body>
- <s1 title="Directory Generator">
- <p>Generates an XML directory listing.</p>
- <p>
- The root node of the generated document will normally be a
- <code>directory</code> node, and a directory node can contain zero
- or more <code>file</code> or <code>directory</code> nodes. A file node has
no
- children. Each node will contain the following attributes:
- </p>
+ <header>
+ <title>Directory Generator</title>
+ <version>0.9</version>
+ <type>Technical document</type>
+ <authors>
+ <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
+ <person name="Jörg Heinicke" email="[EMAIL PROTECTED]"/>
+ </authors>
+ <abstract>This document describes the directory generator of Cocoon.</abstract>
+ </header>
+ <body>
+ <s1 title="Directory Generator">
+ <p>Generates an XML directory listing.</p>
<ul>
- <li>name : the name of the file or directory</li>
- <li>lastModified : the time the file was last modified, measured as the
number of
- milliseconds since the epoch (as in java.io.File.lastModified)</li>
- <li>date (optional) : the time the file was last modified in human-readable
form</li>
+ <li>Name: directory</li>
+ <li>Class: org.apache.cocoon.generation.DirectoryGenerator</li>
+ <li>Cacheable: yes</li>
</ul>
- <p>All generated elements have the namespace
- <code>http://apache.org/cocoon/directory/2.0</code>.
- The root <code>directory</code>
- node has the attribute <code>requested</code> with the value
<code>true</code>.
+ <p>The root node of the generated document will normally be a
<code>directory</code> node. A
+ directory node can contain zero or more <code>file</code> or
<code>directory</code> nodes.
+ A file node has no children. All generated elements have the namespace
+ <code>http://apache.org/cocoon/directory/2.0</code>.
</p>
+ <p>Each node will contain the following attributes:</p>
<ul>
- <li>Name : directory</li>
- <li>Class: org.apache.cocoon.generation.DirectoryGenerator</li>
- <li>Cacheable: no.</li>
+ <li><code>name</code>: the name of the file or directory.</li>
+ <li><code>lastModified</code>: the time the file was last modified,
measured as the number
+ of milliseconds since the epoch (as in
<code>java.io.File.lastModified</code>).</li>
+ <li><code>date</code>: the time the file was last modified in
human-readable form.</li>
+ <li><code>size</code>: the file size (or 0 for directories).</li>
</ul>
+ <p>Furthermore the requested directory has an attribute
<code>requested</code> with the value
+ set to true. This needs not to be the root node as you will see later.</p>
<source><![CDATA[
- <map:generate type="directory" src="the_directory"/>
+ <map:generate type="directory" src="the_directory">
+ <map:parameter name="depth" value="2"/>
+ </map:generate>
]]></source>
- </s1>
+ </s1>
<s1 title="Configuration">
- <p>The following parameter can be specified in the pipeline for
- the generate command:
+ <p>The <code>src</code> attribute on the <code><map:generate/></code> must
be set to the
+ directory the XML listing should be created of. This is the
<em>requested</em> directory.
+ </p>
+ <p>The following parameter are all optional and can be specified in the
pipeline for the
+ generate command (as seen in the example above for the parameter
<code>depth</code>):
</p>
<ul>
- <li>depth (optional) : Sets how deep Directory Generator should delve into
the
- directory structure. If set to 1 (the default), only the starting
- directory's immediate contents will be returned.</li>
- <li>dateFormat (optional) : Sets the format for the date attribute of each
node, as
- described in java.text.SimpleDateFormat. If unset, the default
- format for the current locale will be used.</li>
- <li>root (optional) : The root pattern</li>
- <li>include (optional) : The include pattern</li>
- <li>exclude (optional) : The exclude pattern</li>
+ <li>depth: Sets how deep Directory Generator should delve into the
directory structure. If
+ set to 1 (the default), only the starting directory's immediate
contents will be
+ returned.</li>
+ <li>dateFormat: Sets the format for the date attribute of each node, as
described in
+ <code>java.text.SimpleDateFormat</code>. If unset, the default format
for the current
+ locale will be used.</li>
+ <li>refreshDelay: Sets the delay (in seconds, default is 1) between checks
for
+ updates on the file system.</li>
+ <li>root: The root pattern. From the requested director upwards a directory
is searched
+ using this pattern, that is added as root node to the document. The
path from this root
+ node down to the requested directory will also be in the output. If no
root pattern is
+ specified or no ancestor of the requested directory matches this
pattern, the requested
+ directory will be the root in the output document.<br/>
+ The pattern is a regular expression as described in the API docs of the
+ <link
href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html";>
+ Apache RegExp project</link>.</li>
+ <li>include: The include pattern. Specifies the directories and files that
should be
+ included. Also a regular expression.</li>
+ <li>exclude: The exclude pattern. Specifies the directories and files that
should be
+ excluded. Also a regular expression.</li>
</ul>
</s1>
<s1 title="DTD">
<p>XML generated by directory generator uses namespace
- <code>http://apache.org/cocoon/status/2.0</code>. The DTD
- of XML generated by directory generator:
+ <code>http://apache.org/cocoon/status/2.0</code>. The DTD of XML
generated by directory
+ generator:
</p>
<source><![CDATA[
<!ELEMENT directory (directory|file)*>
<!ATTLIST directroy
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
- date CDATA #IMPLIED
+ date CDATA #REQUIRED
+ size CDATA #REQUIRED
requested CDATA #IMPLIED>
-
- <!ELEMENt file #EMPTY>
+
+ <!ELEMENT file #EMPTY>
<!ATTLIST file
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
- date CDATA #IMPLIED>
+ date CDATA #REQUIRED
+ size CDATA #REQUIRED>
]]></source>
</s1>
<s1 title="Example">
- <p>
- The current directory generator may generate following xml:
- </p>
+ <p>The current directory generator may generate following xml:</p>
<source><![CDATA[
-<directory xmlns="http://apache.org/cocoon/directory/2.0";
- name="stylesheets" lastModified="999425490000"
- date="02.09.01 12:11"
- requested="true">
- <directory name="sites"
- lastModified="999425490000" date="02.09.01 12:11"/>
- <file name="dynamic-page2html.xsl"
- lastModified="999425490000" date="02.09.01 12:11"/>
- <file name="simple-xml2html.xsl"
- lastModified="999425490000" date="02.09.01 12:11"/>
+<directory xmlns="http://apache.org/cocoon/directory/2.0";
+ name="stylesheets" lastModified="999425490000" date="02.09.01 12:11" size="0"
requested="true">
+ <directory name="sites" lastModified="999425490000" date="02.09.01 12:11"
size="0"/>
+ <file name="dynamic-page2html.xsl" lastModified="999425490000" date="02.09.01
12:11" size="0"/>
+ <file name="simple-xml2html.xsl" lastModified="999425490000" date="02.09.01
12:11" size="1234"/>
</directory>
]]></source>
</s1>
