F. Emacs and Mac OS

This section briefly describes the peculiarities of using Emacs under Mac OS with native window system support. For Mac OS X, Emacs can be built either without window system support, with X11, or with Carbon API. This section only applies to the Carbon build. For Mac OS Classic, Emacs can be built with or without Carbon API, and this section applies to either of them because they run on the native window system.

Emacs built on Mac OS X supports most of its major features except display support of PostScript images. The following features of Emacs are not supported on Mac OS Classic: 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. Synchronous subprocesses (call-process) are supported on non-Carbon build, but specially-crafted external programs are needed. Since external programs to handle commands such as print-buffer and diff are not available on Mac OS Classic, they are not supported. Non-Carbon build on Mac OS Classic does not support some features such as file dialogs, drag-and-drop, and Unicode menus.

F.1 Keyboard and Mouse Input on Mac

On Mac, Emacs can use control, command, option, and laptop function keys as any of Emacs modifier keys except SHIFT (i.e., ALT, CTRL, HYPER, META, and SUPER). The assignment is controlled by the variables mac-control-modifier, mac-command-modifier, mac-option-modifier, and mac-function-modifier. The value for each of these variables can be one of the following symbols: alt, control, hyper, meta, super, and nil (no particular assignment). By default, the control key works as CTRL, and the command key as META.

For the option key, if mac-option-modifier is set to nil, which is the default, the key works as the normal option key, i.e., dead-key processing will 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 (Mac OS Classic) or the International system preference pane (Mac OS X) 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.

Mac OS intercepts and handles certain key combinations (e.g., command-SPC for switching input languages). These will not be passed to Emacs. One can disable this interception by setting mac-pass-command-to-system or mac-pass-control-to-system to nil.

Especially for one-button mice, the multiple button feature can be emulated by setting mac-emulate-three-button-mouse to t or reverse. If set to t (reverse, respectively), pressing the mouse button with the option key is recognized as the second (third) button, and that with the command key is recognized as the third (second) button.

For multi-button mice, the wheel button and the secondary button are recognized as the second and the third button, respectively. If mac-wheel-button-is-mouse-2 is set to nil, their roles are exchanged.

F.2 International Character Set Support on Mac

Mac uses non-standard encodings for the upper 128 single-byte characters. They also deviate from the ISO 2022 standard by using character codes in the range 128-159. The coding systems mac-roman, mac-centraleurroman, and mac-cyrillic are used to represent these Mac encodings.

You can use input methods provided either by LEIM (see section Input Methods) or Mac OS to enter international characters. To use the former, see the International Character Set Support section of the manual (see section International Character Set Support).

Emacs on Mac OS automatically changes the value of keyboard-coding-system according to the current keyboard layout. So users don't need to set it manually, and even if set, it will be changed when the keyboard layout change is detected next time.

The Mac clipboard and the Emacs kill ring (see section Killing and Moving Text) are synchronized by default: 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. This feature can be disabled by setting x-select-enable-clipboard to nil. One can still do copy and paste with another application from the Edit menu.

On Mac, the role of the coding system for selection that is set by set-selection-coding-system (see section Coding Systems for Interprocess Communication) is two-fold. First, it is used as a preferred coding system for the traditional text flavor that does not specify any particular encodings and is mainly used by applications on Mac OS Classic. Second, it specifies the intermediate encoding for the UTF-16 text flavor that is mainly used by applications on Mac OS X.

When pasting UTF-16 text data from the clipboard, it is first converted to the encoding specified by the selection coding system using the converter in the Mac OS system, and then decoded into the Emacs internal encoding using the converter in Emacs. If the first conversion failed, then the UTF-16 data is directly converted to Emacs internal encoding using the converter in Emacs. Copying UTF-16 text to the clipboard goes through the inverse path. The reason for this two-pass decoding is to avoid subtle differences in Unicode mappings between the Mac OS system and Emacs such as various kinds of hyphens, and to minimize users' customization. For example, users that mainly use Latin characters would prefer Greek characters to be decoded into the mule-unicode-0100-24ff charset, but Japanese users would prefer them to be decoded into the japanese-jisx0208 charset. Since the coding system for selection is automatically set according to the system locale setting, users usually don't have to set it manually.

The default language environment (see section Language Environments) is set according to the locale setting at the startup time. On Mac OS, the locale setting is consulted in the following order:

1. Environment variables LC_ALL, LC_CTYPE and LANG as in other systems.

2. Preference AppleLocale that is set by default on Mac OS X 10.3 and later.

3. Preference AppleLanguages that is set by default on Mac OS X 10.1 and later.

4. Variable mac-system-locale that is derived from the system language and region codes. This variable is available on all supported Mac OS versions including Mac OS Classic.

