Skip to content

Vale check of Style Guide Part 1 #459

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
daobrien merged 2 commits into from
Jan 24, 2023
Merged

Vale check of Style Guide Part 1 #459

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
ce9dd60
Working on #450.
Dec 19, 2022
c00a40e
Run Vale over Design.xml.
Jan 23, 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
18 changes: 8 additions & 10 deletions en-US/A.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@
]>
<chapter id="a">
<title>A</title>
<!-- Some of the entries were not listed in alphabetical order. -->
<variablelist>
<!-- Entries previously used a mixture of "v." and "vb." to denote a verb. Changed all occurrences to "v." -->
<varlistentry id="amp-and-">
<term>"&amp;" and "+"</term>
<listitem>
Expand Down Expand Up @@ -55,10 +53,10 @@
</varlistentry>
<varlistentry id="all-in-one">
<term role="true">all-in-one</term>
<term role="false">allinone</term>
<listitem>
<para>
<emphasis>n., adj.</emphasis> Hyphenate in both places. Do not use "allinone" or other variations.
<emphasis>n., adj.</emphasis> Write as shown as both a noun and an adjective.
Do not use other variations.
</para>

</listitem>
Expand All @@ -78,7 +76,7 @@
</listitem>

</varlistentry>

<varlistentry id="alternative">
<term role="true">alternative</term>
<listitem>
Expand All @@ -98,7 +96,7 @@
<listitem>
<para>
For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11&nbsp;AM".
</para>
</para>
<para>
See also <xref linkend="pm"/>.
</para>
Expand All @@ -123,7 +121,7 @@
<para>
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />.
</para>
<!-- Updated URL for AMD trademarks. -->
<!-- Updated URL for AMD trademarks. -->
<para>
For more information about Intel&reg; trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />.
</para>
Expand Down Expand Up @@ -157,9 +155,9 @@

</listitem>

</varlistentry>
</varlistentry>

<!-- Commenting out this entry as it is not a literal term entry. Consider moving elsewhere, such as to Section 3.7 and expand scope of that section?
<!-- Commenting out this entry as it is not a literal term entry. Consider moving elsewhere, such as to Section 3.7 and expand scope of that section?
<varlistentry id="application">
<term>application</term>
<listitem>
Expand Down Expand Up @@ -295,7 +293,7 @@
<para>
When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS).
</para>
<!-- When would all capitals be used? -->
<!-- When would all capitals be used? -->

</listitem>
<listitem>
Expand Down
2 changes: 1 addition & 1 deletion en-US/Author_Group.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
]>
<authorgroup>
<author>
<firstname>Red Hat Documentation Team</firstname>
<firstname>Red&nbsp;Hat Documentation Team</firstname>
<surname></surname>
<affiliation>
<orgname></orgname>
Expand Down
5 changes: 2 additions & 3 deletions en-US/B.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,6 @@
<para>
Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also <xref linkend="forwards-compatible" />.
</para>
<!-- Replaced with "compatible with earlier versions", to align with advice for "forwards-compatible". -->

</listitem>

Expand Down Expand Up @@ -362,8 +361,8 @@
<term>broadcast</term>
<listitem>
<para>
To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems.
<!-- Deleted reference to fax.
To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems.
<!-- Deleted reference to fax.
It is also supported by some fax systems. -->
</para>
<para>
Expand Down
6 changes: 4 additions & 2 deletions en-US/Book_Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,9 @@
Drawing these basics together might produce the following example abstract:
</para>
<para>
"The Red&nbsp;Hat Satellite&nbsp;5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications."
"The Red&nbsp;Hat Satellite&nbsp;5.6 API Guide is a full reference for Satellite's XMRPC API.
The guide explains each API method and demonstrates examples of data models for input and output.
This book provides a basis for administrators and developers to write custom scripts and to integrate Red&nbsp;Hat Satellite with third-party applications."
</para>
<para>
Update or modify each component according to the type of book that you are writing.
Expand All @@ -122,7 +124,7 @@
</section>
<section id="unused-heading-titles">
<title>Unused Heading Titles</title>
<para>
<para>
This section lists various heading titles that might be used in Red&nbsp;Hat technical documentation, but that should be avoided except in specific circumstances.
</para>
<formalpara id="overview">
Expand Down
2 changes: 1 addition & 1 deletion en-US/Cross_references.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
Must the information be repeated?
</para>
<para>
This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. It's not a crime. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.
This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.
</para>
<para>
Cross-referencing is a good servant but a poor master. Content still rules!
Expand Down
63 changes: 38 additions & 25 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
<title>Capitalization</title>
<para>
The standard for all Red&nbsp;Hat technical documentation is title case for all headings and titles.
Table headings, procedure headings, and formal paragraph titles fall under this heading, and consequently, standard title case capitalization rules apply.
Table headings, procedure headings, and formal paragraph titles fall under this heading; standard title case capitalization rules apply.
</para>
</formalpara>
<para>
Expand All @@ -42,7 +42,7 @@

