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 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 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.
>>    
>>
>
>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 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])
>>    
>>
>
>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.
>  
>

+1!

Sylvain

-- 
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