cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
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 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 }


Mime
View raw message