<para>
Be frugal with punctuation.
In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name.
Avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name.
Do not use terminating periods.
</para>
</formalpara>
Expand Down Expand Up @@ -102,7 +102,7 @@
For example, for a button labeled <guibutton>Save As...</guibutton>, do not include the ellipsis in the documentation.
</para>
<para>
In most cases, do not include the element type in instructions.
Avoid including the element type in instructions.
For example, rather than "Click the <guibutton>Save</guibutton> button", write "Click <guibutton>Save</guibutton>".
</para>
<para>
Expand Down Expand Up @@ -136,7 +136,7 @@
<section>
<title>Navigating Through Multiple UI Options</title>
<para>
Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to initiate an action.
Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action.
</para>
<para>
For example, "From the OpenShift web console, navigate to Monitoring → Alerting."
Expand Down Expand Up @@ -182,7 +182,7 @@
</para>
<para>
RHEL&nbsp;8 uses the following approach to starting applications from the desktop.
In an effort to maintain consistency and to make translation easier, Red&nbsp;Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications.
To maintain consistency and to make translation easier, Red&nbsp;Hat documentation assumes the use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications.
</para>
<para>
The preferred approach is to use the <keycap>Super</keycap> key to enter the Activities Overview, to enter the name of the required application, and to press <keycap>Enter</keycap>.
Expand Down Expand Up @@ -272,7 +272,7 @@
<term>Target options <replaceable>[directory]</replaceable></term>
<listitem>
<para>
The optional directory into which the repository will be cloned.
The optional directory into which the repository is cloned.
It must be replaced with a valid value, or be omitted.
</para>

Expand Down Expand Up @@ -326,7 +326,8 @@
<term>Target options (<replaceable>[username@]hostname:/directory</replaceable>)</term>
<listitem>
<para>
The optional username, indicated by brackets ([]), followed by the hostname and path to the target directory. All aspects of this component must be replaced with valid values.
The optional username, indicated by brackets, [], followed by the hostname and path to the target directory.
All aspects of this component must be replaced with valid values.
</para>

</listitem>
Expand All @@ -336,7 +337,7 @@
</variablelist>
<warning>
<para>
In most cases, avoid using the <option>--force (-f)</option> and <option>--assumeyes (-y)</option> options on most commands, especially when logged in as the <systemitem>root</systemitem> user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples:
Avoid using the <option>--force (-f)</option> and <option>--assumeyes (-y)</option> options on most commands, especially when logged in as the <systemitem>root</systemitem> user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that might not suit your system. Refer to the following examples:
</para>

<screen>[root@serverc pam.d]# rm -f system-auth password-auth
Expand All @@ -353,7 +354,8 @@
<section>
<title>Documenting Multiple or Long Commands</title>
<para>
Sometimes you need to demonstrate how to use long commands that extend over two or more lines, or that include several commands in a single example. If the commands are relatively short and straightforward, then include the commands on consecutive lines:
Sometimes you need to show how to use long commands that extend over two or more lines, or that include several commands in a single example.
If the commands are relatively short and straightforward, then include the commands on consecutive lines.
</para>
<example>
<title>Documenting Multiple Commands</title>
Expand Down Expand Up @@ -387,7 +389,7 @@ $ vi myFile.txt
<important>
<para>
Do not mix these styles.
Maintain the same style throughout your document, book, and product set.
Use the same style throughout your document, book, and product set.
</para>
</important>
<para>
Expand All @@ -410,7 +412,7 @@ $ vi myFile.txt

<example><title>Wrapping Long Commands Without Continuation Characters or PS2 Prompts</title>
<para>
This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands.
This example uses neither continuation characters nor PS2 prompts, but it does show how to use line indentation to help to clarify long commands.
</para>
<screen># cd /var/lib/katello

Expand Down Expand Up @@ -470,7 +472,7 @@ $ vi myFile.txt

