Starting to use EmacsW32

Here we give a short description of some features that we have found useful for editing and lemmatising ATF in EmacsW32 (Emacs for Windows), 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 Emacs has its own little quirks. This page aims to make working with Emacs as intuitive and Windows-like as possible.

Troubleshooting

If you get the error message directory ~/.emacs.d/server is unsafe open the .emacs file which you installed from the Emacs setup page, by typing ctrl-x ctrl-f and entering the filename as ~/.emacs. At the end of the file, you'll find a possible solution to this problem.

Fonts

To ensure you have all the necessary transliteration and normalisation characters, we recommend that you install the DejaVu font. Two different ways of typing transliteration characters are described on other pages. You can use either or both, as you like.

The .emacs-file allows you to customize the behaviour of Emacs. The .emacs-file available from the Emacs page [../] sets the default font and the ATF font to DejaVu Mono.

If you want to change the font size, locate the .emacs-file from within Emacs by typing ctrl-x ctrl-f and entering the filename as ~/.emacs. In the file, you'll find three lines with:

"-outline-Dejavu Sans Mono-normal-r-normal-normal-17-*-*-*-c-*-iso10646-1"

If you would prefer a larger or smaller font, simply increase or decrease the -17-. Save the file, close Emacs and restart.

Menus and the Toolbar

When you first install Emacs, 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 Windows 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 have several web pages open at once in different tabs. You may also be unfamiliar with the Emacs terms "directory" (folder) and "search" (find).

Apart from the ATF menu, the File, Edit, Options, and Buffers 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 Buffers 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.

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.

On PCs the Control key is marked Ctrl and is normally found in the bottom left corner 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.

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.

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 Edit > Undo, or type C-x u or C-z (the usual "cancel" in Windows) as you would normally.

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") or with the usual C-Del (where Del is the normal Delete key).
Delete text to the start of the current word with C-Backspace (where Backspace is the key with which you normally delete the previous character, often situated above the Enter key and marked with an arrow).
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 M-g g (for "goto") and then the line number. For instance, M-g g 123 will move the cursor to line 123 of the file.

Searching for text

Search forwards with C-s (for "search"), then type your search term into the minibuffer and press return.
Repeat the search with C-s again.
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. Emacs 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 [RegExp])

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

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

Type M C-s (then enter your search term) to search forwards in a file.
Type M C-r (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). Alternatively, choose Edit > Replace > Replace Regexp.

^ = 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").

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 Buffers menus is self-explanatory. You can almost always open, save, close, and print buffers using menu items, toolbar items. To print .atf-files, choose File > Print Buffer with Notepad (B+W) (requires Lennart Borgman's w32-winprint.el).

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 vertically and C-x 1 removes the split. C-x 3 splits the window horizontally - alternatively, 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 Buffers menu. A * after a file name means that it has been edited since it was last saved. You can also move between buffers with C-Tab and C-Shift-Tab (this requires Igor Boukanov's pc-bufsw.el).

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) with lots of useful information in it. It probably says something like:

-\U\**- filename.atf 68% (334,48) (ATF Outl vl wrap)

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 > Mule (Multilingual Environment) > 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 where your cursor is within the file. In this example it is over 2/3 way down a 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.
The following part in parentheses 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. vl wrap indicates that you're working in Visual Line mode with Line Wrapping.

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.