diff options
| author | Igor Pashev <pashev.igor@gmail.com> | 2013-01-27 23:51:56 +0000 |
|---|---|---|
| committer | Igor Pashev <pashev.igor@gmail.com> | 2013-01-27 23:51:56 +0000 |
| commit | 6ab0c0f5bf14ed9c15370407b9ee7e0b4b089ae1 (patch) | |
| tree | 926065cf45450116098db664e3c61dced9e1f21a /doc | |
| download | icon-6ab0c0f5bf14ed9c15370407b9ee7e0b4b089ae1.tar.gz | |
Initial upstream version 9.4.3upstream/9.4.3
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/blubordr.gif | bin | 0 -> 2174 bytes | |||
| -rw-r--r-- | doc/build.htm | 150 | ||||
| -rw-r--r-- | doc/clnroff.sed | 8 | ||||
| -rw-r--r-- | doc/cube128.gif | bin | 0 -> 6718 bytes | |||
| -rw-r--r-- | doc/cygwin.htm | 133 | ||||
| -rw-r--r-- | doc/docguide.htm | 213 | ||||
| -rw-r--r-- | doc/faq.htm | 443 | ||||
| -rw-r--r-- | doc/faq.txt | 337 | ||||
| -rw-r--r-- | doc/files.htm | 182 | ||||
| -rw-r--r-- | doc/gb80.jpg | bin | 0 -> 2318 bytes | |||
| -rw-r--r-- | doc/ib80.jpg | bin | 0 -> 922 bytes | |||
| -rw-r--r-- | doc/icon.txt | 50 | ||||
| -rw-r--r-- | doc/icont.txt | 126 | ||||
| -rw-r--r-- | doc/index.htm | 29 | ||||
| -rw-r--r-- | doc/install.htm | 65 | ||||
| -rw-r--r-- | doc/istyle.css | 26 | ||||
| -rw-r--r-- | doc/lb80.jpg | bin | 0 -> 2806 bytes | |||
| -rw-r--r-- | doc/macintosh.htm | 80 | ||||
| -rw-r--r-- | doc/port.htm | 235 | ||||
| -rw-r--r-- | doc/relnotes.htm | 215 | ||||
| -rw-r--r-- | doc/shortcut.gif | bin | 0 -> 71 bytes | |||
| -rw-r--r-- | doc/wwwcube.gif | bin | 0 -> 6097 bytes |
22 files changed, 2292 insertions, 0 deletions
diff --git a/doc/blubordr.gif b/doc/blubordr.gif Binary files differnew file mode 100644 index 0000000..12f51c8 --- /dev/null +++ b/doc/blubordr.gif diff --git a/doc/build.htm b/doc/build.htm new file mode 100644 index 0000000..d494b94 --- /dev/null +++ b/doc/build.htm @@ -0,0 +1,150 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Building Version 9.4 of Icon from Source</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1>Building Version 9.4 of Icon from Source</H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/build.htm +<BR> Last updated November 8, 2005 </SMALL> +<!-- $Id: build.htm,v 1.26 2005/11/08 23:24:34 gmt Exp $ --> + +<H2> Introduction </H2> + +<P> These instructions explain how to build and install the source code of +<A HREF=relnotes.htm>Version 9.4 of Icon</A> under Unix. +For instructions on installing a binary release, see +<A HREF=install.htm>Installing Icon Binaries</A>. + +<P> These instructions assume that you have unpacked the Icon +distribution file into a directory. +All commands are issued in that directory. + +<H2> Configuring </H2> + +<P> The Icon source package contains configurations for a variety of +Unix platforms. +Type <CODE>make Configure</CODE> to see the list of known configurations. +A status report for any system can be viewed by entering +<BLOCKQUOTE> + <CODE>make Status name=</CODE><VAR>name</VAR> +</BLOCKQUOTE> +Choose the configuration name that matches your system's +operating system, and be sure to note +any special considerations given in its status report. + +<P><SMALL> (If your system is not among those listed, you will need to +port the code. +This is usually a fairly simple matter that involves copying an existing +configuration and editing it to match the target system. +See <A HREF=port.htm>Porting Icon</A>. +</SMALL> + +<P> Most Unix systems include the X11 window system; type +<BLOCKQUOTE> + <CODE>make X-Configure name=</CODE><VAR>name</VAR> +</BLOCKQUOTE> +to configure Icon with graphics. +If your computer does not have the X window system, type +<BLOCKQUOTE> + <CODE>make Configure name=</CODE><VAR>name</VAR> +</BLOCKQUOTE> +to configure Icon without graphics. + +<P> Installation using any of the supplied configurations <EM>should</EM> +be routine, but some of those were contributed for systems we cannot test, +and it is possible that some minor tweaking may be required. +If so, or if you develop a new configuration, we'd like to hear about it +by e-mail to +<A HREF="mailto:icon-project@cs.arizona.edu">icon-project@cs.arizona.edu</A>. + +<H2> Building </H2> + +<P> After Configuring, type <CODE>make</CODE> to build the Icon system. +This single step now builds: +<UL> + <LI> The Icon translator and interpreter + <LI> Program library procedures + <LI> VIB and other graphics utilities, if graphics are enabled +</UL> + +<P> There may be a few warnings on some platforms, but there should be +no fatal errors. +If there are problems, +fix them in the <CODE>config/</CODE><VAR>platform</VAR> +directory and repeat the configuration step. + +<H2> Testing </H2> + +<P> To verify a successful build, type <CODE>make Test</CODE>. +This command compiles and executes a series of Icon programs, +comparing their outputs with a set of standard results. +A normal run concludes with the phrase "All tests passed." + +<P> A successful graphics build can be confirmed by executing +<CODE>bin/colrbook</CODE>, the color book utility, with no arguments. +It should display a spectrum of colors along the left and a set +of recessed panes to the right. +Click anywhere on the spectrum to fill colors in the panes. +Click <CODE>QUIT</CODE> (in the upper left corner) to exit. + +<H2> Installing </H2> + +<P> Icon can be run directly from the location in which it was built. +To do this, simply add the <CODE>bin</CODE> directory to your shell's +search path. +See the man pages for <A HREF=icon.txt><CODE>icon</CODE></A> +and <A HREF=icont.txt><CODE>icont</CODE></A> +for instructions on building and running Icon programs. + +<P> If you wish to install the binaries elsewhere, +choose a location for a directory dedicated to Icon — +for example, <CODE>/opt/icon</CODE> or <CODE>/usr/local/icon</CODE>. +If you are replacing an existing directory, delete the old one first. +Enter +<BLOCKQUOTE> + <CODE>make Install dest=</CODE><VAR>directory</VAR> +</BLOCKQUOTE> +to create <VAR>directory</VAR> and install Icon in its +<CODE>bin</CODE>, <CODE>lib</CODE>, +<CODE>doc</CODE>, and <CODE>man</CODE> subdirectories. +All files are created using the default permissions +<CITE>(umask)</CITE> of the current user. + +<P> You can make symbolic links from other locations +to programs in the Icon <CODE>bin</CODE> directory. +For example, you can link +<CODE>/usr/local/bin/icon</CODE> to <CODE>/opt/icon/bin/icon</CODE>. +If you do this, link all of <CODE>icon</CODE>, <CODE>icont</CODE>, +<CODE>iconx</CODE>, and (if present) <CODE>vib</CODE>. + +<P> If you'd like to bundle up a gzipped tar file of the binaries +created by the build process, enter <CODE>make Package</CODE>. +Such a package can be used to install binaries on other +systems of the same architecture. + +<H2> Cleaning Up </H2> + +<P> Type <CODE>make Clean</CODE> to remove intermediate files created +during the build process. This command preserves the contents of the +<CODE>bin</CODE> and <CODE>lib</CODE> directories, so the built system +remains functional. + +<P> To restore everything to its original state, type <CODE>make Pure</CODE>. +This removes all the configuration information and newly built files. + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/clnroff.sed b/doc/clnroff.sed new file mode 100644 index 0000000..131f672 --- /dev/null +++ b/doc/clnroff.sed @@ -0,0 +1,8 @@ +# sed(1) directives for cleaning up nroff(1) formatted man page + +/^User Commands/d +/^ICONT/d +/^University/d +s/.//g +s/’/'/g + diff --git a/doc/cube128.gif b/doc/cube128.gif Binary files differnew file mode 100644 index 0000000..ad746a6 --- /dev/null +++ b/doc/cube128.gif diff --git a/doc/cygwin.htm b/doc/cygwin.htm new file mode 100644 index 0000000..88e0a54 --- /dev/null +++ b/doc/cygwin.htm @@ -0,0 +1,133 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Icon on Cygwin</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1> Icon on Cygwin </H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/cygwin.htm +<BR> +Last updated November 8, 2005 </SMALL> +<!-- $Id: cygwin.htm,v 1.5 2005/11/08 23:24:34 gmt Exp $ --> + + +<H2> Introduction </H2> + +<P> Most contemporary operating systems trace their underlying design +to the Unix operating system, +as refined and specified today by the POSIX family of standards. +Microsoft Windows, however, was developed independently and +defines a different set of interfaces for the programmer and the user. + +<P> The <A HREF="http://www.cygwin.com/">Cygwin</A> package provides a +Unix environment under Microsoft Windows. +This allows the latest version of Icon (and many other things) +to be built on a Windows system. +Successful use of Cygwin requires familiarity with both +Windows and Unix. + +<P> This document describes some of the peculiarities of the Cygwin +port of Version 9.4 of Icon. +These differences are not necessarily identified in other documentation. + + +<H2> Building Icon </H2> + +<P> The Cygwin package is available from +<A HREF="http://www.cygwin.com/">www.cygwin.com</A>. +A custom installation of the Cygwin system is required; +the default installation provides a bare-bones system +insufficient for building software. +Icon requires a C compiler and the usual tools and utilities +available on a standard POSIX development system; these are found +in the <CODE>gcc-core</CODE> and <CODE>make</CODE> packages. +The <CODE>xorg</CODE> family of packages is also needed +to build Icon with graphics enabled. + +<P> Icon is built in a Cygwin shell window. +The process is the same as on other platforms +and uses the configuration named <CODE>cygwin</CODE>. +See the <A HREF=build.htm>installation documentation</A> +for instructions on building Icon. + + +<H2> Running Icon programs </H2> + +<P> Icon is run by commands entered in a Cygwin terminal window. +The simplest command is "<CODE>icon prog.icn</CODE>", +which runs the program contained in the source file <CODE>prog.icn</CODE>. +The translator <CODE>icont</CODE> can create executable programs +from Icon source code. +The Unix-style "man pages" for <A HREF=icon.txt><CODE>icon</CODE></A> +and <A HREF=icont.txt><CODE>icont</CODE></A> +describe the command options in a traditionally cryptic manner. + + +<H2> Interpreter path </H2> + +<P> Icon programs require an interpreter for execution. +On Windows, the path of the interpreter is not embedded +in an executable program. +The program must be able to find +<CODE>iconx.exe</CODE> in one of these locations: +<UL> + <LI> in the file named by the <CODE>ICONX</CODE> environment variable + <LI> in the same directory as the executable program + <LI> in the search path +</UL> + + +<H2> Extra built-in functions </H2> + +<P> For compatibility with an earlier port of Icon to Windows, +this implementation includes some extra built-in functions. +The functions are described in section 6.2 of +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd271.htm">IPD271</A>, +which documents that earlier port. + +<P> These unsupported functions are not part of Icon on other platforms, +so their use renders a program non-portable. + + +<H2> Feature test symbols </H2> + +<P> The symbols <CODE>_MS_WINDOWS</CODE> and <CODE>_CYGWIN</CODE> +are defined by the Icon preprocessor. +The symbol <CODE>_GRAPHICS</CODE> is defined if Icon is built with +graphics enabled. +The symbols <CODE>_UNIX</CODE> and <CODE>_X_WINDOW_SYSTEM</CODE> +are not defined. +The corresponding strings are produced or omitted, as appropriate, +by the <CODE>&features</CODE> keyword. + + +<H2> No dynamic loading </H2> + +The dynamic loading interface — <CODE>loadfunc()</CODE> — +is not implemented. + + +<H2> Known bugs </H2> + +<UL> + <LI>Some Unix dependencies cause tests <CODE>io</CODE>, <CODE>tpp</CODE>, + and <CODE>opts</CODE> to fail. + <LI> Resizing a window sends a large number of events to the program. +</UL> + + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/docguide.htm b/doc/docguide.htm new file mode 100644 index 0000000..9bb4121 --- /dev/null +++ b/doc/docguide.htm @@ -0,0 +1,213 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE> Icon Documentation Guide </TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1> Icon Documentation Guide </H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/docguide.htm +<BR> Last updated November 9, 2005 </SMALL> +<!-- $Id: docguide.htm,v 1.28 2005/11/09 18:03:59 gmt Exp $ --> + + +<H2> Introduction </H2> + +<P> Icon is distributed with a small set of documentation pages: +<UL> +<LI> This documentation guide +<LI> <A HREF=relnotes.htm> Release notes</A> +<LI> <A HREF=install.htm> Installation instructions</A> (for binary releases) +<LI> <A HREF=build.htm> Build instructions</A> (for source releases) +<LI> <A HREF=port.htm> Porting instructions</A> +<LI> <A HREF=files.htm> File organization</A> +<LI> <A HREF=macintosh.htm> Icon on Macintosh</A> +<LI> <A HREF=cygwin.htm> Icon on Cygwin</A> +<LI> <A HREF=faq.htm> Frequently asked questions about Icon</A> +</UL> + +<P> This guide provides an overview of additional available information. +Documents designated with IPD numbers are Icon Project Documents +found at the Icon web site, +<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. + + +<H2> Basic Documentation </H2> + +<P> The command-line interface to Icon is described by <CITE>man</CITE> pages. +The <A HREF="icon.txt"><CODE>icon</CODE></A> command executes a program +from a single source file and supports script usage. +The more general <A HREF="icont.txt"><CODE>icont</CODE></A> command, +modeled after <CITE>cc</CITE>, +supports multiple files, separate compilation, and other features. + +<P> +The Icon language is defined by + <BLOCKQUOTE> + <IMG SRC="lb80.jpg" ALT="[cover]" WIDTH=60 HEIGHT=80 ALIGN=LEFT> + <CITE> The Icon Programming Language, Third Edition </CITE> + <BR> Ralph E. Griswold and Madge T. Griswold + <BR> Peer-to-Peer Communications, 1996, out of print + <BR> ISBN 1-57398-001-3 + <BR> Downloadable from + <A HREF="http://www.cs.arizona.edu/icon/books.htm"> + www.cs.arizona.edu/icon/books.htm</A> + <BR CLEAR=ALL> + </BLOCKQUOTE> + +<P> Some introductory material can be found on the web: +<UL> +<LI> Ralph Griswold's overview: + <A HREF="http://www.cs.arizona.edu/icon/docs/ipd266.htm"> + www.cs.arizona.edu/icon/docs/ipd266.htm</A> +<LI> Dave Hanson's introduction: + <A HREF="http://www.cs.arizona.edu/icon/intro.htm"> + www.cs.arizona.edu/icon/intro.htm</A> +<LI> Bill Mitchell's introduction and slides: + <A HREF="http://www.mitchellsoftwareengineering.com/icon/"> + www.mitchellsoftwareengineering.com/icon</A> +<LI> John Shipman's tutorial: + <A HREF="http://www.nmt.edu/tcc/help/lang/icon/"> + www.nmt.edu/tcc/help/lang/icon</A> +</UL> + +<P> +The <CITE>Icon Programming Language Handbook</CITE>, +by Thomas W. Christopher, is available on the web at +<A HREF="http://www.tools-of-computing.com/tc/CS/iconprog.pdf"> +www.tools-of-computing.com/tc/CS/iconprog.pdf</A>. + + +<H2> Graphics </H2> + +<P> +Icon's graphics facilities are defined by + <BLOCKQUOTE> + <IMG SRC="gb80.jpg" ALT="[cover]" WIDTH=60 HEIGHT=80 ALIGN=LEFT> + <CITE> Graphics Programming in Icon </CITE> + <BR> Ralph E. Griswold, Clinton L. Jeffery, and Gregg M. Townsend + <BR> Peer-to-Peer Communications, 1998, out of print + <BR> ISBN 1-57398-009-9 + <BR> Downloadable from + <A HREF="http://www.cs.arizona.edu/icon/books.htm"> + www.cs.arizona.edu/icon/books.htm</A> + <BR CLEAR=ALL> + </BLOCKQUOTE> + +<P> Two older reports present an overview of Icon's graphics: +<UL> + <LI> IPD281, Graphics facilities for Icon, + <A HREF="http://www.cs.arizona.edu/icon/docs/ipd281.htm"> + www.cs.arizona.edu/icon/docs/ipd281.htm</A> + <LI> IPD284, Visual interfaces for Icon programs, + <A HREF="http://www.cs.arizona.edu/icon/docs/ipd284.htm"> + www.cs.arizona.edu/icon/docs/ipd284.htm</A> +</UL> + + +<H2> Recent feature additions </H2> + +<P> A few minor features have been added since the publication +of the Icon books: +<UL> + <LI> Scriptable source files + <LI> Path searching improvements + <LI> Reading directory contents + <LI> Reading foreign text files +</UL> +These features are more fully described in the +<A HREF=relnotes.htm>release notes</A>. + + +<H2> Program Library </H2> + +<P> Program library documentation is contained within the source code. +Extracted documentation is available at +<A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm"> +www.cs.arizona.edu/icon/library/ipl.htm</A>. + + +<H2> Icon Internals </H2> + +<P> Icon's internals are detailed in + <BLOCKQUOTE> + <IMG SRC="ib80.jpg" ALT="[cover]" WIDTH=55 HEIGHT=80 ALIGN=LEFT> + <CITE>The Implementation of the Icon Programming Language</CITE> + <BR> Ralph E. Griswold and Madge T. Griswold + <BR> Princeton University Press, 1986, out of print + <BR> ISBN 0-691-08431-9 + <BR> Downloadable from + <A HREF="http://www.cs.arizona.edu/icon/books.htm"> + www.cs.arizona.edu/icon/books.htm</A> + <BR CLEAR=ALL> + </BLOCKQUOTE> +Although considerable changes have occurred since Version 6, +described in the book, the basic structure is the same. +Two technical reports describe subsequent changes: +<UL> +<LI>IPD112, Supplementary Information for Version 8, +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd112.htm"> +http://www.cs.arizona.edu/icon/docs/ipd112.htm</A> +<LI>IPD239, Supplementary Information for Version 9, +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd239.htm"> +http://www.cs.arizona.edu/icon/docs/ipd239.htm</A> +</UL> + + +<P> Icon's run-time implementation language is described in IPD261, +<A HREF="http://www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf"> +www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf</A> (PDF). + +<P> The construction of loadable C functions is described in +the <CITE>Dynamic Loading</CITE> section of IPD240, +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd240.htm"> +www.cs.arizona.edu/icon/docs/ipd240.htm</A>. +Also see the examples in the +<A HREF="http://www.cs.arizona.edu/icon/library/ccfuncs.htm"> +<CODE>cfuncs</CODE></A> section of the library, which use +a simpler set of interface macros. + + +<H2> Technical Reports </H2> + +<P> The Icon web site provides a large number of technical reports, +including "Icon Project Documents" designated by IPD numbers. +The index is found at +<A HREF="http://www.cs.arizona.edu/icon/docs/docs.htm"> +www.cs.arizona.edu/icon/docs/docs.htm</A>. + +<P> 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. + + +<H2> Discussion Group </H2> + +<P> The Usenet newsgroup <A HREF="news:comp.lang.icon">comp.lang.icon</A> +discusses all aspects of the Icon language and is the best place to ask +programming questions. + + +<H2> Other Sources </H2> + +<P> Other sources of documentation can be found in the +<A HREF="faq.htm"> Icon FAQ </A> and on the Icon web site, +<A HREF="http://www.cs.arizona.edu/icon/"> +www.cs.arizona.edu/icon</A>. + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/faq.htm b/doc/faq.htm new file mode 100644 index 0000000..50175fc --- /dev/null +++ b/doc/faq.htm @@ -0,0 +1,443 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Icon Programming Language FAQ</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> +<!-- Archive-name: comp-lang-icon-faq--> +<P><IMG SRC="wwwcube.gif" WIDTH="128" HEIGHT="144" ALT="" ALIGN=RIGHT> +<H1>Frequently Asked Questions about the Icon programming language</H1> +<A HREF="http://www.cs.arizona.edu/icon/faq.htm"> +www.cs.arizona.edu/icon/faq.htm</A> +<BR>Last updated November 14, 2005<BR> +<!-- $Id: faq.htm,v 1.45 2005/11/14 16:24:44 gmt Exp $ --> + +<P><STRONG>Learning about Icon</STRONG><BR> +<A HREF="#whatsicon">A1. What is Icon?</A><BR> +<A HREF="#whatgood">A2. What is Icon good for?</A><BR> +<A HREF="#features">A3. What are Icon's distinguishing characteristics?</A><BR> +<A HREF="#library">A4. What is the Icon program library?</A><BR> +<A HREF="#intro">A5. Where can I learn more about Icon?</A><BR> +<A HREF="#examples">A6. Where are some simple examples?</A><BR> +<A HREF="#documentation">A7. How about comprehensive documentation?</A><BR> +<P><STRONG>Implementations</STRONG><BR> +<A HREF="#platforms">B1. What platforms support Icon?</A><BR> +<A HREF="#getstarted">B2. How do I get started with Icon?</A><BR> +<A HREF="#unicode">B3. Is there a Unicode version of Icon?</A><BR> +<A HREF="#iconc">B4. What happened to the compiler?</A><BR> +<P><STRONG>Administration</STRONG><BR> +<A HREF="#iconproject">C1. What is the Icon Project?</A><BR> +<A HREF="#updates">C2. How often is the on-line material updated?</A><BR> +<A HREF="#lineage">C3. Where did Icon come from?</A><BR> +<A HREF="#futures">C4. Where is Icon going? </A><BR> +<P><STRONG>Support</STRONG><BR> +<A HREF="#ugroup">D1. Is there a users' group for Icon?</A><BR> +<A HREF="#techsupport">D2. How do I get technical support?</A><BR> +<P><STRONG>Programming</STRONG><BR> +<A HREF="#evread">E1. Why doesn't <CODE>read()</CODE> work with <CODE>every</CODE>?</A><BR> +<A HREF="#strinv">E2. Why doesn't string invocation such as <CODE>"foo"()</CODE> work?</A><BR> +<A HREF="#callc">E3. How can I call a C function?</A><BR> +<A HREF="#rwpipe">E4. Can I open a bidirectional pipe?</A><BR> + +<P><HR><H2>Learning about Icon</H2> + +<H3><A NAME="whatsicon">A1.</A> What is Icon?</H3> +<P> +Icon is a very high level general-purpose programming language with +extensive features for processing strings (text) and data structures. +Icon is an imperative, procedural language with a syntax that is +reminiscent of C and Pascal, but with semantics at a much higher level. +<P> +Icon has a novel expression-evaluation mechanism that integrates +goal-directed evaluation and backtracking with conventional control structures. +It has a string scanning facility for pattern matching that avoids the tedious +details usually associated with analyzing strings. +Icon's built-in data structures include sets and tables with associative +lookup, lists that can be used as vectors or stacks and queues, and records. +<P> +Icon is a strongly, though not statically, typed language. +It provides transparent automatic type conversion: +For example, if an integer is used in an operation that requires a string, +the integer is automatically converted to a string. +<P> +Several implementations of Icon have high-level graphics facilities with +an easily programmed window interface. +<P> +Icon manages storage automatically. +Objects are created as needed during program execution and space is +reclaimed by garbage collection as needed. +The sizes of strings and data structures are limited only by the amount +of available memory. + +<H3><A NAME="whatgood">A2.</A> What is Icon good for?</H3> +<P> +As a general-purpose programming language with a large computational +repertoire, Icon can be used for most programming tasks. +It's especially strong at building software tools, for processing text, +and for experimental and research applications. +<P> +Icon is designed to make programming easy; +it emphasizes the value of programmer's +time and the importance of getting programs to work quickly. +Consequently, Icon is used both for short, one-shot tasks and for +very complex applications. + +<H3><A NAME="features">A3.</A> +What are Icon's distinguishing characteristics?</H3> +<P> +<UL> + <LI> A high-level, general-purpose programming language + <LI> Friendly line-oriented syntax (no semicolons needed) + <LI> Emphasis on programmer productivity + <LI> Usually interpreted +</UL><UL> + <LI> Evolved from programming languages (vs. scripting languages) + <LI> Procedural control flow plus generators and goal-directed evaluation +</UL><UL> + <LI> Values have types; variables are typeless, accept any value + <LI> Static scoping: global or (procedure) local + <LI> Automatic garbage collection +</UL><UL> + <LI> All integers have arbitrary precision + <LI> Uses strings (not chars) as basic text datatype + <LI> Has lists that function as arrays, queues, and stacks + <LI> Also has sets, tables, records (structs), reals (doubles), more + <LI> No second-class "primitive types" +</UL><UL> + <LI> Not "object-oriented" (no classes, inheritance, or instance methods) + <LI> No exception catching + <LI> No concurrency (no threads, monitors, semaphores, or synchronization) + <LI> Has co-expressions (coroutines) +</UL><UL> + <LI> Basic least-common-denominator system interface (a la ANSI C) +</UL><UL> + <LI> Procedural graphics (event-driven paradigm available but not mandated) + <LI> Retained windows (programs are never called to repaint) + <LI> Simple GUI builder that can re-edit its generated code + <LI> Turtle graphics package +</UL><UL> + <LI> Large library of contributed procedures and programs +</UL> + +<H3><A NAME="library">A4.</A> What is the Icon program library?</H3> +<P> +The library is a collection of programs and procedures written in Icon. +User contributions are welcome and form a significant portion of the library. +<P> +Library procedures effectively augment the built-in functions +available to an Icon program. +A wide variety of procedures currently exists, and most +graphically-based programs are built around library procedures. +<P> +The programs in the library range from simple demonstrations to +handy tools to complex graphical applications. +<P> +The library is a resource for both new and experienced programmers. +In addition to their basic utility, +its programs and procedures serve as examples of how things can be +written in Icon. +<P> +The library is indexed at +<A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm"> +www.cs.arizona.edu/icon/library/ipl.htm</A>. + + +<H3><A NAME="intro">A5.</A> Where can I learn more about Icon?</H3> +<P> +Here are some good places to start. +<UL> +<LI> Ralph Griswold's overview: + <A HREF="http://www.cs.arizona.edu/icon/docs/ipd266.htm"> + www.cs.arizona.edu/icon/docs/ipd266.htm</A> +<LI> Dave Hanson's introduction: + <A HREF="http://www.cs.arizona.edu/icon/intro.htm"> + www.cs.arizona.edu/icon/intro.htm</A> +<LI> Bill Mitchell's introduction and slides: + <A HREF="http://www.mitchellsoftwareengineering.com/icon/"> + www.mitchellsoftwareengineering.com/icon</A> +<LI> John Shipman's tutorial: + <A HREF="http://www.nmt.edu/tcc/help/lang/icon/"> + www.nmt.edu/tcc/help/lang/icon</A> +</UL> + +<H3><A NAME="examples">A6.</A> Where are some simple examples?</H3> +<P> +For some simple text-based programs, see any of those +introductory documents in the preceding question. +For some simple graphics programs, see +<A HREF="http://www.cs.arizona.edu/icon/gb/progs/progs.htm"> +www.cs.arizona.edu/icon/gb/progs/progs.htm</A>. +<P> +Many more examples, typically larger, are found in the +Icon program library; see the indexes of +<A HREF="http://www.cs.arizona.edu/icon/library/cprogs.htm">Basic Programs</A> +and <A HREF="http://www.cs.arizona.edu/icon/library/cgprogs.htm"> +Graphics Programs</A>. + +<H3><A NAME="documentation">A7.</A> How about comprehensive documentation?</H3> +<P> +Two books define the Icon language. +The core language is covered in +<A HREF="http://www.cs.arizona.edu/icon/lb3.htm"> +<CITE>The Icon Programming Language (third edition)</CITE></A>, +by Griswold and Griswold. +Graphics facilities are described in +<A HREF="http://www.cs.arizona.edu/icon/gb/"> +<CITE>Graphics Programming in Icon</CITE></A> +by Griswold, Jeffery, and Townsend. +These books contain both tutorial and reference material. +<P> +Icon's internals are detailed in +<A HREF="http://www.cs.arizona.edu/icon/ibsale.htm"> +<CITE>The Implementation of the Icon Programming Language</CITE></A> +by Griswold and Griswold. +Although considerable changes have occurred since Version 6, +described in the book, the basic structure of Icon remains the same. +Two technical reports, +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd112.htm">IPD112</A> and +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd239.htm">IPD239</A>, +describe subsequent changes. +<P> +Printed copies of the +<CITE>Language</CITE> and <CITE>Graphics</CITE> books +are available from Jeffery Systems +(<A HREF="http://www.zianet.com/jeffery/books/">www.zianet.com/jeffery/books</A>). +All three books can be downloaded at no charge from the Icon books page, +<A HREF="http://www.cs.arizona.edu/icon/books.htm"> +www.cs.arizona.edu/icon/books.htm</A>. +<P> +The <CITE>Icon Programming Language Handbook</CITE>, +by Thomas W. Christopher, is available on the web at +<A HREF="http://www.tools-of-computing.com/tc/CS/iconprog.pdf"> +www.tools-of-computing.com/tc/CS/iconprog.pdf</A>. +<P> +An on-line index to the Icon program library is found at +<A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm"> +www.cs.arizona.edu/icon/library/ipl.htm</A>. +<P> +There is a large amount of additional information at the +Icon web site, +<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. + +<P><HR><H2>Implementations</H2> + +<H3><A NAME="platforms">B1.</A> What platforms support Icon?</H3> +<P> +Current implementations with graphics support +are available for Unix (including Linux) and Windows. +The Unix implementation also runs on Darwin, +the Macintosh development environment, or the +<A HREF="http://www.cygwin.com/">Cygwin</A> environment under Windows. +Older versions of Icon are available for some other systems. +An alternative Java-based implementation for Unix, +<A HREF="http://www.cs.arizona.edu/icon/jcon/">Jcon</A>, +is also available. + +<H3><A NAME="getstarted">B2.</A> How do I get started with Icon?</H3> +<P> +Version 9.4.3 of Icon for <STRONG>Unix</STRONG> can be downloaded from +<A HREF="http://www.cs.arizona.edu/icon/v943/"> +www.cs.arizona.edu/icon/v943</A>. +Source and binary packages are available, each with the +complete Icon program library. +<P> +Version 9.3 of Icon for <STRONG>Windows</STRONG> is compatible +at the source level with version 9.4.3. +It can be downloaded from +<A HREF="http://www.cs.arizona.edu/icon/v93w.htm"> +www.cs.arizona.edu/icon/v93w.htm</A>. +The Version 9.4.3 library can be obtained separately from +<A HREF="http://www.cs.arizona.edu/icon/v943/"> +www.cs.arizona.edu/icon/v943</A>. +<P> +For older implementations, start at +<A HREF="http://www.cs.arizona.edu/icon/implver.htm"> +www.cs.arizona.edu/icon/implver.htm</A>. +Jcon is at <A HREF="http://www.cs.arizona.edu/icon/jcon/"> +www.cs.arizona.edu/icon/jcon</A>. + +<H3><A NAME="unicode">B3.</A> Is there a Unicode version of Icon?</H3> +<P> +No. +Icon is defined in terms of 8-bit characters, and changing this presents +several design challenges that would likely break existing programs. +Also, modifying the C implementation is probably infeasible, +but a Unicode version of Jcon might be possible. + +<H3><A NAME="iconc">B4.</A> What happened to the compiler?</H3> +<P> +For a while, Unix distributions included both an interpreter and a compiler; +but the interpreter is is usually fast enough even for production work, and +most people found that using the compiler wasn't worth the extra compilation +time or the hassles involved. +We no longer advertise the compiler or produce binaries for it. +It is still part of the source code distribution, +and we have not deliberately broken it, +but we no longer support it and we cannot offer help if problems arise. + +<P><HR><H2>Administration</H2> + +<H3><A NAME="iconproject">C1.</A> What is the Icon Project?</H3> +<P> +The Icon Project is a name used by the group that +distributes and supports the Icon programming language. +The project maintains the Icon web site at +<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. +A non-commercial organization, the project is supported by the +Department of Computer Science at the University of Arizona. + +<H3><A NAME="updates">C2.</A> How often is the on-line material updated?</H3> +<P> +New material is added when it's available. +Established implementations usually are updated only when there's a +new version. +This typically is every year or two. +The Icon program library is updated on a similar schedule. + +<H3><A NAME="lineage">C3.</A> Where did Icon come from?</H3> +<P> +Icon is the latest in a series of high-level programming languages designed +to facilitate programming tasks involving strings and structures. +The original language, SNOBOL, was developed at Bell Telephone Laboratories +in the early 1960s. +SNOBOL evolved into SNOBOL4, which is still in use. +Subsequent languages were developed at the University of +Arizona with support from the National Science Foundation. +Although it has similar objectives and many similar capabilities, +Icon bears little superficial resemblance to SNOBOL4. +<P> +Icon implementations were developed by faculty, staff, and students +at the University of Arizona, +with significant contributions from volunteers around the world. +An <A HREF="http://doi.acm.org/10.1145/155360.155363">Icon history</A> +by Ralph and Madge Griswold appears in the preprints +of the second History of Programming Languages Conference (HOPL-II), +ACM SIGPLAN Notices, March 1993 (Vol 28, No 3). +<P> +The name Icon is not an acronym, nor does it stand for anything in +particular, although the word <CITE>iconoclastic</CITE> was mentioned +when the name was chosen. +The name predates the now common use of <CITE>icon</CITE> +to refer to small images used in graphical user interfaces. +This sometimes misleads people into thinking +that Icon is designed to create or manipulate icons, +but there's no good solution to that problem. + +<H3><A NAME="futures">C4.</A> Where is Icon going? </H3> +<P> +We continue to use Icon on a daily basis, but no significant changes +are planned. +We expect to support the Unix version for the forseeable future, +and to distribute ports to other systems as supplied by volunteers. +<P> +The Unicon project is developing an object-oriented language based on Icon. +For more information, see +<A HREF="http://unicon.sourceforge.net/"> +unicon.sourceforge.net</A>. + + +An earlier object-oriented extension to Icon, Idol, +can be found in the Icon program library. + +<P><HR><H2>Support</H2> + +<H3><A NAME="ugroup">D1.</A> Is there a users' group for Icon?</H3> +<P> +There is no official Icon users' group, but the Usenet newsgroup +<A HREF="news:comp.lang.icon">comp.lang.icon</A> +is dedicated to issues relating to the Icon language. + +<H3><A NAME="techsupport">D2.</A> How do I get technical support?</H3> +<P> +The Icon Project is not a commercial organization, and its capacity for +providing technical support is limited. Please use the appropriate resource +when you need assistance: +<UL> +<LI> +For <STRONG>programming</STRONG> questions, +submit a query to the Usenet newsgroup +<A HREF="news:comp.lang.icon">comp.lang.icon</A>. +<LI> +For <STRONG>porting</STRONG> assistance +or <STRONG>Unix</STRONG> problems, contact +<A HREF="mailto:icon-project@cs.arizona.edu">icon-project@cs.arizona.edu</A>. +<LI> +For problems with the <STRONG>Windows</STRONG> implementation, +contact the implementor, +<A HREF="mailto:jeffery@cs.nmsu.edu">jeffery@cs.nmsu.edu</A>. +<LI> +For general information and additional documentation, visit the Icon web site: +<A HREF="http://www.cs.arizona.edu/icon/">www.cs.arizona.edu/icon</A>. +</UL> + +<P><HR><H2>Programming</H2> + +<H3><A NAME="evread">E1.</A> +Why doesn't <CODE>read()</CODE> work with <CODE>every</CODE>?</H3> +<P> +<CODE>every s := read() do {...}</CODE> +doesn't loop because <CODE>read()</CODE> produces a single value and +then fails if resumed. +Other "consumer" procedures such as <CODE>get()</CODE> and <CODE>pop()</CODE> +work the same way. +Use a <CODE>while</CODE> loop with these procedures, and save +<CODE>every</CODE> for use with generators such as <CODE>!x</CODE> +or <CODE>key(T)</CODE>. + +<H3><A NAME="strinv">E2.</A> +Why doesn't string invocation such as <CODE>"foo"()</CODE> work?</H3> +<P> +String invocation works if the procedure is present; +the catch is that the linker removes unreferenced procedures. +To ensure a procedure's presence, reference it in the +<CODE>main()</CODE> procedure. +A simple reference suffices, as in +<CODE>refs := [foo, bar, baz]</CODE>; +it's not necessary to actually call it. +<P> +(Why does the linker remove unreferenced procedures? +Because this can save <EM>huge</EM> amounts of memory for +programs that use the library.) + +<H3><A NAME="callc">E3.</A> How can I call a C function?</H3> +<P> +You can't call an arbitrary C function, +but if you're willing to write a function to Icon's specifications, +there are two approaches. +Under Unix, which provides <CODE>loadfunc()</CODE>, +you can load one or more functions from a shared library, +and then treat them as if they had been written in Icon. +Some examples can be found in the +<A HREF="http://www.cs.arizona.edu/icon/library/ccfuncs.htm"> +<CODE>cfuncs</CODE></A> and +<CODE>packs/loadfuncs</CODE> directories of the Icon program library. +The more cumbersome approach is to add code to the Icon interpreter +and rebuild it; some hooks are provided for this purpose. +Both approaches are discussed in <CITE>Calling C Functions from Icon</CITE>, +<A HREF="http://www.cs.arizona.edu/icon/docs/ipd240.htm"> +www.cs.arizona.edu/icon/docs/ipd240.htm</A>. +<P> +The <A HREF="http://www.cs.arizona.edu/icon/jcon/">Jcon</A> implementation +allows Icon programs to call Java code that is written to Jcon specifications. + +<H3><A NAME="rwpipe">E4.</A> Can I open a bidirectional pipe?</H3> +<P> +No, this is not possible. +Although the concept is simple — +write a line to a program via a pipe, then read that program's output +— it probably wouldn't work. +Most I/O libraries don't write anything to a pipe until +they've filled a buffer, and the most likely consequence would be +a deadlock, with each program waiting for the other to send more data. + +<P><HR> +<SMALL> +This FAQ is edited by Gregg Townsend. +It includes contributions from +Ralph Griswold, Cliff Hathaway, Clint Jeffery, Bob Alexander, +and Todd Proebsting. +</SMALL> +</BODY> +</HTML> diff --git a/doc/faq.txt b/doc/faq.txt new file mode 100644 index 0000000..91b4eb9 --- /dev/null +++ b/doc/faq.txt @@ -0,0 +1,337 @@ + + Frequently Asked Questions about the Icon programming language + + www.cs.arizona.edu/icon/faq.htm + Last updated November 14, 2005 + + Learning about Icon + A1. What is Icon? + A2. What is Icon good for? + A3. What are Icon's distinguishing characteristics? + A4. What is the Icon program library? + A5. Where can I learn more about Icon? + A6. Where are some simple examples? + A7. How about comprehensive documentation? + + Implementations + B1. What platforms support Icon? + B2. How do I get started with Icon? + B3. Is there a Unicode version of Icon? + B4. What happened to the compiler? + + Administration + C1. What is the Icon Project? + C2. How often is the on-line material updated? + C3. Where did Icon come from? + C4. Where is Icon going? + + Support + D1. Is there a users' group for Icon? + D2. How do I get technical support? + + Programming + E1. Why doesn't read() work with every? + E2. Why doesn't string invocation such as "foo"() work? + E3. How can I call a C function? + E4. Can I open a bidirectional pipe? + _________________________________________________________________ + +Learning about Icon + + A1. What is Icon? + + Icon is a very high level general-purpose programming language with + extensive features for processing strings (text) and data structures. Icon + is an imperative, procedural language with a syntax that is reminiscent of C + and Pascal, but with semantics at a much higher level. + + Icon has a novel expression-evaluation mechanism that integrates + goal-directed evaluation and backtracking with conventional control + structures. It has a string scanning facility for pattern matching that + avoids the tedious details usually associated with analyzing strings. Icon's + built-in data structures include sets and tables with associative lookup, + lists that can be used as vectors or stacks and queues, and records. + + Icon is a strongly, though not statically, typed language. It provides + transparent automatic type conversion: For example, if an integer is used in + an operation that requires a string, the integer is automatically converted + to a string. + + Several implementations of Icon have high-level graphics facilities with an + easily programmed window interface. + + Icon manages storage automatically. Objects are created as needed during + program execution and space is reclaimed by garbage collection as needed. + The sizes of strings and data structures are limited only by the amount of + available memory. + + A2. What is Icon good for? + + As a general-purpose programming language with a large computational + repertoire, Icon can be used for most programming tasks. It's especially + strong at building software tools, for processing text, and for experimental + and research applications. + + Icon is designed to make programming easy; it emphasizes the value of + programmer's time and the importance of getting programs to work quickly. + Consequently, Icon is used both for short, one-shot tasks and for very + complex applications. + + A3. What are Icon's distinguishing characteristics? + + * A high-level, general-purpose programming language + * Friendly line-oriented syntax (no semicolons needed) + * Emphasis on programmer productivity + * Usually interpreted + + * Evolved from programming languages (vs. scripting languages) + * Procedural control flow plus generators and goal-directed evaluation + + * Values have types; variables are typeless, accept any value + * Static scoping: global or (procedure) local + * Automatic garbage collection + + * All integers have arbitrary precision + * Uses strings (not chars) as basic text datatype + * Has lists that function as arrays, queues, and stacks + * Also has sets, tables, records (structs), reals (doubles), more + * No second-class "primitive types" + + * Not "object-oriented" (no classes, inheritance, or instance methods) + * No exception catching + * No concurrency (no threads, monitors, semaphores, or synchronization) + * Has co-expressions (coroutines) + + * Basic least-common-denominator system interface (a la ANSI C) + + * Procedural graphics (event-driven paradigm available but not mandated) + * Retained windows (programs are never called to repaint) + * Simple GUI builder that can re-edit its generated code + * Turtle graphics package + + * Large library of contributed procedures and programs + + A4. What is the Icon program library? + + The library is a collection of programs and procedures written in Icon. User + contributions are welcome and form a significant portion of the library. + + Library procedures effectively augment the built-in functions available to + an Icon program. A wide variety of procedures currently exists, and most + graphically-based programs are built around library procedures. + + The programs in the library range from simple demonstrations to handy tools + to complex graphical applications. + + The library is a resource for both new and experienced programmers. In + addition to their basic utility, its programs and procedures serve as + examples of how things can be written in Icon. + + The library is indexed at www.cs.arizona.edu/icon/library/ipl.htm. + + A5. Where can I learn more about Icon? + + Here are some good places to start. + * Ralph Griswold's overview: www.cs.arizona.edu/icon/docs/ipd266.htm + * Dave Hanson's introduction: www.cs.arizona.edu/icon/intro.htm + * Bill Mitchell's introduction and slides: + www.mitchellsoftwareengineering.com/icon + * John Shipman's tutorial: www.nmt.edu/tcc/help/lang/icon + + A6. Where are some simple examples? + + For some simple text-based programs, see any of those introductory documents + in the preceding question. For some simple graphics programs, see + www.cs.arizona.edu/icon/gb/progs/progs.htm. + + Many more examples, typically larger, are found in the Icon program library; + see the indexes of Basic Programs and Graphics Programs. + + A7. How about comprehensive documentation? + + Two books define the Icon language. The core language is covered in The Icon + Programming Language (third edition), by Griswold and Griswold. Graphics + facilities are described in Graphics Programming in Icon by Griswold, + Jeffery, and Townsend. These books contain both tutorial and reference + material. + + Icon's internals are detailed in The Implementation of the Icon Programming + Language by Griswold and Griswold. Although considerable changes have + occurred since Version 6, described in the book, the basic structure of Icon + remains the same. Two technical reports, IPD112 and IPD239, describe + subsequent changes. + + Printed copies of the Language and Graphics books are available from Jeffery + Systems (www.zianet.com/jeffery/books). All three books can be downloaded at + no charge from the Icon books page, www.cs.arizona.edu/icon/books.htm. + + The Icon Programming Language Handbook, by Thomas W. Christopher, is + available on the web at www.tools-of-computing.com/tc/CS/iconprog.pdf. + + An on-line index to the Icon program library is found at + www.cs.arizona.edu/icon/library/ipl.htm. + + There is a large amount of additional information at the Icon web site, + www.cs.arizona.edu/icon. + _________________________________________________________________ + +Implementations + + B1. What platforms support Icon? + + Current implementations with graphics support are available for Unix + (including Linux) and Windows. The Unix implementation also runs on Darwin, + the Macintosh development environment, or the Cygwin environment under + Windows. Older versions of Icon are available for some other systems. An + alternative Java-based implementation for Unix, Jcon, is also available. + + B2. How do I get started with Icon? + + Version 9.4.3 of Icon for Unix can be downloaded from + www.cs.arizona.edu/icon/v943. Source and binary packages are available, each + with the complete Icon program library. + + Version 9.3 of Icon for Windows is compatible at the source level with + version 9.4.3. It can be downloaded from www.cs.arizona.edu/icon/v93w.htm. + The Version 9.4.3 library can be obtained separately from + www.cs.arizona.edu/icon/v943. + + For older implementations, start at www.cs.arizona.edu/icon/implver.htm. + Jcon is at www.cs.arizona.edu/icon/jcon. + + B3. Is there a Unicode version of Icon? + + No. Icon is defined in terms of 8-bit characters, and changing this presents + several design challenges that would likely break existing programs. Also, + modifying the C implementation is probably infeasible, but a Unicode version + of Jcon might be possible. + + B4. What happened to the compiler? + + For a while, Unix distributions included both an interpreter and a compiler; + but the interpreter is is usually fast enough even for production work, and + most people found that using the compiler wasn't worth the extra compilation + time or the hassles involved. We no longer advertise the compiler or produce + binaries for it. It is still part of the source code distribution, and we + have not deliberately broken it, but we no longer support it and we cannot + offer help if problems arise. + _________________________________________________________________ + +Administration + + C1. What is the Icon Project? + + The Icon Project is a name used by the group that distributes and supports + the Icon programming language. The project maintains the Icon web site at + www.cs.arizona.edu/icon. A non-commercial organization, the project is + supported by the Department of Computer Science at the University of + Arizona. + + C2. How often is the on-line material updated? + + New material is added when it's available. Established implementations + usually are updated only when there's a new version. This typically is every + year or two. The Icon program library is updated on a similar schedule. + + C3. Where did Icon come from? + + Icon is the latest in a series of high-level programming languages designed + to facilitate programming tasks involving strings and structures. The + original language, SNOBOL, was developed at Bell Telephone Laboratories in + the early 1960s. SNOBOL evolved into SNOBOL4, which is still in use. + Subsequent languages were developed at the University of Arizona with + support from the National Science Foundation. Although it has similar + objectives and many similar capabilities, Icon bears little superficial + resemblance to SNOBOL4. + + Icon implementations were developed by faculty, staff, and students at the + University of Arizona, with significant contributions from volunteers around + the world. An Icon history by Ralph and Madge Griswold appears in the + preprints of the second History of Programming Languages Conference + (HOPL-II), ACM SIGPLAN Notices, March 1993 (Vol 28, No 3). + + The name Icon is not an acronym, nor does it stand for anything in + particular, although the word iconoclastic was mentioned when the name was + chosen. The name predates the now common use of icon to refer to small + images used in graphical user interfaces. This sometimes misleads people + into thinking that Icon is designed to create or manipulate icons, but + there's no good solution to that problem. + + C4. Where is Icon going? + + We continue to use Icon on a daily basis, but no significant changes are + planned. We expect to support the Unix version for the forseeable future, + and to distribute ports to other systems as supplied by volunteers. + + The Unicon project is developing an object-oriented language based on Icon. + For more information, see unicon.sourceforge.net. An earlier object-oriented + extension to Icon, Idol, can be found in the Icon program library. + _________________________________________________________________ + +Support + + D1. Is there a users' group for Icon? + + There is no official Icon users' group, but the Usenet newsgroup + comp.lang.icon is dedicated to issues relating to the Icon language. + + D2. How do I get technical support? + + The Icon Project is not a commercial organization, and its capacity for + providing technical support is limited. Please use the appropriate resource + when you need assistance: + * For programming questions, submit a query to the Usenet newsgroup + comp.lang.icon. + * For porting assistance or Unix problems, contact + icon-project@cs.arizona.edu. + * For problems with the Windows implementation, contact the implementor, + jeffery@cs.nmsu.edu. + * For general information and additional documentation, visit the Icon web + site: www.cs.arizona.edu/icon. + _________________________________________________________________ + +Programming + + E1. Why doesn't read() work with every? + + every s := read() do {...} doesn't loop because read() produces a single + value and then fails if resumed. Other "consumer" procedures such as get() + and pop() work the same way. Use a while loop with these procedures, and + save every for use with generators such as !x or key(T). + + E2. Why doesn't string invocation such as "foo"() work? + + String invocation works if the procedure is present; the catch is that the + linker removes unreferenced procedures. To ensure a procedure's presence, + reference it in the main() procedure. A simple reference suffices, as in + refs := [foo, bar, baz]; it's not necessary to actually call it. + + (Why does the linker remove unreferenced procedures? Because this can save + huge amounts of memory for programs that use the library.) + + E3. How can I call a C function? + + You can't call an arbitrary C function, but if you're willing to write a + function to Icon's specifications, there are two approaches. Under Unix, + which provides loadfunc(), you can load one or more functions from a shared + library, and then treat them as if they had been written in Icon. Some + examples can be found in the cfuncs and packs/loadfuncs directories of the + Icon program library. The more cumbersome approach is to add code to the + Icon interpreter and rebuild it; some hooks are provided for this purpose. + Both approaches are discussed in Calling C Functions from Icon, + www.cs.arizona.edu/icon/docs/ipd240.htm. + + The Jcon implementation allows Icon programs to call Java code that is + written to Jcon specifications. + + E4. Can I open a bidirectional pipe? + + No, this is not possible. Although the concept is simple — write a line to a + program via a pipe, then read that program's output — it probably wouldn't + work. Most I/O libraries don't write anything to a pipe until they've filled + a buffer, and the most likely consequence would be a deadlock, with each + program waiting for the other to send more data. + _________________________________________________________________ + + This FAQ is edited by Gregg Townsend. It includes contributions from Ralph + Griswold, Cliff Hathaway, Clint Jeffery, Bob Alexander, and Todd Proebsting. diff --git a/doc/files.htm b/doc/files.htm new file mode 100644 index 0000000..fd7fef0 --- /dev/null +++ b/doc/files.htm @@ -0,0 +1,182 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>File Organization in Version 9.4 of Icon</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1> File Organization in Version 9.4 of Icon </H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/files.htm +<BR> Last updated November 8, 2005 </SMALL> +<!-- $Id: files.htm,v 1.17 2005/11/08 23:24:35 gmt Exp $ --> + +<H2> Introduction </H2> + +<P> Version 9.4 of Icon introduced several changes to the organization +of Icon's files under Unix and the methods for finding them. +These changes, which are described below, simplify the installation +and use of Icon. + +<H2> Library procedure inclusion </H2> + +<P> As Icon evolved, the procedures from the Icon program library +became more important to basic Icon programs, and vital to graphics +programs; yet the IPL had been treated as a separate product. +A complete Icon system required two downloads and two installation +efforts, with proper coordination. + +<P> With Icon 9.4, the complete set of basic and graphics library +procedures is included with every binary Icon distribution. +Also present are the associated <CODE>$include</CODE> files +and a selected few programs from the library — +notably VIB, the visual interface builder. + +<P> Source distributions of Icon 9.4 include the full library, +which also continues to be available separately. + +<H2> Installation directory structure </H2> + +<P> An Icon binary distribution unpacks to produce an <CODE>icon</CODE> +directory containing <CODE>bin</CODE>, <CODE>lib</CODE>, <CODE>man</CODE>, +and <CODE>doc</CODE> subdirectories. +Building Icon from source produces these same directories. + +<P> The <CODE>bin</CODE> directory contains executables of +<CODE>icont</CODE>, the Icon translator; +<CODE>iconx</CODE>, the Icon interpreter; +a few library programs including <CODE>vib</CODE>; +and <CODE>libcfunc.so</CODE>, the loadable C functions. +There is a symbolic link from <CODE>icon</CODE> to <CODE>icont</CODE>. +Files in this directory are system dependent. + +<P> The <CODE>lib</CODE> directory holds <CODE>$include</CODE> files +and "ucode" (<CODE>.u1</CODE>/<CODE>.u2</CODE>) files of +program library procedures. +This directory is system independent. + +<P> The <CODE>man</CODE> directory holds the Unix <CODE>man</CODE> page +for <CODE>icont</CODE>, and the <CODE>doc</CODE> directory holds +HTML (<CODE>.htm</CODE>) documentation files. +These directories are also system independent. + +<P> This structure is similar to that of binary distributions of Icon 9.3. +The main difference is that the <CODE>lib</CODE> directory no longer holds +just a subset of the procedure collection, and the few files from +the former <CODE>include</CODE> directory have moved into <CODE>lib</CODE>. + +<H2> Installation location </H2> + +<P> The <CODE>icon</CODE> directory can be installed in any public or +private area as long as its internal structure is preserved. +When upgrading an existing Icon installation, replacing the previous +Icon directory with the new one may provide the smoothest transition. +Old Icon binaries will continue to function correctly with the new +interpreter. + +<P> In order to consider packaging Icon binaries in Linux RPM files, +or other similar packages, it is necessary to define a "canonical" +location for installing Icon. +The suggested canonical system installation location for Icon is +<CODE>/opt/icon</CODE>. +The <CODE>/opt</CODE> directory is present today on most Unix systems and is +the location recommended by the emerging File Hierarchy Standard (FHS), +<A HREF="http://www.pathname.com/fhs/">www.pathname.com/fhs</A>. + +<P> For convenience of use it may be desirable to provide symbolic +links from a directory such as /opt/bin or /usr/local/bin +to programs in the Icon <CODE>bin</CODE> directory. +If this is done, the list should include at least <CODE>icon</CODE>, +<CODE>icont</CODE>, <CODE>iconx</CODE>, and <CODE>vib</CODE>. + +<H2> Automatic inference of <CODE>iconx</CODE> location </H2> + +<P> Past versions of <CODE>icont</CODE> were configured to know +the location of <CODE>iconx</CODE> in order to embed this in +generated binaries. +The <CODE>iconx</CODE> location was configured by editing +<CODE>src/h/path.h</CODE> in source builds or by using the +<CODE>patchstr</CODE> utility to edit the <CODE>icont</CODE> +executable when installing a binary distribution. + +<P> In version 9.4, <CODE>icont</CODE> deduces its own location, +and from this it infers the location of <CODE>iconx</CODE> +in the same directory. +No configuration of <CODE>icont</CODE> is needed, and the correct +path is embedded automatically, requiring only that +<CODE>icont</CODE> and <CODE>iconx</CODE> reside in the same directory. + +<P> It is still possible to configure a fixed path in +<CODE>icont</CODE> using the <CODE>patchstr</CODE> utility. +If this is done, the configured path is used instead of the +inferred path. + +<H2> Automatic search for iconx at execution </H2> + +<P> The path that <CODE>icont</CODE> embeds in an Icon executable makes +binary distributions of Icon programs difficult because the embedded +path must be edited to match the installed location of <CODE>iconx</CODE>. +The <CODE>ipatch</CODE> utility performed this task when installing +binary distributions of Icon 9.3. + +<P> Icon 9.4 implements a simple search in the shell script that +heads each generated Icon executable. +The new header script searches for <CODE>iconx</CODE> +in these places: + +<OL> + <LI> in the location specified by the ICONX environment variable + <LI> in the same directory as executing binary + <LI> in a location specified in the script itself + (as generated by <CODE>icont</CODE> or as patched later) + <LI> in the command search path ($PATH) +</OL> + +<P> The second item is the key: If there is a copy of <CODE>iconx</CODE> +in the same directory as the executing program, it is found automatically +and used as the interpreter. +An Icon program can now be distributed in binary form +simply by including an <CODE>iconx</CODE> executable +in the same directory as the program executable. + +<P> The <CODE>ipatch</CODE> utility has been modified to recognize +both old and new headers, and can still be used to edit the path +embedded in an Icon executable. + +<H2> Automatic library access </H2> + +<P> The ability to figure out its own location also lets +<CODE>icont</CODE> provide automatic access to library procedures. +The inferred location of the <CODE>lib</CODE> directory is implicitly +appended to the paths, if any, specified by LPATH and IPATH +environment variables. +To use only the standard library files, no environment variables +need be set. + +<P> In a similar manner, <CODE>iconx</CODE> creates or alters the +FPATH environment variable before beginning execution of an Icon +program. This provides transparent access to the library's +loadable C functions without requiring explicit user action. + +<H2> No Setup step </H2> + +<P> With the changes above, the executable files in an Icon binary +distribution are ready for use without modification. +The annoying and error-prone Setup step that was necessary +with previous versions is no longer required. +With Icon 9.4, installation can be as simple as just unpacking the +tar file and adding its <CODE>bin</CODE> directory to the search path. + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/gb80.jpg b/doc/gb80.jpg Binary files differnew file mode 100644 index 0000000..8ac0081 --- /dev/null +++ b/doc/gb80.jpg diff --git a/doc/ib80.jpg b/doc/ib80.jpg Binary files differnew file mode 100644 index 0000000..3bd7280 --- /dev/null +++ b/doc/ib80.jpg diff --git a/doc/icon.txt b/doc/icon.txt new file mode 100644 index 0000000..4168ba5 --- /dev/null +++ b/doc/icon.txt @@ -0,0 +1,50 @@ +ICON(1) ICON(1) + +NAME + icon - execute Icon program + +SYNOPSIS + icon sourcefile [ arg ... ] + icon -P 'program' [ arg ... ] + +DESCRIPTION + Icon is a simple interface for executing programs written in the Icon + programming language. The source code is translated and linked, then + executed with the given list of arguments. + + Without -P, a single source file is read; its name must be given + exactly and need not end in .icn. A sourcefile name of - reads the + source code from standard input. + + With -P, a small program can be embedded within a larger shell script. + In this case the program argument is a complete Icon program, typically + given as a multi-line quoted string. + + Translation and linking is silent, suppressing progress messages, and + undeclared identifiers are diagnosed. This mirrors the behavior of the + icont command when run with -s and -u options. + + An Icon source file can be made directly executable by setting the + appropriate permission bits and beginning it with a shell header. If + the first line of the file is + #!/usr/bin/env icon + then icon is found on the command search path and called to process the + program upon execution. + +ENVIRONMENT + The environment variables described under icont(1) can also be used + with the icon command. Normally, none of these are needed. + +SEE ALSO + icont(1), the full-featured interface supporting separate compilation, + multiple source files, and other features. + + The Icon Programming Language. Griswold and Griswold, Peer-to-Peer, + third edition, 1996. + + Graphics Programming in Icon. Griswold, Jeffery, and Townsend, Peer- + to-Peer, 1998. + + Version 9.4.3 of Icon. + http://www.cs.arizona.edu/icon/v943. + diff --git a/doc/icont.txt b/doc/icont.txt new file mode 100644 index 0000000..a5eb633 --- /dev/null +++ b/doc/icont.txt @@ -0,0 +1,126 @@ + +NAME + icont - translate Icon program + +SYNOPSIS + icont [ option ... ] file ... [ -x arg ... ] + +DESCRIPTION + Icont translates and links programs written in the Icon language. + Translation produces ucode files, suffixed .u1 and .u2, which are + linked to produce executable files. Icon executables are shell scripts + containing binary data; this data is interpreted by iconx, which must + be present at execution time. + + File names ending in .icn are Icon source files; the .icn suffix may be + omitted from command arguments. An argument of - reads from standard + input. A name ending in .u, .u1, or .u2 selects both files of a ucode + pair. The specified files are combined to produce a single program, + which is named by removing the suffix from the first input file. + + An argument of -x may appear after the file arguments to execute the + linked program. Any subsequent arguments are passed to the program. + + Ucode files produced by translation are normally deleted after linking. + If the -c option is given, processing stops after translation and the + ucode files are left behind. A directory of such files functions as a + linkable library. + +OPTIONS + The following options are recognized by icont: + + -c Stop after producing ucode files. + + -f s + Enable full string invocation by preserving unreferenced procedures + during linking. + + -o file + Write the executable program to the specified file. + + -s Suppress informative messages during translation and linking. + + -t Activate runtime tracing by arranging for &trace to have an initial + value of -1 upon execution. + + -u Diagnose undeclared identifiers. + + -v i + Set verbosity level of informative messages to i. + + -E Direct the results of preprocessing to standard output and inhibit + further processing. + + -N Don't embed iconx path in executable file. + + -V Announce version and configuration information on standard error. + +TRANSLATION ENVIRONMENT + Two environment variables control file search paths during translation + and linking. These variables contain blank- or colon-separated lists + of directories to be searched after the current directory and before + the standard library. + + IPATH + Directories to search for for ucode files specified in link direc- + tives and on the command line. + + LPATH + Directories to search for source files specified in preprocessor + $include directives. + +EXECUTION ENVIRONMENT + Several environment variables control the execution of an Icon program. + Values in parentheses are the default values. + + BLKSIZE (500000) + The initial size, in bytes, of the allocated block region. + + COEXPSIZE (2000) + The size, in words, of each co-expression stack. + + ICONCORE + If set, a core dump is produced for error termination. + + ICONX + The location of iconx, the icon interpreter, overriding the value + built into the executable by icont. Not required if the configura- + tion is unchanged since build time or if iconx is in the same + directory as the executable. + + MSTKSIZE (10000) + The size, in words, of the main interpreter stack for icont. + + NOERRBUF + By default, &errout is buffered. If this variable is set, &errout + is not buffered. + + QLSIZE (5000) + The size, in bytes, of the region used for pointers to strings dur- + ing garbage collection. + + STRSIZE (500000) + The initial size, in bytes, of the string space. + + TRACE + The initial value of &trace. If this variable has a value, it + overrides the translation-time -t option. + +SEE ALSO + icon(1), a simpler command interface for embedding Icon programs in + scripts. + + The Icon Programming Language. Griswold and Griswold, Peer-to-Peer, + third edition, 1996. + + Graphics Programming in Icon. Griswold, Jeffery, and Townsend, Peer- + to-Peer, 1998. + + Version 9.4.3 of Icon. + http://www.cs.arizona.edu/icon/v943. + +CAVEATS + Icon executables are not self-sufficient, but require the iconx inter- + preter. When distributing an Icon program in executable form, include + a copy of iconx in the same directory. + diff --git a/doc/index.htm b/doc/index.htm new file mode 100644 index 0000000..0c62d4e --- /dev/null +++ b/doc/index.htm @@ -0,0 +1,29 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Icon Documentation</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1>Icon Documentation</H1> + +<P> <A HREF=docguide.htm> Documentation guide </A> +<P> <A HREF=relnotes.htm> Release notes </A> +<P> <A HREF=install.htm>Installation instructions (for binary releases) </A> +<P> <A HREF=build.htm> Build instructions (for source releases) </A> +<P> <A HREF=port.htm> Porting instructions </A> +<P> <A HREF=files.htm> File organization </A> +<P> <A HREF=macintosh.htm> Icon on Macintosh </A> +<P> <A HREF=cygwin.htm> Icon on Cygwin </A> +<P> <A HREF=faq.htm> Frequently asked questions about Icon </A> + + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/install.htm b/doc/install.htm new file mode 100644 index 0000000..900227b --- /dev/null +++ b/doc/install.htm @@ -0,0 +1,65 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Installing Binaries of Version 9.4 of Icon</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1>Installing Binaries of Version 9.4 of Icon</H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/install.htm +<BR> Last updated November 8, 2005 </SMALL> +<!-- $Id: install.htm,v 1.17 2005/11/08 23:24:35 gmt Exp $ --> + +<P> + +<P> These instructions explain how to install Unix binaries of +<A HREF=relnotes.htm>Version 9.4 of Icon</A>. +For instructions on building an Icon source package, see +<A HREF=build.htm>Building Icon from Source</A>. + +<H2>Installing a Private Copy of Icon</H2> + +<P> To install Icon in your own directory, just unpack the tar file. +This produces a directory with +four subdirectories: <CODE>bin</CODE>, <CODE>lib</CODE>, +<CODE>doc</CODE>, and <CODE>man</CODE>. +Add the <CODE>bin</CODE> directory to your shell's search path. + +<P> For instructions on building and running Icon programs, see the +man pages for <A HREF=icon.txt><CODE>icon</CODE></A> +and <A HREF=icont.txt><CODE>icont</CODE></A>. +For information about the Icon language, see the +<A HREF=docguide.htm>documentation guide</A>. + +<H2>Installing a Public Copy of Icon</H2> + +<P> A single copy of Icon can be shared among users +by unpacking it in a public area, or moving it there. +We suggest renaming the directory to <CODE>/opt/icon</CODE> +for new installations, but any location is acceptable. +It is only important that the <CODE>bin</CODE> and <CODE>lib</CODE> +directories retain those names as members of a common parent directory. +(More details about the Icon file organization are available +<A HREF=files.htm>separately</A>.) + +<P> You can make symbolic links from other locations +to programs in the Icon <CODE>bin</CODE> directory. +For example, you can link +<CODE>/usr/local/bin/icon</CODE> to <CODE>/opt/icon/bin/icon</CODE>. +If you do this, link all of <CODE>icon</CODE>, <CODE>icont</CODE>, +<CODE>iconx</CODE>, and (if present) <CODE>vib</CODE>. + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/istyle.css b/doc/istyle.css new file mode 100644 index 0000000..820fd71 --- /dev/null +++ b/doc/istyle.css @@ -0,0 +1,26 @@ +/* style sheet for Icon HTML pages */ + +BODY { color: black; background: white url(blubordr.gif) repeat-y; } +BODY { margin-left: 60px; margin-right: 10px; } + +BODY, TH, TD { font-family: Helvetica, Arial, sans-serif; } +EM,VAR,CITE,DFN { font-style: italic; } +STRONG { font-weight: bold; } +CODE { font-family: Helvetica, Arial, sans-serif; font-weight: bold;} +PRE, TT { font-family: "Lucida Sans Typewriter", Monaco, monospace; } + +H1,H2,H3,H4,H5,H6 { font-family:Helvetica,Arial,sans-serif; font-weight:bold; } +H1 { font-size: 150%; margin-top: 2.0em; margin-bottom: 0.4em; } +H2 { font-size: 125%; margin-top: 2.0em; margin-bottom: 0.4em; } +H3, H4, H5, H6 { font-size: 100%; margin-top: 1.5em; margin-bottom: 0.2em; } + +P { margin-top: 0.9em; margin-bottom: 0.0em; } +BLOCKQUOTE { margin-top: 0.4em; margin-bottom: 0.4em; } +UL, OL { margin-top: 0.4em; margin-bottom: 0.4em; } +LI { margin-top: 0.2em; } + +TH, TD { padding-left: 0.4em; padding-right: 0.4em; } +TH, TD { vertical-align: top; text-align: left; } + +A:link { background: white; color: #06C; } +A:visited { background: white; color: #036; } diff --git a/doc/lb80.jpg b/doc/lb80.jpg Binary files differnew file mode 100644 index 0000000..90f75fe --- /dev/null +++ b/doc/lb80.jpg diff --git a/doc/macintosh.htm b/doc/macintosh.htm new file mode 100644 index 0000000..a6b39de --- /dev/null +++ b/doc/macintosh.htm @@ -0,0 +1,80 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<HTML> +<HEAD> + <TITLE>Icon on Macintosh</TITLE> + <LINK rel="STYLESHEET" type="text/css" href="istyle.css"> + <LINK rel="SHORTCUT ICON" href="shortcut.gif"> +</HEAD> + +<BODY> + <P><A href="http://www.cs.arizona.edu/icon/"> + <IMG src= "wwwcube.gif" alt="[Icon home]" + width="128" height="144" border="0" align="right"></A></P> + + <H1>Icon on Macintosh</H1> + + <P>Gregg M. Townsend<BR> + <SMALL>Department of Computer Science</SMALL><BR> + <SMALL>The University of Arizona</SMALL></P> + + <P><SMALL>www.cs.arizona.edu/icon/v943/macintosh.htm<BR> + Last updated November 9, 2005</SMALL> + <!-- $Id: macintosh.htm,v 1.1 2005/11/09 18:03:59 gmt Exp $ --></P> + + <H2>Introduction</H2> + + <P>Because Mac OS X is based on Unix, it can run Icon. There is + no special Macintosh interface, so as a practical matter Icon on + the Mac is for those who are comfortable using a Unix shell in a + Terminal window.</P> + + <P>The command-line interface to Icon is described by Unix + <CITE>man</CITE> pages. The <CODE><A href= + "icon.txt">icon</A></CODE> command executes a program from a + single source file. An Icon program in a simple text file + <CODE>prog.icn</CODE> is executed by typing <CODE>icon + prog.icn</CODE>. The more general <CODE><A href= + "icont.txt">icont</A></CODE> command, modeled after the Unix + <CITE>cc</CITE> command, supports multiple files, separate + compilation, and other features.</P> + + <H2>Graphics</H2> + + <P>For graphics, Icon uses the X Window System, generally called + <A href="http://www.apple.com/macosx/features/x11/">X11</A> in + Macintosh documentation. X11 is not normally installed as part of + OS X; it must be selected as part of a custom installation. + Alternatively, it can be + <A HREF="http://www.apple.com/support/downloads/x11formacosx.html"> + downloaded</A> from Apple.</P> + + <P>The X window system does not start automatically. To run an + Icon graphics program, you must first start the X11 application + and leave it running. The environment variable DISPLAY must be + set in the shell that runs an Icon graphics program. For + example:</P> + + <BLOCKQUOTE> + <P><CODE>setenv DISPLAY :0.0</CODE></P> + </BLOCKQUOTE> + + <H2>Building Icon</H2> + + <P>Building Icon from source requires the <A href= + "http://www.apple.com/macosx/features/xcode/">Xcode</A> toolbox. + This comes in an extra folder on the OS X installation disc. + When installing XCode, be sure to select a custom + installation and add X11 to the default set.</P> + + <P>Icon is built in a Terminal window. The process is the same as + on other platforms and uses the configuration named + <CODE>macintosh</CODE>. See + <A href="build.htm">Building Icon</A> for detailed instructions.</P> + + <BLOCKQUOTE> + +</BLOCKQUOTE> + <HR> +</BODY> +</HTML> diff --git a/doc/port.htm b/doc/port.htm new file mode 100644 index 0000000..5be8473 --- /dev/null +++ b/doc/port.htm @@ -0,0 +1,235 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Porting the Icon Implementation</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1>Porting the Icon Implementation</H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/port.htm +<BR> Last updated November 8, 2005 </SMALL> +<!-- $Id: port.htm,v 1.5 2005/11/08 23:24:35 gmt Exp $ --> + +<H2> Introduction </H2> + +This document describes how to port a source release of Icon to a new platform. +It assumes familiarity with the process by which Icon is +<A HREF=build.htm>built from source</A> +using an existing configuration. + +<H2>Requirements</H2> + +Icon expects the underlying system to conform to certain standards +that are met by most modern systems. +These are not necessarily the latest standards but rather +versions that have already been widely implemented. +Newer standards maintain compatibility and present no problems. + + +<H3>POSIX Commands</H3> + +Icon is build using Makefiles and shell scripts, as defined by +POSIX.2 (IEEE 1003.2-1992). +Additionally, Icon uses Makefile <DFN>includes</DFN>, +which are provided by nearly all modern Unix systems +although they are not part of the 1992 standard. + + +<H3>C Compiler</H3> + +Icon requires a production-quality compiler supporting ANSI C (X3.159-1989). +<EM>Production quality</EM> implies correctness, robustness, +and the ability to handle large files and complicated expressions. + +<H3>C Data Sizes</H3> + +Icon places the following requirements on C data sizes: + <UL> + <LI><I>chars</I> must be 8 bits. + <LI><I>ints</I> must be 16, 32, or 64 bits. + <LI><I>longs</I> and pointers must be 32 or 64 bits. + <LI>All pointers must be the same length. + <LI>Pointers and <I>longs</I> must be the same length. + </UL> +If your C data sizes do not meet these requirements, +do not attempt to configure Icon. + + +<H3>POSIX Library</H3> + +In addition to the standard C library, Icon uses the library functions +specified by POSIX.1 (IEEE 1993.1-1996). +In particular, Icon uses <DFN>POSIX threads</DFN> and <DFN>semaphores</DFN> +to implement context switching for co-expressions. +This eliminates the need for specialized assembly-language code, +some of which can still be seen in older configurations. + + + +<H2> The Porting Process </H2> + +Every different Icon configuration has its own subdirectory in the +<CODE>config</CODE> directory of the Icon source tree. +To add a new configuration, create a new directory and copy in the +<CODE>define.h</CODE>, <CODE>Makedefs</CODE>, and <CODE>status</CODE> files +from the <CODE>posix</CODE> configuration directory. + +<P> The porting process involves repeating these steps until +the system is working: +<OL> + <LI> Edit the configuration files as described below. + <LI> Configure: + <CODE>make Configure name=</CODE><VAR>newdirectory</VAR> + <LI> Build: <CODE>make</CODE> + <LI> Test: <CODE>make Test</CODE> +</OL> +If a configuration parameter is changed it is necessary to +reconfigure and rebuild from the beginning. + +<P> The Icon source code has proven to be robust and portable. +Most porting problems are related to command options and library locations, +the things that are configured in the <CODE>Makedefs</CODE> file. + +<P> If the system builds smoothly, but problems are revealed by +<CODE>make Test</CODE>, try removing any C optimization options. +New compilers are often stressed beyond their capabilities by Icon. + +<P> It is best to start by building just the basic Icon system. +When that is working, repeat with <CODE>make X-Configure</CODE> +instead of <CODE>make Configure</CODE> to build Icon with graphics. +(Note that <CODE>make Test</CODE> does not test graphics, and so you +should also execute <CODE>bin/colrbook</CODE> as an additional manual test.) +Finally, when those configurations are working, you may wish to +enable dynamic loading as described in a later section. + + +<H2> Configuration Parameters </H2> + +Icon is set up by editing three files in the configuration directory +of a particular platform. +You can examine the files in other directories to see working examples. +After a configuration file is changed, Icon must be reconfigured +and rebuilt from the beginning (step 2 above). +These instructions assume that you are starting from copies of +the <CODE>posix</CODE> configuration files. + + +<H3> <CODE>define.h</CODE> </H3> + +Edit the comment at the beginning of <CODE>define.h</CODE>, +but otherwise leave this file alone. +Although some older configurations may define additional values, +they are not needed here. + + +<H3> <CODE>Makedefs</CODE> </H3> + +The critical configuration work is done by editing the +<CODE>Makedefs</CODE> file. +The parameters set here are: +<BLOCKQUOTE><DL> + + <DT><CODE>CC</CODE> + <DD>The command name for the C compiler. Typical values are + <CODE>cc</CODE>, <CODE>gcc</CODE>, or <CODE>c89</CODE>. + + <DT><CODE>CFLAGS</CODE> + <DD>C compiler flags. A path specification for the X11 libraries + is usually needed. + Include <CODE>–O </CODE> to optimize the C code, + but remove it if it causes problems. + + <DT><CODE>CFDYN</CODE> + <DD>C compiler flags for generating dynamic libraries, + usually a flag that generates position-independent code. + A typical value is <CODE>–fPIC</CODE>. + + <DT><CODE>RLINK</CODE> + <DD>General runtime libraries. + Many systems require <CODE>–lm</CODE> to link + the math library. + Some systems also require <CODE>–ldl</CODE> to link + <CODE>dlopen()</CODE>. + + <DT><CODE>TLIBS</CODE> + <DD>Thread library. + Some systems require <CODE>–lpthread</CODE> or other + values (see examples in other configurations) to link the + threads library. + + <DT><CODE>XLIBS</CODE> + <DD>Linker specifications for the X Windows library. + Many systems need both a path and a library name here. + + <DT><CODE>XPMDEFS</CODE> + <DD>Definitions for building the XPM library. + Change this (see other examples) if problems occur + while building the <CODE>src/xpm</CODE> directory. + + <DT><CODE>GDIR</CODE> + <DD>Leave this alone. + +</DL></BLOCKQUOTE> + + +<H3> <CODE>status</CODE> </H3> + +The <CODE>status</CODE> file is not used by the build process, +but it should be edited to document the target platform, +and it should be updated whenever the configuration changes. + + + +<H2> Dynamic Loading </H2> + +Icon's optional dynamic loading facility allows Icon programs +to call specially written user C code via the built-in +<CODE>loadfunc</CODE> procedure. +Dynamic loading is enabled by +<OL> + <LI> Editing <CODE>config/</CODE><VAR>name</VAR><CODE>/define.h</CODE> + to add <CODE>#define LoadFunc</CODE> at the end. + <LI> Editing <CODE>ipl/cfuncs/mklib.sh</CODE> + to add a new case to the shell script that builds + a shared library from a set of C object files. + <LI> Reconfiguring, rebuilding, and retesting as usual. + If dynamic loading is enabled in <CODE>define.h</CODE>, + it is tested by <CODE>make Test</CODE>. +</OL> + +<P> The second step is the hardest; on many systems, documentation +that discusses shared libraries is scant or nonexistent. + +<P> If problems are found while building, check especially the definitions +of the <CODE>Makedefs</CODE> parameters +<CODE>CFDYN</CODE> and <CODE>RLINK</CODE>. + + + +<H2> Feedback </H2> + +Please let us know if you complete a port to a new platform. +Review the <CODE>status</CODE> file one last time and make +sure it is correct. +Send the files from the new configuration directory +(and also <CODE>mklib.sh</CODE>, if changed) to +<A HREF="mailto:icon-project@cs.arizona.edu">icon-project@cs.arizona.edu</A>. +Please also tell us the values reported on that platform by the +<CODE>uname -p</CODE> and <CODE>uname -m</CODE> commands. + + + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/relnotes.htm b/doc/relnotes.htm new file mode 100644 index 0000000..ae6bf1f --- /dev/null +++ b/doc/relnotes.htm @@ -0,0 +1,215 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> +<HEAD> + <TITLE>Release Notes for Version 9.4.3 of Icon</TITLE> + <LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> + <LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> +</HEAD> +<BODY> + +<P><A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" +ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> + +<H1> Release Notes for Version 9.4.3 of Icon </H1> + +<P> Gregg M. Townsend +<BR> <SMALL> Department of Computer Science </SMALL> +<BR> <SMALL> The University of Arizona </SMALL> + +<P> <SMALL> www.cs.arizona.edu/icon/v943/relnotes.htm +<BR> Last updated November 10, 2005 </SMALL> +<!-- $Id: relnotes.htm,v 1.49 2005/11/10 23:02:06 gmt Exp $ --> + + +<H2> Introduction </H2> + +<P> Version 9.4.3 of Icon is a minor update to version 9.4.2 of Icon. +It incorporates configuration, documentation, and library updates. +Some minor bugs have been fixed. + +<P> The Icon language is unchanged, and this Unix implementation +remains compatible at the source level with Icon 9.3 for Windows. + + +<H2> Changes in version 9.4.3 </H2> + +<P> Notable changes in this latest version are listed here. +Some code cleanup work and documentation editing +has also been done. + +<H3> Configurations </H3> + +<P> The system-specific Icon configurations have been reorganized and renamed; +new names focus on operating systems rather than CPU architectures. +The several BSD configurations have been merged into one. + +<P> The <CODE>macintosh</CODE> configuration now supports the +<CODE>loadfunc</CODE> function. This configuration has also been +revised to anticipate Apple's announced migration to the x86 architecture. + +<P> A new <A HREF=port.htm>porting guide</A> has been written, and a new +<CODE>posix</CODE> configuration has been added +as a starting point in constructing new ports. + +<H3> Library changes </H3> + +<P> As usual, several files in the Icon program library have been +added or edited. The core library files, however, remain stable. +Notable changes include: + +<PRE> +procs/dijkstra new procedures implement Dijkstra's control structures +procs/html add procedure for canonicalization of paths +procs/matrix2 new procedures for matrix manipulation +procs/nestlist new procedures for representing nested lists as strings +procs/printf add %e format and fix a rounding problem + +progs/noise new program for producing a random bitstream +progs/unclog improve logic for combining adjacent entries + +gprogs/dlgvu improve coverage map; allow altitude in GPS data +gprogs/gallery faster thumbnail loading for JPEG images +gprogs/img many new features +gprogs/sier better color choices +gprogs/trkvu accept GPS track logs with altitude as the last field +</PRE> + +The undocumented <CODE>save</CODE> function, which only worked +on a few platforms, has been removed. + + +<H2> Earlier feature additions </H2> + +<P> These features appeared in earlier releases of Icon that followed +publication of the Icon books. + +<H3> Millions of colors </H3> +<SMALL> (new with version 9.4.2 of Icon) </SMALL> + +<P> Icon's X-windows interface no longer limits each window to +256 colors at one time. +Median-cut quantization selects image colors when writing a GIF file. + +<H3> Scriptable source files </H3> +<SMALL> (new with version 9.4.1 of Icon) </SMALL> + +<P> An Icon source file can be made executable under Unix by prefixing it +with a comment line +<BLOCKQUOTE><CODE>#!/usr/bin/env icon</CODE></BLOCKQUOTE> +and setting its execute permission bit. +This uses a new <A HREF="icon.txt"><CODE>icon</CODE></A> command, +which in another form allows a small Icon program to be embedded +within a shell script. +See the <A HREF="icon.txt">man page</A> for details. +The traditional <A HREF="icont.txt"><CODE>icont</CODE></A> command +remains available for less specialized purposes. + +<H3> Path searching </H3> +<SMALL> (new with version 9.4.0 of Icon) </SMALL> + +<P> Under Unix, colons (<CODE>:</CODE>) may now separate directories in the +<CODE>LPATH</CODE> and <CODE>IPATH</CODE> environment variables as an +alternative to spaces. +The Icon translator and linker search these paths when looking for +<CODE>$include</CODE> and <CODE>link</CODE> files respectively. + +<P> The Icon program library is now searched automatically, but +<CODE>LPATH</CODE> and <CODE>IPATH</CODE> can still be set to control +the search order. +For version 9.4, the effective path in each case is: +<OL> + <LI> The current directory + <LI> Any directories named by the environment variable + <LI> The Icon library directory +</OL> + +<P> Other changes affect the configuration of Icon at installation time +and the way executable Icon programs locate the interpreter. +These changes, which are transparent to most users, are discussed +in more detail on the <A HREF="files.htm">File Organization</A> page. + +<H3> Reading directory contents </H3> +<SMALL> (new with version 9.3.2 of Icon) </SMALL> + +<P> The files in a directory can be listed by opening the directory as a file. +Subsequent reads return the names of the files contained in the directory. +The names are returned in no particular order, and for Unix, the directories +<CODE>"."</CODE> and <CODE>".."</CODE> are included. + +<H3> Reading foreign text files </H3> +<SMALL> (new with version 9.3.1 of Icon) </SMALL> + +<P> The function <CODE>read()</CODE> recognizes +three kinds of line terminators when reading a file +opened in translated mode: +Windows (CR+LF), Macintosh (CR), or Unix (LF). +Consequently, text files created on one platform can be +read by an Icon program running on a different platform. + + +<H2> Limitations, bugs, and problems </H2> + +<P> Large integers cannot be used with <CODE>i to j</CODE>, +with <CODE>seq()</CODE>, or with integer-valued keywords. + +<P> Large-integer literals are constructed at run-time, so such +literals are best kept outside of loops. + +<P> Conversion of a large integer to a string is quadratic +in the length of the integer. +Conversion of a very large integer may take a long time. + +<P> An "evaluation stack overflow" can occur when a procedure is called +with a huge number (thousands or more) of arguments. +The capacity can be increased by setting the environment variable +<CODE>MSTKSIZE</CODE> or <CODE>COEXPSIZE</CODE>, as appropriate. + +<P> Stack overflow checking uses a heuristic that is not always effective. +Stack overflow in a co-expression is especially likely to escape +detection and cause a mysterious program malfunction. + +<P> Pathologically nested structures can provoke a memory or segmentation +fault during garbage collection by reaching the stack limit. +The stack limit can be raised by the +<CODE>limit</CODE> or <CODE>ulimit</CODE> shell command. + + +<P> If an expression such as <CODE> x := create <VAR>expr</VAR></CODE> +is used in a loop, and <CODE>x</CODE> is not a global variable, +uncollectable co-expressions accumulate with each iteration. +This problem can be circumvented by making <CODE>x</CODE> +a global variable or by assigning a value to <CODE>x</CODE> +before the create operation, as in + <BLOCKQUOTE><CODE> + x := &null <BR> + x := create <VAR>expr</VAR> + </CODE></BLOCKQUOTE> + +<P> Integer overflow on exponentiation may not be detected during execution. +Such overflow may occur during type conversion. + + +<H2> Documentation </H2> + +<P> See the <A HREF=docguide.htm>documentation guide</A> +for an overview of the available Icon documentation. + +<P> For installation instructions, see +<A HREF=install.htm>Installing Binaries</A> or +<A HREF=build.htm>Building from Source</A> as appropriate. + + +<H2> Acknowledgments </H2> + +<P> +Arthur Eschenlauer contributed the <CODE>matrix2</CODE> +and <CODE>nestlist</CODE> libraries. +Frank Lhota contributed the <CODE>dijkstra</CODE> library. +Nolan Clayton contributed revisions to the <CODE>img</CODE> program. +Michael Glass contributed revisions to the <CODE>printf</CODE> procedure. +Chris Tenaglia and Andreas Almroth contributed configuration files. + +<P> <HR> + +</BODY> +</HTML> diff --git a/doc/shortcut.gif b/doc/shortcut.gif Binary files differnew file mode 100644 index 0000000..0268253 --- /dev/null +++ b/doc/shortcut.gif diff --git a/doc/wwwcube.gif b/doc/wwwcube.gif Binary files differnew file mode 100644 index 0000000..7ff695e --- /dev/null +++ b/doc/wwwcube.gif |
