/[emacs]/emacs/man/macos.texi
ViewVC logotype

Diff of /emacs/man/macos.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.21 by ttn, Wed Aug 10 15:14:33 2005 UTC revision 1.22 by mituharu, Wed Sep 21 08:04:18 2005 UTC
# Line 3  Line 3 
3  @c   2005 Free Software Foundation, Inc.  @c   2005 Free Software Foundation, Inc.
4  @c See file emacs.texi for copying conditions.  @c See file emacs.texi for copying conditions.
5  @node Mac OS, MS-DOS, Antinews, Top  @node Mac OS, MS-DOS, Antinews, Top
6  @appendix Emacs and the Mac OS  @appendix Emacs and Mac OS
7  @cindex Mac OS  @cindex Mac OS
8  @cindex Macintosh  @cindex Macintosh
9    
10    Emacs built on Mac OS X supports most of its major features:    This section briefly describes the peculiarities of using Emacs
11  multiple frames, colors, scroll bars, menu bars, use of the mouse,  under Mac OS with native window system support.  For Mac OS X, Emacs
12  fontsets, international characters, input methods, coding systems,  can be built either without window system support, with X11, or with
13  asynchronous and synchronous subprocesses, unexec (@code{dump-emacs}),  Carbon API.  This section only applies to the Carbon build.  For Mac
14  and networking (@code{open-network-stream}).  Support for various  OS Classic, Emacs can be built with or without Carbon API, and this
15  image file formats has not been implemented yet.  section applies to either of them because they run on the native
16    window system.
17    The following features of Emacs are not yet supported on the Mac OS  
18  8 or 9: unexec (@code{dump-emacs}), asynchronous subprocesses    Emacs built on Mac OS X supports most of its major features except
19  (@code{start-process}), and networking (@code{open-network-stream}).  display support of PostScript images.  The following features of Emacs
20  As a result, packages such as Gnus, GUD, and Comint do not work.  are not supported on Mac OS Classic: unexec (@code{dump-emacs}),
21  However, synchronous subprocesses (@code{call-process}) are supported.  asynchronous subprocesses (@code{start-process}), and networking
22  Since external programs to handle commands such as @code{print-buffer}  (@code{open-network-stream}).  As a result, packages such as Gnus,
23  and @code{diff} are not available on Mac OS 8 or 9, they are not  GUD, and Comint do not work.  Synchronous subprocesses
24  supported.  (@code{call-process}) are supported on non-Carbon build, but
25    specially-crafted external programs are needed.  Since external
26    Most of the features that are supported work in the same way as on  programs to handle commands such as @code{print-buffer} and
27  other platforms and are therefore documented in the rest of this  @code{diff} are not available on Mac OS Classic, they are not
28  manual.  This section describes the peculiarities of using Emacs under  supported.  Non-Carbon build on Mac OS Classic does not support some
29  the Mac OS.  features such as file dialogs, drag-and-drop, and Unicode menus.
30    
31  @menu  @menu
32  * Input: Mac Input.                Keyboard input on the Mac.  * Input: Mac Input.                Keyboard and mouse input on Mac.
33  * Intl: Mac International.         International character sets on the Mac.  * Intl: Mac International.         International character sets on Mac.
34  * Env: Mac Environment Variables.  Setting environment variables for Emacs.  * Env: Mac Environment Variables.  Setting environment variables for Emacs.
35  * Directories: Mac Directories.    Volumes and directories on the Mac.  * Directories: Mac Directories.    Volumes and directories on Mac.
36  * Font: Mac Font Specs.            Specifying fonts on the Mac.  * Font: Mac Font Specs.            Specifying fonts on Mac.
37  * Functions: Mac Functions.        Mac-specific Lisp functions.  * Functions: Mac Functions.        Mac-specific Lisp functions.
38  @end menu  @end menu
39    
40  @node Mac Input  @node Mac Input
41  @section Keyboard Input on the Mac  @section Keyboard and Mouse Input on Mac
42  @cindex Meta (Mac OS)  @cindex Meta (Mac OS)
43  @cindex keyboard coding (Mac OS)  @cindex keyboard coding (Mac OS)
 @vindex mac-command-key-is-meta  
 @vindex mac-keyboard-text-encoding  
