Dev:Wiki Documentation Guidelines: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
(General wiki markup moved from here to a new wiki page "Special_Wiki_Markup")
Line 45: Line 45:


Insert some further information.<br>
Insert some further information.<br>
Deploy [[CO:Special_Wiki_Markup|railML markup templates]] whereever useful.<br>


example:
example:
Line 138: Line 140:


Insert some special information that is valid only for this element in a certain position of the XML tree.<br>
Insert some special information that is valid only for this element in a certain position of the XML tree.<br>
Deploy [[CO:Special_Wiki_Markup|railML markup templates]] whereever useful.<br>


example:
example:
Line 157: Line 161:
<li>Done. Thank you for your contribution.</li>
<li>Done. Thank you for your contribution.</li>
</ol>
</ol>
== Text flow templates ==
=== 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>
=== Generic links for types ===
The following templates may be used at every wiki page for refering to
a certain simple type constraint.
==== railML types ====
It shows a link to the basic [http://www.w3.org/TR/xmlschema-2 W3C XML schema type] re-used by railML for a certain reason. It does not cover complex types or enumeration lists.
<pre><nowiki>{{RailMLType|<type-name>}}</nowiki></pre>
example: <code><nowiki>{{RailMLType|tGenericRef}}</nowiki></code> results in {{RailMLType|tGenericRef}}
==== Pure XML Schema types ====
It shows a link to the basic [http://www.w3.org/TR/xmlschema-2 W3C XML schema type].
<pre><nowiki>{{XsdType|<type-name>}}</nowiki></pre>
example: <code><nowiki>{{XsdType|string}}</nowiki></code> results in {{XsdType|string}}
=== Version management ===
The current wiki does not support version management itself. That's the reason for the templates explained in the following sections.
==== New objects ====
If new objects are introduced with some [[CO:versions|official version number]], use the following template for showing it:
<pre><nowiki>{{Intro | <version-number>}}</nowiki></pre>
example: <code><nowiki>{{Intro | 2.1}}</nowiki></code> results in {{Intro | 2.1}}
There is no difference in handling between elements, attributes, enumeration values, occurence changes...
==== Deprecated objects ====
If objects are declared "deprecated" they are kept until the next [[CO:versions|major release]].
<pre><nowiki>{{Depr | <version-number>}}</nowiki></pre>
example: <code><nowiki>{{Depr | 2.1}}</nowiki></code> results in {{Depr | 2.1}}
There is no difference in handling between elements, attributes, enumeration values, occurence changes...
=== Attributes ===
The following template may be used at every wiki page for a corporate layout for attributes:
<pre><nowiki>{{Attr | <attribute-name>}}</nowiki></pre>
example: <code><nowiki>{{Attr | axleSequence}}</nowiki></code> results in {{Attr | axleSequence}}
=== Enumeration values ===
The following template may be used at every wiki page for a corporate layout for enumeration values:
<pre><nowiki>{{Enum | <enumeration-value>}}</nowiki></pre>
example: <code><nowiki>{{Enum | mechanical}}</nowiki></code> results in {{Enum | mechanical}}
=== German layout (de: Deutsche Auszeichnung) ===
It's a good practice to translate some paragraphs and/or words into German since there are many German railML users. In order to offer a flexible layout, please use the following template:
<pre><nowiki>{{Deu | <deutscher-text>}}</nowiki></pre>
example: <code><nowiki>{{Deu | Deutsche Erläuterung}}</nowiki></code> results in {{Deu | Deutsche Erläuterung}}


== Adjust the XML tree ==
== Adjust the XML tree ==
Line 287: Line 180:
<li>Start with the appropriate number of stars "*" indicating the depth in the XML tree.</li>
<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>Choose the appropriate [[:Category:RailML_Documentation | element documentation site]] deploying the [[CO:Special_Wiki_Markup#Link_in_angle_brackets | link in angle brackets]]</li>


<li>Add all possible attributes deploying the [[#Attributes | Attribute template]], separated by comma<br>
<li>Add all possible attributes deploying the [[CO: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>
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>

Revision as of 12:10, 24 October 2012

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 element. 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://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>
    example: http://www.wiki.railml.org/index.php?title=IS:speedProfiles results in http://www.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://www.wiki.railml.org/index.php?title=<sub-schema-prefix>:<element-name>_<parent-element-name>
    example: http://www.wiki.railml.org/index.php?title=IS:geoCoord_mileageChange results in http://www.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.
Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Wiki_Documentation_Guidelines&oldid=3380"