From bcbdd2e7b5ec84742bd3f5d2cada21d1eddfe9bb Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 7 Aug 2023 18:01:38 +0100 Subject: [PATCH 1/2] Added more punctuation guidance --- en-US/Punctuation.xml | 91 +++++++++++++++++++++++++++++--------- en-US/Translation.xml | 100 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 21 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 4e0020a..6f064fb 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -54,9 +54,9 @@ Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - To introduce a list or series: + To introduce a series: - A colon is generally used before a list or series. + A colon is generally used before a series. @@ -70,7 +70,7 @@ - Do not use a colon if the list is a complement or object of an element in the sentence. + Do not use a colon if the series is a complement or object of an element in the sentence. @@ -79,7 +79,7 @@ - + + + + + + Use a semicolon to separate items in a series if the items contain commas. + + + + + Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. + - Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. + Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + + + + + + I think; therefore, I am. + + + + + + + + To introduce a list, command, code block, or procedure + + If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon. + + + + If, however, any sentences intervene between the introduction and the next item, then end both the introduction and any intervening sentences with a period instead. + + + + In the following example, the related list immediately follows the stem, or introductory sentence, after "as follows". + If that sentence instead ends with "the following", then ensure that a noun is used after those words. @@ -142,7 +180,7 @@ - Use a colon to introduce a bullet list. + In the following example, a colon is used to introduce a bullet list: @@ -176,7 +214,7 @@ - Cost per + Cost per unit @@ -185,32 +223,43 @@ - - - Use a semicolon to separate items in a series if the items contain commas. + + + + In the following example, a colon is used for a step that introduces or leads into a command: - + - Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. + 2. Use the ansible-navigator run command to run the allfacts.yml playbook: +[student@workstation manage-facts]$ ansible-navigator run allfacts.yml +PLAY [Gather and display facts for managed nodes] **************************** - - - Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. - + - + + In the following example, a period is used at the end of each of several sentences that introduce a code example: + + - I think; therefore, I am. + To configure SELinux persistently, use the /etc/selinux/config file. + In the following default example, the configuration sets SELinux to mode. + The comments list other valid values, such as the and modes. +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +...output omitted... - +
diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 2cd19b1..9801c5e 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -321,6 +321,102 @@ +
+ +
Punctuation in Lists + + For each item in a list, start with either a complete sentence or a sentence fragment. + + + For a list where all items are complete sentences, end each item with a period. + + + Example: + + + Which statement is true about deployments and deployment configurations? + + + + + Deployments use replica sets, and deployment configurations use replication controllers. + + + + + Deployments use replication controllers, and deployment configurations use replica sets. + + + + + Deployments and deployment configurations both refer to the same thing. + + + + + Deployments use replica sets, and deployment configurations use stateful sets. + + + + + For a list where all items are sentence fragments, do not end the items with any punctuation. + + + Example: + + + Which resource type does the Operator Lifecycle Manager use to store information about installed operators? + + + + + Operator group + + + + + Catalog source + + + + + Install plan + + + + + Operator + + + + + For a list where the items start with sentence fragments, and any of those fragments are followed by a complete sentence, end each of the fragments and sentences with a period. + + + Example: + + + + + Identifier of the object schema version. + + + + + Schema identifier. In this example, the object conforms to the pod schema. + + + + + Name of the container inside a pod. + Container names are important for oc commands when a pod contains multiple containers. + + + + + For information about punctuation in lead-in sentences that introduce a list, see . + +
@@ -510,6 +606,10 @@ Usage: rhevm-iso-uploader [options] list rhevm-iso-uploader [options] upload [file1] [file2] [file3] + + For information about punctuation in lead-in sentences that introduce a code block, see . + +
Entities From 7ebeddcfce2327fd6115c62ba948eb5f4fa7bcd6 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 8 Aug 2023 10:48:35 +0100 Subject: [PATCH 2/2] Implemented review feedback --- en-US/Punctuation.xml | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 6f064fb..fb58491 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -121,14 +121,14 @@ - Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. + Every day I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. - Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + When a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) joins two independent clauses, use a semicolon before the conjunctive adverb and a comma after it. @@ -226,7 +226,7 @@ - In the following example, a colon is used for a step that introduces or leads into a command: + In the following example, a colon is used for a step that introduces a command: @@ -241,7 +241,7 @@ PLAY [Gather and display facts for managed nodes] **************************** - In the following example, a period is used at the end of each of several sentences that introduce a code example: + In the following example, several sentences introduce a code example, and each one ends in a period: @@ -318,6 +318,28 @@ PLAY [Gather and display facts for managed nodes] **************************** + + + With conjunctive adverbs: + + When using a conjunctive adverb (such as however, therefore, otherwise, namely, for example, and so on) in a sentence, set it off with commas. + + + + + + + It rained all afternoon. As a result, we canceled our picnic. + + + + + + The grass, however, stayed dry under the trees. + + + + In adverbial clauses and phrases: