Release Notes for C-INTERCAL

                                  DISCREDITS

This package is an implementation of the language INTERCAL designed by Don
Woods and James Lyon, who have since spent more than twenty years trying to
live it down.

This implementation was created by Eric S. Raymond <esr@snark.thyrsus.com>
during a fit of lunacy from which he has since mostly recovered.  It has been
considerably hacked upon and improved by Steve Swales, Michael Ernst, Louis
Howell, Brian Raiter, Alex Smith, Joris Huizer and others.  For detailed
credits see NEWS.

                                     FILES

The compiler itself is in the src directory.  You can choose where to
install it with the --prefix argument to configure, or by setting DESTDIR
in the Makefile.  The doc directory contains (surprise!)  documentation, and
pit contains various examples of INTERCAL source code, writhing in agony.

The files included are:

README                  -- this file
BUGS                    -- current bug and to-do list
NEWS                    -- info on features and fixes new in this release
COPYING                 -- copyright and licence information
MANIFEST                -- a list of all files in the distribution

doc/READ.ME             -- historical notes on the docs
doc/ick.txi             -- the Revamped Manual sources, a newer manual
doc/fdl-1-2.txi         -- the GNU FDL version 1.2 in Texinfo format
doc/ick.txt             -- the Revamped Manual in plain text format
doc/ick.info            -- the Revamped Manual in Info format
doc/ickstyle.css	-- styling rules for the Revamped Manual in HTML
doc/tidy.cfg		-- HTML tidying rules for the Revamped Manual
doc/fix83.pl            -- script to fixup the HTML output for 8.3 systems
doc/intercal.mm         -- the old manual in groffable form
doc/Makefile            -- makefile to build old and new manuals
doc/THEORY.txt          -- some notes on the internals of the INTERCAL compiler
doc/chipspec.txt        -- plans for an INTERCAL-based microprocessor
doc/ick.1               -- man page for ick
doc/convickt.1          -- man page for convickt

