Skip to content

Jcable/244 a zfixes #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
daobrien merged 27 commits into from
Jul 29, 2021
Merged

Jcable/244 a zfixes #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
79c595c
Tech editor comments on Chapter 2
Jun 17, 2021
5ed536f
Edits to Chapter 2
Jun 18, 2021
e0d113f
Added sections to Grammar.xml.
Jun 21, 2021
a7a60e8
Added and updated various style guide sections.
Jun 22, 2021
380404b
Updates to Style Guide
Jun 25, 2021
137ae93
Renamed Slang.xml to Language.xml and expanded its scope.
Jun 25, 2021
5111399
Updated Chapters 5-7.
Jun 28, 2021
523923b
Updated A-E term entries
Jun 29, 2021
5feb093
Updated usage term entries F-L.
Jun 30, 2021
dcb9750
Style guide updates
Jul 1, 2021
bdde6e4
Style Guide further updates
Jul 2, 2021
a537358
Updated L-P entries.
Jul 5, 2021
f75b28c
A-Z updates up to R
Jul 6, 2021
d3e9209
Updated "S" entries.
Jul 7, 2021
d6af246
Fix up some XML issues.
Jul 8, 2021
c278334
Style Guide updates A-Z and others
Jul 8, 2021
3e98291
Updated A-Z entries.
Jul 9, 2021
06f365e
Ongoing A-Z updates to align with IBM
Jul 9, 2021
345dab6
Deleting tmp files
Jul 9, 2021
5b979e6
Further style guide edits
Jul 9, 2021
6cfec44
Further style guide updates
Jul 20, 2021
1539c0b
Fixed XML build errors
Jul 21, 2021
3566eb7
Inclusive language updates and additions
Jul 21, 2021
ad5e282
Further style guide updates
Jul 22, 2021
378df63
Latest Style Guide updates
Jul 23, 2021
8d59c11
Updated "ZIP Code".
Jul 23, 2021
96b1852
Two small fixes
Jul 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions en-US/0-9.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Conventions_for_Writers_and_Editors.ent">
%BOOK_ENTITIES;
]>
<!-- Suggest not to use numbered chapters for these group separator headings. -->
<chapter id="a0-9">
<title>0-9</title>
<variablelist>
Expand All @@ -20,7 +21,7 @@
<term>2-track (IT)</term>
<listitem>
<para>
<emphasis>adj.</emphasis> A less common way to refer to bimodal or hybrid IT. See <xref linkend="bimodal-it" />
<emphasis>adj.</emphasis> A less common way to refer to bimodal or hybrid IT. See <xref linkend="bimodal-it" />.
</para>

</listitem>
Expand All @@ -30,7 +31,7 @@
<term>3-D</term>
<listitem>
<para>
<emphasis>adj., n.</emphasis>. Correct. Do not use 3D, 3-d, or other variations.
<emphasis>adj., n.</emphasis> Correct. Do not use 3D, 3-d, or other variations.
</para>

</listitem>
Expand Down
206 changes: 112 additions & 94 deletions en-US/A.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,32 @@
]>
<chapter id="a">
<title>A</title>
<!-- Some of the entries were not listed in alphabetical order. -->
<variablelist>
<!-- Entries previously used a mixture of "v." and "vb." to denote a verb. Changed all occurrences to "v." -->
<varlistentry id="amp-and-">
<term>"&amp;" and "+"</term>
<listitem>
<para>
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.
</para>
</listitem>

</varlistentry>
<varlistentry id="above">
<term role="caution">above</term>
<listitem>
<para>
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.
</para>

</listitem>

</varlistentry>
<!-- Removed "acronyms" entry (as it is not a literal term) and added this content instead to section 3.6. -->

<varlistentry id="agile-development">
<term role="true">agile</term>
<term role="true">agile development</term>
Expand All @@ -37,128 +52,91 @@

</listitem>

</varlistentry>
<varlistentry id="am">
<term role="true">a.m.</term>
<term role="false">am</term>
<listitem>
<para>
Correct. Use the lowercase form and include the periods, and use a preceding space.
</para>
<para>
See also <xref linkend="pm"/>.
</para>
<para>
See <citetitle>The IBM Style Guide</citetitle> for a full discussion of how to represent times.
</para>

</listitem>

</varlistentry>
<varlistentry id="all-in-one">
<term role="true">all-in-one</term>
<term role="false">allinone</term>
<listitem>
<para>
<emphasis>n., adj.</emphasis> Correct. Hyphenate in both cases. Do not use "allinone" or other variations.
<emphasis>n., adj.</emphasis> Hyphenate in both places. Do not use "allinone" or other variations.
</para>

</listitem>

</varlistentry>
<varlistentry id="AMD64">
<term role="true">AMD64</term>

<varlistentry id="alternate">
<term role="true">alternate</term>
<listitem>
<para>
Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture.
</para>
<para>
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.
<emphasis>v.</emphasis> "Alternate" as a verb means to change between two states or options.
</para>
<para>
See also <xref linkend="Intel64"/>.
See also <xref linkend="alternative"/>.
</para>
<note>
<para>
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="http://www.amd.com/us/aboutamd/Pages/trademarks.aspx" />.
</para>
<para>
For more information about Intel&reg; trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />.
</para>

</note>

</listitem>

</varlistentry>
<varlistentry id="atm">
<term role="true">ATM</term>
<listitem>
<para>
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.
</para>

