# HG changeset patch # User Glenn Morris # Date 1189054023 0 # Node ID 232e4ce2914eec9720fe01edc17d253a16fa601e # Parent c9e054c6ab4091f3daa2379119add494a4556ca7 Move here from ../../man diff -r c9e054c6ab40 -r 232e4ce2914e doc/emacs/macos.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/macos.texi Thu Sep 06 04:47:03 2007 +0000 @@ -0,0 +1,429 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Mac OS, Microsoft Windows, Antinews, Top +@appendix Emacs and Mac OS +@cindex Mac OS +@cindex Macintosh + + 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 (@code{dump-emacs}), +asynchronous subprocesses (@code{start-process}), and networking +(@code{open-network-stream}). As a result, packages such as Gnus, +GUD, and Comint do not work. Synchronous subprocesses +(@code{call-process}) are supported on non-Carbon build, but +specially-crafted external programs are needed. Since external +programs to handle commands such as @code{print-buffer} and +@code{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. + +@menu +* Input: Mac Input. Keyboard and mouse input on Mac. +* Intl: Mac International. International character sets on Mac. +* Env: Mac Environment Variables. Setting environment variables for Emacs. +* Directories: Mac Directories. Volumes and directories on Mac. +* Font: Mac Font Specs. Specifying fonts on Mac. +* Functions: Mac Functions. Mac-specific Lisp functions. +@end menu + +@node Mac Input +@section Keyboard and Mouse Input on Mac +@cindex Meta (Mac OS) +@cindex keyboard coding (Mac OS) + +@vindex mac-control-modifier +@vindex mac-command-modifier +@vindex mac-option-modifier +@vindex mac-function-modifier + On Mac, Emacs can use @key{control}, @key{command}, @key{option}, and +laptop @key{function} keys as any of Emacs modifier keys except +@key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and +@key{SUPER}). The assignment is controlled by the variables +@code{mac-control-modifier}, @code{mac-command-modifier}, +@code{mac-option-modifier}, and @code{mac-function-modifier}. The value +for each of these variables can be one of the following symbols: +@code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and +@code{nil} (no particular assignment). By default, the @key{control} +key works as @key{CTRL}, and the @key{command} key as @key{META}. + + For the @key{option} key, if @code{mac-option-modifier} is set to +@code{nil}, which is the default, the key works as the normal +@key{option} key, i.e., dead-key processing will work. This is useful +for entering non-@acronym{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. + +@vindex mac-pass-command-to-system +@vindex mac-pass-control-to-system + Mac OS intercepts and handles certain key combinations (e.g., +@key{command}-@key{SPC} for switching input languages). These will not +be passed to Emacs. One can disable this interception by setting +@code{mac-pass-command-to-system} or @code{mac-pass-control-to-system} +to @code{nil}. + +@vindex mac-emulate-three-button-mouse + Especially for one-button mice, the multiple button feature can be +emulated by setting @code{mac-emulate-three-button-mouse} to @code{t} +or @code{reverse}. If set to @code{t} (@code{reverse}, respectively), +pressing the mouse button with the @key{option} key is recognized as +the second (third) button, and that with the @key{command} key is +recognized as the third (second) button. + +@vindex mac-wheel-button-is-mouse-2 + For multi-button mice, the wheel button and the secondary button are +recognized as the second and the third button, respectively. If +@code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles +are exchanged. + +@node Mac International +@section International Character Set Support on Mac +@cindex Mac Roman coding system +@cindex clipboard support (Mac OS) + + 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 +@code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic} +are used to represent these Mac encodings. + + You can use input methods provided either by LEIM (@pxref{Input +Methods}) or Mac OS to enter international characters. To use the +former, see the International Character Set Support section of the +manual (@pxref{International}). + + Emacs on Mac OS automatically changes the value of +@code{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 (@pxref{Killing}) 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 @code{x-select-enable-clipboard} to @code{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 +@code{set-selection-coding-system} (@pxref{Communication Coding}) 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 @code{mule-unicode-0100-24ff} charset, but Japanese users would +prefer them to be decoded into the @code{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 (@pxref{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: + +@enumerate +@item +Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as +in other systems. + +@item +Preference @code{AppleLocale} that is set by default on Mac OS X 10.3 +and later. + +@item +Preference @code{AppleLanguages} that is set by default on Mac OS X +10.1 and later. + +@item +Variable @code{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. +@end enumerate + + 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. + +@node Mac Environment Variables +@section Environment Variables and Command Line Arguments. +@cindex environment variables (Mac OS) + + 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 +@file{~/.MacOSX/environment.plist} that affects all the applications +invoked from the Finder or the @command{open} command. + + Command line arguments are specified like + +@example +/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 & +@end example + +@noindent +if Emacs is installed at @file{/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 @samp{STR#} resources 128 and +129, respectively. A common environment variable that one may want to +set is @samp{HOME}. + + The way to set an environment variable is by adding a string of the +form + +@example +ENV_VAR=VALUE +@end example + +@noindent +to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the +program to use unibyte characters exclusively, for example, add the +string + +@example +EMACS_UNIBYTE=1 +@end example + +@cindex Mac Preferences + Although Emacs on Mac does not support X resources (@pxref{X +Resources}) directly, one can use the Preferences system in place of X +resources. For example, adding the line + +@example +Emacs.cursorType: bar +@end example + +@noindent +to @file{~/.Xresources} in X11 corresponds to the execution of + +@example +defaults write org.gnu.Emacs Emacs.cursorType bar +@end example + +@noindent +on Mac OS X. One can use boolean or numeric values as well as string +values as follows: + +@example +defaults write org.gnu.Emacs Emacs.toolBar -bool false +defaults write org.gnu.Emacs Emacs.lineSpacing -int 3 +@end example + +@noindent +Try @kbd{M-x man RET defaults RET} for the usage of the +@command{defaults} command. Alternatively, if you have Developer +Tools installed on Mac OS X, you can use Property List Editor to edit +the file @file{~/Library/Preferences/org.gnu.Emacs.plist}. + + +@node Mac Directories +@section Volumes and Directories on Mac +@cindex file names (Mac OS) + + This node applies to Mac OS Classic only. + + The directory structure in Mac OS Classic is seen by Emacs as + +@example +/@var{volumename}/@var{filename} +@end example + +So when Emacs requests a file name, doing file name completion on +@file{/} will display all volumes on the system. You can use @file{..} +to go up a directory level. + + On Mac OS Classic, to access files and folders on the desktop, look +in the folder @file{Desktop Folder} in your boot volume (this folder +is usually invisible in the Mac @code{Finder}). + + On Mac OS Classic, Emacs creates the Mac folder +@file{:Preferences:Emacs:} in the @file{System Folder} and uses it as +the temporary directory. Emacs maps the directory name @file{/tmp/} +to that. Therefore it is best to avoid naming a volume @file{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 +@code{TMPDIR} to use another directory but this folder will still be +created. + + +@node Mac Font Specs +@section Specifying Fonts on Mac +@cindex font names (Mac OS) + + 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: + +@lisp +(set-face-attribute 'default nil + :family "courier" :height 140) +@end lisp + +@noindent +Alternatively, an interactive one is also available +(@pxref{Face Customization}). + +But when you do need to specify a font name in Emacs on Mac, use a +standard X font name: + +@smallexample +-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} +@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} +@end smallexample + +@noindent +@xref{Font X}. 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 @acronym{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. + + @acronym{ATSUI}-compatible fonts have maker name @code{apple} and +charset @code{iso10646-1}. For example, 12-point Monaco can be specified +by the name: + +@example +-apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1 +@end example + +Note that these names must be specified using a format containing all +14 @samp{-}s (not by +@samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance), +because every @acronym{ATSUI}-compatible font is a scalable one. + + QuickDraw Text fonts have maker name @code{apple} and various charset +names other than @code{iso10646-1}. Native Apple fonts in Mac Roman +encoding has charset @code{mac-roman}. You can specify a +@code{mac-roman} font for @acronym{ASCII} characters like + +@smalllisp +(add-to-list + 'default-frame-alist + '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman")) +@end smalllisp + +@noindent +but that does not extend to ISO-8859-1: specifying a @code{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 @samp{big5-0}, @samp{gb2312.1980-0}, +@samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0}, +@samp{ksc5601.1989-0}, @samp{mac-centraleurroman}, +@samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats}, +respectively. + + The use of @code{create-fontset-from-fontset-spec} (@pxref{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 +@code{create-fontset-from-mac-roman-font}: + +@lisp +(create-fontset-from-mac-roman-font + "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman" + nil "foo") +@end lisp + +@noindent +and then optionally specifying Chinese, Japanese, or Korean font +families using @code{set-fontset-font}: + +@lisp +(set-fontset-font "fontset-foo" + 'chinese-gb2312 '("song" . "gb2312.1980-0")) +@end lisp + + 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 +@samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by +the name @samp{-ETL-fixed-*-iso8859-1}. + +@vindex mac-allow-anti-aliasing + 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 +@code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil} +(QuickDraw). Both @acronym{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 @var{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 +@command{defaults} command: + +@example +defaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n} +@end example + + +@node Mac Functions +@section Mac-Specific Lisp Functions +@cindex Lisp functions specific to Mac OS + +@findex do-applescript + The function @code{do-applescript} takes a string argument, +executes it as an AppleScript command, and returns the result as a +string. + +@findex mac-file-name-to-posix +@findex posix-file-name-to-mac + The function @code{mac-file-name-to-posix} takes a Mac file name and +returns the GNU or Unix equivalent. The function +@code{posix-file-name-to-mac} performs the opposite conversion. They +are useful for constructing AppleScript commands to be passed to +@code{do-applescript}. + +@findex mac-set-file-creator +@findex mac-get-file-creator +@findex mac-set-file-type +@findex mac-get-file-type + The functions @code{mac-set-file-creator}, +@code{mac-get-file-creator}, @code{mac-set-file-type}, and +@code{mac-get-file-type} can be used to set and get creator and file +codes. + +@findex mac-get-preference + The function @code{mac-get-preference} returns the preferences value +converted to a Lisp object for a specified key and application. + +@ignore + arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 +@end ignore