Home » railML newsgroups » railml.misc » Where to place a "comment" value? (Where do you place comments on individual elements in railML?)
Where to place a "comment" value? [message #1554] Tue, 25 April 2017 09:54 Go to next message
Torben Brand is currently offline  Torben Brand
Messages: 23
Registered: March 2016
Junior Member
Where do you place comments on individual elements in railML?
As part of the use case capacity planning we need to comment on the elements. This is part of the workflow where we need to describe tasks that needs to be done or has been done and we like to emphasize. Currently this is either a separate list or annotations (comment bubble) on a schematic representation of the railML model (schematic track plan). But embedding it in the railML file is more efficient and less error prone. Comments could be any comment not only connected to the described workflow.

Example 1: In a railML file describing the current infrastructure state, on the element speedChange the comment "Check if this speed is correct"
Example 2: In a railML file describing a planned infrastructure state, on the element switch the comment "We need to move this switch outwards 50 meters and increase the deflecting speed/size of the switch".

I suggest for railML 2 using the generally for all elements available attribute @description. The wiki defines @description as "This is a more detailed description as addition to the short name. It shall allow a short overview or hints to the contents of this data set." Comments could be interpreted as "hints to the contents of this data set".

I suggest for railML 3 a separate attribute @comment available for all elements . This as the comments not usually describe the element directly.
Re: Where to place a "comment" value? [message #1556 is a reply to message #1554] Sun, 30 April 2017 08:07 Go to previous messageGo to next message
christian.rahmig is currently offline  christian.rahmig
Messages: 45
Registered: January 2016
Member
Dear Torben,

placing comments within a railML file has not yet been in the focus and
therefore, a dedicated element does not exist. However, there are two
options how to do it in railML v2.x:

Option 1: the attribute @description
This attribute is available for most of the railML elements and its data
type is a string and therefore allows it to put any comment.

Option 2: use the XML comment syntax
You can place comments at every place of your railML file using the
standard XML comment syntax <!-- comment -->. In contrast to option 1
the comment is not directly included in the railML data model.

If you prefer option 1, I agree with your suggestion to have a separate
<comment> element implemented in railML v3 in order not to "misuse" the
attribute @description. However, option 2 is always valid.

Question to all: how do you solve commenting issues currently?
Any comments appreciated...

Best regards
Christian
--
Christian Rahmig - Infrastructure scheme coordinator
railML.org (Registry of Associations: VR 5750)
Phone Coordinator: +49 173 2714509; railML.org: +49 351 47582911
Altplauen 19h; 01187 Dresden; Germany www.railml.org

Am 25.04.2017 um 09:54 schrieb Torben Brand:
> Where do you place comments on individual elements in
> railML?
> As part of the use case capacity planning we need to comment
> on the elements. This is part of the workflow where we need
> to describe tasks that needs to be done or has been done and
> we like to emphasize. Currently this is either a separate
> list or annotations (comment bubble) on a schematic
> representation of the railML model (schematic track plan).
> But embedding it in the railML file is more efficient and
> less error prone. Comments could be any comment not only
> connected to the described workflow.
>
> Example 1: In a railML file describing the current
> infrastructure state, on the element speedChange the comment
> "Check if this speed is correct"
> Example 2: In a railML file describing a planned
> infrastructure state, on the element switch the comment "We
> need to move this switch outwards 50 meters and increase the
> deflecting speed/size of the switch".
>
> I suggest for railML 2 using the generally for all elements available
> attribute @description. The wiki defines
> @description as "This is a more detailed description as
> addition to the short name. It shall allow a short overview
> or hints to the contents of this data set." Comments could
> be interpreted as "hints to the contents of this data set".
>
> I suggest for railML 3 a separate attribute @comment
> available for all elements . This as the comments not
> usually describe the element directly.

[Updated on: Sun, 30 April 2017 15:54] by Moderator

Report message to a moderator

Re: Where to place a "comment" value? [message #1579 is a reply to message #1556] Thu, 18 May 2017 15:32 Go to previous message
Dirk Bräuer is currently offline  Dirk Bräuer
Messages: 202
Registered: August 2008
Senior Member
Dear Christian and Torben,

> Question to all: how do you solve commenting issues currently?
> Any comments appreciated...

My comment for iRFP: No comments used so far because no other (known)
software will support them in the same context.

As already discussed concerning "remarks", it is hard to believe that
two different softwares will have the same "understanding" of attributes
like "remarks" or "comment". Either such attributes can only be
exchanged between two instances of the same software(-family) or after
further bilateral agreements (--> use case!). In both cases, it should
be possible to use more special attribute names and possibly to use
scheme extensions because of specialisation.

So from my opinion: Please use use cases and define scheme extensions in
use cases.

Best regards,
Dirk.
Previous Topic: what about compressed RailML files?
Goto Forum:
  


Current Time: Mon May 29 17:16:39 CEST 2017