Dev:Wiki Documentation Guidelines
Start a new railML Wiki page for a new railML element
Elements without parent inheritance
Some railML elements are re-used across the sub-schemas, e.g. "geoCoord", "valueTable", "efficiency", "*Ref". This section does not cover these re-used element. See next section.
- Define the wiki page name in the browser URL:
http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>
example:http://www.wiki.railml.org/index.php?title=RS:fourQuadrantChopper
results in http://www.wiki.railml.org/index.php?title=RS:fourQuadrantChopper - You get a blank page with the possibility to "Edit".
Choose "edit" or bearbeiten!
Elements with parent inheritance
Some railML elements are re-used across the sub-schemas, e.g. "geoCoord", "valueTable", "efficiency", "*Ref". The wiki provides general documentation templates for these elements that may be extended by special information for this certain semantics.
For all other elements jump to the previous section.
- Define the wiki page name in the browser URL:
http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>
example:http://www.wiki.railml.org/index.php?title=IS:geoCoord_mileageChange
results in http://www.wiki.railml.org/index.php?title=IS:geoCoord_mileageChange - You get a blank page with the possibility to "Edit".
Choose "edit" or bearbeiten!
See the wiki category overview for currently defined element documentation sites. The category "ElementTemplate" is used for this kind of template.
If some currently independently defined railML element is changed into a "general" element and used in "parent inheritance" an according wiki template should be defined and deployed in the original and the new element.
Text flow templates
Attributes
The following template may be used at every wiki page for a corporate layout for attributes and attribute values:
{{Attr | <attribute-name>}}
example: {{Attr | axleSequence}}
results in axleSequence
Generic documentation links for railML elements
The following templates may be used at every wiki page for refering to a certain railML element documentation site.
Link in angle brackets
The link is shown in angle brackets: <...>
. It looks like an XML element.
- Elements without parent inheritance
{{<sub-schema-prefix>:Tag|<element-name>}}
example:{{RS:Tag|fourQuadrantChopper}}
results in <fourQuadrantChopper> - Elements with parent inheritance
{{<sub-schema-prefix>:Tag|<element-name>|<parent-element-name>}}
example: {{RS:Tag|additionalName|vehicle}}
results in <additionalName>
Pure link
The link is shown pure without any characters around. This is better for reading a text flow.
- Elements without parent inheritance
{{<sub-schema-prefix>:Doc|<element-name>}}
example:{{RS:Doc|fourQuadrantChopper}}
results in fourQuadrantChopper - Elements with parent inheritance
{{<sub-schema-prefix>:Doc|<element-name>|<parent-element-name>}}
example: {{RS:Doc|additionalName|vehicle}}
results in additionalName
Adjust the XML tree
- Go to the XML tree wiki page
- Press "Edit" or Bearbeiten
- Crawl to the right position in the railML tree
Instead of scrolling there, it's easier to "search" for the parent element - Insert a new element with a new line at the appropriate position, if necessary
Only insert one line for each different element no matter how often it may occur at this certain position in the XML instance document.- Start with the appropriate number of stars "*" indicating the depth in the XML tree.
- Choose the appropriate wiki documentation link in angle brackets
- Add all possible attributes deploying the Attribute template, separated by comma
The inherited ones come at least (that's for some quick validation purposes of this page, that may be roughly generated by an XQuery search)
No matter, if the attributes are optional or mandatory.
***{{TT:Tag|train}} {{Attr|type}}, {{Attr|trainNumber}}, {{Attr|additionalTrainNumber}}, {{Attr|scope}}, {{Attr|processStatus}}, {{Attr|id}}, {{Attr|code}}, {{Attr|name}}, {{Attr|description}}, {{Attr|xml:lang}}
- Describe your changes with "Summary" or Zusammenfassung
- Check your changes with "Preview" or Vorschau
Adjust the page text where needed - Submit your changes with "Save" or Speichern
- Done. Thank you for your contribution.