Aquamacs (Pete's notes)


Aquamacs loads these files at startup, if they exist, in this order (bold ones exist in my environment, others don't):

  1. ~/.emacs
  2. ~/Library/Preferences/Aquamacs Emacs/customizations.el
    Do not edit this - Aquamacs edits it when you use the "Options" menu
  3. /Library/Preferences/Emacs/Preferences.el
  4. /Library/Preferences/Aquamacs Emacs/Preferences.el
  5. ~/Library/Preferences/Aquamacs Emacs/Preferences.el
    Here's where I put customization and initialization that is Aquamacs-specific, or that I know I won't use except in Aquamacs, like org-mode.
  6. ~/Library/Preferences/Emacs/Preferences.el
  7. ~/.xemacs/init.el
    This is loaded because I set init-file-name in Preferences.el. This is where I put stuff that I want in both Aquamacs and in regular emacs on Linux hosts. I copy this file to Linux hosts and name it ~/.emacs.
When I run cisl-irving:~/bin/, it copies my whole ~/.xemacs directory to Linux machines. On those machines, there is a symbolic link named ~/.emacs, which points to the ~/.xemacs/init.el file. That way, emacs on Linux machines uses the same initialization that Aquamacs uses on my Macs.

Running from the command line

First, start Aquamacs. Then do Tools->Install Command Line Tool. This will install a Perl script named /usr/bin/aquamacs. Then use "aquamacs" to start it. That's too long, so insert this in your .bashrc:

alias aq='aquamacs'

Editing remote files

If a remote system supports SAMBA (like netserver does) you can connect to the remote SAMBA server and access the filesystems under /Volumes. If it doesn't support SAMBA (frgp-ws-1 and wy-nagman don't) you'll want to use TRAMP. TRAMP is distributed wih Emacs, so it's useable in Aquamacs.

For TRAMP to work, some things have to be set up:

To open a file named on a machine named, do

C-x C-f C-f / TAB

To open a file named on a machine named nagman, do

C-x C-f C-f /nagman:/etc/nagios3/plugins/nets/check_snmp_trunks2 TAB

Working with HTML

Aquamacs comes with html-helper-mode, defined in /Applications/ which is quite different than the mode I used to use: XEmacs HTML-mode. I didn't like html-helper-mode at first, but I'm stuck with it.

My customizations for html-helper-mode are in ~/Library/Preferences/Aquamacs Emacs/Preferences.el

I considered nxhtml, but it's for editing XHTML, which never took off.

Anyway, to render the current buffer with Safari, *save the buffer*, then do M-x browse-url-of-buffer. If I want to bind that to a key some day, the key should be C-c C-v. I did local-set-key, which was fine. Figure out how to do it in the .xemacs/init.el file.

For help understanding html-helper-mode, see

Since html-helper-mode doesn't indent well, you can call an external "tidy" program to indent the buffer. Then you have to deal with getting tidy to do what you want. See Vagmi's blog about it

Restoring the meaning of C-x C-R

C-x C-R should run find-file-read-only. In Aquamacs it runs some annoying thing. to fix it, I did a global-set-key in the initialization file.

Getting rid of the toolbar

Click on the little oval at the upper-right part of the window. This makes the toolbar disappear, which is great, but it'll be back the next time you start AquaMacs. To make the changes stick, I did Options->Appearance->Adopt Face and Frame Parameters as Frame Default.

Fonts: proportional vs. monospaced

By default, Aquamacs uses Lucida-Grande as the default font for all modes, including programming languages. This sucks for programming languages, obviously. It also sucks for any other modes where things are presented in columns, like Man mode. You can individually set each mode's font, but there are some you can't set. Like the little window that pops up when you run ediff. If you select '?', that window displays column-aligned help. It looks terrible in a proportional font. I tried to set the default by following theses instructions in the Aquamacs FAQ:

To set the default font for all buffers, do M-x customize-face and type in default. Then place the cursor in the Font Family input area and type in Monaco. Click Save for Future Sessions and Finish.

This failed with an error, so I kept struggling and finally got it to work. It put this into my /Library/Preferences/Aquamacs Emacs/custamizations file:

(load-file (expand-file-name "~/.xemacs/init.el"))

Viewing the keys that Emacs sees

When you're messing with keyboards, you sometimes want to see what character Emacs sees when you hit a given key. To see the last 300 characters, use C-h l.

End-of-line conversions, replacing funny characters

When Emacs opens a file, it automatically detects the "coding system" of the file, including the end-of-line convention used by the file. Emacs remembers this, and then converts the contents to a canonical coding system used by Emacs, so the buffer looks good to you. Later, when the file is written, Emacs converts its internal representation back to the one it detected when the file was opened. This way, you can edit files with weird coding systems, and they'll look good in Emacs while you edit them, but they'll be written with the style they had when you opened them.

Sometimes you'll want to explicitly change the coding style that Emacs uses when writing a file. For example, when you use ZTerm and capture a 6509 switch console session, ZTerm writes a file with just CRs at the end of each line. If you look at such a file with Terminal, you'll see a mess with lots of "^M" characters. If you open such a file with Aquamacs, it'll look good in Aquamacs. If you change the file and save it, it'll still look screwy in Terminal. To make the file look good in Terminal, you need to open the file with Aquamacs, change the coding system, then write the file. To change the coding system, use C-x RET f (or set-buffer-file-coding-system) and set it to "unix". Then save the buffer, and the file will look good in Terminal.

Replacing nulls (^@ characters in Aquamacs, black diamonds in Safari)

If you get the weird Microsofty case where every other character in a .html file is a null (shows as ^@ in Aquamacs and black diamonds in Safari) you can use replace-string to delete them. Go to the top of the buffer and do M-x replace-string ^Q 0 RETURN RETURN RETURN.

Replacing ASCII 160s (blue underscores in Aquamacs, Âs in Safari)

When you use "Save As" in Apple to make a copy of an email message that came from the Internet2 NOC, you may find that the file contains weird spacing characters. The file will look fine when displayed with a "more" or "cat" command, but when you look at it with Aquamacs, some of the space characters will show up as blue underscores. These are ASCII 160 characters. If you copy the file into an HTML file, and then display the file with Safari, the characters will show up as  (capital-A-with-a-circumflex). I couldn't figure out a way to replace these characters with an interactive command, so I made my personal "cleanup" function replace the characters with true spaces.

Color highlighting

This section describes setting the colors of the foreground. To set the background color, see below in the "Background colors" section.

Set a general color theme

To set a color theme (a set of colors for the foregrounds of all the types of text that Emacs displays):

This saves stuff in ~/Library/Preferences/Aquamacs Emacs

I chose "Clarity and Beauty").