44    
45    On the Mac, Emacs can use either the @key{option} key or the  @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  @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),  @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  Emacs uses the @key{command} key as the @key{META} key.  Otherwise it
# Line 55  so that dead-key processing with the @ke Line 54  so that dead-key processing with the @ke
54  useful for entering non-@acronym{ASCII} Latin characters directly from the Mac  useful for entering non-@acronym{ASCII} Latin characters directly from the Mac
55  keyboard, for example.  keyboard, for example.
56    
57    Emacs recognizes the setting in the Keyboard control panel and    Emacs recognizes the setting in the Keyboard control panel (Mac OS
58  supports international and alternative keyboard layouts (e.g., Dvorak).  Classic) or the International system preference pane (Mac OS X) and
59  Selecting one of the layouts from the keyboard layout pull-down menu  supports international and alternative keyboard layouts (e.g., Dvorak)
60  will affect how the keys typed on the keyboard are interpreted.  if its script is either Roman, Japanese, Traditional Chinese, Korean,
61    Cyrillic, Simplified Chinese, or Central European.  Keyboard layouts
62    The Mac OS intercepts and handles certain key combinations (e.g.,  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  @key{command}-@key{SPC} for switching input languages).  These will not
70  be passed to Emacs.  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    The Mac keyboard ordinarily generates characters in the Mac Roman  to @code{nil}.
73  encoding.  To use it for entering ISO Latin-1 characters directly, set  
74  the value of the variable @code{mac-keyboard-text-encoding} to  @vindex mac-emulate-three-button-mouse
75  @code{kTextEncodingISOLatin1}.  Note that not all Mac Roman characters    Especially for one-button mice, the multiple button feature can be
76  that can be entered at the keyboard can be converted to ISO Latin-1  emulated by setting @code{mac-emulate-three-button-mouse} to @code{t}
77  characters.  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    To enter ISO Latin-2 characters directly from the Mac keyboard, set  the second (third) button, and that with the @key{command} key is
80  the value of @code{mac-keyboard-text-encoding} to  recognized as the third (second) button.
81  @code{kTextEncodingISOLatin2}.  Then let Emacs know that the keyboard  
82  generates Latin-2 codes, by typing @kbd{C-x @key{RET} k iso-latin-2  @vindex mac-wheel-button-is-mouse-2
83  @key{RET}}.  To make this setting permanent, put this in your    For multi-button mice, the wheel button and the secondary button are
84  @file{.emacs} init file:  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  @lisp  are exchanged.
 (set-keyboard-coding-system 'iso-latin-2)  
 @end lisp  
87    
88  @node Mac International  @node Mac International
89  @section International Character Set Support on the Mac  @section International Character Set Support on Mac
90  @cindex Mac Roman coding system  @cindex Mac Roman coding system
91  @cindex clipboard support (Mac OS)  @cindex clipboard support (Mac OS)
92    
93    The Mac uses a non-standard encoding for the upper 128 single-byte    Mac uses non-standard encodings for the upper 128 single-byte
94  characters.  It also deviates from the ISO 2022 standard by using  characters.  They also deviate from the ISO 2022 standard by using
95  character codes in the range 128-159.  The coding system  character codes in the range 128-159.  The coding systems
96  @code{mac-roman} is used to represent this Mac encoding.  It is used  @code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic}
97  for editing files stored in this native encoding, and for displaying  are used to represent these Mac encodings.
 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.  
