5. Presentation
This chapter describes overall preferred presentation style. It is designed as an aid only and is not an exhaustive list of instructions. The Open Group document templates and production systems dictate most presentation elements.
If more information is required, you should consult The Open Group rather than inventing individual presentation styles.
5.1 Contents
The Contents list should include entries to the third level of the document hierarchy, a page number for each entry, and leader strings connecting entries with page numbers.
There may be a list of Figures showing the number and title of each entry, a page number for each entry, and leader strings connecting entries with page numbers.
There may be a list of Tables showing the number and title of each entry, a page number for each entry, and leader strings connecting entries with page numbers.
5.2 Cross-References
Initial capitals are used for cross-references.
References within a document should consist of the type of item referenced (i.e., chapter, appendix, section, figure, table, or example) and its number.
In White Papers where there is no section numbering, an auto-generated page number may be added to the cross-reference.
5.3 Drafts
Drafts may have line numbers and change bars (if required).
Drafts should be clearly identified as such (e.g., using a watermark).
5.4 Examples
Most examples appear in constant width font. User input may be identified using Bold font. Variable information may be identified using Italic font.
5.5 External References
Use initial capitals and Italic font for the titles of third-party referenced documents.
5.6 Figures
Figures should be in line with the text and centered, and should not be surrounded by a frame or box.
Use the same typeface as the text, unless typographic and keying conventions apply.
Captions for figures must begin with the text "Figure" and must be placed below the figure.
5.7 Fonts
The Open Group technical documentation is produced in Times New Roman, font size 11 (on 13) for body text.
Punctuation is presented in the base font, unless it is part of
syntax. See also
Most examples appear in constant width font.
5.8 Footnotes
Use superscript numbers to refer to a footnote in text. Place the number after the key word in the text or table, and use the same number with the footnote itself.
An asterisk (*), dagger (†), or other symbol may be used where the same footnote applies to several points.
Place footnotes at the bottom of the page.
5.9 Glossary
Glossaries are typically formatted as a definition (or variable) list, with a short indent. Use a line break between the glossary term and the definition text if the term is too long.
A series of unnumbered headings may also be used to structure the glossary.
5.10 Headings
Use initial capitals for the following words:
Chapter, Appendix, Section, Version, Release, Guideline, Table, Figure
The left margin should be sufficient for all heading (section) numbers.
The fonts and point sizes of the various heading levels are determined by the processing tools in use.
5.11 Index
The Index includes a list of indexed terms, with a page number for each entry, and leader strings connecting entries with page numbers. Main index entries should make the page number appear in Bold font.
5.12 Lists
For unnumbered lists, use bullets for a first-level list, and em-dashes (—) for a second-level list.
For numbered lists, use Arabic numbers (1. 2. 3.) for a first-level list, and Letters (a. b. c.) for a second-level list.
5.13 Notes
Notes are highlighted by placing the text "Note:" in Bold font and indenting the note text itself.
In drafts, editor's notes may be identified with shading and the text "Notes to Reviewers".
5.14 Page Layout
Most hard-copy technical documents published by The Open Group use US Letter (8.5 x 11 inches), although the print area should accommodate standard A4.
All document elements begin on a right-hand, odd-numbered page, with the exception of the front matter sections which are run on.
The title page should include the series title, document title, and The Open Group logo.
Page numbering is placed at the outer edge of the footer. Front matter is typically numbered using Roman numerals; the document body is typically numbered using Arabic numerals. There are exceptions to this convention (e.g., in White Papers), and these are defined in the respective document templates.
Page headers and footers are dictated by the document template in use or by the production tool.
5.15 Pagination
Some required space should be built into each section or subsection heading, so that they cannot start near the bottom of the page.
To avoid widows and orphans, there should be at least two lines on each page.
Second-level headings may start on a new page, except where the effect is to leave large amounts of white space that appears unnecessary. If the chapter is short (say, 10 pages or less in run-on form), all sections may be run on.
5.16 Reference Pages
Each reference page starts on a new page.
Reference page headings are displayed on the outer top edge of the page, as follows:
- For functions, in Bold font with parentheses; for example, function()
- For COBOL functions, in Bold font; for example, function
- For headers, in Bold font with angle brackets; for example, <header.h>
- For macros, in Bold font; for example, macro
- For data types, in Bold font; for example, data_type
- For X Windows widgets, in Bold font; for example, widget
For full guidance please refer to the PDF edition of this document.
5.18 Tables
Tables should be centered and boxed.
Use the same typeface as the text, unless typographic and keying conventions apply.
Column headings should be centered and appear in Bold font. There should be a horizontal rule underneath them. Repeat the column headings when a table is continued onto one or more pages.
Use vertical rules to separate all of the columns.
Text in table cells should be flush left. However, if entries are three (3) characters or less, they may be centered. Also, numerics may be aligned using the decimal point.
Use em-dashes (—) in cells that do not have information in them.
Here is a typical table:
Column 1 |
Column 2 |
Column 3 |
Column 4 |
|---|---|---|---|
1.0 | 1.5 | 2.0 | 2.5 |
2.0 | 2.5 | 3.0 | 3.5 |
3.0 | 4.0 | 5.0 | 6.0 |
Captions for tables must begin with the text "Table" and should be placed above the table.
5.19 Typographical Conventions
The following typographical conventions are preferred:
- Bold font is used in text for options to commands, filenames, keywords, type names, and data structures and their members
-
Italic
strings are used for emphasis, to identify the first instance of a
word requiring definition, or for foreign phrases
Italics in text also denote:
- Command operands, command option-arguments, or variable names; for example, substitutable argument prototypes
- Environment variables, which are also shown in capitals
- Utility names
- Macro names
- External variables, such as errno
-
Functions
These are shown as follows: name(); names without parentheses are C external variables, C function family names, utility names, command operands, or command option-arguments.
- Normal font is used for the names of constants and literals
- The notation <file.h> indicates a header
- Names surrounded by braces, for example, {ARG_MAX}, represent symbolic limits or configuration values which may be declared in appropriate headers by means of the C #define construct
- The notation [EABCD] is used to identify an error value EABCD
-
Syntax, code examples, and user input in interactive examples are shown
in fixed width font
Brackets shown in this font, [], are part of the syntax and do not indicate optional items. In syntax the | symbol is used to separate alternatives, and ellipses (...) are used to show that additional arguments are optional.
- Bold fixed width font can be used to identify brackets that surround optional items in syntax, [], and to identify system output in interactive examples
- Variables within syntax statements may be shown in Italic fixed width font
-
Ranges of values are indicated with parentheses or brackets as follows:
- (a,b) means the range of all values from a to b, including neither a nor b
- [a,b] means the range of all values from a to b, including a and b
- [a,b) means the range of all values from a to b, including a, but not b
- (a,b] means the range of all values from a to b, including b, but not a
- Arial is used for the Pseudo Interface Definition Language (PIDL)
- Arial Bold is used for the Interface Definition Language (IDL)
5.20 Underlining
Underling is not used, except where it is required to conform with a referenced document, for example:
- COBOL syntax
- An extract reproduced from another document where underlining is used
return to top of page