# Icon Documentation Guide

Gregg M. Townsend
Department of Computer Science
The University of Arizona

www.cs.arizona.edu/icon/v941/docguide.htm
Last updated January 30, 2002

## Introduction

Icon is distributed with a small set of documentation pages:

- This documentation guide
- Release notes
- File organization
- Build instructions (for source releases)
- Installation instructions (for binary releases)
- Frequently asked questions about Icon

This guide provides an overview of additional available information. Documents designated with IPD numbers are Icon Project Documents found at the Icon web site, www.cs.arizona.edu/icon.

## Basic Documentation

The command-line interface to Icon is described by man pages. The new `icon` command executes a program from a single source file and supports script usage. The more general `icont` command, modeled after cc, supports multiple files, separate compilation, and other features.

The Icon language is defined by

> The Icon Programming Language, Third Edition
> Ralph E. Griswold and Madge T. Griswold
> Peer-to-Peer Communications, 1996
> ISBN 1-57398-001-3

Some introductory material can be found on the web:

- Ralph Griswold's overview: www.cs.arizona.edu/icon/docs/ipd266.htm
- Dave Hanson's introduction: www.cs.arizona.edu/icon/intro.htm
- John Shipman's tutorial: www.nmt.edu/tcc/help/lang/icon

The Icon Programming Language Handbook, by Thomas W. Christopher, is available on the web at www.toolsofcomputing.com/IconHandbook.

## Graphics

Icon's graphics facilities are defined by

> Graphics Programming in Icon
> Ralph E. Griswold, Clinton L. Jeffery, and Gregg M. Townsend
> Peer-to-Peer Communications, 1998
> ISBN 1-57398-009-9

Two older reports present an overview of Icon's graphics:

- IPD281, Graphics facilities for Icon, www.cs.arizona.edu/icon/docs/ipd281.htm
- IPD284, Visual interfaces for Icon programs, www.cs.arizona.edu/icon/docs/ipd284.htm

## Recent feature additions

A few minor features have been added since the publication of the Icon books:

- Scriptable source files
- Path searching improvements
- Reading directory contents
- Reading foreign text files

These features are more fully described in the release notes.

## Program Library

Program library documentation is contained within the source code. Extracted documentation is available at www.cs.arizona.edu/icon/v941/library/ipl.htm.

## Icon Internals

Icon's internals are detailed in

> The Implementation of the Icon Programming Language
> Ralph E. Griswold and Madge T. Griswold
> Princeton University Press, 1986, out of print
> ISBN 0-691-08431-9

Although considerable changes have occurred since Version 6, described in the book, the basic structure is the same. Two technical reports describe subsequent changes:

- IPD112, Supplementary Information for Version 8, http://www.cs.arizona.edu/icon/docs/ipd112.htm
- IPD239, Supplementary Information for Version 9, http://www.cs.arizona.edu/icon/docs/ipd239.htm

Icon's run-time implementation language is described in IPD261, www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf (PDF).

The construction of loadable C functions is described in the Dynamic Loading section of IPD240, www.cs.arizona.edu/icon/docs/ipd240.htm. Also see the examples in the `cfuncs` section of the library, which use a simpler set of interface macros.

Configuration options for new ports are described in IPD238, www.cs.arizona.edu/icon/docs/ipd238.htm, although the details of the porting process have now changed somewhat.

## Technical Reports

The Icon web site provides a large number of technical reports, including "Icon Project Documents" designated by IPD numbers. The index is found at www.cs.arizona.edu/icon/docs/docs.htm.

Many of these reports are historical and describe past research experiments. Those cited above are among the most current, although they may not be completely correct with respect to Version 9.4.

## Other Sources

Other sources of documentation can be found in the Icon FAQ and on the Icon web site, www.cs.arizona.edu/icon.