			   Macaulay 2
	    by Daniel R. Grayson <dan@math.uiuc.edu>
	 and Michael E. Stillman <mike@math.cornell.edu>

	available from http://www.math.uiuc.edu/Macaulay2/

----------------------
1. Introduction
----------------------

Macaulay 2 is a software system for algebraic geometry research, written by
Daniel R. Grayson and Michael E. Stillman with generous support of the
National Science Foundation, for which we thank them.

----------------------
2. Installation
----------------------

We assume now that you are installing a binary distribution.

If you are installing Macaulay 2 on a Windows machine, see the special
instructions in a later section of this document.

You have downloaded an unpacked a file with a name something like

    Macaulay2-0.9-i686-Linux.tar.gz

Untarring this file creates a directory called Macaulay2-0.9, where 0.9 may be
replaced by the current version number, and whose subdirectories and files are
organized as follows:

    Macaulay2-0.9/bin/M2
	    - the shell script that starts Macaulay2.
    Macaulay2-0.9/bin/M2-help
	    - a shell script that starts your web browser reading the online
	      documentation in the form of html files
    Macaulay2-0.9/INSTALL
	    - a one line pointer to this file
    Macaulay2-0.9/lib/Macaulay2-0.9/README
	    - this file
    Macaulay2-0.9/lib/Macaulay2-0.9/
	    - the directory containing Macaulay2's files.
    Macaulay2-0.9/lib/Macaulay2-0.9/setup
	    - a shell script that dumps pseudo-compiled Macaulay 2 code.
    Macaulay2-0.9/encapinfo
	    - a configuration file used by 'epkg' to install packages.
    Macaulay2-0.9/postinstall
	    - a shell script used by 'epkg' when installing packages.
	      It runs 'setup' for you (see below) and edits the file bin/M2 to 
	      record the location of Macaulay2's directory.

There are two ways to install the package:

    1. Automatically, with 'epkg'.

	Put the entire Macaulay2-0.9 directory tree in the source directory
	for epkg, which is /usr/local/encap by default.  Then run

		epkg Macaulay2

	The program 'epkg' is available from

		http://encap.cso.uiuc.edu/epkg/

    2. Manually

	There are four steps.

	a.  Edit the shell script bin/M2 to record the location of Macaulay2's files.
	    The line starting with 'M2HOME=' should be made to look like
		M2HOME=/.../Macaulay2-*.*/lib/Macaulay2-*.*
	    where you replace ... by the path to the directory created
	    by untarring, and *.* is the version number provided.

	    Then put a link to it from a directory on your path.

	b.  Edit the shell script bin/M2-help (relative to the top of the distribution
	    directory tree) to record the location of Macaulay2's files, as above.

	    Then put a link to it from a directory on your path.

	c.  Edit the file emacs/M2-init.el (located relative to the directory
	    this README file is in) to record the location of Macaulay2's files.
	    The first line should be
		(defvar M2HOME "/.../Macaulay2-*.*/lib/Macaulay2-*.*")
	    where ... is replaced by the same path as in step (a) above.

	d.  Optionally run this command:

		setup

	    or
		./setup

	    if it's unix and '.' is not first on your path.

		NOTE (for system administrators): On some types of computers
		Macaulay 2 will take extra time to start up: it will print
		"loading source code" and load the contents of about 100
		files containing code written in the Macaulay 2 language.
		On other types of computers, this process is replaced by one
		we call "loaddata", which is much quicker because it
		involves mapping into memory a large file containing an
		image of the data segment of the program saved with
		"dumpdata" by the "setup" script mentioned above.  That
		'dumpdata' file is named libexec/Macaulay2-*-data, where *
		identifies the type of system you have.  That file and the
		binary executable file libexec/Macaulay2.exe or
		libexec/Macaulay2 are the only architecture dependent files:
		the rest may be shared.  On Sun machines, the differences
		between architectures sun4d and sun4c are slight enough that
		the binary file bin/Macaulay2 will work on both, but the
		libexec/Macaulay2-XXXX.data files will differ.  If you have
		both of these types of machines, you can run 'setup' on each
		of these in the same directory tree.

After installing the package, to see if Macaulay 2 works, run 'M2',
make a ring with

	R = ZZ/101[x,y,z]

and then make a resolution with

	res coker vars R

