Dev:Wiki Structuring Guidelines: Difference between revisions
Jump to navigation
Jump to search
| [checked revision] | [checked revision] |
(New page) |
|||
| Line 10: | Line 10: | ||
*It helps users to find relevant information | *It helps users to find relevant information | ||
*This structure sets a frame for the [[dev:Certification|certification]] | *This structure sets a frame for the [[dev:Certification|certification]] | ||
==Paragraphs== | ==Paragraphs ({{rml|2}} Wiki== | ||
[[Template:ElementDocu]] creates the following paragraphs: | In the {{rml|2}} wiki, [[Template:ElementDocu]] creates the following paragraphs:<br>(But some of them only, if used) | ||
*'''Position of ''XYZ'' in the XML-Tree: | *'''Position of ''XYZ'' in the XML-Tree: | ||
**Shall contain the position of the element 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 | ||
** | ** ''Generally speaking, an application must conform to this structure to get certified successfully.'' | ||
*'''Multiplicity:''' | |||
*'''Multiplicity:''' straightforward from the schema | **Shall contain the element [[dev:Multiplicity|multiplicity]] | ||
*'''Semantics:''' | ** Generated manually by the coordinator straightforward from the schema | ||
*'''Attributes:''' | ** ''Generally speaking, an application must conform to this structure to get certified successfully.'' | ||
*'''Syntactic constraints:''' straightforward from the schema | *'''Semantics:''' | ||
*'''[[dev:Semantic Constraints|Semantic constraints]]:''' | ** Shall contain the element semantics | ||
*'''Best Practice Examples:''' | ** This paragraph is developed by the {{rml}} community | ||
*'''Open Issues:''' open discussions and unsolved problems | ** Should only state the intention of the element. | ||
*'''Notes | **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}}'' | |||
*'''Attributes:''' | |||
** Shall contain the element semantics | |||
** This paragraph is developed by the {{rml}} community | |||
**Do not place rules or explanations 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}}'' | |||
*'''Syntactic constraints:''' | |||
** Shall contain syntactic constraints set within the schema | |||
** Generated manually by the coordinator straightforward from the schema | |||
** ''Generally speaking, an application must conform to this structure to get certified successfully.'' | |||
*'''[[dev:Semantic Constraints|Semantic constraints]]:''' | |||
** Shall contain [[dev:Semcon|semantic constraints]] | |||
** Semantic constraints should be added only by the subschema coordinator or in reconcilement with him | |||
** ''Generally speaking, an application must conform to this structure to get certified successfully.'' | |||
*'''Best Practice Examples:''' | |||
**Shall contain best practice; national rules and peculiarities; Code examples | |||
** 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}}'' | |||
*'''Open Issues:''' | |||
**Shall contain open discussions and unsolved problems | |||
** 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}}'' | |||
*'''Notes:''' | |||
**Shall contain Anything that does not fit into other paragraphs | |||
** 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}}'' | |||
==Structure ({{rml|3}} Wiki== | |||
In the {{rml|3}} wiki, The pages are created via GWPS<ref name=gwps>GWPS = Gruschwitz' Wonderful Phython Script</ref>. GWPS will for each element create a ''hand page'' where that are supposed for content created by the wiki authors (best practice, notes etc) and a ''robot page'' that contains information directly retreaved 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<ref name=gwps /> 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 {{rml}} community | |||
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}'' | |||
*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 | |||
**Never edit manually! | |||
*Semantics: | |||
** 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. | |||
**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}}'' | |||
*Best Practice / Examples: | |||
**Shall contain best practice; national rules and peculiarities; Code examples | |||
** 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}}'' | |||
*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 {{rml}} community | |||
** ''Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand {{rml}}'' | |||
*Open Issues: | |||
**Shall contain open discussions and unsolved problems | |||
** 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}}'' | |||
===Paragraphs ''Robot Pages''=== | |||
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.'' | |||
<references /> | |||
Revision as of 11:27, 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
Purpose
Element pages in this wiki are being created with Template:ElementDocu. 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
- Generally speaking, an application must conform to this structure to get certified successfully.
- Multiplicity:
- Shall contain the element multiplicity
- Generated manually by the coordinator straightforward from the schema
- Generally speaking, an application must conform to this structure to get certified successfully.
- 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
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- 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
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- Syntactic constraints:
- Shall contain syntactic constraints set within the schema
- Generated manually by the coordinator straightforward from the schema
- Generally speaking, an application must conform to this structure to get certified successfully.
- Semantic constraints:
- Shall contain semantic constraints
- Semantic constraints should be added only by the subschema coordinator or in reconcilement with him
- Generally speaking, an application must conform to this structure to get certified successfully.
- Best Practice Examples:
- Shall contain best practice; national rules and peculiarities; Code examples
- This paragraph is developed by the railML® community
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- Open Issues:
- Shall contain open discussions and unsolved problems
- This paragraph can be edited by the railML® community
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- Notes:
- Shall contain Anything that does not fit into other paragraphs
- This paragraph is developed by the railML® community
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
Structure (railML® 3 Wiki
In the railML® 3 wiki, The pages are created via GWPS[1]. GWPS will for each element create a hand page where that are supposed for content created by the wiki authors (best practice, notes etc) and a robot page that contains information directly retreaved 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
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand 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
- Never edit manually!
- 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
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- Best Practice / Examples:
- Shall contain best practice; national rules and peculiarities; Code examples
- This paragraph is developed by the railML® community
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand 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
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
- Open Issues:
- Shall contain open discussions and unsolved problems
- This paragraph can be edited by the railML® community
- Generally speaking, this information is irrelevant for certification. It is intended to help the user to understand railML®
Paragraphs Robot Pages
Robot pages are created by GWPS[1] with Template:Schemaexport.
Generally speaking, an application must conform to the structure depicted here to get certified successfully.