doc/man/emacs.1

   1 .\" See section COPYING for copyright and redistribution information.
   2 .TH EMACS 1 "2007 April 13" "GNU Emacs 23.2.50"
   3 .
   4 .
   5 .SH NAME
   6 emacs \- GNU project Emacs
   7 .
   8 .
   9 .SH SYNOPSIS
  10 .B emacs
  11 [
  12 .I command-line switches
  13 ] [
  14 .I files ...\&
  15 ]
  16 .
  17 .
  18 .SH DESCRIPTION
  19 .I GNU Emacs
  20 is a version of
  21 .IR Emacs ,
  22 written by the author of the original (PDP-10)
  23 .IR Emacs ,
  24 Richard Stallman.
  25 The user functionality of GNU Emacs encompasses everything other
  26 editors do, and it is easily extensible since its editing commands are
  27 written in Lisp.
  28 .PP
  29 The primary documentation of GNU Emacs is in the GNU Emacs Manual,
  30 which you can read using Info, either from Emacs or as a standalone
  31 program.
  32 Please look there for complete and up-to-date documentation.
  33 This man page is updated only when someone volunteers to do so.
  34 .PP
  35 .I Emacs
  36 has an extensive interactive help facility,
  37 but the facility assumes that you know how to manipulate
  38 .I Emacs
  39 windows and buffers.
  40 CTRL-h or F1 enters the Help facility.
  41 Help Tutorial (CTRL-h t) starts an interactive tutorial to quickly
  42 teach beginners the fundamentals of
  43 .I Emacs.
  44 Help Apropos (CTRL-h a) helps you find a command given its
  45 functionality, Help Key (CTRL-h k) describes a given key sequence, and
  46 Help Function (CTRL-h f) describes a given Lisp function.
  47 .PP
  48 .IR "GNU Emacs" 's
  49 many special packages handle mail reading (RMail) and sending (Mail),
  50 outline editing (Outline), compiling (Compile), running subshells
  51 within
  52 .I Emacs
  53 windows (Shell), running a Lisp read-eval-print loop
  54 (Lisp-Interaction-Mode), automated psychotherapy (Doctor), and much more.
  55 .
  56 .SS Emacs Options
  57 The following options are of general interest:
  58 .RS
  59 .TP 8
  60 .I file
  61 Edit
  62 .IR file .
  63 .TP
  64 .BI \-\-file " file\fR,\fP " \-\-find-file " file\fR,\fP " \-\-visit " file"
  65 The same as specifying
  66 .I file
  67 directly as an argument.
  68 .TP
  69 .BI + number
  70 Go to the line specified by
  71 .I number
  72 (do not insert a space between the "+" sign and
  73 the number).
  74 This applies only to the next file specified.
  75 .TP
  76 .BI + line:column
  77 Go to the specified
  78 .I line
  79 and
  80 .IR column .
  81 .TP
  82 .BR \-q ", " \-\-no\-init\-file
  83 Do not load an init file.
  84 .TP
  85 .B \-\-no\-site\-file
  86 Do not load the site-wide startup file.
  87 .TP
  88 .B \-\-no\-desktop
  89 Do not load a saved desktop.
  90 .TP
  91 .BR \-Q ", " \-\-quick
  92 Similar to "\-q \-\-no\-site\-file \-\-no\-splash".  Also, avoid
  93 processing X resources.
  94 .TP
  95 .B \-\-no\-splash
  96 Do not display a splash screen during start-up.
  97 .TP
  98 .B \-\-debug\-init
  99 Enable
 100 .I Emacs
 101 Lisp debugger during the processing of the user init file
 102 .BR ~/.emacs .
 103 This is useful for debugging problems in the init file.
 104 .TP
 105 .BI \-u " user\fR,\fP " \-\-user " user"
 106 Load
 107 .IR user 's
 108 init file.
 109 .TP
 110 .BI \-t " file\fR,\fP " \-\-terminal " file"
 111 Use specified
 112 .I file
 113 as the terminal instead of using stdin/stdout.
 114 This must be the first argument specified in the command line.
 115 .TP
 116 .B \-\-daemon
 117 Start Emacs as a daemon, enabling the Emacs server and disconnecting
 118 from the terminal.  You can then use the emacsclient command to
 119 connect to the server (see
 120 .BR emacsclient (1)).
 121 .TP
 122 .B \-\-version
 123 Display
 124 .I Emacs
 125 version information and exit.
 126 .TP
 127 .B \-\-help
 128 Display this help and exit.
 129 .RE
 130 .PP
 131 The following options are Lisp-oriented
 132 (these options are processed in the order encountered):
 133 .RS
 134 .TP 8
 135 .BI \-f " function\fR,\fP " \-\-funcall " function"
 136 Execute the lisp function
 137 .IR function .
 138 .TP
 139 .BI \-l " file\fR,\fP " \-\-load " file"
 140 Load the lisp code in the file
 141 .IR file .
 142 .TP
 143 .BI \-\-eval " expr\fR,\fP " \-\-execute " expr"
 144 Evaluate the Lisp expression
 145 .IR expr .
 146 .RE
 147 .PP
 148 The following options are useful when running
 149 .I Emacs
 150 as a batch editor:
 151 .RS
 152 .TP 8
 153 .B \-\-batch
 154 Edit in batch mode.
 155 The editor will send messages to stderr.
 156 You must use \-l and \-f options to specify files to execute
 157 and functions to call.
 158 .TP
 159 .BI \-\-script " file"
 160 Run
 161 .I file
 162 as an Emacs Lisp script.
 163 .TP
 164 .BI \-\-insert " file"
 165 Insert contents of
 166 .I file
 167 into the current buffer.
 168 .TP
 169 .B \-\-kill
 170 Exit
 171 .I Emacs
 172 while in batch mode.
 173 .TP
 174 .BI \-L " dir\fR,\fP " \-\-directory " dir"
 175 Add
 176 .I dir
 177 to the list of directories
 178 .I Emacs
 179 searches for Lisp files.
 180 .RE
 181 .
 182 .\" START DELETING HERE IF YOU'RE NOT USING X
 183 .SS Using Emacs with X
 184 .I Emacs
 185 has been tailored to work well with the X window system.
 186 If you run
 187 .I Emacs
 188 from under X windows, it will create its own X window to
 189 display in.
 190 You will probably want to start the editor as a background
 191 process so that you can continue using your original window.
 192 .PP
 193 .I Emacs
 194 can be started with the following X switches:
 195 .RS
 196 .TP 8
 197 .BI \-\-name " name"
 198 Specify the name which should be assigned to the initial
 199 .I Emacs
 200 window.
 201 This controls looking up X resources as well as the window title.
 202 .TP
 203 .BI \-T " name\fR,\fP " \-\-title " name"
 204 Specify the title for the initial X window.
 205 .TP
 206 .BR \-r ", " \-rv ", " \-\-reverse\-video
 207 Display the
 208 .I Emacs
 209 window in reverse video.
 210 .TP
 211 .BI \-fn " font\fR,\fP " \-\-font " font"
 212 Set the
 213 .I Emacs
 214 window's font to that specified by
 215 .IR font .
 216 You will find the various
 217 .I X
 218 fonts in the
 219 .I /usr/lib/X11/fonts
 220 directory.
 221 Note that
 222 .I Emacs
 223 will only accept fixed width fonts.
 224 Under the X11 Release 4 font-naming conventions, any font with the
 225 value "m" or "c" in the eleventh field of the font name is a fixed
 226 width font.
 227 Furthermore, fonts whose name are of the form
 228 .IR width x height
 229 are generally fixed width, as is the font
 230 .IR fixed .
 231 See
 232 .BR xlsfonts (1)
 233 for more information.
 234
 235 When you specify a font, be sure to put a space between the
 236 switch and the font name.
 237 .TP
 238 .BI \-\-xrm " resources"
 239 Set additional X resources.
 240 .TP
 241 .BI "\-\-color\fR,\fP \-\-color=" mode
 242 Override color mode for character terminals;
 243 .I mode
 244 defaults to `auto', and can also be `never', `auto', `always',
 245 or a mode name like `ansi8'.
 246 .TP
 247 .BI \-bw " pixels\fR,\fP " \-\-border\-width " pixels"
 248 Set the
 249 .I Emacs
 250 window's border width to the number of pixels specified by
 251 .IR pixels .
 252 Defaults to one pixel on each side of the window.
 253 .TP
 254 .BI \-ib " pixels\fR,\fP " \-\-internal\-border " pixels"
 255 Set the window's internal border width to the number of pixels specified
 256 by
 257 .IR pixels .
 258 Defaults to one pixel of padding on each side of the window.
 259 .TP
 260 .BI \-g " geometry\fR,\fP " \-\-geometry " geometry"
 261 Set the
 262 .I Emacs
 263 window's width, height, and position as specified.
 264 The geometry specification is in the standard X format; see
 265 .BR X (7)
 266 for more information.
 267 The width and height are specified in characters; the default is
 268 80 by 24.
 269 See the Emacs manual, section "Options for Window Size and Position",
 270 for information on how window sizes interact
 271 with selecting or deselecting the tool bar and menu bar.
 272 .TP
 273 .BI \-lsp " pixels\fR,\fP " \-\-line\-spacing " pixels"
 274 Additional space to put between lines.
 275 .TP
 276 .BR \-vb ", " \-\-vertical\-scroll\-bars
 277 Enable vertical scrollbars.
 278 .TP
 279 .BR \-fh ", " \-\-fullheight
 280 Make the first frame as high as the screen.
 281 .TP
 282 .BR \-fs ", " \-\-fullscreen
 283 Make the first frame fullscreen.
 284 .TP
 285 .BR \-fw ", " \-\-fullwidth
 286 Make the first frame as wide as the screen.
 287 .TP
 288 .BR \-mm ", " \-\-maximized
 289 Maximize the first frame, like "\-fw \-fh".
 290 .TP
 291 .BI \-fg " color\fR,\fP " \-\-foreground\-color " color"
 292 On color displays, set the color of the text.
 293
 294 Use the command
 295 .I M\-x list\-colors\-display
 296 for a list of valid color names.
 297 .TP
 298 .BI \-bg " color\fR,\fP " \-\-background\-color " color"
 299 On color displays, set the color of the window's background.
 300 .TP
 301 .BI \-bd " color\fR,\fP " \-\-border\-color " color"
 302 On color displays, set the color of the window's border.
 303 .TP
 304 .BI \-cr " color\fR,\fP " \-\-cursor\-color " color"
 305 On color displays, set the color of the window's text cursor.
 306 .TP
 307 .BI \-ms " color\fR,\fP " \-\-mouse\-color " color"
 308 On color displays, set the color of the window's mouse cursor.
 309 .TP
 310 .BI \-d " displayname\fR,\fP " \-\-display " displayname"
 311 Create the
 312 .I Emacs
 313 window on the display specified by
 314 .IR displayname .
 315 Must be the first option specified in the command line.
 316 .TP
 317 .BR \-nbi ", " \-\-no\-bitmap\-icon
 318 Do not use picture of gnu for Emacs icon.
 319 .TP
 320 .B \-\-iconic
 321 Start
 322 .I Emacs
 323 in iconified state.
 324 .TP
 325 .BR \-nbc ", " \-\-no\-blinking\-cursor
 326 Disable blinking cursor.
 327 .TP
 328 .BR \-nw ", " \-\-no\-window\-system
 329 Tell
 330 .I Emacs
 331 not to create a graphical frame.
 332 If you use this switch when invoking
 333 .I Emacs
 334 from an
 335 .BR xterm (1)
 336 window, display is done in that window.
 337 .TP
 338 .BR \-D ", " \-\-basic\-display
 339 This option disables many display features; use it for
 340 debugging Emacs.
 341 .RE
 342 .PP
 343 You can set
 344 .I X
 345 default values for your
 346 .I Emacs
 347 windows in your
 348 .I \.Xresources
 349 file (see
 350 .BR xrdb (1)).
 351 Use the following format:
 352 .IP
 353 .RI emacs. keyword : value
 354 .PP
 355 where
 356 .I value
 357 specifies the default value of
 358 .IR keyword .
 359 .I Emacs
 360 lets you set default values for the following keywords:
 361 .RS
 362 .TP 8
 363 .BR background " (class " Background )
 364 For color displays,
 365 sets the window's background color.
 366 .TP
 367 .BR bitmapIcon " (class " BitmapIcon )
 368 If
 369 .BR bitmapIcon 's
 370 value is set to
 371 .IR on ,
 372 the window will iconify into the "kitchen sink."
 373 .TP
 374 .BR borderColor " (class " BorderColor )
 375 For color displays,
 376 sets the color of the window's border.
 377 .TP
 378 .BR borderWidth " (class " BorderWidth )
 379 Sets the window's border width in pixels.
 380 .TP
 381 .BR cursorColor " (class " Foreground )
 382 For color displays,
 383 sets the color of the window's text cursor.
 384 .TP
 385 .BR cursorBlink " (class " CursorBlink )
 386 Specifies whether to make the cursor blink.
 387 The default is
 388 .IR on .
 389 Use
 390 .I off
 391 or
 392 .I false
 393 to turn cursor blinking off.
 394 .TP
 395 .BR font " (class " Font )
 396 Sets the window's text font.
 397 .TP
 398 .BR foreground " (class " Foreground )
 399 For color displays,
 400 sets the window's text color.
 401 .TP
 402 .BR fullscreen " (class " Fullscreen )
 403 The desired fullscreen size.
 404 The value can be one of
 405 .IR fullboth ,
 406 .IR maximized ,
 407 .IR fullwidth ,
 408 or
 409 .IR fullheight ,
 410 which correspond to the command-line options `\-fs', `-mm', `\-fw',
 411 and `\-fh', respectively.
 412 Note that this applies to the initial frame only.
 413 .TP
 414 .BR geometry " (class " Geometry )
 415 Sets the geometry of the
 416 .I Emacs
 417 window (as described above).
 418 .TP
 419 .BR iconName " (class " Title )
 420 Sets the icon name for the
 421 .I Emacs
 422 window icon.
 423 .TP
 424 .BR internalBorder " (class " BorderWidth )
 425 Sets the window's internal border width in pixels.
 426 .TP
 427 .BR lineSpacing " (class " LineSpacing )
 428 Additional space ("leading") between lines, in pixels.
 429 .TP
 430 .BR menuBar " (class " MenuBar )
 431 Gives frames menu bars if
 432 .IR on ;
 433 don't have menu bars if
 434 .IR off .
 435 See the Emacs manual, sections "Lucid Resources" and "LessTif
 436 Resources", for how to control the appearance of the menu bar
 437 if you have one.
 438 .TP
 439 .BR minibuffer " (class " Minibuffer )
 440 If
 441 .IR none ,
 442 don't make a minibuffer in this frame.
 443 It will use a separate minibuffer frame instead.
 444 .TP
 445 .BR paneFont " (class " Font )
 446 Font name for menu pane titles, in non-toolkit versions of
 447 .IR Emacs .
 448 .TP
 449 .BR pointerColor " (class " Foreground )
 450 For color displays,
 451 sets the color of the window's mouse cursor.
 452 .TP
 453 .BR privateColormap " (class " PrivateColormap )
 454 If
 455 .IR on ,
 456 use a private color map, in the case where the "default
 457 visual" of class
 458 .B PseudoColor
 459 and
 460 .B Emacs
 461 is using it.
 462 .TP
 463 .BR reverseVideo " (class " ReverseVideo )
 464 If
 465 .BR reverseVideo 's
 466 value is set to
 467 .IR on ,
 468 the window will be displayed in reverse video.
 469 .TP
 470 .BR screenGamma " (class "ScreenGamma )
 471 Gamma correction for colors, equivalent to the frame parameter
 472 `screen\-gamma'.
 473 .TP
 474 .BR scrollBarWidth " (class "ScrollBarWidth )
 475 The scroll bar width in pixels, equivalent to the frame parameter
 476 `scroll\-bar\-width'.
 477 .TP
 478 .BR selectionFont " (class " SelectionFont )
 479 Font name for pop-up menu items, in non-toolkit versions of
 480 .IR Emacs .
 481 (For toolkit versions, see the Emacs manual, sections
 482 "Lucid Resources" and "LessTif Resources".)
 483 .TP
 484 .BR selectionTimeout " (class " SelectionTimeout )
 485 Number of milliseconds to wait for a selection reply.
 486 A value of 0 means wait as long as necessary.
 487 .TP
 488 .BR synchronous " (class " Synchronous )
 489 Run Emacs in synchronous mode if
 490 .IR on .
 491 Synchronous mode is useful for debugging X problems.
 492 .TP
 493 .BR title " (class " Title )
 494 Sets the title of the
 495 .I Emacs
 496 window.
 497 .TP
 498 .BR toolBar " (class " ToolBar )
 499 Number of lines to reserve for the tool bar.
 500 .TP
 501 .BR useXIM " (class " UseXIM )
 502 Turns off use of X input methods (XIM) if
 503 .I false
 504 or
 505 .IR off .
 506 .TP
 507 .BR verticalScrollBars " (class " ScrollBars )
 508 Gives frames scroll bars if
 509 .IR on ;
 510 suppresses scroll bars if
 511 .IR off .
 512 .TP
 513 .BR visualClass " (class " VisualClass )
 514 Specify the "visual" that X should use.
 515 This tells X how to handle colors.
 516 The value should start with one of
 517 .IR TrueColor ,
 518 .IR PseudoColor ,
 519 .IR DirectColor ,
 520 .IR StaticColor ,
 521 .IR GrayScale ,
 522 and
 523 .IR StaticGray ,
 524 followed by
 525 .BI \- depth\fR,\fP
 526 where
 527 .I depth
 528 is the number of color planes.
 529 .RE
 530 .
 531 .SH MANUALS
 532 You can order printed copies of the GNU Emacs Manual from the Free
 533 Software Foundation, which develops GNU software.
 534 See the file ORDERS for ordering information.
 535 .br
 536 Your local Emacs maintainer might also have copies available.
 537 As with all software and publications from FSF, everyone is permitted
 538 to make and distribute copies of the Emacs manual.
 539 The TeX source to the manual is also included in the Emacs source
 540 distribution.
 541 .
 542 .
 543 .SH FILES
 544 /usr/local/share/info \(em files for the Info documentation browser.
 545 The complete text of the Emacs reference manual is included in a
 546 convenient tree structured form.
 547 Also includes the Emacs Lisp Reference Manual, useful to anyone
 548 wishing to write programs in the Emacs Lisp extension language.
 549
 550 /usr/local/share/emacs/$VERSION/lisp \(em Lisp source files and
 551 compiled files that define most editing commands.
 552 Some are preloaded; others are autoloaded from this directory when
 553 used.
 554
 555 /usr/local/libexec/emacs/$VERSION/$ARCH \(em various programs that are
 556 used with GNU Emacs.
 557
 558 /usr/local/share/emacs/$VERSION/etc \(em various files of information.
 559
 560 /usr/local/share/emacs/$VERSION/etc/DOC.* \(em contains the documentation
 561 strings for the Lisp primitives and preloaded Lisp functions
 562 of GNU Emacs.
 563 They are stored here to reduce the size of Emacs proper.
 564
 565 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
 566 various services to assist users of GNU Emacs, including education,
 567 troubleshooting, porting and customization.
 568 .
 569 .
 570 .SH BUGS
 571 There is a mailing list, bug-gnu-emacs@gnu.org, for reporting Emacs
 572 bugs and fixes.
 573 But before reporting something as a bug, please try to be sure that
 574 it really is a bug, not a misunderstanding or a deliberate feature.
 575 We ask you to read the section ``Reporting Emacs Bugs'' near the
 576 end of the reference manual (or Info system) for hints on how and
 577 when to report bugs.
 578 Also, include the version number of the Emacs you are running in
 579 \fIevery\fR bug report that you send in.
 580 Bugs tend actually to be fixed if they can be isolated, so it is
 581 in your interest to report them in such a way that they can be
 582 easily reproduced.
 583
 584 Do not expect a personal answer to a bug report.
 585 The purpose of reporting bugs is to get them fixed for everyone
 586 in the next release, if possible.
 587 For personal assistance, look in the SERVICE file (see above) for
 588 a list of people who offer it.
 589
 590 Please do not send anything but bug reports to this mailing list.
 591 For more information about Emacs mailing lists, see the
 592 file /usr/local/share/emacs/$VERSION/etc/MAILINGLISTS.
 593 .
 594 .
 595 .SH UNRESTRICTIONS
 596 .I Emacs
 597 is free; anyone may redistribute copies of
 598 .I Emacs
 599 to
 600 anyone under the terms stated in the
 601 .I Emacs
 602 General Public License,
 603 a copy of which accompanies each copy of
 604 .I Emacs
 605 and which also
 606 appears in the reference manual.
 607 .PP
 608 Copies of
 609 .I Emacs
 610 may sometimes be received packaged with distributions of Unix systems,
 611 but it is never included in the scope of any license covering those
 612 systems.
 613 Such inclusion violates the terms on which distribution is permitted.
 614 In fact, the primary purpose of the General Public License is to
 615 prohibit anyone from attaching any other restrictions to
 616 redistribution of
 617 .IR Emacs .
 618 .PP
 619 Richard Stallman encourages you to improve and extend
 620 .IR Emacs ,
 621 and urges that
 622 you contribute your extensions to the GNU library.
 623 Eventually GNU (Gnu's Not Unix) will be a complete replacement
 624 for Unix.
 625 Everyone will be free to use, copy, study and change the GNU system.
 626 .
 627 .
 628 .SH SEE ALSO
 629 .BR emacsclient (1),
 630 .BR etags (1),
 631 .BR X (7),
 632 .BR xlsfonts (1),
 633 .BR xterm (1),
 634 .BR xrdb (1)
 635 .
 636 .
 637 .SH AUTHORS
 638 .I Emacs
 639 was written by Richard Stallman and the Free Software Foundation.
 640 For detailed credits and acknowledgements, see the GNU Emacs manual.
 641 .
 642 .
 643 .
 644 .SH COPYING
 645 Copyright
 646 .if t \(co
 647 .if n (C)
 648 1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
 649 2009, 2010
 650 Free Software Foundation, Inc.
 651 .PP
 652 Permission is granted to make and distribute verbatim copies of this
 653 document provided the copyright notice and this permission notice are
 654 preserved on all copies.
 655 .PP
 656 Permission is granted to copy and distribute modified versions of
 657 this document under the conditions for verbatim copying, provided that
 658 the entire resulting derived work is distributed under the terms of
 659 a permission notice identical to this one.
 660 .PP
 661 Permission is granted to copy and distribute translations of this
 662 document into another language, under the above conditions for
 663 modified versions, except that this permission notice may be stated
 664 in a translation approved by the Free Software Foundation.
 665 .
 666 .\" arch-tag: 04dfd376-b46e-4924-919a-cecc3b257eaa