--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/interps/clc-intercal/inst/man/man1/intercalc.1p	Sun Dec 09 19:30:08 2012 +0000
@@ -0,0 +1,340 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "INTERCALC 1p"
+.TH INTERCALC 1p "2008-03-29" "perl v5.14.2" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+intercalc \- CLC\-INTERCAL desk calculator
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBintercalc\fR [options]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBintercalc\fR is a simple desk calculator, allowing the user to
+enter \s-1INTERCAL\s0 statements (to see what they do) and expressions
+(to see what value they produce); it uses an interpreter object
+from CLC-INTERCAL to provide immediate feedback.
+.PP
+The desk calculator accepts several options, some of which are documented here.
+.SS "User Interface Options"
+.IX Subsection "User Interface Options"
+.IP "\fB\-X\fR / \fB\-\-graphic\fR" 4
+.IX Item "-X / --graphic"
+Enters X\-based graphical user interface. Requires Perl-GTK. This is the
+default if Perl-GTK is installed, the environment variable \fI\f(CI$DISPLAY\fI\fR is
+set and the opening of the X display succeeds.
+.IP "\fB\-c\fR / \fB\-\-curses\fR" 4
+.IX Item "-c / --curses"
+Enters full screen, curses-based interface. This is the default if the
+X based interface cannot be started, the environment variable \fI\f(CI$TERM\fI\fR
+is set and the terminal name is known.
+.IP "\fB\-\-line\fR" 4
+.IX Item "--line"
+Enters the line-mode user interface. This is the default if the X based
+and the curses based interfaces do not work.
+.Sp
+In this mode, the program executes each line from standard input according
+to the current mode and language, and prints results to standard output.
+A line starting with a backspark is interpreted as a command to the
+calculator. Use backspark-g to \s-1GIVE\s0 \s-1UP\s0 (you'll need to do it twice), or
+backspark-h to display the ehm, help page. Things which are available
+via menu entries on the Curses and X interfaces are also available via
+the backspark. For now, you can refer to the source code for a list.
+.Sp
+Command-line editing and command history is provided by the readline
+library. Command completion works if the underlying compiler supports it
+(the compilers provided with the distributions do).
+.IP "\fB\-\-batch\fR" 4
+.IX Item "--batch"
+Avoids entering interactive mode. This is the default if the standard
+input and output are not connected to a terminal and the X based interface
+cannot be started. This mode is very similar to the line mode except that
+command-line editing and command history are not implemented. Backspark
+escapes work just the same.
+.IP "\fB\-i\fR\fItype\fR / \fB\-\-interface\fR=\fItype\fR" 4
+.IX Item "-itype / --interface=type"
+Selects the user interface \fItype\fR. Currently, only \fIX\fR, \fICurses\fR,
+\&\fILine\fR and \fINone\fR are defined, but more can be installed as compiler
+plug-ins. If the interface selected is \fINone\fR, \fBintercalc\fR will work in
+batch mode. In addition, an empty string will reinstate the default
+behaviour.
+.SS "Source language and compilation options"
+.IX Subsection "Source language and compilation options"
+.IP "\fB\-\-bug\fR=\fInumber\fR" 4
+.IX Item "--bug=number"
+Selects a different probability for the compiler bug. The compiler bug is
+implemented by initialising the compiler's state with the required probability:
+when a statement is compiled (usually at runtime), a \*(L"\s-1BUG\s0\*(R" instruction is
+emitted with the required probability. The default is 1%.
+.IP "\fB\-\-ubug\fR=\fInumber\fR" 4
+.IX Item "--ubug=number"
+Selects a probability for the unexplainable compiler bug. This is the compiler
+bug which occurs when the probability of a (explainable) compiler bug is zero.
+Only wimps would use this option. The default is 0.01%.
+.IP "\fB\-I\fR\fIpath\fR / \fB\-\-include\fR=\fIpath\fR" 4
+.IX Item "-Ipath / --include=path"
+Adds a directory before the standard search path for compiler objects
+and source code. If a file is accessible from the current directory,
+it is never searched in any include path.
+.Sp
+If this option is repeated, the given paths will be searched in the
+order given, followed by the standard paths.
+.IP "\fB\-l\fR\fIlanguage\fR / \fB\-\-language\fR=\fIlanguage\fR" 4
+.IX Item "-llanguage / --language=language"
+Selects the language to use when interpreting user input. This should
+correspond to the name of a compiler, which is an \s-1INTERCAL\s0 object
+which was originally built by \fIiacc\fR. Only the expression and
+statement parsers are used, so it is possible to test incomplete
+compilers by loading them into \fIintercalc\fR even if they don't
+work with \fIsick\fR. The default is obtained from the \fIsickrc\fR
+option \fI.INTERCALC.LANGUAGE\fR.
+.IP "\-\fB\-o\fR\fIoption\fR \-\fB\-\-option\fR=\fIoption\fR" 4
+.IX Item "--ooption ---option=option"
+Adds a language option. For example, \-\fB\-o\fR\fI3\fR selects base 3 calculation,
+and \-\fB\-o\fR\fIwimp\fR selects wimp mode. If no options are provided, and the
+default language was taken from the \fIsickrc\fR file, the default options
+are taken from the \fIsickrc\fR file. Note that if an option or a language is
+specified on the command line, the \fIsickrc\fR defaults are ignored.
+.Sp
+Unlike previous versions of \fIintercalc\fR, this version checks that the
+options make sense in the context of the calculator; for example trying
+to load a compiler as an option will cause an error, but a compiler
+extension will be \s-1OK\s0.
+.IP "\fB\-m\fR\fImode\fR / \fB\-\-mode\fR=\fImode\fR" 4
+.IX Item "-mmode / --mode=mode"
+Select operation mode. Currently, the only valid modes are \fIfull\fR,
+\&\fIexpr\fR and \fIone\fR. See \*(L"Operating Modes\*(R". If this is not specified,
+the default is taken from the \fIsickrc\fR option \fI..INTERCALC.MODE\fR.
+.SS "Misc Options"
+.IX Subsection "Misc Options"
+.IP "\fB\-r\fR\fIname\fR / \fB\-\-rcfile\fR=\fIname\fR" 4
+.IX Item "-rname / --rcfile=name"
+Executes commands from file \fIname\fR before starting to accept input.
+This option can be repeated, to execute more than one file. If it is
+not specified, the standard library, the current directory, and the
+current user's home directory are searched for files with name
+\&\fIsystem.sickrc\fR or \fI.sickrc\fR, which are then executed. The order
+for this search is: specified library (\fB\-\-include\fR), system library,
+home directory, current directory. This is different from the search
+order used when looking for objects or source code. If a directory
+contains both \fI.sickrc\fR and \fIsystem.sickrc\fR, the \fIsystem.sickrc\fR
+is executed first, followed by \fI.sickrc\fR. Also note that if the
+current directory or the home directory appear in the search path
+and contain one of these files, they will be executed twice.
+.Sp
+If filenames are explicitely specified, they must be fully qualified:
+the search path is not used to find them.
+.IP "\fB\-\-nouserrc\fR" 4
+.IX Item "--nouserrc"
+Prevents loading a user rcfile (.sickrc); also limits loading of
+system.sickrc to the first one found. This option is normally only
+used when testing the installation, to prevent interference from
+previous versions of CLC-INTERCAL.
+.SH "Operating Modes"
+.IX Header "Operating Modes"
+The calculator can operate in the following modes:
+.IP "full Fully functional \s-1INTERCAL\s0 interpreter." 5
+.IX Item "full Fully functional INTERCAL interpreter."
+The calculator can parse and execute any statement or expression.
+.Sp
+Statements are compiled as a one-statement program, and executed;
+any register value etc. will be preserved between statements, so
+entering a list of statements is equivalent to running a program
+in which all these statements are executed in sequence.
+.Sp
+It is important to note that some statements will not execute in
+the normal manner. For example, a \s-1COME\s0 \s-1FROM\s0 will be parsed but
+have no effect, unless it is something like:
+.Sp
+.Vb 1
+\&    (1) PLEASE COME FROM (1)
+.Ve
+.Sp
+which causes the calculator to hang. On the other hand, an \s-1ABSTAIN\s0 \s-1FROM\s0
+or a \s-1REINSTATE\s0 will work as expected, as will \s-1CREATE\s0 and \s-1DESTROY\s0.
+A \s-1GIVE\s0 \s-1UP\s0 does not cause the calculator to terminate. One final
+difference is that comments are not parsed, and therefore you get a
+\&\*(L"Syntax Error\*(R" from the calculator rather than a splat *000 from the
+\&\s-1INTERCAL\s0 interpreter.
+.Sp
+For expressions, the calculator READs \s-1OUT\s0 the expression's result.
+Any side effects will be remembered, so if the expression contains
+overloads they will remain to haunt the calculator.
+.IP "expr \s-1INTERCAL\s0 expression interpreter" 5
+.IX Item "expr INTERCAL expression interpreter"
+The calculator can only parse expressions or assignments. In either
+case, the calculated values are \s-1READ\s0 \s-1OUT\s0; assignments will also
+store the value to the destination, while expressions will then
+discard the result.
+.IP "oic The \fBO\fRne \fBI\fRnstruction \fBC\fRalculator." 5
+.IX Item "oic The One Instruction Calculator."
+This is something we've made
+up one early morning while discussing desk calculators (as one does).
+It is not \s-1INTERCAL\s0 at all, in fact it is inspired from the One Instruction
+Set Computer.
+.Sp
+The calculator has a number of memories (default 100 \- these can be changed
+by appending a number to the operating mode, for example \fIoic10\fR will
+use a 10\-memory calculator). These memories are identified by the letter
+\&\fBm\fR followed by a number; in the default 100\-memory version, the first two
+digits after \fBm\fR are the memory, and any subsequent digit forms part
+of the next operand. At the start, all memories are initialised to 0.
+.Sp
+Since there is only one operation, there is no need to specify it, so an
+\&\*(L"operation\*(R" is a sequence of three operands and a result. The result must
+be a memory, while each operand can be a number or a memory, with the
+limitation that consecutive numbers are acceptable only if the parser can
+determine where one ends and the next one starts. So for example \*(L"1\-0\*(R" is
+two numeric operands, 1 and \-0 (aka 0); \*(L"1.2.3\*(R" is also two operands,
+1.2 and 3; \*(L"12\*(R" is a single operand, even if you intended it to be two
+operands, 1 and 2, and even if you put spaces: \*(L"1 2\*(R" is still interpreted
+as the single operand 12.
+.Sp
+The operation performed is the difference between the first two operands,
+divided by the third. For example, the three operations:
+.Sp
+.Vb 3
+\&    7 m01 2 M01
+\&    1 m02 1 m02
+\&    m1 .5 m2 m03
+.Ve
+.Sp
+will produce results m01=3.5 ((7\-0)/2); m02=1 ((1\-0)/1); m03=3 ((3.5\-.5)/1).
+and will produce the following output if the calculator is running in batch
+mode:
+.Sp
+.Vb 3
+\&    m01                  3.5     (7 \- m01) / 2
+\&    m02                    1     (1 \- m02) / 1
+\&    m03                    3     (m01 \- .5) / m02
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \s-1INTERCAL\s0 on-line documentation, by running \fBintercalc\fR and finding the
+\&\*(L"help\*(R" menu or key (X and Curses) or backspark escape (Line and None).