This section reviews basic punctuation rules and guidelines for the English language, and notes exceptions that are specific to computer documentation.
Note - Traditional punctuation marks take on specialized meanings in the context of programming languages. A classic example is that of quotation marks in the C shell or Bourne shell, which provide specialized, non-intuitive meanings for single quotes (`), double quotes ("), and back quotes ('). Watch for these in your writing and editing.
Use an apostrophe:
Class of '66
Spirit of '76
If they do not end in "s," add an apostrophe and an "s" to most indefinite pronouns, singular nouns (including collective nouns), and plural nouns.
the file's properties
the group's privileges
To form the possessive of singular nouns ending in "s" (or its sound), you often add an apostrophe and an "s."
the mouse's buttons
the bus's capacity
When the addition of an "s" produces an awkward sound, add only the apostrophe.
ACME Systems' employees
In a few cases, however, either is acceptable.
M. Travis's files
M. Travis' files
Add an apostrophe to form the possessive of plural nouns that end in "s."
the Travises' files
the boards' interrupts
Add an apostrophe and an "s" to the last word of the compound to form the possessive of most compound constructions.
each other's files
anyone else's business
The possessive of two or more proper nouns depends upon ownership. In the first example, ownership is joint; in the second, individual.
Malcolm and Mary's files
Malcolm's and Mary's files
~'s and #'s
The plural possessive of single lowercase letters and single uppercase letters will be awkward in the plural possessive form. A rewrite often can avoid this situation.
The dots on the "i's."
The "i's'" dots.
The apostrophe is not necessary (although not incorrect) when you are forming the plural of two or more unitary uppercase letters or numerals.
plug in all CPUs
the operating system of the 1990s
Brackets are not substitutes for parentheses. To preserve brackets' unique service as meaningful signals to readers of computer documentation, construct sentences in a way that minimizes the grammatical need for such punctuation.
It often makes sense to place comments within a menu file (see page 154 of Advanced Skills, Revision A [May, 1991] for more information).
Use a colon:
Note that the colon takes the place of introductory phrases such as "as follows" and "listed below."
Default settings include four secondary groups: operator, devices, accounts, and networks.
Three options available from the Diagnostics menu are:
When the introduction to a list or steps in a procedure is a complete sentence, use of the colon is optional. However, judge whether the ensuing list seems to flow naturally from the introduction; in effect, to "complete" the introductory sentence. If so, use a colon.
Learn how to send a message by following these steps:
To send a message:
Follow the steps in the next exercise to learn how to mail a message.
The colon serves as a substitute for phrases such as "in other words," "namely," or "for instance."
Notice in the following example that the first word following the colon is capitalized. Capitalize the statement if it is a complete sentence; don't capitalize it if it's a fragment.
It was a software package doomed from the start: Its price was $12,000, its language written in ALGOL, and its documentation was printed on 300 sheets of unbound paper.
Here is the choice: Do you want to save the file or delete it?
Remember this cardinal rule: Never reboot your system until you've saved all of your files.
Use a comma:
Among your hidden files are .cshrc, .defaults, .login, .logout, and .mailrc.
Use a comma before the conjunction that joins the last two items of a series.
In complex sentences, however, elimination of the final serial comma sometimes helps to separate a long series from an independent clause.
Before going to the next step, position the pointer on the desktop, display the menu, make your selection and confirm the result, and you will ensure the accuracy of your data.
However, if an independent clause already contains a comma, use a semicolon to separate items in a series.
The window has a menu bar, which lists available menus; a palette, which shows graphics tools; and a working area, where you draw.
A comma separates independent clauses joined by the coordinating conjunctions "and," "but," "yet," "for," "nor," and "or." Place the comma before the conjunction.
You don't have to back up your files, but doing so is prudent.
She lost all of her work, yet she still doesn't back up files.
Omit the comma between two short independent clauses in a sentence.
Back up your work or you're fired.
Display the menu and choose Save.
Use a comma to separate a subordinate clause or long introductory phrase from the rest of the sentence.
Using the text editor, change the last line of the file.
By recording transactions and automating billing, the financial software saves time and prevents costly errors.
Use a comma after a dependent adverbial clause that starts a sentence, but not if the clause appears in normal order in the sentence.
Because this feature automatically updates system files, it saves time.
This feature saves time because it automatically updates system files.
A comma separates an introductory modifier from the rest of the sentence.
Hopefully, he entered the personnel office.
Confident she had saved her work, she logged out.
A comma sets off introductory interjections or transitional words.
Oh, did you need more information?
Fine, go ahead and set up that meeting.
The mail icon, which looks like a mailbox, flashes.
Writers often refer to this book, which is a style guide for the computer industry.
The software, with its simple interface, will decrease input time by 50 percent.
Write to ACME Systems, Santa Maria, California.
The monitor, hardware that looks like a television set, has only one function.
She was hired on January 1, 1989, and left six months later.
:She was hired in January 1989.
Use an em dash, with no space before or after the dash:
Three vital pieces of hardware - the keyboard, the system unit, and the monitor - are packed in the largest carton.
Use of dashes in the example above avoids the confusion that could be caused by using commas both within the series and to set off the series from the rest of the sentence.
In most cases, use commas instead of dashes to set off a single appositive.
The monitor, hardware that looks like a television set, sits on top of the system unit.
Log in to the system - but that's an obvious first step.
Become superuser - you must type su to do this - and delete all files in M. Travis's directory.
All of the options - Create, Modify, and Save - enable you to customize the software's features.
Use an en dash:
Refer to pages 16 - 24.
Do not operate this equipment in temperatures lower than - 10 °C.
The word processing software features:
An ellipsis mark comprises three ellipsis points (periods) with a space between each point. A space separates the ellipsis mark from preceding and subsequent text and punctuation.
Use an ellipsis mark:
When the system displays, "Do you want the . . . settings now?"
Add a period when a complete sentence ends with an ellipsis mark or when you have omitted entire sentences from quoted matter. In effect, you type four periods, each preceded by a space.
You see this message on the screen: "If you like, you may press the Stop key . . . ."
The system then displays this message: "This system is being configured . . . . When this system is configured, it will finish booting."
Reformatting page. Wait . . .
Because the computer industry has developed unique terminology, the use of hyphens has become troublesome. Computer documents are often littered with unnecessary hyphens. Refer to Table 5-1 for a list of words and phrases that have come into general acceptance as hyphenated, unhyphenated, or compound.
If you can't find a specific word or term in the table, apply this general rule: Hyphenate a multiword expression when used as a modifier; do not hyphenate the expression when used as a verb or noun.
the check-in procedure
check in the material
the direct-access password
if you have direct access
the end-user application
writing for end users
This section includes guidelines for when to use a hyphen and when not to use a hyphen.
Use a hyphen:
This applies only to user-defined functions.
Print your 500,000-byte file.
Hyphenate a compound modifier when it appears before the noun. Usually, when it appears after the noun, a compound modifier should not be hyphenated.
An easy-to-remember mail alias is a person's first initial and last name.
A mail alias that is easy to remember is a person's first initial and last name.
Occasionally, the initial elements of two or more compound modifiers within the same sentence share the same final element. In these constructions, hyphenate the initial elements, even when they are not joined directly to the final, common element.
The sending application and the receiving application expect 8- and 7-bit characters, respectively.
These computers have file-, directory-, and labor-saving features.
"Ed owns a toy-repair store" vs. "Ed owns a toy repair store"
"He recovered the disc" vs. "He re-covered the disc"
re-enable, co-organizer, shell-like, reentry, unnumbered, misspell
Use a hyphen to join numbers and proper nouns or adjectives with the following prefixes. (These same prefixes, however, are usually joined without hyphens to common nouns and modifiers.)
anti- mid- neo- non-
pan- pro- un-
Almost without exception, hyphens join the following prefixes with the main word of a compound.
all- ex- self-
The resulting core file will take up nearly one-third of your system memory.
Do not use a hyphen:
Dial up only after reading the dial-up instructions.
Look up the value in the look-up table.
An easily remembered mail alias is a person's first initial and last name.
Your file comprises 500,000 bytes.
bi inter meta micro mini multi
non pre post un under
Refer to pages 16 - 24.
Table 5-1 Hyphenation Guidelines
------------------------------------------ Word or Phrase Usage ------------------------------------------ A add on verb add-on noun, modifier all-inclusive modifier alphanumeric modifier analog-to-digital modifier antiglare modifier automount verb autotransformer noun B back panel noun back-panel modifier backplane modifier, noun backquote modifier, noun backslash modifier, noun backspace modifier, noun, verb back up verb backup modifier, noun bandwidth modifier, noun benchmark modifier, noun bidirectional modifier bisynchronous modifier bitmap modifier, noun bitstring modifier, noun breakpoint modifier, noun build in verb built-in modifier C card cage noun CD-ROM noun, modifier check in verb check-in noun, modifier checklist noun check out verb check-out noun, modifier client-server modifier coaxial modifier code name noun colormap modifier, noun command line noun command-line modifier compact disc noun coprocessor modifier, noun coroutine modifier, noun cross-refer verb cross-reference noun cross-section noun cross-sectional modifier D database modifier, noun datasheet modifier, noun datastream modifier, noun daughterboard modifier, noun debug modifier, noun, verb deselect verb desktop modifier, noun dial up verb dial-up modifier digital-to-analog modifier direct access noun direct-access modifier directory name noun double click noun double-click modifier, verb download verb downtime modifier, noun drag and drop noun drag-and-drop modifier dual-access modifier dual-density modifier dump file noun E electromagnetic modifier email modifier, noun endpoint noun end user noun end-user modifier entry level noun entry-level modifier F feedback noun file name noun file server noun file sharing noun file-sharing modifier file system noun firmware noun fixed length noun fixed-length modifier fixed point noun fixed-point modifier floating point noun floating-point modifier flowchart modifier, noun follow up verb follow-up modifier frame buffer noun front end noun front-end modifier front panel noun front-panel modifier full height noun full-height modifier G general-purpose modifier grayscale modifier, noun H half-height modifier hard copy noun hard-copy modifier hardwire verb hardwired modifier hexadecimal modifier high end noun high-end modifier high level noun high-level modifier high performance noun high-performance modifier high resolution noun high-resolution modifier high speed noun high-speed modifier host name noun host-name modifier hot key noun hotline modifier, noun I in-line modifier inode noun interconnect modifier, noun, verb interface modifier, noun internetwork modifier, noun interoperability noun interprocess modifier, noun K keyboard modifier, noun keymap modifier, noun keypad modifier, noun keyword modifier, noun L laser disc noun left-justified modifier list file noun local-area modifier lock up verb lockup modifier, noun log file noun log in verb login modifier, noun log out verb logout modifier, noun look up verb look-up modifier low end noun low-end modifier low level noun low-level modifier low resolution noun low-resolution modifier lowercase modifier, noun M mailbox noun mainframe modifier, noun mass storage noun mass-storage modifier metadisk modifier, noun metafile modifier, noun microcode modifier, noun microprocessor modifier, noun microsecond noun midrange modifier, noun minicomputer modifier, noun miniroot noun monochrome modifier motherboard modifier, noun multilevel modifier multimedia modifier, noun multiplexer modifier, noun multiprocessor noun multitasking modifier multitrack modifier, noun multiuser modifier N newline modifier, noun node name noun noninterlaced modifier nonproprietary modifier nontechnical modifier nonzero modifier O object-oriented modifier off line adverb off-line modifier off-load verb on-board modifier on line (or online) adverb on-line (or online) modifier P path name noun path-name modifier pop-up modifier print out verb printout modifier, noun pull-down modifier pull-right modifier R random access modifier raster file noun raster-file modifier read-only modifier real time noun real-time modifier re-create verb restart verb retry verb right-justified modifier runtime modifier, noun S SBus noun scrollbar noun self-test modifier, noun set up verb setup modifier, noun shut down verb shutdown modifier single-tasking modifier source code noun source-code modifier source file noun source-file modifier standalone modifier start up verb startup modifier, noun subdirectory noun subentry noun subroutine modifier, noun subset modifier, noun subsystem modifier, noun subtest noun superblock noun supercomputer modifier, noun superuser noun T 2-D modifier 3-D modifier text-only modifier time-out modifier timesharing modifier, noun timestamp noun time zone noun token ring modifier toolkit modifier, noun tradeoff noun triple-height modifier troubleshoot verb troubleshooting modifier U upload modifier, verb uppercase modifier, noun uptime noun user ID noun user name noun V video disc noun W wide-area modifier wildcard modifier, noun word processing modifier workgroup modifier, noun worksheet noun workspace modifier, noun workstation noun write-back modifier write-enable verb write-enabled modifier write-protect verb write-protected modifier Z Z-buffer noun ------------------------------------------
Before using parentheses, consider whether the parenthetic material is, in fact, important enough to be included at all. If it is, perhaps the text fits better without parentheses within the paragraph. If the information is not important, don't write it.
The Font menu, which provides four options (Regular, Italic, Bold, Bold Italic), is easy to use.
You can save these settings in a "quick-start" file (explained fully in the next step) to load them automatically.
To suppress the printing of address information (particularly useful for messages with many addresses), remove the check from the Print Header box.
Choose from (a) keyboard entry, (b) mouse entry, and (c) voice entry.
Choose from (a keyboard entry, (b mouse entry, and (c voice entry.
The operating system inserts a tilde (~) when a file name is too long.
The software package tracks maintenance on your heating, ventilating, and air conditioning (HVAC) systems.
Whole paragraphs should never be parenthetic.
Position the pointer on the top scrollbox and click the left mouse button. (For detailed instructions on scrolling windows, see page 33.)
Use a period:
The procedures are in the howto.doc file.
The ls -a command lists .cshrc and .orgrc among your hidden files.
In the UNIX system, a period also serves as an abbreviation for the current directory.
To copy a file into the current directory, type cp ~/work/budget .
Computer documentation is always grammatically precise.
Whenever possible, avoid ending a sentence with a verbatim command that the must be typed. A reader might misinterpret the sentence's ending punctuation as an integral part of the command.
"Type boot to restart the computer." vs.
"To restart the computer, type boot."
The meeting is at 10 a.m. on Friday.
Use quotation marks:
Don't enclose verbatim commands, system messages, file names, and so forth in quotation marks. In some cases a reader may be misled into thinking that the quotation marks are an integral part of what is to be typed.
The comment in the .login file states that the file is "read in when you exit from the login shell."
For more information about editing mail, see Chapter 5, "Sending and Receiving Mail."
You can use the tee command to take a "snapshot" of your keystrokes.
The word "menu" is often used in technical writing.
The letter "x" denotes . . . .
No single rule governs the placement of quotation marks that are next to other punctuation marks. Whether the final quotation mark follows or precedes another punctuation mark depends upon context.
"Yes," he replied, the program is written.
There are three buttons on your "mouse": left, middle, and right.
Some of your files are "hidden"; that is, their names do not appear in a standard ls directory listing.
The system prompts, "Do you want to continue?"
The user guide answers the question, "What does it do?"
But place the final quotation mark before a question mark or exclamation point that is not part of the quoted material.
How do I display a list of files that are "hidden"?
Use a semicolon:
The Open key is a toggle key; that is, a key with alternating functions.
Some of the options are not available; for example, the Undo option is grayed out and the Spell option is not displayed.
Because this software is supplied in source-code form, users may adapt it for use on other systems; however, modified source code is not supported by ACME Systems.
A semicolon also separates independent clauses not joined by a conjunction.
Don't write the introduction; all introductions are now written by Marketing.
The Reply button provides the following options: Reply (all), include; Reply, include; Reply (all); and Reply.