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
