Skip to content

Closes #458 Run Vale over style guide part 4. #467

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
merged 1 commit into from
Feb 13, 2023
Merged

Closes #458 Run Vale over style guide part 4. #467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
13 changes: 6 additions & 7 deletions en-US/T.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,32 +149,31 @@
</listitem>

</varlistentry>
<!-- IBM has now changed to use of one-word forms for many "time-" prefixed words: timebox, timeframe, timeline, timeout, timeslice, timestamp, but still "time zone". -->
<varlistentry id="time-frame">
<term>time frame (n.)</term>
<term>time frame</term>
<listitem>
<para>
Correct. Do not use "timeframe" or "time-frame".
<emphasis>n.</emphasis> Correct. Do not use "timeframe" or "time-frame".
</para>

</listitem>

</varlistentry>
<varlistentry id="time-zone">
<term>time zone (n.)</term>
<term>time zone</term>
<listitem>
<para>
Correct. Do not use "timezone" or "time-zone".
<emphasis>n.</emphasis> Correct. Do not use "timezone" or "time-zone".
</para>

</listitem>

</varlistentry>
<varlistentry id="token-ring">
<term>token-ring (n.)</term>
<term>token-ring</term>
<listitem>
<para>
When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard.
<emphasis>n.</emphasis> When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard.
<!-- See the <citetitle>IBM Style Guide</citetitle> for further uses of this term. -->
</para>

Expand Down
19 changes: 10 additions & 9 deletions en-US/Translation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,20 @@
<section id="Sentence_Structure-Using_Lists_Correctly">
<title>Using and Formatting Lists</title>
<para>
Lists appear in a range of formats, such as series, ordered, unordered (itemized), and so on. Avoid using itemized lists to format a single sentence. Some translation tools display list items and the introductory sentence (or <firstterm>sentence stem</firstterm>) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate.
Lists appear in a range of formats, such as series, ordered, unordered (bulleted), and so on.
Avoid using bulleted lists to format a single sentence.
Some translation tools display list items and the introductory sentence (or <firstterm>sentence stem</firstterm>) as individual sentences for translation.
If they are not complete sentences, they can be difficult to translate.
</para>
<para>
The following general guidelines apply to lists:
</para>
<variablelist>
<varlistentry>
<term>Itemized lists</term>
<term>Bulleted lists</term>
<listitem>
<para>
They appear as a bulleted list.
Use this list type for three or more entries where order is not important, or in a demonstration section when students are encouraged not to perform steps but to watch the instructor instead.
Use this list type for three or more entries where order is not important.
Titles are optional.
</para>
</listitem>
Expand All @@ -38,7 +40,7 @@
<term>Ordered lists</term>
<listitem>
<para>
They appear as a numbered list.
These appear as numbered lists.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the sake of translation, "These" should be followed by a noun wherever it occurs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, this guide is not translated, but ok.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but regardless, we should follow our own guidance in "Use of This That These Those" in https://stylepedia.net/style/6.0/#sentence-structure.

Copy link
Collaborator Author

@daobrien daobrien Feb 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tbh I disagree with that section in the current guide. I don't remember reviewing or ack'ing it (doesn't mean I didn't) but a) it's not a very good title, and b) I don't think following nouns are always required. I think this small section is far to prescriptive, leaving no room for other possibilities, and being a lot more strict than "providing guidelines", which is what the style guide is for in many cases.

In this particular case, the result would be "These lists appear as numbered lists", which is not pretty. This construction also appears many, many times in the current guide. If you think it's an issue that definitely needs addressing then I recommend making it part of the "review the style guide" GH issue.

Use this list type for multiple entries if you need to refer to one of the entries from elsewhere in your document, or where order is important.
For example, if you need to list the order of operations that are required to prepare for an installation, or list a sequence of events that occurs.
Titles are optional.
Expand All @@ -49,7 +51,7 @@
<term>Variable lists</term>
<listitem>
<para>
They appear as a list of terms followed by definitions.
These appear as a list of terms followed by definitions.
Use this list type to list and describe a series of terms, such as variables, command options or arguments, and similar items.
Titles are optional.
(This list is written as a variable list.)
Expand All @@ -62,19 +64,18 @@
<term>Procedures</term>
<listitem>
<para>
They appear as a list of numbered steps.
These appear as a list of numbered steps.
Procedures always include a title, and are used to list the required steps to achieve a task.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
You can nest lists, but try to keep the number of levels to two or fewer.
To nest procedures in DocBook, use &lt;substep&gt; elements.
</para>
<section><title>Formatting Lists for Readability</title>
<para>
It is important to provide sufficient spacing between elements in your documents to facilitate reading and comprehension.
It is important to provide enough spacing between elements in your documents to facilitate reading and comprehension.
You can include a lot of information in a few short paragraphs but readers need to be able to process that information in chunks.
The same consideration applies to lists.
</para>
Expand Down
25 changes: 18 additions & 7 deletions en-US/U.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,12 @@
<term>UltraSPARC</term>
<listitem>
<para>
Correct. Do not use "ULTRASPARC", "UltraSparc", or other variations.
Correct.
Do not use "ULTRASPARC", "UltraSparc", or other variations.
</para>
<para>
UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc.
UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc.
Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc.
</para>

</listitem>
Expand All @@ -33,7 +35,10 @@
<term>undercloud</term>
<listitem>
<para>
<emphasis>n.</emphasis> Always lowercase. It is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also <xref linkend="overcloud" />.
<emphasis>n.</emphasis> Always lowercase.
It is a concept, not a technology or product name.
Being a common noun, it normally requires an article.
See also <xref linkend="overcloud" />.
</para>

