Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Hi, On 2 Feb 2005, at 16:38, Tim Larson wrote: If nobody objects within then next little bit, I will use: At least it will be a simple standard, and we could do an automated textual replacement if we feel the need later. ... and we can extend with more syntax later. Sounds good to me ... The other issue is should this actually belong in the semantic content of the XML file. But I guess the revision of the content and the SVN revision of the file itself can be different things, depending on the content. Andrew. -- Andrew Savory, Managing Director, Luminas Limited Tel: +44 (0)870 741 6658 Fax: +44 (0)700 598 1135 Web: http://www.luminas.co.uk/ Orixo alliance: http://www.orixo.com/ smime.p7s Description: S/MIME cryptographic signature
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Hi, On 2 Feb 2005, at 14:43, Sylvain Wallez wrote: 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. Ahem. Oops. I have the source for xsldoc in my mail archive dating back to around this time last year. I spoke with Rick Maddy, the author, who was willing to contribute it to wherever wanted it, but there were problems since it was based on the Sun Javadoc sourcecode. If anyone feels like picking this up and dealing with Sun, I'm sure that would be fine. LMK, Andrew. -- Andrew Savory, Managing Director, Luminas Limited Tel: +44 (0)870 741 6658 Fax: +44 (0)700 598 1135 Web: http://www.luminas.co.uk/ Orixo alliance: http://www.orixo.com/ smime.p7s Description: S/MIME cryptographic signature
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
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:
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 }
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
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: At least it will be a simple standard, and we could do an automated textual replacement if we feel the need later. --Tim Larson
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Tim Larson wrote:
On Wed, Feb 02, 2005 at 02:39:49PM +0100, Sylvain Wallez wrote:
Conal Tuohy wrote:
What about a processing instruction?
This has the advantage over a comment that it can be retrieved
unambiguously with an XPath query: "processing-instruction('version')"
Question is: do we need that? IMO no, as I don't see valid use cases for
analyzing the version string of an XML document or XSL stylesheet at
runtime in Cocoon.
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).
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.
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])
Sylvain
[1] http://sourceforge.net/projects/xsldoc/
[2] http://jsdoc.sourceforge.net/
[3] http://www.stack.nl/~dimitri/doxygen/
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
On Wed, 02 Feb 2005 14:39:49 +0100, Sylvain Wallez <[EMAIL PROTECTED]> wrote:
> Conal Tuohy wrote:
>
> >What about a processing instruction?
> >
> >
> >This has the advantage over a comment that it can be retrieved unambiguously
> >with an XPath query:
> >"processing-instruction('version')"
> >
> >
>
> Question is: do we need that? IMO no, as I don't see valid use cases for
> analyzing the version string of an XML document or XSL stylesheet at
> runtime in Cocoon.
How about on the management tools side? Something like generation of
reports on what versions of the config is currently being used (with
no code changes required). Given that there's no real cost to using a
PI instead of a comment allowing for future use cases we haven't yet
come up with seems more forward thinking
--
Peter Hunsberger
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
On Wed, Feb 02, 2005 at 01:49:35PM +, Tim Larson wrote:
> On Wed, Feb 02, 2005 at 02:39:49PM +0100, Sylvain Wallez wrote:
> > Conal Tuohy wrote:
> > >What about a processing instruction?
> > >
> > >
> > >This has the advantage over a comment that it can be retrieved
> > >unambiguously with an XPath query: "processing-instruction('version')"
> >
> > Question is: do we need that? IMO no, as I don't see valid use cases for
> > analyzing the version string of an XML document or XSL stylesheet at
> > runtime in Cocoon.
>
> 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.
Would the benevolent dictator please speak, so I can finish
the changes? Oops, that's in Linux kernel land ;)
More seriously, could a few more people respond so we can
come to a conclusion. I'm champing at the bit to get this
done, so I can move on to more "real" cocoon work :)
--Tim Larson
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
On Wed, Feb 02, 2005 at 02:39:49PM +0100, Sylvain Wallez wrote:
> Conal Tuohy wrote:
> >What about a processing instruction?
> >
> >
> >This has the advantage over a comment that it can be retrieved
> >unambiguously with an XPath query: "processing-instruction('version')"
>
> Question is: do we need that? IMO no, as I don't see valid use cases for
> analyzing the version string of an XML document or XSL stylesheet at
> runtime in Cocoon.
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.
--Tim Larson
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Conal Tuohy wrote:
What about a processing instruction?
This has the advantage over a comment that it can be retrieved unambiguously with an XPath query:
"processing-instruction('version')"
Question is: do we need that? IMO no, as I don't see valid use cases for
analyzing the version string of an XML document or XSL stylesheet at
runtime in Cocoon.
There has been discussions in the past about including static strings in
java source holding the revision info (i.e. public static final String
SCM_ID="$Id$") so that we can retrieve them with the "what" command, but
that use case doesn't apply to XML files since, contrarily to Java
classes, they are available in source form in a Cocoon distro.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Tim Larson wrote:
I personally do not like including a reference to the
revision control system, especially since we have already
experienced the data moving from one rcs system to another,
invalidating all the "CVS" comments. FWIW, I fully expect
another move in the future (not yet, don't get worried.)
+1
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
RE: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Tim Larson wrote:
> On Wed, Feb 02, 2005 at 10:35:03AM +1300, Conal Tuohy wrote:
> > > Tim Larson wrote:
> > > > As part of my effort to keep whiteboard/forms mergeable,
>
> > > >Could we pick a style, and then I will make the files I
> > > >happen to touch match it?
> >
> > What about a processing instruction?
> >
> >
> > This has the advantage over a comment that it can be
> retrieved unambiguously with an XPath query:
> > "processing-instruction('version')"
>
> I like the ability to retrieve the Id info...not knowing
> much about processing instructions, will this produce
> valid processing instructions when the version control
> system expands $Id$? This expands into lots of stuff:
> datestamp, filename, submitter, etc.
So long as it doesn't include the string "?>" it will be OK.
> Also, can this mess up any existing document processing?
It shouldn't. Most XML software should be happy to ignore processing
instructions (unless the pi is targeted at them), just like with comments.
In the SAX pipeline, the processing instructions are passed using a
"processingInstruction" method, so completely independently of
startElement/endElement/characters/etc. Typically, pipeline components will
inherit a "processingInstruction" method from a superclass, which will do
nothing.
Cheers
Con
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
On Wed, Feb 02, 2005 at 10:35:03AM +1300, Conal Tuohy wrote:
> > Tim Larson wrote:
> > > As part of my effort to keep whiteboard/forms mergeable,
> > >Could we pick a style, and then I will make the files I
> > >happen to touch match it?
>
> What about a processing instruction?
>
>
> This has the advantage over a comment that it can be retrieved unambiguously
> with an XPath query:
> "processing-instruction('version')"
I like the ability to retrieve the Id info...not knowing
much about processing instructions, will this produce
valid processing instructions when the version control
system expands $Id$? This expands into lots of stuff:
datestamp, filename, submitter, etc.
Also, can this mess up any existing document processing?
--Tim Larson
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
On Tue, Feb 01, 2005 at 01:20:10PM -0800, Ralph Goers wrote: > Tim Larson wrote: > > >As part of my effort to keep whiteboard/forms mergeable, > > > >I am fixing a bunch of Id's and ran across a minor issue. > >How do we want to mark the version in xml files? There > >is quite a variety+possibilities: > I only see one choice that is within a comment. How do the others keep > from breaking the document? The others are all in comments such as: I just included the comment delimiters for the one example to show that in some documents the comments have extra decoration (the ascii-art +---+ stuff.) > I would use > > I personally do not like including a reference to the revision control system, especially since we have already experienced the data moving from one rcs system to another, invalidating all the "CVS" comments. FWIW, I fully expect another move in the future (not yet, don't get worried.) --Tim Larson
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Conal Tuohy wrote:
What about a processing instruction?
This has the advantage over a comment that it can be retrieved unambiguously with an XPath query:
"processing-instruction('version')"
Cheers
Con
Sure, that works too.
RE: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
> Tim Larson wrote:
>
> > As part of my effort to keep whiteboard/forms mergeable,
> >
> >I am fixing a bunch of Id's and ran across a minor issue.
> >How do we want to mark the version in xml files? There
> >is quite a variety+possibilities:
> > CVS $Id$
> > SVN $Id$
> >
> > Version $Id$
> > version $Id$
> > @version $Id$
> > etc...
> >Could we pick a style, and then I will make the files I
> >happen to touch match it?
> >
> >--Tim Larson
> >
> >
> I only see one choice that is within a comment. How do the
> others keep
> from breaking the document?
What about a processing instruction?
This has the advantage over a comment that it can be retrieved unambiguously
with an XPath query:
"processing-instruction('version')"
Cheers
Con
Re: Version $Id$ style for xml files (Was: SVN behaviour with "Id" keyword)
Tim Larson wrote: As part of my effort to keep whiteboard/forms mergeable, I am fixing a bunch of Id's and ran across a minor issue. How do we want to mark the version in xml files? There is quite a variety+possibilities: CVS $Id$ SVN $Id$ Version $Id$ version $Id$ @version $Id$ etc... Could we pick a style, and then I will make the files I happen to touch match it? --Tim Larson I only see one choice that is within a comment. How do the others keep from breaking the document? I would use
