| blob | 0727c834b2fc3802cc98788bad1e5b9079977c30 |
1 .\" See section COPYING for copyright and redistribution information.
2 .TH EMACS 1 "2007 April 13" "GNU Emacs 23.0.95"
3 .
4 .
5 .SH NAME
6 emacs \- GNU project Emacs
7 .
8 .
9 .SH SYNOPSIS
10 .B emacs
11 [
12 .I command-line switches
13 ] [
14 .I files ...\&
15 ]
16 .
17 .
18 .SH DESCRIPTION
19 .I GNU Emacs
20 is a version of
21 .IR Emacs ,
22 written by the author of the original (PDP-10)
23 .IR Emacs ,
24 Richard Stallman.
25 .br
26 The primary documentation of GNU Emacs is in the GNU Emacs Manual,
27 which you can read using Info, either from Emacs or as a standalone
28 program.
29 Please look there for complete and up-to-date documentation.
30 This man page is updated only when someone volunteers to do so; the
31 Emacs maintainers' priority goal is to minimize the amount of time
32 this man page takes away from other more useful projects.
33 .br
34 The user functionality of GNU Emacs encompasses
35 everything other
36 .I Emacs
37 editors do, and it is easily extensible since its
38 editing commands are written in Lisp.
39 .PP
40 .I Emacs
41 has an extensive interactive help facility,
42 but the facility assumes that you know how to manipulate
43 .I Emacs
44 windows and buffers.
45 CTRL-h or F1 enters the Help facility.
46 Help Tutorial (CTRL-h t) starts an interactive tutorial which can
47 teach beginners the fundamentals of
48 .I Emacs
49 in a few minutes.
50 Help Apropos (CTRL-h a) helps you
51 find a command given its functionality, Help Character (CTRL-h c)
52 describes a given character's effect, and Help Function (CTRL-h f)
53 describes a given Lisp function specified by name.
54 .PP
55 .IR Emacs 's
56 Undo can undo several steps of modification to your buffers, so it is
57 easy to recover from editing mistakes.
58 .PP
59 .IR "GNU Emacs" 's
60 many special packages handle mail reading (RMail) and sending (Mail),
61 outline editing (Outline), compiling (Compile), running subshells
62 within
63 .I Emacs
64 windows (Shell), running a Lisp read-eval-print loop
65 (Lisp-Interaction-Mode), automated psychotherapy (Doctor), and much more.
66 .PP
67 There is an extensive reference manual, but
68 users of other Emacses
69 should have little trouble adapting even
70 without a copy.
71 Users new to
72 .I Emacs
73 will be able
74 to use basic features fairly rapidly by studying the tutorial and
75 using the self-documentation features.
76 .
77 .SS Emacs Options
78 The following options are of general interest:
79 .RS
80 .TP 8
81 .I file
82 Edit
83 .IR file .
84 .TP
85 .BI \-\-file " file\fR,\fP " \-\-find-file " file\fR,\fP " \-\-visit " file"
86 The same as specifying
87 .I file
88 directly as an argument.
89 .TP
90 .BI + number
91 Go to the line specified by
92 .I number
93 (do not insert a space between the "+" sign and
94 the number).
95 This applies only to the next file specified.
96 .TP
97 .BI + line:column
98 Go to the specified
99 .I line
100 and
101 .IR column .
102 .TP
103 .BR \-q ", " \-\-no\-init\-file
104 Do not load an init file.
105 .TP
106 .B \-\-no\-site\-file
107 Do not load the site-wide startup file.
108 .TP
109 .B \-\-no\-desktop
110 Do not load a saved desktop.
111 .TP
112 .BR \-nl ", " \-\-no\-shared\-memory
113 Do not use shared memory.
114 .TP
115 .BR \-Q ", " \-\-quick
116 Equivalent to "\-q \-\-no\-site\-file \-\-no\-splash".
117 .TP
118 .B \-\-no\-splash
119 Do not display a splash screen during start-up.
120 .TP
121 .B \-\-debug\-init
122 Enable
123 .I Emacs
124 Lisp debugger during the processing of the user init file
125 .BR ~/.emacs .
126 This is useful for debugging problems in the init file.
127 .TP
128 .BI \-u " user\fR,\fP " \-\-user " user"
129 Load
130 .IR user 's
131 init file.
132 .TP
133 .BI \-t " file\fR,\fP " \-\-terminal " file"
134 Use specified
135 .I file
136 as the terminal instead of using stdin/stdout.
137 This must be the first argument specified in the command line.
138 .TP
139 .BR \-\-multibyte ", " \-\-no-unibyte
140 Enable multibyte mode (enabled by default).
141 .TP
142 .BR \-\-unibyte ", " \-\-no-multibyte
143 Enable unibyte mode.
144 .TP
145 .B \-\-version
146 Display
147 .I Emacs
148 version information and exit.
149 .TP
150 .B \-\-help
151 Display this help and exit.
152 .RE
153 .PP
154 The following options are lisp-oriented
155 (these options are processed in the order encountered):
156 .RS
157 .TP 8
158 .BI \-f " function\fR,\fP " \-\-funcall " function"
159 Execute the lisp function
160 .IR function .
161 .TP
162 .BI \-l " file\fR,\fP " \-\-load " file"
163 Load the lisp code in the file
164 .IR file .
165 .TP
166 .BI \-\-eval " expr\fR,\fP " \-\-execute " expr"
167 Evaluate the Lisp expression
168 .IR expr .
169 .RE
170 .PP
171 The following options are useful when running
172 .I Emacs
173 as a batch editor:
174 .RS
175 .TP 8
176 .B \-\-batch
177 Edit in batch mode.
178 The editor will send messages to stderr.
179 This option must be the first in the argument list.
180 You must use \-l and \-f options to specify files to execute
181 and functions to call.
182 .TP
183 .BI \-\-script " file"
184 Run
185 .I file
186 as an Emacs Lisp script.
187 .TP
188 .BI \-\-insert " file"
189 Insert contents of
190 .I file
191 into the current buffer.
192 .TP
193 .B \-\-kill
194 Exit
195 .I Emacs
196 while in batch mode.
197 .TP
198 .BI \-L " dir\fR,\fP " \-\-directory " dir"
199 Add
200 .I dir
201 to the list of directories
202 .I Emacs
203 searches for Lisp files.
204 .RE
205 .
206 .\" START DELETING HERE IF YOU'RE NOT USING X
207 .SS Using Emacs with X
208 .I Emacs
209 has been tailored to work well with the X window system.
210 If you run
211 .I Emacs
212 from under X windows, it will create its own X window to
213 display in.
214 You will probably want to start the editor as a background
215 process so that you can continue using your original window.
216 .PP
217 .I Emacs
218 can be started with the following X switches:
219 .RS
220 .TP 8
221 .BI \-\-name " name"
222 Specify the name which should be assigned to the initial
223 .I Emacs
224 window.
225 This controls looking up X resources as well as the window title.
226 .TP
227 .BI \-T " name\fR,\fP " \-\-title " name"
228 Specify the title for the initial X window.
229 .TP
230 .BR \-r ", " \-rv ", " \-\-reverse\-video
231 Display the
232 .I Emacs
233 window in reverse video.
234 .TP
235 .BI \-fn " font\fR,\fP " \-\-font " font"
236 Set the
237 .I Emacs
238 window's font to that specified by
239 .IR font .
240 You will find the various
241 .I X
242 fonts in the
243 .I /usr/lib/X11/fonts
244 directory.
245 Note that
246 .I Emacs
247 will only accept fixed width fonts.
248 Under the X11 Release 4 font-naming conventions, any font with the
249 value "m" or "c" in the eleventh field of the font name is a fixed
250 width font.
251 Furthermore, fonts whose name are of the form
252 .IR width x height
253 are generally fixed width, as is the font
254 .IR fixed .
255 See
256 .BR xlsfonts (1)
257 for more information.
259 When you specify a font, be sure to put a space between the
260 switch and the font name.
261 .TP
262 .BI \-\-xrm " resources"
263 Set additional X resources.
264 .TP
265 .BI "\-\-color\fR,\fP \-\-color=" mode
266 Override color mode for character terminals;
267 .I mode
268 defaults to `auto', and can also be `never', `auto', `always',
269 or a mode name like `ansi8'.
270 .TP
271 .BI \-bw " pixels\fR,\fP " \-\-border\-width " pixels"
272 Set the
273 .I Emacs
274 window's border width to the number of pixels specified by
275 .IR pixels .
276 Defaults to one pixel on each side of the window.
277 .TP
278 .BI \-ib " pixels\fR,\fP " \-\-internal\-border " pixels"
279 Set the window's internal border width to the number of pixels specified
280 by
281 .IR pixels .
282 Defaults to one pixel of padding on each side of the window.
283 .TP
284 .BI \-g " geometry\fR,\fP " \-\-geometry " geometry"
285 Set the
286 .I Emacs
287 window's width, height, and position as specified.
288 The geometry specification is in the standard X format; see
289 .BR X (7)
290 for more information.
291 The width and height are specified in characters; the default is
292 80 by 24.
293 See the Emacs manual, section "Options for Window Size and Position",
294 for information on how window sizes interact
295 with selecting or deselecting the tool bar and menu bar.
296 .TP
297 .BI \-lsp " pixels\fR,\fP " \-\-line\-spacing " pixels"
298 Additional space to put between lines.
299 .TP
300 .BR \-vb ", " \-\-vertical\-scroll\-bars
301 Enable vertical scrollbars.
302 .TP
303 .BR \-fh ", " \-\-fullheight
304 Make the first frame as high as the screen.
305 .TP
306 .BR \-fs ", " \-\-fullscreen
307 Make the first frame fullscreen.
308 .TP
309 .BR \-fw ", " \-\-fullwidth
310 Make the first frame as wide as the screen.
311 .TP
312 .BI \-fg " color\fR,\fP " \-\-foreground\-color " color"
313 On color displays, set the color of the text.
315 Use the command
316 .I M\-x list\-colors\-display
317 for a list of valid color names.
318 .TP
319 .BI \-bg " color\fR,\fP " \-\-background\-color " color"
320 On color displays, set the color of the window's background.
321 .TP
322 .BI \-bd " color\fR,\fP " \-\-border\-color " color"
323 On color displays, set the color of the window's border.
324 .TP
325 .BI \-cr " color\fR,\fP " \-\-cursor\-color " color"
326 On color displays, set the color of the window's text cursor.
327 .TP
328 .BI \-ms " color\fR,\fP " \-\-mouse\-color " color"
329 On color displays, set the color of the window's mouse cursor.
330 .TP
331 .BI \-d " displayname\fR,\fP " \-\-display " displayname"
332 Create the
333 .I Emacs
334 window on the display specified by
335 .IR displayname .
336 Must be the first option specified in the command line.
337 .TP
338 .BR \-nbi ", " \-\-no\-bitmap\-icon
339 Do not use picture of gnu for Emacs icon.
340 .TP
341 .B \-\-iconic
342 Start
343 .I Emacs
344 in iconified state.
345 .TP
346 .BR \-nbc ", " \-\-no\-blinking\-cursor
347 Disable blinking cursor.
348 .TP
349 .BR \-nw ", " \-\-no\-window\-system
350 Tell
351 .I Emacs
352 not to use its special interface to X.
353 If you use this switch when invoking
354 .I Emacs
355 from an
356 .BR xterm (1)
357 window, display is done in that window.
358 .TP
359 .BR \-D ", " \-\-basic\-display
360 This option disables many display features; use it for
361 debugging Emacs.
362 .RE
363 .PP
364 You can set
365 .I X
366 default values for your
367 .I Emacs
368 windows in your
369 .I \.Xresources
370 file (see
371 .BR xrdb (1)).
372 Use the following format:
373 .IP
374 .RI emacs. keyword : value
375 .PP
376 where
377 .I value
378 specifies the default value of
379 .IR keyword .
380 .I Emacs
381 lets you set default values for the following keywords:
382 .RS
383 .TP 8
384 .BR background " (class " Background )
385 For color displays,
386 sets the window's background color.
387 .TP
388 .BR bitmapIcon " (class " BitmapIcon )
389 If
390 .BR bitmapIcon 's
391 value is set to
392 .IR on ,
393 the window will iconify into the "kitchen sink."
394 .TP
395 .BR borderColor " (class " BorderColor )
396 For color displays,
397 sets the color of the window's border.
398 .TP
399 .BR borderWidth " (class " BorderWidth )
400 Sets the window's border width in pixels.
401 .TP
402 .BR cursorColor " (class " Foreground )
403 For color displays,
404 sets the color of the window's text cursor.
405 .TP
406 .BR cursorBlink " (class " CursorBlink )
407 Specifies whether to make the cursor blink.
408 The default is
409 .IR on .
410 Use
411 .I off
412 or
413 .I false
414 to turn cursor blinking off.
415 .TP
416 .BR font " (class " Font )
417 Sets the window's text font.
418 .TP
419 .BR foreground " (class " Foreground )
420 For color displays,
421 sets the window's text color.
422 .TP
423 .BR fullscreen " (class " Fullscreen )
424 The desired fullscreen size.
425 The value can be one of
426 .IR fullboth ,
427 .IR fullwidth ,
428 or
429 .IR fullheight ,
430 which correspond to the command-line options `\-fs', `\-fw', and
431 `\-fh', respectively.
432 Note that this applies to the initial frame only.
433 .TP
434 .BR geometry " (class " Geometry )
435 Sets the geometry of the
436 .I Emacs
437 window (as described above).
438 .TP
439 .BR iconName " (class " Title )
440 Sets the icon name for the
441 .I Emacs
442 window icon.
443 .TP
444 .BR internalBorder " (class " BorderWidth )
445 Sets the window's internal border width in pixels.
446 .TP
447 .BR lineSpacing " (class " LineSpacing )
448 Additional space ("leading") between lines, in pixels.
449 .TP
450 .BR menuBar " (class " MenuBar )
451 Gives frames menu bars if
452 .IR on ;
453 don't have menu bars if
454 .IR off .
455 See the Emacs manual, sections "Lucid Resources" and "LessTif
456 Resources", for how to control the appearance of the menu bar
457 if you have one.
458 .TP
459 .BR minibuffer " (class " Minibuffer )
460 If
461 .IR none ,
462 don't make a minibuffer in this frame.
463 It will use a separate minibuffer frame instead.
464 .TP
465 .BR paneFont " (class " Font )
466 Font name for menu pane titles, in non-toolkit versions of
467 .IR Emacs .
468 .TP
469 .BR pointerColor " (class " Foreground )
470 For color displays,
471 sets the color of the window's mouse cursor.
472 .TP
473 .BR privateColormap " (class " PrivateColormap )
474 If
475 .IR on ,
476 use a private color map, in the case where the "default
477 visual" of class
478 .B PseudoColor
479 and
480 .B Emacs
481 is using it.
482 .TP
483 .BR reverseVideo " (class " ReverseVideo )
484 If
485 .BR reverseVideo 's
486 value is set to
487 .IR on ,
488 the window will be displayed in reverse video.
489 .TP
490 .BR screenGamma " (class "ScreenGamma )
491 Gamma correction for colors, equivalent to the frame parameter
492 `screen\-gamma'.
493 .TP
494 .BR scrollBarWidth " (class "ScrollBarWidth )
495 The scroll bar width in pixels, equivalent to the frame parameter
496 `scroll\-bar\-width'.
497 .TP
498 .BR selectionFont " (class " SelectionFont )
499 Font name for pop-up menu items, in non-toolkit versions of
500 .IR Emacs .
501 (For toolkit versions, see the Emacs manual, sections
502 "Lucid Resources" and "LessTif Resources".)
503 .TP
504 .BR selectionTimeout " (class " SelectionTimeout )
505 Number of milliseconds to wait for a selection reply.
506 A value of 0 means wait as long as necessary.
507 .TP
508 .BR synchronous " (class " Synchronous )
509 Run Emacs in synchronous mode if
510 .IR on .
511 Synchronous mode is useful for debugging X problems.
512 .TP
513 .BR title " (class " Title )
514 Sets the title of the
515 .I Emacs
516 window.
517 .TP
518 .BR toolBar " (class " ToolBar )
519 Number of lines to reserve for the tool bar.
520 .TP
521 .BR useXIM " (class " UseXIM )
522 Turns off use of X input methods (XIM) if
523 .I false
524 or
525 .IR off .
526 .TP
527 .BR verticalScrollBars " (class " ScrollBars )
528 Gives frames scroll bars if
529 .IR on ;
530 suppresses scroll bars if
531 .IR off .
532 .TP
533 .BR visualClass " (class " VisualClass )
534 Specify the "visual" that X should use.
535 This tells X how to handle colors.
536 The value should start with one of
537 .IR TrueColor ,
538 .IR PseudoColor ,
539 .IR DirectColor ,
540 .IR StaticColor ,
541 .IR GrayScale ,
542 and
543 .IR StaticGray ,
544 followed by
545 .BI \- depth\fR,\fP
546 where
547 .I depth
548 is the number of color planes.
549 .RE
550 .PP
551 If you try to set color values while using a black and white display,
552 the window's characteristics will default as follows:
553 the foreground color will be set to black,
554 the background color will be set to white,
555 the border color will be set to grey,
556 and the text and mouse cursors will be set to black.
557 .
558 .SS Using the Mouse
559 .PP
560 The following lists some of the mouse button bindings for the
561 .I Emacs
562 window under X11.
563 .
564 .RS
565 .TS
566 l l
567 - -
568 l l.
569 MOUSE BUTTON FUNCTION
570 left Set point.
571 middle Paste text.
572 right Cut text into X cut buffer.
573 SHIFT-middle Cut text into X cut buffer.
574 SHIFT-right Paste text.
575 CTRL-middle Cut text into X cut buffer and kill it.
576 CTRL-right T{
577 Select this window, then split it into two windows.
578 Same as typing CTRL\-x 2.
579 T}
580 .\" START DELETING HERE IF YOU'RE NOT USING X MENUS
581 CTRL-SHIFT-left T{
582 X buffer menu \(em hold the buttons and keys
583 down, wait for menu to appear, select buffer, and release.
584 Move mouse out of menu and release to cancel.
585 T}
586 CTRL-SHIFT-middle T{
587 X help menu \(em pop up index card menu for Emacs help.
588 T}
589 .\" STOP DELETING HERE IF YOU'RE NOT USING X MENUS
590 CTRL-SHIFT-right T{
591 Select window with mouse, and delete all other windows.
592 Same as typing CTRL\-x 1.
593 T}
594 .\" STOP DELETING HERE IF YOU'RE NOT USING X
595 .TE
596 .RE
597 .
598 .
599 .SH MANUALS
600 You can order printed copies of the GNU Emacs Manual from the Free
601 Software Foundation, which develops GNU software.
602 See the file ORDERS for ordering information.
603 .br
604 Your local Emacs maintainer might also have copies available.
605 As with all software and publications from FSF, everyone is permitted
606 to make and distribute copies of the Emacs manual.
607 The TeX source to the manual is also included in the Emacs source
608 distribution.
609 .
610 .
611 .SH FILES
612 /usr/local/share/info \(em files for the Info documentation browser.
613 The complete text of the Emacs reference manual is included in a
614 convenient tree structured form.
615 Also includes the Emacs Lisp Reference Manual, useful to anyone
616 wishing to write programs in the Emacs Lisp extension language.
618 /usr/local/share/emacs/$VERSION/lisp \(em Lisp source files and
619 compiled files that define most editing commands.
620 Some are preloaded; others are autoloaded from this directory when
621 used.
623 /usr/local/libexec/emacs/$VERSION/$ARCH \(em various programs that are
624 used with GNU Emacs.
626 /usr/local/share/emacs/$VERSION/etc \(em various files of information.
628 /usr/local/share/emacs/$VERSION/etc/DOC.* \(em contains the documentation
629 strings for the Lisp primitives and preloaded Lisp functions
630 of GNU Emacs.
631 They are stored here to reduce the size of Emacs proper.
633 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
634 various services to assist users of GNU Emacs, including education,
635 troubleshooting, porting and customization.
636 .
637 .
638 .SH BUGS
639 There is a mailing list, bug-gnu-emacs@gnu.org, for reporting Emacs
640 bugs and fixes.
641 But before reporting something as a bug, please try to be sure that
642 it really is a bug, not a misunderstanding or a deliberate feature.
643 We ask you to read the section ``Reporting Emacs Bugs'' near the
644 end of the reference manual (or Info system) for hints on how and
645 when to report bugs.
646 Also, include the version number of the Emacs you are running in
647 \fIevery\fR bug report that you send in.
648 Bugs tend actually to be fixed if they can be isolated, so it is
649 in your interest to report them in such a way that they can be
650 easily reproduced.
652 Do not expect a personal answer to a bug report.
653 The purpose of reporting bugs is to get them fixed for everyone
654 in the next release, if possible.
655 For personal assistance, look in the SERVICE file (see above) for
656 a list of people who offer it.
658 Please do not send anything but bug reports to this mailing list.
659 For more information about Emacs mailing lists, see the
660 file /usr/local/share/emacs/$VERSION/etc/MAILINGLISTS.
661 .
662 .
663 .SH UNRESTRICTIONS
664 .I Emacs
665 is free; anyone may redistribute copies of
666 .I Emacs
667 to
668 anyone under the terms stated in the
669 .I Emacs
670 General Public License,
671 a copy of which accompanies each copy of
672 .I Emacs
673 and which also
674 appears in the reference manual.
675 .PP
676 Copies of
677 .I Emacs
678 may sometimes be received packaged with distributions of Unix systems,
679 but it is never included in the scope of any license covering those
680 systems.
681 Such inclusion violates the terms on which distribution is permitted.
682 In fact, the primary purpose of the General Public License is to
683 prohibit anyone from attaching any other restrictions to
684 redistribution of
685 .IR Emacs .
686 .PP
687 Richard Stallman encourages you to improve and extend
688 .IR Emacs ,
689 and urges that
690 you contribute your extensions to the GNU library.
691 Eventually GNU (Gnu's Not Unix) will be a complete replacement
692 for Unix.
693 Everyone will be free to use, copy, study and change the GNU system.
694 .
695 .
696 .SH SEE ALSO
697 .BR emacsclient (1),
698 .BR etags (1),
699 .BR X (7),
700 .BR xlsfonts (1),
701 .BR xterm (1),
702 .BR xrdb (1)
703 .
704 .
705 .SH AUTHORS
706 .I Emacs
707 was written by Richard Stallman and the Free Software Foundation.
708 Joachim Martillo and Robert Krawitz added the X features.
709 .
710 .
711 .SH COPYING
712 Copyright
713 .if t \(co
714 .if n (C)
715 1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
716 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
717 .PP
718 Permission is granted to make and distribute verbatim copies of this
719 document provided the copyright notice and this permission notice are
720 preserved on all copies.
721 .PP
722 Permission is granted to copy and distribute modified versions of
723 this document under the conditions for verbatim copying, provided that
724 the entire resulting derived work is distributed under the terms of
725 a permission notice identical to this one.
726 .PP
727 Permission is granted to copy and distribute translations of this
728 document into another language, under the above conditions for
729 modified versions, except that this permission notice may be stated
730 in a translation approved by the Free Software Foundation.
731 .
732 .\" arch-tag: 04dfd376-b46e-4924-919a-cecc3b257eaa