etc/emacs.1

   1 .TH EMACS 1 "1995 December 7"
   2 .UC 4
   3 .SH NAME
   4 emacs \- GNU project Emacs
   5 .SH SYNOPSIS
   6 .B emacs
   7 [
   8 .I command-line switches
   9 ] [
  10 .I files ...
  11 ]
  12 .br
  13 .SH DESCRIPTION
  14 .I GNU Emacs
  15 is a version of
  16 .I Emacs,
  17 written by the author of the original (PDP-10)
  18 .I Emacs,
  19 Richard Stallman.
  20 .br
  21 The primary documentation of GNU Emacs is in the GNU Emacs Manual,
  22 which you can read on line using Info, a subsystem of Emacs.  Please
  23 look there for complete and up-to-date documentation.  This man page
  24 is updated only when someone volunteers to do so; the Emacs
  25 maintainers' priority goal is to minimize the amount of time this man
  26 page takes away from other more useful projects.
  27 .br
  28 The user functionality of GNU Emacs encompasses
  29 everything other
  30 .I Emacs
  31 editors do, and it is easily extensible since its
  32 editing commands are written in Lisp.
  33 .PP
  34 .I Emacs
  35 has an extensive interactive help facility,
  36 but the facility assumes that you know how to manipulate
  37 .I Emacs
  38 windows and buffers.
  39 CTRL-h (backspace
  40 or CTRL-h) enters the Help facility.  Help Tutorial (CTRL-h t)
  41 requests an interactive tutorial which can teach beginners the fundamentals
  42 of
  43 .I Emacs
  44 in a few minutes.
  45 Help Apropos (CTRL-h a) helps you
  46 find a command given its functionality, Help Character (CTRL-h c)
  47 describes a given character's effect, and Help Function (CTRL-h f)
  48 describes a given Lisp function specified by name.
  49 .PP
  50 .I Emacs's
  51 Undo can undo several steps of modification to your buffers, so it is
  52 easy to recover from editing mistakes.
  53 .PP
  54 .I GNU Emacs's
  55 many special packages handle mail reading (RMail) and sending (Mail),
  56 outline editing (Outline), compiling (Compile), running subshells
  57 within
  58 .I Emacs
  59 windows (Shell), running a Lisp read-eval-print loop
  60 (Lisp-Interaction-Mode), and automated psychotherapy (Doctor).
  61 .PP
  62 There is an extensive reference manual, but
  63 users of other Emacses
  64 should have little trouble adapting even
  65 without a copy.  Users new to
  66 .I Emacs
  67 will be able
  68 to use basic features fairly rapidly by studying the tutorial and
  69 using the self-documentation features.
  70 .PP
  71 .SM Emacs Options
  72 .PP
  73 The following options are of general interest:
  74 .TP 8
  75 .I file
  76 Edit
  77 .I file.
  78 .TP
  79 .BI \+ number
  80 Go to the line specified by
  81 .I number
  82 (do not insert a space between the "+" sign and
  83 the number).
  84 .TP
  85 .B \-q
  86 Do not load an init file.
  87 .TP
  88 .BI \-u " user"
  89 Load
  90 .I user's
  91 init file.
  92 .TP
  93 .BI \-t " file"
  94 Use specified
  95 .I file
  96 as the terminal instead of using stdin/stdout.
  97 This must be the first argument specified in the command line.
  98 .PP
  99 The following options are lisp-oriented
 100 (these options are processed in the order encountered):
 101 .TP 8
 102 .BI \-f " function"
 103 Execute the lisp function
 104 .I function.
 105 .TP
 106 .BI \-l " file"
 107 Load the lisp code in the file
 108 .I file.
 109 .PP
 110 The following options are useful when running
 111 .I Emacs
 112 as a batch editor:
 113 .TP 8
 114 .BI \-batch
 115 Edit in batch mode.  The editor will send messages to stderr.  This
 116 option must be the first in the argument list.  You must use -l and -f
 117 options to specify files to execute and functions to call.
 118 .TP
 119 .B \-kill
 120 Exit
 121 .I Emacs
 122 while in batch mode.
 123 .\" START DELETING HERE IF YOU'RE NOT USING X
 124 .PP
 125 .SM Using Emacs with X
 126 .PP
 127 .I Emacs
 128 has been tailored to work well with the X window system.
 129 If you run
 130 .I Emacs
 131 from under X windows, it will create its own X window to
 132 display in.  You will probably want to start the editor
 133 as a background process
 134 so that you can continue using your original window.
 135 .PP
 136 .I Emacs
 137 can be started with the following X switches:
 138 .TP 8
 139 .BI \-name " name"
 140 Specifies the name which should be assigned to the initial
 141 .I Emacs
 142 window.  This controls looking up X resources as well as the window title.
 143 .TP 8
 144 .BI \-title " name"
 145 Specifies the title for the initial X window.
 146 .TP 8
 147 .B \-r
 148 Display the
 149 .I Emacs
 150 window in reverse video.
 151 .TP
 152 .B \-i
 153 Use the "kitchen sink" bitmap icon when iconifying the
 154 .I Emacs
 155 window.
 156 .TP
 157 .BI \-font " font, " \-fn " font"
 158 Set the
 159 .I Emacs
 160 window's font to that specified by
 161 .I font.
 162 You will find the various
 163 .I X
 164 fonts in the
 165 .I /usr/lib/X11/fonts
 166 directory.
 167 Note that
 168 .I Emacs
 169 will only accept fixed width fonts.
 170 Under the X11 Release 4 font-naming conventions, any font with the
 171 value "m" or "c" in the eleventh field of the font name is a fixed
 172 width font.  Furthermore, fonts whose name are of the form
 173 .IR width x height
 174 are generally fixed width, as is the font
 175 .IR fixed .
 176 See
 177 .IR xlsfonts (1)
 178 for more information.
 179
 180 When you specify a font, be sure to put a space between the
 181 switch and the font name.
 182 .TP
 183 .BI \-b " pixels"
 184 Set the
 185 .I Emacs
 186 window's border width to the number of pixels specified by
 187 .I pixels.
 188 Defaults to one pixel on each side of the window.
 189 .TP
 190 .BI \-ib " pixels"
 191 Set the window's internal border width to the number of pixels specified
 192 by
 193 .I pixels.
 194 Defaults to one pixel of padding on each side of the window.
 195 .PP
 196 .TP 8
 197 .BI \-geometry " geometry"
 198 Set the
 199 .I Emacs
 200 window's width, height, and position as specified.  The geometry
 201 specification is in the standard X format; see
 202 .IR X (1)
 203 for more information.
 204 The width and height are specified in characters; the default is 80 by
 205 24.
 206 .PP
 207 .TP 8
 208 .BI \-fg " color"
 209 On color displays, sets the color of the text.
 210
 211 See the file
 212 .I /usr/lib/X11/rgb.txt
 213 for a list of valid
 214 color names.
 215 .TP
 216 .BI \-bg " color"
 217 On color displays,
 218 sets the color of the window's background.
 219 .TP
 220 .BI \-bd " color"
 221 On color displays,
 222 sets the color of the window's border.
 223 .TP
 224 .BI \-cr " color"
 225 On color displays,
 226 sets the color of the window's text cursor.
 227 .TP
 228 .BI \-ms " color"
 229 On color displays,
 230 sets the color of the window's mouse cursor.
 231 .TP
 232 .BI \-d " displayname, " \-display " displayname"
 233 Create the
 234 .I Emacs
 235 window on the display specified by
 236 .IR displayname .
 237 Must be the first option specified in the command line.
 238 .TP
 239 .B \-nw
 240 Tells
 241 .I Emacs
 242 not to use its special interface to X.  If you use this
 243 switch when invoking
 244 .I Emacs
 245 from an
 246 .IR xterm (1)
 247 window, display is done in that window.
 248 This must be the first option specified in the command line.
 249 .PP
 250 You can set
 251 .I X
 252 default values for your
 253 .I Emacs
 254 windows in your
 255 .I \.Xresources
 256 file (see
 257 .IR xrdb (1)).
 258 Use the following format:
 259 .IP
 260 emacs.keyword:value
 261 .PP
 262 where
 263 .I value
 264 specifies the default value of
 265 .I keyword.
 266 .I Emacs
 267 lets you set default values for the following keywords:
 268 .TP 8
 269 .B font (\fPclass\fB Font)
 270 Sets the window's text font.
 271 .TP
 272 .B reverseVideo (\fPclass\fB ReverseVideo)
 273 If
 274 .I reverseVideo's
 275 value is set to
 276 .I on,
 277 the window will be displayed in reverse video.
 278 .TP
 279 .B bitmapIcon (\fPclass\fB BitmapIcon)
 280 If
 281 .I bitmapIcon's
 282 value is set to
 283 .I on,
 284 the window will iconify into the "kitchen sink."
 285 .TP
 286 .B borderWidth (\fPclass\fB BorderWidth)
 287 Sets the window's border width in pixels.
 288 .TP
 289 .B internalBorder (\fPclass\fB BorderWidth)
 290 Sets the window's internal border width in pixels.
 291 .TP
 292 .B foreground (\fPclass\fB Foreground)
 293 For color displays,
 294 sets the window's text color.
 295 .TP
 296 .B background (\fPclass\fB Background)
 297 For color displays,
 298 sets the window's background color.
 299 .TP
 300 .B borderColor (\fPclass\fB BorderColor)
 301 For color displays,
 302 sets the color of the window's border.
 303 .TP
 304 .B cursorColor (\fPclass\fB Foreground)
 305 For color displays,
 306 sets the color of the window's text cursor.
 307 .TP
 308 .B pointerColor (\fPclass\fB Foreground)
 309 For color displays,
 310 sets the color of the window's mouse cursor.
 311 .TP
 312 .B geometry (\fPclass\fB Geometry)
 313 Sets the geometry of the
 314 .I Emacs
 315 window (as described above).
 316 .TP
 317 .B title (\fPclass\fB Title)
 318 Sets the title of the
 319 .I Emacs
 320 window.
 321 .TP
 322 .B iconName (\fPclass\fB Title)
 323 Sets the icon name for the
 324 .I Emacs
 325 window icon.
 326 .PP
 327 If you try to set color values while using a black and white display,
 328 the window's characteristics will default as follows:
 329 the foreground color will be set to black,
 330 the background color will be set to white,
 331 the border color will be set to grey,
 332 and the text and mouse cursors will be set to black.
 333 .PP
 334 .SM Using the Mouse
 335 .PP
 336 The following lists the mouse button bindings for the
 337 .I Emacs
 338 window under X11.
 339
 340 .in +\w'CTRL-SHIFT-middle'u+4n
 341 .ta \w'CTRL-SHIFT-middle'u+4n
 342 .ti -\w'CTRL-SHIFT-middle'u+4n
 343 MOUSE BUTTON    FUNCTION
 344 .br
 345 .ti -\w'CTRL-SHIFT-middle'u+4n
 346 left    Set point.
 347 .br
 348 .ti -\w'CTRL-SHIFT-middle'u+4n
 349 middle  Paste text.
 350 .br
 351 .ti -\w'CTRL-SHIFT-middle'u+4n
 352 right   Cut text into X cut buffer.
 353 .br
 354 .ti -\w'CTRL-SHIFT-middle'u+4n
 355 SHIFT-middle    Cut text into X cut buffer.
 356 .br
 357 .ti -\w'CTRL-SHIFT-middle'u+4n
 358 SHIFT-right     Paste text.
 359 .br
 360 .ti -\w'CTRL-SHIFT-middle'u+4n
 361 CTRL-middle     Cut text into X cut buffer and kill it.
 362 .br
 363 .ti -\w'CTRL-SHIFT-middle'u+4n
 364 CTRL-right      Select this window, then split it into
 365 two windows.  Same as typing CTRL-x 2.
 366 .\" START DELETING HERE IF YOU'RE NOT USING X MENUS
 367 .br
 368 .ti -\w'CTRL-SHIFT-middle'u+4n
 369 CTRL-SHIFT-left X buffer menu--hold the buttons and keys
 370 down, wait for menu to appear, select
 371 buffer, and release.  Move mouse out of
 372 menu and release to cancel.
 373 .br
 374 .ti -\w'CTRL-SHIFT-middle'u+4n
 375 CTRL-SHIFT-middle       X help menu--pop up index card menu for
 376 Emacs help.
 377 .\" STOP DELETING HERE IF YOU'RE NOT USING X MENUS
 378 .br
 379 .ti -\w'CTRL-SHIFT-middle'u+4n
 380 CTRL-SHIFT-right        Select window with mouse, and delete all
 381 other windows.  Same as typing CTRL-x 1.
 382 .\" STOP DELETING HERE IF YOU'RE NOT USING X
 383 .PP
 384 .SH MANUALS
 385 You can order printed copies of the GNU Emacs Manual from the Free
 386 Software Foundation, which develops GNU software.  See the file ORDERS
 387 for ordering information.
 388 .br
 389 Your local Emacs maintainer might also have copies available.  As
 390 with all software and publications from FSF, everyone is permitted to
 391 make and distribute copies of the Emacs manual.  The TeX source to the
 392 manual is also included in the Emacs source distribution.
 393 .PP
 394 .SH FILES
 395 /usr/local/info - files for the Info documentation browser
 396 (a subsystem of Emacs) to refer to.  Currently not much of Unix
 397 is documented here, but the complete text of the Emacs reference
 398 manual is included in a convenient tree structured form.
 399
 400 /usr/local/share/emacs/$VERSION/src - C source files and object files
 401
 402 /usr/local/share/emacs/$VERSION/lisp - Lisp source files and compiled files
 403 that define most editing commands.  Some are preloaded;
 404 others are autoloaded from this directory when used.
 405
 406 /usr/local/share/emacs/$VERSION/etc - various programs that are used with
 407 GNU Emacs, and some files of information.
 408
 409 /usr/local/share/emacs/$VERSION/etc/DOC.* - contains the documentation
 410 strings for the Lisp primitives and preloaded Lisp functions
 411 of GNU Emacs.  They are stored here to reduce the size of
 412 Emacs proper.
 413
 414 /usr/local/share/emacs/$VERSION/etc/OTHER.EMACSES discusses GNU Emacs
 415 vs. other versions of Emacs.
 416 .br
 417 /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering
 418 various services to assist users of GNU Emacs, including education,
 419 troubleshooting, porting and customization.
 420 .br
 421 These files also have information useful to anyone wishing to write
 422 programs in the Emacs Lisp extension language, which has not yet been fully
 423 documented.
 424
 425 /usr/local/com/emacs/lock - holds lock files that are made for all
 426 files being modified in Emacs, to prevent simultaneous modification
 427 of one file by two users.
 428
 429 .\" START DELETING HERE IF YOU'RE NOT USING X
 430 /usr/lib/X11/rgb.txt - list of valid X color names.
 431 .\" STOP DELETING HERE IF YOU'RE NOT USING X
 432 .PP
 433 .SH BUGS
 434 There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the internet
 435 (ucbvax!prep.ai.mit.edu!bug-gnu-emacs on UUCPnet), for reporting Emacs
 436 bugs and fixes.  But before reporting something as a bug, please try
 437 to be sure that it really is a bug, not a misunderstanding or a
 438 deliberate feature.  We ask you to read the section ``Reporting Emacs
 439 Bugs'' near the end of the reference manual (or Info system) for hints
 440 on how and when to report bugs.  Also, include the version number of
 441 the Emacs you are running in \fIevery\fR bug report that you send in.
 442
 443 Do not expect a personal answer to a bug report.  The purpose of reporting
 444 bugs is to get them fixed for everyone in the next release, if possible.
 445 For personal assistance, look in the SERVICE file (see above) for
 446 a list of people who offer it.
 447
 448 Please do not send anything but bug reports to this mailing list.
 449 Send requests to be added to mailing lists to the special list
 450 info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP
 451 address).  For more information about Emacs mailing lists, see the
 452 file /usr/local/emacs/etc/MAILINGLISTS.  Bugs tend actually to be
 453 fixed if they can be isolated, so it is in your interest to report
 454 them in such a way that they can be easily reproduced.
 455 .PP
 456 Bugs that I know about are: shell will not work with programs
 457 running in Raw mode on some Unix versions.
 458 .SH UNRESTRICTIONS
 459 .PP
 460 .I Emacs
 461 is free; anyone may redistribute copies of
 462 .I Emacs
 463 to
 464 anyone under the terms stated in the
 465 .I Emacs
 466 General Public License,
 467 a copy of which accompanies each copy of
 468 .I Emacs
 469 and which also
 470 appears in the reference manual.
 471 .PP
 472 Copies of
 473 .I Emacs
 474 may sometimes be received packaged with distributions of Unix systems,
 475 but it is never included in the scope of any license covering those
 476 systems.  Such inclusion violates the terms on which distribution
 477 is permitted.  In fact, the primary purpose of the General Public
 478 License is to prohibit anyone from attaching any other restrictions
 479 to redistribution of
 480 .I Emacs.
 481 .PP
 482 Richard Stallman encourages you to improve and extend
 483 .I Emacs,
 484 and urges that
 485 you contribute your extensions to the GNU library.  Eventually GNU
 486 (Gnu's Not Unix) will be a complete replacement for Berkeley
 487 Unix.
 488 Everyone will be free to use, copy, study and change the GNU system.
 489 .SH SEE ALSO
 490 X(1), xlsfonts(1), xterm(1), xrdb(1)
 491 .SH AUTHORS
 492 .PP
 493 .I Emacs
 494 was written by Richard Stallman and the Free Software Foundation.
 495 Joachim Martillo and Robert Krawitz added the X features.