Dev:How to join, edit and create the railML wiki: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(Mirror)
Tag: Replaced
Line 1: Line 1:
{|
{{mirror}}
|This wiki should supporting the development of railML-schemes. It allows users to create new content and edit existing articles, and setup a comprehensive knowledge database to the railML standard.<br>
|{{Deu|Mit Hilfe dieses {{external|http://de.wikipedia.org/wiki/Wiki|Wikis|inlang=de|lang=de}} soll der Einstieg in die Entwicklung der railML-Teilschemen 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.}}
|}
==Principles==
*As a small community we have a real name policy and give writing privileges only to registered Users. The registration procedure is explained [[#How to join the Wiki|below]]. Edits will become visible to the public only after review. If you decide not to register we will yet appreciate your feedback via e-mail.
*Please, follow both the common rules of a beneficial coexistence and the [[Dev:Wiki Documentation Guidelines|Guidelines of this wiki]].
 
== How to join the Wiki ==
To obtain editing privileges on the railML<sup>®</sup> wiki you have to register with {{site|http://www.railml.org|railML.org}} and then ask for a wiki account. Please, understand that the preference for writing privileges will be given to experienced users from registered partners, as we prefer a long lasting cooperation.
*Register at {{site|http://www.railml.org/en/login-registration.html}}
*Send an e-mail to the coordinator (coordination ät raiML dot org). We appreciate you explaining us your motivation and working expericence with railML schemes.
*The coordinator will provide you a separate wiki account.
*Log into the wiki at [[Special:UserLogin]]
*Now you can start contributing.
As a logged in user, you can [[Special:preferences|set the interface language]] by you whish.
 
== How to contribute ==
As a registered User, you can edit the railML<sup>®</sup> wiki. Your contributions will be reviewed by a coordinator bevore merged to the checked stuff. The changes are visible at a special page also short after editing.
 
The principles of editing a wiki are explained {{external|https://meta.wikimedia.org/wiki/Help:Editing_FAQ|here}}.
 
As of January 2020 we do not yet offer the '''{{external|https://en.wikipedia.org/wiki/Wikipedia:VisualEditor|VisualEditor}}''' you may know from {{external|https://en.wikipedia.org|Wikipedia}}, as it is not yet stable and requires additional alpha software.
 
Please, stick to our common templates to allow for a standardized documentation. Some essential templates are explained on [[dev:Special_Wiki_Markup|railML markup templates]]. Especially, employ [[template:external]] for external links.
===Edit a page===
In the case you want to change or extend some content on a certain element documentation page, do the following:
# Log in or register
# Go to the certain wiki site
# Choose "Edit"!
# Extend or change the content by deploying the [[dev:Special_Wiki_Markup| railML markup templates]].
::Please respect others work and publish changements prior to the edit in the appropriate {{site|http://forum.railml.org|forum}}.
::Please be careful (especially with brackets), there are parameters to fill. Sometimes some surprise occurs after a preview.
# Do the "preview" cycle. All fine?
# Describe your changes with "Summary".
# Submit your changes with "Save"
# Done. Thank you for your contribution.
 
=== Adjust the XML tree ===
<ol>
 
<li>Go to the [[dev: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 element documentation page deploying the [[dev:Special_Wiki_Markup#Link_in_angle_brackets | link in angle brackets]]</li>
 
<li>Add all possible attributes deploying the [[dev:Special_Wiki_Markup#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>
 
== Start a new railML Wiki page for a new railML element ==
The documentation paradigm of {{rml|2}} and {{rml|3}} differ fundamentally. Therefore,the processes will be described separately, '''beginning with {{rml|3}}.
=== In {{rml|3}} ===
In {{rml|3}}, new element pages are generated automatically. They will contain default chapters. Feel free to add content.
{{note|Don't remove or expand {{wiki3|template:robot}}!|error}}
{{note|Don't edit the automatically maintained version pages!
 
These pages contain [[template:Schemaexport]] and their pagenames end with a version number, e.g.: ''/3.1''|error}}
 
=== In {{rml|2}} ===
==== 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 [[#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://wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name></pre>
 
example: <code><nowiki>http://wiki.railml.org/index.php?title=IS:speedProfiles</nowiki></code> results in http://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 [[template: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>
 
Deploy [[dev:Special_Wiki_Markup|railML markup templates]] whereever useful.<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://wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name></pre>
 
example: <code><nowiki>http://wiki.railml.org/index.php?title=IS:geoCoord_mileageChange</nowiki></code> results in http://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 [[:Category:Element_Template| 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>{{InheritAdditionalName}}</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>{{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=
}}
</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>
 
Deploy [[dev:Special_Wiki_Markup|railML markup templates]] whereever useful.<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>
 
==Support==
We appreciate your interest to contribute to the railML<sup>®</sup> wiki and will try to support you.
* A documentation for the mediawiki sofware which is the basis of this wiki can be found {{external|https://www.mediawiki.org/wiki/Help:Contents|here}}.
* Please, follow [[Dev:Wiki_Documentation_Guidelines|our Wiki Documentation Guidelines]].
* Questions referring to the use of this wiki are welcome on [[Diskussion:How_to_join,_edit_and_create_the_railML_wiki|the discussion page]].
* Please, act responsibly with contacting the webmaster (webmaster ät railml dot org).
 
[[Category:GeneralDescription]]

Revision as of 14:35, 23 November 2020

🗒️ This page is mirrored from page Dev:How to join, edit and create the railML wiki in The railML® 3 wiki.
This wiki should be supporting the development of railML-schemes. 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-Teilschemen 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 railML2 (link to the railML® website), railML3 (link to the railML® website) as well as railML Ontology, which facilitates interoperability and data exchange between different rail systems and applications. Additionally, RailTopoModel (link to the railML® website) 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 https://wiki3.railml.org/wiki/File:Preview_of_editing.svg

Edit a page

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

  1. Ensure you are logged in as a registered user on the website railml.org. If not, follow the provided steps to register.
  2. Go to the respective railML Wiki page you want to edit. If login issues persist, refer to the steps outlined above.
  3. 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.
  4. ‘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.
  5. 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.
  6. 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.
  7. 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 this Wikipage:
  8. Alternatively, use the search option to find relevant subschema pages.
  9. 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.
  10. 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.
  11. Before finalising, perform a ‘Preview’ to catch any potential issues. Ensure template parameters and closing brackets are accurate.
  12. Describe your changes in the ‘Summary’ section to provide context.
  13. Submit your changes by clicking ‘Save’. Confirm that your changes are satisfactory. Address any surprises, especially regarding template parameters.
  14. 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

  1. Go to the XML tree wiki page
  2. Press "Edit" or Bearbeiten
  3. Crawl to the right position in the railML tree
    Instead of scrolling there, it's easier to "search" for the parent element
  4. 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}}
    
  5. Describe your changes with "Summary" or Zusammenfassung
  6. Check your changes with "Preview" or Vorschau
    Adjust the page text where needed
  7. Submit your changes with "Save" or Speichern
  8. Done. Thank you for your contribution.

Start a new railML Wiki page for a new railML element

The documentation paradigm of railML® 2 and railML® 3 differ fundamentally. Therefore,the processes will be described separately, beginning with railML® 3. In railML® 3, new element pages are generated automatically. They will contain default chapters. Feel free to add content.

🗒️ Don't remove or expand template:robot!
🗒️ Don't edit the automatically maintained version pages!

These pages contain template:Schemaexport and their pagenames end with a version number, e.g.: /3.1


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).