.so tmac.tr
.DA "August 16, 1984"
.TR 84-12
.Gr
.TL
The Icon Program Library; Version 5.9
.AU
Compiled by Ralph E. Griswold
.AE
.tr *\(**
.LP
.af PN i
.LP
.ce 1
\f3Preface\fR
.sp
.PP
The Icon program library consists of Icon programs, procedures, C
functions, and support material.
The library is distributed as part of the Version 5.9 Icon system [1-4].
.PP
The format of the library mimics the \*U Programmer's Manual [5].
.Un
Section 1 contains application programs. Section 2 contains
collections of Icon procedures.
C functions, which can be used to augment the repertoire of built-in Icon functions,
are contained in Section 3.
Sections 4 and 5 are reserved for future use. Section 6 contains
demonstration programs and games. Section 7 contains
miscellaneous material, while Icon program library maintenance information
is included in Section 8. See the table of contents for details.
.NH 1
Using the Library
.PP
See \fIi-hier(7)\fR for the structure of the Icon system.
The program material in the library is
divided into three components.
Two of the components consists of Icon source code. The third consists
of C source code.
The prefix \fIi-\fR is used to identif programs in the library that are
related to Icon program development.
Some procedures in the Icon program library depend on the inclusion of
optional extensions to Icon [4] or on particular UNIX environments. Such
dependencies are note in the \fIREQUIREMENTS\fR sections of the manual
pages.
.SH
Application Programs and Games
.PP
The programs in Sections 1 and 6 are on a par with programs in the
corresponding sections of the UNIX manual.
The fact that the programs
in the Icon library are written in Icon is irrelevant to the user;
Icon application programs and games can be moved to a local
library without modification.
.SH
Procedures
.PP
The procedures in Section 2 can be linked into an Icon program in
two ways: by specifying them with their \*M.u1\fR suffix on
the \fIicont(1)\fR command line when the program is translated [6],
or by including an appropriate link directive in the program itself [3].
See the library manual page for \fIi-hier(7)\fR for the path that is needed.
.PP
Some procedures have global symbols in addition to the procedures names
themselves. There is, therefore, the possibility of collisions between
names in user programs and names in the library procedures.
.SH
C Functions
.PP
C functions can be added to the built-in repertoire of Icon by building
a personalized interpreter [7]. Alternatively, they can be incorporated
into Icon directly [8].
Some of the C functions require the loading of libraries. Check the
library manual pages on specific functions.
.NH
The UNIX Manual Versus the Library Manual
.PP
Library manual pages, as included in this report, are slightly
different from UNIX manual pages in their head and foot formats.
See \fIlman(8)\fR for the production of such manual pages.
Library manual pages with head and foot formats in the style of
the UNIX manual can be obtained as described in \fIuman(8)\fR.
.PP
Reference to manual pages that are not in the library, such as \fIed(1)\fR,
apply to the UNIX manual.
.NH
Bug Reports and Submissions of New Material
.PP
Bug reports
should be mailed to
.DS
.ft R
Icon Project
Department of Computer Science
The University of Arizona
Tucson, Arizona   85721
U.S.A.
.DE
or send electronic mail to
.Nt
.PP
New material for the library is welcome, although the final decision on inclusion
in the Icon library is at the discretion of the Icon Project. Submissions should
be sent in machine-readable form,
including  documentation, either on \fItar\fR-format magnetic
tape or via electronic mail.
.SH
Acknowledgements
.PP
Several persons have contributed material to the Icon program
library, as noted by the attributions on the manual pages.
In order to make program material easier to read, contributions
have been reformatted to provide a degree of uniformity. Program
layout therefore does not necessarily reflect the author's preference.
.PP
In addition to contributing material to the library, Tom Hicks, Bill
Mitchell, and Steve Wampler have made numerous helpful suggestions
about the library and its documentation.
.SH
References
.IP 1.
Griswold, Ralph E. and Madge T. Griswold. \fIThe Icon Programming
Language\fR. Prentice-Hall, Inc., Englewood Cliffs, New Jersey.
1983.
.IP 2.
Griswold, Ralph E., Robert K. McConeghy, and William H. Mitchell.
\fIVersion 5.9 of Icon\fR.
Technical report, Department of Computer Science, The University of
Arizona. August 1984.
.IP 3.
Griswold, Ralph E., Robert K. McConeghy, and William H. Mitchell.
\fIExtensions to Version 5 of the Icon Programming Language\fR.
Technical Report TR 84-10a, Department of Computer Science, The
University of Arizona. August 1984.
.IP 4.
Griswold, Ralph E. and William H. Mitchell.
\fIInstallation and Maintenance Guide for Version 5.9 of Icon\fR.
Technical Report TR 84-13, Department of Computer Science, The
University of Arizona, Tucson, Arizona. August 1984.
.IP 5.
\fIUNIX Programmer's Manual; Seventh Edition, Volume 1\fR. Bell Laboratories,
Murray Hill, New Jersey. 1979.
.IP 6.
Griswold, Ralph E. and William H. Mitchell. \fIICONT(1)\fR,
manual page for \fIUNIX Programmer's Manual\fR, Department of
Computer Science, The University of Arizona. August 1984.
.IP 7.
Griswold, Ralph E., Robert K. McConeghy, and William H. Mitchell.
\fIPersonalized Interpreters for Icon\fR. Technical Report TR 84-14,
Department of Computer Science, The University of Arizona. August 1984.
.IP 8.
Griswold, Ralph E., Robert K. McConeghy, and William H. Mitchell.
\fIA Tour Through the C Implementation of Icon; Version 5.9\fR.
Technical Report TR 84-11, Department of Computer Science,
The University of Arizona. August 1984.