Here's what you should get:

	      1      3      3      1
	o2 = R  <-- R  <-- R  <-- R  <-- 0

	     0      1      2      3      4

	o2 : ChainComplex

The directions above are intended mainly for system administrators.  The next
thing that individual users should do is to read the file emacs/README.  On
all systems except the Macintosh, the best way to interact with Macaulay 2 is
through an emacs macro package we provide.

----------------------
3. The manual
----------------------

The manual is available in various forms, and includes tutorials as well as
descriptions of each function.  Its constituent files are provided in a
separate tar file at our web site, as mentioned above.

A. While running Macaulay 2.

    While running Macaulay2, on-line help is available on 
    predefined functions and types, and other topics.  For example,
    'help Matrix' gives information about matrices, and
    'help matrix' describes the 'matrix' command.

    Also useful is the 'apropos' command: 'apropos "Matrix"' will return
    a list containing all identifiers containing the string "Matrix".
    One caveat: it is case sensititive, so that for example the 'matrix'
    routine will not appear on the list.

B. With a web browser

    The directory 'html' contains the documentation in HTML form.  Start
    at the file 'html/index.html' using your favorite web browser, such as
    Netscape or Internet Explorer.

----------------------
4. Other documentation
----------------------

The file emacs/emacs-hlp.txt gives a brief tutorial introduction to the use of
emacs with Macaulay 2, and includes some lines of emacs code to put into your
.emacs file.  One nice feature of emacs' Macaulay 2 mode is command
completion.

See also emacs/emacs.m2, for information about editing Macaulay 2 source files.

Read the file CHANGES to see what changes have been made since the last
version you used.

-------------------------
5. Licenses and copyright
-------------------------

Macaulay 2 is copyright 1993-2001 by Daniel R. Grayson and Michael
E. Stillman.  We permit you to use it under the terms of the GNU General
Public License, version 2, as published by the Free Software Foundation; see
the file COPYING.  This is free software.  There is no warranty; not even for
merchantability or fitness for a particular purpose.

----------------------
6. Distribution
----------------------

Take a look at the home page for Macaulay 2

	http://www.math.uiuc.edu/Macaulay2/

to download the source code, versions of Macaulay 2 for various machines, or
the documentation.

----------------------
7. Other help
----------------------

Send email to <Macaulay2@math.uiuc.edu> if you get stuck.  Email to that
address will get forwarded to both of us.

	Dan Grayson <dan@math.uiuc.edu>
	Mike Stillman <mike@math.cornell.edu>

