Tim Larson wrote:
On Wed, Feb 02, 2005 at 02:39:49PM +0100, Sylvain Wallez wrote:
Conal Tuohy wrote:
What about a processing instruction? <?version $Id$?>Question is: do we need that? IMO no, as I don't see valid use cases for analyzing the version string of an XML document or XSL stylesheet at runtime in Cocoon.
This has the advantage over a comment that it can be retrieved unambiguously with an XPath query: "processing-instruction('version')"
I like the idea of having _some_ way to access the version
info in xml files, because someday we may have tools like
javadocs which would collect and display this info (think
for xml files like sitemaps, cforms definitions, models,
templates, etc.) Since the work of standardizing the Id's
(to get rid of spurious "CVS" references, etc.) is tedious
I would like to do it only once, hence this discussion.
I see and agree with your point. My concern is adding this information in a way that changes the structure of XML documents, i.e. the data that will be manipulated by the Cocoon runtime. Having to explicitely distinguish processing-instructions that are relevant to the application from those used to document source files can be a major PITA or lead to having a lot of these processing-instructions at the end of the pipeline (i.e. in the browser).
So I'm more than ok with formalizing a syntax for the Id string and other metadata for later analysis, but using specially-formatted comments. There used to be an xsldoc project at http://www.xsldoc.org/ that was producing javadoc-like documentation from javadoc-like comments (i.e. "@version $Id$", but also "@param", "@return" etc). Unfortunately the site is down.
There's also another xsldoc project at SF.net [1] that uses elements in a special namespace for XSL documentation, but using elements means it can only be applied to XSL stylesheets and is not a general-purpose solution for all XML files.
So my opinion would be to use javadoc-style comments. This is well-known in Java, and used also by other languages (see jsdoc [2] and doxygen [3])
Sylvain
[1] http://sourceforge.net/projects/xsldoc/ [2] http://jsdoc.sourceforge.net/ [3] http://www.stack.nl/~dimitri/doxygen/
-- Sylvain Wallez Anyware Technologies http://www.apache.org/~sylvain http://www.anyware-tech.com { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