The default values of almost all variables about coding systems are also set according to the language environment. So usually you don't have to customize these variables manually.

F.3 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 only inherits environment variable values defined in the file `~/.MacOSX/environment.plist' that affects all the applications invoked from the Finder or the open command.

Command line arguments are specified like

/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 &

if Emacs is installed at `/Applications/Emacs.app'. If Emacs is invoked like this, then it also inherits the values of environment variables from the shell from which it is invoked.

On Mac OS Classic, 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

Although Emacs on Mac does not support X resources (see section X Options and Resources) directly, one can use the Preferences system in place of X resources. For example, adding the line

Emacs.cursorType: bar

to `~/.Xresources' in X11 corresponds to the execution of

defaults write org.gnu.Emacs Emacs.cursorType bar

on Mac OS X. One can use boolean or numeric values as well as string values as follows:

defaults write org.gnu.Emacs Emacs.toolBar -bool false
defaults write org.gnu.Emacs Emacs.lineSpacing -int 3

Try M-x man RET defaults RET for the usage of the defaults command. Alternatively, if you have Developer Tools installed on Mac OS X, you can use Property List Editor to edit the file `~/Library/Preferences/org.gnu.Emacs.plist'.

F.4 Volumes and Directories on Mac

This node applies to Mac OS Classic only.

The directory structure in Mac OS Classic 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 Classic, 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 Classic, 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.

F.5 Specifying Fonts on Mac

It is rare that you need to specify a font name in Emacs; usually you specify face attributes instead. For example, you can use 14pt Courier by customizing the default face attributes for all frames:

(set-face-attribute 'default nil
                    :family "courier" :height 140)

Alternatively, an interactive one is also available (see section Customizing Faces).

But when you do need to specify a font name in Emacs on Mac, use a standard X font name:

-maker-family-weight-slant-widthtype-style…
…-pixels-height-horiz-vert-spacing-width-charset

See section Font Specification Options. Wildcards are supported as they are on X.

Emacs on Mac OS Classic uses QuickDraw Text routines for drawing texts by default. Emacs on Mac OS X uses ATSUI, Apple Type Services for Unicode Imaging as well as QuickDraw Text, and most of the characters other than Chinese, Japanese, and Korean ones are drawn using the former by default.

ATSUI-compatible fonts have maker name apple and charset iso10646-1. For example, 12-point Monaco can be specified by the name:

-apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1

Note that these names must be specified using a format containing all 14 `-'s (not by `-apple-monaco-medium-r-normal--12-*-iso10646-1', for instance), because every ATSUI-compatible font is a scalable one.

QuickDraw Text fonts have maker name apple and various charset names other than iso10646-1. Native Apple fonts in Mac Roman encoding has charset mac-roman. You can specify a mac-roman font for ASCII characters like

(add-to-list
 'default-frame-alist
 '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman"))

but that does not extend to ISO-8859-1: specifying a mac-roman font for Latin-1 characters introduces wrong glyphs.

Native Apple Traditional Chinese, Simplified Chinese, Japanese, Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have the charsets `big5-0', `gb2312.1980-0', `jisx0208.1983-sjis' and `jisx0201.1976-0', `ksc5601.1989-0', `mac-centraleurroman', `mac-cyrillic', `mac-symbol', and `mac-dingbats', respectively.

The use of create-fontset-from-fontset-spec (see section Defining fontsets) for defining fontsets often results in wrong ones especially when using only OS-bundled QuickDraw Text fonts. The recommended way to use them is to create a fontset using create-fontset-from-mac-roman-font:

(create-fontset-from-mac-roman-font
 "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman"
 nil "foo")

and then optionally specifying Chinese, Japanese, or Korean font families using set-fontset-font:

(set-fontset-font "fontset-foo"
		  'chinese-gb2312 '("song" . "gb2312.1980-0"))

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 OS X 10.2 or later can use two types of text renderings: Quartz 2D (aka Core Graphics) and QuickDraw. By default, Emacs uses the former on such versions. It can be changed by setting mac-allow-anti-aliasing to t (Quartz 2D) or nil (QuickDraw). Both ATSUI and QuickDraw Text drawings are affected by the value of this variable.

Appearance of text in small sizes will also be affected by the "Turn off text smoothing for font sizes n and smaller" setting in the General pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 or later) of the System Preferences. This threshold can alternatively be set just for Emacs (i.e., not as the system-wide setting) using the defaults command:

defaults write org.gnu.Emacs AppleAntiAliasingThreshold n

F.6 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.

The functions mac-set-file-creator, mac-get-file-creator, mac-set-file-type, and mac-get-file-type can be used to set and get creator and file codes.

The function mac-get-preference returns the preferences value converted to a Lisp object for a specified key and application.

This document was generated by Mark Kaminski on July, 3 2008 using texi2html 1.70.