annotate doc/misc/ns-emacs.texi @ 98468:bc63ca36bd15

* faces.el (inhibit-frame-set-background-mode): New var. (frame-set-background-mode): Use it to avoid a loop in face-spec-recalc.

\input texinfo @c -*-texinfo-*-

@setfilename ../../info/ns-emacs
@settitle Emacs.app

@dircategory Emacs
@direntry
* NS-Emacs: (ns-emacs).   Emacs.app for GNUstep and MacOS X.
@end direntry

@iftex
@finalout
@end iftex

@copying
This document describes Emacs.app for GNUstep and MacOS X.

Copyright @copyright{} 1994, 1997, 2005, 2006, 2007, 2008 Free Software
Foundation, Inc.

Copyright @copyright{} 2001 Christophe de Dinechin.
Copyright @copyright{} 1997 Christian Limpach.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying


@titlepage
@sp 10
@center @titlefont{Emacs.app}

@center (Version 9.0-rc3, November, 2007)

@sp 2
@center Carl Edman
@sp 2
@center Christian Limpach
@sp 2
@center Scott Bender
@sp 2
@center Christophe de Dinechin
@sp 2
@center Adrian Robert
@sp 2

@end titlepage

@ignore
@menu
* Introduction::                
* Events::                      
* Preferences Panel::
* Preferences::                    
* Tips and Tricks::             
* Thanks::                      
@end menu
@end ignore

@node Top, Introduction, (dir), (dir)
@top Emacs.app

