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 16:53:51 GMT
Tim Larson wrote:

>On Wed, Feb 02, 2005 at 03:43:19PM +0100, Sylvain Wallez wrote:
>>Tim Larson wrote:
>>>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).
>These sound (to my little brain) like solid issues against using processing instructions
for this purpose.
>>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.
>This was also my favorite, "@version $Id$", which I did not state at first to not bias
the result.

Cool! But you know, you can voice your opinion at the same time that you 
raise the issue. This makes an initial proposal that may avoid exploring 
too much directions!

>>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])
>If nobody objects within then next little bit, I will use:
>  <!--
>    Any text already present...
>    (A blank line between the text above and the version below?)
>    @version $Id$
>  -->
>At least it will be a simple standard, and we could do an
>automated textual replacement if we feel the need later.



Sylvain Wallez                                  Anyware Technologies 
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }

View raw message