On the editor’s list here at O’Reilly, we often get into discussions about
technology trends and the latest gadget. But we also talk about the craft
of editing and dealing with the English language, which can sometimes be a
real joy when you’re talking about tech writing. (I’ll get back to the “joy”
in a second.)
No book has sparked more activity on the O’Reilly editor’s list than
Eats, Shoots & Leaves: The Zero Tolerance Approach to Punctuation, by Lynne Truss. In her book, Lynne talks about her frustrations with misplaced punctuation, and encourages us fellow “sticklers” to be on the lookout for improper usage and to correct it whenever possible. She gives the best overview of how to properly use various punctuation marks that I’ve ever seen, and Lynne does so with such grace and humour (sorry, I had to, she’s British) that you can’t help but love the woman.
I’ve read all the “classic” books that editors and writers are told to read
to learn about “proper” style. Books like Strunk & White’s The Elements of Style, the AP Stylebook, and the book that most publishing houses refer to as their “Bible” (including O’Reilly), The Chicago Manual of Style. (Yes, I have read the entire CMS. Twice.) But Eats, Shoots & Leaves hits the nail on the head when it comes to explaining how to properly apply punctuation.
Now back to the “joy” I hinted at earlier.
One of the hardest parts of editing and writing technology books is that
you sometimes have to let go of the things you’ve been taught in high school
or university English courses. You see, here is the dilemma:
When calling out UI elements (or other such things you want the reader
to type in) in the text, we often place them in quotations to call
attention to them. The problem is, some of these UI elements (or
typed-in things) don’t have punctuation, so when these fall in the
middle or at the end of a sentence, does it not make sense to put the
punctuation outside of the closing quotation?
For example:
…click the checkbox “Show displays in menu bar.”
After searching Google for “Mac inurl:tiger,” the search results…
Notice the problems with placing the punctuation inside the quotes?
Now I know what you’re going to say: “The punctuation goes inside the
quotes, right?” Wrong. And here’s why…
In referring to the Bible (the Chicago Manual of Style, 15th Edition),
I found the following buried in para 6.8 (p. 242):
“… In computer related writing, in which a file name or other
character string enclosed in quotation marks might be rendered
inaccurate or ambiguous by the addition of punctuation within
the quotation marks, the alternative system may be used, or
the character string may be set in a different font, without
quotation marks (see 7.79).”
The “alternative system” in question here is described in para 6.10 (p. 243):
“Alternative system. According to what is sometimes called the
British style (set forth in The Oxford Guide to Style [the successor to Hart’s Rules; see bibliog. 1.1]), a style also followed in other English-speaking countries, only those punctuation points that appeared in the original material should be included within the quotation marks; all others follow the closing quotation marks. This system, which requires extreme authorial precision and
occasional decisions by the editor or typesetter, works best with
single quotation marks. (The British tend to use double quotation
marks only for quotations within quotations.)”
My interpretation of this is that the proper usage should be:
…click the checkbox “Show displays in menu bar”.
After searching Google for “Mac inurl:tiger”, the search results…
Not:
…click the checkbox “Show displays in menu bar.”
After searching Google for “Mac inurl:tiger,” the search results…
See the difference?
Adding the punctuation inside the quotes implies that, in the first
example, the period is part of the UI element, which it isn’t, and
that the comma would be part of the search string, which it shouldn’t.
And since O’Reilly doesn’t use a different font style or type face for things
that we’ve quoted, that negates the ending statement of para 6.8
(”… or the character string may be set in another font, without
quotation marks”).
While traditional North American (or better, U.S.) style tells you to
put everything inside the quotes — no matter what — that shouldn’t
always be the case. In the case of tech books, the “alternative system”
(”…only those punctuation points that appeared in the original material
should be included within the quotation marks; all others follow the
closing quotation marks.”) should apply.
To quote Lady Truss (Eats, Shoots & Leaves,
p. 155):
“The basic rule is straightforward and logical: when the punctuation
relates to the quoted words it goes inside the inverted commas; when
it relates to the sentence, it goes outside. Unless, of course, you
are in America.”
And while I am an American, it’s hard to argue with logic.
Sticklers unite!
Are you a stickler for punctuation?