Skip to content

Commit

Permalink
Merge commits from dev to master branch for 6.2 release (#565)
Browse files Browse the repository at this point in the history 
* Working on #450.

* Run Vale over Design.xml.

This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to
try to handle in one issue and PR.

* Ongoing updates for #456

* Closes #456

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.

* s/may/might/ per Julian's review.

* Working on #457 Run Vale of the style guide part 3.

* Closes #457 Run Vale over the style guide, part 3.

* Remove spurious space.

* Closes #458 Run Vale over style guide part 4.

* Closes #365 Remove DocBook references.

* Closes #78 Update entry for "virtualized".

Basically copy/paste from corp guide.

* Closes #355. Improve a bit of formatting.

* feat: Add advice on naming the default branch in an inclusive way. (#493)

* feat: Add advice on naming the default branch in an inclusive way.

* Update en-US/Language.xml

Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com>

* Update en-US/Language.xml

Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com>

* Update en-US/Language.xml

Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com>

---------

Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com>

* Updated section about writing titles (#492)

* Updated section about writing titles

* Reverted title ID

* Further edits

* Updated guidance on continuation prompts (#494)

* Various fixes for 6.1 release (#495)

* Various fixes for 6.1 release

* XML fix

* Updated IBM Style access info (#496)

* Updated term entries (#497)

* Added guidance on omitting part of an output (#500)

* Added guidance on omitting part of an output

* Updated wording

* Typo fix

* Updated sample names and other small fixes (#502)

* Various fixes (#512)

* Implementing various feedback suggestions from Rachel (#513)

* Implementing various feedback suggestions from Rachel

* Addressed review comments

* Addressed further review comment

* Added more punctuation guidance (#515)

* Added more punctuation guidance

* Implemented review feedback

* Updated audience description (#518)

* Updated audience description

* Further updated audience wording

* Adding information about posessives (#519)

* feat: added section about posessives

* feat: here's the actual section

* fix: made some revisions

* Content and formatting updates

* Update en-US/Punctuation.xml

Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com>

* fix: made some revisions

* fix: made another revision

* Removed company name and restructured section

* added link in section 3.6

* Final XML fix

---------

Co-authored-by: Julian Cable <jcable@redhat.com>
Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com>

* Updated view and edit files section

* Added release notes for 6.1 and updated version information (#522)

* updating homepage (#525)

* 6.2 quick fixes (#544)

* Some updates concerning punctuation (#545)

* Updated guidance for punctuation and special characters

* Enhanced guidance about punctuation in lists

* Minor formatting

* Content and formatting

* Applied feedback

* Minor fixes

* Word usage updates: screenshot, lookup, see/refer to (#546)

* Word usage updates: screenshot, lookup, see/refer to

* Addresses one comment

* Updates to see/refer to entries

* Minor fix

* Line continuation for multiple operating systems (#548)

* Line continuation for multiple operating systems

* Minor edit

* Add 64-bit architecture guidance (#547)

* Add 64-bit architecture guidance

* Implementing edits from review

* Updated Boolean guidance and a bug fix (#551)

* Updated Boolean guidance and a bug fix

* Update to Boolean entry

* Reworked entries for tar, tarball, untar, unzip, zip (#552)

* Clarify capitalization for table titles (#553)

* Updates on referring to object names and using realistic usernames (#554)

* Updates on referring to object names and using realistic usernames

* Apply review comments

* Updates for apostrophes and quotation marks (#557)

* Updates for apostrophes and quotation marks

* Updated list of punctuation marks

* Updated guidance about titles (#559)

* Updated guidance about titles

* Change 'book' to 'publication'

* Footnote update (#560)

* adding ulink tag to a url

* Replace an invalid URL

---------

Co-authored-by: Julian Cable <jcable@redhat.com>

* fix(docs): add some build instructions (#562)

* fix(docs): add some build instructions

* feat: add build shortcut

* Added small comment

---------

Co-authored-by: julian-cable <jcable@redhat.com>

* Corrected some titles to use title case (#563)

* Add release notes and update version info (#564)

* Add release notes and update version info

* Minor wording fix

---------

Co-authored-by: daobrien <noreply@solaris.milky.way>
Co-authored-by: David O'Brien <daobrien@users.noreply.github.com>
Co-authored-by: mweetman-redhat <mweetman@redhat.com>
Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com>
Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com>
Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com>
Co-authored-by: Alex Corcoles <alex@pdp7.net>
  • Loading branch information
@julian-cable @daobrien
@mweetman-redhat @CBID2 @rclee33 @harpasin @alexpdp7
8 people committed Feb 27, 2024
1 parent 4c54b6d commit ae704b2
Show file tree
Hide file tree
Showing 36 changed files with 926 additions and 288 deletions.
16 changes: 16 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,19 @@ The Red&nbsp;Hat Style Guide and Word Usage Dictionary is a joint effort by vari
It covers 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.

It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions.

Dependencies:

```
$ sudo dnf install publican
```

Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that.

To build:

```
$ publican build --langs=en-US --formats html
```

Generates `tmp/en-US/html/index.html`.
3 changes: 3 additions & 0 deletions build
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#!/bin/sh

publican build --langs en-US --formats html
73 changes: 72 additions & 1 deletion en-US/0-9.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,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. Refer to <xref linkend="bimodal-it" />.
</para>

</listitem>
Expand All @@ -38,6 +38,77 @@

</varlistentry>

<varlistentry id="a64-bit">
<term role="true">64-bit ARM</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
This term can refer to both AArch66/`aarch64` and to ARM64/`arm64`.
</para>
<para>
Use this format in general cases to refer to names of the architecture for various cloud providers.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Examples:
</para>
<itemizedlist>
<listitem>
<para>
Amazon Web Services (AWS) on 64-bit ARM systems
</para>
</listitem>
<listitem>
<para>
Machine types for Microsoft Azure on 64-bit ARM infrastructures
</para>
</listitem>
</itemizedlist>
<para>
Refer also to <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
</para>

</listitem>

</varlistentry>
<varlistentry id="a64-bit-x86">
<term role="true">64-bit x86</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the x86 architecture.
This term is a synonym of x86_64.
Use this format in general cases to refer to names of the architecture for various cloud providers.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Examples:
</para>
<itemizedlist>
<listitem>
<para>
Amazon Web Services (AWS) on 64-bit x86 systems
</para>
</listitem>
<listitem>
<para>
Machine types for Microsoft Azure on 64-bit x86 infrastructures
</para>
</listitem>
</itemizedlist>
<para>
Refer also to <xref linkend="a64-bit"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
</para>

</listitem>

</varlistentry>

</variablelist>
</chapter>

126 changes: 114 additions & 12 deletions en-US/A.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
<emphasis>v.</emphasis> "Alternate" as a verb means to change between two states or options.
</para>
<para>
See also <xref linkend="alternative"/>.
Refer also to <xref linkend="alternative"/>.
</para>

</listitem>
Expand All @@ -84,7 +84,7 @@
"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"/>.
Refer also to <xref linkend="alternate"/>.
</para>

</listitem>
Expand All @@ -97,38 +97,140 @@
For times of day, use uppercase without periods, and use a preceding nonbreaking space after the numeral, for example "11&nbsp;AM".
</para>
<para>
See also <xref linkend="pm"/>.
Refer also to <xref linkend="pm"/>.
</para>

</listitem>

</varlistentry>
<varlistentry id="aarch64">
<term role="true">AArch64, aarch64</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term when referring to operating systems and server instances, for example Red&nbsp;Hat Enterprise Linux, Fedora, CoreOS, and other Linux distributions.
</para>
<para>
Use the uppercase (AArch64) format in general cases when referring to system architecture.
Use the lowercase (aarch64) format only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Examples:
</para>
<itemizedlist>
<listitem>
<para>
When running Red&nbsp;Hat Enterprise Linux with an AArch64 system, run the following commands:
</para>
</listitem>
<listitem>
<para>
Specify the system architecture of your cluster, such as <code>x86_64</code> or <code>aarch64</code>.
</para>
</listitem>
</itemizedlist>
<para>
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="AMD64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
</para>

</listitem>

</varlistentry>
<varlistentry id="AMD64">
<term role="true">AMD64</term>
<term role="true">AMD64, amd64</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.
<emphasis>n.</emphasis> The AMD 64-bit version of the x86 architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), or command-line interface (CLI) objects.
</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.
Use the uppercase format (AMD64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
Use the lowercase format (amd64) only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Examples:
</para>
<itemizedlist>
<listitem>
<para>
This operator is supported on AMD64 and ARM64 platforms.
</para>
</listitem>
<listitem>
<para>
In this scenario, <code>amd64</code> is a valid value for X.
</para>
</listitem>
</itemizedlist>
<!-- <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="Intel64"/>.
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="ARM64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
</para>
<note>
<!-- <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" />.
The AMD64 logo is trademarked; the term "AMD64" is not. For more information about AMD trademarks, refer to the <citetitle>AMD Trademark Information</citetitle> page at <ulink url="https://www.amd.com/en/corporate/trademarks" />.
</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" />.
For more information about Intel&reg; trademarks, refer to <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>
</note> -->

</listitem>

</varlistentry>
<varlistentry id="ARM64">
<term role="true">ARM64, arm64</term>
<listitem>
<para>
<emphasis>n.</emphasis> A 64-bit version of the ARM architecture.
Use this term for Red&nbsp;Hat OpenShift Container Platform attributes, Kubernetes, operators, application programming interfaces (APIs), and command-line interface (CLI) objects.
</para>
<para>
Use the uppercase format (ARM64) in general sentences when referring to Red&nbsp;Hat OpenShift Container Platform features.
Use lowercase format (arm64) only when referring to objects or parameters.
It can be styled as code (monospace font or a code-styled block) when referring to code.
</para>
<para>
Cloud providers might use different formats of this term to refer to architectures.
If you are documenting code, commands, or outputs, then confer with your subject-matter expert on the correct format for the specific use case.
</para>
<para>
Examples:
</para>
<itemizedlist>
<listitem>
<para>
In this exercise, you create an ARM64 compute machine set.
</para>
</listitem>
<listitem>
<para>
In this scenario, <code>arm64</code> is a valid value for X.
</para>
</listitem>
</itemizedlist>
<para>
Refer also to <xref linkend="a64-bit"/>, <xref linkend="a64-bit-x86"/>, <xref linkend="aarch64"/>, <xref linkend="AMD64"/>, <xref linkend="Intel64"/>, and <xref linkend="x86-64"/>.
</para>

</listitem>

</varlistentry>

<varlistentry id="andor">
<term role="false">and/or</term>
<listitem>
Expand Down
31 changes: 20 additions & 11 deletions en-US/B.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
Use the one-word form only if it is part of the established product terminology, for example "Mobile Backend-as-a-Service", and when it is not being used to describe a generic process.
</para>
<para>
See also <xref linkend="front-end" />
Refer also to <xref linkend="front-end" />
</para>

</listitem>
Expand Down Expand Up @@ -73,7 +73,7 @@
<term>backwards compatible</term>
<listitem>
<para>
Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. See also <xref linkend="forwards-compatible" />.
Do not use. Instead, use "compatible with earlier versions" to refer to something that is compatible with older equipment or previous versions of software. Refer also to <xref linkend="forwards-compatible" />.
</para>

</listitem>
Expand Down Expand Up @@ -106,7 +106,7 @@
<term>basically</term>
<listitem>
<para>
Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." See also <xref linkend="simply" />.
Do not use. For example, removing the word "basically" in the following sentence strengthens it: "This is how it is basically done." Refer also to <xref linkend="simply" />.
</para>

</listitem>
Expand Down Expand Up @@ -152,7 +152,7 @@
<term>big data</term>
<listitem>
<para>
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. See also <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective.
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective.
</para>

</listitem>
Expand Down Expand Up @@ -227,9 +227,18 @@
Correct. Named after George Boole, who first developed the concept.
</para>
<para>
According to the <citetitle>IBM Style Guide</citetitle>, it is acceptable to use "boolean" in API programming information when it refers to a primitive return type.
According to the <citetitle>IBM Style Guide</citetitle>, it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
</para>

<para>
To set Boolean values in YAML files, use <varname>true</varname> or <varname>false</varname>, written lowercase, rather than <varname>yes</varname> or <varname>no</varname>, because YAML&nbsp;1.2 and later versions do not support the latter syntax.
</para>
<para>
For example, the following scenario specifies that a task is run only one time:
</para>
<screen>- name: Pause 30 seconds
ansible.builtin.pause:
seconds: 30
<userinput>run_once: true</userinput></screen>
</listitem>

</varlistentry>
Expand Down Expand Up @@ -296,7 +305,7 @@
<term>Bps, bps</term>
<listitem>
<para>
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 <xref linkend="bandwidth" />.
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. Refer also to <xref linkend="bandwidth" />.
</para>

</listitem>
Expand All @@ -306,7 +315,7 @@
<term>breadcrumb trail</term>
<listitem>
<para>
See the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
Refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
</para>
<note>
<para>
Expand Down Expand Up @@ -379,10 +388,10 @@
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.
</para>
<para>
See <ulink url="http://en.wikipedia.org/wiki/Btrfs" /> for more information on this file system.
Refer to <ulink url="http://en.wikipedia.org/wiki/Btrfs" /> for more information on this file system.
</para>
<para>
See <ulink url="http://en.wikipedia.org/wiki/List_of_file_systems" /> for a list of file-system names and how to present them.
Refer to <ulink url="http://en.wikipedia.org/wiki/List_of_file_systems" /> for a list of file-system names and how to present them.
</para>

</listitem>
Expand Down Expand Up @@ -428,7 +437,7 @@
Ordinarily you would not include the text "button" in a procedure or description. For example, "Click <guibutton>OK</guibutton> to continue" is perfectly acceptable. It might be necessary to distinguish between buttons and links; for example, "Click the <guibutton>Download</guibutton> link".
</para>
<para>
See also <xref linkend="documenting-ui"/>.
Refer also to <xref linkend="documenting-ui"/>.
</para>

</listitem>
Expand Down
Loading

0 comments on commit ae704b2

Please sign in to comment.