Skip to content

Added more punctuation guidance #515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julian-cable merged 2 commits into from
Aug 8, 2023
Merged

Added more punctuation guidance #515

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bcbdd2e
Added more punctuation guidance
julian-cable Aug 7, 2023
7ebeddc
Implemented review feedback
julian-cable Aug 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 92 additions & 21 deletions en-US/Punctuation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@
Try to limit your use of colons and semicolons. Separate sentences with a period if possible.
</para>
<formalpara>
<title>To introduce a list or series:</title>
<title>To introduce a series:</title>
<para>
A colon is generally used before a list or series.
A colon is generally used before a series.
</para>

</formalpara>
Expand All @@ -70,7 +70,7 @@

</itemizedlist>
<para>
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.
</para>
<itemizedlist>
<listitem>
Expand All @@ -79,7 +79,7 @@
</para>

</listitem>
<listitem>
<!-- <listitem>
<para>
The colors I hate most are:
</para>
Expand Down Expand Up @@ -107,15 +107,53 @@
magenta
</para>

</listitem>
</listitem>

</itemizedlist>
</itemizedlist>

</listitem> -->

</itemizedlist>

<para>
Use a semicolon to separate items in a series if the items contain commas.
</para>
<itemizedlist>
<listitem>
<para>
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.
</para>

</listitem>

</itemizedlist>
<para>
Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence.
When a conjunctive adverb (such as <emphasis>however, therefore, otherwise, namely, for example</emphasis>, and so on) joins two independent clauses, use a semicolon before the conjunctive adverb and a comma after it.
</para>

<itemizedlist>
<listitem>
<para>
I think; therefore, I am.
</para>

</listitem>

</itemizedlist>

<formalpara id="list-intro-punc">
<title>To introduce a list, command, code block, or procedure</title>
<para>
If a list, command, code block, or procedure immediately follows a single stem or introductory sentence, then end that sentence with a colon.
</para>
</formalpara>
<para>
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.
</para>

<para>
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.
</para>
<itemizedlist>
<listitem>
Expand All @@ -142,7 +180,7 @@

</itemizedlist>
<para>
Use a colon to introduce a bullet list.
In the following example, a colon is used to introduce a bullet list:
</para>
<itemizedlist>
<listitem>
Expand Down Expand Up @@ -176,7 +214,7 @@
</listitem>
<listitem>
<para>
Cost per
Cost per unit
</para>

</listitem>
Expand All @@ -185,32 +223,43 @@

</listitem>

</itemizedlist>
<para>
Use a semicolon to separate items in a series if the items contain commas.
</itemizedlist>

<para>
In the following example, a colon is used for a step that introduces a command:
</para>
<itemizedlist>
<itemizedlist>
<listitem>
<para>
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 <command>ansible-navigator run</command> command to run the <filename>allfacts.yml</filename> playbook:
</para>
<screen>[student@workstation manage-facts]$ ansible-navigator run allfacts.yml
PLAY [Gather and display facts for managed nodes] ****************************</screen>

</listitem>

</itemizedlist>
<para>
Use a semicolon before a conjunctive adverb, such as <emphasis>however, therefore, otherwise, namely, for example</emphasis>, and so on.
</para>
</itemizedlist>

<itemizedlist>
<para>
In the following example, several sentences introduce a code example, and each one ends in a period:
</para>
<itemizedlist>
<listitem>
<para>
I think; therefore, I am.
To configure SELinux persistently, use the <filename>/etc/selinux/config</filename> file.
In the following default example, the configuration sets SELinux to <option>enforcing</option> mode.
The comments list other valid values, such as the <option>permissive</option> and <option>disabled</option> modes.
</para>
<screen># 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.
<emphasis>...output omitted...</emphasis> </screen>

</listitem>

</itemizedlist>
</itemizedlist>

</section>
<section id="commas">
Expand Down Expand Up @@ -269,6 +318,28 @@

</listitem>

</itemizedlist>
<formalpara id="conjunctive-adverbs">
<title>With conjunctive adverbs:</title>
<para>
When using a conjunctive adverb (such as <emphasis>however, therefore, otherwise, namely, for example</emphasis>, and so on) in a sentence, set it off with commas.
</para>

</formalpara>
<itemizedlist>
<listitem>
<para>
It rained all afternoon. As a result, we canceled our picnic.
</para>

</listitem>
<listitem>
<para>
The grass, however, stayed dry under the trees.
</para>

</listitem>

</itemizedlist>
<formalpara id="adverbial-clauses">
<title>In adverbial clauses and phrases:</title>
Expand Down
100 changes: 100 additions & 0 deletions en-US/Translation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,102 @@

</table>

</section>

<section><title>Punctuation in Lists</title>
<para>
For each item in a list, start with either a complete sentence or a sentence fragment.
</para>
<para>
For a list where all items are complete sentences, end each item with a period.
</para>
<para>
Example:
</para>
<para>
Which statement is true about deployments and deployment configurations?
</para>
<itemizedlist>
<listitem>
<para>
Deployments use replica sets, and deployment configurations use replication controllers.
</para>
</listitem>
<listitem>
<para>
Deployments use replication controllers, and deployment configurations use replica sets.
</para>
</listitem>
<listitem>
<para>
Deployments and deployment configurations both refer to the same thing.
</para>
</listitem>
<listitem>
<para>
Deployments use replica sets, and deployment configurations use stateful sets.
</para>
</listitem>
</itemizedlist>
<para>
For a list where all items are sentence fragments, do not end the items with any punctuation.
</para>
<para>
Example:
</para>
<para>
Which resource type does the Operator Lifecycle Manager use to store information about installed operators?
</para>
<itemizedlist>
<listitem>
<para>
Operator group
</para>
</listitem>
<listitem>
<para>
Catalog source
</para>
</listitem>
<listitem>
<para>
Install plan
</para>
</listitem>
<listitem>
<para>
Operator
</para>
</listitem>
</itemizedlist>
<para>
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.
</para>
<para>
Example:
</para>
<itemizedlist>
<listitem>
<para>
Identifier of the object schema version.
</para>
</listitem>
<listitem>
<para>
Schema identifier. In this example, the object conforms to the pod schema.
</para>
</listitem>
<listitem>
<para>
Name of the container inside a pod.
Container names are important for <command>oc</command> commands when a pod contains multiple containers.
</para>
</listitem>
</itemizedlist>
<para>
For information about punctuation in lead-in sentences that introduce a list, see <xref linkend="list-intro-punc"/>.
</para>

</section>
</section>

Expand Down Expand Up @@ -510,6 +606,10 @@
<screen>Usage: <command>rhevm-iso-uploader <replaceable>[options]</replaceable> list</command>
<command>rhevm-iso-uploader <replaceable>[options] </replaceable>upload <replaceable>[file1] [file2] [file3]</replaceable></command></screen>

<para>
For information about punctuation in lead-in sentences that introduce a code block, see <xref linkend="list-intro-punc"/>.
</para>

</section>
<section id="Writing_Clearly_and_Succinctly-Entities">
<title>Entities</title>
Expand Down