cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <>
Subject Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Date Wed, 02 Feb 2005 14:43:19 GMT
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$?>
>>>This has the advantage over a comment that it can be retrieved 
>>>unambiguously with an XPath query: "processing-instruction('version')" 
>>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.
>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 
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 [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 Wallez                                  Anyware Technologies 
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }

View raw message