From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>,
Quentin Schulz <quentin.schulz@theobroma-systems.com>
Subject: [PATCH v4] manuals: standards.md5: add standard for project names
Date: Fri, 19 Apr 2024 09:55:26 +0200 [thread overview]
Message-ID: <20240419075526.4135600-1-michael.opdenacker@bootlin.com> (raw)
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
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.
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
Changes in V4
- Remove the exception for references to section titles (rare case)
- Remove the exception for single quotes in section titles
(not needed are single quotes are properly processed in this case)
Changes in V3
- Mention that project names don't need single quotes
when they are part of a hyperlink.
Changes in V2
- Specify that uncapitalized project names should remain so
even at the beginning of a sentence. This follows what Wikipedia
seems to be doing, e.g. on https://en.wikipedia.org/wiki/Perf_(Linux)
---
documentation/standards.md | 33 ++++++++++++++++++---------------
1 file 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
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
--
2.34.1
next reply other threads:[~2024-04-19 7:55 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-19 7:55 michael.opdenacker [this message]
2024-04-22 8:37 ` [PATCH v4] manuals: standards.md5: add standard for project names Quentin Schulz
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240419075526.4135600-1-michael.opdenacker@bootlin.com \
--to=michael.opdenacker@bootlin.com \
--cc=docs@lists.yoctoproject.org \
--cc=quentin.schulz@theobroma-systems.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).