Dev:Wiki Structuring Guidelines: Difference between revisions

From railML 3 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
(→‎Structure {{rml|3}} Wiki: Punkte, Fettschrift)
Line 52: Line 52:


==Structure {{rml|3}} Wiki==
==Structure {{rml|3}} Wiki==
In the {{rml|3}} wiki, The pages are created via GWPS<ref name=gwps>GWPS = Gruschwitz' Wonderful Python Script</ref>. GWPS will for each element create a ''hand page'' that is supposed for content created by the wiki authors (best practice, notes etc) and a ''robot page'' that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page.
In the {{rml|3}} wiki, element pages are created via GWPS<ref name=gwps>GWPS = Gruschwitz' Wonderful Python Script</ref>. GWPS will for each element create a ''hand page'' that is supposed for content created by the wiki authors (best practice, notes etc) and a ''robot page'' that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page.
===Paragraphs ''Hand Pages''===
===Paragraphs ''Hand Pages''===
Hand pages are created by GWPS<ref name=gwps /> with [[Template:DocBase]] (which will be expanded by creation). Template:DocBase creates the following paragraphs:
Hand pages are created by GWPS<ref name=gwps /> with [[Template:DocBase]] (which will be expanded by creation). Template:DocBase creates the following paragraphs:
*'''Introduction:'''
*'''Introduction:'''
**Shall contain a short introduction
**Shall contain a short introduction.
** This paragraph is developed by the {{rml}} community
** This paragraph is developed by the {{rml}} community.
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}''
**''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.''
*Documentation:
*'''Documentation:'''
**Container for subchapters ''Syntax'', ''Semantics'' and (possibly) ''Semantic Constraints''
**Container for subchapters ''Syntax'', ''Semantics'' and (possibly) ''Semantic Constraints''.
**This paragraph should not be edited manually, except within the subparagraphs ''Semantics'' and ''Semantic Constraints''
**This paragraph should not be edited manually, except within the subparagraphs ''Semantics'' and ''Semantic Constraints''.
*Syntax:
*'''Syntax:'''
**Here the robot pages are being framed
**Here the robot pages are being framed.
**Never edit manually!
**Do not edit manually!
*Semantics:
**''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.''
** Shall contain the semantics of and attributes
*'''Semantics:'''
** This paragraph is developed by the {{rml}} community
** Shall contain the semantics of and attributes.
** This paragraph is developed by the {{rml}} community.
** Should only state the intention of the element respectively attribute.
** Should only state the intention of the element respectively attribute.
**No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they explain the intention
**No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they explain the intention.
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}''
**''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.''
*Best Practice / Examples:
*'''Best Practice / Examples:'''
**Shall contain best practice; national rules and peculiarities; Code examples
**Shall contain best practice; national rules and peculiarities; Code examples.
** This paragraph is developed by the {{rml}} community
** This paragraph is developed by the {{rml}} community.
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}''
**''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.''
*Additional Information:
*'''Additional Information:'''
**Container for subchapters ''Notes'' and ''Open Issues''
**Container for subchapters ''Notes'' and ''Open Issues''.
**This paragraph should not be edited manually, except within the subparagraphs ''Notes'' and ''Open Issues''
**This paragraph should not be edited manually, except within the subparagraphs ''Notes'' and ''Open Issues''.
*Notes:
*'''Notes:'''
**Shall contain Anything that does not fit into other paragraphs
**Shall contain Anything that does not fit into other paragraphs.
** This paragraph is developed by the {{rml}} community
** This paragraph is developed by the {{rml}} community.
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}''
**''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.''
*Open Issues:
*'''Open Issues:'''
**Shall contain open discussions and unsolved problems
**Shall contain open discussions and unsolved problems.
** This paragraph can be edited by the {{rml}} community
** This paragraph can be edited by the {{rml}} community.
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}''
**''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.''
===Paragraphs ''Robot Pages''===
===Paragraphs ''Robot Pages''===
Robot pages are created by GWPS<ref name=gwps /> with [[Template:Schemaexport]].
Robot pages are created by GWPS<ref name=gwps /> with [[Template:Schemaexport]].


''Generally speaking, an application must conform to the structure depicted here to get certified successfully.''
''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.''


