| blob | 2a0c0e962e24c70e193fcee7968d9f53f47671c6 |
1 .\" Copyright (C) 1995, 1999, 2000, 2001 Free Software Foundation, Inc.
2 .\"
3 .\" This file is part of GNU Emacs.
4 .\"
5 .\" GNU Emacs is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License as published by
7 .\" the Free Software Foundation; either version 2, or (at your option)
8 .\" any later version.
9 .\"
10 .\" GNU Emacs is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 .\" GNU General Public License for more details.
14 .\"
15 .\" You should have received a copy of the GNU General Public License
16 .\" along with GNU Emacs; see the file COPYING. If not, write to the
17 .\" Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 .\" Boston, MA 02111-1307, USA.
19 .\"
20 '\" t
21 .TH EMACS 1 "2001 November 23"
22 .UC 4
23 .SH NAME
24 emacs \- GNU project Emacs
25 .SH SYNOPSIS
26 .B emacs
27 [
28 .I command-line switches
29 ] [
30 .I files ...
31 ]
32 .br
33 .SH DESCRIPTION
34 .I GNU Emacs
35 is a version of
36 .I Emacs,
37 written by the author of the original (PDP-10)
38 .I Emacs,
39 Richard Stallman.
40 .br
41 The primary documentation of GNU Emacs is in the GNU Emacs Manual,
42 which you can read on line using Info, a subsystem of Emacs. Please
43 look there for complete and up-to-date documentation. This man page
44 is updated only when someone volunteers to do so; the Emacs
45 maintainers' priority goal is to minimize the amount of time this man
46 page takes away from other more useful projects.
47 .br
48 The user functionality of GNU Emacs encompasses
49 everything other
50 .I Emacs
51 editors do, and it is easily extensible since its
52 editing commands are written in Lisp.
53 .PP
54 .I Emacs
55 has an extensive interactive help facility,
56 but the facility assumes that you know how to manipulate
57 .I Emacs
58 windows and buffers.
59 CTRL-h or F1 enters the Help facility. Help Tutorial (CTRL-h t)
60 requests an interactive tutorial which can teach beginners the fundamentals
61 of
62 .I Emacs
63 in a few minutes.
64 Help Apropos (CTRL-h a) helps you
65 find a command given its functionality, Help Character (CTRL-h c)
66 describes a given character's effect, and Help Function (CTRL-h f)
67 describes a given Lisp function specified by name.
68 .PP
69 .I Emacs's
70 Undo can undo several steps of modification to your buffers, so it is
71 easy to recover from editing mistakes.
72 .PP
73 .I GNU Emacs's
74 many special packages handle mail reading (RMail) and sending (Mail),
75 outline editing (Outline), compiling (Compile), running subshells
76 within
77 .I Emacs
78 windows (Shell), running a Lisp read-eval-print loop
79 (Lisp-Interaction-Mode), and automated psychotherapy (Doctor).
80 .PP
81 There is an extensive reference manual, but
82 users of other Emacses
83 should have little trouble adapting even
84 without a copy. Users new to
85 .I Emacs
86 will be able
87 to use basic features fairly rapidly by studying the tutorial and
88 using the self-documentation features.
89 .PP
90 .SM Emacs Options
91 .PP
92 The following options are of general interest:
93 .TP 8
94 .I file
95 Edit
96 .I file.
97 .TP
98 .BI \+ number
99 Go to the line specified by
100 .I number
101 (do not insert a space between the "+" sign and
102 the number).
103 .TP
104 .BI \+ line:column
105 Go to the specified
106 .I line
107 and
108 .I column
109 .TP
110 .B \-q
111 Do not load an init file.
112 .TP
113 .B \-no-site-file
114 Do not load the site-wide startup file.
115 .TP
116 .BI \-debug-init
117 Enable
118 .I Emacs
119 Lisp debugger during the processing of the user init file
120 .BI ~/.emacs.
121 This is useful for debugging problems in the init file.
122 .TP
123 .BI \-u " user"
124 Load
125 .I user's
126 init file.
127 .TP
128 .BI \-t " file"
129 Use specified
130 .I file
131 as the terminal instead of using stdin/stdout.
132 This must be the first argument specified in the command line.
133 .TP
134 .B \-version
135 Display
136 .I Emacs
137 version information and exit.
138 .PP
139 The following options are lisp-oriented
140 (these options are processed in the order encountered):
141 .TP 8
142 .BI \-f " function"
143 Execute the lisp function
144 .I function.
145 .TP
146 .BI \-l " file"
147 Load the lisp code in the file
148 .I file.
149 .TP
150 .BI \-eval " expr"
151 Evaluate the Lisp expression
152 .I expr.
153 .PP
154 The following options are useful when running
155 .I Emacs
156 as a batch editor:
157 .TP 8
158 .BI \-batch
159 Edit in batch mode. The editor will send messages to stderr. This
160 option must be the first in the argument list. You must use -l and -f
161 options to specify files to execute and functions to call.
162 .TP
163 .B \-kill
164 Exit
165 .I Emacs
166 while in batch mode.
167 .TP
168 .BI \-L " directory"
169 Add
170 .I directory
171 to the list of directories
172 .I Emacs
173 searches for Lisp files.
174 .\" START DELETING HERE IF YOU'RE NOT USING X
175 .PP
176 .SM Using Emacs with X
177 .PP
178 .I Emacs
179 has been tailored to work well with the X window system.
180 If you run
181 .I Emacs
182 from under X windows, it will create its own X window to
183 display in. You will probably want to start the editor
184 as a background process
185 so that you can continue using your original window.
186 .PP
187 .I Emacs
188 can be started with the following X switches:
189 .TP 8
190 .BI \-name " name"
191 Specifies the name which should be assigned to the initial
192 .I Emacs
193 window. This controls looking up X resources as well as the window title.
194 .TP 8
195 .BI \-title " name"
196 Specifies the title for the initial X window.
197 .TP 8
198 .B \-r
199 Display the
200 .I Emacs
201 window in reverse video.
202 .TP
203 .B \-i
204 Use the "kitchen sink" bitmap icon when iconifying the
205 .I Emacs
206 window.
207 .TP
208 .BI \-font " font, " \-fn " font"
209 Set the
210 .I Emacs
211 window's font to that specified by
212 .I font.
213 You will find the various
214 .I X
215 fonts in the
216 .I /usr/lib/X11/fonts
217 directory.
218 Note that
219 .I Emacs
220 will only accept fixed width fonts.
221 Under the X11 Release 4 font-naming conventions, any font with the
222 value "m" or "c" in the eleventh field of the font name is a fixed
223 width font. Furthermore, fonts whose name are of the form
224 .IR width x height
225 are generally fixed width, as is the font
226 .IR fixed .
227 See
228 .IR xlsfonts (1)
229 for more information.
231 When you specify a font, be sure to put a space between the
232 switch and the font name.
233 .TP
234 .BI \-bw " pixels"
235 Set the
236 .I Emacs
237 window's border width to the number of pixels specified by
238 .I pixels.
239 Defaults to one pixel on each side of the window.
240 .TP
241 .BI \-ib " pixels"
242 Set the window's internal border width to the number of pixels specified
243 by
244 .I pixels.
245 Defaults to one pixel of padding on each side of the window.
246 .PP
247 .TP 8
248 .BI \-\-geometry " geometry"
249 Set the
250 .I Emacs
251 window's width, height, and position as specified. The geometry
252 specification is in the standard X format; see
253 .IR X (1)
254 for more information.
255 The width and height are specified in characters; the default is 80 by
256 24. See the Emacs manual, section "Options for Window Size and Position",
257 for information on how window sizes interact
258 with selecting or deselecting the tool bar and menu bar.
259 .PP
260 .TP 8
261 .BI \-fg " color"
262 On color displays, sets the color of the text.
264 See the file
265 .I /usr/lib/X11/rgb.txt
266 for a list of valid
267 color names.
268 .TP
269 .BI \-bg " color"
270 On color displays,
271 sets the color of the window's background.
272 .TP
273 .BI \-bd " color"
274 On color displays,
275 sets the color of the window's border.
276 .TP
277 .BI \-cr " color"
278 On color displays,
279 sets the color of the window's text cursor.
280 .TP
281 .BI \-ms " color"
282 On color displays,
283 sets the color of the window's mouse cursor.
284 .TP
285 .BI \-d " displayname, " \-display " displayname"
286 Create the
287 .I Emacs
288 window on the display specified by
289 .IR displayname .
290 Must be the first option specified in the command line.
291 .TP
292 .B \-nw
293 Tells
294 .I Emacs
295 not to use its special interface to X. If you use this
296 switch when invoking
297 .I Emacs
298 from an
299 .IR xterm (1)
300 window, display is done in that window.
301 This must be the first option specified in the command line.
302 .PP
303 You can set
304 .I X
305 default values for your
306 .I Emacs
307 windows in your
308 .I \.Xresources
309 file (see
310 .IR xrdb (1)).
311 Use the following format:
312 .IP
313 emacs.keyword:value
314 .PP
315 where
316 .I value
317 specifies the default value of
318 .I keyword.
319 .I Emacs
320 lets you set default values for the following keywords:
321 .TP 8
322 .B font (\fPclass\fB Font)
323 Sets the window's text font.
324 .TP
325 .B reverseVideo (\fPclass\fB ReverseVideo)
326 If
327 .I reverseVideo's
328 value is set to
329 .I on,
330 the window will be displayed in reverse video.
331 .TP
332 .B bitmapIcon (\fPclass\fB BitmapIcon)
333 If
334 .I bitmapIcon's
335 value is set to
336 .I on,
337 the window will iconify into the "kitchen sink."
338 .TP
339 .B borderWidth (\fPclass\fB BorderWidth)
340 Sets the window's border width in pixels.
341 .TP
342 .B internalBorder (\fPclass\fB BorderWidth)
343 Sets the window's internal border width in pixels.
344 .TP
345 .B foreground (\fPclass\fB Foreground)
346 For color displays,
347 sets the window's text color.
348 .TP
349 .B background (\fPclass\fB Background)
350 For color displays,
351 sets the window's background color.
352 .TP
353 .B borderColor (\fPclass\fB BorderColor)
354 For color displays,
355 sets the color of the window's border.
356 .TP
357 .B cursorColor (\fPclass\fB Foreground)
358 For color displays,
359 sets the color of the window's text cursor.
360 .TP
361 .B pointerColor (\fPclass\fB Foreground)
362 For color displays,
363 sets the color of the window's mouse cursor.
364 .TP
365 .B geometry (\fPclass\fB Geometry)
366 Sets the geometry of the
367 .I Emacs
368 window (as described above).
369 .TP
370 .B title (\fPclass\fB Title)
371 Sets the title of the
372 .I Emacs
373 window.
374 .TP
375 .B iconName (\fPclass\fB Title)
376 Sets the icon name for the
377 .I Emacs
378 window icon.
379 .PP
380 If you try to set color values while using a black and white display,
381 the window's characteristics will default as follows:
382 the foreground color will be set to black,
383 the background color will be set to white,
384 the border color will be set to grey,
385 and the text and mouse cursors will be set to black.
386 .PP
387 .SM Using the Mouse
388 .PP
389 The following lists the mouse button bindings for the
390 .I Emacs
391 window under X11.
393 .TS
394 l l.
395 MOUSE BUTTON FUNCTION
396 left Set point.
397 middle Paste text.
398 right Cut text into X cut buffer.
399 SHIFT-middle Cut text into X cut buffer.
400 SHIFT-right Paste text.
401 CTRL-middle Cut text into X cut buffer and kill it.
402 CTRL-right T{
403 Select this window, then split it into
404 two windows. Same as typing CTRL-x 2.
405 T}
406 .\" START DELETING HERE IF YOU'RE NOT USING X MENUS
407 CTRL-SHIFT-left T{
408 X buffer menu--hold the buttons and keys
409 down, wait for menu to appear, select
410 buffer, and release. Move mouse out of
411 menu and release to cancel.
412 T}
413 CTRL-SHIFT-middle X help menu--pop up index card menu for Emacs help.
414 .\" STOP DELETING HERE IF YOU'RE NOT USING X MENUS
415 CTRL-SHIFT-right T{
416 Select window with mouse, and delete all
417 other windows. Same as typing CTRL-x 1.
418 T}
419 .\" STOP DELETING HERE IF YOU'RE NOT USING X
420 .TE
421 .PP
422 .SH MANUALS
423 You can order printed copies of the GNU Emacs Manual from the Free
424 Software Foundation, which develops GNU software. See the file ORDERS
425 for ordering information.
426 .br
427 Your local Emacs maintainer might also have copies available. As
428 with all software and publications from FSF, everyone is permitted to
429 make and distribute copies of the Emacs manual. The TeX source to the
430 manual is also included in the Emacs source distribution.
431 .PP
432 .SH FILES
433 /usr/local/info - files for the Info documentation browser
434 (a subsystem of Emacs) to refer to. Currently not much of Unix
435 is documented here, but the complete text of the Emacs reference
436 manual is included in a convenient tree structured form.
438 /usr/local/share/emacs/$VERSION/src - C source files and object files
440 /usr/local/share/emacs/$VERSION/lisp - Lisp source files and compiled files
441 that define most editing commands. Some are preloaded;
442 others are autoloaded from this directory when used.
444 /usr/local/share/emacs/$VERSION/etc - various programs that are used with
445 GNU Emacs, and some files of information.
447 /usr/local/share/emacs/$VERSION/etc/DOC.* - contains the documentation
448 strings for the Lisp primitives and preloaded Lisp functions
449 of GNU Emacs. They are stored here to reduce the size of
450 Emacs proper.
452 /usr/local/share/emacs/$VERSION/etc/OTHER.EMACSES discusses GNU Emacs
453 vs. other versions of Emacs.
454 .br
455 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
456 various services to assist users of GNU Emacs, including education,
457 troubleshooting, porting and customization.
458 .br
459 These files also have information useful to anyone wishing to write
460 programs in the Emacs Lisp extension language, which has not yet been fully
461 documented.
463 /usr/local/com/emacs/lock - holds lock files that are made for all
464 files being modified in Emacs, to prevent simultaneous modification
465 of one file by two users.
467 .\" START DELETING HERE IF YOU'RE NOT USING X
468 /usr/lib/X11/rgb.txt - list of valid X color names.
469 .\" STOP DELETING HERE IF YOU'RE NOT USING X
470 .PP
471 .SH BUGS
472 There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the internet
473 (ucbvax!prep.ai.mit.edu!bug-gnu-emacs on UUCPnet), for reporting Emacs
474 bugs and fixes. But before reporting something as a bug, please try
475 to be sure that it really is a bug, not a misunderstanding or a
476 deliberate feature. We ask you to read the section ``Reporting Emacs
477 Bugs'' near the end of the reference manual (or Info system) for hints
478 on how and when to report bugs. Also, include the version number of
479 the Emacs you are running in \fIevery\fR bug report that you send in.
481 Do not expect a personal answer to a bug report. The purpose of reporting
482 bugs is to get them fixed for everyone in the next release, if possible.
483 For personal assistance, look in the SERVICE file (see above) for
484 a list of people who offer it.
486 Please do not send anything but bug reports to this mailing list.
487 Send requests to be added to mailing lists to the special list
488 info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP
489 address). For more information about Emacs mailing lists, see the
490 file /usr/local/emacs/etc/MAILINGLISTS. Bugs tend actually to be
491 fixed if they can be isolated, so it is in your interest to report
492 them in such a way that they can be easily reproduced.
493 .PP
494 Bugs that I know about are: shell will not work with programs
495 running in Raw mode on some Unix versions.
496 .SH UNRESTRICTIONS
497 .PP
498 .I Emacs
499 is free; anyone may redistribute copies of
500 .I Emacs
501 to
502 anyone under the terms stated in the
503 .I Emacs
504 General Public License,
505 a copy of which accompanies each copy of
506 .I Emacs
507 and which also
508 appears in the reference manual.
509 .PP
510 Copies of
511 .I Emacs
512 may sometimes be received packaged with distributions of Unix systems,
513 but it is never included in the scope of any license covering those
514 systems. Such inclusion violates the terms on which distribution
515 is permitted. In fact, the primary purpose of the General Public
516 License is to prohibit anyone from attaching any other restrictions
517 to redistribution of
518 .I Emacs.
519 .PP
520 Richard Stallman encourages you to improve and extend
521 .I Emacs,
522 and urges that
523 you contribute your extensions to the GNU library. Eventually GNU
524 (Gnu's Not Unix) will be a complete replacement for Berkeley
525 Unix.
526 Everyone will be free to use, copy, study and change the GNU system.
527 .SH SEE ALSO
528 X(1), xlsfonts(1), xterm(1), xrdb(1)
529 .SH AUTHORS
530 .PP
531 .I Emacs
532 was written by Richard Stallman and the Free Software Foundation.
533 Joachim Martillo and Robert Krawitz added the X features.
534 .SH COPYING
535 Copyright
536 .if t \(co
537 .if n (c)
538 1995, 1999, 2000, 2001 Free Software Foundation, Inc.
539 .PP
540 Permission is granted to make and distribute verbatim copies of this
541 document provided the copyright notice and this permission notice are
542 preserved on all copies.
543 .PP
544 Permission is granted to copy and distribute modified versions of
545 this document under the conditions for verbatim copying, provided that
546 the entire resulting derived work is distributed under the terms of
547 a permission notice identical to this one.
548 .PP
549 Permission is granted to copy and distribute translations of this
550 document into another language, under the above conditions for
551 modified versions, except that this permission notice may be stated
552 in a translation approved by the Free Software Foundation.