Dev:Wiki Documentation Guidelines: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][checked revision]
m ("backHome" link removed, use new automatic category instead)
(Replaced content with "{{mirror}}")
Tag: Replaced
 
(42 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Start a new railML Wiki page for a new railML element ==
{{mirror}}
 
=== 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 [[#Elements_with_parent_inheritance | next section]].
 
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.
 
<ol>
<li>Define the wiki page name in the browser URL:
 
<pre>http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name></pre>
 
example: <code><nowiki>http://www.wiki.railml.org/index.php?title=IS:speedProfiles</nowiki></code> results in http://www.wiki.railml.org/index.php?title=IS:speedProfiles</li>
 
<li>You get a blank page with the possibility to "Edit".<br>
 
Choose "edit" or {{Deu | bearbeiten}}!</li>
 
<li>Insert the [[Vorlage:ElementDocu | element documentation template]] into the blank editor
 
<pre><nowiki>{{ElementDocu}}</nowiki></pre>
 
Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further. </li>
 
<li>Insert parameters, they may occur in any order.
 
<pre><nowiki>{{ElementDocu
|elementName
|parent
|childs
|semantics
|inheritedAttributes
|ownAttributes
|constraints
|notes
|example
}}
</nowiki></pre>
 
Do the "preview" cycle. :-) Nothing changed? That's good news. Go further.
</li>
 
<li>
 
Insert some further information.<br>
 
example:
<pre><nowiki>{{ElementDocu
|elementName = speedProfiles
|parent =  {{IS:Tag|infrastructure}}
|childs = {{IS:Tag|speedProfile}}
|semantics =
The element {{IS:Tag|speedProfiles}} works as a "container element" for {{IS:Tag|speedProfile}} elements.
 
|inheritedAttributes
|ownAttributes
|constraints
|notes
|example
}}
</nowiki></pre>
 
Do the "preview" cycle. :-) "FIXME"s left? Fine.
 
Leave other parameters blank for easier later edition by other authors.
</li>
 
<li>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
 
<li>Submit your changes with "Save" or {{Deu|Speichern}}</li>
 
<li>Done. Thank you for your contribution.</li>
</ol>
 
=== 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 [[#Elements_without_parent_inheritance | previous section]].
 
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.
 
<ol>
<li>Define the wiki page name in the browser URL:
 
<pre>http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name></pre>
 
example: <code><nowiki>http://www.wiki.railml.org/index.php?title=IS:geoCoord_mileageChange</nowiki></code> results in http://www.wiki.railml.org/index.php?title=IS:geoCoord_mileageChange</li>
 
<li>You get a blank page with the possibility to "Edit".<br>
 
Choose "edit" or {{Deu | bearbeiten}}!</li>
 
<li>Search the appropriate [http://www.wiki.railml.org/index.php?title=Kategorie:ElementTemplate template for element content] to deploy.</li>
 
<li>Insert the template into the blank editor
 
<pre><nowiki>{{<template-name-without-prefix>}}</nowiki></pre>
 
example: <code><nowiki>{{InheritGeoCoord}}</nowiki></code>
 
Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further. </li>
 
<li>Insert parameters
 
<pre><nowiki>{{<template-name-without-prefix>
|<parameter-name>
}}</nowiki></pre>
 
You will find all possible parameters of a template by searching for <code><nowiki>{{{...}}}</nowiki></code> in the template plain code. They may occur in any order.
 
example:
<pre><nowiki>{{InheritGeoCoord
|parentLink
|selfLink
|semantics_en
|semantics_de
|constraints_en
|constraints_de
|notes_en
|notes_de
|coord
|coord_de
|extraHeight
|extraHeight_de
|epsgCode
|epsgCode_de
|heightEpsgCode
|heightEpsgCode_de
}}
</nowiki></pre>
 
Do the "preview" cycle. :-) Nothing changed? That's good news. Go further.
</li>
 
<li>
 
Insert some special information that is valid only for this element in a certain position of the XML tree.<br>
 
example:
<pre><nowiki>|parentLink = {{IS:Tag|mileageChange}}
|selfLink = {{IS:Tag|geoCoord|mileageChange}}
</nowiki></pre>
 
Do the "preview" cycle. :-) "FIXME"s left? Fine.
 
Leave other parameters blank for easier later edition by other authors.
 
If there are some further explanations, that are not only important for the current element but for all elements of this kind, please edit the template.
</li>
 
<li>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
 
<li>Submit your changes with "Save" or {{Deu|Speichern}}</li>
 
<li>Done. Thank you for your contribution.</li>
</ol>
 
== Text flow templates ==
 
=== Attributes ===
 
The following template may be used at every wiki page for a corporate layout for attributes and attribute values:
 
<pre><nowiki>{{Attr | <attribute-name>}}</nowiki></pre>
 
example: <code><nowiki>{{Attr | axleSequence}}</nowiki></code> results in {{Attr | 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: <code><...></code>. It looks like an XML element.
 
<ul>
<li>Elements without parent inheritance
 
<pre><nowiki>{{<sub-schema-prefix>:Tag|<element-name>}}</nowiki></pre>
 
example: <code><nowiki>{{RS:Tag|fourQuadrantChopper}}</nowiki></code> results in {{RS:Tag|fourQuadrantChopper}}</li>
 
<li>Elements with parent inheritance
 
<pre><nowiki>{{<sub-schema-prefix>:Tag|<element-name>|<parent-element-name>}}</nowiki></pre>
 
example: <code><nowiki>{{RS:Tag|additionalName|vehicle}}</nowiki></code> results in {{RS:Tag|additionalName|vehicle}}
</li></ul>
 
==== Pure link ====
 
The link is shown pure without any characters around. This is better for reading a text flow.
 
<ul>
<li>Elements without parent inheritance
 
<pre><nowiki>{{<sub-schema-prefix>:Doc|<element-name>}}</nowiki></pre>
 
example: <code><nowiki>{{RS:Doc|fourQuadrantChopper}}</nowiki></code> results in {{RS:Doc|fourQuadrantChopper}}</li>
 
<li>Elements with parent inheritance
 
<pre><nowiki>{{<sub-schema-prefix>:Doc|<element-name>|<parent-element-name>}}</nowiki></pre>
 
example: <code><nowiki>{{RS:Doc|additionalName|vehicle}}</nowiki></code> results in {{RS:Doc|additionalName|vehicle}}
</li></ul>
 
== Adjust the XML tree ==
<ol>
 
<li>Go to the [[CO:XMLtree | XML tree wiki page]]</li>
 
<li>Press "Edit" or {{Deu|Bearbeiten}}</li>
 
<li>Crawl to the right position in the railML tree<br>
 
Instead of scrolling there, it's easier to "search" for the parent element</li>
 
<li>Insert a new element with a new line at the appropriate position, if necessary<br>
 
Only insert one line for each different element no matter how often it may occur at this certain position in the XML instance document.
<ul>
 
<li>Start with the appropriate number of stars "*" indicating the depth in the XML tree.</li>
 
<li>Choose the appropriate wiki documentation [[#Link_in_angle_brackets | link in angle brackets]]</li>
 
<li>Add all possible attributes deploying the [[#Attributes | Attribute template]], separated by comma<br>
 
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)<br>
 
No matter, if the attributes are optional or mandatory.</li>
</ul>
 
example: <pre><nowiki>***{{TT:Tag|train}} {{Attr|type}}, {{Attr|trainNumber}}, {{Attr|additionalTrainNumber}}, {{Attr|scope}}, {{Attr|processStatus}}, {{Attr|id}}, {{Attr|code}}, {{Attr|name}}, {{Attr|description}}, {{Attr|xml:lang}}
</nowiki></pre>
</li>
 
<li>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
 
<li>Check your changes with "Preview" or {{Deu|Vorschau}}<br>
 
Adjust the page text where needed</li>
 
<li>Submit your changes with "Save" or {{Deu|Speichern}}</li>
 
<li>Done. Thank you for your contribution.</li>
</ol>
 
[[Category:GeneralDescription]]

Latest revision as of 17:13, 5 March 2021

🗒️ This page is mirrored from page Dev:Wiki Documentation Guidelines in The railML® 3 wiki.

Principles

  • Please, notice the basic Principles for joining this wiki, as explained here
  • The working language of this wiki is English. The complete content should be covered in English. Translations in German are welcome, but should not deliver additional content. Please, employ Template:Deu for German content, as to make the languages distinguishable at first glance.
  • This documentation should describe the currently supported versions of railML®. Please, neither describe obsolete versions (that are not any longer supported), nor describe future features.
  • The discussion pages are designated for issues about this wiki. Any discussions concerning e.g. the railML® schema and its further development should be led in the forum (link to the railML® website). User questions can be placed in the forum or sent to the coordinators (link to the railML® website). For very complex issues concerning the wiki, the forum can be the better place, too, rather than a wiki discussion page.
  • Employ the existing wiki templates where applicable. In particular stick to the markup guidelines.
  • As a privileged user, please review the changes continously; comp. Help:Page validation.
  • Please, follow the structuring guidelines for element pages.

Terminology

Please, use Template:rml for displaying the railML® logo. {{rml}} produces railML®. It is consens, that the initial letter r should allways be written small, and that the superscript ® should always be displayed. Both is granted for by the template. Don't use the superscript ® in URLs — such links cannot be processed! Instead, use railML in the URL and employ the vertical bar | to display an appropriate link text, e.g. [[dev:How to join, edit and create the railML wiki|How to join, edit and create the {{rml}} wiki]] for How to join, edit and create the railML® wiki.

Schema

Please, use the term schema rather than scheme and the plural form schemas rather than schemata.

The term schema denotes the complete railML® XML schema.

The schema has three subschemas: Timetable, Rollingstock and Infrastructure.

Key Words

Please, employ the key words must, must not, required, shall, shall not, should, should not, recommendended, may, and optional according to RFC 2119 (external link) (see wikipedia (external link) to learn more about RFCs, and CEN/CENELEC Rules of Procedure (external link)).

  • Must (also: required, shall, have to) denotes an absolute requirement.
  • May: (also: optional) denotes a true optionality. An implementation must interoperate with any other implementation, independent of whether either of the implementations employs the option except for the feature the option provides.
  • Must not (also: shall not) denotes an absolute prohibition.
  • Should (also: recommended) means that a course is not required, but the full implications must be understood before choosing a different course.
  • Should not (also: not recommended) means that a course is not prohibited, but the full implications must be understood before choosing that course.

Lists and enumerations

For attribute lists and value lists, please use concise language. Make enumerations rather than using complete sentences, as to avoid redundancies.

Language standards

Edit element documentation pages

The railML® wiki should document the actual state of railML®.


Please, describe only elements that already exist! Don't start articles about elements that are only in discussion or in development! You can start describing new elements as soon as they are part of a release candidate version of railML®.
The core of this wiki are pages documenting single railML® elements. The framework for such pages is provided by template:ElementDocu. Please, stick to it as to ensure a corporate layout.
In most cases the element documentation pages are already defined. If not, have a look at the Developers Guide for new element documentation sites.

Please, employ Template:Constraint, whereever defaults are being defined. For the details, read Dev:Defaults.

New pages are created automatically with the publication of new versions.

For every element there exist a hand page, framing plus one or more robot pages:

  • Hand pages are named according to the schema <subshema slug>:<element name>, e.g. for element interlocking the hand page is <interlocking>. This page is meant for contributions by wiki-authors. Feel free to edit them manually.
🗒️ please do not edit subsection #Syntax manually.
  • Robot pages are named according to the schema <subshema slug>:<element name>/<version number>. E.g. for element interlocking there exist the pages IL:interlocking/3.1 and IL:interlocking/3.2.
🗒️ Please, never edit robot pages manually.

Start a new railML Wiki page for a new railML element

Allways use Template:ElementDocu to grant for a uniform presentation of railML®-elements. An explanation of the procedure can be found here.


In special cases, you can employ a template that is based on Template:ElementDocu as to inherit certain data. Read here, how to do so.

New element pages should be generated automatically.

🗒️ Please, do not create new element pages by hand!

Adjust the XML tree

We offer the readers an XML-Tree on page dev:XMLtree.

Whereever the structure of railML changes with a new release (new or depricated elements and/or attributes), the tree should be actualized.

An instruction on how to edit the tree can be found here.

Enter mathematical Formulas

This wiki does not offer you a math mode. Therefore you should insert formulas as graphics:

  • Create the formula e.g. with a word processor; save it as a graphic
    If you use an online formula editor, please be aware of the terms of use. You do it at your own liability.
  • Upload it via the page Special:Upload
  • Insert it with [[file:<file name>|x<height>]], e.g. <nowiki>[[File:Example formula.png|x15px]] for Example formula.png — the x states, that the 15 points are the height rather than the width; 15px fits well into the line height.

Citations and References

Footnotes

Please, reference sources in footnotes rather than in the running text. Footnotes can be generated with <ref> tags. A documentation of <ref> tags can be found at mediawiki.org (external link). As to provide a uniform page structure, don't forget to add a section

== References ==

containing the <references /> call.

References outside our wikis

Within the <ref> tags, the references should be depicted in a standardized way using one of the folloging templates:

Images

A general outline how to include images in mediawiki can be found at Help:Images (Wiki banner.png).

Please, respect other people's copyrights.

Within this wiki:

  • You can upload and include images without reference, if:
    • the image belongs to railML® e.V.
    • the owner explicitly made the image available for railML® e.V.
    • the image belogns to the public domain or similar (e.g. CCO (external link))
  • If you reference it correctly, you can upload and use images:
    • Images that are explicitly licenced for railML® e.V. with obligation of reference
    • Images under certain Creative Commons licences (Wiki banner.png):
CC-BY (external link)
CC-BY-ND (external link)
For displaying the references of a CC-licenced image Template:CC may be helpful. You might find it convenient to enter the reference in Template:Licence.
  • Please, do Not upload or include images:
Without explicit permission
Of unknown origin
Share Alike licences, e.g. CC-SA (external link) in any combination
Noncommercial licences, e.g. CC-NC (external link) in any combination
A viable workaround is to offer a link to an image on the owners website. Please, avoid deep links (Wiki banner.png) directly to the image file like in this example (external link). Rather, link to a page that presents the file like here (external link).

Use cases

The railML® wiki offers a number of Use Cases.

A Guideline to implementing Use Cases can be found under Dev:Use cases.

Examples

In contrast to railML® 2, railML® 3 is not supposed to be backward compatible. As a consequence, Examples may be relevant for one version only. Please, always make clear, to which version an example applies!

Discussion Pages

All Wiki Pages have a discussion page which is linked at the top of the page. There, all matters concerning the page can be discussed.

Dos & Don'ts

  • Please, use this page to discuss issues of the referring article
  • Please, don't discuss the object of the article here. Questions, suggestions etc. about e.g. a certein railML®-Element should be addressed in the forum (external link).
  • Let us share in your cordial nature.

Formal Guideline

  • Start a new chapter for a new issue to discuss: ===<Title of the issue>===
  • Allways sign your contributions with —~~~~ — the four tildas will be replaced automatically with your user name and a time stamp
  • If you answer somebody, show this by indenting the text. You can set indents with colons (:) at the start of the line. Allways use one colon more than the person you are answering.
Example: Two colons (::) to indent this line towards the line above.