etc/emacs.1

   1 .\" Copyright (C) 1995, 1999, 2000, 2001, 2002, 2003, 2004,
   2 .\"   2005, 2006, 2007 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 "2007 April 13" "GNU Emacs 22.1"
  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 using Info, either from Emacs or as a standalone
  43 program.  Please look there for complete and up-to-date documentation.
  44 This man page is updated only when someone volunteers to do so; the
  45 Emacs maintainers' priority goal is to minimize the amount of time
  46 this man 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 starts 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), automated psychotherapy (Doctor), and much more.
  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).  This applies only to the next file specified.
 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 .BI \-font " font, " \-fn " font"
 204 Set the
 205 .I Emacs
 206 window's font to that specified by
 207 .I font.
 208 You will find the various
 209 .I X
 210 fonts in the
 211 .I /usr/lib/X11/fonts
 212 directory.
 213 Note that
 214 .I Emacs
 215 will only accept fixed width fonts.
 216 Under the X11 Release 4 font-naming conventions, any font with the
 217 value "m" or "c" in the eleventh field of the font name is a fixed
 218 width font.  Furthermore, fonts whose name are of the form
 219 .IR width x height
 220 are generally fixed width, as is the font
 221 .IR fixed .
 222 See
 223 .IR xlsfonts (1)
 224 for more information.
 225
 226 When you specify a font, be sure to put a space between the
 227 switch and the font name.
 228 .TP
 229 .BI \-bw " pixels"
 230 Set the
 231 .I Emacs
 232 window's border width to the number of pixels specified by
 233 .I pixels.
 234 Defaults to one pixel on each side of the window.
 235 .TP
 236 .BI \-ib " pixels"
 237 Set the window's internal border width to the number of pixels specified
 238 by
 239 .I pixels.
 240 Defaults to one pixel of padding on each side of the window.
 241 .PP
 242 .TP 8
 243 .BI \-\-geometry " geometry"
 244 Set the
 245 .I Emacs
 246 window's width, height, and position as specified.  The geometry
 247 specification is in the standard X format; see
 248 .IR X (1)
 249 for more information.
 250 The width and height are specified in characters; the default is 80 by
 251 24.  See the Emacs manual, section "Options for Window Size and Position",
 252 for information on how window sizes interact
 253 with selecting or deselecting the tool bar and menu bar.
 254 .PP
 255 .TP 8
 256 .BI \-fg " color"
 257 On color displays, sets the color of the text.
 258
 259 Use the command
 260 .I M-x list-colors-display
 261 for a list of valid
 262 color names.
 263 .TP
 264 .BI \-bg " color"
 265 On color displays,
 266 sets the color of the window's background.
 267 .TP
 268 .BI \-bd " color"
 269 On color displays,
 270 sets the color of the window's border.
 271 .TP
 272 .BI \-cr " color"
 273 On color displays,
 274 sets the color of the window's text cursor.
 275 .TP
 276 .BI \-ms " color"
 277 On color displays,
 278 sets the color of the window's mouse cursor.
 279 .TP
 280 .BI \-d " displayname, " \-display " displayname"
 281 Create the
 282 .I Emacs
 283 window on the display specified by
 284 .IR displayname .
 285 Must be the first option specified in the command line.
 286 .TP
 287 .B \-nw
 288 Tells
 289 .I Emacs
 290 not to use its special interface to X.  If you use this
 291 switch when invoking
 292 .I Emacs
 293 from an
 294 .IR xterm (1)
 295 window, display is done in that window.
 296 .PP
 297 You can set
 298 .I X
 299 default values for your
 300 .I Emacs
 301 windows in your
 302 .I \.Xresources
 303 file (see
 304 .IR xrdb (1)).
 305 Use the following format:
 306 .IP
 307 emacs.keyword:value
 308 .PP
 309 where
 310 .I value
 311 specifies the default value of
 312 .I keyword.
 313 .I Emacs
 314 lets you set default values for the following keywords:
 315 .TP 8
 316 .B font (\fPclass\fB Font)
 317 Sets the window's text font.
 318 .TP
 319 .B reverseVideo (\fPclass\fB ReverseVideo)
 320 If
 321 .I reverseVideo's
 322 value is set to
 323 .I on,
 324 the window will be displayed in reverse video.
 325 .TP
 326 .B bitmapIcon (\fPclass\fB BitmapIcon)
 327 If
 328 .I bitmapIcon's
 329 value is set to
 330 .I on,
 331 the window will iconify into the "kitchen sink."
 332 .TP
 333 .B borderWidth (\fPclass\fB BorderWidth)
 334 Sets the window's border width in pixels.
 335 .TP
 336 .B internalBorder (\fPclass\fB BorderWidth)
 337 Sets the window's internal border width in pixels.
 338 .TP
 339 .B foreground (\fPclass\fB Foreground)
 340 For color displays,
 341 sets the window's text color.
 342 .TP
 343 .B background (\fPclass\fB Background)
 344 For color displays,
 345 sets the window's background color.
 346 .TP
 347 .B borderColor (\fPclass\fB BorderColor)
 348 For color displays,
 349 sets the color of the window's border.
 350 .TP
 351 .B cursorColor (\fPclass\fB Foreground)
 352 For color displays,
 353 sets the color of the window's text cursor.
 354 .TP
 355 .B pointerColor (\fPclass\fB Foreground)
 356 For color displays,
 357 sets the color of the window's mouse cursor.
 358 .TP
 359 .B geometry (\fPclass\fB Geometry)
 360 Sets the geometry of the
 361 .I Emacs
 362 window (as described above).
 363 .TP
 364 .B title (\fPclass\fB Title)
 365 Sets the title of the
 366 .I Emacs
 367 window.
 368 .TP
 369 .B iconName (\fPclass\fB Title)
 370 Sets the icon name for the
 371 .I Emacs
 372 window icon.
 373 .PP
 374 If you try to set color values while using a black and white display,
 375 the window's characteristics will default as follows:
 376 the foreground color will be set to black,
 377 the background color will be set to white,
 378 the border color will be set to grey,
 379 and the text and mouse cursors will be set to black.
 380 .PP
 381 .SM Using the Mouse
 382 .PP
 383 The following lists the mouse button bindings for the
 384 .I Emacs
 385 window under X11.
 386
 387 .TS
 388 l l.
 389 MOUSE BUTTON    FUNCTION
 390 left    Set point.
 391 middle  Paste text.
 392 right   Cut text into X cut buffer.
 393 SHIFT-middle    Cut text into X cut buffer.
 394 SHIFT-right     Paste text.
 395 CTRL-middle     Cut text into X cut buffer and kill it.
 396 CTRL-right      T{
 397 Select this window, then split it into
 398 two windows.  Same as typing CTRL-x 2.
 399 T}
 400 .\" START DELETING HERE IF YOU'RE NOT USING X MENUS
 401 CTRL-SHIFT-left T{
 402 X buffer menu \(em hold the buttons and keys
 403 down, wait for menu to appear, select
 404 buffer, and release.  Move mouse out of
 405 menu and release to cancel.
 406 T}
 407 CTRL-SHIFT-middle       X help menu \(em pop up index card menu for Emacs help.
 408 .\" STOP DELETING HERE IF YOU'RE NOT USING X MENUS
 409 CTRL-SHIFT-right        T{
 410 Select window with mouse, and delete all
 411 other windows.  Same as typing CTRL-x 1.
 412 T}
 413 .\" STOP DELETING HERE IF YOU'RE NOT USING X
 414 .TE
 415 .PP
 416 .SH MANUALS
 417 You can order printed copies of the GNU Emacs Manual from the Free
 418 Software Foundation, which develops GNU software.  See the file ORDERS
 419 for ordering information.
 420 .br
 421 Your local Emacs maintainer might also have copies available.  As
 422 with all software and publications from FSF, everyone is permitted to
 423 make and distribute copies of the Emacs manual.  The TeX source to the
 424 manual is also included in the Emacs source distribution.
 425 .PP
 426 .SH FILES
 427 /usr/local/share/info - files for the Info documentation browser.
 428 The complete text of the Emacs reference manual is included in a
 429 convenient tree structured form.  Also includes the Emacs Lisp
 430 Reference Manual, useful to anyone wishing to write programs in the
 431 Emacs Lisp extension language.
 432
 433 /usr/local/share/emacs/$VERSION/lisp - Lisp source files and compiled files
 434 that define most editing commands.  Some are preloaded;
 435 others are autoloaded from this directory when used.
 436
 437 /usr/local/libexec/emacs/$VERSION/$ARCH - various programs that are
 438 used with GNU Emacs.
 439
 440 /usr/local/share/emacs/$VERSION/etc - various files of information.
 441
 442 /usr/local/share/emacs/$VERSION/etc/DOC.* - contains the documentation
 443 strings for the Lisp primitives and preloaded Lisp functions
 444 of GNU Emacs.  They are stored here to reduce the size of
 445 Emacs proper.
 446
 447 .br
 448 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
 449 various services to assist users of GNU Emacs, including education,
 450 troubleshooting, porting and customization.
 451
 452 .PP
 453 .SH BUGS
 454 There is a mailing list, bug-gnu-emacs@gnu.org, for reporting Emacs
 455 bugs and fixes.  But before reporting something as a bug, please try
 456 to be sure that it really is a bug, not a misunderstanding or a
 457 deliberate feature.  We ask you to read the section ``Reporting Emacs
 458 Bugs'' near the end of the reference manual (or Info system) for hints
 459 on how and when to report bugs.  Also, include the version number of
 460 the Emacs you are running in \fIevery\fR bug report that you send in.
 461
 462 Do not expect a personal answer to a bug report.  The purpose of reporting
 463 bugs is to get them fixed for everyone in the next release, if possible.
 464 For personal assistance, look in the SERVICE file (see above) for
 465 a list of people who offer it.
 466
 467 Please do not send anything but bug reports to this mailing list.
 468 For more information about Emacs mailing lists, see the
 469 file /usr/local/emacs/etc/MAILINGLISTS.  Bugs tend actually to be
 470 fixed if they can be isolated, so it is in your interest to report
 471 them in such a way that they can be easily reproduced.
 472 .SH UNRESTRICTIONS
 473 .PP
 474 .I Emacs
 475 is free; anyone may redistribute copies of
 476 .I Emacs
 477 to
 478 anyone under the terms stated in the
 479 .I Emacs
 480 General Public License,
 481 a copy of which accompanies each copy of
 482 .I Emacs
 483 and which also
 484 appears in the reference manual.
 485 .PP
 486 Copies of
 487 .I Emacs
 488 may sometimes be received packaged with distributions of Unix systems,
 489 but it is never included in the scope of any license covering those
 490 systems.  Such inclusion violates the terms on which distribution
 491 is permitted.  In fact, the primary purpose of the General Public
 492 License is to prohibit anyone from attaching any other restrictions
 493 to redistribution of
 494 .I Emacs.
 495 .PP
 496 Richard Stallman encourages you to improve and extend
 497 .I Emacs,
 498 and urges that
 499 you contribute your extensions to the GNU library.  Eventually GNU
 500 (Gnu's Not Unix) will be a complete replacement for Unix.
 501 Everyone will be free to use, copy, study and change the GNU system.
 502 .SH SEE ALSO
 503 emacsclient(1), etags(1), X(1), xlsfonts(1), xterm(1), xrdb(1)
 504 .SH AUTHORS
 505 .PP
 506 .I Emacs
 507 was written by Richard Stallman and the Free Software Foundation.
 508 Joachim Martillo and Robert Krawitz added the X features.
 509 .SH COPYING
 510 Copyright
 511 .if t \(co
 512 .if n (C)
 513 1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
 514       2006, 2007 Free Software Foundation, Inc.
 515 .PP
 516 Permission is granted to make and distribute verbatim copies of this
 517 document provided the copyright notice and this permission notice are
 518 preserved on all copies.
 519 .PP
 520 Permission is granted to copy and distribute modified versions of
 521 this document under the conditions for verbatim copying, provided that
 522 the entire resulting derived work is distributed under the terms of
 523 a permission notice identical to this one.
 524 .PP
 525 Permission is granted to copy and distribute translations of this
 526 document into another language, under the above conditions for
 527 modified versions, except that this permission notice may be stated
 528 in a translation approved by the Free Software Foundation.
 529
 530 .\" arch-tag: 04dfd376-b46e-4924-919a-cecc3b257eaa