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