Ticket #57772: redcsl.1

.TH REDCSL 1 "2010 October 10" "redcsl"
.
.
.SH NAME
redcsl \- Run REDUCE under CSL
.
.
.SH Synopsis
.B redcsl
[
.I command-line switches
] [
.I file ...\&
]
.
.
.SH DESCRIPTION
.I redcsl
runs REDUCE based on the 
.BR CSL
Lisp system.
.
.
.SH REDCSL Options
.TP
.I file
read input from file. 

After all other options have been processed, the files given on the rest of
the command line are read in and processed. A filename of
.B -
can be used to designate standard input.
.TP
.B -b [OIP]
tells the system to avoid any attempt to recolour prompts and input text.
It will mainly be needed on X terminals that have been set up so that they
use colours that make the defaults here unhelpful, like white-on-black.

This option can be followed by colour specifications to make things yet
more specific. It is supposed to be the idea that three colours can be
specified after it for output, input and prompts, with the letters KRGYbMCW
standing for blacK, Red, Green, Yellow, blue, Magenta, Cyan and White.

This may not fully work yet!
.TP
.BI -d " symbol[=value]"
defines Lisp symbol
.I symbol
at system start, with value 
.I value
.
.TP
.B -g
enables debugging mode.  It sets a lisp variable
.SB !*backtrace
and arranges that all backtraces are displayed notwithstanding use of
.SB errorset.
.TP
.BI \-i " imagefile\fR,\fP " \-i-
CSL and Reduce use image files to keep both initial heap images and
.I fasl
loadable modules. By default if the executable launched has some name,
say xxx, then an image file xxx.img is used. But to support greater
generality 
.B -i
introduces a new image,
.B -i-
indicates the default one and a sequence of such directives list
image files that are searched in the order given. These are read-only.
The similar option 
.B -o
equally introduces image files that are scanned for input, but that
can also be used for output. Normally there would only be one
.B -o
directive.
.TP
.BI -j " dumpfile"
dumps a record of all the files read during the Lisp run into
.I dumpfile
with a view that it can be included in a Makefile to document dependencies.
.TP
.BI -k " nnn[/ss]"
sets the size of the heap to be used.  If 
.BI -k nnn 
is given then that much
memory will be allocated and the heap will never expand.  Without this 
option a default amount is used, and (on many machines) it will grow
if space seems tight.

If this options is given as
.B -k 
.I nnn/ss
then ss is the number of CSL pages to be allocated to the Lisp stack.
The default value (which is 1) should suffice for almost all users, and
it should be noted that the C stack is separate from and independent of
this one and it too could overflow.

A suffix K, M or G on the number indicates units of kilobytes,
megabytes or gigabytes, with megabytes being the default. so
.B -k200M
might represent typical usage.
.TP
.BI -l " logfile"
sends a copy of the standard output to 
.I logfile\fR.\fP
It is very much as if the Lisp function
.SB (spool logfile)
had been invoked at the start of the run.
.TP
.B -n
ignore startup function.

Normally when the system is started it will run a 
.I restart function
as indicated in its heap image. There can be cases where a heap image has
been created in a bad way such that the saved restart function always fails
abruptly, and hence working out what was wrong becomes hard. In such cases
it may be useful to give the
.B -n
options that forces CSL to ignore any startup function and merely begin
in a minimal Lisp-style read-eval-print loop.
.TP 
.B -o
see 
.B -i
.TP
.B -q
quiet run: sets
.SB !*echo
to
.SB nil
and switches off garbage collector messages.
.TP
.BI -r " nnn[,mmm]"
seed random number generator.

The random-number generator in CSL is normally initialised to a value
based on the time of day and is hence not reproducible from run to run.
In many cases that behavious is desirable, but for debugging it can be useful
to force a seed. The directive
.B -r 
.I nnn[,mmm]
sets the seed to up to 64 bits taken from the values 
.I nnn 
and 
.I mmm. 
THe second value is optional, and specifying 
.B -r0
explicitly asks for the non-reproducible behaviour (I hope). Note that
the main Reduce-level random number source is coded at a higher level
and does not get reset this way - this is the lower level CSL
generator.
.TP 
.B -s
sets the Lisp variable 
.SB !*plap
and hence the compiler generates an assembly listing.
.TP
.BI -t " name"
reports the time-stamp on the named module, and then exits. This is
for use in perl scripts and the like, and is needed because the stamps
on modules within an image or library file are not otherwise instantly
available.

Note that especially on windowed systems it may be necessary to use
this with 
.BI -- " filename"
since the information generated here goes to the default output, which
in some cases is just the screen.
.TP
.BI -u " symbol"
forcibly undefine a Lisp symbol. There are probably very very few
cases where it is useful since I do not have a large number of
system-specific predefined names.
.TP
.B -v
An option to make things mildly more verbose. It displays more of a
banner at startup and switches garbage collection messages on.
.TP
.B -w
force console mode.

On a typical system if the system is launched it creates a new window and uses
its own windowed intarface in that. If it is run such that at startup the
standard input or output are associated with a file or pipe, or under X the
variable 
.SB DISPLAY
is not set it will try to start up in console
mode. The flag 
.B -w
indicates that the system should run in console
more regadless, while 
.B -w+
attempts a window even if that seems doomed to failure. When running
the system to obey a script it will often make sense to use the
.B -w
option. Note that on Windows the system is provided as
two separate (but almost identical) binaries. For example the file
.SB csl.exe
is linked in windows mode. A result is that if launched from the
command line it detaches from its console, and if launched by
double-clicking it does not create a console. It is in fact very ugly
when double clicking on an application causes an unwanted console
window to appear. In contrast
.SB csl.com
is a console mode version of just the same program, so when launched
from a command line it can communicate with the console in the
ordinary expected manner.
.TP
.B -z 
start without image.

When bootstrapping it is necessary to start up the system for one initial time
without the benefit of any image file at all. This option makes
this happen, so when it is specified the system starts up with a minimal
environment and only those capabilities that are present in the CSL
kernel. It will normally make sense to start loading some basic Lisp
definitions rather rapidly. The files
.SB compat.lsp
,
.SB extras.lsp 
and 
.SB compiler.lsp
have Lisp source for the main things I use, and once they are loaded
the Lisp compiler can be used to compile itself.
.TP
.B --help
It is probably obvious what this option does! But in particular it
displays an explanation of the 
.B --dump-source
option, and hence should count as a prominent and easy-to-find way of
alerting people to their rights and obligations. Note that on Windows
of the application was linked as a windows binary it carefully creates
a console to display the help text in, and organizes a delay to give
people a chance to read it.
.TP
.BI -- " filename"
If the application is run in console mode then its standard output could
be redirected to a file using shell facilities. But the
.B --
directive (followed by a file name) redirects output within the Lisp
rather than outside it. If this is done a very limited capability for
sending progress or status reports to stderr (or the title-bar when
running in windowed mode) remains via the 
.SB report!-right
function.

The 
.B -w 
option may frequently make sense in such cases, but if that
is not used and the system tries to run in a window it will create it
starting off minimised.
.