diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2024-04-15 11:58:54 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2024-04-24 14:22:55 +0100 |
commit | 05d54880e47b6e7c7a0bb3220e06e1a6588e3179 (patch) | |
tree | 1800fd6a1ded372b4e55642b504f8afc237587f8 | |
parent | 30d5b6f7ddfea99fdc97709978d0a3ecf00e0ee0 (diff) | |
download | poky-05d54880e47b6e7c7a0bb3220e06e1a6588e3179.tar.gz |
manuals: standards.md5: add standard for project names
Set a new standard to introduce project names with single quotes,
so that they appear in generated text with an italic font,
to make them easier to distinguish from command names and from
ordinary English words.
Rework and move the standard for command and file names
to make the whole description "flow" better.
(From yocto-docs rev: fa6700af56213a5079eaa8d9683f3c2b2fc93740)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Quentin Schulz <quentin.schulz@theobroma-systems.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/standards.md | 33 |
1 files changed, 18 insertions, 15 deletions
diff --git a/documentation/standards.md b/documentation/standards.md index e0c0cba83c..bc403e393e 100644 --- a/documentation/standards.md +++ b/documentation/standards.md | |||
@@ -70,27 +70,30 @@ cannot be split without infringing syntactic rules | |||
70 | or reducing readability, as well as for command output | 70 | or reducing readability, as well as for command output |
71 | which should be kept unmodified. | 71 | which should be kept unmodified. |
72 | 72 | ||
73 | ### Project names | 73 | ### File, tool and command names |
74 | 74 | ||
75 | Project names should be capitalized in the same | 75 | File, tool, command and package names should be double tick-quoted. |
76 | way they are on Wikipedia, in particular: | 76 | For example, ``` ``conf/local.conf`` ``` is preferred over |
77 | `"conf/local.conf"`. | ||
77 | 78 | ||
78 | * BitBake | 79 | ### Project names |
79 | * OpenEmbedded | ||
80 | 80 | ||
81 | There are exceptions in which such names can be used | 81 | Project names should be introduced with single quotes, to have them rendered |
82 | in lower case: | 82 | with an italic font and make them easier to distinguish from command names |
83 | (double tick-quoted) and from regular English words. | ||
83 | 84 | ||
84 | * When referring to a package name | 85 | An exception is when project names appear in hyperlinks, as nested markup |
85 | * When referring to the corresponding command name | 86 | is not supported by Sphinx yet. |
86 | * When used in a cross-reference title. Such | ||
87 | titles are usually in lower case. | ||
88 | 87 | ||
89 | ### File, tool and command names | 88 | Project names should also be capitalized (or not) in the same way they are on |
89 | Wikipedia, or on their own project pages if they are not described on | ||
90 | Wikipedia. If a project name isn't capitalized, it should remain so even | ||
91 | at the beginning of a sentence. | ||
90 | 92 | ||
91 | File, tool and command names should be double tick-quoted. | 93 | For example: |
92 | For example, ``` ``conf/local.conf`` ``` is preferred over | 94 | |
93 | `"conf/local.conf"`. | 95 | * ``` `BitBake` ``` |
96 | * ``` `ftrace` ``` | ||
94 | 97 | ||
95 | ### Variables | 98 | ### Variables |
96 | 99 | ||