Last updated: January 14, 2010

This stylesheet is maintained (and frequently updated) by Publishing Services and is available online at:

http://www.oreilly.com/oreilly/author/stylesheet.html
ftp://ftp.oreilly.com/pub/stylesheet/styles.pdf

General O’Reilly Specifications

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 all authors, including those writing in Word, DocBook XML, or other format. Documentation for styling your manuscript with the ORA.dot Word template can be found at https://prod.oreilly.com/external/tools/templates/word/ORA/docs/ (username: guest; leave the password blank). DocBook documentation and examples are available at https://prod.oreilly.com/external/tools/docbook/docs/authoring/ (username: guest; leave the password blank).

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.

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.

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 published name; on subsequent references just use 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 include the book’s catalog page URL, which can be found at http://www.oreilly.com/store/complete.html.

For other information regarding bibliographical entries, see The Chicago Manual of Style, 15th Edition.

Cross References

  • Use chapter number only for references in a chapter.

  • 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 “see the section “Treatment” on page 37.”)

  • An example of a section cross-reference in another chapter: see “Acceptable Gifts” in Chapter 27.

  • These cross-reference styles are also available in DocBook under various <xref> formats. Please refer to https://prod.oreilly.com/external/tools/docbook/docs/authoring/ (username: guest; leave the password blank).

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.

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 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

Maximum line length for code varies slightly between book formats. For standard non-Nutshell books, the maximum line length for code is 82 characters, with 86 characters available in captioned examples. In Nutshell books, standard line length for code is 73 characters, with 77 characters available in captioned examples. Pocket references have even smaller code line length—check with your editor for this information. Please keep code within the code margins that appear in the Word template and indicate proper linebreaks and indents for all code. Indent using spaces, not tabs.

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

Try to minimize the use of footnotes, as they can cause difficulties in page layout. Whenever possible and if the author is amenable, delete footnotes, work them back into the text as parenthetical comments, or tag them as Notes.

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

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.

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 initial-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,” and “sub” (e.g., “multiusers,” “pseudoattribute,” “nonprogammer,” and “subprocess”).

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

  • Use “between” for two items, “among” for three or more. Use “each other” for two, “one another” for three or more.

Punctuation

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

  • The Chicago Manual style (15th Edition) is our default.

Typography and Font Conventions

The following table outlines the basic font conventions used in O’Reilly books. It also lists the specific Word style tags and DocBook 4.4 elements you should use for these fonts.

Type of element in document

Result in final document

Style name(s) in ORA.dot (Word template)

Element name(s) in DocBook 4.4

Filenames, file extensions (such as . jpeg ), directory paths

Commands in Unix, Oracle, SQL, and Linux books.

Body font italic

Filename

<filename>

URLs, URIs, email addresses

Body font italic

Hyperlink, url

<ulink>

Emphasized words (shouting!)

Body font italic

Emphasis, fi

<emphasis>

First instance of a technical term

Body font italic

Technical Italic, fix

<firstterm>

Code blocks

Constant width

Code, x

<programlisting>

Registry keys

Constant width

Literal, fc

<literal>

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

Literal, fc

<literal>

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

login: username

Constant width italic

Replaceable, fci

<replaceable>

Commands or text to be typed by the user

Constant width bold

User Input, fcb

<userinput>

Line annotations

Body font italic (but smaller)

XRefColor, hc

<lineannotation>

Bulleted lists

ListBullet, lb

<itemizedlist>

Numbered lists

ListNumber, ln

<orderedlist>

Variable lists

ListVariableTerm, lvt; ListVariable, lv

<variablelist>
  <varlistentry>
    <term>
    <listitem>

Notes

Note, n

<note>

Warnings

NoteWarning, nw

<warning>

Tables (titles, cell headings, cells, and other elements)

TableTitle, tt; CellHeading, th; CellBody, tb; CellSubhead, ts

<table>
  <title>
  <tgroup>
    <colspec>
    <thead>
      <row>
    <tbody>
      <row>
        <entry>

Figures (and figure titles)

FigureHolder, gh; FigureTitle, gt

<figure>
<title>
<mediaobject>
  <imageobject>
    <imagedata>

Examples (and example titles)

ExampleTitle, xt; Code, x

<example>
  <title>
  <programlisting>

Cross-references (in-text references to figures, tables, examples, other sections, other pages)

No style; use a hyphen (-), not an en dash (–), within figure, table, and example cross-references

<xref>

For instance, if you are referencing a <figure>, check its id attribute. If there is no @id, then add a unique @id attribute[a] to the figure, like so:

<figure id="foo">

Now that you have the @id, you can insert an <xref> with an @linkend attribute that references the <figure>, like so:

<xref linkend="foo” />

The same rules apply to other <xref>s.

Placeholders in paths, directories, GUI items, URLs, or other text that would be italic anyway: http://www.<yourname>.com

http://www.<yourname>.com

No style; enclose in angle brackets

<emphasis>

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

Body text

No style or font convention; leave as regular text

Regular text

Superscripted items (not footnote markers: insert footnotes for these)

