Mercurial > emacs

--- /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