Skip to contentSkip to conversation

manuals: standards.md5: add standard for project names

RFC PATCH Superseded [email protected] 2 participants 5 messages Apr 15, 2024

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

RFC 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.

---
 documentation/standards.md | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)
documentation/standards.md +16 -15
index e0c0cba83c..05c5afffe8 100644
@@ -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
 
Signature · 1 line
2.34.1
#1 lore raw

Hi Michael,

Quoted 52 lines · On 4/15/24 12:05, [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.

---
  documentation/standards.md | 31 ++++++++++++++++---------------
  1 file changed, 16 insertions(+), 15 deletions(-)
documentation/standards.md +11 -12
index e0c0cba83c..05c5afffe8 100644
@@ -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:

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

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.
 

Looks good to me but I'm wondering if we shouldn't have an exception for BitBake and Yocto Project? Those will be extensively used across the documentation and I think there shouldn't be too much confusing about the word (as opposed to some other programs which mean something in English for example, e.g. perf).

The idea behind this is that we'd then have an exception for those words in Vale and that would help us catch typos and have some kind of consistency across the documentation, without having to check manually.

Cheers,
Quentin

#2 lore raw

Hi Quentin,

Thanks for the quick feedback!

Quoted 65 lines · Quentin Schulz

Hi Michael,

Quoted 56 lines · On 4/15/24 12:05, [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.

---
  documentation/standards.md | 31 ++++++++++++++++---------------

  1 file changed, 16 insertions(+), 15 deletions(-)
documentation/standards.md +0 -0
index e0c0cba83c..05c5afffe8 100644
@@ -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

documentation/standards.md +3 -1
-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

documentation/standards.md +1 -1
-* OpenEmbedded
+### Project names

  -There are exceptions in which such names can be used

documentation/standards.md +1 -1
-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

documentation/standards.md +1 -3
-* 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.

documentation/standards.md +4 -2
-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 
Quoted 3 lines

cross-reference
+to a section. In that case, capitalization and quotes are ignored by Sphinx.

Looks good to me but I'm wondering if we shouldn't have an exception for BitBake and Yocto Project? Those will be extensively used across the documentation and I think there shouldn't be too much confusing about the word (as opposed to some other programs which mean something in English for example, e.g. perf).

Quoted 1 line

The idea behind this is that we'd then have an exception for those words in Vale and that would help us catch typos and have some kind of consistency across the documentation, without having to check manually.

Right, perf and ftrace are typical sources of confusion. I agree with what you suggest for very usually names like BitBake, Yocto Project, OpenEmbedded. This could also include frequent project names like Linux.

Hey, a more relaxed rule could be to only use single quotes for uncapitalized project names, once again such as perf and ftrace. These are the ones that can be harder to distinguish from English words. On the other hand, having all project names  (like Docker or Toaster, with the accepted exceptions) styled this way, would make the distinction clearer to readers.

What do you think?
Cheers
Michael.

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

Hi Michael,

Quoted 70 lines · Michael Opdenacker

Hi Quentin,

Thanks for the quick feedback!

Quoted 65 lines · Quentin Schulz

Hi Michael,

Quoted 56 lines · On 4/15/24 12:05, [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.

---
  documentation/standards.md | 31 ++++++++++++++++---------------

  1 file changed, 16 insertions(+), 15 deletions(-)
documentation/standards.md +0 -0
index e0c0cba83c..05c5afffe8 100644
@@ -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

documentation/standards.md +3 -1
-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

documentation/standards.md +1 -1
-* OpenEmbedded
+### Project names

  -There are exceptions in which such names can be used

documentation/standards.md +1 -1
-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

documentation/standards.md +1 -3
-* 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.

documentation/standards.md +4 -2
-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 
Quoted 3 lines

cross-reference
+to a section. In that case, capitalization and quotes are ignored by Sphinx.

Looks good to me but I'm wondering if we shouldn't have an exception for BitBake and Yocto Project? Those will be extensively used across the documentation and I think there shouldn't be too much confusing about the word (as opposed to some other programs which mean something in English for example, e.g. perf).

Quoted 6 lines
Quoted 1 line

The idea behind this is that we'd then have an exception for those words in Vale and that would help us catch typos and have some kind of consistency across the documentation, without having to check manually.

Right, perf and ftrace are typical sources of confusion. I agree with what you suggest for very usually names like BitBake, Yocto Project, OpenEmbedded. This could also include frequent project names like Linux.

Hey, a more relaxed rule could be to only use single quotes for uncapitalized project names, once again such as perf and ftrace.

The issue would be the same if a capital letter for the word is expected in a sentence. e.g. if a sentence starts with perf all lowercase, I'm assuming it is the name of some piece of SW. But if the sentence starts with Docker, is it the name of a piece of SW or an actual word?

Quoted 2 lines

These are the ones that can be harder to distinguish from English words. On the other hand, having all project names  (like Docker or Toaster, with the accepted exceptions) styled this way, would make the distinction clearer to readers.

Mmmmm Toaster is a good example of something related to YP that is also an English word... I guess all project names highlighted would make sense then. We can always try to have some elaborate sed/grep command to find Bitbake/bitbake/bitBake instead of BitBake for example instead of relying on Vale for it.

Cheers,
Quentin

#4 lore raw

Hello Quentin

Quoted 6 lines · Quentin Schulz

The issue would be the same if a capital letter for the word is expected in a sentence. e.g. if a sentence starts with perf all lowercase, I'm assuming it is the name of some piece of SW. But if the sentence starts with Docker, is it the name of a piece of SW or an actual word?

Quoted 2 lines

These are the ones that can be harder to distinguish from English words. On the other hand, having all project names  (like Docker or Toaster, with the accepted exceptions) styled this way, would make the distinction clearer to readers.

Mmmmm Toaster is a good example of something related to YP that is also an English word... I guess all project names highlighted would make sense then. We can always try to have some elaborate sed/grep command to find Bitbake/bitbake/bitBake instead of BitBake for example instead of relying on Vale for it.

Right, good catch. Then let's keep highlighting all project names, unless somebody else can convince us otherwise.

Cheers
Michael.

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