Superscript2

Superscript

<superscript>

Subscripted items

Subscript3

Subscript

<subscript>

[a] Note that @id attributes cannot have spaces or start with a number. Additionally, you cannot use the word “inherit” as an @id because it won’t render properly in the PDF.

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 https://prod.oreilly.com/external/tools/templates/word/ORA/docs/ (username: guest; leave the password blank); DocBook authors should refer to the documentation at https://prod.oreilly.com/external/tools/docbook/docs/authoring/ (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 the Tools Department () 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, the section called “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

acknowledgments appendixes
ActionScript applet (or Java applet)
ActiveX control AppleScript
Addison-Wesley AppleScript Studio (ASS)
ADO.NET ARPAnet
a.k.a. or aka (be consistent) ASCII
a.m. or A.M. ASP.NET
Alt key at sign
Alt-N autogenerate
anonymous FTP awk

B

backend bitmap
background processes bit mask
backquote Bitnet
backslash bit plane
Backspace key bitwise operators
backtick BlackBerry
backup (n) Boolean (unless referring
back up (v) to a datatype in code,
backward in which case s/b lowercase)
backward compatible Bourne-again shell (bash)
bandwidth Bourne shell
BeOS braces or curly braces
Berkeley Software Distribution (BSD) brackets or square brackets
Berkeley Unix browsable
  (older books may have UNIX) built-in (a, n)
BHOs button bar
bioinformatics  

C

Caps Lock key Common Object Request
caret or circumflex Broker Architecture (CORBA)
CAT-5 compact disc
CD-ROM compile time (n)
C language (n) compile-time (a)
C-language (a) CompuServe
checkbox Control key (Mac)
checkmark copyleft
classpath copyright
client/server coworker
client side (n) CPU
client-side (a) criterion (s), criteria (p)
co-class cross-reference
coauthor C shell
code set <CR><LF>
colorcell Ctrl key (Windows)
colormap Ctrl-Alt-Delete
Command key (Macintosh) Ctrl-N
command line (n) curly braces or braces
command-line (a)  

D

database DNS
data block DocBook
Data Encryption Standard (DES) Document Object Model (DOM)
datafile Domain Name System
datatype or data type (be consistent) dot
data is dot-com
DB-9 double-click
Debian GNU/Linux double-precision (a)
dial-up (a) double quotes
dial up (v) down arrow
disk downlevel (a)
disk-imaging software download
Delete key drag-and-drop (n)
design time (n) drag and drop (v)
design-time (a) drop-down (a)

E

ebooks end user
ebusiness Enter key
ecommerce equals sign
eBay ereader
Emacs Escape key (or Esc key)
email et al.
empty-element tag Ethernet
end-of-file (EOF) exclamation mark
end-tag Exim

F

failback Fortran 90
failover forward (adv)
fax frame type
file manager FreeBSD
filename Free Documentation License (FDL)
file server Free Software Foundation (FSF)
filesystem frontend
file type ftp (Unix command)
FireWire FTP (protocol)
foreground FTP site
FORTRAN  

G

gateway GNU Emacs
Gb (gigabit) GNU Public License (GPL)
GB (gigabyte) GNUstep
GBps (gigabytes per second) Google PageRank
GHz grayscale
gid greater-than sign or >
GIMP GUI, GUIs
GNOME  

H

handcode high-level (adj)
hardcoded home page
hardcore hostname
hardcode (v) hotspot
hardcopy HTML
hard link HTTP
hash sign or sharp sign hypertext

I

IDs intranet
IDE Intrinsics
inline I/O
inode IP (Internet Protocol)
interclient IPsec
Internet ISO
internetwork ISP

J

Jabber JAR archive
Jabber client JAR file
Jabber server JavaScript
Jabber applet JPEG

K

K Desktop Environment (KDE) keycode
Kb (kilobit) keymaps
KB (kilobyte) keypad
  (denotes file size or disk space) keystroke
Kbps (kilobits per second) keysym
Kerberos keywords
keepalive (n or a) kHz (kilohertz)
keyclick Korn shell

L

local area network or LAN listbox
left angle bracket or < logfile
lefthand (a) login, logout, or logon (n or a)
leftmost log in, log out, or log on (v)
less-than sign or < lower- and uppercase
leveled (not levelled) lowercase
line-feed (a) lower-level (a)
line feed (n) lower-right (a)
Linux Linux Professional Institute (LPI)
LinuxPPC  

M

