Chapter 1. General O’Reilly Specifications

Last updated: December 12, 2013

This stylesheet is maintained by Publishing Services and is available online.

Getting Started

Authors, please consult with your editor, editorial assistant, 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 stylesheet 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.

  • Avoid using "above" and "below" when referencing 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.
  • URLs should be anchored to text nodes whenever possible, like they would be on a website.

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.

  • Long URLs should be shortened so that they’re easy for print readers to type manually. If a book contains many long URLs, our Tools group may be able to automate link shortening.