Chapter 2. O’Reilly Grammar, Punctuation, etc.

Abbreviations/Acronyms

  • Acronyms should generally be spelled out the first time they appear in a book, as in: “Computer Development Environment (CDE).” After the acronym has been defined, you should generally use the acronym only (not the whole term, unless it makes more sense contextually to use the whole term). Usually, acronyms are defined only once per book. But if you prefer, you can also define them the first time they appear in each chapter.
  • A.M. and P.M. or a.m. and p.m.—be consistent.
  • K = 1,024; k = 1,000. So a 56 kbps modem is equal to 56,000 bps, while 64K of memory is equal to 65,536.
  • In units of measure, do not use a hyphen. For example, it’s 32 MB hard drive, not 32-MB hard drive. (Though when the unit is spelled out, use a hyphen, e.g., 32-megabyte hard drive.)
  • University degrees (e.g., B.A., B.S., M.A., M.S., Ph.D., etc.) can appear with or without periods—just be consistent.
  • United States and United Kingdom should be spelled out on first mention. After that, just use the acronym with no periods (so, US or UK).

Bibliographical Entries

In general, when referencing another book within a book’s text paragraphs, include the author name(s) when there is one or two authors. When there are three or more authors, state the first author name, followed by “et al.”

On first reference to another book, include author and publisher name. For example, "You can find more information in The Elements of Typographic Style by Robert Bringhurst (H&M)," or "For more information, consult Robert Bringhurt’s The Elements of Typographic Style (H&M)." On subsequent references, just use the book title.

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 catalog page.

Make sure that the catalog page is anchored to the book’s title, rather than standing on its own.

Like this: "See Programming F# 3.0"

Not: "See Programming F# 3.0 (http://shop.oreilly.com/product/0636920024033.do)."

For full bibliographical entries (which usually appear in bibliographies or reference lists), see The Chicago Manual of Style, 15th Edition.

Cross References

  • An example of a chapter cross-reference: see Chapter 27.
  • An example of a section cross-reference: see the section “Treatment”. The text “on page x” will be added post-conversion, so the final xref will eventually read “Treatment” on page 37.
  • An example of a section cross-reference in another chapter: see “Acceptable Gifts” on page 58 in Chapter 27.
  • More details on cross-references in Asciidoc are available in our Getting Started with Atlas Guide.
  • These cross-reference styles are also available in DocBook under various <xref> formats. Please refer to the DocBook Authoring Guidelines.

For information about styling URLs and hyperlinks, see “Considering Electronic Formats”.

Dates and Numbers

  • Spell out numbers under 10, unless the same object appears in a sentence with an object 10 or over (five apples; 5 apples and 100 oranges).
  • In most numbers of one thousand or more, commas should be used between groups of three digits, counting from the right (32,904 not 32904). Exceptions: page numbers, addresses, port numbers, etc.
  • Use numerals for versions (version 5 or v5).
  • You may use a numeral if it’s an actual value (e.g., 5% 7″ $6.00).
  • 32-bit integer.
  • 1980s or ’80s.
  • Phone numbers can appear in the format xxx-xxx-xxxx.
  • Use an en dash (–) with negative numbers or for minus signs, rather than a hyphen.
  • Use x for dimensions, not by (e.g., "8.5 x 11").
  • Ordinal numbers: Spell out first through ninth, use numerals for 10th and above. No superscript.

Figures, Tables, and Examples

Every figure, table, and example should be preceded by a specific in-text reference (for example: see Figure 99-1; Example 1-99 shows; Table 1-1 lists, etc.). Figures, tables, and examples should not be introduced with colons or phrases like “in the following figure,” or “as shown in this table.” Lack of specific in-text references may cause incorrect placement of figures.

If you are writing or copyediting in Word, figure, table, and example numbers should be numbered as follows: 1-2 (note hyphen [-], not en dash [–] between numbers). The first number is the chapter number. This will be soft-coded in production if not during the writing process.

