Starting to use Aquamacs

Here we give a short description of some features that we have found useful for editing and lemmatising ATF in Aquamacs (Emacs for Mac), apart from those provided by ATF Mode.

Emacs is a very powerful piece of software, but its documentation is dense, difficult to navigate, and usually assumes that you are working in Unix without a mouse. And it doesn't help that Aquamacs has its own little quirks. This page aims to make working with Emacs as intuitive and Mac-like as possible.

Setting the default font

In Aquamacs, you can open up (and close) a Fonts window with the command ⌘⇧T. In that window, you can choose a font, size, colour, as you would normally, and save different combinations as favourites. To ensure you have all the necessary transliteration and normalisation characters, we recommend that you install the DejaVu font and set it as the default. Two different ways of typing transliteration characters are described on other pages. You can use either or both, as you like.

Menus and the Toolbar

When you first install Aquamacs, it is worth looking through the menus to locate the basic commands. Much is where you would expect it, though Emacs terminology can seem rather strange to Mac users. A "buffer" is essentially a view of a document, which is displayed in one or more "frames" (windows). A frame may have more than one tab, each containing a different buffer, in the same way that a web browser can several web pages open at once in different tabs.You may also be unfamiliar with the Aquamacs terms "directory" (folder) and "search" (find).

Apart from the ATF menu, the File, Edit, Options, and Windows menus will be most useful to you. You are unlikely to need anything in Tools, and the Help menu lists far too many different sorts of help to be useful for a beginner. Even on the File, Edit, Options, and Windows menus there are many items that you will never need, so do not worry if they seem mostly incomprehensible to you for now.

There is also a toolbar at the top of each Emacs frame, with clickable icons for basic editing and file commands. You can add items to the toolbar, and remove them from it, by selecting and deselecting them from the Options > View > Toolbar Items menu item.

Menus and toolbars are comforting and intuitive, especially when you are first learning to use a new piece of software. But for more efficient working it is useful to learn as many keyboard shortcuts as possible. Next to most menu items you will see the equivalent keyboard shortcut, and there are many hundreds more. But almost everything you will need can be found through the menus or is described on this page.

The Control and Meta keys

Almost all Emacs keyboard shortcuts are combinations with the Control or Meta keys. You'll see them written as, for instance, C-g or M-x.

The minibuffer is Emacs's name for the little window that appears at the bottom of a frame when you type a command and where, for instance, you type text that you want to find or replace. If you find your cursor there accidentally C-g will get you out of it with no harm done.

On Macs the Control key is marked ctrl and is often found near the fn, alt and ⌘ (Apple/command) keys near the bottom of the keyboard. When you see a command such as C-g, this means that you should hold down the Control key and then press the g key simultaneously. Many keyboard shortcuts involve sequences of commands, so that for instance C-c C-c means that you type Control-and-c twice.

The Meta key is the esc key (usually top left on the keyboard). For, say, M-u you type esc first and then the u key, not the two simultaneously.

As you will see on the menus, the ⌘ key also retains much of its functionality in Aquamacs, so that for instance you can save files with ⌘S, just as usual.

To make sure that the alt key works properly in Aquamacs, go to the Option Key item on the Options menu, and select Standard Mac characters.

Keyboard shortcuts

The most important command you need to know is C-g. This will cancel any command that you are in the middle of, and is particularly useful if you've typed a command by mistake.
If you want to undo a command that has already been carried out, then choose File > Undo, or type C-x u or ⌘Z (the usual Mac "cancel") as you would normally.

Word wrapping

You can get lines of a paragraph to break at word boundaries (and not in the middle of a word) with the command C-x w (where w is for "wrap").

Changing case

Change case, from the position of the cursor to the end of the current word, with M-u (upper-case), M-l (lower-case), and M-c (initial capital).

Deleting text

Delete text, from the position of the cursor to the end of the current word, with M-d (for "delete").
Delete text to the start of the current word with M-Del (where Del is the normal Delete key).
Delete the whole line, from the position of the cursor to the end, with C-k (for "kill").

Swapping and sorting text

Transpose two adjacent characters with C-t (for "transpose").
Transpose two adjacent words with M-t.
Transpose two adjacent lines with C-x C-t.
Sort lines into alphabetical order by selecting them with the mouse (or the Shift and Arrow keys) and then typing M-x sort-lines.

Going to a particular line

Go to a particular line by typing ⌘L (for "line") and then the line number. For instance, ⌘L 123 will move the cursor to line 123 of the file.

Searching for text

Search forwards with C-s (for "search") or ⌘F (the usual Mac "find"), then type your search term into the minibuffer and press return.
Repeat the search with C-s again or ⌘G.
Search backwards within the file with C-r.
Return to where search started (if you are still in search mode) with C-g.

Systematically replacing text

