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.
 257 .PP
 258 .TP 8
 259 .BI \-fg " color"
 260 On color displays, sets the color of the text.
 261
 262 See the file
 263 .I /usr/lib/X11/rgb.txt
 264 for a list of valid
 265 color names.
 266 .TP
 267 .BI \-bg " color"
 268 On color displays,
 269 sets the color of the window's background.
 270 .TP
 271 .BI \-bd " color"
 272 On color displays,
 273 sets the color of the window's border.
 274 .TP
 275 .BI \-cr " color"
 276 On color displays,
 277 sets the color of the window's text cursor.
 278 .TP
 279 .BI \-ms " color"
 280 On color displays,
 281 sets the color of the window's mouse cursor.
 282 .TP
 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.
 289 .TP
 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.
 300 .PP
 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:
 310 .IP
 311 emacs.keyword:value
 312 .PP
 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.
 322 .TP
 323 .B reverseVideo (\fPclass\fB ReverseVideo)
 324 If
 325 .I reverseVideo's
 326 value is set to
 327 .I on,
 328 the window will be displayed in reverse video.
 329 .TP
 330 .B bitmapIcon (\fPclass\fB BitmapIcon)
 331 If
 332 .I bitmapIcon's
 333 value is set to
 334 .I on,
 335 the window will iconify into the "kitchen sink."
 336 .TP
 337 .B borderWidth (\fPclass\fB BorderWidth)
 338 Sets the window's border width in pixels.
 339 .TP
 340 .B internalBorder (\fPclass\fB BorderWidth)
 341 Sets the window's internal border width in pixels.
 342 .TP
 343 .B foreground (\fPclass\fB Foreground)
 344 For color displays,
 345 sets the window's text color.
 346 .TP
 347 .B background (\fPclass\fB Background)
 348 For color displays,
 349 sets the window's background color.
 350 .TP
 351 .B borderColor (\fPclass\fB BorderColor)
 352 For color displays,
 353 sets the color of the window's border.
 354 .TP
 355 .B cursorColor (\fPclass\fB Foreground)
 356 For color displays,
 357 sets the color of the window's text cursor.
 358 .TP
 359 .B pointerColor (\fPclass\fB Foreground)
 360 For color displays,
 361 sets the color of the window's mouse cursor.
 362 .TP
 363 .B geometry (\fPclass\fB Geometry)
 364 Sets the geometry of the
 365 .I Emacs
 366 window (as described above).
 367 .TP
 368 .B title (\fPclass\fB Title)
 369 Sets the title of the
 370 .I Emacs
 371 window.
 372 .TP
 373 .B iconName (\fPclass\fB Title)
 374 Sets the icon name for the
 375 .I Emacs
 376 window icon.
 377 .PP
 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.
 384 .PP
 385 .SM Using the Mouse
 386 .PP
 387 The following lists the mouse button bindings for the
 388 .I Emacs
 389 window under X11.
 390
 391 .TS
 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.
 403 T}
 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.
 410 T}
 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.
 416 T}
 417 .\" STOP DELETING HERE IF YOU'RE NOT USING X
 418 .TE
 419 .PP
 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.
 424 .br
 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.
 429 .PP
 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.
 435
 436 /usr/local/share/emacs/$VERSION/src - C source files and object files
 437
 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.
 444
 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.
 449
 450 /usr/local/share/emacs/$VERSION/etc/OTHER.EMACSES discusses GNU Emacs
 451 vs. other versions of Emacs.
 452 .br
 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.
 456 .br
 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.
 460
 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.
 464
 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
 468 .PP
 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.
 478
 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.
 483
 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.
 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 Free Software Foundation, Inc.
 537 .PP
 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.
 541 .PP
 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.
 546 .PP
 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.