From 7bedd8636c1ba1e5c51aa471559c4905d1836ac5 Mon Sep 17 00:00:00 2001 From: daobrien Date: Sun, 9 Feb 2020 08:24:19 +1000 Subject: [PATCH 1/7] Refactoring chapter 'A' to be parseable. #161 Covered most of the entries, adding true|false (=correct|incorrect) attributes to terms. A couple of entries were split and parts relocated to other files. One entry commented out due to questionable validity. --- en-US/A.xml | 102 +++++++++++++++++++++++++++++++++++----------------- en-US/I.xml | 29 +++++++++++++++ en-US/P.xml | 16 +++++++++ 3 files changed, 114 insertions(+), 33 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 41aa978..75f8d26 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -17,7 +17,8 @@ - agile, agile development + 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. @@ -27,7 +28,8 @@ - air gap + 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. @@ -36,12 +38,15 @@ - - a.m. and p.m. + + a.m. Correct. Use the lowercase form and include the periods, and use a preceding space. + + See also . + See The IBM Style Guide for a full discussion of how to represent times. @@ -50,7 +55,8 @@ - all-in-one + all-in-one + allinone n., adj. Correct. Hyphenate in both cases. Do not use "allinone" or other variations. @@ -59,15 +65,19 @@ - - AMD64 and Intel 64 + + 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." 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 implementations specifically. + 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 . @@ -82,20 +92,23 @@ - ATM + 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 used with older technologies. + 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. - above + above - Do not use to refer to information mentioned previously. When documents are converted to online format, the information may no longer be "above." Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. + Do not use to refer to information mentioned previously. + When documents are converted to online format, the information may no longer be "above." + Use a cross-reference if the referenced material is sufficiently removed, or write "as mentioned previously" instead. @@ -117,41 +130,52 @@ - - alright, all right + + alternate - Avoid if at all possible. These terms carry a more familiar or colloquial tone than is expected in Red Hat documentation. Use more formal alternatives such as "correct" or "as expected," depending on context. + vb. "Alternate" as a verb means to change between two states or options. + + See also . + - - alternate + + + alternative - Do not use this to mean "an alternative to 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. 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..." + + See also . + - and/or + 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. + 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. - - applications + + application - When used as a proper name, use the capitalization of the product, such as GNUPro, Source-Navigator, and Red Hat Enterprise Linux. When used as a command, use lowercase as appropriate, such as "To start GCC, type gcc." + When used as a proper name, use the capitalization of the product, such as GNUPro, Source-Navigator, and Red Hat Enterprise Linux. + When used as a command, use lowercase as appropriate, such as "To start GCC, type gcc." @@ -164,7 +188,9 @@ - Applixware + Applixware + Applix + ApplixWare Correct. Do not use "Applix" or "ApplixWare." @@ -177,25 +203,33 @@ 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 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. For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." + 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. + 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. + For example, a sentence that mentions rearchitecting might require "refactoring" as a replacement rather than "rebuilding." - as well as + 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." + 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 + as-a-Service - Be aware that there is a great deal of overlap in as-a-Service acronyms. To avoid confusion, always spell out the full term on first possible use. + Be aware that there is a great deal of overlap in as-a-Service acronyms. + To avoid confusion, always spell out the full term on first use. @@ -288,7 +322,7 @@ - + - autofs + autofs - Always lowercase. This refers to the kernel-based automount utility. No other forms are recognized. + Always lowercase. + This refers to the kernel-based automount utility. + No other forms are recognized. diff --git a/en-US/I.xml b/en-US/I.xml index d5c1977..84703f8 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -99,6 +99,35 @@ + + 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 diff --git a/en-US/P.xml b/en-US/P.xml index 71e6aaf..c110e46 100644 --- a/en-US/P.xml +++ b/en-US/P.xml @@ -111,6 +111,22 @@ + + p.m. + + + Correct. Use the lowercase form and include the periods, and use a preceding space. + + + See also . + + + See The IBM Style Guide for a full discussion of how to represent times. + + + + + pop-up From 32db97411fcdeedb1d7532a4aef15300593f99c4 Mon Sep 17 00:00:00 2001 From: Nikki Lucas Date: Tue, 14 Jul 2020 10:33:54 -0400 Subject: [PATCH 2/7] update url and link text to v2 and v3; remove point release references --- index.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 3a54732..c27b286 100644 --- a/index.html +++ b/index.html @@ -44,13 +44,13 @@

- - RHT DocBook XML Guide v2.1 + + RHT DocBook XML Guide v2

