How To Install EMacro

• Quick Start
• Upgrade Essentials
• System Requirements
• Detailed Install

Detailed Install

• Required System Information
• Tested Platforms
• Description
• Supported Third Party Programs
• Configuration
• Other Configuration Files
• Mac OS

Quick Start

Just extract emacro*.tar.gz to your $HOME directory. Windows users run %HOME%\emacs\bin\w32\install.bat
Everyone else runs $HOME/emacs/bin/unix/install
Otherwise, in general, and classic Mac OS 8-9.x users in particular, you need to rename init.el to .emacs
Note the leading dot preceding .emacs
If you are new to Emacs keybindings, grab cua.el from emacs.html and put it in the ~/emacs/packages/ directory, before starting Emacs with EMacro. Enjoy!

Upgrade Essentials

If you are upgrading an existing .emacs, you will move your code into ~/emacs/e-postload.el
You can also move code into e-preload.el, if it needs to execute before EMacro. Next, follow the install directions.
What follows are directions for upgrading an existing EMacro install. Be sure to backup your files! In particular, you should save and re-use the following files in your [~/emacs/] preferences directory. They are very much like user data. Older users may have to rename files from another directory, which still work the same way.

• e-custom.el
• e-preload.el
• e-prefs.el
• e-postload.el
• e-xcustom.el

You may also have changed

• e-path.el

In other words, you will likely want to discard any new version of these files, and overwrite them with your existing version. For preload.el and postload.el, consider just making a call to your file:

  (load-file "/home/emacs/packages/myCode.el")

Next, remove all bytecompiled elisp and cache files. This should do the trick:

• cd $HOME/emacs
• bin/unix/refresh
• bin/w32/refresh