<references />
<references />


{{interwiki}}
{{interwiki}}

Revision as of 14:51, 7 April 2020

Structuring Guidelines for Element Pages
 

Focus

This page explains, how to structure an element documentation page within this wiki. A General outline for contibuting to this wiki can be found here. If you want to start contributing to this wiki, please begin with this outline.

CurrentlyApril 2020 not all parts of the railML® 2 wiki contain all descriptions in the correct section. Please be indulgent and support us in maintaining the Wiki.
Derzeit enthalten nicht alle Teile des railML® 2 Wikis alle Beschreibungen im richtigen Abschnitt. Bitte seien Sie nachsichtig und unterstützen Sie uns bei der Pflege des Wikis.

Purpose

Element pages in the railML® wikis are being created with templates: Template:DocBase and Template:Schemaexport in the railML® 3 wiki and Template:ElementDocu in the railML® 2 wiki. Employing this template grants for a standardized design. The template specifies the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs according to the rules set below. This clearcut structure serves two aims:

  • It helps users to find relevant information
  • This structure sets a frame for the certification

Paragraphs (railML® 2 Wiki)

In the railML® 2 wiki, Template:ElementDocu creates the following paragraphs:
(But some of them only, if used)

  • Position of XYZ in the XML-Tree:
    • Shall contain the position of the element in the XML tree.
    • Generated manually by the coordinator straightforward from the schema; no manual additions.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Multiplicity:
    • Shall contain the element multiplicity.
    • Generated manually by the coordinator straightforward from the schema.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Semantics:
    • Shall contain the element semantics.
    • This paragraph is developed by the railML® community.
    • Should only state the intention of the element.
    • No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they explain the intention.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Attributes:
    • Shall contain the element semantics.
    • This paragraph is developed by the railML® community.
    • Do not place rules or explanations here. Concise remarks like “not to be confused with” are allowed, if they explain the intention.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Syntactic constraints:
    • Shall contain syntactic constraints set within the schema.
    • Generated manually by the coordinator straightforward from the schema.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Semantic constraints:
    • Shall contain semantic constraints.
    • Semantic constraints should be added only by the subschema coordinator or in reconcilement with him.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Best Practice Examples:
    • Shall contain best practices; national rules and peculiarities as well as code examples.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.
  • Open Issues:
    • Shall contain open discussions and unsolved problems. Not to be used as discussion bored (use [1] instead; links to the forum discussion are welcome) nor as ticket system (use [2] instead; links to the trac tickets are welcome).
    • This paragraph can be edited by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.
  • Notes:
    • Shall contain anything that does not fit into other paragraphs.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.

Structure railML® 3 Wiki

In the railML® 3 wiki, element pages are created via GWPS[1]. GWPS will for each element create a hand page that is supposed for content created by the wiki authors (best practice, notes etc) and a robot page that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page.

Paragraphs Hand Pages

Hand pages are created by GWPS[1] with Template:DocBase (which will be expanded by creation). Template:DocBase creates the following paragraphs:

  • Introduction:
    • Shall contain a short introduction.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
  • Documentation:
    • Container for subchapters Syntax, Semantics and (possibly) Semantic Constraints.
    • This paragraph should not be edited manually, except within the subparagraphs Semantics and Semantic Constraints.
  • Syntax:
    • Here the robot pages are being framed.
    • Do not edit manually!
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
  • Semantics:
    • Shall contain the semantics of and attributes.
    • This paragraph is developed by the railML® community.
    • Should only state the intention of the element respectively attribute.
    • No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they explain the intention.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
  • Best Practice / Examples:
    • Shall contain best practice; national rules and peculiarities; Code examples.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
  • Additional Information:
    • Container for subchapters Notes and Open Issues.
    • This paragraph should not be edited manually, except within the subparagraphs Notes and Open Issues.
  • Notes:
    • Shall contain Anything that does not fit into other paragraphs.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
  • Open Issues:
    • Shall contain open discussions and unsolved problems.
    • This paragraph can be edited by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.

Paragraphs Robot Pages

Robot pages are created by GWPS[1] with Template:Schemaexport.

Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.

  1. 1.0 1.1 1.2 GWPS = Gruschwitz' Wonderful Python Script