In message <email@example.com>
Elaine Firestone writes:
> Hi all! I'm posting this message to three different mailing lists, so
> please forgive me if you receive duplicates (or triplicates).
> I'm editing a document that has a lot of description of software programs,
> files, and the way the programs work. It includes such things as the names
> of programs, status codes, names of buttons to press (or click), names of
> widgets and gui's, etc. It's in chapter format where each chapter deals
> with different issues and has different sets of authors, and as a result,
> there is no consistency between the chapters as to how these items appear.
> Some have initial caps, some are all caps, some have single quotes around
> the items, etc. I have to achieve internal consistency throughout the
> Our standard for text is in Times Roman (TeX's version) in 10 pt type. All
> program names and files are set in a Courier font. Since this is the first
> time we've had a myriad of buttons described, I've typeset these in a small
> caps font.
> I guess my question is how to y'all handle these in typsetting? I still
> have names of widgets and gui's, and status codes to typeset, and I'm
> running out of nice looking ideas to use. Can anyone help me out?
You might want to look at the house styles of some of the
larger publishers of computer manuals. Many use a
Sans-Serif font for menu items and bold for dialog button names.
Some publishers seem to set button names in bold sans-serif.
Often a single letter in the name of a Menu command
is underlined to indicate a shortcut key.
IBM have published a number of design guides. I'm sure they
have one for manuals which might provide some useful ideas.
Listed below are some other conventions which seem to be
followed in many computer manuals from a major
software publishers and publishers of computer handbooks.
This is a completly unscientific survey, but I have gleaned
these looking at many computer manuals and think that
most frequent users of such manuals will recognize them.
In many cases more than one text attribute must be applied
to a single item.
Typeface or Symbol Meaning
Serif A standard serif typeface like Times Roman
is usually used for all text except
example programs, user input, screen output
Monospace A monospace typeface like Courier is
almost always used for example programs,
program fragments, and the names of user defined
functions and variables. This face also indicates
user input and screen output.
Sans Serif In many manuals a sans serif type like Helvetica
or Arial is used to indicate commands
which can be selected from a menu.
Where there is a shortcut key which
forms part of the menu command
individual letters may be underlined
e.g. File, Save, Exit.
~ ~ ~
Sans Serif is also sometimes used for names
of command buttons (which may also be in
Upper Case In MS DOS manuals uppercase letters often represent
DOS commands - however you must not use this
convention for systems like Unix which have
case sensitive filenames and commands.
Some computer programming languages like C, C++
use case sensitive commands, keywords
and variable and type identifiers - so
the case of sample code and commands must not be
altered. Other programming languages like Pascal
and BASIC are not case sensitive so a
consistent system of seperating user defined
variables, functions and subroutines
from standard keywords by case can be used.
Small caps Small capital letters almost always denote names of
keys on the keyboard. A plus sign (+) indicates a
combination of keys. For example, SHIFT+F5 (in
small caps) tells the user to hold down the SHIFT
key while pressing the F5 key. Ocassionaly a "keycaps"
font is used for this purpose.
Boldface Boldface letters in both text and code samples usually
indicate standard features of a programming language like
keywords, operators, standard library functions and
compiler options. In manuals for applications often
used for names of command buttons in descriptions:
i.e. "Click Add" or "Click the Add Button"
(where only the word Add is boldface)
Italics Words in italics indicate placeholders for
information which the user must supply, such as
a filename. Italics are often also used for
emphasis in the explanitory text.
Acronyms The first time an acronym appears it
should be spelled out: American National
Standards Institute (ANSI).
Ellipsis ... A horizontal ellipsis following an item
indicates that more items having the same
form may follow.
A vertical ellipsis indicates that part
of an example program has been intentionally
Quotes " " The first time a new term is defined it is
usually enclosed in quotation marks. In programming
language manuals some knowledge of programming
is generally assumed - so common terms like
memory or branch may not be defined.
 Square brackets (often nested) enclose
optional paramaters in commands. Where
these options are also in italic they are
not literal and must be supplied by the
user (e.g. filename).
<Round bullet> To highlight items in a list.
<Square bullet> This symbol often indicates the begining of a
procedure the user must follow. The text
that follows this symbol describes a set of
general steps that the user should take for
performing a specified kind of task.
<Arrowhead bullet> This symbol is used to indicate a specific
action the user should take, such as a
(single) step in an example.
Keyboard symbol This symbol often precedes text describing the
steps a user should take to accomplish
a specific task by using the keyboard.
Mouse symbol This symbol often precedes text describing the
steps a user should take to accomplish
a specific task by using the mouse.
Bitmap of Icon A bitmap of an icon often precedes text
describing tasks which can be accomplished
by pressing the given icon or command button.
P.S. The most important thing in any computer manual is a very
good index. If the documentation is in several volumes
the first or last volume should contain an index which
Christopher J Fynn <[log in to unmask]>
4 Chester Court
84 Salusbury Rd
London NW6 6PA
United Kingdom Tel: +44 (0) 171 625 8925