etc/emacs.1

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