98    
99    The fontset @code{fontset-mac} is created automatically when Emacs    The fontset @code{fontset-mac} is created automatically when Emacs
100  is run on the Mac.  It displays characters in the @code{mac-roman}  is run on Mac, and used by default.  It displays as many kinds of
101  coding system using 12-point Monaco.  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    To insert characters directly in the @code{mac-roman} coding system,  impossible to display it only by customizing font settings (@pxref{Mac
104  type @kbd{C-x @key{RET} k mac-roman @key{RET}}, customize the variable  Font Specs}).
 @code{keyboard-coding-system}, or put this in your init file:  
   
 @lisp  
 (set-keyboard-coding-system 'mac-roman)  
 @end lisp  
   
 @noindent  
 This is useful for editing documents in native Mac encoding.  
105    
106    You can use input methods provided either by LEIM (@pxref{Input    You can use input methods provided either by LEIM (@pxref{Input
107  Methods}) or the Mac OS to enter international characters.  Methods}) or Mac OS to enter international characters.  To use the
108    former, see the International Character Set Support section of the
109    To use the former, see the International Character Set Support section  manual (@pxref{International}).
110  of the manual (@pxref{International}).  
111      Emacs on Mac OS automatically changes the value of
112    To use input methods provided by the Mac OS, set the keyboard coding  @code{keyboard-coding-system} according to the current keyboard
113  system accordingly using the @kbd{C-x @key{RET} k} command  layout.  So users don't need to set it manually, and even if set, it
114  (@code{set-keyboard-coding-system}).  For example, for Traditional  will be changed when the keyboard layout change is detected next time.
 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.  
115    
116    The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are    The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are
117  connected as follows: the most recent kill is copied to the clipboard  synchronized by default: you can yank a piece of text and paste it
118  when Emacs is suspended and the contents of the clipboard is inserted  into another Mac application, or cut or copy one in another Mac
119  into the kill ring when Emacs resumes.  The result is that you can yank  application and yank it into a Emacs buffer.  This feature can be
120  a piece of text and paste it into another Mac application, or cut or copy  disabled by setting @code{x-select-enable-clipboard} to @code{nil}.
121  one in another Mac application and yank it into a Emacs buffer.  One can still do copy and paste with another application from the Edit
122    menu.
123    The encoding of text selections must be specified using the commands  
124  @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) or @kbd{C-x    On Mac, the role of the coding system for selection that is set by
125  @key{RET} X} (@code{set-next-selection-coding-system}) (e.g., for  @code{set-selection-coding-system} (@pxref{Specify Coding}) is
126  Traditional Chinese, use @samp{chinese-big5-mac} and for Japanese,  two-fold.  First, it is used as a preferred coding system for the
127  @samp{sjis-mac}).  @xref{Specify Coding}, for more details.  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  @node Mac Environment Variables
177  @section Environment Variables and Command Line Arguments.  @section Environment Variables and Command Line Arguments.
# Line 145  Traditional Chinese, use @samp{chinese-b Line 179  Traditional Chinese, use @samp{chinese-b
179    
180    On Mac OS X, when Emacs is run in a terminal, it inherits the values    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.  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  However, when it is run from the Finder as a GUI application, it only
183  inherits no environment variable values.  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    On Mac OS 8 or 9, environment variables and command line arguments  @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  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  129, respectively.  A common environment variable that one may want to
201  set is @samp{HOME}.  set is @samp{HOME}.
# Line 169  string Line 216  string
216  EMACS_UNIBYTE=1  EMACS_UNIBYTE=1
217  @end example  @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  @node Mac Directories
252  @section Volumes and Directories on the Mac  @section Volumes and Directories on Mac
253  @cindex file names (Mac OS)  @cindex file names (Mac OS)
254    
255    The directory structure in the Mac OS is seen by Emacs as    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  @example
260  /@var{volumename}/@var{filename}  /@var{volumename}/@var{filename}
# Line 184  So when Emacs requests a file name, doin Line 264  So when Emacs requests a file name, doin
264  @file{/} will display all volumes on the system.  You can use @file{..}  @file{/} will display all volumes on the system.  You can use @file{..}
265  to go up a directory level.  to go up a directory level.
266    
267    On Mac OS 8 or 9, to access files and folders on the desktop, look    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  in the folder @file{Desktop Folder} in your boot volume (this folder
269  is usually invisible in the Mac @code{Finder}).  is usually invisible in the Mac @code{Finder}).
270    
271    On Mac OS 8 or 9, Emacs creates the Mac folder    On Mac OS Classic, Emacs creates the Mac folder
272  @file{:Preferences:Emacs:} in the @file{System Folder} and uses it as  @file{:Preferences:Emacs:} in the @file{System Folder} and uses it as
273  the temporary directory.  Emacs maps the directory name @file{/tmp/}  the temporary directory.  Emacs maps the directory name @file{/tmp/}
274  to that.  Therefore it is best to avoid naming a volume @file{tmp}.  to that.  Therefore it is best to avoid naming a volume @file{tmp}.
# Line 199  created. Line 279  created.
279    
280    
281  @node Mac Font Specs  @node Mac Font Specs
282  @section Specifying Fonts on the Mac  @section Specifying Fonts on Mac
283  @cindex font names (Mac OS)  @cindex font names (Mac OS)
284    
285    It is rare that you need to specify a font name in Emacs; usually    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  you specify face attributes instead.  But when you do need to specify
287  a font name in Emacs on the Mac, use a standard X font name:  a font name in Emacs on Mac, use a standard X font name:
288    
289  @smallexample  @smallexample
290  -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}  -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
# Line 216  a font name in Emacs on the Mac, use a s Line 296  a font name in Emacs on the Mac, use a s
296    
297    Native Apple fonts in Mac Roman encoding has maker name @code{apple}    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  and charset @code{mac-roman}.  For example 12-point Monaco can be
299  specified by the name @samp{-apple-monaco-*-12-*-mac-roman}.  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    Native Apple Traditional Chinese, Simplified Chinese, Japanese, and    You can specify a @code{mac-roman} font for @acronym{ASCII}
305  Korean fonts have charsets @samp{big5-0}, @samp{gb2312.1980-0},  characters like
306  @samp{jisx0208.1983-sjis}, and @samp{ksc5601.1989-0}, respectively.  
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    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  in the Mac Roman encoding, have foundry, family, and character sets
# Line 228  encoded in the names of their font suitc Line 354  encoded in the names of their font suitc
354  @samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by  @samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by
355  the name @samp{-ETL-fixed-*-iso8859-1}.  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  @node Mac Functions
365  @section Mac-Specific Lisp Functions  @section Mac-Specific Lisp Functions
# Line 246  returns the GNU or Unix equivalent.  The Line 378  returns the GNU or Unix equivalent.  The
378  are useful for constructing AppleScript commands to be passed to  are useful for constructing AppleScript commands to be passed to
379  @code{do-applescript}.  @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  @ignore
395     arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6     arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
396  @end ignore  @end ignore

Legend:
Removed from v.1.21  
changed lines
  Added in v.1.22

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26