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