.png)
Appendix C. Typographic Conventions
Typographic conventions help a reader distinguish special uses of fonts. This appendix shows elements used in typical technical documentation for which typographic conventions are established.
To provide consistency in typographic cues for readers, use the following conventions in your document.
Note
The examples in the following table show typographic conventions only. These examples are not meant to dictate other aspects of formatting technical information such as how code should be indented or where braces should be placed in code examples.
Table C-1. Typographic Conventions
| Text[1] | Specification[2] | Examples |
|---|---|---|
| Alert names | Lowercase, regular text font | critical alert, major alert, minor alert |
| Arguments | Monospace font | -f, Slapi_PBlock |
| Arrow keys | Lowercase, regular text font | Press the up arrow, then the left arrow. |
| ASIC names | Lowercase for name, regular text font | address multiplexer ASIC |
| reset, interrupt, scan, and clock (RISC) ASIC | ||
| data arbiter ASIC | ||
| Board names, when referring to a specific model of board | Initial capitals, regular text font | GT SBus Adapter Board |
| 600MP System Board | ||
| 600MP Expansion Memory Board | ||
| Board types, when referring to a generic type of board | Lowercase, regular text font | auxiliary video board, system board, power distribution board |
| Book titles | Italic, regular text font | See the PlirgPak Reference Guide. |
| Bus names | All capitals for the bus name, but not for the word “bus”; regular text font | AFX bus, PROM bus, PCI bus |
| Bus types | Lowercase, regular text font | address bus, host bus |
| Button names | Initial capitals for the button name, but not for the word “button”; regular text font | Power button |
| Card names | Initial capitals or all capitals for the card name, but not for the word “card”; regular text font | Control card, TNT card |
| Card types | Lowercase, regular text font | optics card, smart card, graphics card |
| CD titles | Initial capitals, regular text font | PlirgSoft Installation CD |
| Chapter titles or section headings | Initial capitals in quotation marks, regular text font | See Chapter 1, “Getting Started.” |
| Classes | Monospace font | Morf, AncestorEvent, DoubleBuffer |
| Code examples | Monospace font |
struct inode {
struct inode *i_chain[2];
struct vnode i_vnode;
struct vnode *i_devvp;u_short i_flag;
};
|
| Command field names | Monospace font | Look at the Flags field in the output. |
| Command names or options | Monospace font | Type ls -a to list all files. |
| Constants | Monospace font | NULL, NIS_CBError |
| Daemon names | Monospace font | cron, lpsched |
| Database files | Monospace font | bootparams.dir, hosts.byaddr.dir |
| Database names | Initial capitals, regular text font | Clientbase |
| Data types | Monospace font | short, boolean, kcondvar_t |
| Directory names or path names | Monospace font | Check the book directory in /docs/work. |
| DOS commands | All capitals, monospace font | RENAME, FDISK |
| Driver names | Monospace font | asy, ata, dnet |
| Email addresses | Monospace font | Send questions to support@plirgware.com. |
| Emphasized words or new terms[3] | Italic, regular text font | You must delete your old files. |
| A cache is a copy that is stored locally. | ||
| Environment variables | All capitals, monospace font | PATH, PROMPT, TMPDIR, TERM |
| Equations | Italic, regular text font for replaceable items, and monospace font for constants and mathematical operators | availability = update /(uptime + downtime) × 100% |
| Error messages, when you know the exact wording | Monospace font |
stty: No such device or address. |
| Event names | Monospace font for the event name, but lowercase, regular text font for the word “event” |
snmp-mibII.system event |
| Exceptions | Monospace font | IllegalStateException, NullPointerException |
| Field names in a programming context | Monospace font | NULL_ATTRIBUTE_VALUE, au_sample_rate |
| Field names from a graphical user interface in text | No colon or ellipsis points, regular text font | [Field name appears as Tag Type: __________] |
| Type the name of the tag in the Tag Type field. | ||
| File format names | Monospace font | mif, mpeg, java |
| File names, generic | Regular text font | When you use makefiles, additional swap space might be required. |
| File names, specific | Monospace font | Delete all .bak and core files. |
| File permissions | Monospace font | To make the file readable and writable by the file owner and readable by everyone else, change the permissions to u+x. |
| File system names | Monospace font | /usr, /opt, /var |
| File system types in text | All capitals, regular text font | UFS, NFS, HSFS |
| Flags | Monospace font | The flag THR_NEW_LWP is passed to the function thr_create() to create LWP. |
| Functions, function calls, and interfaces | Monospace font | abs(), ctermid() |
| Graphical user interface elements | Regular text font | Choose Save from the File menu. |
| Click OK. | ||
| Headers | Monospace font | exception, exception.h |
| HTML tags | Monospace font | <h1>, <body> |
| Interface names in text, when referring to a specific type of interface | Initial capitals for the interface name, but most often not for the word “interface”; regular text font | Ethernet interface, InterDomain Network interface, Windows interface, SCSI interface |
| Interfaces (in a programming context) | Monospace font | Runnable, la_objfilter(), PathIterator |
| Interface types, when referring to a broad category of interface | Lowercase, regular text font | user interface, network interface, serial interface, command-line interface |
| IP addresses | Monospace font | 10.255.255.255 |
| Key names[4] | Initial capitals, regular text font | Press the Control key. |
| Keywords in files (see also “reserved words”) | Monospace font | netmask |
| LED names | Initial capitals for the LED name, but all capitals for the word “LED”; regular text font | Warning LED |
| Machine names | Monospace font | newstop, dickens |
| Macros | All capitals, monospace font | MAX(), MIN() |
| Man page names | Monospace font for the man page name only, regular text font for the parentheses and section name | boot (1M), connect(3SOCKET) |
| Menu options, menu names | Initial capitals, no colon or ellipsis points, regular text font |
Choose Go To from the Page menu.
[Option appears as Insert Markup on screen.] Choose Insert Markup from the Markup menu. |
| Method and constructor names[5] | Monospace font | add, add(Object), add(int, Object) |
| Mode names | Initial capitals for the mode name, but not for the word “mode”; regular text font | Config mode, Edit mode, Run mode |
| Module names | Initial capitals for the module name, but not for the word “module”; regular text font | Wireless Connection Wizard module, Mod module |
| Module types, when referring to a generic type of module | Lowercase, regular text font | locking module, software module, stacking module, web module |
| Node names | Initial capitals for the node name, but not for the word “node”; regular text font | Control node, Packet Data Serving node |
| Node types, when referring to a generic type of node | Lowercase, regular text font | junction node, interface node, application server node |
| Operators and operations | Monospace font | &&, !=, instanceof |
| Package names, installation | Monospace font | PLRGman, PLRGlib |
| Package names, Java | Monospace font | java.io, java.security.cert |
| Parameters | Monospace font | foo(x, y) (x and y are parameters for foo()) |
| Partition names, the PC disk partition fdisk | Monospace font | Reformat the PLIRGPAK partition. |
| Patch IDs (referred to as “update IDs” by some groups) | Regular text font | 111879-01 |
| Permission names | Lowercase, regular text font | execute permission, read permission, write permission, read/write permissions |
| Port names in text | All capitals, regular text font | COM1, LPT3 |
| Print services | Regular text font | LP print services |
| Printer names | Monospace font | Assign catalpa as the printer name. |
| Prompts | Monospace font, unless from a GUI | %, $, # |
system123% system123$ system123# > ok |
||
| Property names | Monospace font | Specify the nohangup property. |
| Protocol names | Initial capitals including the word “Protocol”; regular text font | File Transfer Protocol |
| README files, generic | All capitals, regular text font | See the README file in /tmp. |
| README files, specific file name | Monospace font | See the README.html file. |
| Release media (CD, diskette, and DVD titles) | Initial capitals, regular text font | Insert the first PlirgSoft 1.1 Update CD. |
| Reserved words, or keywords (see also “keywords in files”) | Monospace font | if, else, int, float |
| Return values | Monospace font | The function open_max() returns TRUE. |
| A value of -1 is returned. | ||
| Root symbol (slash) | Monospace font | Go to the / (root) directory. |
| Routines | Monospace font | The time() routine computes time. |
| Run levels | Monospace font | Type init S to change to run level S. |
| Settings in windows | Initial capitals, regular text font | Check the Pair Kern setting. |
| Script names | Monospace font | check, rc, sbin/rc3 |
| Signal names | Initial capitals for the signal name, but not for the word “signal”; regular text font | Clear To Send signal |
| Slice names | Monospace font | s0, /opt |
| Slot names | Initial capitals for the name or letter of the slot, but not for the word “slot”; regular text font | slot 0, slot A |
| Software elements that need to be distinguished from regular text | Monospace font | file realm, enabled state |
| Structures[6] | Monospace font | proc, sockaddr |
| Switch names and switch settings | Initial capitals for the switch name, but not for the word “switch”; regular text font | Power switch |
| System calls or subroutines | Monospace font | read(), open(), _lwp_info() |
| System error codes | All capitals, monospace font | EINVAL, ENOENT, setErr() |
| System names | Monospace font | Move the file to the nesfa1 system. |
| System variables | Monospace font | The system variable in set maxusers=40 is maxusers. |
| Test names | Initial capitals for the test name, but not for the word “test”; regular text font | Alarm Card test |
| Tool or utility names | Case-sensitive, monospace font if the command name is used; initial capitals, regular text font if the formal name (if any) is used | grep, sed, vi, appletviewer Formal names: Nametool, Mail Tool, Bugfix |
| URLs or domain names | Monospace font | http://www.plirg.com example.com, my.site.com |
| User input in running text or steps | Monospace font | Use ls -a to list all files. |
| 1. Type teh in the Find text field. | ||
| Note: Some authoring tools might not allow regular-weight alternate font material within a bold step. | ||
| User input contrasted with computer output or with a prompt in code examples | Bold, monospace font |
system123% su Password: # tar -xvf filename |
| User names and IDs | Monospace font | User davemc has a user ID of 1001. User root destroyed the system. |
| Variables, command-line placeholders | Italic, regular text font | Name the file filename TOC.doc. |
| Go to /hostname/docs/work. | ||
| % chmod 600 filename | ||
| Web site names | Monospace font | For more details, go to http://www.plirg.com. |
| Window button names | Initial capitals, regular text font | Click Apply to save your changes. |
| Window elements | Regular text font | In the Alarms pane, click Remove. |
[1] A plural term is usually generic and in those cases should not appear in monospace font, for example, makefiles.
[2] The point size of the font for monospace elements should match the point size of the text within which they appear, including a heading, paragraph, table, or caption.
[3] In some single-source authoring environments, emphasized text is shown in italic in print but displayed in bold online.
[4] See “Key Name Conventions” on page 85.
[5] Omit parentheses for the general form of methods and constructors. When a method or constructor has multiple forms and you mean to refer to a specific form, use parentheses and argument types.
[6] The file index structures inode, vnode, and rnode are not literals and use the default body font.