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.

Obtaining Emacs

Fonts

It is best to install the DejaVu fonts before installing ATF mode; see the fonts page for further information.

Downloading and Installing ATF Mode and friends

  1. Download the Emacs lisp files in the archive atf-mode.zip.
  2. Unzip the archive to extract the files in the directory or folder where you want them to live:
    • for Unix and Mac OS X it is simplest to extract into your home directory.
    • on Windows XP EmacsW32 considers the home directory to be (for user 's') c:\Documents and Settings\s\Application Data.
  3. Locate your .emacs file; this will be in your home directory and it may be hidden. It is possible that it may not exist, if your Emacs installation creates it on demand when needed to store configuration options. To locate this file it is easiest to use Emacs: type ctrl-x ctrl-f and enter the filename as ~/.emacs. If the file does not exist, Emacs will create it.
  4. Edit your .emacs file to include the following line: 
    (load-file "~/cdl-init.el")
    (The file name will be different if you do not extract the files to your home directory or Application Data under Windows).
  5. Save your .emacs, exit Emacs and restart.

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.

Note:

Before you begin checking, ensure the XML-RPC Customization option 'Xml Rpc Allow Unicode String' is set to 'nil'.

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

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 cdl.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@cdl.museum.upenn.edu:sources/<TAB>

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

Tramp and Emacs on Windows

Windows needs additional programs to enable Tramp to work effectively, but installing them is not hard:

  1. Install putty from the PuTTY Download Page. Use the Windows installer that installs everything.
  2. Edit your Windows path to include C:\Program Files\PuTTY:
    1. Left-click on My Computer
    2. Select Properties
    3. Go to the Advanced tab
    4. Click Environment Variables button
    5. Scroll down to the Path variable in System Variables field
    6. Double-click Path variable
    7. Append your PuTTy install directory to the Variable value field, for example
      ;C:\Program Files\PuTTy, to the end of the line. Remember the semi-colon first - It's important.
    8. Apply settings, get back to desktop.
  3. Open the file .emacs by typing C-x C-f and answering ~/.emacs at the Find File: prompt. Now add the following line to .emacs and then save the file: 
    (setq tramp-default-method "plink")
  4. Restart Emacs.

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:

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.

Sequence Accent Name Available for: Results:
\-'AcuteaeiuAEIUsSáéíúÁÉÍÚśŚ
\-`GraveaeiuAEIUàèìùÀÈÌÙ
\-=MacronaeiuAEIUāēīūĀĒĪŪ
\-^CircumflexaeiuAEIUâêîûÂÊÎÛ
\-vHacheksSšŠ
\-dDot-undersStTṣṢṭṬ

Several other characters are provided using the following sequences:

\-h , \-Hḫ , Ḫ
\-j , \-Jŋ , Ŋ
\-[ , \-]˹ , ˺
\-_[ , \-_]⸤ , ⸥

(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:

\times×
\alefʾ
\ayinʿ

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

\-00
\-11
...
\-99
\-++
\-xx