Message ID | 20240417070703.3883433-1-michael.opdenacker@bootlin.com |
---|---|
State | New |
Headers | show |
Series | manuals: standards.md5: add standard for project names | expand |
Hi Michael, On 4/17/24 09:07, 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 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 :) > 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 :) > 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 > > diff --git a/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch b/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch > new file mode 100644 > index 0000000000..8b9e36dda6 > --- /dev/null > +++ b/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch > @@ -0,0 +1,70 @@ > +From 10924847c19a69a8f7fd2acd97f84987cdfea2c8 Mon Sep 17 00:00:00 2001 > +From: Michael Opdenacker <michael.opdenacker@bootlin.com> > +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 <michael.opdenacker@bootlin.com> > +CC: Quentin Schulz <quentin.schulz@theobroma-systems.com> > +--- > + 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 > + > diff --git a/documentation/standards.md b/documentation/standards.md > index e0c0cba83c..3fc5796301 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. > +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. > 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, Reviewed-by: Quentin Schulz <quentin.schulz@theobroma-systems.com> Thanks, Quentin
Hi Quentin, Thanks for the review! On 4/17/24 at 10:48, Quentin Schulz wrote: > Don't forget the v3 in patch title :) > >> 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! >> +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.
diff --git a/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch b/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch new file mode 100644 index 0000000000..8b9e36dda6 --- /dev/null +++ b/documentation/0001-manuals-standards.md5-add-standard-for-project-names.patch @@ -0,0 +1,70 @@ +From 10924847c19a69a8f7fd2acd97f84987cdfea2c8 Mon Sep 17 00:00:00 2001 +From: Michael Opdenacker <michael.opdenacker@bootlin.com> +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 <michael.opdenacker@bootlin.com> +CC: Quentin Schulz <quentin.schulz@theobroma-systems.com> +--- + 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 + diff --git a/documentation/standards.md b/documentation/standards.md index e0c0cba83c..3fc5796301 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. +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