README, July 1995


This directory contains the necessary files to install MuPAD, the Multi
Processing Algebra Data Tool, Version 1.2.2.

Note that you have to obtain a license of MuPAD in order to get the full-
featured MuPAD version.

Copyright (C) B. Fuchssteiner, Automath, University of Paderborn, Germany.
All rights reserved.

Users of Version 1.2/1.2.1 should read the chapters 'How to install MuPAD' and
'How to upgrade MuPAD'.

Contents
--------

* How to order MuPAD
* Before you get MuPAD
* How to get MuPAD
* How to install MuPAD
* How to run MuPAD 
* Possible warnings when starting MuPAD
* How to upgrade MuPAD
* Disc space needed for MuPAD 
* How to reduce disc space
* Differences on IBM RS/6000
* Remarks on Silicon Graphics
* Remarks on HP
* Remarks on Sun4
* Known Bugs


How to order MuPAD
------------------

At present MuPAD is available for the Sun 4 machine types, IBM RS/6000,
Silicon Graphics, DECstation, Apple Macintosh and 386/468 PC's under
Linux or FreeBSD. Pre-release versions exist for the Sequent Symmetry.
If you want to receive information about further please subscribe to

              MuPAD-talk@uni-paderborn.de

Subscription is free of charge.

The full-featured Sun4-, IBM RS/6000-, Silicon Graphics-, DEC-, Macintosh-
HP-, Linux- and FreeBSD-versions of MuPAD are available to all scientific and
educational non-profit institutions free of charge. Commercial institutions
should inquire about the respective license conditions either at

              MuPAD-distribution@uni-paderborn.de

or they should write to

              MuPAD-Distribution
              University of Paderborn
              Deptartment of Mathematics
              Warburger Str. 100 
              D-33095 Paderborn

              Germany

To obtain a license of MuPAD  for a non-profit organization just sign a copy
of the enclosed license (see file LICENSE) and send it to the address above.
Furthermore we need the name of a contact person and preferably an e-mail
address. You then receive a keyword and an ftp-address so that you can
copy and decode the MuPAD system.

For users who cannot use "ftp" MuPAD is supplied on appropriate media. If
you order MuPAD on media we expect you to reimburse for our expenses.

(1)	Exabyte 8mm 		$50 (75,- DM)
(2)	1/4" tape   		$50 (75,- DM)
(3)	1.44 MB, 3,5" disks 	$25 (40,- DM)

(1),(2) Sun 4, SGI, DEC, HP	(3) PC, Macintosh


A detailed description of MuPAD you will find in the manuals:

in German:
  Birkhaeuser Verlag Basel, 1993
  MuPAD: Multi Processing Algebra Data Tool;
  Benutzerhandbuch; MuPAD Version 1.1
  ISBN 3-7643-2872-X

in English:
  Birkhaeuser Verlag Basel, 1994
  MuPAD: Multi Processing Algebra Data Tool;
  Tutorial
  ISBN 3-7643-5017-2

The English reference manual will follow in autumn 1995. There also is
sufficient on-line documentation in English.
(Reference manual, helppages, tutorial, sample session and a demo in English)


Before you get MuPAD
--------------------

You must obtain a password to get the full-featured MuPAD version. Please 
get your password before you proceed. Without registration you get only
a demo version.

Before you copy MuPAD from the ftp server you should decide which kind of
binaries you need. There are 7 different kinds of binaries:

- binaries for Sun4 (SunOS)

- binaries for Sun4 (Solaris)

- binaries for IBM RS/6000 (AIX)

- binaries for DECstations (Ultrix)

- binaries for Silicon Graphics (Irix)

- binaries for Hewlett Packard (HP-UX)

- binaries for PC 386/486 (Linux)

- binaries for PC 386/486 (FreeBSD)

Sun4 contains dynamically and statically linked binaries.
The binaries which use dynamic linked libraries, are normally prefered
as they are much smaller and need less system resources. To use the 
dynamically linked binaries the shared libraries of the XView-Toolkit
must be installed on your system. You can choose the binaries 
appropriate to your system during unpacking.

Linux contains only dynamically linked binaries.

In order to run Sun4 (SunOS) binaries you need: 

- SunOS 4.1.1 or later
- OpenWindows 2.0/3.0 or X11 R5/R6
  - using the dynamically linked version you need the shared libraries
    libxview.so.3.0, libX11.so.4.2, libolgx.so.3.0 or later

In order to run Sun4 (Solaris) binaries you need:
 
