Commit | Line | Data |
---|---|---|
edfda783 AR |
1 | \input texinfo @c -*-texinfo-*- |
2 | ||
568beaa2 | 3 | @setfilename ../../info/ns-emacs |
edfda783 AR |
4 | @settitle Emacs.app |
5 | ||
568beaa2 AS |
6 | @dircategory Emacs |
7 | @direntry | |
8 | * NS-Emacs: (ns-emacs). Emacs.app for GNUstep and MacOS X. | |
9 | @end direntry | |
10 | ||
edfda783 AR |
11 | @iftex |
12 | @finalout | |
13 | @end iftex | |
14 | ||
767a4d92 GM |
15 | @copying |
16 | This document describes Emacs.app for GNUstep and MacOS X. | |
17 | ||
18 | Copyright @copyright{} 1994, 1997, 2005, 2006, 2007, 2008 Free Software | |
19 | Foundation, Inc. | |
20 | ||
21 | Copyright @copyright{} 2001 Christophe de Dinechin. | |
22 | Copyright @copyright{} 1997 Christian Limpach. | |
23 | ||
24 | @quotation | |
25 | Permission is granted to copy, distribute and/or modify this document | |
26 | under the terms of the GNU Free Documentation License, Version 1.2 or | |
27 | any later version published by the Free Software Foundation; with no | |
28 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', | |
29 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
30 | is included in the section entitled ``GNU Free Documentation License''. | |
31 | ||
32 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
33 | modify this GNU manual. Buying copies from the FSF supports it in | |
34 | developing GNU and promoting software freedom.'' | |
35 | @end quotation | |
36 | @end copying | |
37 | ||
38 | ||
edfda783 AR |
39 | @titlepage |
40 | @sp 10 | |
41 | @center @titlefont{Emacs.app} | |
42 | ||
2f45a8ed | 43 | @center (Version 9.0-rc3, November, 2007) |
edfda783 AR |
44 | |
45 | @sp 2 | |
46 | @center Carl Edman | |
47 | @sp 2 | |
48 | @center Christian Limpach | |
49 | @sp 2 | |
50 | @center Scott Bender | |
51 | @sp 2 | |
52 | @center Christophe de Dinechin | |
53 | @sp 2 | |
54 | @center Adrian Robert | |
55 | @sp 2 | |
56 | ||
57 | @end titlepage | |
58 | ||
edfda783 AR |
59 | @ignore |
60 | @menu | |
61 | * Introduction:: | |
62 | * Events:: | |
63 | * Preferences Panel:: | |
64 | * Preferences:: | |
65 | * Tips and Tricks:: | |
66 | * Thanks:: | |
67 | @end menu | |
68 | @end ignore | |
69 | ||
70 | @node Top, Introduction, (dir), (dir) | |
71 | @top Emacs.app | |
72 | ||
73 | Emacs.app for GNUstep and MacOS X (http://emacs-app.sf.net) is a version of | |
767a4d92 GM |
74 | GNU Emacs which adds support for the GNUstep and MacOS X systems via the |
75 | OpenStep APIs (referred to as "Cocoa" under OS X). For support for | |
76 | NeXTstep, OpenStep, and Rhapsody systems, try the older "Emacs-on-Aqua", | |
edfda783 AR |
77 | available at http://emacs-on-aqua.sf.net. |
78 | ||
79 | This port leaves most of the core functions of Emacs unchanged and is | |
80 | fully-compatible with all Emacs Lisp packages, however it has a number of | |
81 | step-ish features which do not have any equivalent in Emacs's X11 interface. | |
82 | The design aim was to make it look as similar as possible to an X application | |
83 | to Emacs Lisp programs and to make it look like a normal GNUstep or MacOS X | |
84 | application to users. | |
85 | ||
86 | (From here on out we refer to this port as "Emacs.app", and the systems | |
87 | supported by this port as "NeXTstep", "NS", or "OpenStep", because saying | |
88 | GNUstep / MacOS X is too clumsy. Both systems were derived from the NeXTstep | |
89 | libraries developed by NeXT, Inc. for its NeXT computer and operating system, | |
90 | whose APIs were later published as the OpenStep specification. All classes | |
91 | and functions in these APIs start with the letters 'NS' for this historical | |
92 | reason.) | |
93 | ||
94 | Comments and bug reports relating to the window system interface are welcome. | |
95 | To report a bug please use the @samp{Help/Report Emacs.app bug...} menu item. | |
96 | This sends messages to the maintainer. (Note, please include your email | |
97 | address if you don't usually send email from this machine.) | |
98 | ||
99 | Problems and bugs which do not relate to the NS support (i.e. which can be | |
100 | reproduced even in a dumb terminal or under the Carbon port or X11) should be | |
101 | reported through the normal Emacs channels. | |
102 | ||
103 | Also, please inspect the ``Known Issues'' contained in the README file you may | |
104 | have received with this distribution or listed at the web site | |
105 | http://emacs-app.sf.net . | |
106 | ||
107 | There is also a developer mailing list for Emacs.app, | |
108 | <emacs-app-dev-@@lists.sourceforge.net>. Sign up through the project page at | |
109 | http://emacs-app.sf.net. A user mailing list will be added in time and if | |
110 | warranted. | |
111 | ||
112 | ||
113 | @menu | |
114 | * Introduction:: What you need to know to use and program. | |
115 | * Events:: How NS window system events are handled. | |
116 | * Preferences Panel:: Using the Preferences Panel to customize Emacs. | |
117 | * Customization:: Customization for Emacs.app. | |
118 | * Tips and Tricks:: Collected hints from Emacs users | |
119 | * Thanks:: The people who helped create Emacs.app | |
120 | @end menu | |
121 | ||
122 | @node Introduction, Events, Top, Top | |
123 | @section Introduction | |
124 | ||
125 | Despite the size and complexity of GNU Emacs, NeXTstep and the NeXTstep | |
126 | support code, this manual can be kept mercifully short by saying that | |
127 | everything written in the Emacs and the Emacs Lisp manuals about GNU Emacs | |
128 | applies equally to this Emacs except as noted here. | |
129 | ||
130 | @itemize @bullet | |
131 | @item | |
132 | The ``right-click'' button (usually the right-hand button on a two-button | |
133 | mouse) is mapped to Mouse-3, instead of Mouse-2 as earlier versions of | |
134 | Emacs.app. This is for compatibility with X versions of emacs. To get some | |
135 | of the old behavior back, you can put in your .emacs: | |
136 | ||
137 | @lisp | |
138 | (global-set-key [mouse-3] 'mouse-yank-at-click) | |
139 | @end lisp | |
140 | ||
141 | The other functionality of mouse-3 in a buffer of extending a selection is | |
142 | available via shift-click as in other NS applications. To pop up a context | |
143 | menu, | |
144 | ||
145 | @item | |
146 | The Alt or Opt key is bound to the traditional emacs "meta" by default, while | |
147 | the NS "command" key is bound to 'super', for which a set of keybindings are | |
148 | set to mimic other NeXTstep applications. (See @ref{Events}.) You can change | |
149 | either of these bindings using the preferences panel (see @ref{Preferences | |
150 | Panel}). | |
151 | ||
152 | @item | |
153 | The standard NeXTstep font and color panels are accessible through the Windows | |
154 | menu, or through the standard Cmd-t and Cmd-C. These are easier to use than | |
155 | Emacs's own methods for setting these items. To use the color panel, drag | |
156 | from it to an emacs frame. The foreground (or background, if shift is held | |
157 | down) of the face at that point will be changed. To finalize settings for | |
2f45a8ed | 158 | either color or font, choose 'Save Options' from under the Options menu. To |
edfda783 AR |
159 | discard these settings, create a new frame and close the altered one. |
160 | ||
161 | @item | |
162 | Opening files / directories and 'Save Buffer As' operated from the menus use | |
163 | the standard NS file panels. Likewise if you use Cmd-o or Cmd-S. However, | |
164 | if you use the regular Emacs key combinations Ctrl-x,Ctrl-f and Ctrl-x,w for | |
165 | these functions, the normal Emacs mode of typing filenames into the minibuffer | |
166 | is used. | |
167 | ||
168 | @item | |
169 | On GNUstep, in an X-windows environment you need to use Cmd-c instead of one | |
170 | of the Ctrl-w or Meta-w commands to transfer text to the X primary selection. | |
171 | (Ordinarily the "clipboard" selection is used, for compatibility with more | |
172 | modern Gnome and KDE programs.) Likewise, Cmd-y (instead of Ctrl-y) will | |
173 | yank/paste in the X primary selection instead of the kill-ring / clipboard. | |
174 | ||
175 | @item | |
176 | The @code{window-system} variable can now have the value @code{ns} in addition | |
177 | to, e.g., @code{x} or @code{nil}. You can use this in your .emacs file: | |
178 | ||
179 | If you just want to distinguish between cases in which there is a | |
180 | window system and in which there isn't, this construct is useful. | |
181 | @lisp | |
182 | (if window-system | |
183 | ... ;;; evaluate if any window system is running | |
184 | ...) ;;; evaluate only when running on a dumb terminal | |
185 | @end lisp | |
186 | ||
187 | For more detailed control, use this. | |
188 | @lisp | |
189 | (cond | |
190 | ((eq window-system 'ns) ;;; NS specific instructions | |
191 | ...) | |
192 | ((eq window-system 'x) ;;; X specific instructions | |
193 | ...) | |
194 | (t ;;; Instructions for dumb terminal or other window systems | |
195 | ...)) | |
196 | @end lisp | |
197 | ||
198 | @item | |
199 | Likewise, you can detect whether you are running in emacs-23 or an earlier | |
200 | version with: | |
201 | ||
202 | @lisp | |
203 | (if (eq emacs-major-version '23) <emacs-23 code> <emacs-22- code>) | |
204 | @end lisp | |
205 | ||
206 | @item | |
207 | Most NS specific functions begin with 'ns-'. Do "C-h f ns-[TAB]" to list | |
208 | these. Many of these replace equivalent 'x-' functions, while others perform | |
209 | uniquely NS things, such as Service invocation. | |
210 | ||
211 | @item | |
212 | There are also NS variables beginning with 'ns-', however in most cases users | |
213 | need not pay attention to them since the customizability they provide is also | |
214 | available through the defaults system and preferences panel (see | |
215 | @ref{Preferences Panel} and @ref{Customization}). | |
216 | ||
217 | @item | |
218 | When Emacs is called by a name which ends in @file{-nw} it will always | |
219 | start in terminal mode. For example, a user who needs a terminal only | |
220 | emacs would create a symbolic link from @file{emacs} to @file{emacs-nw}. | |
221 | When he launches @file{emacs-nw} from the command line, the window | |
222 | system will never be involved. (Note, as of rc2, terminal mode is still not | |
223 | working under OS X.) | |
224 | @end itemize | |
225 | ||
226 | @node Events, Preferences Panel, Introduction, Top | |
227 | @section Events | |
228 | ||
229 | Under Emacs.app the NeXTstep command key works as the @dfn{super} modifier | |
230 | key. In principle users can bind their command keys to whatever function they | |
231 | want, but to make the transition for NS users easier the default NS startup | |
232 | files bind the most commonly used NS command keys to work just like they do in | |
233 | most other NS applications. Some are shown in the menus. Choose "List | |
234 | Keybindings" from the Help menu and scroll down to the keys labeled starting | |
235 | with 's-' to see all of them. | |
236 | ||
237 | NS applications receive a number of special events which have no X equivalent. | |
238 | These are sent as specially defined ``keys'' (which don't correspond to any | |
239 | keyboard stroke combination). Under Emacs these ``key'' events can be bound | |
240 | to functions just like ordinary keystrokes. Here is a list of these events. | |
241 | ||
242 | @table @code | |
243 | @item ns-open-file | |
244 | This event occurs when another NeXTstep application requests that Emacs | |
245 | open a file. A typical reason for this would be a user double-clicking | |
246 | a file in the Finder. When this event is registered the | |
247 | name of the file to open is found in the variable @code{ns-input-file}. | |
248 | ||
249 | The behaviour of the default binding is controlled by the variable | |
250 | @code{ns-pop-up-frames}. It's default value @code{'fresh} causes Emacs | |
251 | to open the new file in the selected frame if the selected buffer is a | |
252 | scratch buffer. Otherwise Emacs opens a new frame and displays the file | |
253 | in that. | |
254 | ||
255 | To always get a new frame one would change @code{ns-pop-up-frames} to | |
256 | @code{t}. To get the opposite behaviour (i.e. always putting the file into | |
257 | the selected frame), change @code{ns-pop-up-frames} to @code{nil}. | |
258 | ||
259 | @item ns-open-temp-file | |
260 | This event occurs when another application requests that Emacs open a | |
261 | temporary file. The file name is again in @code{ns-input-file}. By | |
262 | default this is handled by just generating a @code{ns-open-file} event | |
263 | (which then causes the @code{ns-open-file} function to be called | |
264 | whatever that may be). | |
265 | ||
266 | @lisp | |
267 | (define-key global-map [ns-open-temp-file] [ns-open-file]) | |
268 | @end lisp | |
269 | ||
270 | @item ns-open-file-line | |
271 | Some applications (like e.g. ProjectBuilder or gdb) request not only a | |
272 | particular file, but also a particular line or sequence of lines in the | |
273 | file. The file name is in @code{ns-input-file}, and | |
274 | @code{ns-input-line} is either the line or a cons cell the car of which | |
275 | contains the beginning line and the cdr of which the ending line. | |
276 | ||
277 | @lisp | |
278 | (define-key global-map [ns-open-file-line] 'ns-open-file-select-line) | |
279 | @end lisp | |
280 | ||
281 | @item ns-drag-file | |
282 | When a user drags files from another application into an Emacs frame | |
283 | this event is triggered. Here @code{ns-input-file} is a list of all | |
284 | dragged files. The default binding inserts all the dragged files into | |
285 | the current buffer. | |
286 | ||
287 | @lisp | |
288 | (define-key global-map [ns-drag-file] 'ns-insert-files) | |
289 | @end lisp | |
290 | ||
291 | @item ns-drag-color | |
292 | When a user drags a color from the color well (or some other source) | |
293 | Emacs sees this event and @code{ns-input-color} contains the name of the | |
294 | dragged color. The default bindings alter the foreground color of the | |
295 | area the color was dragged onto (or background color if the color was | |
296 | shift dragged). | |
297 | ||
298 | @lisp | |
299 | (define-key global-map [ns-drag-color] | |
300 | 'ns-set-foreground-at-mouse) | |
301 | (define-key global-map [S-ns-drag-color] | |
302 | 'ns-set-background-at-mouse) | |
303 | @end lisp | |
304 | ||
305 | @item ns-change-font | |
306 | Emacs.app allows the user to open a standard NS font panel (by default that | |
307 | function is bound to @kbd{Cmd-t}). When the user selects a font in that | |
308 | panel this event occurs. @code{ns-input-font} will contain the name of | |
309 | the selected font and @code{ns-input-fontsize} is its size. The | |
310 | default binding causes Emacs to adjust the font of the selected frame. | |
311 | ||
312 | @lisp | |
313 | (define-key global-map [ns-change-font] 'ns-respond-to-changefont) | |
314 | @end lisp | |
315 | ||
316 | @item ns-power-off | |
317 | Finally when the user logs out and Emacs is still running it receives | |
318 | this event so that it has a chance to save its files before it dies. | |
319 | ||
320 | @lisp | |
321 | (define-key global-map [ns-power-off] | |
322 | '(lambda () (interactive) (save-buffers-kill-emacs t))) | |
323 | @end lisp | |
324 | ||
325 | @end table | |
326 | ||
327 | Emacs.app also allows users to make use of NeXTstep services programatically, | |
328 | in addition to via the Services menu. On the most basic level programmers can | |
329 | use the @code{ns-perform-service} to pass arbitrary strings to arbitrary | |
330 | services and receive the results back. However convenience functions are | |
331 | automatically provided for all services so there should be no need to use | |
332 | this. These function names begin with 'ns-service-', and they will either | |
333 | operate on marked text (replacing it with the result) or take a string | |
334 | argument and return the result as a string. Type "M-x ns-service-[TAB][TAB]" | |
335 | to see those currently defined. Note that Emacs may require a restart to | |
336 | access newly available services. | |
337 | ||
338 | ||
339 | @node Preferences Panel, Customization, Events, Top | |
340 | @section Preferences Panel | |
341 | ||
342 | The Preferences Panel can be used to set or change some of the settings for | |
343 | Emacs such as the text appearance, cursor settings, and key bindings. | |
344 | ||
345 | To save any settings changed through the Preferences Panel, hit OK; | |
346 | this has the same effect as if you had explicitly chosen Help > Save | |
347 | Preferences. | |
348 | ||
349 | To restore Emacs to use its default settings click Reset to Defaults from | |
350 | the Preferences Panel. | |
351 | ||
352 | Additional GNUstep/OS X preferences may be set from the command line using | |
353 | the @command{defaults} command. (See @ref{Customization}.) | |
354 | ||
355 | ||
356 | @section Text Rendering Preferences | |
357 | ||
358 | Font and color settings can be set using the standard NeXTstep font | |
359 | and color panels. | |
360 | ||
361 | @itemize @bullet | |
362 | @item | |
363 | To set the default font used by Emacs click the Default Font... button | |
364 | to launch the Font Panel. Click on a frame before selecting the font | |
365 | family, typeface, and size of the default font from the Font Panel. | |
366 | ||
367 | Note that the default font will not be changed if a frame hasn't been | |
368 | selected first. | |
369 | ||
370 | @item | |
371 | To set the default foreground or background color click the | |
372 | Colors... button to launch the Color Panel. Choose the color you want | |
373 | using any of the color models (color wheel, sliders, palette, image, | |
374 | or crayons) available from the Colors toolbar. To apply the color | |
375 | drag a swatch from the color bar at the top of the panel to text on | |
376 | an Emacs frame. Holding down shift will change the background color | |
377 | instead of the foreground. | |
378 | ||
379 | @item | |
380 | To use antialiased text check the Smooth Fonts option. Lighter font | |
381 | smoothing can be achieved by checking the Use Quickdraw (lighter) | |
382 | smoothing option. | |
383 | ||
384 | @item | |
385 | To change the line height that text is displayed at drag the Expand | |
386 | Line Spacing slider. When the slider is set to 0.0 Emacs will use the | |
387 | same line height as other Mac OS X applications. To increase the line | |
388 | height (and decrease the number of lines that can be displayed on the | |
389 | screen) drag the slider towards 1.0. To decrease the line height | |
390 | (increases the number of lines that can be displayed) drag the slider | |
391 | towards -1.0. | |
392 | ||
393 | After the line spacing setting has been changed Emacs must be restarted | |
394 | to take account of the change. | |
395 | ||
396 | @end itemize | |
397 | ||
398 | @section Display Preferences | |
399 | ||
400 | The Display Preferences can be used to change the appearance of the | |
401 | default cursor used by Emacs. | |
402 | ||
403 | @itemize @bullet | |
404 | @item | |
405 | The Cursor Type radio buttons can be used to select the style used for the cursor: | |
406 | ||
407 | @itemize | |
408 | @item | |
409 | Box - the cursor is displayed as a box | |
410 | @item | |
411 | Underscore - the cursor is displayed as a horizontal bar | |
412 | @item | |
413 | Bar - the cursor is displayed as a vertical bar | |
414 | @item | |
415 | Hollow - the cursor is displayed as a box with an outline but no fill | |
416 | @end itemize | |
417 | ||
418 | @item | |
419 | Use the Cursor Blink Rate slider to set the frequency at which the cursor blinks. | |
420 | ||
421 | @item | |
422 | Check the Use System Highlight Color option to use the system default | |
423 | color for highlighted text. | |
424 | ||
425 | @end itemize | |
426 | ||
427 | @section Modifier Interpretation Preferences | |
428 | ||
429 | The Modifier Preferences can be used to change the behaviour of the | |
430 | Alt/Opt and Command keys. By default the Alt or Opt key is bound to | |
431 | the Emacs 'Meta' key, and the Command key is bound to 'super' which | |
432 | allows the Command key to function in a way similar to other | |
433 | NeXTstep/OS X applications. | |
434 | ||
435 | @itemize @bullet | |
436 | @item | |
437 | To re-bind the Alt or Opt key select a keybinding from the Alt/Opt Key | |
438 | combo box. | |
439 | @item | |
440 | To re-bind the Command key select a keybinding from the Command Key | |
441 | combo box. | |
442 | @end itemize | |
443 | ||
444 | ||
445 | @node Customization, Tips and Tricks, Preferences Panel, Top | |
446 | @section Customization | |
447 | ||
2f45a8ed AR |
448 | Under X, resources are used to customize the behavior of Emacs to the |
449 | needs of the user. These resources are queried programmatically with | |
450 | the @code{x-get-resource} function. Under NS defaults fulfill a | |
451 | similar function. They can be read using the @code{ns-get-resource} | |
452 | function. Calls to @code{x-get-resource} are automatically mapped to | |
453 | @code{ns-get-resource}. From the command line, the command | |
454 | `@code{defaults read org.gnu.Emacs}' will show these resources as of | |
455 | last Emacs quit, and individual resources can be read/written by | |
456 | commands like `@code{defaults read Emacs Foo}' and `@code{defaults | |
457 | write Emacs Foo barvalue}'. | |
edfda783 AR |
458 | |
459 | Calling the function @code{ns-save-preferences} in lisp, or selecting ``Save | |
460 | Options'' from the 'Options' menu will automatically write out the defaults | |
461 | corresponding to the selected window. | |
462 | ||
463 | In addition, it is also possible to set many of the following customizations | |
464 | by setting the @code{default-frame-alist} in the @file{~/.emacs} file. | |
465 | ||
466 | Many of the preferences relating specifically to the NS windowing system (font | |
467 | rendering, cursor type, etc.) can be set using a @ref{Preferences Panel} | |
468 | accessed in the standard fashion from the menubar or Cmd-,. It is important | |
469 | to note that when you hit 'OK' on this panel, @emph{all} NS settings are saved | |
470 | (including font and colors) just as if you had called | |
471 | @code{ns-save-preferences}. | |
472 | ||
473 | Note that if you use the 'Default Font' button on the Preferences panel, you | |
474 | must click on a frame before selecting a font, otherwise nothing will happen. | |
475 | If you pop up the color panel, you must drag colors to a frame for them to | |
476 | have an effect. (Remember to hold down 'shift' to change background instead | |
477 | of foreground.) | |
478 | ||
479 | This is a listing of some of the more useful defaults (and their default | |
480 | values). Several of these defaults accept the names of colors as values. For | |
481 | a list of all available colors pull up the color panel and look at the color | |
482 | list called ``Emacs''. Emacs also accepts color specifications of the form | |
483 | @samp{ARGBaarrggbb} where @var{aa}, @var{rr}, @var{gg}, and @var{bb} are two | |
484 | hexadecimal digits describing the alpha, red, green, and blue content of the | |
db8ef699 AR |
485 | color respectively. @samp{HSBhhssbb}, @samp{CMYKccmmyykk} and |
486 | @samp{GRAYgg} are the equivalents in @samp{HSB}, @samp{CMYK} and gray | |
487 | scales. (For HSB, @samp{AHSBaahhssbb} is also accepted.) | |
edfda783 AR |
488 | |
489 | @table @samp | |
490 | @item InternalBorderWidth | |
491 | Width in pixels of the internal border of the NS frame. This acts to separate | |
492 | the text area of the window from the fringes, scrollbars, and/or edges. | |
493 | ||
494 | @example | |
495 | defaults write Emacs InternalBorderWidth 2 | |
496 | @end example | |
497 | ||
498 | @item VerticalScrollBars | |
499 | @samp{YES} or @samp{NO} to enable or disable scroll bars, @samp{left} or | |
500 | @samp{right} to explicitly set the side. | |
501 | ||
502 | @example | |
503 | defaults write Emacs VerticalScrollBars YES | |
504 | @end example | |
505 | ||
506 | @item Font | |
507 | Name of the default font to be used for new frames (which can be overriden by | |
508 | various faces). If this font is not set, Emacs.app will use the system | |
509 | wide fixed pitch font. For most users the system fixed pitch font will be | |
510 | @samp{Monaco} which doesn't have any bold or italic versions. (Italic will be | |
511 | synthesized.) | |
512 | ||
513 | @item FontSize | |
514 | Size of the font to be used for new frames. If not set Emacs for NS will use | |
515 | the default size of the system wide fixed pitch font. | |
516 | ||
517 | @item Foreground | |
518 | The default foreground (text) color for new frames. | |
519 | ||
520 | @example | |
521 | defaults write Emacs Foreground "Black" | |
522 | @end example | |
523 | ||
524 | @item Background | |
525 | The default background color for new frames. | |
526 | ||
527 | @example | |
528 | defaults write Emacs Background "White" | |
529 | @end example | |
530 | ||
531 | @item Height | |
532 | Height in rows of the default window. | |
533 | ||
534 | @example | |
535 | defaults write Emacs Height 48 | |
536 | @end example | |
537 | ||
538 | @item Width | |
539 | Width in columns of the default window. | |
540 | ||
541 | @example | |
542 | defaults write Emacs Width 80 | |
543 | @end example | |
544 | ||
545 | @item CursorType | |
546 | Name of the default cursor type for Emacs. Allowed values are | |
547 | @samp{box}, @samp{hollow}, @samp{underscore}, @samp{bar}, @samp{line} and @samp{no}. | |
548 | ||
549 | @example | |
550 | defaults write Emacs CursorType box | |
551 | @end example | |
552 | ||
553 | @item CursorBlinkRate | |
554 | Users who want their cursor to blink can set the rate (in seconds) with | |
555 | this defaults write. Setting it to @samp{NO} disables cursor blinking. | |
556 | ||
557 | @example | |
558 | defaults write Emacs CursorBlinkRate NO | |
559 | @end example | |
560 | ||
561 | @item CursorColor | |
562 | Name of the default cursor color for Emacs. Of a particular use for this | |
563 | setting is the @samp{Highlight} "color". When it is the cursor color, | |
564 | Emacs will draw the cursor using the standard NS highlighting operator. | |
565 | ||
566 | @example | |
567 | defaults write Emacs CursorColor Highlight | |
568 | @end example | |
569 | ||
570 | @item Top | |
571 | Distance in pixels from the top of the screen of the upper left corner | |
572 | of the default window. | |
573 | ||
574 | @example | |
575 | defaults write Emacs Top 100 | |
576 | @end example | |
577 | ||
578 | @item Left | |
579 | Distance in pixels from the left edge of the screen to the upper left | |
580 | corner of the default window. | |
581 | ||
582 | @example | |
583 | defaults write Emacs Left 100 | |
584 | @end example | |
585 | ||
586 | @item HideOnAutoLaunch | |
587 | @samp{YES} or @samp{NO} to determine whether Emacs will hide itself when | |
588 | autolaunched from the dock. | |
589 | ||
590 | @example | |
591 | defaults write Emacs HideOnAutoLaunch NO | |
592 | @end example | |
593 | ||
594 | @item ExpandSpace | |
595 | This lets you expand or shrink the line height used for displaying text. When | |
596 | this is set to 0.0, display should look like other NS apps. If you set it | |
597 | higher than 0, Emacs will spread the text lines apart, less than 0, compress | |
598 | them together. (With settings below zero parts of characters may be chopped | |
599 | off in certain fonts.) When using the @ref{Preferences Panel}, this is | |
600 | controlled by a slider. You must OK the panel and then restart Emacs.app for | |
601 | this default to take effect. | |
602 | ||
603 | When setting this using @code{"defaults write"}, you can either set a floating | |
604 | point value, or @samp{YES}, which is equivalent 0.5, or @samp{NO}, which is | |
605 | equivalent to 0.0. | |
606 | ||
607 | @example | |
608 | defaults write Emacs ExpandSpace -0.125 | |
609 | @end example | |
610 | ||
611 | @item GSFontAntiAlias | |
612 | This turns antialiasing on and off on. Note that, on OS X, even if | |
613 | antialiasing is on, Emacs will not antialias text of a size below the system | |
614 | preference setting. | |
615 | ||
616 | @example | |
617 | defaults write Emacs GSFontAntiAlias NO | |
618 | @end example | |
619 | ||
620 | @item UseQuickdrawSmoothing | |
621 | On OS X 10.3 and higher, this will render fonts using Quickdraw antialiasing, | |
622 | which is less heavy than the Quartz antialiasing used by default. Whether | |
623 | this is on or off, the system font size threshold for antialiasing (see above) | |
624 | is respected. | |
625 | ||
626 | @example | |
627 | defaults write Emacs UseQuickdrawSmoothing YES | |
628 | @end example | |
629 | ||
630 | @item AlternateModifier | |
631 | This allows you to set the effect of the Alt or Opt key. The default is | |
632 | @samp{meta}, meaning to use as the Emacs 'meta' key. You can also set this to | |
633 | @samp{command}, @samp{hyper}, @samp{alt}, or @samp{none}. The last is useful | |
634 | for Continental users who normally use this key to enter accented and other | |
635 | special characters. | |
636 | ||
637 | @example | |
638 | defaults write Emacs AlternateModifier "none" | |
639 | @end example | |
640 | ||
641 | @item CommandModifier | |
642 | This allows you to set the effect of the Command key. The default is | |
643 | @samp{super}, which is used in a set of keybindings such as @code{s-o} for | |
644 | ``open file'' and @code{s-z} for ``undo'' that are similar to other NeXTstep | |
645 | applications. On the other hand, some people who use the Alt/Opt key for | |
646 | accent entry like to set this to @samp{meta} so they still have easy access to | |
647 | Emacs functionality bound to meta keys. You can also set this, like Alt/Opt, | |
648 | to @samp{hyper} or @samp{alt}, though there are no bindings to combinations | |
649 | using these keys by default. The @samp{none} option is not available for the | |
650 | Command key. | |
651 | ||
652 | @example | |
653 | defaults write Emacs CommandModifier "meta" | |
654 | @end example | |
655 | ||
656 | @item fooFrame | |
657 | Position and size to use for the frame named @var{foo} when it is | |
658 | created. The position and size have to be specified as a space | |
659 | separated list: @samp{top}, @samp{left}, @samp{height} and | |
660 | @samp{width}. @samp{top} and @samp{left} are expressed in pixels, | |
661 | @samp{height} is given in rows and @samp{width} is given in columns. | |
662 | Named frames can be created by e.g. @code{(make-frame '((name | |
663 | . "FOO")))}. | |
664 | ||
665 | @example | |
666 | defaults write Emacs TestFrame "100 200 30 70" | |
667 | @end example | |
668 | ||
669 | Another default previouly used by many Emacs users is this. | |
670 | ||
671 | @example | |
672 | defaults write Workspace DefaultOpenApp Emacs | |
673 | @end example | |
674 | ||
675 | It caused the NeXTstep Workspace to open files without a registered extension | |
676 | in Emacs instead of as usual Edit. For this default to work, Emacs needed to | |
677 | be in the application search path of the Workspace (which usually includes | |
678 | @file{~/Applications} and @file{~/Applications}). If anyone knows the current | |
679 | way to do this under OS X please contact the authors. | |
680 | ||
681 | @end table | |
682 | ||
683 | @node Tips and Tricks, Thanks, Customization, Top | |
684 | @section Tips and Tricks | |
685 | ||
686 | Emacs is an extremely customizable editor. You can make it conform to | |
687 | virtually any conceivable user idiosyncrasy (and some which are not) by adding | |
688 | a few well-chosen lines of emacs lisp to your @file{~/.emacs}. Unfortunately | |
689 | even many experienced C developers are unfamiliar with Emacs Lisp. For that | |
690 | reason many Emacs.app defaults have been chosen to make it behave as similar | |
691 | to TextEdit as possible. But there are some customizations which a majority | |
692 | of users probably would hate as much as a minority would love them. This | |
693 | section contains a cookbook of such customizations. New contributions by | |
694 | Emacs users are very welcome. | |
695 | ||
696 | @menu | |
697 | * Grabbing environment variables:: | |
698 | * Miscellaneous useful variables:: | |
699 | * Color adjustments:: | |
700 | * Evaling in the minibuffer:: | |
701 | * Highlighting matching parentheses:: | |
702 | * Dealing with X specific packages:: | |
703 | * Rebinding the numeric keypad:: | |
704 | * Improving C mode:: | |
705 | * Custom menu items:: | |
706 | * Single line scrolling:: | |
707 | * Open files by dragging to an Emacs window:: | |
708 | @ignore | |
709 | * Extended font customization:: | |
710 | @end ignore | |
711 | @end menu | |
712 | ||
713 | @node Grabbing environment variables, Miscellaneous useful variables, Tips and Tricks, Tips and Tricks | |
714 | @subsection Grabbing environment variables | |
715 | ||
716 | Many programs which may run under Emacs like latex or man depend on the | |
717 | settings of environment variables. If Emacs is launched from the shell, it | |
718 | will automatically inherit these environment variables and its subprocesses | |
719 | will inherit them from it. But if Emacs.app is launched from the Finder it | |
720 | is not a descendant of any shell, so its environment variables haven't been | |
721 | set which often causes the subprocesses it launches to behave differently than | |
722 | they would when launched from the shell. | |
723 | ||
724 | To solve this problem for Emacs.app, there are two solutions. First is to | |
725 | run, from the command line: | |
726 | ||
727 | @example | |
728 | .../Emacs.app/Contents/MacOS/bin/mac-fix-env | |
729 | @end example | |
730 | ||
731 | This will pick up your environment settings and save them into a special file | |
732 | @file{~/.MacOSX/environment.plist}, which the desktop environment will use to | |
733 | set the environment for all launched applications. The drawback of this | |
734 | method is it needs to be run again whenever something changes. | |
735 | ||
736 | The other approach is to use the @code{ns-grabenv} command inside Emacs. This | |
737 | function will run a subshell and copy its environment variables into Emacs. | |
738 | ||
739 | Adding this line to your @file{~/.emacs} will grab the csh environment | |
740 | whenever emacs runs under a window system. | |
741 | ||
742 | @lisp | |
743 | (if window-system (ns-grabenv)) | |
744 | @end lisp | |
745 | ||
746 | If you have a different shell you will have to give @code{ns-grabenv} some | |
747 | arguments. For zsh you would do this. | |
748 | ||
749 | @lisp | |
750 | (if window-system (ns-grabenv "/usr/bin/zsh" | |
751 | "source /etc/zshenv" | |
752 | "source ~/.zshenv")) | |
753 | @end lisp | |
754 | ||
755 | The reason that @code{ns-grabenv} is not done by default is that it adds up | |
756 | to a second or two to the Emacs startup time. | |
757 | ||
758 | @node Miscellaneous useful variables, Color adjustments, Grabbing environment variables, Tips and Tricks | |
759 | @subsection Miscellaneous useful variables | |
760 | ||
761 | This section describes a few variables you might want to set in your | |
762 | @file{~/.emacs} each of which doesn't warrant its own section. | |
763 | ||
764 | There is a conflict between the way the region behaved in emacs in the | |
765 | pre-GUI days and the way GUI users expect the selection to work. By | |
766 | default that conflict is resolved by having the former adopt the | |
767 | behaviour of the latter which most people prefer. However if you are a | |
768 | die-hard emacs user you may prefer things the other way around and add | |
769 | this line to your @file{~/.emacs}. Experiment with both settings. | |
770 | ||
771 | @lisp | |
772 | (setq transient-mark-mode nil) | |
773 | @end lisp | |
774 | ||
775 | When you try to move beyond the end of a file Emacs used to add newlines as | |
776 | needed, however from Emacs-21 on, this was no longer done. If you prefer the | |
777 | old behavior, this line in your @file{~/.emacs} will restore it. | |
778 | ||
779 | @lisp | |
780 | (setq next-line-add-newlines t) | |
781 | @end lisp | |
782 | ||
783 | By default when you kill a line with text on it, only the text is | |
784 | removed while the line itself remains. You have to kill twice to really | |
785 | get rid of the whole line. When this variable is set and you kill a | |
786 | line while at the beginning of the line it will go at once. | |
787 | ||
788 | @lisp | |
789 | (setq kill-whole-line t) | |
790 | @end lisp | |
791 | ||
792 | Annoyed by the Emacs startup message ? Add this and you start with a | |
793 | tabula rasa. | |
794 | ||
795 | @lisp | |
796 | (setq inhibit-startup-message t) | |
797 | @end lisp | |
798 | ||
799 | @node Color adjustments, Evaling in the minibuffer, Miscellaneous useful variables, Tips and Tricks | |
800 | @subsection Color adjustments | |
801 | ||
802 | A non-elisp hint: The easiest way to adjust your emacs color scheme is to | |
803 | bring up a color panel (with @key{Cmd-C}) and drag the color you want over the | |
804 | emacs face you want to change. Normal dragging will alter the foreground | |
805 | color. Shift dragging will alter the background color. To make the changes | |
806 | permanent select the "Save Options" item in the "Options" menu, or run | |
807 | @code{ns-save-preferences}. Useful in this context is the listing of all | |
808 | faces obtained by @key{M-x} @code{list-faces-display}. | |
809 | ||
810 | @node Evaling in the minibuffer, Highlighting matching parentheses, Color adjustments, Tips and Tricks | |
811 | @subsection Evaling in the minibuffer | |
812 | ||
813 | Often you (at least if you are an elisp hacker) want to quickly evaluate | |
814 | an elisp expression. To accomodate this desire Emacs provides the | |
815 | @code{eval-expression} command bound to @key{M-:}. By default it is | |
816 | disabled to protect novice users from themselves. These commands | |
817 | re-enable it and turn on an extremely powerful completion facility. | |
818 | ||
819 | @lisp | |
820 | (put 'eval-expression 'disabled nil) | |
821 | ||
822 | (define-key read-expression-map "\t" 'lisp-complete-symbol) | |
823 | @end lisp | |
824 | ||
825 | @node Highlighting matching parentheses, Dealing with X specific packages, Evaling in the minibuffer, Tips and Tricks | |
826 | @subsection Highlighting matching parentheses | |
827 | ||
828 | I doubt that there is anybody who doesn't use this already, but just in | |
829 | case: | |
830 | ||
831 | @lisp | |
832 | (show-paren-mode 't) | |
833 | @end lisp | |
834 | ||
835 | In Emacs.app this is currently enhanced by use of the @code{mic-paren} package | |
836 | from http://www.docs.uu.se/~mic/emacs.html. | |
837 | ||
838 | @node Dealing with X specific packages, Rebinding the numeric keypad, Highlighting matching parentheses, Tips and Tricks | |
839 | @subsection Dealing with X specific packages | |
840 | ||
841 | Some emacs lisp packages explicitly call X specific functions instead of | |
842 | calling generic functions which call the NS or X versions as appropriate. | |
843 | Typically such packages will result in error messages like @samp{Symbol's | |
844 | function definition is void: x-foo-bar}. The proper way of dealing with this | |
845 | is to have the author fix the code to call the generic functions. Generally | |
846 | all that requires is removing the @samp{x-} prefix from all function calls. | |
847 | ||
848 | However, sometimes that is not possible, or it may be a package internal to | |
849 | emacs itself. In this case please report a bug to the Emacs.app maintainers | |
850 | (not the main GNU emacs maintainers). | |
851 | ||
852 | A related problem is font names. For historical reasons, Emacs assumes all | |
853 | font names are given ``X style'', as in ``-adobe-courier-....-iso8859-1''. | |
854 | Emacs.app tries to work around this as well as possible, and the best thing to | |
855 | do is never rely on functions to set font names yourself but to always use the | |
856 | font panel. | |
857 | ||
858 | @node Rebinding the numeric keypad, Improving C mode, Dealing with X specific packages, Tips and Tricks | |
859 | @subsection Rebinding the numeric keypad | |
860 | ||
861 | By default in Emacs the numeric keypad keys are bound to the same | |
862 | characters they are in all other NS applications. But it is easy to | |
863 | change these bindings to commands many will find more useful. As an | |
864 | example here is the code which rebinds the numeric keypad for me. | |
865 | ||
866 | @lisp | |
867 | (global-set-key [kp-0] 'other-window) | |
868 | (global-set-key [kp-1] 'end-of-buffer) | |
869 | (global-set-key [kp-2] [down]) | |
870 | (global-set-key [kp-3] 'scroll-up) | |
871 | (global-set-key [kp-4] [left]) | |
872 | (global-set-key [kp-5] 'set-mark-command) | |
873 | (global-set-key [kp-6] [right]) | |
874 | (global-set-key [kp-7] 'beginning-of-buffer) | |
875 | (global-set-key [kp-8] [up]) | |
876 | (global-set-key [kp-9] 'scroll-down) | |
877 | (global-set-key [kp-decimal] 'yank) | |
878 | (global-set-key [kp-enter] 'set-mark-command) | |
879 | (global-set-key [kp-add] 'copy-region-as-kill) | |
880 | (global-set-key [kp-subtract] 'kill-region) | |
881 | @end lisp | |
882 | ||
883 | On machines with function keys they can be bound as well. This for example | |
884 | would bind @key{F12} to run gnus. | |
885 | ||
886 | @lisp | |
887 | (global-set-key [f12] 'gnus) | |
888 | @end lisp | |
889 | ||
890 | @node Improving C mode, Custom menu items, Rebinding the numeric keypad, Tips and Tricks | |
891 | @subsection Improving C mode | |
892 | ||
893 | That underscores are considered to break words in C mode has been driving me | |
894 | insane for a long time. This line fixes the problem. | |
895 | ||
896 | @lisp | |
897 | (modify-syntax-entry ?_ "w" c-mode-syntax-table) | |
898 | @end lisp | |
899 | ||
900 | @node Custom menu items, Single line scrolling, Improving C mode, Tips and Tricks | |
901 | @subsection Custom menu items | |
902 | ||
903 | The tools menu is intended for customization. Adding items to it is | |
904 | relatively painless as this example illustrates. | |
905 | ||
906 | @lisp | |
907 | (define-key global-map [menu-bar tools www] '("WWW" . w3-use-hotlist)) | |
908 | @end lisp | |
909 | ||
910 | @node Single line scrolling, Open files by dragging to an Emacs window, Custom menu items, Tips and Tricks | |
911 | @subsection Single line scrolling | |
912 | ||
913 | The meta-arrow keys will perform single-line scrolling in Emacs | |
914 | just like they did in the old NeXT/OpenStep Stuart.app. | |
915 | ||
916 | @node Open files by dragging to an Emacs window, , Single line scrolling, Tips and Tricks | |
917 | @subsection Open files by dragging to an Emacs window | |
918 | ||
919 | The default behaviour when a user drags files from another application | |
920 | into an Emacs frame is to insert the contents of all the dragged files | |
921 | into the current buffer. To remap the @code{ns-drag-file} event to | |
922 | open the dragged files in the current frame use the following line: | |
923 | ||
924 | @lisp | |
925 | (define-key global-map [ns-drag-file] 'ns-find-file) | |
926 | @end lisp | |
927 | ||
928 | @ignore | |
929 | @node Extended font customization, , Single line scrolling, Tips and Tricks | |
930 | @subsection Extended font customization | |
931 | ||
932 | By default Emacs tries to guess the right font when you ask for a bold, | |
933 | italic or bold-italic face. Unfortunately this fails sometimes, for | |
934 | example Emacs won't guess that it should use @samp{Courier-Bold} as the | |
935 | font for the bold face of @samp{Ohlfs}. As an example here is the code | |
936 | which sets up @samp{Courier-Bold}, @samp{Courier-Oblique} and | |
937 | @samp{Courier-BoldOblique} as the fonts to be used with @samp{Ohlfs}. | |
938 | ||
939 | @lisp | |
940 | (setq ns-convert-font-trait-alist | |
941 | '(("Ohlfs" "Courier-Bold" "Courier-Oblique" | |
942 | "Courier-BoldOblique"))) | |
943 | @end lisp | |
944 | ||
945 | You will still have to set the @samp{DefaultFont}, @samp{BoldFont}, | |
946 | @samp{ItalicFont} and @samp{Bold-ItalicFont} defaults as Emacs | |
947 | initializes the default faces before it reads your @file{~/.emacs}. | |
948 | Also Emacs initializes @code{ns-convert-font-trait-alist} from these | |
949 | defaults so that normally it's sufficient to set these defaults to get | |
950 | correct faces. | |
951 | ||
952 | @example | |
953 | defaults write Emacs DefaultFont Ohlfs | |
954 | defaults write Emacs BoldFont Courier-Bold | |
955 | defaults write Emacs ItalicFont Courier-Oblique | |
956 | defaults write Emacs Bold-ItalicFont Courier-BoldOblique | |
957 | @end example | |
958 | @end ignore | |
959 | ||
960 | ||
961 | @node Thanks, , Tips and Tricks, Top | |
962 | @section Thanks | |
963 | A signficant number of people have been involved in the creation of Emacs.app. | |
964 | Carl Edman <cedman@@lynx.ps.uci.edu> created and maintained Emacs up to | |
965 | version 4.1 and it's reasonable to say that without his work, Emacs.app | |
966 | wouldn't exist. Michael Brouwer <michael@@thi.nl> wrote the original version | |
967 | (up to and including version 3.x) and was a constant contributor to Emacs.app | |
968 | version 4 and above. Christian Limpach <chris@@nice.ch> took over maintenance | |
969 | and updating at version 4.2, and made substantial contributions in a number of | |
970 | areas. Scott Bender <sbender@@harmony-ds.com> ported the code to OpenStep and | |
971 | Rhapsody for version 6.0. Christophe de Dinechin <ddd@@cup.hp.com> ported the | |
972 | code to MacOS X for version 7.0 and moved the code base to SourceForge. Leigh | |
973 | Smith <leigh@@leighsmith.com> maintained the SourceForge project for a period. | |
974 | Adrian Robert <arobert@@cogsci.ucsd.edu> ported the code to GNUstep | |
975 | (http://gnustep.org), updated it for post-emacs-20, and maintains it for the | |
976 | present. | |
977 | ||
978 | Also a number of others have contributed code. Steve Nygard | |
979 | <nygard@@telusplanet.net> got emacs to dump under OpenStep. The font panel | |
980 | code was Andrew Athan's <athan@@object.com> work. Joe Reiss | |
981 | <jreiss@@magnus.acs.ohio-state.edu> both created the beautiful icons you see | |
9e2a2647 | 982 | and wrote the popup menu and dialog box code as well as much else. |
edfda783 AR |
983 | |
984 | Finally, suggestions from Darcy Brockbank, Timothy Bissell, Scott Byer, David | |
985 | Griffiths, Scott Hess, Eberhard Mandler, John C. Randolph, and Bradley Taylor | |
986 | all helped things along at one point or another. Axel Seibert | |
987 | <seiberta@@informatik.tu-muenchen.de> and Paul J. Sanchez | |
988 | <paul@@whimsy.umsl.edu> offered their time and machines to make a binary | |
989 | release possible. | |
990 | ||
991 | The GNUstep port was made possible through the assistance of Adam Fedor, Fred | |
992 | Kiefer, M. Uli Klusterer, Alexander Malmberg, and Jonas Matton. Gürkan Sengün | |
993 | made it accessible to a wider community. | |
994 | ||
995 | Riccardo Mottola helped with compatibility with MacOS versions 10.1 and 10.2, | |
996 | and GNUstep on platforms other than Linux. | |
997 | ||
998 | Peter Dyballa kept things honest with multilingual support. Rahul Abrol, Adam | |
999 | Ratcliffe, David M. Cooke, and Carsten Bormann provided various small patches. | |
1000 | ||
1001 | Then there were a number of people who kept up the constant supply of bug | |
1002 | reports, suggested features and praise (which is the main fuel which the | |
1003 | development of a project like this runs) and so helped ensure that this | |
1004 | program is as bug free (hah !) and feature rich as you see it today. First | |
1005 | among them were Hardy Mayer <hardy@@golem.ps.uci.edu>, Gisli Ottarsson | |
1006 | <gisli@@timoshenko.eecs.umich.edu>, Anthony Heading <ajrh@@signal.dra.hmg.gb>, | |
1007 | David Bau <bau@@cs.cornell.edu>, Jamie Zawinski <jwz@@lucid.com>, Martin | |
1008 | Moncrieffe <moncrief@@mayo.edu>, Simson L. Garfinkel | |
1009 | <simsong@@next.cambridge.ma.us>, Richard Stallman <rms@@gnu.ai.mit.edu>, | |
1010 | Stephen Anderson <anderson@@sapir.cog.jhu.edu>, Ivo Welch | |
1011 | <ivo@@next.agsm.ucla.edu>, Magnus Nordborg <magnus@@fisher.Stanford.EDU>, Tom | |
1012 | Epperly <epperly@@valeron.che.wisc.edu>, Andreas Koenig | |
1013 | <k@@franz.ww.tu-berlin.de>, Yves Arrouye <Yves.Arrouye@@imag.fr>, Anil | |
1014 | Somayaji <soma@@hotspur.mit.edu>, Gregor Hoffleit | |
1015 | <flight@@mathi.uni-heidelberg.DE> and doubtlessly many more. | |
1016 | ||
1017 | Finally, let us also thank those few hundred other people on the mailing list | |
1018 | from whom we didn't hear much, but the presence of which assured us that maybe | |
1019 | this project was actually worth doing. | |
1020 | @bye | |
0ae1e5e5 MB |
1021 | |
1022 | @ignore | |
1023 | arch-tag: 286bdf18-ccfb-48b2-b730-994771de6bdd | |
1024 | @end ignore |