Template:Change

From railML 3 Wiki
Revision as of 15:30, 18 May 2020 by RailML Coord Documentation (talk | contribs) (→‎Usage)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 Dev: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 recomendations
  • trac: a list of related trac tickets. Pleas, employ Template:Ticket.
  • svn: a list of related svn commits. Please, employ 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

Empty Template

{{change
|fact=
|reason=
|recomendation=
|trac=
|svn=
|example=
|xsd=
|nattr=
|uattr=
|nelem=
|uelem=
}}

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?
|recomendation=Use the new {{IS:Tag|tsi}} and/or {{IS:Tag|designator}} elements instead.
|trac={{ticket|112}}, {{ticket|153}}
|svn={{svn|335}}, {{svn|439}}
|example=Old sample (railML 2.1):
<syntaxhighlight lang="xml">
<ocp ... name="Passau Hbf." abbrevation="NPA"/>
</syntaxhighlight>
New sample (railML 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?
Recomendation: Use the new <tsi> and/or <designator> elements instead.
Related Trac Tickets: #112, #153
Related SVN 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>