Quick Install Info

Detailed Install

Configuration

Quick Start

Package Install

You must tell Microsoft Windows where the system directory is, to install the site-start.el file. Emacs and/or XEmacs must be installed before EMacro. Thereafter, you may install EMacro Libs.

Cygwin Package Install

  1. Launch Cygwin's setup.exe
  2. Choose Download from Internet or Install from Internet
  3. When prompted to choose a mirror site, enter http://emacro.sourceforge.net/cygwin and click Add

Note that Ctrl-left-mouse (button 1) lets you choose more than one download site.

emacro*.tar.gz Install

Just as easy: extract emacro*.tar.gz to your / (root) directory. MS Windows shell users run
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.
Still having problems? See the Detailed Install.


Upgrade Essentials

If you are upgrading an existing .emacs, you can move your code into ~/emacs/e-postload.el. You may need to test EMacro without your .emacs. You may find overlap of functionality; EMacro does combine the best of popular .emacs files floating about the internet.
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 ~/emacs/preferences/:

You may also have changed

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:

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.

Tools->Compare from the menu, or M-x ediff is a valuable tool, to see what has changed in any file.


System Requirements

EMacro uses less than 2 Meg of disk space, and likely even less RAM memory, in addition to Emacs or XEmacs's requirements.

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://www.cygwin.com/. After installing it, run the bash shell. Extract the archive with commands like:

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

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


Detailed Install

EMacro must install into /usr/share/elisp. It will create your preferences in ~/emacs/preferences/. If you had a previous .emacs, you can move your code into ~/emacs/e-postload.el (preferred) or ~/emacs/e-preload.el.
Note! EMacro cannot support the code you add to e-postload.el nor e-preload.el, nor its impact!
If you are upgrading, you should make backup copies of the following files in the preferences directory:

You may also need to backup

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.
EMacro works by searching your PATH and your load-path, and caching the results. See the section on Configuration for details. EMacro also prompts you the first time, for things like your login name, and saves these results into ~/emacs/preferences/e-prefs.el


Required System Information

Be sure to have the following information available:

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 Classic Mac OS (v9.x) 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

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

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

Emacs v21 or higher is strongly recommended for Mac OS X. Mac Emacs and Emacs On Aqua are not at full production quality, and have not their ports in synch with recent releases. I recommend against these unsupported (by EMacro) packages. See the Mac OS section for further caveats.
Expect problems with xemacs-gtk (still beta), but should work adequately.


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


Configuration

How EMacro Works