Emacs shares the colors of things that are common across programming languages. This is beautiful - comments in C, Java, Perl or shell scripts are all the same color. To see the list of syntactic elements that can be individually colored, do M-x customize-group RET font-lock-faces RET. I set:

Aquamacs has per-mode syntax highlighting, so you can set it up so that when you edit a shell script, you get different colors than when you edit a Perl program. I don't want to do that - I want comments to use the same color in Bash mode as in Perl mode. But if I did, you do it by gotting in the mode, then:

This saves stuff in ~/Library/Preferences/Aquamacs Emacs

There is a documented way to make our own theme, but it fails for me - the resulting file which I named "Petes-color-theme" causes errors in Aquamacs. Nevertheless, the procedure is to first select a theme (I chose "Clarity and Beauty"), then do M-x color-theme-print. Copy the resulting Lisp to a file named ~/.xemacs/Petes-color-theme.el. Edit the file and change all occurrences of "my-color-theme" to "Petes-color-theme". On that line near the end, replace "THEME NAME" with "Dark blue contrast", and replace "YOUR NAME" with "Pete Siemsen,". Save the file and exit Aquamacs. Start Aquamacs. Do M-x load-file to load /.xemacs/Petes-color-theme.el. Do M-x Petes-color-theme. When I did this, I got an error, and Aquamacs was henceforth broken.

If you get it to work, then you're ready to modify it to turn it into what I really want. Each of the lines basically defines attributes of a face. To see a list of faces and the way they are currently set, do M-x list-faces-display. Experiment, changing one face color at a time and restarting Aquamacs to see the results. A faster way is to use the face-list.el function, which you can download from

Background colors

In Emacs, background colors are part of the face used to display a buffer.

To change the font for a mode, get in the mode and select Options->Appearance->Font for xxx-Mode.... Here's where you set the font and also the background color, by choosing the "Document Color" icon on the top at the far right. Then save the options. This'll change ~/Library/Preferences/Aquamacs Emacs/customizations.el. I went into that files and simplified it to set up a default font as "Monaco 12". When I upgrade to Snow Leopard, I'll change to the new Mensa font.


On the Mac, I installed ispell with
fink install ispell
...which installed /sw/bin/ispell. This was sufficient to allow Aquamacs to handle "M-x ispell". I also installed cocoaspell, but I'm not surewhat the effect was - when I select Aquamacs -> Edit -> Spelling -> Spell-Check Buffer, it still starts an ispell process.

Meta key

The Mac's "Option" (a.k.a. Alt) key is Aquamacs "Meta".

info mode

Info files can be found in

Aquamacs uses the files in /usr/share/info.

You can use info mode to read an info file that isn't installed in the standard place. Suppose you have a file named sitting in ~Downloads. Go into info mode in Aquamacs, type 'g', and when it prompts "Go to node:", enter


fit-frame, Drew's Libraries, one-on-one Emacs, etc.

The fit-frame package provides a way to resize windows to fit their contents. You can use it manually, or turn on autofit-frames-flag. I tried auto-fit-frame but I discovered that I don't really want it when I use tabs. I discovered that fit-frame, written by Drew Adams, does exactly this, and is part of a large library of stuff that's designed to make Emacs handle frames better, which Drew calls One On One Emacs. It turns out that Drew's Libraries are a part of Aquamacs, in /Applications/

