Skip to contentSkip to conversation

bitbake-user-manual: punctuation fixes

PATCH In review [email protected] 2 participants 7 messages Mar 29, 2022 – Jun 22, 2022 2 messages not in the archive

lore
Share & tools
lore
#0 lore raw

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
index 7325831d..d4f56afa 100644
@@ -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
index 088eb818..7a22e96e 100644
@@ -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
index ea42d77c..af4b1358 100644
@@ -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
#1 lore raw

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

#2 lore raw

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
#3 lore raw

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

#4 lore raw

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
#6 lore raw
In reply to a message not in the archive

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
#8 lore raw
In reply to a message not in the archive
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