Working with ATF in Emacs using atf-mode

An Emacs major mode is available which makes editing ATF files a bit easier and gives access to the template generator and checker.

Starting to use Emacs

See the pages on Aquamacs and EmacsW32 for some additional help on getting started with Emacs.

Using ATF mode

If you name your files using the extension .atf, Emacs will automatically switch into ATF mode when you create a new file or load an existing one.

If you name your files using another extension, for example .txt, you can set the mode explicitly by typing Esc-x (escape then x) and then entering atf-mode at the prompt.

You can now use the ATF menu to read the ATF mode help, which will in turn tell you how to use the other menu items effectively.

Creating New Transliterations

1. Use menu File Visit new file to open a new file

2. If your new file does not have a .atf extension, enter ATF mode manually

3. Enter a template specification in your new file; you can access the template help from the ATF menu

4. When you have completed your template, select menu Create Template

5. Review the block structure you have created; if is incorrect, use the undo function to remove the block structure, edit the template specification and recreate the template

6. When you are satisfied with your template, delete the template specification

Selective Views

As of 2009-05-04, atf-mode enables outline-minor-mode; use the 'ATF mode help' item from the ATF menu and read the 'Selective Display' section for more information.

Using the Checker

Although you can use the menu, there are two particularly useful keystrokes for working with the checker:

C-c-C-c

This is control-c then control-c again. This runs the checker and displays the results in another window.

C-c-C-n

This is control-c then control-n. This moves the cursor to the next erroneous line in your ATF file (it is often easier to use this key than C-x-`, which is the mainstream key-binding for the next-error command.

Using Tramp to Edit Files on a Server

Emacs includes a package named tramp which can be used to edit files on a remote machine. This means that if you work on a project which is hosted on oracc.museum.upenn.edu you can keep the files there and edit them using Emacs. When you save the file it is saved back to the server.

Tramp is activated automatically when you type a filename that starts with a forward slash (/). Tramp filenames have the following syntax:

/<USER>@<MACHINE>:<FILE>

This works with directories, too, which can then be clicked on to open files; and you can also use <TAB>-completion, so tramp will go away and get the list of files that complete for you.

So, if you are part of a project named, say, dcclt, and you have the DCCLT password, you can start by typing the Emacs command to open a file:

C-x C-f

You'll get a prompt Find file: which may have some filename or directory already there. You can ignore anything that may be there and type starting with the forward slash:

/dcclt@oracc.museum.upenn.edu:00atf/<TAB>

You should be prompted for a password and then see a list of the sources. Click on a file to open it.

Troubleshooting

Checker fails on Windows with strange '&amp;P123456' results

Check the XML-RPC Customization option 'Xml Rpc Allow Unicode String': if it is not set to 'nil', then set it to 'nil' and try again.

(To find this option, try Options -> Customize Emacs -> Settings Matching Regexp and type xml-rpc-* at the prompt.)

Using a Remote Access Program, e.g., HummingBird

If you are having difficulty connecting via a graphical user interface to SSH and friends, check that all of the following are correct:

• Hostname = oracc.museum.upenn.edu

• Port number = 80

• User ID = your project's abbreviation, in lowercase letters

• Password = the correct password for your project

• Starting Directory = the path /home/ followed by your project's abbreviation, in lowercase letters.

Entering Unicode Characters

The Emacs ATF package includes an input method which is based on the Emacs MULE TeX input method but adds some characters which are useful for cuneiform transliterations. If the ATF mode package is installed correctly this input method is available under the name 'Cuneiform'.

To use this input method:

1. Use control-backslash (\) to switch the Cuneiform input method on and off; when the method is enabled you will see a backslash at the left end of the status line

Keyboard Sequences in Cuneiform Input Method

The Cuneiform transliteration input method is based on control sequences used by the typesetting package TeX, with some additions. In general these sequences start with the backslash character, followed by an accent character, then the character that will receive the accent. These sequences are notated as, e.g., \-v-s in the following table (meaning, in this case, that you type the backslash, then v, then s, which gives you shin, š).

Note that the table below restricts the list of available characters to those needed for cuneiform transliteration; many more characters are available following the same principles.

See also the Unicode for cuneiform transliteration page and the fonts page. If you don't see the subscript x character you probably need to update to the latest fonts.

Several other characters are provided using the following sequences:

(Note that lower left/right square brackets are not used in ATF; they are provided for use in citing published work.)

A few characters require typing a word after the backslash:

If you are using the #atf: use unicode protocol you must also type the grapheme index numbers as Unicode subscripts using the \-<digit> sequences:

Eleanor Robson & Greta Van Buylaere

Eleanor Robson & Greta Van Buylaere, 'Working with ATF in Emacs using atf-mode', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 [http://oracc.museum.upenn.edu/doc/help/nammuandemacs/emacsforatf/]