From my cursory inspection, it looks like fit-frame works but autofit-frame doesn't.

Developing Aquamacs

Getting and building Aquamacs

on 2009-09-25, I installed git using fink. Then I downloaded the full Aquamacs source with this command:

git clone git://

This created a git repository in /Users/siemsen/aquamacs-emacs/.git/ and more importantly, ~/aquamacs-emacs. I was able to run build-aquamacs and make a working Aquamacs, and then run it with

open ~/aquamacs-emacs/nextstep/
It's faster to use "make" to avoid rebuilding everything.

Working on the Aquamacs manual

In October 2009, David Reitter posted a message to the Emacs on OS X mailing list asking for volunteers to edit the Aquamacs manual. His email explained

The list of items is essentially visible in the aquamacs/doc/latex/changelog.tex file.
The manual is written in LaTeX and contained in aquamacs/doc/latex/aquamacs.tex.
Use "make" to recreate the html/pdf versions.

That's fine if you want to edit the manual, but to process it into anything, you need to have LaTeX. See my instructions for how to get TeX and LaTeX.

Writing a major mode


Lisp mode (and SLIME)

If you want to experiment with Lisp programming, you'll probably want to open a lisp file like init.el and try to evaluate a line in the buffer by going to the end of the line and typing C-x C-e. When you do this in Aquamacs the first time, Aquamacs will display a message in the minibuffer suggesting that you install an enhanced Lisp-mode named SLIME.

Don't bother to install SLIME - you'll just be unhappy if you do. SLIME may be superior for heavy Lisp coders, but it's overkill for me. I just want to evaluate little snippets of Lisp code. SLIME is a complex environment that requires that connects to an external Lisp system. To get SLIME to work, you have to install an external, stand-alone Lisp system. Not worth the bother, hence, just don't install SLIME. The following documents what I did before I discovered that SLIME is more than I need.

SLIME is the "Superior Lisp Interaction Mode for Emacs". It is available for Aquamacs as an Aquamacs "plugin". It's installed via what Reitter calls a "point-and-click installer". To install it:

  1. Go to the Aquamacs Web site an get the ".pkg.tar" file
  2. Untar it
  3. In Finder, double-click on the ".pkg" file
  4. Follow the prompts
  5. Restart Aquamacs

This installs /Library/Application Support/Aquamacs Emacs/SLIME/.

Once you've done this, and you go into Lisp mode, Aquamacs will no longer suggest that you install SLIME. Ok - so you must be running SLIME, right? Not so fast. When you try C-x C-e, it'll error out with the message "Not connected". This happened because you haven't started the external lisp process that SLIME uses. To start SLIME, do M-x slime. When I did this, it said "Searching for program, no such file or directory, lisp". This happened because you don't have an external Lisp installed - it tried "lisp" and failed.

Lock file problem with SAMBA shares

If you have shared files sitting on a Unix server (like netserver), and you share them using smbd (SAMBA), and you mount them on a Mac and then try to edit the remote files using Aquamacs, you may run into a problem with lock files. Aquamacs creates files named ".#xxxx" whenever you modify a buffer. Aquamacs won't be able to delete the files when you save a buffer, because of a known problem with the Mac SAMBA client. The lock files will remain after an editing session. The next time Aquamacs tries to modify the file, Aquamacs will hang with the spinning wheel of death.

A work-around is to modify the config of the smbd server. Add "unix extensions = no" and restart the smdb process. Problem solved.

Aquamacs starts with a "BEEP" and is unusable

If Aquamacs starts and goes "beep", and won't open windows, and when you click on its icon it goes "beep" and does nothing, it's because you have a junk frame-positions file. Aquamacs remembers where your windows (frames) are. If you were using multiple displays, and had windows spread around, and now you only have one display, Aquamacs gets confused. The solution is to quit the brain-dead Aquamacs, delete the file named ~/Library/Preferences/Aquamacs\ Emacs/frame-positions.el, and restart Aquamacs.


Gtypist is a program to help you learn to type. Gtypist-mode is an Emacs mode that accesses the same tutorial files as Gtypist. To install gtypist-mode, I

  1. downloaded the package into ~/.xemacs/gtypist-2.8
  2. followed the directions for building and installing the binary, not because I want the binary, but because it builds the .elc file
  3. copied the tools/gtypist-mode.el and tools/gtypist-mode.elc to my .xemacs directory
  4. added this to my init.el file:<
    (autoload 'gtypist-mode "gtypist-mode")
    (setq auto-mode-alist (cons '("\\.typ\\'" . gtypist-mode) auto-mode-alist))

Now, I can use Aquamacs to open a gtypist tutorial file like ~/.xemacs/gtypist-2.8/lessons/m.typ, and I'm in gtypist mode. It's not at all clear how to *use* it :-) Now to figure out how it works, and see if I can use it to make me faster with Aquamacs.

Pete Siemsen