- Solaris 2.3/2.4 (SunOS 5.3/5.4)
- OpenWindows 3.0/3.4 or X11 R5/R6
  - using the dynamically linked version you need the shared libraries
    libxview.so.3, libX11.so.4, libolgx.so.3
    These are the OpenWindows libraries distributed by Sun for Solaris 2.3
  - the meaning of a statically linked version is as follows:
    All of the X and XView libraries required by MuPAD are statically
    linked. Standard libraries like libc are dynamically linked.

In order to run IBM RS/6000 binaries you need:

- AIX 3.2 or later
- AIXWindows 3.1 (X11R5) or later

In order to run Linux binaries you need:

- Linux 1.0 or later
- XView 3.0 Linux Release 4 and X11R5 or X11R6
  - you need the shared libraries
    libxv3.so.3.0, libolg.so.3.0, libX11.so.3.1.0.
    MuPAD should also work with older versions, for example 
    libxv3.so.2.0, libolg.so.2.0, libX11.so.3.0, but this has not been tested.
- We recommend 12-16 MB main memory

In order to run Silicon Graphics binaries you need:

- IRIX 5.2 or later

In order to run Silicon Graphics binaries you need:

- HP-UX A9 or later

In order to run DECstation binaries you need:

- Ultrix 4.3 or later

In order to run FreeBSD binaries you need:

- FreeBSD 2.0 or later
  - XView 3.2   
    - using the dynamically linked version you need the shared libraries
      of FreeBSD 2.0 and XFree86 2.1.1

* Sun4 (SunOS 4.1.x) binaries work also with Solaris 2.x (SunOS 5.x)
See 'How to install MuPAD' for details.


How to get MuPAD
----------------

Before you copy MuPAD via ftp, you should create and change to the directory
in which you want to install MuPAD, say /usr/local/MuPAD for example:

mkdir /usr/local/MuPAD
cd /usr/local/MuPAD

You may use any other directory instead of /usr/local/MuPAD. After you have
created and changed to the MuPAD root directory, you should copy the MuPAD
files to that directory. They come as compressed, tar-files. 

You need to copy the following files from the ftp server:

- README		 -- this file
- unpack.sh		 -- shell script to unpack the MuPAD tar-files
- share.tar.gz		 -- sharable parts of the MuPAD system
- at least one of
    bin.ibmrs6000.tar.gz   -- binaries for IBM RS/6000 (AIX 3.2)
    bin.sun4.tar.gz	   -- binaries for Sun4 (SunOS 4.1.x)
    bin.solaris.tar.gz	   -- binaries for Sun4 (Solaris 2.4)
    bin.sgi5.tar.gz	   -- binaries for Silicon Graphics (IRIX 5.2)
    bin.dec.tar.gz	   -- binaries for DECstation (Ultrix 4.3)
    bin.hp.tar.gz          -- binaries for HP (HP-UX A9)
    bin.linux.tar.gz       -- binaries for PC (Linux 1.x / X11R5)
    bin.linux.X11R6.tar.gz -- binaries for PC (Linux 1.x / X11R6)
    bin.freebsd.tar.gz     -- binaries for PC (FreeBSD 2.x)

Additional software:

- share-ext.tar.gz	 -- extensions of the sharable parts.
			    Animation (only available for Sun4)
- doc-ext.tar.gz	 -- Additional documentation
			     - Moduls, Domains, Polynomials
			    saved as PostScript files.
- doc-small.tar.gz	 -- The manual, the tutorial and the demo are formated
			    according to a screen with a resolution of 600
			    pixel (height).
- xview.fonts.tar.gz      -- XView fonts


A sample ftp session to copy MuPAD might look like:

ftp....
ftp> cd ...
ftp> binary
ftp> get README
ftp> get unpack.sh
ftp> get share.tar.gz
ftp> get bin.sun4.tar.gz
ftp> bye


How to install MuPAD
--------------------

After you have copied the MuPAD tar-files you need to unpack them with the
unpack.sh script. Change to the MuPAD root directory where the tar-files are
located and start unpack.sh. If your MuPAD root directory is /usr/local/MuPAD
for example the necessary commands are:

cd /usr/local/MuPAD
sh unpack.sh

Please stay at the terminal during unpacking as the script may ask for
additional information.

That's all you need to install MuPAD. After unpacking has been completed
you should try to start MuPAD, following the guidelines in section
'How to run MuPAD'.

Users of Version 1.2/1.2.1 should install Version 1.2.2 in a new directory.
Please do not mix up Version 1.2.2 and 1.2 or 1.2.1! See 'How to run MuPAD',
because the directory structure of MuPAD has changed and therefore
some environment variables must be changed.

