peter@aucs.UUCP (Peter Steele) (08/24/88)
Here's a dumb question that someone might have an answer to. I write a
lot of documentation on my Mac. When I want a hyphen, I just press
the minus key. When I want an em-dash (a long dash), I use option
shift minus. The Mac keyboard also has a medium dash (option minus).
When is this type of dash used in documentation as opposed to the
short dash and the long dash?
And while we're on the subject...
When I write user documentation, I often have things like
...click on the button called "Okay".
Note the period: ^
Should this be outside the quotes as I have it, or should it go inside
the quotes? What are the general rules for quoted words/phrases and
punctuation in cases like this in technical documents?
And one final one: When an italicized phrase ends in a semicolon or colon
and the text that follows is not italicized, should the colon or semicolon
be italics or normal?
I know this is pretty mindless stuff to be wasting bandwidth on, but
would someone like to enlighten me?
--
Peter Steele, Microcomputer Applications Analyst
Acadia University, Wolfville, NS, Canada B0P1X0 (902)542-2201x121
UUCP: {uunet|watmath|utai|garfield}!dalcs!aucs!Peter
BITNET: Peter@Acadia Internet: Peter%Acadia.BITNET@CUNYVM.CUNY.EDUmouser@Portia.Stanford.EDU (Michael Wang) (08/30/88)
See article <1233@aucs.UUCP> titled 'A question for Mac Authors' for the
original text. This posting is LONG and possibly BORING.
I warned you!
-----------------------------------------------------------------------------
Hyphen (minus) ('-' in this text)
The hyphen is used to form compound words like 'X-rated' or 'mother-in-law'.
Another use of the hyphen is to break words on syllables at the end of lines.
-----------------------------------------------------------------------------
En Dash (option-minus) ('--' in this text)
The en dash is used for number ranges like 'pages 101--102'.
The word 'to' must be used if the numbers are preceeded by the word 'from'.
Wrong: from 1987--1988
Right: from 1987 to 1988
The en dash cannot be substituted for 'and'.
Wrong: Between 1987--1988 Apple reached record profit levels.
Right: Between 1987 and 1988 Apple reached record profit levels.
Generally it is incorrect to put a space on either side of an en dash.
Wrong: 1987 -- 1988
Right: 1987--1988
-----------------------------------------------------------------------------
Em Dash (shift-option-minus) ('---' in this text)
The em dash is used for punctuation in sentances---it is often simply called
a dash. An em dash may be open with a space on both sides, or closed with
no spaces, but generally it is used with no spaces on either side.
-----------------------------------------------------------------------------
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?
-----------------------------------------------------------------------------
On the subject of italicizing punctation, the rule I follow is below---I
have no idea if this is correct.
If a italicized phase contains punctuation as part of the phrase, then the
punctuation should be italicized. If the punctuation is not part of the
phrase, but part of the main sentence, then it should not be italicized.
-----------------------------------------------------------------------------
While we are on the subject of typography, use the proper quotations marks
whenever possible. If you are printing on a PostScript printer they look a
LOT better than ' and ".
Open double quote (option [)
Close double quote (shift-option [)
Open single quote (option ])
Close single quote (shift-option ])
-----------------------------------------------------------------------------
There are other uses of the hyphen, en dash, and em dash that are not listed
here, but can be found in any good style book.
References:
Barnet & Stubbs's Practical Guide to Writing
Macintosh Desktop Typography by John Baxter
The Little English Handbook by Edward Corbett
The TeXbook by Donald E. Knuth
-----------------------------------------------------------------------------
-Michael Wang
+--------------+------------------------------------------------------------+
| Michael Wang | Stanford University, Stanford, CA 94305 |
|--------------+------------------------------------------------------------|
| ARPAnet, CSNET, BITNET, Internet: mouser@portia.stanford.edu |
| UUCP: ...decwrl!portia.stanford.edu!mouser AppleLink: ST0064 |
+---------------------------------------------------------------------------+tedj@hpcilzb.HP.COM (Ted Johnson) (08/31/88)
>And while we're on the subject... > >When I write user documentation, I often have things like > > ...click on the button called "Okay". > >Note the period: ^ >Should this be outside the quotes as I have it, or should it go inside >the quotes? Outside the quotes. >What are the general rules for quoted words/phrases and >punctuation in cases like this in technical documents? If the item that your were quoting contained a period or any other punctuation, then this would be enclosed in quotes, and then the sentence would be terminated with a period (or whatever). E.g., if the button said "Click me if you hate Reagan!" then your documentation would read: ...click on the button labeled "Click me if you hate Reagan!". >And one final one: When an italicized phrase ends in a semicolon or colon >and the text that follows is not italicized, should the colon or semicolon >be italics or normal? Italics. -Ted
barmar@think.COM (Barry Margolin) (08/31/88)
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
shino@motbos.UUCP (Rei Shinozuka) (09/02/88)
In article <870223@hpcilzb.HP.COM>, tedj@hpcilzb.HP.COM (Ted Johnson) writes: > ...click on the button labeled "Click me if you hate Reagan!". The CORRECT form is: ...click on the button labeled "Click me to waste Dukakis in '88!" -rei
frank@mnetor.UUCP (Frank Kolnick) (09/02/88)
In article <1233@aucs.UUCP> peter@aucs.UUCP (Peter Steele) writes: >Here's a dumb question that someone might have an answer to. I write a >lot of documentation on my Mac. When I want a hyphen, I just press >the minus key. When I want an em-dash (a long dash), I use option >shift minus. The Mac keyboard also has a medium dash (option minus). >When is this type of dash used in documentation as opposed to the >short dash and the long dash? First, dashes are not just long hyphens. But let me quote Jan V. White in "Graphic Design for the Electronic Age": Hyphens link words together, but must be used with care because interpretation can be affected by the inclusion (or lack) of a hyphen. Follow the practice suggested by a good, up-to-date dictionary. There are two main kinds of dashes: the long em-dash and the short en-dash. ... The em-dash is a full square of the type size. One of its main uses is to signal sudden changes in tone. Or it may be used instead of parentheses to set off a clause or phrase. ... But, in general, use the em-dash sparingly, for it attracts attention to itself and can be disturbing. An en-dash is only one-half of the square of the type size and resembles a hyphen. It is used primarily to represent missing but implied items in a series ("2-4" means the numbers 2 through 4) > >And while we're on the subject... > >When I write user documentation, I often have things like > > ...click on the button called "Okay". > >Note the period: ^ >Should this be outside the quotes as I have it, or should it go inside >the quotes? What are the general rules for quoted words/phrases and >punctuation in cases like this in technical documents? Outside the quotes, unless the quotation itself is a complete sentence ending with a period. (e.g., "This is it." vs. This is "it".) > >And one final one: When an italicized phrase ends in a semicolon or colon >and the text that follows is not italicized, should the colon or semicolon >be italics or normal? White describes underlining and italics together: If you use underlining instead of italics, it should be uninterrupted -- the whole phrase whould be underlined, not just the individual words. But do not underline the final period or any other punctuation mark that ends the phrase or sentence. I take this to mean that italicizing the punctuation is OK. Personally, I don't italicize punctuation unless the preceding text obscures it (by leaning over it too far). >-- >Peter Steele, Microcomputer Applications Analyst BTW, J.V. White is the author of numerous books on graphics, typesetting, charts and graphs, etc. Highly recommended reading. -- Frank Kolnick, consulting for, and therefore expressing opinions independent of, Computer X UUCP: {allegra, linus, ihnp4}!utzoo!mnetor!frank
sysop@stech.UUCP (Jan Harrington) (09/02/88)
in article <1233@aucs.UUCP>, peter@aucs.UUCP (Peter Steele) says: > > Here's a dumb question that someone might have an answer to. I write a > lot of documentation on my Mac. When I want a hyphen, I just press > the minus key. When I want an em-dash (a long dash), I use option > shift minus. The Mac keyboard also has a medium dash (option minus). > When is this type of dash used in documentation as opposed to the > short dash and the long dash? The "en" dash (the one you call a medium dash) is often used to separate numbers, as in "pages 12-14." (Note that the dash in the example is a plain hyphen, since this Unix machine doesn't know one dash from the other.) > > And while we're on the subject... > > When I write user documentation, I often have things like > > ...click on the button called "Okay". > > Note the period: ^ > Should this be outside the quotes as I have it, or should it go inside > the quotes? What are the general rules for quoted words/phrases and punctuation in cases like this in technical documents? The punctuation almost always goes inside the quote, as in "Okay." I know, it seems weird, but every time I do it differently, some copy editor changes it. > > And one final one: When an italicized phrase ends in a semicolon or colon > and the text that follows is not italicized, should the colon or semicolon > be italics or normal? Normal. > > I know this is pretty mindless stuff to be wasting bandwidth on, but > would someone like to enlighten me? > This isn't mindless stuff, if it's important to you and makes your life easier. I hope this helps (I've posted it because I know there are so many people who write using this newsgroup!) Jan Harrington, sysop Scholastech Telecommunications UUCP: husc6!amcad!stech!sysop or allegra!stech!sysop BITNET: JHARRY@BENTLEY ******************************************************************************** Miscellaneous profundity: "No matter where you go, there you are." Buckaroo Banzai ********************************************************************************
tom@iconsys.UUCP (Tom Kimpton) (09/20/88)
The textbook for our technical writing class at school was:
"Technical Writing"
Gordon H. Mills and John A. Walter
Holt, Rinehart and Winston
copyright 1978 (4th edition)
--
Tom Kimpton UUCP: {uunet,caeco,nrc-ut}!iconsys!tom
Software Development Engineer ARPANET: icon%byuadam.bitnet@cunyvm.cuny.edu
Icon International, Inc. BITNET: icon%byuadam.bitnet (multi-user acct)
Orem, Utah 84058 PHONE: (801) 225-6888