------------------------------------------------------------------
8. Notes on Windows 95/NT installation
------------------------------------------------------------------

    ** this section may be out of date **

    You will have downloaded a file with a name like this:

              Macaulay2-0.9-i586-Windows-95-98-NT.zip

    This file contains the files you need to run the program, as well as the
    html documentation files.  If you want the dvi file containing the book
    form of the documentation, you'll have to download that separately.

    To unpack it you will need a program like WinZip or PKZIP for Windows.
    You can get WinZip from http://www.winzip.com, and you can get PKZIP from
    http://www.pkware.com.  It is important not to use the older PKUNZIP
    program for MSDOS, because it will truncate filenames to 8+3 characters.
    Be careful when using these programs - they tend to have an option for
    ignoring the path names we provide, in which case they will dump all of
    the files into a single directory.  For WinZip, make sure the check box
    "Use Folder Names" is checked.  Check that you obtain files in
    directories with names including the following: Macaulay2/m2,
    Macaulay2/bin, Macaulay2/tutorial, Macaulay2/html, Macaulay2/cache, and
    Macaulay2/emacs.

    After unpacking the file, you must follow the instructions in the
    installation section above.  In particular, you will run the 'setup'
    program.  The source code is provided in the file Macaulay2/util/setup.c
    - it's pretty simple.  It produces a script called 'M2.bat' which you can
    use with Windows or in an MS-DOS window.

    We are currently using the Microsoft Visual C/C++ compiler, running under
    Windows NT, to compile Macaulay 2 as a 32 bit application.  It should
    work equally well under Windows 95, Windows 98, and Windows NT.  It
    should also work on both 486 and Pentium machines.

    We don't support Macaulay 2 for Windows 3.1 or for MSDOS, but the source
    code is available on our web site, and you're welcome to try to compile
    it and see whether it can pass all of our tests.

    When running Macaulay 2 under the bash shell obtainable from
    http://www.cygnus.com, it thinks its standard input is closed or
    truncated in random ways.  One can avoid this by using Macaulay 2 only as
    described below, but it is annoying.

    The best way to run Macaulay 2 under Windows is inside emacs, using our
    provided emacs macros, as described below.  The version of emacs that
    works under Windows 95 and Windows NT is is NTemacs.  It is available at
    http://www.cs.washington.edu/homes/voelker/ntemacs.html .  We recommend it
    highly - it includes on line tutorials and documentation, and once you
    learn it, you will probably want to make it your only text editor.

    One problem with running Macaulay2 in a shell window inside emacs running
    bash is that Macaulay2 can't tell it is talking to a tty, and hence won't
    offer input prompts soon enough.  To fix this problem, add "-tty" as an
    argument to the command line when starting the program, like this:

	     M2 -tty

    This problem also affects running Macaulay2 inside emacs using our
    macros.  Assuming you have version 20, add the following line to your
    .emacs file:

	(setq explicit-M2-args '("-tty"))

    Another problem that may occur wehn running Macaulay2 inside emacs is
    the appearance of ASCII carriage return characters on the screen at the
    end of each line as "^M" combinations.  To eliminate this, put the
    following lines in your .emacs file.

	(setq process-coding-system-alist
	      (cons (cons "M2" 'raw-text) process-coding-system-alist))

    or maybe even

	(setq process-coding-system-alist
              (cons (cons "M2" (cons 'raw-text-dos 'raw-text-unix))
	            process-coding-system-alist))

    Eventually you may want to interchange the control key with the caps lock
    key on your Windows keyboard.  This can be done.  For Windows 95, you can
    use the Kernel Toys from Microsoft, available at
  http://www.microsoft.com/windows/downloads/contents/powertoys/w95keybdremap/default.asp
    .  For Windows NT you could use the following procedure, which worked for
    us, and came from Chris McMahan <cmcmahan@teknowledge.com>.

    >> Open the registry editor and go to:
    >> HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\KeyBoard Layout
    >> 
    >> (note:  KeyBoard Layout, not KeyBoard Layouts)
    >> 
    >> Then create a new binary value by right-clicking on the KeyBoard
    >> Layout entry in the left window and selecting New\Binary Value
    >> 
    >> A new entry will appear in the right window called "New Value #1",
    >> rename this to "Scancode Map" (no quotes).
    >> 
    >> Right click on the new entry you just created, select the Modify
    >> entry and you'll see a window with a Value name field and a large
    >> textarea (named Value data:) with the value 0000 in it.
    >> 
    >> Click on the 0000 and a text prompt will appear in the text area.
    >> Then type the following values in this area:
    >> 
    >> 00 00 00 00 00 00 00 00 
    >> 
    >> At this point, a new row will be created with the label
    >> 0008
    >> 
    >> Now type these values:
    >> 
    >> 03 00 00 00 1d 00 3a 00 
    >> 
    >> and a new row will appear with the label
    >> 0010
    >> 
    >> type these values into this row
    >> 
    >> 3a 00 1d 00 00 00 00 00
    >> 
    >> A new row will appear with the label 0018...ignore it.
    >> 
    >> Now review the text area and ensure it looks like this:
    >> 
    >> 0000  00 00 00 00 00 00 00 00
    >> 0008  03 00 00 00 1d 00 3a 00
    >> 0010  3a 00 1d 00 00 00 00 00  
    >> 0018
    >> 
    >> Press the ok key, and VOILA! you have modified the scancode for your
    >> system. Close the registry and reboot your machine, and your CapsLock
    >> and Ctrl key should now be swapped.

    Another way to run Macaulay 2 under Windows is to set up a shortcut for
    opening an MSDOS window that provides you with very wide lines.  Create
    such a shortcut, and then edit the numbers on the Layout tab in the
    Properties window.  Make the width as large as you can, and make the
    height as large as you want.  (Macaulay 2 doesn't wrap lines for you, so
    if you print out a wide matrix, you will want the window not to wrap the
    lines either, for it will tend to separate things that below together,
    like variables and their exponents.  Making the lines very wide will
    allow you to scroll left and right to view large matrices.)
