Resources
Table of Contents

3. Writing Style

The Open Group preferred writing style is based upon the guidelines contained in Read Me First! A Style Guide for the Computer Industry.

The information presented here summarizes the key features of this writing style, and documents decisions made for areas where the above guide does not recommend specific editorial policy.

This chapter starts with a list of general writing style guidelines, and thereafter consists of an alphabetically ordered list of style components.

3.1 General Guidelines

These general guidelines are designed to take account of readership, internationalization, and translation considerations.

3.1.1 Audience

3.1.2 Plain Language

3.1.3 Consistency

3.1.4 Geography and Culture

3.1.5 Racial Insensitivity

Note:
The term "master" can still be used on its own in the following cases:
  • When discussing skills and proficiency; for example, "Webmaster", "master class", "mastering the basics", or "Master's degree"
  • As part of a longer term, such as "master data", as long as there is no connection to slavery or dominance, either directly or through metaphor
  • In other standard English terms that have no connection to "slave" in apposition, such as "scrum master", "mastermind", "master bill", and the like

3.1.6 Gender Neutrality

3.1.7 Ableist Language

When trying to achieve a friendly and conversational tone, problematic ableist language may slip in. This can come in the form of figures of speech and other turns of phrase. Be sensitive to your word choice, especially when aiming for an informal tone. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. Choose alternative words depending on the context.
For example: Replace the dummy variable in this example with the appropriate variable.

could become:

Replace the placeholder variable in this example with the appropriate variable.

3.1.8 References to Third-Party Products/Organizations

3.1.9 Miscellaneous

3.2 Abbreviations, Acronyms, and Mnemonics

Where possible, keep to commonly used abbreviations, acronyms, and mnemonics and avoid inventing new ones. Once introduced, use them consistently.

An abbreviation is a shortened form of a term. An acronym is a word formed from the initial letters or parts of compound terms. A mnemonic is a memory aid.

For clarity, define abbreviations, acronyms, and mnemonics the first time you use them and add them to the glossary. In such cases, show the spelled-out version followed by the abbreviation, acronym, or mnemonic in parentheses. For example: 

the Open Data Element Framework (O-DEFTM)

Use uppercase letters for acronyms and mnemonics. Use uppercase initials for spelled-out versions where this is helpful. Acronyms can include lowercase letters if they are trademarks.

The derivation of an abbreviation, acronym, or mnemonic may be of little importance to the reader if it is commonly used; for example, BASIC or FORTRAN. In this case, omit the spelled-out version.

If the pronunciation of an acronym may not be obvious to the user, provide the pronunciation.

The preceding indefinite article (a or an) depends on the way the abbreviation is commonly pronounced; an is used where the abbreviation begins with a vowel sound, otherwise use a. For example, "a mOSI" (pronounced "mosee"), "a LAN", "an NDR".

Do not use an apostrophe to form the plural of an abbreviation, acronym, or mnemonic. Add a lowercase "s"; for example, OEMs.

Avoid beginning sentences with abbreviations, acronyms, or mnemonics, unless they have been fully explained in preceding text.

Do not use periods or intervening spaces with abbreviations, acronyms, and mnemonics unless the abbreviation can be confused with an actual word; for example, "no." for number, or "in." for inch.

Abbreviations may be used in tables, examples, figures, and footnotes.

3.3 Acknowledgements

Create a list of contributors, and indicate the nature of their contribution, such as author of source material, provider of source material, drafting, reviewing, and so on.

Use the same style for each contributor; e.g., A. Smith, Company X.

Where practical, arrange the contributors in alphabetical order by surname.

If applicable, you may include a list of the members of the Forum or Work Group involved in the development of the document.

3.4 Alphabetical Order

In general, any list of items which does not have a sequence or priority should be arranged in alphabetical order.

Use the order produced by the sort command, except that all special characters should be grouped together.

The following list (read from left to right, from the top down) shows the correct alphabetical sequence: 

