[README.install for MetaCard 2.5 Apr 18, 2003]

=========================== Upgrading =============================

If you're upgrading from a previous version of MetaCard, we recommend
a fresh install of MetaCard 2.5 rather than upgrading a previous
release by replacing selected files.  The first step in the upgrade is
to move any substacks of your current Home stack out into separate
files.  You do this by opening "stack properties" for the Home stack,
choosing "components" and then topleveling any stacks you see there.
Use "Save as..." from the File menu to save each stack you want to
keep into its own file.  Then back up all your stacks.  On Windows
systems you can uninstall MetaCard with the "Add/Remove Programs"
control panel.  On all systems, you can uninstall MetaCard by renaming
or deleting the directory the MetaCard files are stored in (/Program
Files/MetaCard for Windows systems).

This release uses the MetaCard subscription keys that were distributed
starting with the 2.2.1 release.  If you purchased your license after
to March 2000, your key will work with this release.  If you purchased
your license before then, you'll need to renew your subscription
before you'll be able to use this release.  Choose "Licensing" from
the Help menu to renew your subscription.  Details on the MetaCard
subscription model licensing can be found on the MetaCard WWW site.

After licensing, restore your backed up stacks, being sure not to
overwrite any of the MetaCard files (mchome.mc, mctools.mc, or
mchelp.mc) with the files from a previous release.

========================= MacOS Installation ======================

On MacOS systems, the complete distribution isin the file MacOS.sit on
the FTP sites and the directory "MetaCard 2.5" on physical media
distributions.  To install MetaCard, just unstuff MacOS.sit and then
move the folder "MetaCard 2.5" to a convenient place on your hard
drive.  The engines for 68K and Carbon (Mac OS X) are compressed
within the archive.  You can unstuff them later if you need to run on
or build standalones for these platforms.

======================== Windows Installation =====================

The files required to run MetaCard on Windows systems are in the file
mcsetup.exe.  You download this one file and execute it to install
MetaCard on those systems.  Be sure that you don't have a lot of junk
in your /TEMP/ or /WINDOWS/TEMP/ directories or the installer may fail
(the /Program Files/MetaCard/ directory will be empty or only have a
couple of files in it if this happens).  Those TEMP directories should
be empty if you're not running any other applications, but program
bugs and crashes can leave garbage in there that accumulates over
time.  While you're at it, make sure that your root directory (usually
C:/) also doesn't have a lot of junk in it.  Be more careful when
deleting files there, as some are important for booting Windows.
Anything with a .chk or .tmp or ending with a string of numbers is
safe to delete.

Be sure that you have the absolute latest drivers for your graphics
card before using MetaCard.  Many of the drivers that ship with
Windows 95 and 98 are severely broken and you'll see strange things
like missing images, wrong colors, garbage left on the screen after
windows are closed or objects are moved, or even application or system
crashes.  If you see any of these things and can't upgrade your
display adapter driver, turning off acceleration (using the
"Performance" tab in the System control panel) will often eliminate
them.  Similar problems have also been reported with printer drivers,
and upgrading to the lastest versions of those drivers will usually
correct printing problems.  Setting the "printColors" property to
false also cures problems with some printers that lack sufficient
memory to print large images in color.

To run MetaCard on Windows 3.1 systems, you must unpack the files on
an 95/NT system and then copy them over to the 3.1 systems, and must
have previously installed the Win32s system extension.  The latest
known version was in a file "PW1118.EXE" on the Microsoft WWW site
http://www.microsoft.com/, but they seem to move it on a regular
basis.  Search there or ask Microsoft technical support for a pointer
to it.  See the file README.2.5 for directions and limitations on
running MetaCard on Windows 3.1.

========================== UNIX Installation ======================

For UNIX systems, you'll need to get the file "stacks.tgz" which
contains the MetaCard development environment and on-line
documentation.  You'll also need an engine appropriate for your
platform (e.g., sparc.tar or rs6000.tar, see the file README.1st for
platform name and OS version information).

To install MetaCard on a UNIX system, put the distribution files in a
convenient, preferably empty, directory.  The run "sh unpackmc.sh" to
unpack the distribution into a directory of your choice, or use "tar"
and "gunzip" to unpack the files yourself.

