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: 101
Registered: March 2016
Senior 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: 285
Registered: January 2016
Senior 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 messageGo to next message
Dirk Bräuer is currently offline  Dirk Bräuer
Messages: 295
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.
Re: Where to place a "comment" value? [message #2596 is a reply to message #1579] Sun, 22 November 2020 10:11 Go to previous message
Torben Brand is currently offline  Torben Brand
Messages: 101
Registered: March 2016
Senior Member
Dear railML-community,

We come back to this older forum posting. We will refer to "remarks" from now on, to describe comments/remarks, as this is a better describing term of the desired use. I will refer to railML2 here. RailML3 knowledgably users please also check if fulfilled in railML3. The term "remarks" is in use in the intended manner in railML2 in an @remarks attribute under, amongst others, <state>, <train>, <opcTT>, <sectionTT>.
I agree that there should be created a use case for "Metadata" in railML3 which also should be applied in railML2.5 as we have the same requirements here. UC for "remarks" is Planners note with opinion on the object. Often describing actions to be taken concerning the remarked object in a workflow.(see also definition suggestion bellow). Context to the remark is given on which object it is placed.
For an example for an remark (in infrastructure) please see: https://railoscope.com/tickets/bRbcASDgBifKJ9rM?modelId=5c81 5c32137e0f14761f0bae&selectId=153

The definition of "remarks" is varying a great deal in the railMl2 wiki and should be improved and made consistent.
Remarks definition under <train>: This is a free attribute for further remarks, which should not be mixed with the description of a train.

I suggest the following two definitions:
Description: Human-readable description giving added information to the name of an object.
Remark: Planners note with opinion on the object. Often describing actions to be taken concerning the remarked object in a workflow.

For implementation we have chosen to go with Christians option 1 for the moment, mixing description and remarks in the @description attribute. As this is not very clean modelling, we suggest the following.

Make a separate element <remark> that can refer to any element. Have a <remarks> container, placed under <metadata> in railML2 and <common> in railML3, as the use case is a common one for all schemas.

The remarks are visualized related to but placed by the user in the visualisation free of the related object (usually with bubbles containing the remark text with a tether connecting to the object). With a separate <remark> element the remark can also be placed independently in the visualisation scheme (in railML2 only for infrastructure).

What does the community think about this solution suggestion? Any feedback is highly appreciated.

Kind regards


Torben Brand
Jernbanedirektoratet

[Updated on: Sun, 22 November 2020 10:29]

Report message to a moderator

Previous Topic: Visualization: Proposal to move to a separate subschema
Next Topic: Suggested refined definitions and extension to organizationalUnits
Goto Forum:
  


Current Time: Tue Dec 01 18:04:18 CET 2020