%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  install.tex                 GAP documentation            Martin Schoenert
%%
%H  @(#)$Id: install.tex,v 3.19 1994/07/08 09:52:27 vfelsch Rel $
%%
%Y  Copyright (C)  1993,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
%%
%%  This file describes the installation and features of \GAP\ on various OS.
%%
%%  Currently UNIX, IBM PC compatibles under  MS-DOS,  Windows, or  OS/2, and
%%  the Atari ST under TOS on the Atari ST are available.  We hope to provide
%%  ports to DEC  VAX or  AXP systems under VMS and the Apple Macintosh under
%%  MPW soon.
%%
%%  To read about the  system you are   interested in, search for  the string
%%  'Section{GAP for <system>}', e.g., 'Section{GAP for UNIX}'.
%%
%H  $Log: install.tex,v $
%H  Revision 3.19  1994/07/08  09:52:27  vfelsch
%H  updated release number
%H
%H  Revision 3.18  1994/03/23  09:43:05  fceller
%H  changed internet address of pell
%H
%H  Revision 3.17  1993/11/09  00:08:10  martin
%H  updated installation descriptions
%H
%H  Revision 3.16  1993/05/06  11:35:47  fceller
%H  fixed a misspelling
%H
%H  Revision 3.15  1993/04/15  18:03:42  fceller
%H  added 'dehn.mth.pdx.edu'
%H
%H  Revision 3.14  1993/02/19  11:30:42  gap
%H  removed overfull hboxes
%H
%H  Revision 3.13  1993/02/19  10:48:42  gap
%H  adjustments in line length and spelling
%H
%H  Revision 3.12  1993/02/18  07:55:21  felsch
%H  some misprints removed
%H
%H  Revision 3.11  1993/02/17  15:07:32  felsch
%H  example fixed
%H
%H  Revision 3.10  1993/02/16  15:06:04  fceller
%H  fixed example, changed description of 'gapexe.next'
%H
%H  Revision 3.9  1993/02/11  15:51:53  martin
%H  updated for 3.2
%H
%H  Revision 3.8  1992/05/25  18:09:39  martin
%H  added "Upgrading GAP"
%H
%H  Revision 3.7  1992/05/22  08:58:45  martin
%H  added the sections for IBM PC compatibles
%H
%H  Revision 3.6  1992/04/09  11:36:01  martin
%H  made a few changes so that two LaTeX passes suffice
%H
%H  Revision 3.5  1992/04/07  22:48:42  martin
%H  fixed the examples
%H
%H  Revision 3.4  1992/04/02  18:03:40  martin
%H  added the banner
%H
%H  Revision 3.3  1992/03/25  15:49:27  martin
%H  changed the output of 'ls <gap-dir>/doc'
%H
%H  Revision 3.2  1992/03/23  12:37:54  martin
%H  added "Getting GAP"
%H
%H  Revision 3.1  1992/03/23  11:58:51  martin
%H  improved the installation sections
%H
%H  Revision 3.0  1991/12/27  16:10:27  martin
%H  initial revision under RCS
%H
%%
\Chapter{Getting and Installing GAP}%
\index{installation}\index{options}

{\GAP} runs on a large number of different operating systems.  It behaves
slightly  different on  each  of  those.    This chapter  describes   the
behaviour of {\GAP}, the  installation, and the options  on some of those
operating systems.

Currently it contains sections  for *UNIX*  (see  "GAP for UNIX"),  which
runs on an ever increasing number of machines, for *MS-DOS* (see "GAP for
MS-DOS"),  which  is one operating  system  on *IBM PC  compatibles*, and
*TOS*  (see "GAP for  TOS"), which is the operating system on *Atari ST*.

We hope to provide ports of  {\GAP} to  DEC  VAX or AXP systems under VMS
and the Apple Macintosh  under MPW soon.  For  other systems the  section
"Porting GAP" gives hints how to approach such a port.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Getting GAP}%
\index{ftp}

{\GAP} is distributed *free of charge*.  You can obtain  it via 'ftp' and
give it away to your colleagues.  {\GAP} is  *not*  in the public domain,
however.   In particular you are  not  allowed  to incorporate  {\GAP} or
parts thereof into a commercial product.

If you get {\GAP}, we would appreciate it if you  could notify  us, e.g.,
by  sending a short  e-mail message  to 'gap@samson.math.rwth-aachen.de',
containing your full name and address,  so that we  have a  rough idea of
the number of users.   We also hope that this number will be large enough
to  convince  various  agencies  that  {\GAP}  is  a  project  worthy  of
(financial) support.  If you publish some result that was partly obtained
using {\GAP},  we  would appreciate it  if you would cite {\GAP}, just as
you would cite another paper that you used.  Again we would appreciate if
you could inform us about such a paper.

We  distribute  the *full source*  for everything, the  C  code  for  the
kernel, the {\GAP}  code for the library, and  the {\LaTeX}  code for the
manual, which has at present about 900 pages.  So it should be no problem
to get {\GAP}, even  if  you  have a rather uncommon system.   Of course,
ports to  non UNIX  systems may require some work.  We already have ports
for IBM PC compatibles with an Intel 80386 or 80486 under MS-DOS, Windows,
or OS/2, and for the Atari ST under TOS.  We hope to provide ports to DEC
VAX or AXP systems under  VMS and the  Apple Macintosh  under  MPW  soon.
Note that about 4 MByte of main memory and a harddisk are required to run
{\GAP}.

{\GAP} 3.4 can be obtained by anonymous *ftp* from the following servers.

'samson.math.rwth-aachen.de':\\
        Lehrstuhl D fur Mathematik, RWTH Aachen, Germany,\\
        internet number 137.226.152.6,\\
        directory '/pub/gap/'.

'dimacs.rutgers.edu':\\
        DIMACS, Rutgers, New Brunswick, New Jersey,\\
        internet number 128.6.75.16,\\
        directory '/pub/gap/'.

'math.ucla.edu':\\
        Math. Dept., Univ. of California at Los Angeles,\\
        internet number 128.97.4.254,\\
        directory '/pub/gap/'.

'wuarchive.wustl.edu':\\
        Math. Archives, Washington Univ. at St. Louis,\\
        internet number 128.252.135.4,\\
        directory '/edu/math/source.code/group.theory/gap'.

'dehn.mth.pdx.edu':\\
        PSU Mathematics Department, Portland State Univ.,\\
        internet number 131.252.40.89,\\
        directory '/mirror/gap/'

'pell.anu.edu.au':\\
        School of Mathematical Sciences, Australian National Univ.,
        Canberra,\\
        internet number 150.203.33.4,\\
        directory '/pub/gap/'.

'ftp' to the server *closest*  to you, login as  user 'ftp' and give your
full e-mail address as password.  Remember when you transmit the files to
set the file transfer  type to *binary  image*,  otherwise you will  only
receive   unusable garbage.  Those   servers will always  have the latest
version of {\GAP} available.

For  users in  the United  Kingdom with Janet access  'ftp' may not work.
Please contact Derek Holt (e-mail address 'dfh@maths.warwick.ac.uk').  He
has kindly offered us to distribute {\GAP} in the United Kingdom.

The  'ftp' directory contains the  following files.  Please   check first
which files you need, to avoid transferring those that you don\'t need.

'README':\\
        the file you are currently reading.

'gap3r4p0.zoo':\\
        This  file contains the  *complete*  distribution
        of {\GAP} version 3 release 4  current patchlevel 0.
        It is a 'zoo' archive approximately 7 MByte large.

'unzoo.c':\\
        A simple 'zoo' archive extractor, which should be
        used  to  unpack  the  distribution.  The 'utils'
        subdirectory contains ready  compiled executables
        for common systems.

More files are in the following *subdirectories*:

'bin':\\
        This directory contains *executables* for systems
        that dont come with a C compiler or where another
        C compiler  produces  a  faster  executable.  The
        'KERNELS' file tells you  which  executables  are
        here.

'split':\\
        This directory contains the complete distribution
        of {\GAP} 3r4p0 in several archives.  This allows
        you to get only the  parts  that  you  are really
        interested in.  The 'SPLIT' file tells you  which
        archive contains what.

'utils':\\
        This directory contains  several  utilities  that
        you may need to get or upgrade GAP, e.g., 'unzoo'
        and  'patch'.  The  'UTILS'  file tells you which
        files are here.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Upgrading GAP}

From time  to  time we  will  *upgrade* {\GAP}.  There  are generally two
types of  upgrades.  The  major  upgrades create  new  *releases* and the
minor  are upgrades between releases.  New releases usually introduce new
features while upgrades  between releases  usually only fix bugs found in
one release.

Each version  has  a  number.  The number of  a  release consists of  two
parts.  The first  part is  the  *version number*,  which is currently 3.
The  second part  is  the *release  number*,  which  is  1 for  the first
release, 2 for  the second, and so on.  The current number is  *version 3
release  4*, which we  sometimes abbreviate  to  'V3R4'.  The number of a
upgrade between releases consists of three  parts.  The first and  second
part are the  version and release  number  of  the  current release.  The
third part is called the *patchlevel*.  The first upgrade after a release
has patchlevel 1, the second patchlevel 2, and so on.  The current number
is *version 3 release  4 patchlevel 0*, which we sometimes abbreviate  to
'V3R4P0'.

Because  it might  be  too  much work for  you  to   obtain the  complete
distribution for every upgrade, we also make  the differences between one
upgrade and  the next one  available.  They are stored  in a single file,
called an *upgrade file*.   For example the differences between  'V3R4P0'
and 'V3R4P1' will be stored in a file called 'upg3r4p1.dif'.

Note that upgrade files always take you from one version to the next.  So
to upgrade to  'V3R4P2'  you  must first  upgrade  to 'V3R4P1'.

To make it easier for you to apply an upgrade, the upgrade files are in a
special format, called (unified) 'diff', which a  special program, called
'patch',  can   understand.    'patch'   reads   the   upgrade  file  and
automatically makes all the necessary changes to the files.  This program
is  available on  most UNIX machines.  However, we also make it available
on the 'ftp' servers, so  you can get it from there  if your machine does
not have one or if your machine  has one  that is  too  old to understand
unified 'diff'-s.

