O’Reilly Style Guide and Word List

Getting Started

Authors, please consult with your editor or production editor if you have questions specific to your book. If you’d like to use different conventions, please confer with your editor.

This style guide contains information for authors writing in all formats. If you’re an author, please also consult the authoring documentation for the format in which you’re writing (Asciidoc, DocBook, or Word).

Our general style reference is The Chicago Manual of Style, 15th Edition (though some O’Reilly styles differ).

Our dictionary is Merriam-Webster’s Collegiate Dictionary, 11th Edition. Please refer here for any words not on the O’Reilly word list.

Considering Electronic Formats

Because we use a single set of source files to produce the print and electronic versions of our books, it’s important to keep all possible formats in mind during the authoring, editorial, and production phases.

Warning

When anchoring URLs to text nodes, be as descriptive as possible, as the print version of your book renders hyperlinks like this: "text anchor (http://url.example.com/)."

For example, this:

Download the source code (http://www.url.thisismadeup.com) and install the package"

is more useful than this:

"Download the source code from this website (http://www.url.thisismadeup.com) and install the package."

Avoid anchoring URLs to generic words or phrases such as "here," "this website," etc.

Warning

Content should not contain any active links to products on any sales channels other than oreilly.com, including Apple, Google, or Amazon. If these remain, it will cause issues (i.e., Apple and Google will refuse to sell content that links to products on Amazon). For vendors, please flag any links to these online vendors and let the production editor know they exist.

However, saying "XX book is available on Amazon"—sans link—is OK.

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.

Note

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:

code syntax highlighting word
Figure 2-1.

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]).

Typography and Font Conventions

The following shows the basic font conventions used in O’Reilly books. Follow these links for detailed instructions for applying these styles in Asciidoc, DocBook, and Word.

Type of element Final result

Filenames, file extensions (such as .jpeg), directory paths, commands in Unix, Oracle, SQL, and Linux books

Body font italic

URLs, URIs, email addresses

Body font italic

Emphasized words (shouting!)

Body font italic

First instance of a technical term

Body font italic

Code blocks

Constant width

Registry keys

Constant width

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: System.Web.UI, a while loop, the Socket class, and the Obsolete attribute. Exception: commands in Unix, Oracle, SQL, and Linux book, which are regular italics.

Constant width

Replaceable items (placeholder items in syntax); “username” in the following example is a placeholder: login: username

Constant width italic

Commands or text to be typed by the user

Constant width bold

Line annotations

Body font italic (but smaller)

Placeholders in paths, directories, GUI items, URLs, or other text that would be italic anyway

http://www.<yourname>.com

Keyboard accelerators (Ctrl, Shift, etc.), menu titles, menu options, menu buttons

Body text

These font conventions may vary slightly for each project; please consult your editor, the production editor, or the freelance coordinator if you have any questions. Please note: Word authors should refer to the Word author Quick Start Guide (username: guest; leave the password blank); DocBook authors should refer to our DocBook Authoring Guidelines (username: guest; leave the password blank).

It’s very important to follow tagging conventions for terms. The method for applying conventions will vary depending on the format: Word/OpenOffice, DocBook XML, or InDesign. Please consult with your editor or toolsreq@oreilly.com for instructions specific to each environment.

For Word copyediting, please do the following before submitting files for conversion: replace any tabs in code with the appropriate number of spaces (see earlier section, Code); convert any remaining Word comments to tagged Comment paragraphs highlighted in blue; search for any manual linebreaks (^l) and delete or replace with paragraph breaks as appropriate; and accept all changes and make sure filenames adhere to house style.

Note

If you’re an author, and you want to use a font convention that is slightly different for one of the following items, check with your editor first—some things can change; some can’t.

For instance, URLs will not be anything but italic, but you might come up with a different font convention for function names or menu items. If you do use something that differs from the following list, please write it down on your printout of this stylesheet, which should be submitted with your manuscript.

Or, if you have a “new” element, please consult with your editor about which font to use, then write it on your printout and submit it with your manuscript.

O’Reilly Word List

Alphabetical Word List: Default Spellings

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z