diff --git a/en-US/M.xml b/en-US/M.xml index 63d7d08..e35a362 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -41,12 +41,13 @@ - master - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use another term such as "main", "primary", "controller", or "leader". + Do not use "master" when it is paired with "slave". + Such use diminishes the horror of the dehumanizing practice of slavery. + Use another term such as "main", "primary", "controller", or "leader". Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. @@ -58,7 +59,9 @@ matrixes - Correct. This is the correct plural form for US English spelling. Do not use "matrices". + Correct. + This is the correct plural form for US English spelling. + Do not use "matrices". @@ -125,18 +128,20 @@ Objects on which data can be stored. These include hard disks, CDs, and tapes. - - In computer networks, "media" refers to the cables that link workstations together. Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass). + In computer networks, "media" refers to the cables that link workstations together. + Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass). + - The form and technology to communicate information. Multimedia presentations, for example, combine sound, pictures, and videos, all of which are different types of media. + The form and technology to communicate information. + Multimedia presentations, for example, combine sound, pictures, and videos, which are all different types of media. @@ -254,7 +259,10 @@ mouse button - n. Two words. Do not use "mouse-button" or "mousebutton". If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button". Do not hyphenate. + n. Two words. + Do not use "mouse-button" or "mousebutton". + If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button". + Do not hyphenate. @@ -264,7 +272,9 @@ Mozilla Firefox - Correct. First reference must be "Mozilla Firefox". Subsequent references can be "Firefox". + Correct. + The first reference must be "Mozilla Firefox". + Any following references can be "Firefox". @@ -274,7 +284,9 @@ Mozilla Thunderbird - Correct. First reference must be "Mozilla Thunderbird". Subsequent references can be "Thunderbird". + Correct. + The first reference must be "Mozilla Thunderbird". + Any following references can be "Thunderbird". diff --git a/en-US/N.xml b/en-US/N.xml index 94d16d7..ecac797 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -10,7 +10,8 @@ navigate to - Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting." + Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. + For example, "From the OpenShift web console, navigate to Monitoring → Alerting." Do not use "Go to", or "point to", or other variations. @@ -22,7 +23,8 @@ needs, needs to be, need to - Avoid when possible. Suggested alternatives include "must" or "required". + Avoid when possible. + Use "must" or "required" or similar. @@ -56,10 +58,13 @@ NFS - Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types. NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP. Users can manipulate shared files as if they were stored locally on the user's own hard disk. + Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types. + NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP. + Users can manipulate shared files as if they were stored locally on the user's own hard disk. - With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files. The NFS standards are publicly available and widely used. + With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files. + The NFS standards are publicly available and widely used. @@ -111,17 +116,14 @@ number sign - Generally, use "number sign" to refer to the # character. Alternatively, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see ), or when writing exclusively for a European audience. You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context. + Generally, use "number sign" to refer to the # character. + Or, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see ), or when writing exclusively for a European audience. + You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context. - - - diff --git a/en-US/O.xml b/en-US/O.xml index 49ce877..9cd08ac 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -51,15 +51,13 @@ offline backup - Correct. Use this term to refer to backing up a database while the database is not being accessed by applications. Do not use "cold backup" or any other variations. + Correct. + Use this term to refer to backing up a database while the database is not being accessed by applications. + Do not use "cold backup" or any other variations. - The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications. Do not use "hot backup" or any other variations. - - + The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications. + Do not use "hot backup" or any other variations. @@ -69,12 +67,13 @@ OK - When referring to the OK button, it is not necessary to use "button" in the sentence. For example, "Click OK to close the dialog box." + When referring to the OK button, it is not necessary to use "button" in the sentence. + For example, "Click OK to close the dialog box." - Use "OK" only to refer to an interface element, not in general text. For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command". + Use "OK" only to refer to an interface element, not in general text. + For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command". - @@ -92,7 +91,8 @@ once - Use only to mean "one time". Do not use as a conjunction to mean "after" or "when". + Use only to mean "one time". + Do not use as a conjunction to mean "after" or "when". Example 1: Instead of "Once the name is set for a network interface on the system, the name of the interface does not change", use "When the name is set for a network interface on the system, the name of the interface does not change". @@ -162,7 +162,9 @@ on-the-fly - Do not use. Avoid idioms, which might not be globally known. In this case, for example, "real time" is both non-idiomatic and more technically accurate. + Do not use. + Avoid idioms, which might not be globally known. + In this case, for example, "real time" is both non-idiomatic and more technically accurate. @@ -172,7 +174,10 @@ oops - A kernel oops is an error message that is generated as a result of a bug in the kernel. Do not use "oops" on its own. Also, avoid using "kernel oops" at the beginning of a sentence. See also "kernel panic". + A kernel oops is an error message that is generated because of a bug in the kernel. + Do not use "oops" on its own. + Also, avoid using "kernel oops" at the beginning of a sentence. + See also "kernel panic". @@ -244,10 +249,11 @@ open source way - A phrase that was coined by the Red Hat community and adopted by opensource.com in 2009. It is a reference to an "open source method", as in "Let's develop this project the open source way." + A phrase that was coined by the Red Hat community and adopted by opensource.com in 2009. + It is a reference to an "open source method", as in "Let's develop this project the open source way." - Do not use to suggest that something is being done only in the "spirit" of open source without actually having an open source policy as defined by Open Source Initiative, to avoid diluting the legal meaning of the term "open source". + Do not use to suggest that something is being done only in the "spirit" of open source without having an open source policy as defined by Open Source Initiative, to avoid diluting the legal meaning of the term "open source". @@ -287,7 +293,10 @@ overcloud - n. Always lowercase. This is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also . + n. Always lowercase. + This is a concept, not a technology or product name. + Being a common noun, it normally requires an article. + See also . @@ -297,7 +306,8 @@ override - Correct. Do not use "over-ride" or "over ride". + Correct. + Do not use "over-ride" or "over ride". diff --git a/en-US/Objectives.xml b/en-US/Objectives.xml index fc7a45f..a4b0796 100644 --- a/en-US/Objectives.xml +++ b/en-US/Objectives.xml @@ -6,7 +6,10 @@ Objectives of this Guide - The objective of the Red Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery. We write documentation for a variety of audiences, across multiple geographies and with very different skill sets. We write for end users as well as expert users. Red Hat documentation is: + The objective of the Red Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery. + We write documentation for various audiences, across multiple geographies and with different skill sets. + We write for end users as well as expert users. + Red Hat documentation is: - Accurate and consistent + Accurate and consistent. - Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale. + Readable, with a score of 60-70 on the Flesch-Kincaid reading ease scale. @@ -44,7 +47,10 @@ Readability - Technical documents should be readable by the targeted audience. In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years. The Flesch-Kincaid and Gunning Fog index provide measurable grades. A Red Hat guide should have a Gunning Fog index of 9-12. + Technical documents should be readable by the targeted audience. + In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years. + The Flesch-Kincaid and Gunning Fog index provide measurable grades. + A Red Hat guide should have a Gunning Fog index of 9-12. diff --git a/en-US/P.xml b/en-US/P.xml index 1f2f11d..d1e5df7 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -72,10 +72,13 @@ plain text - n. Two words. In most cases, do not use "plaintext", "cleartext", or other variants. + n. Two words. + In most cases, do not use "plaintext", "cleartext", or other variants. - Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm). Red Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm. Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext". + Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm). + Red Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm. + Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext". @@ -85,9 +88,9 @@ please - Do not use. Instead of saying "Please see the Getting Started Guide", use "See the Getting Started Guide." + Do not use. + Instead of saying "Please see the Getting Started Guide", use "See the Getting Started Guide." - Technical information requires an authoritative tone; terms of politeness convey the wrong tone for technical information and are not regarded the same way in all cultures. @@ -109,12 +112,11 @@ plug-in - n. Write hyphenated. Do not use "plugin". + n. Write hyphenated. + Do not use "plugin". A hardware or software module that adds a specific feature or service to a larger system. - - @@ -173,10 +175,12 @@ n. The name of the Power architecture is "Power", but the designation of individual chips tends to be either "PowerPC" or "POWER". Refer to IBM marketing or the Open Power Foundation if unsure. - Do not use the "PPC64" or "ppc64le" shorthand. Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct. Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode". + Do not use the "PPC64" or "ppc64le" shorthand. + Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct. + Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode". - Note: The PowerPC version of Red Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in almost all cases. + Note: The PowerPC version of Red Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 1ec0e8c..4e0020a 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -419,11 +419,13 @@ - If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. + If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. + If not, the period goes outside. - Do not use "(s)" in parentheses to denote a plural. If something can be singular or plural, make it plural. + Do not use "(s)" in parentheses to denote a plural. + If something can be singular or plural, make it plural. @@ -470,13 +472,6 @@
Quotation Marks - When indicating the start or end of a direct quotation, use curly quotation marks. In all other contexts, such as when writing code samples, code syntax, hexadecimal numbers, or hypertext links, use straight quotation marks. @@ -506,7 +501,7 @@ If you use the keyword operand PGMID="PAYCOM", you must ... --> - Julius Caesar said, “I came. I saw. I conquered.” + Julius Caesar said, "I came. I saw. I conquered." @@ -521,15 +516,8 @@ - - Do not put quotation marks around cliches or slang terms (in fact, avoid using cliches and slang as it makes the translation of content more difficult). - -Remove this sentence, and leave it to chapter 4 to cover avoidance of slang. +--> - - A word or words being introduced to readers should not be placed in quotation marks. In DocBook, use the <firstterm> element for first reference. If you are writing outside of the SGML tagging environment, use quotation marks for first references. Subsequent references do not need quotation marks or the <firstterm> element. - -Deleted paragraph now that DocBook tagging no longer applies. -->
Apostrophes @@ -554,7 +542,6 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Exclamation Points @@ -563,7 +550,6 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Referring to Punctuation Marks @@ -593,14 +579,12 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
Names of Punctuation Marks and Special Characters Use the names in the following table to refer to punctuation marks or special characters: - Names of Punctuation Marks and Special Characters @@ -667,7 +651,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> ✓ - Check mark + Checkmark @@ -789,4 +773,4 @@ Deleted paragraph now that DocBook tagging no longer applies. --> - \ No newline at end of file + diff --git a/en-US/Q.xml b/en-US/Q.xml index 32244f2..8ef1139 100644 --- a/en-US/Q.xml +++ b/en-US/Q.xml @@ -10,12 +10,8 @@ qeth - Lowercase at all times. + Always lowercase. - @@ -23,7 +19,8 @@ quiesce, quiescent - Use with caution. This term is readily understood in the context of databases and stateful systems, but in other contexts another term might be more suitable. + Use with caution. + This term is readily understood in the context of databases and stateful systems, but in other contexts another term might be more suitable. diff --git a/en-US/R.xml b/en-US/R.xml index 21d275f..1d43bc7 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -23,7 +23,10 @@ Correct. Do not use "RAMdisk", "ramdisk", or "RAdisk". - Refers to RAM that is configured to simulate a disk drive. You can access files on a RAM disk as you would access files on a real disk. RAM disks, however, are approximately a thousand times faster than hard disk drives. They are particularly useful, therefore, for applications that require frequent disk accesses. + Refers to RAM that is configured to simulate a disk drive. + You can access files on a RAM disk as you would access files on a real disk. + RAM disks, however, are about a thousand times faster than hard disk drives. + They are particularly useful, therefore, for applications that require frequent disk accesses. @@ -135,7 +138,8 @@ remote access server - A dedicated server to handle users who are not on a LAN but who need remote access to it. With a remote access server, users can gain access to files and print services on the LAN from a remote location. + A dedicated server to handle users who are not on a LAN but who need remote access to it. + With a remote access server, users can access files and print services on the LAN from a remote location. @@ -211,7 +215,10 @@ RPM - Initialism for RPM Package Manager. RPM manages files in the RPM format, known as RPM packages. Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. Files in RPM format are referred to as "RPM packages". + Initialism for RPM Package Manager. + RPM manages files in the RPM format, known as RPM packages. + Note: RPM packages are known informally as rpm files, but this informal usage is not used in Red Hat documentation, to avoid confusion with the command name. + Files in RPM format are referred to as "RPM packages". diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index 7c735c6..3bab0ad 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -86,13 +86,13 @@ BZ 927031: Review 'The Page Test' and 'The Reverse Test' entries. BZ 1020131: Section 6.2 The Page Test is not sensible. BZ 1070003: Add entry for "Internet of Things (IoT)". - Relocate some slang and jargon terms to appropriate section. + Move some slang and jargon terms to appropriate section. BZ 1070001: Add entry for "untrusted". BZ 1064711: Update section on hyphenation. BZ 1061598: Add section about correct use of Introductions, Titles, and other headings. Removed <quote> tags from body text to follow own advice. Updated section on using tags with abbreviations and acronyms. - BZ 1028253: Document standard for user and host names in CLI examples. + BZ 1028253: Document standard for user and hostnames in CLI examples. @@ -309,7 +309,7 @@ BZ 921826 Add entry for "best practices" to chapter "Avoiding Slang". BZ 916000 Add entry for correct use of product version numbers to Design chapter. - Fix entry for VDSM; it's not an acronym. + Fix entry for VDSM; not an acronym. BZ 909015 Entry for "refer to" conflicts with IBM style guide. Update some punctuation standards and cross references. diff --git a/en-US/S.xml b/en-US/S.xml index 46da1b8..20b92eb 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -141,7 +141,7 @@ Abbreviation of Security-Enhanced Linux. SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. - Do not use any other alternatives. + Do not use any other forms. @@ -216,7 +216,9 @@ Pronounced "shä" and thus requires "an" as the indefinite article. - SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. SHA2 variants are often specified by using their digest size, in bits, as the trailing number, in lieu of "2". Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. + SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. + SHA2 variants are often specified by using their digest size, in bits, as the trailing number, instead of "2". + Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions. See for full details. @@ -302,7 +304,9 @@ should - Do not use if it is something the user must do. For example, "You should make a backup" is a suggestion, while "You must make a backup" is a requirement. See also . + Do not use if it is something the user must do. + For example, "You should make a backup" is a suggestion, but "You must make a backup" is a requirement. + See also . @@ -351,7 +355,9 @@ since, as, because - Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" or "as" to refer to the passage of time. + Do not use "since" or "as" to mean "because"; it is ambiguous. + Use "because" to refer to a reason. + Use "since" or "as" to refer to the passage of time. @@ -398,12 +404,13 @@ - slave - Do not use. It diminishes the horror of the dehumanizing practice of slavery. Use another term such as "worker", "child", "helper", "replica", or "secondary (server, node, process, or other noun)". + Do not use. + It diminishes the horror of the dehumanizing practice of slavery. + Use another term such as "worker", "child", "helper", "replica", or "secondary (server, node, process, or other noun)". @@ -587,11 +594,11 @@ a programming and technical sense, it also means "Run the sourcestand-alone - adj. Write hyphenated. Do not use "standalone". + adj. Hyphenate. + Do not use "standalone". Refers to something that is self-contained, or that does not require any other devices to function. - For example, a smartphone is a stand-alone device because it does not require a computer, printer, modem, or other device. A printer, on the other hand, is not a stand-alone device because it requires a computer to feed it data. @@ -617,7 +624,8 @@ a programming and technical sense, it also means "Run the sourcestart up - v. Do not use. Instead, use "activate" or "invoke". + v. Do not use. + Instead, use "start", "activate", or "invoke".