manuals: standards.md5: add standard for project names
PATCH v4 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 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(-)
documentation/standards.md +18 -15
@@ -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
Signature · 1 line
2.34.1
Hi Michael,
Quoted 46 lines · On 4/19/24 09:55, [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.
Signed-off-by Michael Opdenacker <[email protected]>CC Quentin Schulz <[email protected]>---
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(-)documentation/standards.md +2
-3@@ -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.
documentation/standards.md cannot be split without infringing syntactic rules · line 81
Quoted 10 lines
documentation/standards.md +4
-4+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
"single tick-quotes" I believe is what you wanted to say here?
documentation/standards.md cannot be split without infringing syntactic rules · line 87
Quoted 10 lines
documentation/standards.md +4
-4+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.
Not sure to fully understand what you mean by that?
Like... modifying a URL so that the project name is highlighted? Wouldn't that make it a different URL (even maybe a broken one)?
Can you provide an example here?
Because we do use tick quotes in sections for which the reflink then requires to use tick quotes, but escaped with a backslash.
Cheers,
Quentin