summaryrefslogtreecommitdiffstats
path: root/documentation/standards.md
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/standards.md')
-rw-r--r--documentation/standards.md48
1 files changed, 33 insertions, 15 deletions
diff --git a/documentation/standards.md b/documentation/standards.md
index 9f4771ebd9..bc403e393e 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -5,6 +5,21 @@ documentation is created.
It is currently a work in progress.
+## Automatic style validation
+
+There is an ongoing effort to automate style validation
+through the [Vale](https://vale.sh/). To try it, run:
+
+ $ make stylecheck
+
+Note that this just applies to text. Therefore, the syntax
+conventions described below still apply.
+
+If you wish to add a new word to an "accept.txt" file
+(./styles/config/vocabularies/<Vocab>/accept.txt),
+make sure the spelling and capitalization matches
+what Wikipedia or the project defining this word uses.
+
## Text standards
### Bulleted lists
@@ -55,27 +70,30 @@ cannot be split without infringing syntactic rules
or reducing readability, as well as for command output
which should be kept unmodified.
-### Project names
+### File, tool and command names
-Project names should be capitalized in the same
-way they are on Wikipedia, in particular:
+File, tool, command and package names should be double tick-quoted.
+For example, ``` ``conf/local.conf`` ``` is preferred over
+`"conf/local.conf"`.
-* BitBake
-* OpenEmbedded
+### Project names
-There are exceptions in which such names can be used
-in lower case:
+Project names should be introduced with single quotes, to have them rendered
+with an italic font and make them easier to distinguish from command names
+(double tick-quoted) and from regular English words.
-* When referring to a package name
-* When referring to the corresponding command name
-* When used in a cross-reference title. Such
- titles are usually in lower case.
+An exception is when project names appear in hyperlinks, as nested markup
+is not supported by Sphinx yet.
-### File, tool and command names
+Project names should also be capitalized (or not) in the same way they are on
+Wikipedia, or on their own project pages if they are not described on
+Wikipedia. If a project name isn't capitalized, it should remain so even
+at the beginning of a sentence.
-File, tool and command names should be double tick-quoted.
-For example, ``` ``conf/local.conf`` ``` is preferred over
-`"conf/local.conf"`.
+For example:
+
+* ``` `BitBake` ```
+* ``` `ftrace` ```
### Variables