To start a global search-and-replace within a file, type M-%. In the minibuffer type the search term (e.g., teh) and press return, then type the replacement term (e.g., the) and press return again. Aquamacs will highlight the first occurrence of the search term.

To replace this occurrence and move on to the next one, type y ("yes") or press the space bar.
To move to the next occurrence without replacing the current one, type n ("no") or the delete key.
To replace all following occurences, type !.
To go back to a previous occurrence, type ^.
To cancel before the end of the file, type q ("quit") or press return.

Search and replace with special characters (regular expressions)

If you want to search for text that only occurs in a particular context, then you will need to learn a little bit about Emac's so-called regular expressions. For instance you can specify that text is a whole word, or occurs at the end of a line.

^ = start of line: For instance, ^the finds "the" at the beginning of a line.
$ = end of line: Similarly, the$ finds "the" at the end of a line.
\< = start of word: Then \<the finds "the" at the start of a word (e.g., in "there" but not in "lithe")
\> = end of word: the\> finds "the" at the end of a word (e.g., in "lithe" but not in "there"). Thus \<the\> finds whole-word "the" (but not words like "there" or "lithe".

You can also use regular expressions to make more generalised search terms.

[ ] can contain any set of characters: For instance, th[aeiou] will find the characters "th" followed by any short vowel. You can put any combination of characters inside the square brackets.
. = any single character: Also, t.e will find the characters "t" and "e" separated by any single character (e.g., "the" but also "tee", "tre" "t-e", etc.)
.* = any number of characters: t.*e will find the characters "t" and "e" separated by any number of characters (e.g., "te" but also "treasure").

To use these regular expressions in a search, you need to:

Type M C-s and return (then enter your search term) to search forwards in a file.
Type M C-r and return (then enter your search term) to search backwards.
To search and replace, type M-x query-replace-regexp and return (then enter your search term and replacement term).

Searching in multiple files at once

To search for texts in many files in the same folder, type M-x lgrep and follow the prompts in the mini-buffer. To search in nested folders, type M-x rgrep.

Working with windows and buffers

Almost everything on the File and Windows menus is self-explanatory. You can almost always open, save, close, and print buffers using menu items, toolbar items, and normal Mac keyboard shortcuts just as you would normally.

It's often useful to have two views of the same file at once, especially if you are lemmatising and translating at the same time. C-x 2 splits a buffer in half horizontally and C-x 1 removes the split. C-x 5 2 opens the same buffer in a new frame, so that you can put them side by side.

C-x 1 is particularly useful for getting rid of messages and error reports from the ATF checker when you have finished with them—but make sure your cursor is in the frame you want to keep!

If you have several buffers open at once, you can keep track of them, and move between them through the list in the Windows menu. A * after a file name means that it has been edited since it was last saved.

When Emacs starts up, it automatically opens a buffer called *scratch*, which you can use as a dumping ground for notes, to-do lists and text (such as ATF protocol lines) that you frequently re-use. If you don't want to use *scratch*, just ignore it: you can't get rid of it but it's harmless.

The Mode Line

Just above the minibuffer is a grey line (called the Mode Line, for what it's worth) with lots of useful information in it. It probably says something like:

\u:** filename.atf 68% of 43k (334,48) [(ATF Outl)]

If \ is showing this means that you have Cuneiform typing mode on (see the Emacs page). To toggle it on and off, type C-\.
The letter u means that your character set is correctly set to Unicode UTF-8. If you see some other letter instead, choose the Menu item Options > Language > Set Language Environment > UTF-8.
The characters ** mean that the buffer has been edited or changed since you last saved it; the characters -- mean that it is unchanged since the last save.
Then the Mode Line gives the name of the file in the buffer, with whatever name and extension you have given it.
After that you see how large the file is, and where your cursor is within the file. In this example it is over 2/3 way down a 43k file.
The numbers in parentheses tell you exactly where you are in the file, if it is not too large. In this case, the cursor is on the 334th line and the 48th character from the beginning (left) of that line. It is often quite useful to know where you are in a file.
The part in square brackets tells you which mode you are working in. It should be set to ATF and perhaps also Outl(ine) mode. If not, type M-x atf-mode to enter ATF mode.

Exploring more of Emacs's capabilities

The GNU Emacs manual [http://www.gnu.org/software/emacs/manual/emacs.html] is exhaustive and useful (if you are patient) but is geared to Unix users and/or programmers. Similarly, Debra Cameron et al.'s book, Learning GNU Emacs, 3rd ed., O'Reilly (2005) starts too slowly and then covers far more ground than you will need. But it does include a very handy detachable reference card inside the back cover listing dozens of useful keyboard shortcuts. In the end, a search in your web browser for "Emacs thing command" (where "thing" is whatever you are looking for) is almost always the quickest way to find what you want to know.