X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b08fa67e1cc306e72815d4d15e82df8309954a12..a26126e7ea2d68c4b248516907c70ea5f69428fd:/man/macos.texi diff --git a/man/macos.texi b/man/macos.texi index 3e433a0afe..9795294389 100644 --- a/man/macos.texi +++ b/man/macos.texi @@ -1,144 +1,204 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2000 Free Software Foundation, Inc. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mac OS, MS-DOS, Antinews, Top -@appendix Emacs and the Mac OS +@appendix Emacs and Mac OS @cindex Mac OS @cindex Macintosh - Emacs built on the Mac OS supports many of its major features: -multiple frames, colors, scroll bars, menu bars, use of the mouse, -fontsets, international characters, input methods, coding systems, and -synchronous subprocesses (@code{call-process}). Much of this works in -the same way as on other platforms and is therefore documented in the -rest of this manual. This section describes the peculiarities of using -Emacs under the Mac OS. - - The following features of Emacs are not yet supported on the Mac: -unexec (@code{dump-emacs}), asynchronous subprocesses -(@code{start-process}), and networking (@code{open-network-connection}). -As a result, packages such as Gnus, Ispell, and Comint do not work. - - Since external Unix programs to handle commands such as -@code{print-buffer} and @code{diff} are not available on the Mac OS, -they are not supported in the Mac OS version. + 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 input on the Mac. -* Intl: Mac International. International character sets on the Mac. +* 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 the Mac. -* Font: Mac Font Specs. Specifying fonts on the Mac. +* 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 Input on the Mac -@cindex Meta (under Mac OS) -@cindex Mac keyboard coding -@vindex mac-command-key-is-meta -@vindex mac-keyboard-text-encoding +@section Keyboard and Mouse Input on Mac +@cindex Meta (Mac OS) +@cindex keyboard coding (Mac OS) - On the Mac, Emacs can use either the @key{option} key or the +@vindex mac-command-key-is-meta + On Mac, Emacs can use either the @key{option} key or the @key{command} key as the @key{META} key. If the value of the variable @code{mac-command-key-is-meta} is non-@code{nil} (its default value), -Emacs uses the @key{command} key as the @key{META} key. Otherwise it uses the -@key{option} key as the @key{META} key. +Emacs uses the @key{command} key as the @key{META} key. Otherwise it +uses the @key{option} key as the @key{META} key. Most people should want to use the @key{command} key as the @key{META} key, so that dead-key processing with the @key{option} key will still work. This is -useful for entering non-ASCII Latin characters directly from the Mac +useful for entering non-@acronym{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., + 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) +if its script is either Roman, Japanese, Traditional Chinese, Korean, +Cyrillic, Simplified Chinese, or Central European. Keyboard layouts +based on Unicode may not work properly. 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. - - 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 @code{mac-keyboard-text-encoding} to -@code{kTextEncodingISOLatin1}. Note that 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 @code{mac-keyboard-text-encoding} to -@code{kTextEncodingISOLatin2}. Then let Emacs know that the keyboard -generates Latin-2 codes by typink @kbd{C-x RET k iso-latin-2 RET}. To -make this setting permanent, put this in your @file{.emacs} init file: - -@lisp -(set-keyboard-coding-system 'iso-latin-2) -@end lisp +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 the Mac +@section International Character Set Support on Mac @cindex Mac Roman coding system -@cindex Mac clipboard support - - The Mac uses a non-standard encoding for the upper 128 single-byte -characters. It also deviates from the ISO 2022 standard by using code -points in the range 128-159. The coding system @code{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 @code{mac-roman} coding system. +@cindex clipboard support (Mac OS) - The fontset @code{fontset-mac} is created automatically when Emacs is -run on the Mac by the following expression. It displays characters in -the @code{mac-roman} coding system using 12-point Monaco. + 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. - To insert characters directly in the @code{mac-roman} coding system, -type @kbd{C-x RET k mac-roman RET}, or put this in your @file{.emacs} -init file: - -@lisp -(set-keyboard-coding-system 'mac-roman) -@end lisp - -@noindent -This is useful for editing documents in native Mac encoding. + The fontset @code{fontset-mac} is created automatically when Emacs +is run on Mac, and used by default. It displays as many kinds of +characters as possible using 12-point Monaco as a base font. If you +see some character as a hollow box with this fontset, then it's almost +impossible to display it only by customizing font settings (@pxref{Mac +Font Specs}). You can use input methods provided either by LEIM (@pxref{Input -Methods}) or the Mac OS to enter international characters. +Methods}) or Mac OS to enter international characters. To use the +former, see the International Character Set Support section of the +manual (@pxref{International}). - To use the former, see the International Character Set Support section -of the manual. - - To use input methods provided by the Mac OS, set the keyboard coding -system accordingly using the @kbd{C-x RET k} command -(@code{set-keyboard-coding-system}). For example, for Traditional -Chinese, use @samp{chinese-big5} as keyboard coding system; for -Japanese, use @samp{sjis}, etc. Then select the desired input method in -the keyboard layout pull-down menu. + 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 -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 -@kbd{C-x RET x} (@code{set-selection-coding-system}) or @kbd{C-x RET X} -(@code{set-next-selection-coding-system}) (e.g., for Traditional -Chinese, use @samp{chinese-big5-mac} and for Japanese, -@samp{sjis-mac}). @xref{Specify Coding}, for more details. - +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{Specify 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-path 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 Mac environment variables +@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 - 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}. +@example +/Applications/Emacs.app/Contents/MacOS/Emacs -geometry 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 @@ -156,58 +216,137 @@ string 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 the Mac -@cindex file names under Mac OS +@section Volumes and Directories on Mac +@cindex file names (Mac OS) - The directory structure in the Mac OS is seen by Emacs as + 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. As in Unix, @file{..} -can be used to go up a directory level. +@file{/} will display all volumes on the system. You can use @file{..} +to go up a directory level. - 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, 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}). - Emacs creates the Mac folder @file{:Preferences:Emacs:} in the -@file{System Folder} and uses it as the temporary directory. The Unix -emulation code maps the Unix directory @file{/tmp} to it. 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. + 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 the Mac -@cindex font names under Mac OS +@section Specifying Fonts on Mac +@cindex font names (Mac OS) - Fonts are specified to Emacs on the Mac in the form of a standard X -font name. I.e., + 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 Mac, use a standard X font name: @smallexample --@var{foundry}-@var{family}-@var{weight}-@var{slant}-@var{width}--@var{pixels}-@var{points}-@var{hres}-@var{vres}-@var{spacing}-@var{avewidth}-@var{charset} +-@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 -where the fields refer to foundry, font family, weight, slant, width, -pixels, point size, horizontal resolution, vertical resolution, -spacing, average width, and character set, respectively. Wildcards -are supported as they are on X. +@xref{Font X}. Wildcards are supported as they are on X. - Native Apple fonts in Mac Roman encoding has foundry name @code{apple} + Native Apple fonts in Mac Roman encoding has maker name @code{apple} and charset @code{mac-roman}. For example 12-point Monaco can be -specified by the name @samp{-apple-monaco-*-12-*-mac-roman}. +specified by the name @samp{-apple-monaco-*-12-*-mac-roman}. When +using a particular size of scalable fonts, it must be specified in a +format containing 14 @samp{-}s like +@samp{-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman}. + + You can specify a @code{mac-roman} font for @acronym{ASCII} +characters like + +@lisp +(add-to-list + 'default-frame-alist + '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman")) +@end lisp + +@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 +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. + + Since Emacs as of the current version uses QuickDraw Text routines +for drawing texts, only characters in the charsets listed above can be +displayed with the OS-bundled fonts, even if other applications that +use @acronym{ATSUI} or Cocoa can display variety of characters with +them. + + 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 fonts. The recommended way is +to create a fontset using @code{create-fontset-from-mac-roman-font}: - Native Apple Traditional Chinese, Simplified Chinese, Japanese, and -Korean fonts have charsets @samp{big5-0}, @samp{gb2312-0}, -@samp{jisx0208.1983-sjis}, and @samp{ksc5601-1}, respectively. +@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 @@ -215,19 +354,43 @@ 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 + Emacs uses the QuickDraw text rendering by default. On Mac OS X +10.2 and later, it can be changed so that it uses the Quartz 2D text +rendering (aka CG text rendering) by setting +@code{mac-allow-anti-aliasing} to @code{t}. However, it is reported +to sometimes leave some garbages. @node Mac Functions -@section Mac Specific Lisp Functions -@cindex Lisp functions on the Mac OS +@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-filename-to-unix -@findex unix-filename-to-mac - The function @code{mac-filename-to-unix} takes a Mac file name and -returns the Unix equivalent. The function @code{unix-filename-to-mac} -performs the opposite conversion. They are useful for constructing -AppleScript commands to be passed to @code{do-applescript}. +@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