</listitem>
Expand Down Expand Up @@ -185,10 +190,14 @@
<term>user interface</term>
<listitem>
<para>
<emphasis>n.</emphasis> Correct. Do not use "user-interface" or "userinterface".
<emphasis>n.</emphasis> Correct.
Do not use "user-interface" or "userinterface".
</para>
<para>
The junction between a user and a computer program. An interface is a set of commands or menus through which a user communicates with a program. In a command-driven interface, you enter commands. In a menu-driven interface, you select command choices from various menus that are displayed on the screen.
The junction between a user and a computer program.
An interface is a set of commands or menus through which a user communicates with a program.
In a command-driven interface, you enter commands.
In a menu-driven interface, you select command choices from various menus that are displayed on the screen.
</para>

</listitem>
Expand All @@ -198,7 +207,7 @@
<term>username</term>
<listitem>
<para>
<emphasis>n.</emphasis> One word in most cases.
<emphasis>n.</emphasis> Usually one word.
Capitalize the "U" at the beginning of a sentence.
See the <citetitle>IBM Style Guide</citetitle> for more information.
</para>
Expand All @@ -210,7 +219,9 @@
<term>user space</term>
<listitem>
<para>
<emphasis>n.</emphasis> Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space". Do not use "userspace".
<emphasis>n.</emphasis> Correct when used as a noun.
When used as a modifier, use the hyphenated form, "user-space".
Do not use "userspace".
</para>

</listitem>
Expand Down
5 changes: 4 additions & 1 deletion en-US/V.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,10 @@
Only use "vim" (all lowercase) when referring to the command to start the application.
</para>
<para>
Vim is an acronym, derived from Vi IMproved. (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved when ported to various UNIX-based operating systems in 1992.) Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
Vim is an acronym, derived from Vi IMproved.
(In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation.
It became Vi IMproved when ported to various UNIX-based operating systems in 1992.)
Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
</para>

</listitem>
Expand Down
20 changes: 12 additions & 8 deletions en-US/W.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,9 @@
<term>web page</term>
<listitem>
<para>
<emphasis>n.</emphasis> Two words. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly.
<emphasis>n.</emphasis> Two words.
Capitalize the "W" at the beginning of a sentence.
If part of a proper noun, capitalize accordingly.
</para>

</listitem>
Expand All @@ -73,7 +75,8 @@
<term>web UI</term>
<listitem>
<para>
Correct. Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web.
Correct.
Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web.
Do not hyphenate the abbreviation or use the one-word form.
</para>

Expand All @@ -97,7 +100,7 @@
<term>whether</term>
<listitem>
<para>
Use “whether” instead of “if” to refer to a choice or to alternatives.
Use "whether" instead of "if" to refer to a choice or to alternatives.
For example, instead of "Test if authenticated FTP access is restored", write "Test whether authenticated FTP access is restored".
</para>

Expand All @@ -109,23 +112,23 @@
<term>while</term>
<listitem>
<para>
In technical content, use “while” only to indicate that many tasks or processes occur at the same time.
For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs".
In technical content, use "while" only to indicate that many tasks or processes occur at the same time.
For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs."
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest not to include the period in the quotation, to mirror the comma placement in the previous example.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that was where they belonged. Did I read it wrong?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last example in this sentence could go either way, because it is a complete sentence in itself; however, my overriding preference is to move the punctuation outside the quotation marks, for consistency with the previous example that ends with a comma. A minor point for sure.

</para>

</listitem>

</varlistentry>

<!-- Added for inclusive language -->
<varlistentry id="whitelist">
<term>whitelist</term>
<listitem>
<para>
Do not use. Use "allowlist".
</para>
<para>
Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad. Such usage reinforces a model that promotes racial bias.
Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad.
Such usage reinforces a model that promotes racial bias.
</para>
</listitem>

Expand All @@ -138,7 +141,8 @@
Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition.
</para>
<para>
For example: Who owns this phone? To whom does this phone belong?
For example: Who owns this phone?
To whom does this phone belong?
</para>

</listitem>
Expand Down
8 changes: 6 additions & 2 deletions en-US/WUG_Intro.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,18 @@
<chapter id="usage-dictionary">
<title>Usage Dictionary</title>
<para>
This page provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling where variations exist. This page is constantly evolving, and open to discussion and improvement.
This page provides guidelines for the correct use of common terms in Red&nbsp;Hat documentation, which terms to avoid, and the preferred spelling where variations exist.
This page is constantly evolving, and open to discussion and improvement.
</para>
<variablelist>
<varlistentry id="Usage_Dictionary-A_note_about_trademarks">
<term>A note about trademarks</term>
<listitem>
<para>
The status of a trademark can vary from country to country. Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. In XML terms, this means that you should not generally tag trademarks with the &lt;trademark&gt; tag. We do mark Red Hat's own trademarks. See <ulink url="https://home.corp.redhat.com/node/34059">Copyright Notices and Trademark Legends</ulink> for more information.
The status of a trademark can vary from country to country.
Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red&nbsp;Hat legal asks you to do so.
We do mark Red&nbsp;Hat trademarks.
See <ulink url="https://home.corp.redhat.com/node/34059">Copyright Notices and Trademark Legends</ulink> for more information.
</para>

</listitem>
Expand Down
6 changes: 4 additions & 2 deletions en-US/XYZ.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@
<term>YAML</term>
<listitem>
<para>
Recursive acronym for "YAML Ain't Markup Language." Expand on first use only.
Recursive acronym for "YAML Ain't Markup Language."
Expand on first use only.
</para>

</listitem>
Expand All @@ -80,7 +81,8 @@
<term>you</term>
<listitem>
<para>
Use second person wherever possible. Do not use "I", "we", "he", or "she."
Use second person wherever possible.
Do not use "I", "we", "he", or "she."
</para>

</listitem>
Expand Down