From: Alex Smith Date: Sun, 27 Apr 2008 02:56:17 +0000 (-0400) Subject: add_docs X-Git-Tag: 0.29~241 X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=3afc0d1891d31815577c02560c0e40096aaa8fd7;p=intercal.git add_docs --- diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..58a2121 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,93 @@ +# +# 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 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 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 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 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 diff --git a/doc/READ.ME b/doc/READ.ME new file mode 100644 index 0000000..0a53649 --- /dev/null +++ b/doc/READ.ME @@ -0,0 +1,44 @@ +This directory contains the documentation (such as it is) for INTERCAL. + +READ.ME + This file. + +intercal.mm: + Masters for the INTERCAL manual (needs pic to render illos) + This has been carefully proofread against the original paper + version. + +THEORY + Implementation notes on the C-INTERCAL implementation. + +chip.spec: + Christian Brunschen's spec sheet for the INTERCAL chip. + +ick.txi: + Master for the Revamped reference manual, a newer manual + independent of the old one. + +Note 1: The TeX version we formerly distributed has been dropped. The +combination of groff and pic does an effective job of rendering the +illustrations and is easier to maintain. + +Note 2: The supplemental reference manual, ick.txt, has been merged +into the intercal manual. (It is still possible to generate the +original; see the Makefile.) + +Note 3: The flat-ASCII directly transcribed from the paper original is +also gone. You can regenerate something very close to it with `make +original.txt'. The differences will be (a) page breaks may fall in +different places, (b) the circuit diagrams present in the paper +version but absent in the ASCII transcription are instead poorly +approximated with ASCII boxology, (c) every "butchered Roman numeral" +is preceded and followed by a line break, (d) the hanging-indent list +of Princeton compiler options has all marks above each description, +rather than to its left. + +The aim of these changes was to reduce to one the number of manual masters that +need to be maintained for the original manual, which can both produce the +original INTERCAL-72 manual and the revised version that existed up to about +version 0.18. The revised version proved to be unportable and impractical; it's +still worth a read, but for up-to-date information available in a range of +formats it's worth reading the Revamped manual instead. \ No newline at end of file diff --git a/doc/THEORY.txt b/doc/THEORY.txt new file mode 100644 index 0000000..9668955 --- /dev/null +++ b/doc/THEORY.txt @@ -0,0 +1,168 @@ + INTERCAL IMPLEMENTOR'S NOTES + by ESR (and AIS where noted) + +The C-INTERCAL compiler has a very conventional implementation using YACC and +LEX (latterly, bison and flex). It generates C, which is then passed to your C +compiler. + + Lexical issues + +Note that the spectacular ugliness of INTERCAL syntax requires that the lexical +analyzer have two levels. One, embedded in the input() function, handles the +backquote and bang constructs, and stashes the input line away in a buffer for +the splat construct's benefit. The upper level is generated by lex(1) and does +normal tokenizing for YACC. + +In order to splatter erroneous statements correctly, the generated code has to +track both logical and physical lines. That's the reason for the `lineno' +variable in the generated C, it's actually tracking physical lines. + +Numeral tokens for input are defined in a symbol table (numerals.c) that is +directly included in the run-time library module (cesspool.c). This avoids +having to put the the size of the numerals array in an extern. To add new +numeral tokens, simply put them in the numerals initializer. + +AIS: Now computed COME FROM is in the language, the lexer is called forth to do + a bit of syntax analysis, by distinguishing it from an ordinary COME FROM + and passing different symbols to the parser. The lexer is also responsible + for helping the parser to match sparks and ears in complicated array + situations, by distinguishing possibly closing sparkears from definitely + opening sparkears. + + Compilation + +The parser builds an array of tuples, one for each INTERCAL statement. Most +tuples have node trees attached. Once all tuples have been generated, the +compile-time checker and optimizer phases can do consistency checks and +expression-tree rewrites. Finally, the tuples are ground out as C code by the +emit() function. + +Calculations are fully type-checked at compile time; they have to be because +(as I read the manual) the 16- and 32-bit versions of the unary ops do +different things. The only potential problem here is that the typechecker has +to assume that :m ~ :n has the type of :n (32-bit) even though the result might +fit in 16 bits. At run-time everything is calculated in 32 bits. When +INTERCAL-72 was designed 32 bits was expensive; now it's cheap. Really, the +only reason for retaining a 16-bit type at all is for the irritation value of +it (yes, C-INTERCAL *does* enforce the 16-bit limit on constants). + +Labels are mapped to tuple indices (logical line numbers) in the code checker, +just before optimization. + +The optimizer does full recursive folding of all constant expressions at +compile time (evaluating away all the irritating little kluges you have to use +to generate 32-bit constants). It also checks for known INTERCAL idioms for +`test for equality', `test for nonzeroness', and the C logical operators &, |, +^, and ~. + +AIS: The optimizer has now been expanded. See below. + + Code Generation + +Each line of INTERCAL is translated into a C if()-then; the guard part is used +to implement abstentions and RESUMES, and the arm part translates the `body' of +the corresponding INTERCAL statement. + +The generated C code is plugged into the template file ick-wrap.c inside +main(). It needs to be linked with cesspool.o, fiddle.o and lose.o (these are +in libick.a, with the support for runtime switches, arrgghh.o). Cesspool.o is +the code that implements the storage manager; fiddle.o implements the INTERCAL +operators; and lose.o is the code that generates INTERCAL's error messages. +The routine arrgghh.o parses the runtime command line arguments. + +The abstain[] array in the generated C is used to track line and label +abstentions; if member i is on, the statement on line i is being abstained +from. If gerund abstentions/reinstatements are present in the code, a second +array recording the type of each statement in generated into the runtime, and +used to ensure that these operations are translated into abstention-guard +changes on all appropriate line numbers. + +RESUMES are implemented with a branch to a generated switch statement that +executes a goto to the appropriate label. If there are no RESUMES, no such +switch is generated. + +The compiler places a simple label at the location of each COME FROM in the +program, while all of the machinery for checking for abstention and conditional +execution and actually performing the jump is placed immediately after the code +for the target statement. + + Credits + +I wrote the first version of this compiler over a weekend using a pre-ANSI C +compiler. It worked, but it wasn't pretty. Louis Howell added the array +support later; he also torture-tested the COME FROM implementation by actually +using it for the life2.i program included in this distribution, and fixed some +bugs. Brian Raiter did a much-needed delinting while porting it for ANSI C, +flex and Linux. He also improved the lexical analyzer's line tracking. + + Code Generation 2 (by AIS) + +The recent additions to the language have made code generation potentially more +complicated, depending on which switches are on. Each INTERCAL command is still +translated into an if()-then, but with extra guards around it. COME FROM is +still handled the same way, but only in singlethreaded programs with no +computed COME FROMs. For anything more complicated than that, a general COMING +FROM mechanism is invoked. C's most confusing control-flow identifiers, setjmp +and longjmp, are used. When computed COME FROMs are involved, after every +labeled statement, a set of gotos are done to check each in turn. A jmp_buf, +cjb, is used to store the point in the program where the check started. Each +COME FROM leading to that line and computed COME FROM anywhere in the program +is checked, and modifies cjb to aim for its suckpoint if neccesary. In the case +of a multithreaded program, one cjb will be stored in a linked ring of threads, +and the other will be the one in the main program. Extra guards are also added +for ONCE/AGAIN; the position of this guard depends on whether the command is a +NEXT or something else. ONCE/AGAIN are quite legal even in singlethreaded +programs. Computed ABSTAIN is dealt with by allowing the abstain[] array to +hold values other than 0 or 1. Multithreading is supported by a new library, +libickmt.a, to hold the multithread versions of libick.a functions. See +unravel.c for an explanation of the full gory details of the multithread +implementation (it has many comments explaining the implementation at the top). + + Optimisation (by AIS) + +When I got my C-INTERCAL distribution, it only had a rudimentary +optimiser. Constant folding had already been done, and the following +optimisations. The following is mixed INTERCAL and C, sometimes in the same +statement. It should be clear from context and whether I have used INTERCAL +spark-ears or C brackets which language is which, although in some places I've +mixed them. Note that the optimizer is only run in binary. + +Optimizations available with -O + +Optimisations that had already been done + +Constant folding +'Vx$y'~"#0x55555555" into (x | y) +'?x$y'~"#0x55555555" into (x ^ y) +'&x$y'~"#0x55555555" into (x & y) +(x ^ 0xFFFF) or (x ^ 0xFFFFFFFF) into ~x + +I added: + +[This list has been removed as it got out of date; see src/idiotism.oil for the +new list. Most of the idioms are due to me, a few are by Joris Huizer.] + +Optimizations available with -f (I wrote all these) + +Guard removal (if a line can't be abstained, the if(!abstained[x]) line is +removed when possible) + +Ignorance checks (if a variable can't be ignored and it can't overflow, +assignment is done with C's = rather than a function) + +Recognition of NEXT...NEXT...computed RESUME as an idiom for if() (currently +disabled because the rest of the optimiser can't handle it) + +Optimizations available with -F (I wrote this one) + +This optimization should mean that INTERCAL suddenly becomes the best language +for various benchmark programs. Basically, the file is analysed to try to +determine whether it takes no input and always produces the same output. If +that is the case, the output is simply a shell-script (with executable +permissions set and a #! line) that outputs the correct output! Therefore, the +time required for one run of the program is taken up during compilation, and +whenever the program is executed, it just copies out the predetermined +output. This means (for instance) that primes.i runs in only a fraction of a +second when optimized with -F. Of course, this tends to slow down the compiler +and often produces a large object file, which is why it has a command-line +option of its own. diff --git a/doc/convickt.1 b/doc/convickt.1 new file mode 100644 index 0000000..128050a --- /dev/null +++ b/doc/convickt.1 @@ -0,0 +1,88 @@ +.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. diff --git a/doc/ick.1 b/doc/ick.1 new file mode 100644 index 0000000..3b5f91e --- /dev/null +++ b/doc/ick.1 @@ -0,0 +1,164 @@ +.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 +, for the Debian GNU/Linux system. diff --git a/doc/ickstyle.css b/doc/ickstyle.css new file mode 100644 index 0000000..7768fd5 --- /dev/null +++ b/doc/ickstyle.css @@ -0,0 +1,24 @@ + +/* Custom styles for the C-INTERCAL manual. These are partly for a + small amount of beautification, but mostly to work around the + ugliness of the default stylesheet on at least one compiler. This + stylesheet is public domain from this comment onwards. */ + + body {text-align:justify; font-family:serif;} + pre {margin:0.5em 3em 0.5em 3em; + background-color:#F8F8F8; + border:1px solid #CCCCCC;} + pre.smallexample {font-size:75%;} + p {margin:0.5em 0em 0.5em 0em;} + li {margin:0.5em 0em 0.5em 0em;} + ul.menu li {margin:0em 0em 0em 0em;} + ul.index-cp li {margin:0em 0em 0em 0em;} + div.contents ul li {margin:0em 0em 0em 0em;} + blockquote {margin:0.5em 3em 0.5em 3em;} + dt {margin:0em 0em 0em 0em; font-weight:bold;} + dd {margin:0.5em 0em 1em 3em;} + code {background-color:#F8F8F8;} + tt {background-color:#F8F8F8;} + samp {background-color:#F8F8F8;} + table {border:1px solid #666666; background-color:#CCCCCC;} + td {border:1px solid #666666; background-color:#FFFFFF;}