Dev:How to edit and contribute to the Wiki

This wiki should be supporting the development of railML^® schemas. It allows users to create new content and edit existing articles, and setup a comprehensive knowledge database to the railML^® standard.

Mit Hilfe dieses Wikis (externer Link, 🇩🇪) soll der Einstieg in die Entwicklung der railML^®-Teilschemas erleichtert werden. Es ermöglicht den Benutzern neue Inhalte zu schaffen, sowie vorhandene Beiträge zu bearbeiten und damit eine umfassende Wissensdatenbank zum railML^®-Standard aufzubauen.

Introduction

This platform serves as a central hub for information and collaboration. To maintain a thriving and collaborative environment, we have established these guidelines to help users understand how to join, contribute and edit content. railML^® is an open-source data exchange standard specifically tailored for railway applications. It includes railML^® 2 and railML^® 3 as well as railML^® Ontology, which facilitates interoperability and data exchange between different rail systems and applications. Additionally, RailTopoModel^® provides frameworks and models for representing railway infrastructure and operations in a standardized manner.

Principles

Our Wiki is built on the following principles:

We adhere to an authenticity policy, requiring users to register with their real names. This promotes transparency and accountability within our community.
Writing privileges are granted only to registered users. The registration procedure is explained below. If you decide not to register, we would still appreciate your feedback via e-mail.
Edits will undergo review, which users can locate under ‘Pending changes’ label, to ensure the accuracy and quality of the information shared.
When contributing to the Wiki, prioritise clarity and user-friendly language to enhance the understanding of railway software operations for users with varying levels of understanding.
All information added to the Wiki should be backed by citeable sources whenever possible. This ensures that the information presented is reliable and can be verified by others.
Contributions should be neutral and free from bias. Avoid promoting specific tools or companies and strive to present information objectively.
Aim to provide information that is applicable and relevant across different countries and regions. Avoid references or details specific to a particular country's regulations or practices unless it is necessary for context and strive to keep the content relevant to a general audience.

By following these principles, we can collectively build a robust knowledge base that reflects the values and standards of our community while ensuring the understandability and integrity of railML.

How to register to the Wiki

To contribute to the railML Wiki, you need to register on the website railML.org and request a Wiki account. Preference for writing privileges is given to experienced users from our registered partners, with whom we seek to build long-term collaborative working relationships. To join, please follow these steps:

Visit the following link https://www.railml.org/en/registration.html and complete the registration process.
Send an e-mail to our coordinator from your company business e-mail. Additionally, you may include information about your motivation and experience with railML schemas in the e-mail.
The coordinator will review your request and provide you with a separate Wiki account.
Log in to https://railml.org (link to the railML^® website) using your e-mail (account). Once logged in, you can navigate to the Wiki section from the website and start contributing to the railML Wiki.
Please note that the system will automatically switch to the Wiki page for editing. If not, click on ‘Log into railml.org’ on the Wiki page, log out and log in again to ensure your account is active for Wiki contributions. We also recommend checking your browser and cookie settings if necessary.
As a logged-in user, you can set the interface language according to your preference.

How to contribute

As a registered user on the railML Wiki, you have the possibility to contribute and help improve our documentation. We encourage active participation and contributions from all members. Before contributing, familiarise yourself with existing content to avoid duplication.

The principles of editing a wiki are explained here (external link).

Please, stick to our common templates to allow for a standardized documentation. Some essential templates are explained on railML^® markup templates. Especially, employ template:external for external links.

Preview of editing before saving the changes

Edit a page

If you want to change or extend some content on a specific railML element page, do the following:

Ensure you are logged in as a registered user on the website railml.org. If not, follow the provided steps to register.
Go to the respective railML Wiki page you want to edit. If login issues persist, refer to the steps outlined above.
Click on ‘Edit’ to begin changes. ‘Edit’ button typically allows you to edit the content of an element page within a visual editor for general cases. However, when working with railML®, we use extensive markup templates. Thus the ‘Edit’ button limits you to open the template editor and modify parameters in the source editor within it.
‘Edit source’ button, on the other hand, takes you to the Wiki markup or Wiki text editor where you can edit the underlying code that generates the page’s layout and formatting. This is useful for making more complex changes or for contributors who prefer working with markup directly.
Use the “Preview” feature. Look for a button labelled “Show Preview” within the editing interface. This option is typically located between “Submit changes” and “Show changes” button. Click on this to see how your edits will appear once published, without actually making the changes live on the Wiki. Here you can see the example of a preview after you edit.
Please refrain from editing “Documentation” section of railML Wiki3 as this will be overwritten by the automatic transfer from the XSD documentation to the Wiki.
We highly encourage users to focus their efforts on the “Introduction”, “Best Practice/Examples” or “Additional Information” sections. This area is important for seeking practical advice and real-world applications of railML. You can see the best practice under the following wiki pages:
- https://wiki3.railml.org/wiki/IS:speedSection or
- https://wiki3.railml.org/wiki/IS:overCrossing
Alternatively, use the search option to find relevant subschema pages.
If you have difficulty editing the page and it displays or mentions ‘Mirror’, it indicates that the content resides on another railML Wiki. To edit the desired page, simply navigate to the appropriate Wiki installation - railML2 or railML3 respectively.
Respect others’ contributions. Discuss proposed changes in the appropriate railML forum (link to the railML^® website) before editing. Engage in discussions on railML forum to share ideas, ask questions and provide feedback as well.
Before finalising, perform a ‘Preview’ to catch any potential issues. Ensure template parameters and closing brackets are accurate.
Describe your changes in the ‘Summary’ section to provide context.
Submit your changes by clicking ‘Save’. Confirm that your changes are satisfactory. Address any surprises, especially regarding template parameters.
Your contribution is complete. Thank you for enhancing railML documentation.

