Dev:Wiki Documentation Guidelines

From railML 2 Wiki
Jump to navigation Jump to search

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. [[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 four subschemas: Timetable, Rollingstock, Infrastructure and Interlocking.

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

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

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.

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

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; 15pt corresponds with the line height.

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.