bitbake-user-manual: punctuation fixes
PATCH 1/1 bitbake-user-manual: punctuation fixes
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
See https://www.grammarly.com/blog/hyphens-and-dashes/
- No uppercase after em dashes
- No uppercase after colons if what follows is not a complete sentence.
- Fix spacing before colons ":"
- Replace em-dashes with colons for consistency in a section
--- doc/README | 2 +- .../bitbake-user-manual-execution.rst | 4 +- .../bitbake-user-manual-metadata.rst | 4 +- .../bitbake-user-manual-ref-variables.rst | 64 +++++++++---------- 4 files changed, 37 insertions(+), 37 deletions(-)
doc/README +1 -1
@@ -8,7 +8,7 @@ Manual Organization Folders exist for individual manuals as follows: -* bitbake-user-manual - The BitBake User Manual +* bitbake-user-manual --- The BitBake User Manual Each folder is self-contained regarding content and figures.
doc/bitbake-user-manual/bitbake-user-manual-execution.rst +2 -2
@@ -523,7 +523,7 @@ it cannot figure out dependencies. Thus far, this section has limited discussion to the direct inputs into a task. Information based on direct inputs is referred to as the "basehash" in the code. However, there is still the question of a task's -indirect inputs - the things that were already built and present in the +indirect inputs --- the things that were already built and present in the build directory. The checksum (or signature) for a particular task needs to add the hashes of all the tasks on which the particular task depends. Choosing which dependencies to add is a policy decision. However, the
@@ -534,7 +534,7 @@ At the code level, there are a variety of ways both the basehash and the dependent task hashes can be influenced. Within the BitBake configuration file, we can give BitBake some extra information to help it construct the basehash. The following statement effectively results -in a list of global variable dependency excludes - variables never +in a list of global variable dependency excludes --- variables never included in any checksum. This example uses variables from OpenEmbedded to help illustrate the concept::
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +2 -2
@@ -1658,8 +1658,8 @@ user interfaces: .. _variants-class-extension-mechanism: -Variants - Class Extension Mechanism -==================================== +Variants --- Class Extension Mechanism +====================================== BitBake supports multiple incarnations of a recipe file via the :term:`BBCLASSEXTEND` variable.
doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +32 -32
153 lines not on this page · raw message
Signature · 1 line
2.25.1
Hi Michael,
Quoted 3 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
I seem to recall we ultimately decided to not go for em dashes because it wouldn't be matched by a search in the browser or in the sources?
Cheers,
Quentin
Hi Quentin,
Thanks for the review!
Quoted 9 lines · Quentin Schulz
Hi Michael,
Quoted 3 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
I seem to recall we ultimately decided to not go for em dashes because it wouldn't be matched by a search in the browser or in the sources?
Ouch, this is frustrating. I'd rather not deviate from English writing rules, so that we don't have to keep a list of exceptions to them, or worse keep them in the back of our heads.
And why would one need to look for an em dash in the browser or in the sources? As a reader, I'd avoid special characters in my searches, and as a developer, I would do the same, but if I really want to look for a specific em dash, I'll quickly find what the corresponding characters are in the sources, thanks to the surrounding context.
Would it be possible to vote again on this?
Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hi Michael,
Quoted 15 lines · Michael Opdenacker
Hi Quentin,
Thanks for the review!
Quoted 9 lines · Quentin Schulz
Hi Michael,
Quoted 3 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
I seem to recall we ultimately decided to not go for em dashes because it wouldn't be matched by a search in the browser or in the sources?
c.f. https://lists.yoctoproject.org/g/docs/topic/85211078#1731
for the original discussion around em dashes. Didn't decide anything at that time though but you have all the arguments there.
Quoted 11 lines
Ouch, this is frustrating. I'd rather not deviate from English writing rules, so that we don't have to keep a list of exceptions to them, or worse keep them in the back of our heads.
And why would one need to look for an em dash in the browser or in the sources? As a reader, I'd avoid special characters in my searches, and as a developer, I would do the same, but if I really want to look for a specific em dash, I'll quickly find what the corresponding characters are in the sources, thanks to the surrounding context.
You just gave the example as to why I think we shouldn't use em dashes: to "avoid special characters in my searches".
No more arguments since the discussion Robert started last August, so... up to you.
Cheers,
Quentin
Hi Quentin,
Quoted 36 lines · Quentin Schulz
Hi Michael,
Quoted 15 lines · Michael Opdenacker
Hi Quentin,
Thanks for the review!
Quoted 9 lines · Quentin Schulz
Hi Michael,
Quoted 3 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
I seem to recall we ultimately decided to not go for em dashes because it wouldn't be matched by a search in the browser or in the sources?
c.f. https://lists.yoctoproject.org/g/docs/topic/85211078#1731
for the original discussion around em dashes. Didn't decide anything at that time though but you have all the arguments there.
Quoted 11 lines
Ouch, this is frustrating. I'd rather not deviate from English writing rules, so that we don't have to keep a list of exceptions to them, or worse keep them in the back of our heads.
And why would one need to look for an em dash in the browser or in the sources? As a reader, I'd avoid special characters in my searches, and as a developer, I would do the same, but if I really want to look for a specific em dash, I'll quickly find what the corresponding characters are in the sources, thanks to the surrounding context.
Quoted 5 lines
You just gave the example as to why I think we shouldn't use em
dashes: to "avoid special characters in my searches".No more arguments since the discussion Robert started last August, so... up to you.
Thanks for the reminder about the original discussion. You have a better memory than I do ;-)
Could others (at least Richard, Nico ?) share their opinion here? Otherwise it's hard to find a majority opinion...
The question is whether we should use em dashes
(https://www.thepunctuationguide.com/em-dash.html), described as "---" in Restructed Text. This respects the English punctuation rules, but is harder to grep in the sources.
If we prefer to use hyphens instead of em dashes in the documentation, we will have to document the exception, but the risk remains to get questions from time to time.
My vote goes to using em dashes, and I submitted patches for the YP and Bitbake docs, but of course, I can accept the opposite choice if there's a majority for it.
Thanks in advance
Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hello,
Quoted 55 lines · Michael Opdenacker via lists.openembedded.org
Hi Quentin,
Quoted 31 lines · Quentin Schulz
Hi Michael,
Quoted 13 lines · Michael Opdenacker
Hi Quentin,
Thanks for the review!
Quoted 8 lines · Quentin Schulz
Hi Michael,
Quoted 3 lines · Michael Opdenacker via lists.yoctoproject.org
From: Michael Opdenacker <[email protected]>
- Replace hyphens by em dashes when necessary
I seem to recall we ultimately decided to not go for em dashes because it wouldn't be matched by a search in the browser or in the sources?
c.f. https://lists.yoctoproject.org/g/docs/topic/85211078#1731
for the original discussion around em dashes. Didn't decide anything at that time though but you have all the arguments there.
Quoted 10 lines
Ouch, this is frustrating. I'd rather not deviate from English writing rules, so that we don't have to keep a list of exceptions to them, or worse keep them in the back of our heads.
And why would one need to look for an em dash in the browser or in the sources? As a reader, I'd avoid special characters in my searches, and as a developer, I would do the same, but if I really want to look for a specific em dash, I'll quickly find what the corresponding characters are in the sources, thanks to the surrounding context.
Quoted 5 lines
You just gave the example as to why I think we shouldn't use em
dashes: to "avoid special characters in my searches".No more arguments since the discussion Robert started last August, so... up to you.
Thanks for the reminder about the original discussion. You have a better memory than I do ;-)
Could others (at least Richard, Nico ?) share their opinion here? Otherwise it's hard to find a majority opinion...
The question is whether we should use em dashes
(https://www.thepunctuationguide.com/em-dash.html), described as "---" in Restructed Text. This respects the English punctuation rules, but is harder to grep in the sources.If we prefer to use hyphens instead of em dashes in the documentation, we will have to document the exception, but the risk remains to get questions from time to time.
Quoted 7 lines
My vote goes to using em dashes, and I submitted patches for the YP and Bitbake docs, but of course, I can accept the opposite choice if there's a majority for it.
Thanks in advance
Cheers
Michael.
Since nobody except Quentin voted against this change (for practical reasons to grep in the source code), I'll like to proceed with this change, to be consistent with standard rules for English text.
At least, this will allow us to distinguish simple dashes and em dashes, which have a different meaning, and may help Sphinx to break lines (or not to) in a correct way.
Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 5 lines · Michael Opdenacker via lists.yoctoproject.org
Since nobody except Quentin voted against this change (for practical reasons to grep in the source code), I'll like to proceed with this change, to be consistent with standard rules for English text.
At least, this will allow us to distinguish simple dashes and em dashes, which have a different meaning, and may help Sphinx to break lines (or not to) in a correct way.
Actually, this patch got merged: https://git.openembedded.org/bitbake/commit/?id=f1c4ac816e927f490fb9852c12aa408e8c9403b1
So, I resent the corresponding patch for em dashes in yocto-docs.
Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com