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