Emacs and the Mac OS
********************

Emacs built on Mac OS X supports most of its major features: multiple frames, colors, scroll bars, menu bars, use of the mouse, fontsets, international characters, input methods, coding systems, asynchronous and synchronous subprocesses, unexec (dump-emacs), and networking (open-network-stream).  Support for various image file formats has not been implemented yet.

The following features of Emacs are not yet supported on the Mac OS 8 or 9: unexec (dump-emacs), asynchronous subprocesses (start-process), and networking (open-network-stream). As a result, packages such as Gnus, GUD, and Comint do not work. However, synchronous subprocesses (call-process) are supported. Since external programs to handle commands such as print-buffer and diff are not available on Mac OS 8 or 9, they are not supported.

Most of the features that are supported work in the same way as on other platforms and are therefore documented in the rest of this manual.  This section describes the peculiarities of using Emacs under the Mac OS.

Keyboard Input on the Mac
=========================

On the Mac, Emacs can use either the option key or the command key as the META key.  If the value of the variable mac-command-key-is-meta is non-nil (its default value), Emacs uses the command key as the META key.  Otherwise it uses the option key as the META key.

Most people should want to use the command key as the META key, so that dead-key processing with the option key will still work.  This is useful for entering non-ASCII Latin characters directly from the Mac keyboard, for example.

Emacs recognizes the setting in the Keyboard control panel and supports international and alternative keyboard layouts (e.g., Dvorak). Selecting one of the layouts from the keyboard layout pull-down menu will affect how the keys typed on the keyboard are interpreted.

The Mac OS intercepts and handles certain key combinations (e.g., command-SPC for switching input languages).  These will not be passed to Emacs.

The Mac keyboard ordinarily generates characters in the Mac Roman encoding.  To use it for entering ISO Latin-1 characters directly, set the value of the variable mac-keyboard-text-encoding to kTextEncodingISOLatin1.  Note that not all Mac Roman characters that can be entered at the keyboard can be converted to ISO Latin-1 characters.

To enter ISO Latin-2 characters directly from the Mac keyboard, set the value of mac-keyboard-text-encoding to kTextEncodingISOLatin2.  Then let Emacs know that the keyboard generates Latin-2 codes, by typing C-x RET k iso-latin-2 RET.  To make this setting permanent, put this in your .emacs init file:

     (set-keyboard-coding-system 'iso-latin-2)

International Character Set Support on the Mac
==============================================

The Mac uses a non-standard encoding for the upper 128 single-byte characters.  It also deviates from the ISO 2022 standard by using character codes in the range 128-159.  The coding system mac-roman is used to represent this Mac encoding.  It is used for editing files stored in this native encoding, and for displaying file names in Dired mode.

Any native (non-symbol) Mac font can be used to correctly display characters in the mac-roman coding system.

The fontset fontset-mac is created automatically when Emacs is run on the Mac.  It displays characters in the mac-roman coding system using 12-point Monaco.

To insert characters directly in the mac-roman coding system, type C-x RET k mac-roman RET, customize the option keyboard-coding-system, or put this in your init file:

     (set-keyboard-coding-system 'mac-roman)

This is useful for editing documents in native Mac encoding.

You can use input methods provided either by LEIM (see Input Methods) or the Mac OS to enter international characters.

To use the former, see the International Character Set Support section of the manual (see International).

To use input methods provided by the Mac OS, set the keyboard coding system accordingly using the C-x RET k command (set-keyboard-coding-system).  For example, for Traditional Chinese, use chinese-big5 as keyboard coding system; for Japanese, use sjis, etc.  Then select the desired input method in the keyboard layout pull-down menu.

The Mac clipboard and the Emacs kill ring (see Killing) are connected as follows: the most recent kill is copied to the clipboard when Emacs is suspended and the contents of the clipboard is inserted into the kill ring when Emacs resumes.  The result is that you can yank a piece of text and paste it into another Mac application, or cut or copy one in another Mac application and yank it into a Emacs buffer.

The encoding of text selections must be specified using the commands C-x RET x (set-selection-coding-system) or C-x RET X (set-next-selection-coding-system) (e.g., for Traditional Chinese, use chinese-big5-mac and for Japanese, sjis-mac).  See Specify Coding, for more details.

Environment Variables and Command Line Arguments.
=================================================

On Mac OS X, when Emacs is run in a terminal, it inherits the values of environment variables from the shell from which it is invoked. However, when it is run from the Finder as a GUI application, it inherits no environment variable values.

On Mac OS 8 or 9, environment variables and command line arguments for Emacs can be set by modifying the STR# resources 128 and 129, respectively.  A common environment variable that one may want to set is HOME.

The way to set an environment variable is by adding a string of the form

     ENV_VAR=VALUE

to resource STR# number 128 using ResEdit. To set up the program to use unibyte characters exclusively, for example, add the string

     EMACS_UNIBYTE=1

Volumes and Directories on the Mac
==================================

The directory structure in the Mac OS is seen by Emacs as

     /VOLUMENAME/FILENAME

So when Emacs requests a file name, doing file name completion on / will display all volumes on the system.  You can use .. to go up a directory level.

On Mac OS 8 or 9, to access files and folders on the desktop, look in the folder Desktop Folder in your boot volume (this folder is usually invisible in the Mac Finder).

On Mac OS 8 or 9, Emacs creates the Mac folder :Preferences:Emacs: in the System Folder and uses it as the temporary directory.  Emacs maps the directory name /tmp/ to that.  Therefore it is best to avoid naming a volume tmp. If everything works correctly, the program should leave no files in it when it exits.  You should be able to set the environment variable TMPDIR to use another directory but this folder will still be created.

Specifying Fonts on the Mac
===========================

It is rare that you need to specify a font name in Emacs; usually you specify face attributes instead.  But when you do need to specify a font name in Emacs on the Mac, use a standard X font name:

     -MAKER-FAMILY-WEIGHT-SLANT-WIDTHTYPE-STYLE...
     ...-PIXELS-HEIGHT-HORIZ-VERT-SPACING-WIDTH-CHARSET

See Font X.  Wildcards are supported as they are on X.

Native Apple fonts in Mac Roman encoding has maker name apple and charset mac-roman.  For example 12-point Monaco can be specified by the name -apple-monaco-*-12-*-mac-roman.

Native Apple Traditional Chinese, Simplified Chinese, Japanese, and Korean fonts have charsets big5-0, gb2312.1980-0, jisx0208.1983-sjis, and ksc5601.1989-0, respectively.

Single-byte fonts converted from GNU fonts in BDF format, which are not in the Mac Roman encoding, have foundry, family, and character sets encoded in the names of their font suitcases.  E.g., the font suitcase ETL-Fixed-ISO8859-1 contains fonts which can be referred to by the name -ETL-fixed-*-iso8859-1.

Mac-Specific Lisp Functions
===========================

The function do-applescript takes a string argument, executes it as an AppleScript command, and returns the result as a string.

The function mac-file-name-to-posix takes a Mac file name and returns the GNU or Unix equivalent.  The function posix-file-name-to-mac performs the opposite conversion.  They are useful for constructing AppleScript commands to be passed to do-applescript.