You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by jo...@apache.org on 2003/06/27 02:46:41 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/generators directory-generator.xml
joerg 2003/06/26 17:46:41
Modified: src/documentation/xdocs/userdocs/generators
directory-generator.xml
Log:
as promised the update on the documentation of the DirectoryGenerator
Revision Changes Path
1.2 +113 -114 cocoon-2.1/src/documentation/xdocs/userdocs/generators/directory-generator.xml
Index: directory-generator.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/generators/directory-generator.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- directory-generator.xml 9 Mar 2003 00:08:19 -0000 1.1
+++ directory-generator.xml 27 Jun 2003 00:46:41 -0000 1.2
@@ -1,126 +1,125 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
<document>
- <header>
- <title>Directory Generator</title>
- <version>0.9</version>
- <type>Technical document</type>
- <authors>
- <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
- <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/>
- <person name="John Morrison" email="morrijr@apache.org"/>
- </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>
- <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>size : the file size in bytes (as returned by
- java.io.File.length)</li>
- <li>date (optional) : the time the file was last modified in
- human-readable form</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>. The
- sort order is described by the attribute <code>sort</code>,
- which defaults to sorting according to <code>name</code>.
- </p>
- <ul>
- <li>Name : directory</li>
- <li>Class: org.apache.cocoon.generation.DirectoryGenerator</li>
- <li>Cacheable: no.</li>
- </ul>
- <source><![CDATA[
-<map:generate type="directory" src="the_directory"/>]]></source>
- </s1>
- <s1 title="Configuration">
- <p>The following parameter can be specified in the pipeline for the
- generate command:
- </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. This is a regular
- expression as described
- <link href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">here.</link></li>
- <li>include (optional) : The include pattern. Also a
- regular expression.</li>
- <li>exclude (optional) : The exclude pattern. Also a
- regular expression.</li>
- <li>sort (optional) : This parameter determines the order in
- which the <code>file</code> and <code>directory</code> nodes
- are returned. Default sort order is as defined by the
- system. Possible values are "name", "size", "time", and
- "directory". "directory" is the same as "name", except that
- directory entries are listed first.</li>
- <li>reverse (optional) : This parameter reverses the sort order.
- reverse="false" is the default.</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:
- </p>
- <source><![CDATA[
-<!ELEMENT directory (directory|file)*>
-<!ATTLIST directory
+ <header>
+ <title>Directory Generator</title>
+ <version>1.0</version>
+ <type>Technical document</type>
+ <authors>
+ <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
+ <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/>
+ <person name="John Morrison" email="morrijr@apache.org"/>
+ <person name="Jörg Heinicke" email="joerg@apache.org"/>
+ </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: directory</li>
+ <li>Class: org.apache.cocoon.generation.DirectoryGenerator</li>
+ <li>Cacheable: yes</li>
+ </ul>
+ <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><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>Additionally the node for the requested directory has the attributes:</p>
+ <ul>
+ <li><code>requested</code>: with the value set to <code>true</code>.</li>
+ <li><code>sort</code>: the sort order of the <code>file</code> and <code>directory</code>
+ nodes.</li>
+ <li><code>reverse</code>: determines whether reverse sort was chosen.</li>
+ </ul>
+ <p>This node needs not to be the root node as you will see later.</p>
+ </s1>
+ <s1 title="Configuration">
+ <source><![CDATA[
+ <map:generate type="directory" src="the/requested/directory">
+ <map:parameter name="depth" value="2"/>
+ </map:generate>
+ ]]></source>
+ <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: 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. So this option influences the caching of the directory listing.</li>
+ <li>sort: Sets the sort order in which the <code>file</code> and <code>directory</code>
+ nodes are returned. Possible values are <code>name</code>, <code>size</code>,
+ <code>time</code> and <code>directory</code> (where <code>directory</code> is the same
+ as <code>name</code>, except that directory entries are listed first). The default sort
+ order is <code>name</code>.</li>
+ <li>reverse: Reverses the sort order, defaults to <code>false</code>.</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:
+ </p>
+ <source><![CDATA[
+ <!ELEMENT directory (directory|file)*>
+ <!ATTLIST directroy
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
- date CDATA #IMPLIED
- size CDATA #IMPLIED
+ date CDATA #REQUIRED
+ size CDATA #REQUIRED
+ requested CDATA #IMPLIED
sort CDATA #IMPLIED
- reverse CDATA #IMPLIED
- requested CDATA #IMPLIED>
+ reverse CDATA #IMPLIED>
-<!ELEMENT file #EMPTY>
-<!ATTLIST file
+ <!ELEMENT file #EMPTY>
+ <!ATTLIST file
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
- date CDATA #IMPLIED
- size CDATA #IMPLIED>
-]]></source>
- </s1>
- <s1 title="Example">
- <p>The current directory generator may generate following xml:</p>
- <source><![CDATA[
+ date CDATA #REQUIRED
+ size CDATA #REQUIRED>
+ ]]></source>
+ </s1>
+ <s1 title="Example">
+ <p>The current directory generator may generate following xml:</p>
+ <source><![CDATA[
<dir:directory xmlns:dir="http://apache.org/cocoon/directory/2.0"
- name="stylesheets"
- lastModified="1019666489000"
- date="24.04.02 18:41"
- size="461"
- sort="name"
- reverse="false"
- requested="true">
- <dir:directory name="sites" lastModified="1019666489000"
- date="24.04.02 18:41" size="118"/>
- <dir:file name="dynamic-page2html.xsl" lastModified="1019666489000"
- date="24.04.02 18:41" size="1832"/>
- <dir:file name="simple-xml2html.xsl" lastModified="1019666489000"
- date="24.04.02 18:41" size="12676"/>
+ name="stylesheets" lastModified="1056668768203" date="27.06.03 01:06" size="0"
+ requested="true" sort="name" reverse="false">
+ <dir:directory name="sites" lastModified="1056668768203" date="27.06.03 01:06" size="0"/>
+ <dir:file name="dynamic-page2html.xsl" lastModified="1056668768203" date="27.06.03 01:06" size="0"/>
+ <dir:file name="simple-xml2html.xsl" lastModified="1056668768203" date="27.06.03 01:06" size="1234"/>
</dir:directory>
- ]]></source>
- </s1>
- </body>
+ ]]></source>
+ </s1>
+ </body>
</document>
RE: resolving the DTDs nightmare
Posted by Upayavira <uv...@upaya.co.uk>.
On 27 Jun 2003 at 11:22, Carsten Ziegeler wrote:
> David Crossley wrote:
> > > - I think we should remove all
> > > the doc handling from cocoon. By this I mean the subsitemap we
> > > currently have that generates the docs on the fly in the built
> > > webapp. I hope to move this to forrest as well.
> >
> > I agree. However, what do you mean by "move this to forrest"?
> > Do you mean that Cocoon will do its samples, and the on-the-fly
> > documentation is somehow handled by a "forrest webapp"? Or do you
> > mean get rid of on-the-fly documentation altogether?
> >
> > I hope for the former, because many samples link straight to the
> > documentation.
> >
> Yeah, of course the former. I have posted a RT for this to the forrest
> list, so let's see what comes out of it.
At present we have a separate webapp for generating docs from the samples
webapp. My guess as to why this is is because, up until now, it has not been possible
for the CLI to strip off the first directory name from a URI. So, if you have the Cocoon
URI documents/index.html, it will be saved as documents/index.html. You cannot
change the folder into which it is written. Therefore, to get rid of the 'documents'
folder, you need a separate webapp that mounts the docs to the root, i.e. /index.html.
The new CLI and its Targets allow you to get around this by specifying a uri-prefix
and source uri, e.g. src-prefix="documents/" and src="index.html". That way the src-
prefix is ignored when deciding where to write the file. With a (for example)
dest="cocoon-docs", you can choose precisely where the docs should be written.
However, Forrest doesn't yet use the xconf functionality in the CLI, so won't be able to
do this yet.
I hope I'm making sense and that I'm not completely off-beam.
Regards, Upayavira
RE: resolving the DTDs nightmare
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
David Crossley wrote:
> > - I think we should remove all
> > the doc handling from cocoon. By this I mean the subsitemap we currently
> > have that generates the docs on the fly in the built webapp. I
> > hope to move this to forrest as well.
>
> I agree. However, what do you mean by "move this to forrest"?
> Do you mean that Cocoon will do its samples, and the on-the-fly
> documentation is somehow handled by a "forrest webapp"? Or do you
> mean get rid of on-the-fly documentation altogether?
>
> I hope for the former, because many samples link straight to the
> documentation.
>
Yeah, of course the former. I have posted a RT for this to the forrest
list, so let's see what comes out of it.
Carsten
RE: resolving the DTDs nightmare
Posted by David Crossley <cr...@indexgeo.com.au>.
Carsten Ziegeler wrote:
> David Crossley wrote:
> <snip/>
> > Anyway, what do you think of the other issue - the idea of getting rid
> > of Cocoon's validate-xdocs target?
>
> +1 if forrest does this for us it's ok
Okay, i will tidy that up in the next few days unless someone stops me.
> - I think we should remove all
> the doc handling from cocoon. By this I mean the subsitemap we currently
> have that generates the docs on the fly in the built webapp. I
> hope to move this to forrest as well.
I agree. However, what do you mean by "move this to forrest"?
Do you mean that Cocoon will do its samples, and the on-the-fly
documentation is somehow handled by a "forrest webapp"? Or do you
mean get rid of on-the-fly documentation altogether?
I hope for the former, because many samples link straight to the
documentation.
--David
RE: resolving the DTDs nightmare
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
David Crossley wrote:
> Bugger. I was going to look into the Jing code because that would be the
> ideal - make Jing use the xml-commons entity resolver. I see that there
> is a newer Jing available - will investigate sometime.
Great ;)
>
> Anyway, what do you think of the other issue - the idea of getting rid
> of Cocoon's validate-xdocs target?
>
+1 if forrest does this for us it's ok - I think we should remove all
the doc handling from cocoon. By this I mean the subsitemap we currently
have that generates the docs on the fly in the built webapp. I
hope to move this to forrest as well.
Carsten
RE: resolving the DTDs nightmare
Posted by David Crossley <cr...@indexgeo.com.au>.
Carsten Ziegeler wrote:
> David Crossley wrote:
> <snip/>
> > We also do some specific validation of certain core configuration
> > using RELAX NG and the Jing task. This works fine for validating
> > the cocoon.roles file (note it has an internal DTD subset). We were
> > also doing some experimental validation of other files, such as
> > **/book.xml files. However, there are problems now, because the parser
> > that is used still needs to resolve the DTD. I presume that it does not
> > use an entity resolver, ...<snip/>
>
> Yes, exactly - I thought for some minutes about extending the jing task
> to use a resolver (or better the xmlcatalog from ant) but after looking
> at the jing code I withdrew from that idea.
Bugger. I was going to look into the Jing code because that would be the
ideal - make Jing use the xml-commons entity resolver. I see that there
is a newer Jing available - will investigate sometime.
Anyway, what do you think of the other issue - the idea of getting rid
of Cocoon's validate-xdocs target?
--David
RE: resolving the DTDs nightmare (Was: Re: cvs commit:directory-generator.xml)
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
David Crossley wrote:
> We also do some specific validation of certain core configuration
> using RELAX NG and the Jing task. This works fine for validating
> the cocoon.roles file (note it has an internal DTD subset). We were
> also doing some experimental validation of other files, such as
> **/book.xml files. However, there are problems now, because the parser
> that is used still needs to resolve the DTD. I presume that it does not
> use an entity resolver,
Yes, exactly - I thought for some minutes about extending the jing task
to use a resolver (or better the xmlcatalog from ant) but after looking
at the jing code I withdrew from that idea.
Carsten
resolving the DTDs nightmare (Was: Re: cvs commit:
directory-generator.xml)
Posted by David Crossley <cr...@indexgeo.com.au>.
Joerg Heinicke wrote:
<snip/>
> I validated the file using jEdit - I hope it did it correctly.
> 'validate-xdocs' does not work at the moment. From the messages
> yesterday I guess you know this, but here is the message:
<snip/>
Oh damn. I was sure that worked for me yesterday. I was obviously
mistaken because it fails now.
Do not worry about the System Identifiers for the DTDs. They are not
used at all (however see below). The catalog entity resolver does work.
It finds the DTDs from WEB-INF/entities based on the Public Identifiers
and ignores the hard-coded System Identifers. If ever we see different
behaviour (such as now) then we know that something is wrong.
I will try to explain the various issues that we are faced with today.
The Cocoon webapp is producing the documentation okay. The parser
there uses the catalog entity resolver with great success. ... okay.
The 'build docs' target, which now uses "forrest" directly, also uses
a catalog entity resolver. ... okay.
Forrest has a 'validate-xdocs' target which uses Forrest's Ant (v1.6)
and its xmlvalidate task. That uses the xmlcatalog/catalogpath and
refers to Forrest's OASIS catalog and the DTDs in Forrest. ... okay.
Cocoon has a 'validate-xdocs' target which uses Cocoon's Ant (v1.5.3)
and its xmlvalidate task. The xmlcatalog/catalogpath is not in this
version of Ant, so we cannot utilise Cocoon's OASIS catalog and DTDs.
We need to rely on the hard-coded System Identifiers. ... bad.
Anyway we recently removed the copies of the DTDs, so now it is
really broken.
We also do some specific validation of certain core configuration
using RELAX NG and the Jing task. This works fine for validating
the cocoon.roles file (note it has an internal DTD subset). We were
also doing some experimental validation of other files, such as
**/book.xml files. However, there are problems now, because the parser
that is used still needs to resolve the DTD. I presume that it does not
use an entity resolver, so it has to rely on the System Identifier,
which is now broken. ... bad. So i just removed that experiment from
the build.
--0--
The solution is to just remove the validate-xdocs target from Cocoon.
This then leaves it to Forrest to do the validation while it is
building the docs.
For those that don't have Forrest and still want to do xdocs editing,
they can do validation with their own xml editing tools or use a
special-purpose validator such as "xmllint", or "onsgmls" from OpenSP.
Just point the tool to Cocoon's catalog files at
WEB-INF/entities/catalog
The Cocoon validate-xdocs target has passed its use-by date. It was
good for the time because it helped us to maintain our xdocs. We can
now pass that concern on to other processes.
--David
Re: cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/generators
directory-generator.xml
Posted by Joerg Heinicke <jo...@gmx.de>.
joerg@apache.org wrote:
> joerg 2003/06/26 17:46:41
>
> Modified: src/documentation/xdocs/userdocs/generators
> directory-generator.xml
> Log:
> as promised the update on the documentation of the DirectoryGenerator
>
> Revision Changes Path
> 1.2 +113 -114 cocoon-2.1/src/documentation/xdocs/userdocs/generators/directory-generator.xml
>
> Index: directory-generator.xml
> ===================================================================
> RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/generators/directory-generator.xml,v
> retrieving revision 1.1
> retrieving revision 1.2
> diff -u -r1.1 -r1.2
> --- directory-generator.xml 9 Mar 2003 00:08:19 -0000 1.1
> +++ directory-generator.xml 27 Jun 2003 00:46:41 -0000 1.2
> @@ -1,126 +1,125 @@
> <?xml version="1.0" encoding="UTF-8"?>
> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
I validated the file using jEdit - I hope it did it correctly.
'validate-xdocs' does not work at the moment. From the messages
yesterday I guess you know this, but here is the message:
validate-xdocs:
Conducting validation of core XML documentation.
Validating all **/book.xml instances using RELAX NG ...
Fatal error: exception "java.io.FileNotFoundException" thrown:
D:\cocoon-2.1\build\cocoon-2.1m3-dev\documentation\xdocs\dtd\book-cocoon-v10.dtd
(Das System kann den angegebenen Pfad nicht finden)
BUILD FAILED
file:d:/cocoon-2.1/src/targets/validate-build.xml:71: Validation failed,
messages should have been provided.
What's the correct SYSTEM ID for the XDocs files? I changed at least
"../../dtd/document-v10.dtd" to "document-v10.dtd". Do we have (or need)
something like "http://cocoon.apache.org/dtd/document-v10.dtd"?
Joerg