To apply an upgrade you need the sources for the parts of {\GAP} that you
are interested in.  This should at least be the sources, the library, and
the documentation.  You may also have  the groups  library, the primitive
groups library,  the 2-groups library, and  the character table  library.
If  an upgrade changes  a file in one of the  parts that you do not have,
'patch'  will ask you about the file it  cannot find.  Then  you can tell
'patch' to ignore this change, and it will continue to change those files
it can find.

In  the following example,  we assume that  you (as user 'you') have  all
parts of {\GAP}, that {\GAP}  is installed in  the subdirectory 'gap/' of
your homedirectory, and that you want to upgrade from 'V3R1' to 'V3R1P1'.

The first thing  of course is to get the upgrade file.  The upgrade files
are available at  the  same  places as the rest  of {\GAP} (see  "Getting
GAP").  If you are subscribed to the  {\GAP}-forum, you will also get the
upgrade  files as  e-mail messages.   In this example we will assume that
you have obtained the upgrade file  'upg3r1p1.dif'  from one of the 'ftp'
servers.

|    you@ernie:~/gap > ls -l
    drwxr-xr-x  2 you          1536 May 25 18:03 doc
    drwxr-xr-x  2 you           512 May 25 18:03 grp
    drwxr-xr-x  2 you          1536 May 25 18:02 lib
    drwxr-xr-x  2 you          1536 May 25 18:01 src
    drwxr-xr-x  2 you          1536 May 25 18:04 tbl
    drwxr-xr-x  2 you          1024 May 25 18:04 two
    -rw-r--r--  1 you        123695 May 25 18:04 upg3r1p1.dif
    you@ernie:~/gap > |

The first thing that you should do is always to read the beginning of the
upgrade file.  It contains instructions on how to apply the upgrade.  You
should always read this  to see if there are special  things that must be
done before  this  upgrade can be applied.  For  example, before  you can
apply the upgrade from 'V3R1P1' to 'V3R1P2' you must first make a copy of
the file  'src/system.st'.  In our example, i.e., the upgrade from 'V3R1'
to 'V3R1P1' no special tasks must be performed.

Now you apply the upgrade with the following command.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif
    Hmm...  Looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !What is this file?
    !==================

    # 'patch' prints the introduction text, about 200 lines long

    !Now for the upgrade itself
    !==========================
    !
    !diff -u doc/aboutgap.tex doc/aboutgap.tex
    !--- doc/aboutgap.tex   Thu Apr  9 14:06:31 1992
    !+++ doc/aboutgap.tex   Thu Apr 30 14:38:06 1992
    --------------------------
    Patching file doc/aboutgap.tex using Plan A...
    Hunk |'\#'|1 succeeded at 6.
    Hunk |'\#'|2 succeeded at 13.
    Hunk |'\#'|3 succeeded at 493.
    Hunk |'\#'|4 succeeded at 529.
    Hunk |'\#'|5 succeeded at 1074.
    Hunk |'\#'|6 succeeded at 5168.
    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u doc/aggroup.tex doc/aggroup.tex
    !--- doc/aggroup.tex    Thu Apr  9 14:06:33 1992
    !+++ doc/aggroup.tex    Thu Apr 30 14:20:05 1992
    --------------------------
    Patching file doc/aggroup.tex using Plan A...
    Hunk |'\#'|1 succeeded at 2.
    Hunk |'\#'|2 succeeded at 10.
    Hunk |'\#'|3 succeeded at 336.
    Hunk |'\#'|4 succeeded at 2708.

    # similar output for 70 more files, about 700 lines

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u src/word.h src/word.h
    !--- src/word.h Fri Apr  3 20:56:34 1992
    !+++ src/word.h Wed Apr 29 13:28:43 1992
    --------------------------
    Patching file src/word.h using Plan A...
    Hunk |'\#'|1 succeeded at 3.
    done
    you@ernie:~/gap > |

See below about the  things that  could go wrong.  For the moment we will
assume that everything worked, i.e., that 'patch' did not complain.

Next compile  the  source  of the  kernel   again.  How  this is  done is
described in  the installation  sections  (see "Installation  of GAP  for
UNIX").  Note that it  may not be  necessary to do this  if the source of
the kernel did  not change, or  if the changes  were only  cosmetic.  The
introduction of the upgrade file will tell you  if it is really necessary
or not.

Then   {\LaTeX} the  documentation  again.    How  this is  done is  also
described   in the installation sections   (see "Installation  of GAP for
UNIX", "Installation of GAP for MS-DOS",  "Installation of GAP for TOS").
Again this may not be  necessary, if the changes to  the manual were only
minor.  Again the introduction of the upgrade file will tell you if it is
really necessary or not.

Now you may want to throw away the original files.  'patch' saves them by
appending the suffix '.orig' to the original file name.  So to remove all
original files issue the following command.

|    you@ernie:~/gap > rm -f */*.orig
    you@ernie:~/gap > |

There are several things that can go wrong.

The first possibility is that you don\'t  have 'patch'.  In this case get
'patch', for example by anonymous 'ftp' from 'samson.math.rwth-aachen.de'
(Internet number 137.226.152.6).

Another possibility is that  you  have a version  of 'patch' that  is too
old.   Versions  of  'patch'  before  2.0.2.0  (patchlevel  12u4)  don\'t
understand the unified 'diff' format of this upgrade file.  In this  case
you will see the following message.

|    you@ernie:~/gap > patch -p0 < upg3r1.dif
    Hmm...  I can't seem to find a patch in there anywhere.
    you@ernie:~/gap > |

To solve this problem, get a newer version of 'patch'.   For  example  by
anonymous 'ftp' from 'samson.math.rwth-aachen.de'.

Another possibility is that you forgot the '-p0' option for 'patch'.   In
this case 'patch' assumes  that the files to patch are all in the current
directory (not in the subdirectories 'doc', 'grp', etc.).  It can\'t find
them there of course.  Therefore it asks you for the names  of  the files
to patch interactively.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif
    Hmm...  Looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !What is this file?
    !==================

    # 'patch' prints the introduction text, about 200 lines long

    !Now for the upgrade itself
    !==========================
    !
    !diff -u doc/aboutgap.tex doc/aboutgap.tex
    !--- doc/aboutgap.tex   Thu Apr  9 14:06:31 1992
    !+++ doc/aboutgap.tex   Thu Apr 30 14:38:06 1992
    --------------------------
    File to patch: |

Stop 'patch' by hitting <ctr>-'C', and  start it anew, this time with the
option '-p0'.

Another possibility is that you already  changed a file.  For  example if
you already changed 'word.c', which could not be  compiled with GNU cc on
the NeXT, you will get  the  following  message (note  the  message  that
hunk '\#3' failed).

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif

    # the usual output from 'patch'

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u src/word.c src/word.c
    !--- src/word.c Sun Apr  5 23:29:44 1992
    !+++ src/word.c Wed Apr 29 13:28:43 1992
    --------------------------
    Patching file src/word.c using Plan A...
    Hunk |'\#'|1 succeeded at 3.
    Hunk |'\#'|2 succeeded at 10.
    Hunk |'\#'|3 failed at 2094.
    Hunk |'\#'|4 succeeded at 2218.
    Hunk |'\#'|5 succeeded at 2469.
    1 out of 5 hunks failed--saving rejects to src/word.c.rej

    # the rest of the output from 'patch'

    you@ernie:~/gap > |

In this case examine the '\*.rej' files  carefully after running 'patch'.
They will tell you what 'patch' expected to find in the file, and what it
really  found.   Then  examine the  source file itself to see if  you can
ignore the rejection, or if you should apply the patch manually.

Another  possibility is that 'patch'  cannot  find the  files  it  should
patch.   For example,  if you  don\'t have  the  groups library installed
'patch' will give the following output.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif

    # the usual output from 'patch'

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u grp/permgrp.grp grp/permgrp.grp
    !--- grp/permgrp.grp  Tue Apr  7 22:39:12 1992
    !+++ grp/permgrp.grp  Thu Apr 30 13:14:12 1992
    --------------------------
    File to patch: |

Simply type <return> to this question.  'patch' will ask you then.

|    No file found--skip this patch? [n] |

Answer with 'y<return>', i.e., tell 'patch' to ignore this file.  'patch'
will then show the following output.

|    Skipping patch...
    Hunk |'\#'|1 ignored at 2.
    Hunk |'\#'|2 ignored at 9.
    Hunk |'\#'|3 ignored at 83.
    3 out of 3 hunks ignored--saving rejects to grp/permgrp.grp.rej
    patch: can't create grp/permgrp.grp.rej,
           output is in /tmp/patchra22700. |

Then it will continue to apply the other patches.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for UNIX}%
\index{BSD}\index{4.2BSD}\index{4.3BSD}\index{ULTRIX}%
\index{System V}\index{SysV}\index{HP-UX}\index{SunOS}%

{\GAP} runs very well under UNIX.  In fact  it is being developed on UNIX
workstations.   {\GAP} running on any UNIX machine  should behave exactly
as described in the manual.

{\GAP} has successfully been compiled and installed on the following UNIX
machines.

|    Vendor,  Model,            Processor,  System,      Compiler
    DEC,     DECstation 3100,  MIPS R2000, Ultrix 4.0,  cc and GNU gcc
    DEC,     DECstation 5120,  MIPS R3000, Ultrix 4.2,  cc and GNU gcc
    HP,      HP 9000/825,      HP-PA 1.0,  HP-UX 7.0,   cc
    HP,      HP 9000/720,      HP-PA 1.1,  HP-UX 8.0.5, cc
    IBM,     POWERstation 530, RS/6000,    AIX,         cc
    IBM,     PC,               i386/i486,  386BSD,      GNU gcc
    IBM,     PC,               i386/i486,  Linux,       GNU gcc
    MIPS,    M120/5,           MIPS R2000, RiscOS,      cc
    NeXT,    NeXTstation,      MC68040,    Mach,        GNU gcc
    Sequent, Symmetry,         ---,        Dynix,       cc,
    SGI,     Iris,             MIPS R3000, Irix,        cc and GNU gcc
    Sun,     Sun 3/60,         MC68020,    SunOS 4.0.1, cc and GNU gcc
    Sun,     Sun 4/280,        Sparc,      SunOS 4.0.1, cc and GNU gcc|

We hope that compiling and installing {\GAP} on another UNIX machine does
not  pose any problem.   If it does,  please  inform us of your problems,
and, if possible of your solution.

The  section "Installation of GAP   for UNIX" describes  how you  install
{\GAP}  on a UNIX  machine, and  the section "Features  of  GAP for UNIX"
describe the options that {\GAP} accepts undex UNIX.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for UNIX}%
\index{installation!under UNIX}\index{UNIX!installation}

Installation of {\GAP} for UNIX is fairly easy.

First go to the directory where you want to install  {\GAP}.  If you will
be the only user  using  {\GAP}, you probably  should  install it  in you
homedirectory.  If other  users will  be using  {\GAP} also,  you  should
install it in a public place, such as  '/usr/local/lib/'.  {\GAP} will be
installed in a subdirectory 'gap3r4p0' of this  directory.  You can later
move {\GAP} to a  different location.  For example  you can first install
it in your homedirectory and when  it works move it to '/usr/local/lib/'.
In the following example we will assume that you,  as user 'you', want to
install {\GAP} for your own  use in  your  homedirectory on a  DECstation
called 'ernie'.   Note that certain  parts of the  output in the examples
should  only be  taken as rough  outline,  especially file sizes and file
dates are *not* to be taken literally.

Get the distribution 'gap3r4p0.zoo'  and the source for  the zoo  archive
extractor 'unzoo.c'.  How  you can get those  files is  described  in the
section "Getting GAP".  The usual way would be to  get it with 'ftp' onto
your  machine.  Remember that the distribution  consists of  binary files
and that you must transmit them in binary mode.

Compile the zoo archive extractor 'unzoo' with the command

|    you@ernie:~ > cc  -o unzoo  -DSYS_IS_UNIX  -O unzoo.c
    you@ernie:~ > ls -l unzoo
    -rwxr-xr-x     you       45056 Nov  3 10:11 unzoo
    you@ernie:~ > |

Unpack the distribution with the command

|    you@ernie:~ > unzoo -x gap3r4p0.zoo
    gap3r4p0/bin/gap.sh      -- extracted as text
    gap3r4p0/doc/aboutgap.tex        -- extracted as text
    gap3r4p0/doc/aggroup.tex         -- extracted as text
    # about 500 more lines
    gap3r4p0/two/twogpd8.grp         -- extracted as text
    you@ernie:~ > |

Change  into the source directory  'gap3r4p0/src/' and  execute 'make' to
see which compilation targets are predefined.

|    you@ernie:~ > cd gap3r4p0/src
    you@ernie:~/gap3r4p0/src > make
    usage: 'make <target>' where target is one of
    'atari-m68k-tos-gcc2'   for Atari ST under TOS with GNU cc 2
    'dec-mips-ultrix-gcc2'  for DECstation under Ultrix with GNU cc 2
    'dec-mips-ultrix-cc'    for DECstation under Ultrix with cc
    'hp-hppa1.0-hpux-cc'    for HP 9000/800 under HP-UX with cc
    'hp-hppa1.1-hpux-cc'    for HP 9000/700 under HP-UX with cc
    'ibm-power-aix-cc'      for IBM RS/6000 under AIX with cc
    'ibm-i386-386bsd-gcc2'  for IBM PC under 386BSD with GNU cc 2
    'ibm-i386-386bsd-cc'    for IBM PC under 386BSD with cc (GNU)
    'ibm-i386-linux-gcc2'   for IBM PC under Linux with GNU cc 2
    'ibm-i386-msdos-djgpp'  for IBM PC under MSDOS with DJ GNU cc
    'ibm-i386-os2-emx'      for IBM PC under OS/2 with EMX GNU cc
    'mips-mips-bsd-cc'      for MIPS under RISC/os Berkeley with cc
    'mips-mips-sysv-cc'     for MIPS under RISC/os System V with cc
    'next-m68k-mach-gcc2'   for NeXT under Mach with GNU cc 2
    'next-m68k-mach-cc'     for NeXT under Mach with cc (GNU)
    'sequent-i386-dynix-cc' for Sequent Symmetry under Dynix with cc
    'sgi-mips-irix-gcc2'    for SGI under Irix with GNU cc 2
    'sgi-mips-irix-cc'      for SGI under Irix with cc
    'sun-m68k-sunos-gcc2'   for SUN 3 under SunOs with GNU cc 2
    'sun-m68k-sunos-cc'     for SUN 3 under SunOS with cc
    'sun-sparc-sunos-gcc2'  for SUN 4 under SunOs with GNU cc 2
    'sun-sparc-sunos-cc'    for SUN 4 under SunOS with cc
    'bsd'                   for others under Berkeley UNIX with cc
    'usg'                   for others under System V UNIX with cc
       targets are listed according to preference, i.e.,
       'sun-sparc-sunos-gcc2' is better than 'sun-sparc-sunos-cc'.
       additional C compiler and linker flags can be passed with
       'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
       i.e., 'make sun-sparc-sunos-gcc2 COPTS=-g LOPTS=-g.'
    you@ernie:~/gap3r4p0/src > |

Choose the best matching target.  If nothing matches precisely, use 'bsd'
(if your UNIX is more Berkeley) or 'usg' (if your UNIX is more System V).
If compilation of  the file 'system.c' fails  or the command line editing
does not work, remove the file 'system.o' and try  the  other target.  If
'system.c' cannot be compiled neither  with target  'bsd' nor with target
'usg', look at this file and try to modify it so that  compilation works.
If you can compile  but command line  editing  does not  work with either
target,  we suggest  that  you always  start  {\GAP}  with option '-n' to
disable  command line editing.  In  any case we would  like to hear about
such problems.

In  our  example the   right  target  is  obviously  'dec-mips-ultrix-cc'
(remember 'ernie' was assumed to be a DECstation).  Compile {\GAP}.

|    you@ernie:~/gap3r4p0/src > make dec-mips-ultrix-cc
    cc -DSYS_IS_BSD -DSYS_HAS_ANSI=1 -c system.c
    cc -O2 -c gap.c
    # about 30 more lines
    you@ernie:~/gap3r4p0/src > ls -l gap
    -rwxr-xr-x     you      711620 Nov 13 12:47 gap
    you@ernie:~/gap3r4p0/src > |

You may  want to keep  the source and  object files around until  you are
certain that  everything works.  However if space  is a tight resource on
your system you may remove the source and object files now.  All you need
in the 'src/' subdirectory from now on is (are) the executable(s).

Copy or move the executable to  the 'gap3r4p0/bin/' directory.

|    you@ernie:~/gap3r4p0/src > mv gap ../bin
    you@ernie:~/gap3r4p0/src > cd ../..
    you@ernie:~ > |

Then  edit the shell   script 'gap.sh'  in the 'gap3r4p0/bin/'  directory
according  to the instructions  in this  file.    This script will  start
{\GAP}  and is  the place  for all neccessary  configurations.  Then copy
this script to a directory in your search path,  i.e., '~/bin/'.  (If you
are using  the C-shell, you   will also  have  to  'rehash', so that  the
C-shell adds 'gap' to its internal tables).

|    you@ernie:~ > cd gap3r4p0/bin
    you@ernie:~/gap3r4p0/bin > cp gap.sh ~/bin/gap
    you@ernie:~/gap3r4p0/bin > cd ../..
    you@ernie:~ > |

When  you later move  {\GAP} to another location you  must only edit this
script.

Now start {\GAP}  and try a few things.   The '-b' option suppresses  the
banner.  Note that {\GAP} has to read most of  the library for the fourth
statement below, so this takes quite a  while.  Subsequent definitions of
groups will be much faster.

|    you@ernie:~ > gap -b
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    gap> Factors( 10^42 + 1 );
    [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
    gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
    gap> Size( m11 );
    7920
    gap> Factors( 7920 );
    [ 2, 2, 2, 2, 3, 3, 5, 11 ]
    gap> Number( ConjugacyClasses( m11 ) );
    10 |

Especially try the  command line  editing and history facilities, because
the are probably the most machine dependent  feature of {\GAP}.   Enter a
few  commands and  then  make  sure  that <ctr>-'P'   redisplays the last
command, that  <ctr>-'E' moves the cursor to  the  end of  the line, that
<ctr>-'B' moves the cursor back one character, and that <ctr>-'D' deletes
single characters.  So, after entering the above commands, typing\\
<ctr>-'P' <ctr>-'P' <ctr>-'E' <ctr>-'B' 
<ctr>-'B' <ctr>-'B' <ctr>-'B' <ctr>-'D' '1'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If command line editing does not work, remove the file 'system.o' and try
to compile with a different target, i.e., 'bsd' instead of  'usg' or vice
versa.  If  neither works,  we   suggest that  you  disable command  line
editing  by calling {\GAP}  always with the '-n' option.   In any case we
would like to hear about such problems.

If your operating  system has job control, make  sure that  you can still
stop {\GAP}, which is usually done by pressing <ctr>-'Z'.

If you have a big version of {\LaTeX} available, you may now want to make
a printed copy of the  manual.  Change into the directory 'gap3r4p0/doc/'
and run {\LaTeX} *twice* on  the source.  The   first pass with  {\LaTeX}
produces the '.aux'  files, which resolve  all the cross references.  The
second pass  produces the final formatted  *dvi* file 'manual.dvi'.  Then
print the  *dvi*  file.  How  this is done  depends on  your local {\TeX}
installation, if in doubt ask your local computer guru.

|    you@ernie:~ > cd gap3r4p0/doc
    you@ernie:~/gap3r4p0/doc > latex manual
    # about 2400 messages about undefined references
    you@ernie:~/gap3r4p0/doc > latex manual
    # there should be no warnings this time
    you@ernie:~/gap3r4p0/doc > ls -l manual.dvi
    -rw-r--r--     you    2806136 Nov  3 23:28 manual.dvi
    you@ernie:~/gap3r4p0/doc > lp -dvi manual.dvi
    you@ernie:~/gap3r4p0/doc > cd ../..
    you@ernie:~ > |

Note that because  of the large number  of cross references in the manual
you need a *big*  {\LaTeX} to format  the {\GAP} manual.   If you see the
error message 'TeX capacity exceeded',  you do not  have a big  {\LaTeX};
again ask your local computer guru to  provide a big version of {\LaTeX}.
If this is not possible, you may  also obtain the already formatted *dvi*
file 'manual.dvi' from the same place where  you obtained the rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    you@ernie:~ > cd gap3r4p0/doc
    you@ernie:~/gap3r4p0/doc > latex manual
    # about 2000 messages about undefined references
    you@ernie:~/gap3r4p0/doc > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    you@ernie:~/gap3r4p0/doc > latex manual
    # still some messages about undefined citations
    you@ernie:~/gap3r4p0/doc > makeindex manual
    # 'makeindex' prints some diagnostic output
    you@ernie:~/gap3r4p0/doc > latex manual
    # there should be no warnings this time
    you@ernie:~/gap3r4p0/doc > lp -dvi manual.dvi
    you@ernie:~/gap3r4p0/doc > cd ../..
    you@ernie:~ > |

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features of GAP for UNIX}%
\index{features!under UNIX}\index{UNIX!features}%
\index{options!under UNIX}\index{UNIX!options}%
\index{.gaprc}

When you start {\GAP}  for UNIX, you may  specify a number of  options on
the command-line to change  the default behaviour  of {\GAP}.  All  these
options  start with a  hyphen '-', followed by a  single letter.  Options
must not be   grouped, e.g.,  'gap  -gq' is   illegal, use   'gap -g  -q'
instead.  Some options  require an argument, this  must follow the option
and  must be separated   by a <space>, e.g.,  'gap   -m 256k', it is  not
correct to say 'gap -m256k' instead.

{\GAP} for UNIX will only accept lower case options.

As is  described in  the previous section  (see  "Installation of GAP for
UNIX") usually you  will not execute {\GAP}  directly.  Instead  you will
call a shell script, with the name 'gap',  which in turn executes {\GAP}.
This shell script sets some options as  neccessary to make {\GAP} work on
your  system.  This means that the   default settings mentioned below may
not be what you experience when you execute {\GAP} on your system.

'-g'

The option  '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 4096 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 4096 KBytes are available afterwards.

'-l <libname>'

The option '-l' tells {\GAP} that  the  library of {\GAP} functions is in
the directory  <libname>.  Per  default <libname>  is 'lib/',  i.e.,  the
library is normally  expected in the  subdirectory  'lib/' of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to  {\GAP}, in this
directory.   <libname> should end with  a  pathname separator, i.e., '/',
but {\GAP} will silently add one  if it is missing.  {\GAP} will read the
file '<libname>/init.g' during startup.  If {\GAP} cannot find this  file
it will print the following warning

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <lib>'?|

If you want  a bare bones {\GAP},  i.e., if you do  not need  any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start it  again, specifying the  correct library path using the  '-l'
option.

It  is also possible to   specify several alternative  library pathes  by
separating them with  semicolons ';'.   Note that in  this  case all path
names must end with the pathname  separator '/'.  {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds. E.g., if  you specify  |-l "lib/;/usr/local/lib/gap3r4p0/lib/"|
{\GAP} will search for a library file first in the subdirectory 'lib/' of
the current directory, and if it does not find  it there in the directory
|/usr/local/lib/gap3r4p0/lib/|. This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP} searches  for the group files,  whose filenames end in '.grp', and
which contain the groups initially known  to {\GAP}, in the directory one
gets  by replacing the  string 'lib' in  <libname> with the string 'grp'.
If you  do not  want  to  put  the group   directory  'grp/' in  the same
directory as the  'lib/' directory, for  example if you want  to  put the
groups onto another hard disk partition,  you have to edit the assignment
in '<libname>/init.g' that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of 'lib/' is replaced by 'grp/'.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The option '-h'  tells {\GAP} that the on-line documenation for {\GAP} is
in  the  directory  <docname>.  Per  default  <docname>  is  obtained  by
replacing 'lib'  in  <libname> with  'doc'.   <docname> should end with a
pathname  separator, i.e., '/', but {\GAP} will silently add one if it is
missing.  {\GAP} will read the file '<docname>/manual.toc' when you first
use the help system.  If  {\GAP} cannot find this file it will print  the
following warning

|    help: hmm, I cannot open the table of contents file 'doc/manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to allocate <memory>  bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

Under UNIX the default amount  of memory allocated  by {\GAP} is 4 MByte.
The amount of memory  should be large  enough so that computations do not
require  too  many  garbage  collections.  On the   other hand  if {\GAP}
allocates more virtual memory than  is physically available it will spend
most of  the  time  paging.   4 MByte    is  reasonable for  single  user
workstations with 8 MByte or for multi user systems with more.

'-n'

The option  '-n'  tells {\GAP}  to disable  the line editing  and history
(see "Line Editing").

You may want to do this if the command line  editing is incompatible with
another program that is used to run {\GAP}.  For example if {\GAP} is run
from inside a GNU Emacs shell window, '-n' should be used since otherwise
every input line will be echoed twice, once by Emacs and once by {\GAP}.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The option  '-q' tells {\GAP} to  be quiet.  This  means that {\GAP} does
not display the  banner and the prompts  'gap>'.  This is  useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this option  you can tell  {\GAP}  how long lines  are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80, which is the right value if you have  a standard
ASCII terminal.  If you have a larger monitor, or use a  smaller font, or
redirect the output to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is 24, which is the right  value if you have a standard
ASCII terminal.  If you have a larger monitor, or use  a smaller font, or
redirect the output to a printer, you may want to increase this value.

Further arguments are taken as filenames of files that are read by {\GAP}
during  startup, after '<libname>/init.g' is read, but  before the  first
prompt is printed.  The files are read  in the order  in that they appear
on  the command line.  {\GAP} only accepts  14  filenames  on the command
line.  If a file cannot be opened {\GAP} will print  an error message and
will abort.

When you  start {\GAP}, it looks  for the file  with the name '.gaprc' in
your  homedirectory.  If   such  a file   is    found it  is  read  after
'<libname>/init.g', but before any of the files  mentioned on the command
line are read.  You  can use this  file  for your private customizations.
For example,  if you have a  file containing functions  or  data that you
always need, you could read this from '.gaprc'.  Or if  you  find some of
the names  in the library too  long, you could  define  abbreviations for
those names in '.gaprc'.  The following sample '.gaprc' file does both.

|    Read("/usr/you/dat/mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for MS-DOS}%
\index{GAP for MS-DOS}\index{MSDOS}\index{Windows}

This  sections contain information about  {\GAP} that is  specific to the
port  of {\GAP} for IBM PC   compatibles under MS-DOS  or Windows (simply
called {\GAP} for MS-DOS below).

To run  {\GAP} for MS-DOS  you  need an IBM PC   compatible with an Intel
80386, Intel 80486, or Intel Pentium processor, it will not run on IBM PC
compatibles with  an Intel 80186  or  Intel 80286 processor.   The system
must have at least 4 MByte of main  memory and a harddisk.  The operating
system  must be  MS-DOS version  5.0  or later  or Windows  3.1  or later
(earlier versions may work, but this has not been tested).

The section "Copyright of GAP  for MS-DOS" describes  the copyright as it
applies  to the  executable version  that  we  distribute.  The   section
"Installation  of GAP  for MS-DOS"  describes how you  install {\GAP} for
MS-DOS, and  the section "Features    of GAP for  MS-DOS" describes   the
special features of {\GAP} for MS-DOS.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Copyright of GAP for MS-DOS}

In  addition  to the  general copyright   for  {\GAP} set  forth  in  the
Copyright the following terms apply to {\GAP} for MS-DOS.

The system  dependent part  for {\GAP}  for MS-DOS was  written  by Steve
Linton   (111  Ross St.,  Cambridge,  CB1    3BS,  UK, +44   223  411661,
'sl25@cus.cam.ac.uk').  He assignes the copyright to the Lehrstuhl D fuer
Mathematik.  Many thanks to Steve Linton for his work.

The executable of {\GAP} for MS-DOS that  we distribute was compiled with
DJ Delorie\'s  port  of the  Free  Software Foundation\'s GNU  C compiler
version 2.4.   The  compiler  can be  obtained  by  anonymous  'ftp' from
'grape.ecs.clarkson.edu' where  it is in the directory 'pub/msdos/djgpp'.
Many thanks to  the Free  Software Foundation and   DJ Delorie  for  this
amazing piece of work.

The GNU C compiler is

*Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA*

under the  terms  of the GNU General Public License (GPL).  Note that the
GNU  GPL  states  that the  mere act  of compiling  does not  affect  the
copyright status of {\GAP}.

The modifications to the compiler to make it operating under  MS-DOS, the
functions from  the standard library 'libpc.a', the  modifications of the
functions from the standard library  'libc.a' to make  them operate under
MS-DOS, and the DOS extender  'go32' (which is prepended to 'gapexe.386')
are

*Copyright (C) 1991 DJ Delorie,
24 Kirsten Ave, Rochester NH 03867-2954, USA*

also under the terms of  the GNU GPL.  The  terms of the GPL require that
we make the source code for 'libpc.a' available.  They can be obtained by
writing to Steve Linton (however, it may be easier for  you to 'ftp' them
from 'grape.ecs.clarkson.edu' yourself).  They  also require  that {\GAP}
falls under the GPL too, i.e.,  is distributed freely, which it basically
does anyhow.

The functions in 'libc.a' that {\GAP} for the 386 uses are

*Copyright (c) 1988 Regents of the University of California*

under the following terms

*All rights reserved.*

*Redistribution and use in source and binary forms are permitted provided
that the above copyright notice and this paragraph are  duplicated in all
such forms and that  any documentation, advertising  materials, and other
materials  related to  such  distribution and  use acknowledge  that  the
software  was developed by  the University of California, Berkeley.   The
name  of the University  may not be  used to endorse or promote  products
derived from this software without specific prior written permission.*

*THIS  SOFTWARE  IS  PROVIDED AS IS  AND WITHOUT  ANY EXPRESS OR  IMPLIED
WARRANTIES,  INCLUDING,  WITHOUT  LIMITATION, THE  IMPLIED WARRANTIES  OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.*

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for MS-DOS}%
\index{installation!under MS-DOS}\index{MS-DOS!installation}
\index{installation!under Windows}\index{Windows!installation}

Installation of {\GAP} on IBM PC compatibles is fairly  easy.  As already
mentioned above,  {\GAP} must  be installed on a harddisk,  because it is
too large to be run from floppy disks.

First go to a directory where  you  want to install  {\GAP}, e.g., |c:\|.
{\GAP} will be installed in a subdirectory |gap3r4p0\| of this directory.
You can later move {\GAP} to another location, for  example you can first
install it in  |d:\tmp\| and once  it works move it  to  |c:\|.   In  the
following  example we assume that  you want  to install {\GAP} in  |c:\|.
Note that  certain parts of  the output in the examples  should  only  be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

Get  the {\GAP} distribution onto your IBM PC  compatible.  One usual way
would be  to get the  distribution  with 'ftp' onto some UNIX workstation
and to download it from there onto your  IBM  PC  compatible, for example
with 'kermit'.  Remember  that the distribution  consists of binary files
and that you must transmit them  in binary  mode.  Another possibility is
that you got a set of floppy disks.

If you  get the  distribution via   'ftp', you must get the  distribution
'gap3r4p0.zoo',  the  zoo archive  extractor  'unzoo-ibm-i386-msdos.exe',
which is   in the subdirectory  'util' and   which   you should rename to
'unzoo.exe', and the  executable 'bin3r4p0-ibm-i386-msdos.zoo',  which is
in the subdirectory 'bin' and which you  should rename to 'bin3r4p0.zoo'.
You may have to get the latter 2 files from 'samson.math.rwth-aachen.de',
because some 'ftp' servers may  not keep it.   We recommend that  you use
'unzoo' even if you already  have  'zoo' on  your system, because 'unzoo'
automatically translates text files to the appropriate local format.

If you got  the  distribution via 'ftp'  unpack  the  executable and  the
distribution with the following commands

|    C: > unzoo -x bin3r4p0.zoo
    gap3r4p0\bin\README.DOS  -- extracted as text
    gap3r4p0\bin\gap.bat     -- extracted as text
    gap3r4p0\bin\gapdjg.exe  -- extracted as binary
    C: > unzoo -x gap3r4p0.zoo
    gap3r4p0\bin\gap.sh      -- extracted as text
    gap3r4p0\doc\aboutgap.tex        -- extracted as text
    gap3r4p0\doc\aggroup.tex         -- extracted as text
    # about 500 more lines
    gap3r4p0\two\twogpd8.grp         -- extracted as text
    C: > |

If you got the executable and the distribution on  disks, you must unpack
them with the following comands (assuming that your disk drive is |A:|)

|   C: > rem Insert the 1. disk.
    C: > copy a:\unzoo.exe .
    C: > unzoo -x a:\bin3r4p0.zoo
    gap3r4p0\bin\README.DOS  -- extracted as text
    gap3r4p0\bin\gap.bat     -- extracted as text
    gap3r4p0\bin\gapdjg.exe  -- extracted as binary
    C: > unzoo -x a:\etc3r4p0.zoo
    gap3r4p0\etc\README      -- extracted as text
    # about 20 more messages
    C: > unzoo -x a:\grp3r4p0.zoo
    gap3r4p0\grp\basic.grp   -- extracted as text
    # about 10 more messages
    C: > unzoo -x a:\lib3r4p0.zoo
    gap3r4p0\lib\abattoir.g  -- extracted as text
    # about 77 more messages
    C: > rem Insert the 2. disk.
    C: > unzoo -x a:\doc3r4p0.zoo
    gap3r4p0\doc\about.tex   -- extracted as text
    # about 65 more messages
    C: > unzoo -x a:\two3r4p0.zoo
    gap3r4p0\two\twogp.grp
    # about 25 more messages
    C: > unzoo -x a:\thr3r4p0.zoo
    gap3r4p0\thr\thrgp.grp
    # about 10 more messages
    C: > rem Insert the 3. disk.
    C: > unzoo -x a:\tbl3r4x1.zoo
    gap3r4p0\tbl\ctbalter.tbl
    # about 50 more messages
    C: > rem Insert the 4. disk.
    C: > unzoo -x a:\tbl3r4x2.zoo
    gap3r4p0\tbl\ctomonst.tbl
    # about 10 more messages
    C: > unzoo -x a:\tom3r4p0.zoo
    gap3r4p0\tom\tmaltern.tom
    # about 10 more messages
    C: > unzoo -x a:\src3r4p0.zoo
    gap3r4p0\src\Makefile    -- extracted as text
    # about 60 more messages
    C: > rem Insert the 5. disk.
    C: > unzoo -x a:\pkg3r4p0.zoo
    gap3r4p0\pkg\anupq\MakeLibrary\MakeLibray -- extracted as text
    # about 150 more messages
    C: > |

Instead of using the executable that we provide in 'bin3r4p0.zoo' you can
compile {\GAP} yourself if you have the DJGPP compiler installed.   To do
this change into  the source directory  |gap3r4p0\src| and compile {\GAP}
with the commands

|    C: > chdir gap3r4p0\src
    C:\GAP3R4P0\SRC > make ibm-i386-msdos-djgpp
    gcc -DSYS_IS_MSDOS_DJGPP -DSYS_HAS_STRING_PROTO -DSYS_HAS_STDIO_PROTO\
        -DSYS_HAS_MISC_PROTO -c system.c
    gcc -O2 -c gap.c
    # about 30 more messages
    C:\GAP3R4P0\SRC > copy gapdjg.exe ..\bin
    C:\GAP3R4P0\SRC > chdir ..\..
    C: > |

Change into the directory |gap3r4p0\bin\| and  edit the script 'gap.bat',
which starts {\GAP}, according  to the instructions in  this  file.  Then
copy  this  script to a  directory in your  search path, e.g., |c:\bin\|,
with the commands

|    C: > chdir gap3r4p0\bin
    C:\GAP3R4P0\BIN > edit gap.bat
    # edit the script 'gap.bat'
    C:\GAP3R4P0\BIN > copy gap.bat c:\bin\gap.bat
    C:\GAP3R4P0\BIN > chdir ..\..
    C: > |

When you later move {\GAP} to another  location  you must only  edit this
script.

{\GAP} must sometimes open  more than  8 files at once.  MS-DOS disallows
this, unless you add the following line to  the file 'config.sys' on your
boot drive.  You must then reboot for this change to take effect.

|    files=32 |

Start {\GAP} and try a few things.  Note that {\GAP} has  to read most of
the library for the fourth statement below,  so this takes quite a while.
Subsequent definitions of groups will be much faster.

|    C: > gap -b
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    gap> Factors( 10^42 + 1 );
    [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
    gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
    gap> Size( m11 );
    7920
    gap> Factors( 7920 );
    [ 2, 2, 2, 2, 3, 3, 5, 11 ]
    gap> Number( ConjugacyClasses( m11 ) );
    10 |

Especially try the command  line editing  and history facilities, because
the are probably the most  machine dependent feature  of {\GAP}.  Enter a
few commands   and then make  sure  that  <ctr>-'P' redisplays   the last
command, that  <ctr>-'E'  moves the cursor  to the end  of the line, that
<ctr>-'B' moves the cursor back one character, and that <ctr>-'D' deletes
single characters.  So after entering the above three commands typing\\
<ctr>-'P' <ctr>-'P' <ctr>-'E' <ctr>-'B'
<ctr>-'B' <ctr>-'B' <ctr>-'B' <ctr>-'D' '1'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If you have a big version of {\LaTeX} available  you may now want to make
a printed copy of the  manual.  Change into the directory |gap3r4p0\doc\|
and  run {\LaTeX} *twice* on the   source.  The first  pass with {\LaTeX}
produces the '.aux'  files, which resolve  all the cross references.  The
second pass produces  the final formatted  *dvi* file 'manual.dvi'.  This
will take quite a while, since the manual is large.  Then print the *dvi*
file.  How you actually print the 'dvi' file produced by {\LaTeX} depends
on the printer you  have, the version of {\LaTeX}  you have,  and whether
you use a  {\TeX}-shell  or not, so we   will not attempt to describe  it
here.

|    C: > chdir gap3r4p0\doc
    C:\GAP3R4P0\DOC > latex manual
    # about 2000 messages about undefined references
    C:\GAP3R4P0\DOC > latex manual
    # there should be no warnings this time
    C:\GAP3R4P0\DOC > dir manual.dvi
    -a---   2591132 Nov 13 23:29 manual.dvi
    C:\GAP3R4P0\DOC > chdir ..\..
    C: > |

Note that because of the large  number of  cross references in the manual
you need a *big*  {\LaTeX} to format the {\GAP}  manual.  If you  see the
error message  'TeX capacity  exceeded', you do  not have a big {\LaTeX}.
In this case  you  may also  obtain the  already    formatted *dvi*  file
'manual.dvi' from  the  same place where   you obtained the   rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    C: > chdir gap3r4p0\doc
    # about 2000 messages about undefined references
    C:\GAP3R4P0\DOC > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    C:\GAP3R4P0\DOC > latex manual
    # still some messages about undefined citations
    C:\GAP3R4P0\DOC > makeindex manual
    # 'makeindex' prints some diagnostic output
    C:\GAP3R4P0\DOC > latex manual
    # there should be no warnings this time
    C:\GAP3R4P0\DOC > chdir ..\..
    C: > |

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features of GAP for MS-DOS}
\index{features!under MS-DOS}\index{MS-DOS!features}%
\index{options!under MS-DOS}\index{MS-DOS!options}%
\index{gap.rc}\index{.gaprc}

Note that {\GAP} for MS-DOS  will use up to  128 MByte of extended memory
(using XMS, VDISK memory  allocation strategies) or  up  to 128  MByte of
expanded memory (using VCPI programs, such as QEMM  and 386MAX) and up to
128 MByte of disk space for swapping.

If you hit  <ctr>-'C'  the DOS extender  ('go32')  catches it and  aborts
{\GAP} immediately.  The keys <ctr>-'Z' and <alt>-'C' can be used instead
to interrupt {\GAP}.

The arrow keys <left>, <right>, <up>, <down>, <home>, <end>, and <delete>
can be used for command line editing with their intuitive meaning.

Pathnames may  be  given   inside {\GAP}  using  either  slash  ('/')  or
backslash (|\|) as a separator (though |\|  must be escaped in strings of
course).

When  you  start  {\GAP}  you  may specify a  number   of options  on the
command-line to  change the  default   behaviour of {\GAP}.   All   these
options start with a  hyphen '-', followed  by a single  letter.  Options
must not  be   grouped, e.g., 'gap -gq'    is illegal, use  'gap  -g  -q'
instead.  Some  options require an argument,  this must follow the option
and must   be separated by   a <space>, e.g., 'gap  -m  256k', it  is not
correct to say 'gap -m256k' instead.

{\GAP} for MS-DOS accepts the following (lowercase) options.

'-g'

The options '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 3072 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 3072 KBytes are available afterwards.

'-l <libname>'

The option '-l' tells {\GAP}  that the library  of {\GAP} functions is in
the  directory <libname>.  Per  default  <libname> is  'lib/', i.e.,  the
library  is normally expected in the subdirectory  'lib/'  of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to  {\GAP}, in this
directory.   <libname> should end  with a  pathname separator, i.e., |\|,
but {\GAP} will silently add one  if it is missing.  {\GAP} will read the
file <libname>|\init.g| during startup.  If {\GAP} cannot find this  file
it will print the following warning

|    gap: hmm, I cannot find 'lib\init.g', maybe use option '-l <lib>'?|

If you  want a bare bones {\GAP},  i.e., if you do  not  need any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start  it again, specifying the correct  library path  using the '-l'
option.

It is  also possible to  specify several  alternative library  pathes  by
separating them  with semicolons ';'.   Note that in  this  case all path
names must end with the pathname separator  |\|.  {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds.  E.g., if  you specify |-l "lib\;\usr\local\lib\gap3r4p0\lib\"|
{\GAP} will search for a library file first in the subdirectory |lib\| of
the current directory, and if it does not find it  there in the directory
|\usr\local\lib\gap3r4p0\lib\|. This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP}  searches for the group files,  whose filenames end in '.grp', and
which contain the groups initially known to  {\GAP}, in the directory one
gets by replacing the string 'lib' in <libname> by the  string 'grp'.  If
you do not want  to put the group  directory |grp\| in the same directory
as the |lib\| directory,  for example if you want  to put the groups onto
another   hard  disk  partition,  you have  to   edit the   assignment in
<libname>|\init.g| that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of |lib\| is replaced by |grp\|.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The  option '-h' tells {\GAP} that the on-line documenation for {\GAP} is
in  the directory  <docname>.   Per  default  <docname>  is  obtained  by
replacing 'lib' in <libname>  with 'doc'.   <docname> should  end  with a
pathname separator, i.e., |\|, but {\GAP} will silently  add one if it is
missing.  {\GAP} will read the file <docname>|\manual.toc| when you first
use the help system.  If {\GAP} cannot find this file  it will print  the
following warning

|    help: hmm, I cannot open the table of contents file 'doc\manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to  allocate <memory> bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

{\GAP} for MS-DOS  will by default allocate  4 MBytes of  memory.  If you
specify  '-m <memory>' {\GAP} will  only allocate that  much memory.  The
amount of  memory  should be large  enough so  that computations  do  not
require too  many garbage   collections.  On the   other  hand if  {\GAP}
allocates more virtual memory than is  physically available it will spend
most of the time paging.

'-n'

The  options  '-n' tells {\GAP} to  disable  the line editing and history
(see "Line Editing").

There does not seem to be a good reason to do this on IBM PC compatibles.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The  option '-q' tells  {\GAP} to be quiet.  This  means that {\GAP} does
not  display the banner and the  prompts 'gap>'.  This  is useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this  option you can tell  {\GAP} how long   lines are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80,  which  is correct if  you start {\GAP} from the
desktop or one of the usual shells.  However, if you  start {\GAP} from a
window shell such as 'gemini', you may want to decrease  this  value.  If
you have a larger monitor, or use a smaller font, or  redirect the output
to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is  24, which is  the right value  if  you start {\GAP}
from the desktop or one  of  the  usual shells.   However, if  you  start
{\GAP} from a window  shell such as 'gemini',   you may want  to decrease
this value.  If  you  have a larger monitor,  or use  a smaller  font, or
redirect the output to a printer, you may want to increase this value.

'-z <freq>'

{\GAP} for  MS-DOS  checks  in  regular  intervals  whether the user  has
entered    <ctr>-'Z' or <alt>-'C'  to   interrupt an ongoing computation.
Under MS-DOS this requires reading the keyboard status (UNIX on the other
hand will deliver a  signal to {\GAP}  when the user  entered <ctr>-'C'),
which   is rather expensive.   Therefor   {\GAP} only reads the  keyboard
status  every <freq>-th time.  The  default is 20.   With the option '-z'
this value  can be changed.  Lower  values make {\GAP} more responsive to
interrupts, higher values make {\GAP} a little bit faster.

Further arguments are taken as filenames of files that are read by {\GAP}
during startup, after <libname>|\init.g| is read,  but  before  the first
prompt is  printed.  The files are read in the order in  that they appear
on  the command line.  {\GAP}  only  accepts 14 filenames on the  command
line.  If a file  cannot be opened {\GAP} will print an error message and
will abort.

When you start {\GAP}, it looks  for  the file  with the name 'gap.rc' in
your  homedirectory (i.e., the   directory   defined by  the  environment
variable     'HOME').  If  such   a file  is    found it   is read  after
<libname>|\init.g|, but before any of the  files mentioned on the command
line are read.   You can use  this file for your private  customizations.
For example, if you  have a file  containing  functions  or data that you
always need, you could read this from 'gap.rc'.   Or if you find  some of
the names in  the  library too long,  you could define abbreviations  for
those names in 'gap.rc'.  The following sample 'gap.rc' file does both.

|    Read("c:\\gap\\dat\\mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for TOS}%
\index{TOS}\index{Atari ST}

This sections contain  information about {\GAP}  that is  specific to the
port of  {\GAP} for Atari ST systems  under TOS (simply called {\GAP} for
TOS below).

To run {\GAP} for TOS you need an Atari ST or Atari  TT.  The system must
have  at least  4 MByte  of main memory  and  a harddisk.   The operation
system   must  be TOS  1.4  or  later.   Since   {\GAP}  is a  plain text
application a monochrom monitor is probably best, but you  may also use a
color monitor.

The section "Copyright  of  GAP for TOS"   describes the copyright as  it
applies to the  executable   version  that we distribute.    The  section
"Installation  of GAP for TOS" describes  how you install {\GAP} for TOS,
and the section "Features of GAP for TOS"  describes the special features
of {\GAP} for TOS.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Copyright of GAP for TOS}

In   addition to  the  general  copyright for  {\GAP}   set forth  in the
copyright the following terms apply to the executable of {\GAP} for TOS.

{\GAP}  for TOS was compiled with  J. Bammi\'s port  of the Free Software
Foundation\'s  GNU C compiler version  2.5.  The compiler is available by
anonymous 'ftp' from  the 'ftp' server 'atari.archive.umich.edu' where it
is found in the directory 'atari/Gnustuff/Tos'.  Many  thanks to the Free
Software Foundation and J. Bammi for this amazing piece of work.

The GNU C compiler is

*Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA*

under the  terms  of the GNU General Public License (GPL).  Note that the
GNU  GPL  states  that the  mere act  of compiling  does not  affect  the
copyright status of {\GAP}.

The executable is linked with the GNU library 'gnu.obl', which is

*Copyright (C) 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA*

under  the terms of the GNU  Library General Public  License (LGPL).  The
terms of the LGPL require that we make the source  code for the 'gnu.olb'
available.  They can be obtained by writing to Martin Schoenert (however,
it may  be  easier for you  to 'ftp'  them from 'atari.archive.umich.edu'
yourself).  They also  require that we  make  {\GAP} available  in a form
that allows you to modify it, which we basically to anyhow.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for TOS}%
\index{installation!under TOS}\index{TOS!installation}

Installation of  {\GAP}  on an  Atari  ST  is  fairly  easy.  As  already
mentioned above, {\GAP}  must be installed  on a harddisk, because  it is
too large to be run from floppy disks.

First go to a directory where  you  want to install  {\GAP}, e.g., |c:\|.
{\GAP} will be installed in a subdirectory |gap3r4p0\| of this directory.
You can later move {\GAP} to another location, for  example you can first
install it in  |d:\tmp\| and once  it works move it  to  |c:\|.   In  the
following  example we assume that  you want  to install {\GAP} in  |c:\|.
We will  also assume in the examples  that you  install {\GAP} using some
shell, e.g.   'tcsh', 'ksh', 'bash', or  'gulam'.   Installation from the
desktop is also  possible, but it would be  much  more difficult to  give
examples, because you  have to use   the mouse in  this case.   Note that
certain parts of the output in the examples should only be taken as rough
outline,  especially  file sizes and file  dates  are *not*  to  be taken
literally.

Get the {\GAP} distribution  onto your Atari ST.   One usual way would be
to get  the  distribution with 'ftp'  onto  some UNIX workstation  and to
download it  from there  onto your  Atari ST,  for example with 'kermit'.
Remember that the distribution consists of binary files and that you must
transmit them in binary mode.  Another possibility is  that you got a set
of floppy disks.

If you  get the  distribution via   'ftp', you must get the  distribution
'gap3r4p0.zoo',  the  zoo archive  extractor  'unzoo-atari-m68k-tos.ttp',
which is   in the subdirectory  'util' and   which   you should rename to
'unzoo.ttp', and the  executable 'bin3r4p0-atari-m68k-tos.zoo',  which is
in the subdirectory 'bin' and which you  should rename to 'bin3r4p0.zoo'.
You may have to get the latter 2 files from 'samson.math.rwth-aachen.de',
because some 'ftp' servers may  not keep it.   We recommend that  you use
'unzoo' even if you already  have  'zoo' on  your system, because 'unzoo'
automatically translates text files to the appropriate local format.

If you got  the  distribution via 'ftp'  unpack  the  executable and  the
distribution with the following commands

|    C: > unzoo -x bin3r4p0.zoo
    gap3r4p0\bin\README.TOS  -- extracted as text
    gap3r4p0\bin\gap.ttp     -- extracted as binary
    C: > unzoo -x gap3r4p0.zoo
    gap3r4p0\bin\gap.sh      -- extracted as text
    gap3r4p0\doc\aboutgap.tex        -- extracted as text
    gap3r4p0\doc\aggroup.tex         -- extracted as text
    # about 500 more lines
    gap3r4p0\two\twogpd8.grp         -- extracted as text
    C: > |

If you got the executable and the distribution on  disks, you must unpack
them with the following comands (assuming that your disk drive is |A:|)

|    C: > rem Insert the 1. disk.
    C: > copy a:\unzoo.exe .
    C: > unzoo -x a:\bin3r4p0.zoo
    gap3r4p0\bin\README.TOS  -- extracted as text
    gap3r4p0\bin\gap.ttp     -- extracted as binary
    C: > unzoo -x a:\etc3r4p0.zoo
    gap3r4p0\etc\README      -- extracted as text
    # about 20 more messages
    C: > unzoo -x a:\grp3r4p0.zoo
    gap3r4p0\grp\basic.grp   -- extracted as text
    # about 10 more messages
    C: > unzoo -x a:\lic3r4p0.zoo
    gap3r4p0\lib\ctautoms.g  -- extracted as text
    # about 10 more messages
    C: > rem Insert the 2. disk.
    C: > unzoo -x a:\lib3r4p0.zoo
    gap3r4p0\lib\abattoir.g  -- extracted as text
    # about 70 more messages
    C: > rem Insert the 3. disk.
    C: > unzoo -x a:\doc3r4p0.zoo
    gap3r4p0\doc\about.tex   -- extracted as text
    # about 65 more messages
    C: > rem Insert the 4. disk.
    C: > unzoo -x a:\two3r4p0.zoo
    gap3r4p0\two\twogp.grp
    # about 25 more messages
    C: > unzoo -x a:\thr3r4p0.zoo
    gap3r4p0\thr\thrgp.grp
    # about 10 more messages
    C: > rem Insert the 5. disk.
    C: > unzoo -x a:\tom3r4p0.zoo
    gap3r4p0\tom\tmaltern.tom
    # about 10 more messages
    C: > rem Insert the 6. disk.
    C: > unzoo -x a:\src3r4p0.zoo
    gap3r4p0\src\Makefile    -- extracted as text
    # about 60 more messages
    C: > |

Instead of using the executable that we provide in 'bin3r4p0.zoo' you can
compile {\GAP} yourself if you have the GNU C compiler installed.   To do
this change into  the source directory |gap3r4p0\src\| and compile {\GAP}
with the commands

|    C: > chdir gap3r4p0\src
    C:\GAP3R4P0\SRC > make atari-m68k-tos-gcc2
    gcc -DSYS_IS_TOS_GCC2 -DSYS_HAS_MISC_PROTO -c system.c
    gcc -O2 -c gap.c
    # about 30 more messages
    C:\GAP3R4P0\SRC > copy gap.ttp ..\bin
    C:\GAP3R4P0\SRC > chdir ..\..
    C: > |

In either case now move the executable 'gap.ttp' from the |gap3r4p0\bin\|
subdirectory  to the  |gap3r4p0\|  directory.  Then you  can either start
{\GAP} from the desktop by double clicking or from  a shell such as Gulam
or 'bash' (in which  case you must use |-b |<install-dir>|\gap3r4p0\lib\|
option to tell {\GAP} where to find the library).

Start {\GAP} and try a few things.  Note that {\GAP} has  to read most of
the library for the fourth statement below,  so this takes quite a while.
Subsequent definitions of groups will be much faster.

|    C: > gap -b
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    gap> Factors( 10^42 + 1 );
    [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
    gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
    gap> Size( m11 );
    7920
    gap> Factors( 7920 );
    [ 2, 2, 2, 2, 3, 3, 5, 11 ]
    gap> Number( ConjugacyClasses( m11 ) );
    10 |

Especially try the command  line editing  and history facilities, because
the are probably the most  machine dependent feature  of {\GAP}.  Enter a
few commands   and then make  sure  that  <ctr>-'P' redisplays   the last
command, that  <ctr>-'E'  moves the cursor  to the end  of the line, that
<ctr>-'B' moves the cursor back one character, and that <ctr>-'D' deletes
single characters.  So after entering the above three commands typing\\
<ctr>-'P' <ctr>-'P' <ctr>-'E' <ctr>-'B'
<ctr>-'B' <ctr>-'B' <ctr>-'B' <ctr>-'D' '1'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If you have a big version of {\LaTeX} available  you may now want to make
a printed copy of the  manual.  Change into the directory |gap3r4p0\doc\|
and  run {\LaTeX} *twice* on the   source.  The first  pass with {\LaTeX}
produces the '.aux'  files, which resolve  all the cross references.  The
second pass produces  the final formatted  *dvi* file 'manual.dvi'.  This
will take quite a while, since the manual is large.  Then print the *dvi*
file.  How you actually print the 'dvi' file produced by {\LaTeX} depends
on the printer you  have, the version of {\LaTeX}  you have,  and whether
you use a  {\TeX}-shell  or not, so we   will not attempt to describe  it
here.

|    C: > chdir gap3r4p0\doc
    C:\GAP3R4P0\DOC > latex manual
    # about 2000 messages about undefined references
    C:\GAP3R4P0\DOC > latex manual
    # there should be no warnings this time
    C:\GAP3R4P0\DOC > dir manual.dvi
    -a---   2591132 Nov 13 23:29 manual.dvi
    C:\GAP3R4P0\DOC > chdir ..\..
    C: > |

Note that because of the large  number of  cross references in the manual
you need a *big*  {\LaTeX} to format the {\GAP}  manual.  If you  see the
error message  'TeX capacity  exceeded', you do  not have a big {\LaTeX}.
In this case  you  may also  obtain the  already    formatted *dvi*  file
'manual.dvi' from  the  same place where   you obtained the   rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    C: > chdir gap3r4p0\doc
    # about 2000 messages about undefined references
    C:\GAP3R4P0\DOC > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    C:\GAP3R4P0\DOC > latex manual
    # still some messages about undefined citations
    C:\GAP3R4P0\DOC > makeindex manual
    # 'makeindex' prints some diagnostic output
    C:\GAP3R4P0\DOC > latex manual
    # there should be no warnings this time
    C:\GAP3R4P0\DOC > chdir ..\..
    C: > |

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features of GAP for TOS}%
\index{features!under TOS}\index{TOS!features}%
\index{options!under TOS}\index{TOS!options}%
\index{gap.rc}\index{.gaprc}

{\GAP} for TOS will  usually  allocate all  available memory.  Note  that
{\GAP} for TOS does not  support virtual memory,  i.e., you can never use
more memory than this  default gives you.   If you specify '-m <memory>',
{\GAP} will only allocate  that much memory.   If you specify a  negative
amount, {\GAP} leaves this  much memory unallocated.  You  may want to do
this,  so  that that it is   possible to run  other  programs from inside
{\GAP} with the 'Exec' command.

The arrow keys <left>, <right>, <up>, and  <down> can be used for command
line editing with their intuitive meaning.

{\GAP} for TOS supports 'UNIXMODE',   i.e., if the environment   variable
'UNIXMODE' is  set to an  appropriate value such  as '/.,rCLAHbd', {\GAP}
will emulate a UNIX style file system on top of the TOS filesystem.  That
is {\GAP} will accept pathnames with the  '/' as separator, which it will
automatically map to  the  TOS separator |\|.  It  will  also allow  long
filenames  (with more than  8+3 characters),  which it will automatically
map to TOS  filenames and remember the  true filenames in  a special file
'.dir'.  '.dir'  is  used to  symbolic links,  which  can be  resolved by
{\GAP} (to create then you need the GNU 'ln' program).

{\GAP} for TOS runs as an ordinary TOS program.  That  means that it does
not open  windows or display a  menu bar etc.   The advantage of  this is
that  no  valuable   memory space  is    wasted  for  the windows.    The
disadvantage  is that GEM programs  with windows are certainly more sexy.
A GEM version is being developed, but don\'t hold your breath.

Apart  from this everything  works as  described  in this manual  and you
should not have any problems using {\GAP}.

When you  start  {\GAP} on  the Atari  ST, you may   specify a  number of
options  on the command-line to  change the default  behaviour of {\GAP}.
All these  options start with a hyphen  '-', followed by a single letter.
Options must not be grouped, e.g., 'gap -gq' is  illegal, use 'gap -g -q'
instead.   Some options require an argument,  this must follow the option
and  must  be separated by a   <space>, e.g., 'gap  -m  256k',  it is not
correct to say 'gap -m256k' instead.

You  must declare {\GAP} as  TOS-takes-parameter  program if  you want to
specify command-line options when you   start {\GAP} by double  clicking.
This means that  the name of the {\GAP}  program file  must be 'gap.ttp'.
When you start {\GAP} from a shell, such  as 'gulam.tos', the name of the
program file does not matter.  {\GAP}  for TOS, unlike the UNIX versions,
does not distuingish upper and lower case for options.

{\GAP} for TOS accepts the following (lowercase) options.

'-g'

The options '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 3072 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 3072 KBytes are available afterwards.

'-l <libname>'

The option '-l' tells {\GAP}  that the library  of {\GAP} functions is in
the  directory <libname>.  Per  default  <libname> is  'lib/', i.e.,  the
library  is normally expected in the subdirectory  'lib/'  of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to  {\GAP}, in this
directory.   <libname> should end  with a  pathname separator, i.e., |\|,
but {\GAP} will silently add one  if it is missing.  {\GAP} will read the
file <libname>|\init.g| during startup.  If {\GAP} cannot find this  file
it will print the following warning

|    gap: hmm, I cannot find 'lib\init.g', maybe use option '-l <lib>'?|

If you  want a bare bones {\GAP},  i.e., if you do  not  need any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start  it again, specifying the correct  library path  using the '-l'
option.

It is  also possible to  specify several  alternative library  pathes  by
separating them  with semicolons ';'.   Note that in  this  case all path
names must end with the pathname separator  |\|.  {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds.  E.g., if  you specify |-l "lib\;\usr\local\lib\gap3r4p0\lib\"|
{\GAP} will search for a library file first in the subdirectory |lib\| of
the current directory, and if it does not find it  there in the directory
|\usr\local\lib\gap3r4p0\lib\|. This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP}  searches for the group files,  whose filenames end in '.grp', and
which contain the groups initially known to  {\GAP}, in the directory one
gets by replacing the string 'lib' in <libname> by the  string 'grp'.  If
you do not want  to put the group  directory |grp\| in the same directory
as the |lib\| directory,  for example if you want  to put the groups onto
another   hard  disk  partition,  you have  to   edit the   assignment in
<libname>|\init.g| that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of |lib\| is replaced by |grp\|.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The  option '-h' tells {\GAP} that the on-line documenation for {\GAP} is
in  the directory  <docname>.   Per  default  <docname>  is  obtained  by
replacing 'lib' in <libname>  with 'doc'.   <docname> should  end  with a
pathname separator, i.e., |\|, but {\GAP} will silently  add one if it is
missing.  {\GAP} will read the file <docname>|\manual.toc| when you first
use the help system.  If {\GAP} cannot find this file  it will print  the
following warning

|    help: hmm, I cannot open the table of contents file 'doc\manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to  allocate <memory> bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

{\GAP} for TOS will by  default allocate all   available memory.  If  you
specify '-m <memory>' {\GAP} will  only allocate that much memory, unless
<memory> is larger than  the default, in that  case {\GAP} will fail.  If
you  speficy a   negative   amount   {\GAP}   leaves that   much   memory
unallocated.  You may want to do this so that it is possible to run other
programs from inside {\GAP} with the 'Exec'  command, for example 'gap -m
-256k' will leave  256 KByte unallocated,  enough to run  MicroEMACS from
inside {\GAP}.

'-n'

The  options  '-n' tells {\GAP} to  disable  the line editing and history
(see "Line Editing").

There does not seem to be a good reason to do this on an Atari ST.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The  option '-q' tells  {\GAP} to be quiet.  This  means that {\GAP} does
not  display the banner and the  prompts 'gap>'.  This  is useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this  option you can tell  {\GAP} how long   lines are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80,  which  is correct if  you start {\GAP} from the
desktop or one of the usual shells.  However, if you  start {\GAP} from a
window shell such as 'gemini', you may want to decrease  this  value.  If
you have a larger monitor, or use a smaller font, or  redirect the output
to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is  24, which is  the right value  if  you start {\GAP}
from the desktop or one  of  the  usual shells.   However, if  you  start
{\GAP} from a window  shell such as 'gemini',   you may want  to decrease
this value.  If  you  have a larger monitor,  or use  a smaller  font, or
redirect the output to a printer, you may want to increase this value.

'-z <freq>'

{\GAP} for TOS checks  in regular intervals  whether the user has entered
<ctr>-'Z'  or <alt>-'C' to  interrupt an ongoing  computation.  Under TOS
this  requires reading the keyboard status  (UNIX on the  other hand will
deliver a signal to  {\GAP}  when the user  entered <ctr>-'C'),  which is
rather  expensive.  Therefor {\GAP} only  reads the keyboard status every
<freq>-th time.  The default is 20.  With  the option '-z' this value can
be changed.   Lower values  make  {\GAP} more responsive  to  interrupts,
higher values make {\GAP} a little bit faster.

Further arguments are taken as filenames of files that are read by {\GAP}
during startup, after <libname>|\init.g| is read,  but  before  the first
prompt is  printed.  The files are read in the order in  that they appear
on  the command line.  {\GAP}  only  accepts 14 filenames on the  command
line.  If a file  cannot be opened {\GAP} will print an error message and
will abort.

When you start {\GAP}, it looks  for  the file  with the name 'gap.rc' in
your  homedirectory (i.e., the   directory   defined by  the  environment
variable     'HOME').  If  such   a file  is    found it   is read  after
<libname>|\init.g|, but before any of the  files mentioned on the command
line are read.   You can use  this file for your private  customizations.
For example, if you  have a file  containing  functions  or data that you
always need, you could read this from 'gap.rc'.   Or if you find  some of
the names in  the  library too long,  you could define abbreviations  for
those names in 'gap.rc'.  The following sample 'gap.rc' file does both.

|    Read("c:\\gap\\dat\\mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Porting GAP}

Porting {\GAP}  to a new operating  system should not  be very difficult.
However,  {\GAP} expects some features from the  operating system and the
compiler  and porting {\GAP}  to a system or with  a compiler that do not
have those features may prove very difficult.

The design of {\GAP} makes it quite portable.  {\GAP} consists of a small
kernel written in the programming language C  and a large library written
in the programming language provided by  the {\GAP} kernel, which is also
called {\GAP}.

Once the kernel has been ported, the library poses no additional problem,
because all those functions  only need the kernel to  work, they  need no
additional support from the environment.

The  kernel  itself is  separated   into a large    part that  is largely
operating system and compiler independent, and one file that contains all
the operating system and compiler dependent functions.  Usually only this
file must be modified to port {\GAP} to a new operating system.

Now lets take  a look at the minimal  support that {\GAP} needs from  the
operating system and the machine.

First of  all you  need enough filespace.   The  kernel  sources  and the
object files need between 3.5 MByte and 4 MByte, depending on the size of
object  files  produced  by your  compiler.    The library  takes   up an
additional 3.5 MBytes, and the online documentation also needs 2.5 MByte.
So you  need about  10 MByte  of  available filespace,  for example  on a
harddisk.

Next  you need  enough main memory  in  your computer.   The  size of the
{\GAP} kernel  varies between different  machine,  with as little as  300
KByte  (compiled with GNU C  on  an Atari ST)   and as much  as 600 KByte
(compiled with UNIX  cc  on a  HP 9000/800).   Add  to that the fact  the
library of functions that {\GAP} loads takes up another 1.5 MByte.  So it
is  clear that at least 4   MByte of main memory   are required to do any
serious work with {\GAP}.

Note that this implies that there is no point in trying to port {\GAP} to
plain MS-DOS running  on IBM PCs and compatibles.   The version of {\GAP}
for IBM PC compatibles that  we  provide runs on  machines with the Intel
80386  or Intel  80486  processor under  extended DOS in protected 32 bit
mode.  (This is also necessary, because, as mentioned below, {\GAP} wants
to view its memory as a large flat address space.)

Next lets turn to the requirements for the C compiler and its library.

As was already mentioned, the {\GAP} kernel is written in the C language.
We  have tried  to use  as few features  of  the C language as  possible.
{\GAP} has  been compiled without  problems with compilers that adhere to
the old  definition from Kernighan and Ritchie,  and with  compilers that
adhere to the new definition from the ANSI-C standard.

However, it is probably necessary that the compiler has a default integer
size of 32   bits, i.e., 'sizeof(int)'  should be  4  not 2.  It  may  be
possible  to fix all the  places where 32 bit  'int's are assumed, but we
assume that it will be easier to get a 32 bit compiler.

The most critical aspect probably is that  the {\GAP} kernel needs a flat
address space.  There are especially two systems where this is a problem.

The first is MS-DOS with its segments.  As  was already  mentioned above,
we circumvent this by using an extended DOS in protected  32 bit  mode on
PC compatibles with an Intel 386 or Intel 486 processor.

The other system is the Macintosh.  On the Macintosh the operating system
wants   to deal out   the  memory only in  small  chunks,  and also wants
programs to allow it to move those chunks to the  disk temporarily.  This
is because Apple  wanted to support programs  that used quite some memory
on its  initial Macs, which had  only 512 KByte   of memory, without true
virtual memory  support.  Thus  they forced  the application programs  to
simulate virtual memory.  {\GAP} does not do this.  Probably the best way
to  deal with that  is to allocate  as much memory  as one can get in one
large chunk,  while leaving enough memory  free for the operating system,
and to    lock  this chunk  in   memory.  Such  behaviour   is considered
uncooperative, but it is the best {\GAP} can do without a major rewrite.

The two points   mentioned above  are necessary,  because  most parts  of
{\GAP} depend on those features.  All other dependencies on the operating
system or compiler   should be separated   in one special file  which  is
called  the 'system'  file.   When you  port {\GAP}  to   a new operating
system, you probably  have  to create a new  'system'  file.   You should
however look through the 'system.c' file that we  supply and take as much
code from them as possible.  Currently 'system.c' supports Berkeley UNIX,
System V UNIX, IBM  PC compatibles under  MS-DOS with the DJGPP compiler,
and the Atari ST under TOS with the GNU C compiler.

The 'system' file contains the following functions.

First  file  input and output.  The   functions used by  the three system
files mentioned above are 'fopen', 'fclose',  'fgets', and 'fputs'.  They
are pretty standard, and in fact are in the ANSI C standard library.  The
only thing that may be necessary is to make sure that files are opened in
text  mode.  However, the most  important transformation  applied in text
mode seems to be to replace  the end of line sequence <newline>-<return>,
used in some  operating  systems, with a  single  <newline>, used  in  C.
However, since  {\GAP} treats <newline> and  <return> both as whitespaces
even this is not absolutely necessary.

Second you need  character oriented input  from the keyboard   and to the
screen.  This is not absolutely necessary, you can  use the line oriented
input and output described above.  However, if  you want the  history and
the command  line editing, {\GAP}  must  be  able   to read every  single
character as the user types it without echo, and also must be able to put
single characters  to  the screen.    Reading  characters  unblocked  and
without echo is very  system dependent.

Third you need a  way to detect if the  user typed <ctr>-'C' to interrupt
an   ongoing  computation   in  {\GAP}.  Again    this is not  absolutely
necessary,  you can   do without.   However  if you want  to   be able to
interrupt computations,  {\GAP} must be able to  receive  the  interrupt.
This can be done in two ways.  Under  UNIX you can  catch the signal that
is   generated  if   the  user types <ctr>-'C'  ('SIGINT').   Under other
operating systems that do not support such signals you can poll the input
stream at regular intervals and simply look for <ctr>-'C'.

Fourth you  need  a way  to  find out how long  {\GAP} has  been running.
Again this is not  absolutely necessary.  You can simply always return 0,
fooling  {\GAP} into  thinking that it is extremely fast.  However if you
want timing statistics, {\GAP} must be able to find out how much CPU time
it has spent.

The  last and most important function  is the function to allocate memory
for {\GAP}.  {\GAP}  assumes that  it can allocate the initial  workspace
with the function  'SyGetmem' and expand this workspace  on  demand  with
further calls to 'SyGetmem'.  The  memory allocated by consequitive calls
to 'SyGetmem' must be  adjacent, because {\GAP}  wants to manage a single
large  block  of memory.  Usually this   can be done  with  the C library
function 'sbrk'.  If this does  not work, you  can define a  large static
array in  the  'system'  file and return  this  on    the  first call  to
'SyGetmem' and return 0  on subsequent calls  to indicate that this array
cannot dynamically be expanded.
