This document describes how to install GAP 4 on a Unix system. Section
"Getting GAP" describes where to get GAP 4 and which files to get. Section
"Installation of GAP for UNIX" describes the installation process. Section
"Porting GAP" describes what to do to port GAP 4 to other systems.



   Installation for the Impatient
   ==============================
   
   Because GAP supports three different platforms, Windows, Macintosh and
   Unix, the installation process might differ a bit from what you are
   used to. This document explains in detail which files to get and how
   to install the system and if you are inexperienced we strongly
   recommend you follow these descriptions.
   
   If you have already experience in installing GAP or would not read the
   installation instructions anyhow this section provides a quick run
   through. (If it is incomprehensible or causes problems, _please follow
   the explicit installation instructions given below!_):
   
   Get an unzoo binary and installation archive(s) and bugfix files. Call
   unzoo -x archive.zoo
   cd gap4r2
   
   If there were bugfixes, extract all of them with:
   unzoo -x ../fixXX4r2.zoo
   
   To compile a binary call
   ./configure
   make
   
   and you will get a shell script bin/gap.sh to start GAP which you can
   copy in a standard path.
   
   Send an email to gap@dcs.st-and.ac.uk, telling us about the
   installation.
   
   You might also want to unpack and install share packages in the pkg
   directory.
   
   Also note that a few details might have changed since the last
   release.
   


   Getting GAP
   ===========
   
   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@dcs.st-and.ac.uk, 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. (The copyright page of the manual
   gives a sample citation.) Again we would appreciate if you could
   inform us about such a paper.
   
   The current release of GAP is version 4.2.
   
   We distribute the _full source_ for everything, the C code for the
   kernel, the GAP code for the library, and the TeX code for the manual.
   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. Note that about 16 MByte of main memory (though at least 32MByte
   is desirable) and about 30MB of disk space are required to run GAP. A
   full GAP installation, including all share packages and data libraries
   can use 200MB and more of disk space. GAP will compile on pentium
   (586) processors, though a faster machine is recommended.
   
   (If you already downloaded an installation archive, you may ignore the
   rest of this section.)
   
   The easiest way to get GAP for most users is probably via the World
   Wide Web. The main GAP Web site is found at
   http://www-gap.dcs.st-and.ac.uk/gap
   
   There are three _mirror sites_ updated automatically each night, at:
   http://www.math.rwth-aachen.de/~GAP http://www.ccs.neu.edu/mirrors/GAP
   and http://wwwmaths.anu.edu.au/research.groups/algebra/GAP/www/
   
   At these sites you can browse this manual, download the system and
   contributed extensions, read past postings to the GAP forum, and find
   out about authors of and contributors to GAP, publications that cited
   GAP and GAP related events.
   
   GAP can also be obtained by anonymous _ftp_ from (at least) the
   following servers.
   
   ftp-gap.dcs.st-and.ac.uk:
          School of Mathematical and Computational Sciences, University
          of St Andrews, Scotland, UK. Directory /pub/gap/gap4/.
   ftp.math.rwth-aachen.de:
          Lehrstuhl D fr Mathematik, RWTH Aachen, Germany. Directory
          /pub/gap4/.
   ftp.ccs.neu.edu:
          College of Computer Science, Northeastern University, Boston,
          USA. Directory
          /pub/mirrors/ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4.
   pell.anu.edu.au:
          School of Mathematical Sciences, Australian National
          University, Canberra, Australia. Directory /pub/algebra/gap4/.
          
   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.
   
   The WWW page for the GAP distribution and the ftp directory contain
   the following files. Please check first which files you need, to avoid
   transferring those that you do not need.
   
   INSTALL, INSTALL.WIN, INSTALL-MAC.TXT:
          Installation files, one of which you are currently reading.
   FILES:
          More detailed description of the available files.
   gap4r2.zoo:
          This file contains the _complete_ distribution of GAP version
          4.2.
   basic4r2.zoo:
          This file contains a _minimal_ distribution of GAP version 4.2.
          (There are further archives with which you can ``upgrade'' it
          to the full version.)
   gappc4r2.zoo:
          This file contains a complete distribution for 32-bit Windows.
          It includes a precompiled binary.
   gapmac4r2.zoo:
          This file contains a complete distribution for Macintosh under
          MacOS. You will also need to obtain the binaries separately
          from the bin subdirectory.
   allshare4r2.zoo:
          This file contains all accepted share packages as of the
          release date.
   submitshare4r2.zoo:
          This file contains all submitted, but not accepted, share
          packages whose authors wish to make them available, as of the
          release date. They should be viewed as analagous to preprints.
   util/unzoo.c:
          A simple zoo archive extractor, which should be used to unpack
          the distribution. The bin subdirectory contains precompiled
          executables for common systems.
          More files are in the following _subdirectories_:
   bin:
          This directory contains _executables_ for systems that do not
          come with a C compiler or where another C compiler produces a
          faster executable.
   split:
          This directory contains the complete distribution of GAP 4.2 in
          several smaller archives.
   share:
          This directory contains all accepted share packages in case you
          don't want to load the comprehensive allshare archive.
   deposit/psh:
          This directory contains all submitted but not accepted share
          packages whose authors wish to make them available, in case you
          don't want to load the comprehensive submitshare archive.
          


   GAP for UNIX
   ============
   
   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:
   DECalpha under OSF 3.2 with GNU cc 2 or cc,
   HP9000 under HP-UX with GNU cc 2,
   IBM PC under Linux with GNU cc 2,
   IBM RS/6000 & AIX with GNU cc 2, SGI Mips under IRIX 5/6 with gcc2 or
   cc, Sun Sparc under Solaris with GCC 2 or cc.
   
   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. See Chapter Running GAP for information about
   command line options that GAP accepts under UNIX.
   


   Installation of GAP for UNIX
   ============================
   
   Installing GAP on a UNIX machine is fairly easy. Get the files
   described in Getting GAP and decide into which directory you want to
   install GAP 4.2. If you will be the only user using GAP, you probably
   should install it in your home directory. If other users will be also
   using GAP, you should install it in a public place, such as
   /usr/local/lib/. GAP will be installed in a subdirectory gap4r2 of
   this directory. You can later move GAP to a different location. For
   example you can first install it in your home directory and when it
   works move it to /usr/local/lib/.
   
   The following installation example assumes that you (as user you on
   the machine unix) are installing GAP into the directory /usr/local/lib
   on a Pentium Pro running Linux.
   
   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.
   
   If you encounter problems please also see section If Things Go Wrong
   of this document.
   
   Get the distribution gap4r2.zoo and the source for the zoo archive
   extractor unzoo.c. How you can get those files is described in the
   section Getting GAP. 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@unix> cc -o unzoo -DSYS_IS_UNIX -O unzoo.c
   you@unix> ls -l unzoo
   -rwxr-xr-x you 45056 Nov 3 10:11 unzoo
   you@unix>
   
   Now unpack the distribution with the command
   
   you@unix> ./unzoo -x gap4r2.zoo
   gap4r2/doc/aboutgap.tex -- extracted as text
   gap4r2/doc/aggroup.tex  -- extracted as text
   [many more lines]
   you@unix>
   
   If you got not the full distribution file but several small files,
   extract all of them (_except the bug fixes and share packages!_) in
   this way.
   
   (Afterwards you will not need the file gap4r2.zoo any longer. If you
   are short of disk space you can remove it now.)
   you@unix> rm gap4r2.zoo
   
   Now go in the directory gap4r2 If you got any bug fixes (there are
   none in the initial release but doubtlessly some will follow. You can
   find them in the bugfixes directory on our ftp server(s).) extract
   these there. (The bug fixes extract only on this level to make them
   applicable even if you chose later to rename the root directory of
   your GAP distribution.)
   
   If there is more than one fix file, first unpack fix1, then fix2, an
   so on.
   
   you@unix> cd gap4r2
   you@unix> ../unzoo -x ../fixXX4r2.zoo
   [again extraction information]
   
   If you got any share packages, extract them in the pkg subdirectory in
   the same way. For example if you got the allshare4r2.zoo and
   submitshare4r2.zoo archives, you would issue:
   
   you@unix> cd pkg
   you@unix> ../../unzoo -x ../../allshare4r2.zoo
   you@unix> ../../unzoo -x ../../submitshare4r2.zoo
   you@unix> cd ..
   
   The directories tbl, tom, trans, small and prim contain data
   libraries. If you are short of disk space you can erase some of them,
   but then of course you will not be able to access this data.
   
   Under UNIX, we now use the ``autoconfig'' method to take care of
   system dependencies. (See Porting GAP if this is not working on your
   machine.)
   
   If you are installing GAP on various systems that share a file system
   and if you have installed GAP already on another machine you _must_
   remove the files config.cache and config.status first!
   
   Then run the shell script configure:
   
   you@unix> ./configure
   checking host system type... i686-unknown-linux2.0.27
   [many more lines]
   
   This will automatially detect the machine and compiler target. The
   process will automatically create an appropriate binary subdirectory.
   It also creates a Makefile that will be used to compile GAP on this
   machine. Simply call make:
   
   you@unix> make
   [many lines of further configuration and compilation]
   
   If configure or make fails, see section Known Problems of the
   Configure Process for a description of some remedies.
   
   If you have UNIX experience you might want to change the compilation
   options to obtain a better performance. Section Optimization and
   Compiler Options explains how to do this.
   
   The compilation process creates the object files and the executable in
   the directory /usr/local/lib/gap4r2/bin/target/, where target is the
   name printed by the first configure. In our example the executable
   will be created as
   /usr/local/lib/gap4r2/bin/i686-unknown-linux2.0.27/gap
   
   The automatic configuration should work on any UNIX system. If it does
   not, please inform us at gap-trouble@dcs.st-and.ac.uk.
   
   In order to test your compilation now run the newly created
   executable. You should get the GAP banner and then the GAP prompt.
   (The process of starting GAP may take a little while.)
   
   you@unix> cd ..
   you@unix> bin/i686-unknown-linux2.0.27/gap -l /usr/local/lib/gap4r2
   [... lines deleted]
   gap>
   
   (Having to give the library path with the -l option each time would be
   a bit tedious. Below we will therefore install a shell script to start
   GAP.)
   
   Try a few things to see if the compilation succeeded.
   
   gap> 2 * 3 + 4;
   10
   gap> Factorial( 30 );
   265252859812191058636308480000000
   gap> Size( SymmetricGroup( 10 ) );
   3628800
   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> Length( ConjugacyClasses( m11 ) );
   10
   
   Especially try the command line editing and history facilities,
   because they 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 return
   
   should give the following lines:
   
   gap> Factors( 7921 );
   [ 89, 89 ]
   
   If you can compile but command line editing does not work you can
   always start GAP with option -n to disable command line editing. In
   such a case however 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.
   
   The make process should also have created a shell script gap.sh in the
   bin subdirectory. This file already contains proper directory paths
   and it should be possible to start GAP by simply calling this script.
   Still, you might want to edit it to give further default command line
   options or modify the default memory.
   
   Execute the script to start GAP again
   you@unix> bin/gap.sh
   
   If the shell complains that it cannot execute or find gap.sh check the
   permissions of the file by doing a ls -l bin/gap.sh. The permissions
   should include execute permissions, if they don't you can set them by
   you@unix> chmod +x bin/gap.sh
   
   Then copy this script into a directory in your search path, for
   example /usr/local/bin/ as gap (or gap4 if you also have GAP 3 running
   on the same machine). (If you are using the C-shell, you will also
   have to rehash, so that the C-shell adds gap to its internal tables).
   When you later move GAP to another location you only need to edit this
   script.
   
   There also is a shell script gac in the same place that can be used to
   invoke the compiler. Depending on your installation you also might
   want to copy it in a directory in your search path.
   
   Now you should be able to start GAP by its name:
   
   you@unix> cd ~
   you@unix> gap
   
   (If you get an error message ``hmm, I cannot find lib/init.g'' you are
   starting the pure binary. It needs to find the library which is given
   via the command line parameter -l.)
   
   A set of test files is provided, running them all takes some 40
   minutes on a Pentium Pro 200 Mhz. As a quick test we start
   combinat.tst first.
   
   gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" );
   "/usr/local/lib/gap4r2/tst/combinat.tst"
   gap> ReadTest(last);
   + $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $
   + GAP4stones: 27801
   true
   
   The number given as GAP4stones will vary, depending on the speed of
   your machine.
   
   Now use Read (_not_ ReadTest) to read the file testall.g to run _all_
   available test files. This is not a necessary part of the
   installation, it only serves as a confirmation that everything went
   OK. The full test suite takes some time (almost 2 hours on a Pentium
   III/500) and uses quite a bit of memory (around 100MB), so you may
   wish to skip this step or run only part of the tests. This does no
   harm)
   
   gap> Filename( DirectoriesLibrary("tst"), "testall.g" );
   "/usr/local/lib/gap4r2/tst/testall.g"
   gap> Read(last);
   [lines omitted]
   test file         GAP4stones     time(msec)
   -------------------------------------------
   testing: ./tst/boolean.tst
   boolean.tst                0              0
   testing: ./tst/unknown.tst
   unknown.tst                0             10
   testing: ./tst/gaussian.tst
   gaussian.tst               0            250
   [further lines omitted]
   
   You can ignore warnings from weakptr.tst, which stem from garbage
   collections occurring at different times, and those from grpconst.tst
   which stem from differences in available share packages.
   
   The information about the manual is system independent, you can find
   it in section The Documentation.
   
   If you also installed share packages which require external binaries
   now go to the share packages directories (the directories under pkg)
   and follow the instructions given there to compile their binaries.
   
   Some share packages are set up to load (or provide the documentation)
   automatically. To enable this you have to list all packages in a file
   ALLPKG in the pkg directory (see section Loading a Share Package in
   the reference manual for details), the easiest way to do this under
   UNIX is by issuing the command
   find * -type d -maxdepth 0 -print > ALLPKG
   
   in the pkg directory.
   
   If you want to install GAP also on different architectures, which
   share the same file system with the machine on which you just
   installed GAP log into these machines and go to the GAP home
   directory. You do not need to extract any new files, simply execute
   the same ``configure/make'' process which has been described above
   again. Make sure, however that you copy the bin/gap.sh and bin/gac
   shell scripts created by the make process because they are system
   dependent and will be overwritten when compiling on another system.
   
   A few final reminders: Make sure that you got and installed all
   bugfixes. We would appreciate if after installation you could send us
   a short note at gap@dcs.st-and.ac.uk (even if you had installed GAP3
   before). We also suggest that you subscribe to our gap-forum mailing
   list, see the GAP web pages for details.
   
   Thats all, the installation is complete. We hope that you will enjoy
   using GAP. If you have problems, do not hesitate to contact us at
   gap-trouble@dcs.st-and.ac.uk.
   


   Known Problems of the Configure Process
   =======================================
   
   If make complains ``Do not know how to make xyz'' but xyz is an
   existing file, it is likely that the dates of the files were not
   extracted properly (Alpha-OSF machines are prone to this). Call
   touch * cnf/* src/*
   
   from the main GAP directory (this ought to reset the date of all
   relevant files to ``now'') and try again.
   
   Rarely the configure process does not find out properly about the
   ``inline'' compiler command. If you get error messages that complain
   that ``inline'' is unknown, edit the file config.h in the bin/target
   subdirectory and replace the line
   /* #undef inline */
   
   by
   #define inline
   
   and then try to compile again.
   
   The configure script respects compiler settings given in environment
   variables. However such settings may conflict with the automatic
   configuration process. If configure produces strange error messages
   about not being able to run the compiler, check whether environment
   variables that might affect the compilation (in particular CC, LD,
   CFLAGS, LDFLAGS and C_INCLUDE_PATH) are set and reset them using
   unsetenv.
   
   Some users reported problems with make, while the GNU version gmake
   worked. Thus if problems occur you should try gmake instead if it is
   installed on your machine.
   


   Problems on Particular Systems
   ==============================
   
   The highest levels of optimization of the OSF/4 C compiler cc on the
   Compaq alpha chip make assumptions about the use of pointers which are
   not valid for GAP, and produce executables that can crash. -O3 seems
   to be safe, but -O4 and -fast do not.
   
   On Sun and Irix systems which are capable of running in 32 or 64 bit
   modes, it is possible to build a 64 bit version of GAP, but special
   procedures are needed (and, on Suns, a compiler bug must be
   circumvented). If you wish to compile on such a system, send email to
   |gap-trouble@dcs.st-and.ac.uk|.
   


   Optimization and Compiler Options
   =================================
   
   Because of the large variety of different versions of UNIX and
   different compilers it is possible that the configure process will not
   chose best possible optimization level, but you might need to tell
   make about it.
   
   If you want to compile GAP with further compiler options (for example
   specific processor optimizations) you will have to assign them to the
   variable COPTS as in the following example when calling make:
   make COPTS=-option
   
   If there are several compiler options or if they contain spaces you
   might have to enclose them by quotes to avoid depending on the shell
   you are using.
   
   The configure process also introduces some default compiler options.
   (See the Makefile in the bin directory for details.) You can eliminate
   these by assigning the variable CFLAGS (which contains the default
   options and COPTS) to the desired list of compiler options in the same
   way as you would assign COPTS.
   
   The _recommended_ C compiler for GAP is the GNU C compiler gcc, or a
   related compiler such as egcs. There are two reasons for this
   recommendation: firstly we use gcc in GAP development and so this
   combination has been far more heavily tested than any other and
   secondly, we have found that it generally produces code which is
   faster than that produced by other compilers.
   
   If you do wish to use another compiler, you should remove config.cache
   and config.status in the GAP root directory, set the environment
   variable CC to the name of your preferred compiler and then rerun
   configure and make. You may have to experiment to determine the best
   values for CFLAGS and/or COPTS as described above. Please let us
   (gap@dcs.st-and.ac.uk) know the results of your experiments.
   


   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:
   
   You need enough main memory in your computer. The size of the GAP
   kernel varies between 1.5 and 2.5 MByte (depending on the machine).
   The GAP library additionally takes a minimum of 10MByte library of
   functions that GAP loads takes up another 1.5 MByte. So it is clear
   that at least 16 MByte of main memory are required to do any serious
   work with GAP.
   
   Additionally, the GAP kernel needs a flat address space, that is all
   the memory is available in one contiguous chunk.
   
   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
   80486, Pentium or ibeyond processor under 32-bit Windows. (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.
   
   Porting GAP to another UNIX should not be hard. You need some very
   basic understanding of C and UNIX. If you plan to port GAP to a
   non-UNIX system please contact gap-trouble@dcs.st-and.ac.uk.
   
   The configuration script runs various tests to determine the
   configuration of your system. It produces a file
   bin/architecture/config.h which contains definitions according to the
   test results. It might be, however, that the tests used don't produce
   on your machine the results they are expected to or that further tests
   are necessary. If this is the case the easiest way is to edit the
   config.h script, remove all object files and call make in the
   bin/architecture subdirectory. If you have to resort to changing or
   amending this file, please tell us what had to be changed (mail to
   gap-trouble@dcs.st-and.ac.uk). If you had to add further definitions
   please also tell what properties of your system these defines
   represent.
   
   If GAP compiles but crashes while reading the library or during a
   garbage collection with a bus error it is possible that the
   configuration script did not guess the permitted pointer alignment
   correctly. This value is stored in the line
   #define C_STACK_ALIGN      2
   
   of config.h. Increase the value to the next power of 2 (<= 8) and
   compile GAP anew.
   
   There is still a Makefile in the src directory, but it is not used by
   the configuration process any longer. As a last resort you might want
   to try this file, but please still report your problems to
   gap-trouble.
   


   The Documentation
   =================
   
   The GAP manual is distributed in various ``books''. The standard
   distribution contains four of them (as well as a comprehensive index).
   Share packages and other extensions may provide their own manuals.
   
   All documentation will be available automatically for the online help
   (see Help). There also is (if installed) an HTML version in the
   doc/htm subdirectory that can be viewed with an HTML browser. Note
   that you need to set up the symbol font properly in your web browser
   to get a correct display of mathematical formulae (see section HTML
   Font Setup).
   
   Typing ?topic after the gap> prompt will display the manual section
   about topic (or offer you a list of sections that fit), ??topic will
   list all sections in whose title topic occurs.
   
   Unless you only downloaded a rudimentary distribution, there will be
   already dvi and pdf files for the manual books provided with the
   standard distribution. You find these in the directory gap4r2/doc in
   the subdirectories tut (a beginner's tutorial), ref (the reference
   manual), prg (programmer's tutorial) and ext (programmer's reference).
   
   If you do not yet have a viewer for pdf files, you can take for
   example Adobe Acrobat
   http://www.adobe.com/products/acrobat/readstep.html (a copyrighted,
   but free program) or XPDF http://www.foolabs.com/xpdf/xpdf.html (a
   free program under GPL).
   
   As a complete beginner, we suggest you read the tutorial first for an
   introduction to GAP4.
   
   If you have experience with GAP3, it might be still worth to at least
   glance over the first chapters of the tutorial. You however should
   read the last chapter of the tutorial, ``Migrating to GAP4''. This
   chapter gives a summary of changes between GAP3 and GAP4 that will
   affect the user. It also explains a ``compatibility mode'' you may
   turn on to make GAP4 behave a bit more like GAP3.
   
   As some of the manuals are quite large you should not immediately
   print them. If you start using GAP it will be helpful to print the
   tutorial (and probably the first chapters of the reference manual).
   There is no compelling reason to print the whole of the reference
   manual. We also recommend to print the full index to the manuals to be
   found in gap4r2/doc/fullindex.dvi.
   


   HTML Font Setup
   ===============
   
   The HTML pages of the manual use the symbol font to display non-latin
   symbols in mathematical formulae. This font might not be enabled by
   default on your browser. The section on Browser Problems in the
   documentation of the tth converter
   http://hutchinson.belmont.ma.us/tth/manual.cgi describes some common
   problems and their solution.
   
   In particular, it suggests the following quick way to achieve a proper
   setup for Netscape 4 under X-Windows: Add the following line to your
   .Xdefaults (or .Xresources) file:
   Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
   
   and call
   xrdb .Xdefaults
   
   (or restart the X server) to make it read the file. Once netscape is
   restarted the fonts should be rendered properly.
   


   If Things Go Wrong
   ==================
   
   This section lists a few common problems when installing or running
   GAP and their remedies:
   
   GAP starts with a warning ``hmm, I cannot find 'lib/init.g'''.
          You either started only the binary or did not edit the shell
          script/batch file to give the correct library path. You must
          start the binary with the command line option -l path where
          path is the path to the GAP home directory. See section Command
          Line Options in the reference manual.
   When starting, GAP produces error messages about undefined variables.
          You might have a .gaprc file that was intended for GAP 3 but is
          not compatible with GAP 4. See section The .gaprc file in
          chapter Running GAP of the reference manual.
   GAP stops with an error message: ``cannot extend the workspace any
          more''.
          Your calculation exceeded the available memory. Most likely you
          asked GAP to do something which required more memory than you
          have (as listing all elements of _S_15 for example). You can
          use the command line option -g (see section Command Line
          Options in the reference manual) to display how much memory GAP
          uses. If this is below what your machine has available (this
          happens for example under Windows) extending the workspace is
          impossible. Start GAP with more memory or use the -a option to
          pre-allocate initially a large piece of workspace.
   GAP complains: ``corrupted completion file''.
          Some library files got changed without rebuilding the
          completion files. This is often a sign that earlier bugfixes
          were not installed properly or that you changed the library
          yourself. In th elatter case, start GAP with command line
          option -N and see section Completion Files.
   GAP stops with an error message ``exceeded the permitted memory''.
          Your job got bigger than what is permitted by default (128MB).
          (This is a safety feature to avoid singe jobs wrecking a
          multi-user system.) You can type return; to continue, if the
          error message happens repeatedly you better start the job anew
          and use the command line option -o to set a higher memory
          limit.
          make complains about not being able to find files in cnf or src
          which
   exist.
          The dates of the new files were not extracted properly
          (Alpha-OSF machines are prone to this). Call
   touch * cnf/* src/*
          from the main GAP directory (this ought to reset the date of
          all relevant files to ``now'') and try again.
   Recompilation does not actually compile changed files.
          The dates of the new files were not extracted properly. Go in
          the source directory and touch (UNIX command to change date)
          the new files.
   Recompilation fails or the new binary crashes.
          Call make clean and restart the configure / make process
          completely from scratch. (It is possible that the operating
          system and/or compiler got upgraded in the meantime and so the
          existing .o files cannot be used any longer.
   A calculation runs into an error ``no method found''.
          GAP is not able to execute a certain operation with the given
          arguments. Besides the possibility of bugs in the library this
          means two things: Either GAP truely is incapable of coping with
          this task (the objects might be too complicated for the
          existing algorithms or there might be no algorithm that can
          cope with the input). Another possibility is that GAP does not
          _know_ that the objects have certain nice properties (like
          being finite) which are required for the available algorithms.
          See sections ApplicableMethod and KnownPropertiesOfObject.
          
   _Problems specific to Windows_
   
   The gap.bat file does not start GAP.
          Make sure you ran instwin.bat. If your version of Windows uses
          a language other than English you must still edit the resulting
          file gap.bat in the bin subdirectory, due to a misdesign of
          Windows.
   Windows complains Out of environment space.
          Click the batch file instwin.bat or gap.bat which caused the
          problem with the right mouse button and select
          Properties,Memory and increase the initial environment space to
          at least 1024. This will create a pif shortcut which should be
          used to start GAP.
   Command line editing does not work under Windows.
          The default key commands are UNIX-like. GAP also tries to
          emulate some of the special keys under Windows, however if the
          key repeat is set too high, Windows loses parts of the codes
          for these keys and thus GAP cannot recognize them. Windows98
          produces the same scan code for all cursor keys. As GAP does
          not interface directly with the Windows machinery, there is no
          way around this problem so far.
   The ^-key cannot be entered.
          This is a problem if you are running a keyboard driver for some
          non-english languages. These drivers catch the ^ character to
          produce the French accent-circonflexe and do not pass it
          properly to GAP.
   Cut and Paste does not work
          See http://www-gap.dcs.st-and.ac.uk/~gap/Info4/windows.html for
          a remedy.
          
   _If all these remedies fail_ or you encountered a bug please send a
   mail to gap-trouble@dcs.st-and.ac.uk. Please give the input which
   caused your problem and state the machine, operating system and
   version of GAP (for example ``gap4r2, fix1'') you are using.
   
