This style guide is for authors, copyeditors, and proofreaders working on books of all formats. As writers and editors, we know that language changes over time, so please check back regularly for updates to terms and conventions. Recent additions will be set in bold for a few months.
Authors, please also consult the authoring documentation for the format in which you’re writing (Asciidoc, HTMLbook, DocBook, or Word). For sponsored projects, please see our statement of editorial independence.
For term conventions, check our guide and word list first, then The Chicago Manual of Style, 17th edition, then Merriam-Webster’s Collegiate Dictionary. Use your book-specific word list (provided by production) to document style choices that differ or are not covered here (e.g., A.M. or a.m., data center or datacenter).
To avoid unintentional bias, when writing about groups of people, check the group’s advocacy organization for guidance on appropriate language. The Conscious Style Guide is one good resource, aggregating links to relevant organizations. The University of Washington has another that is tech-specific. The Disability Language Style Guide is a thorough guide to writing about disabilities with sensitivity. Always follow a person’s preference and note exceptions, if necessary (e.g., quoting research that is decades old).
For questions specific to your book or assignment, please consult with your editor or production editor.
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 formats in mind while writing and editing:
Avoid using "above" and "below" to reference figures, tables, examples, unnumbered code blocks, equations, etc. (e.g., "In the example below…"). Using live cross references (e.g., "see Figure 2-1") is best, but when that’s not possible, use "preceding" or "following," as the physical placement of elements could be different in reflowable formats.
Anchor URLs to text nodes whenever possible, like you would on a website. See Links for more information.
Be as descriptive as possible because 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.
Long URLs will be shortened so that they’re easy for print readers to type manually.
Do not link to products on any sales channels other than oreilly.com, including Apple, Google, or Amazon. Apple and Google will refuse to sell content that links to products on Amazon. Vendors, please flag any links to these sales channels and let the production editor know they exist.
Saying "XX book is available on Amazon"—sans link—is OK.
For any words or conventions not covered here, refer to The Chicago Manual of Style, 17th edition and Merriam-Webster.
Generic pronouns should be they/their when needed, not he, she, or he/she.
Acronyms should generally be spelled out the first time they appear in a book, as in: "collaborative development environment (CDE)." See the Word List for common exceptions. 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 the author prefers, we can also define certain terms the first time they appear in each chapter.
Acronyms should be capitalized when expanded only if the term is a proper noun (and spelled that way by the company). For example, key performance indicator (KPI), but Amazon Web Services (AWS).
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 64 K 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).
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).
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 Bringhurst’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 THIS: "See Programming F# 3.0 (http://shop.oreilly.com/product/0636920024033.do)."
When citing other materials in bibliographies, reference lists, or footnotes, use the “Notes and Bibliography” system from the The Chicago Manual of Style, 17th edition. 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.
Let your production editor know which of Chicago's systems you applied by adding a note to the Word List Doc.
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.
Footnotes should contain more than just a URL, whether a full citation for the text the URL points to or context for where the link leads.
This:
Not this:
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 Writing in AsciiDoc.
Here are a few examples of cross references:
Chapter: See Chapter 27.
Section: See “Treatment” on page xx. (The text “on page xx” will be dynamic in Atlas, updating as page numbers change.)
Figure: ...as shown in Figure 1-1.
Sidebars: See “A Note for Mac Users” on page xx. (As with section xrefs, the page number will update automatically in Atlas.)
More details on cross-references in Asciidoc are available in our Writing in AsciiDoc 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.
Capitalization in headings:
In most of our design templates, A- and B-level headings are initial-capped (or title case): cap the first letter of each word, with the exception of articles, conjunctions, and program names or technical words that are always lowercase.
Prepositions of four letters or fewer 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 (also called sentence-case), 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 initial-capped, or title case (like A- and B-level headings, mentioned previously).
Admonition (note/tip/warning) titles are initial-capped, or title case (like A- and B-level headings, mentioned previously). Admonition titles are optional.
Headings should not contain inline code font or style formatting such as bold, italic, or code font.
Headings should always immediately precede body text. Do not follow a heading with an admonition or another heading without some form of introductory or descriptive text.
What to spell out and when:
Spell out numbers from zero to nine and certain round multiples of those numbers unless the same object appears in a sentence with an object 10 or over (five apples; five apples and one hundred oranges; 5 apples and 110 oranges).
Whole numbers one through nine followed by hundred, thousand, million, billion, and so forth are usually spelled out (except in the sciences or with monetary amounts).
Centuries follow the same zero through nine rule, so those will usually be numerals (i.e., 20th century, 21st century).
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).
Use a numeral if it’s an actual value (e.g., 5% 7″ $6.00).
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.
Ordinal numbers: Spell out first through ninth, use numerals for 10th and above. No superscript.
Formatting:
Use spaces around inline operators (1 + 1 = 2. NOT 1+1=2).
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 multiplication symbol “×” for dimensions, not "by" (e.g., "8.5 × 11").
Every formally numbered 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.). Formal figures, tables, and examples should not be introduced with colons or phrases like “in the following figure,” or “as shown in this table.” Though we do support unnumbered informal figures/tables/examples, these should be used only for elements whose contents are not discussed at length or referred back to. Lack of specific in-text references may cause incorrect placement of figures. See Cross References above for more detail on including cross references.
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 Writing in AsciiDoc 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 sentence-cased, with the exception of proper nouns. Code styling is allowed within the figure name or caption. There is no period after figure captions. Exceptions should be discussed with your production editor (e.g., if several long captions require punctuation, we can collaborate on efficient ways to achieve consistency).
Table 1-1. Column heads and table titles are sentence-cased, with the exception of proper nouns. Code styling is allowed within the table name or caption. There is no period after table titles.
Example 1-1. Example titles are sentence-cased, with the exception of proper nouns. Code styling is allowed within the example name or caption. 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.
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 |
Trade 6x9 |
76 |
72 |
65 |
80 |
69 |
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 |
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 Writing in AsciiDoc. To apply syntax highlighting in DocBook, consult the DocBook Authoring Guidelines. To apply syntax highlighting in Word, consult the O’Reilly Media Word Template Quickstart Guide.
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.
Display text generated by artificial intelligence in blockquotes. To separate a prompt from a response, showing who “said” what, use italics:
Prompt: Can you write some text?
(insert appropriate technology name here): Sure can!
We want to accurately replicate the back-and-forth between human and AI. Human prompts can be edited very lightly (e.g., punctuation, capitalization), but AI-generated text should be kept verbatim. If AI output is edited for some reason, be sure to still acknowledge the AI's contribution. It must be clear what is AI-generated.
In books produced in Atlas, URLs should be anchored to descriptive text where possible. In ebook versions, the markup will render like this:
Navigate to the O'Reilly home page for more information.
In the print book, the URL will unfurl in a parenthetical after the linked text:
Navigate to the O'Reilly home page (https://oreilly.com) for more information.
Because of this difference in appearance of links in ebooks and print books, long and complex URLs are shortened during production. In the past, we used bit.ly to shorten these URLs, but as of May 2019, all shortened links will be hosted and tracked internally, using the oreil.ly short link.
We do not anchor URLs to text in books produced in InDesign.
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. List items should be treated as separate items and should not be strung together with punctuation or conjunctions. Unless one item in a list forms a complete sentence, the list's items do not take periods. If one does form a complete sentence, use periods for all items within that list, even fragments.
NOT O'Reilly style:
O'Reilly style:
Following are examples of each type of list.
The following list of step-by-step instructions is an example of a numbered list:
Save Example 2-1 as the file hello.cs.
Open a command window.
From the command line, enter csc /debug hello.cs.
To run the program, enter Hello.
The following list of defined terms is an example of a variable list:
This creates a setup file that automatically installs your files and resources.
This helps deploy a web-based project.
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:
Process of correcting spelling
Process of breaking pages
For anything not covered in this list, please consult the Chicago Manual of Style, 17th Edition.
Serial comma (this, that, and the other).
Commas and periods go inside quotation marks.
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).
Em dashes are always closed (no space around them).
Ellipses are always closed (no space around them).
For menu items that end with an ellipsis (e.g., "New Folder…"), do not include ellipsis in running text.
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]).
Do not use a hyphen between an adverb and the word it modifies. So, “incredibly wide table” rather than “incredibly-wide table.”
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").
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.
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. Copyeditors: please check with your production editor if you wish to suggest global changes to tone.)
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 or mixed case 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.)
Use “between” for two items, “among” for three or more. Use “each other” for two, “one another” for three or more.
Use the American spellings of words when they differ.
Common foreign terms (such as “en masse”) are roman.
Introduce unnumbered code blocks with colons.
Do not stack admonitions, sidebars, or headings.
Avoid obscenities and slurs, and obscure if included (grawlix, a two-em dash, etc.)
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.
If 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 example, 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 have a “new” element, please consult with your editor about which font to use.
| Type of element | Final result |
|---|---|
Filenames, file extensions (such as .jpeg), directory paths, libraries, and commands in Unix, Oracle, and Linux books. Exception: Python packages (e.g., NumPy, scikit-learn, TensorFlow, etc.) are roman and cased according to convention. |
Body font italic |
URLs, URIs, email addresses, domain names |
Body font italic |
Emphasized words (shouting!). Please use italics rather than bold for emphasis. |
Body font italic |
First instance of a technical term |
Body font italic |
Code blocks |
|
Registry keys |
|
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: |
|
SQL commands ( |
|
Replaceable items (placeholder items in syntax); “username” in the following example is a placeholder:
|
|
Commands or text to be typed by the user |
|
Line annotations |
Body font italic (but smaller) |
Placeholders in paths, directories, URLs, or other text that would be italic anyway |
|
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 Template Quickstart Guide; 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.
Use Chicago Manual of Style, 17th Edition for anything not mentioned here.
Bulleted lists on the back cover should begin with a capitalized word and end with no punctuation. Even if the list item is a complete sentence, it will not take a period.
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 |nginx (server)