Dev:Wiki Documentation Guidelines: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
m (Category added)
(Inter-wiki-links with templates added, XML tree documentation adjusted)
Line 1: Line 1:
== Start a new railML Wiki page for a new railML element ==
== Start a new railML Wiki page for a new railML element ==


[to be written]
== Text flow templates ==
 
=== Attributes ===
 
The following template may be used at every wiki page for a corporate layout for attributes and attribute values:
 
<pre><nowiki>{{Attr | <attribute-name>}}</nowiki></pre>
 
example: <code><nowiki>{{Attr | axleSequence}}</nowiki></code> results in {{Attr | axleSequence}}
 
=== 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></li>
</ul>
 
example: <code><nowiki>{{RS:Tag|additionalName|vehicle}}</nowiki></code> results in {{RS:Tag|additionalName|vehicle}}
 
==== 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></li>
</ul>
 
example: <code><nowiki>{{RS:Doc|additionalName|vehicle}}</nowiki></code> results in {{RS:Doc|additionalName|vehicle}}


== Adjust the XML tree ==
== Adjust the XML tree ==
Line 14: Line 62:
Instead of scrolling there, it's easier to "search" for the parent element</li>
Instead of scrolling there, it's easier to "search" for the parent element</li>


<li>Insert the new element<br>
<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>
<ul>


<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>Define the wiki link page with the appropriate syntax (see other element page links as examples)<br>
<li>Choose the appropriate wiki documentation [[#Link_in_angle_brackets | link in angle brackets]]</li>


example: <code><nowiki>******{{RS:Tag|fourQuadrantChopper}}</nowiki></code><br>
<li>Add all possible attributes deploying the [[#Attributes | Attribute template]], separated by comma<br>


Be careful with "generic" sub-elements, they get an additional link part for the parent element<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>


example: <code><nowiki>****{{RS:Tag|additionalName|vehicle}}</nowiki></code></li>
No matter, if the attributes are optional or mandatory.</li>
 
</ul>
<li>Add all possible attributes, 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>


example: <code><nowiki> {{Attr|startDate}}, {{Attr|endDate}}, {{Attr|id}}, {{Attr|code}}, {{Attr|name}}, {{Attr|description}}, {{Attr|xml:lang}}</nowiki></code></li>
example: <pre><nowiki>****{{RS:Tag|additionalName|vehicle}} {{Attr|name}}, {{Attr|description}}, {{Attr|xml:lang}}</nowiki></pre>
</ul></li>
</li>


<li>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>
<li>Describe your changes with "Summary" or {{Deu|Zusammenfassung}}</li>

Revision as of 17:17, 17 October 2012

Start a new railML Wiki page for a new railML element

Text flow templates

Attributes

The following template may be used at every wiki page for a corporate layout for attributes and attribute values: 

{{Attr | <attribute-name>}}

example: {{Attr | axleSequence}} results in axleSequence

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: <...>. It looks like an XML element.

  • Elements without parent inheritance 
    {{<sub-schema-prefix>:Tag|<element-name>}}
    example: {{RS:Tag|fourQuadrantChopper}} results in <fourQuadrantChopper>
  • Elements with parent inheritance 
    {{<sub-schema-prefix>:Tag|<element-name>|<parent-element-name>}}

example: {{RS:Tag|additionalName|vehicle}} results in <additionalName>

Pure link

The link is shown pure without any characters around. This is better for reading a text flow.

  • Elements without parent inheritance 
    {{<sub-schema-prefix>:Doc|<element-name>}}
    example: {{RS:Doc|fourQuadrantChopper}} results in fourQuadrantChopper
  • Elements with parent inheritance 
    {{<sub-schema-prefix>:Doc|<element-name>|<parent-element-name>}}

example: {{RS:Doc|additionalName|vehicle}} results in additionalName

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 wiki documentation 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: 
    ****{{RS:Tag|additionalName|vehicle}} {{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=3287"