etc/emacs.1

   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.
 230
 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.
 263
 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.
 392
 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.
 437
 438 /usr/local/share/emacs/$VERSION/src - C source files and object files
 439
 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.
 443
 444 /usr/local/share/emacs/$VERSION/etc - various programs that are used with
 445 GNU Emacs, and some files of information.
 446
 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.
 451
 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.
 462
 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.
 466
 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.
 480
 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.
 485
 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.