Style and Usage
This chapter provides guidelines on writing style and usage. The intent of these guidelines is to help maintain a consistent voice in publications of the Neos Project and in the user interface.
File Types
Use all caps for abbreviations of file types:
a PHP file, a YAML file, the RST file
Filename extensions, which indicate the file type, should be in lowercase:
.php, .jpg, .css
Abbreviations and Acronyms
An acronym is a pronounceable word formed from the initial letter or letters of major parts of a compound term. An abbreviation is usually formed in the same way but is not pronounced as a word.
Abbreviations are often lowercase or a mix of lowercase and uppercase. Acronyms are almost always all caps, regardless of the capitalization style of the spelled-out form.
Latin: Avoid using Latin abbreviations.
Correct:
for example, and others, and so on,
andthat is,
or equivalent phrasesIncorrect:
e.g.
(for example),et al.
(and others),etc.
(and so on),i.e.
(that is)
Above
You can use above
to describe an element or section of an onscreen document
that cannot be paged through (such as a single webpage).
Don’t use above
in print documents; instead, use one of these styles:
Earlier chapter: Use the chapter name and number:
To learn how to create movies, see Chapter 4, “Composing Movies.”
Earlier section: Use the section name followed by the page number:
For more information, see “Printing” on page 154.
Earlier figure, table, or code listing: Use the number of the element followed by the page number:
For a summary of slot and drive numbers, see Table 1-2 (page 36).
Braces
Use braces
, not curly brackets
, to describe these symbols: { }.
When you need to distinguish between the opening and closing braces, use left brace
and right brace
.
Brackets
Use brackets
, not squarebrackets
, to describe these symbols: [].
Don’t use brackets
when you mean angle brackets
(< >).
Capitalization
Three styles of capitalization are available: sentence style, title style, and all caps.
Sentence-style capitalization:
This line provides an example of sentence-style capitalization.
Title-style capitalization:
This Line Provides an Example of Title-Style Capitalization.
All caps:
THIS LINE PROVIDES AN EXAMPLE OF ALL CAPS.
Don’t use all caps for emphasis.
Capitalization (Title Style)
Use title-style capitalization for book titles, part titles, chapter titles, section titles (text heads), disc titles, running footers that use chapter titles, and cross-references to such titles.
- References to specific book elements:
In cross-references to a specific appendix or chapter, capitalize the word Appendix or Chapter (exception to The Chicago Manual of Style). When you refer to appendixes or chapters in general, don’t capitalize the word appendix or chapter:
See Chapter 2, “QuickTime on the Internet.” See Appendix B for a list of specifications. See the appendix for specifications.
- References to untitled sections:
In cross-references to sections that never take a title (glossary, index, table of contents, and so on), don’t capitalize the name of the section.
- What to capitalize:
Follow these rules when you use title-style capitalization.
Capitalize every word except:
Articles (
a, an, the
), unless an article is the first word or follows a colonCoordinating conjunctions(
and, but, or, nor, for, yet
andso
)The word to in infinitives (
How to Install Flow
)The word as, regardless of the part of speech
Words that always begin with a lower case letter, such as
iPad
Prepositions of four letters or fewer (
at, by, for, from, in, into, of, off, on, onto, out, over, to, up
andwith
), except when the word is part of a verb phrase or is used as another part of speech (such as an adverb, adjective, noun, or verb):Starting Up the Computer Logging In to the Server Getting Started with Your MacBook Pro
Capitalize:
The first and last word, regardless of the part of speech:
For New Mac OS X Users What the Finder Is ForThe second word in a hyphenated compound:
Correct: High-Level Events, 32-Bit Addressing Incorrect: High-level Events, 32-bit Addressing Exceptions: Built-in, Plug-inThe words
Are, If, Is, It, Than, That
andThis
Command Line
Write as two separate words when referring to the noun and use the hypenated form command-line
for and adjective.
Commas
Use a serial comma before and
or or
in a list of three or more items.
Correct: Apple sells MacBook Pro computers, the AirPort Extreme Card, and Final Cut Pro software.
Incorrect: Apple sells MacBook Pro computers, the AirPort Extreme Card and Final Cut Pro software.
Dash (em)
Use the em dash (—) to set off a word or phrase that interrupts or changes the direction of a sentence or to set off a lengthy list that would otherwise make the syntax of a sentence confusing. Don’t overuse em dashes. If the text being set off does not come at the end of the sentence, use an em dash both before it and after it:
Setting just three edit points—the clip In point, the clip Out point, and the sequence In
point—gives you total control of the edit that’s performed.
To generate an em dash in a reStructured text, use ---
.
Close up the em dash with the word before it and the word after it. Consult your department’s
guidelines for instructions on handling em dashes in HTML.
dash (en)
The en dash (–) is shorter than an em dash and longer than a hyphen. Use the en dash as follows:
- Numbers in a range:
Use an en dash between numbers that represent the endpoints of a continuous range:
bits 3–17, 2003–2005
- Compound adjectives:
Use an en dash between the elements of a compound adjective when one of those elements is itself two words:
desktop interface–specific instructions
- Keyboard shortcuts using combination keystrokes:
Use an en dash between key names in a combination keystroke when at least one of those names is two words or a hyphenated word:
Command–Option–Up Arrow, Command–Shift–double-click See also key, keys.
- Minus sign:
Use an en dash as a minus sign (except in code font, where you use a hyphen):
–1, –65,535
To generate an en dash in ReStructured Text, use --
. Close up the en
dash with the word (or number) before it and the word (or number) after it.
Kickstarter
A small application provided by the Kickstart paackage, which generates scaffolding for packages, models, controllers and more.