INTERCAL 0.13 release.
[intercal:intercal.git] / READ.ME
1                 Release Notes for C-INTERCAL
2                         version 0.13
3
4                         DISCREDITS
5
6 This package is an implementation of the language INTERCAL designed by Don
7 Woods and James Lyon, who have since spent more than twenty years trying to
8 live it down.
9
10 This implementation was created by Eric S. Raymond <esr@snark.thyrsus.com>
11 during a fit of lunacy from which he has since mostly recovered.  It has
12 been considerably hacked upon and improved by Steve Swales, Michael Ernst,
13 Louis Howell (who wrote the array support stubbed out in Eric's original
14 version), and others.  Brian Raiter ported it to Linux and enabled it to use
15 flex.
16
17 You can surf to the latest version of this package, and related resources, from
18 http://www.ccil.org/~esr/home.html.
19
20                         FILES
21
22 The compiler itself is in the src directory.  Setting a symbol in the
23 makefile will allow you to install it and its libraries and support files
24 in a directory of your choice.  The doc directory contains (surprise!)
25 documentation, and pit contains various examples of INTERCAL source code,
26 writhing in agony.
27
28 The files included are:
29
30 READ.ME                 -- this file
31 BUGS                    -- current bug and to-do list
32 NEWS                    -- info on features and fixes new in this release
33 intercal.el             -- elisp for editing INTERCAL code under GNU Emacs
34
35 doc/intercal.txt        -- The INTERCAL manual (read this next!)
36 doc/intercal.tex        -- TeX source form
37 doc/intercal.sty        -- TeX style file
38 doc/intercal.ms         -- the manual in nroffable form
39 doc/ick.txt             -- new features in C-INTERCAL
40 doc/THEORY              -- some notes on the internals of the INTERCAL compiler
41
42 src/Makefile            -- makefile for the INTERCAL compiler
43 src/lexer.l             -- the lexical analyzer specification (in LEX)
44 src/ick.y               -- the grammar specification (in YACC)
45 src/ick.h               -- compilation types and defines
46 src/perpetrate.c        -- main routine for compiler
47 src/feh.c               -- INTERCAL-to-C code generator
48 src/fiddle.c            -- the INTERCAL operators
49 src/lose.[ch]           -- INTERCAL compile- and run-time error handling
50 src/ick-wrap.c          -- the driver for generated C-from-INTERCAL code
51 src/arrgghh.c           -- option argument parsing for generated programs
52 src/cesspool.c          -- the INTERCAL runtime support code
53 src/cesspool.h          -- interface to INTERCAL runtime support
54 src/numerals.c          -- numerals table for INTERCAL input
55
56 pit/*                   -- sample INTERCAL code; see pit/CATALOG
57
58                 HOW TO GET STARTED
59
60 You want a man page?  Man pages are for wimps.  To compile an INTERCAL
61 program `foo.i' to executable code, just do
62
63         ick foo.i
64
65 There's a -c option that leaves the generated `foo.c' in place for inspection
66 (suppressing compilation to machine code), a -d option that enables verbose
67 parse reporting from the yacc/bison parser, a -t option that requires strict
68 INTERCAL-72 compliance (rejecting COME FROM and the extensions for bases other
69 than two) and an -O option that enables the (hah!) optimizer.  Invoking ick -?
70 prints a usage message.  Other than that, yer on yer own.
71
72 Another switch affects C-INTERCAL's runtime behavior.  The `-C'
73 option forces output in "clockface" mode, for superstitious users who
74 believe writing "IV" upside-down offends IVPITER and would rather
75 see IIII.
76
77 Every INTERCAL runtime also accepts certain options at runtime (code by 
78 Steve Swales).  These include [+/-]help, [+/-]traditional, and [+/-]wimpmode. 
79 The help option (with either + or -) triggers a 'usage' message. The
80 +traditional option is presently a no-op.
81
82 Steve writes: "The wimpmode option is the most interesting. I found myself
83 always running my test programs with filters on both ends to work around the
84 'nifty' intercal number representations. This was so painful that I decided it
85 would be LESS painful (and a lot less code) if I added a 'wimp' option.  With
86 the +wimpmode option, the user is subjected to a humiliating message about what
87 a wimp he or she is to use this mode, but after that is allowed to use
88 conventional numerical notation.  While such a mode doubtless violates to some
89 extent the INTERCAL philosophy, the fact that a 'unbutcher' command has been
90 posted clearly indicates the need for it. Anyway... if you don't like it, don't
91 use it... the default is -wimpmode (i.e. NOT wimp mode)."
92
93                         SPREADING THE BLAME
94
95 The latest version of INTERCAL is kept available at the Retrocomputing Museun,
96 http://www.ccil.org/retro.
97
98 There is, in addition, an occasionally active USENET newsgroup devoted to the
99 language: alt.lang.intercal.
100
101                         NOTES ON THE LINUX BUILD
102
103 At the top of ick.h are two defines that you may need to remove if you
104 are using lex instead of flex.
105
106 Many lexes export a yylineno variable, an undocumented feature that is
107 not in flex (by default). If your build fails because of redecleration
108 of yylineno, comment out the define of YYLINENO_BY_HAND.
109
110 Some lexes also supply a yyrestart function to begin parsing a second
111 file, while others automatically restart after seeing an EOF. (This is
112 the case with flex.) If your build fails at link time because
113 yyrestart is not defined, comment out the define of USE_YYRESTART.
114
115 If you are using gcc in an non-ANSI environment, such as SunOS, it is
116 strongly recommended that you add "-Wno-unused -Wimplicit" to the gcc
117 command in the makefile. If you are in an ANSI environment and are
118 using the current versions of gcc, flex, and bison, C-INTERCAL should
119 build with no warnings.
120
121
122
123
124