</listitem>

</varlistentry>
<varlistentry id="above">
<term role="caution">above</term>

<varlistentry id="alternative">
<term role="true">alternative</term>
<listitem>
<para>
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.
<emphasis>adj.</emphasis> 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 ..."
</para>
<para>
See also <xref linkend="alternate"/>.
</para>

</listitem>

</varlistentry>
<varlistentry id="acronyms">
<term>acronyms</term>
<varlistentry id="am">
<term role="true">a.m.</term>
<!-- <term role="false">am</term> -->
<listitem>
<para>
An acronym is a word formed from the initial letters of a name, such as ROM for <emphasis>R</emphasis>ead <emphasis>O</emphasis>nly <emphasis>M</emphasis>emory, or by combining initial letters or part of a series of words, such as LILO for <emphasis>LI</emphasis>nux <emphasis>LO</emphasis>ader.
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.
</para>
<para>
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.
<para>
Use lowercase with periods, such as "11&nbsp;a.m.". Use a nonbreaking space between the numeral and "a.m.".
</para>
<para>
To form the plural of an acronym, add a trailing, lowercase "s," or "es," for example, ROMs, PINs, BIOSes.
</para>

</listitem>

</varlistentry>
<varlistentry id="alternate">
<term role="true">alternate</term>
<listitem>
<!-- Not implementing this change yet.
<para>
<emphasis>vb.</emphasis> "Alternate" as a verb means to change between two states or options.
</para>
Use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11&nbsp;AM".
</para> -->
<para>
See also <xref linkend="alternative"/>.
See also <xref linkend="pm"/>.
</para>
<!-- <para>
See the <citetitle>IBM Style Guide</citetitle> for a full discussion of how to represent times.
</para> -->

</listitem>

</varlistentry>

<varlistentry id="alternative">
<term role="true">alternative</term>
<varlistentry id="AMD64">
<term role="true">AMD64</term>
<listitem>
<para>
<emphasis>adj.</emphasis> 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..."
Correct. Do not use "Hammer," "x86_64," "x86-64," "x64," "64-bit x86" or other variations as the name of this architecture.
</para>
<para>
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.
</para>
<para>
See also <xref linkend="alternate"/>.
See also <xref linkend="Intel64"/>.
</para>
<note>
<para>
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, see the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />.
</para>
<!-- Updated URL for AMD trademarks. -->
<para>
For more information about Intel&reg; trademarks, see <ulink url="http://www.intel.com/content/www/us/en/legal/trademarks.html" /> and <ulink url="http://www.intel.com/content/www/us/en/trademarks/trademarks.html" />.
</para>

</note>

</listitem>

Expand All @@ -170,12 +148,26 @@
Avoid if possible.
Try to rewrite to make the available options explicit and clear.
Do not write <emphasis>this and/or that</emphasis>.
Write <emphasis>this or that or both</emphasis>.
Write <emphasis>this or that, or both</emphasis>.
</para>

</listitem>

</varlistentry>

<!-- Added "appendixes" entry. -->
<varlistentry id="appendixes">
<term>appendixes</term>
<listitem>
<para>
Correct. This is the correct plural form for US English spelling. Do not use "appendices."
</para>

</listitem>

</varlistentry>

<!-- Commenting out this entry as it is not a literal term entry. Consider moving elsewhere, such as to Section 3.7 and expand scope of that section?
<varlistentry id="application">
<term>application</term>
<listitem>
Expand All @@ -193,13 +185,15 @@
</listitem>

</varlistentry>
-->

<varlistentry id="applixware">
<term role="true">Applixware</term>
<term role="false">Applix</term>
<term role="false">ApplixWare</term>
<listitem>
<para>
Correct.
"Applixware" is correct.
Do not use "Applix" or "ApplixWare."
</para>

Expand All @@ -211,9 +205,9 @@
<listitem>
<para>
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."
</para>
</listitem>
Expand All @@ -235,7 +229,7 @@
<term role="caution">as-a-Service</term>
<listitem>
<para>
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.
</para>
<itemizedlist>
Expand All @@ -259,7 +253,7 @@
</listitem>
<listitem>
<para>
FaaS (Function[s]-as-a-Service)
FaaS (Functions-as-a-Service)
</para>

</listitem>
Expand Down Expand Up @@ -301,27 +295,28 @@
<itemizedlist>
<listitem>
<para>
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.
</para>

</listitem>
<listitem>
<para>
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).
</para>
<!-- When would all capitals be used? -->

</listitem>
<listitem>
<para>
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.
</para>

</listitem>
<listitem>
<para>
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.
</para>

</listitem>
Expand All @@ -330,7 +325,30 @@

</listitem>

<!-- Suggested addition of "as long as" -->
</varlistentry>
<varlistentry id="as-long-as">
<term role="caution">as long as</term>
<listitem>
<para>
Use only to refer to a comparison of length or time. Otherwise, use an alternative, such as "provided that".
</para>

</listitem>

</varlistentry>
<varlistentry id="atm">
<term role="true">ATM</term>
<listitem>
<para>
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.
</para>

</listitem>

</varlistentry>

<!--<varlistentry id="auto-detect">
<term>auto-detect</term>
<listitem>
Expand All @@ -346,7 +364,7 @@
<listitem>
<para>
Always lowercase.
This refers to the kernel-based automount utility.
It refers to the kernel-based automount utility.
No other forms are recognized.
</para>

Expand Down
Loading