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