From 79c595c4cc8cd2b2b55fd95bf1ccd81c9eb51420 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 17 Jun 2021 14:20:08 +0100 Subject: [PATCH 01/27] Tech editor comments on Chapter 2 --- en-US/Conventions_for_Writers_and_Editors.ent | 1 + en-US/Grammar.xml | 42 ++++++++++++++++++- en-US/Objectives.xml | 1 + en-US/Punctuation.xml | 10 ++++- 4 files changed, 51 insertions(+), 3 deletions(-) diff --git a/en-US/Conventions_for_Writers_and_Editors.ent b/en-US/Conventions_for_Writers_and_Editors.ent index a631fd8..250840b 100644 --- a/en-US/Conventions_for_Writers_and_Editors.ent +++ b/en-US/Conventions_for_Writers_and_Editors.ent @@ -2,3 +2,4 @@ + \ No newline at end of file diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index ea6fc76..492bc3e 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -123,6 +123,8 @@ Relative pronoun when a person (or persons) is the subject. + + @@ -133,6 +135,7 @@ Relative pronoun when person is not the subject. + @@ -221,7 +224,7 @@ The GNOME developers to whom I owe my gratitude are... - + @@ -229,6 +232,8 @@ To help you choose between who and whom, substitute the person about whom you are speaking with either him or he. + + @@ -246,7 +251,7 @@ - +
Sentence Structure @@ -256,11 +261,14 @@ The following are things to consider when constructing sentences: + Sentence Length Try not to pack too much information into one sentence. Keep it short. For example, the following sentence is a good example of how not to write: + + @@ -271,6 +279,7 @@ Two or more complete ideas that are joined without punctuation create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: + @@ -284,18 +293,21 @@ Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; longer than a comma. + Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process will start, but it will produce an error." + Insert a subordinating conjunction, such as "although" or "because", which will form a compound sentence with a subordinate clause. For example, "Although the process will start, it will produce an error." + @@ -340,12 +352,14 @@ A sentence fragment is an incomplete sentence. For example, "We will release no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. + Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. + @@ -437,6 +451,7 @@ The individual member of the social community often receives his information via visual, symbolic channels. People read. (Translation by Richard Feynman.) + @@ -469,6 +484,7 @@ To update the address lists may be your primary concern. Your primary concern may be to update the address lists. + @@ -523,6 +539,7 @@ The verb "may" can be used to express possibility as well as to grant permissions. Similarly, "should" can be used to make recommendations as well as to express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + @@ -653,6 +670,20 @@ + @@ -661,6 +692,7 @@ Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Always write out in full. Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. See The IBM Style Guide for full details. + @@ -669,6 +701,7 @@ There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. + Hyphenate for Clarity @@ -735,6 +768,10 @@ Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." In most cases, use "you" when giving instructions, and "the user," "new users," and so on in more general explanations. Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. +
@@ -742,6 +779,7 @@ Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The screen will display...") does not read as well as the present tense ("The screen displays..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. + Use simple present tense as much as possible. It avoids problems with consequences and time related communications, and is the easiest tense for translation. diff --git a/en-US/Objectives.xml b/en-US/Objectives.xml index 09475af..fc7a45f 100644 --- a/en-US/Objectives.xml +++ b/en-US/Objectives.xml @@ -48,6 +48,7 @@ + diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 953e782..314be71 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -31,6 +31,7 @@ They had been writing code all night; this could explain their bloodshot eyes. + @@ -133,7 +134,7 @@ Type cd Documents/Books - + @@ -201,6 +202,7 @@ Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + @@ -382,6 +384,7 @@ Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is very closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. + @@ -400,6 +403,7 @@ Expressions beginning with i.e., e.g., that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. + @@ -425,15 +429,18 @@ Commas and periods go inside quotation marks. + Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. 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). + 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. +
@@ -441,6 +448,7 @@ Plural nouns not ending in s should add an 's (for example, the alumni's contribution). + Plural nouns ending in s only need an apostrophe (for example, the horses' food). From 5ed536f3e4ceae38bac5efed242da989585ccf63 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 18 Jun 2021 17:39:21 +0100 Subject: [PATCH 02/27] Edits to Chapter 2 --- en-US/Grammar.xml | 86 +++++++++++++++++++------------------------ en-US/Punctuation.xml | 32 +++++++++------- 2 files changed, 55 insertions(+), 63 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 492bc3e..02c0c09 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -121,10 +121,8 @@ Who - Relative pronoun when a person (or persons) is the subject. + Relative pronoun when persons are the subject. - - @@ -133,9 +131,8 @@ Whom - Relative pronoun when person is not the subject. + Relative pronoun when persons are not the subject. - @@ -222,28 +219,27 @@ - The GNOME developers to whom I owe my gratitude are... + The GNOME developers to whom they owe gratitude are... - + - To help you choose between who and whom, substitute the person about whom you are speaking with either him or he. + To help you choose between who and whom, substitute the person about whom you are speaking with he, she, him, or her. - - + - If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" + If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" - If the restatement contains the word he, she, they, I, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" + If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" @@ -251,7 +247,7 @@ - +
Sentence Structure @@ -259,16 +255,14 @@ A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). - The following are things to consider when constructing sentences: + Consider the following points when constructing sentences: - + Sentence Length - Try not to pack too much information into one sentence. Keep it short. For example, the following sentence is a good example of how not to write: + Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: - - @@ -277,9 +271,8 @@ Run-on Sentences - Two or more complete ideas that are joined without punctuation create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: + Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: - @@ -291,23 +284,20 @@ - Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; longer than a comma. + Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. - - Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process will start, but it will produce an error." + Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." - - Insert a subordinating conjunction, such as "although" or "because", which will form a compound sentence with a subordinate clause. For example, "Although the process will start, it will produce an error." + Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error." - @@ -350,16 +340,14 @@ Sentence Fragments - A sentence fragment is an incomplete sentence. For example, "We will release no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. + A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. - Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. - @@ -449,11 +437,15 @@
- The individual member of the social community often receives his information via visual, symbolic channels. + The individual member of the social community often receives information via visual, symbolic channels. People read. (Translation by Richard Feynman.) - + + Perform the installation of the product. + Install the product. + + / @@ -482,9 +474,8 @@ - To update the address lists may be your primary concern. - Your primary concern may be to update the address lists. - + To update the address lists might be your primary concern. + Your primary concern might be to update the address lists. @@ -537,9 +528,9 @@ Homographic Verbs - The verb "may" can be used to express possibility as well as to grant permissions. Similarly, "should" can be used to make recommendations as well as to express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. - +
@@ -671,6 +662,8 @@
Hyphenation - There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. + There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. - + Hyphenate for Clarity @@ -766,22 +758,18 @@ Use the utility to run activities, and then when you are done, save your setting
Gender References - Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." In most cases, use "you" when giving instructions, and "the user," "new users," and so on in more general explanations. Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. - - +
Tense - Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The screen will display...") does not read as well as the present tense ("The screen displays..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. + Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. - + - Use simple present tense as much as possible. It avoids problems with consequences and time related communications, and is the easiest tense for translation. + Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. Report an issue diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 314be71..661fd30 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -23,15 +23,14 @@ - They had been writing code all night: this could explain their bloodshot eyes. + They had been writing code all night: this factor could explain their bloodshot eyes. - They had been writing code all night; this could explain their bloodshot eyes. + They had been writing code all night; this factor could explain their bloodshot eyes. - @@ -126,15 +125,15 @@ - Open a terminal + Open a terminal. - Type cd Documents/Books + Type cd Documents/Books. - + @@ -200,9 +199,9 @@ - Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + Use a semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. - + @@ -382,9 +381,9 @@
Parentheses - Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is very closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. + Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. - + @@ -401,9 +400,9 @@ - Expressions beginning with i.e., e.g., that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. + Expressions beginning with for example, that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. - + @@ -413,7 +412,7 @@ - Classic works of literature (e.g., Dickens, Shakespeare, the Brontes) lined the shelves. + Classic works of literature (such as Dickens, Shakespeare, the Brontes) lined the shelves. @@ -445,10 +444,15 @@
Apostrophes + + Do not use an apostrophe to denote a plural. + + + To denote a possessive, use an apostrophe as follows: + Plural nouns not ending in s should add an 's (for example, the alumni's contribution). - Plural nouns ending in s only need an apostrophe (for example, the horses' food). From e0d113f2aff9cdad84910226c1b92e8e9ba7787f Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 21 Jun 2021 18:03:17 +0100 Subject: [PATCH 03/27] Added sections to Grammar.xml. --- en-US/Grammar.xml | 237 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 220 insertions(+), 17 deletions(-) diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 02c0c09..3ba0aef 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -247,7 +247,7 @@ - +
Sentence Structure @@ -414,6 +414,38 @@ + + + "That" in Clauses + + Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, + + + +
+ + + + + + + Example + Improvement + + + + + + + Verify your directory service is working. + Verify that your directory service is working. + + + + + + +
Verbosity @@ -485,10 +517,50 @@ +
Avoiding Ambiguities + + + + Dates + + + Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. + + + + + + + + + + Example + Improvement + + + + + + + The product was manufactured on 4/1/21. + The product was manufactured on 1 April 2021. + + + + + + + +
+ + + + + Capitalizing Proper Nouns @@ -611,6 +683,43 @@ + + Verb phrases + + + When you have more than one infinitive verb within a sentence, be clear what each verb refers to. + + + + + + + + + + Example + Improvement + + + + + + + Use the utility to run activities and save your settings. + Either: Use the utility to run activities and to save your settings (if the utility does both functions); or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + + + + + + +
+ + + + + Invisible Plurals @@ -644,8 +753,44 @@ + + + Verb phrases + + + Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. + + + + + + + + + + Example + Improvement + + + + + + + If the completed field has text, it does not change. + If the completed field has text, that text does not change. + + + + + + + +
+ + + Synonymity @@ -659,24 +804,82 @@ + + Use of "using" + + + Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. + + + + + + + + + + Example + Improvement + + + + + + + Create the resource using all relevant options. + Create the resource by using all relevant options. + + + + + + + +
+ + + + + + Verb phrases + + + Ensure that a verb phrase at the start of a sentence modifies the correct word. + + + + + + + + + + Example + Improvement + + + + + + + Having configured your environment, the product is ready to be used. (The product does not configure the environment.) + After you configure your environment, you can use the product. + + + + + + + +
+ + + + - + +
From a7a60e8c77b94272fd6e6bdc4c417a3c117b3f9d Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 22 Jun 2021 17:57:41 +0100 Subject: [PATCH 04/27] Added and updated various style guide sections. --- en-US/A.xml | 5 +- en-US/Book_Info.xml | 1 + en-US/C.xml | 11 +- en-US/Grammar.xml | 374 ++------------------------------------------ en-US/P.xml | 5 +- en-US/Slang.xml | 373 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 390 insertions(+), 379 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 26b30c4..eaad450 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -37,13 +37,14 @@ + - a.m. + AM am - Correct. Use the lowercase form and include the periods, and use a preceding space. + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". See also . diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index fa5d3b2..cbd073a 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -5,6 +5,7 @@ ]> Conventions for Writers and Editors + The Red Hat Style Guide 4.2 diff --git a/en-US/C.xml b/en-US/C.xml index 46ef295..6afef28 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -409,16 +409,7 @@ - - - contractions - - - Do not use. Contractions are a mark of informal writing, and should be avoided when writing policy manuals or other more formal types of manuals. They also cause problems for translation. - - - - + control character diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 3ba0aef..1a4c15f 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -517,376 +517,20 @@ - - -
- Avoiding Ambiguities - - - - - Dates - - - Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. - - - - - - - - - - Example - Improvement - - - - - - - The product was manufactured on 4/1/21. - The product was manufactured on 1 April 2021. - - - - - - - -
- - - - - - - Capitalizing Proper Nouns - - - In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. - - - - - - - - - Example - Improvement - - - - - - - This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. - This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. - - - - - - - -
- - - - - - Homographic Verbs - - - The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. - - - - - - - - - - Example - Improvement - - - - - - - The next() method should return null to indicate the end of results. - The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. - - - - It may be held in memory. - It can be held in memory. OR It might be held in memory. - - - - - - - -
- - - - - - Homonymity - - - When a single term has multiple meanings, be explicit in order to differentiate between them. - - - - - - - - - Example - Improvement - - - - - - - Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. - Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. - - - - To create another administrator, click New on the File menu. - To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. - - - - - - - -
- - - See also . - - - - - - - - - Verb phrases - - - When you have more than one infinitive verb within a sentence, be clear what each verb refers to. - - - - - - - - - - Example - Improvement - - - - - - - Use the utility to run activities and save your settings. - Either: Use the utility to run activities and to save your settings (if the utility does both functions); or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). - - - - - - - -
+ - - - - - - Invisible Plurals - - - Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. - - - - - - - - - Example - Improvement - - - - - - - Once the file retrieval has been completed, you are ready to restart your system. - After the files have been retrieved, you can restart your system. - - - - - - - -
- - - - - - Verb phrases - - - Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. - - - - - - - - - - Example - Improvement - - - - - - - If the completed field has text, it does not change. - If the completed field has text, that text does not change. - - - - - - - -
- - - - - - Synonymity - - - Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. - - - For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. - - - - - - - Use of "using" - - - Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. - - - - - - - - - - Example - Improvement - - - - - - - Create the resource using all relevant options. - Create the resource by using all relevant options. - - - - - - - -
- - - - - - Verb phrases - - - Ensure that a verb phrase at the start of a sentence modifies the correct word. - - - - - - - - - - Example - Improvement - - - - - - - Having configured your environment, the product is ready to be used. (The product does not configure the environment.) - After you configure your environment, you can use the product. - - - - - - - -
- - - - - - - - - -
+
Contractions and Abbreviations - Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Always write out in full. Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. + Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They also cause problems for translation. + + + + Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on.
diff --git a/en-US/P.xml b/en-US/P.xml index 02ec0ac..2ea1b5e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -110,12 +110,13 @@ + - p.m. + PM - Correct. Use the lowercase form and include the periods, and use a preceding space. + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". See also . diff --git a/en-US/Slang.xml b/en-US/Slang.xml index f4ec60b..2c4b6f5 100644 --- a/en-US/Slang.xml +++ b/en-US/Slang.xml @@ -4,6 +4,7 @@ %BOOK_ENTITIES; ]> + Avoiding Jargon, Slang, Metaphors, and Misleading Language Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. @@ -873,4 +874,376 @@ + +
+ Inclusive Language + + Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. + + + Terms that reinforce cultural, racial, or other types of bias should be replaced with an alternative. + + + Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + + + Other considerations apply for inclusive writing, including to avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + + + Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. + +
+ + +
+ Avoiding Ambiguities + + + + Capitalizing Proper Nouns + + + In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. + + + + + + + + + Example + Improvement + + + + + + + This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. + This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. + + + + + + + +
+ + + + + + Homographic Verbs + + + The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + + + + + + + + + + Example + Improvement + + + + + + + The next() method should return null to indicate the end of results. + The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. + + + + It may be held in memory. + It can be held in memory. OR It might be held in memory. + + + + + + + +
+ + + + + + Homonymity + + + When a single term has multiple meanings, be explicit in order to differentiate between them. + + + + + + + + + Example + Improvement + + + + + + + Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. + Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. + + + + To create another administrator, click New on the File menu. + To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. + + + + + + + +
+ + + See also . + + + + + + + + + Verb phrases + + + When you have more than one infinitive verb within a sentence, be clear what each verb refers to. + + + + + + + + + + Example + Improvement + + + + + + + Use the utility to run activities and save your settings. + Either: Use the utility to run activities and to save your settings (if the utility does both functions); or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + + + + + + +
+ + + + + + + Invisible Plurals + + + Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. + + + + + + + + + Example + Improvement + + + + + + + Once the file retrieval has been completed, you are ready to restart your system. + After the files have been retrieved, you can restart your system. + + + + + + + +
+ + + + + + Verb phrases + + + Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. + + + + + + + + + + Example + Improvement + + + + + + + If the completed field has text, it does not change. + If the completed field has text, that text does not change. + + + + + + + +
+ + + + + + Synonymity + + + Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. + + + For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. + + + + + + + Use of "using" + + + Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. + + + + + + + + + + Example + Improvement + + + + + + + Create the resource using all relevant options. + Create the resource by using all relevant options. + + + + + + + +
+ + + + + + Verb phrases + + + Ensure that a verb phrase at the start of a sentence modifies the correct word. + + + + + + + + + + Example + Improvement + + + + + + + Having configured your environment, the product is ready to be used. (The product does not configure the environment.) + After you configure your environment, you can use the product. + + + + + + + +
+ + + + + + + +
+ +
+ Dates and Times + + + Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. + + + + Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". + + + + Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. + + + + For times of day, use uppercase without periods, such as “11 AM”. Use a nonbreaking space between the numeral and “AM” or “PM”. + + +
+ From 380404b0991a4c9740fb8ef7e5581ad10b2ba297 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 25 Jun 2021 16:40:32 +0100 Subject: [PATCH 05/27] Updates to Style Guide --- en-US/Book_Design.xml | 14 ++--- en-US/Design.xml | 137 ++++++++++++++++++++++++------------------ en-US/Slang.xml | 8 ++- 3 files changed, 91 insertions(+), 68 deletions(-) diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index 1bfbc04..d182a6d 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -6,7 +6,7 @@
Overall Book Design - This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and may not suit content produced by other groups. + This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. This section covers the following topics: @@ -51,7 +51,7 @@ The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 6 for all architectures". + The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures".
@@ -87,7 +87,7 @@ - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This provides a basis for administrators and developers to write custom scripts and integrate Red Hat Satellite with third-party applications." + Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." @@ -99,10 +99,10 @@ Drawing these basics together might produce the following example abstract: - "The Red Hat Satellite 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 provides a basis for administrators and developers to write custom scripts and integrate Red Hat Satellite with third-party applications." + "The Red Hat Satellite 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." - Update or modify each component according to the type of book you are writing. + Update or modify each component according to the type of book that you are writing. @@ -116,12 +116,12 @@
Unused Heading Titles - This section lists various heading titles that have been used in Red Hat technical documentation, but should be avoided except in specific circumstances. + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. Overview - Do not use "overview" as a title. No justification was found for using this as a title; anywhere that it might be considered is already covered by either better or more common titles. + Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. diff --git a/en-US/Design.xml b/en-US/Design.xml index 6620120..fafeb2b 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -17,9 +17,10 @@ The standard for all Red Hat technical documentation is title case for all headings and titles. Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. - The currently accepted reference for determining title case is https://titlecase.com/titlecase. + The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - + + Use sentence case for table column headers. These are not classified as titles. @@ -44,8 +45,9 @@ Avoid Imperative Form - Use the gerund form (noun form of verb) for titles, not the imperative form. + Use the gerund form (noun form of verb) for titles, not the imperative form. For example, "Testing the Product", not "Test the Product". + See The IBM Style Guide for more information. @@ -62,7 +64,7 @@ When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. - Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and even cause failed builds. + Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. @@ -70,8 +72,9 @@
Documenting Fonts - The preferred way to refer to each type of postscript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. + The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. +
@@ -105,7 +108,7 @@ - If you cannot easily reproduce the symbol, include a screen capture and/or a succinct description of the object type. + If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. Use this approach for icons, especially when they have no tooltip or other help text. Preferred Style for Documenting Icons @@ -118,7 +121,7 @@ - See the Computer Interfaces chapter in The IBM Style Guide for more information. + See the UI elements chapter in The IBM Style Guide for more information.
Navigating Through Multiple GUI Options @@ -129,15 +132,23 @@ From example, "From the OpenShift web console, navigate to Monitoring → Alerting." + + + +
Starting Applications from the Red Hat Enterprise Linux Desktop - Red Hat Enterprise Linux 7 introduces a new approach to starting applications from the desktop. In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes the customer is using GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. + Red Hat Enterprise Linux 7 introduces a new approach to starting applications from the desktop. + + In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. - The preferred approach is to use the Super key to enter the Activities Overview, enter the name of the required application, and to press Enter. The Super key appears in a variety of guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: + The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. + + The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: Preferred Approach to Starting Applications from the Desktop @@ -151,7 +162,7 @@
Documenting Command Terminology and Syntax - Sufficient variation exists in the terminology used to describe commands, options, arguments, and so on that only general advice is provided here. + Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here. When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses. @@ -169,7 +180,7 @@ - See info bash and the Computer Interfaces chapter of The IBM Style Guide for further guidance. + See info bash and The IBM Style Guide for further guidance. The following examples are intended to highlight correct usage. @@ -184,14 +195,14 @@ - In the entire command consists of the following components: + In , the entire command consists of the following components: The prompt ($) - Indicates that a normal user can run the command, as compared to the root user, indicated by the number sign (#). + Indicates that a normal user can run the command, as compared to the root user, which would be indicated by the number sign (#). @@ -202,7 +213,7 @@ The actual command to run, without any optional or replaceable values. - This must be typed as is. + It must be typed as-is. @@ -224,7 +235,7 @@ The optional directory into which the repository will be cloned. - This must be replaced with a valid value, or omitted. + It must be replaced with a valid value, or be omitted. @@ -237,9 +248,10 @@ $ scp filename [username@]hostname:/directory + - In the entire command consists of the following components: + In , the entire command consists of the following components: @@ -256,7 +268,7 @@ The command (scp) - The actual command to run, without any optional or replaceable values. This must be typed as is. + The actual command to run, without any optional or replaceable values. It must be typed as-is. @@ -266,7 +278,7 @@ Source options (filename) - The file name to copy. This must be replaced with a valid value. + The file name to copy. It must be replaced with a valid value. @@ -286,24 +298,25 @@ - Avoid using the and options on most commands, especially when logged in as the root user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that may not suit your system. Refer to the following examples: + + Generally, avoid using the and options on most commands, especially when logged in as the root 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: [root@serverc pam.d]# rm -f system-auth password-auth [root@serverc ~]# yum install -y new-package - In the examples shown above, omit the and options, respectively. + In these examples, omit the and options, respectively. - In some cases, such as in Ansible Playbooks or other automation scripts, it may be necessary to use these options. + In some cases, such as in Ansible Playbooks or other automation scripts, it might be necessary to use these options.
Documenting Multiple or Long Commands - Sometimes you need to demonstrate how to use very long commands that extend over two or more lines, or include several commands in a single example. If the commands are relatively short and straightforward, include the commands on consecutive lines: + 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, include the commands on consecutive lines: Documenting Multiple Commands @@ -337,7 +350,7 @@ $ vi myFile.txt You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. - You can use this option for either of the two designs mentioned above. + You can use this option for either of these two designs. @@ -356,7 +369,7 @@ $ vi myFile.txt Wrapping Long Commands Without Continuation Characters - This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help clarify long commands. + This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. # cd /var/lib/katello @@ -371,7 +384,7 @@ $ vi myFile.txt
Referring to Replaceable Paths - To refer to a path that users need to replace with something specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. + To refer to a path that users need to replace with something that is specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. Use a leading slash if the absolute path is required. Referring to Replaceable Paths on Linux Systems @@ -380,7 +393,7 @@ $ vi myFile.txt - Remember to use the syntax appropriate to the system that you are documenting or describing. + Remember to use the appropriate syntax for the system that you are documenting or describing. Referring to Replaceable Paths on Microsoft Windows Systems @@ -413,14 +426,14 @@ $ vi myFile.txt Classroom Exceptions - Although security is important, it is more important to not have unnecessary classroom security distract from the immediate topic being taught. + Although security is important, it is more important that classroom security does not unnecessarily distract from the immediate topic that is being taught.
General Recommendations These are recommendations, not rules. - As with most things, consistency is important. + As in most matters, consistency is important. Do not swap between different approaches without reason. Choose which approach works best for your situation and use it consistently. @@ -428,23 +441,23 @@ $ vi myFile.txt - In all cases, use the minimum privilege level required to achieve the task. + In all cases, use the minimum required privilege level to achieve the task. - In exercises, use sudo and sudo -i and set this up to work throughout all relevant systems in the classroom. + In exercises, use sudo and sudo -i and set it up to work throughout all relevant systems in the classroom. Do not use su - without good cause. - When there is a scattered minority of privileged commands in a mostly unprivileged exercise, use sudo on a per-command basis. + When a scattered minority of privileged commands occur in a mostly unprivileged exercise, use sudo on a per-command basis. - When the exercise is majority privileged, or has a significant number of privileged commands, use sudo -i either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. + When the exercise is majority privileged, or has many privileged commands, use sudo -i, either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. @@ -457,8 +470,8 @@ $ vi myFile.txt
Exceptions - Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers and so on. - For these courses, use the required variation for the topic being taught. + Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers, and so on. + For these courses, use the required variation for the topic that is being taught.
Ansible Courses @@ -487,16 +500,16 @@ $ vi myFile.txt
Describing How to View and Edit Files - To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a desired result. + To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. - For example, do not refer to cat or vi if you need to tell readers to "View the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text that needs to be changed. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. + For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. - If the file that you need to edit is empty or does not exist, do not use <code> tags to highlight any content that needs to be added. + If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. - You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on, but a simple example is shown below. This example creates the my-script file in the current directory, using the example content. + You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. my-script @@ -505,14 +518,14 @@ $ vi myFile.txt > # Start adding variables after this line > EOF]]> - In some cases it is necessary to indicate which tool to use to view a file. This is especially true of log files and other very long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl. + In some cases, it is necessary to indicate which tool to use to view a file, especially for log files and other long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl.
Using Host and User Names Correctly - Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following. + Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. @@ -523,7 +536,7 @@ $ vi myFile.txt - Use RFC 2606 to determine suitable domain names. For documentation and example purposes, this is typically example.com, example.net, example.org, and example.edu. + Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. @@ -538,7 +551,7 @@ $ vi myFile.txt As much as possible, use user, username, root, admin, or similar names to identify classes of users. - Use these generic names when you refer to users outside of a case study. This helps students identify which part of a command can and should be replaced by establishing a consistent format for names of users and system items. For example: + Use these generic names when you refer to users outside a case study. It helps students to identify which part of a command to replace, by establishing a consistent format for names of users and system items. For example: [root@fedora ~]# setfacl -m u:user1:rw /project/file1 @@ -583,12 +596,12 @@ $ vi myFile.txt - For example, you are the system administrator at Global Banking and you have been asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs to be able to read from the accounting directory, Sunni is the lead accountant and needs both read and write access. + For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. Choosing a Realistic Name - Consider the following when choosing a realistic name: + Consider the following points when choosing a realistic name: Examples taken from The IBM Style Guide and the Google Developer Documentation Style Guide. @@ -622,6 +635,7 @@ $ vi myFile.txt You can use any of the following name generators to create realistic names for users: + @@ -666,7 +680,7 @@ $ vi myFile.txt
Documenting Currencies - Use local currency symbols wherever possible. If symbol clash occurs (USD vs AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. + Use local currency symbols wherever possible. If symbol clash occurs (USD versus AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. @@ -696,7 +710,7 @@ $ vi myFile.txt - Bear pronunciation in mind when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). + Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see The IBM Style Guide or another suitable reference if you are unsure. @@ -709,14 +723,14 @@ $ vi myFile.txt - Bear pronunciation in mind when using articles. See for more information. + Consider pronunciation when using articles. See for more information.
Using Company, Product, and Brand Names Correctly - A number of restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. + Various restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. @@ -745,7 +759,7 @@ $ vi myFile.txt - Use non-breaking spaces to avoid breaking the company name over multiple lines. This also applies to product names and their versions. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. + Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. @@ -761,11 +775,12 @@ $ vi myFile.txt Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. + - The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;7.0 + The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 @@ -775,7 +790,7 @@ $ vi myFile.txt - Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack" nor between "OpenStack" and "Platform." + Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." @@ -791,7 +806,7 @@ $ vi myFile.txt - In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on may not be part of the product name, in which case an article is acceptable, if not necessary. + In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. @@ -808,7 +823,7 @@ $ vi myFile.txt - Red Hat Enterprise Linux 7 + Red Hat Enterprise Linux 8 @@ -823,7 +838,7 @@ $ vi myFile.txt - When writing about a product line, product release, or product family, use major version numbers. This includes all the releases (past, present, and future) of that major version. + When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version. Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example: @@ -852,7 +867,7 @@ $ vi myFile.txt - This rule only applies to Red Hat products. Refer to other companies' products and use their version numbers as they use them. + This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. @@ -864,7 +879,7 @@ $ vi myFile.txt To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning 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 in mind 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 in mind these considerations if using admonitions: @@ -886,7 +901,7 @@ $ vi myFile.txt - Use an Important admonition to show the user a piece of information that should not be overlooked. While this information may not change anything the user is doing, it should show the user that this piece of information could be vital. + Use an Important 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. @@ -950,6 +965,7 @@ $ vi myFile.txt <citetitle>Book Title</citetitle> by <author><firstname>First name</firstname><surname>Surname</surname></author>; Publisher. + For example, Maximum RPM by @@ -957,7 +973,7 @@ $ vi myFile.txt Bailey - ; Red Hat Press. + ; Red Hat Press. Referencing Other Internet Sites @@ -975,13 +991,13 @@ $ vi myFile.txt - Short URLs, such as http://partner.redhat.com are OK to use in body text at your discretion. + Short URLs, such as http://partner.redhat.com, are OK to use in body text at your discretion. - If the URL is excessively long, or complex, create a link using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species + If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species http://world-database-of-everything.com/en/classifcation_of_species/mammals.html page for more information. @@ -998,6 +1014,7 @@ $ vi myFile.txt DocBook provides the <blockquote> and <attribution> tags for this purpose, but how they should be rendered is currently being discussed. For example: +
Thomas Jefferson Why use two words when one will do? diff --git a/en-US/Slang.xml b/en-US/Slang.xml index 2c4b6f5..c7f55ff 100644 --- a/en-US/Slang.xml +++ b/en-US/Slang.xml @@ -893,7 +893,13 @@ Dates and Times (new) --> Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. - Other considerations apply for inclusive writing, including to avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + + + Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + + + Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. From 137ae939f59ca564eba0b134b69592afd7386c2e Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 25 Jun 2021 17:22:03 +0100 Subject: [PATCH 06/27] Renamed Slang.xml to Language.xml and expanded its scope. --- en-US/{Slang.xml => Language.xml} | 64 +++++++++++++++++++------------ 1 file changed, 39 insertions(+), 25 deletions(-) rename en-US/{Slang.xml => Language.xml} (88%) diff --git a/en-US/Slang.xml b/en-US/Language.xml similarity index 88% rename from en-US/Slang.xml rename to en-US/Language.xml index c7f55ff..79d181c 100644 --- a/en-US/Slang.xml +++ b/en-US/Language.xml @@ -5,13 +5,20 @@ ]> - Avoiding Jargon, Slang, Metaphors, and Misleading Language + Language + - Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + + If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. + + + Red Hat is committed to eliminating use of language that might exclude or offend certain groups of people. This chapter describes some considerations for use of inclusive language. - If you find slang terms or other difficult-to-understand passages in our documentation, use this page to search for alternatives. + Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. +
Avoiding Misleading or Confusing Language @@ -61,10 +68,10 @@ - anything you/they like + anything you like, anything they like - This is probably readily understood but should not appear in Red Hat documentation. + This phrase is probably readily understood but should not appear in Red Hat documentation. @@ -72,7 +79,7 @@ "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." - Rephrase to something more suitable, such as "...to register any other kind of plug-in." + Rephrase to something more suitable, such as "... to register any other kind of plug-in." @@ -188,7 +195,7 @@ core competency - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," etc. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." @@ -238,7 +245,7 @@ enterprise-ready - Although we used to use this term to emphasize our products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. @@ -258,7 +265,7 @@ fib - A fib is a "small lie," also known as a "white lie." This appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." + A fib is a "small lie," also known as a "white lie." This sentence appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." @@ -288,8 +295,9 @@ frown upon - "To frown upon" means to hold in low regard, not to approve of, etc. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + "To frown upon" means to hold in low regard, not to approve of, and so on. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + @@ -303,7 +311,7 @@ - In Directory Server, if you do a fuzzy search for "Smith" you will probably also get "Smyth," because it sounds the same. + In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. @@ -336,7 +344,7 @@ happy path - Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is very localized slang and could easily be misunderstood. It could also produce problems for translation. + Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is localized slang and could easily be misunderstood. It could also produce problems for translation. @@ -353,7 +361,7 @@ - have a crack at/jump right in + have a crack at, jump right in Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. @@ -464,7 +472,7 @@ Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. - Typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." + It is typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." @@ -504,7 +512,7 @@ mission-critical - Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Make sure you have the applications you need to help your customers." vs. "Make sure you have the mission-critical applications your customers demand." + Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Ensure that you have the applications that you need to help your customers." versus "Ensure that you have the mission-critical applications that your customers demand." @@ -534,7 +542,7 @@ over the wire - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent/transmitted in plain text" is fine. + Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. @@ -544,7 +552,7 @@ pain in the backside - Nobody should ever write this or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. + Nobody should ever write this expression or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. @@ -642,7 +650,7 @@ root your server in the /serverRoot directory - This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. + This expression is inelegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. @@ -652,7 +660,7 @@ shoot yourself in the foot - To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Remove the sentence - it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") @@ -662,7 +670,7 @@ shy of - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang. + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. @@ -672,8 +680,9 @@ silo, siloed - Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," "segregated," or something similar. + Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," or something similar. + @@ -783,7 +792,7 @@ very - Use with caution. For example, there is little value in saying "very cost-effective" vs. "cost-effective." + Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." @@ -806,7 +815,7 @@
Neologisms (Invented Words) - The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. + The English language is full of these words. Some of them are useful; some of them are less so; others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and is generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. Examples @@ -817,7 +826,7 @@ - This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." @@ -832,7 +841,7 @@
Anthropomorphism - Anthropomorphism is applying human qualities to non-human things or animals. Avoid this in your writing. + Anthropomorphism is applying human qualities to non-human things or animals. Avoid it in your writing. Examples @@ -1250,6 +1259,11 @@ Dates and Times (new) --> For times of day, use uppercase without periods, such as “11 AM”. Use a nonbreaking space between the numeral and “AM” or “PM”. + + Use "noon" or "12 noon" instead of "12 PM". + Use "midnight" or "12 midnight" instead of "12 AM". + +
From 51113990ba1af9f300e679e394677e6720510a52 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 28 Jun 2021 17:38:47 +0100 Subject: [PATCH 07/27] Updated Chapters 5-7. --- en-US/Cross_references.xml | 15 +++++---- en-US/Resources.xml | 12 ++++--- en-US/Translation.xml | 66 ++++++++++++++++++++------------------ 3 files changed, 51 insertions(+), 42 deletions(-) diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index c413ea7..21f86da 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -6,10 +6,11 @@ Using Cross-references Effectively - This section contains suggestions on how to use cross-references in the most effective way. That is, so that it works for the reader, rather than the author. In DocBook XML, cross-references are formatted according to the style sheets; at this point no references are available that describe how they should be formatted in other media. Formatting is not described in this section. + This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. In DocBook XML, cross-references are formatted according to the style sheets; at this point no references are available that describe how they should be formatted in other media. Formatting is not described in this section. + - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book; on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. It is still the author who must do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link could indicate that the author is writing for their own ease, and not for the good of the reader. + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader.
The Additional Information Test @@ -17,7 +18,7 @@ Is the cross-reference pointing to vital information or additional information? - A cross-reference should always point to additional information, not core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure provide the link to the appendix. + A cross-reference should always point to additional information, not to core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure, provide a link to the appendix.
@@ -27,11 +28,11 @@ Does the paragraph or section consist largely of links? - In running text, there should not be more than a couple of links per paragraph. There should not be links in every paragraph, and there certainly must not be links in titles, subheadings, figure or table captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs a lot of additional information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section indicating where more information is available. + In running text, each paragraph should contain no more than a couple of links. Links should not occur in every paragraph, and they must not occur in titles, subheadings, figure captions, or table captions. Cross-references interrupt the flow of thought, and can actively interfere with the absorption of information. If the reader needs much extra information, rethink the structure of the section, and enrich the quality of the information. Do not let the cross-references overpower the message. A solution is to add a sentence to the end of the section to indicate where to find more information. - Lists can be an exception, but try to provide the reader with a descriptive phrase or sentence for each cross-referenced item, as well as a lead-in and concluding sentence for the paragraph that contains the list. + Lists can be an exception, but try to provide the reader with a descriptive phrase or sentence for each cross-referenced item, as well as a lead-in and a concluding sentence for the paragraph that contains the list. @@ -40,10 +41,10 @@
The Repeatability Test - Does the information have to be repeated? + Must the information be repeated? - This is a hard one, and one that many authors abhor. Often the answer is yes. If the information is vital, and needs to appear in multiple places, it just has to be done. It's not a crime. In some circumstances, like online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it may be the only chance the reader has to find critical information quickly. Any vital information, that is not more than a couple of paragraphs, (or half a page, or 5 rows of a table) can be repeated rather than 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. 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. Cross-referencing is a good servant but a poor master. Content still rules! diff --git a/en-US/Resources.xml b/en-US/Resources.xml index a02719b..50986ce 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -8,13 +8,15 @@ This section lists some books and websites for you to consult on your quest to create the perfect document. + - The guides that you refer to first are generally dictated by the type of material you are writing. It is important to establish this first because the guidelines in the following references sometimes contradict each other. This does not mean they are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: + The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: - Technical content: software manuals and documentation, user guides + Technical content: software manuals and documentation, user guides, training courses + @@ -50,8 +52,9 @@ - IBM Style Guide, Sixth Edition. IBM Corp, 2004. + IBM Style Guide. IBM Corporation, latest version. + @@ -104,10 +107,11 @@
Secondary References - The following references may provide guidance when the primary references cannot provide a suitable solution. + The following references might provide guidance when the primary references cannot provide a suitable solution. + Microsoft Manual of Style for Technical Publications, Third Edition. Redmond, WA: Microsoft Press, 2004. diff --git a/en-US/Translation.xml b/en-US/Translation.xml index c0cfaa1..dc40326 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -6,19 +6,19 @@ Writing Clearly and Succinctly - This chapter provides guidelines, tips, and techniques to help make your writing easier to read and understand, and also to translate. + This chapter provides guidelines, tips, and techniques to help to make your writing easier to read and understand, and also to translate.
Sentence Structure - This section helps to describe how to construct your content for clarity and readability. + This section describes how to construct your content for clarity and readability. A full discussion of this topic is beyond the scope of this guide.
Using and Formatting Lists - 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 sentence stem) as individual sentences for translation. If these are not complete sentences, they can be difficult to translate. + 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 sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. The following general guidelines apply to lists: @@ -28,8 +28,8 @@ Itemized lists - These 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 to not perform steps but to watch the instructor instead. + 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. Titles are optional. @@ -38,9 +38,9 @@ Ordered lists - These appear as a numbered list. + They appear as a numbered list. 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 required to prepare for an installation, or list a sequence of events that occurs. + 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. @@ -49,12 +49,12 @@ Variable lists - These appear as a list of terms followed by definitions. + They 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.) A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. - Tables are best reserved for information that relies upon, or benefits greatly from, a grid layout. + Tables are best reserved for information that relies on, or benefits greatly from, a grid layout. @@ -62,8 +62,8 @@ Procedures - These appear as a list of numbered steps. - Procedures always include a title, and are used to list the steps required to achieve a task. + They appear as a list of numbered steps. + Procedures always include a title, and are used to list the required steps to achieve a task. @@ -71,23 +71,25 @@ You can nest lists, but try to keep the number of levels to two or fewer. To nest procedures in DocBook, use <substep> elements. +
Formatting Lists for Readability It is important to provide sufficient 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 applies to lists. + The same consideration applies to lists. If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. DocBook uses the spacing attribute by default. + - Use a list with normal spacing if any list item contains the following: + Use a list with normal spacing if any list item contains the following components: Nested lists. - Note that nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. @@ -106,7 +108,7 @@ - The use of all but very simple graphics in lists is strongly discouraged. + The use of all but the simplest graphics in lists is strongly discouraged. @@ -130,7 +132,7 @@ - Before you start the installation, make sure you have + Before you start the installation, ensure that you have @@ -157,7 +159,7 @@ - Ensure you have enough free storage on your system. + Ensure that you have enough free storage on your system. @@ -184,7 +186,7 @@
Noun Stacking - Modifier strings (modifier + noun + noun sentence format), over-modified nouns (or noun stacks), are especially difficult to translate, particularly when several different combinations could make sense. + Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. @@ -207,8 +209,8 @@ - Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press ENTER. - For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then press ENTER. + Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press Enter. + For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. @@ -223,10 +225,10 @@
Grammatical Genders - When using ambiguous pronouns such as "they" or "it" it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and may require other grammatical adjustments. + When using ambiguous pronouns such as "they" or "it", it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and might require other grammatical adjustments. - Further, an initialism such as RPM might refer to the package or the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package. + Further, an initialism such as RPM might refer to the package or to the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package.
@@ -243,13 +245,14 @@ - Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. - Set the XYZ parameter to 1 in the configuration /etc/config.conf file. This parameter configures how the Gateway application handles incoming network traffic. + Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. + Set the XYZ parameter to 1 in the /etc/config.conf configuration file. This parameter configures how the Gateway application handles incoming network traffic. The RPM is useful. The RPM package is useful. OR The RPM Package Manager is useful. + @@ -263,13 +266,13 @@
DocBook Elements - Use the correct DocBook elements to help translators understand the meaning of and to identify translatable and non-translatable terms. + Use the correct DocBook elements to help translators to understand the meaning of, and to identify, translatable and non-translatable terms. Tagged Terms in Sentences - Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators have to fill in the blanks or tag terms themselves. + Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators must complete the blanks or tag terms themselves. @@ -318,10 +321,10 @@
Code Blocks - Avoid including commentary within the same box as command input or output. These might be confused with part of the output, and during translation might be accidentally overlooked and left in English. + Avoid including commentary within the same box as command input or output. These comments might be confused with part of the output, and during translation might be accidentally overlooked and left in English. - For example, consider the word "Usage" in the following: + For example, consider the word "Usage" in the following block: Usage: rhevm-iso-uploader [options] list @@ -336,11 +339,12 @@ . Entities are called by reference, and take the form &name; (both the ampersand and the semicolon are required). + - Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators need to compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not translated at all. + Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities required to actually build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand, but only the following are required for a standard book: + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: @@ -370,7 +374,7 @@ - Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The St. James Bible". To learn more about entities, see the relevant chapter in + Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in
From 523923b18cbf397b2acadd47e7354fd600d16df7 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 29 Jun 2021 17:21:40 +0100 Subject: [PATCH 08/27] Updated A-E term entries --- en-US/0-9.xml | 5 ++-- en-US/A.xml | 45 ++++++++++++++++++++-------------- en-US/B.xml | 53 ++++++++++++++++++++------------------- en-US/C.xml | 64 +++++++++++++++++++++++++----------------------- en-US/D.xml | 23 +++++++++-------- en-US/Design.xml | 15 ++++++++++-- en-US/E.xml | 26 +++++++++++--------- en-US/I.xml | 10 ++++++++ en-US/O.xml | 1 + 9 files changed, 142 insertions(+), 100 deletions(-) diff --git a/en-US/0-9.xml b/en-US/0-9.xml index ec89d36..1ad984c 100644 --- a/en-US/0-9.xml +++ b/en-US/0-9.xml @@ -3,6 +3,7 @@ %BOOK_ENTITIES; ]> + 0-9 @@ -20,7 +21,7 @@ 2-track (IT) - adj. A less common way to refer to bimodal or hybrid IT. See + adj. A less common way to refer to bimodal or hybrid IT. See . @@ -30,7 +31,7 @@ 3-D - adj., n.. Correct. Do not use 3D, 3-d, or other variations. + adj., n. Correct. Do not use 3D, 3-d, or other variations. diff --git a/en-US/A.xml b/en-US/A.xml index eaad450..a644721 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -12,6 +12,7 @@ Ampersands or plus signs can be used in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. + @@ -61,7 +62,7 @@ allinone - n., adj. Correct. Hyphenate in both cases. Do not use "allinone" or other variations. + n., adj. Hyphenate in both places. Do not use "allinone" or other variations. @@ -82,8 +83,9 @@ - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + For more information about Intel® trademarks, see and . @@ -98,7 +100,7 @@ Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. - The cell size used with ATM is relatively small compared to units used with older technologies. + The cell size used with ATM is relatively small compared to units that are used with older technologies. @@ -108,13 +110,14 @@ above - Do not use to refer to information mentioned previously. - When documents are converted to online format, the information may no longer be "above." + Do not use to refer to information that was mentioned previously. + When documents are converted to online format, the information might no longer be "above." Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. + @@ -154,8 +158,8 @@ alternative - adj. Used to describe another way or method of doing something. - "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to..." + adj. Describes another way or method of doing something. + "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." See also . @@ -171,12 +175,13 @@ Avoid if possible. Try to rewrite to make the available options explicit and clear. Do not write this and/or that. - Write this or that or both. + Write this or that, or both. + @@ -200,7 +206,7 @@ ApplixWare - Correct. + "Applixware" is correct. Do not use "Applix" or "ApplixWare." @@ -212,9 +218,9 @@ Do not use as a verb. - Even though it might make sense in the correct context, using it as a verb can be jargon or unclear for your audience. + Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience. Use "design," "build," "create," or another descriptive verb instead. - Before replacing the verb form of "architect" during the editing process, check with the writer to find out the intended meaning. + Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning. For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." @@ -236,7 +242,7 @@ as-a-Service - Be aware that there is a great deal of overlap in as-a-Service acronyms. + Some as-a-Service acronyms overlap. To avoid confusion, always spell out the full term on first use. @@ -260,7 +266,7 @@ - FaaS (Function[s]-as-a-Service) + FaaS (Functions-as-a-Service) @@ -302,27 +308,28 @@ - Capitalize the noun (e.g., Platform, Software, Infrastructure) and Service, both when abbreviated and written out. + Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out. - When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (e.g., INTRODUCTION TO PaaS SOLUTIONS). + When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS). + Hyphenate when written out: Thing-as-a-Service. - For two-word prefixes, do not include a hyphen between the first and second words: Mobile Backend-as-a-Service. - Can be used as an adjective to describe multiple (e.g., when referring to an IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording). + For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. + It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. - Avoid an acronym if it could stand for more than one term in a single asset (e.g., if you're writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service). + Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service. @@ -347,7 +354,7 @@ Always lowercase. - This refers to the kernel-based automount utility. + It refers to the kernel-based automount utility. No other forms are recognized. diff --git a/en-US/B.xml b/en-US/B.xml index fcbedb5..2b9e1a8 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -10,10 +10,10 @@ back end, back-end - n. Two words. Refers to software that performs the final stages of a process, or tasks that are not visible to the user. For example, "each back end provides a set of calls." + n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls." - adj. Hyphenate. For example, "when the back-end database processes a search operation…" + adj. Hyphenate. For example, "when the back-end database processes a search operation …" Do not use "backend." @@ -28,8 +28,9 @@ backup, back up - - Depending on usage, this could appear in either of two ways: + + Write as one word as an adjective or noun, or as two words as a verb. + @@ -63,7 +64,7 @@ backtrace - n. "Backtrace" is the most common term used to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. @@ -92,7 +93,7 @@ bandwidth - Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed amount of time. + Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed time. @@ -135,7 +136,7 @@ below - Do not use to refer to information mentioned "below," or later in a document. When documents are converted to online format, the information may no longer be "below." Use a cross-reference instead. + Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead. @@ -155,14 +156,14 @@ bimodal IT - Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. There are many ways to talk about this combination approach; be sure you use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those not familiar with Gartner's phrasing. + Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. Many ways exist to describe this combination approach; be sure to use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those who are not familiar with Gartner's phrasing. The practice of having both modes together is often referred to as hybrid, agile, or modern IT. - Hybrid IT is a more general term, e.g. it could mean on-premise plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination you mean. + Hybrid IT is a more general term, for example it could mean on-premises plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination that you mean. @@ -171,16 +172,16 @@ - bimonthly, biweekly, semiweekly, semimonthly + biannual, bimonthly, biweekly, semiweekly, semimonthly - People have trouble remembering if biweekly means "every two weeks" or "twice a week." Semiweekly has a similar problem. Even though both terms have clear dictionary definitions, we recommend that you avoid them in favor of clear communication. + People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. Instead of biweekly, write "every two weeks" or "every other week." - Instead of semiweekly or semimonthly, write "twice a week." + Instead of semiweekly, write "twice a week." @@ -190,7 +191,7 @@ BIND - This is correct when referring to the DNS software. Do not use Bind. + Correct when referring to the DNS software. Do not use Bind. @@ -233,13 +234,13 @@ boot - v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software loaded during the boot process. + v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software to load during the boot process. - n. Refers to the starting-up of a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. + n. Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. - Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help get your boot on. Hence, the expression "pull oneself up by the bootstraps." Similarly, bootstrap utilities help the computer get started. + Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started. @@ -272,7 +273,7 @@ One word. Do not use "bottle neck" or "bottle-neck." - A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information being relayed at the speed it is being processed. There are, however, many factors that can create a bottleneck in a system. + A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system. @@ -306,7 +307,7 @@ - Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path taken to reach the current page. + Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path that is taken to reach the current page. @@ -329,7 +330,7 @@ break - (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such "cause the system to fail." + (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail." @@ -347,7 +348,7 @@ Britain - If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and to some implies a specific subjective statement about the state of Northern Ireland. + If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland. @@ -357,10 +358,12 @@ broadcast - To simultaneously send the same message to multiple recipients. Broadcasting is a useful feature in email systems. It is also supported by some fax systems. + To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. + - In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a select list of recipients. + In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a selected list of recipients. @@ -370,7 +373,7 @@ Btrfs - A copy-on-write file system for Linux. Use a capital "B" when referring to the file system. When referring to tools, commands, and other utilities related to the file system, be faithful to those utilities. + A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. See for more information on this file system. @@ -406,7 +409,7 @@ bunches of - Do not use, unless "bunch" is a specific term used in the software being documented. Use "many" or some other alternative instead. + Do not use, unless "bunch" is a specific term that is used in the documented software. Use "many" or some other alternative instead. @@ -419,7 +422,7 @@ Describe a GUI button as a "button," not a "pushbutton" or "push-button." - Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It may be necessary to distinguish between buttons and links; for example, "Click the Download link." + Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link." See also . diff --git a/en-US/C.xml b/en-US/C.xml index 6afef28..210fecd 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -10,7 +10,7 @@ can, may - Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" - it is less tentative. + Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If any of "can," "could," or "may" apply, use "can"; it is less tentative. @@ -20,7 +20,7 @@ cannot - Correct, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." + Correct, as one word, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." @@ -56,7 +56,7 @@ CD #1 - When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1 + When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1. @@ -79,7 +79,7 @@ cgroup - Correct (all lowercase) when referring to the kernel-based technology. This is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. This being the case, it is permissible to capitalize if used at the beginning of a sentence. + Correct (all lowercase) when referring to the kernel-based technology. It is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. It is therefore permissible to capitalize it if used at the beginning of a sentence. Where cgroup refers to something else, for example, a package name, file name, and so on, use a literal rendition. @@ -92,7 +92,7 @@ characters - Do not use "characters" when you should use "bytes." In English, bytes and characters can be used interchangeably; in other languages a single character may consist of multiple bytes. + Do not use "characters" to mean "bytes." In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. @@ -105,7 +105,7 @@ check - Avoid. Use "verify," "make sure," "ensure," or "read," depending on the context. + Avoid. Use "verify," "ensure," or "read," depending on the context. @@ -135,7 +135,7 @@ CI/CD - Define on first use; generally continuous integration/continuous delivery. This is not continuous development, a term with questionable usefulness and only marginal adoption. + Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. See also , , . @@ -148,7 +148,7 @@ ciphertext - n. One word. Do not use "cipher text" or "cipher-text" or other variants. + n. One word. Do not use "cipher text", "cipher-text", or other variants. @@ -158,8 +158,9 @@ click - v. Use when referring to a GUI control button, for example, "Click OK." + v. Use when referring to a GUI control button, for example, "Click OK." Do not use "click on". + See the Word Usage appendix of The IBM Style Guide for more information. @@ -171,8 +172,9 @@ client-side, client side - adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service used to connect to Windows NT servers." + adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." + n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." @@ -181,10 +183,10 @@ - clobber or clobbered + clobber, clobbered - Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the specific context. + Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the context. @@ -194,7 +196,7 @@ cloud - Although cloud is important to our business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." @@ -207,7 +209,7 @@ Define briefly on first use. - Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization only pays for extra compute resources when they are needed. + Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization pays only for extra computing resources when they are needed. @@ -235,6 +237,7 @@ n. Use only as a noun, not a verb. Use "write" for a verb. + @@ -263,7 +266,7 @@ comma-separated values (CSV) - Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information broken up through use of commas. Often used to share data between different, but similar applications, wherein the comma is a translator of the data. + Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information that is broken up through use of commas. This method is often used to share data between different, but similar applications, wherein the comma is a translator of the data. @@ -286,7 +289,7 @@ adj. Correct (compound adjective). Do not use "command driven" or "commanddriven." - Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. + Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. @@ -296,10 +299,10 @@ command language - n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. + n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. - With graphical user interfaces, the command language consists of operations you perform with a mouse or similar input device. + With graphical user interfaces, the command language consists of operations that you perform with a mouse or similar input device. @@ -319,7 +322,7 @@ commodity - Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and can make conservative readers think it is cheap. Use instead: + Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and might imply that it is cheap. Use instead: @@ -354,7 +357,7 @@ Containers-as-a-Service - The term "Containers-as-a-Service" is owned by Docker and should only be used when referring to that company's offering. See also . + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . @@ -364,7 +367,7 @@ container-based - Used to refer to more complex applications made up of multiple services that are distributed in containers. More common than "containerized." + Used to refer to more complex applications with multiple services that are distributed in containers. More common than "containerized." @@ -384,7 +387,7 @@ continuous delivery (CD) - A software implementation architecture that ensures all approved code can be easily pushed to production. + A software implementation architecture that ensures that all approved code can be easily pushed to production. @@ -404,8 +407,9 @@ continuous integration (CI) - A software development architecture where the developer code branch is synchronized with the main code branch or master multiple times per day. Development always works with the current code base. + A software development architecture where the developer code branch is synchronized with the main code branch multiple times per day. Development always works with the current code base. + @@ -415,7 +419,7 @@ control character - A special, non-printing character that begins, modifies, or ends a function, event, operation or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. + A special, non-printing character that begins, modifies, or ends a function, event, operation, or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. @@ -438,7 +442,7 @@ A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows. - Control programs are also called operating environments. + Control programs are also called operating environments. @@ -450,7 +454,7 @@ n. A message given to a web browser by a web server. - The browser stores the message in a text file called cookie.txt. + The browser stores the message in a text file named cookie.txt. The message is then sent back to the server each time the browser requests a page from the server. @@ -462,7 +466,7 @@ CR - Use if referring to code, such as "Type CR at the end of each line..." If referring to the keyboard key, use either Enter or Return, depending upon the platform. + Use if referring to code, such as "Type CR at the end of each line ..." If referring to the keyboard key, use either Enter or Return, depending on the platform. @@ -472,7 +476,7 @@ crash - IBM recommends the use of "fail" rather than "crash." The latter is not outlawed, but you would have to justify its use; that is, indicate why "fail" is inadequate. + IBM recommends the use of "fail" rather than "crash." Use the latter only if you can justify why "fail" is inadequate. @@ -505,7 +509,7 @@ CVE - n. CVE stands for Common Vulnerabilities and Exposures and should be capitalized as shown. + n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. See for more information. @@ -514,7 +518,7 @@ Cygmon - Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). + Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). Refer to it as "Cygmon: a ROM monitor," not "Cygmon: the Cygnus ROM monitor," or "Cygmon: the ROM monitor." diff --git a/en-US/D.xml b/en-US/D.xml index 84095a2..2e8c2ce 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -10,10 +10,10 @@ daisy chain - Noun: A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. + n. A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. - Verb: To connect devices in a daisy chain pattern. + v. To connect devices in a daisy chain pattern. @@ -50,7 +50,7 @@ data mirroring - The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a completely different location. + The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information that is stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a different location. @@ -104,13 +104,14 @@ data type - n. Do not use "datatype" or "data-type" unless they are actually variable names or some other literal value. + n. Do not use "datatype" or "data-type" unless they are variable names or some other literal value. + - + @@ -158,7 +160,7 @@ Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer. - Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. + Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. @@ -168,7 +170,7 @@ DevOps - n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps may also refer to the engineers and developers who work within these modern IT organizations. + n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps can also refer to the engineers and developers who work within these modern IT organizations. @@ -198,14 +200,14 @@ digital transformation - Avoid this phrase. It is vague and could mean using digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. + Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. Disk Druid - Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool incorporated into Red Hat Enterprise Linux. + Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. @@ -217,6 +219,7 @@ Use "compact disc," but "diskette" or "hard disk." See The IBM Style Guide for more information and example use cases. + @@ -268,7 +271,7 @@ double-click - v. Do not use "double click." + v. Always write hyphenated. diff --git a/en-US/Design.xml b/en-US/Design.xml index fafeb2b..94ed730 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -705,16 +705,27 @@ $ vi myFile.txt Acronyms - What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as an actual word. For example, COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). + + + Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." + Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." + Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + + + + To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. + + Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see The IBM Style Guide or another suitable reference if you are unsure. + Initialisms diff --git a/en-US/E.xml b/en-US/E.xml index 37285a8..976efae 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -12,15 +12,16 @@ Refer to the primary reference for the type of copy you are creating, either AP or IBM. + - - e.g., i.e. + + e.g. - Red Hat technical documentation always expands these abbreviations. + Red Hat technical documentation always expands these abbreviations. Write out "for example". @@ -40,7 +41,7 @@ Emacs - If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." + If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." @@ -63,6 +64,7 @@ When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. + When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." @@ -77,13 +79,13 @@ environment - The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, when one speaks of running a program in a UNIX environment, it means running a program on a computer that has the UNIX operating system. + The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, running a program in a UNIX environment means running a program on a computer that has the UNIX operating system. - One ingredient of an environment, therefore, is the operating system. But operating systems include a number of different parameters. For example, many operating systems allow you to choose your command prompt or a default command path. All these parameters taken together constitute the environment. + One ingredient of an environment, therefore, is the operating system. But operating systems include many different parameters. For example, in some operating systems, you can choose your command prompt or a default command path. All these parameters together constitute the environment. - Another term for environment in this sense is platform. + Another term for environment in this sense is platform. @@ -99,7 +101,7 @@ n. Initialism for "end of line" - Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as that shown in the GUI. + Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. @@ -129,7 +131,7 @@ event - An action or occurrence detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. + An action or occurrence that is detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. @@ -159,7 +161,7 @@ execute - Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. + Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. @@ -169,7 +171,7 @@ Exif - Correct. Do not use "EXIF." Exif is an image file format specification that enables metadata tags to be added to existing JPEG, TIFF and RIFF files. Sometimes to referred to as "Exif Print." + Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." @@ -179,7 +181,7 @@ extranet - Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to people who are members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. + Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. Capitalize only at the beginning of a sentence. diff --git a/en-US/I.xml b/en-US/I.xml index 260b90b..d21f0d9 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -45,6 +45,16 @@ + + + i.e. + + + Do not use a Latin abbreviation. Instead, write out "that is". + + + + illegal diff --git a/en-US/O.xml b/en-US/O.xml index 7bc3847..ab6574c 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -104,6 +104,7 @@ + on-site From 5feb09394072f49e3ef26f5f03ea3c8404f6a6fd Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 30 Jun 2021 18:20:50 +0100 Subject: [PATCH 09/27] Updated usage term entries F-L. --- en-US/A.xml | 3 ++- en-US/B.xml | 1 + en-US/Design.xml | 6 ++--- en-US/Easily_Confused_Words.xml | 10 +++---- en-US/F.xml | 36 +++++++++++++++---------- en-US/G.xml | 8 +++--- en-US/H.xml | 19 +++++++------ en-US/I.xml | 47 ++++++++++++++++++++------------- en-US/J.xml | 6 ++--- en-US/K.xml | 6 ++--- en-US/L.xml | 15 ++++++----- en-US/P.xml | 4 +-- en-US/W.xml | 11 ++++++++ 13 files changed, 104 insertions(+), 68 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index a644721..e1cb855 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -6,6 +6,7 @@ A + "&" and "+" @@ -144,7 +145,7 @@ alternate - vb. "Alternate" as a verb means to change between two states or options. + v. "Alternate" as a verb means to change between two states or options. See also . diff --git a/en-US/B.xml b/en-US/B.xml index 2b9e1a8..bbb2505 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -85,6 +85,7 @@ Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also . + diff --git a/en-US/Design.xml b/en-US/Design.xml index 94ed730..a16e6f3 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -19,11 +19,11 @@ Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - + - Use sentence case for table column headers. - These are not classified as titles. + Use sentence case for captions, legends, and table column headers. + They are not classified as titles. Marketing and Brand Capitalization Guide diff --git a/en-US/Easily_Confused_Words.xml b/en-US/Easily_Confused_Words.xml index 9f952bc..53bf144 100644 --- a/en-US/Easily_Confused_Words.xml +++ b/en-US/Easily_Confused_Words.xml @@ -23,7 +23,7 @@ n. Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you. - vb. Means to have an influence on something, or to cause something to change. + v. Means to have an influence on something, or to cause something to change. @@ -36,7 +36,7 @@ n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." - vb. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." + v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." @@ -59,7 +59,7 @@ assure - vb. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." + v. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." @@ -69,7 +69,7 @@ ensure - vb. Means to make sure of something, to be certain that something exists or some condition has been met. + v. Means to make sure of something, to be certain that something exists or some condition has been met. @@ -79,7 +79,7 @@ insure - vb. Relates to monetary insurance. + v. Relates to monetary insurance. diff --git a/en-US/F.xml b/en-US/F.xml index 952d661..baa4e3f 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -10,7 +10,7 @@ fail back, failback - vb. Use the 2-word form. + v. Use the 2-word form. n. Use the 1-word form. @@ -26,7 +26,7 @@ fail over, failover - vb. Use the 2-word form. + v. Use the 2-word form. n., adj. Use the 1-word form. @@ -51,7 +51,7 @@ fault tolerance (n.), fault-tolerant (adj.) - The ability of a system to respond gracefully to an unexpected hardware or software failure. There are many levels of fault tolerance, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so if one fails the other can take over. + The ability of a system to respond gracefully to an unexpected hardware or software failure. Fault tolerance has many levels, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so that if one fails, then the other can take over. @@ -84,7 +84,7 @@ A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FAL). - FAL was designed for new mass storage devices and other peripheral devices that require very high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100MBps. FAL is compatible with, and is expected to eventually replace, SCSI for high-performance storage systems. + FAL was designed for new mass storage devices and other peripheral devices that require high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100 MBps. FAL is compatible with, and is expected eventually to replace, SCSI for high-performance storage systems. @@ -106,9 +106,11 @@ n. Write as shown, two words, unless used as a variable. See The IBM Style Guide for more information. + adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." + @@ -117,8 +119,9 @@ FireWire - Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it does not need to be listed with a trademark symbol when mentioned. Only when talking about Apple's FireWire software license or specific logos should the symbol be used (which is almost never). See http ://developer.apple.com/softwarelicensing/agreements/firewire.html for full details. + Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. + @@ -130,7 +133,7 @@ n. Do not use "firm ware" or "firm-ware." - Software (programs or data) that has been written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. + Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. @@ -164,13 +167,14 @@ + follow - vb. Refers to the use of the () option to various commands, such as tail, so that output is appended as the file grows. + v. Refers to the use of the () option for various commands, such as tail, so that output is appended as the file grows. @@ -180,7 +184,7 @@ - In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. + In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. @@ -200,7 +204,7 @@ fortnight - A period of two weeks (14 nights). Avoid using. This term is not common in American English and may also be unfamiliar to non-native speakers. + A period of two weeks (14 nights). Avoid; this term is not common in American English and might also be unfamiliar to non-native speakers. @@ -232,6 +236,7 @@ Do not use. Instead, use "compatible with later versions." See also . + @@ -240,14 +245,15 @@ FQDN - A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated using the full stop (.) character (dot or period) as a separator between labels.https://en.wikipedia.org/wiki/Fully_qualified_domain_name + A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels.https://en.wikipedia.org/wiki/Fully_qualified_domain_name For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. - A FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also a FQDN. + An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. + @@ -275,7 +281,7 @@ Do not use "frontend" as a noun or adjective. - See also + See also . @@ -292,21 +298,23 @@ - Futexes + futexes Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. + - Fuzzy + fuzzy Correct only when referring to fuzzy searches. See for details and examples. + diff --git a/en-US/G.xml b/en-US/G.xml index 9b3b2a5..743211f 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -108,6 +108,7 @@ Do not use. Use "region" or "geographical location" according to your needs. + @@ -116,7 +117,7 @@ GFS, GFS2 - As of Red Hat Enterprise Linux 6, this is known as the Resilient Storage Add-On. Ensure you use the correct term. + As of Red Hat Enterprise Linux 6, it is known as the Resilient Storage Add-On. Ensure that you use the correct term. @@ -166,7 +167,7 @@ GNOME - Correct. Do not use "gnome," "Gnome," or other variants. See also + Correct. Do not use "gnome," "Gnome," or other variants. See also . @@ -176,7 +177,7 @@ GNOME Classic - Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, we should stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). + Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). @@ -208,6 +209,7 @@ Do not use. + diff --git a/en-US/H.xml b/en-US/H.xml index fc8703f..5ca7062 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -54,7 +54,7 @@ - he, she + he/she Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. @@ -80,6 +80,7 @@ Under review. Need context and example. + @@ -110,7 +111,7 @@ - Do not capitalize when referring to those services in a general way. For example: "A health check ensures your systems perform at their best." + Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." @@ -132,6 +133,7 @@ adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." + n. Two words. For example, "Support is available 24x7 to help maintain high availability." @@ -150,11 +152,12 @@ - home page + homepage - n. Two words. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. See The IBM Style Guide for more information. + n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + @@ -244,7 +247,7 @@ HTML - When referring to the language, use "HTML," such as "To see the HTML version of this documentation..." When referring to a web page extension, use "html," such as "The main page is index.html." + When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." @@ -257,7 +260,7 @@ adj. Hyphenate. Normal hyphenation rules apply. - n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization used in that interface. + n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization that is used in that interface. @@ -267,7 +270,7 @@ hybrid IT - The preferred term when talking about IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of these. Because hybrid can indicate either infrastructure or environment or both, be specific about the underlying combination. See also . + The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . @@ -277,7 +280,7 @@ Hyper-Threading - n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use hyperthreading or hyper-threading. If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. + n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use "hyperthreading" or "hyper-threading". If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. diff --git a/en-US/I.xml b/en-US/I.xml index d21f0d9..eddde06 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -10,7 +10,7 @@ IA64 or ia64 - Do not use. Always use the term Itanium instead. It can be used in file names because they are not visible in the content. + Do not use. Always use the term Itanium instead. These terms can be used in file names because they are not visible in the content. @@ -25,6 +25,7 @@ + IBM Z - IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In July 2017, with another generation of products, the official family was changed to IBM Z from IBM z Systems. + IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. + i.e. @@ -70,7 +73,7 @@ InfiniBand - InfiniBand is a switched fabric network topology used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. + InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. "Open InfiniBand" is deprecated and should not be used. @@ -113,12 +116,13 @@ Intel 64 - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. The correct term for Intel's implementation of this architecture is "Intel® 64." Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. @@ -127,8 +131,9 @@ The AMD64 logo is trademarked; the term "AMD64" is not. - For more information about AMD trademarks, see the AMD Trademark Information page at . + For more information about AMD trademarks, see the AMD Trademark Information page at . + For more information about Intel® trademarks, see and . @@ -166,7 +171,7 @@ Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, nor include any trademark symbols, such as ™ or "(TM)." + Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." @@ -207,7 +212,7 @@ Internet of Things (IoT) - Correct. Capitalize as shown, spell out on the first occurrence, and use the initialism thereafter. + Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. @@ -233,10 +238,10 @@ I/O - Correct. Stands for input/output (pronounced "eye-oh"). The term I/O is used to describe any program, operation or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. + Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. - The term I/O is a non-countable noun. Append "operations" in order to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. + The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. @@ -266,10 +271,10 @@ IP Masquerade - A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not the internal PCs. + A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. - Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. + Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. @@ -289,8 +294,9 @@ IP switching - A new type of IP routing developed by Ipsilon Networks, Inc. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. + A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. + @@ -299,7 +305,7 @@ ISV - Short for independent software vendor, a company that produces software. + Short for "independent software vendor", a company that produces software. @@ -309,7 +315,7 @@ IT/I.T. - Use "I.T." (with periods) only in headlines or subheadings where all caps are used, in order to clarify that the word is "IT" vs. "it." + Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." @@ -319,31 +325,33 @@ Itanium - A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions be executed together, Itanium has the highest FPU power available. + A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. - In 64-bit mode, Itanium is able to calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. + In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. - Do not use the term IA64. It can be used in file names because they are not printed in the content. + Do not use the term "IA64". It can be used in file names because they are not printed in the content. - Itanium 2 + Itanium 2 - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." + Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." + + diff --git a/en-US/J.xml b/en-US/J.xml index 715093f..28be68f 100644 --- a/en-US/J.xml +++ b/en-US/J.xml @@ -10,7 +10,7 @@ JavaScript - "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file written using this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." + "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." @@ -30,7 +30,7 @@ job - A task performed by a computer system. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. + A task that a computer system performs. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. @@ -40,7 +40,7 @@ jsvc - The Apache Commons Daemon jsvc is a set of libraries and applications for making Java applications run on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. + The Apache Commons Daemon jsvc is a set of libraries and applications to run Java applications on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. diff --git a/en-US/K.xml b/en-US/K.xml index 3867def..f74cbf2 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -43,7 +43,7 @@ kernel - The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services required by other parts of the operating system and applications. Typically, the kernel is responsible for memory management, process and task management, and disk management. + The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. @@ -63,7 +63,7 @@ kernel panic - Correct. Numerous circumstances may cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. + Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. @@ -115,7 +115,7 @@ keytab - n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. See for full details. + n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . diff --git a/en-US/L.xml b/en-US/L.xml index 1e2e109..f692291 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -54,6 +54,7 @@ Do not use. Use "omit" instead. + @@ -123,7 +124,7 @@ - To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. + To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. @@ -135,7 +136,7 @@ - n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) being carried by the network, or the amount of CPU being used at any given time. + n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) that the network carries, or the amount of CPU in use at any given time. @@ -149,7 +150,7 @@ load balancing - Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that will be issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. + Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. @@ -159,7 +160,7 @@ logical topology - Also called signal topology. Every LAN has a topology, or the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the actual cables that transmit data - the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. + Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. @@ -195,10 +196,10 @@ loopback address - The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. The loopback interface has no hardware associated with it, and it is not physically connected to a network. + The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. No hardware is associated with a loopback interface, and it is not physically connected to a network. - The loopback interface allows IT professionals to test IP software without worrying about broken or corrupted drivers or hardware. + With a loopback interface, IT professionals can test IP software without concern for broken or corrupted drivers or hardware. @@ -218,7 +219,7 @@ LPAR - Abbreviation of logical partitioning, a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also be used to keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. + Abbreviation of "logical partitioning", a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. diff --git a/en-US/P.xml b/en-US/P.xml index 2ea1b5e..1e804ec 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -37,7 +37,7 @@ persist - vb. + v. Do not use as a verb to mean "store" or "save," for example, when referring to persistent storage. @@ -194,7 +194,7 @@ press - vb. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." + v. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." diff --git a/en-US/W.xml b/en-US/W.xml index 8a9d5d3..cf41dbb 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -70,6 +70,17 @@ + + + webpage + + + n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + + + + + web UI From dcb97502fdfcbb1c5b836def66f429319289db0f Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 1 Jul 2021 17:37:55 +0100 Subject: [PATCH 10/27] Style guide updates --- en-US/Conventions_for_Writers_and_Editors.xml | 2 +- en-US/D.xml | 11 ++++ en-US/Design.xml | 52 ++++++++----------- en-US/Grammar.xml | 2 +- en-US/I.xml | 13 +++++ en-US/M.xml | 31 +++++++---- en-US/Punctuation.xml | 17 ++++-- 7 files changed, 82 insertions(+), 46 deletions(-) diff --git a/en-US/Conventions_for_Writers_and_Editors.xml b/en-US/Conventions_for_Writers_and_Editors.xml index 3f5dfde..d8ebb90 100644 --- a/en-US/Conventions_for_Writers_and_Editors.xml +++ b/en-US/Conventions_for_Writers_and_Editors.xml @@ -17,7 +17,7 @@ - + diff --git a/en-US/D.xml b/en-US/D.xml index 2e8c2ce..c5598f3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -233,6 +233,17 @@ + + + + display + + + v. Use only as a transitive verb. For example, write "the system displays a message" or "the message is displayed" (not "the message displays"). + + + + DNS diff --git a/en-US/Design.xml b/en-US/Design.xml index a16e6f3..ac3ed31 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -19,10 +19,10 @@ Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - + - Use sentence case for captions, legends, and table column headers. + Use sentence case for captions, legends, diagram labels, and table column headers. They are not classified as titles. @@ -42,10 +42,10 @@ Do not use terminating periods. - - Avoid Imperative Form + + Avoid Imperative Mood - Use the gerund form (noun form of verb) for titles, not the imperative form. For example, "Testing the Product", not "Test the Product". + Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". @@ -74,7 +74,6 @@ The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. -
@@ -126,28 +125,25 @@
Navigating Through Multiple GUI Options - Use "Navigate to" when moving through multiple GUI 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. + Use "Navigate to" when moving through multiple GUI 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. From example, "From the OpenShift web console, navigate to Monitoring → Alerting." - - - -
- Starting Applications from the Red Hat Enterprise Linux Desktop + Starting Applications from the Desktop + + This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. + - Red Hat Enterprise Linux 7 introduces a new approach to starting applications from the desktop. - + RHEL 8 uses the following approach to starting applications from the desktop. In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. - The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: @@ -248,7 +244,7 @@ $ scp filename [username@]hostname:/directory - + In , the entire command consists of the following components: @@ -256,22 +252,22 @@ The command prompt ($) - + The command (scp) - + @@ -298,8 +294,7 @@ - - Generally, avoid using the and options on most commands, especially when logged in as the root 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: + In most cases, avoid using the and options on most commands, especially when logged in as the root 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: [root@serverc pam.d]# rm -f system-auth password-auth @@ -635,7 +630,6 @@ $ vi myFile.txt You can use any of the following name generators to create realistic names for users: - @@ -779,14 +773,13 @@ $ vi myFile.txt - Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following examples: + Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. - @@ -797,7 +790,9 @@ $ vi myFile.txt - + + For other markup languages, use the equivalent non-breaking space character. + @@ -1020,12 +1015,11 @@ $ vi myFile.txt
-
+
Thomas Jefferson Why use two words when one will do? @@ -1034,5 +1028,5 @@ $ vi myFile.txt
- +--> diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 1a4c15f..1236bca 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -526,7 +526,7 @@ Split contractions and abbreviations into separate paragraphs. -->
Contractions and Abbreviations - Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They also cause problems for translation. + Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. diff --git a/en-US/I.xml b/en-US/I.xml index eddde06..50d7a55 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -69,6 +69,19 @@ + + + + matrixes + + + Correct. This is the correct plural form for US English spelling. Do not use "indices." + + + + + + InfiniBand diff --git a/en-US/M.xml b/en-US/M.xml index bf5dc7d..000dacc 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -10,7 +10,9 @@ macOS - In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. The latest version of macOS is macOS 10.12 Sierra, which was publicly released in September 2016. + In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. + + @@ -20,17 +22,17 @@ make sure - This means "be careful to remember, attend to, or find out something." For example, "make sure the rhedk group is listed in the output." + This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." - You may be able to use "verify" or "ensure" instead. + You might be able to use "verify" or "ensure" instead. - manual/man page + manual, man page Correct. Two words. Do not use "manpage." @@ -43,8 +45,9 @@ matrixes - Correct. This is the correct plural form for U.S. English spelling. Do not use "matrices." + Correct. This is the correct plural form for US English spelling. Do not use "matrices." + @@ -97,19 +100,21 @@ - Objects on which data can be stored. These include hard disks, diskettes, CDs, and tapes. + Objects on which data can be stored. These include hard disks, CDs, and tapes. + - In computer networks, media refers to the cables linking workstations together. There are many different types of transmission media, the most popular being twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fibre 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 fibre optic cable (cables made out of glass). + - The form and technology used 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, all of which are different types of media. @@ -192,7 +197,7 @@ Montecito - Do not use. This is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. + Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. @@ -209,6 +214,7 @@ To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. + @@ -284,11 +290,12 @@ - Mutexes + mutexes Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. + @@ -297,7 +304,9 @@ MySQL - Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an ball (®) to denote a registered trademark. + Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an + + ® symbol to denote a registered trademark. diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 661fd30..aeddd9a 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -432,14 +432,23 @@ Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. - + + + A Correct Example of the Use of Quotation Marks + + For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." + + + + - +Remove this sentence, and leave it to chapter 4 to cover avoidance of slang. --> + + +Deleted paragraph now that DocBook tagging no longer applies. -->
From bdde6e4a7c90846270f66db4f077f401c399d175 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 2 Jul 2021 16:38:53 +0100 Subject: [PATCH 11/27] Style Guide further updates --- en-US/A.xml | 1 - en-US/D.xml | 1 - en-US/Design.xml | 13 ++++++++----- en-US/Grammar.xml | 10 +++++++--- en-US/Language.xml | 42 ++++++++++++++++++++++++++++++------------ 5 files changed, 45 insertions(+), 22 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index e1cb855..87adb6d 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -200,7 +200,6 @@ --> - Applixware Applix diff --git a/en-US/D.xml b/en-US/D.xml index c5598f3..7c54a22 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -122,7 +122,6 @@ --> - debug diff --git a/en-US/Design.xml b/en-US/Design.xml index ac3ed31..5af4d98 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -244,7 +244,7 @@ $ scp filename [username@]hostname:/directory - + In , the entire command consists of the following components: @@ -701,6 +701,7 @@ $ vi myFile.txt What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). @@ -955,6 +956,7 @@ $ vi myFile.txt
+
Citing Other Works @@ -964,14 +966,15 @@ $ vi myFile.txt - + -<citetitle>Book Title</citetitle> by <author><firstname>First name</firstname><surname>Surname</surname></author>; Publisher. + +Book Title by First name Surname; Publisher. - + For example, Maximum RPM by diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 1236bca..2a305c6 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -414,6 +414,8 @@ +
+ "That" in Clauses @@ -477,7 +479,7 @@ Perform the installation of the product. Install the product. - / + @@ -517,6 +519,8 @@ +
+ -
+
Gender References @@ -622,6 +626,6 @@ Split contractions and abbreviations into separate paragraphs. --> Report an issue -
+
diff --git a/en-US/Language.xml b/en-US/Language.xml index 79d181c..02d37f0 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -5,7 +5,7 @@ ]> - Language + Choosing Appropriate Language Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. @@ -295,9 +295,8 @@ frown upon - "To frown upon" means to hold in low regard, not to approve of, and so on. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). - @@ -883,17 +882,17 @@
- -
+
Inclusive Language Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. - Terms that reinforce cultural, racial, or other types of bias should be replaced with an alternative. + Replace terms that reinforce cultural, racial, or other types of bias with an alternative. Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. @@ -1065,7 +1064,8 @@ Dates and Times (new) --> Use the utility to run activities and save your settings. - Either: Use the utility to run activities and to save your settings (if the utility does both functions); or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). @@ -1136,8 +1136,8 @@ Dates and Times (new) --> - If the completed field has text, it does not change. - If the completed field has text, that text does not change. + If the completed field contains text, it does not change. + If the completed field contains text, that text does not change. @@ -1184,9 +1184,15 @@ Dates and Times (new) --> + - Create the resource using all relevant options. - Create the resource by using all relevant options. + Open the firewall ports using the existing service configuration. + Open the firewall ports by using the existing service configuration. + + + + The resource agents using mail alerts require a mail transport agent. + The resource agents that use mail alerts require a mail transport agent. @@ -1256,7 +1262,7 @@ Dates and Times (new) --> - For times of day, use uppercase without periods, such as “11 AM”. Use a nonbreaking space between the numeral and “AM” or “PM”. + For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". @@ -1264,6 +1270,18 @@ Dates and Times (new) --> Use "midnight" or "12 midnight" instead of "12 AM". + Examples + + + The laptop was manufactured at 10 AM on 1 April 2021. + + + The coffee break is from 2:00 PM to 2:30 PM. + + + + +
From a5373586b0c20547b83916b898feaac26a95639f Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Mon, 5 Jul 2021 19:15:52 +0100 Subject: [PATCH 12/27] Updated L-P entries. --- en-US/L.xml | 33 ++++++++++++++++++++++++++++ en-US/Language.xml | 24 ++++++++++++++++++-- en-US/N.xml | 36 ++++++++++++------------------ en-US/O.xml | 41 ++++++++++++++++++++-------------- en-US/P.xml | 55 +++++++++++++++++++++++++++------------------- en-US/S.xml | 19 ++++++++++++++++ 6 files changed, 146 insertions(+), 62 deletions(-) diff --git a/en-US/L.xml b/en-US/L.xml index f692291..4f2bef7 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -165,6 +165,39 @@ + + + + login, log in + + + Write as one word as an adjective or noun, or as two words as a verb. + + + + + adj., n. One word. For example, "the login credentials". + + + + + + v. Two words. For example, "to log in as root". + + + + + + + + + log in to + + + v. Write as three words. For example, "to log in to the system". + + + lookup, look-up, look up diff --git a/en-US/Language.xml b/en-US/Language.xml index 02d37f0..e3158b5 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -885,7 +885,8 @@ +Dates and Times (new) +Numbers (move from N entry) -->
Inclusive Language @@ -1246,7 +1247,7 @@ Dates and Times (new) -->
-
+
Dates and Times @@ -1284,4 +1285,23 @@ Dates and Times (new) -->
+ +
+ Numbers + + + Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of...), and very large values. + + + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + + + Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). + + + See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. + + +
+ diff --git a/en-US/N.xml b/en-US/N.xml index 4838241..f129cd6 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -10,10 +10,10 @@ navigate to - Use "Navigate to" when moving through multiple GUI 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 GUI 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. + Do not use "Go to", or "point to", or other variations. @@ -22,11 +22,13 @@ need - Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they may not "need" something but may still "want" something). + Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). + + needs, needs to be, need to @@ -34,6 +36,7 @@ Avoid when possible. Suggested alternatives include "must," "required," or "should." + @@ -56,7 +59,7 @@ network transparency - A condition in which an operating system or other service allows the user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems" NFS, which has become a de facto industry standard, provides access to shared files through an interface called the Virtual File System (VFS) that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. + A condition in which an operating system or other service gives user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems NFS, now a de facto industry standard, provides access to shared files through the Virtual File System (VFS) interface that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. @@ -66,10 +69,10 @@ NFS - Abbreviation of Network File System, a client/server application designed by Sun Microsystems that allows all network users to access shared files stored on computers of different types. NFS provides access to shared files through an interface called the Virtual File System (VFS) 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 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. @@ -81,7 +84,7 @@ - In networks, a processing location. A node can be a computer or some other device, such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or Media Access Control (MAC) address. + In networks, a processing location. A node can be a computer or some other device such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or a Media Access Control (MAC) address. @@ -117,22 +120,11 @@ - - numbers - - - Spell out numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of...), and very large values. Use numerals for numbers 10 and greater and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (Red Hat Enterprise Linux 6, Source-Navigator 4.5). - - - Do not use commas in numbers with four digits (use 1000 rather than 1,000). Do use commas in numbers with five or more digits (10,000; 123,456,789; 1,000,000,000). - - - See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. - - - - + + diff --git a/en-US/O.xml b/en-US/O.xml index ab6574c..3cc7ed5 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -20,7 +20,11 @@ object-oriented - Correct. Do not use "object oriented" or "objectoriented." This is a modifier, such as "Java is an object-oriented language." + Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." + + + + Also, do not use "object-orientated". @@ -30,8 +34,9 @@ OEM - n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is really a misnomer because OEMs are not the original manufacturers - they are the customizers. + n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. + To provide equipment to another company, an OEM, which customizes and markets the equipment. @@ -43,7 +48,7 @@ offline - adj. Do not use "off-line." + adj. Write as one word. Do not use "off-line." @@ -56,10 +61,12 @@ 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. + + @@ -71,6 +78,7 @@ 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." + @@ -98,7 +106,7 @@ online - Correct. Do not use "on-line." + adj. Write as one word. Do not use "on-line." @@ -106,6 +114,7 @@ + on-site @@ -120,7 +129,7 @@ on-the-fly - Do not use. Avoid using idioms, as this saying is not 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. @@ -130,7 +139,7 @@ oops - A kernel oops is an error message 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 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." @@ -150,7 +159,7 @@ OpenJDK - The OpenJDK trademark is owned by Oracle with a fair-use clause, so be very careful about how you use this term. + The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. @@ -158,7 +167,7 @@ open architecture - An architecture whose specifications are public. This includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. + An architecture whose specifications are public. It includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. @@ -181,7 +190,7 @@ A Linux desktop suite. Do not use "Openoffice," "Open Office," or "ooo." - See also + See also . @@ -202,10 +211,10 @@ open source way - A phrase 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 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 actually having an open source policy as defined by Open Source Initiative, to avoid diluting the legal meaning of the term "open source". @@ -225,7 +234,7 @@ orientate - Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps familiarize you with the environment." + Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps to familiarize you with the environment." @@ -235,7 +244,7 @@ output device - Any machine capable of representing information from a computer. This includes display screens, printers, plotters, and synthesizers. + Any machine that is capable of representing information from a computer, including display screens, printers, plotters, and synthesizers. @@ -245,7 +254,7 @@ overcloud - n. Always lowercase. This is a concept, not a technology or product name. Being a common noun, this 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 requires an article in most cases. See also . diff --git a/en-US/P.xml b/en-US/P.xml index 1e804ec..16ec71d 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -10,7 +10,7 @@ PaaS - n. This is the correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), hyphens are always used. + n. The correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. Marketing, Brand, Customer Portal Usage @@ -27,7 +27,9 @@ PC - n. Use to refer to a personal computer. See The IBM Style Guide for further information. + n. Use to refer to a personal computer. + @@ -69,10 +71,10 @@ 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 sitting about just being stored or is 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." @@ -84,6 +86,10 @@ Do not use. Instead of saying "Please refer to 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. + @@ -102,10 +108,12 @@ plug-in - n. 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. For example, a number of plug-ins are available for the Netscape Navigator browser that enable it to display different types of audio or video messages. Navigator plug-ins are based on MIME file types. + A hardware or software module that adds a specific feature or service to a larger system. + + @@ -142,7 +150,7 @@ PostScript - n. This is a registered trademark of Adobe. Do not use "Postscript." + n. It is a registered trademark of Adobe. Do not use "Postscript." @@ -152,13 +160,14 @@ PowerPC - n. The name of the Power architecture is "Power", but the designation of individual chips tend to be either "PowerPC" or "POWER". Refer to IBM marketing or the Open Power Foundation if unsure. + 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 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 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". + - NB: 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 almost all cases. @@ -208,13 +217,13 @@ - Use "proofs of concept" when there are multiple proofs, only one concept. + Use "proofs of concept" for multiple proofs and only one concept. - Use "proofs of concepts" when there are multiple proofs and multiple concepts. + Use "proofs of concepts" for multiple proofs and multiple concepts. @@ -242,14 +251,15 @@ - + + @@ -266,32 +276,32 @@ push-button automation, turn-key automation - Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use language accurate to the situation being described, such as: + Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use accurate language for the situation, such as: - User-triggered automation. + User-triggered automation - Ready-to-use/ready-to-deploy. + Ready-to-use, ready-to-deploy - Self-service/self-provisioned. + Self-service, self-provisioned. - Single-step automation. + Single-step automation - On-demand automation. + On-demand automation @@ -301,11 +311,12 @@ PXE - Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. It allows a workstation to boot from a server on a network in preference to booting the operating system on the local hard drive. + Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. + diff --git a/en-US/S.xml b/en-US/S.xml index dcc252c..8441807 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -315,6 +315,25 @@ + + + + sign in + + + v. Write as two words. For example, "two options are available to sign in". + + + + + + sign in to + + + v. Write as three words. For example, "to sign in to the system". + + + simply From f75b28c302fe4291cb07917f4889b6d1d4a9edbe Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 6 Jul 2021 18:26:54 +0100 Subject: [PATCH 13/27] A-Z updates up to R --- en-US/Design.xml | 4 ++-- en-US/K.xml | 2 +- en-US/L.xml | 2 +- en-US/P.xml | 2 +- en-US/Q.xml | 6 ++++-- en-US/R.xml | 27 ++++++++++++++++----------- en-US/Revision_History.xml | 21 +++++++++++++++++++++ 7 files changed, 46 insertions(+), 18 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 5af4d98..db2bc25 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -55,7 +55,7 @@ Gerunds should be avoided elsewhere. - Refer to . + See . @@ -930,7 +930,7 @@ $ vi myFile.txt When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". Recommendations can include best practices, recommended practices, and product-specific suggestions. - Refer to for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. + See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. diff --git a/en-US/K.xml b/en-US/K.xml index f74cbf2..1e84cf8 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,7 @@ <term>KB, kB</term> <listitem> <para> - Refer to <citetitle>The IBM Style Guide</citetitle> for the correct abbreviation to use for specific use cases. + See <citetitle>The IBM Style Guide</citetitle> for the correct abbreviation to use for specific use cases. </para> </listitem> diff --git a/en-US/L.xml b/en-US/L.xml index 4f2bef7..190bf08 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -63,7 +63,7 @@ <term>left-click</term> <listitem> <para> - <emphasis>v.</emphasis> Do not use "left click" or "leftclick." + <emphasis>v.</emphasis> Write the term hyphenated. Do not use "left click" or "leftclick." </para> </listitem> diff --git a/en-US/P.xml b/en-US/P.xml index 16ec71d..a28b663 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -84,7 +84,7 @@ <term>please</term> <listitem> <para> - Do not use. Instead of saying "Please refer to the <citetitle>Getting Started Guide</citetitle>," use "See the <citetitle>Getting Started Guide."</citetitle> + Do not use. Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>," use "See the <citetitle>Getting Started Guide."</citetitle> </para> <!-- Added justification --> <para> diff --git a/en-US/Q.xml b/en-US/Q.xml index 631750c..2754d0a 100644 --- a/en-US/Q.xml +++ b/en-US/Q.xml @@ -16,6 +16,8 @@ <para> In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. </para> +<!-- Should <term> be expanded to "Q and A, Q & A"? +Still relevant to mention DocBook handling? --> </note> @@ -27,11 +29,11 @@ <listitem> <para> Lowercase at all times.<footnote> <para> - Based on information from <ulink url="http://www.ibm.com/developerworks/linux/linux390/development_documentation.html#1">Linux on System z: Device Drivers, Features and Commands</ulink> at http://www.ibm.com/developerworks/linux/linux390/development_documentation.html#1 + <!-- Based on information from <ulink url="http://www.ibm.com/developerworks/linux/linux390/development_documentation.html#1">Linux on System z: Device Drivers, Features and Commands</ulink> at http://www.ibm.com/developerworks/linux/linux390/development_documentation.html#1 --> </para> </footnote> </para> - +<!-- This URL now redirects to a site where this information is not (readily) available. --> </listitem> </varlistentry> diff --git a/en-US/R.xml b/en-US/R.xml index 5dcd72b..bc7ce25 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -10,7 +10,7 @@ <term>RAM</term> <listitem> <para> - Correct. Do not use "Ram" or any other variations. This is an acronym for "random access memory." + Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." </para> </listitem> @@ -23,7 +23,7 @@ Correct. Do not use "RAMdisk," "ramdisk," or "RAdisk." </para> <para> - Refers to RAM that has been 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 approximately a thousand times faster than hard disk drives. They are particularly useful, therefore, for applications that require frequent disk accesses. </para> </listitem> @@ -41,12 +41,13 @@ </listitem> +<!-- Is a separate entry from "raw" needed? --> </varlistentry> <varlistentry id="raw-data"> <term>raw data</term> <listitem> <para> - Information that has not been organized, formatted, or analyzed. + Information that is not organized, formatted, or analyzed. </para> </listitem> @@ -56,7 +57,7 @@ <term>read</term> <listitem> <para> - <emphasis>v.</emphasis> To copy data to a place where it can be used by a program. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. Also used to refer to the act of determining the contents of a variable or parameter. + <emphasis>v.</emphasis> To copy data to a place where a program can use it. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. It can also refer to the act of determining the contents of a variable or parameter. </para> <para> <emphasis>n.</emphasis> The act of reading. For example, a fast disk drive performs 100 reads per second. @@ -69,7 +70,7 @@ <term>read-only</term> <listitem> <para> - Capable of being displayed, but not modified or deleted. All operating systems allow you to protect objects (disks, files, directories) with a read-only attribute that prevents other users from modifying the object. + Capable of being displayed, but not modified or deleted. For all operating systems, you can protect objects (disks, files, or directories) with a read-only attribute that prevents other users from modifying the object. </para> </listitem> @@ -79,7 +80,7 @@ <term>read/write</term> <listitem> <para> - Capable of being displayed (read) and modified (written to). Most objects (disks, files, directories) are read/write, but operating systems also allow you to protect objects with a read-only attribute that prevents other users from modifying the object. + Capable of being displayed (read) and modified (written to). Most objects (disks, files, or directories) are read/write, but you can also protect objects with a read-only attribute that prevents other users from modifying the object. </para> </listitem> @@ -91,6 +92,7 @@ <para> <emphasis>n.</emphasis> The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." </para> +<!-- Whose quotation is this? I would prefer "might" instead of "may". --> <para> <emphasis>adj.</emphasis> Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." </para> @@ -124,6 +126,7 @@ <para> Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." </para> +<!-- Theory and practice diverge in this matter! --> </listitem> @@ -132,7 +135,7 @@ <term>remote access</term> <listitem> <para> - The ability to log onto a network from a distant location. Generally, this implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer actually becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations connected directly to the network is slower data transfer speeds. + The ability to log on to a network from a distant location. Generally, it implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations that are connected directly to the network is slower data transfer speeds. </para> </listitem> @@ -142,8 +145,9 @@ <term>remote access server</term> <listitem> <para> - A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. After the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN. + 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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. </para> +<!-- This example seems a bit dated. --> </listitem> @@ -172,7 +176,7 @@ <term>right-click</term> <listitem> <para> - <emphasis>v.</emphasis> Correct. Do not use "right click." + <emphasis>v.</emphasis> Write the term hyphenated. Do not use "right click." </para> </listitem> @@ -192,7 +196,7 @@ <term>ROM, PROM</term> <listitem> <para> - Acronym for read-only memory, computer memory on which data has been prerecorded. After data has been written onto a ROM chip, it cannot be removed and can only be read. + Acronym for read-only memory, computer memory on which data is prerecorded. After data has been written to a ROM chip, it cannot be removed and can only be read. </para> <para> A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a device called a PROM programmer. @@ -207,6 +211,7 @@ <para> <emphasis>v.</emphasis> Use the one-word form to refer to a type of event or gathering. </para> +<!-- I have never seen this term used as a verb. --> <para> <emphasis>n.</emphasis> Use the two-word form to refer to a circular table. </para> @@ -218,7 +223,7 @@ <term>RPM</term> <listitem> <para> - Initialism for the RPM Package Manager. RPM manages files in the RPM format, known as RPM packages. Note: RPM packages are known informally as <firstterm>rpm files</firstterm>, but this informal usage is not used in Red Hat documentation in order 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 <firstterm>rpm files</firstterm>, 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." </para> </listitem> diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index f1e8054..c82d63a 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -7,6 +7,27 @@ <title>Revision History + + 3.0 + July 2021 + + Julian + Cable + jcable@redhat.com + + + + Major update to align with some recent changes in IBM Style. + Sentence case is required for captions, legends, and diagram labels. + Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. + Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. + Minor edits so the guide itself conforms with its own advice. + + + + + + 2.0-1 Wed Jun 3 2015 From d3e92099e8cf6c42a3655d81de7d4a052a75fe78 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 7 Jul 2021 17:45:41 +0100 Subject: [PATCH 14/27] Updated "S" entries. --- en-US/L.xml | 2 ++ en-US/S.xml | 74 ++++++++++++++++++++++++++++++----------------------- 2 files changed, 44 insertions(+), 32 deletions(-) diff --git a/en-US/L.xml b/en-US/L.xml index 190bf08..1443a75 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -68,6 +68,8 @@ + + LibreOffice diff --git a/en-US/S.xml b/en-US/S.xml index 8441807..03a69d5 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -20,7 +20,9 @@ SaaS - Correct. This is the correct abbreviation for "Software-as-a-Service." See also . + The correct abbreviation for "Software-as-a-Service." + + See also . @@ -99,8 +101,8 @@ With this new version, the application is running on a more secure, gateway-protected endpoint. - This functionality secures your connection. - This functionality improves the security of your connection. + This function secures your connection. + This function improves the security of your connection. Developers can easily change the code to implement secured access. @@ -146,11 +148,11 @@ - - sends out + + send out - Do not use. Instead, use "emits" or "issues." + Do not use. Instead, use "emit" or "issue." @@ -160,7 +162,7 @@ server farm - Also referred to as server cluster, computer farm or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. + Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. @@ -182,6 +184,7 @@ Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: + @@ -214,7 +217,7 @@ 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 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, in lieu of "2." Thus "SHA224," "SHA256," "SHA384," and "SHA512" are considered correct when referring to these specific hash functions. See for full details. @@ -262,6 +265,7 @@ Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." + @@ -349,7 +353,7 @@ 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. @@ -359,7 +363,7 @@ skill set, skills, knowledge - n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge;" it is redundant. See the following examples: + n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: Example Use of Term "Skillset" Versus "Skills" @@ -391,7 +395,7 @@ n. SLA stands for Service Level agreement. The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. - This distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. + This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. @@ -421,7 +425,7 @@ softcopy - Do not use. Instead, use "online." For example, "To view the online documentation..." + Do not use. Instead, use "online." For example, "To view the online documentation ..." @@ -452,7 +456,7 @@ v. In addition to the generic use of this term as a noun and verb, in -a programming and technical sense this also means "Run the source command against the named file." +a programming and technical sense, it also means "Run the source command against the named file." @@ -460,7 +464,7 @@ a programming and technical sense this also means "Run the sourcespace - Use when referring to white space, such as "Ensure there is a space between each command." Use "Spacebar" when referring to the keyboard key. + Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key. @@ -500,11 +504,11 @@ a programming and technical sense this also means "Run the sourcespelled - Correct. Do not use "spelt." + Correct. It is the standard US English spelling. Do not use "spelt." - + @@ -513,16 +517,16 @@ a programming and technical sense this also means "Run the sourceSQL - When referring to the ISO standard (ISO 9075 and its descendants), this is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. + When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. - NB: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." + Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." - More generally, avoid using "SQL" as a generic marker if at all possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." + More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." @@ -532,7 +536,7 @@ a programming and technical sense this also means "Run the sourceSR-IOV - Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification that allows a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. + Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. @@ -542,7 +546,7 @@ a programming and technical sense this also means "Run the sourceSSH - Initialism for Secure Shell, a network protocol that allows data exchange using a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. + Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. Do not use as a verb. @@ -565,7 +569,7 @@ a programming and technical sense this also means "Run the sourceSSL - Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. The majority of web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. + Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. @@ -575,10 +579,13 @@ a programming and technical sense this also means "Run the sourcestand-alone - adj. Correct. Do not use "standalone." + adj. Write hyphenated. Do not use "standalone." - Refers to something that is self-contained, or that does not require any other devices to function. For example, a fax machine 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. + 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. @@ -590,6 +597,7 @@ a programming and technical sense this also means "Run the source A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." + The successors of StarOffice are and . @@ -597,11 +605,11 @@ a programming and technical sense this also means "Run the source - - starts up + + start up - Do not use. Instead, use "activates" or "invokes." + v. Do not use. Instead, use "activate" or "invoke." @@ -641,7 +649,9 @@ a programming and technical sense this also means "Run the sourcesubcommand - Correct. Do not use "sub-command" or "verb." A subcommand refers to a secondary or even tertiary command used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: + Correct. Do not use "sub-command" or "verb." + + A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: hammer import organization --help @@ -688,7 +698,7 @@ a programming and technical sense this also means "Run the source - NB: subpackages are not the same as dependencies and should not be treated as such. + Note: Subpackages are not the same as dependencies and should not be treated as such. @@ -698,7 +708,7 @@ a programming and technical sense this also means "Run the sourcesuperuser - A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this is the correct spelling. Do not use "super user" or "super-user." + A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." @@ -741,7 +751,7 @@ a programming and technical sense this also means "Run the sourcesymmetric encryption - A type of encryption where the same key is used to encrypt and decrypt the message. This differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. + A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. From d6af2465a9cde39f3d7907823f170f7c8c40df19 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 8 Jul 2021 21:22:00 +1000 Subject: [PATCH 15/27] Fix up some XML issues. --- en-US/Design.xml | 24 ++++++++--------- en-US/Language.xml | 53 +++++++++++++++++++------------------- en-US/P.xml | 12 ++++----- en-US/Revision_History.xml | 2 +- 4 files changed, 46 insertions(+), 45 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index db2bc25..1dc77d7 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -47,7 +47,7 @@ Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". - + See The IBM Style Guide for more information. @@ -137,13 +137,13 @@ Starting Applications from the Desktop This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. - + RHEL 8 uses the following approach to starting applications from the desktop. In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. - The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. + The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: @@ -252,22 +252,22 @@ The command prompt ($) - + - + The command (scp) - + @@ -696,7 +696,7 @@ $ vi myFile.txt - + Acronyms What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. @@ -716,7 +716,7 @@ $ vi myFile.txt To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. - + Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see The IBM Style Guide or another suitable reference if you are unsure. @@ -792,7 +792,7 @@ $ vi myFile.txt - For other markup languages, use the equivalent non-breaking space character. + For other markup languages, use the equivalent non-breaking space character. @@ -972,7 +972,7 @@ $ vi myFile.txt -Book Title by First name Surname; Publisher. +Book Title by First name Surname; Publisher. diff --git a/en-US/Language.xml b/en-US/Language.xml index e3158b5..7bbaa53 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -9,6 +9,7 @@ Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. @@ -18,7 +19,7 @@ Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. - +
Avoiding Misleading or Confusing Language @@ -882,7 +883,7 @@
-
Inclusive Language - Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. + Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. Replace terms that reinforce cultural, racial, or other types of bias with an alternative. - Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. 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 as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. - Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". + Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". - Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. + Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time.
@@ -961,7 +962,7 @@ Numbers (move from N entry) --> The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. - + @@ -1046,7 +1047,7 @@ Numbers (move from N entry) --> Verb phrases - When you have more than one infinitive verb within a sentence, be clear what each verb refers to. + When you have more than one infinitive verb within a sentence, be clear what each verb refers to.
@@ -1078,7 +1079,7 @@ Numbers (move from N entry) --> - + Invisible Plurals @@ -1113,13 +1114,13 @@ Numbers (move from N entry) -->
- + Verb phrases - Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. + Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. @@ -1241,7 +1242,7 @@ Numbers (move from N entry) --> - + @@ -1253,15 +1254,15 @@ Numbers (move from N entry) --> Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. - + - Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". + Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. - + For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". @@ -1270,7 +1271,7 @@ Numbers (move from N entry) --> Use "noon" or "12 noon" instead of "12 PM". Use "midnight" or "12 midnight" instead of "12 AM". - + Examples @@ -1280,17 +1281,18 @@ Numbers (move from N entry) --> The coffee break is from 2:00 PM to 2:30 PM. + -
- Numbers +
+ Numbers - Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of...), and very large values. + Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of...), and very large values. Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). @@ -1298,10 +1300,9 @@ Numbers (move from N entry) --> Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). - + See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. -
- - +
+ \ No newline at end of file diff --git a/en-US/P.xml b/en-US/P.xml index a28b663..b7a808e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -27,8 +27,8 @@ PC - n. Use to refer to a personal computer. - @@ -111,7 +111,7 @@ n. Write hyphenated. Do not use "plugin." - A hardware or software module that adds a specific feature or service to a larger system. + A hardware or software module that adds a specific feature or service to a larger system. @@ -257,11 +257,11 @@ n. "IBM eServer System p" is correct for the first reference in a manual; use IBM System p or System p for subsequent references. Do not use "pSeries." - + - --> + - + --> pull-down diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index c82d63a..5b4000e 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -8,7 +8,7 @@ - 3.0 + 3-0 July 2021 Julian From c2783349520cf2567ed82d7488508c853c3ff676 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 8 Jul 2021 17:59:33 +0100 Subject: [PATCH 16/27] Style Guide updates A-Z and others --- en-US/A.xml | 11 +++++++++++ en-US/C.xml | 4 ++-- en-US/Cross_references.xml | 5 +++-- en-US/D.xml | 2 +- en-US/Design.xml | 4 ++-- en-US/F.xml | 13 ++++++++++++- en-US/Language.xml | 26 ++++++++++++++++++++++---- en-US/Resources.xml | 11 ++++------- en-US/T.xml | 26 +++++++++++--------------- en-US/U.xml | 14 +++++++------- en-US/V.xml | 10 +++++----- en-US/W.xml | 11 +++++++---- en-US/XYZ.xml | 20 ++++++++++++-------- 13 files changed, 99 insertions(+), 58 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 87adb6d..2927a20 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -338,6 +338,17 @@ + + + + as long as + + + Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that". + + + + - See the Word Usage appendix of The IBM Style Guide for more information. + See the Word Usage chapter of The IBM Style Guide for more information. diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 21f86da..546c632 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -6,9 +6,10 @@ Using Cross-references Effectively - This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. In DocBook XML, cross-references are formatted according to the style sheets; at this point no references are available that describe how they should be formatted in other media. Formatting is not described in this section. + This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. + + Formatting is not described in this section. - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. diff --git a/en-US/D.xml b/en-US/D.xml index 7c54a22..13465c5 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -179,7 +179,7 @@ dialog box - See the Word Usage appendix of The IBM Style Guide for usage information related to this and similar terms. + See the Word Usage chapter of The IBM Style Guide for usage information related to this and similar terms. diff --git a/en-US/Design.xml b/en-US/Design.xml index 1dc77d7..d1e7347 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -254,7 +254,7 @@ The command prompt ($) - Indicates that a normal user can run the command, as compared to the root user, which is indicated by the number sign (#). + @@ -264,7 +264,7 @@ The command (scp) - The actual command to run, without any optional or replaceable values. It must be typed as-is. + diff --git a/en-US/F.xml b/en-US/F.xml index baa4e3f..1f7eebc 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -170,7 +170,7 @@ - + follow @@ -178,6 +178,17 @@ + + + + following + + + When introducing a list or a procedure, use "following" with a noun. Instead of "Complete the following", use "Complete the following steps". + + + + foreground diff --git a/en-US/Language.xml b/en-US/Language.xml index 7bbaa53..fb6f3b4 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -899,6 +899,9 @@ Numbers (move from N entry) --> Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. @@ -1189,7 +1192,13 @@ Numbers (move from N entry) --> Open the firewall ports using the existing service configuration. - Open the firewall ports by using the existing service configuration. + + + Option 1: Open the firewall ports by using the existing service configuration. + + Option 2: Use the existing service configuration to open the firewall ports. + + @@ -1275,7 +1284,7 @@ Numbers (move from N entry) --> Examples - The laptop was manufactured at 10 AM on 1 April 2021. + The training class begins at 10 AM on 1 April 2021. The coffee break is from 2:00 PM to 2:30 PM. @@ -1292,7 +1301,7 @@ Numbers (move from N entry) -->
Numbers - Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of...), and very large values. + Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). @@ -1300,9 +1309,18 @@ Numbers (move from N entry) --> Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). - + See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. + +
+ Phone numbers + + Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international use by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. + + +
+
\ No newline at end of file diff --git a/en-US/Resources.xml b/en-US/Resources.xml index 50986ce..dbdc529 100644 --- a/en-US/Resources.xml +++ b/en-US/Resources.xml @@ -6,9 +6,8 @@ Resources - This section lists some books and websites for you to consult on your quest to create the perfect document. + This section lists some books and websites for you to consult on your quest to create a better document. - The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: @@ -16,7 +15,6 @@ Technical content: software manuals and documentation, user guides, training courses - @@ -54,7 +52,6 @@ IBM Style Guide. IBM Corporation, latest version. - @@ -104,14 +101,14 @@ -
+ + Microsoft Manual of Style for Technical Publications, Third Edition. Redmond, WA: Microsoft Press, 2004. @@ -142,7 +139,7 @@ -
+ --> diff --git a/en-US/T.xml b/en-US/T.xml index 694d402..110296d 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -20,11 +20,12 @@ tar, tarball - n. See the Word Usage appendix of The IBM Style Guide. + n. See the Word Usage chapter of The IBM Style Guide. + telco @@ -59,17 +60,10 @@ - - - telephone numbers - - - Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. - + - + - terminal @@ -77,7 +71,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - See the Word Usage appendix of The IBM Style Guide for more information. + See the Word Usage chapter of The IBM Style Guide for more information. @@ -87,7 +81,7 @@ terminal emulation - Refers to making a computer respond like a particular type of terminal. Terminal emulation programs allow you to access a mainframe computer or bulletin board service with a personal computer. + Refers to making a computer respond like a particular type of terminal. With a terminal emulation program, you can access a mainframe computer or bulletin board service with a personal computer. @@ -140,7 +134,7 @@ throughput - n. The amount of data transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See The IBM Style Guide for more information about using measurements and abbreviations. + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See The IBM Style Guide for more information about using measurements and abbreviations. @@ -155,6 +149,7 @@ + time frame (n.) @@ -177,10 +172,11 @@ - token ring (n.) + token-ring (n.) - When capitalized, Token Ring refers to the PC network architecture developed by IBM. The IBM Token-Ring specification has been standardized by the IEEE as the IEEE 802.5 standard. See The IBM Style Guide for further uses of this term. + 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. + diff --git a/en-US/U.xml b/en-US/U.xml index 2173e15..7d55d87 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -23,7 +23,7 @@ Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. - UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. Products bearing the SPARC trademarks are based upon 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. @@ -33,7 +33,7 @@ undercloud - n. Always lowercase. This is a concept, not a technology or product name. Being a common noun, this requires an article in most cases. See also . + n. 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 . @@ -69,13 +69,13 @@ unset - Incorrect. Use "Clear" instead. + Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. - This rule only matches TCP packets that have the SYN flag set and the ACK flag cleared. + This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. @@ -169,10 +169,10 @@ user - n. When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. + n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. - If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may want to access your database." + If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." @@ -185,7 +185,7 @@ n. Correct. Do not use "user-interface" or "userinterface." - 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. A command-driven interface is one in which you enter commands. A menu-driven interface is one in which you select command choices from various menus 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. diff --git a/en-US/V.xml b/en-US/V.xml index 8fef600..b14bcb5 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -20,7 +20,7 @@ VDSM - Initialism for Virtual Desktop Server Management. DO NOT spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. + Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. @@ -71,7 +71,7 @@ Correct. Do not use "virtual-console" or "Virtual Console" for general use. - This can be abbreviated to "VC" as long as the term has been introduced in the same content in its full version first, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." + It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." @@ -81,10 +81,10 @@ virtual machine, VM - Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" unless you want to specifically emphasize the fact that it is a guest. + Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - This can be abbreviated to "VM" as long as the term has been introduced in the same content in its full version first, and provided there is no possibility of confusion with other terms, such as "virtual memory." Author discretion is recommended. + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. @@ -127,7 +127,7 @@ VPN - Initialism for virtual private network, a network that is constructed by using public wires to connect nodes. For example, there are a number of systems that enable you to create networks using the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. + Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. diff --git a/en-US/W.xml b/en-US/W.xml index cf41dbb..c3aed22 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -26,8 +26,9 @@ WCA - An abbreviation of "web clipping application," an application that allows users to extract static information from a web server and load that data onto a web-enabled PDA. + An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. + WCAs are also called "query applications." @@ -41,7 +42,7 @@ Use instead of "wish" or "would like." Rephrase to avoid whenever possible. - For example, "If you want to use the debugger..." can be rewritten as "To use the debugger..." + For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." @@ -94,14 +95,14 @@ - who/whom + who, whom Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. - For example: Who owns this? To whom does this belong? + For example: Who owns this phone? To whom does this phone belong? @@ -110,6 +111,7 @@ will + Do not use future tense unless it is absolutely necessary. For example, do not write "The next section will describe the process in detail." @@ -126,6 +128,7 @@ Correct. Do not combine into one word or hyphenate. This is a window manager for the "X Window System." + diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 9bce184..97ca19e 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -30,14 +30,15 @@ Xen - Use where it accurately refers to the original Xen version of the package. If the Xen package we distribute is for all practical purposes the same as the upstream code, we can refer to the package we distribute as "Xen" in a referential way. + Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. - A referential use is one that describes another entity's goods or services, not our own, such as referring to Microsoft Windows as a technology we compete and integrate with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by the noun, do not use a logo form of the trademark, do not make it more prominent than our own marks, and do not incorporate the trademark into our own product names. Here, the proper use would be "Xen hypervisor." + A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. + @@ -56,7 +57,7 @@ X Windows - Do not use. This is an incorrect reference to the X Window System (or X). + Do not use. It is an incorrect reference to the X Window System (or X). @@ -66,7 +67,7 @@ X Window System - Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if... To start an X session, from the shell prompt..." + Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if ..." "To start an X session, from the shell prompt ..." @@ -86,7 +87,7 @@ you - Correct. Do not use "I," "he," or "she." + Use second person wherever possible. Do not use "I," "we," "he," or "she." @@ -96,7 +97,7 @@ you may - Avoid. For example, "you may" can be eliminated from the following: "You may double-click the desktop..." + Avoid. For example, "you may" can be eliminated from the following sentence: "You may double-click the desktop ..." @@ -106,7 +107,7 @@ zip - See the Word Usage appendix of The IBM Style Guide. + See the Word Usage chapter of The IBM Style Guide. @@ -118,10 +119,13 @@ Correct. Do not use "zip code," "Zip code," or any other variation. + + + From 3e982912f7c4a34be16931cc3b0b6ef44e4a3362 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 9 Jul 2021 11:37:44 +0100 Subject: [PATCH 17/27] Updated A-Z entries. --- en-US/A.xml | 152 +- en-US/B.xml | 4 +- en-US/C.xml | 19 +- en-US/D.xml | 6 +- en-US/Design.xml | 12 +- en-US/F.xml | 4 +- en-US/G.xml | 2 +- en-US/H.xml | 2 +- en-US/I.xml | 2 +- en-US/K.xml | 2 +- en-US/P.xml | 4 +- en-US/S.xml | 2 +- en-US/T.xml | 8 +- en-US/Translation.xml | 2 +- en-US/WUG_References.xml | 2 +- en-US/XYZ.xml | 2 +- tmp/en-US/xml/0-9.xml | 42 + tmp/en-US/xml/A.xml | 329 ++++ tmp/en-US/xml/Author_Group.xml | 18 + tmp/en-US/xml/B.xml | 439 ++++++ tmp/en-US/xml/Book_Design.xml | 146 ++ tmp/en-US/xml/Book_Info.xml | 30 + tmp/en-US/xml/C.xml | 535 +++++++ .../Concepts_Cloud_ExpressFeatures.xml | 33 + .../Concepts_Cloud_FlexFeatures.xml | 27 + tmp/en-US/xml/Common_Content/Conventions.xml | 148 ++ tmp/en-US/xml/Common_Content/Feedback.xml | 63 + .../xml/Common_Content/JBoss_Feedback.xml | 89 ++ tmp/en-US/xml/Common_Content/Legal_Notice.xml | 42 + tmp/en-US/xml/Common_Content/Overview.xml | 53 + .../xml/Common_Content/Program_Listing.xml | 32 + .../Ref_Cloud_Compare_Deployment.xml | 117 ++ .../xml/Common_Content/Revision_History.xml | 32 + .../Conventions_for_Writers_and_Editors.xml | 63 + tmp/en-US/xml/Cross_references.xml | 55 + tmp/en-US/xml/D.xml | 340 +++++ tmp/en-US/xml/Design.xml | 1024 +++++++++++++ tmp/en-US/xml/E.xml | 193 +++ tmp/en-US/xml/Easily_Confused_Words.xml | 92 ++ tmp/en-US/xml/F.xml | 334 +++++ tmp/en-US/xml/Feedback.xml | 13 + tmp/en-US/xml/G.xml | 268 ++++ tmp/en-US/xml/Grammar.xml | 621 ++++++++ tmp/en-US/xml/H.xml | 299 ++++ tmp/en-US/xml/I.xml | 369 +++++ tmp/en-US/xml/J.xml | 72 + tmp/en-US/xml/K.xml | 170 +++ tmp/en-US/xml/L.xml | 265 ++++ tmp/en-US/xml/Language.xml | 1299 ++++++++++++++++ tmp/en-US/xml/M.xml | 309 ++++ tmp/en-US/xml/N.xml | 125 ++ tmp/en-US/xml/O.xml | 270 ++++ tmp/en-US/xml/Objectives.xml | 53 + tmp/en-US/xml/P.xml | 327 ++++ tmp/en-US/xml/Preface.xml | 12 + tmp/en-US/xml/Punctuation.xml | 470 ++++++ tmp/en-US/xml/Q.xml | 52 + tmp/en-US/xml/R.xml | 240 +++ tmp/en-US/xml/Resources.xml | 143 ++ tmp/en-US/xml/Revision_History.xml | 524 +++++++ tmp/en-US/xml/S.xml | 760 ++++++++++ tmp/en-US/xml/Slang.xml | 877 +++++++++++ tmp/en-US/xml/T.xml | 244 +++ tmp/en-US/xml/Template_Chapter.xml | 20 + tmp/en-US/xml/Template_Section.xml | 12 + tmp/en-US/xml/Translation.xml | 373 +++++ tmp/en-US/xml/U.xml | 226 +++ tmp/en-US/xml/V.xml | 137 ++ tmp/en-US/xml/W.xml | 121 ++ tmp/en-US/xml/WUG_Intro.xml | 54 + tmp/en-US/xml/WUG_References.xml | 19 + tmp/en-US/xml/XYZ.xml | 138 ++ tmp/en-US/xml_tmp/0-9.xml | 43 + tmp/en-US/xml_tmp/A.xml | 362 +++++ tmp/en-US/xml_tmp/Author_Group.xml | 18 + tmp/en-US/xml_tmp/B.xml | 437 ++++++ tmp/en-US/xml_tmp/Book_Design.xml | 146 ++ tmp/en-US/xml_tmp/Book_Info.xml | 31 + tmp/en-US/xml_tmp/C.xml | 544 +++++++ .../Conventions_for_Writers_and_Editors.xml | 65 + tmp/en-US/xml_tmp/Cross_references.xml | 57 + tmp/en-US/xml_tmp/D.xml | 343 +++++ tmp/en-US/xml_tmp/Design.xml | 1035 +++++++++++++ tmp/en-US/xml_tmp/E.xml | 195 +++ tmp/en-US/xml_tmp/Easily_Confused_Words.xml | 92 ++ tmp/en-US/xml_tmp/F.xml | 336 +++++ tmp/en-US/xml_tmp/Feedback.xml | 13 + tmp/en-US/xml_tmp/G.xml | 270 ++++ tmp/en-US/xml_tmp/Grammar.xml | 631 ++++++++ tmp/en-US/xml_tmp/H.xml | 302 ++++ tmp/en-US/xml_tmp/I.xml | 382 +++++ tmp/en-US/xml_tmp/J.xml | 72 + tmp/en-US/xml_tmp/K.xml | 170 +++ tmp/en-US/xml_tmp/L.xml | 266 ++++ tmp/en-US/xml_tmp/Language.xml | 1326 +++++++++++++++++ tmp/en-US/xml_tmp/M.xml | 317 ++++ tmp/en-US/xml_tmp/N.xml | 130 ++ tmp/en-US/xml_tmp/O.xml | 275 ++++ tmp/en-US/xml_tmp/Objectives.xml | 54 + tmp/en-US/xml_tmp/P.xml | 327 ++++ tmp/en-US/xml_tmp/Preface.xml | 12 + tmp/en-US/xml_tmp/Punctuation.xml | 478 ++++++ tmp/en-US/xml_tmp/Q.xml | 53 + tmp/en-US/xml_tmp/R.xml | 244 +++ tmp/en-US/xml_tmp/Resources.xml | 145 ++ tmp/en-US/xml_tmp/Revision_History.xml | 524 +++++++ tmp/en-US/xml_tmp/S.xml | 762 ++++++++++ tmp/en-US/xml_tmp/Slang.xml | 876 +++++++++++ tmp/en-US/xml_tmp/T.xml | 250 ++++ tmp/en-US/xml_tmp/Template_Chapter.xml | 20 + tmp/en-US/xml_tmp/Template_Section.xml | 12 + tmp/en-US/xml_tmp/Translation.xml | 383 +++++ tmp/en-US/xml_tmp/U.xml | 227 +++ tmp/en-US/xml_tmp/V.xml | 139 ++ tmp/en-US/xml_tmp/W.xml | 139 ++ tmp/en-US/xml_tmp/WUG_Intro.xml | 54 + tmp/en-US/xml_tmp/WUG_References.xml | 19 + tmp/en-US/xml_tmp/XYZ.xml | 142 ++ 118 files changed, 25986 insertions(+), 115 deletions(-) create mode 100644 tmp/en-US/xml/0-9.xml create mode 100644 tmp/en-US/xml/A.xml create mode 100644 tmp/en-US/xml/Author_Group.xml create mode 100644 tmp/en-US/xml/B.xml create mode 100644 tmp/en-US/xml/Book_Design.xml create mode 100644 tmp/en-US/xml/Book_Info.xml create mode 100644 tmp/en-US/xml/C.xml create mode 100644 tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml create mode 100644 tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml create mode 100644 tmp/en-US/xml/Common_Content/Conventions.xml create mode 100644 tmp/en-US/xml/Common_Content/Feedback.xml create mode 100644 tmp/en-US/xml/Common_Content/JBoss_Feedback.xml create mode 100644 tmp/en-US/xml/Common_Content/Legal_Notice.xml create mode 100644 tmp/en-US/xml/Common_Content/Overview.xml create mode 100644 tmp/en-US/xml/Common_Content/Program_Listing.xml create mode 100644 tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml create mode 100644 tmp/en-US/xml/Common_Content/Revision_History.xml create mode 100644 tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml create mode 100644 tmp/en-US/xml/Cross_references.xml create mode 100644 tmp/en-US/xml/D.xml create mode 100644 tmp/en-US/xml/Design.xml create mode 100644 tmp/en-US/xml/E.xml create mode 100644 tmp/en-US/xml/Easily_Confused_Words.xml create mode 100644 tmp/en-US/xml/F.xml create mode 100644 tmp/en-US/xml/Feedback.xml create mode 100644 tmp/en-US/xml/G.xml create mode 100644 tmp/en-US/xml/Grammar.xml create mode 100644 tmp/en-US/xml/H.xml create mode 100644 tmp/en-US/xml/I.xml create mode 100644 tmp/en-US/xml/J.xml create mode 100644 tmp/en-US/xml/K.xml create mode 100644 tmp/en-US/xml/L.xml create mode 100644 tmp/en-US/xml/Language.xml create mode 100644 tmp/en-US/xml/M.xml create mode 100644 tmp/en-US/xml/N.xml create mode 100644 tmp/en-US/xml/O.xml create mode 100644 tmp/en-US/xml/Objectives.xml create mode 100644 tmp/en-US/xml/P.xml create mode 100644 tmp/en-US/xml/Preface.xml create mode 100644 tmp/en-US/xml/Punctuation.xml create mode 100644 tmp/en-US/xml/Q.xml create mode 100644 tmp/en-US/xml/R.xml create mode 100644 tmp/en-US/xml/Resources.xml create mode 100644 tmp/en-US/xml/Revision_History.xml create mode 100644 tmp/en-US/xml/S.xml create mode 100644 tmp/en-US/xml/Slang.xml create mode 100644 tmp/en-US/xml/T.xml create mode 100644 tmp/en-US/xml/Template_Chapter.xml create mode 100644 tmp/en-US/xml/Template_Section.xml create mode 100644 tmp/en-US/xml/Translation.xml create mode 100644 tmp/en-US/xml/U.xml create mode 100644 tmp/en-US/xml/V.xml create mode 100644 tmp/en-US/xml/W.xml create mode 100644 tmp/en-US/xml/WUG_Intro.xml create mode 100644 tmp/en-US/xml/WUG_References.xml create mode 100644 tmp/en-US/xml/XYZ.xml create mode 100644 tmp/en-US/xml_tmp/0-9.xml create mode 100644 tmp/en-US/xml_tmp/A.xml create mode 100644 tmp/en-US/xml_tmp/Author_Group.xml create mode 100644 tmp/en-US/xml_tmp/B.xml create mode 100644 tmp/en-US/xml_tmp/Book_Design.xml create mode 100644 tmp/en-US/xml_tmp/Book_Info.xml create mode 100644 tmp/en-US/xml_tmp/C.xml create mode 100644 tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml create mode 100644 tmp/en-US/xml_tmp/Cross_references.xml create mode 100644 tmp/en-US/xml_tmp/D.xml create mode 100644 tmp/en-US/xml_tmp/Design.xml create mode 100644 tmp/en-US/xml_tmp/E.xml create mode 100644 tmp/en-US/xml_tmp/Easily_Confused_Words.xml create mode 100644 tmp/en-US/xml_tmp/F.xml create mode 100644 tmp/en-US/xml_tmp/Feedback.xml create mode 100644 tmp/en-US/xml_tmp/G.xml create mode 100644 tmp/en-US/xml_tmp/Grammar.xml create mode 100644 tmp/en-US/xml_tmp/H.xml create mode 100644 tmp/en-US/xml_tmp/I.xml create mode 100644 tmp/en-US/xml_tmp/J.xml create mode 100644 tmp/en-US/xml_tmp/K.xml create mode 100644 tmp/en-US/xml_tmp/L.xml create mode 100644 tmp/en-US/xml_tmp/Language.xml create mode 100644 tmp/en-US/xml_tmp/M.xml create mode 100644 tmp/en-US/xml_tmp/N.xml create mode 100644 tmp/en-US/xml_tmp/O.xml create mode 100644 tmp/en-US/xml_tmp/Objectives.xml create mode 100644 tmp/en-US/xml_tmp/P.xml create mode 100644 tmp/en-US/xml_tmp/Preface.xml create mode 100644 tmp/en-US/xml_tmp/Punctuation.xml create mode 100644 tmp/en-US/xml_tmp/Q.xml create mode 100644 tmp/en-US/xml_tmp/R.xml create mode 100644 tmp/en-US/xml_tmp/Resources.xml create mode 100644 tmp/en-US/xml_tmp/Revision_History.xml create mode 100644 tmp/en-US/xml_tmp/S.xml create mode 100644 tmp/en-US/xml_tmp/Slang.xml create mode 100644 tmp/en-US/xml_tmp/T.xml create mode 100644 tmp/en-US/xml_tmp/Template_Chapter.xml create mode 100644 tmp/en-US/xml_tmp/Template_Section.xml create mode 100644 tmp/en-US/xml_tmp/Translation.xml create mode 100644 tmp/en-US/xml_tmp/U.xml create mode 100644 tmp/en-US/xml_tmp/V.xml create mode 100644 tmp/en-US/xml_tmp/W.xml create mode 100644 tmp/en-US/xml_tmp/WUG_Intro.xml create mode 100644 tmp/en-US/xml_tmp/WUG_References.xml create mode 100644 tmp/en-US/xml_tmp/XYZ.xml diff --git a/en-US/A.xml b/en-US/A.xml index 2927a20..86330f2 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -5,19 +5,32 @@ ]> A + "&" and "+" - Ampersands or plus signs can be used in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. + Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. + + + + + + above + + + Do not use to refer to information that was mentioned previously. + When documents are converted to online format, the information might no longer be "above." + Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. - + + agile agile development @@ -39,25 +52,6 @@ - - - - AM - am - - - Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - - - See also . - - - See The IBM Style Guide for a full discussion of how to represent times. - - - - - all-in-one allinone @@ -69,102 +63,78 @@ - - AMD64 + + + alternate - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. - - - The correct term for AMD's implementation of this architecture is "AMD64." - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + v. "Alternate" as a verb means to change between two states or options. - See also . + See also . - - - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - - - - For more information about Intel® trademarks, see and . - - - - - ATM + + + alternative - Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. - The cell size used with ATM is relatively small compared to units that are used with older technologies. + adj. Describes another way or method of doing something. + "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." + + See also . + - - above - - - Do not use to refer to information that was mentioned previously. - When documents are converted to online format, the information might no longer be "above." - Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. - - - - - - acronyms + + AM + am - An acronym is a word formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. - Note that an acronym is pronounced as a word. - Compare this to an initialism, which is also formed in a similar fashion to an acronym, but in which each letter is pronounced separately. - - - Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK)..." - Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version - for example, "central processing unit (CPU)." - Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". + + See also . + - To form the plural of an acronym, add a trailing, lowercase "s," or "es," for example, ROMs, PINs, BIOSes. + See the IBM Style Guide for a full discussion of how to represent times. ---> - - alternate + + AMD64 - v. "Alternate" as a verb means to change between two states or options. + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. - - See also . - - - - - - - - alternative - - - adj. Describes another way or method of doing something. - "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." + + The correct term for AMD's implementation of this architecture is "AMD64." + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - See also . + See also . + + + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + + + + For more information about Intel® trademarks, see and . + + + @@ -198,6 +168,8 @@ + + --> @@ -350,6 +322,18 @@ + + ATM + + + Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. + The cell size used with ATM is relatively small compared to units that are used with older technologies. + + + + + + - See the Word Usage chapter of The IBM Style Guide for more information. + See the Word Usage chapter of the IBM Style Guide for more information. @@ -242,11 +242,22 @@ + + + colocate, colocation + + + Write unhyphenated, to refer to people or services in the same location. + + + + + combo-box - Do not use as an abbreviation for "combination box." See the relevant entry in The IBM Style Guide for further usage information. + Do not use as an abbreviation for "combination box." See the relevant entry in the IBM Style Guide for further usage information. @@ -312,7 +323,7 @@ command line, command prompt, command-line - See the appropriate entries in The IBM Style Guide for an explanation of how to use these terms. + See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. diff --git a/en-US/D.xml b/en-US/D.xml index 13465c5..dd4085f 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -23,7 +23,7 @@ dash - In technical publications, The IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. + In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. @@ -179,7 +179,7 @@ dialog box - See the Word Usage chapter of The IBM Style Guide for usage information related to this and similar terms. + See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. @@ -216,7 +216,7 @@ disk, disc - Use "compact disc," but "diskette" or "hard disk." See The IBM Style Guide for more information and example use cases. + Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. diff --git a/en-US/Design.xml b/en-US/Design.xml index d1e7347..ed0ba05 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -50,7 +50,7 @@ - See The IBM Style Guide for more information. + See the IBM Style Guide for more information. @@ -79,7 +79,7 @@
Documenting the User Interface - In all cases, see The IBM Style Guide for initial guidance. + In all cases, see the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion.
@@ -120,7 +120,7 @@ - See the UI elements chapter in The IBM Style Guide for more information. + See the UI elements chapter in the IBM Style Guide for more information.
Navigating Through Multiple GUI Options @@ -176,7 +176,7 @@ - See info bash and The IBM Style Guide for further guidance. + See info bash and the IBM Style Guide for further guidance. The following examples are intended to highlight correct usage. @@ -597,7 +597,7 @@ $ vi myFile.txt Choosing a Realistic Name Consider the following points when choosing a realistic name: - Examples taken from The IBM Style Guide and the Google Developer Documentation Style Guide. + Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. @@ -718,7 +718,7 @@ $ vi myFile.txt - Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see The IBM Style Guide or another suitable reference if you are unsure. + Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. diff --git a/en-US/F.xml b/en-US/F.xml index 1f7eebc..452a95b 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -94,7 +94,7 @@ file extensions (general usage) - See File names, file types, and directory names in The IBM Style Guide. + See File names, file types, and directory names in the IBM Style Guide. @@ -104,7 +104,7 @@ file mode, file name, file system, file type - n. Write as shown, two words, unless used as a variable. See The IBM Style Guide for more information. + n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. diff --git a/en-US/G.xml b/en-US/G.xml index 743211f..f07fd91 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -30,7 +30,7 @@ GB - Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or The IBM Style Guide. + Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." diff --git a/en-US/H.xml b/en-US/H.xml index 5ca7062..92d3e4a 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -176,7 +176,7 @@ host name - n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See The IBM Style Guide for more information. + n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. diff --git a/en-US/I.xml b/en-US/I.xml index 50d7a55..2c68839 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -241,7 +241,7 @@ Intranet, intranet - See the "Word usage" appendix of The IBM Style Guide for guidance. + See the "Word usage" appendix of the IBM Style Guide for guidance. diff --git a/en-US/K.xml b/en-US/K.xml index 1e84cf8..8a8b51d 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -10,7 +10,7 @@ KB, kB - See The IBM Style Guide for the correct abbreviation to use for specific use cases. + See the IBM Style Guide for the correct abbreviation to use for specific use cases. diff --git a/en-US/P.xml b/en-US/P.xml index b7a808e..a931ed0 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -29,7 +29,7 @@ n. Use to refer to a personal computer. + See the IBM Style Guide for further information. --> @@ -130,7 +130,7 @@ See also . - See The IBM Style Guide for a full discussion of how to represent times. + See the IBM Style Guide for a full discussion of how to represent times. diff --git a/en-US/S.xml b/en-US/S.xml index 03a69d5..0a76bb9 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -52,7 +52,7 @@ screen capture - n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in The IBM Style Guide. + n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. diff --git a/en-US/T.xml b/en-US/T.xml index 110296d..2609a09 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -20,7 +20,7 @@ tar, tarball - n. See the Word Usage chapter of The IBM Style Guide. + n. See the Word Usage chapter of the IBM Style Guide. @@ -71,7 +71,7 @@ n. Do not use to describe where to type commands. Use "command line" instead. - See the Word Usage chapter of The IBM Style Guide for more information. + See the Word Usage chapter of the IBM Style Guide for more information. @@ -134,7 +134,7 @@ throughput - n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See The IBM Style Guide for more information about using measurements and abbreviations. + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. @@ -176,7 +176,7 @@ 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. - + diff --git a/en-US/Translation.xml b/en-US/Translation.xml index dc40326..435afd5 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -114,7 +114,7 @@ - The following discussion provides some initial insight into using lists correctly. See The IBM Style Guide for a full discussion. + The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion.
diff --git a/en-US/WUG_References.xml b/en-US/WUG_References.xml index 104b229..364183d 100644 --- a/en-US/WUG_References.xml +++ b/en-US/WUG_References.xml @@ -6,7 +6,7 @@ References - The IBM Style Guide + the IBM Style Guide Chicago Manual of Style, 17th Edition diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index 97ca19e..cce5486 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -107,7 +107,7 @@ zip - See the Word Usage chapter of The IBM Style Guide. + See the Word Usage chapter of the IBM Style Guide. diff --git a/tmp/en-US/xml/0-9.xml b/tmp/en-US/xml/0-9.xml new file mode 100644 index 0000000..074bdab --- /dev/null +++ b/tmp/en-US/xml/0-9.xml @@ -0,0 +1,42 @@ + + +%BOOK_ENTITIES; +]> + + 0-9 + + + 24x7, 24x7x365 + + + adj. Use "24x7" in most instances. Use "24x7x365" only to differentiate from others or highlight specifically that a service is offered every day of the year, for example, providing 24x7x365 phone support. + + + + + + + 2-track (IT) + + + adj. A less common way to refer to bimodal or hybrid IT. See . + + + + + + + 3-D + + + adj., n. Correct. Do not use 3D, 3-d, or other variations. + + + + + + + + + diff --git a/tmp/en-US/xml/A.xml b/tmp/en-US/xml/A.xml new file mode 100644 index 0000000..713db89 --- /dev/null +++ b/tmp/en-US/xml/A.xml @@ -0,0 +1,329 @@ + + +%BOOK_ENTITIES; +]> + + A + + + "&" and "+" + + + Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. + + + + + + + above + + + Do not use to refer to information that was mentioned previously. When documents are converted to online format, the information might no longer be "above." Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. + + + + + + + agile + agile development + + + adj. Use only as an adjective. It is not a proper noun, nor is it owned or trademarked and should not be capitalized. + + + + + + + air gap + air wall + + + n. Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall." "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist. + + + + + all-in-one + allinone + + + n., adj. Hyphenate in both places. Do not use "allinone" or other variations. + + + + + + + alternate + + + v. "Alternate" as a verb means to change between two states or options. + + + See also . + + + + + + + alternative + + + adj. Describes another way or method of doing something. "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." + + + See also . + + + + + + + + + AM + am + + + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". + + + See also . + + + See the IBM Style Guide for a full discussion of how to represent times. + + + + + + + AMD64 + + + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. + + + The correct term for AMD's implementation of this architecture is "AMD64." When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + + + See also . + + + + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + + + For more information about Intel® trademarks, see and . + + + + + + + + + and/or + + + Avoid if possible. Try to rewrite to make the available options explicit and clear. Do not write this and/or that. Write this or that, or both. + + + + + + + Applixware + Applix + ApplixWare + + + "Applixware" is correct. Do not use "Applix" or "ApplixWare." + + + + + + + architect + + + Do not use as a verb. Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience. Use "design," "build," "create," or another descriptive verb instead. Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning. For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." + + + + + + + as well as + + + Not interchangeable with "and." "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. For example, "We sell kitchen electronics and china, as well as some gourmet foods." But "We sell kitchen electronics, china, and silverware." + + + + + + + as-a-Service + + + Some as-a-Service acronyms overlap. To avoid confusion, always spell out the full term on first use. + + + + + DRaaS (Disaster Recovery-as-a-Service) + + + + + + CaaS (Cloud-as-a-Service, Communications-as-a-Service, ) + + + + + + UCaaS (Unified Communications-as-a-Service) + + + + + + FaaS (Functions-as-a-Service) + + + + + + SaaS (Search-as-a-Service, Security-as-a-Service, Storage-as-a-Service, or Software-as-a-Service) + + + + + + PaaS (Payments-as-a-Service, Platform-as-a-Service) + + + + + + MaaS (Messaging-as-a-Service) + + + + + + SECaaS (Security-as-a-Service) + + + + + + TDBaaS (Time-series Database-as-a-Service) + + + + + + + When using as-a-Service acronyms: + + + + + Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out. + + + + + + When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS). + + + + + + Hyphenate when written out: Thing-as-a-Service. For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. + + + + + + Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service. + + + + + + + + + + + as long as + + + Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that". + + + + + + + ATM + + + Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. The cell size used with ATM is relatively small compared to units that are used with older technologies. + + + + + + + autofs + + + Always lowercase. It refers to the kernel-based automount utility. No other forms are recognized. + + + + + + + + + diff --git a/tmp/en-US/xml/Author_Group.xml b/tmp/en-US/xml/Author_Group.xml new file mode 100644 index 0000000..c0e52a9 --- /dev/null +++ b/tmp/en-US/xml/Author_Group.xml @@ -0,0 +1,18 @@ + + +%BOOK_ENTITIES; +]> + + + Red Hat Documentation Team + + + + + + + + + + diff --git a/tmp/en-US/xml/B.xml b/tmp/en-US/xml/B.xml new file mode 100644 index 0000000..60017d6 --- /dev/null +++ b/tmp/en-US/xml/B.xml @@ -0,0 +1,439 @@ + + +%BOOK_ENTITIES; +]> + + B + + + back end, back-end + + + n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls." + + + adj. Hyphenate. For example, "when the back-end database processes a search operation …" + + + Do not use "backend." + + + See also + + + + + + + backup, back up + + + Write as one word as an adjective or noun, or as two words as a verb. + + + + + adj. One word. For example, "store the backup copies of important files in a secure location." + + + + + + n. One word. For example, "create a backup of your important files." + + + + + + v. Two words. For example, "always back up important files." + + + + + + + Do not use the hyphenated form, "back-up." + + + + + + + backtrace + + + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + + + + + + + backwards + + + Avoid using "backwards" unless you are stating that something has "backwards compatibility." + + + + + + + backwards compatible + + + Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also . + + + + + + + bandwidth + + + Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed time. + + + + + + + bare metal, bare-metal + + + n. Two words. + + + adj. Hyphenate. + + + + + + + basically + + + Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . + + + + + + + because, since, as + + + Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" and "as" to indicate the passage of time. + + + + + + + below + + + Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead. + + + + + + + big data + + + n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. + + + + + + + bimodal IT + + + Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. Many ways exist to describe this combination approach; be sure to use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those who are not familiar with Gartner's phrasing. + + + The practice of having both modes together is often referred to as hybrid, agile, or modern IT. + + + + Hybrid IT is a more general term, for example it could mean on-premises plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination that you mean. + + + + + + + + + biannual, bimonthly, biweekly, semiweekly, semimonthly + + + People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. + + + Instead of biweekly, write "every two weeks" or "every other week." + + + Instead of semiweekly, write "twice a week." + + + + + + + BIND + + + Correct when referring to the DNS software. Do not use Bind. + + + + + + + BIOS + + + Correct. The plural form is BIOSes. + + + + + + + bit rate + + + Correct. Do not use "bitrate." + + + + + + + Boolean + + + Correct. Named after George Boole, who first developed the concept. + + + According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. + + + + + + + boot + + + v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software to load during the boot process. + + + n. Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. + + + Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started. + + + + + + + boot disk + + + Two words. Do not use "boot diskette." + + + + + + + boot loader + + + Two words. Do not use "bootloader." + + + + + + + bottleneck + + + One word. Do not use "bottle neck" or "bottle-neck." + + + A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system. + + + + + + + bpp + + + Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16 bpp," not "16bpp." + + + + + + + Bps, bps + + + The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . + + + + + + + breadcrumb trail + + + See the IBM Style Guide for initial guidance on how to use this term. + + + + Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path that is taken to reach the current page. + + + + + + + Example breadcrumb trail, showing Disks as the actual name of the page. + + + + + + + + + + + break + + + (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail." + + + + + + + bring up + + + Do not use. Use "open" instead. + + + + + + + Britain + + + If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland. + + + + + + + broadcast + + + To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. + + + In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a selected list of recipients. + + + + + + + Btrfs + + + A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. + + + See for more information on this file system. + + + See for a list of file system names and how to present them. + + + + + + + bug fix + + + Two words. Do not use "bugfix." + + + + + + + built-in + + + adj. Hyphenate. Do not use "builtin" unless referring specifically to "Bash builtins" or if it is otherwise a proper noun. + + + + + + + bunches of + + + Do not use, unless "bunch" is a specific term that is used in the documented software. Use "many" or some other alternative instead. + + + + + + + button + + + Describe a GUI button as a "button," not a "pushbutton" or "push-button." + + + Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link." + + + See also . + + + + + + + + + diff --git a/tmp/en-US/xml/Book_Design.xml b/tmp/en-US/xml/Book_Design.xml new file mode 100644 index 0000000..fd6995c --- /dev/null +++ b/tmp/en-US/xml/Book_Design.xml @@ -0,0 +1,146 @@ + + +%BOOK_ENTITIES; +]> +
+ Overall Book Design + + This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. + + + This section covers the following topics: + + + + Titles and subtitles + + + + + + Prefaces + + + + + + Abstracts + + + + + + Introductions + + + + + + Unused heading titles + + + + + + + +
+ Titles and Subtitles + + The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". + + + The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". + + +
+
+ Prefaces + + The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update. + + +
+
+ Abstracts + + Abstracts for Red Hat technical documentation typically fall under the heading of a "descriptive abstract." From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form." + + + + + + A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: + + + + What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." + + + + + + How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." + + + + + + Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + + + + + + + + + Drawing these basics together might produce the following example abstract: + + + "The Red Hat Satellite 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." + + + Update or modify each component according to the type of book that you are writing. + + +
+
+ Introductions + + The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. + + +
+
+ Unused Heading Titles + + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. + + + Overview + + Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. + + + + + About + + Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview." + + + + + Chapter and Section Introductions + + Do not create separate introductions for chapters and sections. Use any material that would constitute an introductory section to form body text following the chapter or section title. + + + + +
+ +
+ diff --git a/tmp/en-US/xml/Book_Info.xml b/tmp/en-US/xml/Book_Info.xml new file mode 100644 index 0000000..417bb28 --- /dev/null +++ b/tmp/en-US/xml/Book_Info.xml @@ -0,0 +1,30 @@ + + +%BOOK_ENTITIES; +]> + + Conventions for Writers and Editors + The Red Hat Style Guide + + 4.2 + 1 + + + The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml/C.xml b/tmp/en-US/xml/C.xml new file mode 100644 index 0000000..7f023d3 --- /dev/null +++ b/tmp/en-US/xml/C.xml @@ -0,0 +1,535 @@ + + +%BOOK_ENTITIES; +]> + + C + + + can, may + + + Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If any of "can," "could," or "may" apply, use "can"; it is less tentative. + + + + + + + cannot + + + Correct, as one word, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." + + + + + + + CapEx, OpEx + + + Correct. These stand for "capital expenditures" and "operating expenses" respectively. Do not use alternative capitalization. + + + + + + + cd, CD + + + When referring to the change directory command, use cd. + + + When referring to a compact disk, use "CD." For example, "Insert the CD into the CD drive." The plural is "CDs." + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + CD #1 + + + When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1. + + + + + + + Ceph + + + Correct. Ceph is a distributed storage platform that provides object, block, and file storage. + See + + Do not use alternative capitalization. + + + + + + + cgroup + + + Correct (all lowercase) when referring to the kernel-based technology. It is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. It is therefore permissible to capitalize it if used at the beginning of a sentence. + + + Where cgroup refers to something else, for example, a package name, file name, and so on, use a literal rendition. + + + + + + + characters + + + Do not use "characters" to mean "bytes." In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. + + + In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. + + + + + + + check + + + Avoid. Use "verify," "ensure," or "read," depending on the context. + + + + + + + check box + + + n. Two words. Do not use "checkbox" or "check-box." + + + + + + + chipset + + + n. One word. Do not use "chip set" or "chip-set." + + + + + + + CI/CD + + + Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. + + + See also , , . + + + + + + + ciphertext + + + n. One word. Do not use "cipher text", "cipher-text", or other variants. + + + + + + + click + + + v. Use when referring to a GUI control button, for example, "Click OK." Do not use "click on". + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + client-side, client side + + + adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." + + + n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." + + + + + + + clobber, clobbered + + + Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the context. + + + + + + + cloud + + + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." + + + + + + + cloudbursting + + + Define briefly on first use. + + + Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization pays only for extra computing resources when they are needed. + + + + + + + + + + cloudwashing + + + Define briefly on first use. + + + Refers to the process of rebranding legacy products to include the term "cloud" to increase their appeal to the cloud market, even if such inclusion is not completely justified. + + + + + + + code + + + n. Use only as a noun, not a verb. Use "write" for a verb. + + + + + + + colocate, colocation + + + Write unhyphenated, to refer to people or services in the same location. + + + + + + + combo-box + + + Do not use as an abbreviation for "combination box." See the relevant entry in the IBM Style Guide for further usage information. + + + + + + + comma-delimited + + + adj. Correct (compound adjective). A data format in which each piece of data is separated by a comma. This is a popular format for transferring data from one application to another, because most database systems are able to import and export comma-delimited data. + + + + + + + comma-separated values (CSV) + + + Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information that is broken up through use of commas. This method is often used to share data between different, but similar applications, wherein the comma is a translator of the data. + + + + + + + command button + + + Use "button" instead. + + + + + + + command-driven + + + adj. Correct (compound adjective). Do not use "command driven" or "commanddriven." + + + Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. + + + + + + + command language + + + n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. + + + With graphical user interfaces, the command language consists of operations that you perform with a mouse or similar input device. + + + + + + + command line, command prompt, command-line + + + See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + + + + + + + commodity + + + Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and might imply that it is cheap. Use instead: + + + + + Volume + + + + + + Industry-standard + + + + + + + + + + + communication service provider (CSP) + + + Another way to refer to a telecommunications provider. See also . + + + + + + + Containers-as-a-Service + + + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . + + + + + + + container-based + + + Used to refer to more complex applications with multiple services that are distributed in containers. More common than "containerized." + + + + + + + containerized + + + Used to refer to an application or service that is distributed in a container or packed in a container. + + + + + + + continuous delivery (CD) + + + A software implementation architecture that ensures that all approved code can be easily pushed to production. + + + + + + + continuous deployment + + + A special case of continuous delivery, where approved code is automatically pushed to production. Do not use "CD" to refer to this practice. + + + + + + + continuous integration (CI) + + + A software development architecture where the developer code branch is synchronized with the main code branch multiple times per day. Development always works with the current code base. + + + + + + + control character + + + A special, non-printing character that begins, modifies, or ends a function, event, operation, or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. + + + + + + + control key + + + Use Ctrl instead, such as "To save the program, press CtrlS." + + + + + + + control program + + + A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows. + + + Control programs are also called operating environments. + + + + + + + cookie + + + n. A message given to a web browser by a web server. The browser stores the message in a text file named cookie.txt. The message is then sent back to the server each time the browser requests a page from the server. + + + + + + + CR + + + Use if referring to code, such as "Type CR at the end of each line ..." If referring to the keyboard key, use either Enter or Return, depending on the platform. + + + + + + + crash + + + IBM recommends the use of "fail" rather than "crash." Use the latter only if you can justify why "fail" is inadequate. + + + + + + + cross-platform + + + adj. Hyphenate. Do not use "crossplatform" or "cross platform." + + + Refers to the capability of software or hardware to run identically on different platforms. + + + + + + + cross-site scripting + + + Correct. When referring to cross-site scripting attacks, use "cross-site scripting attack." Acceptable use is also "cross-site scripting (XSS) attack." + + + + + + + CVE + + + n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. See for more information. + + + + + + + Cygmon + + + Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). + + + Refer to it as "Cygmon: a ROM monitor," not "Cygmon: the Cygnus ROM monitor," or "Cygmon: the ROM monitor." + + + + + + + + + diff --git a/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml b/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml new file mode 100644 index 0000000..8708261 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml @@ -0,0 +1,33 @@ + + +%BOOK_ENTITIES; +]> + + + + Start managing your cloud applications for free + + + + + + Deploy your applications to the cloud at no extra cost + + + + + + Access your logs, databases, and file I/O, in the cloud + + + + + + Easily migrate components across OpenShift offerings using its consistent framework across deployment levels + + + + + + diff --git a/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml b/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml new file mode 100644 index 0000000..a4e94c7 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml @@ -0,0 +1,27 @@ + + +%BOOK_ENTITIES; +]> + + + + Start your cloud environment with IaaS time free with a trial period + + + + + + Migrate existing applications with minimal modifications + + + + + + Enhance application performance with system access + + + + + + diff --git a/tmp/en-US/xml/Common_Content/Conventions.xml b/tmp/en-US/xml/Common_Content/Conventions.xml new file mode 100644 index 0000000..1a9cf35 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Conventions.xml @@ -0,0 +1,148 @@ + + +%BOOK_ENTITIES; +]> +
+ Document Conventions + + This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. + +
+ Typographic Conventions + + Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows. + + + Mono-spaced Bold + + + Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example: + +
+ + To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. + + +
+ + The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. + + + Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example: + +
+ + Press Enter to execute the command. + + + Press CtrlAltF2 to switch to a virtual terminal. + + +
+ + The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously. + + + If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example: + +
+ + File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. + + +
+ + Proportional Bold + + + This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example: + +
+ + Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). + + + To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar. + + +
+ + The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. + + + Mono-spaced Bold Italic or Proportional Bold Italic + + + Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: + +
+ + To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com. + + + The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. + + + To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. + + +
+ + Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. + + + Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: + +
+ + Publican is a DocBook publishing system. + + +
+ +
+
+ Pull-quote Conventions + + Terminal output and source code listings are set off visually from the surrounding text. + + + Output sent to a terminal is set in mono-spaced roman and presented thus: + + +books Desktop documentation drafts mss photos stuff svn +books_tests Desktop1 downloads images notes scripts svgs + + Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows: + + + +
+
+ Notes and Warnings + + Finally, we use three visual styles to draw attention to information that might otherwise be overlooked. + + + + Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier. + + + + + + Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration. + + + + + + Warnings should not be ignored. Ignoring warnings will most likely cause data loss. + + + + +
+
+ diff --git a/tmp/en-US/xml/Common_Content/Feedback.xml b/tmp/en-US/xml/Common_Content/Feedback.xml new file mode 100644 index 0000000..0a80e45 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Feedback.xml @@ -0,0 +1,63 @@ + + +%BOOK_ENTITIES; +]> +
+ Getting Help and Giving Feedback +
+ Do You Need Help? + + help + getting help + + + + If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at . From the Customer Portal, you can: + + + + + Search or browse through a knowledge base of technical support articles about Red Hat products. + + + + + + Submit a support case to Red Hat Global Support Services (GSS). + + + + + + Access other product documentation. + + + + + + + Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at . Click the name of any mailing list to subscribe to that list or to access the list archives. + + +
+
+ We Need Feedback + + feedback + contact information for this manual + + + + If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you. Please submit a report in Bugzilla: http://bugzilla.redhat.com/ against the product &PRODUCT;. + + + When submitting a bug report, be sure to mention the manual's identifier: &BOOKID; + + + If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily. + + +
+
+ diff --git a/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml b/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml new file mode 100644 index 0000000..3601473 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml @@ -0,0 +1,89 @@ + + +%BOOK_ENTITIES; +]> +
+ Getting Help and Giving Feedback +
+ Do You Need Help? + + help + getting help + + + + If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at . From the Customer Portal, you can: + + + + + Search or browse through a knowledge base of technical support articles about Red Hat products. + + + + + + Submit a support case to Red Hat Global Support Services (GSS). + + + + + + Access other product documentation. + + + + + + + Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at . Click the name of any mailing list to subscribe to that list or to access the list archives. + + +
+
+ Give us Feedback + + feedback + contact information for this manual + + + + If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product &BZPRODUCT; and the component &BZCOMPONENT;. The following link will take you to a pre-filled bug report for this product: &BZURL;. + + + Complete the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly. + + +Document URL: + + +Section Number and Name: + + +Describe the issue: + + +Suggestions for improvement: + + +Additional information: + + + + + Be sure to give us your name so that you can receive full credit for reporting the issue. + + +
+ +
+ diff --git a/tmp/en-US/xml/Common_Content/Legal_Notice.xml b/tmp/en-US/xml/Common_Content/Legal_Notice.xml new file mode 100644 index 0000000..21a433e --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Legal_Notice.xml @@ -0,0 +1,42 @@ + + +%BOOK_ENTITIES; +]> + + + Copyright &YEAR; &HOLDER;. + + + This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. + + + Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. + + + Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Infinity logo, JBoss, OpenShift, Fedora, Hibernate, Ansible, CloudForms, RHCA, RHCE, RHCSA, Ceph, and Gluster are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the United States and other countries. + + + Linux is the registered trademark of Linus Torvalds in the United States and other countries. + + + Java is a registered trademark of Oracle and/or its affiliates. + + + XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. + + + MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. + + + Node.js is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. + + + The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. + + + All other trademarks are the property of their respective owners. + + + + diff --git a/tmp/en-US/xml/Common_Content/Overview.xml b/tmp/en-US/xml/Common_Content/Overview.xml new file mode 100644 index 0000000..23a6162 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Overview.xml @@ -0,0 +1,53 @@ + + +%BOOK_ENTITIES; +]> + + OpenShift Overview + + The OpenShift deployment model currently offers two user levels: + + + + + OpenShift Express + + + + + + OpenShift Flex + + + + + + + Each OpenShift deployment level offers specific cloud and application management features. The following table compares the features of each OpenShift deployment level: + + +
+ OpenShift Express + + OpenShift Express provides the tools to create, deploy and manage your applications in the cloud using a browser-based or a command line interface. With OpenShift Express you can: + + + +
+
+ OpenShift Flex + + OpenShift Flex provides a graphical user interface (GUI) that you can use to create, deploy, configure, manage and monitor your cloud environment. With OpenShift Flex you can: + + + +
+ + + diff --git a/tmp/en-US/xml/Common_Content/Program_Listing.xml b/tmp/en-US/xml/Common_Content/Program_Listing.xml new file mode 100644 index 0000000..81cce23 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Program_Listing.xml @@ -0,0 +1,32 @@ + + +%BOOK_ENTITIES; +]> + +static int kvm_vm_ioctl_deassign_device(struct kvm *kvm, + struct kvm_assigned_pci_dev *assigned_dev) +{ + int r = 0; + struct kvm_assigned_dev_kernel *match; + + mutex_lock(&kvm->lock); + + match = kvm_find_assigned_dev(&kvm->arch.assigned_dev_head, + assigned_dev->assigned_dev_id); + if (!match) { + printk(KERN_INFO "%s: device hasn't been assigned before, " + "so cannot be deassigned\n", __func__); + r = -EINVAL; + goto out; + } + + kvm_deassign_device(kvm, match); + + kvm_free_assigned_device(kvm, match); + +out: + mutex_unlock(&kvm->lock); + return r; +} + diff --git a/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml b/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml new file mode 100644 index 0000000..66cc349 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml @@ -0,0 +1,117 @@ + + +%BOOK_ENTITIES; +]> +
+ Example breadcrumb trail, showing Disks as the actual name of the page. + +
+ Deployment Model Comparison + + + + + + + Feature + OpenShift Express + OpenShift Flex + + + + + + + Command Line Interface + Yes + No + + + + GUI Interface + Yes + Yes + + + + Create Cloud Objects + No + Yes + + + + Manage Cloud Objects + No + Yes + + + + Create Clusters + No + Yes + + + + Manage Clusters + No + Yes + + + + Create Servers + No + Yes + + + + Manage Servers + No + Yes + + + + Create Applications + Yes + Yes + + + + Manage Applications + Yes + Yes + + + + Import Applications + No + Yes + + + + Customize Applications + Yes + Yes + + + + Deploy Applications + Yes + Yes + + + + View Cloud Performance Statistics + No + Yes + + + + View Historical Cloud Performance Statistics + No + Yes + + + + + + +
+ diff --git a/tmp/en-US/xml/Common_Content/Revision_History.xml b/tmp/en-US/xml/Common_Content/Revision_History.xml new file mode 100644 index 0000000..b3edc69 --- /dev/null +++ b/tmp/en-US/xml/Common_Content/Revision_History.xml @@ -0,0 +1,32 @@ + + +%BOOK_ENTITIES; +]> + + Revision History + + + + 3.0-0 + Mon Mar 12 2012 + + Jeff + Fearn + jfearn@redhat.com + + + + Publican 3.0 + + + + + + + + + + + + diff --git a/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml b/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml new file mode 100644 index 0000000..7043c32 --- /dev/null +++ b/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml @@ -0,0 +1,63 @@ + + +%BOOK_ENTITIES; +]> + + + + + Writing Style Guide + + + Recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. + + + + + + + + + + + + + + Usage Dictionary + + + The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml/Cross_references.xml b/tmp/en-US/xml/Cross_references.xml new file mode 100644 index 0000000..5db1fa9 --- /dev/null +++ b/tmp/en-US/xml/Cross_references.xml @@ -0,0 +1,55 @@ + + +%BOOK_ENTITIES; +]> + + Using Cross-references Effectively + + This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. Formatting is not described in this section. + + + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. + +
+ The Additional Information Test + + Is the cross-reference pointing to vital information or additional information? + + + A cross-reference should always point to additional information, not to core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure, provide a link to the appendix. + + +
+ +
+ The Repeatability Test + + Must the information be repeated? + + + 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. + + + Cross-referencing is a good servant but a poor master. Content still rules! + + +
+ + + diff --git a/tmp/en-US/xml/D.xml b/tmp/en-US/xml/D.xml new file mode 100644 index 0000000..c455413 --- /dev/null +++ b/tmp/en-US/xml/D.xml @@ -0,0 +1,340 @@ + + +%BOOK_ENTITIES; +]> + + D + + + daisy chain + + + n. A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. + + + v. To connect devices in a daisy chain pattern. + + + + + + + dash + + + In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. + + + + + + + data center, datacenter + + + n. Use the two-word form unless referring to a product name or other proper noun where the one-word form is used. + + + Marketing Publications Exception + + In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used. + + + + + + + + + data mirroring + + + The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information that is stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a different location. + + + + + + + data sheet, datasheet + + + n. Use the two-word form. + + + Marketing Publications Exception + + In marketing publications, the one-word form is recommended. + + + + + + + + + data source + + + n. Use the two-word form unless referring to a proper noun, argument, variable, or other case where the one-word form is required. + + + + + + + data store, datastore + + + n. Use the two-word form. + + + Marketing Publications Exception + + In marketing publications, the one-word form is recommended. + + + + + + + + + data type + + + n. Do not use "datatype" or "data-type" unless they are variable names or some other literal value. + + + + + + + debug + + + To find and remove errors (bugs) from a program or design. + + + + + + + denial of service (DoS) + + + Correct. Do not use "denial-of-service" or "Denial of Service." + + + + + + + desktop + + + Correct. Do not use "desk top" or "desk-top." + + + + + + + device + + + Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer. + + + Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. + + + + + + + DevOps + + + n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps can also refer to the engineers and developers who work within these modern IT organizations. + + + + + + + dialog box + + + See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. + + + + + + + different + + + Use "different from" rather than "different than" when the next part of the sentence is a noun or pronoun (that is, two things are being compared). For example: "Form 123 is different from Form 124." + + + + + + + digital transformation + + + Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. + + + + + + Disk Druid + + + Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. + + + + + + + disk, disc + + + Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. + + + + + + + disk label + + + Correct. Do not use "disklabel" or any other variations. + + + + + + + display + + + v. Use only as a transitive verb. For example, write "the system displays a message" or "the message is displayed" (not "the message displays"). + + + + + + + DNS + + + Initialism of Domain Name System (or Service), an internet service that translates domain names into IP addresses. + + + + + + + documentation + + + When referring to the current manual set, use "documentation." For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." + + + + + + + domain name + + + Correct. Do not use "domainname" or "domain-name." + + + A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com. + + + + + + + double-click + + + v. Always write hyphenated. + + + + + + + downstream + + + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." + + + + + + + downtime + + + Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." + + + + + + + download + + + v., n. Do not use "down load" or "down-load." + + + + + + + dual-boot + + + adj. Do not use "dualboot" or "dual boot." + + + + + + + DVD writer + + + Correct. Do not use the colloquial terms "DVD burner" or "CD burner" (use CD writer in the latter case). + + + + + + + + + diff --git a/tmp/en-US/xml/Design.xml b/tmp/en-US/xml/Design.xml new file mode 100644 index 0000000..ae26cd7 --- /dev/null +++ b/tmp/en-US/xml/Design.xml @@ -0,0 +1,1024 @@ + + +%BOOK_ENTITIES; +]> + + Design + +
+ Heading Styles + + This section covers various aspects of heading styles and design. If your company or organization has specific requirements in this regard, follow those requirements first. + + + Capitalization + + The standard for all Red Hat technical documentation is title case for all headings and titles. Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. The currently accepted reference for determining title case is at https://titlecase.com/titlecase. + + + + + Use sentence case for captions, legends, diagram labels, and table column headers. They are not classified as titles. + + + Marketing and Brand Capitalization Guide + + The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. + + + + + Punctuation + + Be frugal with punctuation. In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. Do not use terminating periods. + + + + + Avoid Imperative Mood + + Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". + + + + + See the IBM Style Guide for more information. + + + + Gerunds should be avoided elsewhere. See . + + + + + File Names, Commands, and Related Terms + + When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. + + + + +
+
+ Documenting Fonts + + The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. + + +
+
+ Documenting the User Interface + + In all cases, see the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion. + +
+ GUI Elements, Punctuation, and Symbols + + When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. + + + For example, for a button labeled Save As..., do not include the ellipsis in the documentation. + + + In most cases, do not include the object type in instructions. For example, rather than "Click the Save button," write "Click Save." + + + In some cases it is preferred practice to include the object type for the sake of clarity. Consider the following: + + + Preferred Style for Documenting Symbols and Other Special Characters + + Click the + sign. + + + Click the ^ symbol. + + + + + If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. Use this approach for icons, especially when they have no tooltip or other help text. + + + Preferred Style for Documenting Icons + + Click the Upload ( + + + + + + + ) icon to upload the files to the server. + + + + + See the UI elements chapter in the IBM Style Guide for more information. + +
+ Navigating Through Multiple GUI Options + + Use "Navigate to" when moving through multiple GUI 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. + + + From example, "From the OpenShift web console, navigate to Monitoring → Alerting." + + +
+ +
+
+ Starting Applications from the Desktop + + This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. + + + RHEL 8 uses the following approach to starting applications from the desktop. In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. + + + The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: + + + Preferred Approach to Starting Applications from the Desktop + + To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. + + + + +
+
+ Documenting Command Terminology and Syntax + + Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here. + + + When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses. Never use "flag" when referring to command-line options in POSIX, even though Microsoft often uses the term "flag" when referring to single-character options in Microsoft Windows. + + + The following extract from info libc is of particular interest here: + +
+ + "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on. + + + See info libc argument syntax for the full discussion. + + +
+ + See info bash and the IBM Style Guide for further guidance. + + + The following examples are intended to highlight correct usage. + + + Cloning a Git Repository + + +$ git clone [username@]hostname:/repository_filename [directory] + + + + + + In , the entire command consists of the following components: + + + + The prompt ($) + + + Indicates that a normal user can run the command, as compared to the root user, which would be indicated by the number sign (#). + + + + + + + The command (git clone) + + + The actual command to run, without any optional or replaceable values. It must be typed as-is. + + + + + + + Source options [username@]hostname:/repository_filename) + + + The optional user name, indicated by brackets ([]), followed by the host name and path to the repository. All aspects of this component must be replaced with valid values. + + + + + + + Target options [directory] + + + The optional directory into which the repository will be cloned. It must be replaced with a valid value, or be omitted. + + + + + + + + + Securely Copying a File Between Hosts + +$ scp filename [username@]hostname:/directory + + + + In , the entire command consists of the following components: + + + + The command prompt ($) + + + + + + + + + + The command (scp) + + + + + + + + + + Source options (filename) + + + The file name to copy. It must be replaced with a valid value. + + + + + + + Target options ([username@]hostname:/directory) + + + The optional user name, indicated by brackets ([]), followed by the host name and path to the target directory. All aspects of this component must be replaced with valid values. + + + + + + + + + + In most cases, avoid using the and options on most commands, especially when logged in as the root 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: + + +[root@serverc pam.d]# rm -f system-auth password-auth +[root@serverc ~]# yum install -y new-package + + + In these examples, omit the and options, respectively. + + + In some cases, such as in Ansible Playbooks or other automation scripts, it might be necessary to use these options. + + + +
+ Documenting Multiple or Long Commands + + 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, include the commands on consecutive lines: + + + Documenting Multiple Commands + +$ cd Documents +$ vi myFile.txt + + + + + If the commands are long, complex, or wrap over multiple lines, two design options are available. + + + + + Use line continuation characters and the associated PS2 prompts. If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit. + + + + + + Use neither line continuation characters nor the associated PS2 prompts. + + + + + + + + Do not mix these two styles. Maintain the same style throughout your document or book. + + + + + You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. You can use this option for either of these two designs. + + + Wrapping Long Commands with Continuation Characters + + This example uses both continuation characters and PS2 prompts. These indicators are always used together. + + +# tar --selinux -czvf config_files.tar.gz /etc/katello \ +> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ +> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ +> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ +> /root/ssl–build /var/www/html/pub/* /var/lib/katello + + + + Wrapping Long Commands Without Continuation Characters + + This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. + + +# cd /var/lib/katello + +# myCommand --option funky --color=true + --config_file=<replaceable>/home/user/config.conf</replaceable> + --output_file=<replaceable>/home/user/output.txt</replaceable> + + + +
+
+ Referring to Replaceable Paths + + To refer to a path that users need to replace with something that is specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. Use a leading slash if the absolute path is required. + + + Referring to Replaceable Paths on Linux Systems + + "Mount the ISO file in <filename><replaceable>/path/to/iso/file</replaceable></filename>." + + + + + Remember to use the appropriate syntax for the system that you are documenting or describing. + + + Referring to Replaceable Paths on Microsoft Windows Systems + + "Mount the ISO file in <filename><replaceable>C:\path\to\iso\file</replaceable></filename>." + + + + + If you are referring to a different object class or type with different delimiters, use the appropriate delimiters. For example: + + + A PATH variable for Bash might appear as <replaceable>/usr/bin:/usr/local/bin</replaceable>. + + + A package path in Lua might appear as <replaceable>local.share.lua</replaceable>. + + +
+ +
+
+ Using Escalated Privileges Correctly + + + This section is aimed primarily at Red Hat Training course material, but the principles and guidelines apply equally in any environment. + + + + + The term escalated privileges 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. + + + Classroom Exceptions + + Although security is important, it is more important that classroom security does not unnecessarily distract from the immediate topic that is being taught. + + + +
+ General Recommendations + + + These are recommendations, not rules. As in most matters, consistency is important. Do not swap between different approaches without reason. Choose which approach works best for your situation and use it consistently. + + + + + + + In all cases, use the minimum required privilege level to achieve the task. + + + + + + In exercises, use sudo and sudo -i and set it up to work throughout all relevant systems in the classroom. Do not use su - without good cause. + + + + + + When a scattered minority of privileged commands occur in a mostly unprivileged exercise, use sudo on a per-command basis. + + + + + + When the exercise is majority privileged, or has many privileged commands, use sudo -i, either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. + + + + + + In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. See for information about command prompts. + + + + + + +
+
+ Exceptions + + Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers, and so on. For these courses, use the required variation for the topic that is being taught. + +
+ Ansible Courses + + + + Ansible courses typically use a devops user with passwordless sudo access (devops ALL=(ALL) NOPASSWD: ALL) on managed nodes to enable the use of become without a become password as root to do anything. + + + + + + As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. + + + + + + If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. + + + + + + +
+ +
+ +
+
+ Describing How to View and Edit Files + + To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. + + + For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. + + + If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. + + + You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. + + + my-script +> # The first line of text +> # The second line +> # Start adding variables after this line +> EOF]]> + + In some cases, it is necessary to indicate which tool to use to view a file, especially for log files and other long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl. + + +
+
+ Using Host and User Names Correctly + + Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. + + + + All names are lowercase. Do not use white space in any part of the name. + + + + + + + Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. + + + + Do not use valid, public IP addresses in any examples. + + + + + + + + As much as possible, use user, username, root, admin, or similar names to identify classes of users. + + + Use these generic names when you refer to users outside a case study. It helps students to identify which part of a command to replace, by establishing a consistent format for names of users and system items. For example: + + +[root@fedora ~]# setfacl -m u:user1:rw /project/file1 + + The following list provides further alternatives: + + + + + operator1 to operator9 + + + + + + developer1 to developer9 + + + + + + architect1 to architect9 + + + + + + + + + +
+ Using Extended User and Group Names + + Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. + + + Using Realistic User Names + + When you are writing a detailed case study, such as training exercises, reviews, and similar material, use realistic names. These names should not be real people. In other words, do not use the name of an employee, a well-known person, or your neighbor. + + + + + For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. + + + Choosing a Realistic Name + + Consider the following points when choosing a realistic name: + Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. + + + + + + + + + In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. + + + + + + Do not use copyrighted fictional characters in examples, and do not use real people. + + + + + + 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. + + + + + + + Sourcing Realistic Names + + You can use any of the following name generators to create realistic names for users: + + + + + + + https://uinames.com/ + + + + + + http://listofrandomnames.com/ + + + + + + http://www.behindthename.com/random/ + + + + + + http://random-name-generator.info/ + + + + + + + Group Names + + Use any lowercase name that is a logical extension of the accepted user names, without the numerical suffix. For example, architects, developers, operators. + + + + +
+ +
+ +
+
+ Documenting Currencies + + Use local currency symbols wherever possible. If symbol clash occurs (USD versus AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. + + + + Do not provide currency conversions. + + + + +
+
+ Using Abbreviations, Acronyms, and Initialisms Correctly + + This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. + + + Abbreviations + + An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated," respectively. Read them as the word for which they are an abbreviation. + + + + + Acronyms + + What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + + + + + Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). + + + Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + + + To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. + + + Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. + + + Initialisms + + An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. + + + + + Consider pronunciation when using articles. See for more information. + + +
+
+ Using Company, Product, and Brand Names Correctly + + Various restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. + + + + In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use." + + + + + + + Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. + + + + + + Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. + + + + + + Do not include "Inc." when referring to Red Hat except in legal documents. + + + + + + Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. + + + If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. + + + + + + Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: + + + + + Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. + + + + + + The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 + + + + + + + For other markup languages, use the equivalent non-breaking space character. + + + + + + Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." + + + + + + Do not use non-breaking spaces with other companies' product names. + + + + + + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." + + + + In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. + + + + + + + + +
+
+ Using Version Numbers Correctly + + The preferred format for product names includes only the major version number. For example: + + + + Red Hat Enterprise Linux 8 + + + + + + JBoss Enterprise Application Platform 3 + + + + + + + + + When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version. + + + Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example: + + + + Red Hat Enterprise Linux 5.2 was released on October 12, 2010. + + + + + + <Application name> was first included in JBoss Enterprise Application Platform 3.2. + + + + + + + + + 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. + + + Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. + + + + This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. + + + + +
+
+ Using Admonitions + + To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning 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 in mind these considerations if using admonitions: + + + + Keep the statements as brief and to the point as possible. + + + + + + Use admonitions sparingly so that they do not lose their effectiveness. + + + + + + Use a Note admonition to bring additional information to the user's attention. + + + + + + Use an Important 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 a Warning 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. + + + + + + + + +
+
+ Making Recommendations + + When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". Recommendations can include best practices, recommended practices, and product-specific suggestions. See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. + + + (incorrect) + + "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project." + + + "It is recommended to generate a service account for each microservice in your project." + + + + + (correct) + + "Although the attack surface is reduced to the same-project traffic, Red Hat recommends creating multiple service accounts within a project." + + + "Red Hat recommends that you generate a service account for each microservice in your project." + + + +
+
+ Citing Other Works + + Referencing Other Books + + When referencing another book, either internal or external to Red Hat, use the following format: + + + + + + +Book Title by First name Surname; Publisher. + + + For example, Maximum RPM by + + Edward + Bailey + + + ; Red Hat Press. + + + Referencing Other Internet Sites + + When referencing another internet site, use the following guidelines: + + + + + + + Do not link words within the body text. That is, do not use structures such as "Go here for more information," where "here" is a link. + + + + + + Short URLs, such as http://partner.redhat.com, are OK to use in body text at your discretion. + + + + + + If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species + http://world-database-of-everything.com/en/classifcation_of_species/mammals.html + + page for more information. + + + + + + +
+ + + diff --git a/tmp/en-US/xml/E.xml b/tmp/en-US/xml/E.xml new file mode 100644 index 0000000..669254e --- /dev/null +++ b/tmp/en-US/xml/E.xml @@ -0,0 +1,193 @@ + + +%BOOK_ENTITIES; +]> + + E + + + e-book, e-business, e-commerce, e-learning, email + + + Refer to the primary reference for the type of copy you are creating, either AP or IBM. + + + + + + + e.g. + + + Red Hat technical documentation always expands these abbreviations. Write out "for example". + + + + + + + earlier + + + Use to refer to earlier releases of products. Do not use "older" or related terms. See also . + + + + + + + Emacs + + + If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." + + + + + + + emdash + + + Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See for more information. + + + + + + + enter + + + When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. + + + When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." + + + When typing information into a single-field dialog box, "enter" means "type and press Enter." An example is "enter the license number." For multi-field dialog boxes, see "type." + + + + + + + environment + + + The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, running a program in a UNIX environment means running a program on a computer that has the UNIX operating system. + + + One ingredient of an environment, therefore, is the operating system. But operating systems include many different parameters. For example, in some operating systems, you can choose your command prompt or a default command path. All these parameters together constitute the environment. + + + Another term for environment in this sense is platform. + + + + + + + EOL + + + adj. Initialism for "end-of-line" + + + n. Initialism for "end of line" + + + Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. + + + + + + + essentially + + + Do not use. + + + + + + + Ethernet + + + n. Uppercase "E" at all times. + + + + + + + event + + + An action or occurrence that is detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. + + + + + + + exclamation points (!) + + + Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. + + + + + + + Exec-Shield + + + Exec-Shield is a security-enhancing modification to the Linux kernel that makes large parts of specially marked programs including their stack not executable. + + + + + + + execute + + + Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. + + + + + + + Exif + + + Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." + + + + + + + extranet + + + Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. + + + Capitalize only at the beginning of a sentence. + + + + + + + + + diff --git a/tmp/en-US/xml/Easily_Confused_Words.xml b/tmp/en-US/xml/Easily_Confused_Words.xml new file mode 100644 index 0000000..08e2523 --- /dev/null +++ b/tmp/en-US/xml/Easily_Confused_Words.xml @@ -0,0 +1,92 @@ + + +%BOOK_ENTITIES; +]> +
+ Easily Confused Words + + This section identifies some easily confused words and how to choose the correct term for your situation. + + + Affect and Effect + + Each of these words can be used as a verb or a noun, but they are not always interchangeable. + + + + + + affect + + + n. Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you. + + + v. Means to have an influence on something, or to cause something to change. + + + + + + + effect + + + n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." + + + v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." + + + The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." + + + + + + + + + Assure, Ensure, and Insure + + These are relatively easy to get right, but here are some quick definitions. + + + + + + assure + + + v. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." + + + + + + + ensure + + + v. Means to make sure of something, to be certain that something exists or some condition has been met. + + + + + + + insure + + + v. Relates to monetary insurance. + + + + + + + + +
+ diff --git a/tmp/en-US/xml/F.xml b/tmp/en-US/xml/F.xml new file mode 100644 index 0000000..4fec021 --- /dev/null +++ b/tmp/en-US/xml/F.xml @@ -0,0 +1,334 @@ + + +%BOOK_ENTITIES; +]> + + F + + + fail back, failback + + + v. Use the 2-word form. + + + n. Use the 1-word form. + + + No hyphenated form is currently recognized. + + + + + + + fail over, failover + + + v. Use the 2-word form. + + + n., adj. Use the 1-word form. + + + No hyphenated form is currently recognized. + + + + + + + FAQ + + + When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an Q") not "a FAQ." The plural form is "FAQs." + + + + + + + fault tolerance (n.), fault-tolerant (adj.) + + + The ability of a system to respond gracefully to an unexpected hardware or software failure. Fault tolerance has many levels, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so that if one fails, then the other can take over. + + + + + + + Fedora™ Project + + + Correct. + + + + + + + fiber + + + Correct. Despite the alternative spelling used in Fibre Channel, "fiber" is the correct form to use in all other cases. + + + + + + + Fibre Channel + + + A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FAL). + + + FAL was designed for new mass storage devices and other peripheral devices that require high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100 MBps. FAL is compatible with, and is expected eventually to replace, SCSI for high-performance storage systems. + + + + + + + file extensions (general usage) + + + See File names, file types, and directory names in the IBM Style Guide. + + + + + + + file mode, file name, file system, file type + + + n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. + + + adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." + + + + + + + FireWire + + + Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. + + + + + + + firmware + + + n. Do not use "firm ware" or "firm-ware." + + + Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. + + + + + + + floating point + + + Correct. Do not hyphenate. + + + + + + + floppy disk + + + Do not use. Use "diskette," and also state the size of the diskette, such as "3.5 in. diskette." + + + + + + + floppy drive + + + Do not use. Use "diskette drive." + + + + + + + follow + + + v. Refers to the use of the () option for various commands, such as tail, so that output is appended as the file grows. + + + + + + + following + + + When introducing a list or a procedure, use "following" with a noun. Instead of "Complete the following", use "Complete the following steps". + + + + + + + foreground + + + + + In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. + + + + + + On display screens, the foreground consists of the characters and pictures that appear on the screen. The background is the uniform canvas behind the characters and pictures. + + + + + + + + + + + fortnight + + + A period of two weeks (14 nights). Avoid; this term is not common in American English and might also be unfamiliar to non-native speakers. + + + + + + + FORTRAN + + + Correct. Do not use "Fortran." + + + + + + + forward + + + Correct. Avoid using "forwards." + + + + + + + forwards compatible + + + Do not use. Instead, use "compatible with later versions." See also . + + + + + + + FQDN + + + A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels. + + https://en.wikipedia.org/wiki/Fully_qualified_domain_name + + + + + For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. + + + An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. + + + + + + + frictionless + + + Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also . + + + + + + + front end, front-end + + + n. Two words. For example, "PRCS is a front end for a version control toolset." + + + adj. Hyphenate. For example, "This chapter explains how to use the front-end API functions." + + + Do not use "frontend" as a noun or adjective. + + + See also . + + + + + + + FTP + + + Use all caps when referring to the protocol. Use lowercase when referring to the command-line program. + + + + + + + futexes + + + Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. + + + + + + + fuzzy + + + Correct only when referring to fuzzy searches. See for details and examples. + + + + + + + + + diff --git a/tmp/en-US/xml/Feedback.xml b/tmp/en-US/xml/Feedback.xml new file mode 100644 index 0000000..b1da4c2 --- /dev/null +++ b/tmp/en-US/xml/Feedback.xml @@ -0,0 +1,13 @@ + + +%BOOK_ENTITIES; +]> +
+ We Need Feedback + + Raise an issue at with suggestions for improvements, requests for additions, recommendations, and any other updates. + + +
+ diff --git a/tmp/en-US/xml/G.xml b/tmp/en-US/xml/G.xml new file mode 100644 index 0000000..96f0a6c --- /dev/null +++ b/tmp/en-US/xml/G.xml @@ -0,0 +1,268 @@ + + +%BOOK_ENTITIES; +]> + + G + + + g++, G++ + + + When referring to the command, use g++. When referring to the program, use G++. + + + + + + + gas, GAS + + + When referring to the command, use gas. When referring to the program, use GAS. + + + + + + + GB + + + Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. + + + AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." + + + IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file." + + + + + + + GbE + + + Correct. Approved abbreviation of Gigabit Ethernet. Do not use GigE or any other variations. Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + Gbps + + + Abbreviation of Gigabits per second, a data transfer speed measurement for high-speed networks such as Gigabit Ethernet. When used to describe data transfer rates, a gigabit equals 1,000,000,000 bits. Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + gcc, GCC + + + When referring to the command, use gcc. When referring to the program, use GCC. + + + + + + + gcj, GCJ + + + When referring to the command, use gcj. When referring to the program, use GCJ. + + + + + + + gdb, GDB + + + When referring to the command, use gdb. When referring to the program, use GDB. + + + + + + + GDBTK + + + Do not use. Use "Insight" instead. GDBTK is an obsolete name for the GNU debugger. + + + + + + + GEO + + + Do not use. Use "region" or "geographical location" according to your needs. + + + + + + + GFS, GFS2 + + + As of Red Hat Enterprise Linux 6, it is known as the Resilient Storage Add-On. Ensure that you use the correct term. + + + + + + + GID + + + Acronym for Group ID. Do not use "gid." + + + + + + + GigE + + + See . + + + + + + + gigabyte + + + 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + GIMP + + + Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp." + + + + + + + GNOME + + + Correct. Do not use "gnome," "Gnome," or other variants. See also . + + + + + + + GNOME Classic + + + Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). + + + + + + + GNU + + + Recursive initialism for "GNU's Not UNIX." Do not use "Gnu" or "gnu." + + + + + + + GNUPro + + + When referring to the Red Hat product, use GNUPro. + + + + + + + got + + + Do not use. + + + + + + + GPL + + + Initialism for General Public License. Do not use "Gpl" or "gpl." + + + + + + + grayscale + + + n. Correct. Do not use "gray-scale" or "gray scale." Only the noun form is currently recognized. + + + + + + + GRUB + + + Correct. All caps. Do not use "Grub." + + + + + + + GTK+ + + + Initialism for GIMP Tool Kit. Do not use "GTK," "Gtk," or "gtk." + + + + + + + guest operating system + + + Refers to the operating system that is installed in a virtual machine. Do not use "guest" by itself because it is ambiguous. + + + + + + + + + diff --git a/tmp/en-US/xml/Grammar.xml b/tmp/en-US/xml/Grammar.xml new file mode 100644 index 0000000..1439247 --- /dev/null +++ b/tmp/en-US/xml/Grammar.xml @@ -0,0 +1,621 @@ + + +%BOOK_ENTITIES; +]> + + Grammar + + This section contains information on a few common grammar topics. For subjects not covered here, consult The Chicago Manual of Style, 17th Edition. + +
+ Active Voice + + Use the active voice ("Type ... to start Linuxconf.") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. + + + This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. + + + For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than + + + "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence. + + + You can also use the passive voice to front-load important keywords in key areas of your content, such as the title, heading, or at the beginning of a paragraph or sentence. You need to make these decisions on a case-by-case basis, weighing the importance of front-loading keywords against content that is readable (that is, not awkward sounding). Consider the following two examples: + + + Active Voice + + "Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization." + + + + + Passive Voice + + "Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion." + + + + +
+
+ Agreement + + In grammar, agreement occurs when specific parts of a sentence are coordinated; that is, they agree in number and gender. + + + There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here. Pronoun-antecedent agreement can be a little more problematic, so... + +
+ Pronoun-antecedent agreement + + A pronoun is a word that is used in place of a noun (for example, I, he, she, it). An antecedent is a word or phrase to which the pronoun refers. + + + When you are comfortable with subject-verb agreement, pronoun-antecedent agreement often follows as a matter of course. + + + The following is an annotated roundup of pronoun-antecedent rules: + + + Singular and Plural Nouns + + A singular pronoun refers to a singular antecedent; a plural pronoun refers to a plural antecedent. For example: + + + + + + + The CD spins in its caddy. (The singular third-person pronoun "its" refers to the singular antecedent "CD".) + + + + + + The developers checked their work. (The plural third-person pronoun "their" refers to the plural antecedent "developers".) + + + + + + + Collective Nouns + + When collective nouns are used as antecedents, use singular or plural pronouns, depending on the sentence's meaning. For example: + + + + + + + Microsoft seems second to none in its marketing skills. (The collective noun "Microsoft" takes the singular pronoun "its" because the collective noun refers to the group as a whole.) + + + + + + The developers were asked for their preferences. (The collective noun "developers" takes the plural pronoun "their" because the reference is to the individuals of the group.) + + + + + + +
+ +
+
+ Using Who, Whom, That, and Which Correctly + + Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns." + + + Use the following as guidelines: + + + + Who + + + Relative pronoun when persons are the subject. + + + + + + + Whom + + + Relative pronoun when persons are not the subject. + + + + + + + Which + + + Relative pronoun for things. + + + + + + + That + + + Restrictive pronoun for things. + + + + + + + + + Examples: + + + + + The jewel case, which once held the CD, was broken recently. + + + + + + The CD that I received for my birthday is defective. + + + + + + Edward C. Bailey, who wrote "Maximum RPM,"... + + + + + + The company that published "Maximum RPM" was... + + + + + + This book belongs to whomever purchased it last week. + + + + + + Who ate all the cereal? + + + + + + To whom should I address the letter? + + + + + + The desktop that was designed by Earl is not called GNOME. + + + + + + The GNOME developers who worked on the desktop are... + + + + + + The GNOME developers to whom they owe gratitude are... + + + + + + + + To help you choose between who and whom, substitute the person about whom you are speaking with he, she, him, or her. + + + + + If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" + + + + + + If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" + + + + + + + + +
+
+ Sentence Structure + + A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). + + + Consider the following points when constructing sentences: + + + Sentence Length + + Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: + + + + + The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. + + + Run-on Sentences + + Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: + + + + + + + Separate independent clauses with a period. Doing so will form two sentences out of one. + + + + + + Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. + + + + + + Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." + + + + + + Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error." + + + + + + + + + + + + + Example + Improvement + + + + + + + The CDs both of which belonged to the developers were in the test lab. + The CDs, both of which belonged to the developers, were in the test lab. + + + + To access your programs click the Start button. + To access your programs, click Start. + + + + The CDs, both of which belonged to the developers, were in the test lab, because they were the only available CDs for the new release, the developers were anxious about keeping them clean. (This sentence exhibits a comma splice which is also often regarded as a run-on sentence.) + The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean. + + + + + + + +
+ + Sentence Fragments + + A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. + + + + + + Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. + + + + + Telegraphic Style + + Extreme cases of word economy can result in a telegraphic style, omitting words that can clarify the meaning of a sentence, such as articles, prepositions, and verbs used with gerunds. + + + + + + + + + + + Example + Improvement + + + + + + + Click button to start. + Click Initiate to start the process. + + + + + + + +
+ + This problem is often encountered in the Revision History. It is important that wording in the Revision History is clear for translators and customers to understand. + + + + + + + + + Example + Improvement + + + + + + + Minor revision - missing element items + Minor revision - added missing element items + + + + Some further work required to avoid 404s at lower levels of the SDK. + Some further work required to avoid 404 errors at lower levels of the SDK. + + + + + + + +
+ + "That" in Clauses + + Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, + + + + + + + + + + + Example + Improvement + + + + + + + Verify your directory service is working. + Verify that your directory service is working. + + + + + + + +
+ + Verbosity + + Avoid unnecessary words. Keep it succinct. + + + + + + + + + + + Example + Improvement + + + + + + + The individual member of the social community often receives information via visual, symbolic channels. + People read. (Translation by Richard Feynman.) + + + + Perform the installation of the product. + Install the product. + + + + + + + +
+ + Word Order + + When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify. + + + + + + + + + + + Example + Improvement + + + + + + + To update the address lists might be your primary concern. + Your primary concern might be to update the address lists. + + + + + + + +
+ +
+ +
+ Contractions and Abbreviations + + Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. + + + Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. + + +
+ +
+ Hyphenation + + There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. + + + Hyphenate for Clarity + + Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. + + + + + + Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof." + www.apstylebook.com + + + + + + + Hyphenate Complex Adjectives + + Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. + + + + + + Do not hyphenate "open source," even when used as a complex adjective. + + + Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. + + + + + Hyphenate Consecutive Vowel Sounds + + Hyphenate words where the prefix ends in a vowel and the word that follows begins with the same vowel. For example, semi-independent, pre-emptive. + + + + + + Exceptions to this rule include cooperate and coordinate. + + + + + Hyphenate Mixed Capitalization + + Hyphenate when the word that follows a prefix is capitalized. For example, un-American, non-British. + + + + + Hyphenate Double Prefixes + + Hyphenate when the word has double prefixes. For example, sub-subparagraph, re-sublet. + + + + +
+
+ Gender References + + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + + +
+
+ Tense + + Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. + + + Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. + + + Report an issue + + +
+ + + diff --git a/tmp/en-US/xml/H.xml b/tmp/en-US/xml/H.xml new file mode 100644 index 0000000..828bc54 --- /dev/null +++ b/tmp/en-US/xml/H.xml @@ -0,0 +1,299 @@ + + +%BOOK_ENTITIES; +]> + + H + + + hard code, hard-coded + + + v. Two words. + + + adj. Hyphenate. + + + Do not use the one-word form. No nominal form is currently recognized. + + + + + + + hard copy + + + Do not use. Use "printed". Under review + + + + + + + + hard disk + + + n. Correct. Do not use "harddisk" or "hard-disk." + + + + + + + hard disk drive + + + n. Correct. Do not use "harddrive" or "hard-drive." + + + + + + + he/she + + + Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. + + + + + + + help desk + + + Typically two words, but use the term accepted by your organization. + + + + + + + healthcare + + + Under review. Need context and example. + + + + + + + + health check + + + n. Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. + + + This term is only capitalized when part of a product name, for example: + + + + Red Hat Enterprise Linux Server Health Check + + + + + + JBoss Middleware Health Check + + + + + + + + + Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." + + + + + + + hertz + + + n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz." + + + + + + + high-availability, high availability + + + adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." + + + n. Two words. For example, "Support is available 24x7 to help maintain high availability." + + + + + + + high-performance computing (HPC) + + + n. Use standard hyphenation guidelines to maintain clarity. + + + + + + + homepage + + + n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + + + + + + + host group + + + n. Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. + + + + + + + host name + + + n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. + + + + + + + hot add + + + v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add." + + + + + + + hotline + + + n. One word, lowercase. Capitalize only at the beginning of a sentence. Under review. Need context and example. + + + + + + + + hot plug + + + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug." + + + + + + + hot swap + + + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap." + + + + + + + hover help + + + See . + + + + + + + HP ProLiant + + + Correct. Do not use any other variations. + + + + + + + HTML + + + When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." + + + + + + + huge-page, huge page + + + adj. Hyphenate. Normal hyphenation rules apply. + + + n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization that is used in that interface. + + + + + + + hybrid IT + + + The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . + + + + + + + Hyper-Threading + + + n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use "hyperthreading" or "hyper-threading". If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. + + + + + + + hypervisor + + + n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser." + + + + + + + + + diff --git a/tmp/en-US/xml/I.xml b/tmp/en-US/xml/I.xml new file mode 100644 index 0000000..40dca43 --- /dev/null +++ b/tmp/en-US/xml/I.xml @@ -0,0 +1,369 @@ + + +%BOOK_ENTITIES; +]> + + I + + + IA64 or ia64 + + + Do not use. Always use the term Itanium instead. These terms can be used in file names because they are not visible in the content. + + + + + + + IaaS + + + Correct. This is the correct abbreviation for "Infrastructure-as-a-Service." See also . + + + + + + + IBM Z + + + IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. + + + + + + + i.e. + + + Do not use a Latin abbreviation. Instead, write out "that is". + + + + + + + illegal + + + Illegal means "prohibited by law," not "incorrect" or "not permitted." Use "invalid" or a related word. + + + + + + + matrixes + + + Correct. This is the correct plural form for US English spelling. Do not use "indices." + + + + + + + InfiniBand + + + InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. + + + "Open InfiniBand" is deprecated and should not be used. + + + + + + + inline + + + adj. Always one word. Do not hyphenate. + + + + + + + insecure + + + adj. Correct. Do not use "nonsecure" or "non-secure." + + + + + + + installation program + + + n. Correct. Do not use "installer" unless it is a formal part of the product or technology. + + + + + + + Intel 64 + + + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. + + + The correct term for Intel's implementation of this architecture is "Intel® 64." Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + + + See also . + + + + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + + + For more information about Intel® trademarks, see and . + + + + + + + + + Intel® CoreTM + + + Correct. Example would be good. + + + + + + + + Intel Tolapai / Intel® EP80579 Integrated Processor + + + Do not use the code-name, "Tolapai." Use the official brand name "Intel® EP80579 Integrated Processor." + + + + + + + Intel Virtualization Technology (Intel VT) + + + Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." + + + Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." + + + + + + + Intel® Xeon® + + + Correct. Example? Reference? + + + + + + + + interesting + + + Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note...", consider using a "Note" admonition. + + + + + + + internet + + + n. Always lowercase except in some specific exceptions, for example . + + + + + + + Internet of Things (IoT) + + + Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. + + + The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. + http://en.wikipedia.org/wiki/Internet_of_things + + + + + + + + + Intranet, intranet + + + See the "Word usage" appendix of the IBM Style Guide for guidance. + + + + + + + I/O + + + Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. + + + The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. + + + + + + + IOPS + + + Correct. All caps. Stands for input/output operations per second. + + + + + + + IP + + + Correct. Stands for Internet Protocol. Capitalize both letters. + + + + + + + IP Masquerade + + + A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. + + + Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. + + + + + + + IPsec + + + IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec." + + + + + + + IP switching + + + A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. + + + + + + + ISV + + + Short for "independent software vendor", a company that produces software. + + + + + + + IT/I.T. + + + Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." + + + + + + + Itanium + + + A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. + + + In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. + + + Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. + + + Do not use the term "IA64". It can be used in file names because they are not printed in the content. + + + + + + + Itanium 2 + + + Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." + + + + + + + + + diff --git a/tmp/en-US/xml/J.xml b/tmp/en-US/xml/J.xml new file mode 100644 index 0000000..9dc1106 --- /dev/null +++ b/tmp/en-US/xml/J.xml @@ -0,0 +1,72 @@ + + +%BOOK_ENTITIES; +]> + + J + + + JavaScript + + + "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." + + + + + + + JBoss Community + + + No longer referred to as "JBoss.org." Use when referring to the community of users and contributors. + + + + + + + job + + + A task that a computer system performs. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. + + + + + + + jsvc + + + The Apache Commons Daemon jsvc is a set of libraries and applications to run Java applications on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. + + + + + + + just + + + Use sparingly. In the phrase, "Just open the file...", omit the word "just." + + + + + + + JVM + + + Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine," or "Java VM," or only the noun itself, "virtual machine." You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)." Do not use Jvm or jvm. + + + + + + + + + diff --git a/tmp/en-US/xml/K.xml b/tmp/en-US/xml/K.xml new file mode 100644 index 0000000..7c62fa7 --- /dev/null +++ b/tmp/en-US/xml/K.xml @@ -0,0 +1,170 @@ + + +%BOOK_ENTITIES; +]> + + K + + + KB, kB + + + See the IBM Style Guide for the correct abbreviation to use for specific use cases. + + + + + + + kbps, KBps, kBps + + + kbps is the accepted abbreviation for kilobit per second, or 1000 bits per second. + + + KBps and kBps are accepted abbreviations for kilobyte per second, or 1000 bytes per second. + + + + + + + kerberize + + + Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence. + + + + + + + kernel + + + The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. + + + + + + + Kernel-based Virtual Machine (KVM) + + + Spell out on first use, capitalized. Use the initialism (KVM) thereafter. It is an industry standard, and a proper noun. + + + + + + + kernel panic + + + Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. + + + + + + + kernel space, kernel-space + + + n. Two words when used as a noun. + + + adj. Hyphenate as an adjective, "kernel-space." Do not use "kernelspace." + + + + + + + keyboard key + + + When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X." When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S." + + + See also . + + + + + + + key ring + + + n. Use the two-word form as a noun. For example, "add your new key to the key ring." + + + adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server." + + + Only use the one-word form, "keyring," if it is the actual name of a command, package, or other proper noun. + + + + + + + keytab + + + n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . + + + + + + + key-value + + + adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair." Do not use "key/value" or any other variations. + + + + + + + Kickstart + + + adj. A network installation system for some Linux distributions. + http://en.wikipedia.org/wiki/Kickstart (Linux) + + + + + + + + + kill + + + If terminating a UNIX process, use "kill." For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate." For example, "To terminate the process, press Q." + + + + + + + knowledge base + + + Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase." In this case, use the one-word form and capitalize the "K." Do not capitalize the "b." + + + + + + + + + diff --git a/tmp/en-US/xml/L.xml b/tmp/en-US/xml/L.xml new file mode 100644 index 0000000..f69c867 --- /dev/null +++ b/tmp/en-US/xml/L.xml @@ -0,0 +1,265 @@ + + +%BOOK_ENTITIES; +]> + + L + + + LAN + + + Correct. This is an acronym for Local Area Network. Do not use Lan or lan. + + + + + + + latency + + + + + In general, the period of time that one component in a system is spinning its wheels waiting for another component. Latency, therefore, is wasted time. For example, in accessing data on a disk, latency is defined as the time it takes to position the proper sector under the read/write head. + + + + + + In networking, the amount of time it takes a packet to travel from source to destination. Together, latency and bandwidth define the speed and capacity of a network. + + + + + + + + + + + later + + + Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also . + + + + + + + leave out + + + Do not use. Use "omit" instead. + + + + + + + left-click + + + v. Write the term hyphenated. Do not use "left click" or "leftclick." + + + + + + + LibreOffice + + + A Linux desktop suite. Do not use "Libre," "Libreoffice," or "Libre Office." + + + See also + + + + + + + license + + + n., v. Use this form for both the noun and the verb. + + + + + + + life cycle, life-cycle, lifecycle + + + n. Two words. Only use the one-word form if it is an established part of a software interface, part of a proper noun, or an external standard. + + + adj. Hyphenate. + + + + + + + Linux + + + Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." + + + Linux is a registered trademark of Linus Torvalds. Use a registered trademark symbol on first use. + + + + + + + load + + + + + To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. + + + + + + v. In programming, "to load" means to move from one storage type to another storage type for use. + + + + + + n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) that the network carries, or the amount of CPU in use at any given time. + + + + + + + + + + + load balancing + + + Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. + + + + + + + logical topology + + + Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. + + + + + + + login, log in + + + Write as one word as an adjective or noun, or as two words as a verb. + + + + + adj., n. One word. For example, "the login credentials". + + + + + + v. Two words. For example, "to log in as root". + + + + + + + + + + + log in to + + + v. Write as three words. For example, "to log in to the system". + + + + + + + lookup, look-up, look up + + + n. Use the one-word form. + + + v. Use the two-word form. + + + adj. Hyphenate when used as a modifier. For example, "a look-up table." + + + + + + + look at + + + Do not use. Use "examine" or "inspect" or some other more precise term instead. + + + + + + + loopback address + + + The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. No hardware is associated with a loopback interface, and it is not physically connected to a network. + + + With a loopback interface, IT professionals can test IP software without concern for broken or corrupted drivers or hardware. + + + + + + + lots of + + + Do not use. Use "many" instead. + + + + + + + LPAR + + + Abbreviation of "logical partitioning", a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. + + + + + + + + + diff --git a/tmp/en-US/xml/Language.xml b/tmp/en-US/xml/Language.xml new file mode 100644 index 0000000..f2b6807 --- /dev/null +++ b/tmp/en-US/xml/Language.xml @@ -0,0 +1,1299 @@ + + +%BOOK_ENTITIES; +]> + + Choosing Appropriate Language + + Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + + + If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. + + + Red Hat is committed to eliminating use of language that might exclude or offend certain groups of people. This chapter describes some considerations for use of inclusive language. + + + Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. + +
+ Avoiding Misleading or Confusing Language + + Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. + + + + best practices + + + This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." + + + See the section for additional information about recommendations in Red Hat documentation. + + + + + + + first come, first served + + + Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. + + + + + + + + +
+
+ Identifying and Avoiding Slang + + Examples of slang terms: + + + + administrivia + + + Not a word. Do not use. + + + + + + + anything you like, anything they like + + + This phrase is probably readily understood but should not appear in Red Hat documentation. + + + + + "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." + + + Rephrase to something more suitable, such as "... to register any other kind of plug-in." + + + + + + + + + + + ask (as a noun), make the ask + + + Ask is a verb. Do not use it as a noun. + + + + + + + at this point in time + + + Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. + + + + + + + automagic + + + Also, automagical. Both terms are slang. Do not use. + + + + + + + best-of-breed + + + Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + + + + + + + bleeding edge + + + Do not use. + + + + + + + bottom line + + + Traditionally used in financial contexts; avoid overuse. + + + + + + + bucketize + + + Not a word. Try "categorize" or "organize into logical groups." + + + + + + + center of competency + + + Do not use. + + + + + + + check this site + + + Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + + + + + + + coopetition + + + Not a word. Do not use. + + + + + + + core competency + + + Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + + + + + + + eat your own dogfood + + + Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + + + + + + + data point + + + Do not use. + + + + + + + dig deeper, delve deeper + + + "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + + + + + + + double-edged sword, double-bladed sword + + + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + + + + + + + enterprise-ready + + + Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + + + + + + + exceed your expectations + + + Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + + + + + + + fib + + + A fib is a "small lie," also known as a "white lie." This sentence appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." + + + + + + + flying by the seat of your pants + + + Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. + + + + + + + frame it up + + + Do not use. + + + + + + + frown upon + + + "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + + + + + + + fuzzy (search) + + + Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: + + + + + In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. + + + + + + + The use of "fuzzy" is valid in this context. + + + Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." + + + Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. + + + + + + + going-forward basis + + + Jargon. Say "from now on," "in the future," or something similar. + + + + + + + happy path + + + Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is localized slang and could easily be misunderstood. It could also produce problems for translation. + + + + + + + harness the power + + + Do not use. + + + + + + + have a crack at, jump right in + + + Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. + + + + + + + if you want, if you wish + + + Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." + + + + + + + in concert with + + + Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." + + + + + + + improve, enhance + + + Vague. Try to be more specific. + + + + + + + in a pinch + + + Under a tight schedule, hard pressed to achieve something. + + + + + + + infomediary + + + Not a word. Do not use. + + + + + + + is designed to + + + Avoid this and similar phrases when describing products and services. Instead, state what the product does. + + + + + Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. + + + + + + Correct: SSH works with almost any kind of public key algorithm or encoding format. + + + + + + + + + + + kettle of fish + + + Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. + + + + + + + leverage + + + Avoid. Alternatives include "use" and "take advantage of". + + + + + + + lights on, lights-on + + + Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. + + + It is typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." + + + + + + + low-hanging fruit + + + Metaphor. Do not use. + + + + + + + marketecture + + + Not a word. Do not use. + + + + + + + meet your needs + + + Vague. Try to be more specific, for example, "lower your middleware costs." + + + + + + + mission-critical + + + Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Ensure that you have the applications that you need to help your customers." versus "Ensure that you have the mission-critical applications that your customers demand." + + + + + + + net-net + + + Jargon. Use "in summary," "the end result," or something similar. + + + + + + + niche focus + + + Do not use. + + + + + + + over the wire + + + Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. + + + + + + + pain in the backside + + + Nobody should ever write this expression or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. + + + + + + + paradigm + + + Avoid. Use "model," "standard," or something similar. + + + + + + + performant + + + In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. + + + + + + + physicalize + + + Not a word. Do not use. + + + + + + + piggyback + + + Slang. Do not use. + + + + + + + pre-baked + + + Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. + + + + + + + productize + + + Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] + + + + + + + ready to rumble + + + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." + + + + + + + rest on your laurels + + + Do not use. + + + + + + + right before doing something + + + Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. + + + + + + + root your server in the /serverRoot directory + + + This expression is inelegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. + + + + + + + shoot yourself in the foot + + + To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + + + + + + + shy of + + + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. + + + + + + + silo, siloed + + + Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," or something similar. + + + + + + + solutioning + + + Not a word. Lazy version of "creating a solution." + + + + + + + solutions-based + + + Do not use. + + + + + + + solution stack + + + Do not use. + + + + + + + stovepipe + + + Jargon. In business, related to lack of cross-organizational communication, similar to "silo." + + + + + + + synergistic, synergy + + + Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. + + + + + + + synergical connectivity + + + Seriously? + + + + + + + to think outside the box + + + 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? + + + + + + + tunnel vision + + + Do not use. + + + + + + + under the covers + + + This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + + + + + + + value-added + + + Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." + + + + + + + very + + + Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." + + + + + + + virtual elephants + + + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. + + + + + + + + +
+
+ Neologisms (Invented Words) + + The English language is full of these words. Some of them are useful; some of them are less so; others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and is generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. + + + Examples + + + "This feature allows synchronization of adds, deletes, and changes ..." + + + + + This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + + + + + + + + + + +
+
+ Anthropomorphism + + Anthropomorphism is applying human qualities to non-human things or animals. Avoid it in your writing. + + + Examples + + + The computer will think for a brief period. + + + + + Computers do not actually think but they might take a while to "process" commands. + + + + + + + + + + The Proxy Server is talking to either RHN Hosted or a Satellite Server. + + + + + It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. + + + + + + + + + + + Report an issue + + +
+
+ Inclusive Language + + Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. + + + Replace terms that reinforce cultural, racial, or other types of bias with an alternative. + + + Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + + For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. + + + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + + + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + + + Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + + + Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". + + + Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. + + +
+
+ Avoiding Ambiguities + + + Capitalizing Proper Nouns + + + In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. + + + + + + + + + Example + Improvement + + + + + + + This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. + This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. + + + + + + + +
+ + + + + + Homographic Verbs + + + The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + + + + + + + + + Example + Improvement + + + + + + + The next() method should return null to indicate the end of results. + The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. + + + + It may be held in memory. + It can be held in memory. OR It might be held in memory. + + + + + + + +
+ + + + + + Homonymity + + + When a single term has multiple meanings, be explicit in order to differentiate between them. + + + + + + + + + Example + Improvement + + + + + + + Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. + Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. + + + + To create another administrator, click New on the File menu. + To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. + + + + + + + +
+ + + See also . + + + + + + + + + Verb phrases + + + When you have more than one infinitive verb within a sentence, be clear what each verb refers to. + + + + + + + + + Example + Improvement + + + + + + + Use the utility to run activities and save your settings. + Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + + + + + + +
+ + + + + + Invisible Plurals + + + Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. + + + + + + + + + Example + Improvement + + + + + + + Once the file retrieval has been completed, you are ready to restart your system. + After the files have been retrieved, you can restart your system. + + + + + + + +
+ + + + + + Verb phrases + + + Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. + + + + + + + + + Example + Improvement + + + + + + + If the completed field contains text, it does not change. + If the completed field contains text, that text does not change. + + + + + + + +
+ + + + + + Synonymity + + + Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. + + + For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. + + + + + + + Use of "using" + + + Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. + + + + + + + + + Example + Improvement + + + + + + + Open the firewall ports using the existing service configuration. + + Option 1: Open the firewall ports by using the existing service configuration. + + + Option 2: Use the existing service configuration to open the firewall ports. + + + + + + The resource agents using mail alerts require a mail transport agent. + The resource agents that use mail alerts require a mail transport agent. + + + + + + + +
+ + + + + + Verb phrases + + + Ensure that a verb phrase at the start of a sentence modifies the correct word. + + + + + + + + + Example + Improvement + + + + + + + Having configured your environment, the product is ready to be used. (The product does not configure the environment.) + After you configure your environment, you can use the product. + + + + + + + +
+ + + + + + + +
+
+ Dates and Times + + Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. + + + Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". + + + Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. + + + For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". + + + Use "noon" or "12 noon" instead of "12 PM". Use "midnight" or "12 midnight" instead of "12 AM". + + + Examples + + + The training class begins at 10 AM on 1 April 2021. + + + The coffee break is from 2:00 PM to 2:30 PM. + + + + + + +
+
+ Numbers + + Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. + + + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + + + Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). + + + See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. + +
+ Phone numbers + + Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international use by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. + + +
+ +
+ + diff --git a/tmp/en-US/xml/M.xml b/tmp/en-US/xml/M.xml new file mode 100644 index 0000000..a4afee2 --- /dev/null +++ b/tmp/en-US/xml/M.xml @@ -0,0 +1,309 @@ + + +%BOOK_ENTITIES; +]> + + M + + + macOS + + + In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. + + + + + + + make sure + + + This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." + + + You might be able to use "verify" or "ensure" instead. + + + + + + + manual, man page + + + Correct. Two words. Do not use "manpage." + + + + + + + matrixes + + + Correct. This is the correct plural form for US English spelling. Do not use "matrices." + + + + + + + MB + + + + + When written as MB, stands for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). + + + + + + When written as Mb, stands for megabit. + + + + + + + + + + + MBps + + + Initialism for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps. + + + + + + + MBR + + + Initialism for Master Boot Record, a small program that is executed when a computer boots up. Typically, the MBR resides on the first sector of the hard disk. The program begins the boot process by looking up the partition table to determine which partition to use for booting. It then transfers program control to the boot sector of that partition, which continues the boot process. In DOS and Windows systems, you can create the MBR with the FDISK /MBR command. + + + + + + + media + + + + + 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 fibre 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. + + + + + + + + + + + menu-driven + + + adj. Correct. Do not use "menu driven" or "menudriven." + + + Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program. + + + + + + + message + + + n. Write "the system displays a message" or "send an instant message." + + + adj. For example, "A messaging system." + + + Do not use as a verb. + + + + + + + metadata + + + Correct. Do not use "meta data" or "meta-data." + + + + + + + microservice + + + n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See https://en.wikipedia.org/wiki/Microservices for a definition. + + + + + + + Microsoft + + + Correct. Do not use "MS," "MSFT," or "MicroSoft." + + + + + + + misconfigure + + + v. This term is in common use and does appear in some dictionaries, but try to avoid it if possible. Do not hyphenate. + + + + + + + Montecito + + + Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. + + + + + + + mount + + + v. + + + + + To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. + + + + + + To install a device, such as a disk drive or expansion board. + + + + + + + + + + + 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. + + + + + + + Mozilla Firefox + + + Correct. First reference must be "Mozilla Firefox." Subsequent references can be "Firefox." + + + + + + + Mozilla Thunderbird + + + Correct. First reference must be "Mozilla Thunderbird." Subsequent references can be "Thunderbird." + + + + + + + MDOS + + + Correct. Do not use "ms-dos," "MSDOS," or "msdos." + + + + + + + multiprocessing + + + Correct. Do not use "multi-processing." + + + + + + + must + + + Use when referring to a task that a user is required to do. For example, "You must make a backup" is a requirement, but "You should make a backup" is a suggestion. + + + + + + + mutexes + + + Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. + + + + + + + MySQL + + + Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an ® symbol to denote a registered trademark. + + + + + + + + + diff --git a/tmp/en-US/xml/N.xml b/tmp/en-US/xml/N.xml new file mode 100644 index 0000000..ef9409f --- /dev/null +++ b/tmp/en-US/xml/N.xml @@ -0,0 +1,125 @@ + + +%BOOK_ENTITIES; +]> + + N + + + navigate to + + + Use "Navigate to" when moving through multiple GUI 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. + + + + + + + need + + + Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). + + + + + + + needs, needs to be, need to + + + Avoid when possible. Suggested alternatives include "must," "required," or "should." + + + + + + + .NET + + + The Microsoft .NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and supports several programming languages. + + + "Microsoft .NET" is correct for the first reference, and ".NET" for all following references. + + + + + + + network transparency + + + A condition in which an operating system or other service gives user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems NFS, now a de facto industry standard, provides access to shared files through the Virtual File System (VFS) interface that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. + + + + + + + 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. + + + 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. + + + + + + + node + + + + + In networks, a processing location. A node can be a computer or some other device such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or a Media Access Control (MAC) address. + + + + + + In tree structures, a point where two or more lines meet. + + + + + + + + + + + nonsecure + + + Do not use. Use "insecure" instead. + + + + + + + NULL or null + + + When a command or value is stated, use NULL. When stating that something is null, use "null," all lowercase. + + + + + + + + + diff --git a/tmp/en-US/xml/O.xml b/tmp/en-US/xml/O.xml new file mode 100644 index 0000000..9dc29b3 --- /dev/null +++ b/tmp/en-US/xml/O.xml @@ -0,0 +1,270 @@ + + +%BOOK_ENTITIES; +]> + + O + + + Objective C + + + Correct. Do not use "Objective-C." + + + + + + + object-oriented + + + Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." + + + Also, do not use "object-orientated". + + + + + + + OEM + + + n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. + + + To provide equipment to another company, an OEM, which customizes and markets the equipment. + + + + + + + offline + + + adj. Write as one word. Do not use "off-line." + + + + + + + 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. + + + 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. + + + + + + + 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." + + + + + + + onboard + + + adj, tr.v. Use the one-word form in all cases. + + + + + + + once + + + Use only to mean "one time." Do not use as a conjunction to mean "after" or "when." + + + + + + + online + + + adj. Write as one word. Do not use "on-line." + + + + + + + on-site + + + adj. Hyphenate when used as an adjective, as in "on-site labs." + + + + + + + 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. + + + + + + + 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." + + + + + + + opcodes + + + Correct. Do not use "op-codes." + + + + + + + OpenJDK + + + The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. + + + + + + + open architecture + + + An architecture whose specifications are public. It includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. + + + + + + + Open InfiniBand + + + "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. + + + + + + + OpenOffice + + + A Linux desktop suite. Do not use "Openoffice," "Open Office," or "ooo." + + + See also . + + + + + + + open source + + + Correct. Do not use "OpenSource," "opensource," or "open-source." Only capitalize the "o" in "open source" at the beginning of a sentence. + + + + + + + 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". + + + + + + + operating system + + + Correct. Do not use Operating System, or OS. + + + + + + + orientate + + + Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps to familiarize you with the environment." + + + + + + + output device + + + Any machine that is capable of representing information from a computer, including display screens, printers, plotters, and synthesizers. + + + + + + + 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 . + + + + + + + override + + + Correct. Do not use "over-ride" or "over ride." + + + + + + + + + diff --git a/tmp/en-US/xml/Objectives.xml b/tmp/en-US/xml/Objectives.xml new file mode 100644 index 0000000..075ec6d --- /dev/null +++ b/tmp/en-US/xml/Objectives.xml @@ -0,0 +1,53 @@ + + +%BOOK_ENTITIES; +]> + + 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: + + + + Accurate and consistent + + + + + + Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale. + + + + + + Comprehensible, with a fog index of 9-12, using the Gunning fog index. + + + + + + User focused, providing information without patronizing the reader, or making presumptions about their skills. + + + + + + + + + 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. + + + + + + diff --git a/tmp/en-US/xml/P.xml b/tmp/en-US/xml/P.xml new file mode 100644 index 0000000..ba71e0f --- /dev/null +++ b/tmp/en-US/xml/P.xml @@ -0,0 +1,327 @@ + + +%BOOK_ENTITIES; +]> + + P + + + PaaS + + + n. The correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. + + + Marketing, Brand, Customer Portal Usage + + For all-caps text, such as banners, use "<VARIANT>-ASERVICE" for the spelled-out version. The same abbreviation is used across all groups. + + + + + + + + + PC + + + n. Use to refer to a personal computer. + + + + + + + persist + + + v. Do not use as a verb to mean "store" or "save," for example, when referring to persistent storage. + + + + + + + PHP + + + n. Use PHP when referring to the language in general. Use php when referring to the specific command or some other literal use. + + + See for specific PHP language information. See for more general information. + + + + + + + Pico, pico + + + n, adj. Capitalize when referring to the text editor or to the programming language. Do not capitalize when referring to the SI prefix. + + + + + + + plain text + + + 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." + + + + + + + please + + + 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. + + + + + + + pluggable + + + adj. Something that is capable of being plugged in, especially in terms of (for example) software modules. "Hot-pluggable" is also widely used with respect to hardware to indicate that it can be connected and recognized without powering down the system. + + + + + + + plug-in + + + n. Write hyphenated. Do not use "plugin." + + + A hardware or software module that adds a specific feature or service to a larger system. + + + + + + + PM + + + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". + + + See also . + + + See the IBM Style Guide for a full discussion of how to represent times. + + + + + + + pop-up + + + n, adj. Do not use "popup" or "pop up." + + + + + + + PostScript + + + n. It is a registered trademark of Adobe. Do not use "Postscript." + + + + + + + PowerPC + + + 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 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. + + + + + + + POSIX + + + n. Do not use "Posix," "posix," or variations thereof. + + + An acronym for "Portable Operating System Interface for UNIX." + + + + + + + PPP + + + n. Do not use "ppp" or "Ppp." + + + An initialism for Point-to-Point Protocol. + + + + + + + press + + + v. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." + + + + + + + proof of concept + + + Use the following rules to form the plural of this phrase: + + + + Use "proofs of concept" for multiple proofs and only one concept. + + + + + + Use "proofs of concepts" for multiple proofs and multiple concepts. + + + + + + Do not use "proof of concepts." + + + + + + + + + + + + + pseudo-ops + + + Correct. Do not use "pseudo ops" or "pseudoops." + + + + + + + pull-down + + + adj. Use only if you must specify the type of menu or list. Do not use "pulldown." + + + + + + + push-button automation, turn-key automation + + + Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use accurate language for the situation, such as: + + + + + User-triggered automation + + + + + + Ready-to-use, ready-to-deploy + + + + + + Self-service, self-provisioned. + + + + + + Single-step automation + + + + + + On-demand automation + + + + + + + + + + + PXE + + + Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. + + + PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. + + + + + + + + + diff --git a/tmp/en-US/xml/Preface.xml b/tmp/en-US/xml/Preface.xml new file mode 100644 index 0000000..264ab5b --- /dev/null +++ b/tmp/en-US/xml/Preface.xml @@ -0,0 +1,12 @@ + + +%BOOK_ENTITIES; +]> + + Preface + + + + + diff --git a/tmp/en-US/xml/Punctuation.xml b/tmp/en-US/xml/Punctuation.xml new file mode 100644 index 0000000..88437ec --- /dev/null +++ b/tmp/en-US/xml/Punctuation.xml @@ -0,0 +1,470 @@ + + +%BOOK_ENTITIES; +]> +
+ Punctuation + + This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. + +
+ Colons and Semicolons + + Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. + + + To relate clauses: + + The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: + + + + + + + They had been writing code all night: this factor could explain their bloodshot eyes. + + + + + + They had been writing code all night; this factor could explain their bloodshot eyes. + + + + + + I spend a lot of money on food; last month, I went out to eat 36 times. + + + + + + I spend a lot of money on food: last month, I went out to eat 36 times. + + + + + + + The phrase following a semicolon or colon should begin with a lowercase letter, unless it begins with a proper noun. In the case of a colon, use an uppercase letter if the phrase constitutes a complete sentence on its own. + + + Try to limit your use of colons and semicolons. Separate sentences with a period if possible. + + + To introduce a list or series: + + A colon is generally used before a list or series. + + + + + + + The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill. + + + + + + + Do not use a colon if the list is a complement or object of an element in the sentence. + + + + + Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail. + + + + + + The colors I hate most are: + + + + + green + + + + + + orange + + + + + + pink + + + + + + magenta + + + + + + + + + + + Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. + + + + + The steps for changing directories are as follows: + + + + + Open a terminal. + + + + + + Type cd Documents/Books. + + + + + + + + + + + Use a colon to introduce a bullet list. + + + + + In the Properties dialog box, notice the following entries: + + + + + Connection name + + + + + + Count + + + + + + Confirm starting connection + + + + + + Confirm stopping connection + + + + + + Cost per + + + + + + + + + + + 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 semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + + + + + I think; therefore, I am. + + + + + + +
+
+ Commas + + In compound sentences: + + Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. + + + + + + + I spent five hours working on this document, but I lost it when my computer crashed. + + + + + + Do you want to go the mall and the grocery store with me, or are you going to watch football instead? + + + + + + You play and I'll sing. + + + + + + + A comma can be omitted from a sentence with several clauses, but only when there is little chance that the sentence could be misread without it. + + + + + We played football all afternoon and were completely exhausted but we still stayed up watching movies all night. + + + + + + + That sentence is acceptable, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence. + + + In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction. + + + + + You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice. + + + + + + + In adverbial clauses and phrases: + + If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: + + + + + + + I'll go to lunch with you if we can get pizza. + + + + + + I don't want to go out for pizza, because I had pizza yesterday. + + + + + + + If a dependent clause comes before the main clause, use a comma whether the clause is restrictive or not. + + + + + If we get pizza, I'll go to lunch with you. + + + + + + When I heard the voice on the other end of the line, I was quite surprised. + + + + + + + In adjectival clauses or phrases: + + An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. + + + + + + + The application, which comes with excellent documentation, is used by many graphic artists. + + + + + + + An adjectival clause that cannot be dropped without changing the meaning of the sentence is not set off with commas: + + + + + The plan that matters most to us will be easy to implement. + + + + + + + With coordinate adjectives: + + Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. + + + + + + + My dog is loyal, obedient, and affectionate. + + + + + + It was a long, boring meeting. + + + + + + + With series and lists: + + Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. + + + + + + + Today I am wearing socks, shoes, pants, and a shirt. + + + + + + +
+
+ Parentheses + + Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. + + + + + I tried to get to the elevator before the door shut, but I was too slow. + + + + + + Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead. + + + + + + + Expressions beginning with for example, that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. + + + + + He interviewed the biggest stars of the day, namely, Madonna, Johnny Cash, and Jack Nicholson. + + + + + + Classic works of literature (such as Dickens, Shakespeare, the Brontes) lined the shelves. + + + + + + + If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. + + +
+
+ Quotation Marks + + Commas and periods go inside quotation marks. + + + Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. + + + A Correct Example of the Use of Quotation Marks + + For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." + + + + +
+
+ Apostrophes + + Do not use an apostrophe to denote a plural. + + + To denote a possessive, use an apostrophe as follows: + + + Plural nouns not ending in s should add an 's (for example, the alumni's contribution). + + + Plural nouns ending in s only need an apostrophe (for example, the horses' food). + + + Singular common nouns ending in s should add an 's unless the next word begins with an s (for example, the witness's answer or the witness' story). + + + Singular proper names ending in s only need an apostrophe (for example, Dickens' novels). + + +
+ +
+ diff --git a/tmp/en-US/xml/Q.xml b/tmp/en-US/xml/Q.xml new file mode 100644 index 0000000..6b600a9 --- /dev/null +++ b/tmp/en-US/xml/Q.xml @@ -0,0 +1,52 @@ + + +%BOOK_ENTITIES; +]> + + Q + + + Q and A + + + n. Abbreviation for "Question and Answer," this format is listed in the American Heritage Dictionary. + + + + In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. + + + + + + + + + qeth + + + Lowercase at all times. + + + + + + + + + + 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. + + + + + + + + + diff --git a/tmp/en-US/xml/R.xml b/tmp/en-US/xml/R.xml new file mode 100644 index 0000000..6008d7a --- /dev/null +++ b/tmp/en-US/xml/R.xml @@ -0,0 +1,240 @@ + + +%BOOK_ENTITIES; +]> + + R + + + RAM + + + Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." + + + + + + + RAM disk + + + 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. + + + + + + + raw + + + Unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device. + + + The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device. + + + + + + + raw data + + + Information that is not organized, formatted, or analyzed. + + + + + + + read + + + v. To copy data to a place where a program can use it. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. It can also refer to the act of determining the contents of a variable or parameter. + + + n. The act of reading. For example, a fast disk drive performs 100 reads per second. + + + + + + + read-only + + + Capable of being displayed, but not modified or deleted. For all operating systems, you can protect objects (disks, files, or directories) with a read-only attribute that prevents other users from modifying the object. + + + + + + + read/write + + + Capable of being displayed (read) and modified (written to). Most objects (disks, files, or directories) are read/write, but you can also protect objects with a read-only attribute that prevents other users from modifying the object. + + + + + + + real time/real-time + + + n. The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." + + + adj. Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." + + + + + + + reboot + + + Correct. Do not use "re-boot." + + + + + + + RedBoot + + + Correct. Do not use "Redboot" or "Red Boot." + + + + + + + refer to + + + Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." + + + + + + + remote access + + + The ability to log on to a network from a distant location. Generally, it implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations that are connected directly to the network is slower data transfer speeds. + + + + + + + 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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. + + + + + + + required + + + See . + + + + + + + return + + + When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. See for other platforms. + + + + + + + right-click + + + v. Write the term hyphenated. Do not use "right click." + + + + + + + right now + + + Use "now" instead. + + + + + + + ROM, PROM + + + Acronym for read-only memory, computer memory on which data is prerecorded. After data has been written to a ROM chip, it cannot be removed and can only be read. + + + A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a device called a PROM programmer. + + + + + + + roundtable, round table + + + v. Use the one-word form to refer to a type of event or gathering. + + + n. Use the two-word form to refer to a circular table. + + + + + + + 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." + + + + + + + runlevel + + + Correct. Do not use "run level" or "run-level." + + + + + + + + + diff --git a/tmp/en-US/xml/Resources.xml b/tmp/en-US/xml/Resources.xml new file mode 100644 index 0000000..8cf6776 --- /dev/null +++ b/tmp/en-US/xml/Resources.xml @@ -0,0 +1,143 @@ + + +%BOOK_ENTITIES; +]> + + Resources + + This section lists some books and websites for you to consult on your quest to create a better document. + + + The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: + + + + Technical content: software manuals and documentation, user guides, training courses + + + + + + Technical collateral: white papers and technology briefs + + + + + + Marketing content: advertising, promotions, articles + + + + + + Corporate collateral: related to company or products + + + + + + Press releases + + + + + + + +
+ References for Technical Content and Collateral + + + + IBM Style Guide. IBM Corporation, latest version. + + + + + + The Chicago Manual of Style, 17th Edition. Chicago: The University of Chicago Press, 2017. + + + + + + Merriam-Webster Collegiate Dictionary + + + Visit https://www.merriam-webster.com/ for subscription options. + + + + + + The American Heritage Dictionary of the English Language + + + An online edition is accessible free of charge through http://www.ahdictionary.com/ + + + + + + +
+
+ References for Marketing and Corporate Collateral + + + + AP Stylebook Online + + + + + + Merriam-Webster Online http://www.merriam-webster.com/ + + + + + + +
+ + + diff --git a/tmp/en-US/xml/Revision_History.xml b/tmp/en-US/xml/Revision_History.xml new file mode 100644 index 0000000..4ee2645 --- /dev/null +++ b/tmp/en-US/xml/Revision_History.xml @@ -0,0 +1,524 @@ + + +%BOOK_ENTITIES; +]> + + Revision History + + + + 3-0 + July 2021 + + Julian + Cable + jcable@redhat.com + + + + Major update to align with some recent changes in IBM Style. + Sentence case is required for captions, legends, and diagram labels. + Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. + Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. + Minor edits so the guide itself conforms with its own advice. + + + + + + + + 2.0-1 + Wed Jun 3 2015 + + David + O'Brien + davido@redhat.com + + + + Fix issue "use 'singular to plural' pronouns -- typo? #6 . + Repair some XML in the grammar section. + Minor repairs to language. + + + + + + + + 1.6-14 + Wed Mar 12 2014 + + David + O'Brien + davido@redhat.com + + + + Added entry for "huge pages". + Updated entry for virtual machine to allow for abbreviation. + Updated section on using non-breaking spaces. + Added entry for correct capitalization of partners. + Added entry for "datasheet". + Change to common brand. + Remove some internal links that are no longer valid. + Generalize some entries based on advice from legal. + + + + + + + + 1.6-13 + Wed Feb 26 2014 + + David + O'Brien + davido@redhat.com + + + + 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. + 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. + + + + + + + + 1.6-12 + Fri Dec 20 2013 + + David + O'Brien + davido@redhat.com + + + + General cleanup of "U" section. BZ 1037923: Added entry for "uninterruptible". + General cleanup of "T" section. BZ 1038090: Added entry for "tier-1". + General tidy-up. Fix some typos. Updates cross-references. Started on BZ 820071. + + + + + + + + 1.6-11 + Wed Nov 27 2013 + + Julie + Wu + docs@redhat.com + + + + BZ 997202 Remove incorrect content regarding Japanese translation. + + + + + + + + 1.6-10 + Mon Nov 25 2013 + + Brice + Fallon-Freeman + docs@redhat.com + + + + BZ 1022268 Add entry for "time frame" + BZ 1022266 Add entry for "roundtable" + BZ 1027041 Add entry for "big data" + + + + + + + + 1.6-9 + Wed Nov 20 2013 + + David + O'Brien + docs@redhat.com + + + + Add balance of entries from "Things Shadowman would Never Say". + + + + + + + + 1.6-8 + Tue Nov 12 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 896006 Add entry for "health check". + BZ 896009 Add entry for "skill set". + BZ 924040 Add entry for referring to fonts. + BZ 915987 Add entry for "bare metal". + Add exception for Brand and Marketing heading styles. + BZ 1017549 Added entry for how to use URLs and footnotes. + BZ 1019258 Fixed Gunning Fog typo Ch 1 under "Readability". + BZ 989838 Updated entry for x86 usage. + BZ 1010163 Added entry for "Q and A". + BZ 821606 Updated entry for qeth based on new information. + BZ 1017149 Add entry for DevOps. + BZ 972916 Add entries for GNOME and GNOME Classic; document use of Super key. + General review and updates to examples. + Fix some revision history entries. + + + + + + + + 1.6-7 + Mon Aug 12 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 995310 Add entry for documenting command syntax. + BZ 984803 Add entry for online and offline backups. + BZ 989942 Add entry How to document Interface element labels. + BZ 989838 Update entries for referring to AMD64, Intel 64, x86, and related terms. + + + + + + + + 1.6-6 + Wed Jul 31 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 892839 Update entry for internet. + BZ 980307 Add entry for hyphenation. + BZ 965898 Add entry for documenting currencies. + BZ 989942 Add entry for documenting interface elements to Design section. + Various punctuation and spelling fixes. + + + + + + + + 1.6-5 + Wed Jul 17 2013 + + Julie + Wu + docs@redhat.com + + + + BZ 973074 Add entry for "talking to" in section on slang + BZ 950303 Add entry for SIOV + BZ 965378 Update entry for "Unset" + + + + + + + + 1.6-4 + Thu May 23 2013 + + David + O'Brien + docs@redhat.com + + + + Add "cloudbursting," "cloudwashing," and "pluggable" to usage dictionary. + + + + + + + + 1.6-2 + Tue Mar 19 2013 + + David + O'Brien + docs@redhat.com + + + + 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. + BZ 909015 Entry for "refer to" conflicts with IBM style guide. + Update some punctuation standards and cross references. + + + + + + + + 1.6-1 + Wed Jan 30 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 905707 Update section on active and passive voice with more examples and exceptions. + BZ 896245 Describe use of non-breaking spaces with company and product names. + BZ 821603 Add entry for Sybase Adaptive Server Enterprise usage. + + + + + + + + 1.6-0 + Tue Jan 15 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 823350 Additional Detail for Chapter 2.4 + BZ 821609 Add correct usage of PHP to Usage Dictionary + BZ 831909 Remove "in depth" from Usage Dictionary; covered in standard references. + BZ 868067 Add usage for PaaS, IaaS, and SaaS + BZ 821615 Correct use of JVM + BZ 836869 Update SSH entry to allow for lowercase version + BZ 829173 Add correct usage of "time to live" to Usage Dictionary + BZ 821616 capitalization when referring to Btrfs + BZ 821612 Usage Dictionary addition: "zip" + BZ 824209 word usage: segfault + BZ 821599 Documenting exceptions + BZ 821607 Definitions for Virtual Machine, Virtualized Guest + BZ 821606 should we say "QETH device" or "qeth device" + BZ 820480 Add "cgroups" to Usage Dictionary + + + + + + + + 1.5-5 + Wed Nov 21 2012 + + David + O'Brien + docs@redhat.com + + + + BZ 878313 - Duplicate "and" in entry for AMD 64. + Review and update sections M, N, T, U, and V. + + + + + + + + 1.5-4 + Sun Nov 11 2012 + + David + O'Brien + docs@redhat.com + + + + Remove "hostname" entry; covered in IBM. + + + + + + + + 1.5-3 + Thu Nov 08 2012 + + David + O'Brien + docs@redhat.com + + + + BZs 871652, 820071, 821611, 821610. + Updates to and integration of Chapters X, Y, and Z. + Updated section on "Avoiding Slang." + Removed some redundant entries. + Various cleanups based on IBM Style Guide. + New entries from Word Nerds discussions. + + + + + + + + 1-4 + Fri Aug 31 2012 + + David + O'Brien + docs@redhat.com + + + + Removed some redundant entries. + Bugs 851646, 850596, 821595, 821617. + + + + + + + + 1-3 + Sun Aug 26 2012 + + David + O'Brien + docs@redhat.com + + + + Removed some redundant entries. + Patched some entries based on IBM Style Guide. + Cleaned up A, B, C, and part of D in Word Usage Dictionary. + + + + + + + + 1-2 + Fri Jul 27 2012 + + David + O'Brien + docs@redhat.com + + + + Added some xrefs to make life simpler. Added some temp links to BZs that are yet to be addressed. + More work on punctuation, spelling, typos, and duplicate and redundant entries. + Some structure reorganization. + Updated Feedback page. + Removed Author Group. + + + + + + + + 1-1 + Fri Apr 13 2012 + + David + O'Brien + docs@redhat.com + + + + Clean up redundant variablelist tags. + Remove a few duplicate entries. + Start working on making punctuation consistent. + + + + + + + + 1-0 + Mon Feb 20 2012 + + Gemma + Sheldon + gsheldon@redhat.com + + + + DocBook conversion from original guide on the Intranet. + + + + + + + + + + + + diff --git a/tmp/en-US/xml/S.xml b/tmp/en-US/xml/S.xml new file mode 100644 index 0000000..21f6bc0 --- /dev/null +++ b/tmp/en-US/xml/S.xml @@ -0,0 +1,760 @@ + + +%BOOK_ENTITIES; +]> + + S + + + S/390 + + + Use the full description "IBM S/390." Do not use "s390," "S390," or any other variations. + + + + + + + SaaS + + + The correct abbreviation for "Software-as-a-Service." See also . + + + + + + + Samba + + + Correct. Do not use "samba" or "SAMBA." + + + + + + + record + + + Correct. Do not use "s-record," "Record," "s-Record," or any other variations. + + + + + + + screen capture + + + n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. + + + + + + + screen saver + + + n. Do not use "screensaver." + + + + + + + scrollbar + + + n. Do not use "scroll bar" or "scroll-bar." + + + + + + + secure + + + n., vb. Due to potential legal ramifications, do not use without a qualifier. See for examples. + + + Using Qualifiers with Sensitive Terms + + + + + + Original text + Improvement + + + + + + + With this new version, the application is running on a secure, gateway-protected endpoint. + With this new version, the application is running on a more secure, gateway-protected endpoint. + + + + This function secures your connection. + This function improves the security of your connection. + + + + Developers can easily change the code to implement secured access. + Developers can easily change the code to make access more secure. + + + + + + + +
+ + + + + + see + + + Use to refer readers to another resource. Avoid using "refer to" in this context. + + + + + + + segmentation fault + + + n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. + + + See also "What is a segfault?" on the Red Hat Customer Portal for more information. + + + + + + + SELinux + + + 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. + + + + + + + send out + + + Do not use. Instead, use "emit" or "issue." + + + + + + + server farm + + + Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. + + + + + + + server-side/server side + + + See . + + + + + + + setup + + + Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: + + + + + Each setup provides different features. + + + + + + You need to set up a user profile as part of the registration process. + + + + + + Follow the set-up instructions included with the hardware. + + + + + + + + + + + SHA-1, SHA-2 + + + 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. + + + See for full details. + + + + + + + Shadowman + + + Correct. Do not use "Shadow Man" or "ShadowMan." The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. + + + + + + + shadow passwords + + + Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. + + + Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package. + + + + + + + shadow utilities + + + Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. + + + + + + + share name + + + Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." + + + + + + + shebang + + + n. Refers to the character sequence consisting of the number sign and exclamation mark (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. + + + + + + + shell + + + A "shell" is a software application, for example, /bin/bash or /bin/sh, which provides an interface to a computer. Do not use this term to describe where to type commands. + + + + + + + shell prompt + + + Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt," "terminal," or "shell." + + + + + + + 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 . + + + + + + + shut down + + + v. Correct. Do not use "shut-down." Only use "shutdown" when referring to the /sbin/shutdown system command. + + + + + + + sign in + + + v. Write as two words. For example, "two options are available to sign in". + + + + + + + sign in to + + + v. Write as three words. For example, "to sign in to the system". + + + + + + + simply + + + Do not use. See also . + + + + + + + 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. + + + + + + + skill set, skills, knowledge + + + n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: + + + Example Use of Term "Skillset" Versus "Skills" + + Incorrect: Do you have the right skillset to be an RHCE? + + + Correct: Do you have the right skills to be an RHCE? + + + + + Example Use of Term "Knowledge" + + Incorrect: This course gives you the skill-set knowledge to complete your RHCT exam successfully. + + + Correct: This course gives you the knowledge to complete your RHCT exam successfully. + + + + + + + + + SLA + + + n. SLA stands for Service Level agreement. The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. + + + + + + + smart card + + + n. Do not use smartcard or smart-card. + + + + + + + SOCKS + + + Correct. Do not use "socks." When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5." + + + + + + + softcopy + + + Do not use. Instead, use "online." For example, "To view the online documentation ..." + + + + + + + sound card + + + n. Do not use "soundcard" or "sound-card." + + + + + + + Source-Navigator™ + + + Correct. Do not use "Source Navigator." Source-Navigator™ is a trademark of Red Hat. + + + + + + + source + + + v. In addition to the generic use of this term as a noun and verb, in a programming and technical sense, it also means "Run the source command against the named file." + + + + + + + space + + + Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key. + + + + + + + Spacebar + + + n. Use when referring to the keyboard key, such as "Press the Spacebar key to continue." + + + + + + + spec file + + + n. Use to refer to an RPM spec file. Do not use "specfile." + + + + + + + specific + + + When used as a modifier, put a hyphen before "specific," such as "MIP-specific," "Linux-specific," and "chip-specific." + + + + + + + spelled + + + Correct. It is the standard US English spelling. Do not use "spelt." + + + + + + + SQL + + + When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. + + + When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. + + + Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." + + + More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." + + + + + + + SR-IOV + + + Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. + + + + + + + SSH + + + Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. + + + Do not use as a verb. + + + Example Use of "SSH" + + Incorrect: To begin, "ssh to the remote server." + + + Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar. + + + + + + + + + SSL + + + Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. + + + + + + + stand-alone + + + adj. Write hyphenated. 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. + + + + + + + StarOffice + + + A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." + + + The successors of StarOffice are and . + + + + + + + start up + + + v. Do not use. Instead, use "activate" or "invoke." + + + + + + + startx + + + Correct. Do not use StartX or other variants. + + + + + + + straightforward + + + adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward." + + + + + + + su + + + Correct. The Linux command to change to a named user. Do not use SU (all caps). + + + + + + + subcommand + + + Correct. Do not use "sub-command" or "verb." A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: + + +hammer import organization --help + + In this example, "hammer" is the main or primary command, and "import" and "organization" are subcommands. is an option. + + + See also . + + + + + + + subdirectory + + + Correct. Do not use "sub-directory." See also . + + + + + + + submenu + + + Correct. Do not use "sub-menu." See also . + + + + + + + subpackage + + + Correct. Do not use "sub-package." + + + This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages." + + + Any other use of this word is strongly discouraged. + + + Note: Subpackages are not the same as dependencies and should not be treated as such. + + + + + + + superuser + + + A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." + + + + + + + swap space + + + Correct. Do not use "swapspace." Capitalize at the beginning of a sentence only. + + + + + + + Sybase Adaptive Server Enterprise (ASE) + + + Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE." If discussing the high-availability version, use "Sybase ASE and High Availability." + + + See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. + + + + + + + SysV + + + Correct. Do not use Sys V or System V. + + + + + + + symmetric encryption + + + A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. + + + + + + + + + diff --git a/tmp/en-US/xml/Slang.xml b/tmp/en-US/xml/Slang.xml new file mode 100644 index 0000000..1d81678 --- /dev/null +++ b/tmp/en-US/xml/Slang.xml @@ -0,0 +1,877 @@ + + +%BOOK_ENTITIES; +]> + + Avoiding Jargon, Slang, Metaphors, and Misleading Language + + Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + + + If you find slang terms or other difficult-to-understand passages in our documentation, use this page to search for alternatives. + +
+ Avoiding Misleading or Confusing Language + + Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. + + + + best practices + + + This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." + + + See the section for additional information about recommendations in Red Hat documentation. + + + + + + + first come, first served + + + Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. + + + + + + + + +
+
+ Identifying and Avoiding Slang + + Examples of slang terms: + + + + administrivia + + + Not a word. Do not use. + + + + + + + anything you/they like + + + This is probably readily understood but should not appear in Red Hat documentation. + + + + + "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." + + + Rephrase to something more suitable, such as "...to register any other kind of plug-in." + + + + + + + + + + + ask (as a noun), make the ask + + + Ask is a verb. Do not use it as a noun. + + + + + + + at this point in time + + + Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. + + + + + + + automagic + + + Also, automagical. Both terms are slang. Do not use. + + + + + + + best-of-breed + + + Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + + + + + + + bleeding edge + + + Do not use. + + + + + + + bottom line + + + Traditionally used in financial contexts; avoid overuse. + + + + + + + bucketize + + + Not a word. Try "categorize" or "organize into logical groups." + + + + + + + center of competency + + + Do not use. + + + + + + + check this site + + + Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + + + + + + + coopetition + + + Not a word. Do not use. + + + + + + + core competency + + + Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," etc. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + + + + + + + eat your own dogfood + + + Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + + + + + + + data point + + + Do not use. + + + + + + + dig deeper, delve deeper + + + "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + + + + + + + double-edged sword, double-bladed sword + + + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + + + + + + + enterprise-ready + + + Although we used to use this term to emphasize our products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + + + + + + + exceed your expectations + + + Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + + + + + + + fib + + + A fib is a "small lie," also known as a "white lie." This appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." + + + + + + + flying by the seat of your pants + + + Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. + + + + + + + frame it up + + + Do not use. + + + + + + + frown upon + + + "To frown upon" means to hold in low regard, not to approve of, etc. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + + + + + + + fuzzy (search) + + + Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: + + + + + In Directory Server, if you do a fuzzy search for "Smith" you will probably also get "Smyth," because it sounds the same. + + + + + + + The use of "fuzzy" is valid in this context. + + + Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." + + + Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. + + + + + + + going-forward basis + + + Jargon. Say "from now on," "in the future," or something similar. + + + + + + + happy path + + + Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is very localized slang and could easily be misunderstood. It could also produce problems for translation. + + + + + + + harness the power + + + Do not use. + + + + + + + have a crack at/jump right in + + + Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. + + + + + + + if you want, if you wish + + + Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." + + + + + + + in concert with + + + Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." + + + + + + + improve, enhance + + + Vague. Try to be more specific. + + + + + + + in a pinch + + + Under a tight schedule, hard pressed to achieve something. + + + + + + + infomediary + + + Not a word. Do not use. + + + + + + + is designed to + + + Avoid this and similar phrases when describing products and services. Instead, state what the product does. + + + + + Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. + + + + + + Correct: SSH works with almost any kind of public key algorithm or encoding format. + + + + + + + + + + + kettle of fish + + + Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. + + + + + + + leverage + + + Avoid. Alternatives include "use" and "take advantage of". + + + + + + + lights on, lights-on + + + Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. + + + Typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." + + + + + + + low-hanging fruit + + + Metaphor. Do not use. + + + + + + + marketecture + + + Not a word. Do not use. + + + + + + + meet your needs + + + Vague. Try to be more specific, for example, "lower your middleware costs." + + + + + + + mission-critical + + + Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Make sure you have the applications you need to help your customers." vs. "Make sure you have the mission-critical applications your customers demand." + + + + + + + net-net + + + Jargon. Use "in summary," "the end result," or something similar. + + + + + + + niche focus + + + Do not use. + + + + + + + over the wire + + + Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent/transmitted in plain text" is fine. + + + + + + + pain in the backside + + + Nobody should ever write this or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. + + + + + + + paradigm + + + Avoid. Use "model," "standard," or something similar. + + + + + + + performant + + + In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. + + + + + + + physicalize + + + Not a word. Do not use. + + + + + + + piggyback + + + Slang. Do not use. + + + + + + + pre-baked + + + Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. + + + + + + + productize + + + Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] + + + + + + + ready to rumble + + + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." + + + + + + + rest on your laurels + + + Do not use. + + + + + + + right before doing something + + + Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. + + + + + + + root your server in the /serverRoot directory + + + This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. + + + + + + + shoot yourself in the foot + + + To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Remove the sentence - it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + + + + + + + shy of + + + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang. + + + + + + + silo, siloed + + + Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," "segregated," or something similar. + + + + + + + solutioning + + + Not a word. Lazy version of "creating a solution." + + + + + + + solutions-based + + + Do not use. + + + + + + + solution stack + + + Do not use. + + + + + + + stovepipe + + + Jargon. In business, related to lack of cross-organizational communication, similar to "silo." + + + + + + + synergistic, synergy + + + Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. + + + + + + + synergical connectivity + + + Seriously? + + + + + + + to think outside the box + + + 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? + + + + + + + tunnel vision + + + Do not use. + + + + + + + under the covers + + + This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + + + + + + + value-added + + + Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." + + + + + + + very + + + Use with caution. For example, there is little value in saying "very cost-effective" vs. "cost-effective." + + + + + + + virtual elephants + + + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. + + + + + + + + +
+
+ Neologisms (Invented Words) + + The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. + + + Examples + + + "This feature allows synchronization of adds, deletes, and changes ..." + + + + + This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + + + + + + + + + + +
+
+ Anthropomorphism + + Anthropomorphism is applying human qualities to non-human things or animals. Avoid this in your writing. + + + Examples + + + The computer will think for a brief period. + + + + + Computers do not actually think but they might take a while to "process" commands. + + + + + + + + + + The Proxy Server is talking to either RHN Hosted or a Satellite Server. + + + + + It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. + + + + + + + + + + + Report an issue + + +
+ + + diff --git a/tmp/en-US/xml/T.xml b/tmp/en-US/xml/T.xml new file mode 100644 index 0000000..4d54550 --- /dev/null +++ b/tmp/en-US/xml/T.xml @@ -0,0 +1,244 @@ + + +%BOOK_ENTITIES; +]> + + T + + + taskbar + + + n. One word. Do not use "task bar." + + + + + + + tar, tarball + + + n. See the Word Usage chapter of the IBM Style Guide. + + + + + + + telco + + + Preferred abbreviation for "telecommunications company." Do not use "telecom." See also . + + + Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. See . + + + + + + + telecommunications service provider + + + Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . + + + + + + + telecommunications + + + Vertical for communication service providers. Preferred abbreviation is "telco." + + + + + + + terminal + + + n. Do not use to describe where to type commands. Use "command line" instead. + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + terminal emulation + + + Refers to making a computer respond like a particular type of terminal. With a terminal emulation program, you can access a mainframe computer or bulletin board service with a personal computer. + + + + + + + text mode + + + Correct. Do not use "textmode" or "text-mode." + + + A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. + + + + + + + text-based + + + adj. Correct. Do not use "text based." + + + + + + + third-party (adj.), third party (n.) + + + adj., n. Use "third-party" as the adjectival form. Use "third party" as the nominal form. Consult a dictionary for more examples. + + + + + + + through + + + Correct. Do not use "thru" and do not use the hyphen or any other type of dash. + + + + + + + throughput + + + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. + + + + + + + tier-1 + + + adj. Always use a numeral, and always hyphenate. Follow standard capitalization guidelines. + + + + + + + time frame (n.) + + + Correct. Do not use "timeframe" or "time-frame." + + + + + + + time zone (n.) + + + Correct. Do not use "timezone" or "time-zone." + + + + + + + token-ring (n.) + + + 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. + + + + + + + toolbar (n.) + + + Correct. Do not use "tool bar" or "tool-bar." + + + + + + + tooltip (n.) + + + Correct. One word. Use the term "tooltip" to refer to a brief, textual description that is displayed when a cursor is moved over a graphical image, such as an icon or button. Do not use the term "hover help". + + + + + + + totally + + + Do not use. See "basically." + + + + + + + troubleshoot (v.) + + + Correct. Do not use "trouble shoot" or "trouble-shoot." + + + + + + + TTL + + + Initialism for "time to live" (n.) and "time-to-live" (adj.) + + + Neither the noun nor the adjective should be capitalized unless you are documenting a GUI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. + + + + + + + type + + + Type can be used as either a verb or noun. You can write "Print the data type of init" or "To start Source-Navigator, type snavigator." + + + + + + + + + diff --git a/tmp/en-US/xml/Template_Chapter.xml b/tmp/en-US/xml/Template_Chapter.xml new file mode 100644 index 0000000..ca70987 --- /dev/null +++ b/tmp/en-US/xml/Template_Chapter.xml @@ -0,0 +1,20 @@ + + +%BOOK_ENTITIES; +]> + + Dummy Title + + dummy text + +
+ Dummy Section Title + + More dummy text. + + +
+ + + diff --git a/tmp/en-US/xml/Template_Section.xml b/tmp/en-US/xml/Template_Section.xml new file mode 100644 index 0000000..914bdd7 --- /dev/null +++ b/tmp/en-US/xml/Template_Section.xml @@ -0,0 +1,12 @@ + + +%BOOK_ENTITIES; +]> +
+ + + + +
+ diff --git a/tmp/en-US/xml/Translation.xml b/tmp/en-US/xml/Translation.xml new file mode 100644 index 0000000..4cfe7c6 --- /dev/null +++ b/tmp/en-US/xml/Translation.xml @@ -0,0 +1,373 @@ + + +%BOOK_ENTITIES; +]> + + Writing Clearly and Succinctly + + This chapter provides guidelines, tips, and techniques to help to make your writing easier to read and understand, and also to translate. + +
+ Sentence Structure + + This section describes how to construct your content for clarity and readability. A full discussion of this topic is beyond the scope of this guide. + +
+ Using and Formatting Lists + + 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 sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. + + + The following general guidelines apply to lists: + + + + Itemized lists + + + 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. Titles are optional. + + + + + + + Ordered lists + + + They appear as a numbered list. 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. + + + + + + + Variable lists + + + They 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.) A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. Tables are best reserved for information that relies on, or benefits greatly from, a grid layout. + + + + + + + Procedures + + + They appear as a list of numbered steps. Procedures always include a title, and are used to list the required steps to achieve a task. + + + + + + + + + You can nest lists, but try to keep the number of levels to two or fewer. To nest procedures in DocBook, use <substep> elements. + +
+ Formatting Lists for Readability + + It is important to provide sufficient 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. If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. DocBook uses the spacing attribute by default. + + + Use a list with normal spacing if any list item contains the following components: + + + + + Nested lists. Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + + + + + + Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). + + + + + + Multiple paragraphs, or sentences that wrap to two or more lines. + + + + + + + Use a list with compact spacing in all other cases. + + + + The use of all but the simplest graphics in lists is strongly discouraged. + + + + + The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. + + + + + + + + + Example + Improvement + + + + + + + + Before you start the installation, ensure that you have + + + + + enough free storage on your system + + + + + + backed up any data that you want to keep + + + + + + + to ensure a smooth installation. + + + + Before you start the installation, follow these steps to ensure a smooth installation: + + + + + Ensure that you have enough free storage on your system. + + + + + + Back up any data that you want to keep. + + + + + + + + + + + + + +
+ +
+ +
+
+ Noun Stacking + + Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. + + + + + + + + + Example + Improvement + + + + + + + Plastic tubing and syringe tips. + Plastic tubing and plastic syringe tips. + + + + Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press Enter. + For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. + + + + + + + +
+ +
+ +
+
+ Grammatical Genders + + When using ambiguous pronouns such as "they" or "it", it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and might require other grammatical adjustments. + + + Further, an initialism such as RPM might refer to the package or to the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package. + + + + + + + + + Example + Improvement + + + + + + + Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. + Set the XYZ parameter to 1 in the /etc/config.conf configuration file. This parameter configures how the Gateway application handles incoming network traffic. + + + + The RPM is useful. + The RPM package is useful. OR The RPM Package Manager is useful. + + + + + + + +
+ +
+
+ DocBook Elements + + Use the correct DocBook elements to help translators to understand the meaning of, and to identify, translatable and non-translatable terms. + + + Tagged Terms in Sentences + + Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators must complete the blanks or tag terms themselves. + + + + + + + + + + + Example + Improvement + + + + + + + In /some/path/, grep for XYZ. + In the /some/path/ directory, use the grep command to search for "XYZ". + + + + contains a reference to the hostname return value from instance-2. + The parameter contains a reference to the hostname return value from your second server instance, instance-2. + + + + Troubleshooting Glance. + Troubleshooting the Glance image service. + + + + Installing the maven-changelog-plugin. + Installing the maven-changelog-plugin package. + + + + + + + +
+ +
+
+ Code Blocks + + Avoid including commentary within the same box as command input or output. These comments might be confused with part of the output, and during translation might be accidentally overlooked and left in English. + + + For example, consider the word "Usage" in the following block: + + +Usage: rhevm-iso-uploader [options] list +rhevm-iso-uploader [options] upload [file1] [file2] [file3] + +
+
+ Entities + + An entity is a primitive data type, which associates a string with either a unique alias (such as a user-specified name) or an SGML reserved word (such as #DEFAULT) + + + . Entities are called by reference, and take the form &name; (both the ampersand and the semicolon are required). + + + Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. + + + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: + + + + + PRODUCT + + + + + + BOOKID + + + + + + YEAR + + + + + + HOLDER + + + + + + + Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in + + +
+ + + diff --git a/tmp/en-US/xml/U.xml b/tmp/en-US/xml/U.xml new file mode 100644 index 0000000..a375dea --- /dev/null +++ b/tmp/en-US/xml/U.xml @@ -0,0 +1,226 @@ + + +%BOOK_ENTITIES; +]> + + U + + + UID + + + n. UID and user ID are abbreviations of user identifier. Do not use "uid" or "User ID" or other variations unless specifically referring to a variable, argument, parameter, UI label, or similar. + + + + + + + UltraSPARC + + + Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. + + + 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. + + + + + + + undercloud + + + n. 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 . + + + + + + + uninterruptible + + + adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)." + + + + + + + UNIX + + + Correct. Do not use "Unix" or "unix." + + + UNIX is a registered trademark of The Open Group. + + + Do not use "UNIX-like." Use an expression such as "Linux, UNIX, and similar operating systems" instead. + + + + + + + unset + + + Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. + + + To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. + + + This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. + + + + + + + untrusted + + + Use only in the context of security relationships. For example, web browsers often indicate that a site is "untrusted" if it cannot verify that site's security certificate. + + + + + + + upgrade + + + v. Correct. Do not use "up-grade" or "up grade." + + + + + + + UPS + + + Abbreviation of uninterruptible power supply, a power supply that includes a battery to maintain power in the event of a power outage. + + + + + + + upsell (v.), upselling (n.) + + + Marketing Use Only + + "The practice of offering customers additional or more expensive products or services after they have already agreed to buy something. + http://www.ahdictionary.com/word/search.html?q=upsell + + " + + + Do not hyphenate or use as two words. No adjectival form is currently recognized. + + + + + + + + + upstream + + + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream." + + + + + + + uptime + + + n. Correct. Do not use "up-time" or "up time." + + + + + + + URL + + + n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. + + + See for more information. + + + + + + + user + + + n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. + + + If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." + + + + + + + user interface + + + n. Correct. Do not use "user-interface" or "userinterface." + + + 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. + + + + + + + user name + + + n. Correct. Do not use "username" unless you are using it as a variable. + + + + + + + user space + + + n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space." Do not use "userspace." + + + + + + + utilize + + + Avoid this term. Write "use" instead. + + + + + + + + + diff --git a/tmp/en-US/xml/V.xml b/tmp/en-US/xml/V.xml new file mode 100644 index 0000000..5ff8aef --- /dev/null +++ b/tmp/en-US/xml/V.xml @@ -0,0 +1,137 @@ + + +%BOOK_ENTITIES; +]> + + V + + + VAR + + + Acronym for value-added reseller. Same as OEM (original equipment manufacturer). + + + + + + + VDSM + + + Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. + + + + + + + vi + + + Correct. Use all lowercase letters. Do not use "VI" (all caps). + + + + + + + Vim + + + Correct when referring to the application. Do not use "VIM" (all caps). Only use "vim" (all lowercase) when referring to the command to start the application. + + + 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. + + + + + + + video mode + + + Correct. Do not use "video-mode" or "videomode." + + + The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. + + + + + + + virtual console + + + Correct. Do not use "virtual-console" or "Virtual Console" for general use. + + + It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." + + + + + + + virtual machine, VM + + + Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. + + + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. + + + + + + + virtualized guest + + + The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." + + + See also "guest operating system." + + + + + + + virtual router + + + An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. + + + + + + + VNIC + + + Abbreviation for virtual network interface card. Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. + + + + + + + VPN + + + Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. + + + + + + + + + diff --git a/tmp/en-US/xml/W.xml b/tmp/en-US/xml/W.xml new file mode 100644 index 0000000..cd136b8 --- /dev/null +++ b/tmp/en-US/xml/W.xml @@ -0,0 +1,121 @@ + + +%BOOK_ENTITIES; +]> + + W + + + WAN + + + A computer network that spans a relatively large geographical area. Typically, a WAN consists of two or more local-area networks (LANs). + + + Computers connected to a wide-area network are often connected through public networks, such as the telephone system. They can also be connected through leased lines or satellites. The largest WAN in existence is the internet. + + + + + + + WCA + + + An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. + + + WCAs are also called "query applications." + + + + + + + want + + + Use instead of "wish" or "would like." Rephrase to avoid whenever possible. For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." + + + + + + + we suggest + + + Do not use. Use a more direct construction, or use "recommend." For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." + + + + + + + webhook + + + n. One word. Common noun. Capitalize only at the beginning of a sentence. Use alternative capitalization only if it appears as a proper noun. + + + + + + + webpage + + + n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + + + + + + + web UI + + + 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. + + + + + + + who, whom + + + Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. + + + For example: Who owns this phone? To whom does this phone belong? + + + + + + + will + + + Do not use future tense unless it is absolutely necessary. For example, do not write "The next section will describe the process in detail." Instead, write "The next section describes the process in detail." + + + + + + + Window Maker + + + Correct. Do not combine into one word or hyphenate. This is a window manager for the "X Window System." + + + + + + + + + diff --git a/tmp/en-US/xml/WUG_Intro.xml b/tmp/en-US/xml/WUG_Intro.xml new file mode 100644 index 0000000..32708b8 --- /dev/null +++ b/tmp/en-US/xml/WUG_Intro.xml @@ -0,0 +1,54 @@ + + +%BOOK_ENTITIES; +]> + + Usage Dictionary + + 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. + + + + A note about trademarks + + + 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 <trademark> tag. We do mark Red Hat's own trademarks. See Copyright Notices and Trademark Legends for more information. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml/WUG_References.xml b/tmp/en-US/xml/WUG_References.xml new file mode 100644 index 0000000..1ef5f6c --- /dev/null +++ b/tmp/en-US/xml/WUG_References.xml @@ -0,0 +1,19 @@ + + +%BOOK_ENTITIES; +]> + + References + + the IBM Style Guide + + + Chicago Manual of Style, 17th Edition + + + American Heritage Dictionary + + + + diff --git a/tmp/en-US/xml/XYZ.xml b/tmp/en-US/xml/XYZ.xml new file mode 100644 index 0000000..d720201 --- /dev/null +++ b/tmp/en-US/xml/XYZ.xml @@ -0,0 +1,138 @@ + + +%BOOK_ENTITIES; +]> + + XYZ + + + X + + + An alternative reference to the "X Window System." Do not use X by itself when referring to "XEmacs." + + + + + + + XEmacs + + + Correct. Do not use "Xemacs." Use "xemacs" only when referring to a command, such as "To start XEmacs, type xemacs." + + + + + + + Xen + + + Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. + + + A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." + + + The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. + + + + + + + xterm + + + Correct. Do not use "Xterm" unless the word is used at the beginning of a sentence. + + + + + + + X Windows + + + Do not use. It is an incorrect reference to the X Window System (or X). + + + + + + + X Window System + + + Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if ..." "To start an X session, from the shell prompt ..." + + + + + + + YAML + + + Recursive acronym for "YAML Ain't Markup Language." Expand on first use only. + + + + + + + you + + + Use second person wherever possible. Do not use "I," "we," "he," or "she." + + + + + + + you may + + + Avoid. For example, "you may" can be eliminated from the following sentence: "You may double-click the desktop ..." + + + + + + + zip + + + See the Word Usage chapter of the IBM Style Guide. + + + + + + + Zip Code + + + Correct. Do not use "zip code," "Zip code," or any other variation. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/0-9.xml b/tmp/en-US/xml_tmp/0-9.xml new file mode 100644 index 0000000..1ad984c --- /dev/null +++ b/tmp/en-US/xml_tmp/0-9.xml @@ -0,0 +1,43 @@ + + +%BOOK_ENTITIES; +]> + + + 0-9 + + + 24x7, 24x7x365 + + + adj. Use "24x7" in most instances. Use "24x7x365" only to differentiate from others or highlight specifically that a service is offered every day of the year, for example, providing 24x7x365 phone support. + + + + + + + 2-track (IT) + + + adj. A less common way to refer to bimodal or hybrid IT. See . + + + + + + + 3-D + + + adj., n. Correct. Do not use 3D, 3-d, or other variations. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/A.xml b/tmp/en-US/xml_tmp/A.xml new file mode 100644 index 0000000..86330f2 --- /dev/null +++ b/tmp/en-US/xml_tmp/A.xml @@ -0,0 +1,362 @@ + + +%BOOK_ENTITIES; +]> + + A + + + + + "&" and "+" + + + Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. + + + + + + above + + + Do not use to refer to information that was mentioned previously. + When documents are converted to online format, the information might no longer be "above." + Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. + + + + + + + + + agile + agile development + + + adj. Use only as an adjective. It is not a proper noun, nor is it owned or trademarked and should not be capitalized. + + + + + + + air gap + air wall + + + n. Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall." "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist. + + + + + + all-in-one + allinone + + + n., adj. Hyphenate in both places. Do not use "allinone" or other variations. + + + + + + + + alternate + + + v. "Alternate" as a verb means to change between two states or options. + + + See also . + + + + + + + + alternative + + + adj. Describes another way or method of doing something. + "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." + + + See also . + + + + + + + + + + AM + am + + + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". + + + See also . + + + See the IBM Style Guide for a full discussion of how to represent times. + + + + + + + AMD64 + + + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. + + + The correct term for AMD's implementation of this architecture is "AMD64." + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + + + See also . + + + + The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . + + + + For more information about Intel® trademarks, see and . + + + + + + + + + and/or + + + Avoid if possible. + Try to rewrite to make the available options explicit and clear. + Do not write this and/or that. + Write this or that, or both. + + + + + + + + + Applixware + Applix + ApplixWare + + + "Applixware" is correct. + Do not use "Applix" or "ApplixWare." + + + + + + + architect + + + Do not use as a verb. + Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience. + Use "design," "build," "create," or another descriptive verb instead. + Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning. + For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." + + + + + as well as + + + Not interchangeable with "and." + "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. + For example, "We sell kitchen electronics and china, as well as some gourmet foods." + But "We sell kitchen electronics, china, and silverware." + + + + + + + as-a-Service + + + Some as-a-Service acronyms overlap. + To avoid confusion, always spell out the full term on first use. + + + + + DRaaS (Disaster Recovery-as-a-Service) + + + + + + CaaS (Cloud-as-a-Service, Communications-as-a-Service, ) + + + + + + UCaaS (Unified Communications-as-a-Service) + + + + + + FaaS (Functions-as-a-Service) + + + + + + SaaS (Search-as-a-Service, Security-as-a-Service, Storage-as-a-Service, or Software-as-a-Service) + + + + + + PaaS (Payments-as-a-Service, Platform-as-a-Service) + + + + + + MaaS (Messaging-as-a-Service) + + + + + + SECaaS (Security-as-a-Service) + + + + + + TDBaaS (Time-series Database-as-a-Service) + + + + + + + When using as-a-Service acronyms: + + + + + Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out. + + + + + + When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS). + + + + + + + Hyphenate when written out: Thing-as-a-Service. + For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. + It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. + + + + + + Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service. + + + + + + + + + + + + as long as + + + Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that". + + + + + + + ATM + + + Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. + The cell size used with ATM is relatively small compared to units that are used with older technologies. + + + + + + + + + autofs + + + Always lowercase. + It refers to the kernel-based automount utility. + No other forms are recognized. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Author_Group.xml b/tmp/en-US/xml_tmp/Author_Group.xml new file mode 100644 index 0000000..ab048b7 --- /dev/null +++ b/tmp/en-US/xml_tmp/Author_Group.xml @@ -0,0 +1,18 @@ + + +%BOOK_ENTITIES; +]> + + + Red Hat Documentation Team + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/B.xml b/tmp/en-US/xml_tmp/B.xml new file mode 100644 index 0000000..3f1d05b --- /dev/null +++ b/tmp/en-US/xml_tmp/B.xml @@ -0,0 +1,437 @@ + + +%BOOK_ENTITIES; +]> + + B + + + back end, back-end + + + n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls." + + + adj. Hyphenate. For example, "when the back-end database processes a search operation …" + + + Do not use "backend." + + + See also + + + + + + + backup, back up + + + Write as one word as an adjective or noun, or as two words as a verb. + + + + + + adj. One word. For example, "store the backup copies of important files in a secure location." + + + + + + n. One word. For example, "create a backup of your important files." + + + + + + v. Two words. For example, "always back up important files." + + + + + + + Do not use the hyphenated form, "back-up." + + + + + + + backtrace + + + n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. + + + + + + backwards + + + Avoid using "backwards" unless you are stating that something has "backwards compatibility." + + + + + + + backwards compatible + + + Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also . + + + + + + + + bandwidth + + + Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed time. + + + + + + + bare metal, bare-metal + + + n. Two words. + + + adj. Hyphenate. + + + + + + + basically + + + Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . + + + + + + + because, since, as + + + Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" and "as" to indicate the passage of time. + + + + + + + below + + + Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead. + + + + + + + big data + + + n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. + + + + + + + bimodal IT + + + Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. Many ways exist to describe this combination approach; be sure to use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those who are not familiar with Gartner's phrasing. + + + The practice of having both modes together is often referred to as hybrid, agile, or modern IT. + + + + Hybrid IT is a more general term, for example it could mean on-premises plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination that you mean. + + + + + + + + + biannual, bimonthly, biweekly, semiweekly, semimonthly + + + People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. + + + Instead of biweekly, write "every two weeks" or "every other week." + + + Instead of semiweekly, write "twice a week." + + + + + + + BIND + + + Correct when referring to the DNS software. Do not use Bind. + + + + + + + BIOS + + + Correct. The plural form is BIOSes. + + + + + + + bit rate + + + Correct. Do not use "bitrate." + + + + + + + Boolean + + + Correct. Named after George Boole, who first developed the concept. + + + According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. + + + + + + + boot + + + v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software to load during the boot process. + + + n. Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. + + + Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started. + + + + + + + boot disk + + + Two words. Do not use "boot diskette." + + + + + + + boot loader + + + Two words. Do not use "bootloader." + + + + + + + bottleneck + + + One word. Do not use "bottle neck" or "bottle-neck." + + + A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system. + + + + + + + bpp + + + Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16 bpp," not "16bpp." + + + + + + + Bps, bps + + + The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . + + + + + + + breadcrumb trail + + + See the IBM Style Guide for initial guidance on how to use this term. + + + + Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path that is taken to reach the current page. + + + + + + + Example breadcrumb trail, showing Disks as the actual name of the page. + + + + + Example breadcrumb trail, showing Disks as the actual name of the page. + + + + + + + + break + + + (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail." + + + + + bring up + + + Do not use. Use "open" instead. + + + + + + + Britain + + + If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland. + + + + + + + broadcast + + + To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. + + + + In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a selected list of recipients. + + + + + + + Btrfs + + + A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. + + + See for more information on this file system. + + + See for a list of file system names and how to present them. + + + + + + + bug fix + + + Two words. Do not use "bugfix." + + + + + + + built-in + + + adj. Hyphenate. Do not use "builtin" unless referring specifically to "Bash builtins" or if it is otherwise a proper noun. + + + + + + + bunches of + + + Do not use, unless "bunch" is a specific term that is used in the documented software. Use "many" or some other alternative instead. + + + + + + + button + + + Describe a GUI button as a "button," not a "pushbutton" or "push-button." + + + Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link." + + + See also . + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Book_Design.xml b/tmp/en-US/xml_tmp/Book_Design.xml new file mode 100644 index 0000000..d182a6d --- /dev/null +++ b/tmp/en-US/xml_tmp/Book_Design.xml @@ -0,0 +1,146 @@ + + +%BOOK_ENTITIES; +]> +
+ Overall Book Design + + This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. + + + This section covers the following topics: + + + + Titles and subtitles + + + + + + Prefaces + + + + + + Abstracts + + + + + + Introductions + + + + + + Unused heading titles + + + + + + + +
+ Titles and Subtitles + + The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". + + + The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". + + +
+
+ Prefaces + + The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update. + + +
+
+ Abstracts + + Abstracts for Red Hat technical documentation typically fall under the heading of a "descriptive abstract." From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form." + + + + + + A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: + + + + What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." + + + + + + How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." + + + + + + Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + + + + + + + + + Drawing these basics together might produce the following example abstract: + + + "The Red Hat Satellite 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." + + + Update or modify each component according to the type of book that you are writing. + + +
+
+ Introductions + + The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. + + +
+
+ Unused Heading Titles + + This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. + + + Overview + + Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. + + + + + About + + Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview." + + + + + Chapter and Section Introductions + + Do not create separate introductions for chapters and sections. Use any material that would constitute an introductory section to form body text following the chapter or section title. + + + + +
+ +
+ diff --git a/tmp/en-US/xml_tmp/Book_Info.xml b/tmp/en-US/xml_tmp/Book_Info.xml new file mode 100644 index 0000000..cbd073a --- /dev/null +++ b/tmp/en-US/xml_tmp/Book_Info.xml @@ -0,0 +1,31 @@ + + +%BOOK_ENTITIES; +]> + + Conventions for Writers and Editors + + The Red Hat Style Guide + + 4.2 + 1 + + + The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/C.xml b/tmp/en-US/xml_tmp/C.xml new file mode 100644 index 0000000..d7e01a4 --- /dev/null +++ b/tmp/en-US/xml_tmp/C.xml @@ -0,0 +1,544 @@ + + +%BOOK_ENTITIES; +]> + + C + + + can, may + + + Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If any of "can," "could," or "may" apply, use "can"; it is less tentative. + + + + + + + cannot + + + Correct, as one word, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." + + + + + + + CapEx, OpEx + + + Correct. These stand for "capital expenditures" and "operating expenses" respectively. Do not use alternative capitalization. + + + + + + + cd, CD + + + When referring to the change directory command, use cd. + + + When referring to a compact disk, use "CD." For example, "Insert the CD into the CD drive." The plural is "CDs." + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + CD #1 + + + When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1. + + + + + + + Ceph + + + Correct. Ceph is a distributed storage platform that provides object, block, and file storage. + See + + Do not use alternative capitalization. + + + + + + + cgroup + + + Correct (all lowercase) when referring to the kernel-based technology. It is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. It is therefore permissible to capitalize it if used at the beginning of a sentence. + + + Where cgroup refers to something else, for example, a package name, file name, and so on, use a literal rendition. + + + + + + + characters + + + Do not use "characters" to mean "bytes." In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. + + + In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. + + + + + + + check + + + Avoid. Use "verify," "ensure," or "read," depending on the context. + + + + + + + check box + + + n. Two words. Do not use "checkbox" or "check-box." + + + + + + + chipset + + + n. One word. Do not use "chip set" or "chip-set." + + + + + + + CI/CD + + + Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. + + + See also , , . + + + + + + + ciphertext + + + n. One word. Do not use "cipher text", "cipher-text", or other variants. + + + + + + + click + + + v. Use when referring to a GUI control button, for example, "Click OK." Do not use "click on". + + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + client-side, client side + + + adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." + + + + n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." + + + + + + + clobber, clobbered + + + Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the context. + + + + + + + cloud + + + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." + + + + + + + cloudbursting + + + Define briefly on first use. + + + Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization pays only for extra computing resources when they are needed. + + + + + + + + + + cloudwashing + + + Define briefly on first use. + + + Refers to the process of rebranding legacy products to include the term "cloud" to increase their appeal to the cloud market, even if such inclusion is not completely justified. + + + + + + + code + + + n. Use only as a noun, not a verb. Use "write" for a verb. + + + + + + + + + colocate, colocation + + + Write unhyphenated, to refer to people or services in the same location. + + + + + + + combo-box + + + Do not use as an abbreviation for "combination box." See the relevant entry in the IBM Style Guide for further usage information. + + + + + + + comma-delimited + + + adj. Correct (compound adjective). A data format in which each piece of data is separated by a comma. This is a popular format for transferring data from one application to another, because most database systems are able to import and export comma-delimited data. + + + + + + + comma-separated values (CSV) + + + Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information that is broken up through use of commas. This method is often used to share data between different, but similar applications, wherein the comma is a translator of the data. + + + + + + + command button + + + Use "button" instead. + + + + + + + command-driven + + + adj. Correct (compound adjective). Do not use "command driven" or "commanddriven." + + + Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. + + + + + + + command language + + + n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. + + + With graphical user interfaces, the command language consists of operations that you perform with a mouse or similar input device. + + + + + + + command line, command prompt, command-line + + + See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. + + + + + + + commodity + + + Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and might imply that it is cheap. Use instead: + + + + + Volume + + + + + + Industry-standard + + + + + + + + + + + communication service provider (CSP) + + + Another way to refer to a telecommunications provider. See also . + + + + + + + Containers-as-a-Service + + + The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . + + + + + + + container-based + + + Used to refer to more complex applications with multiple services that are distributed in containers. More common than "containerized." + + + + + + + containerized + + + Used to refer to an application or service that is distributed in a container or packed in a container. + + + + + + + continuous delivery (CD) + + + A software implementation architecture that ensures that all approved code can be easily pushed to production. + + + + + + + continuous deployment + + + A special case of continuous delivery, where approved code is automatically pushed to production. Do not use "CD" to refer to this practice. + + + + + + + continuous integration (CI) + + + A software development architecture where the developer code branch is synchronized with the main code branch multiple times per day. Development always works with the current code base. + + + + + + + + + control character + + + A special, non-printing character that begins, modifies, or ends a function, event, operation, or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. + + + + + + + control key + + + Use Ctrl instead, such as "To save the program, press CtrlS." + + + + + + + control program + + + A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows. + + + Control programs are also called operating environments. + + + + + + + + cookie + + + n. A message given to a web browser by a web server. + The browser stores the message in a text file named cookie.txt. + The message is then sent back to the server each time the browser requests a page from the server. + + + + + + + + CR + + + Use if referring to code, such as "Type CR at the end of each line ..." If referring to the keyboard key, use either Enter or Return, depending on the platform. + + + + + + + crash + + + IBM recommends the use of "fail" rather than "crash." Use the latter only if you can justify why "fail" is inadequate. + + + + + + + cross-platform + + + adj. Hyphenate. Do not use "crossplatform" or "cross platform." + + + Refers to the capability of software or hardware to run identically on different platforms. + + + + + + + cross-site scripting + + + Correct. When referring to cross-site scripting attacks, use "cross-site scripting attack." Acceptable use is also "cross-site scripting (XSS) attack." + + + + + + + CVE + + + n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. + See for more information. + + + + + Cygmon + + + Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). + + + Refer to it as "Cygmon: a ROM monitor," not "Cygmon: the Cygnus ROM monitor," or "Cygmon: the ROM monitor." + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml b/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml new file mode 100644 index 0000000..d8ebb90 --- /dev/null +++ b/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml @@ -0,0 +1,65 @@ + + +%BOOK_ENTITIES; +]> + + + + + Writing Style Guide + + + Recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. + + + + + + + + + + + + + + Usage Dictionary + + + The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Cross_references.xml b/tmp/en-US/xml_tmp/Cross_references.xml new file mode 100644 index 0000000..546c632 --- /dev/null +++ b/tmp/en-US/xml_tmp/Cross_references.xml @@ -0,0 +1,57 @@ + + +%BOOK_ENTITIES; +]> + + Using Cross-references Effectively + + This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. + + Formatting is not described in this section. + + + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. + +
+ The Additional Information Test + + Is the cross-reference pointing to vital information or additional information? + + + A cross-reference should always point to additional information, not to core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure, provide a link to the appendix. + + +
+ +
+ The Repeatability Test + + Must the information be repeated? + + + 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. + + + Cross-referencing is a good servant but a poor master. Content still rules! + + +
+ + + diff --git a/tmp/en-US/xml_tmp/D.xml b/tmp/en-US/xml_tmp/D.xml new file mode 100644 index 0000000..dd4085f --- /dev/null +++ b/tmp/en-US/xml_tmp/D.xml @@ -0,0 +1,343 @@ + + +%BOOK_ENTITIES; +]> + + D + + + daisy chain + + + n. A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. + + + v. To connect devices in a daisy chain pattern. + + + + + + + dash + + + In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. + + + + + + + data center, datacenter + + + n. Use the two-word form unless referring to a product name or other proper noun where the one-word form is used. + + + Marketing Publications Exception + + In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used. + + + + + + + + + data mirroring + + + The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information that is stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a different location. + + + + + + + data sheet, datasheet + + + n. Use the two-word form. + + + Marketing Publications Exception + + In marketing publications, the one-word form is recommended. + + + + + + + + + data source + + + n. Use the two-word form unless referring to a proper noun, argument, variable, or other case where the one-word form is required. + + + + + + + data store, datastore + + + n. Use the two-word form. + + + Marketing Publications Exception + + In marketing publications, the one-word form is recommended. + + + + + + + + + data type + + + n. Do not use "datatype" or "data-type" unless they are variable names or some other literal value. + + + + + + + + + + debug + + + To find and remove errors (bugs) from a program or design. + + + + + + + denial of service (DoS) + + + Correct. Do not use "denial-of-service" or "Denial of Service." + + + + + + + desktop + + + Correct. Do not use "desk top" or "desk-top." + + + + + + + device + + + Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer. + + + Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. + + + + + + + DevOps + + + n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps can also refer to the engineers and developers who work within these modern IT organizations. + + + + + + + dialog box + + + See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. + + + + + + + different + + + Use "different from" rather than "different than" when the next part of the sentence is a noun or pronoun (that is, two things are being compared). For example: "Form 123 is different from Form 124." + + + + + + + digital transformation + + + Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. + + + + Disk Druid + + + Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. + + + + + + + disk, disc + + + Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. + + + + + + + + disk label + + + Correct. Do not use "disklabel" or any other variations. + + + + + + + + display + + + v. Use only as a transitive verb. For example, write "the system displays a message" or "the message is displayed" (not "the message displays"). + + + + + + + DNS + + + Initialism of Domain Name System (or Service), an internet service that translates domain names into IP addresses. + + + + + + + documentation + + + When referring to the current manual set, use "documentation." For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." + + + + + + + domain name + + + Correct. Do not use "domainname" or "domain-name." + + + A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com. + + + + + + + double-click + + + v. Always write hyphenated. + + + + + + + downstream + + + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." + + + + + + + downtime + + + Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." + + + + + + + download + + + v., n. Do not use "down load" or "down-load." + + + + + + + dual-boot + + + adj. Do not use "dualboot" or "dual boot." + + + + + + + DVD writer + + + Correct. Do not use the colloquial terms "DVD burner" or "CD burner" (use CD writer in the latter case). + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Design.xml b/tmp/en-US/xml_tmp/Design.xml new file mode 100644 index 0000000..ed0ba05 --- /dev/null +++ b/tmp/en-US/xml_tmp/Design.xml @@ -0,0 +1,1035 @@ + + +%BOOK_ENTITIES; +]> + + Design + +
+ Heading Styles + + This section covers various aspects of heading styles and design. + If your company or organization has specific requirements in this regard, follow those requirements first. + + + Capitalization + + The standard for all Red Hat technical documentation is title case for all headings and titles. + Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. + The currently accepted reference for determining title case is at https://titlecase.com/titlecase. + + + + + Use sentence case for captions, legends, diagram labels, and table column headers. + They are not classified as titles. + + + Marketing and Brand Capitalization Guide + + The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. + + + + + + Punctuation + + + Be frugal with punctuation. + In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. + Do not use terminating periods. + + + + Avoid Imperative Mood + + Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". + + + + + See the IBM Style Guide for more information. + + + + Gerunds should be avoided elsewhere. + See . + + + + File Names, Commands, and Related Terms + + When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. + Instead, focus on the task at hand and introduce the required file and command names in the text. + Including such objects in titles is generally considered poor technical writing practice. + Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. + + + +
+
+ Documenting Fonts + + The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. + + +
+
+ Documenting the User Interface + + In all cases, see the IBM Style Guide for initial guidance. + The following sections highlight exceptions or cases that might otherwise cause confusion. + +
+ GUI Elements, Punctuation, and Symbols + + When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. + + + For example, for a button labeled Save As..., do not include the ellipsis in the documentation. + + + In most cases, do not include the object type in instructions. + For example, rather than "Click the Save button," write "Click Save." + + + In some cases it is preferred practice to include the object type for the sake of clarity. + Consider the following: + + Preferred Style for Documenting Symbols and Other Special Characters + + Click the + sign. + + + Click the ^ symbol. + + + + If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. + Use this approach for icons, especially when they have no tooltip or other help text. + + Preferred Style for Documenting Icons + + Click the Upload ( + + + + ) icon to upload the files to the server. + + + + See the UI elements chapter in the IBM Style Guide for more information. + +
+ Navigating Through Multiple GUI Options + + Use "Navigate to" when moving through multiple GUI 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. + + + From example, "From the OpenShift web console, navigate to Monitoring → Alerting." + + +
+
+
+ Starting Applications from the Desktop + + This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. + + + RHEL 8 uses the following approach to starting applications from the desktop. + In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. + + + The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. + The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: + + + Preferred Approach to Starting Applications from the Desktop + + To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. + + + + +
+
+ Documenting Command Terminology and Syntax + + Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here. + + + When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses. + Never use "flag" when referring to command-line options in POSIX, even though Microsoft often uses the term "flag" when referring to single-character options in Microsoft Windows. + + + The following extract from info libc is of particular interest here: + +
+ + "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on. + + + See info libc argument syntax for the full discussion. + +
+ + See info bash and the IBM Style Guide for further guidance. + + + The following examples are intended to highlight correct usage. + + + Cloning a Git Repository + + +$ git clone [username@]hostname:/repository_filename [directory] + + + + + + In , the entire command consists of the following components: + + + + The prompt ($) + + + Indicates that a normal user can run the command, as compared to the root user, which would be indicated by the number sign (#). + + + + + + + The command (git clone) + + + The actual command to run, without any optional or replaceable values. + It must be typed as-is. + + + + + + + Source options [username@]hostname:/repository_filename) + + + The optional user name, indicated by brackets ([]), followed by the host name and path to the repository. + All aspects of this component must be replaced with valid values. + + + + + + + Target options [directory] + + + The optional directory into which the repository will be cloned. + It must be replaced with a valid value, or be omitted. + + + + + + + + + Securely Copying a File Between Hosts + +$ scp filename [username@]hostname:/directory + + + + + In , the entire command consists of the following components: + + + + The command prompt ($) + + + + + + + + + + The command (scp) + + + + + + + + + + Source options (filename) + + + The file name to copy. It must be replaced with a valid value. + + + + + + + Target options ([username@]hostname:/directory) + + + The optional user name, indicated by brackets ([]), followed by the host name and path to the target directory. All aspects of this component must be replaced with valid values. + + + + + + + + + + In most cases, avoid using the and options on most commands, especially when logged in as the root 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: + + +[root@serverc pam.d]# rm -f system-auth password-auth +[root@serverc ~]# yum install -y new-package + + + In these examples, omit the and options, respectively. + + + In some cases, such as in Ansible Playbooks or other automation scripts, it might be necessary to use these options. + + + +
+ Documenting Multiple or Long Commands + + 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, include the commands on consecutive lines: + + + Documenting Multiple Commands + +$ cd Documents +$ vi myFile.txt + + + + + If the commands are long, complex, or wrap over multiple lines, two design options are available. + + + + + Use line continuation characters and the associated PS2 prompts. + If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit. + + + + + Use neither line continuation characters nor the associated PS2 prompts. + + + + + + Do not mix these two styles. + Maintain the same style throughout your document or book. + + + + You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. + You can use this option for either of these two designs. + + + + Wrapping Long Commands with Continuation Characters + + This example uses both continuation characters and PS2 prompts. + These indicators are always used together. + + +# tar --selinux -czvf config_files.tar.gz /etc/katello \ +> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ +> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ +> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ +> /root/ssl–build /var/www/html/pub/* /var/lib/katello + + +Wrapping Long Commands Without Continuation Characters + + This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. + +# cd /var/lib/katello + +# myCommand --option funky --color=true + --config_file=<replaceable>/home/user/config.conf</replaceable> + --output_file=<replaceable>/home/user/output.txt</replaceable> + + + +
+ +
+ Referring to Replaceable Paths + + To refer to a path that users need to replace with something that is specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. + Use a leading slash if the absolute path is required. + + Referring to Replaceable Paths on Linux Systems + + "Mount the ISO file in <filename><replaceable>/path/to/iso/file</replaceable></filename>." + + + + Remember to use the appropriate syntax for the system that you are documenting or describing. + + Referring to Replaceable Paths on Microsoft Windows Systems + + + "Mount the ISO file in <filename><replaceable>C:\path\to\iso\file</replaceable></filename>." + + + + If you are referring to a different object class or type with different delimiters, use the appropriate delimiters. + For example: + + + A PATH variable for Bash might appear as <replaceable>/usr/bin:/usr/local/bin</replaceable>. + + + A package path in Lua might appear as <replaceable>local.share.lua</replaceable>. + +
+ +
+
Using Escalated Privileges Correctly + + + This section is aimed primarily at Red Hat Training course material, but the principles and guidelines apply equally in any environment. + + + + The term escalated privileges 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. + + Classroom Exceptions + + Although security is important, it is more important that classroom security does not unnecessarily distract from the immediate topic that is being taught. + + +
General Recommendations + + + These are recommendations, not rules. + As in most matters, consistency is important. + Do not swap between different approaches without reason. + Choose which approach works best for your situation and use it consistently. + + + + + + In all cases, use the minimum required privilege level to achieve the task. + + + + + In exercises, use sudo and sudo -i and set it up to work throughout all relevant systems in the classroom. + Do not use su - without good cause. + + + + + When a scattered minority of privileged commands occur in a mostly unprivileged exercise, use sudo on a per-command basis. + + + + + When the exercise is majority privileged, or has many privileged commands, use sudo -i, either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. + + + + + In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. + See for information about command prompts. + + + +
+
Exceptions + + Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers, and so on. + For these courses, use the required variation for the topic that is being taught. + +
Ansible Courses + + + + Ansible courses typically use a devops user with passwordless sudo access (devops ALL=(ALL) NOPASSWD: ALL) on managed nodes to enable the use of become without a become password as root to do anything. + + + + + As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. + + + + + If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. + + + +
+
+ + +
+ +
+ Describing How to View and Edit Files + + To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. + + + For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. + + + If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. + + + You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. + + + my-script +> # The first line of text +> # The second line +> # Start adding variables after this line +> EOF]]> + + In some cases, it is necessary to indicate which tool to use to view a file, especially for log files and other long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl. + + +
+
+ Using Host and User Names Correctly + + Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. + + + + All names are lowercase. Do not use white space in any part of the name. + + + + + + + Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. + + + + Do not use valid, public IP addresses in any examples. + + + + + + + + As much as possible, use user, username, root, admin, or similar names to identify classes of users. + + + Use these generic names when you refer to users outside a case study. It helps students to identify which part of a command to replace, by establishing a consistent format for names of users and system items. For example: + + +[root@fedora ~]# setfacl -m u:user1:rw /project/file1 + + The following list provides further alternatives: + + + + + operator1 to operator9 + + + + + + developer1 to developer9 + + + + + + architect1 to architect9 + + + + + + + + + +
+ Using Extended User and Group Names + + Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. + + + Using Realistic User Names + + When you are writing a detailed case study, such as training exercises, reviews, and similar material, use realistic names. These names should not be real people. In other words, do not use the name of an employee, a well-known person, or your neighbor. + + + + + For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. + + + Choosing a Realistic Name + + Consider the following points when choosing a realistic name: + Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. + + + + + + + + + In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. + + + + + + Do not use copyrighted fictional characters in examples, and do not use real people. + + + + + + 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. + + + + + + + Sourcing Realistic Names + + You can use any of the following name generators to create realistic names for users: + + + + + + + https://uinames.com/ + + + + + + http://listofrandomnames.com/ + + + + + + http://www.behindthename.com/random/ + + + + + + http://random-name-generator.info/ + + + + + + + Group Names + + Use any lowercase name that is a logical extension of the accepted user names, without the numerical suffix. For example, architects, developers, operators. + + + + +
+ +
+ +
+
+ Documenting Currencies + + Use local currency symbols wherever possible. If symbol clash occurs (USD versus AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. + + + + Do not provide currency conversions. + + + + +
+
+ Using Abbreviations, Acronyms, and Initialisms Correctly + + This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. + + + Abbreviations + + An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated," respectively. Read them as the word for which they are an abbreviation. + + + + + Acronyms + + What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + + + + + Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). + + + + Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." + Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." + Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. + + + + To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. + + + + Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. + + + + Initialisms + + An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. + + + + + Consider pronunciation when using articles. See for more information. + + +
+
+ Using Company, Product, and Brand Names Correctly + + Various restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. + + + + In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use." + + + + + + + Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. + + + + + + Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. + + + + + + Do not include "Inc." when referring to Red Hat except in legal documents. + + + + + + Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. + + + If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. + + + + + + Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: + + + + + Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. + + + + + + The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 + + + + + + + For other markup languages, use the equivalent non-breaking space character. + + + + + Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." + + + + + + Do not use non-breaking spaces with other companies' product names. + + + + + + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." + + + + In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. + + + + + + + + +
+
+ Using Version Numbers Correctly + + The preferred format for product names includes only the major version number. For example: + + + + Red Hat Enterprise Linux 8 + + + + + + JBoss Enterprise Application Platform 3 + + + + + + + + + When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version. + + + Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example: + + + + Red Hat Enterprise Linux 5.2 was released on October 12, 2010. + + + + + + <Application name> was first included in JBoss Enterprise Application Platform 3.2. + + + + + + + + + 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. + + + Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. + + + + This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. + + + + +
+
+ Using Admonitions + + To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning 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 in mind these considerations if using admonitions: + + + + Keep the statements as brief and to the point as possible. + + + + + + Use admonitions sparingly so that they do not lose their effectiveness. + + + + + + Use a Note admonition to bring additional information to the user's attention. + + + + + + Use an Important 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 a Warning 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. + + + + + + + + +
+ +
+ Making Recommendations + + When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". + Recommendations can include best practices, recommended practices, and product-specific suggestions. + See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. + + + + (incorrect) + + + "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project." + + + "It is recommended to generate a service account for each microservice in your project." + + + + + (correct) + + + "Although the attack surface is reduced to the same-project traffic, Red Hat recommends creating multiple service accounts within a project." + + + "Red Hat recommends that you generate a service account for each microservice in your project." + + +
+ + +
+ Citing Other Works + + Referencing Other Books + + When referencing another book, either internal or external to Red Hat, use the following format: + + + + + + + +Book Title by First name Surname; Publisher. + + + + For example, Maximum RPM by + + Edward + Bailey + + + ; Red Hat Press. + + + Referencing Other Internet Sites + + When referencing another internet site, use the following guidelines: + + + + + + + Do not link words within the body text. That is, do not use structures such as "Go here for more information," where "here" is a link. + + + + + + Short URLs, such as http://partner.redhat.com, are OK to use in body text at your discretion. + + + + + + If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species + http://world-database-of-everything.com/en/classifcation_of_species/mammals.html + + page for more information. + + + + + + +
+ + + diff --git a/tmp/en-US/xml_tmp/E.xml b/tmp/en-US/xml_tmp/E.xml new file mode 100644 index 0000000..976efae --- /dev/null +++ b/tmp/en-US/xml_tmp/E.xml @@ -0,0 +1,195 @@ + + +%BOOK_ENTITIES; +]> + + E + + + e-book, e-business, e-commerce, e-learning, email + + + Refer to the primary reference for the type of copy you are creating, either AP or IBM. + + + + + + + + e.g. + + + Red Hat technical documentation always expands these abbreviations. Write out "for example". + + + + + + + earlier + + + Use to refer to earlier releases of products. Do not use "older" or related terms. See also . + + + + + + + Emacs + + + If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." + + + + + + + emdash + + + Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See for more information. + + + + + + + + enter + + + When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. + + + + When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." + + + When typing information into a single-field dialog box, "enter" means "type and press Enter." An example is "enter the license number." For multi-field dialog boxes, see "type." + + + + + + + environment + + + The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, running a program in a UNIX environment means running a program on a computer that has the UNIX operating system. + + + One ingredient of an environment, therefore, is the operating system. But operating systems include many different parameters. For example, in some operating systems, you can choose your command prompt or a default command path. All these parameters together constitute the environment. + + + Another term for environment in this sense is platform. + + + + + + + EOL + + + adj. Initialism for "end-of-line" + + + n. Initialism for "end of line" + + + Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. + + + + + + + essentially + + + Do not use. + + + + + + + Ethernet + + + n. Uppercase "E" at all times. + + + + + + + event + + + An action or occurrence that is detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. + + + + + + + exclamation points (!) + + + Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. + + + + + + + Exec-Shield + + + Exec-Shield is a security-enhancing modification to the Linux kernel that makes large parts of specially marked programs including their stack not executable. + + + + + + + execute + + + Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. + + + + + + + Exif + + + Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." + + + + + + + extranet + + + Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. + + + Capitalize only at the beginning of a sentence. + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Easily_Confused_Words.xml b/tmp/en-US/xml_tmp/Easily_Confused_Words.xml new file mode 100644 index 0000000..53bf144 --- /dev/null +++ b/tmp/en-US/xml_tmp/Easily_Confused_Words.xml @@ -0,0 +1,92 @@ + + +%BOOK_ENTITIES; +]> +
+ Easily Confused Words + + This section identifies some easily confused words and how to choose the correct term for your situation. + + + Affect and Effect + + Each of these words can be used as a verb or a noun, but they are not always interchangeable. + + + + + + affect + + + n. Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you. + + + v. Means to have an influence on something, or to cause something to change. + + + + + + + effect + + + n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." + + + v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." + + + The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." + + + + + + + + + Assure, Ensure, and Insure + + These are relatively easy to get right, but here are some quick definitions. + + + + + + assure + + + v. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." + + + + + + + ensure + + + v. Means to make sure of something, to be certain that something exists or some condition has been met. + + + + + + + insure + + + v. Relates to monetary insurance. + + + + + + + + +
+ diff --git a/tmp/en-US/xml_tmp/F.xml b/tmp/en-US/xml_tmp/F.xml new file mode 100644 index 0000000..452a95b --- /dev/null +++ b/tmp/en-US/xml_tmp/F.xml @@ -0,0 +1,336 @@ + + +%BOOK_ENTITIES; +]> + + F + + + fail back, failback + + + v. Use the 2-word form. + + + n. Use the 1-word form. + + + No hyphenated form is currently recognized. + + + + + + + fail over, failover + + + v. Use the 2-word form. + + + n., adj. Use the 1-word form. + + + No hyphenated form is currently recognized. + + + + + + FAQ + + + When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an Q") not "a FAQ." The plural form is "FAQs." + + + + + + + fault tolerance (n.), fault-tolerant (adj.) + + + The ability of a system to respond gracefully to an unexpected hardware or software failure. Fault tolerance has many levels, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so that if one fails, then the other can take over. + + + + + + + Fedora™ Project + + + Correct. + + + + + + + fiber + + + Correct. Despite the alternative spelling used in Fibre Channel, "fiber" is the correct form to use in all other cases. + + + + + + + Fibre Channel + + + A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FAL). + + + FAL was designed for new mass storage devices and other peripheral devices that require high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100 MBps. FAL is compatible with, and is expected eventually to replace, SCSI for high-performance storage systems. + + + + + + + file extensions (general usage) + + + See File names, file types, and directory names in the IBM Style Guide. + + + + + + + file mode, file name, file system, file type + + + n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. + + + + adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." + + + + + + + + FireWire + + + Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. + + + + + + + + firmware + + + n. Do not use "firm ware" or "firm-ware." + + + Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. + + + + + + + floating point + + + Correct. Do not hyphenate. + + + + + + + floppy disk + + + Do not use. Use "diskette," and also state the size of the diskette, such as "3.5 in. diskette." + + + + + + + floppy drive + + + Do not use. Use "diskette drive." + + + + + + + + follow + + + v. Refers to the use of the () option for various commands, such as tail, so that output is appended as the file grows. + + + + + + + following + + + When introducing a list or a procedure, use "following" with a noun. Instead of "Complete the following", use "Complete the following steps". + + + + + + foreground + + + + + In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. + + + + + + On display screens, the foreground consists of the characters and pictures that appear on the screen. The background is the uniform canvas behind the characters and pictures. + + + + + + + + + + + fortnight + + + A period of two weeks (14 nights). Avoid; this term is not common in American English and might also be unfamiliar to non-native speakers. + + + + + + + FORTRAN + + + Correct. Do not use "Fortran." + + + + + + + forward + + + Correct. Avoid using "forwards." + + + + + + + forwards compatible + + + Do not use. Instead, use "compatible with later versions." See also . + + + + + + + + FQDN + + + A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels.https://en.wikipedia.org/wiki/Fully_qualified_domain_name + + + For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. + + + An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. + + + + + + + + frictionless + + + Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also . + + + + + + + front end, front-end + + + n. Two words. For example, "PRCS is a front end for a version control toolset." + + + adj. Hyphenate. For example, "This chapter explains how to use the front-end API functions." + + + Do not use "frontend" as a noun or adjective. + + + See also . + + + + + + + FTP + + + Use all caps when referring to the protocol. Use lowercase when referring to the command-line program. + + + + + + + futexes + + + Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. + + + + + + + + fuzzy + + + Correct only when referring to fuzzy searches. See for details and examples. + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Feedback.xml b/tmp/en-US/xml_tmp/Feedback.xml new file mode 100644 index 0000000..69ea61a --- /dev/null +++ b/tmp/en-US/xml_tmp/Feedback.xml @@ -0,0 +1,13 @@ + + +%BOOK_ENTITIES; +]> +
+ We Need Feedback + + Raise an issue at with suggestions for improvements, requests for additions, recommendations, and any other updates. + + +
+ diff --git a/tmp/en-US/xml_tmp/G.xml b/tmp/en-US/xml_tmp/G.xml new file mode 100644 index 0000000..f07fd91 --- /dev/null +++ b/tmp/en-US/xml_tmp/G.xml @@ -0,0 +1,270 @@ + + +%BOOK_ENTITIES; +]> + + G + + + g++, G++ + + + When referring to the command, use g++. When referring to the program, use G++. + + + + + + + gas, GAS + + + When referring to the command, use gas. When referring to the program, use GAS. + + + + + + + GB + + + Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. + + + AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." + + + IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file." + + + + + + + GbE + + + Correct. Approved abbreviation of Gigabit Ethernet. Do not use GigE or any other variations. Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + Gbps + + + Abbreviation of Gigabits per second, a data transfer speed measurement for high-speed networks such as Gigabit Ethernet. When used to describe data transfer rates, a gigabit equals 1,000,000,000 bits. Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + gcc, GCC + + + When referring to the command, use gcc. When referring to the program, use GCC. + + + + + + + gcj, GCJ + + + When referring to the command, use gcj. When referring to the program, use GCJ. + + + + + + + gdb, GDB + + + When referring to the command, use gdb. When referring to the program, use GDB. + + + + + + + GDBTK + + + Do not use. Use "Insight" instead. GDBTK is an obsolete name for the GNU debugger. + + + + + + + GEO + + + Do not use. Use "region" or "geographical location" according to your needs. + + + + + + + + GFS, GFS2 + + + As of Red Hat Enterprise Linux 6, it is known as the Resilient Storage Add-On. Ensure that you use the correct term. + + + + + + + GID + + + Acronym for Group ID. Do not use "gid." + + + + + + + GigE + + + See . + + + + + + + gigabyte + + + 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. + + + + + + + GIMP + + + Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp." + + + + + + + GNOME + + + Correct. Do not use "gnome," "Gnome," or other variants. See also . + + + + + + + GNOME Classic + + + Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). + + + + + + + GNU + + + Recursive initialism for "GNU's Not UNIX." Do not use "Gnu" or "gnu." + + + + + + + GNUPro + + + When referring to the Red Hat product, use GNUPro. + + + + + + + got + + + Do not use. + + + + + + + + GPL + + + Initialism for General Public License. Do not use "Gpl" or "gpl." + + + + + + + grayscale + + + n. Correct. Do not use "gray-scale" or "gray scale." Only the noun form is currently recognized. + + + + + + + GRUB + + + Correct. All caps. Do not use "Grub." + + + + + + + GTK+ + + + Initialism for GIMP Tool Kit. Do not use "GTK," "Gtk," or "gtk." + + + + + + + guest operating system + + + Refers to the operating system that is installed in a virtual machine. Do not use "guest" by itself because it is ambiguous. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Grammar.xml b/tmp/en-US/xml_tmp/Grammar.xml new file mode 100644 index 0000000..2a305c6 --- /dev/null +++ b/tmp/en-US/xml_tmp/Grammar.xml @@ -0,0 +1,631 @@ + + +%BOOK_ENTITIES; +]> + + Grammar + + This section contains information on a few common grammar topics. For subjects not covered here, consult The Chicago Manual of Style, 17th Edition. + +
+ Active Voice + + Use the active voice ("Type ... to start Linuxconf.") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. + + + This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. + + + For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than + + + "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence. + + + You can also use the passive voice to front-load important keywords in key areas of your content, such as the title, heading, or at the beginning of a paragraph or sentence. You need to make these decisions on a case-by-case basis, weighing the importance of front-loading keywords against content that is readable (that is, not awkward sounding). Consider the following two examples: + + + Active Voice + + "Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization." + + + + + Passive Voice + + "Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion." + + + + +
+
+ Agreement + + In grammar, agreement occurs when specific parts of a sentence are coordinated; that is, they agree in number and gender. + + + There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here. Pronoun-antecedent agreement can be a little more problematic, so... + +
+ Pronoun-antecedent agreement + + A pronoun is a word that is used in place of a noun (for example, I, he, she, it). An antecedent is a word or phrase to which the pronoun refers. + + + When you are comfortable with subject-verb agreement, pronoun-antecedent agreement often follows as a matter of course. + + + The following is an annotated roundup of pronoun-antecedent rules: + + + Singular and Plural Nouns + + A singular pronoun refers to a singular antecedent; a plural pronoun refers to a plural antecedent. For example: + + + + + + + The CD spins in its caddy. (The singular third-person pronoun "its" refers to the singular antecedent "CD".) + + + + + + The developers checked their work. (The plural third-person pronoun "their" refers to the plural antecedent "developers".) + + + + + + + Collective Nouns + + When collective nouns are used as antecedents, use singular or plural pronouns, depending on the sentence's meaning. For example: + + + + + + + Microsoft seems second to none in its marketing skills. (The collective noun "Microsoft" takes the singular pronoun "its" because the collective noun refers to the group as a whole.) + + + + + + The developers were asked for their preferences. (The collective noun "developers" takes the plural pronoun "their" because the reference is to the individuals of the group.) + + + + + + +
+ +
+
+ Using Who, Whom, That, and Which Correctly + + Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns." + + + Use the following as guidelines: + + + + Who + + + Relative pronoun when persons are the subject. + + + + + + + Whom + + + Relative pronoun when persons are not the subject. + + + + + + + Which + + + Relative pronoun for things. + + + + + + + That + + + Restrictive pronoun for things. + + + + + + + + + Examples: + + + + + The jewel case, which once held the CD, was broken recently. + + + + + + The CD that I received for my birthday is defective. + + + + + + Edward C. Bailey, who wrote "Maximum RPM,"... + + + + + + The company that published "Maximum RPM" was... + + + + + + This book belongs to whomever purchased it last week. + + + + + + Who ate all the cereal? + + + + + + To whom should I address the letter? + + + + + + The desktop that was designed by Earl is not called GNOME. + + + + + + The GNOME developers who worked on the desktop are... + + + + + + The GNOME developers to whom they owe gratitude are... + + + + + + + + To help you choose between who and whom, substitute the person about whom you are speaking with he, she, him, or her. + + + + + + If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" + + + + + + If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" + + + + + + + + +
+
+ Sentence Structure + + A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). + + + Consider the following points when constructing sentences: + + + + Sentence Length + + Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: + + + + + The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. + + + Run-on Sentences + + Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: + + + + + + + Separate independent clauses with a period. Doing so will form two sentences out of one. + + + + + + Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. + + + + + + Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." + + + + + + Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error." + + + + + + + + + + + + + Example + Improvement + + + + + + + The CDs both of which belonged to the developers were in the test lab. + The CDs, both of which belonged to the developers, were in the test lab. + + + + To access your programs click the Start button. + To access your programs, click Start. + + + + The CDs, both of which belonged to the developers, were in the test lab, because they were the only available CDs for the new release, the developers were anxious about keeping them clean. (This sentence exhibits a comma splice which is also often regarded as a run-on sentence.) + The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean. + + + + + + + +
+ + Sentence Fragments + + A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. + + + + + + Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. + + + + + Telegraphic Style + + Extreme cases of word economy can result in a telegraphic style, omitting words that can clarify the meaning of a sentence, such as articles, prepositions, and verbs used with gerunds. + + + + + + + + + + + Example + Improvement + + + + + + + Click button to start. + Click Initiate to start the process. + + + + + + + +
+ + This problem is often encountered in the Revision History. It is important that wording in the Revision History is clear for translators and customers to understand. + + + + + + + + + Example + Improvement + + + + + + + Minor revision - missing element items + Minor revision - added missing element items + + + + Some further work required to avoid 404s at lower levels of the SDK. + Some further work required to avoid 404 errors at lower levels of the SDK. + + + + + + + +
+ + + + "That" in Clauses + + Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, + + + + + + + + + + + Example + Improvement + + + + + + + Verify your directory service is working. + Verify that your directory service is working. + + + + + + + +
+ + Verbosity + + Avoid unnecessary words. Keep it succinct. + + + + + + + + + + + Example + Improvement + + + + + + + The individual member of the social community often receives information via visual, symbolic channels. + People read. (Translation by Richard Feynman.) + + + + Perform the installation of the product. + Install the product. + + + + + + + +
+ + Word Order + + When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify. + + + + + + + + + + + Example + Improvement + + + + + + + To update the address lists might be your primary concern. + Your primary concern might be to update the address lists. + + + + + + + +
+ +
+ + + + + +
+ Contractions and Abbreviations + + Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. + + + + Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. + + +
+ +
+ Hyphenation + + There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. + + + + Hyphenate for Clarity + + Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. + + + + + + Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof." + www.apstylebook.com + + + + + + + Hyphenate Complex Adjectives + + Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. + + + + + + Do not hyphenate "open source," even when used as a complex adjective. + + + Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. + + + + + Hyphenate Consecutive Vowel Sounds + + Hyphenate words where the prefix ends in a vowel and the word that follows begins with the same vowel. For example, semi-independent, pre-emptive. + + + + + + Exceptions to this rule include cooperate and coordinate. + + + + + Hyphenate Mixed Capitalization + + Hyphenate when the word that follows a prefix is capitalized. For example, un-American, non-British. + + + + + Hyphenate Double Prefixes + + Hyphenate when the word has double prefixes. For example, sub-subparagraph, re-sublet. + + + + +
+
+ Gender References + + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + + +
+
+ Tense + + Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. + + + + Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. + + + Report an issue + + +
+ + diff --git a/tmp/en-US/xml_tmp/H.xml b/tmp/en-US/xml_tmp/H.xml new file mode 100644 index 0000000..92d3e4a --- /dev/null +++ b/tmp/en-US/xml_tmp/H.xml @@ -0,0 +1,302 @@ + + +%BOOK_ENTITIES; +]> + + H + + + hard code, hard-coded + + + v. Two words. + + + adj. Hyphenate. + + + Do not use the one-word form. No nominal form is currently recognized. + + + + + + + hard copy + + + Do not use. Use "printed". Under review + + + + + + + + hard disk + + + n. Correct. Do not use "harddisk" or "hard-disk." + + + + + + + hard disk drive + + + n. Correct. Do not use "harddrive" or "hard-drive." + + + + + + + he/she + + + Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. + + + + + + + help desk + + + Typically two words, but use the term accepted by your organization. + + + + + + + healthcare + + + Under review. Need context and example. + + + + + + + + + health check + + + n. Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. + + + This term is only capitalized when part of a product name, for example: + + + + Red Hat Enterprise Linux Server Health Check + + + + + + JBoss Middleware Health Check + + + + + + + + + Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." + + + + + + + hertz + + + n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz." + + + + + + + high-availability, high availability + + + adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." + + + + n. Two words. For example, "Support is available 24x7 to help maintain high availability." + + + + + + + high-performance computing (HPC) + + + n. Use standard hyphenation guidelines to maintain clarity. + + + + + + + homepage + + + n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + + + + + + + + host group + + + n. Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. + + + + + + + host name + + + n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. + + + + + + + hot add + + + v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add." + + + + + + + hotline + + + n. One word, lowercase. Capitalize only at the beginning of a sentence. Under review. Need context and example. + + + + + + + + hot plug + + + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug." + + + + + + + hot swap + + + v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap." + + + + + + + hover help + + + See . + + + + + + + HP ProLiant + + + Correct. Do not use any other variations. + + + + + + + HTML + + + When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." + + + + + + + huge-page, huge page + + + adj. Hyphenate. Normal hyphenation rules apply. + + + n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization that is used in that interface. + + + + + + + hybrid IT + + + The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . + + + + + + + Hyper-Threading + + + n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use "hyperthreading" or "hyper-threading". If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. + + + + + + + hypervisor + + + n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser." + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/I.xml b/tmp/en-US/xml_tmp/I.xml new file mode 100644 index 0000000..2c68839 --- /dev/null +++ b/tmp/en-US/xml_tmp/I.xml @@ -0,0 +1,382 @@ + + +%BOOK_ENTITIES; +]> + + I + + + IA64 or ia64 + + + Do not use. Always use the term Itanium instead. These terms can be used in file names because they are not visible in the content. + + + + + + + IaaS + + + Correct. This is the correct abbreviation for "Infrastructure-as-a-Service." See also . + + + + + + + + IBM Z + + + IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. + + + + + + + + i.e. + + + Do not use a Latin abbreviation. Instead, write out "that is". + + + + + + + illegal + + + Illegal means "prohibited by law," not "incorrect" or "not permitted." Use "invalid" or a related word. + + + + + + + + + matrixes + + + Correct. This is the correct plural form for US English spelling. Do not use "indices." + + + + + + + + InfiniBand + + + InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. + + + "Open InfiniBand" is deprecated and should not be used. + + + + + + + inline + + + adj. Always one word. Do not hyphenate. + + + + + + + insecure + + + adj. Correct. Do not use "nonsecure" or "non-secure." + + + + + + + installation program + + + n. Correct. Do not use "installer" unless it is a formal part of the product or technology. + + + + + + + Intel 64 + + + Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. + + + The correct term for Intel's implementation of this architecture is "Intel® 64." + Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). + They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. + + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + + + See also . + + + + The AMD64 logo is trademarked; the term "AMD64" is not. + For more information about AMD trademarks, see the AMD Trademark Information page at . + + + + For more information about Intel® trademarks, see and . + + + + + + + + + Intel® CoreTM + + + Correct. Example would be good. + + + + + + + + Intel Tolapai / Intel® EP80579 Integrated Processor + + + Do not use the code-name, "Tolapai." Use the official brand name "Intel® EP80579 Integrated Processor." + + + + + + + Intel Virtualization Technology (Intel VT) + + + Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." + + + Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." + + + + + + + Intel® Xeon® + + + Correct. Example? Reference? + + + + + + + + interesting + + + Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note...", consider using a "Note" admonition. + + + + + + + internet + + + n. Always lowercase except in some specific exceptions, for example . + + + + + + + Internet of Things (IoT) + + + Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. + + + The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. + http://en.wikipedia.org/wiki/Internet_of_things + + + + + + + + + Intranet, intranet + + + See the "Word usage" appendix of the IBM Style Guide for guidance. + + + + + + + I/O + + + Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. + + + The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. + + + + + + + IOPS + + + Correct. All caps. Stands for input/output operations per second. + + + + + + + IP + + + Correct. Stands for Internet Protocol. Capitalize both letters. + + + + + + + IP Masquerade + + + A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. + + + Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. + + + + + + + IPsec + + + IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec." + + + + + + + IP switching + + + A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. + + + + + + + + ISV + + + Short for "independent software vendor", a company that produces software. + + + + + + + IT/I.T. + + + Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." + + + + + + + Itanium + + + A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. + + + In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. + + + Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. + + + Do not use the term "IA64". It can be used in file names because they are not printed in the content. + + + + + + + Itanium 2 + + + Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/J.xml b/tmp/en-US/xml_tmp/J.xml new file mode 100644 index 0000000..28be68f --- /dev/null +++ b/tmp/en-US/xml_tmp/J.xml @@ -0,0 +1,72 @@ + + +%BOOK_ENTITIES; +]> + + J + + + JavaScript + + + "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." + + + + + + + JBoss Community + + + No longer referred to as "JBoss.org." Use when referring to the community of users and contributors. + + + + + + + job + + + A task that a computer system performs. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. + + + + + + + jsvc + + + The Apache Commons Daemon jsvc is a set of libraries and applications to run Java applications on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. + + + + + + + just + + + Use sparingly. In the phrase, "Just open the file...", omit the word "just." + + + + + + + JVM + + + Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine," or "Java VM," or only the noun itself, "virtual machine." You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)." Do not use Jvm or jvm. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/K.xml b/tmp/en-US/xml_tmp/K.xml new file mode 100644 index 0000000..8a8b51d --- /dev/null +++ b/tmp/en-US/xml_tmp/K.xml @@ -0,0 +1,170 @@ + + +%BOOK_ENTITIES; +]> + + K + + + KB, kB + + + See the IBM Style Guide for the correct abbreviation to use for specific use cases. + + + + + + + kbps, KBps, kBps + + + kbps is the accepted abbreviation for kilobit per second, or 1000 bits per second. + + + KBps and kBps are accepted abbreviations for kilobyte per second, or 1000 bytes per second. + + + + + + + kerberize + + + Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence. + + + + + + + kernel + + + The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. + + + + + + + Kernel-based Virtual Machine (KVM) + + + Spell out on first use, capitalized. Use the initialism (KVM) thereafter. It is an industry standard, and a proper noun. + + + + + + + kernel panic + + + Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. + + + + + + + kernel space, kernel-space + + + n. Two words when used as a noun. + + + adj. Hyphenate as an adjective, "kernel-space." Do not use "kernelspace." + + + + + + + keyboard key + + + When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X." When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S." + + + See also . + + + + + + + key ring + + + n. Use the two-word form as a noun. For example, "add your new key to the key ring." + + + adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server." + + + Only use the one-word form, "keyring," if it is the actual name of a command, package, or other proper noun. + + + + + + + keytab + + + n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . + + + + + + + key-value + + + adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair." Do not use "key/value" or any other variations. + + + + + + + Kickstart + + + adj. A network installation system for some Linux distributions. + http://en.wikipedia.org/wiki/Kickstart (Linux) + + + + + + + + + kill + + + If terminating a UNIX process, use "kill." For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate." For example, "To terminate the process, press Q." + + + + + + + knowledge base + + + Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase." In this case, use the one-word form and capitalize the "K." Do not capitalize the "b." + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/L.xml b/tmp/en-US/xml_tmp/L.xml new file mode 100644 index 0000000..1443a75 --- /dev/null +++ b/tmp/en-US/xml_tmp/L.xml @@ -0,0 +1,266 @@ + + +%BOOK_ENTITIES; +]> + + L + + + LAN + + + Correct. This is an acronym for Local Area Network. Do not use Lan or lan. + + + + + + + latency + + + + + In general, the period of time that one component in a system is spinning its wheels waiting for another component. Latency, therefore, is wasted time. For example, in accessing data on a disk, latency is defined as the time it takes to position the proper sector under the read/write head. + + + + + + In networking, the amount of time it takes a packet to travel from source to destination. Together, latency and bandwidth define the speed and capacity of a network. + + + + + + + + + + + later + + + Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also . + + + + + + + leave out + + + Do not use. Use "omit" instead. + + + + + + + + left-click + + + v. Write the term hyphenated. Do not use "left click" or "leftclick." + + + + + + + + + LibreOffice + + + A Linux desktop suite. Do not use "Libre," "Libreoffice," or "Libre Office." + + + See also + + + + + + + license + + + n., v. Use this form for both the noun and the verb. + + + + + + + life cycle, life-cycle, lifecycle + + + n. Two words. Only use the one-word form if it is an established part of a software interface, part of a proper noun, or an external standard. + + + adj. Hyphenate. + + + + + + + Linux + + + Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." + + + Linux is a registered trademark of Linus Torvalds. Use a registered trademark symbol on first use. + + + + + + + load + + + + + To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. + + + + + + v. In programming, "to load" means to move from one storage type to another storage type for use. + + + + + + n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) that the network carries, or the amount of CPU in use at any given time. + + + + + + + + + + + load balancing + + + Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. + + + + + + + logical topology + + + Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. + + + + + + + + login, log in + + + Write as one word as an adjective or noun, or as two words as a verb. + + + + + adj., n. One word. For example, "the login credentials". + + + + + + v. Two words. For example, "to log in as root". + + + + + + + + + log in to + + + v. Write as three words. For example, "to log in to the system". + + + + + + lookup, look-up, look up + + + n. Use the one-word form. + + + v. Use the two-word form. + + + adj. Hyphenate when used as a modifier. For example, "a look-up table." + + + + + + + look at + + + Do not use. Use "examine" or "inspect" or some other more precise term instead. + + + + + + + loopback address + + + The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. No hardware is associated with a loopback interface, and it is not physically connected to a network. + + + With a loopback interface, IT professionals can test IP software without concern for broken or corrupted drivers or hardware. + + + + + + + lots of + + + Do not use. Use "many" instead. + + + + + + + LPAR + + + Abbreviation of "logical partitioning", a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Language.xml b/tmp/en-US/xml_tmp/Language.xml new file mode 100644 index 0000000..fb6f3b4 --- /dev/null +++ b/tmp/en-US/xml_tmp/Language.xml @@ -0,0 +1,1326 @@ + + +%BOOK_ENTITIES; +]> + + + Choosing Appropriate Language + + + Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + + + If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. + + + Red Hat is committed to eliminating use of language that might exclude or offend certain groups of people. This chapter describes some considerations for use of inclusive language. + + + Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. + + +
+ Avoiding Misleading or Confusing Language + + Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. + + + + best practices + + + This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." + + + See the section for additional information about recommendations in Red Hat documentation. + + + + + + first come, first served + + + Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. + + + + + + + + +
+
+ Identifying and Avoiding Slang + + Examples of slang terms: + + + + administrivia + + + Not a word. Do not use. + + + + + + + anything you like, anything they like + + + This phrase is probably readily understood but should not appear in Red Hat documentation. + + + + + "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." + + + Rephrase to something more suitable, such as "... to register any other kind of plug-in." + + + + + + + + + + + + ask (as a noun), make the ask + + + Ask is a verb. Do not use it as a noun. + + + + + + + at this point in time + + + Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. + + + + + + + automagic + + + Also, automagical. Both terms are slang. Do not use. + + + + + + + best-of-breed + + + Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + + + + + + + bleeding edge + + + Do not use. + + + + + + + bottom line + + + Traditionally used in financial contexts; avoid overuse. + + + + + + + + bucketize + + + Not a word. Try "categorize" or "organize into logical groups." + + + + + + + center of competency + + + Do not use. + + + + + + + check this site + + + Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + + + + + + + coopetition + + + Not a word. Do not use. + + + + + + + core competency + + + Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + + + + + + + eat your own dogfood + + + Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + + + + + + + data point + + + Do not use. + + + + + + + dig deeper, delve deeper + + + "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + + + + + + + double-edged sword, double-bladed sword + + + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + + + + + + + enterprise-ready + + + Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + + + + + + + exceed your expectations + + + Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + + + + + + + fib + + + A fib is a "small lie," also known as a "white lie." This sentence appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." + + + + + + + flying by the seat of your pants + + + Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. + + + + + + + frame it up + + + Do not use. + + + + + + + frown upon + + + "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + + + + + + + fuzzy (search) + + + Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: + + + + + In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. + + + + + + + The use of "fuzzy" is valid in this context. + + + Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." + + + Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. + + + + + + + going-forward basis + + + Jargon. Say "from now on," "in the future," or something similar. + + + + + + + happy path + + + Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is localized slang and could easily be misunderstood. It could also produce problems for translation. + + + + + + + harness the power + + + Do not use. + + + + + + + have a crack at, jump right in + + + Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. + + + + + + + if you want, if you wish + + + Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." + + + + + + + in concert with + + + Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." + + + + + + + improve, enhance + + + Vague. Try to be more specific. + + + + + + + in a pinch + + + Under a tight schedule, hard pressed to achieve something. + + + + + + + infomediary + + + Not a word. Do not use. + + + + + + + is designed to + + + Avoid this and similar phrases when describing products and services. Instead, state what the product does. + + + + + Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. + + + + + + Correct: SSH works with almost any kind of public key algorithm or encoding format. + + + + + + + + + + + kettle of fish + + + Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. + + + + + + + leverage + + + Avoid. Alternatives include "use" and "take advantage of". + + + + + + + lights on, lights-on + + + Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. + + + It is typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." + + + + + + + low-hanging fruit + + + Metaphor. Do not use. + + + + + + + marketecture + + + Not a word. Do not use. + + + + + + + meet your needs + + + Vague. Try to be more specific, for example, "lower your middleware costs." + + + + + + + mission-critical + + + Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Ensure that you have the applications that you need to help your customers." versus "Ensure that you have the mission-critical applications that your customers demand." + + + + + + + net-net + + + Jargon. Use "in summary," "the end result," or something similar. + + + + + + + niche focus + + + Do not use. + + + + + + + over the wire + + + Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. + + + + + + + pain in the backside + + + Nobody should ever write this expression or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. + + + + + + + paradigm + + + Avoid. Use "model," "standard," or something similar. + + + + + + + performant + + + In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. + + + + + + + physicalize + + + Not a word. Do not use. + + + + + + + piggyback + + + Slang. Do not use. + + + + + + + pre-baked + + + Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. + + + + + productize + + + Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] + + + + + + + ready to rumble + + + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." + + + + + + + rest on your laurels + + + Do not use. + + + + + + + right before doing something + + + Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. + + + + + + + root your server in the /serverRoot directory + + + This expression is inelegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. + + + + + + + shoot yourself in the foot + + + To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + + + + + + + shy of + + + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. + + + + + + + silo, siloed + + + Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," or something similar. + + + + + + + + solutioning + + + Not a word. Lazy version of "creating a solution." + + + + + + + solutions-based + + + Do not use. + + + + + + + solution stack + + + Do not use. + + + + + + + + stovepipe + + + Jargon. In business, related to lack of cross-organizational communication, similar to "silo." + + + + + + + synergistic, synergy + + + Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. + + + + + + + synergical connectivity + + + Seriously? + + + + + + + to think outside the box + + + 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? + + + + + + + tunnel vision + + + Do not use. + + + + + + + under the covers + + + This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + + + + + + + value-added + + + Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." + + + + + + + very + + + Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." + + + + + + + virtual elephants + + + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. + + + + + + + + +
+
+ Neologisms (Invented Words) + + The English language is full of these words. Some of them are useful; some of them are less so; others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and is generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. + + + Examples + + + "This feature allows synchronization of adds, deletes, and changes ..." + + + + + This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + + + + + + + + + + +
+
+ Anthropomorphism + + Anthropomorphism is applying human qualities to non-human things or animals. Avoid it in your writing. + + + Examples + + + The computer will think for a brief period. + + + + + Computers do not actually think but they might take a while to "process" commands. + + + + + + + + + + The Proxy Server is talking to either RHN Hosted or a Satellite Server. + + + + + It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. + + + + + + + + + + + Report an issue + + +
+ + +
+ Inclusive Language + + Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. + + + Replace terms that reinforce cultural, racial, or other types of bias with an alternative. + + + Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + + For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. + + + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + + + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + + + Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + + + Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". + + + Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. + +
+ + +
+ Avoiding Ambiguities + + + + Capitalizing Proper Nouns + + + In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. + + + + + + + + + Example + Improvement + + + + + + + This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. + This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. + + + + + + + +
+ + + + + + Homographic Verbs + + + The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + + + + + + + + + + Example + Improvement + + + + + + + The next() method should return null to indicate the end of results. + The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. + + + + It may be held in memory. + It can be held in memory. OR It might be held in memory. + + + + + + + +
+ + + + + + Homonymity + + + When a single term has multiple meanings, be explicit in order to differentiate between them. + + + + + + + + + Example + Improvement + + + + + + + Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. + Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. + + + + To create another administrator, click New on the File menu. + To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. + + + + + + + +
+ + + See also . + + + + + + + + + Verb phrases + + + When you have more than one infinitive verb within a sentence, be clear what each verb refers to. + + + + + + + + + + Example + Improvement + + + + + + + Use the utility to run activities and save your settings. + + Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + + + + + + + +
+ + + + + + + Invisible Plurals + + + Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. + + + + + + + + + Example + Improvement + + + + + + + Once the file retrieval has been completed, you are ready to restart your system. + After the files have been retrieved, you can restart your system. + + + + + + + +
+ + + + + + Verb phrases + + + Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. + + + + + + + + + + Example + Improvement + + + + + + + If the completed field contains text, it does not change. + If the completed field contains text, that text does not change. + + + + + + + +
+ + + + + + Synonymity + + + Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. + + + For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. + + + + + + + Use of "using" + + + Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. + + + + + + + + + + Example + Improvement + + + + + + + + Open the firewall ports using the existing service configuration. + + + Option 1: Open the firewall ports by using the existing service configuration. + + Option 2: Use the existing service configuration to open the firewall ports. + + + + + + The resource agents using mail alerts require a mail transport agent. + The resource agents that use mail alerts require a mail transport agent. + + + + + + + +
+ + + + + + Verb phrases + + + Ensure that a verb phrase at the start of a sentence modifies the correct word. + + + + + + + + + + Example + Improvement + + + + + + + Having configured your environment, the product is ready to be used. (The product does not configure the environment.) + After you configure your environment, you can use the product. + + + + + + + +
+ + + + + + + +
+ +
+ Dates and Times + + + Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. + + + + Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". + + + + Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. + + + + For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". + + + + Use "noon" or "12 noon" instead of "12 PM". + Use "midnight" or "12 midnight" instead of "12 AM". + + + Examples + + + The training class begins at 10 AM on 1 April 2021. + + + The coffee break is from 2:00 PM to 2:30 PM. + + + + + + +
+ + + +
+ Numbers + + Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. + + + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + + + Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). + + + See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. + + + +
+ Phone numbers + + Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international use by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. + + +
+ +
+ \ No newline at end of file diff --git a/tmp/en-US/xml_tmp/M.xml b/tmp/en-US/xml_tmp/M.xml new file mode 100644 index 0000000..000dacc --- /dev/null +++ b/tmp/en-US/xml_tmp/M.xml @@ -0,0 +1,317 @@ + + +%BOOK_ENTITIES; +]> + + M + + + macOS + + + In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. + + + + + + + + + make sure + + + This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." + + + You might be able to use "verify" or "ensure" instead. + + + + + + + manual, man page + + + Correct. Two words. Do not use "manpage." + + + + + + + matrixes + + + Correct. This is the correct plural form for US English spelling. Do not use "matrices." + + + + + + + + MB + + + + + When written as MB, stands for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). + + + + + + When written as Mb, stands for megabit. + + + + + + + + + + + MBps + + + Initialism for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps. + + + + + + + MBR + + + Initialism for Master Boot Record, a small program that is executed when a computer boots up. Typically, the MBR resides on the first sector of the hard disk. The program begins the boot process by looking up the partition table to determine which partition to use for booting. It then transfers program control to the boot sector of that partition, which continues the boot process. In DOS and Windows systems, you can create the MBR with the FDISK /MBR command. + + + + + + + media + + + + + 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 fibre 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. + + + + + + + + + + + menu-driven + + + adj. Correct. Do not use "menu driven" or "menudriven." + + + Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program. + + + + + + + message + + + n. Write "the system displays a message" or "send an instant message." + + + adj. For example, "A messaging system." + + + Do not use as a verb. + + + + + + + metadata + + + Correct. Do not use "meta data" or "meta-data." + + + + + + + microservice + + + n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See https://en.wikipedia.org/wiki/Microservices for a definition. + + + + + + + Microsoft + + + Correct. Do not use "MS," "MSFT," or "MicroSoft." + + + + + + + misconfigure + + + v. This term is in common use and does appear in some dictionaries, but try to avoid it if possible. Do not hyphenate. + + + + + + + Montecito + + + Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. + + + + + + + mount + + + v. + + + + + To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. + + + + + + + To install a device, such as a disk drive or expansion board. + + + + + + + + + + + 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. + + + + + + + Mozilla Firefox + + + Correct. First reference must be "Mozilla Firefox." Subsequent references can be "Firefox." + + + + + + + Mozilla Thunderbird + + + Correct. First reference must be "Mozilla Thunderbird." Subsequent references can be "Thunderbird." + + + + + + + MDOS + + + Correct. Do not use "ms-dos," "MSDOS," or "msdos." + + + + + + + multiprocessing + + + Correct. Do not use "multi-processing." + + + + + + + must + + + Use when referring to a task that a user is required to do. For example, "You must make a backup" is a requirement, but "You should make a backup" is a suggestion. + + + + + + + mutexes + + + Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. + + + + + + + + MySQL + + + Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an + + ® symbol to denote a registered trademark. + + + + + + + + diff --git a/tmp/en-US/xml_tmp/N.xml b/tmp/en-US/xml_tmp/N.xml new file mode 100644 index 0000000..f129cd6 --- /dev/null +++ b/tmp/en-US/xml_tmp/N.xml @@ -0,0 +1,130 @@ + + +%BOOK_ENTITIES; +]> + + N + + + navigate to + + + Use "Navigate to" when moving through multiple GUI 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. + + + + + + need + + + Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). + + + + + + + + + needs, needs to be, need to + + + Avoid when possible. Suggested alternatives include "must," "required," or "should." + + + + + + + + + .NET + + + The Microsoft .NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and supports several programming languages. + + + "Microsoft .NET" is correct for the first reference, and ".NET" for all following references. + + + + + + + network transparency + + + A condition in which an operating system or other service gives user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems NFS, now a de facto industry standard, provides access to shared files through the Virtual File System (VFS) interface that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. + + + + + + + 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. + + + 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. + + + + + + + node + + + + + In networks, a processing location. A node can be a computer or some other device such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or a Media Access Control (MAC) address. + + + + + + In tree structures, a point where two or more lines meet. + + + + + + + + + + + nonsecure + + + Do not use. Use "insecure" instead. + + + + + + + NULL or null + + + When a command or value is stated, use NULL. When stating that something is null, use "null," all lowercase. + + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/O.xml b/tmp/en-US/xml_tmp/O.xml new file mode 100644 index 0000000..3cc7ed5 --- /dev/null +++ b/tmp/en-US/xml_tmp/O.xml @@ -0,0 +1,275 @@ + + +%BOOK_ENTITIES; +]> + + O + + + Objective C + + + Correct. Do not use "Objective-C." + + + + + + + object-oriented + + + Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." + + + + Also, do not use "object-orientated". + + + + + + + OEM + + + n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. + + + + To provide equipment to another company, an OEM, which customizes and markets the equipment. + + + + + + + offline + + + adj. Write as one word. Do not use "off-line." + + + + + + + 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. + + + 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. + + + + + + + + + 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." + + + + + + + + onboard + + + adj, tr.v. Use the one-word form in all cases. + + + + + + once + + + Use only to mean "one time." Do not use as a conjunction to mean "after" or "when." + + + + + + + online + + + adj. Write as one word. Do not use "on-line." + + + + + + + + + + on-site + + + adj. Hyphenate when used as an adjective, as in "on-site labs." + + + + + + + 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. + + + + + + + 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." + + + + + + + opcodes + + + Correct. Do not use "op-codes." + + + + + + + OpenJDK + + + The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. + + + + + open architecture + + + An architecture whose specifications are public. It includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. + + + + + + + Open InfiniBand + + + "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. + + + + + + + OpenOffice + + + A Linux desktop suite. Do not use "Openoffice," "Open Office," or "ooo." + + + See also . + + + + + + + open source + + + Correct. Do not use "OpenSource," "opensource," or "open-source." + Only capitalize the "o" in "open source" at the beginning of a sentence. + + + + + + + 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". + + + + + + + operating system + + + Correct. Do not use Operating System, or OS. + + + + + + + orientate + + + Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps to familiarize you with the environment." + + + + + + + output device + + + Any machine that is capable of representing information from a computer, including display screens, printers, plotters, and synthesizers. + + + + + + + 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 . + + + + + + + override + + + Correct. Do not use "over-ride" or "over ride." + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Objectives.xml b/tmp/en-US/xml_tmp/Objectives.xml new file mode 100644 index 0000000..fc7a45f --- /dev/null +++ b/tmp/en-US/xml_tmp/Objectives.xml @@ -0,0 +1,54 @@ + + +%BOOK_ENTITIES; +]> + + 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: + + + + Accurate and consistent + + + + + + Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale. + + + + + + Comprehensible, with a fog index of 9-12, using the Gunning fog index. + + + + + + User focused, providing information without patronizing the reader, or making presumptions about their skills. + + + + + + + + + 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. + + + + + + + diff --git a/tmp/en-US/xml_tmp/P.xml b/tmp/en-US/xml_tmp/P.xml new file mode 100644 index 0000000..a931ed0 --- /dev/null +++ b/tmp/en-US/xml_tmp/P.xml @@ -0,0 +1,327 @@ + + +%BOOK_ENTITIES; +]> + + P + + + PaaS + + + n. The correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. + + + Marketing, Brand, Customer Portal Usage + + For all-caps text, such as banners, use "<VARIANT>-ASERVICE" for the spelled-out version. The same abbreviation is used across all groups. + + + + + + + + + PC + + + n. Use to refer to a personal computer. + + + + + + + + persist + + + v. + Do not use as a verb to mean "store" or "save," for example, when referring to persistent storage. + + + + + PHP + + + n. Use PHP when referring to the language in general. Use php when referring to the specific command or some other literal use. + + + See for specific PHP language information. See for more general information. + + + + + + + Pico, pico + + + n, adj. Capitalize when referring to the text editor or to the programming language. Do not capitalize when referring to the SI prefix. + + + + + + + plain text + + + 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." + + + + + + + please + + + 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. + + + + + + + pluggable + + + adj. Something that is capable of being plugged in, especially in terms of (for example) software modules. "Hot-pluggable" is also widely used with respect to hardware to indicate that it can be connected and recognized without powering down the system. + + + + + + + plug-in + + + n. Write hyphenated. Do not use "plugin." + + + A hardware or software module that adds a specific feature or service to a larger system. + + + + + + + + + + PM + + + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". + + + See also . + + + See the IBM Style Guide for a full discussion of how to represent times. + + + + + + + pop-up + + + n, adj. Do not use "popup" or "pop up." + + + + + + + PostScript + + + n. It is a registered trademark of Adobe. Do not use "Postscript." + + + + + + + PowerPC + + + 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 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. + + + + + + + POSIX + + + n. Do not use "Posix," "posix," or variations thereof. + + + An acronym for "Portable Operating System Interface for UNIX." + + + + + + + PPP + + + n. Do not use "ppp" or "Ppp." + + + An initialism for Point-to-Point Protocol. + + + + + + + press + + + v. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." + + + + + + + proof of concept + + + Use the following rules to form the plural of this phrase: + + + + Use "proofs of concept" for multiple proofs and only one concept. + + + + + + Use "proofs of concepts" for multiple proofs and multiple concepts. + + + + + + Do not use "proof of concepts." + + + + + + + + + + + + + pseudo-ops + + + Correct. Do not use "pseudo ops" or "pseudoops." + + + + + + + + + pull-down + + + adj. Use only if you must specify the type of menu or list. Do not use "pulldown." + + + + + + + push-button automation, turn-key automation + + + Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use accurate language for the situation, such as: + + + + + User-triggered automation + + + + + Ready-to-use, ready-to-deploy + + + + + Self-service, self-provisioned. + + + + + Single-step automation + + + + + On-demand automation + + + + + + + PXE + + + Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. + + + PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Preface.xml b/tmp/en-US/xml_tmp/Preface.xml new file mode 100644 index 0000000..b356255 --- /dev/null +++ b/tmp/en-US/xml_tmp/Preface.xml @@ -0,0 +1,12 @@ + + +%BOOK_ENTITIES; +]> + + Preface + + + + + diff --git a/tmp/en-US/xml_tmp/Punctuation.xml b/tmp/en-US/xml_tmp/Punctuation.xml new file mode 100644 index 0000000..aeddd9a --- /dev/null +++ b/tmp/en-US/xml_tmp/Punctuation.xml @@ -0,0 +1,478 @@ + + +%BOOK_ENTITIES; +]> +
+ Punctuation + + This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. + +
+ Colons and Semicolons + + Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. + + + To relate clauses: + + The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: + + + + + + + They had been writing code all night: this factor could explain their bloodshot eyes. + + + + + + They had been writing code all night; this factor could explain their bloodshot eyes. + + + + + + I spend a lot of money on food; last month, I went out to eat 36 times. + + + + + + I spend a lot of money on food: last month, I went out to eat 36 times. + + + + + + + The phrase following a semicolon or colon should begin with a lowercase letter, unless it begins with a proper noun. In the case of a colon, use an uppercase letter if the phrase constitutes a complete sentence on its own. + + + Try to limit your use of colons and semicolons. Separate sentences with a period if possible. + + + To introduce a list or series: + + A colon is generally used before a list or series. + + + + + + + The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill. + + + + + + + Do not use a colon if the list is a complement or object of an element in the sentence. + + + + + Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail. + + + + + + The colors I hate most are: + + + + + green + + + + + + orange + + + + + + pink + + + + + + magenta + + + + + + + + + + + Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. + + + + + The steps for changing directories are as follows: + + + + + Open a terminal. + + + + + + Type cd Documents/Books. + + + + + + + + + + + Use a colon to introduce a bullet list. + + + + + In the Properties dialog box, notice the following entries: + + + + + Connection name + + + + + + Count + + + + + + Confirm starting connection + + + + + + Confirm stopping connection + + + + + + Cost per + + + + + + + + + + + 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 semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. + + + + + + I think; therefore, I am. + + + + + + +
+
+ Commas + + In compound sentences: + + Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. + + + + + + + I spent five hours working on this document, but I lost it when my computer crashed. + + + + + + Do you want to go the mall and the grocery store with me, or are you going to watch football instead? + + + + + + You play and I'll sing. + + + + + + + A comma can be omitted from a sentence with several clauses, but only when there is little chance that the sentence could be misread without it. + + + + + We played football all afternoon and were completely exhausted but we still stayed up watching movies all night. + + + + + + + That sentence is acceptable, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence. + + + In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction. + + + + + You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice. + + + + + + + In adverbial clauses and phrases: + + If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: + + + + + + + I'll go to lunch with you if we can get pizza. + + + + + + I don't want to go out for pizza, because I had pizza yesterday. + + + + + + + If a dependent clause comes before the main clause, use a comma whether the clause is restrictive or not. + + + + + If we get pizza, I'll go to lunch with you. + + + + + + When I heard the voice on the other end of the line, I was quite surprised. + + + + + + + In adjectival clauses or phrases: + + An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. + + + + + + + The application, which comes with excellent documentation, is used by many graphic artists. + + + + + + + An adjectival clause that cannot be dropped without changing the meaning of the sentence is not set off with commas: + + + + + The plan that matters most to us will be easy to implement. + + + + + + + With coordinate adjectives: + + Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. + + + + + + + My dog is loyal, obedient, and affectionate. + + + + + + It was a long, boring meeting. + + + + + + + With series and lists: + + Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. + + + + + + + Today I am wearing socks, shoes, pants, and a shirt. + + + + + + +
+
+ Parentheses + + Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. + + + + + + I tried to get to the elevator before the door shut, but I was too slow. + + + + + + Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead. + + + + + + + Expressions beginning with for example, that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. + + + + + + He interviewed the biggest stars of the day, namely, Madonna, Johnny Cash, and Jack Nicholson. + + + + + + Classic works of literature (such as Dickens, Shakespeare, the Brontes) lined the shelves. + + + + + + + If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. + + +
+
+ Quotation Marks + + Commas and periods go inside quotation marks. + + + + Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. + + + + A Correct Example of the Use of Quotation Marks + + For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." + + + + + + + +
+
+ Apostrophes + + Do not use an apostrophe to denote a plural. + + + To denote a possessive, use an apostrophe as follows: + + + Plural nouns not ending in s should add an 's (for example, the alumni's contribution). + + + Plural nouns ending in s only need an apostrophe (for example, the horses' food). + + + Singular common nouns ending in s should add an 's unless the next word begins with an s (for example, the witness's answer or the witness' story). + + + Singular proper names ending in s only need an apostrophe (for example, Dickens' novels). + + +
+ +
+ diff --git a/tmp/en-US/xml_tmp/Q.xml b/tmp/en-US/xml_tmp/Q.xml new file mode 100644 index 0000000..2754d0a --- /dev/null +++ b/tmp/en-US/xml_tmp/Q.xml @@ -0,0 +1,53 @@ + + +%BOOK_ENTITIES; +]> + + Q + + + Q and A + + + n. Abbreviation for "Question and Answer," this format is listed in the American Heritage Dictionary. + + + + In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. + + + + + + + + + + qeth + + + Lowercase at all times. + + + + + + + + + + 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. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/R.xml b/tmp/en-US/xml_tmp/R.xml new file mode 100644 index 0000000..bc7ce25 --- /dev/null +++ b/tmp/en-US/xml_tmp/R.xml @@ -0,0 +1,244 @@ + + +%BOOK_ENTITIES; +]> + + R + + + RAM + + + Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." + + + + + + + RAM disk + + + 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. + + + + + + + raw + + + Unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device. + + + The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device. + + + + + + + + raw data + + + Information that is not organized, formatted, or analyzed. + + + + + + + read + + + v. To copy data to a place where a program can use it. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. It can also refer to the act of determining the contents of a variable or parameter. + + + n. The act of reading. For example, a fast disk drive performs 100 reads per second. + + + + + + + read-only + + + Capable of being displayed, but not modified or deleted. For all operating systems, you can protect objects (disks, files, or directories) with a read-only attribute that prevents other users from modifying the object. + + + + + + + read/write + + + Capable of being displayed (read) and modified (written to). Most objects (disks, files, or directories) are read/write, but you can also protect objects with a read-only attribute that prevents other users from modifying the object. + + + + + + + real time/real-time + + + n. The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." + + + + adj. Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." + + + + + + + reboot + + + Correct. Do not use "re-boot." + + + + + + + RedBoot + + + Correct. Do not use "Redboot" or "Red Boot." + + + + + + + refer to + + + Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." + + + + + + + + remote access + + + The ability to log on to a network from a distant location. Generally, it implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations that are connected directly to the network is slower data transfer speeds. + + + + + + + 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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. + + + + + + + + required + + + See . + + + + + + + return + + + When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. See for other platforms. + + + + + + + right-click + + + v. Write the term hyphenated. Do not use "right click." + + + + + + + right now + + + Use "now" instead. + + + + + + + ROM, PROM + + + Acronym for read-only memory, computer memory on which data is prerecorded. After data has been written to a ROM chip, it cannot be removed and can only be read. + + + A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a device called a PROM programmer. + + + + + + + roundtable, round table + + + v. Use the one-word form to refer to a type of event or gathering. + + + + n. Use the two-word form to refer to a circular table. + + + + + + + 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." + + + + + + + runlevel + + + Correct. Do not use "run level" or "run-level." + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Resources.xml b/tmp/en-US/xml_tmp/Resources.xml new file mode 100644 index 0000000..dbdc529 --- /dev/null +++ b/tmp/en-US/xml_tmp/Resources.xml @@ -0,0 +1,145 @@ + + +%BOOK_ENTITIES; +]> + + Resources + + This section lists some books and websites for you to consult on your quest to create a better document. + + + The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: + + + + Technical content: software manuals and documentation, user guides, training courses + + + + + + Technical collateral: white papers and technology briefs + + + + + + Marketing content: advertising, promotions, articles + + + + + + Corporate collateral: related to company or products + + + + + + Press releases + + + + + + + +
+ References for Technical Content and Collateral + + + + IBM Style Guide. IBM Corporation, latest version. + + + + + + The Chicago Manual of Style, 17th Edition. Chicago: The University of Chicago Press, 2017. + + + + + + Merriam-Webster Collegiate Dictionary + + + Visit https://www.merriam-webster.com/ for subscription options. + + + + + + The American Heritage Dictionary of the English Language + + + An online edition is accessible free of charge through http://www.ahdictionary.com/ + + + + + + +
+
+ References for Marketing and Corporate Collateral + + + + AP Stylebook Online + + + + + + Merriam-Webster Online http://www.merriam-webster.com/ + + + + + + +
+ + + + + diff --git a/tmp/en-US/xml_tmp/Revision_History.xml b/tmp/en-US/xml_tmp/Revision_History.xml new file mode 100644 index 0000000..5b4000e --- /dev/null +++ b/tmp/en-US/xml_tmp/Revision_History.xml @@ -0,0 +1,524 @@ + + +%BOOK_ENTITIES; +]> + + Revision History + + + + 3-0 + July 2021 + + Julian + Cable + jcable@redhat.com + + + + Major update to align with some recent changes in IBM Style. + Sentence case is required for captions, legends, and diagram labels. + Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. + Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. + Minor edits so the guide itself conforms with its own advice. + + + + + + + + 2.0-1 + Wed Jun 3 2015 + + David + O'Brien + davido@redhat.com + + + + Fix issue "use 'singular to plural' pronouns -- typo? #6 . + Repair some XML in the grammar section. + Minor repairs to language. + + + + + + + + 1.6-14 + Wed Mar 12 2014 + + David + O'Brien + davido@redhat.com + + + + Added entry for "huge pages". + Updated entry for virtual machine to allow for abbreviation. + Updated section on using non-breaking spaces. + Added entry for correct capitalization of partners. + Added entry for "datasheet". + Change to common brand. + Remove some internal links that are no longer valid. + Generalize some entries based on advice from legal. + + + + + + + + 1.6-13 + Wed Feb 26 2014 + + David + O'Brien + davido@redhat.com + + + + 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. + 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. + + + + + + + + 1.6-12 + Fri Dec 20 2013 + + David + O'Brien + davido@redhat.com + + + + General cleanup of "U" section. BZ 1037923: Added entry for "uninterruptible". + General cleanup of "T" section. BZ 1038090: Added entry for "tier-1". + General tidy-up. Fix some typos. Updates cross-references. Started on BZ 820071. + + + + + + + + 1.6-11 + Wed Nov 27 2013 + + Julie + Wu + docs@redhat.com + + + + BZ 997202 Remove incorrect content regarding Japanese translation. + + + + + + + + 1.6-10 + Mon Nov 25 2013 + + Brice + Fallon-Freeman + docs@redhat.com + + + + BZ 1022268 Add entry for "time frame" + BZ 1022266 Add entry for "roundtable" + BZ 1027041 Add entry for "big data" + + + + + + + + 1.6-9 + Wed Nov 20 2013 + + David + O'Brien + docs@redhat.com + + + + Add balance of entries from "Things Shadowman would Never Say". + + + + + + + + 1.6-8 + Tue Nov 12 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 896006 Add entry for "health check". + BZ 896009 Add entry for "skill set". + BZ 924040 Add entry for referring to fonts. + BZ 915987 Add entry for "bare metal". + Add exception for Brand and Marketing heading styles. + BZ 1017549 Added entry for how to use URLs and footnotes. + BZ 1019258 Fixed Gunning Fog typo Ch 1 under "Readability". + BZ 989838 Updated entry for x86 usage. + BZ 1010163 Added entry for "Q and A". + BZ 821606 Updated entry for qeth based on new information. + BZ 1017149 Add entry for DevOps. + BZ 972916 Add entries for GNOME and GNOME Classic; document use of Super key. + General review and updates to examples. + Fix some revision history entries. + + + + + + + + 1.6-7 + Mon Aug 12 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 995310 Add entry for documenting command syntax. + BZ 984803 Add entry for online and offline backups. + BZ 989942 Add entry How to document Interface element labels. + BZ 989838 Update entries for referring to AMD64, Intel 64, x86, and related terms. + + + + + + + + 1.6-6 + Wed Jul 31 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 892839 Update entry for internet. + BZ 980307 Add entry for hyphenation. + BZ 965898 Add entry for documenting currencies. + BZ 989942 Add entry for documenting interface elements to Design section. + Various punctuation and spelling fixes. + + + + + + + + 1.6-5 + Wed Jul 17 2013 + + Julie + Wu + docs@redhat.com + + + + BZ 973074 Add entry for "talking to" in section on slang + BZ 950303 Add entry for SIOV + BZ 965378 Update entry for "Unset" + + + + + + + + 1.6-4 + Thu May 23 2013 + + David + O'Brien + docs@redhat.com + + + + Add "cloudbursting," "cloudwashing," and "pluggable" to usage dictionary. + + + + + + + + 1.6-2 + Tue Mar 19 2013 + + David + O'Brien + docs@redhat.com + + + + 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. + BZ 909015 Entry for "refer to" conflicts with IBM style guide. + Update some punctuation standards and cross references. + + + + + + + + 1.6-1 + Wed Jan 30 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 905707 Update section on active and passive voice with more examples and exceptions. + BZ 896245 Describe use of non-breaking spaces with company and product names. + BZ 821603 Add entry for Sybase Adaptive Server Enterprise usage. + + + + + + + + 1.6-0 + Tue Jan 15 2013 + + David + O'Brien + docs@redhat.com + + + + BZ 823350 Additional Detail for Chapter 2.4 + BZ 821609 Add correct usage of PHP to Usage Dictionary + BZ 831909 Remove "in depth" from Usage Dictionary; covered in standard references. + BZ 868067 Add usage for PaaS, IaaS, and SaaS + BZ 821615 Correct use of JVM + BZ 836869 Update SSH entry to allow for lowercase version + BZ 829173 Add correct usage of "time to live" to Usage Dictionary + BZ 821616 capitalization when referring to Btrfs + BZ 821612 Usage Dictionary addition: "zip" + BZ 824209 word usage: segfault + BZ 821599 Documenting exceptions + BZ 821607 Definitions for Virtual Machine, Virtualized Guest + BZ 821606 should we say "QETH device" or "qeth device" + BZ 820480 Add "cgroups" to Usage Dictionary + + + + + + + + 1.5-5 + Wed Nov 21 2012 + + David + O'Brien + docs@redhat.com + + + + BZ 878313 - Duplicate "and" in entry for AMD 64. + Review and update sections M, N, T, U, and V. + + + + + + + + 1.5-4 + Sun Nov 11 2012 + + David + O'Brien + docs@redhat.com + + + + Remove "hostname" entry; covered in IBM. + + + + + + + + 1.5-3 + Thu Nov 08 2012 + + David + O'Brien + docs@redhat.com + + + + BZs 871652, 820071, 821611, 821610. + Updates to and integration of Chapters X, Y, and Z. + Updated section on "Avoiding Slang." + Removed some redundant entries. + Various cleanups based on IBM Style Guide. + New entries from Word Nerds discussions. + + + + + + + + 1-4 + Fri Aug 31 2012 + + David + O'Brien + docs@redhat.com + + + + Removed some redundant entries. + Bugs 851646, 850596, 821595, 821617. + + + + + + + + 1-3 + Sun Aug 26 2012 + + David + O'Brien + docs@redhat.com + + + + Removed some redundant entries. + Patched some entries based on IBM Style Guide. + Cleaned up A, B, C, and part of D in Word Usage Dictionary. + + + + + + + + 1-2 + Fri Jul 27 2012 + + David + O'Brien + docs@redhat.com + + + + Added some xrefs to make life simpler. Added some temp links to BZs that are yet to be addressed. + More work on punctuation, spelling, typos, and duplicate and redundant entries. + Some structure reorganization. + Updated Feedback page. + Removed Author Group. + + + + + + + + 1-1 + Fri Apr 13 2012 + + David + O'Brien + docs@redhat.com + + + + Clean up redundant variablelist tags. + Remove a few duplicate entries. + Start working on making punctuation consistent. + + + + + + + + 1-0 + Mon Feb 20 2012 + + Gemma + Sheldon + gsheldon@redhat.com + + + + DocBook conversion from original guide on the Intranet. + + + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/S.xml b/tmp/en-US/xml_tmp/S.xml new file mode 100644 index 0000000..0a76bb9 --- /dev/null +++ b/tmp/en-US/xml_tmp/S.xml @@ -0,0 +1,762 @@ + + +%BOOK_ENTITIES; +]> + + S + + + S/390 + + + Use the full description "IBM S/390." Do not use "s390," "S390," or any other variations. + + + + + + + SaaS + + + The correct abbreviation for "Software-as-a-Service." + + See also . + + + + + + + Samba + + + Correct. Do not use "samba" or "SAMBA." + + + + + + + record + + + Correct. Do not use "s-record," "Record," "s-Record," or any other variations. + + + + + + + screen capture + + + n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. + + + + + + + screen saver + + + n. Do not use "screensaver." + + + + + + + scrollbar + + + n. Do not use "scroll bar" or "scroll-bar." + + + + + + + secure + + + n., vb. Due to potential legal ramifications, do not use without a qualifier. + See for examples. + + Using Qualifiers with Sensitive Terms + + + + + + Original text + Improvement + + + + + With this new version, the application is running on a secure, gateway-protected endpoint. + With this new version, the application is running on a more secure, gateway-protected endpoint. + + + This function secures your connection. + This function improves the security of your connection. + + + Developers can easily change the code to implement secured access. + Developers can easily change the code to make access more secure. + + + +
+ + + + see + + + Use to refer readers to another resource. Avoid using "refer to" in this context. + + + + + + + segmentation fault + + + n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. + + + See also "What is a segfault?" on the Red Hat Customer Portal for more information. + + + + + + + SELinux + + + 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. + + + + + + + send out + + + Do not use. Instead, use "emit" or "issue." + + + + + + + server farm + + + Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. + + + + + + + server-side/server side + + + See . + + + + + + + setup + + + Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: + + + + + + Each setup provides different features. + + + + + + You need to set up a user profile as part of the registration process. + + + + + + Follow the set-up instructions included with the hardware. + + + + + + + + + + + SHA-1, SHA-2 + + + 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. + + + See for full details. + + + + + + + Shadowman + + + Correct. Do not use "Shadow Man" or "ShadowMan." The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. + + + + + + + shadow passwords + + + Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. + + + Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package. + + + + + + + shadow utilities + + + Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. + + + + + + + share name + + + Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." + + + + + + + + shebang + + + n. Refers to the character sequence consisting of the number sign and exclamation mark (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. + + + + + + + shell + + + A "shell" is a software application, for example, /bin/bash or /bin/sh, which provides an interface to a computer. Do not use this term to describe where to type commands. + + + + + + + shell prompt + + + Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt," "terminal," or "shell." + + + + + + + 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 . + + + + + + + shut down + + + v. Correct. Do not use "shut-down." Only use "shutdown" when referring to the /sbin/shutdown system command. + + + + + + + + sign in + + + v. Write as two words. For example, "two options are available to sign in". + + + + + + sign in to + + + v. Write as three words. For example, "to sign in to the system". + + + + + + simply + + + Do not use. See also . + + + + + + + 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. + + + + + + + skill set, skills, knowledge + + + n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: + + + Example Use of Term "Skillset" Versus "Skills" + + Incorrect: Do you have the right skillset to be an RHCE? + + + Correct: Do you have the right skills to be an RHCE? + + + + + Example Use of Term "Knowledge" + + Incorrect: This course gives you the skill-set knowledge to complete your RHCT exam successfully. + + + Correct: This course gives you the knowledge to complete your RHCT exam successfully. + + + + + + + + + SLA + + + n. SLA stands for Service Level agreement. + The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. + This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. + + + + + + smart card + + + n. Do not use smartcard or smart-card. + + + + + + + + SOCKS + + + Correct. Do not use "socks." When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5." + + + + + + + softcopy + + + Do not use. Instead, use "online." For example, "To view the online documentation ..." + + + + + + + sound card + + + n. Do not use "soundcard" or "sound-card." + + + + + + + Source-Navigator™ + + + Correct. Do not use "Source Navigator." Source-Navigator™ is a trademark of Red Hat. + + + + + + + source + + + v. In addition to the generic use of this term as a noun and verb, in +a programming and technical sense, it also means "Run the source command against the named file." + + + + + space + + + Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key. + + + + + + + Spacebar + + + n. Use when referring to the keyboard key, such as "Press the Spacebar key to continue." + + + + + + + spec file + + + n. Use to refer to an RPM spec file. Do not use "specfile." + + + + + + + specific + + + When used as a modifier, put a hyphen before "specific," such as "MIP-specific," "Linux-specific," and "chip-specific." + + + + + + + spelled + + + Correct. It is the standard US English spelling. Do not use "spelt." + + + + + + + + SQL + + + When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. + + + When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. + + + Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." + + + More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." + + + + + + + SR-IOV + + + Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. + + + + + + + SSH + + + Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. + + + Do not use as a verb. + + + + Example Use of "SSH" + + + Incorrect: To begin, "ssh to the remote server." + + + Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar. + + + + + + + SSL + + + Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. + + + + + + + stand-alone + + + adj. Write hyphenated. 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. + + + + + + + StarOffice + + + A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." + + + + The successors of StarOffice are and . + + + + + + + start up + + + v. Do not use. Instead, use "activate" or "invoke." + + + + + + + startx + + + Correct. Do not use StartX or other variants. + + + + + + + straightforward + + + adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward." + + + + + + + su + + + Correct. The Linux command to change to a named user. Do not use SU (all caps). + + + + + + + subcommand + + + Correct. Do not use "sub-command" or "verb." + + A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: + + +hammer import organization --help + + In this example, "hammer" is the main or primary command, and "import" and "organization" are subcommands. is an option. + + + See also . + + + + + + + subdirectory + + + Correct. Do not use "sub-directory." See also . + + + + + + + submenu + + + Correct. Do not use "sub-menu." See also . + + + + + + + subpackage + + + Correct. Do not use "sub-package." + + + This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages." + + + Any other use of this word is strongly discouraged. + + + Note: Subpackages are not the same as dependencies and should not be treated as such. + + + + + + + superuser + + + A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." + + + + + + + swap space + + + Correct. Do not use "swapspace." Capitalize at the beginning of a sentence only. + + + + + + + Sybase Adaptive Server Enterprise (ASE) + + + Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE." If discussing the high-availability version, use "Sybase ASE and High Availability." + + + See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. + + + + + + + SysV + + + Correct. Do not use Sys V or System V. + + + + + + + symmetric encryption + + + A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Slang.xml b/tmp/en-US/xml_tmp/Slang.xml new file mode 100644 index 0000000..f4ec60b --- /dev/null +++ b/tmp/en-US/xml_tmp/Slang.xml @@ -0,0 +1,876 @@ + + +%BOOK_ENTITIES; +]> + + Avoiding Jargon, Slang, Metaphors, and Misleading Language + + Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. + + + If you find slang terms or other difficult-to-understand passages in our documentation, use this page to search for alternatives. + +
+ Avoiding Misleading or Confusing Language + + Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. + + + + best practices + + + This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." + + + See the section for additional information about recommendations in Red Hat documentation. + + + + + + first come, first served + + + Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. + + + + + + + + +
+
+ Identifying and Avoiding Slang + + Examples of slang terms: + + + + administrivia + + + Not a word. Do not use. + + + + + + + anything you/they like + + + This is probably readily understood but should not appear in Red Hat documentation. + + + + + "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." + + + Rephrase to something more suitable, such as "...to register any other kind of plug-in." + + + + + + + + + + + + ask (as a noun), make the ask + + + Ask is a verb. Do not use it as a noun. + + + + + + + at this point in time + + + Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. + + + + + + + automagic + + + Also, automagical. Both terms are slang. Do not use. + + + + + + + best-of-breed + + + Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + + + + + + + bleeding edge + + + Do not use. + + + + + + + bottom line + + + Traditionally used in financial contexts; avoid overuse. + + + + + + + + bucketize + + + Not a word. Try "categorize" or "organize into logical groups." + + + + + + + center of competency + + + Do not use. + + + + + + + check this site + + + Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + + + + + + + coopetition + + + Not a word. Do not use. + + + + + + + core competency + + + Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," etc. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + + + + + + + eat your own dogfood + + + Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + + + + + + + data point + + + Do not use. + + + + + + + dig deeper, delve deeper + + + "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + + + + + + + double-edged sword, double-bladed sword + + + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + + + + + + + enterprise-ready + + + Although we used to use this term to emphasize our products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + + + + + + + exceed your expectations + + + Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + + + + + + + fib + + + A fib is a "small lie," also known as a "white lie." This appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." + + + + + + + flying by the seat of your pants + + + Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. + + + + + + + frame it up + + + Do not use. + + + + + + + frown upon + + + "To frown upon" means to hold in low regard, not to approve of, etc. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). + + + + + + + fuzzy (search) + + + Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: + + + + + In Directory Server, if you do a fuzzy search for "Smith" you will probably also get "Smyth," because it sounds the same. + + + + + + + The use of "fuzzy" is valid in this context. + + + Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." + + + Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. + + + + + + + going-forward basis + + + Jargon. Say "from now on," "in the future," or something similar. + + + + + + + happy path + + + Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is very localized slang and could easily be misunderstood. It could also produce problems for translation. + + + + + + + harness the power + + + Do not use. + + + + + + + have a crack at/jump right in + + + Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. + + + + + + + if you want, if you wish + + + Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." + + + + + + + in concert with + + + Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." + + + + + + + improve, enhance + + + Vague. Try to be more specific. + + + + + + + in a pinch + + + Under a tight schedule, hard pressed to achieve something. + + + + + + + infomediary + + + Not a word. Do not use. + + + + + + + is designed to + + + Avoid this and similar phrases when describing products and services. Instead, state what the product does. + + + + + Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. + + + + + + Correct: SSH works with almost any kind of public key algorithm or encoding format. + + + + + + + + + + + kettle of fish + + + Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. + + + + + + + leverage + + + Avoid. Alternatives include "use" and "take advantage of". + + + + + + + lights on, lights-on + + + Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. + + + Typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." + + + + + + + low-hanging fruit + + + Metaphor. Do not use. + + + + + + + marketecture + + + Not a word. Do not use. + + + + + + + meet your needs + + + Vague. Try to be more specific, for example, "lower your middleware costs." + + + + + + + mission-critical + + + Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Make sure you have the applications you need to help your customers." vs. "Make sure you have the mission-critical applications your customers demand." + + + + + + + net-net + + + Jargon. Use "in summary," "the end result," or something similar. + + + + + + + niche focus + + + Do not use. + + + + + + + over the wire + + + Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent/transmitted in plain text" is fine. + + + + + + + pain in the backside + + + Nobody should ever write this or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. + + + + + + + paradigm + + + Avoid. Use "model," "standard," or something similar. + + + + + + + performant + + + In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. + + + + + + + physicalize + + + Not a word. Do not use. + + + + + + + piggyback + + + Slang. Do not use. + + + + + + + pre-baked + + + Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. + + + + + productize + + + Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] + + + + + + + ready to rumble + + + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." + + + + + + + rest on your laurels + + + Do not use. + + + + + + + right before doing something + + + Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. + + + + + + + root your server in the /serverRoot directory + + + This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. + + + + + + + shoot yourself in the foot + + + To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Remove the sentence - it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") + + + + + + + shy of + + + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang. + + + + + + + silo, siloed + + + Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," "segregated," or something similar. + + + + + + + solutioning + + + Not a word. Lazy version of "creating a solution." + + + + + + + solutions-based + + + Do not use. + + + + + + + solution stack + + + Do not use. + + + + + + + + stovepipe + + + Jargon. In business, related to lack of cross-organizational communication, similar to "silo." + + + + + + + synergistic, synergy + + + Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. + + + + + + + synergical connectivity + + + Seriously? + + + + + + + to think outside the box + + + 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? + + + + + + + tunnel vision + + + Do not use. + + + + + + + under the covers + + + This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + + + + + + + value-added + + + Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." + + + + + + + very + + + Use with caution. For example, there is little value in saying "very cost-effective" vs. "cost-effective." + + + + + + + virtual elephants + + + This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. + + + + + + + + +
+
+ Neologisms (Invented Words) + + The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. + + + Examples + + + "This feature allows synchronization of adds, deletes, and changes ..." + + + + + This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." + + + + + + + + + + +
+
+ Anthropomorphism + + Anthropomorphism is applying human qualities to non-human things or animals. Avoid this in your writing. + + + Examples + + + The computer will think for a brief period. + + + + + Computers do not actually think but they might take a while to "process" commands. + + + + + + + + + + The Proxy Server is talking to either RHN Hosted or a Satellite Server. + + + + + It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. + + + + + + + + + + + Report an issue + + +
+ + diff --git a/tmp/en-US/xml_tmp/T.xml b/tmp/en-US/xml_tmp/T.xml new file mode 100644 index 0000000..2609a09 --- /dev/null +++ b/tmp/en-US/xml_tmp/T.xml @@ -0,0 +1,250 @@ + + +%BOOK_ENTITIES; +]> + + T + + + taskbar + + + n. One word. Do not use "task bar." + + + + + + + tar, tarball + + + n. See the Word Usage chapter of the IBM Style Guide. + + + + + + + + telco + + + Preferred abbreviation for "telecommunications company." Do not use "telecom." See also . + + + Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. + See . + + + + + + + telecommunications service provider + + + Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . + + + + + + + telecommunications + + + Vertical for communication service providers. Preferred abbreviation is "telco." + + + + + + + + + + terminal + + + n. Do not use to describe where to type commands. Use "command line" instead. + + + See the Word Usage chapter of the IBM Style Guide for more information. + + + + + + + terminal emulation + + + Refers to making a computer respond like a particular type of terminal. With a terminal emulation program, you can access a mainframe computer or bulletin board service with a personal computer. + + + + + + + text mode + + + Correct. Do not use "textmode" or "text-mode." + + + A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. + + + + + + + text-based + + + adj. Correct. Do not use "text based." + + + + + + + third-party (adj.), third party (n.) + + + adj., n. Use "third-party" as the adjectival form. Use "third party" as the nominal form. Consult a dictionary for more examples. + + + + + + + through + + + Correct. Do not use "thru" and do not use the hyphen or any other type of dash. + + + + + + + throughput + + + n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. + + + + + + + tier-1 + + + adj. Always use a numeral, and always hyphenate. Follow standard capitalization guidelines. + + + + + + + + time frame (n.) + + + Correct. Do not use "timeframe" or "time-frame." + + + + + + + time zone (n.) + + + Correct. Do not use "timezone" or "time-zone." + + + + + + + token-ring (n.) + + + 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. + + + + + + + + toolbar (n.) + + + Correct. Do not use "tool bar" or "tool-bar." + + + + + + + tooltip (n.) + + + Correct. One word. Use the term "tooltip" to refer to a brief, textual description that is displayed when a cursor is moved over a graphical image, such as an icon or button. Do not use the term "hover help". + + + + + + + totally + + + Do not use. See "basically." + + + + + + + troubleshoot (v.) + + + Correct. Do not use "trouble shoot" or "trouble-shoot." + + + + + + + TTL + + + Initialism for "time to live" (n.) and "time-to-live" (adj.) + + + Neither the noun nor the adjective should be capitalized unless you are documenting a GUI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. + + + + + + + type + + + Type can be used as either a verb or noun. You can write "Print the data type of init" or "To start Source-Navigator, type snavigator." + + + + + + + + diff --git a/tmp/en-US/xml_tmp/Template_Chapter.xml b/tmp/en-US/xml_tmp/Template_Chapter.xml new file mode 100644 index 0000000..bc015f2 --- /dev/null +++ b/tmp/en-US/xml_tmp/Template_Chapter.xml @@ -0,0 +1,20 @@ + + +%BOOK_ENTITIES; +]> + + Dummy Title + + dummy text + +
+ Dummy Section Title + + More dummy text. + + +
+ + + diff --git a/tmp/en-US/xml_tmp/Template_Section.xml b/tmp/en-US/xml_tmp/Template_Section.xml new file mode 100644 index 0000000..cbe285a --- /dev/null +++ b/tmp/en-US/xml_tmp/Template_Section.xml @@ -0,0 +1,12 @@ + + +%BOOK_ENTITIES; +]> +
+ + + + +
+ diff --git a/tmp/en-US/xml_tmp/Translation.xml b/tmp/en-US/xml_tmp/Translation.xml new file mode 100644 index 0000000..435afd5 --- /dev/null +++ b/tmp/en-US/xml_tmp/Translation.xml @@ -0,0 +1,383 @@ + + +%BOOK_ENTITIES; +]> + + Writing Clearly and Succinctly + + This chapter provides guidelines, tips, and techniques to help to make your writing easier to read and understand, and also to translate. + +
+ Sentence Structure + + This section describes how to construct your content for clarity and readability. + A full discussion of this topic is beyond the scope of this guide. + + +
+ Using and Formatting Lists + + 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 sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. + + + The following general guidelines apply to lists: + + + + Itemized lists + + + 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. + Titles are optional. + + + + + Ordered lists + + + They appear as a numbered list. + 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. + + + + + Variable lists + + + They 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.) + A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. + Tables are best reserved for information that relies on, or benefits greatly from, a grid layout. + + + + + Procedures + + + They appear as a list of numbered steps. + Procedures always include a title, and are used to list the required steps to achieve a task. + + + + + + You can nest lists, but try to keep the number of levels to two or fewer. + To nest procedures in DocBook, use <substep> elements. + + +
Formatting Lists for Readability + + It is important to provide sufficient 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. + If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. + DocBook uses the spacing attribute by default. + + + + Use a list with normal spacing if any list item contains the following components: + + + + + Nested lists. + Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. + + + + + Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). + + + + + Multiple paragraphs, or sentences that wrap to two or more lines. + + + + + Use a list with compact spacing in all other cases. + + + + The use of all but the simplest graphics in lists is strongly discouraged. + + + + + + The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. + + + + + + + + + Example + Improvement + + + + + + + + Before you start the installation, ensure that you have + + + + + enough free storage on your system + + + + + + backed up any data that you want to keep + + + + + + + to ensure a smooth installation. + + + + Before you start the installation, follow these steps to ensure a smooth installation: + + + + + Ensure that you have enough free storage on your system. + + + + + + Back up any data that you want to keep. + + + + + + + + + + + + + +
+
+
+ +
+ Noun Stacking + + Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. + + + + + + + + + + Example + Improvement + + + + + + + Plastic tubing and syringe tips. + Plastic tubing and plastic syringe tips. + + + + Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press Enter. + For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. + + + + + + + +
+
+ +
+
+ Grammatical Genders + + When using ambiguous pronouns such as "they" or "it", it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and might require other grammatical adjustments. + + + Further, an initialism such as RPM might refer to the package or to the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package. + + + + + + + + + Example + Improvement + + + + + + + Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. + Set the XYZ parameter to 1 in the /etc/config.conf configuration file. This parameter configures how the Gateway application handles incoming network traffic. + + + + The RPM is useful. + The RPM package is useful. OR The RPM Package Manager is useful. + + + + + + + + +
+ +
+
+ DocBook Elements + + Use the correct DocBook elements to help translators to understand the meaning of, and to identify, translatable and non-translatable terms. + + + + Tagged Terms in Sentences + + Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators must complete the blanks or tag terms themselves. + + + + + + + + + + + Example + Improvement + + + + + + + In /some/path/, grep for XYZ. + In the /some/path/ directory, use the grep command to search for "XYZ". + + + + contains a reference to the hostname return value from instance-2. + The parameter contains a reference to the hostname return value from your second server instance, instance-2. + + + + Troubleshooting Glance. + Troubleshooting the Glance image service. + + + + Installing the maven-changelog-plugin. + Installing the maven-changelog-plugin package. + + + + + + + +
+ +
+
+ Code Blocks + + Avoid including commentary within the same box as command input or output. These comments might be confused with part of the output, and during translation might be accidentally overlooked and left in English. + + + For example, consider the word "Usage" in the following block: + + +Usage: rhevm-iso-uploader [options] list +rhevm-iso-uploader [options] upload [file1] [file2] [file3] + +
+
+ Entities + + An entity is a primitive data type, which associates a string with either a unique alias (such as a user-specified name) or an SGML reserved word (such as #DEFAULT) + + + . Entities are called by reference, and take the form &name; (both the ampersand and the semicolon are required). + + + + Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. + + + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: + + + + + PRODUCT + + + + + + BOOKID + + + + + + YEAR + + + + + + HOLDER + + + + + + + Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in + + +
+ + + diff --git a/tmp/en-US/xml_tmp/U.xml b/tmp/en-US/xml_tmp/U.xml new file mode 100644 index 0000000..7d55d87 --- /dev/null +++ b/tmp/en-US/xml_tmp/U.xml @@ -0,0 +1,227 @@ + + +%BOOK_ENTITIES; +]> + + U + + + UID + + + n. UID and user ID are abbreviations of user identifier. Do not use "uid" or "User ID" or other variations unless specifically referring to a variable, argument, parameter, UI label, or similar. + + + + + + + UltraSPARC + + + Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. + + + 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. + + + + + + + undercloud + + + n. 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 . + + + + + + + uninterruptible + + + adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)." + + + + + + + UNIX + + + Correct. Do not use "Unix" or "unix." + + + UNIX is a registered trademark of The Open Group. + + + Do not use "UNIX-like." Use an expression such as "Linux, UNIX, and similar operating systems" instead. + + + + + + + unset + + + Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. + + + To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. + + + This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. + + + + + + + untrusted + + + Use only in the context of security relationships. For example, web browsers often indicate that a site is "untrusted" if it cannot verify that site's security certificate. + + + + + + + upgrade + + + v. Correct. Do not use "up-grade" or "up grade." + + + + + + + UPS + + + Abbreviation of uninterruptible power supply, a power supply that includes a battery to maintain power in the event of a power outage. + + + + + + + upsell (v.), upselling (n.) + + + Marketing Use Only + + "The practice of offering customers additional or more expensive products or services after they have already agreed to buy something. + http://www.ahdictionary.com/word/search.html?q=upsell + + " + + + Do not hyphenate or use as two words. No adjectival form is currently recognized. + + + + + + + + + upstream + + + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream." + + + + + + + uptime + + + n. Correct. Do not use "up-time" or "up time." + + + + + + + URL + + + n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. + + + See for more information. + + + + + + + + user + + + n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. + + + If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." + + + + + + + user interface + + + n. Correct. Do not use "user-interface" or "userinterface." + + + 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. + + + + + + + user name + + + n. Correct. Do not use "username" unless you are using it as a variable. + + + + + + + user space + + + n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space." Do not use "userspace." + + + + + + + utilize + + + Avoid this term. Write "use" instead. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/V.xml b/tmp/en-US/xml_tmp/V.xml new file mode 100644 index 0000000..b14bcb5 --- /dev/null +++ b/tmp/en-US/xml_tmp/V.xml @@ -0,0 +1,139 @@ + + +%BOOK_ENTITIES; +]> + + V + + + VAR + + + Acronym for value-added reseller. Same as OEM (original equipment manufacturer). + + + + + + + VDSM + + + Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. + + + + + + + vi + + + Correct. Use all lowercase letters. Do not use "VI" (all caps). + + + + + + + Vim + + + Correct when referring to the application. + Do not use "VIM" (all caps). + Only use "vim" (all lowercase) when referring to the command to start the application. + + + 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. + + + + + + + video mode + + + Correct. Do not use "video-mode" or "videomode." + + + The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. + + + + + + + virtual console + + + Correct. Do not use "virtual-console" or "Virtual Console" for general use. + + + It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." + + + + + + + virtual machine, VM + + + Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. + + + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. + + + + + + + virtualized guest + + + The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." + + + See also "guest operating system." + + + + + + + virtual router + + + An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. + + + + + + + VNIC + + + Abbreviation for virtual network interface card. Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. + + + + + + + VPN + + + Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/W.xml b/tmp/en-US/xml_tmp/W.xml new file mode 100644 index 0000000..c3aed22 --- /dev/null +++ b/tmp/en-US/xml_tmp/W.xml @@ -0,0 +1,139 @@ + + +%BOOK_ENTITIES; +]> + + W + + + WAN + + + A computer network that spans a relatively large geographical area. + Typically, a WAN consists of two or more local-area networks (LANs). + + + Computers connected to a wide-area network are often connected through public networks, such as the telephone system. + They can also be connected through leased lines or satellites. + The largest WAN in existence is the internet. + + + + + + + WCA + + + An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. + + + + WCAs are also called "query applications." + + + + + + + want + + + Use instead of "wish" or "would like." + Rephrase to avoid whenever possible. + For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." + + + + + + + we suggest + + + Do not use. + Use a more direct construction, or use "recommend." + For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." + + + + + + + webhook + + + n. One word. Common noun. + Capitalize only at the beginning of a sentence. + Use alternative capitalization only if it appears as a proper noun. + + + + + + + webpage + + + n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + + + + + + + + web UI + + + 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. + + + + + + + who, whom + + + Use the pronoun "who" as a subject. + Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. + + + For example: Who owns this phone? To whom does this phone belong? + + + + + + + will + + + + Do not use future tense unless it is absolutely necessary. + For example, do not write "The next section will describe the process in detail." + Instead, write "The next section describes the process in detail." + + + + + + + Window Maker + + + Correct. Do not combine into one word or hyphenate. + This is a window manager for the "X Window System." + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/WUG_Intro.xml b/tmp/en-US/xml_tmp/WUG_Intro.xml new file mode 100644 index 0000000..3bafcfd --- /dev/null +++ b/tmp/en-US/xml_tmp/WUG_Intro.xml @@ -0,0 +1,54 @@ + + +%BOOK_ENTITIES; +]> + + Usage Dictionary + + 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. + + + + A note about trademarks + + + 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 <trademark> tag. We do mark Red Hat's own trademarks. See Copyright Notices and Trademark Legends for more information. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/tmp/en-US/xml_tmp/WUG_References.xml b/tmp/en-US/xml_tmp/WUG_References.xml new file mode 100644 index 0000000..364183d --- /dev/null +++ b/tmp/en-US/xml_tmp/WUG_References.xml @@ -0,0 +1,19 @@ + + +%BOOK_ENTITIES; +]> + + References + + the IBM Style Guide + + + Chicago Manual of Style, 17th Edition + + + American Heritage Dictionary + + + + diff --git a/tmp/en-US/xml_tmp/XYZ.xml b/tmp/en-US/xml_tmp/XYZ.xml new file mode 100644 index 0000000..cce5486 --- /dev/null +++ b/tmp/en-US/xml_tmp/XYZ.xml @@ -0,0 +1,142 @@ + + +%BOOK_ENTITIES; +]> + + XYZ + + + X + + + An alternative reference to the "X Window System." Do not use X by itself when referring to "XEmacs." + + + + + + + XEmacs + + + Correct. Do not use "Xemacs." Use "xemacs" only when referring to a command, such as "To start XEmacs, type xemacs." + + + + + + + Xen + + + Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. + + + A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." + + + The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. + + + + + + + + xterm + + + Correct. Do not use "Xterm" unless the word is used at the beginning of a sentence. + + + + + + + X Windows + + + Do not use. It is an incorrect reference to the X Window System (or X). + + + + + + + X Window System + + + Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if ..." "To start an X session, from the shell prompt ..." + + + + + + + YAML + + + Recursive acronym for "YAML Ain't Markup Language." Expand on first use only. + + + + + + + you + + + Use second person wherever possible. Do not use "I," "we," "he," or "she." + + + + + + + you may + + + Avoid. For example, "you may" can be eliminated from the following sentence: "You may double-click the desktop ..." + + + + + + + zip + + + See the Word Usage chapter of the IBM Style Guide. + + + + + + + Zip Code + + + Correct. Do not use "zip code," "Zip code," or any other variation. + + + + + + + + + + + + From 06f365ee063078786db2458b6aa2f8681c2108b1 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 9 Jul 2021 12:37:31 +0100 Subject: [PATCH 18/27] Ongoing A-Z updates to align with IBM --- en-US/A.xml | 6 +++--- en-US/B.xml | 14 ++------------ en-US/C.xml | 3 +-- en-US/D.xml | 4 ++-- en-US/E.xml | 6 +++--- en-US/F.xml | 14 +++++--------- 6 files changed, 16 insertions(+), 31 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 86330f2..088be01 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -52,6 +52,7 @@ + all-in-one allinone @@ -94,10 +95,9 @@ - AM - am + Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". @@ -152,7 +152,7 @@ - + diff --git a/en-US/C.xml b/en-US/C.xml index d7e01a4..d21ba5a 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -172,9 +172,8 @@ client-side, client side - adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." + adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to some Windows servers." - n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." diff --git a/en-US/D.xml b/en-US/D.xml index dd4085f..4bae8f3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -216,9 +216,9 @@ disk, disc - Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. + Use "compact disc" or "hard disk." See the IBM Style Guide for more information and example use cases. - + diff --git a/en-US/E.xml b/en-US/E.xml index 976efae..f1865b9 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -7,12 +7,12 @@ E - e-book, e-business, e-commerce, e-learning, email + e-book, e-commerce, e-learning, email Refer to the primary reference for the type of copy you are creating, either AP or IBM. - + @@ -64,7 +64,6 @@ When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. - When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." @@ -137,6 +136,7 @@ + exclamation points (!) diff --git a/en-US/F.xml b/en-US/F.xml index 452a95b..571ab75 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -106,11 +106,9 @@ n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. - adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." - @@ -121,7 +119,7 @@ Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. - + @@ -149,7 +147,8 @@ - + + - + --> follow @@ -247,8 +245,6 @@ Do not use. Instead, use "compatible with later versions." See also . - - @@ -264,7 +260,7 @@ An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. - + From 345dab6c4eb71e77f81860ee8219c36707bd0ec0 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 9 Jul 2021 12:51:11 +0100 Subject: [PATCH 19/27] Deleting tmp files --- tmp/en-US/xml/0-9.xml | 42 - tmp/en-US/xml/A.xml | 329 ---- tmp/en-US/xml/Author_Group.xml | 18 - tmp/en-US/xml/B.xml | 439 ------ tmp/en-US/xml/Book_Design.xml | 146 -- tmp/en-US/xml/Book_Info.xml | 30 - tmp/en-US/xml/C.xml | 535 ------- .../Concepts_Cloud_ExpressFeatures.xml | 33 - .../Concepts_Cloud_FlexFeatures.xml | 27 - tmp/en-US/xml/Common_Content/Conventions.xml | 148 -- tmp/en-US/xml/Common_Content/Feedback.xml | 63 - .../xml/Common_Content/JBoss_Feedback.xml | 89 -- tmp/en-US/xml/Common_Content/Legal_Notice.xml | 42 - tmp/en-US/xml/Common_Content/Overview.xml | 53 - .../xml/Common_Content/Program_Listing.xml | 32 - .../Ref_Cloud_Compare_Deployment.xml | 117 -- .../xml/Common_Content/Revision_History.xml | 32 - .../Conventions_for_Writers_and_Editors.xml | 63 - tmp/en-US/xml/Cross_references.xml | 55 - tmp/en-US/xml/D.xml | 340 ----- tmp/en-US/xml/Design.xml | 1024 ------------- tmp/en-US/xml/E.xml | 193 --- tmp/en-US/xml/Easily_Confused_Words.xml | 92 -- tmp/en-US/xml/F.xml | 334 ----- tmp/en-US/xml/Feedback.xml | 13 - tmp/en-US/xml/G.xml | 268 ---- tmp/en-US/xml/Grammar.xml | 621 -------- tmp/en-US/xml/H.xml | 299 ---- tmp/en-US/xml/I.xml | 369 ----- tmp/en-US/xml/J.xml | 72 - tmp/en-US/xml/K.xml | 170 --- tmp/en-US/xml/L.xml | 265 ---- tmp/en-US/xml/Language.xml | 1299 ---------------- tmp/en-US/xml/M.xml | 309 ---- tmp/en-US/xml/N.xml | 125 -- tmp/en-US/xml/O.xml | 270 ---- tmp/en-US/xml/Objectives.xml | 53 - tmp/en-US/xml/P.xml | 327 ---- tmp/en-US/xml/Preface.xml | 12 - tmp/en-US/xml/Punctuation.xml | 470 ------ tmp/en-US/xml/Q.xml | 52 - tmp/en-US/xml/R.xml | 240 --- tmp/en-US/xml/Resources.xml | 143 -- tmp/en-US/xml/Revision_History.xml | 524 ------- tmp/en-US/xml/S.xml | 760 ---------- tmp/en-US/xml/Slang.xml | 877 ----------- tmp/en-US/xml/T.xml | 244 --- tmp/en-US/xml/Template_Chapter.xml | 20 - tmp/en-US/xml/Template_Section.xml | 12 - tmp/en-US/xml/Translation.xml | 373 ----- tmp/en-US/xml/U.xml | 226 --- tmp/en-US/xml/V.xml | 137 -- tmp/en-US/xml/W.xml | 121 -- tmp/en-US/xml/WUG_Intro.xml | 54 - tmp/en-US/xml/WUG_References.xml | 19 - tmp/en-US/xml/XYZ.xml | 138 -- tmp/en-US/xml_tmp/0-9.xml | 43 - tmp/en-US/xml_tmp/A.xml | 362 ----- tmp/en-US/xml_tmp/Author_Group.xml | 18 - tmp/en-US/xml_tmp/B.xml | 437 ------ tmp/en-US/xml_tmp/Book_Design.xml | 146 -- tmp/en-US/xml_tmp/Book_Info.xml | 31 - tmp/en-US/xml_tmp/C.xml | 544 ------- .../Conventions_for_Writers_and_Editors.xml | 65 - tmp/en-US/xml_tmp/Cross_references.xml | 57 - tmp/en-US/xml_tmp/D.xml | 343 ----- tmp/en-US/xml_tmp/Design.xml | 1035 ------------- tmp/en-US/xml_tmp/E.xml | 195 --- tmp/en-US/xml_tmp/Easily_Confused_Words.xml | 92 -- tmp/en-US/xml_tmp/F.xml | 336 ----- tmp/en-US/xml_tmp/Feedback.xml | 13 - tmp/en-US/xml_tmp/G.xml | 270 ---- tmp/en-US/xml_tmp/Grammar.xml | 631 -------- tmp/en-US/xml_tmp/H.xml | 302 ---- tmp/en-US/xml_tmp/I.xml | 382 ----- tmp/en-US/xml_tmp/J.xml | 72 - tmp/en-US/xml_tmp/K.xml | 170 --- tmp/en-US/xml_tmp/L.xml | 266 ---- tmp/en-US/xml_tmp/Language.xml | 1326 ----------------- tmp/en-US/xml_tmp/M.xml | 317 ---- tmp/en-US/xml_tmp/N.xml | 130 -- tmp/en-US/xml_tmp/O.xml | 275 ---- tmp/en-US/xml_tmp/Objectives.xml | 54 - tmp/en-US/xml_tmp/P.xml | 327 ---- tmp/en-US/xml_tmp/Preface.xml | 12 - tmp/en-US/xml_tmp/Punctuation.xml | 478 ------ tmp/en-US/xml_tmp/Q.xml | 53 - tmp/en-US/xml_tmp/R.xml | 244 --- tmp/en-US/xml_tmp/Resources.xml | 145 -- tmp/en-US/xml_tmp/Revision_History.xml | 524 ------- tmp/en-US/xml_tmp/S.xml | 762 ---------- tmp/en-US/xml_tmp/Slang.xml | 876 ----------- tmp/en-US/xml_tmp/T.xml | 250 ---- tmp/en-US/xml_tmp/Template_Chapter.xml | 20 - tmp/en-US/xml_tmp/Template_Section.xml | 12 - tmp/en-US/xml_tmp/Translation.xml | 383 ----- tmp/en-US/xml_tmp/U.xml | 227 --- tmp/en-US/xml_tmp/V.xml | 139 -- tmp/en-US/xml_tmp/W.xml | 139 -- tmp/en-US/xml_tmp/WUG_Intro.xml | 54 - tmp/en-US/xml_tmp/WUG_References.xml | 19 - tmp/en-US/xml_tmp/XYZ.xml | 142 -- 102 files changed, 25876 deletions(-) delete mode 100644 tmp/en-US/xml/0-9.xml delete mode 100644 tmp/en-US/xml/A.xml delete mode 100644 tmp/en-US/xml/Author_Group.xml delete mode 100644 tmp/en-US/xml/B.xml delete mode 100644 tmp/en-US/xml/Book_Design.xml delete mode 100644 tmp/en-US/xml/Book_Info.xml delete mode 100644 tmp/en-US/xml/C.xml delete mode 100644 tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml delete mode 100644 tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml delete mode 100644 tmp/en-US/xml/Common_Content/Conventions.xml delete mode 100644 tmp/en-US/xml/Common_Content/Feedback.xml delete mode 100644 tmp/en-US/xml/Common_Content/JBoss_Feedback.xml delete mode 100644 tmp/en-US/xml/Common_Content/Legal_Notice.xml delete mode 100644 tmp/en-US/xml/Common_Content/Overview.xml delete mode 100644 tmp/en-US/xml/Common_Content/Program_Listing.xml delete mode 100644 tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml delete mode 100644 tmp/en-US/xml/Common_Content/Revision_History.xml delete mode 100644 tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml delete mode 100644 tmp/en-US/xml/Cross_references.xml delete mode 100644 tmp/en-US/xml/D.xml delete mode 100644 tmp/en-US/xml/Design.xml delete mode 100644 tmp/en-US/xml/E.xml delete mode 100644 tmp/en-US/xml/Easily_Confused_Words.xml delete mode 100644 tmp/en-US/xml/F.xml delete mode 100644 tmp/en-US/xml/Feedback.xml delete mode 100644 tmp/en-US/xml/G.xml delete mode 100644 tmp/en-US/xml/Grammar.xml delete mode 100644 tmp/en-US/xml/H.xml delete mode 100644 tmp/en-US/xml/I.xml delete mode 100644 tmp/en-US/xml/J.xml delete mode 100644 tmp/en-US/xml/K.xml delete mode 100644 tmp/en-US/xml/L.xml delete mode 100644 tmp/en-US/xml/Language.xml delete mode 100644 tmp/en-US/xml/M.xml delete mode 100644 tmp/en-US/xml/N.xml delete mode 100644 tmp/en-US/xml/O.xml delete mode 100644 tmp/en-US/xml/Objectives.xml delete mode 100644 tmp/en-US/xml/P.xml delete mode 100644 tmp/en-US/xml/Preface.xml delete mode 100644 tmp/en-US/xml/Punctuation.xml delete mode 100644 tmp/en-US/xml/Q.xml delete mode 100644 tmp/en-US/xml/R.xml delete mode 100644 tmp/en-US/xml/Resources.xml delete mode 100644 tmp/en-US/xml/Revision_History.xml delete mode 100644 tmp/en-US/xml/S.xml delete mode 100644 tmp/en-US/xml/Slang.xml delete mode 100644 tmp/en-US/xml/T.xml delete mode 100644 tmp/en-US/xml/Template_Chapter.xml delete mode 100644 tmp/en-US/xml/Template_Section.xml delete mode 100644 tmp/en-US/xml/Translation.xml delete mode 100644 tmp/en-US/xml/U.xml delete mode 100644 tmp/en-US/xml/V.xml delete mode 100644 tmp/en-US/xml/W.xml delete mode 100644 tmp/en-US/xml/WUG_Intro.xml delete mode 100644 tmp/en-US/xml/WUG_References.xml delete mode 100644 tmp/en-US/xml/XYZ.xml delete mode 100644 tmp/en-US/xml_tmp/0-9.xml delete mode 100644 tmp/en-US/xml_tmp/A.xml delete mode 100644 tmp/en-US/xml_tmp/Author_Group.xml delete mode 100644 tmp/en-US/xml_tmp/B.xml delete mode 100644 tmp/en-US/xml_tmp/Book_Design.xml delete mode 100644 tmp/en-US/xml_tmp/Book_Info.xml delete mode 100644 tmp/en-US/xml_tmp/C.xml delete mode 100644 tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml delete mode 100644 tmp/en-US/xml_tmp/Cross_references.xml delete mode 100644 tmp/en-US/xml_tmp/D.xml delete mode 100644 tmp/en-US/xml_tmp/Design.xml delete mode 100644 tmp/en-US/xml_tmp/E.xml delete mode 100644 tmp/en-US/xml_tmp/Easily_Confused_Words.xml delete mode 100644 tmp/en-US/xml_tmp/F.xml delete mode 100644 tmp/en-US/xml_tmp/Feedback.xml delete mode 100644 tmp/en-US/xml_tmp/G.xml delete mode 100644 tmp/en-US/xml_tmp/Grammar.xml delete mode 100644 tmp/en-US/xml_tmp/H.xml delete mode 100644 tmp/en-US/xml_tmp/I.xml delete mode 100644 tmp/en-US/xml_tmp/J.xml delete mode 100644 tmp/en-US/xml_tmp/K.xml delete mode 100644 tmp/en-US/xml_tmp/L.xml delete mode 100644 tmp/en-US/xml_tmp/Language.xml delete mode 100644 tmp/en-US/xml_tmp/M.xml delete mode 100644 tmp/en-US/xml_tmp/N.xml delete mode 100644 tmp/en-US/xml_tmp/O.xml delete mode 100644 tmp/en-US/xml_tmp/Objectives.xml delete mode 100644 tmp/en-US/xml_tmp/P.xml delete mode 100644 tmp/en-US/xml_tmp/Preface.xml delete mode 100644 tmp/en-US/xml_tmp/Punctuation.xml delete mode 100644 tmp/en-US/xml_tmp/Q.xml delete mode 100644 tmp/en-US/xml_tmp/R.xml delete mode 100644 tmp/en-US/xml_tmp/Resources.xml delete mode 100644 tmp/en-US/xml_tmp/Revision_History.xml delete mode 100644 tmp/en-US/xml_tmp/S.xml delete mode 100644 tmp/en-US/xml_tmp/Slang.xml delete mode 100644 tmp/en-US/xml_tmp/T.xml delete mode 100644 tmp/en-US/xml_tmp/Template_Chapter.xml delete mode 100644 tmp/en-US/xml_tmp/Template_Section.xml delete mode 100644 tmp/en-US/xml_tmp/Translation.xml delete mode 100644 tmp/en-US/xml_tmp/U.xml delete mode 100644 tmp/en-US/xml_tmp/V.xml delete mode 100644 tmp/en-US/xml_tmp/W.xml delete mode 100644 tmp/en-US/xml_tmp/WUG_Intro.xml delete mode 100644 tmp/en-US/xml_tmp/WUG_References.xml delete mode 100644 tmp/en-US/xml_tmp/XYZ.xml diff --git a/tmp/en-US/xml/0-9.xml b/tmp/en-US/xml/0-9.xml deleted file mode 100644 index 074bdab..0000000 --- a/tmp/en-US/xml/0-9.xml +++ /dev/null @@ -1,42 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - 0-9 - - - 24x7, 24x7x365 - - - adj. Use "24x7" in most instances. Use "24x7x365" only to differentiate from others or highlight specifically that a service is offered every day of the year, for example, providing 24x7x365 phone support. - - - - - - - 2-track (IT) - - - adj. A less common way to refer to bimodal or hybrid IT. See . - - - - - - - 3-D - - - adj., n. Correct. Do not use 3D, 3-d, or other variations. - - - - - - - - - diff --git a/tmp/en-US/xml/A.xml b/tmp/en-US/xml/A.xml deleted file mode 100644 index 713db89..0000000 --- a/tmp/en-US/xml/A.xml +++ /dev/null @@ -1,329 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - A - - - "&" and "+" - - - Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. - - - - - - - above - - - Do not use to refer to information that was mentioned previously. When documents are converted to online format, the information might no longer be "above." Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. - - - - - - - agile - agile development - - - adj. Use only as an adjective. It is not a proper noun, nor is it owned or trademarked and should not be capitalized. - - - - - - - air gap - air wall - - - n. Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall." "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist. - - - - - all-in-one - allinone - - - n., adj. Hyphenate in both places. Do not use "allinone" or other variations. - - - - - - - alternate - - - v. "Alternate" as a verb means to change between two states or options. - - - See also . - - - - - - - alternative - - - adj. Describes another way or method of doing something. "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." - - - See also . - - - - - - - - - AM - am - - - Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - - - See also . - - - See the IBM Style Guide for a full discussion of how to represent times. - - - - - - - AMD64 - - - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. - - - The correct term for AMD's implementation of this architecture is "AMD64." When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - - - See also . - - - - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - - - For more information about Intel® trademarks, see and . - - - - - - - - - and/or - - - Avoid if possible. Try to rewrite to make the available options explicit and clear. Do not write this and/or that. Write this or that, or both. - - - - - - - Applixware - Applix - ApplixWare - - - "Applixware" is correct. Do not use "Applix" or "ApplixWare." - - - - - - - architect - - - Do not use as a verb. Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience. Use "design," "build," "create," or another descriptive verb instead. Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning. For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." - - - - - - - as well as - - - Not interchangeable with "and." "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. For example, "We sell kitchen electronics and china, as well as some gourmet foods." But "We sell kitchen electronics, china, and silverware." - - - - - - - as-a-Service - - - Some as-a-Service acronyms overlap. To avoid confusion, always spell out the full term on first use. - - - - - DRaaS (Disaster Recovery-as-a-Service) - - - - - - CaaS (Cloud-as-a-Service, Communications-as-a-Service, ) - - - - - - UCaaS (Unified Communications-as-a-Service) - - - - - - FaaS (Functions-as-a-Service) - - - - - - SaaS (Search-as-a-Service, Security-as-a-Service, Storage-as-a-Service, or Software-as-a-Service) - - - - - - PaaS (Payments-as-a-Service, Platform-as-a-Service) - - - - - - MaaS (Messaging-as-a-Service) - - - - - - SECaaS (Security-as-a-Service) - - - - - - TDBaaS (Time-series Database-as-a-Service) - - - - - - - When using as-a-Service acronyms: - - - - - Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out. - - - - - - When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS). - - - - - - Hyphenate when written out: Thing-as-a-Service. For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. - - - - - - Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service. - - - - - - - - - - - as long as - - - Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that". - - - - - - - ATM - - - Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. The cell size used with ATM is relatively small compared to units that are used with older technologies. - - - - - - - autofs - - - Always lowercase. It refers to the kernel-based automount utility. No other forms are recognized. - - - - - - - - - diff --git a/tmp/en-US/xml/Author_Group.xml b/tmp/en-US/xml/Author_Group.xml deleted file mode 100644 index c0e52a9..0000000 --- a/tmp/en-US/xml/Author_Group.xml +++ /dev/null @@ -1,18 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Red Hat Documentation Team - - - - - - - - - - diff --git a/tmp/en-US/xml/B.xml b/tmp/en-US/xml/B.xml deleted file mode 100644 index 60017d6..0000000 --- a/tmp/en-US/xml/B.xml +++ /dev/null @@ -1,439 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - B - - - back end, back-end - - - n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls." - - - adj. Hyphenate. For example, "when the back-end database processes a search operation …" - - - Do not use "backend." - - - See also - - - - - - - backup, back up - - - Write as one word as an adjective or noun, or as two words as a verb. - - - - - adj. One word. For example, "store the backup copies of important files in a secure location." - - - - - - n. One word. For example, "create a backup of your important files." - - - - - - v. Two words. For example, "always back up important files." - - - - - - - Do not use the hyphenated form, "back-up." - - - - - - - backtrace - - - n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. - - - - - - - backwards - - - Avoid using "backwards" unless you are stating that something has "backwards compatibility." - - - - - - - backwards compatible - - - Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also . - - - - - - - bandwidth - - - Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed time. - - - - - - - bare metal, bare-metal - - - n. Two words. - - - adj. Hyphenate. - - - - - - - basically - - - Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . - - - - - - - because, since, as - - - Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" and "as" to indicate the passage of time. - - - - - - - below - - - Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead. - - - - - - - big data - - - n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. - - - - - - - bimodal IT - - - Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. Many ways exist to describe this combination approach; be sure to use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those who are not familiar with Gartner's phrasing. - - - The practice of having both modes together is often referred to as hybrid, agile, or modern IT. - - - - Hybrid IT is a more general term, for example it could mean on-premises plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination that you mean. - - - - - - - - - biannual, bimonthly, biweekly, semiweekly, semimonthly - - - People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. - - - Instead of biweekly, write "every two weeks" or "every other week." - - - Instead of semiweekly, write "twice a week." - - - - - - - BIND - - - Correct when referring to the DNS software. Do not use Bind. - - - - - - - BIOS - - - Correct. The plural form is BIOSes. - - - - - - - bit rate - - - Correct. Do not use "bitrate." - - - - - - - Boolean - - - Correct. Named after George Boole, who first developed the concept. - - - According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. - - - - - - - boot - - - v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software to load during the boot process. - - - n. Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. - - - Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started. - - - - - - - boot disk - - - Two words. Do not use "boot diskette." - - - - - - - boot loader - - - Two words. Do not use "bootloader." - - - - - - - bottleneck - - - One word. Do not use "bottle neck" or "bottle-neck." - - - A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system. - - - - - - - bpp - - - Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16 bpp," not "16bpp." - - - - - - - Bps, bps - - - The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . - - - - - - - breadcrumb trail - - - See the IBM Style Guide for initial guidance on how to use this term. - - - - Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path that is taken to reach the current page. - - - - - - - Example breadcrumb trail, showing Disks as the actual name of the page. - - - Example breadcrumb trail, showing Disks as the actual name of the page. - - - - - - - - - - - break - - - (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail." - - - - - - - bring up - - - Do not use. Use "open" instead. - - - - - - - Britain - - - If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland. - - - - - - - broadcast - - - To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. - - - In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a selected list of recipients. - - - - - - - Btrfs - - - A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. - - - See for more information on this file system. - - - See for a list of file system names and how to present them. - - - - - - - bug fix - - - Two words. Do not use "bugfix." - - - - - - - built-in - - - adj. Hyphenate. Do not use "builtin" unless referring specifically to "Bash builtins" or if it is otherwise a proper noun. - - - - - - - bunches of - - - Do not use, unless "bunch" is a specific term that is used in the documented software. Use "many" or some other alternative instead. - - - - - - - button - - - Describe a GUI button as a "button," not a "pushbutton" or "push-button." - - - Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link." - - - See also . - - - - - - - - - diff --git a/tmp/en-US/xml/Book_Design.xml b/tmp/en-US/xml/Book_Design.xml deleted file mode 100644 index fd6995c..0000000 --- a/tmp/en-US/xml/Book_Design.xml +++ /dev/null @@ -1,146 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Overall Book Design - - This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. - - - This section covers the following topics: - - - - Titles and subtitles - - - - - - Prefaces - - - - - - Abstracts - - - - - - Introductions - - - - - - Unused heading titles - - - - - - - -
- Titles and Subtitles - - The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". - - - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". - - -
-
- Prefaces - - The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update. - - -
-
- Abstracts - - Abstracts for Red Hat technical documentation typically fall under the heading of a "descriptive abstract." From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form." - - - - - - A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: - - - - What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." - - - - - - How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." - - - - - - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." - - - - - - - - - Drawing these basics together might produce the following example abstract: - - - "The Red Hat Satellite 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." - - - Update or modify each component according to the type of book that you are writing. - - -
-
- Introductions - - The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. - - -
-
- Unused Heading Titles - - This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. - - - Overview - - Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. - - - - - About - - Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview." - - - - - Chapter and Section Introductions - - Do not create separate introductions for chapters and sections. Use any material that would constitute an introductory section to form body text following the chapter or section title. - - - - -
- -
- diff --git a/tmp/en-US/xml/Book_Info.xml b/tmp/en-US/xml/Book_Info.xml deleted file mode 100644 index 417bb28..0000000 --- a/tmp/en-US/xml/Book_Info.xml +++ /dev/null @@ -1,30 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Conventions for Writers and Editors - The Red Hat Style Guide - - 4.2 - 1 - - - The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml/C.xml b/tmp/en-US/xml/C.xml deleted file mode 100644 index 7f023d3..0000000 --- a/tmp/en-US/xml/C.xml +++ /dev/null @@ -1,535 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - C - - - can, may - - - Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If any of "can," "could," or "may" apply, use "can"; it is less tentative. - - - - - - - cannot - - - Correct, as one word, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." - - - - - - - CapEx, OpEx - - - Correct. These stand for "capital expenditures" and "operating expenses" respectively. Do not use alternative capitalization. - - - - - - - cd, CD - - - When referring to the change directory command, use cd. - - - When referring to a compact disk, use "CD." For example, "Insert the CD into the CD drive." The plural is "CDs." - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - CD #1 - - - When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1. - - - - - - - Ceph - - - Correct. Ceph is a distributed storage platform that provides object, block, and file storage. - See - - Do not use alternative capitalization. - - - - - - - cgroup - - - Correct (all lowercase) when referring to the kernel-based technology. It is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. It is therefore permissible to capitalize it if used at the beginning of a sentence. - - - Where cgroup refers to something else, for example, a package name, file name, and so on, use a literal rendition. - - - - - - - characters - - - Do not use "characters" to mean "bytes." In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. - - - In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. - - - - - - - check - - - Avoid. Use "verify," "ensure," or "read," depending on the context. - - - - - - - check box - - - n. Two words. Do not use "checkbox" or "check-box." - - - - - - - chipset - - - n. One word. Do not use "chip set" or "chip-set." - - - - - - - CI/CD - - - Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. - - - See also , , . - - - - - - - ciphertext - - - n. One word. Do not use "cipher text", "cipher-text", or other variants. - - - - - - - click - - - v. Use when referring to a GUI control button, for example, "Click OK." Do not use "click on". - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - client-side, client side - - - adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." - - - n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." - - - - - - - clobber, clobbered - - - Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the context. - - - - - - - cloud - - - Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." - - - - - - - cloudbursting - - - Define briefly on first use. - - - Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization pays only for extra computing resources when they are needed. - - - - - - - - - - cloudwashing - - - Define briefly on first use. - - - Refers to the process of rebranding legacy products to include the term "cloud" to increase their appeal to the cloud market, even if such inclusion is not completely justified. - - - - - - - code - - - n. Use only as a noun, not a verb. Use "write" for a verb. - - - - - - - colocate, colocation - - - Write unhyphenated, to refer to people or services in the same location. - - - - - - - combo-box - - - Do not use as an abbreviation for "combination box." See the relevant entry in the IBM Style Guide for further usage information. - - - - - - - comma-delimited - - - adj. Correct (compound adjective). A data format in which each piece of data is separated by a comma. This is a popular format for transferring data from one application to another, because most database systems are able to import and export comma-delimited data. - - - - - - - comma-separated values (CSV) - - - Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information that is broken up through use of commas. This method is often used to share data between different, but similar applications, wherein the comma is a translator of the data. - - - - - - - command button - - - Use "button" instead. - - - - - - - command-driven - - - adj. Correct (compound adjective). Do not use "command driven" or "commanddriven." - - - Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. - - - - - - - command language - - - n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. - - - With graphical user interfaces, the command language consists of operations that you perform with a mouse or similar input device. - - - - - - - command line, command prompt, command-line - - - See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. - - - - - - - commodity - - - Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and might imply that it is cheap. Use instead: - - - - - Volume - - - - - - Industry-standard - - - - - - - - - - - communication service provider (CSP) - - - Another way to refer to a telecommunications provider. See also . - - - - - - - Containers-as-a-Service - - - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . - - - - - - - container-based - - - Used to refer to more complex applications with multiple services that are distributed in containers. More common than "containerized." - - - - - - - containerized - - - Used to refer to an application or service that is distributed in a container or packed in a container. - - - - - - - continuous delivery (CD) - - - A software implementation architecture that ensures that all approved code can be easily pushed to production. - - - - - - - continuous deployment - - - A special case of continuous delivery, where approved code is automatically pushed to production. Do not use "CD" to refer to this practice. - - - - - - - continuous integration (CI) - - - A software development architecture where the developer code branch is synchronized with the main code branch multiple times per day. Development always works with the current code base. - - - - - - - control character - - - A special, non-printing character that begins, modifies, or ends a function, event, operation, or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. - - - - - - - control key - - - Use Ctrl instead, such as "To save the program, press CtrlS." - - - - - - - control program - - - A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows. - - - Control programs are also called operating environments. - - - - - - - cookie - - - n. A message given to a web browser by a web server. The browser stores the message in a text file named cookie.txt. The message is then sent back to the server each time the browser requests a page from the server. - - - - - - - CR - - - Use if referring to code, such as "Type CR at the end of each line ..." If referring to the keyboard key, use either Enter or Return, depending on the platform. - - - - - - - crash - - - IBM recommends the use of "fail" rather than "crash." Use the latter only if you can justify why "fail" is inadequate. - - - - - - - cross-platform - - - adj. Hyphenate. Do not use "crossplatform" or "cross platform." - - - Refers to the capability of software or hardware to run identically on different platforms. - - - - - - - cross-site scripting - - - Correct. When referring to cross-site scripting attacks, use "cross-site scripting attack." Acceptable use is also "cross-site scripting (XSS) attack." - - - - - - - CVE - - - n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. See for more information. - - - - - - - Cygmon - - - Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). - - - Refer to it as "Cygmon: a ROM monitor," not "Cygmon: the Cygnus ROM monitor," or "Cygmon: the ROM monitor." - - - - - - - - - diff --git a/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml b/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml deleted file mode 100644 index 8708261..0000000 --- a/tmp/en-US/xml/Common_Content/Concepts_Cloud_ExpressFeatures.xml +++ /dev/null @@ -1,33 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - Start managing your cloud applications for free - - - - - - Deploy your applications to the cloud at no extra cost - - - - - - Access your logs, databases, and file I/O, in the cloud - - - - - - Easily migrate components across OpenShift offerings using its consistent framework across deployment levels - - - - - - diff --git a/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml b/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml deleted file mode 100644 index a4e94c7..0000000 --- a/tmp/en-US/xml/Common_Content/Concepts_Cloud_FlexFeatures.xml +++ /dev/null @@ -1,27 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - Start your cloud environment with IaaS time free with a trial period - - - - - - Migrate existing applications with minimal modifications - - - - - - Enhance application performance with system access - - - - - - diff --git a/tmp/en-US/xml/Common_Content/Conventions.xml b/tmp/en-US/xml/Common_Content/Conventions.xml deleted file mode 100644 index 1a9cf35..0000000 --- a/tmp/en-US/xml/Common_Content/Conventions.xml +++ /dev/null @@ -1,148 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Document Conventions - - This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. - -
- Typographic Conventions - - Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows. - - - Mono-spaced Bold - - - Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example: - -
- - To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. - - -
- - The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. - - - Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example: - -
- - Press Enter to execute the command. - - - Press CtrlAltF2 to switch to a virtual terminal. - - -
- - The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously. - - - If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example: - -
- - File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. - - -
- - Proportional Bold - - - This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example: - -
- - Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). - - - To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar. - - -
- - The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. - - - Mono-spaced Bold Italic or Proportional Bold Italic - - - Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: - -
- - To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com. - - - The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. - - - To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. - - -
- - Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. - - - Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: - -
- - Publican is a DocBook publishing system. - - -
- -
-
- Pull-quote Conventions - - Terminal output and source code listings are set off visually from the surrounding text. - - - Output sent to a terminal is set in mono-spaced roman and presented thus: - - -books Desktop documentation drafts mss photos stuff svn -books_tests Desktop1 downloads images notes scripts svgs - - Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows: - - - -
-
- Notes and Warnings - - Finally, we use three visual styles to draw attention to information that might otherwise be overlooked. - - - - Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier. - - - - - - Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration. - - - - - - Warnings should not be ignored. Ignoring warnings will most likely cause data loss. - - - - -
-
- diff --git a/tmp/en-US/xml/Common_Content/Feedback.xml b/tmp/en-US/xml/Common_Content/Feedback.xml deleted file mode 100644 index 0a80e45..0000000 --- a/tmp/en-US/xml/Common_Content/Feedback.xml +++ /dev/null @@ -1,63 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Getting Help and Giving Feedback -
- Do You Need Help? - - help - getting help - - - - If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at . From the Customer Portal, you can: - - - - - Search or browse through a knowledge base of technical support articles about Red Hat products. - - - - - - Submit a support case to Red Hat Global Support Services (GSS). - - - - - - Access other product documentation. - - - - - - - Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at . Click the name of any mailing list to subscribe to that list or to access the list archives. - - -
-
- We Need Feedback - - feedback - contact information for this manual - - - - If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you. Please submit a report in Bugzilla: http://bugzilla.redhat.com/ against the product &PRODUCT;. - - - When submitting a bug report, be sure to mention the manual's identifier: &BOOKID; - - - If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily. - - -
-
- diff --git a/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml b/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml deleted file mode 100644 index 3601473..0000000 --- a/tmp/en-US/xml/Common_Content/JBoss_Feedback.xml +++ /dev/null @@ -1,89 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Getting Help and Giving Feedback -
- Do You Need Help? - - help - getting help - - - - If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at . From the Customer Portal, you can: - - - - - Search or browse through a knowledge base of technical support articles about Red Hat products. - - - - - - Submit a support case to Red Hat Global Support Services (GSS). - - - - - - Access other product documentation. - - - - - - - Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at . Click the name of any mailing list to subscribe to that list or to access the list archives. - - -
-
- Give us Feedback - - feedback - contact information for this manual - - - - If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product &BZPRODUCT; and the component &BZCOMPONENT;. The following link will take you to a pre-filled bug report for this product: &BZURL;. - - - Complete the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly. - - -Document URL: - - -Section Number and Name: - - -Describe the issue: - - -Suggestions for improvement: - - -Additional information: - - - - - Be sure to give us your name so that you can receive full credit for reporting the issue. - - -
- -
- diff --git a/tmp/en-US/xml/Common_Content/Legal_Notice.xml b/tmp/en-US/xml/Common_Content/Legal_Notice.xml deleted file mode 100644 index 21a433e..0000000 --- a/tmp/en-US/xml/Common_Content/Legal_Notice.xml +++ /dev/null @@ -1,42 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Copyright &YEAR; &HOLDER;. - - - This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. - - - Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. - - - Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Infinity logo, JBoss, OpenShift, Fedora, Hibernate, Ansible, CloudForms, RHCA, RHCE, RHCSA, Ceph, and Gluster are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the United States and other countries. - - - Linux is the registered trademark of Linus Torvalds in the United States and other countries. - - - Java is a registered trademark of Oracle and/or its affiliates. - - - XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. - - - MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. - - - Node.js is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. - - - The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. - - - All other trademarks are the property of their respective owners. - - - - diff --git a/tmp/en-US/xml/Common_Content/Overview.xml b/tmp/en-US/xml/Common_Content/Overview.xml deleted file mode 100644 index 23a6162..0000000 --- a/tmp/en-US/xml/Common_Content/Overview.xml +++ /dev/null @@ -1,53 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - OpenShift Overview - - The OpenShift deployment model currently offers two user levels: - - - - - OpenShift Express - - - - - - OpenShift Flex - - - - - - - Each OpenShift deployment level offers specific cloud and application management features. The following table compares the features of each OpenShift deployment level: - - -
- OpenShift Express - - OpenShift Express provides the tools to create, deploy and manage your applications in the cloud using a browser-based or a command line interface. With OpenShift Express you can: - - - -
-
- OpenShift Flex - - OpenShift Flex provides a graphical user interface (GUI) that you can use to create, deploy, configure, manage and monitor your cloud environment. With OpenShift Flex you can: - - - -
- - - diff --git a/tmp/en-US/xml/Common_Content/Program_Listing.xml b/tmp/en-US/xml/Common_Content/Program_Listing.xml deleted file mode 100644 index 81cce23..0000000 --- a/tmp/en-US/xml/Common_Content/Program_Listing.xml +++ /dev/null @@ -1,32 +0,0 @@ - - -%BOOK_ENTITIES; -]> - -static int kvm_vm_ioctl_deassign_device(struct kvm *kvm, - struct kvm_assigned_pci_dev *assigned_dev) -{ - int r = 0; - struct kvm_assigned_dev_kernel *match; - - mutex_lock(&kvm->lock); - - match = kvm_find_assigned_dev(&kvm->arch.assigned_dev_head, - assigned_dev->assigned_dev_id); - if (!match) { - printk(KERN_INFO "%s: device hasn't been assigned before, " - "so cannot be deassigned\n", __func__); - r = -EINVAL; - goto out; - } - - kvm_deassign_device(kvm, match); - - kvm_free_assigned_device(kvm, match); - -out: - mutex_unlock(&kvm->lock); - return r; -} - diff --git a/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml b/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml deleted file mode 100644 index 66cc349..0000000 --- a/tmp/en-US/xml/Common_Content/Ref_Cloud_Compare_Deployment.xml +++ /dev/null @@ -1,117 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Deployment Model Comparison - - - - - - - Feature - OpenShift Express - OpenShift Flex - - - - - - - Command Line Interface - Yes - No - - - - GUI Interface - Yes - Yes - - - - Create Cloud Objects - No - Yes - - - - Manage Cloud Objects - No - Yes - - - - Create Clusters - No - Yes - - - - Manage Clusters - No - Yes - - - - Create Servers - No - Yes - - - - Manage Servers - No - Yes - - - - Create Applications - Yes - Yes - - - - Manage Applications - Yes - Yes - - - - Import Applications - No - Yes - - - - Customize Applications - Yes - Yes - - - - Deploy Applications - Yes - Yes - - - - View Cloud Performance Statistics - No - Yes - - - - View Historical Cloud Performance Statistics - No - Yes - - - - - - -
- diff --git a/tmp/en-US/xml/Common_Content/Revision_History.xml b/tmp/en-US/xml/Common_Content/Revision_History.xml deleted file mode 100644 index b3edc69..0000000 --- a/tmp/en-US/xml/Common_Content/Revision_History.xml +++ /dev/null @@ -1,32 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Revision History - - - - 3.0-0 - Mon Mar 12 2012 - - Jeff - Fearn - jfearn@redhat.com - - - - Publican 3.0 - - - - - - - - - - - - diff --git a/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml b/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml deleted file mode 100644 index 7043c32..0000000 --- a/tmp/en-US/xml/Conventions_for_Writers_and_Editors.xml +++ /dev/null @@ -1,63 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - - Writing Style Guide - - - Recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. - - - - - - - - - - - - - - Usage Dictionary - - - The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml/Cross_references.xml b/tmp/en-US/xml/Cross_references.xml deleted file mode 100644 index 5db1fa9..0000000 --- a/tmp/en-US/xml/Cross_references.xml +++ /dev/null @@ -1,55 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Using Cross-references Effectively - - This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. Formatting is not described in this section. - - - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. - -
- The Additional Information Test - - Is the cross-reference pointing to vital information or additional information? - - - A cross-reference should always point to additional information, not to core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure, provide a link to the appendix. - - -
- -
- The Repeatability Test - - Must the information be repeated? - - - 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. - - - Cross-referencing is a good servant but a poor master. Content still rules! - - -
- - - diff --git a/tmp/en-US/xml/D.xml b/tmp/en-US/xml/D.xml deleted file mode 100644 index c455413..0000000 --- a/tmp/en-US/xml/D.xml +++ /dev/null @@ -1,340 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - D - - - daisy chain - - - n. A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. - - - v. To connect devices in a daisy chain pattern. - - - - - - - dash - - - In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. - - - - - - - data center, datacenter - - - n. Use the two-word form unless referring to a product name or other proper noun where the one-word form is used. - - - Marketing Publications Exception - - In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used. - - - - - - - - - data mirroring - - - The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information that is stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a different location. - - - - - - - data sheet, datasheet - - - n. Use the two-word form. - - - Marketing Publications Exception - - In marketing publications, the one-word form is recommended. - - - - - - - - - data source - - - n. Use the two-word form unless referring to a proper noun, argument, variable, or other case where the one-word form is required. - - - - - - - data store, datastore - - - n. Use the two-word form. - - - Marketing Publications Exception - - In marketing publications, the one-word form is recommended. - - - - - - - - - data type - - - n. Do not use "datatype" or "data-type" unless they are variable names or some other literal value. - - - - - - - debug - - - To find and remove errors (bugs) from a program or design. - - - - - - - denial of service (DoS) - - - Correct. Do not use "denial-of-service" or "Denial of Service." - - - - - - - desktop - - - Correct. Do not use "desk top" or "desk-top." - - - - - - - device - - - Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer. - - - Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. - - - - - - - DevOps - - - n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps can also refer to the engineers and developers who work within these modern IT organizations. - - - - - - - dialog box - - - See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. - - - - - - - different - - - Use "different from" rather than "different than" when the next part of the sentence is a noun or pronoun (that is, two things are being compared). For example: "Form 123 is different from Form 124." - - - - - - - digital transformation - - - Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. - - - - - - Disk Druid - - - Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. - - - - - - - disk, disc - - - Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. - - - - - - - disk label - - - Correct. Do not use "disklabel" or any other variations. - - - - - - - display - - - v. Use only as a transitive verb. For example, write "the system displays a message" or "the message is displayed" (not "the message displays"). - - - - - - - DNS - - - Initialism of Domain Name System (or Service), an internet service that translates domain names into IP addresses. - - - - - - - documentation - - - When referring to the current manual set, use "documentation." For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." - - - - - - - domain name - - - Correct. Do not use "domainname" or "domain-name." - - - A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com. - - - - - - - double-click - - - v. Always write hyphenated. - - - - - - - downstream - - - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." - - - - - - - downtime - - - Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." - - - - - - - download - - - v., n. Do not use "down load" or "down-load." - - - - - - - dual-boot - - - adj. Do not use "dualboot" or "dual boot." - - - - - - - DVD writer - - - Correct. Do not use the colloquial terms "DVD burner" or "CD burner" (use CD writer in the latter case). - - - - - - - - - diff --git a/tmp/en-US/xml/Design.xml b/tmp/en-US/xml/Design.xml deleted file mode 100644 index ae26cd7..0000000 --- a/tmp/en-US/xml/Design.xml +++ /dev/null @@ -1,1024 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Design - -
- Heading Styles - - This section covers various aspects of heading styles and design. If your company or organization has specific requirements in this regard, follow those requirements first. - - - Capitalization - - The standard for all Red Hat technical documentation is title case for all headings and titles. Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - - - - - Use sentence case for captions, legends, diagram labels, and table column headers. They are not classified as titles. - - - Marketing and Brand Capitalization Guide - - The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. - - - - - Punctuation - - Be frugal with punctuation. In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. Do not use terminating periods. - - - - - Avoid Imperative Mood - - Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". - - - - - See the IBM Style Guide for more information. - - - - Gerunds should be avoided elsewhere. See . - - - - - File Names, Commands, and Related Terms - - When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. - - - - -
-
- Documenting Fonts - - The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. - - -
-
- Documenting the User Interface - - In all cases, see the IBM Style Guide for initial guidance. The following sections highlight exceptions or cases that might otherwise cause confusion. - -
- GUI Elements, Punctuation, and Symbols - - When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. - - - For example, for a button labeled Save As..., do not include the ellipsis in the documentation. - - - In most cases, do not include the object type in instructions. For example, rather than "Click the Save button," write "Click Save." - - - In some cases it is preferred practice to include the object type for the sake of clarity. Consider the following: - - - Preferred Style for Documenting Symbols and Other Special Characters - - Click the + sign. - - - Click the ^ symbol. - - - - - If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. Use this approach for icons, especially when they have no tooltip or other help text. - - - Preferred Style for Documenting Icons - - Click the Upload ( - - - - - - - ) icon to upload the files to the server. - - - - - See the UI elements chapter in the IBM Style Guide for more information. - -
- Navigating Through Multiple GUI Options - - Use "Navigate to" when moving through multiple GUI 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. - - - From example, "From the OpenShift web console, navigate to Monitoring → Alerting." - - -
- -
-
- Starting Applications from the Desktop - - This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. - - - RHEL 8 uses the following approach to starting applications from the desktop. In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. - - - The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: - - - Preferred Approach to Starting Applications from the Desktop - - To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. - - - - -
-
- Documenting Command Terminology and Syntax - - Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here. - - - When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses. Never use "flag" when referring to command-line options in POSIX, even though Microsoft often uses the term "flag" when referring to single-character options in Microsoft Windows. - - - The following extract from info libc is of particular interest here: - -
- - "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on. - - - See info libc argument syntax for the full discussion. - - -
- - See info bash and the IBM Style Guide for further guidance. - - - The following examples are intended to highlight correct usage. - - - Cloning a Git Repository - - -$ git clone [username@]hostname:/repository_filename [directory] - - - - - - In , the entire command consists of the following components: - - - - The prompt ($) - - - Indicates that a normal user can run the command, as compared to the root user, which would be indicated by the number sign (#). - - - - - - - The command (git clone) - - - The actual command to run, without any optional or replaceable values. It must be typed as-is. - - - - - - - Source options [username@]hostname:/repository_filename) - - - The optional user name, indicated by brackets ([]), followed by the host name and path to the repository. All aspects of this component must be replaced with valid values. - - - - - - - Target options [directory] - - - The optional directory into which the repository will be cloned. It must be replaced with a valid value, or be omitted. - - - - - - - - - Securely Copying a File Between Hosts - -$ scp filename [username@]hostname:/directory - - - - In , the entire command consists of the following components: - - - - The command prompt ($) - - - - - - - - - - The command (scp) - - - - - - - - - - Source options (filename) - - - The file name to copy. It must be replaced with a valid value. - - - - - - - Target options ([username@]hostname:/directory) - - - The optional user name, indicated by brackets ([]), followed by the host name and path to the target directory. All aspects of this component must be replaced with valid values. - - - - - - - - - - In most cases, avoid using the and options on most commands, especially when logged in as the root 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: - - -[root@serverc pam.d]# rm -f system-auth password-auth -[root@serverc ~]# yum install -y new-package - - - In these examples, omit the and options, respectively. - - - In some cases, such as in Ansible Playbooks or other automation scripts, it might be necessary to use these options. - - - -
- Documenting Multiple or Long Commands - - 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, include the commands on consecutive lines: - - - Documenting Multiple Commands - -$ cd Documents -$ vi myFile.txt - - - - - If the commands are long, complex, or wrap over multiple lines, two design options are available. - - - - - Use line continuation characters and the associated PS2 prompts. If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit. - - - - - - Use neither line continuation characters nor the associated PS2 prompts. - - - - - - - - Do not mix these two styles. Maintain the same style throughout your document or book. - - - - - You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. You can use this option for either of these two designs. - - - Wrapping Long Commands with Continuation Characters - - This example uses both continuation characters and PS2 prompts. These indicators are always used together. - - -# tar --selinux -czvf config_files.tar.gz /etc/katello \ -> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ -> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ -> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ -> /root/ssl–build /var/www/html/pub/* /var/lib/katello - - - - Wrapping Long Commands Without Continuation Characters - - This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. - - -# cd /var/lib/katello - -# myCommand --option funky --color=true - --config_file=<replaceable>/home/user/config.conf</replaceable> - --output_file=<replaceable>/home/user/output.txt</replaceable> - - - -
-
- Referring to Replaceable Paths - - To refer to a path that users need to replace with something that is specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. Use a leading slash if the absolute path is required. - - - Referring to Replaceable Paths on Linux Systems - - "Mount the ISO file in <filename><replaceable>/path/to/iso/file</replaceable></filename>." - - - - - Remember to use the appropriate syntax for the system that you are documenting or describing. - - - Referring to Replaceable Paths on Microsoft Windows Systems - - "Mount the ISO file in <filename><replaceable>C:\path\to\iso\file</replaceable></filename>." - - - - - If you are referring to a different object class or type with different delimiters, use the appropriate delimiters. For example: - - - A PATH variable for Bash might appear as <replaceable>/usr/bin:/usr/local/bin</replaceable>. - - - A package path in Lua might appear as <replaceable>local.share.lua</replaceable>. - - -
- -
-
- Using Escalated Privileges Correctly - - - This section is aimed primarily at Red Hat Training course material, but the principles and guidelines apply equally in any environment. - - - - - The term escalated privileges 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. - - - Classroom Exceptions - - Although security is important, it is more important that classroom security does not unnecessarily distract from the immediate topic that is being taught. - - - -
- General Recommendations - - - These are recommendations, not rules. As in most matters, consistency is important. Do not swap between different approaches without reason. Choose which approach works best for your situation and use it consistently. - - - - - - - In all cases, use the minimum required privilege level to achieve the task. - - - - - - In exercises, use sudo and sudo -i and set it up to work throughout all relevant systems in the classroom. Do not use su - without good cause. - - - - - - When a scattered minority of privileged commands occur in a mostly unprivileged exercise, use sudo on a per-command basis. - - - - - - When the exercise is majority privileged, or has many privileged commands, use sudo -i, either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. - - - - - - In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. See for information about command prompts. - - - - - - -
-
- Exceptions - - Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers, and so on. For these courses, use the required variation for the topic that is being taught. - -
- Ansible Courses - - - - Ansible courses typically use a devops user with passwordless sudo access (devops ALL=(ALL) NOPASSWD: ALL) on managed nodes to enable the use of become without a become password as root to do anything. - - - - - - As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. - - - - - - If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. - - - - - - -
- -
- -
-
- Describing How to View and Edit Files - - To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. - - - For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. - - - If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. - - - You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. - - - my-script -> # The first line of text -> # The second line -> # Start adding variables after this line -> EOF]]> - - In some cases, it is necessary to indicate which tool to use to view a file, especially for log files and other long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl. - - -
-
- Using Host and User Names Correctly - - Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. - - - - All names are lowercase. Do not use white space in any part of the name. - - - - - - - Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. - - - - Do not use valid, public IP addresses in any examples. - - - - - - - - As much as possible, use user, username, root, admin, or similar names to identify classes of users. - - - Use these generic names when you refer to users outside a case study. It helps students to identify which part of a command to replace, by establishing a consistent format for names of users and system items. For example: - - -[root@fedora ~]# setfacl -m u:user1:rw /project/file1 - - The following list provides further alternatives: - - - - - operator1 to operator9 - - - - - - developer1 to developer9 - - - - - - architect1 to architect9 - - - - - - - - - -
- Using Extended User and Group Names - - Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. - - - Using Realistic User Names - - When you are writing a detailed case study, such as training exercises, reviews, and similar material, use realistic names. These names should not be real people. In other words, do not use the name of an employee, a well-known person, or your neighbor. - - - - - For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. - - - Choosing a Realistic Name - - Consider the following points when choosing a realistic name: - Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. - - - - - - - - - In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. - - - - - - Do not use copyrighted fictional characters in examples, and do not use real people. - - - - - - 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. - - - - - - - Sourcing Realistic Names - - You can use any of the following name generators to create realistic names for users: - - - - - - - https://uinames.com/ - - - - - - http://listofrandomnames.com/ - - - - - - http://www.behindthename.com/random/ - - - - - - http://random-name-generator.info/ - - - - - - - Group Names - - Use any lowercase name that is a logical extension of the accepted user names, without the numerical suffix. For example, architects, developers, operators. - - - - -
- -
- -
-
- Documenting Currencies - - Use local currency symbols wherever possible. If symbol clash occurs (USD versus AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. - - - - Do not provide currency conversions. - - - - -
-
- Using Abbreviations, Acronyms, and Initialisms Correctly - - This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. - - - Abbreviations - - An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated," respectively. Read them as the word for which they are an abbreviation. - - - - - Acronyms - - What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. - - - - - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). - - - Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. - - - To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. - - - Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. - - - Initialisms - - An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. - - - - - Consider pronunciation when using articles. See for more information. - - -
-
- Using Company, Product, and Brand Names Correctly - - Various restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. - - - - In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use." - - - - - - - Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. - - - - - - Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. - - - - - - Do not include "Inc." when referring to Red Hat except in legal documents. - - - - - - Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. - - - If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. - - - - - - Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: - - - - - Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. - - - - - - The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 - - - - - - - For other markup languages, use the equivalent non-breaking space character. - - - - - - Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." - - - - - - Do not use non-breaking spaces with other companies' product names. - - - - - - Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." - - - - In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. - - - - - - - - -
-
- Using Version Numbers Correctly - - The preferred format for product names includes only the major version number. For example: - - - - Red Hat Enterprise Linux 8 - - - - - - JBoss Enterprise Application Platform 3 - - - - - - - - - When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version. - - - Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example: - - - - Red Hat Enterprise Linux 5.2 was released on October 12, 2010. - - - - - - <Application name> was first included in JBoss Enterprise Application Platform 3.2. - - - - - - - - - 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. - - - Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. - - - - This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. - - - - -
-
- Using Admonitions - - To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning 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 in mind these considerations if using admonitions: - - - - Keep the statements as brief and to the point as possible. - - - - - - Use admonitions sparingly so that they do not lose their effectiveness. - - - - - - Use a Note admonition to bring additional information to the user's attention. - - - - - - Use an Important 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 a Warning 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. - - - - - - - - -
-
- Making Recommendations - - When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". Recommendations can include best practices, recommended practices, and product-specific suggestions. See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. - - - (incorrect) - - "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project." - - - "It is recommended to generate a service account for each microservice in your project." - - - - - (correct) - - "Although the attack surface is reduced to the same-project traffic, Red Hat recommends creating multiple service accounts within a project." - - - "Red Hat recommends that you generate a service account for each microservice in your project." - - - -
-
- Citing Other Works - - Referencing Other Books - - When referencing another book, either internal or external to Red Hat, use the following format: - - - - - - -Book Title by First name Surname; Publisher. - - - For example, Maximum RPM by - - Edward - Bailey - - - ; Red Hat Press. - - - Referencing Other Internet Sites - - When referencing another internet site, use the following guidelines: - - - - - - - Do not link words within the body text. That is, do not use structures such as "Go here for more information," where "here" is a link. - - - - - - Short URLs, such as http://partner.redhat.com, are OK to use in body text at your discretion. - - - - - - If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species - http://world-database-of-everything.com/en/classifcation_of_species/mammals.html - - page for more information. - - - - - - -
- - - diff --git a/tmp/en-US/xml/E.xml b/tmp/en-US/xml/E.xml deleted file mode 100644 index 669254e..0000000 --- a/tmp/en-US/xml/E.xml +++ /dev/null @@ -1,193 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - E - - - e-book, e-business, e-commerce, e-learning, email - - - Refer to the primary reference for the type of copy you are creating, either AP or IBM. - - - - - - - e.g. - - - Red Hat technical documentation always expands these abbreviations. Write out "for example". - - - - - - - earlier - - - Use to refer to earlier releases of products. Do not use "older" or related terms. See also . - - - - - - - Emacs - - - If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." - - - - - - - emdash - - - Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See for more information. - - - - - - - enter - - - When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. - - - When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." - - - When typing information into a single-field dialog box, "enter" means "type and press Enter." An example is "enter the license number." For multi-field dialog boxes, see "type." - - - - - - - environment - - - The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, running a program in a UNIX environment means running a program on a computer that has the UNIX operating system. - - - One ingredient of an environment, therefore, is the operating system. But operating systems include many different parameters. For example, in some operating systems, you can choose your command prompt or a default command path. All these parameters together constitute the environment. - - - Another term for environment in this sense is platform. - - - - - - - EOL - - - adj. Initialism for "end-of-line" - - - n. Initialism for "end of line" - - - Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. - - - - - - - essentially - - - Do not use. - - - - - - - Ethernet - - - n. Uppercase "E" at all times. - - - - - - - event - - - An action or occurrence that is detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. - - - - - - - exclamation points (!) - - - Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. - - - - - - - Exec-Shield - - - Exec-Shield is a security-enhancing modification to the Linux kernel that makes large parts of specially marked programs including their stack not executable. - - - - - - - execute - - - Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. - - - - - - - Exif - - - Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." - - - - - - - extranet - - - Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. - - - Capitalize only at the beginning of a sentence. - - - - - - - - - diff --git a/tmp/en-US/xml/Easily_Confused_Words.xml b/tmp/en-US/xml/Easily_Confused_Words.xml deleted file mode 100644 index 08e2523..0000000 --- a/tmp/en-US/xml/Easily_Confused_Words.xml +++ /dev/null @@ -1,92 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Easily Confused Words - - This section identifies some easily confused words and how to choose the correct term for your situation. - - - Affect and Effect - - Each of these words can be used as a verb or a noun, but they are not always interchangeable. - - - - - - affect - - - n. Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you. - - - v. Means to have an influence on something, or to cause something to change. - - - - - - - effect - - - n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." - - - v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." - - - The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." - - - - - - - - - Assure, Ensure, and Insure - - These are relatively easy to get right, but here are some quick definitions. - - - - - - assure - - - v. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." - - - - - - - ensure - - - v. Means to make sure of something, to be certain that something exists or some condition has been met. - - - - - - - insure - - - v. Relates to monetary insurance. - - - - - - - - -
- diff --git a/tmp/en-US/xml/F.xml b/tmp/en-US/xml/F.xml deleted file mode 100644 index 4fec021..0000000 --- a/tmp/en-US/xml/F.xml +++ /dev/null @@ -1,334 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - F - - - fail back, failback - - - v. Use the 2-word form. - - - n. Use the 1-word form. - - - No hyphenated form is currently recognized. - - - - - - - fail over, failover - - - v. Use the 2-word form. - - - n., adj. Use the 1-word form. - - - No hyphenated form is currently recognized. - - - - - - - FAQ - - - When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an Q") not "a FAQ." The plural form is "FAQs." - - - - - - - fault tolerance (n.), fault-tolerant (adj.) - - - The ability of a system to respond gracefully to an unexpected hardware or software failure. Fault tolerance has many levels, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so that if one fails, then the other can take over. - - - - - - - Fedora™ Project - - - Correct. - - - - - - - fiber - - - Correct. Despite the alternative spelling used in Fibre Channel, "fiber" is the correct form to use in all other cases. - - - - - - - Fibre Channel - - - A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FAL). - - - FAL was designed for new mass storage devices and other peripheral devices that require high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100 MBps. FAL is compatible with, and is expected eventually to replace, SCSI for high-performance storage systems. - - - - - - - file extensions (general usage) - - - See File names, file types, and directory names in the IBM Style Guide. - - - - - - - file mode, file name, file system, file type - - - n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. - - - adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." - - - - - - - FireWire - - - Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. - - - - - - - firmware - - - n. Do not use "firm ware" or "firm-ware." - - - Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. - - - - - - - floating point - - - Correct. Do not hyphenate. - - - - - - - floppy disk - - - Do not use. Use "diskette," and also state the size of the diskette, such as "3.5 in. diskette." - - - - - - - floppy drive - - - Do not use. Use "diskette drive." - - - - - - - follow - - - v. Refers to the use of the () option for various commands, such as tail, so that output is appended as the file grows. - - - - - - - following - - - When introducing a list or a procedure, use "following" with a noun. Instead of "Complete the following", use "Complete the following steps". - - - - - - - foreground - - - - - In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. - - - - - - On display screens, the foreground consists of the characters and pictures that appear on the screen. The background is the uniform canvas behind the characters and pictures. - - - - - - - - - - - fortnight - - - A period of two weeks (14 nights). Avoid; this term is not common in American English and might also be unfamiliar to non-native speakers. - - - - - - - FORTRAN - - - Correct. Do not use "Fortran." - - - - - - - forward - - - Correct. Avoid using "forwards." - - - - - - - forwards compatible - - - Do not use. Instead, use "compatible with later versions." See also . - - - - - - - FQDN - - - A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels. - - https://en.wikipedia.org/wiki/Fully_qualified_domain_name - - - - - For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. - - - An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. - - - - - - - frictionless - - - Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also . - - - - - - - front end, front-end - - - n. Two words. For example, "PRCS is a front end for a version control toolset." - - - adj. Hyphenate. For example, "This chapter explains how to use the front-end API functions." - - - Do not use "frontend" as a noun or adjective. - - - See also . - - - - - - - FTP - - - Use all caps when referring to the protocol. Use lowercase when referring to the command-line program. - - - - - - - futexes - - - Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. - - - - - - - fuzzy - - - Correct only when referring to fuzzy searches. See for details and examples. - - - - - - - - - diff --git a/tmp/en-US/xml/Feedback.xml b/tmp/en-US/xml/Feedback.xml deleted file mode 100644 index b1da4c2..0000000 --- a/tmp/en-US/xml/Feedback.xml +++ /dev/null @@ -1,13 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- We Need Feedback - - Raise an issue at with suggestions for improvements, requests for additions, recommendations, and any other updates. - - -
- diff --git a/tmp/en-US/xml/G.xml b/tmp/en-US/xml/G.xml deleted file mode 100644 index 96f0a6c..0000000 --- a/tmp/en-US/xml/G.xml +++ /dev/null @@ -1,268 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - G - - - g++, G++ - - - When referring to the command, use g++. When referring to the program, use G++. - - - - - - - gas, GAS - - - When referring to the command, use gas. When referring to the program, use GAS. - - - - - - - GB - - - Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. - - - AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." - - - IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file." - - - - - - - GbE - - - Correct. Approved abbreviation of Gigabit Ethernet. Do not use GigE or any other variations. Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - Gbps - - - Abbreviation of Gigabits per second, a data transfer speed measurement for high-speed networks such as Gigabit Ethernet. When used to describe data transfer rates, a gigabit equals 1,000,000,000 bits. Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - gcc, GCC - - - When referring to the command, use gcc. When referring to the program, use GCC. - - - - - - - gcj, GCJ - - - When referring to the command, use gcj. When referring to the program, use GCJ. - - - - - - - gdb, GDB - - - When referring to the command, use gdb. When referring to the program, use GDB. - - - - - - - GDBTK - - - Do not use. Use "Insight" instead. GDBTK is an obsolete name for the GNU debugger. - - - - - - - GEO - - - Do not use. Use "region" or "geographical location" according to your needs. - - - - - - - GFS, GFS2 - - - As of Red Hat Enterprise Linux 6, it is known as the Resilient Storage Add-On. Ensure that you use the correct term. - - - - - - - GID - - - Acronym for Group ID. Do not use "gid." - - - - - - - GigE - - - See . - - - - - - - gigabyte - - - 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - GIMP - - - Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp." - - - - - - - GNOME - - - Correct. Do not use "gnome," "Gnome," or other variants. See also . - - - - - - - GNOME Classic - - - Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). - - - - - - - GNU - - - Recursive initialism for "GNU's Not UNIX." Do not use "Gnu" or "gnu." - - - - - - - GNUPro - - - When referring to the Red Hat product, use GNUPro. - - - - - - - got - - - Do not use. - - - - - - - GPL - - - Initialism for General Public License. Do not use "Gpl" or "gpl." - - - - - - - grayscale - - - n. Correct. Do not use "gray-scale" or "gray scale." Only the noun form is currently recognized. - - - - - - - GRUB - - - Correct. All caps. Do not use "Grub." - - - - - - - GTK+ - - - Initialism for GIMP Tool Kit. Do not use "GTK," "Gtk," or "gtk." - - - - - - - guest operating system - - - Refers to the operating system that is installed in a virtual machine. Do not use "guest" by itself because it is ambiguous. - - - - - - - - - diff --git a/tmp/en-US/xml/Grammar.xml b/tmp/en-US/xml/Grammar.xml deleted file mode 100644 index 1439247..0000000 --- a/tmp/en-US/xml/Grammar.xml +++ /dev/null @@ -1,621 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Grammar - - This section contains information on a few common grammar topics. For subjects not covered here, consult The Chicago Manual of Style, 17th Edition. - -
- Active Voice - - Use the active voice ("Type ... to start Linuxconf.") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. - - - This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. - - - For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than - - - "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence. - - - You can also use the passive voice to front-load important keywords in key areas of your content, such as the title, heading, or at the beginning of a paragraph or sentence. You need to make these decisions on a case-by-case basis, weighing the importance of front-loading keywords against content that is readable (that is, not awkward sounding). Consider the following two examples: - - - Active Voice - - "Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization." - - - - - Passive Voice - - "Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion." - - - - -
-
- Agreement - - In grammar, agreement occurs when specific parts of a sentence are coordinated; that is, they agree in number and gender. - - - There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here. Pronoun-antecedent agreement can be a little more problematic, so... - -
- Pronoun-antecedent agreement - - A pronoun is a word that is used in place of a noun (for example, I, he, she, it). An antecedent is a word or phrase to which the pronoun refers. - - - When you are comfortable with subject-verb agreement, pronoun-antecedent agreement often follows as a matter of course. - - - The following is an annotated roundup of pronoun-antecedent rules: - - - Singular and Plural Nouns - - A singular pronoun refers to a singular antecedent; a plural pronoun refers to a plural antecedent. For example: - - - - - - - The CD spins in its caddy. (The singular third-person pronoun "its" refers to the singular antecedent "CD".) - - - - - - The developers checked their work. (The plural third-person pronoun "their" refers to the plural antecedent "developers".) - - - - - - - Collective Nouns - - When collective nouns are used as antecedents, use singular or plural pronouns, depending on the sentence's meaning. For example: - - - - - - - Microsoft seems second to none in its marketing skills. (The collective noun "Microsoft" takes the singular pronoun "its" because the collective noun refers to the group as a whole.) - - - - - - The developers were asked for their preferences. (The collective noun "developers" takes the plural pronoun "their" because the reference is to the individuals of the group.) - - - - - - -
- -
-
- Using Who, Whom, That, and Which Correctly - - Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns." - - - Use the following as guidelines: - - - - Who - - - Relative pronoun when persons are the subject. - - - - - - - Whom - - - Relative pronoun when persons are not the subject. - - - - - - - Which - - - Relative pronoun for things. - - - - - - - That - - - Restrictive pronoun for things. - - - - - - - - - Examples: - - - - - The jewel case, which once held the CD, was broken recently. - - - - - - The CD that I received for my birthday is defective. - - - - - - Edward C. Bailey, who wrote "Maximum RPM,"... - - - - - - The company that published "Maximum RPM" was... - - - - - - This book belongs to whomever purchased it last week. - - - - - - Who ate all the cereal? - - - - - - To whom should I address the letter? - - - - - - The desktop that was designed by Earl is not called GNOME. - - - - - - The GNOME developers who worked on the desktop are... - - - - - - The GNOME developers to whom they owe gratitude are... - - - - - - - - To help you choose between who and whom, substitute the person about whom you are speaking with he, she, him, or her. - - - - - If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" - - - - - - If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" - - - - - - - - -
-
- Sentence Structure - - A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). - - - Consider the following points when constructing sentences: - - - Sentence Length - - Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: - - - - - The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. - - - Run-on Sentences - - Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: - - - - - - - Separate independent clauses with a period. Doing so will form two sentences out of one. - - - - - - Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. - - - - - - Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." - - - - - - Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error." - - - - - - - - - - - - - Example - Improvement - - - - - - - The CDs both of which belonged to the developers were in the test lab. - The CDs, both of which belonged to the developers, were in the test lab. - - - - To access your programs click the Start button. - To access your programs, click Start. - - - - The CDs, both of which belonged to the developers, were in the test lab, because they were the only available CDs for the new release, the developers were anxious about keeping them clean. (This sentence exhibits a comma splice which is also often regarded as a run-on sentence.) - The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean. - - - - - - - -
- - Sentence Fragments - - A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. - - - - - - Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. - - - - - Telegraphic Style - - Extreme cases of word economy can result in a telegraphic style, omitting words that can clarify the meaning of a sentence, such as articles, prepositions, and verbs used with gerunds. - - - - - - - - - - - Example - Improvement - - - - - - - Click button to start. - Click Initiate to start the process. - - - - - - - -
- - This problem is often encountered in the Revision History. It is important that wording in the Revision History is clear for translators and customers to understand. - - - - - - - - - Example - Improvement - - - - - - - Minor revision - missing element items - Minor revision - added missing element items - - - - Some further work required to avoid 404s at lower levels of the SDK. - Some further work required to avoid 404 errors at lower levels of the SDK. - - - - - - - -
- - "That" in Clauses - - Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, - - - - - - - - - - - Example - Improvement - - - - - - - Verify your directory service is working. - Verify that your directory service is working. - - - - - - - -
- - Verbosity - - Avoid unnecessary words. Keep it succinct. - - - - - - - - - - - Example - Improvement - - - - - - - The individual member of the social community often receives information via visual, symbolic channels. - People read. (Translation by Richard Feynman.) - - - - Perform the installation of the product. - Install the product. - - - - - - - -
- - Word Order - - When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify. - - - - - - - - - - - Example - Improvement - - - - - - - To update the address lists might be your primary concern. - Your primary concern might be to update the address lists. - - - - - - - -
- -
- -
- Contractions and Abbreviations - - Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. - - - Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. - - -
- -
- Hyphenation - - There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. - - - Hyphenate for Clarity - - Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. - - - - - - Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof." - www.apstylebook.com - - - - - - - Hyphenate Complex Adjectives - - Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. - - - - - - Do not hyphenate "open source," even when used as a complex adjective. - - - Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. - - - - - Hyphenate Consecutive Vowel Sounds - - Hyphenate words where the prefix ends in a vowel and the word that follows begins with the same vowel. For example, semi-independent, pre-emptive. - - - - - - Exceptions to this rule include cooperate and coordinate. - - - - - Hyphenate Mixed Capitalization - - Hyphenate when the word that follows a prefix is capitalized. For example, un-American, non-British. - - - - - Hyphenate Double Prefixes - - Hyphenate when the word has double prefixes. For example, sub-subparagraph, re-sublet. - - - - -
-
- Gender References - - Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. - - -
-
- Tense - - Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. - - - Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. - - - Report an issue - - -
- - - diff --git a/tmp/en-US/xml/H.xml b/tmp/en-US/xml/H.xml deleted file mode 100644 index 828bc54..0000000 --- a/tmp/en-US/xml/H.xml +++ /dev/null @@ -1,299 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - H - - - hard code, hard-coded - - - v. Two words. - - - adj. Hyphenate. - - - Do not use the one-word form. No nominal form is currently recognized. - - - - - - - hard copy - - - Do not use. Use "printed". Under review - - - - - - - - hard disk - - - n. Correct. Do not use "harddisk" or "hard-disk." - - - - - - - hard disk drive - - - n. Correct. Do not use "harddrive" or "hard-drive." - - - - - - - he/she - - - Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. - - - - - - - help desk - - - Typically two words, but use the term accepted by your organization. - - - - - - - healthcare - - - Under review. Need context and example. - - - - - - - - health check - - - n. Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. - - - This term is only capitalized when part of a product name, for example: - - - - Red Hat Enterprise Linux Server Health Check - - - - - - JBoss Middleware Health Check - - - - - - - - - Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." - - - - - - - hertz - - - n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz." - - - - - - - high-availability, high availability - - - adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." - - - n. Two words. For example, "Support is available 24x7 to help maintain high availability." - - - - - - - high-performance computing (HPC) - - - n. Use standard hyphenation guidelines to maintain clarity. - - - - - - - homepage - - - n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - - - - - - - host group - - - n. Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. - - - - - - - host name - - - n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. - - - - - - - hot add - - - v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add." - - - - - - - hotline - - - n. One word, lowercase. Capitalize only at the beginning of a sentence. Under review. Need context and example. - - - - - - - - hot plug - - - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug." - - - - - - - hot swap - - - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap." - - - - - - - hover help - - - See . - - - - - - - HP ProLiant - - - Correct. Do not use any other variations. - - - - - - - HTML - - - When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." - - - - - - - huge-page, huge page - - - adj. Hyphenate. Normal hyphenation rules apply. - - - n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization that is used in that interface. - - - - - - - hybrid IT - - - The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . - - - - - - - Hyper-Threading - - - n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use "hyperthreading" or "hyper-threading". If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. - - - - - - - hypervisor - - - n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser." - - - - - - - - - diff --git a/tmp/en-US/xml/I.xml b/tmp/en-US/xml/I.xml deleted file mode 100644 index 40dca43..0000000 --- a/tmp/en-US/xml/I.xml +++ /dev/null @@ -1,369 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - I - - - IA64 or ia64 - - - Do not use. Always use the term Itanium instead. These terms can be used in file names because they are not visible in the content. - - - - - - - IaaS - - - Correct. This is the correct abbreviation for "Infrastructure-as-a-Service." See also . - - - - - - - IBM Z - - - IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. - - - - - - - i.e. - - - Do not use a Latin abbreviation. Instead, write out "that is". - - - - - - - illegal - - - Illegal means "prohibited by law," not "incorrect" or "not permitted." Use "invalid" or a related word. - - - - - - - matrixes - - - Correct. This is the correct plural form for US English spelling. Do not use "indices." - - - - - - - InfiniBand - - - InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. - - - "Open InfiniBand" is deprecated and should not be used. - - - - - - - inline - - - adj. Always one word. Do not hyphenate. - - - - - - - insecure - - - adj. Correct. Do not use "nonsecure" or "non-secure." - - - - - - - installation program - - - n. Correct. Do not use "installer" unless it is a formal part of the product or technology. - - - - - - - Intel 64 - - - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. - - - The correct term for Intel's implementation of this architecture is "Intel® 64." Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - - - See also . - - - - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - - - For more information about Intel® trademarks, see and . - - - - - - - - - Intel® CoreTM - - - Correct. Example would be good. - - - - - - - - Intel Tolapai / Intel® EP80579 Integrated Processor - - - Do not use the code-name, "Tolapai." Use the official brand name "Intel® EP80579 Integrated Processor." - - - - - - - Intel Virtualization Technology (Intel VT) - - - Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." - - - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." - - - - - - - Intel® Xeon® - - - Correct. Example? Reference? - - - - - - - - interesting - - - Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note...", consider using a "Note" admonition. - - - - - - - internet - - - n. Always lowercase except in some specific exceptions, for example . - - - - - - - Internet of Things (IoT) - - - Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. - - - The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. - http://en.wikipedia.org/wiki/Internet_of_things - - - - - - - - - Intranet, intranet - - - See the "Word usage" appendix of the IBM Style Guide for guidance. - - - - - - - I/O - - - Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. - - - The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. - - - - - - - IOPS - - - Correct. All caps. Stands for input/output operations per second. - - - - - - - IP - - - Correct. Stands for Internet Protocol. Capitalize both letters. - - - - - - - IP Masquerade - - - A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. - - - Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. - - - - - - - IPsec - - - IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec." - - - - - - - IP switching - - - A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. - - - - - - - ISV - - - Short for "independent software vendor", a company that produces software. - - - - - - - IT/I.T. - - - Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." - - - - - - - Itanium - - - A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. - - - In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. - - - Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. - - - Do not use the term "IA64". It can be used in file names because they are not printed in the content. - - - - - - - Itanium 2 - - - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." - - - - - - - - - diff --git a/tmp/en-US/xml/J.xml b/tmp/en-US/xml/J.xml deleted file mode 100644 index 9dc1106..0000000 --- a/tmp/en-US/xml/J.xml +++ /dev/null @@ -1,72 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - J - - - JavaScript - - - "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." - - - - - - - JBoss Community - - - No longer referred to as "JBoss.org." Use when referring to the community of users and contributors. - - - - - - - job - - - A task that a computer system performs. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. - - - - - - - jsvc - - - The Apache Commons Daemon jsvc is a set of libraries and applications to run Java applications on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. - - - - - - - just - - - Use sparingly. In the phrase, "Just open the file...", omit the word "just." - - - - - - - JVM - - - Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine," or "Java VM," or only the noun itself, "virtual machine." You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)." Do not use Jvm or jvm. - - - - - - - - - diff --git a/tmp/en-US/xml/K.xml b/tmp/en-US/xml/K.xml deleted file mode 100644 index 7c62fa7..0000000 --- a/tmp/en-US/xml/K.xml +++ /dev/null @@ -1,170 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - K - - - KB, kB - - - See the IBM Style Guide for the correct abbreviation to use for specific use cases. - - - - - - - kbps, KBps, kBps - - - kbps is the accepted abbreviation for kilobit per second, or 1000 bits per second. - - - KBps and kBps are accepted abbreviations for kilobyte per second, or 1000 bytes per second. - - - - - - - kerberize - - - Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence. - - - - - - - kernel - - - The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. - - - - - - - Kernel-based Virtual Machine (KVM) - - - Spell out on first use, capitalized. Use the initialism (KVM) thereafter. It is an industry standard, and a proper noun. - - - - - - - kernel panic - - - Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. - - - - - - - kernel space, kernel-space - - - n. Two words when used as a noun. - - - adj. Hyphenate as an adjective, "kernel-space." Do not use "kernelspace." - - - - - - - keyboard key - - - When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X." When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S." - - - See also . - - - - - - - key ring - - - n. Use the two-word form as a noun. For example, "add your new key to the key ring." - - - adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server." - - - Only use the one-word form, "keyring," if it is the actual name of a command, package, or other proper noun. - - - - - - - keytab - - - n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . - - - - - - - key-value - - - adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair." Do not use "key/value" or any other variations. - - - - - - - Kickstart - - - adj. A network installation system for some Linux distributions. - http://en.wikipedia.org/wiki/Kickstart (Linux) - - - - - - - - - kill - - - If terminating a UNIX process, use "kill." For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate." For example, "To terminate the process, press Q." - - - - - - - knowledge base - - - Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase." In this case, use the one-word form and capitalize the "K." Do not capitalize the "b." - - - - - - - - - diff --git a/tmp/en-US/xml/L.xml b/tmp/en-US/xml/L.xml deleted file mode 100644 index f69c867..0000000 --- a/tmp/en-US/xml/L.xml +++ /dev/null @@ -1,265 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - L - - - LAN - - - Correct. This is an acronym for Local Area Network. Do not use Lan or lan. - - - - - - - latency - - - - - In general, the period of time that one component in a system is spinning its wheels waiting for another component. Latency, therefore, is wasted time. For example, in accessing data on a disk, latency is defined as the time it takes to position the proper sector under the read/write head. - - - - - - In networking, the amount of time it takes a packet to travel from source to destination. Together, latency and bandwidth define the speed and capacity of a network. - - - - - - - - - - - later - - - Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also . - - - - - - - leave out - - - Do not use. Use "omit" instead. - - - - - - - left-click - - - v. Write the term hyphenated. Do not use "left click" or "leftclick." - - - - - - - LibreOffice - - - A Linux desktop suite. Do not use "Libre," "Libreoffice," or "Libre Office." - - - See also - - - - - - - license - - - n., v. Use this form for both the noun and the verb. - - - - - - - life cycle, life-cycle, lifecycle - - - n. Two words. Only use the one-word form if it is an established part of a software interface, part of a proper noun, or an external standard. - - - adj. Hyphenate. - - - - - - - Linux - - - Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." - - - Linux is a registered trademark of Linus Torvalds. Use a registered trademark symbol on first use. - - - - - - - load - - - - - To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. - - - - - - v. In programming, "to load" means to move from one storage type to another storage type for use. - - - - - - n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) that the network carries, or the amount of CPU in use at any given time. - - - - - - - - - - - load balancing - - - Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. - - - - - - - logical topology - - - Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. - - - - - - - login, log in - - - Write as one word as an adjective or noun, or as two words as a verb. - - - - - adj., n. One word. For example, "the login credentials". - - - - - - v. Two words. For example, "to log in as root". - - - - - - - - - - - log in to - - - v. Write as three words. For example, "to log in to the system". - - - - - - - lookup, look-up, look up - - - n. Use the one-word form. - - - v. Use the two-word form. - - - adj. Hyphenate when used as a modifier. For example, "a look-up table." - - - - - - - look at - - - Do not use. Use "examine" or "inspect" or some other more precise term instead. - - - - - - - loopback address - - - The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. No hardware is associated with a loopback interface, and it is not physically connected to a network. - - - With a loopback interface, IT professionals can test IP software without concern for broken or corrupted drivers or hardware. - - - - - - - lots of - - - Do not use. Use "many" instead. - - - - - - - LPAR - - - Abbreviation of "logical partitioning", a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. - - - - - - - - - diff --git a/tmp/en-US/xml/Language.xml b/tmp/en-US/xml/Language.xml deleted file mode 100644 index f2b6807..0000000 --- a/tmp/en-US/xml/Language.xml +++ /dev/null @@ -1,1299 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Choosing Appropriate Language - - Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. - - - If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. - - - Red Hat is committed to eliminating use of language that might exclude or offend certain groups of people. This chapter describes some considerations for use of inclusive language. - - - Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. - -
- Avoiding Misleading or Confusing Language - - Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. - - - - best practices - - - This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." - - - See the section for additional information about recommendations in Red Hat documentation. - - - - - - - first come, first served - - - Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. - - - - - - - - -
-
- Identifying and Avoiding Slang - - Examples of slang terms: - - - - administrivia - - - Not a word. Do not use. - - - - - - - anything you like, anything they like - - - This phrase is probably readily understood but should not appear in Red Hat documentation. - - - - - "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." - - - Rephrase to something more suitable, such as "... to register any other kind of plug-in." - - - - - - - - - - - ask (as a noun), make the ask - - - Ask is a verb. Do not use it as a noun. - - - - - - - at this point in time - - - Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. - - - - - - - automagic - - - Also, automagical. Both terms are slang. Do not use. - - - - - - - best-of-breed - - - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. - - - - - - - bleeding edge - - - Do not use. - - - - - - - bottom line - - - Traditionally used in financial contexts; avoid overuse. - - - - - - - bucketize - - - Not a word. Try "categorize" or "organize into logical groups." - - - - - - - center of competency - - - Do not use. - - - - - - - check this site - - - Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. - - - - - - - coopetition - - - Not a word. Do not use. - - - - - - - core competency - - - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." - - - - - - - eat your own dogfood - - - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. - - - - - - - data point - - - Do not use. - - - - - - - dig deeper, delve deeper - - - "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." - - - - - - - double-edged sword, double-bladed sword - - - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. - - - - - - - enterprise-ready - - - Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. - - - - - - - exceed your expectations - - - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." - - - - - - - fib - - - A fib is a "small lie," also known as a "white lie." This sentence appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." - - - - - - - flying by the seat of your pants - - - Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. - - - - - - - frame it up - - - Do not use. - - - - - - - frown upon - - - "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). - - - - - - - fuzzy (search) - - - Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: - - - - - In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. - - - - - - - The use of "fuzzy" is valid in this context. - - - Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." - - - Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. - - - - - - - going-forward basis - - - Jargon. Say "from now on," "in the future," or something similar. - - - - - - - happy path - - - Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is localized slang and could easily be misunderstood. It could also produce problems for translation. - - - - - - - harness the power - - - Do not use. - - - - - - - have a crack at, jump right in - - - Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. - - - - - - - if you want, if you wish - - - Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." - - - - - - - in concert with - - - Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." - - - - - - - improve, enhance - - - Vague. Try to be more specific. - - - - - - - in a pinch - - - Under a tight schedule, hard pressed to achieve something. - - - - - - - infomediary - - - Not a word. Do not use. - - - - - - - is designed to - - - Avoid this and similar phrases when describing products and services. Instead, state what the product does. - - - - - Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. - - - - - - Correct: SSH works with almost any kind of public key algorithm or encoding format. - - - - - - - - - - - kettle of fish - - - Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. - - - - - - - leverage - - - Avoid. Alternatives include "use" and "take advantage of". - - - - - - - lights on, lights-on - - - Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. - - - It is typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." - - - - - - - low-hanging fruit - - - Metaphor. Do not use. - - - - - - - marketecture - - - Not a word. Do not use. - - - - - - - meet your needs - - - Vague. Try to be more specific, for example, "lower your middleware costs." - - - - - - - mission-critical - - - Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Ensure that you have the applications that you need to help your customers." versus "Ensure that you have the mission-critical applications that your customers demand." - - - - - - - net-net - - - Jargon. Use "in summary," "the end result," or something similar. - - - - - - - niche focus - - - Do not use. - - - - - - - over the wire - - - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. - - - - - - - pain in the backside - - - Nobody should ever write this expression or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. - - - - - - - paradigm - - - Avoid. Use "model," "standard," or something similar. - - - - - - - performant - - - In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. - - - - - - - physicalize - - - Not a word. Do not use. - - - - - - - piggyback - - - Slang. Do not use. - - - - - - - pre-baked - - - Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. - - - - - - - productize - - - Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] - - - - - - - ready to rumble - - - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." - - - - - - - rest on your laurels - - - Do not use. - - - - - - - right before doing something - - - Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. - - - - - - - root your server in the /serverRoot directory - - - This expression is inelegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. - - - - - - - shoot yourself in the foot - - - To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") - - - - - - - shy of - - - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. - - - - - - - silo, siloed - - - Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," or something similar. - - - - - - - solutioning - - - Not a word. Lazy version of "creating a solution." - - - - - - - solutions-based - - - Do not use. - - - - - - - solution stack - - - Do not use. - - - - - - - stovepipe - - - Jargon. In business, related to lack of cross-organizational communication, similar to "silo." - - - - - - - synergistic, synergy - - - Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. - - - - - - - synergical connectivity - - - Seriously? - - - - - - - to think outside the box - - - 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? - - - - - - - tunnel vision - - - Do not use. - - - - - - - under the covers - - - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. - - - - - - - value-added - - - Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." - - - - - - - very - - - Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." - - - - - - - virtual elephants - - - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. - - - - - - - - -
-
- Neologisms (Invented Words) - - The English language is full of these words. Some of them are useful; some of them are less so; others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and is generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. - - - Examples - - - "This feature allows synchronization of adds, deletes, and changes ..." - - - - - This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." - - - - - - - - - - -
-
- Anthropomorphism - - Anthropomorphism is applying human qualities to non-human things or animals. Avoid it in your writing. - - - Examples - - - The computer will think for a brief period. - - - - - Computers do not actually think but they might take a while to "process" commands. - - - - - - - - - - The Proxy Server is talking to either RHN Hosted or a Satellite Server. - - - - - It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. - - - - - - - - - - - Report an issue - - -
-
- Inclusive Language - - Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. - - - Replace terms that reinforce cultural, racial, or other types of bias with an alternative. - - - Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. - - - For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. - - - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. - - - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". - - - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. - - - Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". - - - Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. - - -
-
- Avoiding Ambiguities - - - Capitalizing Proper Nouns - - - In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. - - - - - - - - - Example - Improvement - - - - - - - This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. - This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. - - - - - - - -
- - - - - - Homographic Verbs - - - The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. - - - - - - - - - Example - Improvement - - - - - - - The next() method should return null to indicate the end of results. - The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. - - - - It may be held in memory. - It can be held in memory. OR It might be held in memory. - - - - - - - -
- - - - - - Homonymity - - - When a single term has multiple meanings, be explicit in order to differentiate between them. - - - - - - - - - Example - Improvement - - - - - - - Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. - Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. - - - - To create another administrator, click New on the File menu. - To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. - - - - - - - -
- - - See also . - - - - - - - - - Verb phrases - - - When you have more than one infinitive verb within a sentence, be clear what each verb refers to. - - - - - - - - - Example - Improvement - - - - - - - Use the utility to run activities and save your settings. - Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). - - - - - - - -
- - - - - - Invisible Plurals - - - Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. - - - - - - - - - Example - Improvement - - - - - - - Once the file retrieval has been completed, you are ready to restart your system. - After the files have been retrieved, you can restart your system. - - - - - - - -
- - - - - - Verb phrases - - - Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. - - - - - - - - - Example - Improvement - - - - - - - If the completed field contains text, it does not change. - If the completed field contains text, that text does not change. - - - - - - - -
- - - - - - Synonymity - - - Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. - - - For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. - - - - - - - Use of "using" - - - Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. - - - - - - - - - Example - Improvement - - - - - - - Open the firewall ports using the existing service configuration. - - Option 1: Open the firewall ports by using the existing service configuration. - - - Option 2: Use the existing service configuration to open the firewall ports. - - - - - - The resource agents using mail alerts require a mail transport agent. - The resource agents that use mail alerts require a mail transport agent. - - - - - - - -
- - - - - - Verb phrases - - - Ensure that a verb phrase at the start of a sentence modifies the correct word. - - - - - - - - - Example - Improvement - - - - - - - Having configured your environment, the product is ready to be used. (The product does not configure the environment.) - After you configure your environment, you can use the product. - - - - - - - -
- - - - - - - -
-
- Dates and Times - - Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. - - - Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". - - - Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. - - - For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". - - - Use "noon" or "12 noon" instead of "12 PM". Use "midnight" or "12 midnight" instead of "12 AM". - - - Examples - - - The training class begins at 10 AM on 1 April 2021. - - - The coffee break is from 2:00 PM to 2:30 PM. - - - - - - -
-
- Numbers - - Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. - - - Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). - - - Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). - - - See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. - -
- Phone numbers - - Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international use by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. - - -
- -
- - diff --git a/tmp/en-US/xml/M.xml b/tmp/en-US/xml/M.xml deleted file mode 100644 index a4afee2..0000000 --- a/tmp/en-US/xml/M.xml +++ /dev/null @@ -1,309 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - M - - - macOS - - - In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. - - - - - - - make sure - - - This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." - - - You might be able to use "verify" or "ensure" instead. - - - - - - - manual, man page - - - Correct. Two words. Do not use "manpage." - - - - - - - matrixes - - - Correct. This is the correct plural form for US English spelling. Do not use "matrices." - - - - - - - MB - - - - - When written as MB, stands for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). - - - - - - When written as Mb, stands for megabit. - - - - - - - - - - - MBps - - - Initialism for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps. - - - - - - - MBR - - - Initialism for Master Boot Record, a small program that is executed when a computer boots up. Typically, the MBR resides on the first sector of the hard disk. The program begins the boot process by looking up the partition table to determine which partition to use for booting. It then transfers program control to the boot sector of that partition, which continues the boot process. In DOS and Windows systems, you can create the MBR with the FDISK /MBR command. - - - - - - - media - - - - - 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 fibre 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. - - - - - - - - - - - menu-driven - - - adj. Correct. Do not use "menu driven" or "menudriven." - - - Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program. - - - - - - - message - - - n. Write "the system displays a message" or "send an instant message." - - - adj. For example, "A messaging system." - - - Do not use as a verb. - - - - - - - metadata - - - Correct. Do not use "meta data" or "meta-data." - - - - - - - microservice - - - n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See https://en.wikipedia.org/wiki/Microservices for a definition. - - - - - - - Microsoft - - - Correct. Do not use "MS," "MSFT," or "MicroSoft." - - - - - - - misconfigure - - - v. This term is in common use and does appear in some dictionaries, but try to avoid it if possible. Do not hyphenate. - - - - - - - Montecito - - - Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. - - - - - - - mount - - - v. - - - - - To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. - - - - - - To install a device, such as a disk drive or expansion board. - - - - - - - - - - - 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. - - - - - - - Mozilla Firefox - - - Correct. First reference must be "Mozilla Firefox." Subsequent references can be "Firefox." - - - - - - - Mozilla Thunderbird - - - Correct. First reference must be "Mozilla Thunderbird." Subsequent references can be "Thunderbird." - - - - - - - MDOS - - - Correct. Do not use "ms-dos," "MSDOS," or "msdos." - - - - - - - multiprocessing - - - Correct. Do not use "multi-processing." - - - - - - - must - - - Use when referring to a task that a user is required to do. For example, "You must make a backup" is a requirement, but "You should make a backup" is a suggestion. - - - - - - - mutexes - - - Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. - - - - - - - MySQL - - - Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an ® symbol to denote a registered trademark. - - - - - - - - - diff --git a/tmp/en-US/xml/N.xml b/tmp/en-US/xml/N.xml deleted file mode 100644 index ef9409f..0000000 --- a/tmp/en-US/xml/N.xml +++ /dev/null @@ -1,125 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - N - - - navigate to - - - Use "Navigate to" when moving through multiple GUI 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. - - - - - - - need - - - Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). - - - - - - - needs, needs to be, need to - - - Avoid when possible. Suggested alternatives include "must," "required," or "should." - - - - - - - .NET - - - The Microsoft .NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and supports several programming languages. - - - "Microsoft .NET" is correct for the first reference, and ".NET" for all following references. - - - - - - - network transparency - - - A condition in which an operating system or other service gives user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems NFS, now a de facto industry standard, provides access to shared files through the Virtual File System (VFS) interface that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. - - - - - - - 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. - - - 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. - - - - - - - node - - - - - In networks, a processing location. A node can be a computer or some other device such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or a Media Access Control (MAC) address. - - - - - - In tree structures, a point where two or more lines meet. - - - - - - - - - - - nonsecure - - - Do not use. Use "insecure" instead. - - - - - - - NULL or null - - - When a command or value is stated, use NULL. When stating that something is null, use "null," all lowercase. - - - - - - - - - diff --git a/tmp/en-US/xml/O.xml b/tmp/en-US/xml/O.xml deleted file mode 100644 index 9dc29b3..0000000 --- a/tmp/en-US/xml/O.xml +++ /dev/null @@ -1,270 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - O - - - Objective C - - - Correct. Do not use "Objective-C." - - - - - - - object-oriented - - - Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." - - - Also, do not use "object-orientated". - - - - - - - OEM - - - n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. - - - To provide equipment to another company, an OEM, which customizes and markets the equipment. - - - - - - - offline - - - adj. Write as one word. Do not use "off-line." - - - - - - - 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. - - - 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. - - - - - - - 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." - - - - - - - onboard - - - adj, tr.v. Use the one-word form in all cases. - - - - - - - once - - - Use only to mean "one time." Do not use as a conjunction to mean "after" or "when." - - - - - - - online - - - adj. Write as one word. Do not use "on-line." - - - - - - - on-site - - - adj. Hyphenate when used as an adjective, as in "on-site labs." - - - - - - - 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. - - - - - - - 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." - - - - - - - opcodes - - - Correct. Do not use "op-codes." - - - - - - - OpenJDK - - - The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. - - - - - - - open architecture - - - An architecture whose specifications are public. It includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. - - - - - - - Open InfiniBand - - - "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. - - - - - - - OpenOffice - - - A Linux desktop suite. Do not use "Openoffice," "Open Office," or "ooo." - - - See also . - - - - - - - open source - - - Correct. Do not use "OpenSource," "opensource," or "open-source." Only capitalize the "o" in "open source" at the beginning of a sentence. - - - - - - - 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". - - - - - - - operating system - - - Correct. Do not use Operating System, or OS. - - - - - - - orientate - - - Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps to familiarize you with the environment." - - - - - - - output device - - - Any machine that is capable of representing information from a computer, including display screens, printers, plotters, and synthesizers. - - - - - - - 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 . - - - - - - - override - - - Correct. Do not use "over-ride" or "over ride." - - - - - - - - - diff --git a/tmp/en-US/xml/Objectives.xml b/tmp/en-US/xml/Objectives.xml deleted file mode 100644 index 075ec6d..0000000 --- a/tmp/en-US/xml/Objectives.xml +++ /dev/null @@ -1,53 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - 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: - - - - Accurate and consistent - - - - - - Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale. - - - - - - Comprehensible, with a fog index of 9-12, using the Gunning fog index. - - - - - - User focused, providing information without patronizing the reader, or making presumptions about their skills. - - - - - - - - - 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. - - - - - - diff --git a/tmp/en-US/xml/P.xml b/tmp/en-US/xml/P.xml deleted file mode 100644 index ba71e0f..0000000 --- a/tmp/en-US/xml/P.xml +++ /dev/null @@ -1,327 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - P - - - PaaS - - - n. The correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. - - - Marketing, Brand, Customer Portal Usage - - For all-caps text, such as banners, use "<VARIANT>-ASERVICE" for the spelled-out version. The same abbreviation is used across all groups. - - - - - - - - - PC - - - n. Use to refer to a personal computer. - - - - - - - persist - - - v. Do not use as a verb to mean "store" or "save," for example, when referring to persistent storage. - - - - - - - PHP - - - n. Use PHP when referring to the language in general. Use php when referring to the specific command or some other literal use. - - - See for specific PHP language information. See for more general information. - - - - - - - Pico, pico - - - n, adj. Capitalize when referring to the text editor or to the programming language. Do not capitalize when referring to the SI prefix. - - - - - - - plain text - - - 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." - - - - - - - please - - - 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. - - - - - - - pluggable - - - adj. Something that is capable of being plugged in, especially in terms of (for example) software modules. "Hot-pluggable" is also widely used with respect to hardware to indicate that it can be connected and recognized without powering down the system. - - - - - - - plug-in - - - n. Write hyphenated. Do not use "plugin." - - - A hardware or software module that adds a specific feature or service to a larger system. - - - - - - - PM - - - Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". - - - See also . - - - See the IBM Style Guide for a full discussion of how to represent times. - - - - - - - pop-up - - - n, adj. Do not use "popup" or "pop up." - - - - - - - PostScript - - - n. It is a registered trademark of Adobe. Do not use "Postscript." - - - - - - - PowerPC - - - 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 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. - - - - - - - POSIX - - - n. Do not use "Posix," "posix," or variations thereof. - - - An acronym for "Portable Operating System Interface for UNIX." - - - - - - - PPP - - - n. Do not use "ppp" or "Ppp." - - - An initialism for Point-to-Point Protocol. - - - - - - - press - - - v. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." - - - - - - - proof of concept - - - Use the following rules to form the plural of this phrase: - - - - Use "proofs of concept" for multiple proofs and only one concept. - - - - - - Use "proofs of concepts" for multiple proofs and multiple concepts. - - - - - - Do not use "proof of concepts." - - - - - - - - - - - - - pseudo-ops - - - Correct. Do not use "pseudo ops" or "pseudoops." - - - - - - - pull-down - - - adj. Use only if you must specify the type of menu or list. Do not use "pulldown." - - - - - - - push-button automation, turn-key automation - - - Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use accurate language for the situation, such as: - - - - - User-triggered automation - - - - - - Ready-to-use, ready-to-deploy - - - - - - Self-service, self-provisioned. - - - - - - Single-step automation - - - - - - On-demand automation - - - - - - - - - - - PXE - - - Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. - - - PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. - - - - - - - - - diff --git a/tmp/en-US/xml/Preface.xml b/tmp/en-US/xml/Preface.xml deleted file mode 100644 index 264ab5b..0000000 --- a/tmp/en-US/xml/Preface.xml +++ /dev/null @@ -1,12 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Preface - - - - - diff --git a/tmp/en-US/xml/Punctuation.xml b/tmp/en-US/xml/Punctuation.xml deleted file mode 100644 index 88437ec..0000000 --- a/tmp/en-US/xml/Punctuation.xml +++ /dev/null @@ -1,470 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Punctuation - - This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. - -
- Colons and Semicolons - - Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. - - - To relate clauses: - - The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: - - - - - - - They had been writing code all night: this factor could explain their bloodshot eyes. - - - - - - They had been writing code all night; this factor could explain their bloodshot eyes. - - - - - - I spend a lot of money on food; last month, I went out to eat 36 times. - - - - - - I spend a lot of money on food: last month, I went out to eat 36 times. - - - - - - - The phrase following a semicolon or colon should begin with a lowercase letter, unless it begins with a proper noun. In the case of a colon, use an uppercase letter if the phrase constitutes a complete sentence on its own. - - - Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - - - To introduce a list or series: - - A colon is generally used before a list or series. - - - - - - - The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill. - - - - - - - Do not use a colon if the list is a complement or object of an element in the sentence. - - - - - Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail. - - - - - - The colors I hate most are: - - - - - green - - - - - - orange - - - - - - pink - - - - - - magenta - - - - - - - - - - - Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. - - - - - The steps for changing directories are as follows: - - - - - Open a terminal. - - - - - - Type cd Documents/Books. - - - - - - - - - - - Use a colon to introduce a bullet list. - - - - - In the Properties dialog box, notice the following entries: - - - - - Connection name - - - - - - Count - - - - - - Confirm starting connection - - - - - - Confirm stopping connection - - - - - - Cost per - - - - - - - - - - - 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 semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. - - - - - I think; therefore, I am. - - - - - - -
-
- Commas - - In compound sentences: - - Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. - - - - - - - I spent five hours working on this document, but I lost it when my computer crashed. - - - - - - Do you want to go the mall and the grocery store with me, or are you going to watch football instead? - - - - - - You play and I'll sing. - - - - - - - A comma can be omitted from a sentence with several clauses, but only when there is little chance that the sentence could be misread without it. - - - - - We played football all afternoon and were completely exhausted but we still stayed up watching movies all night. - - - - - - - That sentence is acceptable, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence. - - - In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction. - - - - - You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice. - - - - - - - In adverbial clauses and phrases: - - If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: - - - - - - - I'll go to lunch with you if we can get pizza. - - - - - - I don't want to go out for pizza, because I had pizza yesterday. - - - - - - - If a dependent clause comes before the main clause, use a comma whether the clause is restrictive or not. - - - - - If we get pizza, I'll go to lunch with you. - - - - - - When I heard the voice on the other end of the line, I was quite surprised. - - - - - - - In adjectival clauses or phrases: - - An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. - - - - - - - The application, which comes with excellent documentation, is used by many graphic artists. - - - - - - - An adjectival clause that cannot be dropped without changing the meaning of the sentence is not set off with commas: - - - - - The plan that matters most to us will be easy to implement. - - - - - - - With coordinate adjectives: - - Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. - - - - - - - My dog is loyal, obedient, and affectionate. - - - - - - It was a long, boring meeting. - - - - - - - With series and lists: - - Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. - - - - - - - Today I am wearing socks, shoes, pants, and a shirt. - - - - - - -
-
- Parentheses - - Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. - - - - - I tried to get to the elevator before the door shut, but I was too slow. - - - - - - Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead. - - - - - - - Expressions beginning with for example, that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. - - - - - He interviewed the biggest stars of the day, namely, Madonna, Johnny Cash, and Jack Nicholson. - - - - - - Classic works of literature (such as Dickens, Shakespeare, the Brontes) lined the shelves. - - - - - - - If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. - - -
-
- Quotation Marks - - Commas and periods go inside quotation marks. - - - Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. - - - A Correct Example of the Use of Quotation Marks - - For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." - - - - -
-
- Apostrophes - - Do not use an apostrophe to denote a plural. - - - To denote a possessive, use an apostrophe as follows: - - - Plural nouns not ending in s should add an 's (for example, the alumni's contribution). - - - Plural nouns ending in s only need an apostrophe (for example, the horses' food). - - - Singular common nouns ending in s should add an 's unless the next word begins with an s (for example, the witness's answer or the witness' story). - - - Singular proper names ending in s only need an apostrophe (for example, Dickens' novels). - - -
- -
- diff --git a/tmp/en-US/xml/Q.xml b/tmp/en-US/xml/Q.xml deleted file mode 100644 index 6b600a9..0000000 --- a/tmp/en-US/xml/Q.xml +++ /dev/null @@ -1,52 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Q - - - Q and A - - - n. Abbreviation for "Question and Answer," this format is listed in the American Heritage Dictionary. - - - - In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. - - - - - - - - - qeth - - - Lowercase at all times. - - - - - - - - - - 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. - - - - - - - - - diff --git a/tmp/en-US/xml/R.xml b/tmp/en-US/xml/R.xml deleted file mode 100644 index 6008d7a..0000000 --- a/tmp/en-US/xml/R.xml +++ /dev/null @@ -1,240 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - R - - - RAM - - - Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." - - - - - - - RAM disk - - - 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. - - - - - - - raw - - - Unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device. - - - The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device. - - - - - - - raw data - - - Information that is not organized, formatted, or analyzed. - - - - - - - read - - - v. To copy data to a place where a program can use it. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. It can also refer to the act of determining the contents of a variable or parameter. - - - n. The act of reading. For example, a fast disk drive performs 100 reads per second. - - - - - - - read-only - - - Capable of being displayed, but not modified or deleted. For all operating systems, you can protect objects (disks, files, or directories) with a read-only attribute that prevents other users from modifying the object. - - - - - - - read/write - - - Capable of being displayed (read) and modified (written to). Most objects (disks, files, or directories) are read/write, but you can also protect objects with a read-only attribute that prevents other users from modifying the object. - - - - - - - real time/real-time - - - n. The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." - - - adj. Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." - - - - - - - reboot - - - Correct. Do not use "re-boot." - - - - - - - RedBoot - - - Correct. Do not use "Redboot" or "Red Boot." - - - - - - - refer to - - - Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." - - - - - - - remote access - - - The ability to log on to a network from a distant location. Generally, it implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations that are connected directly to the network is slower data transfer speeds. - - - - - - - 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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. - - - - - - - required - - - See . - - - - - - - return - - - When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. See for other platforms. - - - - - - - right-click - - - v. Write the term hyphenated. Do not use "right click." - - - - - - - right now - - - Use "now" instead. - - - - - - - ROM, PROM - - - Acronym for read-only memory, computer memory on which data is prerecorded. After data has been written to a ROM chip, it cannot be removed and can only be read. - - - A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a device called a PROM programmer. - - - - - - - roundtable, round table - - - v. Use the one-word form to refer to a type of event or gathering. - - - n. Use the two-word form to refer to a circular table. - - - - - - - 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." - - - - - - - runlevel - - - Correct. Do not use "run level" or "run-level." - - - - - - - - - diff --git a/tmp/en-US/xml/Resources.xml b/tmp/en-US/xml/Resources.xml deleted file mode 100644 index 8cf6776..0000000 --- a/tmp/en-US/xml/Resources.xml +++ /dev/null @@ -1,143 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Resources - - This section lists some books and websites for you to consult on your quest to create a better document. - - - The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: - - - - Technical content: software manuals and documentation, user guides, training courses - - - - - - Technical collateral: white papers and technology briefs - - - - - - Marketing content: advertising, promotions, articles - - - - - - Corporate collateral: related to company or products - - - - - - Press releases - - - - - - - -
- References for Technical Content and Collateral - - - - IBM Style Guide. IBM Corporation, latest version. - - - - - - The Chicago Manual of Style, 17th Edition. Chicago: The University of Chicago Press, 2017. - - - - - - Merriam-Webster Collegiate Dictionary - - - Visit https://www.merriam-webster.com/ for subscription options. - - - - - - The American Heritage Dictionary of the English Language - - - An online edition is accessible free of charge through http://www.ahdictionary.com/ - - - - - - -
-
- References for Marketing and Corporate Collateral - - - - AP Stylebook Online - - - - - - Merriam-Webster Online http://www.merriam-webster.com/ - - - - - - -
- - - diff --git a/tmp/en-US/xml/Revision_History.xml b/tmp/en-US/xml/Revision_History.xml deleted file mode 100644 index 4ee2645..0000000 --- a/tmp/en-US/xml/Revision_History.xml +++ /dev/null @@ -1,524 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Revision History - - - - 3-0 - July 2021 - - Julian - Cable - jcable@redhat.com - - - - Major update to align with some recent changes in IBM Style. - Sentence case is required for captions, legends, and diagram labels. - Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. - Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. - Minor edits so the guide itself conforms with its own advice. - - - - - - - - 2.0-1 - Wed Jun 3 2015 - - David - O'Brien - davido@redhat.com - - - - Fix issue "use 'singular to plural' pronouns -- typo? #6 . - Repair some XML in the grammar section. - Minor repairs to language. - - - - - - - - 1.6-14 - Wed Mar 12 2014 - - David - O'Brien - davido@redhat.com - - - - Added entry for "huge pages". - Updated entry for virtual machine to allow for abbreviation. - Updated section on using non-breaking spaces. - Added entry for correct capitalization of partners. - Added entry for "datasheet". - Change to common brand. - Remove some internal links that are no longer valid. - Generalize some entries based on advice from legal. - - - - - - - - 1.6-13 - Wed Feb 26 2014 - - David - O'Brien - davido@redhat.com - - - - 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. - 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. - - - - - - - - 1.6-12 - Fri Dec 20 2013 - - David - O'Brien - davido@redhat.com - - - - General cleanup of "U" section. BZ 1037923: Added entry for "uninterruptible". - General cleanup of "T" section. BZ 1038090: Added entry for "tier-1". - General tidy-up. Fix some typos. Updates cross-references. Started on BZ 820071. - - - - - - - - 1.6-11 - Wed Nov 27 2013 - - Julie - Wu - docs@redhat.com - - - - BZ 997202 Remove incorrect content regarding Japanese translation. - - - - - - - - 1.6-10 - Mon Nov 25 2013 - - Brice - Fallon-Freeman - docs@redhat.com - - - - BZ 1022268 Add entry for "time frame" - BZ 1022266 Add entry for "roundtable" - BZ 1027041 Add entry for "big data" - - - - - - - - 1.6-9 - Wed Nov 20 2013 - - David - O'Brien - docs@redhat.com - - - - Add balance of entries from "Things Shadowman would Never Say". - - - - - - - - 1.6-8 - Tue Nov 12 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 896006 Add entry for "health check". - BZ 896009 Add entry for "skill set". - BZ 924040 Add entry for referring to fonts. - BZ 915987 Add entry for "bare metal". - Add exception for Brand and Marketing heading styles. - BZ 1017549 Added entry for how to use URLs and footnotes. - BZ 1019258 Fixed Gunning Fog typo Ch 1 under "Readability". - BZ 989838 Updated entry for x86 usage. - BZ 1010163 Added entry for "Q and A". - BZ 821606 Updated entry for qeth based on new information. - BZ 1017149 Add entry for DevOps. - BZ 972916 Add entries for GNOME and GNOME Classic; document use of Super key. - General review and updates to examples. - Fix some revision history entries. - - - - - - - - 1.6-7 - Mon Aug 12 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 995310 Add entry for documenting command syntax. - BZ 984803 Add entry for online and offline backups. - BZ 989942 Add entry How to document Interface element labels. - BZ 989838 Update entries for referring to AMD64, Intel 64, x86, and related terms. - - - - - - - - 1.6-6 - Wed Jul 31 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 892839 Update entry for internet. - BZ 980307 Add entry for hyphenation. - BZ 965898 Add entry for documenting currencies. - BZ 989942 Add entry for documenting interface elements to Design section. - Various punctuation and spelling fixes. - - - - - - - - 1.6-5 - Wed Jul 17 2013 - - Julie - Wu - docs@redhat.com - - - - BZ 973074 Add entry for "talking to" in section on slang - BZ 950303 Add entry for SIOV - BZ 965378 Update entry for "Unset" - - - - - - - - 1.6-4 - Thu May 23 2013 - - David - O'Brien - docs@redhat.com - - - - Add "cloudbursting," "cloudwashing," and "pluggable" to usage dictionary. - - - - - - - - 1.6-2 - Tue Mar 19 2013 - - David - O'Brien - docs@redhat.com - - - - 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. - BZ 909015 Entry for "refer to" conflicts with IBM style guide. - Update some punctuation standards and cross references. - - - - - - - - 1.6-1 - Wed Jan 30 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 905707 Update section on active and passive voice with more examples and exceptions. - BZ 896245 Describe use of non-breaking spaces with company and product names. - BZ 821603 Add entry for Sybase Adaptive Server Enterprise usage. - - - - - - - - 1.6-0 - Tue Jan 15 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 823350 Additional Detail for Chapter 2.4 - BZ 821609 Add correct usage of PHP to Usage Dictionary - BZ 831909 Remove "in depth" from Usage Dictionary; covered in standard references. - BZ 868067 Add usage for PaaS, IaaS, and SaaS - BZ 821615 Correct use of JVM - BZ 836869 Update SSH entry to allow for lowercase version - BZ 829173 Add correct usage of "time to live" to Usage Dictionary - BZ 821616 capitalization when referring to Btrfs - BZ 821612 Usage Dictionary addition: "zip" - BZ 824209 word usage: segfault - BZ 821599 Documenting exceptions - BZ 821607 Definitions for Virtual Machine, Virtualized Guest - BZ 821606 should we say "QETH device" or "qeth device" - BZ 820480 Add "cgroups" to Usage Dictionary - - - - - - - - 1.5-5 - Wed Nov 21 2012 - - David - O'Brien - docs@redhat.com - - - - BZ 878313 - Duplicate "and" in entry for AMD 64. - Review and update sections M, N, T, U, and V. - - - - - - - - 1.5-4 - Sun Nov 11 2012 - - David - O'Brien - docs@redhat.com - - - - Remove "hostname" entry; covered in IBM. - - - - - - - - 1.5-3 - Thu Nov 08 2012 - - David - O'Brien - docs@redhat.com - - - - BZs 871652, 820071, 821611, 821610. - Updates to and integration of Chapters X, Y, and Z. - Updated section on "Avoiding Slang." - Removed some redundant entries. - Various cleanups based on IBM Style Guide. - New entries from Word Nerds discussions. - - - - - - - - 1-4 - Fri Aug 31 2012 - - David - O'Brien - docs@redhat.com - - - - Removed some redundant entries. - Bugs 851646, 850596, 821595, 821617. - - - - - - - - 1-3 - Sun Aug 26 2012 - - David - O'Brien - docs@redhat.com - - - - Removed some redundant entries. - Patched some entries based on IBM Style Guide. - Cleaned up A, B, C, and part of D in Word Usage Dictionary. - - - - - - - - 1-2 - Fri Jul 27 2012 - - David - O'Brien - docs@redhat.com - - - - Added some xrefs to make life simpler. Added some temp links to BZs that are yet to be addressed. - More work on punctuation, spelling, typos, and duplicate and redundant entries. - Some structure reorganization. - Updated Feedback page. - Removed Author Group. - - - - - - - - 1-1 - Fri Apr 13 2012 - - David - O'Brien - docs@redhat.com - - - - Clean up redundant variablelist tags. - Remove a few duplicate entries. - Start working on making punctuation consistent. - - - - - - - - 1-0 - Mon Feb 20 2012 - - Gemma - Sheldon - gsheldon@redhat.com - - - - DocBook conversion from original guide on the Intranet. - - - - - - - - - - - - diff --git a/tmp/en-US/xml/S.xml b/tmp/en-US/xml/S.xml deleted file mode 100644 index 21f6bc0..0000000 --- a/tmp/en-US/xml/S.xml +++ /dev/null @@ -1,760 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - S - - - S/390 - - - Use the full description "IBM S/390." Do not use "s390," "S390," or any other variations. - - - - - - - SaaS - - - The correct abbreviation for "Software-as-a-Service." See also . - - - - - - - Samba - - - Correct. Do not use "samba" or "SAMBA." - - - - - - - record - - - Correct. Do not use "s-record," "Record," "s-Record," or any other variations. - - - - - - - screen capture - - - n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. - - - - - - - screen saver - - - n. Do not use "screensaver." - - - - - - - scrollbar - - - n. Do not use "scroll bar" or "scroll-bar." - - - - - - - secure - - - n., vb. Due to potential legal ramifications, do not use without a qualifier. See for examples. - - - Using Qualifiers with Sensitive Terms - - - - - - Original text - Improvement - - - - - - - With this new version, the application is running on a secure, gateway-protected endpoint. - With this new version, the application is running on a more secure, gateway-protected endpoint. - - - - This function secures your connection. - This function improves the security of your connection. - - - - Developers can easily change the code to implement secured access. - Developers can easily change the code to make access more secure. - - - - - - - -
- - - - - - see - - - Use to refer readers to another resource. Avoid using "refer to" in this context. - - - - - - - segmentation fault - - - n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. - - - See also "What is a segfault?" on the Red Hat Customer Portal for more information. - - - - - - - SELinux - - - 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. - - - - - - - send out - - - Do not use. Instead, use "emit" or "issue." - - - - - - - server farm - - - Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. - - - - - - - server-side/server side - - - See . - - - - - - - setup - - - Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: - - - - - Each setup provides different features. - - - - - - You need to set up a user profile as part of the registration process. - - - - - - Follow the set-up instructions included with the hardware. - - - - - - - - - - - SHA-1, SHA-2 - - - 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. - - - See for full details. - - - - - - - Shadowman - - - Correct. Do not use "Shadow Man" or "ShadowMan." The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. - - - - - - - shadow passwords - - - Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. - - - Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package. - - - - - - - shadow utilities - - - Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. - - - - - - - share name - - - Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." - - - - - - - shebang - - - n. Refers to the character sequence consisting of the number sign and exclamation mark (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. - - - - - - - shell - - - A "shell" is a software application, for example, /bin/bash or /bin/sh, which provides an interface to a computer. Do not use this term to describe where to type commands. - - - - - - - shell prompt - - - Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt," "terminal," or "shell." - - - - - - - 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 . - - - - - - - shut down - - - v. Correct. Do not use "shut-down." Only use "shutdown" when referring to the /sbin/shutdown system command. - - - - - - - sign in - - - v. Write as two words. For example, "two options are available to sign in". - - - - - - - sign in to - - - v. Write as three words. For example, "to sign in to the system". - - - - - - - simply - - - Do not use. See also . - - - - - - - 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. - - - - - - - skill set, skills, knowledge - - - n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: - - - Example Use of Term "Skillset" Versus "Skills" - - Incorrect: Do you have the right skillset to be an RHCE? - - - Correct: Do you have the right skills to be an RHCE? - - - - - Example Use of Term "Knowledge" - - Incorrect: This course gives you the skill-set knowledge to complete your RHCT exam successfully. - - - Correct: This course gives you the knowledge to complete your RHCT exam successfully. - - - - - - - - - SLA - - - n. SLA stands for Service Level agreement. The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. - - - - - - - smart card - - - n. Do not use smartcard or smart-card. - - - - - - - SOCKS - - - Correct. Do not use "socks." When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5." - - - - - - - softcopy - - - Do not use. Instead, use "online." For example, "To view the online documentation ..." - - - - - - - sound card - - - n. Do not use "soundcard" or "sound-card." - - - - - - - Source-Navigator™ - - - Correct. Do not use "Source Navigator." Source-Navigator™ is a trademark of Red Hat. - - - - - - - source - - - v. In addition to the generic use of this term as a noun and verb, in a programming and technical sense, it also means "Run the source command against the named file." - - - - - - - space - - - Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key. - - - - - - - Spacebar - - - n. Use when referring to the keyboard key, such as "Press the Spacebar key to continue." - - - - - - - spec file - - - n. Use to refer to an RPM spec file. Do not use "specfile." - - - - - - - specific - - - When used as a modifier, put a hyphen before "specific," such as "MIP-specific," "Linux-specific," and "chip-specific." - - - - - - - spelled - - - Correct. It is the standard US English spelling. Do not use "spelt." - - - - - - - SQL - - - When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. - - - When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. - - - Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." - - - More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." - - - - - - - SR-IOV - - - Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. - - - - - - - SSH - - - Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. - - - Do not use as a verb. - - - Example Use of "SSH" - - Incorrect: To begin, "ssh to the remote server." - - - Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar. - - - - - - - - - SSL - - - Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. - - - - - - - stand-alone - - - adj. Write hyphenated. 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. - - - - - - - StarOffice - - - A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." - - - The successors of StarOffice are and . - - - - - - - start up - - - v. Do not use. Instead, use "activate" or "invoke." - - - - - - - startx - - - Correct. Do not use StartX or other variants. - - - - - - - straightforward - - - adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward." - - - - - - - su - - - Correct. The Linux command to change to a named user. Do not use SU (all caps). - - - - - - - subcommand - - - Correct. Do not use "sub-command" or "verb." A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: - - -hammer import organization --help - - In this example, "hammer" is the main or primary command, and "import" and "organization" are subcommands. is an option. - - - See also . - - - - - - - subdirectory - - - Correct. Do not use "sub-directory." See also . - - - - - - - submenu - - - Correct. Do not use "sub-menu." See also . - - - - - - - subpackage - - - Correct. Do not use "sub-package." - - - This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages." - - - Any other use of this word is strongly discouraged. - - - Note: Subpackages are not the same as dependencies and should not be treated as such. - - - - - - - superuser - - - A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." - - - - - - - swap space - - - Correct. Do not use "swapspace." Capitalize at the beginning of a sentence only. - - - - - - - Sybase Adaptive Server Enterprise (ASE) - - - Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE." If discussing the high-availability version, use "Sybase ASE and High Availability." - - - See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. - - - - - - - SysV - - - Correct. Do not use Sys V or System V. - - - - - - - symmetric encryption - - - A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. - - - - - - - - - diff --git a/tmp/en-US/xml/Slang.xml b/tmp/en-US/xml/Slang.xml deleted file mode 100644 index 1d81678..0000000 --- a/tmp/en-US/xml/Slang.xml +++ /dev/null @@ -1,877 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Avoiding Jargon, Slang, Metaphors, and Misleading Language - - Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. - - - If you find slang terms or other difficult-to-understand passages in our documentation, use this page to search for alternatives. - -
- Avoiding Misleading or Confusing Language - - Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. - - - - best practices - - - This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." - - - See the section for additional information about recommendations in Red Hat documentation. - - - - - - - first come, first served - - - Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. - - - - - - - - -
-
- Identifying and Avoiding Slang - - Examples of slang terms: - - - - administrivia - - - Not a word. Do not use. - - - - - - - anything you/they like - - - This is probably readily understood but should not appear in Red Hat documentation. - - - - - "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." - - - Rephrase to something more suitable, such as "...to register any other kind of plug-in." - - - - - - - - - - - ask (as a noun), make the ask - - - Ask is a verb. Do not use it as a noun. - - - - - - - at this point in time - - - Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. - - - - - - - automagic - - - Also, automagical. Both terms are slang. Do not use. - - - - - - - best-of-breed - - - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. - - - - - - - bleeding edge - - - Do not use. - - - - - - - bottom line - - - Traditionally used in financial contexts; avoid overuse. - - - - - - - bucketize - - - Not a word. Try "categorize" or "organize into logical groups." - - - - - - - center of competency - - - Do not use. - - - - - - - check this site - - - Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. - - - - - - - coopetition - - - Not a word. Do not use. - - - - - - - core competency - - - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," etc. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." - - - - - - - eat your own dogfood - - - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. - - - - - - - data point - - - Do not use. - - - - - - - dig deeper, delve deeper - - - "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." - - - - - - - double-edged sword, double-bladed sword - - - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. - - - - - - - enterprise-ready - - - Although we used to use this term to emphasize our products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. - - - - - - - exceed your expectations - - - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." - - - - - - - fib - - - A fib is a "small lie," also known as a "white lie." This appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." - - - - - - - flying by the seat of your pants - - - Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. - - - - - - - frame it up - - - Do not use. - - - - - - - frown upon - - - "To frown upon" means to hold in low regard, not to approve of, etc. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). - - - - - - - fuzzy (search) - - - Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: - - - - - In Directory Server, if you do a fuzzy search for "Smith" you will probably also get "Smyth," because it sounds the same. - - - - - - - The use of "fuzzy" is valid in this context. - - - Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." - - - Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. - - - - - - - going-forward basis - - - Jargon. Say "from now on," "in the future," or something similar. - - - - - - - happy path - - - Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is very localized slang and could easily be misunderstood. It could also produce problems for translation. - - - - - - - harness the power - - - Do not use. - - - - - - - have a crack at/jump right in - - - Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. - - - - - - - if you want, if you wish - - - Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." - - - - - - - in concert with - - - Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." - - - - - - - improve, enhance - - - Vague. Try to be more specific. - - - - - - - in a pinch - - - Under a tight schedule, hard pressed to achieve something. - - - - - - - infomediary - - - Not a word. Do not use. - - - - - - - is designed to - - - Avoid this and similar phrases when describing products and services. Instead, state what the product does. - - - - - Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. - - - - - - Correct: SSH works with almost any kind of public key algorithm or encoding format. - - - - - - - - - - - kettle of fish - - - Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. - - - - - - - leverage - - - Avoid. Alternatives include "use" and "take advantage of". - - - - - - - lights on, lights-on - - - Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. - - - Typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." - - - - - - - low-hanging fruit - - - Metaphor. Do not use. - - - - - - - marketecture - - - Not a word. Do not use. - - - - - - - meet your needs - - - Vague. Try to be more specific, for example, "lower your middleware costs." - - - - - - - mission-critical - - - Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Make sure you have the applications you need to help your customers." vs. "Make sure you have the mission-critical applications your customers demand." - - - - - - - net-net - - - Jargon. Use "in summary," "the end result," or something similar. - - - - - - - niche focus - - - Do not use. - - - - - - - over the wire - - - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent/transmitted in plain text" is fine. - - - - - - - pain in the backside - - - Nobody should ever write this or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. - - - - - - - paradigm - - - Avoid. Use "model," "standard," or something similar. - - - - - - - performant - - - In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. - - - - - - - physicalize - - - Not a word. Do not use. - - - - - - - piggyback - - - Slang. Do not use. - - - - - - - pre-baked - - - Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. - - - - - - - productize - - - Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] - - - - - - - ready to rumble - - - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." - - - - - - - rest on your laurels - - - Do not use. - - - - - - - right before doing something - - - Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. - - - - - - - root your server in the /serverRoot directory - - - This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. - - - - - - - shoot yourself in the foot - - - To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Remove the sentence - it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") - - - - - - - shy of - - - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang. - - - - - - - silo, siloed - - - Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," "segregated," or something similar. - - - - - - - solutioning - - - Not a word. Lazy version of "creating a solution." - - - - - - - solutions-based - - - Do not use. - - - - - - - solution stack - - - Do not use. - - - - - - - stovepipe - - - Jargon. In business, related to lack of cross-organizational communication, similar to "silo." - - - - - - - synergistic, synergy - - - Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. - - - - - - - synergical connectivity - - - Seriously? - - - - - - - to think outside the box - - - 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? - - - - - - - tunnel vision - - - Do not use. - - - - - - - under the covers - - - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. - - - - - - - value-added - - - Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." - - - - - - - very - - - Use with caution. For example, there is little value in saying "very cost-effective" vs. "cost-effective." - - - - - - - virtual elephants - - - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. - - - - - - - - -
-
- Neologisms (Invented Words) - - The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. - - - Examples - - - "This feature allows synchronization of adds, deletes, and changes ..." - - - - - This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." - - - - - - - - - - -
-
- Anthropomorphism - - Anthropomorphism is applying human qualities to non-human things or animals. Avoid this in your writing. - - - Examples - - - The computer will think for a brief period. - - - - - Computers do not actually think but they might take a while to "process" commands. - - - - - - - - - - The Proxy Server is talking to either RHN Hosted or a Satellite Server. - - - - - It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. - - - - - - - - - - - Report an issue - - -
- - - diff --git a/tmp/en-US/xml/T.xml b/tmp/en-US/xml/T.xml deleted file mode 100644 index 4d54550..0000000 --- a/tmp/en-US/xml/T.xml +++ /dev/null @@ -1,244 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - T - - - taskbar - - - n. One word. Do not use "task bar." - - - - - - - tar, tarball - - - n. See the Word Usage chapter of the IBM Style Guide. - - - - - - - telco - - - Preferred abbreviation for "telecommunications company." Do not use "telecom." See also . - - - Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. See . - - - - - - - telecommunications service provider - - - Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . - - - - - - - telecommunications - - - Vertical for communication service providers. Preferred abbreviation is "telco." - - - - - - - terminal - - - n. Do not use to describe where to type commands. Use "command line" instead. - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - terminal emulation - - - Refers to making a computer respond like a particular type of terminal. With a terminal emulation program, you can access a mainframe computer or bulletin board service with a personal computer. - - - - - - - text mode - - - Correct. Do not use "textmode" or "text-mode." - - - A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. - - - - - - - text-based - - - adj. Correct. Do not use "text based." - - - - - - - third-party (adj.), third party (n.) - - - adj., n. Use "third-party" as the adjectival form. Use "third party" as the nominal form. Consult a dictionary for more examples. - - - - - - - through - - - Correct. Do not use "thru" and do not use the hyphen or any other type of dash. - - - - - - - throughput - - - n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. - - - - - - - tier-1 - - - adj. Always use a numeral, and always hyphenate. Follow standard capitalization guidelines. - - - - - - - time frame (n.) - - - Correct. Do not use "timeframe" or "time-frame." - - - - - - - time zone (n.) - - - Correct. Do not use "timezone" or "time-zone." - - - - - - - token-ring (n.) - - - 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. - - - - - - - toolbar (n.) - - - Correct. Do not use "tool bar" or "tool-bar." - - - - - - - tooltip (n.) - - - Correct. One word. Use the term "tooltip" to refer to a brief, textual description that is displayed when a cursor is moved over a graphical image, such as an icon or button. Do not use the term "hover help". - - - - - - - totally - - - Do not use. See "basically." - - - - - - - troubleshoot (v.) - - - Correct. Do not use "trouble shoot" or "trouble-shoot." - - - - - - - TTL - - - Initialism for "time to live" (n.) and "time-to-live" (adj.) - - - Neither the noun nor the adjective should be capitalized unless you are documenting a GUI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. - - - - - - - type - - - Type can be used as either a verb or noun. You can write "Print the data type of init" or "To start Source-Navigator, type snavigator." - - - - - - - - - diff --git a/tmp/en-US/xml/Template_Chapter.xml b/tmp/en-US/xml/Template_Chapter.xml deleted file mode 100644 index ca70987..0000000 --- a/tmp/en-US/xml/Template_Chapter.xml +++ /dev/null @@ -1,20 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Dummy Title - - dummy text - -
- Dummy Section Title - - More dummy text. - - -
- - - diff --git a/tmp/en-US/xml/Template_Section.xml b/tmp/en-US/xml/Template_Section.xml deleted file mode 100644 index 914bdd7..0000000 --- a/tmp/en-US/xml/Template_Section.xml +++ /dev/null @@ -1,12 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- - - - -
- diff --git a/tmp/en-US/xml/Translation.xml b/tmp/en-US/xml/Translation.xml deleted file mode 100644 index 4cfe7c6..0000000 --- a/tmp/en-US/xml/Translation.xml +++ /dev/null @@ -1,373 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Writing Clearly and Succinctly - - This chapter provides guidelines, tips, and techniques to help to make your writing easier to read and understand, and also to translate. - -
- Sentence Structure - - This section describes how to construct your content for clarity and readability. A full discussion of this topic is beyond the scope of this guide. - -
- Using and Formatting Lists - - 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 sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. - - - The following general guidelines apply to lists: - - - - Itemized lists - - - 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. Titles are optional. - - - - - - - Ordered lists - - - They appear as a numbered list. 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. - - - - - - - Variable lists - - - They 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.) A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. Tables are best reserved for information that relies on, or benefits greatly from, a grid layout. - - - - - - - Procedures - - - They appear as a list of numbered steps. Procedures always include a title, and are used to list the required steps to achieve a task. - - - - - - - - - You can nest lists, but try to keep the number of levels to two or fewer. To nest procedures in DocBook, use <substep> elements. - -
- Formatting Lists for Readability - - It is important to provide sufficient 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. If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. DocBook uses the spacing attribute by default. - - - Use a list with normal spacing if any list item contains the following components: - - - - - Nested lists. Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. - - - - - - Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). - - - - - - Multiple paragraphs, or sentences that wrap to two or more lines. - - - - - - - Use a list with compact spacing in all other cases. - - - - The use of all but the simplest graphics in lists is strongly discouraged. - - - - - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. - - - - - - - - - Example - Improvement - - - - - - - - Before you start the installation, ensure that you have - - - - - enough free storage on your system - - - - - - backed up any data that you want to keep - - - - - - - to ensure a smooth installation. - - - - Before you start the installation, follow these steps to ensure a smooth installation: - - - - - Ensure that you have enough free storage on your system. - - - - - - Back up any data that you want to keep. - - - - - - - - - - - - - -
- -
- -
-
- Noun Stacking - - Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. - - - - - - - - - Example - Improvement - - - - - - - Plastic tubing and syringe tips. - Plastic tubing and plastic syringe tips. - - - - Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press Enter. - For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. - - - - - - - -
- -
- -
-
- Grammatical Genders - - When using ambiguous pronouns such as "they" or "it", it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and might require other grammatical adjustments. - - - Further, an initialism such as RPM might refer to the package or to the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package. - - - - - - - - - Example - Improvement - - - - - - - Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. - Set the XYZ parameter to 1 in the /etc/config.conf configuration file. This parameter configures how the Gateway application handles incoming network traffic. - - - - The RPM is useful. - The RPM package is useful. OR The RPM Package Manager is useful. - - - - - - - -
- -
-
- DocBook Elements - - Use the correct DocBook elements to help translators to understand the meaning of, and to identify, translatable and non-translatable terms. - - - Tagged Terms in Sentences - - Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators must complete the blanks or tag terms themselves. - - - - - - - - - - - Example - Improvement - - - - - - - In /some/path/, grep for XYZ. - In the /some/path/ directory, use the grep command to search for "XYZ". - - - - contains a reference to the hostname return value from instance-2. - The parameter contains a reference to the hostname return value from your second server instance, instance-2. - - - - Troubleshooting Glance. - Troubleshooting the Glance image service. - - - - Installing the maven-changelog-plugin. - Installing the maven-changelog-plugin package. - - - - - - - -
- -
-
- Code Blocks - - Avoid including commentary within the same box as command input or output. These comments might be confused with part of the output, and during translation might be accidentally overlooked and left in English. - - - For example, consider the word "Usage" in the following block: - - -Usage: rhevm-iso-uploader [options] list -rhevm-iso-uploader [options] upload [file1] [file2] [file3] - -
-
- Entities - - An entity is a primitive data type, which associates a string with either a unique alias (such as a user-specified name) or an SGML reserved word (such as #DEFAULT) - - - . Entities are called by reference, and take the form &name; (both the ampersand and the semicolon are required). - - - Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - - - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: - - - - - PRODUCT - - - - - - BOOKID - - - - - - YEAR - - - - - - HOLDER - - - - - - - Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in - - -
- - - diff --git a/tmp/en-US/xml/U.xml b/tmp/en-US/xml/U.xml deleted file mode 100644 index a375dea..0000000 --- a/tmp/en-US/xml/U.xml +++ /dev/null @@ -1,226 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - U - - - UID - - - n. UID and user ID are abbreviations of user identifier. Do not use "uid" or "User ID" or other variations unless specifically referring to a variable, argument, parameter, UI label, or similar. - - - - - - - UltraSPARC - - - Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. - - - 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. - - - - - - - undercloud - - - n. 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 . - - - - - - - uninterruptible - - - adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)." - - - - - - - UNIX - - - Correct. Do not use "Unix" or "unix." - - - UNIX is a registered trademark of The Open Group. - - - Do not use "UNIX-like." Use an expression such as "Linux, UNIX, and similar operating systems" instead. - - - - - - - unset - - - Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. - - - To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. - - - This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. - - - - - - - untrusted - - - Use only in the context of security relationships. For example, web browsers often indicate that a site is "untrusted" if it cannot verify that site's security certificate. - - - - - - - upgrade - - - v. Correct. Do not use "up-grade" or "up grade." - - - - - - - UPS - - - Abbreviation of uninterruptible power supply, a power supply that includes a battery to maintain power in the event of a power outage. - - - - - - - upsell (v.), upselling (n.) - - - Marketing Use Only - - "The practice of offering customers additional or more expensive products or services after they have already agreed to buy something. - http://www.ahdictionary.com/word/search.html?q=upsell - - " - - - Do not hyphenate or use as two words. No adjectival form is currently recognized. - - - - - - - - - upstream - - - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream." - - - - - - - uptime - - - n. Correct. Do not use "up-time" or "up time." - - - - - - - URL - - - n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. - - - See for more information. - - - - - - - user - - - n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. - - - If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." - - - - - - - user interface - - - n. Correct. Do not use "user-interface" or "userinterface." - - - 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. - - - - - - - user name - - - n. Correct. Do not use "username" unless you are using it as a variable. - - - - - - - user space - - - n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space." Do not use "userspace." - - - - - - - utilize - - - Avoid this term. Write "use" instead. - - - - - - - - - diff --git a/tmp/en-US/xml/V.xml b/tmp/en-US/xml/V.xml deleted file mode 100644 index 5ff8aef..0000000 --- a/tmp/en-US/xml/V.xml +++ /dev/null @@ -1,137 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - V - - - VAR - - - Acronym for value-added reseller. Same as OEM (original equipment manufacturer). - - - - - - - VDSM - - - Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. - - - - - - - vi - - - Correct. Use all lowercase letters. Do not use "VI" (all caps). - - - - - - - Vim - - - Correct when referring to the application. Do not use "VIM" (all caps). Only use "vim" (all lowercase) when referring to the command to start the application. - - - 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. - - - - - - - video mode - - - Correct. Do not use "video-mode" or "videomode." - - - The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. - - - - - - - virtual console - - - Correct. Do not use "virtual-console" or "Virtual Console" for general use. - - - It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." - - - - - - - virtual machine, VM - - - Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - - - It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. - - - - - - - virtualized guest - - - The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." - - - See also "guest operating system." - - - - - - - virtual router - - - An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. - - - - - - - VNIC - - - Abbreviation for virtual network interface card. Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. - - - - - - - VPN - - - Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. - - - - - - - - - diff --git a/tmp/en-US/xml/W.xml b/tmp/en-US/xml/W.xml deleted file mode 100644 index cd136b8..0000000 --- a/tmp/en-US/xml/W.xml +++ /dev/null @@ -1,121 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - W - - - WAN - - - A computer network that spans a relatively large geographical area. Typically, a WAN consists of two or more local-area networks (LANs). - - - Computers connected to a wide-area network are often connected through public networks, such as the telephone system. They can also be connected through leased lines or satellites. The largest WAN in existence is the internet. - - - - - - - WCA - - - An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. - - - WCAs are also called "query applications." - - - - - - - want - - - Use instead of "wish" or "would like." Rephrase to avoid whenever possible. For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." - - - - - - - we suggest - - - Do not use. Use a more direct construction, or use "recommend." For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." - - - - - - - webhook - - - n. One word. Common noun. Capitalize only at the beginning of a sentence. Use alternative capitalization only if it appears as a proper noun. - - - - - - - webpage - - - n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - - - - - - - web UI - - - 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. - - - - - - - who, whom - - - Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. - - - For example: Who owns this phone? To whom does this phone belong? - - - - - - - will - - - Do not use future tense unless it is absolutely necessary. For example, do not write "The next section will describe the process in detail." Instead, write "The next section describes the process in detail." - - - - - - - Window Maker - - - Correct. Do not combine into one word or hyphenate. This is a window manager for the "X Window System." - - - - - - - - - diff --git a/tmp/en-US/xml/WUG_Intro.xml b/tmp/en-US/xml/WUG_Intro.xml deleted file mode 100644 index 32708b8..0000000 --- a/tmp/en-US/xml/WUG_Intro.xml +++ /dev/null @@ -1,54 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Usage Dictionary - - 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. - - - - A note about trademarks - - - 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 <trademark> tag. We do mark Red Hat's own trademarks. See Copyright Notices and Trademark Legends for more information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml/WUG_References.xml b/tmp/en-US/xml/WUG_References.xml deleted file mode 100644 index 1ef5f6c..0000000 --- a/tmp/en-US/xml/WUG_References.xml +++ /dev/null @@ -1,19 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - References - - the IBM Style Guide - - - Chicago Manual of Style, 17th Edition - - - American Heritage Dictionary - - - - diff --git a/tmp/en-US/xml/XYZ.xml b/tmp/en-US/xml/XYZ.xml deleted file mode 100644 index d720201..0000000 --- a/tmp/en-US/xml/XYZ.xml +++ /dev/null @@ -1,138 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - XYZ - - - X - - - An alternative reference to the "X Window System." Do not use X by itself when referring to "XEmacs." - - - - - - - XEmacs - - - Correct. Do not use "Xemacs." Use "xemacs" only when referring to a command, such as "To start XEmacs, type xemacs." - - - - - - - Xen - - - Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. - - - A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." - - - The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. - - - - - - - xterm - - - Correct. Do not use "Xterm" unless the word is used at the beginning of a sentence. - - - - - - - X Windows - - - Do not use. It is an incorrect reference to the X Window System (or X). - - - - - - - X Window System - - - Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if ..." "To start an X session, from the shell prompt ..." - - - - - - - YAML - - - Recursive acronym for "YAML Ain't Markup Language." Expand on first use only. - - - - - - - you - - - Use second person wherever possible. Do not use "I," "we," "he," or "she." - - - - - - - you may - - - Avoid. For example, "you may" can be eliminated from the following sentence: "You may double-click the desktop ..." - - - - - - - zip - - - See the Word Usage chapter of the IBM Style Guide. - - - - - - - Zip Code - - - Correct. Do not use "zip code," "Zip code," or any other variation. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/0-9.xml b/tmp/en-US/xml_tmp/0-9.xml deleted file mode 100644 index 1ad984c..0000000 --- a/tmp/en-US/xml_tmp/0-9.xml +++ /dev/null @@ -1,43 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - 0-9 - - - 24x7, 24x7x365 - - - adj. Use "24x7" in most instances. Use "24x7x365" only to differentiate from others or highlight specifically that a service is offered every day of the year, for example, providing 24x7x365 phone support. - - - - - - - 2-track (IT) - - - adj. A less common way to refer to bimodal or hybrid IT. See . - - - - - - - 3-D - - - adj., n. Correct. Do not use 3D, 3-d, or other variations. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/A.xml b/tmp/en-US/xml_tmp/A.xml deleted file mode 100644 index 86330f2..0000000 --- a/tmp/en-US/xml_tmp/A.xml +++ /dev/null @@ -1,362 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - A - - - - - "&" and "+" - - - Ampersands or plus signs can be used instead of the word "and" in design elements and graphics when space is limited, and when either referring to or quoting third-party content that uses them. Do not use them in original body copy. - - - - - - above - - - Do not use to refer to information that was mentioned previously. - When documents are converted to online format, the information might no longer be "above." - Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. - - - - - - - - - agile - agile development - - - adj. Use only as an adjective. It is not a proper noun, nor is it owned or trademarked and should not be capitalized. - - - - - - - air gap - air wall - - - n. Use "air gap" to describe systems that are separated, not by software, but physically. Do not use "air wall." "Air gap" is preferred in technical publications because there is no actual wall that you need to breach, but rather a gap that you need to bridge. You cannot break through something that does not exist. - - - - - - all-in-one - allinone - - - n., adj. Hyphenate in both places. Do not use "allinone" or other variations. - - - - - - - - alternate - - - v. "Alternate" as a verb means to change between two states or options. - - - See also . - - - - - - - - alternative - - - adj. Describes another way or method of doing something. - "Alternate" (vb.) means to change between two states or options. If you mean "another way of doing something," use "an alternative method is to ..." - - - See also . - - - - - - - - - - AM - am - - - Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11 AM". - - - See also . - - - See the IBM Style Guide for a full discussion of how to represent times. - - - - - - - AMD64 - - - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture. - - - The correct term for AMD's implementation of this architecture is "AMD64." - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - - - See also . - - - - The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the AMD Trademark Information page at . - - - - For more information about Intel® trademarks, see and . - - - - - - - - - and/or - - - Avoid if possible. - Try to rewrite to make the available options explicit and clear. - Do not write this and/or that. - Write this or that, or both. - - - - - - - - - Applixware - Applix - ApplixWare - - - "Applixware" is correct. - Do not use "Applix" or "ApplixWare." - - - - - - - architect - - - Do not use as a verb. - Even though it might make sense in the correct context, using it as a verb can be jargon or be unclear for your audience. - Use "design," "build," "create," or another descriptive verb instead. - Before replacing the verb form of "architect" during the editing process, clarify with the writer the intended meaning. - For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." - - - - - as well as - - - Not interchangeable with "and." - "As well as" used in a series places more emphasis on the items preceding it, whereas "and" places equal weight on all items in the series. - For example, "We sell kitchen electronics and china, as well as some gourmet foods." - But "We sell kitchen electronics, china, and silverware." - - - - - - - as-a-Service - - - Some as-a-Service acronyms overlap. - To avoid confusion, always spell out the full term on first use. - - - - - DRaaS (Disaster Recovery-as-a-Service) - - - - - - CaaS (Cloud-as-a-Service, Communications-as-a-Service, ) - - - - - - UCaaS (Unified Communications-as-a-Service) - - - - - - FaaS (Functions-as-a-Service) - - - - - - SaaS (Search-as-a-Service, Security-as-a-Service, Storage-as-a-Service, or Software-as-a-Service) - - - - - - PaaS (Payments-as-a-Service, Platform-as-a-Service) - - - - - - MaaS (Messaging-as-a-Service) - - - - - - SECaaS (Security-as-a-Service) - - - - - - TDBaaS (Time-series Database-as-a-Service) - - - - - - - When using as-a-Service acronyms: - - - - - Capitalize the noun (such as Platform, Software, Infrastructure) and Service, both when abbreviated and when written out. - - - - - - When in all capitals, such as a title or headline, the "aa" in the acronym remains lowercase (such as INTRODUCTION TO PaaS SOLUTIONS). - - - - - - - Hyphenate when written out: Thing-as-a-Service. - For two-word prefixes, do not include a hyphen between the first and second words, for example: Mobile Backend-as-a-Service. - It can be used as an adjective to describe multiple: for example, when referring to IaaS, PaaS, and SaaS, use as-a-Service offerings, as-a-Service products, or similar wording. - - - - - - Avoid use of an acronym if it could stand for more than one term in a single asset. for example, if you are writing content that discusses both Cloud-as-a-Service and Containers-as-a-Service. - - - - - - - - - - - - as long as - - - Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that". - - - - - - - ATM - - - Initialism for Asynchronous Transfer Mode, a network technology based on transferring data in cells or packets of a fixed size. - The cell size used with ATM is relatively small compared to units that are used with older technologies. - - - - - - - - - autofs - - - Always lowercase. - It refers to the kernel-based automount utility. - No other forms are recognized. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Author_Group.xml b/tmp/en-US/xml_tmp/Author_Group.xml deleted file mode 100644 index ab048b7..0000000 --- a/tmp/en-US/xml_tmp/Author_Group.xml +++ /dev/null @@ -1,18 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Red Hat Documentation Team - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/B.xml b/tmp/en-US/xml_tmp/B.xml deleted file mode 100644 index 3f1d05b..0000000 --- a/tmp/en-US/xml_tmp/B.xml +++ /dev/null @@ -1,437 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - B - - - back end, back-end - - - n. Two words. Refers to software that performs the final stages of a process, or to tasks that are not visible to the user. For example, "each back end provides a set of calls." - - - adj. Hyphenate. For example, "when the back-end database processes a search operation …" - - - Do not use "backend." - - - See also - - - - - - - backup, back up - - - Write as one word as an adjective or noun, or as two words as a verb. - - - - - - adj. One word. For example, "store the backup copies of important files in a secure location." - - - - - - n. One word. For example, "create a backup of your important files." - - - - - - v. Two words. For example, "always back up important files." - - - - - - - Do not use the hyphenated form, "back-up." - - - - - - - backtrace - - - n. "Backtrace" is the most common term to refer to a stack trace (or stack backtrace), which is a report of the active stack frames (that is, function calls) at a certain point in time during the execution of a program. In contrast, the Python programming language calls its stack trace a "traceback," possibly because the stack frames are printed in the opposite order of those presented by gdb, the GNU Debugger. "Traceback" is the preferred term when referring to a Python stack trace. - - - - - - backwards - - - Avoid using "backwards" unless you are stating that something has "backwards compatibility." - - - - - - - backwards compatible - - - Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also . - - - - - - - - bandwidth - - - Correct. Bandwidth can refer to a range within a band of frequencies or wavelengths, or the amount of data that can be transmitted in a fixed time. - - - - - - - bare metal, bare-metal - - - n. Two words. - - - adj. Hyphenate. - - - - - - - basically - - - Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also . - - - - - - - because, since, as - - - Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" and "as" to indicate the passage of time. - - - - - - - below - - - Do not use to refer to information that follows later in a document. When documents are converted to online format, the information might no longer be "below." Use a cross-reference instead. - - - - - - - big data - - - n., adj. Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. See also . Big data is also never hyphenated, per AP style, even when used as a complex adjective. - - - - - - - bimodal IT - - - Gartner phrase for the combination of traditional (mode 1 or type 1) and modern (mode 2 or type 2) IT infrastructure and resources. Many ways exist to describe this combination approach; be sure to use the right phrase for your audience. Using only the Gartner term can alienate other analysts or those who are not familiar with Gartner's phrasing. - - - The practice of having both modes together is often referred to as hybrid, agile, or modern IT. - - - - Hybrid IT is a more general term, for example it could mean on-premises plus public cloud. Agile and modern IT can both carry an implication of "mode 2", so when using those terms, be specific about the exact technology combination that you mean. - - - - - - - - - biannual, bimonthly, biweekly, semiweekly, semimonthly - - - People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. - - - Instead of biweekly, write "every two weeks" or "every other week." - - - Instead of semiweekly, write "twice a week." - - - - - - - BIND - - - Correct when referring to the DNS software. Do not use Bind. - - - - - - - BIOS - - - Correct. The plural form is BIOSes. - - - - - - - bit rate - - - Correct. Do not use "bitrate." - - - - - - - Boolean - - - Correct. Named after George Boole, who first developed the concept. - - - According to the IBM Style Guide, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type. - - - - - - - boot - - - v. To load the first piece of software that starts a computer. Because the operating system is essential for running all other programs, it is usually the first piece of software to load during the boot process. - - - n. Refers to starting up a computer, which involves loading the operating system and other basic software. A cold boot refers to starting a computer that is turned off. A warm boot refers to resetting a computer that is already running. - - - Boot is an abbreviation of bootstrap, which in olden days was a strap attached to the top of your boot that you could pull to help to get your boot on. Hence, the expression "pull yourself up by the bootstraps." Similarly, bootstrap utilities help the computer to get started. - - - - - - - boot disk - - - Two words. Do not use "boot diskette." - - - - - - - boot loader - - - Two words. Do not use "bootloader." - - - - - - - bottleneck - - - One word. Do not use "bottle neck" or "bottle-neck." - - - A bottleneck refers to the delay in transmission of data through the circuits of a computer's microprocessor or over a TCP/IP network. The delay typically occurs when a system's bandwidth cannot support the amount of information that is being relayed at the speed that it is being processed. However, many factors can create a bottleneck in a system. - - - - - - - bpp - - - Initialism for bits per pixel. All letters are lowercase, unless at the beginning of a sentence. Use a non-breaking space between the numeral and the units. For example, "16 bpp," not "16bpp." - - - - - - - Bps, bps - - - The abbreviation of bytes per second is Bps. The abbreviation of bits per second is bps. To avoid confusion, do not use at the beginning of a sentence. See also . - - - - - - - breadcrumb trail - - - See the IBM Style Guide for initial guidance on how to use this term. - - - - Do not confuse the breadcrumb trail with the name of the actual page in a user interface. The final breadcrumb in the trail is the name of the page, unless the page itself offers a distinct title. The breadcrumb trail indicates the path that is taken to reach the current page. - - - - - - - Example breadcrumb trail, showing Disks as the actual name of the page. - - - - - Example breadcrumb trail, showing Disks as the actual name of the page. - - - - - - - - break - - - (v.) Do not use to mean "break the system" or similar. For example, "applying an unapproved patch might break the system." Choose an alternative such as "cause the system to fail." - - - - - bring up - - - Do not use. Use "open" instead. - - - - - - - Britain - - - If referring to the language, say "English." If referring to the country, say the United Kingdom of Great Britain and Northern Ireland, or the UK. Using Britain or British is usually wrong and might imply a subjective statement about the state of Northern Ireland. - - - - - - - broadcast - - - To send the same message simultaneously to multiple recipients. Broadcasting is a useful feature in email systems. - - - - In networking, a distinction is made between broadcasting and multicasting. Broadcasting sends a message to everyone on the network whereas multicasting sends a message to a selected list of recipients. - - - - - - - Btrfs - - - A copy-on-write file system for Linux. Use an uppercase "B" when referring to the file system. When referring to tools, commands, and other utilities that relate to the file system, be faithful to those utilities. - - - See for more information on this file system. - - - See for a list of file system names and how to present them. - - - - - - - bug fix - - - Two words. Do not use "bugfix." - - - - - - - built-in - - - adj. Hyphenate. Do not use "builtin" unless referring specifically to "Bash builtins" or if it is otherwise a proper noun. - - - - - - - bunches of - - - Do not use, unless "bunch" is a specific term that is used in the documented software. Use "many" or some other alternative instead. - - - - - - - button - - - Describe a GUI button as a "button," not a "pushbutton" or "push-button." - - - Ordinarily you would not include the text "button" in a procedure or description. For example, "Click OK to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the Download link." - - - See also . - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Book_Design.xml b/tmp/en-US/xml_tmp/Book_Design.xml deleted file mode 100644 index d182a6d..0000000 --- a/tmp/en-US/xml_tmp/Book_Design.xml +++ /dev/null @@ -1,146 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Overall Book Design - - This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. - - - This section covers the following topics: - - - - Titles and subtitles - - - - - - Prefaces - - - - - - Abstracts - - - - - - Introductions - - - - - - Unused heading titles - - - - - - - -
- Titles and Subtitles - - The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". - - - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". - - -
-
- Prefaces - - The brands that form part of Publican contain a preface as part of the common content. Whether your publication is for external Red Hat customers, JBoss customers, internal customers, or whomever, the brand you choose should provide a suitable preface. Try to use the standard preface to help maintain consistency, reduce overhead and maintenance, and also to reduce translation costs. If you feel that the preface fails to meet your needs, consider whether or not you are using the correct brand, or if the brand itself requires an update. - - -
-
- Abstracts - - Abstracts for Red Hat technical documentation typically fall under the heading of a "descriptive abstract." From Wikipedia, "The descriptive abstract, also known as the limited abstract or the indicative abstract, provides a description of what the paper covers without delving into its substance. A descriptive abstract is akin to a table of contents in paragraph form." - - - - - - A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: - - - - What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." - - - - - - How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." - - - - - - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." - - - - - - - - - Drawing these basics together might produce the following example abstract: - - - "The Red Hat Satellite 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." - - - Update or modify each component according to the type of book that you are writing. - - -
-
- Introductions - - The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product. - - -
-
- Unused Heading Titles - - This section lists various heading titles that might be used in Red Hat technical documentation, but that should be avoided except in specific circumstances. - - - Overview - - Do not use "overview" as a title. No justification was found for using it as a title; anywhere that it might be considered is already covered by either better or more common titles. - - - - - About - - Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview." - - - - - Chapter and Section Introductions - - Do not create separate introductions for chapters and sections. Use any material that would constitute an introductory section to form body text following the chapter or section title. - - - - -
- -
- diff --git a/tmp/en-US/xml_tmp/Book_Info.xml b/tmp/en-US/xml_tmp/Book_Info.xml deleted file mode 100644 index cbd073a..0000000 --- a/tmp/en-US/xml_tmp/Book_Info.xml +++ /dev/null @@ -1,31 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Conventions for Writers and Editors - - The Red Hat Style Guide - - 4.2 - 1 - - - The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat. It is intended as a supplement to the titles listed in - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/C.xml b/tmp/en-US/xml_tmp/C.xml deleted file mode 100644 index d7e01a4..0000000 --- a/tmp/en-US/xml_tmp/C.xml +++ /dev/null @@ -1,544 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - C - - - can, may - - - Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If any of "can," "could," or "may" apply, use "can"; it is less tentative. - - - - - - - cannot - - - Correct, as one word, when used in the negative form. For example, "you cannot end a sentence with a preposition." Do not use "can not." When used as an additive, use two words. For example, "you can not only end a sentence with a preposition, but you can also start a sentence with a conjunction." - - - - - - - CapEx, OpEx - - - Correct. These stand for "capital expenditures" and "operating expenses" respectively. Do not use alternative capitalization. - - - - - - - cd, CD - - - When referring to the change directory command, use cd. - - - When referring to a compact disk, use "CD." For example, "Insert the CD into the CD drive." The plural is "CDs." - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - CD #1 - - - When referring to a specific CD in the Red Hat Enterprise Linux CD set, it is correct to refer to it as: Red Hat Enterprise Linux CD #1. Avoid using Red Hat Enterprise Linux CD 1. - - - - - - - Ceph - - - Correct. Ceph is a distributed storage platform that provides object, block, and file storage. - See - - Do not use alternative capitalization. - - - - - - - cgroup - - - Correct (all lowercase) when referring to the kernel-based technology. It is a contraction of control group, and not a proper noun in itself; proper nouns use initial caps. It is therefore permissible to capitalize it if used at the beginning of a sentence. - - - Where cgroup refers to something else, for example, a package name, file name, and so on, use a literal rendition. - - - - - - - characters - - - Do not use "characters" to mean "bytes." In English, bytes and characters can be used interchangeably; in other languages, a single character might consist of multiple bytes. - - - In computer software, any symbol that requires one byte of storage. This includes all the ASCII and extended ASCII characters, including the space character. In character-based software, everything that appears on the screen, including graphics symbols, is considered to be a character. In graphics-based applications, the term character is generally reserved for letters, numbers, and punctuation. - - - - - - - check - - - Avoid. Use "verify," "ensure," or "read," depending on the context. - - - - - - - check box - - - n. Two words. Do not use "checkbox" or "check-box." - - - - - - - chipset - - - n. One word. Do not use "chip set" or "chip-set." - - - - - - - CI/CD - - - Define on first use; generally continuous integration/continuous delivery. It does not mean continuous development, a term with questionable usefulness and only marginal adoption. - - - See also , , . - - - - - - - ciphertext - - - n. One word. Do not use "cipher text", "cipher-text", or other variants. - - - - - - - click - - - v. Use when referring to a GUI control button, for example, "Click OK." Do not use "click on". - - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - client-side, client side - - - adj. Use the hyphenated form as an adjective. For example: "Winbind is a client-side service to connect to Windows NT servers." - - - - n. Use the two-word form as a noun. For example: "Winbind runs on the client side of a client/server Samba implementation." - - - - - - - clobber, clobbered - - - Avoid these and similar terms unless they are the actual name of something. Use "altered," "invalidated," or "overwritten," or whatever is appropriate in the context. - - - - - - - cloud - - - Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." - - - - - - - cloudbursting - - - Define briefly on first use. - - - Refers to the event where a private cloud exceeds its capacity and "bursts" into and uses public cloud resources. The advantage of such a hybrid cloud deployment is that an organization pays only for extra computing resources when they are needed. - - - - - - - - - - cloudwashing - - - Define briefly on first use. - - - Refers to the process of rebranding legacy products to include the term "cloud" to increase their appeal to the cloud market, even if such inclusion is not completely justified. - - - - - - - code - - - n. Use only as a noun, not a verb. Use "write" for a verb. - - - - - - - - - colocate, colocation - - - Write unhyphenated, to refer to people or services in the same location. - - - - - - - combo-box - - - Do not use as an abbreviation for "combination box." See the relevant entry in the IBM Style Guide for further usage information. - - - - - - - comma-delimited - - - adj. Correct (compound adjective). A data format in which each piece of data is separated by a comma. This is a popular format for transferring data from one application to another, because most database systems are able to import and export comma-delimited data. - - - - - - - comma-separated values (CSV) - - - Use this in preference to "comma-delimited values" whenever possible. The initialism CSV is widely used to denote information that is broken up through use of commas. This method is often used to share data between different, but similar applications, wherein the comma is a translator of the data. - - - - - - - command button - - - Use "button" instead. - - - - - - - command-driven - - - adj. Correct (compound adjective). Do not use "command driven" or "commanddriven." - - - Refers to programs and operating systems that accept commands in the form of special words or letters. In contrast, programs that provide a list of options in a menu are said to be menu-driven. - - - - - - - command language - - - n. The programming language through which a user communicates with the operating system or an application. For example, the DOS command language includes the commands DIR, COPY, and DEL, to name a few. The part of an operating system that responds to operating system commands is called the command processor. - - - With graphical user interfaces, the command language consists of operations that you perform with a mouse or similar input device. - - - - - - - command line, command prompt, command-line - - - See the appropriate entries in the IBM Style Guide for an explanation of how to use these terms. - - - - - - - commodity - - - Avoid using "commodity" when referring to hardware, including servers or storage, because it implies that the hardware is undifferentiated and might imply that it is cheap. Use instead: - - - - - Volume - - - - - - Industry-standard - - - - - - - - - - - communication service provider (CSP) - - - Another way to refer to a telecommunications provider. See also . - - - - - - - Containers-as-a-Service - - - The term "Containers-as-a-Service" is owned by Docker and should be used only when referring to that company's offering. See also . - - - - - - - container-based - - - Used to refer to more complex applications with multiple services that are distributed in containers. More common than "containerized." - - - - - - - containerized - - - Used to refer to an application or service that is distributed in a container or packed in a container. - - - - - - - continuous delivery (CD) - - - A software implementation architecture that ensures that all approved code can be easily pushed to production. - - - - - - - continuous deployment - - - A special case of continuous delivery, where approved code is automatically pushed to production. Do not use "CD" to refer to this practice. - - - - - - - continuous integration (CI) - - - A software development architecture where the developer code branch is synchronized with the main code branch multiple times per day. Development always works with the current code base. - - - - - - - - - control character - - - A special, non-printing character that begins, modifies, or ends a function, event, operation, or control operation. The ASCII character set defines 32 control characters. Originally, these codes were designed to control teletype machines. Now, however, they are often used to control display monitors, printers, and other modern devices. - - - - - - - control key - - - Use Ctrl instead, such as "To save the program, press CtrlS." - - - - - - - control program - - - A program that enhances an operating system by creating an environment in which you can run other programs. Control programs generally provide a graphical interface and enable you to run several programs at once in different windows. - - - Control programs are also called operating environments. - - - - - - - - cookie - - - n. A message given to a web browser by a web server. - The browser stores the message in a text file named cookie.txt. - The message is then sent back to the server each time the browser requests a page from the server. - - - - - - - - CR - - - Use if referring to code, such as "Type CR at the end of each line ..." If referring to the keyboard key, use either Enter or Return, depending on the platform. - - - - - - - crash - - - IBM recommends the use of "fail" rather than "crash." Use the latter only if you can justify why "fail" is inadequate. - - - - - - - cross-platform - - - adj. Hyphenate. Do not use "crossplatform" or "cross platform." - - - Refers to the capability of software or hardware to run identically on different platforms. - - - - - - - cross-site scripting - - - Correct. When referring to cross-site scripting attacks, use "cross-site scripting attack." Acceptable use is also "cross-site scripting (XSS) attack." - - - - - - - CVE - - - n. CVE stands for Common Vulnerabilities and Exposures, and should be capitalized as shown. - See for more information. - - - - - Cygmon - - - Correct. Do not use "CygMon," "cygmon," or "CYGMON." An exception is if a command is being typed (such as cygmon). - - - Refer to it as "Cygmon: a ROM monitor," not "Cygmon: the Cygnus ROM monitor," or "Cygmon: the ROM monitor." - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml b/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml deleted file mode 100644 index d8ebb90..0000000 --- a/tmp/en-US/xml_tmp/Conventions_for_Writers_and_Editors.xml +++ /dev/null @@ -1,65 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - - - Writing Style Guide - - - Recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. - - - - - - - - - - - - - - Usage Dictionary - - - The Usage Dictionary provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling if variations exist. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Cross_references.xml b/tmp/en-US/xml_tmp/Cross_references.xml deleted file mode 100644 index 546c632..0000000 --- a/tmp/en-US/xml_tmp/Cross_references.xml +++ /dev/null @@ -1,57 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Using Cross-references Effectively - - This section contains suggestions on how to use cross-references in the most effective way: that is, so that they work for the reader rather than for the author. - - Formatting is not described in this section. - - - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. - -
- The Additional Information Test - - Is the cross-reference pointing to vital information or additional information? - - - A cross-reference should always point to additional information, not to core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure, provide a link to the appendix. - - -
- -
- The Repeatability Test - - Must the information be repeated? - - - 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. - - - Cross-referencing is a good servant but a poor master. Content still rules! - - -
- - - diff --git a/tmp/en-US/xml_tmp/D.xml b/tmp/en-US/xml_tmp/D.xml deleted file mode 100644 index dd4085f..0000000 --- a/tmp/en-US/xml_tmp/D.xml +++ /dev/null @@ -1,343 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - D - - - daisy chain - - - n. A hardware configuration in which devices are connected to each other in a series. The SCSI interface, for example, supports a daisy chain of up to seven devices. - - - v. To connect devices in a daisy chain pattern. - - - - - - - dash - - - In technical publications, the IBM Style Guide recommends not to use em dashes or en dashes at all. Use a colon or other suitable punctuation. - - - - - - - data center, datacenter - - - n. Use the two-word form unless referring to a product name or other proper noun where the one-word form is used. - - - Marketing Publications Exception - - In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used. - - - - - - - - - data mirroring - - - The act of copying data from one location to a storage device in real time. Because the data is copied in real time, the information that is stored from the original location is always an exact copy of the data from the production device. Data mirroring is useful in the speedy recovery of critical data after a disaster. Data mirroring can be implemented locally or offsite at a different location. - - - - - - - data sheet, datasheet - - - n. Use the two-word form. - - - Marketing Publications Exception - - In marketing publications, the one-word form is recommended. - - - - - - - - - data source - - - n. Use the two-word form unless referring to a proper noun, argument, variable, or other case where the one-word form is required. - - - - - - - data store, datastore - - - n. Use the two-word form. - - - Marketing Publications Exception - - In marketing publications, the one-word form is recommended. - - - - - - - - - data type - - - n. Do not use "datatype" or "data-type" unless they are variable names or some other literal value. - - - - - - - - - - debug - - - To find and remove errors (bugs) from a program or design. - - - - - - - denial of service (DoS) - - - Correct. Do not use "denial-of-service" or "Denial of Service." - - - - - - - desktop - - - Correct. Do not use "desk top" or "desk-top." - - - - - - - device - - - Any machine or component that attaches to a computer. Examples of devices include disk drives, printers, mice, and modems. These particular devices fall into the category of peripheral devices because they are separate from the main computer. - - - Most devices, whether peripheral or not, require a program called a device driver that acts as a translator, converting general commands from an application into specific commands that the device understands. - - - - - - - DevOps - - - n., adj. A portmanteau that combines "development" and "operations." It refers to a specific method or organizational approach where developers and IT operations work together to create the applications that run the business. DevOps can also refer to the engineers and developers who work within these modern IT organizations. - - - - - - - dialog box - - - See the Word Usage chapter of the IBM Style Guide for usage information related to this and similar terms. - - - - - - - different - - - Use "different from" rather than "different than" when the next part of the sentence is a noun or pronoun (that is, two things are being compared). For example: "Form 123 is different from Form 124." - - - - - - - digital transformation - - - Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. - - - - Disk Druid - - - Correct. Do not use "Disk druid," "disk druid," or "diskdruid." This is a partitioning tool that is incorporated into Red Hat Enterprise Linux. - - - - - - - disk, disc - - - Use "compact disc," but "diskette" or "hard disk." See the IBM Style Guide for more information and example use cases. - - - - - - - - disk label - - - Correct. Do not use "disklabel" or any other variations. - - - - - - - - display - - - v. Use only as a transitive verb. For example, write "the system displays a message" or "the message is displayed" (not "the message displays"). - - - - - - - DNS - - - Initialism of Domain Name System (or Service), an internet service that translates domain names into IP addresses. - - - - - - - documentation - - - When referring to the current manual set, use "documentation." For example, "This manual is also available as part of our online documentation." When referring to another manual, quote the title of the manual, for example, "See the Getting Started Guide for further information." - - - - - - - domain name - - - Correct. Do not use "domainname" or "domain-name." - - - A name that identifies one or more IP addresses. For example, the domain name microsoft.com represents about a dozen IP addresses. Domain names are used in URLs to identify particular web pages. For example, in the URL http://www.redhat.com/docs, the domain name is redhat.com. - - - - - - - double-click - - - v. Always write hyphenated. - - - - - - - downstream - - - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." - - - - - - - downtime - - - Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." - - - - - - - download - - - v., n. Do not use "down load" or "down-load." - - - - - - - dual-boot - - - adj. Do not use "dualboot" or "dual boot." - - - - - - - DVD writer - - - Correct. Do not use the colloquial terms "DVD burner" or "CD burner" (use CD writer in the latter case). - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Design.xml b/tmp/en-US/xml_tmp/Design.xml deleted file mode 100644 index ed0ba05..0000000 --- a/tmp/en-US/xml_tmp/Design.xml +++ /dev/null @@ -1,1035 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Design - -
- Heading Styles - - This section covers various aspects of heading styles and design. - If your company or organization has specific requirements in this regard, follow those requirements first. - - - Capitalization - - The standard for all Red Hat technical documentation is title case for all headings and titles. - Diagram labels, table headings, procedure, and formal paragraph titles all fall under this heading, and consequently, standard title case capitalization rules apply. - The currently accepted reference for determining title case is at https://titlecase.com/titlecase. - - - - - Use sentence case for captions, legends, diagram labels, and table column headers. - They are not classified as titles. - - - Marketing and Brand Capitalization Guide - - The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. - - - - - - Punctuation - - - Be frugal with punctuation. - In most cases, avoid semicolons, colons, dashes, and similar punctuation unless part of the actual subject, or a proper name. - Do not use terminating periods. - - - - Avoid Imperative Mood - - Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product". - - - - - See the IBM Style Guide for more information. - - - - Gerunds should be avoided elsewhere. - See . - - - - File Names, Commands, and Related Terms - - When creating chapter and section titles, do not include file, command, or similar names, and do not include DocBook elements. - Instead, focus on the task at hand and introduce the required file and command names in the text. - Including such objects in titles is generally considered poor technical writing practice. - Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. - - - -
-
- Documenting Fonts - - The preferred way to refer to each type of PostScript font is "PostScript Type x," substituting "x" with either 1, 2, or 3, if the problem is specific to a particular type. - - -
-
- Documenting the User Interface - - In all cases, see the IBM Style Guide for initial guidance. - The following sections highlight exceptions or cases that might otherwise cause confusion. - -
- GUI Elements, Punctuation, and Symbols - - When describing GUI elements, do not include punctuation that appears on those elements, unless omission of that punctuation might lead to confusion. - - - For example, for a button labeled Save As..., do not include the ellipsis in the documentation. - - - In most cases, do not include the object type in instructions. - For example, rather than "Click the Save button," write "Click Save." - - - In some cases it is preferred practice to include the object type for the sake of clarity. - Consider the following: - - Preferred Style for Documenting Symbols and Other Special Characters - - Click the + sign. - - - Click the ^ symbol. - - - - If you cannot easily reproduce the symbol, include a screen capture, or a succinct description of the object type, or both. - Use this approach for icons, especially when they have no tooltip or other help text. - - Preferred Style for Documenting Icons - - Click the Upload ( - - - - ) icon to upload the files to the server. - - - - See the UI elements chapter in the IBM Style Guide for more information. - -
- Navigating Through Multiple GUI Options - - Use "Navigate to" when moving through multiple GUI 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. - - - From example, "From the OpenShift web console, navigate to Monitoring → Alerting." - - -
-
-
- Starting Applications from the Desktop - - This section describes how to start applications from a Red Hat Enterprise Linux-based distribution. - - - RHEL 8 uses the following approach to starting applications from the desktop. - In an effort to maintain consistency and to make translation easier, Red Hat documentation assumes use of GNOME Classic, the default user interface, and prefers a consistent approach to instructing customers how to start applications. - - - The preferred approach is to use the Super key to enter the Activities Overview, to enter the name of the required application, and to press Enter. - The Super key appears in various guises, depending on the keyboard and other hardware, but often as either the Windows or Command key, and typically to the left of the Spacebar. For example: - - - Preferred Approach to Starting Applications from the Desktop - - To start gedit, press the Super key to enter the Activities Overview, type gedit, and then press Enter. - - - - -
-
- Documenting Command Terminology and Syntax - - Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here. - - - When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses. - Never use "flag" when referring to command-line options in POSIX, even though Microsoft often uses the term "flag" when referring to single-character options in Microsoft Windows. - - - The following extract from info libc is of particular interest here: - -
- - "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on. - - - See info libc argument syntax for the full discussion. - -
- - See info bash and the IBM Style Guide for further guidance. - - - The following examples are intended to highlight correct usage. - - - Cloning a Git Repository - - -$ git clone [username@]hostname:/repository_filename [directory] - - - - - - In , the entire command consists of the following components: - - - - The prompt ($) - - - Indicates that a normal user can run the command, as compared to the root user, which would be indicated by the number sign (#). - - - - - - - The command (git clone) - - - The actual command to run, without any optional or replaceable values. - It must be typed as-is. - - - - - - - Source options [username@]hostname:/repository_filename) - - - The optional user name, indicated by brackets ([]), followed by the host name and path to the repository. - All aspects of this component must be replaced with valid values. - - - - - - - Target options [directory] - - - The optional directory into which the repository will be cloned. - It must be replaced with a valid value, or be omitted. - - - - - - - - - Securely Copying a File Between Hosts - -$ scp filename [username@]hostname:/directory - - - - - In , the entire command consists of the following components: - - - - The command prompt ($) - - - - - - - - - - The command (scp) - - - - - - - - - - Source options (filename) - - - The file name to copy. It must be replaced with a valid value. - - - - - - - Target options ([username@]hostname:/directory) - - - The optional user name, indicated by brackets ([]), followed by the host name and path to the target directory. All aspects of this component must be replaced with valid values. - - - - - - - - - - In most cases, avoid using the and options on most commands, especially when logged in as the root 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: - - -[root@serverc pam.d]# rm -f system-auth password-auth -[root@serverc ~]# yum install -y new-package - - - In these examples, omit the and options, respectively. - - - In some cases, such as in Ansible Playbooks or other automation scripts, it might be necessary to use these options. - - - -
- Documenting Multiple or Long Commands - - 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, include the commands on consecutive lines: - - - Documenting Multiple Commands - -$ cd Documents -$ vi myFile.txt - - - - - If the commands are long, complex, or wrap over multiple lines, two design options are available. - - - - - Use line continuation characters and the associated PS2 prompts. - If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit. - - - - - Use neither line continuation characters nor the associated PS2 prompts. - - - - - - Do not mix these two styles. - Maintain the same style throughout your document or book. - - - - You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required. - You can use this option for either of these two designs. - - - - Wrapping Long Commands with Continuation Characters - - This example uses both continuation characters and PS2 prompts. - These indicators are always used together. - - -# tar --selinux -czvf config_files.tar.gz /etc/katello \ -> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \ -> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \ -> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \ -> /root/ssl–build /var/www/html/pub/* /var/lib/katello - - -Wrapping Long Commands Without Continuation Characters - - This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help to clarify long commands. - -# cd /var/lib/katello - -# myCommand --option funky --color=true - --config_file=<replaceable>/home/user/config.conf</replaceable> - --output_file=<replaceable>/home/user/output.txt</replaceable> - - - -
- -
- Referring to Replaceable Paths - - To refer to a path that users need to replace with something that is specific to their system, use <replaceable> tags, the correct syntax for the system and object in question, and an indicative name. - Use a leading slash if the absolute path is required. - - Referring to Replaceable Paths on Linux Systems - - "Mount the ISO file in <filename><replaceable>/path/to/iso/file</replaceable></filename>." - - - - Remember to use the appropriate syntax for the system that you are documenting or describing. - - Referring to Replaceable Paths on Microsoft Windows Systems - - - "Mount the ISO file in <filename><replaceable>C:\path\to\iso\file</replaceable></filename>." - - - - If you are referring to a different object class or type with different delimiters, use the appropriate delimiters. - For example: - - - A PATH variable for Bash might appear as <replaceable>/usr/bin:/usr/local/bin</replaceable>. - - - A package path in Lua might appear as <replaceable>local.share.lua</replaceable>. - -
- -
-
Using Escalated Privileges Correctly - - - This section is aimed primarily at Red Hat Training course material, but the principles and guidelines apply equally in any environment. - - - - The term escalated privileges 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. - - Classroom Exceptions - - Although security is important, it is more important that classroom security does not unnecessarily distract from the immediate topic that is being taught. - - -
General Recommendations - - - These are recommendations, not rules. - As in most matters, consistency is important. - Do not swap between different approaches without reason. - Choose which approach works best for your situation and use it consistently. - - - - - - In all cases, use the minimum required privilege level to achieve the task. - - - - - In exercises, use sudo and sudo -i and set it up to work throughout all relevant systems in the classroom. - Do not use su - without good cause. - - - - - When a scattered minority of privileged commands occur in a mostly unprivileged exercise, use sudo on a per-command basis. - - - - - When the exercise is majority privileged, or has many privileged commands, use sudo -i, either at the beginning of the exercise, or at an appropriate step where the privileged commands begin. - - - - - In the narrative, do not show the use of su or sudo, but always show privileged commands with the correct prompt. - See for information about command prompts. - - - -
-
Exceptions - - Some courses are specifically designed to teach sudo and its variations, the use of the related files, such as /etc/sudoers, and so on. - For these courses, use the required variation for the topic that is being taught. - -
Ansible Courses - - - - Ansible courses typically use a devops user with passwordless sudo access (devops ALL=(ALL) NOPASSWD: ALL) on managed nodes to enable the use of become without a become password as root to do anything. - - - - - As much as possible, leave the system-wide default as become: false or become: no and if a single task needs privileges, set become: true or become: yes on that task. - - - - - If most tasks in a play require escalated privileges, set the entire play to become: true or become: yes and possibly selectively set individual tasks to become: false or become: no. - - - -
-
- - -
- -
- Describing How to View and Edit Files - - To describe how to view and edit files, such as configuration files, scripts, and so on, do not include editor names as part of the guidance, unless the topic is about a specific editor, or is otherwise necessary to achieve a wanted result. - - - For example, do not refer to cat or vi if you need to tell readers to "view the my-script file." If you need to tell readers to edit a file and add or remove content, write "Edit the my-script file and add the following content:" and then include the required content in a <screen> block. Use <code> tags to highlight the text to change. Include some surrounding text in the file for context. Do not use line numbers as a reference point because they can change. - - - If the file to edit is empty or does not exist, do not use <code> tags to highlight any content to add. - - - You can also use here documents to describe how to create a file with required content. The syntax of here documents varies by system, shell, language, and so on. The following example creates the my-script file in the current directory, with the example content. - - - my-script -> # The first line of text -> # The second line -> # Start adding variables after this line -> EOF]]> - - In some cases, it is necessary to indicate which tool to use to view a file, especially for log files and other long files. In these cases, suggest a viewer based on the operating system or environment in which you are working, such as tail, head, less, or journalctl. - - -
-
- Using Host and User Names Correctly - - Many examples in Red Hat documentation require the use of user names, host names, IP addresses, and similar information. In an effort to reduce security risks, to minimize translation overhead, and to maintain consistency, Red Hat recommends the following approach. - - - - All names are lowercase. Do not use white space in any part of the name. - - - - - - - Use RFC 2606 to determine suitable domain names. For documentation and example purposes, it is typically example.com, example.net, example.org, and example.edu. - - - - Do not use valid, public IP addresses in any examples. - - - - - - - - As much as possible, use user, username, root, admin, or similar names to identify classes of users. - - - Use these generic names when you refer to users outside a case study. It helps students to identify which part of a command to replace, by establishing a consistent format for names of users and system items. For example: - - -[root@fedora ~]# setfacl -m u:user1:rw /project/file1 - - The following list provides further alternatives: - - - - - operator1 to operator9 - - - - - - developer1 to developer9 - - - - - - architect1 to architect9 - - - - - - - - - -
- Using Extended User and Group Names - - Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. - - - Using Realistic User Names - - When you are writing a detailed case study, such as training exercises, reviews, and similar material, use realistic names. These names should not be real people. In other words, do not use the name of an employee, a well-known person, or your neighbor. - - - - - For example, you are the system administrator at Global Banking and you are asked to set up permissions to the accounting directory for the following users: John Doe, Sunni Koning, Huong Sabo, and Jerlene Paluch. John is a department manager and needs read access to the accounting directory. Sunni is the lead accountant and needs both read and write access. - - - Choosing a Realistic Name - - Consider the following points when choosing a realistic name: - Examples taken from the IBM Style Guide and the Google Developer Documentation Style Guide. - - - - - - - - - In examples or scenarios, you can use a person's name and then use a gender-specific pronoun to refer to that name. Vary the use of proper names in documentation. Use names that represent various ethnic backgrounds, genders, and locations. - - - - - - Do not use copyrighted fictional characters in examples, and do not use real people. - - - - - - 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. - - - - - - - Sourcing Realistic Names - - You can use any of the following name generators to create realistic names for users: - - - - - - - https://uinames.com/ - - - - - - http://listofrandomnames.com/ - - - - - - http://www.behindthename.com/random/ - - - - - - http://random-name-generator.info/ - - - - - - - Group Names - - Use any lowercase name that is a logical extension of the accepted user names, without the numerical suffix. For example, architects, developers, operators. - - - - -
- -
- -
-
- Documenting Currencies - - Use local currency symbols wherever possible. If symbol clash occurs (USD versus AUD, for example), disambiguate with the 2-character country code. For example, US$, AU$. - - - - Do not provide currency conversions. - - - - -
-
- Using Abbreviations, Acronyms, and Initialisms Correctly - - This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. - - - Abbreviations - - An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated," respectively. Read them as the word for which they are an abbreviation. - - - - - Acronyms - - What are acronyms anyway? They are similar to abbreviations and initialisms but they are pronounced as a word. An acronym is a word that is formed from the initial letters of a name, such as ROM for Read Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. - - - - - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)," because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade," because RAM is an acronym and you pronounce it as a word (răm). - - - - Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ..." - Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)." - Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML. - - - - To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes. - - - - Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. - - - - Initialisms - - An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol. - - - - - Consider pronunciation when using articles. See for more information. - - -
-
- Using Company, Product, and Brand Names Correctly - - Various restrictions apply to using company, product, and brand names in Red Hat documentation. Refer to internal sources for further conditions that might apply to your own products. - - - - In the following sections, "first use" refers to the first use of a name in body text. Titles, banners, and similar objects are not classified as "first use." - - - - - - - Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. - - - - - - Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name. - - - - - - Do not include "Inc." when referring to Red Hat except in legal documents. - - - - - - Use non-breaking spaces to avoid breaking the company name, or product names and their versions, over multiple lines. For example, use a non-breaking space between "Red" and "Hat," and also between "Enterprise," "Linux," and the version number. - - - If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. - - - - - - Do not use non-breaking spaces between "Red Hat" and any product name. Consider the following DocBook XML examples: - - - - - Standardize on Red&nbsp;Hat Enterprise&nbsp;Linux. - - - - - - The latest version is Red&nbsp;Hat Enterprise&nbsp;Linux&nbsp;8.0 - - - - - - - For other markup languages, use the equivalent non-breaking space character. - - - - - Do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between "Linux" and "OpenStack", nor between "OpenStack" and "Platform." - - - - - - Do not use non-breaking spaces with other companies' product names. - - - - - - Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..." - - - - In this case, "Platform" is part of the product name. In other cases, words like "platform," "manager," and so on might not be part of the product name, in which case an article is acceptable, if not necessary. - - - - - - - - -
-
- Using Version Numbers Correctly - - The preferred format for product names includes only the major version number. For example: - - - - Red Hat Enterprise Linux 8 - - - - - - JBoss Enterprise Application Platform 3 - - - - - - - - - When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version. - - - Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example: - - - - Red Hat Enterprise Linux 5.2 was released on October 12, 2010. - - - - - - <Application name> was first included in JBoss Enterprise Application Platform 3.2. - - - - - - - - - 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. - - - Avoid using the "dot-oh" release number. For example, do not use Red Hat Enterprise Linux 6.0. Use instead Red Hat Enterprise Linux 6. - - - - This rule applies only to Red Hat products. Refer to other companies' products and use their version numbers as they use them. - - - - -
-
- Using Admonitions - - To call attention to a statement, use an admonition. Red Hat technical documentation currently uses Note, Important, and Warning 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 in mind these considerations if using admonitions: - - - - Keep the statements as brief and to the point as possible. - - - - - - Use admonitions sparingly so that they do not lose their effectiveness. - - - - - - Use a Note admonition to bring additional information to the user's attention. - - - - - - Use an Important 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 a Warning 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. - - - - - - - - -
- -
- Making Recommendations - - When making a recommendation, the preferred verbiage is "Red Hat recommends..." instead of the common but indirect "It is recommended...". - Recommendations can include best practices, recommended practices, and product-specific suggestions. - See for information on using the terms "best practices" and "recommended practices" in Red Hat documentation. - - - - (incorrect) - - - "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project." - - - "It is recommended to generate a service account for each microservice in your project." - - - - - (correct) - - - "Although the attack surface is reduced to the same-project traffic, Red Hat recommends creating multiple service accounts within a project." - - - "Red Hat recommends that you generate a service account for each microservice in your project." - - -
- - -
- Citing Other Works - - Referencing Other Books - - When referencing another book, either internal or external to Red Hat, use the following format: - - - - - - - -Book Title by First name Surname; Publisher. - - - - For example, Maximum RPM by - - Edward - Bailey - - - ; Red Hat Press. - - - Referencing Other Internet Sites - - When referencing another internet site, use the following guidelines: - - - - - - - Do not link words within the body text. That is, do not use structures such as "Go here for more information," where "here" is a link. - - - - - - Short URLs, such as http://partner.redhat.com, are OK to use in body text at your discretion. - - - - - - If the URL is excessively long or complex, create a link by using the title of the destination as a label, and put the actual URL in a footnote. For example: See the Classification of Species - http://world-database-of-everything.com/en/classifcation_of_species/mammals.html - - page for more information. - - - - - - -
- - - diff --git a/tmp/en-US/xml_tmp/E.xml b/tmp/en-US/xml_tmp/E.xml deleted file mode 100644 index 976efae..0000000 --- a/tmp/en-US/xml_tmp/E.xml +++ /dev/null @@ -1,195 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - E - - - e-book, e-business, e-commerce, e-learning, email - - - Refer to the primary reference for the type of copy you are creating, either AP or IBM. - - - - - - - - e.g. - - - Red Hat technical documentation always expands these abbreviations. Write out "for example". - - - - - - - earlier - - - Use to refer to earlier releases of products. Do not use "older" or related terms. See also . - - - - - - - Emacs - - - If referring to the program, use "Emacs." For example, "Source-Navigator supports Emacs or vi commands." If referring to the shell prompt command, use "emacs." For example, "At the prompt, type emacs." The complete and correct name is "GNU Emacs." - - - - - - - emdash - - - Used (informally) to indicate a pause or abrupt change in thought; for emphasis; or to set off a series in a phrase. See for more information. - - - - - - - - enter - - - When referring to the keyboard key, use Enter. If referring to the keyboard key on Solaris, use Return. - - - - When referring to typing a command, use "type" instead, such as "To open Source-Navigator from the command line, type snavigator." - - - When typing information into a single-field dialog box, "enter" means "type and press Enter." An example is "enter the license number." For multi-field dialog boxes, see "type." - - - - - - - environment - - - The state of a computer, usually determined by which programs are running and basic hardware and software characteristics. For example, running a program in a UNIX environment means running a program on a computer that has the UNIX operating system. - - - One ingredient of an environment, therefore, is the operating system. But operating systems include many different parameters. For example, in some operating systems, you can choose your command prompt or a default command path. All these parameters together constitute the environment. - - - Another term for environment in this sense is platform. - - - - - - - EOL - - - adj. Initialism for "end-of-line" - - - n. Initialism for "end of line" - - - Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as shown in the GUI. - - - - - - - essentially - - - Do not use. - - - - - - - Ethernet - - - n. Uppercase "E" at all times. - - - - - - - event - - - An action or occurrence that is detected by a program. Events can be user actions, such as clicking a mouse button or pressing a key, or system occurrences, such as running out of memory. - - - - - - - exclamation points (!) - - - Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. - - - - - - - Exec-Shield - - - Exec-Shield is a security-enhancing modification to the Linux kernel that makes large parts of specially marked programs including their stack not executable. - - - - - - - execute - - - Has the same meaning as run. Execute means to perform an action, as in executing a program or a command. - - - - - - - Exif - - - Correct. Do not use "EXIF." Exif is an image file format specification that enables adding metadata tags to existing JPEG, TIFF, and RIFF files. Sometimes referred to as "Exif Print." - - - - - - - extranet - - - Refers to an intranet that is partially accessible to authorized outsiders. Whereas an intranet resides behind a firewall and is accessible only to members of the same company or organization, an extranet provides various levels of accessibility to outsiders. You can access an extranet only if you have a valid user name and password, and your identity determines which parts of the extranet you can view. - - - Capitalize only at the beginning of a sentence. - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Easily_Confused_Words.xml b/tmp/en-US/xml_tmp/Easily_Confused_Words.xml deleted file mode 100644 index 53bf144..0000000 --- a/tmp/en-US/xml_tmp/Easily_Confused_Words.xml +++ /dev/null @@ -1,92 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Easily Confused Words - - This section identifies some easily confused words and how to choose the correct term for your situation. - - - Affect and Effect - - Each of these words can be used as a verb or a noun, but they are not always interchangeable. - - - - - - affect - - - n. Refers to the emotional impact of an action. Unless you are writing a psychology article, this is unlikely to be the choice for you. - - - v. Means to have an influence on something, or to cause something to change. - - - - - - - effect - - - n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." - - - v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." - - - The use of "effect" as a verb is less common than the use of "affect," and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." - - - - - - - - - Assure, Ensure, and Insure - - These are relatively easy to get right, but here are some quick definitions. - - - - - - assure - - - v. Suggests mental comfort. For example, "I assured my future father-in-law that I would eventually find a job." - - - - - - - ensure - - - v. Means to make sure of something, to be certain that something exists or some condition has been met. - - - - - - - insure - - - v. Relates to monetary insurance. - - - - - - - - -
- diff --git a/tmp/en-US/xml_tmp/F.xml b/tmp/en-US/xml_tmp/F.xml deleted file mode 100644 index 452a95b..0000000 --- a/tmp/en-US/xml_tmp/F.xml +++ /dev/null @@ -1,336 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - F - - - fail back, failback - - - v. Use the 2-word form. - - - n. Use the 1-word form. - - - No hyphenated form is currently recognized. - - - - - - - fail over, failover - - - v. Use the 2-word form. - - - n., adj. Use the 1-word form. - - - No hyphenated form is currently recognized. - - - - - - FAQ - - - When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an Q") not "a FAQ." The plural form is "FAQs." - - - - - - - fault tolerance (n.), fault-tolerant (adj.) - - - The ability of a system to respond gracefully to an unexpected hardware or software failure. Fault tolerance has many levels, the lowest being the ability to continue operation in the event of a power failure. Many fault-tolerant computer systems mirror all operations; that is, every operation is performed on two or more duplicate systems, so that if one fails, then the other can take over. - - - - - - - Fedora™ Project - - - Correct. - - - - - - - fiber - - - Correct. Despite the alternative spelling used in Fibre Channel, "fiber" is the correct form to use in all other cases. - - - - - - - Fibre Channel - - - A serial data transfer architecture developed by a consortium of computer and mass storage device manufacturers and now being standardized by ANSI. The most prominent Fibre Channel standard is Fibre Channel Arbitrated Loop (FAL). - - - FAL was designed for new mass storage devices and other peripheral devices that require high bandwidth. Using optical fiber to connect devices, FAL supports full-duplex data transfer rates of 100 MBps. FAL is compatible with, and is expected eventually to replace, SCSI for high-performance storage systems. - - - - - - - file extensions (general usage) - - - See File names, file types, and directory names in the IBM Style Guide. - - - - - - - file mode, file name, file system, file type - - - n. Write as shown, two words, unless used as a variable. See the IBM Style Guide for more information. - - - - adj. Hyphenate when used as a compound adjective. For example, "file-system attributes." - - - - - - - - FireWire - - - Correct. Do not use "Firewire" or "firewire." Although FireWire is a trademark of Apple Computer, it is not needed to append a trademark symbol, except to refer to Apple's FireWire software license or specific logos. See https://www.apple.com/legal/intellectual-property/guidelinesfor3rdparties.html. - - - - - - - - firmware - - - n. Do not use "firm ware" or "firm-ware." - - - Software (programs or data) that is written onto read-only memory (ROM). Firmware is a combination of software and hardware. ROMs, PROMs, and EPROMs that have data or programs recorded on them are firmware. - - - - - - - floating point - - - Correct. Do not hyphenate. - - - - - - - floppy disk - - - Do not use. Use "diskette," and also state the size of the diskette, such as "3.5 in. diskette." - - - - - - - floppy drive - - - Do not use. Use "diskette drive." - - - - - - - - follow - - - v. Refers to the use of the () option for various commands, such as tail, so that output is appended as the file grows. - - - - - - - following - - - When introducing a list or a procedure, use "following" with a noun. Instead of "Complete the following", use "Complete the following steps". - - - - - - foreground - - - - - In multiprocessing systems, the process that is currently accepting input from the keyboard or other input device is sometimes called the foreground process. - - - - - - On display screens, the foreground consists of the characters and pictures that appear on the screen. The background is the uniform canvas behind the characters and pictures. - - - - - - - - - - - fortnight - - - A period of two weeks (14 nights). Avoid; this term is not common in American English and might also be unfamiliar to non-native speakers. - - - - - - - FORTRAN - - - Correct. Do not use "Fortran." - - - - - - - forward - - - Correct. Avoid using "forwards." - - - - - - - forwards compatible - - - Do not use. Instead, use "compatible with later versions." See also . - - - - - - - - FQDN - - - A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels.https://en.wikipedia.org/wiki/Fully_qualified_domain_name - - - For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. - - - An FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. - - - - - - - - frictionless - - - Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also . - - - - - - - front end, front-end - - - n. Two words. For example, "PRCS is a front end for a version control toolset." - - - adj. Hyphenate. For example, "This chapter explains how to use the front-end API functions." - - - Do not use "frontend" as a noun or adjective. - - - See also . - - - - - - - FTP - - - Use all caps when referring to the protocol. Use lowercase when referring to the command-line program. - - - - - - - futexes - - - Correct. "Futex" is an abbreviation of "fast user-space mutex." Consequently, "futexes" is the correct plural form. - - - - - - - - fuzzy - - - Correct only when referring to fuzzy searches. See for details and examples. - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Feedback.xml b/tmp/en-US/xml_tmp/Feedback.xml deleted file mode 100644 index 69ea61a..0000000 --- a/tmp/en-US/xml_tmp/Feedback.xml +++ /dev/null @@ -1,13 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- We Need Feedback - - Raise an issue at with suggestions for improvements, requests for additions, recommendations, and any other updates. - - -
- diff --git a/tmp/en-US/xml_tmp/G.xml b/tmp/en-US/xml_tmp/G.xml deleted file mode 100644 index f07fd91..0000000 --- a/tmp/en-US/xml_tmp/G.xml +++ /dev/null @@ -1,270 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - G - - - g++, G++ - - - When referring to the command, use g++. When referring to the program, use G++. - - - - - - - gas, GAS - - - When referring to the command, use gas. When referring to the program, use GAS. - - - - - - - GB - - - Abbreviation of gigabyte. Depending on the type of content you are writing, refer either to The AP Style Guide or the IBM Style Guide. - - - AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file." - - - IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file." - - - - - - - GbE - - - Correct. Approved abbreviation of Gigabit Ethernet. Do not use GigE or any other variations. Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - Gbps - - - Abbreviation of Gigabits per second, a data transfer speed measurement for high-speed networks such as Gigabit Ethernet. When used to describe data transfer rates, a gigabit equals 1,000,000,000 bits. Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - gcc, GCC - - - When referring to the command, use gcc. When referring to the program, use GCC. - - - - - - - gcj, GCJ - - - When referring to the command, use gcj. When referring to the program, use GCJ. - - - - - - - gdb, GDB - - - When referring to the command, use gdb. When referring to the program, use GDB. - - - - - - - GDBTK - - - Do not use. Use "Insight" instead. GDBTK is an obsolete name for the GNU debugger. - - - - - - - GEO - - - Do not use. Use "region" or "geographical location" according to your needs. - - - - - - - - GFS, GFS2 - - - As of Red Hat Enterprise Linux 6, it is known as the Resilient Storage Add-On. Ensure that you use the correct term. - - - - - - - GID - - - Acronym for Group ID. Do not use "gid." - - - - - - - GigE - - - See . - - - - - - - gigabyte - - - 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - - - - - GIMP - - - Acronym for GNU Image Manipulation Program. Do not use "Gimp" or "gimp." - - - - - - - GNOME - - - Correct. Do not use "gnome," "Gnome," or other variants. See also . - - - - - - - GNOME Classic - - - Correct. Although the desktop team tends to refer to GNOME Classic (technically, GNOME Shell with the classic mode extensions enabled) as "classic mode" in internal and developer-oriented community documents, stay consistent with what is exposed to the user on the GDM login screen, that is, "GNOME Classic". The GNOME "modern mode" (technically, GNOME Shell with the classic mode extensions disabled) is referred to as "GNOME" (on the login screen and elsewhere). - - - - - - - GNU - - - Recursive initialism for "GNU's Not UNIX." Do not use "Gnu" or "gnu." - - - - - - - GNUPro - - - When referring to the Red Hat product, use GNUPro. - - - - - - - got - - - Do not use. - - - - - - - - GPL - - - Initialism for General Public License. Do not use "Gpl" or "gpl." - - - - - - - grayscale - - - n. Correct. Do not use "gray-scale" or "gray scale." Only the noun form is currently recognized. - - - - - - - GRUB - - - Correct. All caps. Do not use "Grub." - - - - - - - GTK+ - - - Initialism for GIMP Tool Kit. Do not use "GTK," "Gtk," or "gtk." - - - - - - - guest operating system - - - Refers to the operating system that is installed in a virtual machine. Do not use "guest" by itself because it is ambiguous. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Grammar.xml b/tmp/en-US/xml_tmp/Grammar.xml deleted file mode 100644 index 2a305c6..0000000 --- a/tmp/en-US/xml_tmp/Grammar.xml +++ /dev/null @@ -1,631 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Grammar - - This section contains information on a few common grammar topics. For subjects not covered here, consult The Chicago Manual of Style, 17th Edition. - -
- Active Voice - - Use the active voice ("Type ... to start Linuxconf.") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count. - - - This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material. - - - For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than - - - "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence. - - - You can also use the passive voice to front-load important keywords in key areas of your content, such as the title, heading, or at the beginning of a paragraph or sentence. You need to make these decisions on a case-by-case basis, weighing the importance of front-loading keywords against content that is readable (that is, not awkward sounding). Consider the following two examples: - - - Active Voice - - "Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization." - - - - - Passive Voice - - "Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion." - - - - -
-
- Agreement - - In grammar, agreement occurs when specific parts of a sentence are coordinated; that is, they agree in number and gender. - - - There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here. Pronoun-antecedent agreement can be a little more problematic, so... - -
- Pronoun-antecedent agreement - - A pronoun is a word that is used in place of a noun (for example, I, he, she, it). An antecedent is a word or phrase to which the pronoun refers. - - - When you are comfortable with subject-verb agreement, pronoun-antecedent agreement often follows as a matter of course. - - - The following is an annotated roundup of pronoun-antecedent rules: - - - Singular and Plural Nouns - - A singular pronoun refers to a singular antecedent; a plural pronoun refers to a plural antecedent. For example: - - - - - - - The CD spins in its caddy. (The singular third-person pronoun "its" refers to the singular antecedent "CD".) - - - - - - The developers checked their work. (The plural third-person pronoun "their" refers to the plural antecedent "developers".) - - - - - - - Collective Nouns - - When collective nouns are used as antecedents, use singular or plural pronouns, depending on the sentence's meaning. For example: - - - - - - - Microsoft seems second to none in its marketing skills. (The collective noun "Microsoft" takes the singular pronoun "its" because the collective noun refers to the group as a whole.) - - - - - - The developers were asked for their preferences. (The collective noun "developers" takes the plural pronoun "their" because the reference is to the individuals of the group.) - - - - - - -
- -
-
- Using Who, Whom, That, and Which Correctly - - Use "whom" or "who" to introduce a qualifying phrase when the antecedent is a person. Use "that" or "which" when referring to a thing. Use "which" or "that" to introduce a qualifying phrase when the antecedent is a concept or an object. Who, whom, that, and which are known as "relative pronouns." - - - Use the following as guidelines: - - - - Who - - - Relative pronoun when persons are the subject. - - - - - - - Whom - - - Relative pronoun when persons are not the subject. - - - - - - - Which - - - Relative pronoun for things. - - - - - - - That - - - Restrictive pronoun for things. - - - - - - - - - Examples: - - - - - The jewel case, which once held the CD, was broken recently. - - - - - - The CD that I received for my birthday is defective. - - - - - - Edward C. Bailey, who wrote "Maximum RPM,"... - - - - - - The company that published "Maximum RPM" was... - - - - - - This book belongs to whomever purchased it last week. - - - - - - Who ate all the cereal? - - - - - - To whom should I address the letter? - - - - - - The desktop that was designed by Earl is not called GNOME. - - - - - - The GNOME developers who worked on the desktop are... - - - - - - The GNOME developers to whom they owe gratitude are... - - - - - - - - To help you choose between who and whom, substitute the person about whom you are speaking with he, she, him, or her. - - - - - - If your restatement contains him, her, them, me, or us, then use whom or whomever. "I'm giving the book to him." "To whom am I giving the book?" - - - - - - If the restatement contains the word he, she, they, II, or we, then use who or whoever. "Do you think he would mind?" "Who do you think would mind?" "She's walking in the door." "Who's walking in the door?" - - - - - - - - -
-
- Sentence Structure - - A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). - - - Consider the following points when constructing sentences: - - - - Sentence Length - - Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: - - - - - The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. - - - Run-on Sentences - - Two or more complete ideas that are joined without punctuation, or separated only by a comma, create a run-on sentence (also called a fused sentence). The sentence does not have to be long to be a run-on sentence, although the longer the sentence the more difficult it is to read. You can: - - - - - - - Separate independent clauses with a period. Doing so will form two sentences out of one. - - - - - - Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. - - - - - - Insert a coordinating conjunction, such as "and" or "but", between the independent clauses to form a compound sentence. For example, "The process starts, but it produces an error." - - - - - - Insert a subordinating conjunction, such as "although" or "because", which forms a compound sentence with a subordinate clause. For example, "Although the process starts, it produces an error." - - - - - - - - - - - - - Example - Improvement - - - - - - - The CDs both of which belonged to the developers were in the test lab. - The CDs, both of which belonged to the developers, were in the test lab. - - - - To access your programs click the Start button. - To access your programs, click Start. - - - - The CDs, both of which belonged to the developers, were in the test lab, because they were the only available CDs for the new release, the developers were anxious about keeping them clean. (This sentence exhibits a comma splice which is also often regarded as a run-on sentence.) - The CDs, both of which belonged to the developers, were in the test lab. Because they were the only available CDs for the new release, the developers were anxious about keeping them clean. - - - - - - - -
- - Sentence Fragments - - A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. - - - - - - Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. - - - - - Telegraphic Style - - Extreme cases of word economy can result in a telegraphic style, omitting words that can clarify the meaning of a sentence, such as articles, prepositions, and verbs used with gerunds. - - - - - - - - - - - Example - Improvement - - - - - - - Click button to start. - Click Initiate to start the process. - - - - - - - -
- - This problem is often encountered in the Revision History. It is important that wording in the Revision History is clear for translators and customers to understand. - - - - - - - - - Example - Improvement - - - - - - - Minor revision - missing element items - Minor revision - added missing element items - - - - Some further work required to avoid 404s at lower levels of the SDK. - Some further work required to avoid 404 errors at lower levels of the SDK. - - - - - - - -
- - - - "That" in Clauses - - Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English, - - - - - - - - - - - Example - Improvement - - - - - - - Verify your directory service is working. - Verify that your directory service is working. - - - - - - - -
- - Verbosity - - Avoid unnecessary words. Keep it succinct. - - - - - - - - - - - Example - Improvement - - - - - - - The individual member of the social community often receives information via visual, symbolic channels. - People read. (Translation by Richard Feynman.) - - - - Perform the installation of the product. - Install the product. - - - - - - - -
- - Word Order - - When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify. - - - - - - - - - - - Example - Improvement - - - - - - - To update the address lists might be your primary concern. - Your primary concern might be to update the address lists. - - - - - - - -
- -
- - - - - -
- Contractions and Abbreviations - - Do not use contractions in Red Hat documents. For example, do not use "can't," "don't," "won't," and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. - - - - Take care also with abbreviations; replace "e.g." with "for example," and replace "i.e." with "that is," and so on. - - -
- -
- Hyphenation - - There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. - - - - Hyphenate for Clarity - - Hyphenate when needed for clarity. Words that begin with prefixes are usually not hyphenated. Prefixes can include "multi," "non," "sub," "co," "semi," "pre," "re," and so on. The same applies to suffixes; for example, "less" as a suffix does not require hyphenation. - - - - - - Always use a hyphen if clarity would suffer otherwise. For example, "He recovered his health" versus "He re-covered the leaky roof." - www.apstylebook.com - - - - - - - Hyphenate Complex Adjectives - - Hyphenate complex adjectives (compound modifiers). This is when two adjectives work together to modify an object. The hyphen is used when the first adjective modifies the second adjective. For example, cloud-based solutions, right-side paralysis, system-wide menu. - - - - - - Do not hyphenate "open source," even when used as a complex adjective. - - - Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. - - - - - Hyphenate Consecutive Vowel Sounds - - Hyphenate words where the prefix ends in a vowel and the word that follows begins with the same vowel. For example, semi-independent, pre-emptive. - - - - - - Exceptions to this rule include cooperate and coordinate. - - - - - Hyphenate Mixed Capitalization - - Hyphenate when the word that follows a prefix is capitalized. For example, un-American, non-British. - - - - - Hyphenate Double Prefixes - - Hyphenate when the word has double prefixes. For example, sub-subparagraph, re-sublet. - - - - -
-
- Gender References - - Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. - - -
-
- Tense - - Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. - - - - Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. - - - Report an issue - - -
- - diff --git a/tmp/en-US/xml_tmp/H.xml b/tmp/en-US/xml_tmp/H.xml deleted file mode 100644 index 92d3e4a..0000000 --- a/tmp/en-US/xml_tmp/H.xml +++ /dev/null @@ -1,302 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - H - - - hard code, hard-coded - - - v. Two words. - - - adj. Hyphenate. - - - Do not use the one-word form. No nominal form is currently recognized. - - - - - - - hard copy - - - Do not use. Use "printed". Under review - - - - - - - - hard disk - - - n. Correct. Do not use "harddisk" or "hard-disk." - - - - - - - hard disk drive - - - n. Correct. Do not use "harddrive" or "hard-drive." - - - - - - - he/she - - - Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. - - - - - - - help desk - - - Typically two words, but use the term accepted by your organization. - - - - - - - healthcare - - - Under review. Need context and example. - - - - - - - - - health check - - - n. Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. - - - This term is only capitalized when part of a product name, for example: - - - - Red Hat Enterprise Linux Server Health Check - - - - - - JBoss Middleware Health Check - - - - - - - - - Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." - - - - - - - hertz - - - n. Correct. Capitalize the "H" only at the beginning of a sentence. The correct abbreviation is "Hz." - - - - - - - high-availability, high availability - - - adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." - - - - n. Two words. For example, "Support is available 24x7 to help maintain high availability." - - - - - - - high-performance computing (HPC) - - - n. Use standard hyphenation guidelines to maintain clarity. - - - - - - - homepage - - - n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - - - - - - - - host group - - - n. Two words. Capitalize the "H" at the beginning of a sentence. See RFC 966 for more details. - - - - - - - host name - - - n. Two words in most cases. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. - - - - - - - hot add - - - v. Two words, lowercase. Capitalize only at the beginning of a sentence. Do not use "hotadd" or "hot-add." - - - - - - - hotline - - - n. One word, lowercase. Capitalize only at the beginning of a sentence. Under review. Need context and example. - - - - - - - - hot plug - - - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotplug" or "hot-plug." - - - - - - - hot swap - - - v. Two words, lowercase. Capitalize when used at the beginning of a sentence only. Do not use "hotswap" or "hot-swap." - - - - - - - hover help - - - See . - - - - - - - HP ProLiant - - - Correct. Do not use any other variations. - - - - - - - HTML - - - When referring to the language, use "HTML," such as "To see the HTML version of this documentation ..." When referring to a web page extension, use "html," such as "The main page is index.html." - - - - - - - huge-page, huge page - - - adj. Hyphenate. Normal hyphenation rules apply. - - - n. Use the two-word version in all cases. Capitalize "huge" at the beginning of a sentence, and capitalize both words in titles. If you are documenting a user interface, use the capitalization that is used in that interface. - - - - - - - hybrid IT - - - The preferred term to refer to IT that spans both traditional and modern infrastructure, or private and public environments, or some combination of them. Because hybrid can indicate either infrastructure or environment, or both, be specific about the underlying combination. See also . - - - - - - - Hyper-Threading - - - n. Hyper-Threading is Intel's implementation of simultaneous multithreading. Do not use "hyperthreading" or "hyper-threading". If you are not referring specifically to Intel's implementation, use "simultaneous multithreading" or "SMT" instead. - - - - - - - hypervisor - - - n. Capitalize only at the beginning of a sentence or as part of Red Hat Virtualization Hypervisor. Do not use "HyperVisor" or "Hyperviser." - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/I.xml b/tmp/en-US/xml_tmp/I.xml deleted file mode 100644 index 2c68839..0000000 --- a/tmp/en-US/xml_tmp/I.xml +++ /dev/null @@ -1,382 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - I - - - IA64 or ia64 - - - Do not use. Always use the term Itanium instead. These terms can be used in file names because they are not visible in the content. - - - - - - - IaaS - - - Correct. This is the correct abbreviation for "Infrastructure-as-a-Service." See also . - - - - - - - - IBM Z - - - IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. - - - - - - - - i.e. - - - Do not use a Latin abbreviation. Instead, write out "that is". - - - - - - - illegal - - - Illegal means "prohibited by law," not "incorrect" or "not permitted." Use "invalid" or a related word. - - - - - - - - - matrixes - - - Correct. This is the correct plural form for US English spelling. Do not use "indices." - - - - - - - - InfiniBand - - - InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. - - - "Open InfiniBand" is deprecated and should not be used. - - - - - - - inline - - - adj. Always one word. Do not hyphenate. - - - - - - - insecure - - - adj. Correct. Do not use "nonsecure" or "non-secure." - - - - - - - installation program - - - n. Correct. Do not use "installer" unless it is a formal part of the product or technology. - - - - - - - Intel 64 - - - Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86," or other variations as the name of this architecture. - - - The correct term for Intel's implementation of this architecture is "Intel® 64." - Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). - They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. - - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. - - - See also . - - - - The AMD64 logo is trademarked; the term "AMD64" is not. - For more information about AMD trademarks, see the AMD Trademark Information page at . - - - - For more information about Intel® trademarks, see and . - - - - - - - - - Intel® CoreTM - - - Correct. Example would be good. - - - - - - - - Intel Tolapai / Intel® EP80579 Integrated Processor - - - Do not use the code-name, "Tolapai." Use the official brand name "Intel® EP80579 Integrated Processor." - - - - - - - Intel Virtualization Technology (Intel VT) - - - Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi." - - - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT." Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)." - - - - - - - Intel® Xeon® - - - Correct. Example? Reference? - - - - - - - - interesting - - - Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note...", consider using a "Note" admonition. - - - - - - - internet - - - n. Always lowercase except in some specific exceptions, for example . - - - - - - - Internet of Things (IoT) - - - Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. - - - The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. - http://en.wikipedia.org/wiki/Internet_of_things - - - - - - - - - Intranet, intranet - - - See the "Word usage" appendix of the IBM Style Guide for guidance. - - - - - - - I/O - - - Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. - - - The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. - - - - - - - IOPS - - - Correct. All caps. Stands for input/output operations per second. - - - - - - - IP - - - Correct. Stands for Internet Protocol. Capitalize both letters. - - - - - - - IP Masquerade - - - A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. - - - Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. - - - - - - - IPsec - - - IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec." - - - - - - - IP switching - - - A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. - - - - - - - - ISV - - - Short for "independent software vendor", a company that produces software. - - - - - - - IT/I.T. - - - Use "I.T." (with periods) only in headlines or subheadings where all caps are used, to clarify that the word is "IT" versus "it." - - - - - - - Itanium - - - A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. - - - In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. - - - Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. - - - Do not use the term "IA64". It can be used in file names because they are not printed in the content. - - - - - - - Itanium 2 - - - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2." - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/J.xml b/tmp/en-US/xml_tmp/J.xml deleted file mode 100644 index 28be68f..0000000 --- a/tmp/en-US/xml_tmp/J.xml +++ /dev/null @@ -1,72 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - J - - - JavaScript - - - "JavaScript" is a trademark of Oracle Corporation, and should be used when referring to the scripting language. When referring to a file that is written with this language, use all lowercase; for example, "...copy the IPA javascript file to the /temp directory." - - - - - - - JBoss Community - - - No longer referred to as "JBoss.org." Use when referring to the community of users and contributors. - - - - - - - job - - - A task that a computer system performs. For example, printing a file is a job. Jobs can be performed by a single program or by a collection of programs. - - - - - - - jsvc - - - The Apache Commons Daemon jsvc is a set of libraries and applications to run Java applications on UNIX more easily. At the beginning of a sentence, use "Jsvc", otherwise all lowercase. - - - - - - - just - - - Use sparingly. In the phrase, "Just open the file...", omit the word "just." - - - - - - - JVM - - - Initialism for Java Virtual Machine, and a registered trademark of Oracle Corporation. Due to this registration, rather than using "JVM" as a noun when referring to the virtual machine, use the full phrase "Java Virtual Machine," or "Java VM," or only the noun itself, "virtual machine." You can include "JVM" for clarity, because most people know it as such, for example, "Java Virtual Machine (JVM)." Do not use Jvm or jvm. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/K.xml b/tmp/en-US/xml_tmp/K.xml deleted file mode 100644 index 8a8b51d..0000000 --- a/tmp/en-US/xml_tmp/K.xml +++ /dev/null @@ -1,170 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - K - - - KB, kB - - - See the IBM Style Guide for the correct abbreviation to use for specific use cases. - - - - - - - kbps, KBps, kBps - - - kbps is the accepted abbreviation for kilobit per second, or 1000 bits per second. - - - KBps and kBps are accepted abbreviations for kilobyte per second, or 1000 bytes per second. - - - - - - - kerberize - - - Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence. - - - - - - - kernel - - - The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. - - - - - - - Kernel-based Virtual Machine (KVM) - - - Spell out on first use, capitalized. Use the initialism (KVM) thereafter. It is an industry standard, and a proper noun. - - - - - - - kernel panic - - - Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. - - - - - - - kernel space, kernel-space - - - n. Two words when used as a noun. - - - adj. Hyphenate as an adjective, "kernel-space." Do not use "kernelspace." - - - - - - - keyboard key - - - When referring to a keyboard key, it is uppercase, singular, and the word "key" is not necessary, such as "To exit, press X." When the Ctrl or Alt keys are needed, use a plus sign between the keys, such as "To save the file, press "Ctrl+S." - - - See also . - - - - - - - key ring - - - n. Use the two-word form as a noun. For example, "add your new key to the key ring." - - - adj. Use the hyphenated form as an adjective. For example, "copy the key-ring file to the server." - - - Only use the one-word form, "keyring," if it is the actual name of a command, package, or other proper noun. - - - - - - - keytab - - - n. (Kerberos) Correct. A keytab (short for "key table") stores long-term keys for one or more principals. For details, see . - - - - - - - key-value - - - adj. Correct when referring to a data representation in computing systems and applications, for example a "key-value pair." Do not use "key/value" or any other variations. - - - - - - - Kickstart - - - adj. A network installation system for some Linux distributions. - http://en.wikipedia.org/wiki/Kickstart (Linux) - - - - - - - - - kill - - - If terminating a UNIX process, use "kill." For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate." For example, "To terminate the process, press Q." - - - - - - - knowledge base - - - Correct. Use the two-word form unless referring specifically to the "Red Hat Knowledgebase." In this case, use the one-word form and capitalize the "K." Do not capitalize the "b." - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/L.xml b/tmp/en-US/xml_tmp/L.xml deleted file mode 100644 index 1443a75..0000000 --- a/tmp/en-US/xml_tmp/L.xml +++ /dev/null @@ -1,266 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - L - - - LAN - - - Correct. This is an acronym for Local Area Network. Do not use Lan or lan. - - - - - - - latency - - - - - In general, the period of time that one component in a system is spinning its wheels waiting for another component. Latency, therefore, is wasted time. For example, in accessing data on a disk, latency is defined as the time it takes to position the proper sector under the read/write head. - - - - - - In networking, the amount of time it takes a packet to travel from source to destination. Together, latency and bandwidth define the speed and capacity of a network. - - - - - - - - - - - later - - - Use to refer to later or more recent releases of products. Do not use "newer" or related terms. See also . - - - - - - - leave out - - - Do not use. Use "omit" instead. - - - - - - - - left-click - - - v. Write the term hyphenated. Do not use "left click" or "leftclick." - - - - - - - - - LibreOffice - - - A Linux desktop suite. Do not use "Libre," "Libreoffice," or "Libre Office." - - - See also - - - - - - - license - - - n., v. Use this form for both the noun and the verb. - - - - - - - life cycle, life-cycle, lifecycle - - - n. Two words. Only use the one-word form if it is an established part of a software interface, part of a proper noun, or an external standard. - - - adj. Hyphenate. - - - - - - - Linux - - - Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." - - - Linux is a registered trademark of Linus Torvalds. Use a registered trademark symbol on first use. - - - - - - - load - - - - - To copy a program from a storage device into memory. Every program must be loaded into memory before it can be executed. Usually the loading process is performed invisibly by a part of the operating system called the loader. - - - - - - v. In programming, "to load" means to move from one storage type to another storage type for use. - - - - - - n. The measurement of how any finite resource is being used. For example, the amount of data (traffic) that the network carries, or the amount of CPU in use at any given time. - - - - - - - - - - - load balancing - - - Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. - - - - - - - logical topology - - - Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. - - - - - - - - login, log in - - - Write as one word as an adjective or noun, or as two words as a verb. - - - - - adj., n. One word. For example, "the login credentials". - - - - - - v. Two words. For example, "to log in as root". - - - - - - - - - log in to - - - v. Write as three words. For example, "to log in to the system". - - - - - - lookup, look-up, look up - - - n. Use the one-word form. - - - v. Use the two-word form. - - - adj. Hyphenate when used as a modifier. For example, "a look-up table." - - - - - - - look at - - - Do not use. Use "examine" or "inspect" or some other more precise term instead. - - - - - - - loopback address - - - The loopback address is a special IP address (127.0.0.1 for IPv4, ::1 for IPv6) that is designated for the software loopback interface of a machine. No hardware is associated with a loopback interface, and it is not physically connected to a network. - - - With a loopback interface, IT professionals can test IP software without concern for broken or corrupted drivers or hardware. - - - - - - - lots of - - - Do not use. Use "many" instead. - - - - - - - LPAR - - - Abbreviation of "logical partitioning", a system of taking a computer's total resources, such as processors, memory, and storage, and splitting them into smaller units that can be run with their own instance of the operating system and applications. Logical partitioning, which requires specialized hardware circuits, is typically used to separate different functions of a system, such as web serving, database functions, client/server actions, or systems that serve multiple time zones or languages. Logical partitioning can also keep testing environments separated from production environments. Because the partitions act as separate physical machines, they can communicate with each other. Logical partitioning was first used in 1976 by IBM. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Language.xml b/tmp/en-US/xml_tmp/Language.xml deleted file mode 100644 index fb6f3b4..0000000 --- a/tmp/en-US/xml_tmp/Language.xml +++ /dev/null @@ -1,1326 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - - Choosing Appropriate Language - - - Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This chapter attempts to identify commonly used slang terms and phraseology, and to provide alternatives. - - - If you find slang terms or other difficult-to-understand passages in our documentation, use this section to search for alternatives. - - - Red Hat is committed to eliminating use of language that might exclude or offend certain groups of people. This chapter describes some considerations for use of inclusive language. - - - Also in this chapter is guidance on some common categories of ambiguity in writing and how to avoid it. - - -
- Avoiding Misleading or Confusing Language - - Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. - - - - best practices - - - This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." - - - See the section for additional information about recommendations in Red Hat documentation. - - - - - - first come, first served - - - Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. - - - - - - - - -
-
- Identifying and Avoiding Slang - - Examples of slang terms: - - - - administrivia - - - Not a word. Do not use. - - - - - - - anything you like, anything they like - - - This phrase is probably readily understood but should not appear in Red Hat documentation. - - - - - "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." - - - Rephrase to something more suitable, such as "... to register any other kind of plug-in." - - - - - - - - - - - - ask (as a noun), make the ask - - - Ask is a verb. Do not use it as a noun. - - - - - - - at this point in time - - - Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. - - - - - - - automagic - - - Also, automagical. Both terms are slang. Do not use. - - - - - - - best-of-breed - - - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. - - - - - - - bleeding edge - - - Do not use. - - - - - - - bottom line - - - Traditionally used in financial contexts; avoid overuse. - - - - - - - - bucketize - - - Not a word. Try "categorize" or "organize into logical groups." - - - - - - - center of competency - - - Do not use. - - - - - - - check this site - - - Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. - - - - - - - coopetition - - - Not a word. Do not use. - - - - - - - core competency - - - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." - - - - - - - eat your own dogfood - - - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. - - - - - - - data point - - - Do not use. - - - - - - - dig deeper, delve deeper - - - "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." - - - - - - - double-edged sword, double-bladed sword - - - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. - - - - - - - enterprise-ready - - - Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. - - - - - - - exceed your expectations - - - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." - - - - - - - fib - - - A fib is a "small lie," also known as a "white lie." This sentence appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." - - - - - - - flying by the seat of your pants - - - Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. - - - - - - - frame it up - - - Do not use. - - - - - - - frown upon - - - "To frown upon" means to hold in low regard, not to approve of, and so on. For example: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). - - - - - - - fuzzy (search) - - - Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: - - - - - In Directory Server, if you do a fuzzy search for "Smith," you will probably also get "Smyth," because it sounds the same. - - - - - - - The use of "fuzzy" is valid in this context. - - - Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." - - - Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. - - - - - - - going-forward basis - - - Jargon. Say "from now on," "in the future," or something similar. - - - - - - - happy path - - - Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is localized slang and could easily be misunderstood. It could also produce problems for translation. - - - - - - - harness the power - - - Do not use. - - - - - - - have a crack at, jump right in - - - Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. - - - - - - - if you want, if you wish - - - Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." - - - - - - - in concert with - - - Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." - - - - - - - improve, enhance - - - Vague. Try to be more specific. - - - - - - - in a pinch - - - Under a tight schedule, hard pressed to achieve something. - - - - - - - infomediary - - - Not a word. Do not use. - - - - - - - is designed to - - - Avoid this and similar phrases when describing products and services. Instead, state what the product does. - - - - - Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. - - - - - - Correct: SSH works with almost any kind of public key algorithm or encoding format. - - - - - - - - - - - kettle of fish - - - Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. - - - - - - - leverage - - - Avoid. Alternatives include "use" and "take advantage of". - - - - - - - lights on, lights-on - - - Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. - - - It is typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." - - - - - - - low-hanging fruit - - - Metaphor. Do not use. - - - - - - - marketecture - - - Not a word. Do not use. - - - - - - - meet your needs - - - Vague. Try to be more specific, for example, "lower your middleware costs." - - - - - - - mission-critical - - - Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Ensure that you have the applications that you need to help your customers." versus "Ensure that you have the mission-critical applications that your customers demand." - - - - - - - net-net - - - Jargon. Use "in summary," "the end result," or something similar. - - - - - - - niche focus - - - Do not use. - - - - - - - over the wire - - - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent or transmitted in plain text" is fine. - - - - - - - pain in the backside - - - Nobody should ever write this expression or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. - - - - - - - paradigm - - - Avoid. Use "model," "standard," or something similar. - - - - - - - performant - - - In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. - - - - - - - physicalize - - - Not a word. Do not use. - - - - - - - piggyback - - - Slang. Do not use. - - - - - - - pre-baked - - - Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. - - - - - productize - - - Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] - - - - - - - ready to rumble - - - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." - - - - - - - rest on your laurels - - - Do not use. - - - - - - - right before doing something - - - Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. - - - - - - - root your server in the /serverRoot directory - - - This expression is inelegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. - - - - - - - shoot yourself in the foot - - - To "shoot yourself in the foot" indicates that you did something to harm your own cause, or acting against your own best interests. Remove the sentence; it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") - - - - - - - shy of - - - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. - - - - - - - silo, siloed - - - Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," or something similar. - - - - - - - - solutioning - - - Not a word. Lazy version of "creating a solution." - - - - - - - solutions-based - - - Do not use. - - - - - - - solution stack - - - Do not use. - - - - - - - - stovepipe - - - Jargon. In business, related to lack of cross-organizational communication, similar to "silo." - - - - - - - synergistic, synergy - - - Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. - - - - - - - synergical connectivity - - - Seriously? - - - - - - - to think outside the box - - - 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? - - - - - - - tunnel vision - - - Do not use. - - - - - - - under the covers - - - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. - - - - - - - value-added - - - Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." - - - - - - - very - - - Use with caution. For example, there is little value in saying "very cost-effective" versus "cost-effective." - - - - - - - virtual elephants - - - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. - - - - - - - - -
-
- Neologisms (Invented Words) - - The English language is full of these words. Some of them are useful; some of them are less so; others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and is generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. - - - Examples - - - "This feature allows synchronization of adds, deletes, and changes ..." - - - - - This sentence converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." - - - - - - - - - - -
-
- Anthropomorphism - - Anthropomorphism is applying human qualities to non-human things or animals. Avoid it in your writing. - - - Examples - - - The computer will think for a brief period. - - - - - Computers do not actually think but they might take a while to "process" commands. - - - - - - - - - - The Proxy Server is talking to either RHN Hosted or a Satellite Server. - - - - - It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. - - - - - - - - - - - Report an issue - - -
- - -
- Inclusive Language - - Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. - - - Replace terms that reinforce cultural, racial, or other types of bias with an alternative. - - - Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. - - - For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. - - - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. - - - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". - - - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. - - - Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". - - - Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. - -
- - -
- Avoiding Ambiguities - - - - Capitalizing Proper Nouns - - - In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. - - - - - - - - - Example - Improvement - - - - - - - This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. - This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. - - - - - - - -
- - - - - - Homographic Verbs - - - The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. - - - - - - - - - - Example - Improvement - - - - - - - The next() method should return null to indicate the end of results. - The next() method is expected to return null to indicate the end of results. OR The next() method must return null to indicate the end of results. - - - - It may be held in memory. - It can be held in memory. OR It might be held in memory. - - - - - - - -
- - - - - - Homonymity - - - When a single term has multiple meanings, be explicit in order to differentiate between them. - - - - - - - - - Example - Improvement - - - - - - - Tab through the dialog box. Set the tab. Move the tab on the ruler. How to show or hide tabs. Select the tab. - Use the tab key to move through the dialog box. Set the tab stop. Move the tab mark on the ruler. How to show or hide tab characters. Select the View tab in the Options dialog box. - - - - To create another administrator, click New on the File menu. - To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. - - - - - - - -
- - - See also . - - - - - - - - - Verb phrases - - - When you have more than one infinitive verb within a sentence, be clear what each verb refers to. - - - - - - - - - - Example - Improvement - - - - - - - Use the utility to run activities and save your settings. - - Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). - - - - - - - -
- - - - - - - Invisible Plurals - - - Some two-word phrases (noun + noun) do not clarify whether the first noun is singular or plural. - - - - - - - - - Example - Improvement - - - - - - - Once the file retrieval has been completed, you are ready to restart your system. - After the files have been retrieved, you can restart your system. - - - - - - - -
- - - - - - Verb phrases - - - Avoid ambiguous pronoun references, where a pronoun can refer to more than one antecedent. - - - - - - - - - - Example - Improvement - - - - - - - If the completed field contains text, it does not change. - If the completed field contains text, that text does not change. - - - - - - - -
- - - - - - Synonymity - - - Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. - - - For example, "Administration GUI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. - - - - - - - Use of "using" - - - Use of the word "using" can result in ambiguity, which can often be resolved by using "that uses" or "by using", according to the meaning. - - - - - - - - - - Example - Improvement - - - - - - - - Open the firewall ports using the existing service configuration. - - - Option 1: Open the firewall ports by using the existing service configuration. - - Option 2: Use the existing service configuration to open the firewall ports. - - - - - - The resource agents using mail alerts require a mail transport agent. - The resource agents that use mail alerts require a mail transport agent. - - - - - - - -
- - - - - - Verb phrases - - - Ensure that a verb phrase at the start of a sentence modifies the correct word. - - - - - - - - - - Example - Improvement - - - - - - - Having configured your environment, the product is ready to be used. (The product does not configure the environment.) - After you configure your environment, you can use the product. - - - - - - - -
- - - - - - - -
- -
- Dates and Times - - - Do not use an all-numeric representation for dates. For example, 9/12/2020 means September 12, 2020 in the US but 9 December 2020 in most other countries. Instead, write the month as a word. - - - - Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". - - - - Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. - - - - For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". - - - - Use "noon" or "12 noon" instead of "12 PM". - Use "midnight" or "12 midnight" instead of "12 AM". - - - Examples - - - The training class begins at 10 AM on 1 April 2021. - - - The coffee break is from 2:00 PM to 2:30 PM. - - - - - - -
- - - -
- Numbers - - Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. - - - Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). - - - Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate goups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). - - - See The Chicago Manual of Style, 17th Edition for detailed information on numbering formats. - - - -
- Phone numbers - - Use spaces, not dashes or dots, to punctuate phone numbers. When indicating a number for international use, include the country code (+1 555 555 5555 for a US number, for example). US 800 numbers are not accessible from outside the country, so do not precede them with a country code (800 555 5555). Phone numbers beginning with 0 are not for international use. Make these numbers ready for international use by dropping the zero and adding the appropriate country code. For example, (055) 12345 would be for use in Italy only; change it to +39 (55) 12345 for international use. - - -
- -
- \ No newline at end of file diff --git a/tmp/en-US/xml_tmp/M.xml b/tmp/en-US/xml_tmp/M.xml deleted file mode 100644 index 000dacc..0000000 --- a/tmp/en-US/xml_tmp/M.xml +++ /dev/null @@ -1,317 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - M - - - macOS - - - In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. - - - - - - - - - make sure - - - This means "be careful to remember, attend to, or find out something." For example, "make sure that the rhedk group is listed in the output." - - - You might be able to use "verify" or "ensure" instead. - - - - - - - manual, man page - - - Correct. Two words. Do not use "manpage." - - - - - - - matrixes - - - Correct. This is the correct plural form for US English spelling. Do not use "matrices." - - - - - - - - MB - - - - - When written as MB, stands for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). - - - - - - When written as Mb, stands for megabit. - - - - - - - - - - - MBps - - - Initialism for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps. - - - - - - - MBR - - - Initialism for Master Boot Record, a small program that is executed when a computer boots up. Typically, the MBR resides on the first sector of the hard disk. The program begins the boot process by looking up the partition table to determine which partition to use for booting. It then transfers program control to the boot sector of that partition, which continues the boot process. In DOS and Windows systems, you can create the MBR with the FDISK /MBR command. - - - - - - - media - - - - - 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 fibre 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. - - - - - - - - - - - menu-driven - - - adj. Correct. Do not use "menu driven" or "menudriven." - - - Refers to programs whose user interface employs menus. The antithesis of a menu-driven program is a command-driven program. - - - - - - - message - - - n. Write "the system displays a message" or "send an instant message." - - - adj. For example, "A messaging system." - - - Do not use as a verb. - - - - - - - metadata - - - Correct. Do not use "meta data" or "meta-data." - - - - - - - microservice - - - n. Correct. One word, common noun. Do not use "micro-service" or "micro service". Only capitalize at the beginning of a sentence or in a title. See https://en.wikipedia.org/wiki/Microservices for a definition. - - - - - - - Microsoft - - - Correct. Do not use "MS," "MSFT," or "MicroSoft." - - - - - - - misconfigure - - - v. This term is in common use and does appear in some dictionaries, but try to avoid it if possible. Do not hyphenate. - - - - - - - Montecito - - - Do not use. It is a code name for the "Intel Itanium Processor 9000 Sequence." This latter phrase should be used instead. - - - - - - - mount - - - v. - - - - - To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. - - - - - - - To install a device, such as a disk drive or expansion board. - - - - - - - - - - - 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. - - - - - - - Mozilla Firefox - - - Correct. First reference must be "Mozilla Firefox." Subsequent references can be "Firefox." - - - - - - - Mozilla Thunderbird - - - Correct. First reference must be "Mozilla Thunderbird." Subsequent references can be "Thunderbird." - - - - - - - MDOS - - - Correct. Do not use "ms-dos," "MSDOS," or "msdos." - - - - - - - multiprocessing - - - Correct. Do not use "multi-processing." - - - - - - - must - - - Use when referring to a task that a user is required to do. For example, "You must make a backup" is a requirement, but "You should make a backup" is a suggestion. - - - - - - - mutexes - - - Correct. "Mutex" is an abbreviation of "mutual exclusion." Consequently, "mutexes" is the correct plural form. - - - - - - - - MySQL - - - Common open source database server and client package. Do not use "MYSQL" or "mySQL." Mark the first mention of MySQL in body text with an - - ® symbol to denote a registered trademark. - - - - - - - - diff --git a/tmp/en-US/xml_tmp/N.xml b/tmp/en-US/xml_tmp/N.xml deleted file mode 100644 index f129cd6..0000000 --- a/tmp/en-US/xml_tmp/N.xml +++ /dev/null @@ -1,130 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - N - - - navigate to - - - Use "Navigate to" when moving through multiple GUI 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. - - - - - - need - - - Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). - - - - - - - - - needs, needs to be, need to - - - Avoid when possible. Suggested alternatives include "must," "required," or "should." - - - - - - - - - .NET - - - The Microsoft .NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and supports several programming languages. - - - "Microsoft .NET" is correct for the first reference, and ".NET" for all following references. - - - - - - - network transparency - - - A condition in which an operating system or other service gives user access to a remote resource through a network without needing to know if the resource is remote or local. For example, Sun Microsystems NFS, now a de facto industry standard, provides access to shared files through the Virtual File System (VFS) interface that runs on top of the TCP/IP stack. Users can manipulate shared files as if they were stored locally on the user's own hard disk. - - - - - - - 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. - - - 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. - - - - - - - node - - - - - In networks, a processing location. A node can be a computer or some other device such as a printer. Every node has a unique network address, sometimes called a Data Link Control (DLC) address or a Media Access Control (MAC) address. - - - - - - In tree structures, a point where two or more lines meet. - - - - - - - - - - - nonsecure - - - Do not use. Use "insecure" instead. - - - - - - - NULL or null - - - When a command or value is stated, use NULL. When stating that something is null, use "null," all lowercase. - - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/O.xml b/tmp/en-US/xml_tmp/O.xml deleted file mode 100644 index 3cc7ed5..0000000 --- a/tmp/en-US/xml_tmp/O.xml +++ /dev/null @@ -1,275 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - O - - - Objective C - - - Correct. Do not use "Objective-C." - - - - - - - object-oriented - - - Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." - - - - Also, do not use "object-orientated". - - - - - - - OEM - - - n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. - - - - To provide equipment to another company, an OEM, which customizes and markets the equipment. - - - - - - - offline - - - adj. Write as one word. Do not use "off-line." - - - - - - - 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. - - - 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. - - - - - - - - - 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." - - - - - - - - onboard - - - adj, tr.v. Use the one-word form in all cases. - - - - - - once - - - Use only to mean "one time." Do not use as a conjunction to mean "after" or "when." - - - - - - - online - - - adj. Write as one word. Do not use "on-line." - - - - - - - - - - on-site - - - adj. Hyphenate when used as an adjective, as in "on-site labs." - - - - - - - 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. - - - - - - - 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." - - - - - - - opcodes - - - Correct. Do not use "op-codes." - - - - - - - OpenJDK - - - The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. - - - - - open architecture - - - An architecture whose specifications are public. It includes officially approved standards as well as privately designed architectures whose specifications are made public by the designers. The opposite of open is closed or proprietary. - - - - - - - Open InfiniBand - - - "Open InfiniBand" is deprecated and should not be used. See "InfiniBand" for usage rules regarding the current preferred term for this switched fabric network topology. - - - - - - - OpenOffice - - - A Linux desktop suite. Do not use "Openoffice," "Open Office," or "ooo." - - - See also . - - - - - - - open source - - - Correct. Do not use "OpenSource," "opensource," or "open-source." - Only capitalize the "o" in "open source" at the beginning of a sentence. - - - - - - - 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". - - - - - - - operating system - - - Correct. Do not use Operating System, or OS. - - - - - - - orientate - - - Do not use. A user becomes "oriented" to an environment. Try a synonym such as "familiarize," as in "This section helps to familiarize you with the environment." - - - - - - - output device - - - Any machine that is capable of representing information from a computer, including display screens, printers, plotters, and synthesizers. - - - - - - - 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 . - - - - - - - override - - - Correct. Do not use "over-ride" or "over ride." - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Objectives.xml b/tmp/en-US/xml_tmp/Objectives.xml deleted file mode 100644 index fc7a45f..0000000 --- a/tmp/en-US/xml_tmp/Objectives.xml +++ /dev/null @@ -1,54 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - 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: - - - - Accurate and consistent - - - - - - Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale. - - - - - - Comprehensible, with a fog index of 9-12, using the Gunning fog index. - - - - - - User focused, providing information without patronizing the reader, or making presumptions about their skills. - - - - - - - - - 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. - - - - - - - diff --git a/tmp/en-US/xml_tmp/P.xml b/tmp/en-US/xml_tmp/P.xml deleted file mode 100644 index a931ed0..0000000 --- a/tmp/en-US/xml_tmp/P.xml +++ /dev/null @@ -1,327 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - P - - - PaaS - - - n. The correct abbreviation for "Platform-as-a-Service." In the spelled-out version of this term and its variants (for example, Infrastructure-as-a-Service and Software-as-a-Service), always use hyphens. - - - Marketing, Brand, Customer Portal Usage - - For all-caps text, such as banners, use "<VARIANT>-ASERVICE" for the spelled-out version. The same abbreviation is used across all groups. - - - - - - - - - PC - - - n. Use to refer to a personal computer. - - - - - - - - persist - - - v. - Do not use as a verb to mean "store" or "save," for example, when referring to persistent storage. - - - - - PHP - - - n. Use PHP when referring to the language in general. Use php when referring to the specific command or some other literal use. - - - See for specific PHP language information. See for more general information. - - - - - - - Pico, pico - - - n, adj. Capitalize when referring to the text editor or to the programming language. Do not capitalize when referring to the SI prefix. - - - - - - - plain text - - - 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." - - - - - - - please - - - 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. - - - - - - - pluggable - - - adj. Something that is capable of being plugged in, especially in terms of (for example) software modules. "Hot-pluggable" is also widely used with respect to hardware to indicate that it can be connected and recognized without powering down the system. - - - - - - - plug-in - - - n. Write hyphenated. Do not use "plugin." - - - A hardware or software module that adds a specific feature or service to a larger system. - - - - - - - - - - PM - - - Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "2 PM". - - - See also . - - - See the IBM Style Guide for a full discussion of how to represent times. - - - - - - - pop-up - - - n, adj. Do not use "popup" or "pop up." - - - - - - - PostScript - - - n. It is a registered trademark of Adobe. Do not use "Postscript." - - - - - - - PowerPC - - - 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 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. - - - - - - - POSIX - - - n. Do not use "Posix," "posix," or variations thereof. - - - An acronym for "Portable Operating System Interface for UNIX." - - - - - - - PPP - - - n. Do not use "ppp" or "Ppp." - - - An initialism for Point-to-Point Protocol. - - - - - - - press - - - v. Use for keyboard instructions. For example: "Press the Enter key" or more succinctly "Press Enter." - - - - - - - proof of concept - - - Use the following rules to form the plural of this phrase: - - - - Use "proofs of concept" for multiple proofs and only one concept. - - - - - - Use "proofs of concepts" for multiple proofs and multiple concepts. - - - - - - Do not use "proof of concepts." - - - - - - - - - - - - - pseudo-ops - - - Correct. Do not use "pseudo ops" or "pseudoops." - - - - - - - - - pull-down - - - adj. Use only if you must specify the type of menu or list. Do not use "pulldown." - - - - - - - push-button automation, turn-key automation - - - Metaphorical language (literally, push a button or turn a key to begin automation), and difficult to translate. Often used to refer to easy or hands-off automation, but human intervention is required, so this use is not accurate. Instead, use accurate language for the situation, such as: - - - - - User-triggered automation - - - - - Ready-to-use, ready-to-deploy - - - - - Self-service, self-provisioned. - - - - - Single-step automation - - - - - On-demand automation - - - - - - - PXE - - - Short for Pre-Boot Execution Environment. Pronounced "pixie," PXE is one of the components of Intel's Wired for Management (WfM) specification. With PXE, a workstation can boot from a server on a network in preference to booting the operating system on the local hard drive. - - - PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Preface.xml b/tmp/en-US/xml_tmp/Preface.xml deleted file mode 100644 index b356255..0000000 --- a/tmp/en-US/xml_tmp/Preface.xml +++ /dev/null @@ -1,12 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Preface - - - - - diff --git a/tmp/en-US/xml_tmp/Punctuation.xml b/tmp/en-US/xml_tmp/Punctuation.xml deleted file mode 100644 index aeddd9a..0000000 --- a/tmp/en-US/xml_tmp/Punctuation.xml +++ /dev/null @@ -1,478 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- Punctuation - - This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. - -
- Colons and Semicolons - - Current standards allow the use of a colon or semicolon in a range of different circumstances. Some of these are described in the following sections. - - - To relate clauses: - - The following sentences show a connection or shared theme between two clauses, or use the second clause to reiterate or amplify the idea in the first clause: - - - - - - - They had been writing code all night: this factor could explain their bloodshot eyes. - - - - - - They had been writing code all night; this factor could explain their bloodshot eyes. - - - - - - I spend a lot of money on food; last month, I went out to eat 36 times. - - - - - - I spend a lot of money on food: last month, I went out to eat 36 times. - - - - - - - The phrase following a semicolon or colon should begin with a lowercase letter, unless it begins with a proper noun. In the case of a colon, use an uppercase letter if the phrase constitutes a complete sentence on its own. - - - Try to limit your use of colons and semicolons. Separate sentences with a period if possible. - - - To introduce a list or series: - - A colon is generally used before a list or series. - - - - - - - The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill. - - - - - - - Do not use a colon if the list is a complement or object of an element in the sentence. - - - - - Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail. - - - - - - The colors I hate most are: - - - - - green - - - - - - orange - - - - - - pink - - - - - - magenta - - - - - - - - - - - Use a colon after "as follows" and "the following" if the related list immediately follows the stem, or introductory sentence. - - - - - The steps for changing directories are as follows: - - - - - Open a terminal. - - - - - - Type cd Documents/Books. - - - - - - - - - - - Use a colon to introduce a bullet list. - - - - - In the Properties dialog box, notice the following entries: - - - - - Connection name - - - - - - Count - - - - - - Confirm starting connection - - - - - - Confirm stopping connection - - - - - - Cost per - - - - - - - - - - - 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 semicolon before a conjunctive adverb, such as however, therefore, otherwise, namely, for example, and so on. - - - - - - I think; therefore, I am. - - - - - - -
-
- Commas - - In compound sentences: - - Use a comma to join clauses in a compound sentence, unless the clauses are short and have a similar theme. - - - - - - - I spent five hours working on this document, but I lost it when my computer crashed. - - - - - - Do you want to go the mall and the grocery store with me, or are you going to watch football instead? - - - - - - You play and I'll sing. - - - - - - - A comma can be omitted from a sentence with several clauses, but only when there is little chance that the sentence could be misread without it. - - - - - We played football all afternoon and were completely exhausted but we still stayed up watching movies all night. - - - - - - - That sentence is acceptable, but adding a comma before "...but we still stayed up..." would provide a pause and avoid the chance of having it read like a run-on sentence. - - - In a compound sentence that contains several short independent clauses, separate the clauses with commas and use a comma before the conjunction. - - - - - You need to go to the grocery store for milk, drop off my dry cleaning, and pick up your little sister from soccer practice. - - - - - - - In adverbial clauses and phrases: - - If a dependent clause is restrictive (omission affects the meaning of the main clause), do not set it off with commas. If it is nonrestrictive (omission does not affect the main clause), set it off with commas: - - - - - - - I'll go to lunch with you if we can get pizza. - - - - - - I don't want to go out for pizza, because I had pizza yesterday. - - - - - - - If a dependent clause comes before the main clause, use a comma whether the clause is restrictive or not. - - - - - If we get pizza, I'll go to lunch with you. - - - - - - When I heard the voice on the other end of the line, I was quite surprised. - - - - - - - In adjectival clauses or phrases: - - An adjectival clause that can be dropped without changing the meaning of the sentence is set off with commas. - - - - - - - The application, which comes with excellent documentation, is used by many graphic artists. - - - - - - - An adjectival clause that cannot be dropped without changing the meaning of the sentence is not set off with commas: - - - - - The plan that matters most to us will be easy to implement. - - - - - - - With coordinate adjectives: - - Separate coordinate adjectives (two or more adjectives modifying the same noun) with commas. - - - - - - - My dog is loyal, obedient, and affectionate. - - - - - - It was a long, boring meeting. - - - - - - - With series and lists: - - Separate elements in a series of three or more with commas, including a comma before the conjunction if one is used. - - - - - - - Today I am wearing socks, shoes, pants, and a shirt. - - - - - - -
-
- Parentheses - - Parentheses are similar to commas in that they set off information that further explains or enhances a statement. Information that is closely related to the statement should be set off with commas; information that is more incidental should be set off with parentheses. - - - - - - I tried to get to the elevator before the door shut, but I was too slow. - - - - - - Most of my favorite authors (Shakespeare, Dickens, Woolf) are dead. - - - - - - - Expressions beginning with for example, that is and so on can be set off with parentheses if they cause a major break in the sentence. If the break is minor, use commas. - - - - - - He interviewed the biggest stars of the day, namely, Madonna, Johnny Cash, and Jack Nicholson. - - - - - - Classic works of literature (such as Dickens, Shakespeare, the Brontes) lined the shelves. - - - - - - - If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. - - -
-
- Quotation Marks - - Commas and periods go inside quotation marks. - - - - Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. - - - - A Correct Example of the Use of Quotation Marks - - For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." - - - - - - - -
-
- Apostrophes - - Do not use an apostrophe to denote a plural. - - - To denote a possessive, use an apostrophe as follows: - - - Plural nouns not ending in s should add an 's (for example, the alumni's contribution). - - - Plural nouns ending in s only need an apostrophe (for example, the horses' food). - - - Singular common nouns ending in s should add an 's unless the next word begins with an s (for example, the witness's answer or the witness' story). - - - Singular proper names ending in s only need an apostrophe (for example, Dickens' novels). - - -
- -
- diff --git a/tmp/en-US/xml_tmp/Q.xml b/tmp/en-US/xml_tmp/Q.xml deleted file mode 100644 index 2754d0a..0000000 --- a/tmp/en-US/xml_tmp/Q.xml +++ /dev/null @@ -1,53 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Q - - - Q and A - - - n. Abbreviation for "Question and Answer," this format is listed in the American Heritage Dictionary. - - - - In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. - - - - - - - - - - qeth - - - Lowercase at all times. - - - - - - - - - - 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. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/R.xml b/tmp/en-US/xml_tmp/R.xml deleted file mode 100644 index bc7ce25..0000000 --- a/tmp/en-US/xml_tmp/R.xml +++ /dev/null @@ -1,244 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - R - - - RAM - - - Correct. Do not use "Ram" or any other variations. It is an acronym for "random access memory." - - - - - - - RAM disk - - - 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. - - - - - - - raw - - - Unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device. - - - The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device. - - - - - - - - raw data - - - Information that is not organized, formatted, or analyzed. - - - - - - - read - - - v. To copy data to a place where a program can use it. The term is commonly used to describe copying data from a storage medium, such as a disk, to main memory. It can also refer to the act of determining the contents of a variable or parameter. - - - n. The act of reading. For example, a fast disk drive performs 100 reads per second. - - - - - - - read-only - - - Capable of being displayed, but not modified or deleted. For all operating systems, you can protect objects (disks, files, or directories) with a read-only attribute that prevents other users from modifying the object. - - - - - - - read/write - - - Capable of being displayed (read) and modified (written to). Most objects (disks, files, or directories) are read/write, but you can also protect objects with a read-only attribute that prevents other users from modifying the object. - - - - - - - real time/real-time - - - n. The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." - - - - adj. Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." - - - - - - - reboot - - - Correct. Do not use "re-boot." - - - - - - - RedBoot - - - Correct. Do not use "Redboot" or "Red Boot." - - - - - - - refer to - - - Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." - - - - - - - - remote access - - - The ability to log on to a network from a distant location. Generally, it implies a computer, a modem, and some remote access software to connect to the network. Whereas remote control refers to taking control of another computer, remote access means that the remote computer becomes a full-fledged host on the network. The remote access software dials in directly to the network server. The only difference between a remote host and workstations that are connected directly to the network is slower data transfer speeds. - - - - - - - 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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. - - - - - - - - required - - - See . - - - - - - - return - - - When referring to the keyboard key on Solaris or Mac, use Return or return, respectively. See for other platforms. - - - - - - - right-click - - - v. Write the term hyphenated. Do not use "right click." - - - - - - - right now - - - Use "now" instead. - - - - - - - ROM, PROM - - - Acronym for read-only memory, computer memory on which data is prerecorded. After data has been written to a ROM chip, it cannot be removed and can only be read. - - - A variation of a ROM is a PROM (programmable read-only memory). PROMs are manufactured as blank chips on which data can be written with a device called a PROM programmer. - - - - - - - roundtable, round table - - - v. Use the one-word form to refer to a type of event or gathering. - - - - n. Use the two-word form to refer to a circular table. - - - - - - - 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." - - - - - - - runlevel - - - Correct. Do not use "run level" or "run-level." - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Resources.xml b/tmp/en-US/xml_tmp/Resources.xml deleted file mode 100644 index dbdc529..0000000 --- a/tmp/en-US/xml_tmp/Resources.xml +++ /dev/null @@ -1,145 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Resources - - This section lists some books and websites for you to consult on your quest to create a better document. - - - The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. The following documentation types are recognized: - - - - Technical content: software manuals and documentation, user guides, training courses - - - - - - Technical collateral: white papers and technology briefs - - - - - - Marketing content: advertising, promotions, articles - - - - - - Corporate collateral: related to company or products - - - - - - Press releases - - - - - - - -
- References for Technical Content and Collateral - - - - IBM Style Guide. IBM Corporation, latest version. - - - - - - The Chicago Manual of Style, 17th Edition. Chicago: The University of Chicago Press, 2017. - - - - - - Merriam-Webster Collegiate Dictionary - - - Visit https://www.merriam-webster.com/ for subscription options. - - - - - - The American Heritage Dictionary of the English Language - - - An online edition is accessible free of charge through http://www.ahdictionary.com/ - - - - - - -
-
- References for Marketing and Corporate Collateral - - - - AP Stylebook Online - - - - - - Merriam-Webster Online http://www.merriam-webster.com/ - - - - - - -
- - - - - diff --git a/tmp/en-US/xml_tmp/Revision_History.xml b/tmp/en-US/xml_tmp/Revision_History.xml deleted file mode 100644 index 5b4000e..0000000 --- a/tmp/en-US/xml_tmp/Revision_History.xml +++ /dev/null @@ -1,524 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Revision History - - - - 3-0 - July 2021 - - Julian - Cable - jcable@redhat.com - - - - Major update to align with some recent changes in IBM Style. - Sentence case is required for captions, legends, and diagram labels. - Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. - Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. - Minor edits so the guide itself conforms with its own advice. - - - - - - - - 2.0-1 - Wed Jun 3 2015 - - David - O'Brien - davido@redhat.com - - - - Fix issue "use 'singular to plural' pronouns -- typo? #6 . - Repair some XML in the grammar section. - Minor repairs to language. - - - - - - - - 1.6-14 - Wed Mar 12 2014 - - David - O'Brien - davido@redhat.com - - - - Added entry for "huge pages". - Updated entry for virtual machine to allow for abbreviation. - Updated section on using non-breaking spaces. - Added entry for correct capitalization of partners. - Added entry for "datasheet". - Change to common brand. - Remove some internal links that are no longer valid. - Generalize some entries based on advice from legal. - - - - - - - - 1.6-13 - Wed Feb 26 2014 - - David - O'Brien - davido@redhat.com - - - - 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. - 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. - - - - - - - - 1.6-12 - Fri Dec 20 2013 - - David - O'Brien - davido@redhat.com - - - - General cleanup of "U" section. BZ 1037923: Added entry for "uninterruptible". - General cleanup of "T" section. BZ 1038090: Added entry for "tier-1". - General tidy-up. Fix some typos. Updates cross-references. Started on BZ 820071. - - - - - - - - 1.6-11 - Wed Nov 27 2013 - - Julie - Wu - docs@redhat.com - - - - BZ 997202 Remove incorrect content regarding Japanese translation. - - - - - - - - 1.6-10 - Mon Nov 25 2013 - - Brice - Fallon-Freeman - docs@redhat.com - - - - BZ 1022268 Add entry for "time frame" - BZ 1022266 Add entry for "roundtable" - BZ 1027041 Add entry for "big data" - - - - - - - - 1.6-9 - Wed Nov 20 2013 - - David - O'Brien - docs@redhat.com - - - - Add balance of entries from "Things Shadowman would Never Say". - - - - - - - - 1.6-8 - Tue Nov 12 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 896006 Add entry for "health check". - BZ 896009 Add entry for "skill set". - BZ 924040 Add entry for referring to fonts. - BZ 915987 Add entry for "bare metal". - Add exception for Brand and Marketing heading styles. - BZ 1017549 Added entry for how to use URLs and footnotes. - BZ 1019258 Fixed Gunning Fog typo Ch 1 under "Readability". - BZ 989838 Updated entry for x86 usage. - BZ 1010163 Added entry for "Q and A". - BZ 821606 Updated entry for qeth based on new information. - BZ 1017149 Add entry for DevOps. - BZ 972916 Add entries for GNOME and GNOME Classic; document use of Super key. - General review and updates to examples. - Fix some revision history entries. - - - - - - - - 1.6-7 - Mon Aug 12 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 995310 Add entry for documenting command syntax. - BZ 984803 Add entry for online and offline backups. - BZ 989942 Add entry How to document Interface element labels. - BZ 989838 Update entries for referring to AMD64, Intel 64, x86, and related terms. - - - - - - - - 1.6-6 - Wed Jul 31 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 892839 Update entry for internet. - BZ 980307 Add entry for hyphenation. - BZ 965898 Add entry for documenting currencies. - BZ 989942 Add entry for documenting interface elements to Design section. - Various punctuation and spelling fixes. - - - - - - - - 1.6-5 - Wed Jul 17 2013 - - Julie - Wu - docs@redhat.com - - - - BZ 973074 Add entry for "talking to" in section on slang - BZ 950303 Add entry for SIOV - BZ 965378 Update entry for "Unset" - - - - - - - - 1.6-4 - Thu May 23 2013 - - David - O'Brien - docs@redhat.com - - - - Add "cloudbursting," "cloudwashing," and "pluggable" to usage dictionary. - - - - - - - - 1.6-2 - Tue Mar 19 2013 - - David - O'Brien - docs@redhat.com - - - - 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. - BZ 909015 Entry for "refer to" conflicts with IBM style guide. - Update some punctuation standards and cross references. - - - - - - - - 1.6-1 - Wed Jan 30 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 905707 Update section on active and passive voice with more examples and exceptions. - BZ 896245 Describe use of non-breaking spaces with company and product names. - BZ 821603 Add entry for Sybase Adaptive Server Enterprise usage. - - - - - - - - 1.6-0 - Tue Jan 15 2013 - - David - O'Brien - docs@redhat.com - - - - BZ 823350 Additional Detail for Chapter 2.4 - BZ 821609 Add correct usage of PHP to Usage Dictionary - BZ 831909 Remove "in depth" from Usage Dictionary; covered in standard references. - BZ 868067 Add usage for PaaS, IaaS, and SaaS - BZ 821615 Correct use of JVM - BZ 836869 Update SSH entry to allow for lowercase version - BZ 829173 Add correct usage of "time to live" to Usage Dictionary - BZ 821616 capitalization when referring to Btrfs - BZ 821612 Usage Dictionary addition: "zip" - BZ 824209 word usage: segfault - BZ 821599 Documenting exceptions - BZ 821607 Definitions for Virtual Machine, Virtualized Guest - BZ 821606 should we say "QETH device" or "qeth device" - BZ 820480 Add "cgroups" to Usage Dictionary - - - - - - - - 1.5-5 - Wed Nov 21 2012 - - David - O'Brien - docs@redhat.com - - - - BZ 878313 - Duplicate "and" in entry for AMD 64. - Review and update sections M, N, T, U, and V. - - - - - - - - 1.5-4 - Sun Nov 11 2012 - - David - O'Brien - docs@redhat.com - - - - Remove "hostname" entry; covered in IBM. - - - - - - - - 1.5-3 - Thu Nov 08 2012 - - David - O'Brien - docs@redhat.com - - - - BZs 871652, 820071, 821611, 821610. - Updates to and integration of Chapters X, Y, and Z. - Updated section on "Avoiding Slang." - Removed some redundant entries. - Various cleanups based on IBM Style Guide. - New entries from Word Nerds discussions. - - - - - - - - 1-4 - Fri Aug 31 2012 - - David - O'Brien - docs@redhat.com - - - - Removed some redundant entries. - Bugs 851646, 850596, 821595, 821617. - - - - - - - - 1-3 - Sun Aug 26 2012 - - David - O'Brien - docs@redhat.com - - - - Removed some redundant entries. - Patched some entries based on IBM Style Guide. - Cleaned up A, B, C, and part of D in Word Usage Dictionary. - - - - - - - - 1-2 - Fri Jul 27 2012 - - David - O'Brien - docs@redhat.com - - - - Added some xrefs to make life simpler. Added some temp links to BZs that are yet to be addressed. - More work on punctuation, spelling, typos, and duplicate and redundant entries. - Some structure reorganization. - Updated Feedback page. - Removed Author Group. - - - - - - - - 1-1 - Fri Apr 13 2012 - - David - O'Brien - docs@redhat.com - - - - Clean up redundant variablelist tags. - Remove a few duplicate entries. - Start working on making punctuation consistent. - - - - - - - - 1-0 - Mon Feb 20 2012 - - Gemma - Sheldon - gsheldon@redhat.com - - - - DocBook conversion from original guide on the Intranet. - - - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/S.xml b/tmp/en-US/xml_tmp/S.xml deleted file mode 100644 index 0a76bb9..0000000 --- a/tmp/en-US/xml_tmp/S.xml +++ /dev/null @@ -1,762 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - S - - - S/390 - - - Use the full description "IBM S/390." Do not use "s390," "S390," or any other variations. - - - - - - - SaaS - - - The correct abbreviation for "Software-as-a-Service." - - See also . - - - - - - - Samba - - - Correct. Do not use "samba" or "SAMBA." - - - - - - - record - - - Correct. Do not use "s-record," "Record," "s-Record," or any other variations. - - - - - - - screen capture - - - n. Do not use "screen shot," "screenshot," or other terms or variations. See the relevant entry in the IBM Style Guide. - - - - - - - screen saver - - - n. Do not use "screensaver." - - - - - - - scrollbar - - - n. Do not use "scroll bar" or "scroll-bar." - - - - - - - secure - - - n., vb. Due to potential legal ramifications, do not use without a qualifier. - See for examples. - - Using Qualifiers with Sensitive Terms - - - - - - Original text - Improvement - - - - - With this new version, the application is running on a secure, gateway-protected endpoint. - With this new version, the application is running on a more secure, gateway-protected endpoint. - - - This function secures your connection. - This function improves the security of your connection. - - - Developers can easily change the code to implement secured access. - Developers can easily change the code to make access more secure. - - - -
- - - - see - - - Use to refer readers to another resource. Avoid using "refer to" in this context. - - - - - - - segmentation fault - - - n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb. - - - See also "What is a segfault?" on the Red Hat Customer Portal for more information. - - - - - - - SELinux - - - 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. - - - - - - - send out - - - Do not use. Instead, use "emit" or "issue." - - - - - - - server farm - - - Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup. - - - - - - - server-side/server side - - - See . - - - - - - - setup - - - Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: - - - - - - Each setup provides different features. - - - - - - You need to set up a user profile as part of the registration process. - - - - - - Follow the set-up instructions included with the hardware. - - - - - - - - - - - SHA-1, SHA-2 - - - 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. - - - See for full details. - - - - - - - Shadowman - - - Correct. Do not use "Shadow Man" or "ShadowMan." The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries. - - - - - - - shadow passwords - - - Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. - - - Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package. - - - - - - - shadow utilities - - - Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only. - - - - - - - share name - - - Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." - - - - - - - - shebang - - - n. Refers to the character sequence consisting of the number sign and exclamation mark (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations. - - - - - - - shell - - - A "shell" is a software application, for example, /bin/bash or /bin/sh, which provides an interface to a computer. Do not use this term to describe where to type commands. - - - - - - - shell prompt - - - Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt," "terminal," or "shell." - - - - - - - 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 . - - - - - - - shut down - - - v. Correct. Do not use "shut-down." Only use "shutdown" when referring to the /sbin/shutdown system command. - - - - - - - - sign in - - - v. Write as two words. For example, "two options are available to sign in". - - - - - - sign in to - - - v. Write as three words. For example, "to sign in to the system". - - - - - - simply - - - Do not use. See also . - - - - - - - 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. - - - - - - - skill set, skills, knowledge - - - n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. See the following examples: - - - Example Use of Term "Skillset" Versus "Skills" - - Incorrect: Do you have the right skillset to be an RHCE? - - - Correct: Do you have the right skills to be an RHCE? - - - - - Example Use of Term "Knowledge" - - Incorrect: This course gives you the skill-set knowledge to complete your RHCT exam successfully. - - - Correct: This course gives you the knowledge to complete your RHCT exam successfully. - - - - - - - - - SLA - - - n. SLA stands for Service Level agreement. - The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. - This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements. - - - - - - smart card - - - n. Do not use smartcard or smart-card. - - - - - - - - SOCKS - - - Correct. Do not use "socks." When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5." - - - - - - - softcopy - - - Do not use. Instead, use "online." For example, "To view the online documentation ..." - - - - - - - sound card - - - n. Do not use "soundcard" or "sound-card." - - - - - - - Source-Navigator™ - - - Correct. Do not use "Source Navigator." Source-Navigator™ is a trademark of Red Hat. - - - - - - - source - - - v. In addition to the generic use of this term as a noun and verb, in -a programming and technical sense, it also means "Run the source command against the named file." - - - - - space - - - Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key. - - - - - - - Spacebar - - - n. Use when referring to the keyboard key, such as "Press the Spacebar key to continue." - - - - - - - spec file - - - n. Use to refer to an RPM spec file. Do not use "specfile." - - - - - - - specific - - - When used as a modifier, put a hyphen before "specific," such as "MIP-specific," "Linux-specific," and "chip-specific." - - - - - - - spelled - - - Correct. It is the standard US English spelling. Do not use "spelt." - - - - - - - - SQL - - - When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article. - - - When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel." In this case, it takes "a" as an indefinite article. - - - Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel." - - - More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL." When discussing Microsoft SQL Server, write "Microsoft SQL Server." When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL." - - - - - - - SR-IOV - - - Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV. - - - - - - - SSH - - - Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use ssh. - - - Do not use as a verb. - - - - Example Use of "SSH" - - - Incorrect: To begin, "ssh to the remote server." - - - Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar. - - - - - - - SSL - - - Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. - - - - - - - stand-alone - - - adj. Write hyphenated. 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. - - - - - - - StarOffice - - - A legacy Linux desktop suite. Do not use "Star," "Staroffice," or "Star Office." - - - - The successors of StarOffice are and . - - - - - - - start up - - - v. Do not use. Instead, use "activate" or "invoke." - - - - - - - startx - - - Correct. Do not use StartX or other variants. - - - - - - - straightforward - - - adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward." - - - - - - - su - - - Correct. The Linux command to change to a named user. Do not use SU (all caps). - - - - - - - subcommand - - - Correct. Do not use "sub-command" or "verb." - - A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: - - -hammer import organization --help - - In this example, "hammer" is the main or primary command, and "import" and "organization" are subcommands. is an option. - - - See also . - - - - - - - subdirectory - - - Correct. Do not use "sub-directory." See also . - - - - - - - submenu - - - Correct. Do not use "sub-menu." See also . - - - - - - - subpackage - - - Correct. Do not use "sub-package." - - - This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages." - - - Any other use of this word is strongly discouraged. - - - Note: Subpackages are not the same as dependencies and should not be treated as such. - - - - - - - superuser - - - A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user." - - - - - - - swap space - - - Correct. Do not use "swapspace." Capitalize at the beginning of a sentence only. - - - - - - - Sybase Adaptive Server Enterprise (ASE) - - - Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE." If discussing the high-availability version, use "Sybase ASE and High Availability." - - - See http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise for more information. - - - - - - - SysV - - - Correct. Do not use Sys V or System V. - - - - - - - symmetric encryption - - - A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message. - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Slang.xml b/tmp/en-US/xml_tmp/Slang.xml deleted file mode 100644 index f4ec60b..0000000 --- a/tmp/en-US/xml_tmp/Slang.xml +++ /dev/null @@ -1,876 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Avoiding Jargon, Slang, Metaphors, and Misleading Language - - Red Hat produces documentation for a global audience, and in many cases this documentation is translated into many languages. To reach the widest possible audience, and to make the task of translation as straightforward as possible, avoid slang and other culture-specific terminology. This section attempts to identify commonly used slang terms and phraseology, and to provide alternatives. - - - If you find slang terms or other difficult-to-understand passages in our documentation, use this page to search for alternatives. - -
- Avoiding Misleading or Confusing Language - - Some terms, phrases, and general language can be confusing if you are not a native speaker or if the phraseology has regional significance. Sometimes spelling changes are introduced over time and regions, based purely on differences in pronunciation. Some phrases can carry hidden or unintentional meanings. This section attempts to introduce a few examples. - - - - best practices - - - This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices." - - - See the section for additional information about recommendations in Red Hat documentation. - - - - - - first come, first served - - - Indicates that customers will be attended to in the order that they arrive. The phrase abbreviates the sentence "The first to come is the first to be served," so use "served" instead of "serve" to keep the verb function the same. This phrase is an idiom, so avoid using it when content will be translated. When you use this phrase as an adjective, it is hyphenated as follows: Admittance is on a first-come, first-served basis. - - - - - - - - -
-
- Identifying and Avoiding Slang - - Examples of slang terms: - - - - administrivia - - - Not a word. Do not use. - - - - - - - anything you/they like - - - This is probably readily understood but should not appear in Red Hat documentation. - - - - - "They can also use the slapi_register_plugin() call to register any kind of plug-in they like." - - - Rephrase to something more suitable, such as "...to register any other kind of plug-in." - - - - - - - - - - - - ask (as a noun), make the ask - - - Ask is a verb. Do not use it as a noun. - - - - - - - at this point in time - - - Do not use. In most cases, use "now." In some cases it is acceptable to use "at this point," for example, when you have reached a specific point in a procedure. - - - - - - - automagic - - - Also, automagical. Both terms are slang. Do not use. - - - - - - - best-of-breed - - - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type." Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. - - - - - - - bleeding edge - - - Do not use. - - - - - - - bottom line - - - Traditionally used in financial contexts; avoid overuse. - - - - - - - - bucketize - - - Not a word. Try "categorize" or "organize into logical groups." - - - - - - - center of competency - - - Do not use. - - - - - - - check this site - - - Understood to mean "have a look at this website." The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. - - - - - - - coopetition - - - Not a word. Do not use. - - - - - - - core competency - - - Jargon, cold and impersonal. Better choices include "specialization," "skill," "strength," "expertise," etc. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." - - - - - - - eat your own dogfood - - - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. - - - - - - - data point - - - Do not use. - - - - - - - dig deeper, delve deeper - - - "Visit the following web link to dig deeper into [subject]..." Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." - - - - - - - double-edged sword, double-bladed sword - - - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. - - - - - - - enterprise-ready - - - Although we used to use this term to emphasize our products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. - - - - - - - exceed your expectations - - - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." - - - - - - - fib - - - A fib is a "small lie," also known as a "white lie." This appeared in one of the GLS books: "this command tells fibs." Use something like "The output of this command can be misleading." - - - - - - - flying by the seat of your pants - - - Generally understood to mean "reacting to events as they occur." Difficult to offer alternatives without context. - - - - - - - frame it up - - - Do not use. - - - - - - - frown upon - - - "To frown upon" means to hold in low regard, not to approve of, etc. This appeared in the Seam guide: "...we generally frown on the use of session context...". This translates to (and should have been written as) "...the use of session context is not recommended..." (or words to that effect). - - - - - - - fuzzy (search) - - - Even though "fuzzy" is slang, it is common when referring to searches, especially in databases. This example came from the Directory Server documentation: - - - - - In Directory Server, if you do a fuzzy search for "Smith" you will probably also get "Smyth," because it sounds the same. - - - - - - - The use of "fuzzy" is valid in this context. - - - Note the difference between this and "wildcard" searches: "Sm?th" could return "Smith," "Smyth," "Smeth," or even "Smrth." - - - Do not use "fuzzy" to describe something that is not clear, such as an image, a concept, an idea, and so on. For example, "He was a bit fuzzy on the details" is not valid. - - - - - - - going-forward basis - - - Jargon. Say "from now on," "in the future," or something similar. - - - - - - - happy path - - - Do not use. Often understood to mean "a path or method of least resistance" or "the preferred way to solve the current issue", this is very localized slang and could easily be misunderstood. It could also produce problems for translation. - - - - - - - harness the power - - - Do not use. - - - - - - - have a crack at/jump right in - - - Have a crack at and jump right in are closely related in meaning as they imply to "get started or give it a try." Alternatives to these are "start," "try," and "begin," and will depend on the context of what is being discussed. - - - - - - - if you want, if you wish - - - Do not use. For example, instead of saying "If you want to perform an action,..." say "To perform an action,..." - - - - - - - in concert with - - - Do not use. Instead, say "with." For example, change "Use gcov in concert with GCC to analyze..." to "Use gcov with GNU CC to analyze..." - - - - - - - improve, enhance - - - Vague. Try to be more specific. - - - - - - - in a pinch - - - Under a tight schedule, hard pressed to achieve something. - - - - - - - infomediary - - - Not a word. Do not use. - - - - - - - is designed to - - - Avoid this and similar phrases when describing products and services. Instead, state what the product does. - - - - - Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format. - - - - - - Correct: SSH works with almost any kind of public key algorithm or encoding format. - - - - - - - - - - - kettle of fish - - - Commonly used in the expression "a different kettle of fish," meaning "that's a different matter (altogether)." Depending on the context, try to use "topic," "subject," "matter," or something similar. - - - - - - - leverage - - - Avoid. Alternatives include "use" and "take advantage of". - - - - - - - lights on, lights-on - - - Avoid using this term, because 1) it is jargon, 2) not everyone knows what it means, and 3) the meaning could be lost or confused in translation to other languages. - - - Typically used to mean maintaining the status quo or just doing what is required to keep things up and running (versus being proactive and innovative). For example, "A cloud can deliver strategic advantages to the business by redirecting resources from lights-on to innovation." - - - - - - - low-hanging fruit - - - Metaphor. Do not use. - - - - - - - marketecture - - - Not a word. Do not use. - - - - - - - meet your needs - - - Vague. Try to be more specific, for example, "lower your middleware costs." - - - - - - - mission-critical - - - Overused and jargony. Unless the topic is actually critical to a mission, use a factual term or phrase, for example, "Make sure you have the applications you need to help your customers." vs. "Make sure you have the mission-critical applications your customers demand." - - - - - - - net-net - - - Jargon. Use "in summary," "the end result," or something similar. - - - - - - - niche focus - - - Do not use. - - - - - - - over the wire - - - Commonly used in expressions such as "password information is sent in plain text over the wire," meaning "sent unencrypted through the transmission medium" (whether it is a wired or wireless network, the internet, or whatever). The phrase is probably not required at all. "Sent/transmitted in plain text" is fine. - - - - - - - pain in the backside - - - Nobody should ever write this or anything like it in any Red Hat documentation. Most people should know what it means. Use "problematic," "difficult," or something similar. - - - - - - - paradigm - - - Avoid. Use "model," "standard," or something similar. - - - - - - - performant - - - In the technical industry context, it means "performs as expected" or "well-performing." It is not necessarily a word everyone knows (and technically, it means "a performer," as in a play, according to most dictionaries), so use an alternative if possible. - - - - - - - physicalize - - - Not a word. Do not use. - - - - - - - piggyback - - - Slang. Do not use. - - - - - - - pre-baked - - - Means "prepared beforehand." Choose a suitable alternative, such as "preconfigured," depending on the context. - - - - - productize - - - Not a word. Find another way to say "modify something to become suitable as a commercial product." [wiktionary] - - - - - - - ready to rumble - - - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start." - - - - - - - rest on your laurels - - - Do not use. - - - - - - - right before doing something - - - Preferred phrase would be "immediately before doing something." Otherwise, write around the phrase. - - - - - - - root your server in the /serverRoot directory - - - This is not very elegant. Be aware of the multiple meanings of words. Try something like "Use the /serverRoot directory as the root directory for your server." This example came from the Directory Server documentation, but it could apply to Web Servers or any other type of server. - - - - - - - shoot yourself in the foot - - - To "shoot yourself in the foot" indicates that you have done something to harm your own cause, or acting against your own best interests. Remove the sentence - it should be self-evident from the surrounding information. (Found this statement alongside the "double-edged sword" comment with an added note about "preserving all your toes.") - - - - - - - shy of - - - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark," meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have less than the minimum number required. Avoid this terminology and use more easily understood terms; it will help our translators and also those reading our English documentation who are unfamiliar with such slang. - - - - - - - silo, siloed - - - Useful in farming, but in business it is jargon. Use "stand-alone," "confined," "separated," "segregated," or something similar. - - - - - - - solutioning - - - Not a word. Lazy version of "creating a solution." - - - - - - - solutions-based - - - Do not use. - - - - - - - solution stack - - - Do not use. - - - - - - - - stovepipe - - - Jargon. In business, related to lack of cross-organizational communication, similar to "silo." - - - - - - - synergistic, synergy - - - Jargon. Use "cooperative," "working together," "collaborative," "harmonious," or something similar. - - - - - - - synergical connectivity - - - Seriously? - - - - - - - to think outside the box - - - 1990 called and wants its jargon back. How about "(think) creatively" or "(think) unconventionally"? - - - - - - - tunnel vision - - - Do not use. - - - - - - - under the covers - - - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. - - - - - - - value-added - - - Jargon. Say "added value" or "valuable." Or be more specific, for example, "adds value by improving productivity." - - - - - - - very - - - Use with caution. For example, there is little value in saying "very cost-effective" vs. "cost-effective." - - - - - - - virtual elephants - - - This refers to a group of blind-folded people all touching different parts of an elephant and trying to describe what it is. Nobody sees the "big picture." Curiously, it appeared in an STC article about working in global and virtual teams and using effective communication. It falls into the same category as "skeletons in the closet," "dark horse," "black sheep," and so on. Use descriptions and adjectives that are not specific to a particular culture or locale. See http://en.wikipedia.org/wiki/Blind_Men-anElephant for more information. - - - - - - - - -
-
- Neologisms (Invented Words) - - The English language is full of these. Some of them are useful, some of them are less so, others are just painful, difficult to translate, and should be avoided. Many of them are the result of creating nouns from verbs, verbs from nouns, and adjectives from just about anything. Unless a particular word has been in use for some time and has been generally accepted into common English, try to avoid these neologisms. If necessary, reword or restructure your sentences. - - - Examples - - - "This feature allows synchronization of adds, deletes, and changes ..." - - - - - This sentence has converted three verbs to nouns. A better structure might be, "This feature allows the synchronization of add, delete, and change operations..." - - - - - - - - - - -
-
- Anthropomorphism - - Anthropomorphism is applying human qualities to non-human things or animals. Avoid this in your writing. - - - Examples - - - The computer will think for a brief period. - - - - - Computers do not actually think but they might take a while to "process" commands. - - - - - - - - - - The Proxy Server is talking to either RHN Hosted or a Satellite Server. - - - - - It is quite common to say "talk to" in this context, but "communicate with," "connected to," "registered with," or something similar would be better. - - - - - - - - - - - Report an issue - - -
- - diff --git a/tmp/en-US/xml_tmp/T.xml b/tmp/en-US/xml_tmp/T.xml deleted file mode 100644 index 2609a09..0000000 --- a/tmp/en-US/xml_tmp/T.xml +++ /dev/null @@ -1,250 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - T - - - taskbar - - - n. One word. Do not use "task bar." - - - - - - - tar, tarball - - - n. See the Word Usage chapter of the IBM Style Guide. - - - - - - - - telco - - - Preferred abbreviation for "telecommunications company." Do not use "telecom." See also . - - - Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs. - See . - - - - - - - telecommunications service provider - - - Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See . - - - - - - - telecommunications - - - Vertical for communication service providers. Preferred abbreviation is "telco." - - - - - - - - - - terminal - - - n. Do not use to describe where to type commands. Use "command line" instead. - - - See the Word Usage chapter of the IBM Style Guide for more information. - - - - - - - terminal emulation - - - Refers to making a computer respond like a particular type of terminal. With a terminal emulation program, you can access a mainframe computer or bulletin board service with a personal computer. - - - - - - - text mode - - - Correct. Do not use "textmode" or "text-mode." - - - A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. - - - - - - - text-based - - - adj. Correct. Do not use "text based." - - - - - - - third-party (adj.), third party (n.) - - - adj., n. Use "third-party" as the adjectival form. Use "third party" as the nominal form. Consult a dictionary for more examples. - - - - - - - through - - - Correct. Do not use "thru" and do not use the hyphen or any other type of dash. - - - - - - - throughput - - - n. The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. See the IBM Style Guide for more information about using measurements and abbreviations. - - - - - - - tier-1 - - - adj. Always use a numeral, and always hyphenate. Follow standard capitalization guidelines. - - - - - - - - time frame (n.) - - - Correct. Do not use "timeframe" or "time-frame." - - - - - - - time zone (n.) - - - Correct. Do not use "timezone" or "time-zone." - - - - - - - token-ring (n.) - - - 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. - - - - - - - - toolbar (n.) - - - Correct. Do not use "tool bar" or "tool-bar." - - - - - - - tooltip (n.) - - - Correct. One word. Use the term "tooltip" to refer to a brief, textual description that is displayed when a cursor is moved over a graphical image, such as an icon or button. Do not use the term "hover help". - - - - - - - totally - - - Do not use. See "basically." - - - - - - - troubleshoot (v.) - - - Correct. Do not use "trouble shoot" or "trouble-shoot." - - - - - - - TTL - - - Initialism for "time to live" (n.) and "time-to-live" (adj.) - - - Neither the noun nor the adjective should be capitalized unless you are documenting a GUI field, label, or similar element, in which case you should use the same capitalization. Capitalization at the beginning of a sentence is acceptable. The initialism is always uppercase. - - - - - - - type - - - Type can be used as either a verb or noun. You can write "Print the data type of init" or "To start Source-Navigator, type snavigator." - - - - - - - - diff --git a/tmp/en-US/xml_tmp/Template_Chapter.xml b/tmp/en-US/xml_tmp/Template_Chapter.xml deleted file mode 100644 index bc015f2..0000000 --- a/tmp/en-US/xml_tmp/Template_Chapter.xml +++ /dev/null @@ -1,20 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Dummy Title - - dummy text - -
- Dummy Section Title - - More dummy text. - - -
- - - diff --git a/tmp/en-US/xml_tmp/Template_Section.xml b/tmp/en-US/xml_tmp/Template_Section.xml deleted file mode 100644 index cbe285a..0000000 --- a/tmp/en-US/xml_tmp/Template_Section.xml +++ /dev/null @@ -1,12 +0,0 @@ - - -%BOOK_ENTITIES; -]> -
- - - - -
- diff --git a/tmp/en-US/xml_tmp/Translation.xml b/tmp/en-US/xml_tmp/Translation.xml deleted file mode 100644 index 435afd5..0000000 --- a/tmp/en-US/xml_tmp/Translation.xml +++ /dev/null @@ -1,383 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Writing Clearly and Succinctly - - This chapter provides guidelines, tips, and techniques to help to make your writing easier to read and understand, and also to translate. - -
- Sentence Structure - - This section describes how to construct your content for clarity and readability. - A full discussion of this topic is beyond the scope of this guide. - - -
- Using and Formatting Lists - - 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 sentence stem) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate. - - - The following general guidelines apply to lists: - - - - Itemized lists - - - 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. - Titles are optional. - - - - - Ordered lists - - - They appear as a numbered list. - 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. - - - - - Variable lists - - - They 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.) - A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. - Tables are best reserved for information that relies on, or benefits greatly from, a grid layout. - - - - - Procedures - - - They appear as a list of numbered steps. - Procedures always include a title, and are used to list the required steps to achieve a task. - - - - - - You can nest lists, but try to keep the number of levels to two or fewer. - To nest procedures in DocBook, use <substep> elements. - - -
Formatting Lists for Readability - - It is important to provide sufficient 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. - If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the or attributes to specify the spacing between list items. - DocBook uses the spacing attribute by default. - - - - Use a list with normal spacing if any list item contains the following components: - - - - - Nested lists. - Nested lists themselves can use the attribute if they fall outside the bounds of these recommendations. - - - - - Navigation or similar instructions (such as "Navigate to Menu -> Submenu"). - - - - - Multiple paragraphs, or sentences that wrap to two or more lines. - - - - - Use a list with compact spacing in all other cases. - - - - The use of all but the simplest graphics in lists is strongly discouraged. - - - - - - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. - - - - - - - - - Example - Improvement - - - - - - - - Before you start the installation, ensure that you have - - - - - enough free storage on your system - - - - - - backed up any data that you want to keep - - - - - - - to ensure a smooth installation. - - - - Before you start the installation, follow these steps to ensure a smooth installation: - - - - - Ensure that you have enough free storage on your system. - - - - - - Back up any data that you want to keep. - - - - - - - - - - - - - -
-
-
- -
- Noun Stacking - - Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. - - - - - - - - - - Example - Improvement - - - - - - - Plastic tubing and syringe tips. - Plastic tubing and plastic syringe tips. - - - - Set default printer configuration parameters for new users. Enter the maximum length of time that you want to keep the automatic synchronization address list updates in days and press Enter. - For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. - - - - - - - -
-
- -
-
- Grammatical Genders - - When using ambiguous pronouns such as "they" or "it", it is not always clear what they refer to. For languages that have different genders for nouns, it is important to know exactly what each pronoun refers to. For example, the word "it" can be translated in several different ways and might require other grammatical adjustments. - - - Further, an initialism such as RPM might refer to the package or to the package manager. In German, manager is a masculine noun, and so RPM requires the masculine article "der" when it refers to the RPM Package Manager. Package is a neuter noun, and requires the neuter article "das" when it refers to an RPM package. - - - - - - - - - Example - Improvement - - - - - - - Set the parameter XYZ to 1 in the configuration file /etc/config.conf. It configures the way the Gateway application handles incoming network traffic. - Set the XYZ parameter to 1 in the /etc/config.conf configuration file. This parameter configures how the Gateway application handles incoming network traffic. - - - - The RPM is useful. - The RPM package is useful. OR The RPM Package Manager is useful. - - - - - - - - -
- -
-
- DocBook Elements - - Use the correct DocBook elements to help translators to understand the meaning of, and to identify, translatable and non-translatable terms. - - - - Tagged Terms in Sentences - - Many tagged terms are not translatable, and so they should not be used as structural parts of a sentence. Otherwise, translators must complete the blanks or tag terms themselves. - - - - - - - - - - - Example - Improvement - - - - - - - In /some/path/, grep for XYZ. - In the /some/path/ directory, use the grep command to search for "XYZ". - - - - contains a reference to the hostname return value from instance-2. - The parameter contains a reference to the hostname return value from your second server instance, instance-2. - - - - Troubleshooting Glance. - Troubleshooting the Glance image service. - - - - Installing the maven-changelog-plugin. - Installing the maven-changelog-plugin package. - - - - - - - -
- -
-
- Code Blocks - - Avoid including commentary within the same box as command input or output. These comments might be confused with part of the output, and during translation might be accidentally overlooked and left in English. - - - For example, consider the word "Usage" in the following block: - - -Usage: rhevm-iso-uploader [options] list -rhevm-iso-uploader [options] upload [file1] [file2] [file3] - -
-
- Entities - - An entity is a primitive data type, which associates a string with either a unique alias (such as a user-specified name) or an SGML reserved word (such as #DEFAULT) - - - . Entities are called by reference, and take the form &name; (both the ampersand and the semicolon are required). - - - - Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - - - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: - - - - - PRODUCT - - - - - - BOOKID - - - - - - YEAR - - - - - - HOLDER - - - - - - - Do not include entities such as &PRODNAME; or &VERSION; and so on, or things like &BIBLE; to represent "The King James Bible". To learn more about entities, see the relevant chapter in - - -
- - - diff --git a/tmp/en-US/xml_tmp/U.xml b/tmp/en-US/xml_tmp/U.xml deleted file mode 100644 index 7d55d87..0000000 --- a/tmp/en-US/xml_tmp/U.xml +++ /dev/null @@ -1,227 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - U - - - UID - - - n. UID and user ID are abbreviations of user identifier. Do not use "uid" or "User ID" or other variations unless specifically referring to a variable, argument, parameter, UI label, or similar. - - - - - - - UltraSPARC - - - Correct. Do not use "ULTRASPARC," "UltraSparc," or other variations. - - - 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. - - - - - - - undercloud - - - n. 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 . - - - - - - - uninterruptible - - - adj. Despite not appearing in the American Heritage Dictionary, this term does appear in the Merriam-Webster Unabridged Dictionary, and is considered acceptable in Red Hat documentation, especially in the context of "uninterruptible power supply (UPS)." - - - - - - - UNIX - - - Correct. Do not use "Unix" or "unix." - - - UNIX is a registered trademark of The Open Group. - - - Do not use "UNIX-like." Use an expression such as "Linux, UNIX, and similar operating systems" instead. - - - - - - - unset - - - Incorrect. Use "Clear" instead, to refer to removing a selection from a check box. - - - To disable the Wobbly Widget application, clear the Enable Wobbly Widget check box. - - - This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. - - - - - - - untrusted - - - Use only in the context of security relationships. For example, web browsers often indicate that a site is "untrusted" if it cannot verify that site's security certificate. - - - - - - - upgrade - - - v. Correct. Do not use "up-grade" or "up grade." - - - - - - - UPS - - - Abbreviation of uninterruptible power supply, a power supply that includes a battery to maintain power in the event of a power outage. - - - - - - - upsell (v.), upselling (n.) - - - Marketing Use Only - - "The practice of offering customers additional or more expensive products or services after they have already agreed to buy something. - http://www.ahdictionary.com/word/search.html?q=upsell - - " - - - Do not hyphenate or use as two words. No adjectival form is currently recognized. - - - - - - - - - upstream - - - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "up-stream" or "up stream." - - - - - - - uptime - - - n. Correct. Do not use "up-time" or "up time." - - - - - - - URL - - - n. Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. - - - See for more information. - - - - - - - - user - - - n. When referring to the reader, use "you" instead of "the user." For example, "The user must..." is incorrect. Use "You must..." instead. - - - If referring to more than one user, calling the collection "users" is acceptable, such as "Other users might want to access your database." - - - - - - - user interface - - - n. Correct. Do not use "user-interface" or "userinterface." - - - 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. - - - - - - - user name - - - n. Correct. Do not use "username" unless you are using it as a variable. - - - - - - - user space - - - n. Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space." Do not use "userspace." - - - - - - - utilize - - - Avoid this term. Write "use" instead. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/V.xml b/tmp/en-US/xml_tmp/V.xml deleted file mode 100644 index b14bcb5..0000000 --- a/tmp/en-US/xml_tmp/V.xml +++ /dev/null @@ -1,139 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - V - - - VAR - - - Acronym for value-added reseller. Same as OEM (original equipment manufacturer). - - - - - - - VDSM - - - Initialism for Virtual Desktop Server Management. Do not spell out this initialism. Using the term "virtual desktop" in this context has negative marketing implications. Use VDSM without expansion. - - - - - - - vi - - - Correct. Use all lowercase letters. Do not use "VI" (all caps). - - - - - - - Vim - - - Correct when referring to the application. - Do not use "VIM" (all caps). - Only use "vim" (all lowercase) when referring to the command to start the application. - - - 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. - - - - - - - video mode - - - Correct. Do not use "video-mode" or "videomode." - - - The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. - - - - - - - virtual console - - - Correct. Do not use "virtual-console" or "Virtual Console" for general use. - - - It can be abbreviated to "VC" provided that the term is first introduced in the same content in its full version, such as "A virtual console (VC) is a shell prompt in a non-graphical environment. Multiple VCs can be accessed simultaneously." - - - - - - - virtual machine, VM - - - Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - - - It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. - - - - - - - virtualized guest - - - The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." - - - See also "guest operating system." - - - - - - - virtual router - - - An abstract object managed by VRRP (virtual router redundancy protocol) that acts as a default router for hosts on a shared LAN. It consists of a Virtual Router Identifier and a set of associated IP addresses across a common LAN. - - - - - - - VNIC - - - Abbreviation for virtual network interface card. Use all uppercase characters for the abbreviation, but all lowercase for the expansion, except at the beginning of a sentence. - - - - - - - VPN - - - Initialism for virtual private network, a network that uses public wires to connect nodes. For example, various systems can create networks with the internet as the medium for transporting data. These systems use encryption and other security mechanisms to ensure that only authorized users can access the network and that the data cannot be intercepted. - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/W.xml b/tmp/en-US/xml_tmp/W.xml deleted file mode 100644 index c3aed22..0000000 --- a/tmp/en-US/xml_tmp/W.xml +++ /dev/null @@ -1,139 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - W - - - WAN - - - A computer network that spans a relatively large geographical area. - Typically, a WAN consists of two or more local-area networks (LANs). - - - Computers connected to a wide-area network are often connected through public networks, such as the telephone system. - They can also be connected through leased lines or satellites. - The largest WAN in existence is the internet. - - - - - - - WCA - - - An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. - - - - WCAs are also called "query applications." - - - - - - - want - - - Use instead of "wish" or "would like." - Rephrase to avoid whenever possible. - For example, "If you want to use the debugger, ..." can be rewritten as "To use the debugger, ..." - - - - - - - we suggest - - - Do not use. - Use a more direct construction, or use "recommend." - For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." - - - - - - - webhook - - - n. One word. Common noun. - Capitalize only at the beginning of a sentence. - Use alternative capitalization only if it appears as a proper noun. - - - - - - - webpage - - - n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - - - - - - - - web UI - - - 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. - - - - - - - who, whom - - - Use the pronoun "who" as a subject. - Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. - - - For example: Who owns this phone? To whom does this phone belong? - - - - - - - will - - - - Do not use future tense unless it is absolutely necessary. - For example, do not write "The next section will describe the process in detail." - Instead, write "The next section describes the process in detail." - - - - - - - Window Maker - - - Correct. Do not combine into one word or hyphenate. - This is a window manager for the "X Window System." - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/WUG_Intro.xml b/tmp/en-US/xml_tmp/WUG_Intro.xml deleted file mode 100644 index 3bafcfd..0000000 --- a/tmp/en-US/xml_tmp/WUG_Intro.xml +++ /dev/null @@ -1,54 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - Usage Dictionary - - 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. - - - - A note about trademarks - - - 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 <trademark> tag. We do mark Red Hat's own trademarks. See Copyright Notices and Trademark Legends for more information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tmp/en-US/xml_tmp/WUG_References.xml b/tmp/en-US/xml_tmp/WUG_References.xml deleted file mode 100644 index 364183d..0000000 --- a/tmp/en-US/xml_tmp/WUG_References.xml +++ /dev/null @@ -1,19 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - References - - the IBM Style Guide - - - Chicago Manual of Style, 17th Edition - - - American Heritage Dictionary - - - - diff --git a/tmp/en-US/xml_tmp/XYZ.xml b/tmp/en-US/xml_tmp/XYZ.xml deleted file mode 100644 index cce5486..0000000 --- a/tmp/en-US/xml_tmp/XYZ.xml +++ /dev/null @@ -1,142 +0,0 @@ - - -%BOOK_ENTITIES; -]> - - XYZ - - - X - - - An alternative reference to the "X Window System." Do not use X by itself when referring to "XEmacs." - - - - - - - XEmacs - - - Correct. Do not use "Xemacs." Use "xemacs" only when referring to a command, such as "To start XEmacs, type xemacs." - - - - - - - Xen - - - Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. - - - A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." - - - The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. - - - - - - - - xterm - - - Correct. Do not use "Xterm" unless the word is used at the beginning of a sentence. - - - - - - - X Windows - - - Do not use. It is an incorrect reference to the X Window System (or X). - - - - - - - X Window System - - - Also referred to as X. When making multiple references to the X Window System, the complete reference must appear first, with shortened references following. For example, "Reinstalling the X Window System, or X, is not necessary if ..." "To start an X session, from the shell prompt ..." - - - - - - - YAML - - - Recursive acronym for "YAML Ain't Markup Language." Expand on first use only. - - - - - - - you - - - Use second person wherever possible. Do not use "I," "we," "he," or "she." - - - - - - - you may - - - Avoid. For example, "you may" can be eliminated from the following sentence: "You may double-click the desktop ..." - - - - - - - zip - - - See the Word Usage chapter of the IBM Style Guide. - - - - - - - Zip Code - - - Correct. Do not use "zip code," "Zip code," or any other variation. - - - - - - - - - - - - From 5b979e6629b98c92515e1f078976cd3e94a69d44 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 9 Jul 2021 17:10:54 +0100 Subject: [PATCH 20/27] Further style guide edits --- en-US/B.xml | 32 ++++++++++++++++---------------- en-US/D.xml | 18 +++++++++--------- en-US/E.xml | 11 +---------- en-US/G.xml | 14 +++++++------- en-US/H.xml | 20 ++++++++++---------- en-US/I.xml | 2 +- en-US/L.xml | 20 ++++++++++---------- en-US/M.xml | 20 ++++++++++---------- en-US/O.xml | 16 ++++++++-------- en-US/P.xml | 26 +++++++++++++------------- en-US/Punctuation.xml | 20 ++++++++++++++++---- en-US/Revision_History.xml | 3 ++- en-US/S.xml | 1 + en-US/T.xml | 18 +++++++++--------- en-US/V.xml | 36 ++++++++++++++++++------------------ en-US/W.xml | 38 +++++++++++++++++++------------------- 16 files changed, 150 insertions(+), 145 deletions(-) diff --git a/en-US/B.xml b/en-US/B.xml index 7b4b17f..ca95d34 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -132,6 +132,22 @@ + + + biannual, bimonthly, biweekly, semiweekly, semimonthly + + + People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. + + + Instead of biweekly, write "every two weeks" or "every other week." + + + Instead of semiweekly, write "twice a week." + + + + big data @@ -161,22 +177,6 @@ - - - biannual, bimonthly, biweekly, semiweekly, semimonthly - - - People have trouble remembering whether biweekly means "every two weeks" or "twice a week." "Semiweekly" has a similar problem. Even though both terms have clear dictionary definitions, it is best to avoid them in favor of clear communication. - - - Instead of biweekly, write "every two weeks" or "every other week." - - - Instead of semiweekly, write "twice a week." - - - - BIND diff --git a/en-US/D.xml b/en-US/D.xml index 4bae8f3..6653646 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -287,31 +287,31 @@ - - downstream + + download - Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." + v., n. Do not use "down load" or "down-load." - - downtime + + downstream - Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." + Correct. Use the one-word form for both the nominal and adjectival forms. See also . Do not use "down-stream" or "down stream." - - download + + downtime - v., n. Do not use "down load" or "down-load." + Correct. Refers to the period during which a server, service, or other resource is unavailable. Do not use "down-time" or "down time." diff --git a/en-US/E.xml b/en-US/E.xml index f1865b9..4659c4a 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -136,17 +136,8 @@ - - - exclamation points (!) - - - Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. - + - - - Exec-Shield diff --git a/en-US/G.xml b/en-US/G.xml index f07fd91..cf118d0 100644 --- a/en-US/G.xml +++ b/en-US/G.xml @@ -133,21 +133,21 @@ - - GigE + + gigabyte - See . + 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. - - - gigabyte + + + GigE - 2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. When abbreviating "gigabyte," use "GB." Use a non-breaking space between the unit and any value to prevent widows and orphans. + See . diff --git a/en-US/H.xml b/en-US/H.xml index 92d3e4a..c80853f 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -62,16 +62,6 @@ - - - help desk - - - Typically two words, but use the term accepted by your organization. - - - - healthcare @@ -117,6 +107,16 @@ + + help desk + + + Typically two words, but use the term accepted by your organization. + + + + + hertz diff --git a/en-US/I.xml b/en-US/I.xml index 2c68839..1992d80 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -72,7 +72,7 @@ - matrixes + indexes Correct. This is the correct plural form for US English spelling. Do not use "indices." diff --git a/en-US/L.xml b/en-US/L.xml index 1443a75..e04def0 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -200,6 +200,16 @@ + + + look at + + + Do not use. Use "examine" or "inspect" or some other more precise term instead. + + + + lookup, look-up, look up @@ -216,16 +226,6 @@ - - - look at - - - Do not use. Use "examine" or "inspect" or some other more precise term instead. - - - - loopback address diff --git a/en-US/M.xml b/en-US/M.xml index 000dacc..cb9605f 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -93,6 +93,16 @@ + + + MDOS + + + Correct. Do not use "ms-dos," "MSDOS," or "msdos." + + + + media @@ -258,16 +268,6 @@ - - - MDOS - - - Correct. Do not use "ms-dos," "MSDOS," or "msdos." - - - - multiprocessing diff --git a/en-US/O.xml b/en-US/O.xml index 3cc7ed5..d9abbef 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -155,14 +155,6 @@ - - OpenJDK - - - The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. - - - open architecture @@ -182,6 +174,14 @@ + + + OpenJDK + + + The OpenJDK trademark is owned by Oracle with a fair-use clause, so be careful about how you use this term. + + OpenOffice diff --git a/en-US/P.xml b/en-US/P.xml index a931ed0..1f0826e 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -145,6 +145,19 @@ + + + POSIX + + + n. Do not use "Posix," "posix," or variations thereof. + + + An acronym for "Portable Operating System Interface for UNIX." + + + + PostScript @@ -172,19 +185,6 @@ - - - POSIX - - - n. Do not use "Posix," "posix," or variations thereof. - - - An acronym for "Portable Operating System Interface for UNIX." - - - - PPP diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index aeddd9a..5b88655 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -5,6 +5,7 @@ ]>
Punctuation + This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. @@ -425,18 +426,21 @@
Quotation Marks + + --> - Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quote; if not, they go outside. + In technical documentation, punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. - A Correct Example of the Use of Quotation Marks + Correct Examples of the Use of Quotation Marks For example, the following message indicates multiple possible solutions: "This message could be resolved by changing the time." + + + In this example, the final period is not part of the command in the quoted text: Use "xemacs" only when referring to a command, such as "To start XEmacs, type xemacs". @@ -474,5 +478,13 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
+ +
+ Exclamation Points + + Do not use at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command. + + +
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index 5b4000e..d1112e6 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -19,8 +19,9 @@ Major update to align with some recent changes in IBM Style. Sentence case is required for captions, legends, and diagram labels. + All punctuation, including periods and commas, is now placed outside quotation marks unless the punctuation is part of the quotation. Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. - Usage A-Z: Various additions and updates. Moved items that are not literal term entries to an earlier chapter. + Usage A-Z: Various additions and updates. Corrected alphabetical sorting sequence. Moved items that are not literal term entries to an earlier chapter. Minor edits so the guide itself conforms with its own advice. diff --git a/en-US/S.xml b/en-US/S.xml index 0a76bb9..500ba43 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -39,6 +39,7 @@ + record diff --git a/en-US/T.xml b/en-US/T.xml index 2609a09..8963ca9 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -87,24 +87,24 @@ - - text mode + + text-based - Correct. Do not use "textmode" or "text-mode." - - - A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. + adj. Correct. Do not use "text based." - - text-based + + text mode - adj. Correct. Do not use "text based." + Correct. Do not use "textmode" or "text-mode." + + + A video mode in which a display screen is divided into rows and columns of boxes. Each box can contain one character. Text mode is also called character mode. diff --git a/en-US/V.xml b/en-US/V.xml index b14bcb5..f10df65 100644 --- a/en-US/V.xml +++ b/en-US/V.xml @@ -36,29 +36,29 @@ - - Vim + + video mode - Correct when referring to the application. - Do not use "VIM" (all caps). - Only use "vim" (all lowercase) when referring to the command to start the application. + Correct. Do not use "video-mode" or "videomode." - 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. + The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. - - video mode + + Vim - Correct. Do not use "video-mode" or "videomode." + Correct when referring to the application. + Do not use "VIM" (all caps). + Only use "vim" (all lowercase) when referring to the command to start the application. - The setting of a video adapter. Most video adapters can run in either text mode or graphics mode. In text mode, a monitor can display only ASCII characters. In graphics mode, a monitor can display any bit-mapped image. In addition to the text and graphics modes, video adapters offer different modes of resolution and color depth. + 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. @@ -77,27 +77,27 @@ - - virtual machine, VM + + virtualized guest - Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. + The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." - It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. + See also "guest operating system." - - virtualized guest + + virtual machine, VM - The term "virtualized guest" should be used only when comparing a "fully virtualized guest" with a "paravirtualized guest." + Refers to virtual hardware that consists of virtual CPUs, memory, devices, and so on. Do not use "guest virtual machine" except for specific emphasis that it is a guest. - See also "guest operating system." + It can be abbreviated to "VM" provided that the term is first introduced in the same content in its full version, and without any possible confusion with other terms, such as "virtual memory." Author discretion is recommended. diff --git a/en-US/W.xml b/en-US/W.xml index c3aed22..d363338 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -21,20 +21,6 @@ - - - WCA - - - An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. - - - - WCAs are also called "query applications." - - - - want @@ -48,13 +34,15 @@ - - we suggest + + WCA - Do not use. - Use a more direct construction, or use "recommend." - For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." + An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. + + + + WCAs are also called "query applications." @@ -93,6 +81,18 @@ + + + we suggest + + + Do not use. + Use a more direct construction, or use "recommend." + For example, instead of "We suggest that you make a backup of your data disk," write "Back up your data disk." + + + + who, whom From 6cfec44438bbf09cca5c46bda8c076cdacf27ba4 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Tue, 20 Jul 2021 18:09:29 +0100 Subject: [PATCH 21/27] Further style guide updates --- en-US/A.xml | 13 ++ en-US/G.xml | 8 +- en-US/H.xml | 16 +-- en-US/I.xml | 9 +- en-US/L.xml | 1 - en-US/Language.xml | 50 +++++++- en-US/Punctuation.xml | 248 +++++++++++++++++++++++++++++++++++-- en-US/Revision_History.xml | 3 +- en-US/W.xml | 5 +- 9 files changed, 317 insertions(+), 36 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 088be01..f19afdc 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -152,6 +152,19 @@ + + + + appendixes + + + Correct. This is the correct plural form for US English spelling. Do not use "appendices." + + + + + + @@ -203,17 +202,16 @@ - + - + --> GPL diff --git a/en-US/H.xml b/en-US/H.xml index c80853f..020f633 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -63,18 +63,17 @@ - + - + --> health check @@ -127,13 +126,15 @@ + high-availability, high availability - adj. Hyphenate. For example, "high-availability cluster." Do not use "high availability." + adj. Hyphenate, except as part of a product name. For example, "high-availability cluster." + - + n. Two words. For example, "Support is available 24x7 to help maintain high availability." @@ -152,12 +153,11 @@ - homepage + home page - n. One word. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + n. Two words. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - diff --git a/en-US/I.xml b/en-US/I.xml index 1992d80..fabe045 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -133,10 +133,8 @@ The correct term for Intel's implementation of this architecture is "Intel® 64." - Until late 2006, Intel's official name for the architecture was "Intel EM64T" (for Extended Memory 64 Technology). - They have since changed the name to "Intel® 64" however, and Red Hat documentation should reflect this change. - - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. See also . @@ -307,9 +305,8 @@ IP switching - A new type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. Although the technology is new, it appears to be considerably faster than older router techniques. + A type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. This type of IP routing appears to be considerably faster than older router techniques. - diff --git a/en-US/L.xml b/en-US/L.xml index e04def0..2634e8e 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -54,7 +54,6 @@ Do not use. Use "omit" instead. - diff --git a/en-US/Language.xml b/en-US/Language.xml index fb6f3b4..4e0aed5 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -838,6 +838,54 @@
+ +
+ Phrasal Verbs + + Avoid using a two-word verb form (a phrasal verb) if a one-word equivalent exists. + + + + + + + + + Example + Improvement + + + + + + + click on + click + + + + fill in, fill out (a form) + complete (a form) + + + + leave out + omit + + + + print out + print + + + + + + + +
+ +
Anthropomorphism @@ -1265,7 +1313,7 @@ Numbers (move from N entry) --> - Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, write "The product was manufactured on 1 April 2021". + Instead of writing "The product was manufactured on 4/1/21", which is ambiguous, use a format in running text where the month is represented as a word rather than as a numeral, such as "The product was manufactured on 1 April 2021". diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 5b88655..549fd92 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -5,7 +5,6 @@ ]>
Punctuation - This section contains information on common punctuation topics. For more information, consult The Chicago Manual of Style, 17th Edition. @@ -426,15 +425,19 @@
Quotation Marks - - - In technical documentation, punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. - + + Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. + + +Remove this sentence, and leave it to chapter 4 to cover avoidance of slang. - @@ -486,5 +489,228 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
-
+ +
+ Referring to Punctuation Marks + + To refer to a punctuation mark or special character, use its name alone if it is one of the following standard characters: + + + . , : ; ' " ( ) [ ] ! ? + + + For another character, use its name followed by the symbol in parentheses. + + + Do not use the symbol on its own. + + Referring to Punctuation Marks + + + Use a semicolon to separate two parts of a sentence that can each stand on their own. + + + The path contains the library qualifier in braces, { }. + + + + For more details, see the IBM Style Guide. + + +
+ + +
+ Names of Punctuation Marks and Special Characters + + Use the names in the following table to refer to punctuation marks or special characters: + + + + + + + + + + Symbol + Name + + + + + + + & + Ampersand + + + + < > + Angle brackets + + + + ' + Apostrophe + + + + * + Asterisk + + + + @ + At sign + + + + \ + Backslash + + + + ` + Backtick + + + + { } + Braces + + + + [ ] + Brackets + + + + ^ + Caret + + + + ✓ + Check mark + + + + : + Colon + + + + , + Comma + + + + " " + Double quotation marks + + + + ... + Ellipsis + + + + — + Em dash + + + + – + En dash + + + + = + Equal sign + + + + ! + Exclamation point + + + + / + Forward slash + + + + > + Greater than symbol + + + + - + Hyphen or minus sign + + + + < + Less than symbol + + + + # + Number sign; use hash to refer to a hashtag in social media + + + + ( ) + Parentheses + + + + % + Percent sign + + + + . + Period; dot (when not referring to punctuation) + + + + + + Plus sign + + + + ? + Question mark + + + + ; + Semicolon + + + + ' ' + Single quotation marks + + + + ~ + Tilde + + + + _ + Underscore + + + + + + + +
+ +
\ No newline at end of file diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index d1112e6..92f53f6 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -19,7 +19,8 @@ Major update to align with some recent changes in IBM Style. Sentence case is required for captions, legends, and diagram labels. - All punctuation, including periods and commas, is now placed outside quotation marks unless the punctuation is part of the quotation. + + Punctuation: Added sections on referring to punctuation marks and names of punctuation marks and special characters. Rename Chapter 4 to "Choosing Appropriate Language": expand scope beyond slang and jargon, to cover inclusive language; avoiding ambiguities (moved from Chapter 2 and added more categories); dates and times (AM and PM are now written in uppercase without periods); and numbers. Usage A-Z: Various additions and updates. Corrected alphabetical sorting sequence. Moved items that are not literal term entries to an earlier chapter. Minor edits so the guide itself conforms with its own advice. diff --git a/en-US/W.xml b/en-US/W.xml index d363338..37ba5cf 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -61,12 +61,11 @@ - webpage + web page - n. One word. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + n. Two words. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. - From 1539c0bdaf0fd84bad915f131bee3b1c81266eea Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 21 Jul 2021 10:50:48 +0100 Subject: [PATCH 22/27] Fixed XML build errors --- en-US/Punctuation.xml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 549fd92..a445508 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -432,6 +432,7 @@ Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. +
-
Apostrophes @@ -511,7 +511,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> Use a semicolon to separate two parts of a sentence that can each stand on their own. - The path contains the library qualifier in braces, { }. + The path contains the library qualifier in braces, { }. @@ -577,17 +577,17 @@ Deleted paragraph now that DocBook tagging no longer applies. --> - { } + { } Braces - [ ] + [ ] Brackets - ^ + ^ Caret @@ -713,4 +713,6 @@ Deleted paragraph now that DocBook tagging no longer applies. --> +
+
\ No newline at end of file From 3566eb74876e6666fde9fec1374a9dfa291dfea8 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 21 Jul 2021 17:32:58 +0100 Subject: [PATCH 23/27] Inclusive language updates and additions --- en-US/B.xml | 13 +++++++++++++ en-US/Language.xml | 35 +++++++++++++++++++---------------- en-US/M.xml | 13 +++++++++++++ en-US/S.xml | 10 ++++++++++ en-US/W.xml | 13 +++++++++++++ 5 files changed, 68 insertions(+), 16 deletions(-) diff --git a/en-US/B.xml b/en-US/B.xml index ca95d34..a59c9da 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -208,6 +208,19 @@ + + + blacklist + + + Do not use. Use “denylist” or "blocklist". + + + 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. + + + + Boolean diff --git a/en-US/Language.xml b/en-US/Language.xml index 4e0aed5..88e9432 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -939,31 +939,34 @@ Numbers (move from N entry) -->
Inclusive Language - Red Hat, together with other companies and institutions in the IT industry, is committed to identifying and eliminating the use of language that might exclude or be offensive to certain groups of people. + In a blog post, Red Hat senior vice president and chief technology officer, Chris Wright, affirms a commitment for Red Hat to identify and replace problematic language that is potentially divisive and does not foster inclusion: - - Replace terms that reinforce cultural, racial, or other types of bias with an alternative. + + - - Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + Follow these guiding principles: - + + Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. Such usage reinforces a model that promotes racial bias. + + For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. - - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. - - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". + + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". Avoid binary gendered language, such as “he” or “she”, except to refer to a specific named person. Do not use “he or she”. Instead, use the ungendered “they” as the preferred pronoun. - - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + + Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. - - Avoid superlatives in job titles and descriptions, such as "ninja", "rockstar", or "evangelist". + + Avoid superlatives in job titles and descriptions, especially problematic terms such as “guru”, "ninja", "rockstar", or "evangelist". - - Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. + + Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time.
diff --git a/en-US/M.xml b/en-US/M.xml index cb9605f..3063520 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -41,6 +41,19 @@ + + + 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". + + + Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + + + + matrixes diff --git a/en-US/S.xml b/en-US/S.xml index 500ba43..b59f8c3 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -401,6 +401,16 @@ + + + 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)". + + + + smart card diff --git a/en-US/W.xml b/en-US/W.xml index 37ba5cf..a7a3ba0 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -93,6 +93,19 @@ + + + whitelist + + + Do not use. Use “allowlist". + + + 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. + + + + who, whom From ad5e28240354dfe195d4dd0f1d24607984e29565 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Thu, 22 Jul 2021 16:39:43 +0100 Subject: [PATCH 24/27] Further style guide updates --- en-US/A.xml | 14 ++++++++------ en-US/B.xml | 4 ++-- en-US/C.xml | 2 +- en-US/D.xml | 11 +++++++++++ en-US/Language.xml | 25 ++++++++++++++----------- en-US/M.xml | 10 ++++------ en-US/N.xml | 15 +-------------- en-US/O.xml | 16 ++++++---------- en-US/P.xml | 22 ++++++++++++---------- en-US/Punctuation.xml | 15 ++++++++------- en-US/Q.xml | 24 +++--------------------- en-US/R.xml | 24 ++++++------------------ en-US/S.xml | 18 +++++++----------- en-US/W.xml | 15 +++++++++++++-- 14 files changed, 96 insertions(+), 119 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index f19afdc..75cf57e 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -93,21 +93,23 @@ - - - AM + a.m. + + Use lowercase with periods, such as "11 a.m.". Use a nonbreaking space between the numeral and "a.m.". + + See also . - + diff --git a/en-US/B.xml b/en-US/B.xml index a59c9da..63b1d4b 100644 --- a/en-US/B.xml +++ b/en-US/B.xml @@ -213,10 +213,10 @@ blacklist - Do not use. Use “denylist” or "blocklist". + Do not use. Use "denylist" or "blocklist". - 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. diff --git a/en-US/C.xml b/en-US/C.xml index d21ba5a..59b63a9 100644 --- a/en-US/C.xml +++ b/en-US/C.xml @@ -195,7 +195,7 @@ cloud - Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase “c” when referring to cloud or cloud computing in a general sense. Use a capitalized “C” when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." + Although cloud is important to Red Hat's business, it is not a proper noun. Do not capitalize, unless it is part of a Red Hat product, service, solution, or business unit name. Use a lowercase "c" when referring to cloud or cloud computing in a general sense. Use a capitalized "C" when referring to the full name of official products, such as Red Hat CloudForms or Red Hat Cloud Foundations. See also "big data." diff --git a/en-US/D.xml b/en-US/D.xml index 6653646..4e62af4 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -142,6 +142,17 @@ + + + desire + + + Use "want" instead of "desire" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). + + + + + desktop diff --git a/en-US/Language.xml b/en-US/Language.xml index 88e9432..c1dad32 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -948,22 +948,22 @@ Numbers (move from N entry) --> Follow these guiding principles: - Do not use the terms “white” or "black" in a context where white is represented as good or black is represented as bad, such as “whitelist” and “blacklist”. 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 as "whitelist" and "blacklist". Such usage reinforces a model that promotes racial bias. - For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example “allowlist” instead of “whitelist”, or “blocklist” or “denylist” instead of “blacklist”. + For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example "allowlist" instead of "whitelist", or "blocklist" or "denylist" instead of "blacklist". - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of “master” is acceptable in other contexts, such as to refer to mastery of a skill. + Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". Avoid binary gendered language, such as “he” or “she”, except to refer to a specific named person. Do not use “he or she”. Instead, use the ungendered “they” as the preferred pronoun. + Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". Avoid binary gendered language, such as "he" or "she", except to refer to a specific named person. Do not use "he or she". Instead, use the ungendered "they" as the preferred pronoun. Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. - Avoid superlatives in job titles and descriptions, especially problematic terms such as “guru”, "ninja", "rockstar", or "evangelist". + Avoid superlatives in job titles and descriptions, especially problematic terms such as "guru", "ninja", "rockstar", or "evangelist". Such guidance, including judgement of what constitutes acceptable versus unacceptable use, will evolve over time. @@ -1322,23 +1322,26 @@ Numbers (move from N entry) --> Exception: Use of an all-numeric representation is allowed when space is limited, as in a user interface, or to enhance readability. In such cases, use the ISO date format with a 4-digit year (YYYY-MM-DD) and define the format in a header or legend. - - For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". + For times of day, use lowercase with periods, such as "11 a.m.". Use a nonbreaking space between the numeral and "a.m." or "p.m.". + - Use "noon" or "12 noon" instead of "12 PM". - Use "midnight" or "12 midnight" instead of "12 AM". + Use "noon" or "12 noon" instead of "12 p.m.". + Use "midnight" or "12 midnight" instead of "12 a.m.". Examples - The training class begins at 10 AM on 1 April 2021. + The training class begins at 10 a.m. on 1 April 2021. - The coffee break is from 2:00 PM to 2:30 PM. + The coffee break is from 2:00 p.m. to 2:30 p.m. diff --git a/en-US/M.xml b/en-US/M.xml index 3063520..c28b479 100644 --- a/en-US/M.xml +++ b/en-US/M.xml @@ -46,10 +46,10 @@ 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. + Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. @@ -130,8 +130,7 @@ - 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 fibre 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). @@ -235,9 +234,8 @@ - To make a mass storage device available. In Linux environments, for example, inserting a floppy disk into the drive is called mounting the floppy. + To make a mass storage device available. For example, inserting a USB flash drive is called mounting the drive. - diff --git a/en-US/N.xml b/en-US/N.xml index f129cd6..4ec6a2e 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -18,25 +18,12 @@ - - need - - - Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). - - - - - - - needs, needs to be, need to - Avoid when possible. Suggested alternatives include "must," "required," or "should." + Avoid when possible. Suggested alternatives include "must" or "required." - diff --git a/en-US/O.xml b/en-US/O.xml index d9abbef..f780786 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -20,12 +20,9 @@ object-oriented - Correct. Do not use "object oriented" or "objectoriented." It is a modifier, such as "Java is an object-oriented language." - - - - Also, do not use "object-orientated". + Correct. Do not use "object oriented," "objectoriented," or "object-orientated." It is a modifier, such as "Java is an object-oriented language." + @@ -36,10 +33,6 @@ n. Stands for original equipment manufacturer, which is a misleading term for a company that has a special relationship with computer producers. OEMs buy computers in bulk and customize them for a particular application. They then sell the customized computer under their own name. The term is a misnomer because OEMs are not the original manufacturers; they are the customizers. - - - To provide equipment to another company, an OEM, which customizes and markets the equipment. - @@ -78,7 +71,10 @@ 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". + + diff --git a/en-US/P.xml b/en-US/P.xml index 1f0826e..52325fd 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -19,6 +19,9 @@ + + See also . + @@ -28,8 +31,6 @@ n. Use to refer to a personal computer. - @@ -118,20 +119,23 @@ - - PM + p.m. + + Use lowercase with periods, such as "2 p.m.". Use a nonbreaking space between the numeral and "p.m.". + + See also . - + @@ -176,9 +180,8 @@ 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 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. @@ -316,7 +319,6 @@ PXE is a mandatory element of the WfM specification. To be considered compliant, PXE must be supported by the computer's BIOS and its NIC. - diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index a445508..e1046c9 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -527,11 +527,12 @@ Deleted paragraph now that DocBook tagging no longer applies. --> Use the names in the following table to refer to punctuation marks or special characters: + - + Names of Punctuation Marks and Special Characters - - + + Symbol @@ -607,8 +608,8 @@ Deleted paragraph now that DocBook tagging no longer applies. --> - " " - Double quotation marks + " + Double quotation mark @@ -692,8 +693,8 @@ Deleted paragraph now that DocBook tagging no longer applies. --> - ' ' - Single quotation marks + ' + Single quotation mark diff --git a/en-US/Q.xml b/en-US/Q.xml index 2754d0a..32244f2 100644 --- a/en-US/Q.xml +++ b/en-US/Q.xml @@ -6,32 +6,14 @@ Q - - Q and A - - - n. Abbreviation for "Question and Answer," this format is listed in the American Heritage Dictionary. - - - - In DocBook XML, the title is defined by the DocBook style sheets for the <qandadiv> element. The relevant generated text in English is "Q & A" and is localized automatically. - - - - - - - - qeth - Lowercase at all times. - + Lowercase at all times. diff --git a/en-US/R.xml b/en-US/R.xml index bc7ce25..5176aaa 100644 --- a/en-US/R.xml +++ b/en-US/R.xml @@ -34,6 +34,9 @@ Unprocessed. The term refers to data that is passed to an I/O device without being interpreted. In contrast, cooked refers to data that is processed before being passed to the I/O device. + + + The term can also refer to information that is not organized, formatted, or analyzed. The term comes from UNIX, which supports cooked and raw modes for data output to a terminal. In cooked mode, special characters, such as erase and kill, are processed by the device driver before being sent to the output device. @@ -41,17 +44,6 @@ - - - - raw data - - - Information that is not organized, formatted, or analyzed. - - - - read @@ -87,12 +79,11 @@ - real time/real-time + real time, real-time n. The actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." - adj. Use the hyphenated version. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor." @@ -126,7 +117,6 @@ Do not use to indicate a reference (within a manual) or a cross-reference (to another manual or documentation source). Use "See." - @@ -145,9 +135,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. For example, a user who dials in to a network from home with an analog modem or an ISDN connection dials in to a remote access server. An authenticated user can then access shared drives and printers as if they were physically connected to the office LAN. + 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. - @@ -209,9 +198,8 @@ roundtable, round table - v. Use the one-word form to refer to a type of event or gathering. + n. Use the one-word form to refer to a type of event or gathering. - n. Use the two-word form to refer to a circular table. diff --git a/en-US/S.xml b/en-US/S.xml index b59f8c3..fabaee0 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -21,8 +21,7 @@ The correct abbreviation for "Software-as-a-Service." - - See also . + See also . @@ -39,8 +38,7 @@ - - record + S-record Correct. Do not use "s-record," "Record," "s-Record," or any other variations. @@ -179,13 +177,13 @@ + setup - Use "setup" as a noun, "set up" as a verb, and "set-up" as an adjective. For example: + Use "setup" as a noun or an adjective, and "set up" as a verb. For example: - @@ -201,7 +199,7 @@ - Follow the set-up instructions included with the hardware. + Follow the setup instructions that are included with the hardware. @@ -264,9 +262,8 @@ share name - Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as "smbclient -L." + Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as smbclient -L or similar. - @@ -660,8 +657,7 @@ a programming and technical sense, it also means "Run the sourcesubcommand - Correct. Do not use "sub-command" or "verb." - + Correct. Do not use "sub-command" or refer to a subcommand as a "verb." A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example: diff --git a/en-US/W.xml b/en-US/W.xml index a7a3ba0..af55ffe 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -98,10 +98,10 @@ whitelist - Do not use. Use “allowlist". + Do not use. Use "allowlist". - 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. @@ -145,6 +145,17 @@ + + + desire + + + Use "want" instead of "wish" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). + + + + + From 378df636a664a82c375afec77f894775d0d78ffc Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 23 Jul 2021 11:53:42 +0100 Subject: [PATCH 25/27] Latest Style Guide updates --- en-US/T.xml | 3 +-- en-US/W.xml | 8 +++----- en-US/XYZ.xml | 8 +------- 3 files changed, 5 insertions(+), 14 deletions(-) diff --git a/en-US/T.xml b/en-US/T.xml index 8963ca9..f255be0 100644 --- a/en-US/T.xml +++ b/en-US/T.xml @@ -25,7 +25,6 @@ - telco @@ -149,8 +148,8 @@ - + time frame (n.) diff --git a/en-US/W.xml b/en-US/W.xml index af55ffe..99d767b 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -38,9 +38,8 @@ WCA - An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled PDA. + An abbreviation of "web clipping application," to extract static information from a web server and load that data onto a web-enabled personal digital assistant (PDA). - WCAs are also called "query applications." @@ -138,16 +137,15 @@ Correct. Do not combine into one word or hyphenate. - This is a window manager for the "X Window System." + This is a window manager for the X Window System. - - desire + wish Use "want" instead of "wish" when the reader's actions are optional (that is, they might not "need" something but might still "want" something). diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index cce5486..ee1c57b 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -32,13 +32,6 @@ Use where it accurately refers to the original Xen version of the package. You can refer to the distributed package as "Xen" if it is essentially the same as the upstream code. - - A referential use is one that describes the goods or services of an entity other than Red Hat, such as referring to Microsoft Windows as a technology that Red Hat competes with and integrates with. When referring to another entity's trademark, always use good trademark practices; that is, only use the trademark as an adjective followed by a noun; do not use a logo form of the trademark; do not make it more prominent than Red Hat marks; and do not incorporate the trademark into Red Hat product names. Here, the proper use would be "Xen hypervisor." - - - The Xen Trademark Policy is available at http://www.xenproject.org/trademark-policy.html. - - @@ -113,6 +106,7 @@ + Zip Code From 8d59c117bd5c9caa76576e5050cf02b8121663e7 Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Fri, 23 Jul 2021 14:25:42 +0100 Subject: [PATCH 26/27] Updated "ZIP Code". --- en-US/XYZ.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml index ee1c57b..d560434 100644 --- a/en-US/XYZ.xml +++ b/en-US/XYZ.xml @@ -106,14 +106,14 @@ - + + - Zip Code + ZIP Code - Correct. Do not use "zip code," "Zip code," or any other variation. + Use only for an address in the US, a US territory, or the Philippines. Otherwise, use "postal code". - From 96b1852f1356aafed894aae884d254efb8710fce Mon Sep 17 00:00:00 2001 From: Julian Cable Date: Wed, 28 Jul 2021 18:10:24 +0100 Subject: [PATCH 27/27] Two small fixes --- en-US/Design.xml | 2 +- en-US/F.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index ed0ba05..a8e10e5 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -128,7 +128,7 @@ Use "Navigate to" when moving through multiple GUI 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. - From example, "From the OpenShift web console, navigate to Monitoring → Alerting." + For example, "From the OpenShift web console, navigate to Monitoring → Alerting." diff --git a/en-US/F.xml b/en-US/F.xml index 571ab75..4120192 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -41,7 +41,7 @@ FAQ - When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an Q") not "a FAQ." The plural form is "FAQs." + When referring to a Frequently Asked Questions (FAQ) section of content, refer to it as "an FAQ" (to be read as "an F") not "a FAQ." The plural form is "FAQs."