If you are writing or copyediting in Asciidoc, please refer to Getting Started with Atlas for examples of Asciidoc cross references.

If you are writing or copyediting in DocBook, please reference each figure, table, and example with an <xref>.

Any word groupings within a figure should have an initial cap on the first word only, with the exception of proper nouns. Generally, we don’t use periods at the end of these word groupings.

  • Figure 1-1. Figure captions are initial-capped on first word only, with the exception of proper nouns. There is no period after figure captions, but if all captions are long and sentence style, periods can be used as long as they are used consistently throughout.
  • Table 1-1. Column heads and table titles are initial-capped on the first word only, with the exception of proper nouns. There is no period after table titles.
  • Example 1-1. Example titles are initial-capped on the first word only, with the exception of proper nouns. There is no period after example titles.

When working in Word, make sure all table cells are tagged with a cell paragraph tag, even if they’re blank. Any bold “headings” that appear below the very first row of a table should be tagged CellSubheading rather than CellHeading.

Also in Word, all figures must be within a FigureHolder paragraph followed directly by a FigureTitle paragraph.

Code

Line Length

Maximum line length for code varies slightly between book formats. Consult the table below to find the maximum line length for your book’s series within Atlas v2. If writing in Word, please keep code within the margins that appear in the Word template and indicate proper linebreaks and indents for all code. Indent using spaces, not tabs.

Series Body (top-level code) Examples Lists Readeraids Sidebars

Animal

81

85

73

57

77

Animal 6x9

64

68

56

40

60

Report 6x9

64

68

56

40

60

Cookbook

81

85

73

57

77

Make 1-column

89

89

81

66

39

Make 2-column

45

46

35

28

40

Make Getting Started

63

67

60

51

60

Nutshell

71

75

67

60

75

Pocket Ref

51

55

50

42

51

Theory in Practice

81

85

77

51

83

Syntax Highlighting

We use a tool called Pygments to colorize code. In most books, code will appear in black and white in the print book and in color in all electronic formats, including the web pdf. If you’re an author, please consult the list of available lexers and apply them to your code as you write. To apply syntax highlighting in Asciidoc, consult the Asciidoc Authoring Guidelines. To apply syntax highlighting in DocBook, consult the DocBook Authoring Guidelines. If you’re writing in Word, for each block of code that you want to have syntax highlighted, indicate the programming language in brackets, styled as a Comment that immediately precedes the block of code. For example, you’d indicate that the following code is in Java like so:

Formatting Code in Word

When copyediting in Word, please do a global search and replace for tabs in code (search for \^t to find them) before submitting files for conversion; tabs will not convert. A general rule of thumb is one tab can be replaced with four spaces (which is the same number that the clean-up macro in the ORA.dot template uses). However, this number can vary, so the most important thing is that copyeditors replace tabs with the numbers of spaces needed to match the indentation and make sure levels of indentation are preserved.

Footnotes

Footnotes in running text are numbered and start over at 1 in each chapter. Footnote markers in running text should always appear after punctuation.

This:

The following query selects the symbol column and all columns from stocks whose names start with the prefix price.1

Not this:

The following query selects the symbol column and all columns from stocks whose names start with the prefix price1.

Table footnotes are lettered (a, b, c, etc.) and appear directly after the table. They should be kept to a minimum.

More details about styling footnotes in Asciidoc are in Getting Started with Atlas.

