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