• R/O
  • SSH

YSLib-wiki: Commit

The wiki source of YSLib documentation.


Commit MetaInfo

Revisión2a974847cd046cc2bf322d7c388c20327d0516d1 (tree)
Tiempo2022-08-12 20:22:26
AutorFrankHB <frankhb1989@gmai...>
CommiterFrankHB

Log Message

WikiRules.en-US.md: Added a notes for the language using and the annex for external incompatible rules.

Cambiar Resumen

Diferencia incremental

diff -r 2fe927166c45 -r 2a974847cd04 WikiRules.en-US.md
--- a/WikiRules.en-US.md Sun Apr 17 13:00:40 2022 +0800
+++ b/WikiRules.en-US.md Fri Aug 12 19:22:26 2022 +0800
@@ -59,6 +59,8 @@
5959 * `zh-CN`
6060 * `zh`
6161
62+**NOTE** The form of these literals conforms to the recommendation of [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag), specifically, the "language" and "region" syntax elements in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646.html).
63+
6264 If no one edition in above languages is complete, the documentation is defective.
6365
6466 A language tag may be used to annotate one or more words in text. An annotation of such use is a *language tag annotation*, which consists of a tag combined with one pair of enclosing parentheses (namely, `(` and `)`).
@@ -84,7 +86,11 @@
8486 7. All lowercase style shall be used for words in the embedded translations or detailed descriptions in parentheses in other cases.
8587 8. Sentence case should be used otherwise.
8688
87-English wording documentation is intended to be conforming to [the ISO/IEC directive, part 3](http://std.dkuug.dk/jtc1/sc22/wg9/isodir3.pdf). Note the use of modal verbs is distinct with [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt). For RFC documents, RFC 2119 is preferred, but not necessary with the case clarification (i.e. [RFC 8174](https://tools.ietf.org/html/rfc8174)) for documents published earlier than RFC 8174 due to compatibility issues.
89+English wording documentation is intended to be conforming to [the ISO/IEC directive, part 3](http://std.dkuug.dk/jtc1/sc22/wg9/isodir3.pdf).
90+
91+**NOTE** The use of modal verbs is distinct with [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
92+
93+For wording referenced from RFC documents, RFC 2119 is preferred, but not necessary with the case clarification (i.e. [RFC 8174](https://tools.ietf.org/html/rfc8174)) for documents published earlier than RFC 8174 due to compatibility issues.
8894
8995 The following grammartical forms of English (with `en` or `en-US` tags) are considered idiomatic and application of such forms may be preferred:
9096
@@ -138,7 +144,9 @@
138144
139145 ### Dialects
140146
141-Unless explicitly specified elsewhere, only common dialects are to be used. Currently this should be [GFM](https://help.github.com/articles/github-flavored-markdown).
147+Unless explicitly specified elsewhere, only common dialects are to be used. Currently this should be [GFM (GitHub Flavored Markdown)](https://help.github.com/articles/github-flavored-markdown).
148+
149+**NOTE** This is not [GLFM (GitLab Flavored Markdown)](https://docs.gitlab.com/ee/user/markdown.html), which also abbreviated as GFM formerly.
142150
143151 And if the content may be presented on [Bitbucket](https://bitbucket.org) wiki, stricter rules applies, notably:
144152
@@ -169,3 +177,29 @@
169177
170178 * [Programming Language Documentations](https://github.com/FrankHB/pl-docs) by FrankHB
171179
180+# Annex (Informative)
181+
182+## Alternaive imcompatible rules
183+
184+Usually there the rules of documentation here are compatible to other rules in various specifications. However, some of the well-known rules are considered overspecified (albeit not rigouous) and with insufficient quality in specification. Thus, these rules are *deliberately* kept incompatible, and never accepted here:
185+
186+* The specification may be too vague by missing separating the comformance rules and the suggestions, so it is difficult to manually verify the conformance just by the specification text.
187+ * Some confusions may be from the lack of rules on the modal verbs.
188+ * Some rules may be underspecified for external resources. For example, the claim of "be a valid Markdown file" is unclear without further notes, because there is no unique standard to determine the definition of "valid", since there are multiple dialects of the Markdown language and no flavor is definitely more representative than others.
189+* The rules of mandated letter cases (in particular, capitalization) may be too restrictive.
190+ * This may be generally too subjective. It can be good to sticking to a well-name for to ease for use cases for technical merits (like for machine verication), but the fixed spelling on cases may be overspecified.
191+ * The exception is when the name is standardized and machine-oriented by default.
192+ * As a notable instance, [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646.html) recommends but does not mandate the capitalization for the codes from [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1), while the preferred capitalization diverges in the 2 standards.
193+ * On the other hand, mandotory like "README" instead of "Readme" is too restrictve. It will be problatic to be transferred between case-insensitive enviornments and case-sensitive environments (e.g. names in filesystems), where one environment may allow entries of `README` and `Readme` coexisting but another may not.
194+ * When techically feasible to having different cases coexisting, "README" and "Readme" are symmentric, i.e. no one is definitely more preferred than the other for machines. It is then not intuitive to reason why "README" must be preferred to "Readme" instead of the exact opposite in the specification, in particular with the fact that such entry is mainly created for human readers but not machines.
195+ * Instead, keeping one overridable as well as a recommended default form (which does not necessarily to be all capitalized) of spelling is better for both portability and other needs.
196+ * Further, names like "README.md" are less consistent to "README.MD". The latter is at least required in some ancient systems not support the small case, hence even more preferred for portability (in extreme cases).
197+* Prioritizing non-regional subtags for languages should not be recommended normally, because this is less accurate, and the confusion may even be offensive to specific culture, since there can be lack of consensus that one subtag can override another without changing the meaning of the text (which is not the case of the relationship between tags and subtags).
198+* Validation of hyperlinks should be acknowledged not always possible when the linked resource is out of the control (i.e. external) in a document.
199+ * Anyway, there is no persistency guarantee for most hyperlinks in the Web.
200+ * Mandating the state of the referenced resource of hyperlinks unconditionally will make any verification result one-time, because the exteranl links may be broken immediately after the verification. Then the conformance is non-deterministic.
201+ * Such mandatory is applicable only for hyperlinks provable to be persistent. But this is infeasible with automatic methods at least for external links on the Web, because the test of persistency may be unreliable until the link is broken.
202+ * So, unless external links are not allowed (which seems an overkill), rules having impractical assumptions of the validation process should be in the specification.
203+
204+An example of most bullets above can be found in the [specification](https://github.com/RichardLitt/standard-readme/blob/master/spec.md) of [standard-readme](https://github.com/RichardLitt/standard-readme).
205+
Show on old repository browser