doc/man/emacs.1

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