Only the first time you start EMacro, it asks you some questions. See Install Questions Explained for more info. EMacro is designed to work out of the box, requiring no elisp programming. Be sure to run e-refresh to remove ~/emacs/preferences/*cache.el if you've run EMacro before.

EMacro tries to be smart, by searching for binaries in your PATH, and for elisp libraries in your load-path
Since searching the load-path is slow, EMacro caches the results in either ~/emacs/preferences/e-cache.el (Emacs) or ~/emacs/preferences/e-xcache.el (XEmacs). If you change your elisp libraries, you should remove these files. This is what ~/emacs/bin/unix/e-refresh or ~/emacs/bin/w32/e-refresh.bat do(es).

EMacro lists elisp libraries in the *cache.el files, which support "Plug & Play". Just download these into the load-path , such as the ~/emacs/packages/ directory, then remove their listings from the cache file, (such as by running e-refresh) and restart Emacs/XEmacs.

Note that listings in the cache are in no particular order, and may be freely edited or deleted. If you run into problems, you should run e-refresh before contacting us for help.


Supported Third Party Programs


load-path

The load-path Emacs variable works just like the PATH environment variable. Emacs cannot find *.el nor *.elc elisp libraries, unless they are in a directory listed in the load-path. You can inspect any Emacs variable, by typing
C-h v
load-path
You can simply put all your downloaded optional elisp libraries in ~/emacs/
You might wish to edit ~/e-path.el to add additional paths. You might avoid this trivial, but optional elisp editing, by installing Tiny-Path. Tiny-Path is part of Tiny-Tools, and can automatically build your load-path. Again, put this optional library in ~/emacs/
One last issue: some packages, such as Tiny-Tools & JDEE put their *.el elisp libraries in a subdirectory named lisp. You should look at the source code for /usr/share/elisp/emacro/e-path.el, to see how EMacro deals with these. Typically, EMacro expects you to create a link to these files. For example, you would do
ln -s ~/emacs/packages/emacs-tiny-tools-2002.0805/ ~/emacs/tiny-tools/
or
ln -s ~/emacs/packages/jde-latest/ ~/emacs/jde/
For Microsoft Windows users, you will have to rename the directories. The e-path.el of EMacro is currently coded to put /usr/share/elisp/tiny-tools/lisp/*.el and /usr/share/elisp/jde/lisp/*.el (as well as ~/emacs/ into your load-path. However, you can change or add appropriate paths to your load-path, by editing /usr/share/elisp/emacro/e-path.el


Configuration

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

Emacs older than v21Help->Customize
XEmacs and Emacs v21+Options->Customize

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

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.

Finally, EMacro searches the Emacs variable load-path for optional libraries. The results are written to ~/emacs/preferences/e-cache.el or e-xcache.el, if you run XEmacs. You should look at them to see which libraries you should download, to enhance Emacs.
Example: You open e-cache.el in Emacs, and see the line
(defconst cache-tinyload t)   ;For tinyload support, get tiny-tools from <url: http://tiny-tools.sourceforge.net/ >
You download tiny-tools into ~/emacs/ (which is in the load-path), and delete e-cache.el. EMacro rebuilds this cache when you restart Emacs, and now you will notice that Emacs becomes available sooner, when loading.


Mac OS

Recent versions of Mac OS X XEmacs should work, but have not been tested. Various ports of Emacs work fine on Mac OS X. Classic Mac OS (v8-9) may still work, but is no longer maintained.


The Install Questions Explained

If you are not reading this section in English, the phrases may vary, and you may get an additional question about character encoding, where appropriate.
Only the first time you start EMacro, it asks you some questions, and saves the results into ~/emacs/preferences/e-prefs.el. If you make a mistake, you can either edit this file, delete it, or delete the lines that are wrong. Order of lines in this file is not important.

Here are all the possible questions that you will asked, when starting EMacro. Note that EMacro tries to be smart, so you might not see all these questions.

If you use Emacs (hereafter includes XEmacs) to read email or NNTP news, EMacro will prompt to conveniently save your login, and server info. You can still access the internet with Emacs, even if you say n. However, this enables loading e-net.el, which helps automate remote editing through EFS/Ange-FTP, or TRAMP and SSH connections, browsing html files, including EMacro help, telnet inside Emacs, and Watson, which lets you click and net-search on phrases in an Emacs buffer.

If you do have a modem, and you say y, this likely won't be much of an aggravation. If you say n, the consequences follow.
EMacro includes a function, where you can click on text it recognizes as an URL, and can launch it. However, if you have a modem, which goes through a long dialup process to connect to the internet, or you have no net connection, say n. This also enables parsing of XML documents, using remote DTDs. You can test this, by loading ~/emacs/contrib/test.xml which loads http://emacro.sourceforge.net/dtd/test.dtd. This requires additional elisp libraries in your load-path, (put them in ~/emacs/packages/, if unsure), in particular html-helper-mode.el, w3.el and advice.el

This is the default to save you typing, when you are asked later, what your email, NNTP news, and SQL login IDs are.

This is what appears in your email header.

This is the a default, to save you typing. EMacro is hosted at http://emacro.sourceforge.net so its network domain is sourceforge.net

My email address (as an example) is If you still have problems with this one, contact your System Administrator, or visit the store where you bought your computer from.

You need this, so that Emacs can send email. You may need to contact your System Administrator, or Internet Service Provider. Example values are smtp-server.YourDomain.com or mailserver.sourceforge.net. You might find these values in other email clients, which you might already have working.

Commonly, this is the same server name as for sending email. If you use IMAP for receiving email, contact the author, so we can test and develop a solution for you. Proprietary email systems, such as Microsoft Exchange are not currently supported.

Not all systems have news servers. You may need to contact your System Administrator or Internet Service Provider. Example values are nntp-server.foobar.com or newsserver.sourceforge.net

Typically, this is the same as your system login ID, which is usually the same as your email address, up to the @ sign. Thus, my email address is
My login ID would be bingalls

The size of paper you load into your default printer. Answer letter if you live in the USA or in the country sometimes known as Burma. The rest of the world uses the metric a4. Read the documentation for (ps-)print.el, for other sizes, such as legal or b4

This is the device name your plain text printer. Example values for unix are /dev/lp0 or /dev/rp1. Windows users can get their properties from the printer control panel. Examples are PRN or //server/hplaser
I recommend that Microsoft Windows users use forward slashes, as using native backslashes need to be escaped, and become hard to understand.

Commonly the same as your regular printer name. Just take the default, if you don't have a postscript printer. If you have ghostscript in your PATH , use the same name as your regular printer.

Unsure Linux (and compatibles) users, can just accept the default. Windows users should consider using Cygwin. They can put /usr/share/elisp/emacro/contrib/lpr in their PATH, or take a look at http://www.gnu.org/software/emacs/windows/faq6.html#printing-emacs for help.

This is the default, when you hit tab in programming source code.

EMacro detected isql(.exe) in your PATH but does not know whether to provide support for Microsoft, Sybase or Borland's Interbase.

Contact your Database Administrator. Typically, this is the same as your system login ID, as above. Note that EMacro currently supports the following databases:

For your convenience, EMacro allows you to store the password to your database account in clear text. The EMacro team, nor its affiliates are not responsible for such consequences, including data loss.

This is the DNS name for the machine that is running your sql database. An example is sqlserver.sourceforge.net

A database system might have multiple databases on its server. Example names include
accounting
sales
rosebud
Contact your Database Administrator for more help.

EMacro tries to automatically guess, and use your full screen height, then saves the result in ~/emacs/preferences/e-prefs.el as (setq use-height 24) , where, instead of 24, your actual screen height is used. If you set this height to 0 (zero) instead, EMacro will always automatically guess your desktop height. On X Window systems, this takes can delay startup by about 1 second, while EMacro checks for taskbars which take up desktop space. Note further, that EMacro assumes that desktop taskbars are at the top or default bottom.

Valid XHTML 1.1! Valid CSS!