Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!bloom-beacon!think!barmar
From: barmar@think.COM (Barry Margolin)
Newsgroups: comp.sys.mac
Subject: Re: A question for Mac Authors
Message-ID: <27086@think.UUCP>
Date: 30 Aug 88 23:56:11 GMT
References: <1233@aucs.UUCP> <3496@Portia.Stanford.EDU>
Sender: news@think.UUCP
Reply-To: barmar@kulla.think.com.UUCP (Barry Margolin)
Organization: Thinking Machines Corporation, Cambridge, MA
Lines: 62

In article <3496@Portia.Stanford.EDU> mouser@portia.stanford.edu (Michael Wang) writes:
>On the subject of where the period should go after quotation marks the
>opinions are divided.  Style handbooks state that periods or commas always
>go inside the quotation marks.  However, many writers, when they use
>quotation marks to set-off a word or phrase put the period or comma after
>the quotations marks.
>
>Probably OK:     Click on the window named 'Untitled'.
>
>Mabye somebody who majored in English can clear this up?

Well, I didn't major in English, but I have an opinion about this.  In
normal English text, puctuation is supposed to go inside the quotes.
However, this rule was intended for sentences such as:

	John said, "Give me that."

The quoted material in such cases is also a sentence, so putting
punctuation inside the quotes makes sense.  I'm not so sure how it
works when the inner and outer sentences should end with different
punctuation, e.g.

	Did John say, "Give me that."?

I suspect in this case that the period should not be there, but that
the question mark is properly placed (because otherwise it would look
like "'Give me that?'", and the quotation would appear to be a
question, which it wasn't).

The specific needs of technical writing are not generally addressed in
standard writing style guides.  Indeed, many things that are good
style in prose are bad ideas in technical writing; for example, it is
better to use the same word for something in technical text, but in
literature it is better not to be repetitive.

In the case of program documentation, the quoted text is NOT generally
a sentence, it is a label.  In this case, I think the most important
feature of the writing style should be clarity.  Since the purpose of
the quotes is to set off a piece of text that should be identical to
something the user should see on the screen, the only thing inside the
quotes should be exactly what should be displayed.  Since the window's
name (using the above example) does NOT end in a period, there should
be no period inside the quotes.

In actuality, my personal preference is for documentation to use
typography rather than punctuation to set off such literals; quoting
is mostly a holdover from the days of simplistic line printers and
typewriters.  It is usually the case that the running text of the
documentation is not in the same typeface as the labels on the screen;
therefore, all you need to do is switch to the screen typeface when
you want to indicate something that the user will see on the screen.
For example:

	[New York]Click on the window named [Chicago]Untitled[New York].

(where I am using [Font] to indicate switching to the specified font).

Barry Margolin
Thinking Machines Corp.

barmar@think.com
{uunet,harvard}!think!barmar