Template:Change

From railML 2 Wiki
Jump to navigation Jump to search

Usage

This template is suposed to standardize the depiction of changes between railML® versions. It is used in certain subpages of Changes.

Arguments

The template has five optional arguments:

  • fact: a prompt of the change, e.g. Element X has been extended by attribute Y.
  • reason: an explanation of why and how the change has been implemented.
  • recomendation: any recommendations
  • ticket: a list of related development tickets (formerly organized via trac; now via GITLab). Please, employ Template:Ticket.
  • commit: a list of related svn commits. Please, employ template:commit, or, for vintage tickets, Template:SVN.
  • example: An example, usually a code snippet.
  • xsd: updated XSD-files
  • nattr: new attributes
  • uattr: updated attributes
  • nelem: new Elements
  • uelem: updated Elements
  • nsemcon: New semantic constraints
  • usemcon: Updated semantic constraints

Empty Template

{{change
|fact=
|reason=
|recommendation=
|ticket=
|commit=
|example=
|xsd=
|nattr=
|uattr=
|nelem=
|uelem=
|nsemcon=
|usemcon=
}}

Example

{{change
|fact={{Attr|@abbrevation}} and {{attr|@number}} in the {{IS:Tag|ocp}} element have been declared deprecated. {{attr|@parentOcpRef}} and {{IS:Tag|designator}} have been introduced. {{IS:Doc|additionalName|ocp}} has been expanded by [[IS:additionalName_ocp#type|{{attr|@type}}]].
|reason=There are multiple different abbreviations and numbers for single operation or control points. They can't be defined with one attribute. Use, depending on context, {{IS:Tag|designator}} or {{IS:Doc|additionalName|ocp}} instead. {{attr|@parentOcpRef}} allows for grouping ocps. {{IS:Tag|designator}} allows for more codes than the depricated {{attr|@code}}, plus it can establish a relation with the [[dev:codelists|codelist]] ''Registers.xml''. {{IS:Doc|additionalName|ocp}}/{{attr|@type}} allowes to declare the context of a name: is it valid under operational or traffic aspects, or as a local name?
|recommendation=Use the new {{IS:Tag|tsi}} and/or {{IS:Tag|designator}} elements instead.
|ticket={{ticket|112}}, {{ticket|153}}
|commit={{svn|335}}, {{svn|439}}
|example=Old sample ({{rml|2.1}}):
<syntaxhighlight lang="xml">
<ocp ... name="Passau Hbf." abbrevation="NPA"/>
</syntaxhighlight>
New sample ({{rml|2.2}}):
<syntaxhighlight lang="xml">
<ocp ... name='Passau Hbf.' ...>
  <tsi country="80"/>
  <designator register='RL100' entry='NPA'/>
  <designator register='ENEE' entry='80-26506-6'/>
  <designator register='PLC' entry='DE18274'/>
  <designator register='IBNR' entry='8000298'/>
  <designator register='DB640' entry='Pa'/>
</ocp>
</syntaxhighlight>
}}

delivers:


Fact: @abbrevation and @number in the <ocp> element have been declared deprecated. @parentOcpRef and <designator> have been introduced. additionalName has been expanded by @type.
Reason: There are multiple different abbreviations and numbers for single operation or control points. They can't be defined with one attribute. Use, depending on context, <designator> or additionalName instead. @parentOcpRef allows for grouping ocps. <designator> allows for more codes than the depricated @code, plus it can establish a relation with the codelist Registers.xml. additionalName/@type allowes to declare the context of a name: is it valid under operational or traffic aspects, or as a local name?
Recommendation: Use the new <tsi> and/or <designator> elements instead.
Related Development Tickets: #112, #153
Related Commits: [335] (Note on legacy SVN commits), [439] (Note on legacy SVN commits)
Example: Old sample (railML® 2.1):
<ocp ... name="Passau Hbf." abbrevation="NPA"/>

New sample (railML® 2.2):

<ocp ... name='Passau Hbf.' ...>
  <tsi country="80"/>
  <designator register='RL100' entry='NPA'/>
  <designator register='ENEE' entry='80-26506-6'/>
  <designator register='PLC' entry='DE18274'/>
  <designator register='IBNR' entry='8000298'/>
  <designator register='DB640' entry='Pa'/>
</ocp>