Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Message-ID: <4200E707.4080504@apache.org>
Date: Wed, 02 Feb 2005 15:43:19 +0100
From: Sylvain Wallez <sylvain@apache.org>
Organization: Anyware Technologies
User-Agent: Mozilla Thunderbird 1.0 (Macintosh/20041206)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id"
 keyword)
References: <802926B6AB8533408C33ADBCA3EE5C2A138D7B@coso.staff.vuw.ac.nz>
 <4200D825.1090100@apache.org> <20050202134935.GE25820@localhost>
In-Reply-To: <20050202134935.GE25820@localhost>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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 }