-
Notifications
You must be signed in to change notification settings - Fork 19
WikiRules.en US
This document describs a set of rules for creating and maintaining documentations or some other kinds of materials, which is not project-specific. This document is also self-conforming to these rules.
Terms are emphasized at first appearence in italic.
Contents of materials are split as resources (e.g. files) in possibly nested namespaces (e.g. directories). A namespace is also considered as a resource for convenience.
A path is used to identifying or locating a resource, which can be in various forms (e.g. filesystem path or URL).
A path may have several components denoting different levels of namespace or the last level non-namespace resource.
An empty path is a path without any components.
A path with more than one components shall have syntactic separators (e.g. a slash(/) or whitespace) to split different components.
An identifier is a path with exactly one components without any separators, which can be used to differentiate resources in the same namespace or to collectively name some sets of resources in various namespaces.
A resource may be denoted with not necessarily the unique identifier or path. However, all resources this document discussed below are named.
English wording documentation is intended to be conforming to the ISO/IEC directive, part 3. Note the use of modal verbs is distinct with RFC 2119.
A set of documentation may be in one language. The IETF language tag with at least one subtag and additional prefix dot(.) shall be placed in the end of identifier of the resource before the dot and the extension name (if any). Otherwise the documentation shall be in multiple language, and no language code shall be in the identifier of the resource.
When the additional dot and tag is removed, all different resource with same names shall refer the same set of contents only in different languages, or at least one of them shall be incomplete which means to be complete as in former case. The resource is one edition in specific language of the documentation.
Unless explicitly specified, when the meaning is in conflict for multiple editions in different languages, the complete one shall be valid over others. If there are no only one complete edition, the validity is specified in following order:
- en-US
- en
- zh-CN
- zh
If no one edition in above languages is complete, the documentation has defects.
All text files should be encoded as UTF-8 with BOM enabled.
Newlines shall be consistent. Default use of newline is CR+LF.
Two subsequent newlines indicates an EOF logically. Subsequent newlines should only be used at EOF.
Except at the first of line, each word which consists of alphanumeric characters should be seperated by a single space character(U+0020) with other words.
No space characters should be at EOL.
To keep the semantics rules clear, use horizontal tab character(U+0009) instead of other spaces(i.e. U+0020) to indent, unless the text is verbatim quoted.
Names of markdown files should be with .md extension.
Unless explicitly specified elsewhere, only common dialects are to be used. Currently this should be GFM. And if the content may be presented on BitBucket wiki, more strict rules applies, notably there is currently no inline HTML support.
As text files, markdown files shall obey the same rules above. The indentation rule is necessary to avoid some compatibility issues, e.g. this.
This document may be referenced by other repositories.
Except for the following list, do not edit unless ultimately necessary.
Known refereced by:
- Programing Language Documentations by FrankHB