Headings

  • In most of our design templates, A- and B-level headings are cap and lowercase: cap the first letter of each word, with the exception of articles, conjunctions, and program names or technical words that are always lowercase and coordinating conjunctions (e.g., and, but, for, etc.). Prepositions of four letters or less are not initial-capped, unless they function as part of a verb (e.g., “Set Up Your Operating System”). Hyphenated words in subordinating conjunctions (e.g., as, if, that, because, etc.) are always initial-capped (even if they are four letters or less). Hyphenated words in titles or captions should both be capped if the second word is a main word, but only the first should be capped if the second word isn’t too important (it’s a bit of a judgment call). For example: Big-Endian, Built-in. See The Chicago Manual of Style.
  • C-level headings have initial cap on the first word only, with the exception of proper nouns and the first word that follows a colon (unless that word refers to code and should be lowercase).
  • D-level headings (rare) are run-in with the following paragraph and have an initial cap on the first word only, with the exception of proper nouns and the first word that follows a colon (unless that word refers to code and should be lowercase), with a period at the end of the heading.
  • Sidebar titles are cap and lowercase (like A- and B-level headings, mentioned previously).
  • Headings should not contain inline code font.

Lists

Typically, we use three types of lists: numbered lists, for ordered steps or chronological items; variable lists, for terms and explanations/definitions; and bulleted lists, for series of items. List items are sentence-capped. Following are examples of each type of list.

Numbered list

The following list of step-by-step instructions is an example of a numbered list:

  1. Save Example 2-1 as the file hello.cs.
  2. Open a command window.
  3. From the command line, enter csc /debug hello.cs.
  4. To run the program, enter Hello.

Variable list

The following list of defined terms is an example of a variable list:

Setup project
This creates a setup file that automatically installs your files and resources.
Web setup project
This helps deploy a web-based project.

Bulleted list

The following series of items is an example of a bulleted list:

  • Labels
  • Buttons
  • A text box

“Bulleted” lists nested inside of bulleted lists should have em dashes as bullets.

Frequently, bulleted lists should be converted to variable lists. Any bulleted list whose entries consist of a short term and its definition should be converted. For example, the following bulleted list entries:

  • Spellchecking: process of correcting spelling
  • Pagebreaking—process of breaking pages

should be variable list entries:

Spellchecking
Process of correcting spelling
Pagebreaking
Process of breaking pages

Miscellaneous

  • Don’t use “they” for third-person singular; alternate between “he” and “she.”
  • Do not use a hyphen between an adverb and the word it modifies. So, “incredibly wide table” rather than “incredibly-wide table.”
  • Unless part of a proper noun, close up words with the prefixes “multi,” “pseudo,” “non,” “sub,” and "co" (e.g., “multiusers,” “pseudoattribute,” “nonprogammer,” “subprocess,” "coauthor").
  • 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.”
  • 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.
  • 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 not. (Also applies to generic terms “organization,” “team,” “group,” etc.)
  • When referring to software elements or labels, always capitalize words that are capitalized on screen. Put quotes around any multiword element names that are lowercase on screen and would thus be hard to distinguish from the rest of the text (e.g., Click “Don’t select object until rendered” only if necessary.)
  • For menu items that end with an ellipsis (e.g., "New Folder…"), do not include ellipsis in running text.
  • Use “between” for two items, “among” for three or more. Use “each other” for two, “one another” for three or more.
  • Common foreign terms (such as “en masse”) are roman.
  • Commas and periods go inside quotation marks.
  • Em-dashes: always closed (no space around them).
  • Ellipses: always closed (no space around them).
  • Hyphens: close up words used as nouns (“coverup”); hyphenate words used as adjectives (“the cover-up measures”); verbs are two words (“cover up the flaw with…”).
  • Introduce unnumbered code blocks with colons.

Punctuation

For anything not covered in this list, please consult the Chicago Manual of Style, 15th Edition.

  • Serial comma (this, that, and the other).
  • Curly quotes and apostrophes (“ ” not " ") in regular text.
  • Straight quotes (" " not “ ”) in constant-width text and all code. Some Unix commands use backticks (`), which must be preserved.
  • No period after list items unless one item forms a complete sentence (then use periods for all items within that list, even fragments).
  • Lowercase the first letter after a colon: this is how we do it. (Exception: headings.)
  • Parentheses are always roman, even when the contents are italic. For parentheses within parentheses, use square brackets (here’s the first parenthetical [and here’s the second]).