# HG changeset patch # User Glenn Morris # Date 1189053480 0 # Node ID e5fcc34f547fec9ff994895151d736a9c8edb32b # Parent 22d32094ab61f5540b288dbe9623faa0c95dafec Move to ../doc/emacs/, misc/ diff -r 22d32094ab61 -r e5fcc34f547f man/macos.texi --- a/man/macos.texi Thu Sep 06 04:37:55 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,429 +0,0 @@ -@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