cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Larson <...@keow.org>
Subject Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Date Wed, 02 Feb 2005 16:38:00 GMT
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.

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

--Tim Larson

Mime
View raw message