--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/interps/c-intercal/README	Sun Dec 09 19:30:08 2012 +0000
@@ -0,0 +1,261 @@
+                         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.