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: styleguide/index.md
+20-18Lines changed: 20 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -140,7 +140,7 @@ title: O'Reilly Style Guide
140
140
141
141
<p>In general, when referring to another book within a book’s text, include the author name(s) for up to two authors. For three or more authors, state the first author name, followed by “et al.” (be sure to include the period).</p>
142
142
143
-
<p>On first reference to another book, include author and publisher name. For example, "You can find more information in <em>The Elements of Typographic Style</em> by Robert Bringhurst (H&M)," or "For more information, consult Robert Bringhurt’s <em>The Elements of Typographic Style</em> (H&M)." On subsequent references, just use the book title.</p>
143
+
<p>On first reference to another book, include author and publisher name. For example, "You can find more information in <em>The Elements of Typographic Style</em> by Robert Bringhurst (H&M)," or "For more information, consult Robert Bringhurst’s <em>The Elements of Typographic Style</em> (H&M)." On subsequent references, just use the book title.</p>
144
144
145
145
<p>When referencing an O’Reilly book within the text, note only "O’Reilly" in parentheses, not "O’Reilly Media, Inc." References to other O’Reilly books should be linked to the book’s <ahref="http://shop.oreilly.com/category/browse-subjects.do">catalog page</a>.</p>
146
146
@@ -149,7 +149,7 @@ title: O'Reilly Style Guide
149
149
</div>
150
150
151
151
<h3>Citations</h3>
152
-
<p>When citing other materials in bibliographies, reference lists, or footnotes, use the “Notes and Bibliography” system from the <ahref="https://www.chicagomanualofstyle.org/tools_citationguide.html"><em>The Chicago Manual of Style</em></a>, 17th edition. <strong>Chicago also has an Author-Date system that some authors prefer, which is perfectly acceptable. If there is no discernable consistency, suggest Chicago's Notes for footnotes and Bibliography for endnotes or back matter.</strong></p>
152
+
<p>When citing other materials in bibliographies, reference lists, or footnotes, use the “Notes and Bibliography” system from the <ahref="https://www.chicagomanualofstyle.org/tools_citationguide.html"><em>The Chicago Manual of Style</em></a>, 17th edition. <strong>Chicago also has an Author-Date system that some authors prefer, which is perfectly acceptable. If there is no discernible consistency, suggest Chicago's Notes for footnotes and Bibliography for endnotes or back matter.</strong></p>
153
153
154
154
<p><strong>Let your production editor know which of Chicago's systems you applied by adding a note to the Word List Doc.</strong></p>
155
155
@@ -289,7 +289,7 @@ title: O'Reilly Style Guide
289
289
<p>Use a numeral if it’s an actual value (e.g., 5% 7″ $6.00).</p>
290
290
</li>
291
291
<li>
292
-
<p>Always use the symbol % with numerals rather than the spelled out word (percent), and make sure it is closed up to number: .05%. Unless the percentage begins a sentence or title/caption, the number should be a numeral with the % symbol.</p>
292
+
<p>Always use the symbol % with numerals rather than the spelled out word (percent), and make sure it is closed up to number: 0.05%. Unless the percentage begins a sentence or title/caption, the number should be a numeral with the % symbol.</p>
293
293
</li>
294
294
<li>
295
295
<p>Ordinal numbers: Spell out first through ninth, use numerals for 10th and above. No superscript.</p>
@@ -563,9 +563,9 @@ title: O'Reilly Style Guide
563
563
564
564
<p>O'Reilly style:</p>
565
565
<ul>
566
-
<li>Here is an item</li>
567
-
<li>Here is another item</li>
568
-
<li>Here is the final item</li>
566
+
<li>Here is an item.</li>
567
+
<li>Here is another item.</li>
568
+
<li>Here is the final item.</li>
569
569
</ul>
570
570
</div>
571
571
@@ -669,7 +669,7 @@ title: O'Reilly Style Guide
669
669
<sectiondata-type="sect2"id="punctuation">
670
670
<h2>Punctuation</h2>
671
671
672
-
<p>For anything not covered in this list, please consult the Chicago Manual of Style, 17th Edition.</p>
672
+
<p>For anything not covered in this list, please consult the _Chicago Manual of Style_, 17th Edition.</p>
673
673
674
674
<ul>
675
675
<li>
@@ -688,7 +688,7 @@ title: O'Reilly Style Guide
688
688
<p>No period after list items unless one item forms a complete sentence (then use periods for all items within that list, even fragments).</p>
689
689
</li>
690
690
<li>
691
-
<p>Em-dashes are always closed (no space around them).</p>
691
+
<p>Emdashes are always closed (no space around them).</p>
692
692
</li>
693
693
<li>
694
694
<p>Ellipses are always closed (no space around them).</p>
@@ -723,7 +723,7 @@ title: O'Reilly Style Guide
723
723
<p>Do not use a hyphen between an adverb and the word it modifies. So, “incredibly wide table” rather than “incredibly-wide table.”</p>
724
724
</li>
725
725
<li>
726
-
<p>Unless part of a proper noun, close up words with the prefixes “micro,” “meta,” “multi,” “pseudo,” “re,” “non,” “sub,” and "co" (e.g., “multiusers,” “pseudoattribute,” “nonprogammer,” “subprocess,” "coauthor"). <strong>Exceptions are noted in the word list (e.g., "re-create," "re-identification")</strong>.</p>
726
+
<p>Close up words with the following prefixes (unless part of a proper noun) “micro,” “meta,” “multi,” “pseudo,” “re,” “non,” “sub,” and "co" (e.g., “multiusers,” “pseudoattribute,” “nonprogrammer,” “subprocess,” "coauthor"). Exceptions are noted in the word list (e.g., "re-create," "re-identification").</p>
727
727
</li>
728
728
<li>
729
729
<p>Avoid using the possessive case for singular nouns ending in “s,” if possible. So, it’s “the Windows Start menu,” not “Windows’s Start menu.”</p>
@@ -732,7 +732,7 @@ title: O'Reilly Style Guide
732
732
<p>Avoid wholesale changes to the author’s voice—for example, changing the first-person plural (the royal “we”) to the first-person singular or the second person. However, do try to maintain a consistency within sentences or paragraphs, where appropriate.</p>
733
733
</li>
734
734
<li>
735
-
<p>We advise using a conversational, user-friendly tone that assumes the reader is intelligent but doesn’t have this particular knowledge yet—like an experienced colleague onboarding a new hire. Firstperson pronouns, contractions, and active verbs are all encouraged.<strong>(Copyeditors: please check with your production editor if you wish to suggest global changes to tone.)</strong></p>
735
+
<p>We advise using a conversational, user-friendly tone that assumes the reader is intelligent but doesn’t have this particular knowledge yet—like an experienced colleague onboarding a new hire. First-person pronouns, contractions, and active verbs are all encouraged.<strong>(Copyeditors: please check with your production editor if you wish to suggest global changes to tone.)</strong></p>
736
736
</li>
737
737
<li>
738
738
<p>Companies are always singular. So, for example, “Apple emphasizes the value of aesthetics in its product line. Consequently, it dominates the digital-music market” is correct. “Apple emphasize the value of aesthetics in their product line. They dominate the digital-music market” is <em>not</em>. (Also applies to generic terms “organization,” “team,” “group,” etc.)</p>
@@ -756,7 +756,7 @@ title: O'Reilly Style Guide
756
756
<p>Do not stack admonitions, sidebars, or headings.</p>
757
757
</li>
758
758
<li>
759
-
<p>Avoid obscenities and slurs, and obscure if included (grawlix, a twoem dash, etc.)</p>
759
+
<p>Avoid obscenities and slurs, and obscure if included (grawlix, a two-em dash, etc.)</p>
760
760
</li>
761
761
</ul>
762
762
@@ -816,7 +816,7 @@ title: O'Reilly Style Guide
816
816
<td><p><code>Constant width</code></p></td>
817
817
</tr>
818
818
<tr>
819
-
<td><p>Language and script elements: class names, types, namespaces, attributes, methods, variables, keywords, functions, modules, commands, properties, parameters, values, objects, events, XML and HTML tags, and similar elements. Some examples include: <code>System.Web.UI</code>, a <code>while</code> loop, the <code>Socket</code> class, and the <code>Obsolete</code> attribute. <strong>Exception:</strong> commands in Unix, Oracle, and Linux book, which are regular italics.</p></td>
819
+
<td><p>Language and script elements: class names, types, namespaces, attributes, methods, variables, keywords, functions, modules, commands, properties, parameters, values, objects, events, XML and HTML tags, and similar elements. Some examples include: <code>System.Web.UI</code>, a <code>while</code> loop, the <code>Socket</code> class, and the <code>Obsolete</code> attribute. <strong>Exception:</strong> commands in Unix, Oracle, and Linux books, which are regular italics.</p></td>
820
820
<td><p><code>Constant width</code></p></td>
821
821
</tr>
822
822
<tr>
@@ -862,7 +862,7 @@ title: O'Reilly Style Guide
862
862
863
863
<sectiondata-type="sect1"id="cover-style">
864
864
<h1>O'Reilly Cover Style</h1>
865
-
<p>Use Chicago Maual of Style, 17th Edition for anything not mentioned here.</p>
865
+
<p>Use _Chicago Manual of Style_, 17th Edition for anything not mentioned here.</p>
866
866
867
867
<p>Bulleted lists on the back cover should begin with a capitalized word and end with <em>no</em> punctuation. Even if the list item is a complete sentence, it will not take a period.</p>
868
868
@@ -1052,7 +1052,9 @@ title: O'Reilly Style Guide
1052
1052
1053
1053
<h2id="worldlist-E">E</h2>
1054
1054
<ul>
1055
-
<li>ebook* ebusiness* ecommerce </li>
1055
+
<li>ebook</li>
1056
+
<li>ebusiness</li>
1057
+
<li>ecommerce</li>
1056
1058
<li>eBay</li>
1057
1059
<li>Emacs</li>
1058
1060
<li>email</li>
@@ -1265,7 +1267,7 @@ title: O'Reilly Style Guide
1265
1267
<li>MKS Toolkit</li>
1266
1268
<li>model-in-the-loop</li>
1267
1269
<li>MS-DOS</li>
1268
-
<li>multiline (Unless before a proper noun, always close up the following prefixes: “non,” “sub,” “multi,” and “pseudo.”)</li>
1270
+
<li>multiline </li>
1269
1271
<li>Multi-Touch (when referring to Apple's trademark)</li>
1270
1272
<li>My Services</li>
1271
1273
<li>MySpace</li>
@@ -1338,7 +1340,7 @@ title: O'Reilly Style Guide
1338
1340
<li>packet switch networks</li>
1339
1341
<li>Paint Shop Pro</li>
1340
1342
<li>pagefile</li>
1341
-
<li>page rank (but Google PageRank™)</li>
1343
+
<li>page rank (but Google PageRank)</li>
1342
1344
<li>parentheses (p)</li>
1343
1345
<li>parenthesis (s)</li>
1344
1346
<li>Pascal</li>
@@ -1413,7 +1415,7 @@ title: O'Reilly Style Guide
1413
1415
<li>reference page or manpage</li>
1414
1416
<li>re-identification (hyphenate)</li>
1415
1417
<li>remote-access server</li>
1416
-
<li>Rendezvous (<em>Mac OS X Zeroconf networking</em>)</li>
1418
+
<li>Rendezvous (<em>Mac OS X zeroconf networking</em>)</li>
1417
1419
<li>Return (key)</li>
1418
1420
<li>RFC 822</li>
1419
1421
<li>rich text (n)</li>
@@ -1485,7 +1487,7 @@ title: O'Reilly Style Guide
1485
1487
<li>stateless</li>
1486
1488
<li>status bar</li>
1487
1489
<li>stylesheet</li>
1488
-
<li>subprocess (Unless before a proper noun, always close up the following prefixes: “non,” “sub,” “multi,” and “pseudo.”)</li>
0 commit comments