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 versionI 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).
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.
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 }
