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]
No edit summary
No edit summary
(30 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{|
{|
|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>
|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 [http://de.wikipedia.org/wiki/Wiki Wikis] 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.}}
|{{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==
==Principles==
*The working language of this wiki is Englisch. The complete content should be covered in English. Translations in German and French are welcome, but should not deliver additional content. Please, employ [[Template:Deu]] for German content and [[Template:Fra]] for french content, as to make the languages distinguishable at first sight.
*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.
*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.
*Please, follow both the common rules of a beneficial coexistence and the [[Dev:Wiki Documentation Guidelines|Guidelines of this wiki]].
*Please, follow both the common rules of a beneficial coexistence ant the [[Dev:Wiki Documentation Guidelines|Guidelines of this wiki]].
 
== How to join the Wiki ==
== How to join the Wiki ==
Joining the Wiki is very easy and only a matter of seconds.
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 release your common railML login to be a wiki login too.
*Log in at {{site|http://railml.org}} (or [[Special:UserLogin|direct at the wiki]]).
*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 Summer 2017 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>


#''Go to the login page''
<li>Add all possible attributes deploying the [[dev:Special_Wiki_Markup#Attributes | Attribute template]], separated by comma<br>
#*In the upper right corner of this page, you find a link to [http://wiki.railml.org/index.php?title=Spezial:Userlogin sign in] to this Wiki. If you currently use the German layout of this Wiki, the link is called "Anmelden".
#*Follow that link to get to the login page.
# ''Choose a user name and a password''
#*The first two text fields of the login page ask you to enter a user name and a password. The username can be arbitrary, but should be the full real name (first name(s) followed by your complete last name, like [[Benutzer:Philip_Wobst | Philip Wobst]] for example). Nicknames or company names are not accepted.
#*Since you are new to Wiki, you must re-enter you password, enter your email address and your real name. That what the lower three text fields are for.
#*Now you can request a new account ("Neues Nutzerkonto anlegen") and after confirmation by a railML admin you'll able to work with the Wiki!
#''Confirm your mail address''
#*Immediately after creating a new account, an email is sent to you which contains a link. Click that link to confirm that the mail address you've entered above is really yours.
#''That's it!''
#*You are ready to contribute to the Wiki!
#*If you like to, you can enter some information about you on your personal page. Your personal page's name is Benutzer:Username (like [[Benutzer:Philip_Wobst | Benutzer:Philip_Wobst]]).


=== How to contribute ===
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>


==== Edit element documentation sites ====
No matter, if the attributes are optional or mandatory.</li>
All articles must be created in English. Additional German comments are welcomed. The language of the user interface can be changed after login. In order to ensure a corporate layout, please use the [[CO:Special_Wiki_Markup| railML markup templates]] in your edits. Please refer to the [http://meta.wikipedia.org/wiki/MediaWiki_User%27s_Guide user manual] (external link to a different wiki - not railML) for help to edit the wiki.<br>
</ul>
{{Deu|Um ein einheitliches Layout zu erreichen, nutzen Sie bitte die [[CO:Special_Wiki_Markup| railML Auszeichnungsvorlagen]]. Hilfe zum Bearbeiten des Wikis finden Sie im [http://meta.wikipedia.org/wiki/MediaWiki_User%27s_Guide Benutzerhandbuch] (externer Link zu einem anderen Wiki - nicht railML).}}


In most cases the [[:Category:RailML_Documentation | element documentation sites]] are already defined. If not, have a look at the [[Dev:Wiki_Documentation_Guidelines#Start_a_new_railML_Wiki_page_for_a_new_railML_element | Developers Guide for new element documentation sites]].
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>


In the case you want to change or extend some content on a certain [[:Category:RailML_Documentation | element documentation site]], do the following:
<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 ==
 
=== 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>
<ol>
<li>Go to the certain wiki site</li>
<li>Define the wiki page name in the browser URL:


<li>Choose "Edit" or {{Deu | Bearbeiten}}!</li>
<pre>http://wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name></pre>


<li>Extend or change the content by deploying the [[CO:Special_Wiki_Markup| railML markup templates]].
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>


Please respect others work and publish changements prior to the edit in the appropriate [http://forum.railml.org Forum].
<li>You get a blank page with the possibility to "Edit".<br>


Please be careful (especially with brackets), there are parameters to fill. Sometimes some surprise occurs after a preview.</li>
Choose "edit" or {{Deu | bearbeiten}}!</li>


<li>Do the "preview" cycle. All fine?</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>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
Line 53: Line 156:
</ol>
</ol>


==== Edit or create FAQ sites ====
=== 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.


Sometimes more general topics should be summarized covering a bunch of elements. That's a good point to start a FAQ page in the appropriate sub-schema.
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>
<ol>
<li>Define the wiki page name in the browser URL:
<li>Define the wiki page name in the browser URL:


<pre>http://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<page-name-with-underscores></pre>
<pre>http://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=Dev:Wiki_Documentation_Guidelines</nowiki></code> results in http://www.wiki.railml.org/index.php?title=Dev:Wiki_Documentation_Guidelines</li>
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>
<li>You get a blank page with the possibility to "Edit".<br>


Choose "Edit" or {{Deu | Bearbeiten}}!</li>
Choose "edit" or {{Deu | bearbeiten}}!</li>
<li>Insert the content you may contribute by deploying the [[CO:Special_Wiki_Markup| railML markup templates]]</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>{{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>Do the "preview" cycle. All fine?</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>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
Line 77: Line 241:
<li>Done. Thank you for your contribution.</li>
<li>Done. Thank you for your contribution.</li>
</ol>
</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:51, 19 August 2019

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

Principles

  • As a small community we have a real name policy and give writing privileges only to registered Users. The registration procedure is explained 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 Guidelines of this wiki.

How to join the Wiki

To obtain editing privileges on the railML® wiki you have to register with railML.org (link to the railML® website) 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 http://www.railml.org/en/login-registration.html (link to the railML® website)
  • 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 release your common railML login to be a wiki login too.
  • Log in at http://railml.org (link to the railML® website) (or direct at the wiki).
  • Now you can start contributing.

As a logged in user, you can set the interface language by you whish.

How to contribute

As a registered User, you can edit the railML® 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 here (external link).

As of Summer 2017 we do not yet offer the VisualEditor (external link) you may know from Wikipedia (external link), 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 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:

  1. Log in or register
  2. Go to the certain wiki site
  3. Choose "Edit"!
  4. Extend or change the content by deploying the railML markup templates.
Please respect others work and publish changements prior to the edit in the appropriate forum (link to the railML® website).
Please be careful (especially with brackets), there are parameters to fill. Sometimes some surprise occurs after a preview.
  1. Do the "preview" cycle. All fine?
  2. Describe your changes with "Summary".
  3. Submit your changes with "Save"
  4. Done. Thank you for your contribution.

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

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.

  1. Define the wiki page name in the browser URL:
    http://wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>
    example: http://wiki.railml.org/index.php?title=IS:speedProfiles results in http://wiki.railml.org/index.php?title=IS:speedProfiles
  2. You get a blank page with the possibility to "Edit".
    Choose "edit" or bearbeiten!
  3. Insert the element documentation template into the blank editor
    {{ElementDocu}}
    Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further.
  4. 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.

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

  6. Describe your changes with "Summary" or Zusammenfassung
  7. Submit your changes with "Save" or Speichern
  8. 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.

  1. Define the wiki page name in the browser URL:
    http://wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>
    example: http://wiki.railml.org/index.php?title=IS:geoCoord_mileageChange results in http://wiki.railml.org/index.php?title=IS:geoCoord_mileageChange
  2. You get a blank page with the possibility to "Edit".
    Choose "edit" or bearbeiten!
  3. Search the appropriate template for element content to deploy.
  4. Insert the template into the blank editor
    {{<template-name-without-prefix>}}

    example: {{InheritGeoCoord}}

    Do the "preview" cycle. :-) Do you encounter some "FIXME" strings? Go further.
  5. 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:

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

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

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

  7. Describe your changes with "Summary" or Zusammenfassung
  8. Submit your changes with "Save" or Speichern
  9. 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).