man/macos.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 2000, 2001, 2002, 2003, 2004,
   3 @c   2005 Free Software Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @node Mac OS, MS-DOS, Antinews, Top
   6 @appendix Emacs and Mac OS
   7 @cindex Mac OS
   8 @cindex Macintosh
   9
  10   This section briefly describes the peculiarities of using Emacs
  11 under Mac OS with native window system support.  For Mac OS X, Emacs
  12 can be built either without window system support, with X11, or with
  13 Carbon API.  This section only applies to the Carbon build.  For Mac
  14 OS Classic, Emacs can be built with or without Carbon API, and this
  15 section applies to either of them because they run on the native
  16 window system.
  17
  18   Emacs built on Mac OS X supports most of its major features except
  19 display support of PostScript images.  The following features of Emacs
  20 are not supported on Mac OS Classic: unexec (@code{dump-emacs}),
  21 asynchronous subprocesses (@code{start-process}), and networking
  22 (@code{open-network-stream}).  As a result, packages such as Gnus,
  23 GUD, and Comint do not work.  Synchronous subprocesses
  24 (@code{call-process}) are supported on non-Carbon build, but
  25 specially-crafted external programs are needed.  Since external
  26 programs to handle commands such as @code{print-buffer} and
  27 @code{diff} are not available on Mac OS Classic, they are not
  28 supported.  Non-Carbon build on Mac OS Classic does not support some
  29 features such as file dialogs, drag-and-drop, and Unicode menus.
  30
  31 @menu
  32 * Input: Mac Input.                Keyboard and mouse input on Mac.
  33 * Intl: Mac International.         International character sets on Mac.
  34 * Env: Mac Environment Variables.  Setting environment variables for Emacs.
  35 * Directories: Mac Directories.    Volumes and directories on Mac.
  36 * Font: Mac Font Specs.            Specifying fonts on Mac.
  37 * Functions: Mac Functions.        Mac-specific Lisp functions.
  38 @end menu
  39
  40 @node Mac Input
  41 @section Keyboard and Mouse Input on Mac
  42 @cindex Meta (Mac OS)
  43 @cindex keyboard coding (Mac OS)
  44
  45 @vindex mac-command-key-is-meta
  46   On Mac, Emacs can use either the @key{option} key or the
  47 @key{command} key as the @key{META} key.  If the value of the variable
  48 @code{mac-command-key-is-meta} is non-@code{nil} (its default value),
  49 Emacs uses the @key{command} key as the @key{META} key.  Otherwise it
  50 uses the @key{option} key as the @key{META} key.
  51
  52   Most people should want to use the @key{command} key as the @key{META} key,
  53 so that dead-key processing with the @key{option} key will still work.  This is
  54 useful for entering non-@acronym{ASCII} Latin characters directly from the Mac
  55 keyboard, for example.
  56
  57   Emacs recognizes the setting in the Keyboard control panel (Mac OS
  58 Classic) or the International system preference pane (Mac OS X) and
  59 supports international and alternative keyboard layouts (e.g., Dvorak)
  60 if its script is either Roman, Japanese, Traditional Chinese, Korean,
  61 Cyrillic, Simplified Chinese, or Central European.  Keyboard layouts
  62 based on Unicode may not work properly.  Selecting one of the layouts
  63 from the keyboard layout pull-down menu will affect how the keys typed
  64 on the keyboard are interpreted.
  65
  66 @vindex mac-pass-command-to-system
  67 @vindex mac-pass-control-to-system
  68   Mac OS intercepts and handles certain key combinations (e.g.,
  69 @key{command}-@key{SPC} for switching input languages).  These will not
  70 be passed to Emacs.  One can disable this interception by setting
  71 @code{mac-pass-command-to-system} or @code{mac-pass-control-to-system}
  72 to @code{nil}.
  73
  74 @vindex mac-emulate-three-button-mouse
  75   Especially for one-button mice, the multiple button feature can be
  76 emulated by setting @code{mac-emulate-three-button-mouse} to @code{t}
  77 or @code{reverse}.  If set to @code{t} (@code{reverse}, respectively),
  78 pressing the mouse button with the @key{option} key is recognized as
  79 the second (third) button, and that with the @key{command} key is
  80 recognized as the third (second) button.
  81
  82 @vindex mac-wheel-button-is-mouse-2
  83   For multi-button mice, the wheel button and the secondary button are
  84 recognized as the second and the third button, respectively.  If
  85 @code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles
  86 are exchanged.
  87
  88 @node Mac International
  89 @section International Character Set Support on Mac
  90 @cindex Mac Roman coding system
  91 @cindex clipboard support (Mac OS)
  92
  93   Mac uses non-standard encodings for the upper 128 single-byte
  94 characters.  They also deviate from the ISO 2022 standard by using
  95 character codes in the range 128-159.  The coding systems
  96 @code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic}
  97 are used to represent these Mac encodings.
  98
  99   The fontset @code{fontset-mac} is created automatically when Emacs
 100 is run on Mac, and used by default.  It displays as many kinds of
 101 characters as possible using 12-point Monaco as a base font.  If you
 102 see some character as a hollow box with this fontset, then it's almost
 103 impossible to display it only by customizing font settings (@pxref{Mac
 104 Font Specs}).
 105
 106   You can use input methods provided either by LEIM (@pxref{Input
 107 Methods}) or Mac OS to enter international characters.  To use the
 108 former, see the International Character Set Support section of the
 109 manual (@pxref{International}).
 110
 111   Emacs on Mac OS automatically changes the value of
 112 @code{keyboard-coding-system} according to the current keyboard
 113 layout.  So users don't need to set it manually, and even if set, it
 114 will be changed when the keyboard layout change is detected next time.
 115
 116   The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are
 117 synchronized by default: you can yank a piece of text and paste it
 118 into another Mac application, or cut or copy one in another Mac
 119 application and yank it into a Emacs buffer.  This feature can be
 120 disabled by setting @code{x-select-enable-clipboard} to @code{nil}.
 121 One can still do copy and paste with another application from the Edit
 122 menu.
 123
 124   On Mac, the role of the coding system for selection that is set by
 125 @code{set-selection-coding-system} (@pxref{Specify Coding}) is
 126 two-fold.  First, it is used as a preferred coding system for the
 127 traditional text flavor that does not specify any particular encodings
 128 and is mainly used by applications on Mac OS Classic.  Second, it
 129 specifies the intermediate encoding for the UTF-16 text flavor that is
 130 mainly used by applications on Mac OS X.
 131
 132   When pasting UTF-16 text data from the clipboard, it is first
 133 converted to the encoding specified by the selection coding system
 134 using the converter in the Mac OS system, and then decoded into the
 135 Emacs internal encoding using the converter in Emacs.  If the first
 136 conversion failed, then the UTF-16 data is directly converted to Emacs
 137 internal encoding using the converter in Emacs.  Copying UTF-16 text
 138 to the clipboard goes through the inverse path.  The reason for this
 139 two-path decoding is to avoid subtle differences in Unicode mappings
 140 between the Mac OS system and Emacs such as various kinds of hyphens,
 141 and to minimize users' customization.  For example, users that mainly
 142 use Latin characters would prefer Greek characters to be decoded into
 143 the @code{mule-unicode-0100-24ff} charset, but Japanese users would
 144 prefer them to be decoded into the @code{japanese-jisx0208} charset.
 145 Since the coding system for selection is automatically set according
 146 to the system locale setting, users usually don't have to set it
 147 manually.
 148
 149   The default language environment (@pxref{Language Environments}) is
 150 set according to the locale setting at the startup time.  On Mac OS,
 151 the locale setting is consulted in the following order:
 152
 153 @enumerate
 154 @item
 155 Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as
 156 in other systems.
 157
 158 @item
 159 Preference @code{AppleLocale} that is set by default on Mac OS X 10.3
 160 and later.
 161
 162 @item
 163 Preference @code{AppleLanguages} that is set by default on Mac OS X
 164 10.1 and later.
 165
 166 @item
 167 Variable @code{mac-system-locale} that is derived from the system
 168 language and region codes.  This variable is available on all
 169 supported Mac OS versions including Mac OS Classic.
 170 @end enumerate
 171
 172   The default values of almost all variables about coding systems are
 173 also set according to the language environment.  So usually you don't
 174 have to customize these variables manually.
 175
 176 @node Mac Environment Variables
 177 @section Environment Variables and Command Line Arguments.
 178 @cindex environment variables (Mac OS)
 179
 180   On Mac OS X, when Emacs is run in a terminal, it inherits the values
 181 of environment variables from the shell from which it is invoked.
 182 However, when it is run from the Finder as a GUI application, it only
 183 inherits environment variable values defined in the file
 184 @file{~/.MacOSX/environment.plist} that affects all the applications
 185 invoked from the Finder or the @command{open} command.
 186
 187   Command line arguments are specified like
 188
 189 @example
 190 /Applications/Emacs.app/Contents/MacOS/Emacs -geometry 80x25 &
 191 @end example
 192
 193 @noindent
 194 if Emacs is installed at @file{/Applications/Emacs.app}.  If Emacs is
 195 invoked like this, then it also inherits the values of environment
 196 variables from the shell from which it is invoked.
 197
 198   On Mac OS Classic, environment variables and command line arguments
 199 for Emacs can be set by modifying the @samp{STR#} resources 128 and
 200 129, respectively.  A common environment variable that one may want to
 201 set is @samp{HOME}.
 202
 203   The way to set an environment variable is by adding a string of the
 204 form
 205
 206 @example
 207 ENV_VAR=VALUE
 208 @end example
 209
 210 @noindent
 211 to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the
 212 program to use unibyte characters exclusively, for example, add the
 213 string
 214
 215 @example
 216 EMACS_UNIBYTE=1
 217 @end example
 218
 219 @cindex Mac Preferences
 220   Although Emacs on Mac does not support X resources (@pxref{X
 221 Resources}) directly, one can use the Preferences system in place of X
 222 resources.  For example, adding the line
 223
 224 @example
 225 Emacs.cursorType: bar
 226 @end example
 227
 228 @noindent
 229 to @file{~/.Xresources} in X11 corresponds to the execution of
 230
 231 @example
 232 defaults write org.gnu.Emacs Emacs.cursorType bar
 233 @end example
 234
 235 @noindent
 236 on Mac OS X.  One can use boolean or numeric values as well as string
 237 values as follows:
 238
 239 @example
 240 defaults write org.gnu.Emacs Emacs.toolBar -bool false
 241 defaults write org.gnu.Emacs Emacs.lineSpacing -int 3
 242 @end example
 243
 244 @noindent
 245 Try @kbd{M-x man RET defaults RET} for the usage of the
 246 @command{defaults} command.  Alternatively, if you have Developer
 247 Tools installed on Mac OS X, you can use Property List Editor to edit
 248 the file @file{~/Library/Preferences/org.gnu.Emacs.plist}.
 249
 250
 251 @node Mac Directories
 252 @section Volumes and Directories on Mac
 253 @cindex file names (Mac OS)
 254
 255   This node applies to Mac OS Classic only.
 256
 257   The directory structure in Mac OS Classic is seen by Emacs as
 258
 259 @example
 260 /@var{volumename}/@var{filename}
 261 @end example
 262
 263 So when Emacs requests a file name, doing file name completion on
 264 @file{/} will display all volumes on the system.  You can use @file{..}
 265 to go up a directory level.
 266
 267   On Mac OS Classic, to access files and folders on the desktop, look
 268 in the folder @file{Desktop Folder} in your boot volume (this folder
 269 is usually invisible in the Mac @code{Finder}).
 270
 271   On Mac OS Classic, Emacs creates the Mac folder
 272 @file{:Preferences:Emacs:} in the @file{System Folder} and uses it as
 273 the temporary directory.  Emacs maps the directory name @file{/tmp/}
 274 to that.  Therefore it is best to avoid naming a volume @file{tmp}.
 275 If everything works correctly, the program should leave no files in it
 276 when it exits.  You should be able to set the environment variable
 277 @code{TMPDIR} to use another directory but this folder will still be
 278 created.
 279
 280
 281 @node Mac Font Specs
 282 @section Specifying Fonts on Mac
 283 @cindex font names (Mac OS)
 284
 285   It is rare that you need to specify a font name in Emacs; usually
 286 you specify face attributes instead.  But when you do need to specify
 287 a font name in Emacs on Mac, use a standard X font name:
 288
 289 @smallexample
 290 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
 291 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
 292 @end smallexample
 293
 294 @noindent
 295 @xref{Font X}.  Wildcards are supported as they are on X.
 296
 297   Native Apple fonts in Mac Roman encoding has maker name @code{apple}
 298 and charset @code{mac-roman}.  For example 12-point Monaco can be
 299 specified by the name @samp{-apple-monaco-*-12-*-mac-roman}.  When
 300 using a particular size of scalable fonts, it must be specified in a
 301 format containing 14 @samp{-}s like
 302 @samp{-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman}.
 303
 304   You can specify a @code{mac-roman} font for @acronym{ASCII}
 305 characters like
 306
 307 @lisp
 308 (add-to-list
 309  'default-frame-alist
 310  '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman"))
 311 @end lisp
 312
 313 @noindent
 314 but that does not extend to ISO-8859-1: specifying a @code{mac-roman}
 315 font for Latin-1 characters introduces wrong glyphs.
 316
 317   Native Apple Traditional Chinese, Simplified Chinese, Japanese,
 318 Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have
 319 charsets @samp{big5-0}, @samp{gb2312.1980-0},
 320 @samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0},
 321 @samp{ksc5601.1989-0}, @samp{mac-centraleurroman},
 322 @samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats},
 323 respectively.
 324
 325   Since Emacs as of the current version uses QuickDraw Text routines
 326 for drawing texts, only characters in the charsets listed above can be
 327 displayed with the OS-bundled fonts, even if other applications that
 328 use @acronym{ATSUI} or Cocoa can display variety of characters with
 329 them.
 330
 331   The use of @code{create-fontset-from-fontset-spec} (@pxref{Defining
 332 Fontsets}) for defining fontsets often results in wrong ones
 333 especially when using only OS-bundled fonts.  The recommended way is
 334 to create a fontset using @code{create-fontset-from-mac-roman-font}:
 335
 336 @lisp
 337 (create-fontset-from-mac-roman-font
 338  "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman"
 339  nil "foo")
 340 @end lisp
 341
 342 @noindent
 343 and then optionally specifying Chinese, Japanese, or Korean font
 344 families using @code{set-fontset-font}:
 345
 346 @lisp
 347 (set-fontset-font "fontset-foo"
 348                   'chinese-gb2312 '("song" . "gb2312.1980-0"))
 349 @end lisp
 350
 351   Single-byte fonts converted from GNU fonts in BDF format, which are not
 352 in the Mac Roman encoding, have foundry, family, and character sets
 353 encoded in the names of their font suitcases.  E.g., the font suitcase
 354 @samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by
 355 the name @samp{-ETL-fixed-*-iso8859-1}.
 356
 357 @vindex mac-allow-anti-aliasing
 358   Emacs uses the QuickDraw text rendering by default.  On Mac OS X
 359 10.2 and later, it can be changed so that it uses the Quartz 2D text
 360 rendering (aka CG text rendering) by setting
 361 @code{mac-allow-anti-aliasing} to @code{t}.  However, it is reported
 362 to sometimes leave some garbages.
 363
 364 @node Mac Functions
 365 @section Mac-Specific Lisp Functions
 366 @cindex Lisp functions specific to Mac OS
 367
 368 @findex do-applescript
 369   The function @code{do-applescript} takes a string argument,
 370 executes it as an AppleScript command, and returns the result as a
 371 string.
 372
 373 @findex mac-file-name-to-posix
 374 @findex posix-file-name-to-mac
 375   The function @code{mac-file-name-to-posix} takes a Mac file name and
 376 returns the GNU or Unix equivalent.  The function
 377 @code{posix-file-name-to-mac} performs the opposite conversion.  They
 378 are useful for constructing AppleScript commands to be passed to
 379 @code{do-applescript}.
 380
 381 @findex mac-set-file-creator
 382 @findex mac-get-file-creator
 383 @findex mac-set-file-type
 384 @findex mac-get-file-type
 385   The functions @code{mac-set-file-creator},
 386 @code{mac-get-file-creator}, @code{mac-set-file-type}, and
 387 @code{mac-get-file-type} can be used to set and get creator and file
 388 codes.
 389
 390 @findex mac-get-preference
 391   The function @code{mac-get-preference} returns the preferences value
 392 converted to a Lisp object for a specified key and application.
 393
 394 @ignore
 395    arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
 396 @end ignore