Then just run the program "mc" to start up MetaCard.  If no program
starts up, you either have the wrong engine for your platform, or the
current directory (".") is not on your PATH.  You can work around the
latter problem by running "./mc", but this is not a good long-term
solution since you will not be able to play movies using the included
xanim player if "." or the current directory is not on your PATH.  See
your Unix documentation or ask your sysadmin about adding directories
to your PATH (hint, it's usually set in your .profile file).

If you see some other program start up when you run "mc" (e.g.,
"Midnight Commander" on Linux systems), either run "./mc", put "." on
your path before /usr/bin, or delete or rename the "mc" in the
/usr/bin directory.  You could also rename the MetaCard engine, but
you lose the ability to start up a stack directly from the command
line if you do this.

If you've got an older version of xanim on your PATH, remove it,
rename it, or make sure that the MetaCard directory is on the PATH
before the directory containing the old xanim executable.

MetaCard consists of an engine and a collection of stacks.  The most
important stack is the Home stack.  An unlicensed Home stack
(mchome.mc) is included in this distribution.  The other stacks in the
distribution are the tools stacks (mctools.mc), the on-line
documentation (mchelp.mc), and the MetaCard demo stacks (mcdemo.mc).

From the Home stack, your first steps should be to look at demo stack
if you have it.  You should also go through the Tutorial stacks
(choose "Tutorials" from the "Help" menu) and do some exploring of the
help system as you go.  A quick trip through the Concepts & Techniques
stack would also be time well spent.

If you need a hardcopy scripting reference, you can order one (choose
Licensing from the Help menu for more information).  Also note that
any book on HyperCard can be used as a getting started guide since
MetaTalk is compatible with HyperTalk.  See the Concepts & Techniques
and FAQ stacks for references.  Just keep in mind that the MetaCard
development environment is not the same as HyperCard's, just the
scripting language.

========== WWW browser Helper Application Configuration ===========

Most WWW browsers can be set up to start up Helper Applications when
you click on a link to a file of a type not supported by the browser.
Though the Helper Application opens the file in a new window, it is a
quick and easy way to deliver MetaCard-based content over the
Internet.  To use MetaCard as a Helper Application, you'll need to put
the engine and mctools.mc someplace on your $PATH and register it as a
helper application with the file extension "mc".  With Netscape you do
this by adding the following line to a file named .mime.types in your
$HOME directory: application/metacard mc

You must also add a line to a file named .mailcap in your $HOME
directory:
application/metacard; mc -f %s

After creating these files, you must force your browser to reread
them.  You can do this by restarting the browser, or with Netscape by
opening the "Helpers" section of the General Preferences dialog and
pressing the OK button.

It's important to include the -f option to the "mc" command which
disables opening files and starting processes.  If you leave this flag
off, MetaCard will have full access to your file system which is a
large security hole.  If your browser has a GUI interface for
specifying helper applications which doesn't allow specifying
command-line parameters, setting an environment variable named
MCNOFILES to some value other than "0" before starting up your WWW
browser will achieve the same result.

Use the Helper Application Checker on the MetaCard Stacks page
(accessible from the MetaCard Home Page http://www.metacard.com) to
verify correct installation.

To make MetaCard stacks available on your own HTTP server, you'll need
to add new file type information to the server configuration files
(which files you have to edit depends on which HTTP server you're
using.  See your HTTP server documentation on adding types for more
information).  Some servers allow adding types by putting the
following line in a file named .htaccess in the directory with the
MetaCard files:
AddType application/metacard mc

============ X server and window manager configuration ============

Be sure that both the 75dpi and the 100dpi font directories are on the
server's font path ("xset q" will show the current font path, "xset
+fp directory" will add a directory to the font path).  Some systems
(notably Suns and DECs) don't come with all the MIT standard fonts.
On these systems the MetaCard engine will substitute fonts
(occasionally with ugly results).  One of the first places you'll see
this is in the demo stacks.

Although MetaCard sets the appropriate properties for use with olwm
(the window manager that comes with Open Windows on SPARC systems),
its use is actively discouraged.  olwm never was all that robust (see
the BUGS.txt file) and now that it obsolete (Sun will be using Motif
in all future products) time spent making MetaCard compatible with it
is not a good investment.  If you don't have Motif on your Sun system
yet, there are a number of places to get it at a reasonable price.
For example, MetroLink (305-970-7353) has a complete Motif package for
SPARC and Linux systems at a very reasonable price.

Use of twm and other window managers is also discouraged as they
frequently don't properly enforce modal dialog boxes, don't honor
application specifications of positioning and sizing of windows, and
don't provide application control over window decorations.  They also
frequently have a confusing "destroy window"/"delete window" pair in
their menus, one of which calls xkill, aborting the application
without confirmation and possibly causing data loss.  On Linux systems
use mwm if possible and fvwm if not.  If you must use fvwm be sure to
enable full Motif emulation in the file
/usr/lib/X11/fvwm/system.fvwmrc or ~/.fvwmrc.

As an active focus application, MetaCard relies on window managers
being set to explicit input focus (click to type).  It will work with
focus follows pointer modes, but you run the risk of seriously
damaging your stacks every time you use the layout tools, utilities
stacks, or even cut/copy/paste from the Edit menu.  Tools that require
a text selection, such as the character chooser also don't work with
pointer focus.  This is not just a religious issue: there are no
workarounds for these problems, because pointer focus is fundamentally
incompatible with modern GUI application design principles since text
selections cannot be maintained properly in multi-window applications.

We *strongly* recommend using explicit focus when using MetaCard.  mwm
and olwm use click-to-type focus by default, and it is the only focus
policy available on the Mac, MS-Windows, OS/2, and NextStep.  SGI is
the only vendor who insists on using this obsolete UI technique by
default.  If you're not sure which mode your window manager is using,
move the mouse from one window to another.  If the border of the new
window changes, your window manager is using pointer focus, and it
should be changed.  Here are the relevant resources to put in your
.Xdefaults file.  You might also ask your system administrator to
change the appropriate file in the directory /usr/lib/X11/app-defaults
back to their factory defaults:

olwm
  OpenWindows.SetInput: select
    value can be "select" or "followmouse"
  The -c command line option to the olwm command can also be used in
  /usr/openwin/lib/Xinitrc.

mwm
  Mwm.keyboardFocusPolicy: explicit
    value can be "explicit" or "pointer"

On SGI systems, you may have to change /usr/lib/X11/app-defaults/4DWm
to change this behavior.  The implementation of pointer focus with
active-focus applications in olwm is broken, so you'll have to specify
the -pointer option on the MetaCard command line if you're determined
to use pointer focus with olwm.

On all systems, you must restart the window manager after making this
change.  Most WMs have a "Restart" option in the root window menu, but
with others you'll have to log out and log back in to restart it.

There are also settings in the MetaCard "Preferences" dialog for
enabling pointer focus and disabling raising of menus bars when menus
are opened which doesn't work properly under fvwm due to a bug in
fvwm.

================= Special note for x86 UNIX users =================

The "solintel" engine was built on a Solaris x86 system, and may or may
not run on other SVR4 systems.  If it doesn't work, please try the ODT
engine, and report the incompatibility as a bug to your OS vendor
(MetaCard has been certified ABI+ compliant, as are most of the
affected OSes).  To run the "solintel" engine on some x86 SVR4 UNIX
systems, you need to make symbolic links from your X11 libraries to
the names the MetaCard engine expects.  To make the links, execute the
following two commands as root (note that the exact path to these
libraries may be different on your system):

ln -s /usr/lib/libX11.so.5.0 /usr/lib/libXext.so.0
ln -s /usr/lib/libXext.so.5.0 /usr/lib/libXext.so.4

======================= Licensing MetaCard ========================

To get a save-enabling key for MetaCard, fill out the license form
(pick Licensing from the MetaCard "Help" menu), and email (or phone)
it in.  If you include a credit card number, a key will be generated
and emailed to you immediately via return email (the credit card
number is encrypted in the transmission for your protection).

If you can't use a credit card to purchase MetaCard, please put a PO
number in the credit card field.  The PO can be faxed to 303-499-9855
to expedite processing.  Keys may or may not be issued on receipt of
the PO, depending on the size and credit rating of the purchasing
organization.  MetaCard Corporation will send an invoice to your
purchasing department after receiving the PO.  Note that unless it
specifically requested, a physical media distribution will not be sent
with the invoice.

To license MetaCard, the stacks must be owned by you, and that you
must also own and have write permission in the directory they are in
before you'll be able to complete the licensing process.  If the root
user installed the software, the root user will have to change the
ownership of the files.  As with any end-user application, running
MetaCard when logged in as root is discouraged since you may
accidentally damage important files on your system.

After licensing MetaCard, you'll probably want to move the executables
out of harm's way.  They must be moved some place listed in the PATH
environment variable.  We recommend /usr/local/bin, but you may have
to create that directory and add that directory to your PATH
environment variable (which is usually set in the .profile, .cshrc, or
.login file in your home directory).  Move the engine (mc), the tools
stack (mctools.mc), and the help stack (mchelp.mc) to the directory of
choice, and write-protect them (e.g. "chmod a-w mc mctools.mc
mchelp.mc").  The home stack (mchome.mc) should be left in one of your
own directories (such as your home directory), since you will probably
edit it frequently.

Note that if the home stack is not writable, or is not named
mchome.mc, MetaCard will behave as if it were unlicensed.  This is to
ensure that multiple users don't share a home stack.  Please help us
enforce the licensing agreement by restricting access to the home
stack to the licensed user (chmod 700 mchome.mc).

=================== Calling external C functions ==================

If you want to write external commands or functions ('C' functions
that can be called from MetaCard), you'll need to build the sample
external and complete the External Tutorial.  On Windows systems, the
external package can be found in the MetaCard folder.  A Visual C++
project file is included in the distribution, but you can easily build
a project file for other compilers but just adding all of the .c and
.h files.

On UNIX systems, uncompress and untar the file external.tgz in
another directory.  The Makefile will have to modified to work
properly on your system by uncommenting the appropriate lines and
changing library or include file paths, if necessary (sorry, imake is
not supported).  A stack to exercise the external is one of the
tutorials.  Use this stack to verify that the existing external works
before modifying it.  Note that the executable "external" has to be in
a directory on your PATH before the External Tutorial stack will work.

If you have any trouble with the installation or use of MetaCard, send
email to "support@metacard.com" or call 303-447-3936.  Be sure to
include your machine type and operating system version (the command
"uname -a" will give you this information).