!  ``  #  $  %  &  '  (  )  *  +  '  -  .  /  :
;  <  =  >  ?  @  [  \  ]  ^  _  `  {  |  }  ˜
0  1  2  3  4  5  6  7  8  9
A  a  B  b  C  c
 .
 .
 .
X  x  Y  y  Z  z

Alphabetize acronyms according to their shortened form.

Use locale-specific collating order for non-English languages.

3.5 Capitalization

Use initial capitals for nouns that refer to a specific person, title, or object.

Do not use initial capitals for nouns that refer to generic or non-specific people, titles, or objects; for example, system manager, computer, program.

Use initial capitals for product names.

Use initial capitals for the names of objects capitalized on the screen; for example, "The Clear menu item ...".

Use initial capitals for the following words when followed by a letter or number: Chapter, Appendix, Section, Version, Release, Guideline, Table, and Figure.

Do not use initial capitals for the words step, line, or column when they are followed by a number.

See also 3.38 Titles .

3.6 Cautions

Use a caution to draw the reader's attention to information which can have a significant or serious impact on the subject being described. See also 3.28 Notes and 3.40 Warnings .

3.7 Contents

The table of contents is produced automatically when a document is built.

3.8 Copyright

All documents published by The Open Group are copyrighted, and this information must be included in all documentation.

Copyright notices must include the word Copyright and the copyright symbol (©), the copyright date (month, year), and the copyright owner. For example, "Copyright © March 2020, The Open Group".

Follow this with the words "All rights reserved".

Include The Open Group standard statement concerning restricted rights.

Note:
All copyright text will be checked and verified by The Open Group Legal team at the Executive approval stage in the publication process.

A statement of the country of origin should be added, such as "Published in the UK by The Open Group, March 2020".

3.9 Cross-References

Cross-references can be made to complete elements (such as chapters and appendices), sections, figures, tables, and examples.

If a table or figure has no identifier, you can refer to it is as "the following ...", provided this text is immediately before the referenced object.

Do not hard-code page numbers.

All internal cross-references should be as precise as possible, to ensure rapid location of the required material. Note that a reference to Section 7.1 is an instruction to the reader to read all of Section 7.1, not merely the introductory paragraph.

Brief cross-references should be placed in parentheses within sentences. Longer cross-references should be placed in a separate sentence.

3.10 Dates

Dates should be written out in full. The month should be spelled out and the year should not be abbreviated, even when used in a range. For example, "March 5, 2020".

If dates are used in examples, include an explanation of the purpose, so that it can be translated correctly.

3.11 Definitions

The Open Group Standards should include a chapter on terms and definitions. Since The Open Group Standards are designed to follow a template acceptable for ISO/IEC standardization, this is usually the second chapter. This should start with the text below: "For the purposes of this standard, the following terms and definitions apply. Merriam-Webster's Collegiate Dictionary should be referenced for terms not defined in this section."

There is no need for the standard to define a term if the dictionary definition as defined by the Merriam-Webster's Collegiate Dictionary suffices.

Definitions should appear in alphabetical order, and the term defined should be written out completely and should not be inverted (e.g., "data architecture" rather than "architecture, data"). Alternatively, a systematic order according to a hierarchy of concepts may be used.

Each definition should be a brief, self-contained description of the term in question and shall not contain any other information, such as requirements or elaborative text. The term should not be used in its own definition.

Definitions should not take the form of a cross-reference to another definition only. You should rewrite it to contain a short definition.

Cross-references to other definitions should occur after the definition. Use of "See" refers to a term where the desired definition can be found. Use of "See also" refers to a related term.

References to other sections of the document should be moved to a note. Try to keep the note with the definition.

3.12 Equations

Equations should be used with care — they may not display adequately in all output formats.

3.13 Examples

Consider adding examples to illustrate the following:

Try to avoid artificial names such as "foo" and "bar" in examples. Try to use meaningful names for filenames and other arguments used in examples.

Vary the use of names for people — Anglo-Saxon and non-Anglo-Saxon, male and female.

In location examples, use cities that are recognizable without the state or country.

Never include names of actual system accounts and passwords. Remember to edit system and user information out of screen-captures.

Program examples should include extensive comments as part of the program text.

Avoid the use of editorial "we", "our", and "let's" in text surrounding examples.

Avoid examples that require an alphabetically ordered list of abbreviations, acronyms, or mnemonics to convey meaning. This can cause translation difficulties because the translated list will probably not be in alphabetical order. If you cannot avoid using an alphabetically ordered list, indicate the purpose of the example so that translators can design an example that is appropriate.

Example titles should use the conventions described in 3.38 Titles .

If the example shows an action performed by a system item, use the gerund form of the action in the example title (for example, "Sorting a File"). Do not use gerunds in titles of descriptive examples (such as showing a sample file or presenting a table of useful expressions).

3.14 External References

The preferred method for referring to any document is to use standard text for all occurrences.

You can use an abbreviated document title within the text of a document (for example, "see the ANSI COBOL standard"), but you should include the full title and bibliographic details in the Referenced Documents section.

When referring to a book produced by The Open Group, use the book's abbreviated title (for example,"see the O-RA Standard").

Avoid referring to specific elements (such as chapters or sections) of another document.

Some useful URLs for checking bibliographic details are provided in B. Resources .

Brief document references should be placed in parentheses within sentences. Longer document references should be placed in a separate sentence or in a footnote.

3.15 Filenames, Pathnames, and URLs

Use initial periods when referring to a file type. For example, "a .c program", "the .LIS file".

If punctuation characters are part of a filename, pathname, or URL, set it off from the text when its appearance in a sentence might be confusing.

You do not need to include "http://" in URLs that start with "www".

3.16 Font Usage

Refer to 5. Presentation for font usage.

3.17 Footnotes

Use footnotes with care to avoid introducing distracting information which can hinder rather than help the reader. If an explanation is required that would interrupt the flow of information in the text, use a footnote.

3.18 Glossary

A glossary should include specialized words, abbreviations, acronyms, and mnemonics used in the body of the document.

Note:
For The Open Group Standards, the glossary contains supplementary terms only.

Each glossary entry should consist of the term itself, followed by a brief definition. A brief expanded definition of the term may also be added.

Synonyms of words used in the text should be included with a cross-reference to the main glossary entry.

3.19 Grammar

Where no particular rule is specified and if there is a difference between usage in the UK and the US, the US version is used.

Use simple syntax, present tense, and active voice whenever possible.

Use imperative verbs to tell the user what to do.

An infinitive (to verb) must be treated as one word; try not to split the infinitive by inserting another word between the to and the verb.

A sentence must not start or end with a preposition.

Avoid using irregular perfect participles such as learnt and spelt, using instead learned and spelled.

Do not leave out articles, such as "a", "an", and "the". This style of writing can lead to misinterpretation and incorrect translation. (This rule may be waived where space is limited, such as in a table, figure, or example.)

Make sure the noun to which a pronoun refers is clear. If necessary, repeat the noun.

The following pronouns are always singular: another, any, anybody, each, either, every, everybody, everything, neither, nobody, no-one, nothing, one, someone. The following pronouns are always plural: both, few, many, others, several, some.

Avoid using system items as verbs; for example, "use grep to find the string", rather than "grep for the string".

3.20 Graphics

Use Arial font for all text in graphics, and align the text with the document content (e.g., consistent naming).

Use an initial capital for the first letter of every word of text used in graphics, with the exception of flowcharts and data structures (where just the first word is capitalized), and case-sensitive system item names.

For figure captions, use the conventions described in 3.38 Titles .

Colors should be in line with The Open Group corporate palette.

Note:
The Open Group editors require editable source for all graphics (e.g., pptx, Archi, Visio, svg).

The exceptions to this are:

  • Where a third-party graphic is included, we can reproduce the original with permission (note this must be high resolution)
  • Where a stock image has been used, such as a photograph (note this must be high resolution)

3.21 Hyphenation

Use the hyphen for the following prefixes: 

all-  cross-  half-  multi-  non-  post-  quasi-  self-

Do not use the hyphen for the following prefixes: 

anti  bi  co  dis  extra  infra  inter  intra  macro  meta  micro
mid  mis  over  pre  pseudo  re  sub  super  ultra  un

However, when any prefix is followed by a word beginning with the same letter, add a hyphen.

Prefixes should always include a hyphen if the root word is all uppercase, has an initial capital, a number expressed as a figure, or if the root element is a hyphenated compound.

Use a hyphen if adding a prefix results in unclear meaning. For example, re-collect/recollect, re-cover/recover, re-solve/resolve, and so on.

The words in a noun phrase, when the phrase is functioning as an adjective or modifier, are joined by a hyphen (even though they might not be otherwise). For example, a process initiated by the user is a user-initiated process.

The following suffixes can be added to nouns:

-based -defined -dependent -independent -oriented -specific

The compound adjectives so formed must be used with care. Do not adopt this practice where the sentence is simpler and clearer with a different construction; for example, "the transaction-manager-dependent issue" is clearer as "the issue dependent on the transaction manager".

Adverbial phrases are not hyphenated; for example, "externally developed program".

Hyphenate a modifying phrase when it precedes the noun it modifies. For example, "state-of-the-art design".

3.22 Index

An index is produced automatically when the document is built, provided index terms have been added.

The index should consist of important words and symbols from the text, together with concepts, synonyms, or paraphrases that are related to the main index entries.

Be consistent in spelling index entries and avoid using plurals and initial capitals wherever possible, so that all entries on one topic can be collected together correctly.

Do not use automatic indexing tools. The results are typically too long and do not adequately pinpoint information for the reader.

3.23 Keyboard Keys

When referring to the name of a control key on a keyboard (such as Control or Enter), use an initial capital letter.

When referring to the name of a key which is not on a keyboard, use a lowercase initial; for example, the space bar, the comma key.

Use x to refer to a generic letter key, and n to refer to a generic number key.

Refer to a control sequence in text as follows: Ctrl-x. That is, use an initial capital for the word "Ctrl", followed by a hyphen, followed by the lowercase letter. Use ^x to refer to a control sequence when describing system output.

Place angle brackets around key names that are labeled on the keyboard; for example, <Return>.

Use <Return> to refer to the key used to enter commands.

Use the verb press when referring to keys.

Refer to keys on the keyboard, not buttons.

Do not use the name of a key as an adjective. For example, use "Press <Return>" and not "Press the Return key".

Functions may be bound to different keys due to localization. Follow these guidelines when documenting keyboards:

3.24 Lists

Lists are a good way to break up long sentences or paragraphs and to clarify choices and steps, but it is important that lists are introduced with a clear (but brief) lead-in phrase. Too many lists without clear lead-in phrases interrupt the flow of the text, and can be distracting to the reader.

Use a colon after a lead-in phrase that is a complete statement; for example, "The values of local are defined as follows:".

The type of list you use depends on the type of items contained in the list:


Use the following rules when constructing lists. These rules apply to all types of lists, unless otherwise indicated:

Nested lists can be used as follows:

If a list item runs to several paragraphs, or includes complex material, you should consider using unnumbered headings instead of a list.

For lists in text use a comma (the Oxford comma) to separate items in a series of three or more words, phrases, or clauses, including the last item before a conjunction. For example, "a, b, and c".

3.25 Measurement

Provide measurements in SI units.

Place the abbreviation for a unit of measurement at the end of a series of two or more items; for example, "1200, 1400, or 1600MHz".

Repeat the abbreviation for a unit of measurement in a series of two items; for example, "10KB to 12KB".

Plural and singular abbreviations of units of measurement are the same; for example, "1KB" and "10KB".

Insert a space between a number and the unit of measurement it modifies, except for KB, MB, kHz, MHz, GHz, and K. For example, "6 m" and "6MB".

The context should enable differentiation between the two meanings of K: binary thousand and Kelvin.

Avoid using the number sign (#), single quote ('), and double quotes (") symbols to indicate the pound, foot, and inch Imperial units of measurement.

Indicate which units of measurement are used as an aid to translators.

3.26 Monetary Values

Avoid monetary values since they are country-specific.

Monetary values may be included in examples, but their purpose must be indicated as an aid to translators.

3.27 Names

Use initial capitals for names.

The name of an organization is treated as a singular noun. For example, "The Open Group publishes documents".

3.28 Notes

Notes should be used to call attention to important information that the reader should not overlook. They should be used sparingly. See also 3.6 Cautions and 3.40 Warnings .

3.29 Numbers

As a general rule, use numerals rather than spelled-out numbers, and be consistent in their use.

Avoid beginning sentences or headings with numerals.

Use to (and not through) for inclusive ranges. In tables and graphics, use a dash.

Hyphenate numbers or numerals in compound modifiers (500,000-byte file), but not in single modifiers (500,000 bytes).

Use a comma in numerals of more than four digits (for example, 10,000). Do not use commas in binary, octal, or hexadecimal numbers.

Do not use an apostrophe to form the plural of a number. Instead, add a lowercase s; for example, 4s, 1920s.

Insert a space between a number and the unit symbol it modifies, except for degrees, minutes, and seconds of an angle.

3.30 Pagination

Refer to 5. Presentation for pagination.

3.31 Portability Codes

Where a technical specification is aligned with one or more formal standards, it often supersets and extends the functionality of the formal standard, or perhaps presents a more exact (and restrictive) definition. When this occurs, it is often desirable to clearly mark this in the document as an aid to the reader. A number of techniques are available to do this; whichever is chosen must be clearly defined within the document (see 5.17 Shading ).

3.32 Punctuation

()
Parentheses enclose qualifying or explanatory material that is included in a sentence or paragraph. In most cases, it is preferable to restructure the sentence to avoid overuse of parentheses.

If the text inside parentheses is a complete sentence, put the terminating period inside the parentheses and terminate the preceding sentence. (This is an example.)

If the text inside parentheses is not a complete sentence, embed it in a sentence, so that the normal period or comma appears on the outside of the parentheses (like this).

If required by the context, place a comma after the closing bracket.

Try to avoid nested parentheses in text; nested tangential thoughts can be difficult to follow. Use several sentences inside the parentheses if necessary.

[]
Brackets are not used in text. They are used literally in syntax to indicate bracket characters. Each document should describe how it uses brackets in a section on "Typographical Conventions".
{}
Braces are not used in text. They are used literally in syntax to indicate brace characters. Each document should describe how it uses braces in a section on "Typographical Conventions".
<>
Angle brackets are not used in text. They are used literally in some cases where, for example, C programs use them to indicate a filename. In arithmetic, text may refer to these characters as less than and greater than, respectively.

They should be placed around key names that are labeled on the keyboard; for example, <Return>.

'
An apostrophe indicates possession or a missing character. It is never used to form a plural.

Its is the possessive pronoun of it. It is should be used in preference to its contracted form it's.

Use an apostrophe and a lowercase "s" to form the plural of a lowercase letter used as a noun; for example, a's, y's.

This character is also a single quote. Use 66-99 quotes in preference to single quotes. However, the single quote may be used literally in syntax.

:
A colon directs the reader's attention to whatever follows it.

Use a colon when you use for example, the following, follows, or as follows to lead in to an object beginning on the line below.

Use a colon at the end of lead-in phrases for lists, tables, figures, and so on.

;
Use a semicolon to join closely related independent sentences or clauses.

When the elements in a series are long and complex, or involve internal punctuation, they should be separated by semicolons.

''
(Double quote) Use literally in syntax if required. See 66-99 below.
`
(Back quote) Use literally in syntax if required.
“”
(66-99) In text, quote using 66-99. Only use quotes when the item quoted would look awkward, incomplete, or ambiguous without them, or when the reader would have trouble parsing the sentence without them. Do not use them when defining a new term.