src/abcess.h            -- interface to functions linked with programs
src/arrgghh.c           -- option argument parsing for generated programs
src/bin2c.c             -- creates C code representations of binary files
src/cesspool.c          -- the INTERCAL runtime support code
src/clc-cset.c          -- compatibility code for CLC-INTERCAL character sets
src/csetstub.c          -- small file to allow convickt to link
src/configh.in          -- config.h template generated by autoheader
src/configdj.h          -- config.h substitute for DJGPP without config.sh
src/convickt.c          -- command line character set converter
src/coopt.sh            -- script to help out the -F optimizer (POSIX only)
src/dekludge.c          -- INTERCAL optimizer wrapper and utility functions
src/feh.h               -- interface to INTERCAL-to-C code generator
src/feh2.c              -- INTERCAL-to-C code generator
src/fiddle.[ch]         -- the INTERCAL operators
src/ick-wrap.c          -- the driver for generated C-from-INTERCAL code
src/ick.h               -- compilation types and defines
src/ick_ec.[ch]		-- external call support for INTERCAL
src/ick_lose.[ch]       -- INTERCAL compile- and run-time error handling
src/idiotism.oil        -- list of INTERCAL idioms to optimize
src/lexer.l             -- the lexical analyzer specification (in LEX)
src/numerals.c          -- numerals table for INTERCAL input
src/oil.y               -- compiler to translate idiotism.oil into C
src/oil.h               -- name mangling for OIL files
src/parser.y            -- the grammar specification (in YACC)
src/perpet.c            -- main routine for compiler
src/pick1.h             -- template for compiler-dependent PIC C headers
src/pick2.h             -- runtime support for compiled PIC-INTERCAL
src/pickwrap.c          -- the driver for generated PIC C-from-INTERCAL code
src/sizes.h             -- variables defining the numeric base
src/uncommon.[ch]       -- code common to the compiler and debugger
src/unravel.c           -- multithreading functions
src/yuk.[ch]            -- INTERCAL debugger and profiler
src/*.bin               -- character set definitions for clc-cset and convickt

prebuilt/parser.[ch]    -- Prebuilt parser (for systems without bison)
prebuilt/lexer.c        -- Prebuilt lexer (for systems without flex)
prebuilt/oil-oil.c      -- Prebuilt OIL compiler (again, for bisonless systems)

etc/intercal.el         -- elisp for editing INTERCAL code under GNU Emacs
etc/intercal.vim        -- INTERCAL syntax higlighting information for vim
etc/cftoec.sh         	-- script to convert cfunge to a library (see below)
etc/IFFI*               -- input to that script
etc/cfunge.patch        -- more input to that script
etc/temp                -- temporary directory used by that script

configure               -- GNU Autoconf script that generates a Makefile
configure.ac            -- autoconf source for configure
Makefile.in             -- template Makefile for compiling C-INTERCAL
Makefile.am             -- automake source for Makefile.in

buildaux/*              -- helper scripts for the build provided by automake
aclocal.m4              -- helper file needed to build the build system itself

pit/*                   -- sample INTERCAL code; see pit/CATALOG
pit/explib/*            -- source code for expansion libraries
pit/lib/syslib.*i       -- source code for the system libraries

                              HOW TO GET STARTED

First, note that there is a much fuller manual than this file available. For
full information about C-INTERCAL, including extensive installation and usage
instructions, see that one; run `info -f doc/ick.inf', or failing that read
the plain text version at doc/ick.txt. (You can build a variety of other
formats as well, such as HTML and PDF, using the Makefile in the doc
directory.) After C-INTERCAL is installed, the manual is also available with
just `info ick' for information about running ick, the compiler, or `info
C-INTERCAL' for the available information about ick and C-INTERCAL.  (If you
installed C-INTERCAL in a directory that did not contain the main Info
documentation tree, instead `info ick' will do what `info C-INTERCAL' should
do, and `info C-INTERCAL' will not work at all.)

You want a man page? Man pages are for wimps. (However, Debian wrote one
anyway, and it's available in the distribution as doc/ick.1.) To compile an
INTERCAL program `foo.i' to executable code, just do

        ick foo.i

There are many other useful options available, which used to be listed in this
README but it eventually became several long unreadable run-on sentences;
interested readers are referred to the Revamped Manual, or to ick -@ (which
prints a usage message).

Every compiled INTERCAL program also accepts certain options at runtime (code
by Steve Swales).  These include [+/-]help, [+/-]traditional, and
[+/-]wimpmode.  The help option (with either + or -) triggers a 'usage'
message. The +traditional option is presently a no-op. Also available are
[+/-] printflow, which gives information that may or may not be helpful for
debugging a program, and [+/-] mystery, which is deliberately undocumented.

Steve writes: "The wimpmode option is the most interesting. I found myself
always running my test programs with filters on both ends to work around the
'nifty' INTERCAL number representations. This was so painful that I decided it
would be LESS painful (and a lot less code) if I added a 'wimp' option.  With
the +wimpmode option, the user is subjected to a humiliating message about what
a wimp he or she is to use this mode, but after that is allowed to use
conventional numerical notation.  While such a mode doubtless violates to some
extent the INTERCAL philosophy, the fact that a 'unbutcher' command has been
posted clearly indicates the need for it. Anyway... if you don't like it, don't
use it... the default is -wimpmode (i.e. NOT wimp mode)."

                              SPREADING THE BLAME

There is an INTERCAL Resource Page at http://www.catb.org/intercal

The latest version of INTERCAL is also kept available at the Retrocomputing
Museun, http://www.catb.org/retro.

(The above two paragraphs are somewhat out of date, but I kept them there,
including the typos, for historical purposes. Looking through the
alt.lang.intercal archives is usually the best way to find out what the latest
version of C-INTERCAL (and you'll find out how to get its rival too, for that
matter) is nowadays; they tend to pop up in various unusual places, so giving
a URL might be misleading.  Note also that contact details, and even who to
contact, often end up out of date; the newsgroup is also a good way to find
out who to contact.

As of when I wrote this, the current homepage for C-INTERCAL and CLC-INTERCAL
is http://intercal.freeshell.org.)

There is, in addition, an occasionally active USENET newsgroup devoted to the
language: alt.lang.intercal. (It is a somewhat unusual newsgroup, as although
large numbers of people are known to read it hardly anyone ever writes in it;
occasionally someone asks if the newsgroup is dead and gets several responses
claiming it isn't. Mostly it's full of C-INTERCAL release notices, and is thus
a good way to determine the most recent version of C-INTERCAL.)

			     BUILDING C-INTERCAL

C-INTERCAL now uses a GNU Autotools-based build system, this is something like
the fourth build system that has been tried for it, and hopefully it now works
(we've given the build system several interesting twists, of course; for
instance, automake dumps things like the prebuilt parser in the root of the
distribution by default, which is ugly, so we moved them to the prebuilt
directory.) It is possible to build with the straightforward configure/make/
make install routine, just as most other distributed software does; however,
this dumps all the generated files into the root of the distribution, which
violates the author's sense of aesthetics, and so the recommended approach is
to build out-of-tree; create a directory anywhere you like, and run configure
from that directory, then make and install there. You can give configure
arguments (see configure --help for details); probably the only one you'll
want to use is --prefix, which selects the directory to install C-INTERCAL
into (--prefix=/usr and --prefix=/usr/local (the default) are both likely
choices, but you may want to install into a subdirectory of your home
directory to avoid the need for root priveleges). Some revious versions of
C-INTERCAL required various information to be specified by the user; the build
system now figures this all out for itself, so you can relax and not need to
worry (in theory).

Building on DOS (via DJGPP) and Windows (via Cygwin) both work fine the same
way as builds on POSIX-like systems like Linux, Mac OS X, and BSD.

I have come across lexes whose default limits for various things aren't high
enough to handle INTERCAL's various lexing conundrums. In this case, pay
attention to the error messages they give you, and alter the source file
src/lexer.l accordingly. This should not happen on most modern systems, as
most modern lexers allocate memory dynamically and so can handle source files
of any length.

The build now uses your default compiler and compiler options; you can change
either of these by specifying them as options to configure (for instance,
configure CC=gcc CFLAGS=-O3 -funroll-loops). (You can also set the appropriate
environment variables instead.) The default options are -g on all compilers,
and also -O2 if you're using gcc, and the default compiler is calculated
automatically by configure; note in particular that if you're using a non-gcc
compiler you'll have to request optimisation yourself by setting the CFLAGS if
you want an optimising build.

Although the build system tries to find a good high-resolution timing function
to use for profiling, such functions are often system-specific; you may be
able to get better profiling output by tinkering with yuk.h to specify a
different method of profiling.

                        NOTES ON COMPILING PIC-INTERCAL

PIC C compilers tend to differ substantially in the way they handle various
language constructs. As a result, this compiler will only compile to C (not to
hex or asm) when compiling a PIC-INTERCAL program. There are two header files,
pick1.h and pick2.h in the /src directory; these need to be placed somewhere
your compiler can find them, and pick1.h will need to be modified to contain
compiler-specific data (like the names of data types and the syntax for
specifying the device type, fuses, and various commands).

	    NOTES ON THE C-INTERCAL / CFUNGE EXTERNAL CALLS SYSTEM

Code is provided to allow linking of Funge-98 programs to INTERCAL programs;
however, this requires a Funge-98 interpreter, which is not present in this
distribution. Therefore, in order to do this, a Funge-98 interpreter must
first be downloaded and prepared for use with C-INTERCAL. At present, code is
only available for linking with 'cfunge', a Funge-98 interpreter written in
C. You can get the latest sources for that interpreter from the Internet via
the bzr version-control system by running this command:

bzr branch http://rage.kuonet.org/~anmaster/bzr/cfunge

Once you have the source code to cfunge, you can compile it into a library
suitable for use by C-INTERCAL by changing to the /etc directory of the
C-INTERCAL distribution, and running the cftoec.sh shell script in that
directory with the path to the cfunge distribution as an argument. The script
will make a copy of cfunge, modify it as required, and then place the
resulting library (libick_ecto_b98.a) in the /prebuilt directory of the
C-INTERCAL distribution; installing (or reinstalling) C-INTERCAL after that
will copy that library into the correct location in your filesystem.

For information on actually using this system once you've set it up, consult
the Revamped Manual.

                                   LICENSING

C-INTERCAL is now distributed under the General Public License version 2 (or
at your choice any later version), except for the C skeleton file which is
explicitly *not* GPLed in order to avoid the (possibly mythical) "license
virus" effect, and the Revamped Manual, which is licenced under the GNU Free
Documentation Licence version 1.2.  See the file COPYING for details on the
General Public License, and the file doc/fdl-1-2.txi (which is also included
as a chapter in each of the compiled versions of the documentation, in case
you don't feel like reading Texinfo) for information on the GNU Free
Documentation Licence.