*** empty log message ***
[emacs.git] / etc / emacs.1
blob2c3bbe2bedae093bdfc505e3b60acd2cdbbadeb0
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
28 .I command-line switches
29 ] [
30 .I files ...
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).
104 .BI \+ line:column
105 Go to the specified
106 .I line
108 .I column
110 .B \-q
111 Do not load an init file.
113 .B \-no-site-file
114 Do not load the site-wide startup file.
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.
123 .BI \-u " user"
124 Load
125 .I user's
126 init file.
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.
134 .B \-version
135 Display
136 .I Emacs
137 version information and exit.
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.
146 .BI \-l " file"
147 Load the lisp code in the file
148 .I file.
150 .BI \-eval " expr"
151 Evaluate the Lisp expression
152 .I expr.
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.
163 .B \-kill
164 Exit 
165 .I Emacs 
166 while in batch mode.
168 .BI \-L " directory"
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
176 .SM Using Emacs with X
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.
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.
203 .B \-i
204 Use the "kitchen sink" bitmap icon when iconifying the
205 .I Emacs
206 window.
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 .
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.
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.
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.
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
258 .TP 8
259 .BI \-fg " color"
260 On color displays, sets the color of the text.
262 See the file
263 .I /usr/lib/X11/rgb.txt
264 for a list of valid
265 color names.
267 .BI \-bg " color"
268 On color displays,
269 sets the color of the window's background.
271 .BI \-bd " color"
272 On color displays,
273 sets the color of the window's border.
275 .BI \-cr " color"
276 On color displays,
277 sets the color of the window's text cursor.
279 .BI \-ms " color"
280 On color displays,
281 sets the color of the window's mouse cursor.
283 .BI \-d " displayname, " \-display " displayname"
284 Create the
285 .I Emacs
286 window on the display specified by
287 .IR displayname .
288 Must be the first option specified in the command line.
290 .B \-nw
291 Tells
292 .I Emacs
293 not to use its special interface to X.  If you use this
294 switch when invoking
295 .I Emacs
296 from an
297 .IR xterm (1)
298 window, display is done in that window.
299 This must be the first option specified in the command line.
301 You can set
302 .I X
303 default values for your
304 .I Emacs
305 windows in your
306 .I \.Xresources
307 file (see
308 .IR xrdb (1)).
309 Use the following format:
311 emacs.keyword:value
313 where
314 .I value
315 specifies the default value of
316 .I keyword.
317 .I Emacs
318 lets you set default values for the following keywords:
319 .TP 8
320 .B font (\fPclass\fB Font)
321 Sets the window's text font.
323 .B reverseVideo (\fPclass\fB ReverseVideo)
325 .I reverseVideo's
326 value is set to
327 .I on,
328 the window will be displayed in reverse video.
330 .B bitmapIcon (\fPclass\fB BitmapIcon)
332 .I bitmapIcon's
333 value is set to
334 .I on,
335 the window will iconify into the "kitchen sink."
337 .B borderWidth (\fPclass\fB BorderWidth)
338 Sets the window's border width in pixels.
340 .B internalBorder (\fPclass\fB BorderWidth)
341 Sets the window's internal border width in pixels.
343 .B foreground (\fPclass\fB Foreground)
344 For color displays,
345 sets the window's text color.
347 .B background (\fPclass\fB Background)
348 For color displays,
349 sets the window's background color.
351 .B borderColor (\fPclass\fB BorderColor)
352 For color displays,
353 sets the color of the window's border.
355 .B cursorColor (\fPclass\fB Foreground)
356 For color displays,
357 sets the color of the window's text cursor.
359 .B pointerColor (\fPclass\fB Foreground)
360 For color displays,
361 sets the color of the window's mouse cursor.
363 .B geometry (\fPclass\fB Geometry)
364 Sets the geometry of the
365 .I Emacs
366 window (as described above).
368 .B title (\fPclass\fB Title)
369 Sets the title of the
370 .I Emacs
371 window.
373 .B iconName (\fPclass\fB Title)
374 Sets the icon name for the
375 .I Emacs
376 window icon.
378 If you try to set color values while using a black and white display,
379 the window's characteristics will default as follows:
380 the foreground color will be set to black,
381 the background color will be set to white,
382 the border color will be set to grey,
383 and the text and mouse cursors will be set to black.
385 .SM Using the Mouse 
387 The following lists the mouse button bindings for the
388 .I Emacs
389 window under X11.
392 l l.
393 MOUSE BUTTON    FUNCTION
394 left    Set point.
395 middle  Paste text.
396 right   Cut text into X cut buffer.
397 SHIFT-middle    Cut text into X cut buffer.
398 SHIFT-right     Paste text.
399 CTRL-middle     Cut text into X cut buffer and kill it.
400 CTRL-right      T{
401 Select this window, then split it into 
402 two windows.  Same as typing CTRL-x 2.
404 .\" START DELETING HERE IF YOU'RE NOT USING X MENUS
405 CTRL-SHIFT-left T{
406 X buffer menu--hold the buttons and keys
407 down, wait for menu to appear, select 
408 buffer, and release.  Move mouse out of
409 menu and release to cancel.
411 CTRL-SHIFT-middle       X help menu--pop up index card menu for Emacs help.
412 .\" STOP DELETING HERE IF YOU'RE NOT USING X MENUS
413 CTRL-SHIFT-right        T{
414 Select window with mouse, and delete all
415 other windows.  Same as typing CTRL-x 1.
417 .\" STOP DELETING HERE IF YOU'RE NOT USING X
420 .SH MANUALS
421 You can order printed copies of the GNU Emacs Manual from the Free
422 Software Foundation, which develops GNU software.  See the file ORDERS
423 for ordering information.
425 Your local Emacs maintainer might also have copies available.  As
426 with all software and publications from FSF, everyone is permitted to
427 make and distribute copies of the Emacs manual.  The TeX source to the
428 manual is also included in the Emacs source distribution.
430 .SH FILES
431 /usr/local/info - files for the Info documentation browser
432 (a subsystem of Emacs) to refer to.  Currently not much of Unix
433 is documented here, but the complete text of the Emacs reference
434 manual is included in a convenient tree structured form.
436 /usr/local/share/emacs/$VERSION/src - C source files and object files
438 /usr/local/share/emacs/$VERSION/lisp - Lisp source files and compiled files
439 that define most editing commands.  Some are preloaded;
440 others are autoloaded from this directory when used.
441   
442 /usr/local/share/emacs/$VERSION/etc - various programs that are used with
443 GNU Emacs, and some files of information.
445 /usr/local/share/emacs/$VERSION/etc/DOC.* - contains the documentation
446 strings for the Lisp primitives and preloaded Lisp functions
447 of GNU Emacs.  They are stored here to reduce the size of
448 Emacs proper.
450 /usr/local/share/emacs/$VERSION/etc/OTHER.EMACSES discusses GNU Emacs
451 vs. other versions of Emacs.
453 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
454 various services to assist users of GNU Emacs, including education,
455 troubleshooting, porting and customization.
457 These files also have information useful to anyone wishing to write
458 programs in the Emacs Lisp extension language, which has not yet been fully
459 documented.
461 /usr/local/com/emacs/lock - holds lock files that are made for all
462 files being modified in Emacs, to prevent simultaneous modification
463 of one file by two users.
465 .\" START DELETING HERE IF YOU'RE NOT USING X
466 /usr/lib/X11/rgb.txt - list of valid X color names.
467 .\" STOP DELETING HERE IF YOU'RE NOT USING X
469 .SH BUGS
470 There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the internet
471 (ucbvax!prep.ai.mit.edu!bug-gnu-emacs on UUCPnet), for reporting Emacs
472 bugs and fixes.  But before reporting something as a bug, please try
473 to be sure that it really is a bug, not a misunderstanding or a
474 deliberate feature.  We ask you to read the section ``Reporting Emacs
475 Bugs'' near the end of the reference manual (or Info system) for hints
476 on how and when to report bugs.  Also, include the version number of
477 the Emacs you are running in \fIevery\fR bug report that you send in.
479 Do not expect a personal answer to a bug report.  The purpose of reporting
480 bugs is to get them fixed for everyone in the next release, if possible.
481 For personal assistance, look in the SERVICE file (see above) for
482 a list of people who offer it.
484 Please do not send anything but bug reports to this mailing list.
485 Send requests to be added to mailing lists to the special list
486 info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP
487 address).  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.
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
496 .I Emacs 
497 is free; anyone may redistribute copies of 
498 .I Emacs 
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.
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.
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
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 Free Software Foundation, Inc.
538 Permission is granted to make and distribute verbatim copies of this
539 document provided the copyright notice and this permission notice are
540 preserved on all copies.
542 Permission is granted to copy and distribute modified versions of
543 this document under the conditions for verbatim copying, provided that
544 the entire resulting derived work is distributed under the terms of
545 a permission notice identical to this one.
547 Permission is granted to copy and distribute translations of this
548 document into another language, under the above conditions for
549 modified versions, except that this permission notice may be stated
550 in a translation approved by the Free Software Foundation.