| Message ID | 20240419075526.4135600-1-michael.opdenacker@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v4] manuals: standards.md5: add standard for project names | expand |
Hi Michael, On 4/19/24 09:55, michael.opdenacker@bootlin.com wrote: > 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 "single tick-quotes" I believe is what you wanted to say here? > +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
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