Sun4 (SunOS 4.1.x) binaries work also with Solaris 2.x (SunOS 5.x)
If you want to run Sun4 binaries with Solaris create a symbolic link
	ln -s sun4 solaris
below the MuPAD root directory. Sun4 binaries runs about 30-50 % 
slower with Solaris than Solaris binaries! 
Note: In this case, you can't use MuPAD's module generator.

SGI (IRIX 4.x) binaries work also with IRIX 5.x . If you want to run
IRIX 4.x binaries with IRIX 5.x create a symbolic link
	ln -s sgi4 sgi5
below the MuPAD root directory.
Note: In this case, you can't use MuPAD's module generator.


Running MuPAD on IBM RS/6000 or DECstation, you may need the XView fonts too.
Copy xview.fonts.tar.gz from the ftp server. To unpack these fonts type:
 
gunzip xview.fonts.tar.gz ; tar xpf xview.fonts.tar ; rm xview.fonts.tar
 
To install these fonts on your system, please read the README, which is
located in the directory Xview.fonts .
See also `Differences on IBM RS/6000` at the end of this README.

To install the 'smaller' documents, please do the following:

gunzip doc-small.tar.gz ; tar xpf doc-small.tar ; rm doc-small.tar
mv doc-small/* /usr/local/MuPAD/share/doc/hytex
rm -rf doc-small

Remember that the directory /usr/local/MuPAD serves only as an example and
must be substituted by the MuPAD root directory in which the MuPAD system is
installed.


How to run MuPAD
----------------

In order to run MuPAD some environment variables must be defined or changed.
The single most important variable ist MuPAD_ROOT_PATH, which defines the
MuPAD root directory:

- MuPAD_ROOT_PATH	-- the root directory of the MuPAD system.
- FONT_PATH		-- the directory where the fonts for the help system
			   are searched for.
- PAGER			-- the pager (ie. more or less) used to display the
			   help pages in a MuPAD terminal session. If not set,
			   more is used.
- MANPATH		-- the search path for man pages.
- path or PATH		-- the command search path.

- LW_PRINTER            -- the name of a Postscript-printer. 
- PREVIEWER             -- the previewer (i.e. xv or xloadimage) used to
                           display GIF-pictures in MuPAD's on-line manual.
                           If not set, /usr/local/X11/bin/xv is used.
			   Note: This is unnecessary for MuPAD 1.2.2

In any case you have to specify MuPAD_ROOT_PATH and FONT_PATH, and you
have to extend the command search path (path or PATH).

Add the following lines to your .cshrc if you use the csh or tcsh:

	#
	# MuPAD environment
	#
	setenv MuPAD_ROOT_PATH /usr/local/MuPAD
	setenv FONT_PATH $MuPAD_ROOT_PATH/share/doc/hytex/fonts
        if ( ! $?MANPATH ) then
           setenv MANPATH ${MuPAD_ROOT_PATH}/share/doc/man
        else
           setenv MANPATH ${MANPATH}:${MuPAD_ROOT_PATH}/share/doc/man
        endif
        set path = ($path $MuPAD_ROOT_PATH/share/bin)

Add the following lines to your .profile if you use a sh, ksh or bash:

	#
	# MuPAD environment
	#
        MuPAD_ROOT_PATH=/usr/local/MuPAD
        export MuPAD_ROOT_PATH
        FONT_PATH=$MuPAD_ROOT_PATH/share/doc/hytex/fonts
        export FONT_PATH
        if test -n "$MANPATH" ; then
	   MANPATH=$MANPATH:$MuPAD_ROOT_PATH/share/doc/man
        else
           MANPATH=$MuPAD_ROOT_PATH/share/doc/man
        fi
        export MANPATH
        PATH=$PATH:$MuPAD_ROOT_PATH/share/bin
        export PATH
 
Remember that the directory /usr/local/MuPAD serves only as an example and
must be substituted by the MuPAD root directory in which the MuPAD system is
installed.

If you have installed less, you could use this pager instead of more:

setenv PAGER 'less -C -w -P"<Commands\: f = forward ; b = backward ; q= quit>"'

respectively

PAGER='less -C -w -P"<Commands\: f = forward ; b = backward ; q = quit>"'
export PAGER

Note: If you don't want users to have to modify their .cshrc or
      respectively their .profile, use the program setup which is
      located in share/bin/admin below the MuPAD root directory.

Remember also that the fonts for the MuPAD help system may be located at
other places than $MuPAD_ROOT_PATH/share/doc/hytex/fonts if the fonts already
exist elsewhere on your system.


Possible warnings when starting MuPAD
-------------------------------------

If you get the system warning 
	No such file or directory, extras menu file 
	/usr/lib/.text_extras_menu (Textsw package)
when starting xmupad, copy the file text_extras_menu which is located in 
$MuPAD_ROOT_PATH/share/xview to /usr/lib/.text_extras_menu .
Can also be set via environment variable EXTRASMENU, for example
setenv EXTRASMENU $MuPAD_ROOT_PATH/share/xview/text_extras_menu

If you get the system warning
	Warning: make sure that you can write <utmp>
when starting xmupad, please check the access permissions of the file <utmp>.
A short extract of the utmp manual page:
Some window systems will make entries in utmp  for  terminal
emulation  windows  running shells, so that library routines
such as getlogin will work correctly in that window.

If you get the MuPAD warning
	Warning: Could not open 'startup.mb', reading system init file.
when starting mupad or xmupad, call rebuild_startup which is located in
MuPAD_ROOT_PATH/share/bin/admin.

If you get the 
	XView warning: Cannot load font '--0' (Font package)
when starting xmupad, please set your LD_LIBRARY_PATH.

If you get the
	XView warning: Cannot load font set 
        '-*-FONT_FAMILY_LUCIDA-medium-r-*-*-*-120-*-*-*-*-*-*' 
        (Font package)
when starting xmupad, the X server will automatically choose a font that
is available.

The
	XView warning: ttysw_sigwinch, 
                       can't get tty process group: Not a typewriter
when starting mdx within a xterm under Linux or HP, is a known bug, but causes 
no problems within the actual MuPAD session.

The MuPAD warning
	Sorry, can't open file: /tmp/xmupad_mupad_connect.xxxx
when starting xmupad, is a known bug, but causes no problems within
the actual MuPAD session. The next release of MuPAD will fix this bug.

How to upgrade MuPAD
--------------------

Call mupad or xmupad and type

	register("<code name>", "<code>");

where <code name> and <code> are taken from the MuPAD licence agreement.

Note: Users of MuPAD 1.2/1.2.1 can use their former code name and code.

Possible errors:

* Wrong password or not registrated user

  You possibly misspelled the code name or code.
  Make sure that there are no leading or trailing blanks.

* Can't cancel memory limitation

  You are not allowed to write into the MuPAD root directory.
  You must have write permission.

* Illegal argument

  You have to enclose the code name and the code in ".


Disc space needed for MuPAD
---------------------------

(1) Standard version

	Standard configuration: 13 - 23 MB

	binaries
           SunOS 4.1.x  --      ~  8 MB (a)
           Solaris 2.3  --      ~ 12 MB (b)
           Linux        --      ~  2 MB (c)
           AIX          --      ~  6 MB
           Irix 4       --      ~  8 MB
           Irix 5       --      ~ 11 MB (d)
           Ultrix       --      ~  8 MB
	share   	--      ~ 11 MB

        (a) Statically linked version : ~ 5 MB
            Dynamically linked version: ~ 2 MB
            Modules                   : ~ 1 MB
        (b) Statically linked version : ~ 9 MB
            Dynamically linked version: ~ 2 MB 
            Modules                   : ~ 1 MB
        (c) Only dynamically linked version available.
        (d) Only statically linked version available.

	Extended configuration: 32 - 42 MB

	binaries	-- 	see Standard configuration
	share		-- 	see Standard configuration
	doc-ext 	--	~  2 MB
	share-ext	--	~ 17 MB

	Minimal configuration: 7 - 17 MB

	binaries	--	see Standard configuration
	share		--	~  5 MB (see 'How to reduce disc space')

(2) Terminal version

	The terminal version is completely independent from any
	window system and therefor all graphical interfaces like 
	xmupad, vcam, mdx and the online hypertext documentation
	are missing. 
	The terminal version contains all of MuPAD's functionality,
	inclusive online help, lineeditor, debugger, profiler,
        modul generator and graphics. The graphics produced by this
    	version are data files. You can use vcam as a standalone
	tool, or you can convert this data to the format, that is
	accepted by another renderer. 

	Standard configuration: ~ 3.3 MB

	binaries	--	~ 1.1 MB
	share		--	~ 2.2 MB

	You need only the directories
          share/bin/  share/lib/   share/doc/ascii/   
          share/mmg/  <arch>/modules
        and only the binaries mupad and mmg in the directory
          <arch>/bin/  
        where <arch> is the machine hardware name, for example sun4.
	If you cannot find the binary mmg and the directory 
	<arch>/modules/, then MuPAD doesn't support the modul generator
	for your hardware, and you can remove the directory share/mmg/


(3) Additional software:

	xview.fonts	-- 	~ 3 MB


How to reduce disc space
------------------------

In order to reduce the disc space needed for MuPAD you may further be able to
delete some TeX-PK-fonts. These fonts are used for the MuPAD help system and
might already be installed on your system.
 
The fonts for the MuPAD help system are located in the directory
 
        share/doc/hytex/fonts/			(~ 160 KB)
 
below the MuPAD root directory. You may delete this font directory if you
allready have these fonts in other places, but note that in this case you must
change the environment variable FONT_PATH according to the existing font
directories. Typical places where such fonts could be located are
/usr/local/tex/fonts/pk118 and /usr/local/tex/fonts/pk300 for example.
 
If your system has the shared libraries libxview.so.3.x, libX11.so.4.x
and libolgx.so.3.x you can remove all files with the extension .static
which are located in sun4/bin, solaris/bin below the MuPAD root directory.


If you do not need the tutorial, you can remove the following files/directories:

	share/doc/hytex/tutorial.*		(~  600 KB)
	share/doc/hytex/bsp/tutorial/           (~  500 KB)
	share/doc/hytex/gif/tutorial/		(~  600 KB)

If you do not need the demo, you can remove the following files/directories:

        share/doc/hytex/demo.*			(~  200 KB)
        share/doc/hytex/bsp/demo/		(~  500 KB)
	share/demo/				(~ 1500 KB)

If your system does not provide MuPAD's modul generator, or if you
do not need the modul generator, you can remove the directory:

	share/mmg/				(~  600 KB)




Differences on IBM RS/6000
-------------------------

Editing Keys
The IBM RS/6000 keyboard does not have a left set of function keys or any
usable function keys past F10. The editing keys can be remapped via xmodmap
(see below for examples) or the standard keyboard equivalents can be used.

Sun             IBM
L2  (Again)     Meta-a
L4  (Undo)      Meta-u
L6  (Copy)      Meta-c
L8  (Paste)     Meta-v
L9  (Find)      Meta-f
L10 (Cut)       Meta-x

Help Key
To use the help functions of XView and OLWM you must bind the Help keysym
to some other key. For example, to make the F8 key act like the Help key, type:

xmodmap - << EOF
keysym F8 = Help
EOF

Meta Key
The AIX Windows keyboard map must first be altered for the Meta key to be
noticed by the XView Toolkit. Use the xmodmap command:

xmodmap - << EOF
keysym Alt_L = Meta_L
keysym Alt_R = Meta_R
EOF


Remarks on Silicon Graphics 
---------------------------

All of MuPAD's graphical interfaces run in 'full-screen-debug' mode, because
of a bug in the X11-server Xsgi. This mode slows down the speed of xmupad,
hypage (hypertext system), mdx (debugger) and vcam (graphic tool).

Within mdx, user input is repeated in the terminal window. This is a bug
in the TERMSW-package of the SGI-XView port.

You have to specify the font for MuPAD's graphical interfaces.
Please select a font with a fixed width. xlsfonts lists all available
fonts on your server. Make an entry in your .Xdefaults, for example
Font.name: lucida-normal-10
or
font.name: screen-medium-15


Remarks on HP
-------------

If you run the HP binaries which uses always dynamic link libraries it
is necessary to change the environment variable SHLIB_PATH. (This variable
is used to search for dynamic libraries at run time.) 
      setenv SHLIB_PATH $SHLIB_PATH:$MuPAD_ROOT_PATH/hp/xview
If you don't want to modify your SHLIB_PATH, you can do the following:
alias xmupad "(setenv SHLIB_PATH $SHLIB_PATH:$MuPAD_ROOT_PATH/hp/xview;\xmupad)"

Remarks on Sun4
---------------

If you run the Sun4 binaries which uses dynamic link libraries it may
be necessary to change the environment variable LD_LIBRARY_PATH. (This
variable is used to search for dynamic libraries at run time.) If you get an
error message from ld.so you should extend LD_LIBRARY_PATH by the directories
where the necessary libraries are located, for example
        setenv LD_LIBRARY_PATH /usr/lib:/usr/openwin/lib:/usr/X11/lib
If you don't want to modify your LD_LIBRARY_PATH, you can do the following:
 alias xmupad "(setenv LD_LIBRARY_PATH /usr/lib:/usr/openwin/lib; \xmupad)"


Known Bugs
----------

In some cases a window remains empty. Activate a window by clicking the 
left mouse anywhere on the window background or click the menu item Refresh 
in the Window popup. This will refresh the contents of a window. 
For example, if you use the dynamically linked version of MuPAD under
Solaris 2.4 you have to do a refresh by hand, because of a bug in the
new Solaris XView libraries.