Macintosh Meta-N
Mac OS MHz (megahertz)
Mac OS 9 ( note the use of spaces ) mice or mouses (be consistent)
Mac OS X ( note the use of spaces ) Microsoft Windows
mail-handling (adjective) Microsoft Windows Me
manpage Microsoft Windows NT
markup Microsoft Windows XP
Mb (megabit) Microsoft Windows 2000
MB (megabyte) MIDlet
MBps (megabytes per second) MKS Toolkit
McGraw-Hill MS-DOS
menu bar multiline[1]
Multi-Touch (when referring to Apple's trademark) metacharacter
Meta key My Services
MySpace

N

nameserver NetInfo
name service newline
namespace newsgroups
the Net NeXTSTEP
.NET nonlocal[1]
NetBIOS Novell NetWare
NetBSD the New York Times

O

Objective-C OpenStep
object linking and embedding (OLE) OpenWindows
object-oriented programming (OOP) Option key (Macintosh)
object request broker (ORB) Oracle7
OK Oracle8
offline Oracle 8.0
offload Oracle 8 i (italic “i”)
onboard Oracle 9 i (italic “i”)
ongoing Oracle Parallel Query Option
online O’Reilly Media, Inc.
open source (n or a) OS/2
open source software (OSS) OSA
OpenBSD OSF/Motif
OpenMotif OS X

P

packet switch networks Point-to-Point Protocol (PPP)
Paint Shop Pro pop up (v, n)
pagefile pop-up (a)
page rank (but Google PageRank™) POP-3
parentheses (p) Portable Document Format (PDF)
parenthesis (s) Portable Network Graphics (PNG)
Pascal Portable Operating
password   System Interface (POSIX)
pathname POSIX-compliant
pattern-matching (a) Post Office Protocol (POP)
peer-to-peer (or P2P) postprocess
performant (Oracle) PostScript
period Prentice Hall
Perl process ID
Perl DBI progress bar
plain text (n) pseudoattribute[1]
plain-text (a) pseudo-tty
Plug and Play (PnP) public key (n)
plug in (v) public-key (a)
plug-in (a, n) pull-down (a)
p.m. or P.M.  

Q

qmail QuickTime
Qt quotation marks
QuarkXPress   (spell out first time it;
Quartz   can be “quotes” thereafter)
Quartz Extreme  

R

random-access (a) RFC 822
RCS rich text (n)
read-only (a) rich-text (a)
read/write right angle bracket or
real time (n) greater-than sign (>)
real-time (a) right-click
Red Hat Linux righthand (a)
Red Hat Package Manager (RPM) rmail
redirection roll back (v)
reference page or manpage rollback (n)
remote-access server rootkit
rename Rubout key
Rendezvous rulebase
  ( Mac OS X Zeroconf networking ) ruleset
Return (key) runtime (n, a)

S

Samba site map
saveset slideshow
screen dump Smalltalk
screenful SMP (a, n)
screensaver SOAP
screenshot Social Security number (SSN)
scroll bar source code
securelevel (in Linux) space bar
Secure Shell (SSH) spam (not SPAM)
Secure Sockets Layer (SSL) spellcheck
sed scripts spellchecker
semicolon split screen
server-dependent square brackets or brackets
server side (n) standalone
server-side (a) standard input (stdin)
servlet standard output (stdout)
set up (v) start tag
setup (n) startup file
SGML status bar
sharp sign or hash sign stylesheet
shell (lowercase even in subprocess[2]
  shell name: Bourne shell) SUSE Linux
shell scripts swapfile
Shift key swapspace
shortcut sync
Simple API for XML (SAX) system administrator
single-precision (a) system-wide
single quote  

T

10-baseT thread pooling (n)
T1 time-sharing processes
t-shirt timestamp
Tab key time zone
TAR file title bar
TCP/IP Token Ring
Telnet (the protocol) toolbar
telnet (v) toolkit
terabyte tool tip
TEX top-level (a)
texinfo toward
text box trade-off
text-input mode troubleshoot

U

UK UPSs
Ultrix up-to-date
Universal Serial Bus (USB) URLs
Unix (UNIX in many US (for United States)
  books, esp. older ones) Usenet
up arrow user ID (n)
upper- and lowercase user-ID (a)
uppercase username
upper-left corner  

V

v2 or version 2 Visual Basic .NET
VAX/VMS Visual Basic 6 or VB 6
VB.NET Visual C++ .NET
versus (avoid vs.) Visual Studio .NET
vice versa VS.NET
VoiceXML Volume One

W

the Wall Street Journal Windows 95
the Web (n) Windows 98
web (a) Windows 2000
web client Windows NT
webmaster Windows Vista
web page Windows XP
web server Wizard (proper noun)
web services (unless wizard (a, n)
  preceded by a proper noun, workaround
  as in Microsoft Web Services) workbench
website workgroup
white pages workstation
whitespace World Wide Web (WWW)
wide area network or WAN wraparound
WiFi writable
wiki write-only (a)
wildcard WYSIWYG

X Y Z

(x,y) (no space) XML Query Language (XQuery)
x-axis XML-RPC
Xbox XPath
X client XPointer
x coordinate XSL
X protocol XSLT
X server Yahoo!
X Toolkit y-axis
XView y coordinate
X Window series Zeroconf
X Window System   (short for “Zero Configuration”)
x86 zeros
xFree86 zip code
XHTML zip (v)
XLink ZIP file
XML  


[1] Unless before a proper noun, always close up the following prefixes: “non,” “sub,” “multi,” and “pseudo.”

[2] Unless before a proper noun, always close up the following prefixes: “non,” “sub,” “multi,” and “pseudo.”