--- /dev/null
+#
+# Makefile for the Intercal documentation
+#
+
+# Making the original manual:
+# To see the Revised Manual, generate intercal.txt or intercal.ps
+# To see the original INTERCAL-72 manual, generate original.txt or original.ps.
+
+# Making the Revamped Manual:
+# generate ick.inf, ickhtml (will be placed into a directory),
+# ick.htm (all in one file), ick.pdf, or ick.txt.
+
+# We make two passes in order to resolve SETR/GETNH references.
+# The sed hackery strips the trailing dots from level 1 section references.
+
+x.txt: x.mm
+ groff -dc=y -Tascii -p -t -mm x.mm >x.txt
+
+all: allorig allnew
+
+allorig: intercal.ps intercal.txt original.ps original.txt
+
+allnew: ick.inf ickhtml ick.htm ick.txt ick.pdf
+
+intercal.ps: intercal.mm
+ groff -dc=y -Tps -p -t -mm intercal.mm >intercal.refs.tmp
+ sed <intercal.refs.tmp -e '/hn \([0-9]*\)\.$$/s//hn \1/' >tmp.refs;
+ mv tmp.refs intercal.refs.tmp
+ groff -dc=y -Tps -p -t -mm intercal.mm >intercal.ps
+ -rm intercal.refs.qrf
+
+original.ps: intercal.mm
+ groff -dc=n -Tps -p -t -mm intercal.mm >intercal.refs.tmp
+ sed <intercal.refs.tmp -e '/hn \([0-9]*\)\.$$/s//hn \1/' >tmp.refs;
+ mv tmp.refs intercal.refs.tmp
+ groff -dc=n -Tps -p -t -mm intercal.mm >original.ps
+ -rm intercal.refs.qrf
+
+intercal.txt: intercal.mm
+ groff -dc=y -Tascii -p -t -mm intercal.mm >/dev/null
+ sed <intercal.refs.tmp -e '/hn \([0-9]*\)\.$$/s//hn \1/' >tmp.refs;
+ mv tmp.refs intercal.refs.tmp
+ GROFF_NO_SGR=1 groff -dc=y -Tascii -p -t -mm intercal.mm >intercal.txt
+ -rm intercal.refs.qrf
+
+original.txt: intercal.mm
+ groff -dc=n -Tascii -p -t -mm intercal.mm >/dev/null
+ sed <intercal.refs.tmp -e '/hn \([0-9]*\)\.$$/s//hn \1/' >tmp.refs;
+ mv tmp.refs intercal.refs.tmp
+ GROFF_NO_SGR=1 groff -dc=n -Tascii -p -t -mm intercal.mm >original.txt
+ -rm intercal.refs.qrf
+
+clean:
+ rm -f *.ps *.txt *.refs* ick.in* ick.txt ick.htm ick.pdf
+ rm -rf html
+
+ick.inf: ick.txi fdl-1-2.txi
+ makeinfo -o ick.info ick.txi
+ -mv ick.info ick.inf
+
+# The --css-include is skipped here because it seems to cause makeinfo
+# to leak open file space, and it fails with an EMFILE error. Instead,
+# fix83.pl (which changes filenames to 8.3 format, among other things)
+# is used to add the styling. Tidy is run to clean up the output if
+# available, but if it isn't, that isn't a problem; there will just be
+# a harmless warning.
+ickhtml:html/index.htm
+
+html/index.htm: ick.txi ickstyle.css fdl-1-2.txi tidy.cfg
+ rm -rf html
+ makeinfo --html -o html ick.txi
+ ls -1 html | perl -w fix83.pl | sh
+ perl -i.tmp -w fix83.pl html/*.htm
+ chmod u+w html/*.htm
+ -tidy -config tidy.cfg -m html/*.htm || :
+ rm html/*.tmp
+
+# fixtoc.pl is used here to reformat the TOC to look good under the
+# multiple-part system (which makeinfo doesn't really know about).
+ick.htm: ick.txi ickstyle.css fdl-1-2.txi tidy.cfg
+ makeinfo --html --no-split --no-header --css-include=ickstyle.css -D notsplit -o ick.htm ick.txi
+ -perl -i.tmp -w fixtoc.pl ick.htm
+ rm ick*.tmp
+ chmod u+w ick.htm
+ -tidy -config tidy.cfg -m ick.htm || :
+
+# For some reason, ick.htm comes out of this readonly sometimes, which
+# is why the chmod seems to be needed. No idea why, though.
+
+ick.txt: ick.txi fdl-1-2.txi
+ makeinfo --plaintext -D notsplit -o ick.txt ick.txi
+ick.pdf: ick.txi fdl-1-2.txi
+ -texi2dvi -b -c -e -p -q ick.txi
--- /dev/null
+This directory contains the documentation (such as it is) for INTERCAL.\r
+\r
+READ.ME\r
+ This file.\r
+\r
+intercal.mm:\r
+ Masters for the INTERCAL manual (needs pic to render illos)\r
+ This has been carefully proofread against the original paper\r
+ version.\r
+\r
+THEORY\r
+ Implementation notes on the C-INTERCAL implementation.\r
+\r
+chip.spec:\r
+ Christian Brunschen's spec sheet for the INTERCAL chip.\r
+\r
+ick.txi:\r
+ Master for the Revamped reference manual, a newer manual\r
+ independent of the old one.\r
+\r
+Note 1: The TeX version we formerly distributed has been dropped. The\r
+combination of groff and pic does an effective job of rendering the\r
+illustrations and is easier to maintain.\r
+\r
+Note 2: The supplemental reference manual, ick.txt, has been merged\r
+into the intercal manual. (It is still possible to generate the \r
+original; see the Makefile.)\r
+\r
+Note 3: The flat-ASCII directly transcribed from the paper original is\r
+also gone. You can regenerate something very close to it with `make\r
+original.txt'. The differences will be (a) page breaks may fall in\r
+different places, (b) the circuit diagrams present in the paper\r
+version but absent in the ASCII transcription are instead poorly\r
+approximated with ASCII boxology, (c) every "butchered Roman numeral"\r
+is preceded and followed by a line break, (d) the hanging-indent list\r
+of Princeton compiler options has all marks above each description,\r
+rather than to its left.\r
+\r
+The aim of these changes was to reduce to one the number of manual masters that\r
+need to be maintained for the original manual, which can both produce the\r
+original INTERCAL-72 manual and the revised version that existed up to about\r
+version 0.18. The revised version proved to be unportable and impractical; it's\r
+still worth a read, but for up-to-date information available in a range of\r
+formats it's worth reading the Revamped manual instead.
\ No newline at end of file
--- /dev/null
+ INTERCAL IMPLEMENTOR'S NOTES\r
+ by ESR (and AIS where noted)\r
+\r
+The C-INTERCAL compiler has a very conventional implementation using YACC and\r
+LEX (latterly, bison and flex). It generates C, which is then passed to your C\r
+compiler.\r
+\r
+ Lexical issues\r
+\r
+Note that the spectacular ugliness of INTERCAL syntax requires that the lexical\r
+analyzer have two levels. One, embedded in the input() function, handles the\r
+backquote and bang constructs, and stashes the input line away in a buffer for\r
+the splat construct's benefit. The upper level is generated by lex(1) and does\r
+normal tokenizing for YACC.\r
+\r
+In order to splatter erroneous statements correctly, the generated code has to\r
+track both logical and physical lines. That's the reason for the `lineno'\r
+variable in the generated C, it's actually tracking physical lines.\r
+\r
+Numeral tokens for input are defined in a symbol table (numerals.c) that is\r
+directly included in the run-time library module (cesspool.c). This avoids\r
+having to put the the size of the numerals array in an extern. To add new\r
+numeral tokens, simply put them in the numerals initializer.\r
+\r
+AIS: Now computed COME FROM is in the language, the lexer is called forth to do\r
+ a bit of syntax analysis, by distinguishing it from an ordinary COME FROM\r
+ and passing different symbols to the parser. The lexer is also responsible\r
+ for helping the parser to match sparks and ears in complicated array\r
+ situations, by distinguishing possibly closing sparkears from definitely\r
+ opening sparkears.\r
+\r
+ Compilation\r
+\r
+The parser builds an array of tuples, one for each INTERCAL statement. Most\r
+tuples have node trees attached. Once all tuples have been generated, the\r
+compile-time checker and optimizer phases can do consistency checks and\r
+expression-tree rewrites. Finally, the tuples are ground out as C code by the\r
+emit() function.\r
+\r
+Calculations are fully type-checked at compile time; they have to be because\r
+(as I read the manual) the 16- and 32-bit versions of the unary ops do\r
+different things. The only potential problem here is that the typechecker has\r
+to assume that :m ~ :n has the type of :n (32-bit) even though the result might\r
+fit in 16 bits. At run-time everything is calculated in 32 bits. When\r
+INTERCAL-72 was designed 32 bits was expensive; now it's cheap. Really, the\r
+only reason for retaining a 16-bit type at all is for the irritation value of\r
+it (yes, C-INTERCAL *does* enforce the 16-bit limit on constants).\r
+\r
+Labels are mapped to tuple indices (logical line numbers) in the code checker,\r
+just before optimization.\r
+\r
+The optimizer does full recursive folding of all constant expressions at\r
+compile time (evaluating away all the irritating little kluges you have to use\r
+to generate 32-bit constants). It also checks for known INTERCAL idioms for\r
+`test for equality', `test for nonzeroness', and the C logical operators &, |,\r
+^, and ~.\r
+\r
+AIS: The optimizer has now been expanded. See below.\r
+\r
+ Code Generation\r
+\r
+Each line of INTERCAL is translated into a C if()-then; the guard part is used\r
+to implement abstentions and RESUMES, and the arm part translates the `body' of\r
+the corresponding INTERCAL statement.\r
+\r
+The generated C code is plugged into the template file ick-wrap.c inside\r
+main(). It needs to be linked with cesspool.o, fiddle.o and lose.o (these are\r
+in libick.a, with the support for runtime switches, arrgghh.o). Cesspool.o is\r
+the code that implements the storage manager; fiddle.o implements the INTERCAL\r
+operators; and lose.o is the code that generates INTERCAL's error messages.\r
+The routine arrgghh.o parses the runtime command line arguments.\r
+\r
+The abstain[] array in the generated C is used to track line and label\r
+abstentions; if member i is on, the statement on line i is being abstained\r
+from. If gerund abstentions/reinstatements are present in the code, a second\r
+array recording the type of each statement in generated into the runtime, and\r
+used to ensure that these operations are translated into abstention-guard\r
+changes on all appropriate line numbers.\r
+\r
+RESUMES are implemented with a branch to a generated switch statement that\r
+executes a goto to the appropriate label. If there are no RESUMES, no such\r
+switch is generated.\r
+\r
+The compiler places a simple label at the location of each COME FROM in the\r
+program, while all of the machinery for checking for abstention and conditional\r
+execution and actually performing the jump is placed immediately after the code\r
+for the target statement.\r
+\r
+ Credits\r
+\r
+I wrote the first version of this compiler over a weekend using a pre-ANSI C\r
+compiler. It worked, but it wasn't pretty. Louis Howell added the array\r
+support later; he also torture-tested the COME FROM implementation by actually\r
+using it for the life2.i program included in this distribution, and fixed some\r
+bugs. Brian Raiter did a much-needed delinting while porting it for ANSI C,\r
+flex and Linux. He also improved the lexical analyzer's line tracking.\r
+\r
+ Code Generation 2 (by AIS)\r
+\r
+The recent additions to the language have made code generation potentially more\r
+complicated, depending on which switches are on. Each INTERCAL command is still\r
+translated into an if()-then, but with extra guards around it. COME FROM is\r
+still handled the same way, but only in singlethreaded programs with no\r
+computed COME FROMs. For anything more complicated than that, a general COMING\r
+FROM mechanism is invoked. C's most confusing control-flow identifiers, setjmp\r
+and longjmp, are used. When computed COME FROMs are involved, after every\r
+labeled statement, a set of gotos are done to check each in turn. A jmp_buf,\r
+cjb, is used to store the point in the program where the check started. Each\r
+COME FROM leading to that line and computed COME FROM anywhere in the program\r
+is checked, and modifies cjb to aim for its suckpoint if neccesary. In the case\r
+of a multithreaded program, one cjb will be stored in a linked ring of threads,\r
+and the other will be the one in the main program. Extra guards are also added\r
+for ONCE/AGAIN; the position of this guard depends on whether the command is a\r
+NEXT or something else. ONCE/AGAIN are quite legal even in singlethreaded\r
+programs. Computed ABSTAIN is dealt with by allowing the abstain[] array to\r
+hold values other than 0 or 1. Multithreading is supported by a new library,\r
+libickmt.a, to hold the multithread versions of libick.a functions. See\r
+unravel.c for an explanation of the full gory details of the multithread\r
+implementation (it has many comments explaining the implementation at the top).\r
+\r
+ Optimisation (by AIS)\r
+\r
+When I got my C-INTERCAL distribution, it only had a rudimentary\r
+optimiser. Constant folding had already been done, and the following\r
+optimisations. The following is mixed INTERCAL and C, sometimes in the same\r
+statement. It should be clear from context and whether I have used INTERCAL\r
+spark-ears or C brackets which language is which, although in some places I've\r
+mixed them. Note that the optimizer is only run in binary.\r
+\r
+Optimizations available with -O\r
+\r
+Optimisations that had already been done\r
+\r
+Constant folding\r
+'Vx$y'~"#0x55555555" into (x | y)\r
+'?x$y'~"#0x55555555" into (x ^ y)\r
+'&x$y'~"#0x55555555" into (x & y)\r
+(x ^ 0xFFFF) or (x ^ 0xFFFFFFFF) into ~x\r
+\r
+I added:\r
+\r
+[This list has been removed as it got out of date; see src/idiotism.oil for the\r
+new list. Most of the idioms are due to me, a few are by Joris Huizer.]\r
+\r
+Optimizations available with -f (I wrote all these)\r
+\r
+Guard removal (if a line can't be abstained, the if(!abstained[x]) line is\r
+removed when possible)\r
+\r
+Ignorance checks (if a variable can't be ignored and it can't overflow,\r
+assignment is done with C's = rather than a function)\r
+\r
+Recognition of NEXT...NEXT...computed RESUME as an idiom for if() (currently\r
+disabled because the rest of the optimiser can't handle it)\r
+\r
+Optimizations available with -F (I wrote this one)\r
+\r
+This optimization should mean that INTERCAL suddenly becomes the best language\r
+for various benchmark programs. Basically, the file is analysed to try to\r
+determine whether it takes no input and always produces the same output. If\r
+that is the case, the output is simply a shell-script (with executable\r
+permissions set and a #! line) that outputs the correct output! Therefore, the\r
+time required for one run of the program is taken up during compilation, and\r
+whenever the program is executed, it just copies out the predetermined\r
+output. This means (for instance) that primes.i runs in only a fraction of a\r
+second when optimized with -F. Of course, this tends to slow down the compiler\r
+and often produces a large object file, which is why it has a command-line\r
+option of its own.\r
--- /dev/null
+.TH CONVICKT 1
+.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
+.\" other parms are allowed: see man(7), man(1)
+.\"
+.\" Created by Alex Smith; licensed under GNU GPL v2 or later.
+.SH NAME
+convickt \- convert INTERCAL files between formats
+.SH SYNOPSIS
+.B convickt
+.I "incharset outcharset [paddingrule [arrayname]]"
+.SH "DESCRIPTION"
+This manual page describes the
+.BR convickt
+command.
+Fuller documentation is available via the command
+.B info convickt
+.
+.PP
+.B convickt
+converts INTERCAL programs from one character set to another; it takes
+input from standard input and sends its output to standard output.
+.SH OPTIONS
+For
+.I incharset
+and
+.I outcharset
+.TP
+.B atari
+Interpret the input as being ASCII-7 Atari syntax INTERCAL, as is used
+by the Atari INTERCAL-72 compiler, J-INTERCAL, and C-INTERCAL default
+syntax, or output in that syntax.
+.TP
+.B baudot
+Interpret the input as being in CLC-INTERCAL's extended Baudot
+syntax, or output in that syntax.
+.TP
+.B ebcdic
+Interpret the input as being in the CLC-INTERCAL dialect of EBCDIC, or
+output in that syntax.
+.TP
+.B latin1
+Interpret the input as being Latin-1 Princeton syntax INTERCAL, as is
+used by default by CLC-INTERCAL and also readable by C-INTERCAL with
+the
+.B \-X
+switch, or output in that syntax.
+.PP
+For
+.I paddingrule
+.TP
+.B zero
+Pad the irrelevant bits in ASCII-7 and Baudot output with zeros.
+.TP
+.B printable
+Set the values of the irrelevant bits in ASCII-7 and Baudot output to
+try to cause the output to stay within character range 32-126. This
+option is the default. (Note that
+.I paddingrule
+is irrelevant for 8-bit character sets like Latin-1 and EBCDIC).
+.TP
+.B random
+Pad the irrelevant bits in ASCII-7 and Baudot output with random data,
+except that outputing an all-bits-zero octet is avoided.
+.SH CAVEATS
+Not all conversions are possible, due to the character sets having
+different characters available. In most cases, an unconvertible or
+invalid character will be converted to a 0 (padded appropriately); the
+exception is that if a tab cannot be converted, it will instead be
+converted to a single space (so that INTERCAL programs still run if
+converted to Baudot). Using
+.B atari
+as an input or output character set will literally convert characters
+which differ between Atari and Princeton syntax without checking to
+see whether they are being used as operators or not.
+.PP
+If
+.I arrayname
+is given, then instead of outputting the converted text literally, it
+will be output as portable (that is, legal in INTERCAL-72, C-INTERCAL,
+J-INTERCAL and CLC-INTERCAL) INTERCAL that dimensions the tail array
+given as
+.I arrayname
+and assigns each byte of the output to an element of that array; this
+is mostly useful for producing Baudot text for CLC-INTERCAL-style
+array IO.
+.SH AUTHOR
+.B convickt
+and this manual page were written by Alex Smith.
--- /dev/null
+.TH ICK 1
+.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
+.\" other parms are allowed: see man(7), man(1)
+.\"
+.\" Modified by Alex Smith under the terms of the GPL.
+.SH NAME
+ick \- INTERCAL compiler
+.SH SYNOPSIS
+.B ick
+.I "[options] file..."
+.PP
+.B ick
+.I "-e [options] intercal-file [non-intercal-file...] [library...]"
+.SH "DESCRIPTION"
+This manual page documents briefly the
+.BR ick
+command.
+This manual page was originally written for the Debian GNU/Linux
+distribution (but may be used by others), because the original program
+did not have a manual page, and was then added back to the main
+distribution.
+Fuller documentation is available via the command
+.B info ick
+(for the
+.B ick
+command itself; even fuller documentation is available via
+.B info C-INTERCAL
+(which contains the documentation for both the compiler and the
+INTERCAL language)).
+.\"Comment this back in on Debian:
+.\"There is also other documentation in
+.\".B /usr/share/doc/intercal
+.\"and
+.\".B /usr/share/doc/intercal/examples
+.\"as one would expect on a Debian system.
+.PP
+.B ick
+takes INTERCAL programs and generates code from them (by running gcc).
+.PP
+Note that the base in which a program is written is deduced from its
+extension; INTERCAL programs in base 2 must have the extension .i,
+INTERCAL programs in bases from 3 to 7 must have an extension from .3i
+to .7i respectively.
+.PP
+No options take arguments; multiple options can be given separately or
+combined in the usual way (even -e).
+The order in which options is given is irrelevant unless they
+conflict, in which case the options that are given last on the command
+line take precedence.
+.SH OPTIONS
+.TP
+.B \-c
+Compile INTERCAL to C, but don't compile the resulting C.
+.TP
+.B \-d
+Print yacc debugging information (implies -c).
+.TP
+.B \-t
+Requires strict INTERCAL-72 compliance (rejecting COME FROM, the extensions
+for bases other than two, and other features not found in INTERCAL-72).
+.TP
+.B \-b
+Disables the INTERCAL-72 random-bug feature.
+.TP
+.B \-O
+Attempt to optimize expressions in the generated code.
+.TP
+.B \-C
+Clockface output (using IIII rather than IV in Roman numerals).
+.TP
+.B \-f
+Optimize control flow in generated code (prevents -yp).
+.TP
+.B \-F
+Optimize everything in generated code for
+speed, regardless of how slow the compiler becomes or how
+large the object file becomes. Implies -fO, prevents -cdeghpyH.
+.TP
+.B \-h
+Print optimizer debugging information (implies -cO).
+.TP
+.B \-H
+Print verbose optimizer debugging information (implies -cO).
+.TP
+.B \-hH
+Print optimizer debugging information in a different form (implies
+-cO).
+.TP
+.B \-w
+Enable the +printflow option in output programs even if they are not
+multithreaded.
+.TP
+.B \-y
+Run the yuk debugger on the code (prevents -fme).
+.TP
+.B \-p
+Run the yuk profiler on the code (prevents -fme).
+.TP
+.B \-m
+Allow multithreading and backtracking (prevents -ype, implies -w).
+.TP
+.B \-e
+Link one INTERCAL file to non-INTERCAL files or to expansion libraries.
+Doing this changes the syntax of the command line; the first file
+given must be the INTERCAL source file, then this can be followed by
+any number of files in other languages to link via the external calls
+system (currently only C programs are allowed), and then any number of
+expansion libraries.
+The non-INTERCAL files will be processed to link them to the INTERCAL
+files, and then compiled with gcc and linked to the main INTERCAL
+program.
+.TP
+.B \-E
+Do not link the system library, even if the code suggests that it is
+needed (prevents -P).
+.TP
+.B \-a
+Allow the use of the CREATE statement (prevents -P).
+.TP
+.B \-v
+Allow anything on the left of an assignment, and turn off the
+protection that constants otherwise have against being assigned to
+(prevents -fFOP).
+.TP
+.B \-P
+Compile PIC-INTERCAL rather than INTERCAL (prevents -amFvxeE, implies -cfO).
+.TP
+.B \-o
+Output to stdout rather than .c (implies -c).
+.TP
+.B \-X
+Interpret ambiguous syntax such as ? and @ with Princeton meanings (as
+used by CLC-INTERCAL), rather than with the default Atari meanings.
+.TP
+.B \-x
+Use CLC-INTERCAL rules for text I/O and for abstaining from a GIVE UP
+by label (prevents -P).
+.TP
+.B \-u
+Print a message whenever the compiler tries to open a file.
+.TP
+.B \-U
+Dump core on E778 as well as printing an error.
+.TP
+.B \-g
+Leave the generated C in place, and make the output executable
+debuggable.
+.TP
+.B \-l
+Attempt to report likely bugs and nonportabilities (implies -O).
+.SH "SEE ALSO"
+The newsgroup
+.B alt.lang.intercal
+is where INTERCAL compilers are announced, and INTERCAL itself is
+discussed; the website
+.B http://intercal.freeshell.org
+is where the most recent versions of C-INTERCAL (and also
+CLC-INTERCAL) are currently hosted.
+.
+.SH AUTHOR
+.B ick
+was originally written by Eric S. Raymond.
+This manual page was originally written by Mark W. Eichin
+<eichin@kitten.gen.ma.us>, for the Debian GNU/Linux system.
--- /dev/null
+\r
+/* Custom styles for the C-INTERCAL manual. These are partly for a\r
+ small amount of beautification, but mostly to work around the\r
+ ugliness of the default stylesheet on at least one compiler. This\r
+ stylesheet is public domain from this comment onwards. */\r
+\r
+ body {text-align:justify; font-family:serif;}\r
+ pre {margin:0.5em 3em 0.5em 3em;\r
+ background-color:#F8F8F8;\r
+ border:1px solid #CCCCCC;}\r
+ pre.smallexample {font-size:75%;}\r
+ p {margin:0.5em 0em 0.5em 0em;}\r
+ li {margin:0.5em 0em 0.5em 0em;}\r
+ ul.menu li {margin:0em 0em 0em 0em;}\r
+ ul.index-cp li {margin:0em 0em 0em 0em;}\r
+ div.contents ul li {margin:0em 0em 0em 0em;}\r
+ blockquote {margin:0.5em 3em 0.5em 3em;}\r
+ dt {margin:0em 0em 0em 0em; font-weight:bold;}\r
+ dd {margin:0.5em 0em 1em 3em;}\r
+ code {background-color:#F8F8F8;}\r
+ tt {background-color:#F8F8F8;}\r
+ samp {background-color:#F8F8F8;}\r
+ table {border:1px solid #666666; background-color:#CCCCCC;}\r
+ td {border:1px solid #666666; background-color:#FFFFFF;}\r
projects / intercal.git / commitdiff