(nl): Rename to name_list to avoid ncurses.h clash (bug#86).

[emacs.git] / man / macos.texi

@c This is part of the Emacs manual.
@c Copyright (C) 2000, 2001, 2002, 2003, 2004,
@c   2005, 2006, 2007, 2008 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