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