<para>
The term <firstterm>escalated privileges</firstterm> refers to changing to a user whose privileges allow operations that a normal user cannot access.
It also refers to temporarily changing the privileges of the current user to perfom those operations without actually changing user accounts.
It also refers to temporarily changing the privileges of the current user to perfom those operations without changing user accounts.
</para>
<note>
<para>
Expand Down Expand Up @@ -587,7 +589,8 @@ $ vi myFile.txt
<section id="use-hostnames-correctly">
<title>Using Host and Usernames Correctly</title>
<para>
Many examples in Red&nbsp;Hat documentation require the use of usernames, hostnames, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red&nbsp;Hat recommends the following approach.
Many examples in Red&nbsp;Hat documentation require the use of usernames, hostnames, IP addresses, and similar information.
To reduce security risks, to minimize translation overhead, and to maintain consistency, Red&nbsp;Hat recommends the following approach:
</para>
<note>
<para>
Expand All @@ -598,7 +601,8 @@ $ vi myFile.txt
<itemizedlist>
<listitem>
<para>
Use <ulink url="http://tools.ietf.org/search/rfc2606">RFC 2606</ulink> to determine suitable domain names. For documentation and example purposes, it is typically <systemitem>example.com</systemitem>, <systemitem>example.net</systemitem>, <systemitem>example.org</systemitem>, and <systemitem>example.edu</systemitem>.
Use <ulink url="http://tools.ietf.org/search/rfc2606">RFC 2606</ulink> to find suitable domain names.
For documentation and example purposes, it is typically <systemitem>example.com</systemitem>, <systemitem>example.net</systemitem>, <systemitem>example.org</systemitem>, and <systemitem>example.edu</systemitem>.
</para>
<important>
<para>
Expand All @@ -618,7 +622,7 @@ $ vi myFile.txt

<screen><prompt>[root@fedora ~]# </prompt><userinput>setfacl -m u:user1:rw /project/file1</userinput></screen>
<para>
The following list provides further alternatives:
The following list provides further options:
</para>
<itemizedlist>
<listitem>
Expand Down Expand Up @@ -685,7 +689,8 @@ $ vi myFile.txt
</listitem>
<listitem>
<para>
Include a diverse set of names in your examples to reflect the diversity of the real world. For example, use male, female, and culturally diverse names that suggest a variety of backgrounds in examples to avoid implying that only certain groups have specific skills.
Include a diverse set of names in your examples to reflect the diversity of the real world.
For example, use male, female, and culturally diverse names that suggest various backgrounds in examples to avoid implying that only certain groups have specific skills.
</para>

</listitem>
Expand Down Expand Up @@ -1087,14 +1092,18 @@ $ vi myFile.txt

</para>
<para>
In most cases, major changes take place in major version releases, and are carried through any minor updates to that release. If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release.
Major changes usually take place in major version releases, and are carried through any minor updates to that release.
If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release.
</para>
<para>
Avoid using the "dot-oh" release number. For example, do not use Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;6.0. Use instead Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;6.
Avoid using the "dot-oh" release number.
For example, do not use Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;6.0.
Use instead Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;6.
</para>
<important>
<para>
This rule applies only to Red&nbsp;Hat products. Refer to other companies' products and use their version numbers as they use them.
This rule applies only to Red&nbsp;Hat products.
Refer to other companies' products and use their version numbers as they use them.
</para>

</important>
Expand All @@ -1103,14 +1112,17 @@ $ vi myFile.txt
<section id="admonitions">
<title>Using Admonitions</title>
<para>
To call attention to a statement, use an admonition. Red&nbsp;Hat technical documentation currently uses <command>Note</command>, <command>Important</command>, and <command>Warning</command> admonitions.
To call attention to a statement, use an admonition.
Red&nbsp;Hat technical documentation currently uses <command>Note</command>, <command>Important</command>, and <command>Warning</command> admonitions.
</para>
<para>
Admonitions automatically include a suitable title according to the type of admonition. Do not use a phrase or anything else for the title. Keep in mind these considerations if using admonitions:
Admonitions automatically include a suitable title according to the type of admonition.
Do not use a phrase or anything else for the title.
Keep the following considerations in mind if using admonitions:
<itemizedlist>
<listitem>
<para>
Keep the statements as brief and to the point as possible.
Keep statements brief and to the point.
</para>

</listitem>
Expand All @@ -1122,19 +1134,20 @@ $ vi myFile.txt
</listitem>
<listitem>
<para>
Use a <command>Note</command> admonition to bring additional information to the user's attention.
Use a <command>Note</command> admonition to bring extra information to the user's attention.
</para>

</listitem>
<listitem>
<para>
Use an <command>Important</command> admonition to show the user a piece of information that should not be overlooked. While this information might not change anything that the user is doing, it should show the user that this piece of information could be vital.
Use an <command>Important</command> admonition to show the user a piece of information that should not be overlooked.
This information might not change anything that the user is doing, but it should show the user that this piece of information could be vital.
</para>

</listitem>
<listitem>
<para>
Use a <command>Warning</command> admonition to alert the reader that the current setup will change or be altered, such as files being removed, and not to perform the operation unless fully aware of the consequences.
Use a <command>Warning</command> admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences.
</para>

</listitem>
Expand Down