| Where to place a "comment" value? [message #1554] |
Tue, 25 April 2017 09:54  |
Torben Brand
Messages: 162
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  |
christian.rahmig
Messages: 470
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 #2596 is a reply to message #1579] |
Sun, 22 November 2020 10:11 |
Torben Brand
Messages: 162
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 |
|
|
|
Members
Search
Help
Login
Home
