Skip to content

Commit

Permalink
Closes #456
Browse files Browse the repository at this point in the history 
Part 2 of running Vale over the style guide.
I also addressed a few other issues along the way, such as one sentence per
line and removing old comments.

Language.xml in particular contains lots of examples of what not to do, so it
produces lots of noise in Vale.
  • Loading branch information
daobrien committed Feb 2, 2023
1 parent 1de7eec commit 70453b7
Show file tree
Hide file tree
Showing 4 changed files with 167 additions and 97 deletions.
116 changes: 64 additions & 52 deletions en-US/I.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,28 +36,16 @@
</listitem>

</varlistentry>
<!-- The following product name is now obsolete.
</varlistentry>
<varlistentry id="ibm-server-system-p">
<term>IBM eServer System p</term>
<listitem>
<para>
"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".
</para>
</listitem>
-->
<varlistentry id="ibm-z">
<term>IBM Z</term>
<listitem>
<para>
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.
IBM Z is a family name used by IBM for all its mainframe computers from the Z900 on.
In 2017, the official family was changed to IBM Z from IBM z Systems.
</para>

</listitem>

<!-- Added the following entry -->
</varlistentry>
<varlistentry id="ie">
<term>i.e.</term>
Expand All @@ -80,12 +68,13 @@

</varlistentry>

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

</listitem>
Expand All @@ -96,7 +85,10 @@
<term>InfiniBand</term>
<listitem>
<para>
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.
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.
</para>
<para>
"Open InfiniBand" is deprecated and should not be used.
Expand All @@ -109,7 +101,8 @@
<term>inline</term>
<listitem>
<para>
<emphasis>adj.</emphasis> Always one word. Do not hyphenate.
<emphasis>adj.</emphasis> Always one word.
Do not hyphenate.
</para>

</listitem>
Expand All @@ -119,7 +112,8 @@
<term>insecure</term>
<listitem>
<para>
<emphasis>adj.</emphasis> Correct. Do not use "nonsecure" or "non-secure".
<emphasis>adj.</emphasis> Correct.
Do not use "nonsecure" or "non-secure".
</para>

</listitem>
Expand All @@ -129,7 +123,8 @@
<term>installation program</term>
<listitem>
<para>
<emphasis>n.</emphasis> Correct. Do not use "installer" unless it is a formal part of the product or technology.
<emphasis>n.</emphasis> Correct.
Do not use "installer" unless it is a formal part of the product or technology.
</para>

</listitem>
Expand All @@ -139,12 +134,12 @@
<term role="true">Intel 64</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.
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 Intel's implementation of this architecture is "Intel&reg;&nbsp;64".

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.
</para>
<para>
See also <xref linkend="AMD64"/>.
Expand Down Expand Up @@ -179,7 +174,8 @@
<term>Intel Tolapai / Intel® EP80579 Integrated Processor</term>
<listitem>
<para>
Do not use the code-name, "Tolapai". Use the official brand name "Intel® EP80579 Integrated Processor".
Do not use the code-name, "Tolapai".
Use the official brand name "Intel® EP80579 Integrated Processor".
</para>

</listitem>
Expand All @@ -189,10 +185,15 @@
<term>Intel Virtualization Technology (Intel VT)</term>
<listitem>
<para>
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".
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".
</para>
<para>
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)".
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)".
</para>

</listitem>
Expand All @@ -213,7 +214,8 @@
<term>interesting</term>
<listitem>
<para>
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.
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.
</para>

</listitem>
Expand All @@ -233,7 +235,8 @@
<term>Internet of Things (IoT)</term>
<listitem>
<para>
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.
</para>
<para>
The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure.<footnote> <para>
Expand All @@ -259,10 +262,17 @@
<term>I/O</term>
<listitem>
<para>
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; devices such as printers are output-only.
A writable CD is both an input and an output device.
</para>
<para>
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.
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.
</para>

</listitem>
Expand All @@ -272,7 +282,9 @@
<term>IOPS</term>
<listitem>
<para>
Correct. All caps. Stands for input/output operations per second.
Correct.
All caps.
Stands for input/output operations per second.
</para>

</listitem>
Expand All @@ -282,7 +294,9 @@
<term>IP</term>
<listitem>
<para>
Correct. Stands for Internet Protocol. Capitalize both letters.
Correct.
Stands for Internet Protocol.
Capitalize both letters.
</para>

</listitem>
Expand All @@ -292,7 +306,9 @@
<term>IP Masquerade</term>
<listitem>
<para>
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.
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.
</para>
<para>
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.
Expand All @@ -305,7 +321,9 @@
<term>IPsec</term>
<listitem>
<para>
IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec".
IPsec stands for Internet Protocol security.
According to its RFC, IPsec should be used.
Do not use "IPSec".
</para>

</listitem>
Expand All @@ -315,7 +333,9 @@
<term>IP switching</term>
<listitem>
<para>
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.
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 previous router techniques.
</para>

</listitem>
Expand Down Expand Up @@ -345,16 +365,20 @@
<term>Itanium</term>
<listitem>
<para>
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.
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.
</para>
<para>
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.
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.
</para>
<para>
Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications.
</para>
<para>
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.
</para>

</listitem>
Expand All @@ -364,26 +388,14 @@
<term>Itanium&nbsp;2</term>
<listitem>
<para>
Itanium&nbsp;2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2".
</para>

</listitem>

</varlistentry>

<!-- Obsolete - now superseded by IBM Power Systems running IBM i.
<varlistentry id="iseries">
<term>ISeries</term>
<listitem>
<para>
IBM eServer System i is correct for the first reference in a manual; use IBM System i or System i for subsequent references. Do not use "iSeries".
Itanium&nbsp;2 is correct.
Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2".
</para>

</listitem>

</varlistentry>

-->
</variablelist>
</chapter>

13 changes: 10 additions & 3 deletions en-US/K.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,10 @@
<term>kernel</term>
<listitem>
<para>
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.
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 but still provide 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.
</para>

</listitem>
Expand All @@ -63,7 +66,8 @@
<term>kernel panic</term>
<listitem>
<para>
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.
Correct.
Many different 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.
</para>

</listitem>
Expand Down Expand Up @@ -148,7 +152,10 @@
<term>kill</term>
<listitem>
<para>
If terminating a UNIX process, use "kill". For example, to terminate the process, type <command>kill <replaceable>&lt;PID&gt;</replaceable></command>. If terminating a Windows process, use "terminate". For example, "To terminate the process, press <keycap>Q</keycap>."
If terminating a UNIX process, use "kill".
For example, to terminate the process, type <command>kill <replaceable>&lt;PID&gt;</replaceable></command>.
If terminating a Windows process, use "terminate".
For example, "To terminate the process, press <keycap>Q</keycap>."
</para>

</listitem>
Expand Down
12 changes: 9 additions & 3 deletions en-US/L.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,11 @@
<term>load balancing</term>
<listitem>
<para>
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.
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 use 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.
</para>

</listitem>
Expand All @@ -170,12 +174,14 @@
<term>logical topology</term>
<listitem>
<para>
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.
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.
</para>

</listitem>

<!-- Added entries for "log in" and "log in to". -->
</varlistentry>
<varlistentry id="login">
<term>login, log in</term>
Expand Down
Loading

0 comments on commit 70453b7

Please sign in to comment.