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