[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).