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