You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: en-US/Cross_references.xml
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -40,15 +40,15 @@
40
40
41
41
</section>
42
42
<sectionid="repeatability-test">
43
-
<title>The Repeatability Test</title>
43
+
<title>Repetition</title>
44
44
<para>
45
-
Must the information be repeated?
45
+
Repetition is a useful tool for reinforcing new knowledge and skills, emphasizing important ideas, and providing readers with important information at their point of need.
46
46
</para>
47
47
<para>
48
-
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. 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.
48
+
Repeating necessary information also saves the reader time and effort. In some circumstances, such as when using online help, the reader is trying to answer an immediate question or to solve a problem. In a safety situation, it is important for the reader to find critical information quickly.
49
49
</para>
50
50
<para>
51
-
Cross-referencing is a good servant but a poor master. Content still rules!
51
+
If the information is vital, and must appear in multiple places, then it must be repeated. 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.
<title>Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly</title>
926
+
<title>Abbreviations, Acronyms, Initialisms, and Special Characters</title>
927
927
<para>
928
-
This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation.
928
+
This section defines abbreviations, acronyms, initialisms, and special characters.
929
929
</para>
930
-
<formalpara>
930
+
<formalparaid="abbreviations">
931
931
<title>Abbreviations</title>
932
932
<para>
933
933
An abbreviation is a shortened form of a word or phrase. For example, <abbrev>Pty.</abbrev> and <abbrev>Inc.</abbrev> are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation.
They are similar to abbreviations and initialisms but they are pronounced as a word.
942
-
An acronym is a word that is 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.
943
-
<acronym>COBOL</acronym> is the acronym for Common Business-oriented Language, and <acronym>POP</acronym> is the acronym for Post Office Protocol.
940
+
An acronym is a word that is 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.
941
+
<acronym>COBOL</acronym> is the acronym for Common Business-oriented Language, and <acronym>POP</acronym> is the acronym for Post Office Protocol.
942
+
</para>
943
+
944
+
</formalpara>
945
+
<formalparaid="initialisms">
946
+
<title>Initialisms</title>
947
+
<para>
948
+
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.
944
949
</para>
945
950
</formalpara>
946
951
952
+
<formalparaid="special-chars">
953
+
<title>Special Characters</title>
954
+
<para>
955
+
For the purposes of this guide, special characters refer to those characters that are listed in <xreflinkend="punc-names" />.
956
+
This section addresses how to use special characters as part of a file or directory name, such as "the <filename>.bashrc</filename> file" and "the <filename>_build/</filename> directory".
957
+
</para>
958
+
</formalpara>
959
+
960
+
<sectionid="abbreviations-correctly">
961
+
<title>Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly</title>
947
962
<para>
948
-
Consider pronunciation when using articles. For example, use "an <abbrev>RTS</abbrev> (real-time strategy)", because <abbrev>RTS</abbrev> is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a <acronym>RAM</acronym> upgrade", because <acronym>RAM</acronym> is an acronym and you pronounce it as a word (răm).
963
+
This section describes how to use abbreviations, acronyms, initialisms, and special characters correctly in Red Hat documentation.
949
964
</para>
950
965
966
+
<formalparaid="first-mentions">
967
+
<title>First Mentions</title>
951
968
<para>
952
969
Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...".
953
-
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)".
954
-
Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.
970
+
Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.
955
971
</para>
972
+
</formalpara>
956
973
974
+
<formalparaid="cap">
975
+
<title>Capitalization</title>
957
976
<para>
958
-
To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes.
977
+
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)".
978
+
Not all acronyms are capitalized (for example, "spool"); see the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure.
959
979
</para>
980
+
</formalpara>
960
981
982
+
<formalparaid="articles">
983
+
<title>Articles</title>
961
984
<para>
962
-
Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure.
985
+
When deciding which articles to use, consider pronunciation.
986
+
For example, use "an <abbrev>RTS</abbrev> (real-time strategy)", because <abbrev>RTS</abbrev> is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a <acronym>RAM</acronym> upgrade", because <acronym>RAM</acronym> is an acronym and you pronounce it as a word (răm).
963
987
</para>
964
-
965
-
<formalparaid="initialisms">
966
-
<title>Initialisms</title>
967
-
<para>
968
-
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, <abbrev>FTP</abbrev> is an initialism for <systemitemclass="protocol">File Transfer Protocol.</systemitem>
969
-
</para>
970
-
971
988
</formalpara>
989
+
990
+
<formalparaid="plurals">
991
+
<title>Plurals</title>
972
992
<para>
973
-
Consider pronunciation when using articles. See <xreflinkend="acronyms" /> for more information.
993
+
To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes.
974
994
</para>
995
+
</formalpara>
996
+
975
997
<formalparaid="special-characters">
976
998
<title>Special Characters</title>
977
-
<para>
978
-
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
979
-
</para>
999
+
<para>
1000
+
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
0 commit comments