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