If you are uncertain about the changes you have made, do not hesitate to reach out railML for a review and feedback. In case your edits get reverted (external link), please understand that is our part of review process. We appreciate your dedication to enhancing the railML Wiki community!

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 element documentation page deploying the 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.
example:
```
***{{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.

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 elements. See 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.

Define the wiki page name in the browser URL:

https://wiki2.railml.org/wiki/<sub-schema-prefix>:<element-name>

example:

https://wiki2.railml.org/wiki/IS:speedProfiles

results in https://wiki2.railml.org/wiki/IS:speedProfiles

You get a blank page with the possibility to "Edit".
Choose "edit" or bearbeiten!
Insert the element documentation template into the blank editor
```
{{ElementDocu}}
```
Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further.

Insert parameters, they may occur in any order.

{{ElementDocu
|elementName
|parent
|childs
|semantics
|inheritedAttributes
|ownAttributes
|constraints
|notes
|example
}}

Do the "preview" cycle. :-) Nothing changed? That's good news. Go further.

Insert some further information.
Deploy railML^® markup templates whereever useful.
example:

{{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
}}

Do the "preview" cycle. :-) "FIXME"s left? Fine.

Leave other parameters blank for easier later edition by other authors.

Describe your changes with "Summary" or Zusammenfassung
Submit your changes with "Save" or Speichern
Done. Thank you for your contribution.

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.

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.

Define the wiki page name in the browser URL:

https://wiki2.railml.org/wiki/<sub-schema-prefix>:<element-name>_<parent-element-name>

example:

https://wiki2.railml.org/wiki/IS:geoCoord_mileageChange

results in https://wiki2.railml.org/wiki/IS:geoCoord_mileageChange

You get a blank page with the possibility to "Edit".
Choose "edit" or bearbeiten!
Search the appropriate template for element content to deploy.
Insert the template into the blank editor
```
{{<template-name-without-prefix>}}
```
example: {{InheritAdditionalName}}
Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further.

Insert parameters

{{<template-name-without-prefix>
|<parameter-name>
}}

You will find all possible parameters of a template by searching for {{{...}}} in the template plain code. They may occur in any order.

example:

{{InheritAdditionalName
|parentLink=
|selfLink=
|semantics_en=
|semantics_de=
|constraints_en=
|constraints_de=
|notes_en=
|notes_de=
|name=
|name_de=
|description=
|description_de=
|childs=
|inheritedAttributes=
|attributes_en=
|attributes_de=
|example=
|intro=
|depr=
}}

Do the "preview" cycle. :-) Nothing changed? That's good news. Go further.

Insert some special information that is valid only for this element in a certain position of the XML tree.
Deploy railML^® markup templates whereever useful.
example:
```
|parentLink = {{IS:Tag|mileageChange}}
|selfLink = {{IS:Tag|geoCoord|mileageChange}}
```
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.
Describe your changes with "Summary" or Zusammenfassung
Submit your changes with "Save" or Speichern
Done. Thank you for your contribution.

Support

We appreciate your interest to contribute to the railML^® wiki and will try to support you.

A documentation for the mediawiki sofware which is the basis of this wiki can be found here (external link).
Please, follow our Wiki Documentation Guidelines.
Questions referring to the use of this wiki are welcome on the discussion page.
Please, act responsibly with contacting the webmaster (webmaster ät railml dot org).

Dev:How to edit and contribute to the Wiki

Contents

Introduction

Principles

How to register to the Wiki

How to contribute

Edit a page

Adjust the XML tree

Start a new railML^® Wiki page for a new railML^® element

Elements without parent inheritance

Elements with parent inheritance

Support

Navigation menu

Dev:How to edit and contribute to the Wiki

Introduction

Principles

How to register to the Wiki

How to contribute

Edit a page

Adjust the XML tree

Start a new railML® Wiki page for a new railML® element

Elements without parent inheritance

Elements with parent inheritance

Support

Navigation menu

Search

Start a new railML^® Wiki page for a new railML^® element