Only use quotes as a way to emphasize a word or phrase when that word or phrase is unique in some context or technical sense.

Use quotes to indicate material quoted from another source, or to enclose single letters.

Do not use quotes where they may be interpreted as part of the syntax. If in doubt, place the text on its own line.

Do not put quotes around items designated as screen objects.

Closing quotation marks appear before:

  • Colons
  • Semicolons
  • Most adjacent punctuation marks (commas and periods)
  • Question marks and exclamation points, when the question marks and exclamation points are not part of the quoted material

If the text inside quotes is a complete sentence, put the terminating period inside the quotes and terminate the preceding sentence. ("This is an example.")

If the text inside quotes is not a complete sentence, embed it in a sentence, so that the normal period or comma appears on the outside of the quotes ("like this").

,
(Comma) Place a comma before the conjunction in a compound sentence (consisting of two or more independent clauses), unless the clauses are short and closely related. For example, "The system prints an error message, but you can continue processing the file ...".

Use commas to set off a non-restrictive modifier which provides additional information but does not affect the meaning of the words it modifies. For example, "A symbol value may be an absolute constant, expressed as a 32-bit integer, or a relocatable value ...". Conversely, do not use commas to set off a restrictive clause which does affect the meaning of the word it modifies. For example, "Table 6-1 describes the hardware that you need to complete your system ...".