Emacs.app for GNUstep and MacOS X (http://emacs-app.sf.net) is a version of
GNU Emacs which adds support for the GNUstep and MacOS X systems via the
OpenStep APIs (referred to as "Cocoa" under OS X).  For support for
NeXTstep, OpenStep, and Rhapsody systems, try the older "Emacs-on-Aqua",
available at http://emacs-on-aqua.sf.net.

This port leaves most of the core functions of Emacs unchanged and is
fully-compatible with all Emacs Lisp packages, however it has a number of
step-ish features which do not have any equivalent in Emacs's X11 interface.
The design aim was to make it look as similar as possible to an X application
to Emacs Lisp programs and to make it look like a normal GNUstep or MacOS X
application to users.

(From here on out we refer to this port as "Emacs.app", and the systems
supported by this port as "NeXTstep", "NS", or "OpenStep", because saying
GNUstep / MacOS X is too clumsy.  Both systems were derived from the NeXTstep
libraries developed by NeXT, Inc. for its NeXT computer and operating system,
whose APIs were later published as the OpenStep specification.  All classes
and functions in these APIs start with the letters 'NS' for this historical
reason.)

Comments and bug reports relating to the window system interface are welcome.
To report a bug please use the @samp{Help/Report Emacs.app bug...}  menu item.
This sends messages to the maintainer.  (Note, please include your email
address if you don't usually send email from this machine.)

Problems and bugs which do not relate to the NS support (i.e. which can be
reproduced even in a dumb terminal or under the Carbon port or X11) should be
reported through the normal Emacs channels.

Also, please inspect the ``Known Issues'' contained in the README file you may
have received with this distribution or listed at the web site
http://emacs-app.sf.net .

There is also a developer mailing list for Emacs.app,
<emacs-app-dev-@@lists.sourceforge.net>.  Sign up through the project page at
http://emacs-app.sf.net.  A user mailing list will be added in time and if
warranted.


@menu
* Introduction::	What you need to know to use and program.
* Events::              How NS window system events are handled.
* Preferences Panel::   Using the Preferences Panel to customize Emacs.
* Customization::       Customization for Emacs.app.
* Tips and Tricks::     Collected hints from Emacs users
* Thanks::              The people who helped create Emacs.app
@end menu

@node Introduction, Events, Top, Top
@section Introduction

Despite the size and complexity of GNU Emacs, NeXTstep and the NeXTstep
support code, this manual can be kept mercifully short by saying that
everything written in the Emacs and the Emacs Lisp manuals about GNU Emacs
applies equally to this Emacs except as noted here.

@itemize @bullet
@item
The ``right-click'' button (usually the right-hand button on a two-button
mouse) is mapped to Mouse-3, instead of Mouse-2 as earlier versions of
Emacs.app.  This is for compatibility with X versions of emacs.  To get some
of the old behavior back, you can put in your .emacs:

@lisp
(global-set-key [mouse-3] 'mouse-yank-at-click)
@end lisp

The other functionality of mouse-3 in a buffer of extending a selection is
available via shift-click as in other NS applications.  To pop up a context
menu, 

@item
The Alt or Opt key is bound to the traditional emacs "meta" by default, while
the NS "command" key is bound to 'super', for which a set of keybindings are
set to mimic other NeXTstep applications.  (See @ref{Events}.)  You can change
either of these bindings using the preferences panel (see @ref{Preferences
Panel}).

@item
The standard NeXTstep font and color panels are accessible through the Windows
menu, or through the standard Cmd-t and Cmd-C.  These are easier to use than
Emacs's own methods for setting these items.  To use the color panel, drag
from it to an emacs frame.  The foreground (or background, if shift is held
down) of the face at that point will be changed.  To finalize settings for
either color or font, choose 'Save Options' from under the Options menu.  To
discard these settings, create a new frame and close the altered one.

@item
Opening files / directories and 'Save Buffer As' operated from the menus use
the standard NS file panels.  Likewise if you use Cmd-o or Cmd-S.  However,
if you use the regular Emacs key combinations Ctrl-x,Ctrl-f and Ctrl-x,w for
these functions, the normal Emacs mode of typing filenames into the minibuffer
is used.

@item
On GNUstep, in an X-windows environment you need to use Cmd-c instead of one
of the Ctrl-w or Meta-w commands to transfer text to the X primary selection.
(Ordinarily the "clipboard" selection is used, for compatibility with more
modern Gnome and KDE programs.)  Likewise, Cmd-y (instead of Ctrl-y) will
yank/paste in the X primary selection instead of the kill-ring / clipboard.

@item
The @code{window-system} variable can now have the value @code{ns} in addition
to, e.g., @code{x} or @code{nil}.  You can use this in your .emacs file:

If you just want to distinguish between cases in which there is a
window system and in which there isn't, this construct is useful.
@lisp
(if window-system
    ...       ;;; evaluate if any window system is running
  ...)        ;;; evaluate only when running on a dumb terminal
@end lisp

For more detailed control, use this.
@lisp
(cond
 ((eq window-system 'ns)         ;;; NS specific instructions
  ...)        
 ((eq window-system 'x)          ;;; X specific instructions
  ...)
 (t      ;;; Instructions for dumb terminal or other window systems
  ...))
@end lisp

@item
Likewise, you can detect whether you are running in emacs-23 or an earlier
version with:

@lisp
   (if (eq emacs-major-version '23) <emacs-23 code> <emacs-22- code>)
@end lisp

@item
Most NS specific functions begin with 'ns-'.  Do "C-h f ns-[TAB]" to list
these.  Many of these replace equivalent 'x-' functions, while others perform
uniquely NS things, such as Service invocation.

@item
There are also NS variables beginning with 'ns-', however in most cases users
need not pay attention to them since the customizability they provide is also
available through the defaults system and preferences panel (see
@ref{Preferences Panel} and @ref{Customization}).

@item
When Emacs is called by a name which ends in @file{-nw} it will always
start in terminal mode.  For example, a user who needs a terminal only
emacs would create a symbolic link from @file{emacs} to @file{emacs-nw}.
When he launches @file{emacs-nw} from the command line, the window
system will never be involved.  (Note, as of rc2, terminal mode is still not
working under OS X.)
@end itemize

@node Events, Preferences Panel, Introduction, Top
@section Events

Under Emacs.app the NeXTstep command key works as the @dfn{super} modifier
key.  In principle users can bind their command keys to whatever function they
want, but to make the transition for NS users easier the default NS startup
files bind the most commonly used NS command keys to work just like they do in
most other NS applications.  Some are shown in the menus.  Choose "List
Keybindings" from the Help menu and scroll down to the keys labeled starting
with 's-' to see all of them.

NS applications receive a number of special events which have no X equivalent.
These are sent as specially defined ``keys'' (which don't correspond to any
keyboard stroke combination).  Under Emacs these ``key'' events can be bound
to functions just like ordinary keystrokes.  Here is a list of these events.

@table @code
@item ns-open-file
This event occurs when another NeXTstep application requests that Emacs
open a file.  A typical reason for this would be a user double-clicking
a file in the Finder.  When this event is registered the
name of the file to open is found in the variable @code{ns-input-file}.

The behaviour of the default binding is controlled by the variable
@code{ns-pop-up-frames}.  It's default value @code{'fresh} causes Emacs
to open the new file in the selected frame if the selected buffer is a
scratch buffer.  Otherwise Emacs opens a new frame and displays the file
in that.

To always get a new frame one would change @code{ns-pop-up-frames} to
@code{t}.  To get the opposite behaviour (i.e. always putting the file into
the selected frame), change @code{ns-pop-up-frames} to @code{nil}.

@item ns-open-temp-file
This event occurs when another application requests that Emacs open a
temporary file.  The file name is again in @code{ns-input-file}.  By
default this is handled by just generating a @code{ns-open-file} event
(which then causes the @code{ns-open-file} function to be called
whatever that may be).

@lisp
(define-key global-map [ns-open-temp-file] [ns-open-file])
@end lisp

@item ns-open-file-line
Some applications (like e.g. ProjectBuilder or gdb) request not only a
particular file, but also a particular line or sequence of lines in the
file.  The file name is in @code{ns-input-file}, and
@code{ns-input-line} is either the line or a cons cell the car of which
contains the beginning line and the cdr of which the ending line.

@lisp
(define-key global-map [ns-open-file-line] 'ns-open-file-select-line)
@end lisp

@item ns-drag-file
When a user drags files from another application into an Emacs frame
this event is triggered.  Here @code{ns-input-file} is a list of all
dragged files.  The default binding inserts all the dragged files into
the current buffer.

@lisp
(define-key global-map [ns-drag-file] 'ns-insert-files)
@end lisp

@item ns-drag-color
When a user drags a color from the color well (or some other source)
Emacs sees this event and @code{ns-input-color} contains the name of the
dragged color.  The default bindings alter the foreground color of the
area the color was dragged onto (or background color if the color was
shift dragged).

@lisp
(define-key global-map [ns-drag-color]  
            'ns-set-foreground-at-mouse)
(define-key global-map [S-ns-drag-color]
            'ns-set-background-at-mouse)
@end lisp

@item ns-change-font
Emacs.app allows the user to open a standard NS font panel (by default that
function is bound to @kbd{Cmd-t}).  When the user selects a font in that
panel this event occurs.  @code{ns-input-font} will contain the name of
the selected font and @code{ns-input-fontsize} is its size.  The
default binding causes Emacs to adjust the font of the selected frame.

@lisp
(define-key global-map [ns-change-font] 'ns-respond-to-changefont)
@end lisp

@item ns-power-off
Finally when the user logs out and Emacs is still running it receives
this event so that it has a chance to save its files before it dies.

@lisp
(define-key global-map [ns-power-off]
  '(lambda () (interactive) (save-buffers-kill-emacs t)))
@end lisp

@end table

Emacs.app also allows users to make use of NeXTstep services programatically,
in addition to via the Services menu.  On the most basic level programmers can
use the @code{ns-perform-service} to pass arbitrary strings to arbitrary
services and receive the results back.  However convenience functions are
automatically provided for all services so there should be no need to use
this.  These function names begin with 'ns-service-', and they will either
operate on marked text (replacing it with the result) or take a string
argument and return the result as a string.  Type "M-x ns-service-[TAB][TAB]"
to see those currently defined.  Note that Emacs may require a restart to
access newly available services.


@node Preferences Panel, Customization, Events, Top
@section Preferences Panel

The Preferences Panel can be used to set or change some of the settings for
Emacs such as the text appearance, cursor settings, and key bindings.

To save any settings changed through the Preferences Panel, hit OK;
this has the same effect as if you had explicitly chosen Help > Save
Preferences.

To restore Emacs to use its default settings click Reset to Defaults from
the Preferences Panel.

Additional GNUstep/OS X preferences may be set from the command line using
the @command{defaults} command. (See @ref{Customization}.)


@section Text Rendering Preferences

Font and color settings can be set using the standard NeXTstep font
and color panels.

@itemize @bullet
@item
To set the default font used by Emacs click the Default Font... button
to launch the Font Panel.  Click on a frame before selecting the font
family, typeface, and size of the default font from the Font Panel.

Note that the default font will not be changed if a frame hasn't been
selected first.

@item
To set the default foreground or background color click the
Colors... button to launch the Color Panel.  Choose the color you want
using any of the color models (color wheel, sliders, palette, image,
or crayons) available from the Colors toolbar.  To apply the color
drag a swatch from the color bar at the top of the panel to text on
an Emacs frame.  Holding down shift will change the background color
instead of the foreground.

@item
To use antialiased text check the Smooth Fonts option.  Lighter font
smoothing can be achieved by checking the Use Quickdraw (lighter)
smoothing option.

@item
To change the line height that text is displayed at drag the Expand
Line Spacing slider.  When the slider is set to 0.0 Emacs will use the
same line height as other Mac OS X applications.  To increase the line
height (and decrease the number of lines that can be displayed on the
screen) drag the slider towards 1.0.  To decrease the line height
(increases the number of lines that can be displayed) drag the slider
towards -1.0.

After the line spacing setting has been changed Emacs must be restarted
to take account of the change.

@end itemize

@section Display Preferences

The Display Preferences can be used to change the appearance of the
default cursor used by Emacs.

@itemize @bullet
@item
The Cursor Type radio buttons can be used to select the style used for the cursor:

@itemize
@item
Box - the cursor is displayed as a box
@item
Underscore - the cursor is displayed as a horizontal bar
@item
Bar - the cursor is displayed as a vertical bar
@item
Hollow - the cursor is displayed as a box with an outline but no fill
@end itemize

@item
Use the Cursor Blink Rate slider to set the frequency at which the cursor blinks.

@item
Check the Use System Highlight Color option to use the system default
color for highlighted text.

@end itemize

@section Modifier Interpretation Preferences

The Modifier Preferences can be used to change the behaviour of the
Alt/Opt and Command keys.  By default the Alt or Opt key is bound to
the Emacs 'Meta' key, and the Command key is bound to 'super' which
allows the Command key to function in a way similar to other
NeXTstep/OS X applications.

@itemize @bullet
@item
To re-bind the Alt or Opt key select a keybinding from the Alt/Opt Key
combo box.
@item
To re-bind the Command key select a keybinding from the Command Key
combo box.
@end itemize


@node Customization, Tips and Tricks, Preferences Panel, Top
@section Customization

Under X, resources are used to customize the behavior of Emacs to the
needs of the user.  These resources are queried programmatically with
the @code{x-get-resource} function.  Under NS defaults fulfill a
similar function.  They can be read using the @code{ns-get-resource}
function.  Calls to @code{x-get-resource} are automatically mapped to
@code{ns-get-resource}.  From the command line, the command
`@code{defaults read org.gnu.Emacs}' will show these resources as of
last Emacs quit, and individual resources can be read/written by
commands like `@code{defaults read Emacs Foo}' and `@code{defaults
write Emacs Foo barvalue}'.

Calling the function @code{ns-save-preferences} in lisp, or selecting ``Save
Options'' from the 'Options' menu will automatically write out the defaults
corresponding to the selected window.

In addition, it is also possible to set many of the following customizations
by setting the @code{default-frame-alist} in the @file{~/.emacs} file.

Many of the preferences relating specifically to the NS windowing system (font
rendering, cursor type, etc.) can be set using a @ref{Preferences Panel}
accessed in the standard fashion from the menubar or Cmd-,.  It is important
to note that when you hit 'OK' on this panel, @emph{all} NS settings are saved
(including font and colors) just as if you had called
@code{ns-save-preferences}.

Note that if you use the 'Default Font' button on the Preferences panel, you
must click on a frame before selecting a font, otherwise nothing will happen.
If you pop up the color panel, you must drag colors to a frame for them to
have an effect.  (Remember to hold down 'shift' to change background instead
of foreground.)

This is a listing of some of the more useful defaults (and their default
values).  Several of these defaults accept the names of colors as values.  For
a list of all available colors pull up the color panel and look at the color
list called ``Emacs''.  Emacs also accepts color specifications of the form
@samp{ARGBaarrggbb} where @var{aa}, @var{rr}, @var{gg}, and @var{bb} are two
hexadecimal digits describing the alpha, red, green, and blue content of the
color respectively.  @samp{HSBhhssbb}, @samp{CMYKccmmyykk} and
@samp{GRAYgg} are the equivalents in @samp{HSB}, @samp{CMYK} and gray
scales.  (For HSB, @samp{AHSBaahhssbb} is also accepted.)

@table @samp
@item InternalBorderWidth
Width in pixels of the internal border of the NS frame.  This acts to separate
the text area of the window from the fringes, scrollbars, and/or edges.

@example
defaults write Emacs InternalBorderWidth 2
@end example

@item VerticalScrollBars
@samp{YES} or @samp{NO} to enable or disable scroll bars, @samp{left} or
@samp{right} to explicitly set the side.

@example
defaults write Emacs VerticalScrollBars YES
@end example

@item Font
Name of the default font to be used for new frames (which can be overriden by
various faces).  If this font is not set, Emacs.app will use the system
wide fixed pitch font.  For most users the system fixed pitch font will be
@samp{Monaco} which doesn't have any bold or italic versions.  (Italic will be
synthesized.)

@item FontSize
Size of the font to be used for new frames.  If not set Emacs for NS will use
the default size of the system wide fixed pitch font.

@item Foreground
The default foreground (text) color for new frames.

@example
defaults write Emacs Foreground "Black"
@end example

@item Background
The default background color for new frames.

@example
defaults write Emacs Background "White"
@end example

@item Height
Height in rows of the default window.

@example
defaults write Emacs Height 48
@end example

@item Width
Width in columns of the default window.

@example
defaults write Emacs Width 80
@end example

@item CursorType
Name of the default cursor type for Emacs.  Allowed values are
@samp{box}, @samp{hollow}, @samp{underscore}, @samp{bar},  @samp{line} and @samp{no}.

@example
defaults write Emacs CursorType box
@end example

@item CursorBlinkRate
Users who want their cursor to blink can set the rate (in seconds) with
this defaults write.  Setting it to @samp{NO} disables cursor blinking.

@example
defaults write Emacs CursorBlinkRate NO
@end example

@item CursorColor
Name of the default cursor color for Emacs.  Of a particular use for this
setting is the @samp{Highlight} "color".  When it is the cursor color,
Emacs will draw the cursor using the standard NS highlighting operator.

@example
defaults write Emacs CursorColor Highlight
@end example

@item Top
Distance in pixels from the top of the screen of the upper left corner
of the default window.

@example
defaults write Emacs Top 100
@end example

@item Left
Distance in pixels from the left edge of the screen to the upper left
corner of the default window.

@example
defaults write Emacs Left 100
@end example

@item HideOnAutoLaunch
@samp{YES} or @samp{NO} to determine whether Emacs will hide itself when
autolaunched from the dock.

@example
defaults write Emacs HideOnAutoLaunch NO
@end example

@item ExpandSpace
This lets you expand or shrink the line height used for displaying text.  When
this is set to 0.0, display should look like other NS apps.  If you set it
higher than 0, Emacs will spread the text lines apart, less than 0, compress
them together.  (With settings below zero parts of characters may be chopped
off in certain fonts.)  When using the @ref{Preferences Panel}, this is
controlled by a slider.  You must OK the panel and then restart Emacs.app for
this default to take effect.

When setting this using @code{"defaults write"}, you can either set a floating
point value, or @samp{YES}, which is equivalent 0.5, or @samp{NO}, which is
equivalent to 0.0.

@example
defaults write Emacs ExpandSpace -0.125
@end example

@item GSFontAntiAlias
This turns antialiasing on and off on.  Note that, on OS X, even if
antialiasing is on, Emacs will not antialias text of a size below the system
preference setting.

@example
defaults write Emacs GSFontAntiAlias NO
@end example

@item UseQuickdrawSmoothing
On OS X 10.3 and higher, this will render fonts using Quickdraw antialiasing,
which is less heavy than the Quartz antialiasing used by default.  Whether
this is on or off, the system font size threshold for antialiasing (see above)
is respected.

@example
defaults write Emacs UseQuickdrawSmoothing YES
@end example

@item AlternateModifier
This allows you to set the effect of the Alt or Opt key.  The default is
@samp{meta}, meaning to use as the Emacs 'meta' key.  You can also set this to
@samp{command}, @samp{hyper}, @samp{alt}, or @samp{none}.  The last is useful
for Continental users who normally use this key to enter accented and other
special characters.

@example
defaults write Emacs AlternateModifier "none"
@end example

@item CommandModifier
This allows you to set the effect of the Command key.  The default is
@samp{super}, which is used in a set of keybindings such as @code{s-o} for
``open file'' and @code{s-z} for ``undo'' that are similar to other NeXTstep
applications.  On the other hand, some people who use the Alt/Opt key for
accent entry like to set this to @samp{meta} so they still have easy access to
Emacs functionality bound to meta keys.  You can also set this, like Alt/Opt,
to @samp{hyper} or @samp{alt}, though there are no bindings to combinations
using these keys by default.  The @samp{none} option is not available for the
Command key.

@example
defaults write Emacs CommandModifier "meta"
@end example

@item fooFrame
Position and size to use for the frame named @var{foo} when it is
created.  The position and size have to be specified as a space
separated list: @samp{top}, @samp{left}, @samp{height} and
@samp{width}. @samp{top} and @samp{left} are expressed in pixels,
@samp{height} is given in rows and @samp{width} is given in columns.
Named frames can be created by e.g. @code{(make-frame '((name
. "FOO")))}.

@example
defaults write Emacs TestFrame "100 200 30 70"
@end example

Another default previouly used by many Emacs users is this.

@example
defaults write Workspace DefaultOpenApp Emacs
@end example

It caused the NeXTstep Workspace to open files without a registered extension
in Emacs instead of as usual Edit.  For this default to work, Emacs needed to
be in the application search path of the Workspace (which usually includes
@file{~/Applications} and @file{~/Applications}).  If anyone knows the current
way to do this under OS X please contact the authors.

@end table

@node Tips and Tricks, Thanks, Customization, Top
@section Tips and Tricks

Emacs is an extremely customizable editor.  You can make it conform to
virtually any conceivable user idiosyncrasy (and some which are not) by adding
a few well-chosen lines of emacs lisp to your @file{~/.emacs}.  Unfortunately
even many experienced C developers are unfamiliar with Emacs Lisp.  For that
reason many Emacs.app defaults have been chosen to make it behave as similar
to TextEdit as possible.  But there are some customizations which a majority
of users probably would hate as much as a minority would love them.  This
section contains a cookbook of such customizations.  New contributions by
Emacs users are very welcome.

@menu
* Grabbing environment variables::  
* Miscellaneous useful variables::  
* Color adjustments::           
* Evaling in the minibuffer::   
* Highlighting matching parentheses::  
* Dealing with X specific packages::  
* Rebinding the numeric keypad::  
* Improving C mode::            
* Custom menu items::           
* Single line scrolling::       
* Open files by dragging to an Emacs window:: 
@ignore
* Extended font customization::  
@end ignore
@end menu

@node Grabbing environment variables, Miscellaneous useful variables, Tips and Tricks, Tips and Tricks
@subsection Grabbing environment variables

Many programs which may run under Emacs like latex or man depend on the
settings of environment variables.  If Emacs is launched from the shell, it
will automatically inherit these environment variables and its subprocesses
will inherit them from it.  But if Emacs.app is launched from the Finder it
is not a descendant of any shell, so its environment variables haven't been
set which often causes the subprocesses it launches to behave differently than
they would when launched from the shell.

To solve this problem for Emacs.app, there are two solutions.  First is to
run, from the command line:

@example
.../Emacs.app/Contents/MacOS/bin/mac-fix-env
@end example

This will pick up your environment settings and save them into a special file
@file{~/.MacOSX/environment.plist}, which the desktop environment will use to
set the environment for all launched applications.  The drawback of this
method is it needs to be run again whenever something changes.

The other approach is to use the @code{ns-grabenv} command inside Emacs.  This
function will run a subshell and copy its environment variables into Emacs.

Adding this line to your @file{~/.emacs} will grab the csh environment
whenever emacs runs under a window system.

@lisp
(if window-system (ns-grabenv))
@end lisp

If you have a different shell you will have to give @code{ns-grabenv} some
arguments.  For zsh you would do this.

@lisp
(if window-system (ns-grabenv "/usr/bin/zsh"
                           "source /etc/zshenv"
                           "source ~/.zshenv"))
@end lisp

The reason that @code{ns-grabenv} is not done by default is that it adds up
to a second or two to the Emacs startup time.

@node Miscellaneous useful variables, Color adjustments, Grabbing environment variables, Tips and Tricks
@subsection Miscellaneous useful variables

This section describes a few variables you might want to set in your
@file{~/.emacs} each of which doesn't warrant its own section.

There is a conflict between the way the region behaved in emacs in the
pre-GUI days and the way GUI users expect the selection to work.  By
default that conflict is resolved by having the former adopt the
behaviour of the latter which most people prefer.  However if you are a
die-hard emacs user you may prefer things the other way around and add
this line to your @file{~/.emacs}.  Experiment with both settings.

@lisp
(setq transient-mark-mode nil)
@end lisp

When you try to move beyond the end of a file Emacs used to add newlines as
needed, however from Emacs-21 on, this was no longer done.  If you prefer the
old behavior, this line in your @file{~/.emacs} will restore it.

@lisp
(setq next-line-add-newlines t)
@end lisp

By default when you kill a line with text on it, only the text is
removed while the line itself remains.  You have to kill twice to really
get rid of the whole line.  When this variable is set and you kill a
line while at the beginning of the line it will go at once.

@lisp
(setq kill-whole-line t)
@end lisp

Annoyed by the Emacs startup message ?  Add this and you start with a
tabula rasa.

@lisp
(setq inhibit-startup-message t)
@end lisp

@node Color adjustments, Evaling in the minibuffer, Miscellaneous useful variables, Tips and Tricks
@subsection Color adjustments

A non-elisp hint: The easiest way to adjust your emacs color scheme is to
bring up a color panel (with @key{Cmd-C}) and drag the color you want over the
emacs face you want to change.  Normal dragging will alter the foreground
color.  Shift dragging will alter the background color.  To make the changes
permanent select the "Save Options" item in the "Options" menu, or run
@code{ns-save-preferences}.  Useful in this context is the listing of all
faces obtained by @key{M-x} @code{list-faces-display}.

@node Evaling in the minibuffer, Highlighting matching parentheses, Color adjustments, Tips and Tricks
@subsection Evaling in the minibuffer

Often you (at least if you are an elisp hacker) want to quickly evaluate
an elisp expression.  To accomodate this desire Emacs provides the
@code{eval-expression} command bound to @key{M-:}.  By default it is
disabled to protect novice users from themselves.  These commands
re-enable it and turn on an extremely powerful completion facility.

@lisp
(put 'eval-expression 'disabled nil)

(define-key read-expression-map "\t" 'lisp-complete-symbol)
@end lisp

@node Highlighting matching parentheses, Dealing with X specific packages, Evaling in the minibuffer, Tips and Tricks
@subsection Highlighting matching parentheses

I doubt that there is anybody who doesn't use this already, but just in
case:

@lisp
(show-paren-mode 't)
@end lisp

In Emacs.app this is currently enhanced by use of the @code{mic-paren} package
from http://www.docs.uu.se/~mic/emacs.html.

@node Dealing with X specific packages, Rebinding the numeric keypad, Highlighting matching parentheses, Tips and Tricks
@subsection Dealing with X specific packages

Some emacs lisp packages explicitly call X specific functions instead of
calling generic functions which call the NS or X versions as appropriate.
Typically such packages will result in error messages like @samp{Symbol's
function definition is void: x-foo-bar}.  The proper way of dealing with this
is to have the author fix the code to call the generic functions.  Generally
all that requires is removing the @samp{x-} prefix from all function calls.

However, sometimes that is not possible, or it may be a package internal to
emacs itself.  In this case please report a bug to the Emacs.app maintainers
(not the main GNU emacs maintainers).

A related problem is font names.  For historical reasons, Emacs assumes all
font names are given ``X style'', as in ``-adobe-courier-....-iso8859-1''.
Emacs.app tries to work around this as well as possible, and the best thing to
do is never rely on functions to set font names yourself but to always use the
font panel.

@node Rebinding the numeric keypad, Improving C mode, Dealing with X specific packages, Tips and Tricks
@subsection Rebinding the numeric keypad

By default in Emacs the numeric keypad keys are bound to the same
characters they are in all other NS applications.  But it is easy to
change these bindings to commands many will find more useful.  As an
example here is the code which rebinds the numeric keypad for me.

@lisp
(global-set-key [kp-0] 'other-window)
(global-set-key [kp-1] 'end-of-buffer)
(global-set-key [kp-2] [down])
(global-set-key [kp-3] 'scroll-up)
(global-set-key [kp-4] [left])
(global-set-key [kp-5] 'set-mark-command)
(global-set-key [kp-6] [right])
(global-set-key [kp-7] 'beginning-of-buffer)
(global-set-key [kp-8] [up])
(global-set-key [kp-9] 'scroll-down)
(global-set-key [kp-decimal] 'yank)
(global-set-key [kp-enter] 'set-mark-command)
(global-set-key [kp-add] 'copy-region-as-kill)
(global-set-key [kp-subtract] 'kill-region)
@end lisp

On machines with function keys they can be bound as well.  This for example
would bind @key{F12} to run gnus.

@lisp
(global-set-key [f12] 'gnus)
@end lisp

@node Improving C mode, Custom menu items, Rebinding the numeric keypad, Tips and Tricks
@subsection Improving C mode

That underscores are considered to break words in C mode has been driving me
insane for a long time.  This line fixes the problem.

@lisp
(modify-syntax-entry ?_ "w" c-mode-syntax-table)
@end lisp

@node Custom menu items, Single line scrolling, Improving C mode, Tips and Tricks
@subsection Custom menu items

The tools menu is intended for customization.  Adding items to it is
relatively painless as this example illustrates.

@lisp
(define-key global-map [menu-bar tools www] '("WWW" . w3-use-hotlist))
@end lisp

@node Single line scrolling, Open files by dragging to an Emacs window, Custom menu items, Tips and Tricks
@subsection Single line scrolling

The meta-arrow keys will perform single-line scrolling in Emacs
just like they did in the old NeXT/OpenStep Stuart.app.

@node Open files by dragging to an Emacs window, , Single line scrolling, Tips and Tricks
@subsection Open files by dragging to an Emacs window

The default behaviour when a user drags files from another application
into an Emacs frame is to insert the contents of all the dragged files
into the current buffer.  To remap the @code{ns-drag-file} event to
open the dragged files in the current frame use the following line:

@lisp
(define-key global-map [ns-drag-file] 'ns-find-file)
@end lisp

@ignore
@node Extended font customization,  , Single line scrolling, Tips and Tricks
@subsection Extended font customization

By default Emacs tries to guess the right font when you ask for a bold,
italic or bold-italic face.  Unfortunately this fails sometimes, for
example Emacs won't guess that it should use @samp{Courier-Bold} as the
font for the bold face of @samp{Ohlfs}.  As an example here is the code
which sets up @samp{Courier-Bold}, @samp{Courier-Oblique} and
@samp{Courier-BoldOblique} as the fonts to be used with @samp{Ohlfs}.

@lisp
(setq ns-convert-font-trait-alist
      '(("Ohlfs" "Courier-Bold" "Courier-Oblique"
         "Courier-BoldOblique")))
@end lisp

You will still have to set the @samp{DefaultFont}, @samp{BoldFont},
@samp{ItalicFont} and @samp{Bold-ItalicFont} defaults as Emacs
initializes the default faces before it reads your @file{~/.emacs}.
Also Emacs initializes @code{ns-convert-font-trait-alist} from these
defaults so that normally it's sufficient to set these defaults to get
correct faces.

@example
defaults write Emacs DefaultFont Ohlfs
defaults write Emacs BoldFont Courier-Bold
defaults write Emacs ItalicFont Courier-Oblique
defaults write Emacs Bold-ItalicFont Courier-BoldOblique
@end example
@end ignore


@node Thanks,  , Tips and Tricks, Top
@section Thanks
A signficant number of people have been involved in the creation of Emacs.app.
Carl Edman <cedman@@lynx.ps.uci.edu> created and maintained Emacs up to
version 4.1 and it's reasonable to say that without his work, Emacs.app
wouldn't exist.  Michael Brouwer <michael@@thi.nl> wrote the original version
(up to and including version 3.x) and was a constant contributor to Emacs.app
version 4 and above.  Christian Limpach <chris@@nice.ch> took over maintenance
and updating at version 4.2, and made substantial contributions in a number of
areas.  Scott Bender <sbender@@harmony-ds.com> ported the code to OpenStep and
Rhapsody for version 6.0.  Christophe de Dinechin <ddd@@cup.hp.com> ported the
code to MacOS X for version 7.0 and moved the code base to SourceForge.  Leigh
Smith <leigh@@leighsmith.com> maintained the SourceForge project for a period.
Adrian Robert <arobert@@cogsci.ucsd.edu> ported the code to GNUstep
(http://gnustep.org), updated it for post-emacs-20, and maintains it for the
present.

Also a number of others have contributed code.  Steve Nygard
<nygard@@telusplanet.net> got emacs to dump under OpenStep.  The font panel
code was Andrew Athan's <athan@@object.com> work.  Joe Reiss
<jreiss@@magnus.acs.ohio-state.edu> both created the beautiful icons you see
and wrote the popup menu and dialog box code as well as much else.

Finally, suggestions from Darcy Brockbank, Timothy Bissell, Scott Byer, David
Griffiths, Scott Hess, Eberhard Mandler, John C. Randolph, and Bradley Taylor
all helped things along at one point or another.  Axel Seibert
<seiberta@@informatik.tu-muenchen.de> and Paul J. Sanchez
<paul@@whimsy.umsl.edu> offered their time and machines to make a binary
release possible.

The GNUstep port was made possible through the assistance of Adam Fedor, Fred
Kiefer, M. Uli Klusterer, Alexander Malmberg, and Jonas Matton.  Gürkan Sengün
made it accessible to a wider community.

Riccardo Mottola helped with compatibility with MacOS versions 10.1 and 10.2,
and GNUstep on platforms other than Linux.

Peter Dyballa kept things honest with multilingual support.  Rahul Abrol, Adam
Ratcliffe, David M. Cooke, and Carsten Bormann provided various small patches.

Then there were a number of people who kept up the constant supply of bug
reports, suggested features and praise (which is the main fuel which the
development of a project like this runs) and so helped ensure that this
program is as bug free (hah !)  and feature rich as you see it today.  First
among them were Hardy Mayer <hardy@@golem.ps.uci.edu>, Gisli Ottarsson
<gisli@@timoshenko.eecs.umich.edu>, Anthony Heading <ajrh@@signal.dra.hmg.gb>,
David Bau <bau@@cs.cornell.edu>, Jamie Zawinski <jwz@@lucid.com>, Martin
Moncrieffe <moncrief@@mayo.edu>, Simson L. Garfinkel
<simsong@@next.cambridge.ma.us>, Richard Stallman <rms@@gnu.ai.mit.edu>,
Stephen Anderson <anderson@@sapir.cog.jhu.edu>, Ivo Welch
<ivo@@next.agsm.ucla.edu>, Magnus Nordborg <magnus@@fisher.Stanford.EDU>, Tom
Epperly <epperly@@valeron.che.wisc.edu>, Andreas Koenig
<k@@franz.ww.tu-berlin.de>, Yves Arrouye <Yves.Arrouye@@imag.fr>, Anil
Somayaji <soma@@hotspur.mit.edu>, Gregor Hoffleit
<flight@@mathi.uni-heidelberg.DE> and doubtlessly many more.

Finally, let us also thank those few hundred other people on the mailing list
from whom we didn't hear much, but the presence of which assured us that maybe
this project was actually worth doing.
@bye

@ignore
   arch-tag: 286bdf18-ccfb-48b2-b730-994771de6bdd
@end ignore