- - RHT DocBook XML Guide v3.0 + + RHT DocBook XML Guide v3

From 56b30bc3f09dd4dbdc09ed8836667ab9e47ad689 Mon Sep 17 00:00:00 2001 From: Sam Ffrench Date: Thu, 23 Jul 2020 15:01:06 +0100 Subject: [PATCH 3/7] Added "navigate to" entry and navigating through multiple GUI options. Addresses #188 --- en-US/Design.xml | 9 +++++++++ en-US/N.xml | 12 ++++++++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index a970b4a..9200e86 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -91,7 +91,16 @@ See the Computer Interfaces 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, 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 diff --git a/en-US/N.xml b/en-US/N.xml index a7d95fa..b176204 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -6,6 +6,15 @@ 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." + + + + need @@ -26,7 +35,7 @@ - + .NET @@ -124,4 +133,3 @@ - From 8b259c7218814ca9f287e92c8fb0f3b7e639b141 Mon Sep 17 00:00:00 2001 From: Sam Ffrench Date: Fri, 24 Jul 2020 14:35:16 +0100 Subject: [PATCH 4/7] Correcting title case and adding do not use to "navigate to" --- en-US/Design.xml | 2 +- en-US/N.xml | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index 9200e86..e885f43 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -92,7 +92,7 @@ See the Computer Interfaces chapter in The IBM Style Guide for more information.
- Navigating through multiple GUI options + 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. diff --git a/en-US/N.xml b/en-US/N.xml index b176204..4838241 100644 --- a/en-US/N.xml +++ b/en-US/N.xml @@ -12,6 +12,9 @@ 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. + From c32f7101c91ba52ac95caf08509b160594dd6265 Mon Sep 17 00:00:00 2001 From: Sam Ffrench Date: Fri, 4 Sep 2020 15:57:04 +0100 Subject: [PATCH 5/7] Update URL for titlecase web site --- en-US/Design.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Design.xml b/en-US/Design.xml index a970b4a..d348298 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -17,7 +17,7 @@ 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 http://titlecase.com. + The currently accepted reference for determining title case is https://titlecase.com/titlecase. From 098d27187d07292450e4cd8e8f23e3e9cb9f6d51 Mon Sep 17 00:00:00 2001 From: daobrien Date: Mon, 7 Sep 2020 15:12:48 +1000 Subject: [PATCH 6/7] Updates for #161. General design improvements, wording updates. --- en-US/A.xml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/en-US/A.xml b/en-US/A.xml index 75f8d26..26b30c4 100644 --- a/en-US/A.xml +++ b/en-US/A.xml @@ -40,6 +40,7 @@ a.m. + am Correct. Use the lowercase form and include the periods, and use a preceding space. @@ -118,10 +119,14 @@ acronyms - 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. + 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. + 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," for example, ROMs, PINs, BIOSes. @@ -164,7 +169,8 @@ 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. + Do not write this and/or that. + Write this or that or both. @@ -193,7 +199,8 @@ ApplixWare - Correct. Do not use "Applix" or "ApplixWare." + Correct. + Do not use "Applix" or "ApplixWare." @@ -306,7 +313,9 @@ - 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). + 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). From ed0c2775161387111db82e142be9e988cdfb5375 Mon Sep 17 00:00:00 2001 From: daobrien Date: Fri, 11 Sep 2020 14:01:23 +1000 Subject: [PATCH 7/7] Redo section on formatting lists. Somehow this patch got lost. It's been reviewed already so just readding and publishing. --- en-US/Translation.xml | 114 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 104 insertions(+), 10 deletions(-) diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 361f504..c0cfaa1 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -10,16 +10,107 @@
Sentence Structure - - Using Lists Correctly + + This section helps to describe 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, such as Zanata, 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 these are not complete sentences, they can be difficult to translate. - - - - Use an ordered list when the order of entries is important, or if you need to refer to one of the entries from elsewhere in your document. - + + The following general guidelines apply to lists: + + + + 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. + Titles are optional. + + + + + Ordered lists + + + These 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. + Titles are optional. + + + + + Variable lists + + + These appear as a list of terms followed by definitions. + Use this list type to list and describe a series of terms, such as variables, command options or arguments, and similar items. + Titles are optional. + (This list is written as a variable list.) + 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. + + + + + 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. + + + + + + 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. + 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: + + + + + Nested lists. + Note that 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 very simple 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. @@ -87,13 +178,15 @@ - +
+
+ +
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. - @@ -124,6 +217,7 @@
+