Use commas to set off contrasting and opposing expressions within sentences. For example, "He changed the software, not the hardware ...".

Place a comma after an introductory clause or long introductory phrase. For example, "To specify an output device, enter a name in the command line ...".

3.33 Special Characters

The standard character reference used by The Open Group is the ISO 8859-1 Latin-1 character set.

When referring to a printable character for the first time, use the spelled-out name of the character first, followed by the character in parentheses (except in examples, where you should use the character literally). You can add the word "character" if necessary (for example, "the backslash character"). After the first occurrence, you can use the name of the character without showing the character itself.

A special character has no plural form. Spell out the name. For example, "Enter three backslashes (\\\)".

When referring to non-printable characters, use the name of the character alone in text. For example, "you must separate arguments with a space character ...". If the character must be shown without spaces between it and an adjacent character, enclose the name of the non-printable character in angle brackets. For example: 

<Tab><Tab>field1

The special characters you are most likely to use are:

#
The international number symbol; referred to as the hash sign.
(UKP)
The UK pound sign. It should be referred to as the Sterling sign to avoid ambiguity.
@
The at sign.
&
The ampersand.
*
The asterisk.
\
The backslash.
!
The exclamation mark.
$
The dollar sign.
%
The percent sign.
+
The plus sign.
/
The slash. Use to separate components of a pathname. Do not end pathnames with a slash. Do not use a slash before a single directory or filename unless it refers to the system root. Do not use the standalone slash to refer to the root directory; use root.
=
The equals sign.
?
The question mark.
^
The circumflex.
_
The underscore.
`
The grave accent.
|
The vertical bar or pipe symbol.
˜
The tilde.
—
The em-dash. Use to set off an appositive series from the rest of a sentence, to show an abrupt change in thought, and to set off material for emphasis. With the correct use of commas and parentheses, the em-dash is nearly redundant. Place spaces around the em-dash. For example, in the NAME section of a reference page: 
ls — list contents of directory
-
The en-dash. Use to indicate a range; for example, 00-61.
-
The minus sign. Use to indicate negative numbers. If the minus sign appears in a program display, use the <-> key.
...
Ellipses (horizontal or vertical) indicate the omission of information. In syntax, ellipses indicate an item that repeats. If an ellipsis is part of a screen object, include it in the name. For example, "The Open... menu item". When using an ellipsis in text, put a space before it and use three periods without spaces.

3.34 Spelling

Use American English spelling.

As an authority for spellings not specifically recommended in this guide, see Webster's New Collegiate Dictionary.1

3.35 System Items

Use the construction "the name item" when identifying an existing system item such as a command, function, parameter, and so on.

Reverse the construction when identifying a hypothetical system item or something the user must create. For example, "the file /etc/OLDpasswd".

Do not rely solely on typographic conventions to identify a system item.

Capitalize system item names as they appear on the system. All system items which are case-sensitive must be presented correctly.

Do not place quotation marks around system item names.

Do not hyphenate variable names used with commands.

Use system item names only as nouns or adjectives; do not use them as verbs.

Avoid starting sentences with the name of a system item or other name that begins with a lowercase letter. However, if you must begin a sentence with such a name, do not change the way it is capitalized.

The following system items should be semantically identified in source files: 







arguments
array names
bits
character classes
constant expressions
constants
data structure fields or members
data structure names
environment variables
error values
external variables
filenames
flags
functions
global variables

group names
headers
keyboard legends
macros
modifiers
operands
options
parameters
return values
signals
symbolic limits
tokens
user-defined structure names
utilities









3.36 Tables





Tables should be kept as simple as possible to enable conversion to
other formats and display on electronic media with display limitations
(such as when using the
man
command or viewing in HTML).


Introduce tables with a complete sentence, followed by a colon when the
sentence immediately precedes the table.
For example, "The ASCII codes for these functions are shown in
the following table: ...".
If you cannot avoid intervening text between the lead-in sentence and
the table, use a period at the end of both the lead-in sentence and the
intervening text.


Capitalize the first word in each table cell, regardless of whether the
cell contains a complete sentence (the only exception is when the word
is a literal term that must begin with a lowercase letter). Do not
capitalize any other word within a table cell, unless the word is a
proper noun, begins a sentence, or is a literal term that must be
capitalized.


Abbreviations can be used in table cells where space is limited, but
they must be defined. Notes can be used in tables to define
abbreviations. Use superscript numbers for notes.


When a common unit of measure applies to all entries in a column,
abbreviate it or spell it enclosed in parentheses after the column
head. When units of measure are not common to all entries in a column,
include the appropriate unit of measure with each entry in the column.


Align columns of decimal numbers on the decimal point where possible,
adding trailing zeros for consistency if necessary.


Use parallel construction in table text.


Table titles should use the conventions described in

3.38 Titles

.

3.37 Times



Write specific times using the abbreviations am (ante meridian,
morning) and pm (post meridian, afternoon).


If a time could be misinterpreted (for example, when discussing noon or
midnight), you can also add the 24-hour equivalent.
For example, "1:00 pm (13:00)".


Midnight is defined as 12:00 am (00:00).


Noon is defined as 12:00 pm (12:00).


Use the full name of time zones rather than their mnemonic codes.
For example, Central European Time, Eastern Standard Time.


Do not refer to the date of changes to or from Daylight Saving Time,
since this differs depending on the country.


Avoid using the words o'clock, noon, or midnight.

3.38 Titles




In general, make sure all titles are a reasonable length; ideally
less than 60 characters.


Titles are used to start elements (such as chapters and appendices)
sections, and subsections, and to label figures, tables, and examples.


Titles should summarize content.


Use titles levels 1, 2, 3, and unnumbered. Use of level 4 is
discouraged, and use of lower levels is disallowed.


Use initial capitals for the following words in titles:




Do not use initial capitals for the following words in titles:




Avoid using an article as the first word in a title.


Do not begin a title with a technical term that must begin with
a lowercase letter, such as the name of a function or utility.


When a section describes an action to be performed
(as in an example or procedure), you can begin the title with
a gerund (for example, "Copying a Directory"). Sections that are
more descriptive can use a noun phrase in the title
(for example, "Output Formats").

3.39 Trademarks




Trademarks are names, symbols, or other devices that identify products
that are legally restricted to the use of the owner or manufacturer.


Trademarks should be spelled out and capitalized correctly.


Trademarked terms may be marked at the first occurrence within text,
but not thereafter.


All documents for publication, whether in printed or online form,
should include a list of trademark acknowledgements in the front
matter.


Arrange trademark acknowledgements in alphabetical order.


Use trademarked names only as proper adjectives.
For example, the word "UNIX" must be followed by a noun, such as "system".
Trademarks can therefore never be possessive or pluralized.


Do not use a trademark as part of a hyphenated compound.


If an abbreviation or acronym is also a trademarked term, do not spell
it out.


It is the responsibility of the author of the document to provide
a list of all the trademarks mentioned, although these will also be
verified by The Open Group.


Note:

For all The Open Group trademarks, please adhere to the Trademark
Usage Guidelines (see

B. Resources

).




3.40 Warnings





Use a warning to draw the reader's attention to information which, if
ignored, can have a critical impact.
See also

3.28 Notes

and

3.6 Cautions

.







Footnotes


1. Refer to
www.merriam-webster.com.
 




return to top of page





Copyright © 2021 The Open Group, All Rights Reserved. 











<<< PreviousHome Next >>>