--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/interps/clc-intercal/README	Sun Dec 09 19:30:08 2012 +0000
@@ -0,0 +1,313 @@
+CLC-INTERCAL 1.-94.-2
+
+		"human beings are given free will in order to choose between
+		 insanity on the one hand and lunacy on the other"
+								Aldous Huxley
+
+-- - --------
+-2 - Contents
+-- - --------
+
+   -2 - Contents
+   -1 - Foreword
+    0 - Introduction to CLC-INTERCAL pre-pre-escape 1.-94.-2
+    1 - What has changed since CLC-INTERCAL 0.05
+    2 - How to install this escape
+    3 - How to modify the compiler(s)
+    4 - Important notes about the new INTERNET library
+    5 - Licence
+
+
+-- - --------
+-1 - Foreword
+-- - --------
+
+A few years ago, I had, for several reasons, decided to completely GIVE UP
+working on INTERCAL or, if you prefer, ABSTAIN FROM developing CLC-INTERCAL
+any farther.
+
+Of course, the flesh is weak and here I am at it again. It just so happens
+that I am using the "compiler compiler compiler compiler" for a serious
+project, so I am going to develop it further.
+
+
+- - ------------ -- ------------ -------------- --------
+0 - Introduction to CLC-INTERCAL pre-pre-escape 1.-94.-2
+- - ------------ -- ------------ -------------- --------
+
+It has been decided during the development of CLC-INTERCAL 0.06 that there
+would be no further releases of CLC-INTERCAL. However, the compiler has
+been left unattended on an FTP server, and appears to have escaped. For this
+reason, we refer to this as an "escape" rather than a "release".
+
+Additionally, development of CLC-INTERCAL version 0 has effectively stopped
+before the escape of 0.06; a new versioning scheme has been introduced for
+CLC-INTERCAL version 1. The main points to note are:
+
+  * The term "version" has been replaced by "perversion" for correctness
+  * The perversion number consists of a floating-point number with
+    independent signs for the integer and fractional part. Negative
+    fractions indicate pre-escapes (so 1.-94 means "94 pre-escapes to
+    go before 1.00". Or you can just add the numbers together and get
+    0.06, which is entirely a coincidence since 0.06 is not being
+    developed)
+  * The fractional part of a perversion number can be integer or floating
+    point, with a similar meaning for the parts. The current pre-escape is
+    1.-94.-2 which means "2 pre-pre-escapes to go before pre-escape 1.-94".
+
+The fact that the compiler has escaped does not allow you to use without
+reference to its licence: see the end of this document or the file COPYING.
+
+Since this is a pre-pre-escape, there are parts which are unimplemented
+or partially implemented. The file "MISSING" describes what is missing.
+There might also parts which are implemented but are intended to be left
+implemented: these will be removed from the final escapes.
+
+
+- - ---- --- ------- ----- ------------ ----
+1 - What has changed since CLC-INTERCAL 0.05
+- - ---- --- ------- ----- ------------ ----
+
+Just about everything. See the file "Changes" for a complete list, or see
+the following executive summary.
+
+The code is a complete rewrite. The "CREATE" statement which was documented
+but not implemented has now been implemented (in a different form) and not
+documented. This means that the compiler only needs to know about one
+statement, "CREATE", and everything else can be created on-the-fly. This is
+why the compiler itself and the various compatibility modules now include
+INTERCAL source code consisting almost exclusively of "CREATE" statements.
+
+This made it a lot easier to extend the language by specifying new features
+in INTERCAL instead of Perl. Most statements have been modified to allow
+creation of quantum bits. For example, it is possible to create 16 quantum
+bits in one operation by assigning to a register while not assigning to it.
+It goes without saying that the practice is not recommended if you don't
+actually possess a quantum computer.
+
+A new statement, "NEXT FROM", combines all the advantages of "COME FROM" and
+"NEXT". It has been implemented essentially to provide a system call
+interface, where the operating system is supposed to have a "NEXT FROM"
+lurking in its darkest corner. See the last entry in the file "Changes"
+for a complete description of the system call interface. Since this is
+INTERCAL, the syscall interface is entirely system independent. System
+dependent system calls are not supported.
+
+All old programs should work unchanged (modulo the unimplemented parts, but
+this is due to change as the perversion number progresses towards 1.00).
+Programs intended for different compilers can also be compiled by selecting
+a different compiler object (for example, "ick.iacc" provides compatibility
+with the C-INTERCAL compiler "ick", and "1972.iacc" with the original
+Princeton compiler). All these compiler object must be first compiled using
+"iacc.iacc", the INTERCAL Astonishing Compiler Compiler, which is also used to
+compile itself before compiling other compilers. A pre-compiled version is
+provided in this escape otherwise you'll never get started.
+
+The command-line compiler "oo, ick" and the inline module "Language::INTERCAL"
+are not currently provided. They have been replaced by the compiler "sick"
+and the module "Language::INTERCAL::Sick" respectively, which have a rather
+different usage. A compatibility "oo, ick" and "Language::INTERCAL" is
+intended to appear in a future pre-escape, and certainly before the escape.
+
+The former "on-line reference", has been included in the distribution in
+directory doc/html; it has been adapted for CLC-INTERCAL 1.-94; however
+some new features might be still undocumented or underdocumented. Some of
+the HTML documents are included as templates: the actual documentation
+will be produced in blib/htmldoc
+
+
+- - --- -- ------- ---- ------
+2 - How to install this escape
+- - --- -- ------- ---- ------
+
+To unpack the distribution you need the following:
+
+    * A command interpreter compatible with the Bourne shell
+    * the "dd" program
+    * optionally, gzip and/or bzip2
+
+If necessary, uncompress the distribution:
+
+    gzip -d CLC-INTERCAL-1.-94.-2.ddsh.gz
+
+or:
+
+    bzip2 -d CLC-INTERCAL-1.-94.-2.ddsh.bz2
+
+Unpack the distribution:
+
+    sh CLC-INTERCAL-1.-94.-2.ddsh
+
+Create the Makefile:
+
+    cd CLC-INTERCAL-1.-94.-2
+    perl Makefile.PL
+
+Build the compilers:
+
+    make
+
+See if everything works:
+
+    make test
+
+And install:
+
+    make install
+
+It is possible that, by the time you read this, we have provided two
+alternative versions of some modules: pure Perl and Perl-with-C. The latter
+is likely to be better in some way (speed, size), otherwise we would not
+provide it. If Makefile.PL finds that alternative versions are available,
+it will ask which one you want to install. In general, the pure Perl versions
+will work as long as your Perl installation works; the Perl-with-C should
+work but might break because your C compiler is not the same as mine, or
+simply because it's C and it's more self-obfuscating than INTERCAL. If it
+does not work, install the pure Perl version. If that does not work either,
+you have found an unimplemented feature. Congratulations.
+
+The "make" and "make test" will take some time: "make" will run IACC (the
+INTERCAL Astonishing Compiler Compiler) to build itself and all the other
+compilers, and this is not quite a quick job. The "make test" will test
+all parts of the compiler, including the Virual Machine, the Quantum
+Emulator and the Just-Too-Late compiler. Have a coffee break, or read the
+source code and try to figure out how it works. If you can figure out how
+it works, please tell me, because I cannot.
+
+
+- - --- -- ------ --- -----------
+3 - How to modify the compiler(s)
+- - --- -- ------ --- -----------
+
+The compiler and the compiler compiler are currently underdocumented
+(which means that there is no documentation whatsoever). If you feel
+the urge to modify the compiler itself, ignore the Perl runtime library
+and edit the file "sick.iacc", which would have been installed somewhere
+system dependent. If you have write permission to this system dependent
+location and your command interpreter is compatible with the Bourne Shell,
+you can locate the file and edit it by simply typing (all in one line, we
+show it in separate lines for readability):
+
+    sh -c '${EDITOR-vi} `sick -vo/dev/null sick.iacc 2>&1 |
+    head -1 | sed -e "s/\.\.\. \[.*$//"`'
+
+If you would rather not type the above, or you have no write permission to
+the appropriate place (or if you have an inferior command interpreter), try:
+
+    sick -vo/dev/null sick.iacc
+
+The complete path will appear in the first line of the output, so you can copy
+or edit it. You do want to copy it in case you break it:
+
+    sh -c 'cp `sick -vo/dev/null sick.iacc 2>&1 |\
+    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'
+
+When you have edited the file, rebuild the compiler object with:
+
+    sick sick.iacc
+
+If you have edited a copy, type that from the directory where you left the
+edited copy, or "sick" won't find it (but see the "-I" command line option)
+
+A similar consideration applies to rebuilding IACC (the INTERCAL Astonishing
+Compiler Compiler). However, in this case you need to make a copy of "iacc.io"
+as well as "iacc.iacc":
+
+    sh -c 'cp `sick -vo/dev/null iacc.iacc 2>&1 |\
+    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'
+    sh -c 'cp `sick -vo/dev/null iacc.io 2>&1 |\
+    head -1 | sed -e "s/\.\.\. \[.*$//"` iacc.io.SAFE'
+    sh -c '${EDITOR-vi} `sick -vo/dev/null iacc.iacc 2>&1 |\
+    head -1 | sed -e "s/\.\.\. \[.*$//"`'
+    sick iacc.iacc
+
+If you break "iacc.io" you won't be able to recompile "iacc" unless you
+re-install CLC-INTERCAL or use the copy you just made.
+
+
+- - --------- ----- ----- --- --- -------- -------
+4 - Important notes about the new INTERNET library
+- - --------- ----- ----- --- --- -------- -------
+
+A new INTERNET library is now available as an extension to the "sick"
+compiler (it may work with other compilers, but this is not very likely
+for now). See directory doc/INTERNET for details.
+
+When this extension is loaded, the program will automatically start a
+theft server if one isn't found already running on the local computer.
+As there isn't yet an official port assignment for this, the port is
+stored in the file system.sickrc, and should be changed when an official
+assignment is available. Look for the line:
+
+    I CAN UNDERSTAND "..INTERNET.PORT" AS "64928"
+
+and change the number as appropriate. You may also want to run your
+INTERNET applications using a nonstandard port, but doing so will make
+locally running programs incompatible with programs running elsewhere,
+so stealing from remote systems will not succeed - unless of course one
+has agreed on a port number with the remote system's admin.
+
+Some of the forms of the CASE statement, and the STEAL/SMUGGLE without an
+IP address, require knowledge of the IP address and netmask of local LANs.
+In some cases, it may be possible to obtain these automatically, however this
+is not possible in some systems. If the information is not available, no
+broadcasts are possible. To work around this problem it is possible to specify
+the list of interface in sickrc (user or system) with options like:
+
+    I CAN UNDERSTAND "..INTERNET.DEVICE.eth0" AS "192.168.1.2" WITH 24
+    I CAN UNDERSTAND "..INTERNET.DEVICE.eth1" AS "10.3.6.9" WITH 8
+
+Note that the option specifies the IP address and netmask of each interface;
+in this case, 192.168.1.2/24 and 10.3.6.9/8; the device name is ignored at
+present, but it may be a good idea to leave it the same as the name known to
+the kernel. Also note that you must install Net::Netmask to be able to use
+the list of devices from sickrc.
+
+An unusual feature of the INTERNET is that one can steal filehandles and they
+will continue working. For example, if an INTERCAL program with the INTERNET
+extension runs on computer A and has standard write redirected from a file,
+then another program on computer B can steal that standard write filehandle
+and will be able to write in from that file, even if the file is not on a
+networked filesystem (because it's been stolen, however, the program which
+opened the file can no longer use it - smuggling, on the other hand will allow
+to share a file between computers). This feature has been used to create a
+network-wide clipboard in which a server (a simple INTERCAL program) just
+opens a file and then does nothing; clients then SMUGGLE the filehandle
+and store the clipboard contents on it - automagically sharing it over the
+network. Moreover, the server can be found using broadcasts, so there is
+never any need for the user to know where it is running.
+
+
+- - -------
+5 - Licence
+- - -------
+
+Copyright (c) 2006-2008 Claudio Calvelli <intercal@sdf.lonestar.org>
+(Please include the word INTERLEAVING in the subject when emailing that
+address, or the email may be ignored)
+
+In addition to the above, permission is hereby granted to use, misuse,
+modify, distribute, break, fix again, etcetera CLC-INTERCAL-1.-94.-2
+provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+    3. Neither the name of the Author nor the names of its contributors
+       may be used to endorse or promote products derived from this software
+       without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+    ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+    SUCH DAMAGE.
+