Where w32 is for Microsoft Operating Systems; unix, for any other OS. These scripts simply remove [~/emacs/] **/*.elc, and [~/emacs/] preferences/e-*cache.el.

EMacro contains much sample commented code, which may solve your problems. Rather than simply uncommenting this code, consider copying it to a file that e-postload.el invokes, which is there for user code, not to be touched by upgrades. You could put code into e-postload.el directly, but this prevents your code from accidental overwriting, when you unpack the next upgrade.

If you have modified EMacro's code files outside the preferences directory, the current best solution is to use Tools->Compare from the menu, or M-x ediff.

System Requirements

EMacro uses less than 2 Meg of disk space, and likely as much RAM memory.

If you use Microsoft Windows

I recommend setting %HOME%. Otherwise, Emacs (or XEmacs) generally considers C:\ to be your home directory.

You will need tar & gzip to extract the EMacro files. Cygwin has many useful tools, including tar and gzip. It is available free from http://sources.redhat.com/cygwin/ . After installing it, run the bash shell. Extract the archive with commands like:

• cd
• tar -xzf EMacro*.tar.gz

There is also the free (GPL) 7-zip .
There are other archive programs at no cost, but do not have free licenses:

• FilZip
• Ultimate Zip

XEmacs users should also download the latest sumo tarball for XEmacs.

Detailed Install

Note that $HOME/.emacs has been renamed to $HOME/init.el to prevent overwriting your existing .emacs. Note! EMacro cannot offer support, if you modify e-postload.el or e-preload.el!
If you are upgrading, you should make backup copies of the following files in the preferences directory:

• e-custom.el
• e-prefs.el
• e-xcustom.el

You may also need to backup

• e-path.el
• e-preload.el
• e-postload.el

Note that older versions of EMacro had similar files in other directories. You should be able to rename your old files to the new names, and move them into the new directories (preferences), and be on your way.

Required System Information

Be sure to have the following information available:

• Server name for usenet news
• Usenet news login name
• Email address to send email from emacs
• Initial window height (preferred size on graphical screen)
• Printer and print server name
• Pop3 email receiving server name
• Smtp email sending server name
• Database hostname (i.e. SID)
• Database login name

PATH should be set with all Supported Third Party Programs, such as Netscape, so that EMacro can find them.

I recommend that you install the latest sumo tarball, if you use XEmacs. Emacs, as a standard, ships with a complete set of elisp libraries, but this is an issue with XEmacs, as it does not. EMacro has been tested with XEmacs standard distribution of almost no libraries. Testing for missing libraries has become a maintenance nightmare, and EMacro may require the sumo tarball in the future.

EMacro starts by prompting you for some values. If you make a mistake, you can delete or edit preferences.el.

Note that there is a bug in the Mac OS port of Emacs append-to-file() , that it will not create new files. You will have to create empty files in EMacro's emacs/preferences folder (directory) called

• e-prefs.el
• e-gcache.el (Emacs) or e-xcache.el (XEmacs)

Otherwise, remove *.elc and ?cache.el files, which you can do by

• cd $HOME/emacs
• ./refresh

which simply removes ?cache.el and *.elc.
Bytecompiling is great for catching errors, but it also can cause problems, when moving between Gnu Emacs and [Gnu] XEmacs, and different versions of Emacs / XEmacs.

Be sure to check for any byte-compile messages. You might also see a list of packages which will enhance emacs. You can see the log of minibuffer messages with C-h l in XEmacs. In Gnu Emacs you need to switch to *Messages* buffer.

If you have a good web connection, you can easily update Emacs. Download and run http://www.anc.ed.ac.uk/~stephen/emacs/ell.el Restarting EMacro will search for some of these elisp macro libraries.

Tested Platforms

The following platforms have had some testing, with recent Emacs / XEmacs versions. Be sure to check release_notes.html for up-to-date configurations

• Free BSD (on AMD/Intel PCs)
• Linux (on AMD/Intel PCs)
• Mac OS (Classic) 8.x & 9.x
• Mac OS X (terminal/console app)
• Microsoft Windows 9x/ME, NT v4, 2000
• Sun Solaris

Mac OS X has had limited testing. Mac Emacs and Emacs On Aqua are not at full production quality, and have problems. Expect problems with xemacs-gtk (still beta). No Mac XEmacs ports newer than v19.x are currently available, and such old versions are unsupported. See the Mac OS section for further caveats.

Description

EMacro should be the only startup file you will need for any emacs. It also makes it easy for you to learn how to customize emacs. You should also be able to tweak XEmacs without breaking GNU Emacs, and other combinations, such as a .emacs common to linux/windows dual boot. EMacro has been profiled for speed through caching and lazy loading.

Be sure to back up your .emacs file. If you configure from the menu, emacs writes to this file, and might cause problems. On MS Windows, the .emacs file might also be called "_emacs". Windows users may have to use the command prompt to rename the file to ".emacs". The default location on MS Windows is "C:\", if the %HOME% variable does not point to a path. For MS Windows, or unix like systems, you can check for the HOME environment variable by typing set at the command line. For Unix, $HOME should already be set.

Put all the *.el files in your load-path (new downloads go into ~emacs/packages).
Put all third party support programs in your PATH. For example, MS Windows NT, 2000, ME users who want to use Internet Explorer support, should go into Control Panel -> System; MS Windows 95 and 98 users would edit autoexec.bat to add C:\Program Files\Plus!\Microsoft Internet to PATH, in order to launch Internet Explorer from Emacs. You should change load-path.el to add all the directories where you keep *.el elisp macro libraries. On NT, launch the control panel, choose system -> environment. For other MS Windows, put something like the following in your c:\autoexec.bat file:
set HOME=C:\home Put .emacs in the directory set by environment variable HOME. Create a subdirectory (folder) such as "/home/emacs", and put the remaining files there.

Setting the %HOME% environment variable will make your life easy. However, if you don't, note that the precompiled binary for XEmacs v21.1.10 uses c:\users\default for its default directory. We also tested EMacro without %HOME% set, by putting .emacs there, and the remainder in c:\emacs.

Supported Third Party Programs

• General
  • Ghostview
  • Ispell and the older ispell4
  • Jikes
  • Telnet
• Shells (for MS Windows)
  • Bash
  • Ksh
  • Zsh
• Browsers
  • Galeon
  • Grail
  • Internet Explorer
  • Lynx
  • Mozilla
  • Netscape
  • W3 (Emacs's embedded browser)
• Databases
  • Informix
  • Ingres
  • Microsoft SQL Server
  • Mysql
  • Oracle
  • Postgres
  • Solid
  • Sybase

Configuration

EMacro is designed to work out of the box as much as possible. You will want to start by editing loadpath.el. Be sure to run refresh to remove *cache.el.

Be sure to set your PATH environment variable. EMacro will search it for support programs, such as jikes, ghostscript and ispell.

"M-x" means Meta-x. The Meta key is usually 'Esc', and sometimes 'Alt' Be sure to try both left or right Alt keys. You may find it easier to customize emacs via the menu

Else use the command   C-h C or M-x customize You can find where elisp macro packages are being loaded, by

• M-x locate-library RET package RET

Get the latest packages from [Gnu] XEmacs's menu: Options->Manage Packages. Gnu Emacs also supports third party libraries from http://www.anc.ed.ac.uk/~stephen/emacs/ell.html See also emacs.html in this distribution.

There is an optional small unix shell script called e-edit, or for XEmacs, e-xedit which speeds up Emacs, when you run a second (or more) copy, by attaching to an already running Emacs. You can place it in your $PATH, as is, or replace the Emacs/XEmacs filesystem link with this script. Be sure to edit the script, so that it calls the real Emacs, that is, the file softlink emacs was pointing to. If gnuserv was not built with your distribution, you might find it at http://www.beopen.com/. You'll need it for the edit script to work.

Other Configuration Files

Note that ~ = $HOME, the directory in your HOME environment variable.

• /etc/hosts [xemacs] - should have at least the following
  127.0.0.1   localhost
• ~/.authinfo - used by gnus
  machine (newsServerName) login (myLoginName) password (myPassword)
  Then do `chmod 600 ~/.authinfo` to make it difficult to read your password
• ~/.netrc [ange-ftp(gnu emacs); efs(xemacs)]
  machine name.domain.com login myname password mypasswd
  Note that (especially) password is optional, and usually not recommended. See ftp man(ual) page for more info.
• ~/.diary [calendar] - generated by M-x insert-diary-entry

  	Friday Go home from work
  	December 31 1999 New Year Eve
  	10:00 Making a list
  	18:00 Checking it twice
  	

• ~/.gnus Format is like a .emacs file, and could be called from .emacs
• ~/.vm
  (bbdb-insinuate-vm)
(bbdb-insinuate-message)
• ~/.w3/default.css - try just this one line
  a { text-decoration: underline; }

Mac OS

Note that Mac OS XEmacs will not work, until a recent version (>= v20) is ported. This will not likely happen soon.

Classic Mac OS (v8-9) users need to read the FAQ documentation, distributed with the Mac OS port, in order to set environment variables. In particular, you need to know how to set $HOME. The easiest solution is to put EMacro in the same mac folder as the executable emacs application, itself, then rename init.el to .emacs

EMacro will load, but not all parts of Mac Emacs v21 are working. For example, start-process() has not been ported, so (gnu)server and launching help from the menu will not work. You can, of course, simply open your browser, yourself.

Note that some of these features do work on the older Mac Emacs v20.6.

Here are the steps to get EMacro to load:

1. (Re)Move server.el & server.elc out of the lisp folder. These will not work in the current Mac Emacs v21.1 port.
2. Create the following empty files in the preferences folder. Alternately, you can put ; comments in them:

• e-cache.el
• e-prefs.el

The first time EMacro is run on Classic Mac OS (v8-9), it will complain that it cannot run ps. This is expected behavior that goes away, as EMacro looks to its cache on subsequent runs.

Currently, only Netscape is supported for launching EMacro's html help files, for Classic Mac OS (v8-9). I welcome contributions of applescript, to support other browsers.

Customize does not seem to work in Classic Mac Emacs v21.