Skip to contentSkip to conversation

manuals: standards.md5: add standard for project names

PATCH In review [email protected] 2 participants 3 messages Apr 17, 2024 – Apr 19, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 manuals: standards.md5: add standard for project names

From: Michael Opdenacker <[email protected]>

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.

---

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)

---
 ...s.md5-add-standard-for-project-names.patch | 70 +++++++++++++++++++
 documentation/standards.md                    | 33 +++++----
 2 files changed, 88 insertions(+), 15 deletions(-)
 create mode 100644 documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch
documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch new file +70 -0
new file mode 100644
index 0000000000..8b9e36dda6
@@ -0,0 +1,70 @@
+From 10924847c19a69a8f7fd2acd97f84987cdfea2c8 Mon Sep 17 00:00:00 2001
+From: Michael Opdenacker <[email protected]>
+Date: Mon, 15 Apr 2024 11:58:54 +0200
+Subject: [RFC][PATCH] 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.
+
+Signed-off-by: Michael Opdenacker <[email protected]>
+CC: Quentin Schulz <[email protected]>
+---
+ documentation/standards.md | 31 ++++++++++++++++---------------
+ 1 file changed, 16 insertions(+), 15 deletions(-)
+
+diff --git a/documentation/standards.md b/documentation/standards.md
+index e0c0cba83c..05c5afffe8 100644
+--- a/documentation/standards.md
++++ b/documentation/standards.md
+@@ -70,27 +70,28 @@ 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.
++They should also be capitalized in the same way they are on Wikipedia, or on
++their own project pages if they are not described on Wikipedia.
+ 
+-### File, tool and command names
++For example:
+ 
+-File, tool and command names should be double tick-quoted.
+-For example, ``` ``conf/local.conf`` ``` is preferred over
+-`"conf/local.conf"`.
++* ``` `BitBake` ```
++* ``` `ftrace` ```
++
++An exception is when such names are used in a section title, or in a cross-reference
++to a section. In that case, capitalization and quotes are ignored by Sphinx.
+ 
+ ### Variables
+ 
+-- 
+2.34.1
+
documentation/standards.md +18 -15
index e0c0cba83c..3fc5796301 100644
@@ -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.
+They 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
+For example:
 
-File, tool and command names should be double tick-quoted.
-For example, ``` ``conf/local.conf`` ``` is preferred over
-`"conf/local.conf"`.
+* ``` `BitBake` ```
+* ``` `ftrace` ```
+
+An exception is when such names are used in a section title, or in a cross-reference
+to a section. In that case, capitalization and quotes are ignored by Sphinx.
 
 ### Variables
 
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#1 lore raw

Hi Michael,

Quoted 10 lines · On 4/17/24 09:07, [email protected] wrote:

From: Michael Opdenacker <[email protected]>

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.

Quoted 9 lines

---

Changes in V3
- Mention that project names don't need single quotes when they are part of a hyperlink.

Don't forget the v3 in patch title :)

Quoted 6 lines

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)

---
  ...s.md5-add-standard-for-project-names.patch | 70 +++++++++++++++++++

[insert "yo dawg" meme with "Yo dawg I herd you like patches so I put a patch in your patch"]

I don't think we need this file :)

Quoted 118 lines
  documentation/standards.md                    | 33 +++++----
  2 files changed, 88 insertions(+), 15 deletions(-)

create mode 100644 documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch

documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch new file +70 -0
new file mode 100644
index 0000000000..8b9e36dda6
@@ -0,0 +1,70 @@
+From 10924847c19a69a8f7fd2acd97f84987cdfea2c8 Mon Sep 17 00:00:00 2001
+From: Michael Opdenacker <[email protected]>
+Date: Mon, 15 Apr 2024 11:58:54 +0200
+Subject: [RFC][PATCH] 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.
+
+Signed-off-by: Michael Opdenacker <[email protected]>
+CC: Quentin Schulz <[email protected]>
+---
+ documentation/standards.md | 31 ++++++++++++++++---------------
+ 1 file changed, 16 insertions(+), 15 deletions(-)
+
+diff --git a/documentation/standards.md b/documentation/standards.md
+index e0c0cba83c..05c5afffe8 100644
+--- a/documentation/standards.md
++++ b/documentation/standards.md
+@@ -70,27 +70,28 @@ 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.
++They should also be capitalized in the same way they are on Wikipedia, or on
++their own project pages if they are not described on Wikipedia.
+
+-### File, tool and command names
++For example:
+
+-File, tool and command names should be double tick-quoted.
+-For example, ``` ``conf/local.conf`` ``` is preferred over
+-`"conf/local.conf"`.
++* ``` `BitBake` ```
++* ``` `ftrace` ```
++
++An exception is when such names are used in a section title, or in a cross-reference
++to a section. In that case, capitalization and quotes are ignored by Sphinx.
+
+ ### Variables
+
+--
+2.34.1
+
documentation/standards.md +13 -12
index e0c0cba83c..3fc5796301 100644
@@ -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.
+They 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
+For example:

documentation/standards.md cannot be split without infringing syntactic rules · line 97

Quoted 10 lines
documentation/standards.md +5 -3
 
-File, tool and command names should be double tick-quoted.
-For example, ``` ``conf/local.conf`` ``` is preferred over
-`"conf/local.conf"`.
+* ``` `BitBake` ```
+* ``` `ftrace` ```
+
+An exception is when such names are used in a section title, or in a cross-reference
+to a section. In that case, capitalization and quotes are ignored by Sphinx.
 

Can you provide code examples, this isn't that obvious to me and I have done a bit of Sphinx doc writing, so not sure total beginners would know what this rule applies to?

Otherwise,

Thanks,
Quentin

#2 lore raw

Hi Quentin,

Thanks for the review!

Quoted 10 lines · Quentin Schulz

Don't forget the v3 in patch title :)

Quoted 6 lines

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)
---
  ...s.md5-add-standard-for-project-names.patch | 70 +++++++++++++++++++

[insert "yo dawg" meme with "Yo dawg I herd you like patches so I put a patch in your patch"]

Oops twice. Never send a patch when you are in a hurry!

Quoted 6 lines
Quoted 4 lines

+An exception is when such names are used in a section title, or in a cross-reference
+to a section. In that case, capitalization and quotes are ignored by Sphinx.

Can you provide code examples, this isn't that obvious to me and I have done a bit of Sphinx doc writing, so not sure total beginners would know what this rule applies to?

Correct, referring to a section title in a specific document is a very special case. Let's drop it.

I also tried to use something like this:

Building a Meson Package
--------------------------

And it turns out to be formatted in italic in the title too. So, let's not make an exception here :) Cheers
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com