1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
38 When you first download XEmacs 21, you will usually first grab the
39 "core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the
40 21.0 by the current version number.) The core distribution contains
41 the sources of XEmacs and a minimal set of Emacs Lisp files, which are
42 in the subdirectory named `lisp'. This subdirectory used to contain
43 all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
44 space, most non-essential packages were made optional.
46 Choosing the Packages You Need
47 ------------------------------
49 The available packages can currently be found in the same ftp
50 directory where you grabbed the core distribution from, and are located
51 in the subdirectory `packages/binary-packages'. Package file names
52 follow the naming convention `<package-name>-<version>-pkg.tar.gz'.
54 If you have EFS *Note (EFS)::, packages can be installed over the
55 network. Alternatively, if you have copies of the packages locally,
56 you can install packages from a local disk or CDROM.
58 The file `etc/PACKAGES' in the core distribution contains a list of
59 the packages available at the time of the XEmacs release. Packages are
60 also listed on the `Options' menu under:
62 Options->Customize->Emacs->Packages
64 However, don't select any of these menu picks unless you actually
65 want to install the given package (and have properly configured your
68 You can also get a list of available packages, and whether or not
69 they are installed, using the visual package browser and installer.
70 You can access it via the menus:
72 Options->Manage Packages->List & Install
74 Or, you can get to it via the keyboard:
78 Hint to system administrators of multi-user systems: it might be a
79 good idea to install all packages and not interfere with the wishes of
82 If you can't find which package provides the feature you require, try
83 using the `package-get-package-provider' function. Eg., if you know
84 that you need `thingatpt', type:
86 M-x package-get-package-provider RET thingatpt
88 which will return something like (fsf-compat "1.06"). You can the use
89 one of the methods above for installing the package you want.
91 XEmacs and Installing Packages
92 ------------------------------
94 Normally, packages are installed over the network, using EFS *Note
95 (EFS)::. However, you may not have network access, or you may already
96 have some or all of the packages on a local disk, such as a CDROM. If
97 you want to install from a local disk, you must first tell XEmacs where
98 to find the package binaries. This is done by adding a line like the
99 following to your init file:
101 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
106 Here, you'd change `/my/path/to/package/binaries' to be the path to
107 your local package binaries. Next, restart XEmacs, and you're ready to
108 go (advanced users can just re-evaluate the sexp).
110 If you are installing from a temporary, one-time directory, you can
111 also add these directory names to `package-get-remote' using:
113 M-x pui-add-install-directory
115 Note, however, that any directories added using this function are not
116 saved; this information will be lost when you quit XEmacs.
118 If you're going to install over the network, you only have to insure
119 that EFS *Note (EFS):: works, and that it can get outside a firewall, if
120 you happen to be behind one. You shouldn't have to do anything else;
121 XEmacs already knows where to go. However you can add your own mirrors
122 to this list. See `package-get-remote'.
124 The easiest way to install a package is to use the visual package
125 browser and installer, using the menu pick:
127 Options->Manage Packages->List & Install
129 Options->Manage Packages->Using Custom->Select-> ...
131 You can also access it using the keyboard:
133 M-x pui-list-packages
135 The visual package browser will then display a list of all packages.
136 Help information will be displayed at the very bottom of the buffer; you
137 may have to scroll down to see it. You can also press `?' to get the
138 same help. From this buffer, you can tell the package status by the
139 character in the first column:
142 The package has not been installed.
145 The package has been installed, but a newer version is available.
146 The current version is out-of-date.
149 The package has been marked for installation/update.
151 If there is no character in the first column, the package has been
152 installed and is up-to-date.
154 From here, you can select or unselect packages for installation using
155 the <RET> key, the `Mouse-2' button or selecting "Select" from the
156 (Popup) Menu. Once you've finished selecting the packages, you can
157 press the `x' key (or use the menu) to actually install the packages.
158 Note that you will have to restart XEmacs for XEmacs to recognize any
168 Toggle between selecting and unselecting a package for
172 Install selected packages.
175 View, in the minibuffer, additional information about the package,
176 such as the package date (not the build date) and the package
177 author. Moving the mouse over a package name will also do the
181 Toggle between verbose and non-verbose package display.
184 Refresh the package display.
187 Kill the package buffer.
189 Moving the mouse over a package will also cause additional
190 information about the package to be displayed in the minibuffer.
192 Other package installation interfaces
193 -------------------------------------
195 For an alternative package interface, you can select packages from
196 the customize menus, under:
198 Options->Customize->Emacs->Packages-> ...
200 Options->Manage Packages->Using Custom->Select-> ...
202 Set their state to on, and then do:
204 Options->Manage Packages->Using Custom->Update Packages
206 This will automatically retrieve the packages you have selected from
207 the XEmacs ftp site or your local disk, and install them into XEmacs.
208 Additionally it will update any packages you already have installed to
209 the newest version. Note that if a package is newly installed you will
210 have to restart XEmacs for the change to take effect.
212 You can also install packages using a semi-manual interface:
214 M-x package-get-all <return>
216 Enter the name of the package (e.g., `prog-modes'), and XEmacs will
217 search for the latest version (as listed in the lisp file
218 `lisp/package-get-base.el'), and install it and any packages that it
221 Manual Binary Package Installation
222 ----------------------------------
224 Pre-compiled, binary packages can be installed in either a system
225 package directory (this is determined when XEmacs is compiled), or in
226 one of the following subdirectories of your `$HOME' directory:
228 ~/.xemacs/mule-packages
229 ~/.xemacs/xemacs-packages
231 Packages in the former directory will only be found by a Mule-enabled
234 XEmacs does not have to be running to install binary packages,
235 although XEmacs will not know about any newly-installed packages until
236 you restart XEmacs. Note, however, that installing a newer version of a
237 package while XEmacs is running could cause strange errors in XEmacs;
238 it's best to exit XEmacs before upgrading an existing package.
240 To install binary packages manually:
242 1. Download the package(s) that you want to install. Each binary
243 package will typically be a gzip'd tarball.
245 2. Decide where to install the packages: in the system package
246 directory, or in `~/.xemacs/mule-packages' or
247 `~/.xemacs/xemacs-packages', respectively. If you want to install
248 the packages in the system package directory, make sure you can
249 write into that directory. If you want to install in your `$HOME'
250 directory, create the directory, `~/.xemacs/mule-packages' or
251 `~/.xemacs/xemacs-packages', respectively.
253 3. Next, `cd' to the directory under which you want to install the
256 4. From this directory, uncompress and extract each of the gzip'd
257 tarballs that you downloaded in step 1. Unix and Cygnus cygwin
258 users will typically do this using the commands:
260 gunzip < package.tar.gz | tar xvf -
262 Above, replace `package.tar.gz' with the filename of the package
263 that you downloaded in step 1.
265 Of course, if you use GNU `tar', you could also use:
267 tar xvzf package.tar.gz
269 5. That's it. Quit and restart XEmacs to get it to recognize any new
274 File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
276 Source packages are available from the `packages/source-packages'
277 subdirectory of your favorite XEmacs distribution site. Alternatively,
278 they are available via CVS from `cvs.xemacs.org'. Look at
279 `http://cvs.xemacs.org' for instructions.
281 Prerequisites for Building Source Packages
282 ------------------------------------------
284 You must have GNU `cp', GNU `install' (or a BSD compatible `install'
285 program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from
286 `texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The
287 source packages will untar into a correct directory structure. At the
288 top level you must have `XEmacs.rules' and `package-compile.el'. These
289 files are available from the XEmacs FTP site from the same place you
290 obtained your source package distributions.
292 What You Can Do With Source Packages
293 ------------------------------------
295 NB: A global build operation doesn't exist yet as of 13 January
298 Source packages are most useful for creating XEmacs package tarballs
299 for installation into your own XEmacs installations or for distributing
302 Supported operations from `make' are:
305 Remove all built files except `auto-autoloads.el' and
309 Remove XEmacs backups as well as the files deleted by `make clean'.
312 Bytecompile all files, build and bytecompile byproduct files like
313 `auto-autoloads.el' and `custom-load.el'. Create info version of
314 TeXinfo documentation if present.
317 Usually aliased to `make srckit-std'. This does a `make
318 distclean' and creates a package source tarball in the staging
319 directory. This is generally only of use for package maintainers.
322 May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
323 `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
324 indicates there is nothing to install in a data directory or info
325 directory. `sourceinfo' indicates that source and info files are
326 to be installed. `sourcedata' indicates that source and etc
327 (data) files are to be installed. `sourcedatainfo' indicates
328 source, etc (data), and info files are to be installed. A few
329 packages have needs beyond the basic templates so this is not yet
333 Runs the rules `srckit' followed by `binkit'. This is primarily
334 of use by XEmacs maintainers producing files for distribution.
337 File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
342 An "abbrev" is a word which "expands" into some different text.
343 Abbrevs are defined by the user to expand in specific ways. For
344 example, you might define `foo' as an abbrev expanding to `find outer
345 otter'. With this abbrev defined, you would be able to get `find outer
346 otter ' into the buffer by typing `f o o <SPC>'.
348 Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
349 Disabling Abbrev mode does not cause abbrev definitions to be discarded,
350 but they do not expand until Abbrev mode is enabled again. The command
351 `M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
352 turns Abbrev mode on if the argument is positive, off otherwise. *Note
353 Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
354 when the variable is non-`nil'. The variable `abbrev-mode'
355 automatically becomes local to the current buffer when it is set.
357 Abbrev definitions can be "mode-specific"--active only in one major
358 mode. Abbrevs can also have "global" definitions that are active in
359 all major modes. The same abbrev can have a global definition and
360 various mode-specific definitions for different major modes. A
361 mode-specific definition for the current major mode overrides a global
364 You can define Abbrevs interactively during an editing session. You
365 can also save lists of abbrev definitions in files and reload them in
366 later sessions. Some users keep extensive lists of abbrevs that they
367 load in every session.
369 A second kind of abbreviation facility is called the "dynamic
370 expansion". Dynamic abbrev expansion happens only when you give an
371 explicit command and the result of the expansion depends only on the
372 current contents of the buffer. *Note Dynamic Abbrevs::.
376 * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
377 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
378 * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
379 * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
380 * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
383 File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
389 Define an abbrev to expand into some text before point
390 (`add-global-abbrev').
393 Similar, but define an abbrev available only in the current major
394 mode (`add-mode-abbrev').
397 Define a word in the buffer as an abbrev
398 (`inverse-add-global-abbrev').
401 Define a word in the buffer as a mode-specific abbrev
402 (`inverse-add-mode-abbrev').
404 `M-x kill-all-abbrevs'
405 After this command, no abbrev definitions remain in effect.
407 The usual way to define an abbrev is to enter the text you want the
408 abbrev to expand to, position point after it, and type `C-x a g'
409 (`add-global-abbrev'). This reads the abbrev itself using the
410 minibuffer, and then defines it as an abbrev for one or more words
411 before point. Use a numeric argument to say how many words before point
412 should be taken as the expansion. For example, to define the abbrev
413 `foo' as in the example above, insert the text `find outer otter', then
415 `C-u 3 C-x a g f o o <RET>'.
417 An argument of zero to `C-x a g' means to use the contents of the
418 region as the expansion of the abbrev being defined.
420 The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
421 mode-specific abbrev. Mode-specific abbrevs are active only in a
422 particular major mode. `C-x a l' defines an abbrev for the major mode
423 in effect at the time `C-x a l' is typed. The arguments work the same
424 way they do for `C-x a g'.
426 If the text of an abbrev you want is already in the buffer instead of
427 the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
428 instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
429 instead of `C-x a l'. These commands are called "inverse" because they
430 invert the meaning of the argument found in the buffer and the argument
431 read using the minibuffer.
433 To change the definition of an abbrev, just add the new definition.
434 You will be asked to confirm if the abbrev has a prior definition. To
435 remove an abbrev definition, give a negative argument to `C-x a g' or
436 `C-x a l'. You must choose the command to specify whether to kill a
437 global definition or a mode-specific definition for the current mode,
438 since those two definitions are independent for one abbrev.
440 `M-x kill-all-abbrevs' removes all existing abbrev definitions.
443 File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
445 Controlling Abbrev Expansion
446 ============================
448 An abbrev expands whenever it is in a buffer just before point and
449 you type a self-inserting punctuation character (<SPC>, comma, etc.).
450 Most often an abbrev is used by inserting the abbrev followed by
453 Abbrev expansion preserves case; thus, `foo' expands into `find
454 outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
455 OTTER' or `Find Outer Otter' according to the variable
456 `abbrev-all-caps' (a non-`nil' value chooses the first of the two
459 Two commands are available to control abbrev expansion:
462 Separate a prefix from a following abbrev to be expanded
463 (`abbrev-prefix-mark').
466 Expand the abbrev before point (`expand-abbrev'). This is
467 effective even when Abbrev mode is not enabled.
469 `M-x unexpand-abbrev'
470 Undo last abbrev expansion.
472 `M-x expand-region-abbrevs'
473 Expand some or all abbrevs found in the region.
475 You may wish to expand an abbrev with a prefix attached. For
476 example, if `cnst' expands into `construction', you may want to use it
477 to enter `reconstruction'. It does not work to type `recnst', because
478 that is not necessarily a defined abbrev. Instead, you can use the
479 command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the
480 abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a
481 minus sign in the buffer to indicate that it has done its work. Then
482 insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now
483 insert a punctuation character to expand the abbrev `cnst' into
484 `construction'. The minus sign is deleted at this point by `M-''. The
485 resulting text is the desired `reconstruction'.
487 If you actually want the text of the abbrev in the buffer, rather
488 than its expansion, insert the following punctuation with `C-q'. Thus,
489 `foo C-q -' leaves `foo-' in the buffer.
491 If you expand an abbrev by mistake, you can undo the expansion
492 (replace the expansion by the original abbrev text) with `M-x
493 unexpand-abbrev'. You can also use `C-_' (`undo') to undo the
494 expansion; but that will first undo the insertion of the punctuation
497 `M-x expand-region-abbrevs' searches through the region for defined
498 abbrevs, and offers to replace each one it finds with its expansion.
499 This command is useful if you have typed text using abbrevs but forgot
500 to turn on Abbrev mode first. It may also be useful together with a
501 special set of abbrev definitions for making several global
502 replacements at once. The command is effective even if Abbrev mode is
506 File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
508 Examining and Editing Abbrevs
509 =============================
512 Print a list of all abbrev definitions.
515 Edit a list of abbrevs; you can add, alter, or remove definitions.
517 The output from `M-x list-abbrevs' looks like this:
519 (lisp-mode-abbrev-table)
521 (global-abbrev-table)
524 (Some blank lines of no semantic significance, and some other abbrev
525 tables, have been omitted.)
527 A line containing a name in parentheses is the header for abbrevs in
528 a particular abbrev table; `global-abbrev-table' contains all the global
529 abbrevs, and the other abbrev tables that are named after major modes
530 contain the mode-specific abbrevs.
532 Within each abbrev table, each non-blank line defines one abbrev.
533 The word at the beginning is the abbrev. The number that appears is
534 the number of times the abbrev has been expanded. Emacs keeps track of
535 this to help you see which abbrevs you actually use, in case you want
536 to eliminate those that you don't use often. The string at the end of
537 the line is the expansion.
539 `M-x edit-abbrevs' allows you to add, change or kill abbrev
540 definitions by editing a list of them in an Emacs buffer. The list has
541 the format described above. The buffer of abbrevs is called
542 `*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key
543 `C-c C-c' to install the abbrev definitions as specified in the buffer.
544 The `edit-abbrevs-redefine' command does this. Any abbrevs not
545 described in the buffer are eliminated when this is done.
547 `edit-abbrevs' is actually the same as `list-abbrevs', except that
548 it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
549 displays it in another window.
552 File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
557 These commands allow you to keep abbrev definitions between editing
560 `M-x write-abbrev-file'
561 Write a file describing all defined abbrevs.
563 `M-x read-abbrev-file'
564 Read such an abbrev file and define abbrevs as specified there.
566 `M-x quietly-read-abbrev-file'
567 Similar, but do not display a message about what is going on.
570 Define abbrevs from buffer.
573 Insert all abbrevs and their expansions into the buffer.
575 Use `M-x write-abbrev-file' to save abbrev definitions for use in a
576 later session. The command reads a file name using the minibuffer and
577 writes a description of all current abbrev definitions into the
578 specified file. The text stored in the file looks like the output of
581 `M-x read-abbrev-file' prompts for a file name using the minibuffer
582 and reads the specified file, defining abbrevs according to its
583 contents. `M-x quietly-read-abbrev-file' is the same but does not
584 display a message in the echo area; it is actually useful primarily in
585 the init file. *Note Init File::. If you give an empty argument to
586 either of these functions, the file name Emacs uses is the value of the
587 variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'.
589 Emacs offers to save abbrevs automatically if you have changed any of
590 them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
591 Set the variable `save-abbrevs' to `nil' to inhibit this feature.
593 The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
594 similar to the previous commands but work on text in an Emacs buffer.
595 `M-x insert-abbrevs' inserts text into the current buffer before point,
596 describing all current abbrev definitions; `M-x define-abbrevs' parses
597 the entire current buffer and defines abbrevs accordingly.
600 File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
602 Dynamic Abbrev Expansion
603 ========================
605 The abbrev facility described above operates automatically as you
606 insert text, but all abbrevs must be defined explicitly. By contrast,
607 "dynamic abbrevs" allow the meanings of abbrevs to be determined
608 automatically from the contents of the buffer, but dynamic abbrev
609 expansion happens only when you request it explicitly.
612 Expand the word in the buffer before point as a "dynamic abbrev",
613 by searching in the buffer for words starting with that
614 abbreviation (`dabbrev-expand').
616 For example, if the buffer contains `does this follow ' and you type
617 `f o M-/', the effect is to insert `follow' because that is the last
618 word in the buffer that starts with `fo'. A numeric argument to `M-/'
619 says to take the second, third, etc. distinct expansion found looking
620 backward from point. Repeating `M-/' searches for an alternative
621 expansion by looking farther back. After the entire buffer before
622 point has been considered, the buffer after point is searched.
624 Dynamic abbrev expansion is completely independent of Abbrev mode;
625 the expansion of a word with `M-/' is completely independent of whether
626 it has a definition as an ordinary abbrev.
629 File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top
634 If you want to create a picture made out of text characters (for
635 example, a picture of the division of a register into fields, as a
636 comment in a program), use the command `edit-picture' to enter Picture
639 In Picture mode, editing is based on the "quarter-plane" model of
640 text. In this model, the text characters lie studded on an area that
641 stretches infinitely far to the right and downward. The concept of the
642 end of a line does not exist in this model; the most you can say is
643 where the last non-blank character on the line is found.
645 Of course, Emacs really always considers text as a sequence of
646 characters, and lines really do have ends. But in Picture mode most
647 frequently-used keys are rebound to commands that simulate the
648 quarter-plane model of text. They do this by inserting spaces or by
649 converting tabs to spaces.
651 Most of the basic editing commands of Emacs are redefined by Picture
652 mode to do essentially the same thing but in a quarter-plane way. In
653 addition, Picture mode defines various keys starting with the `C-c'
654 prefix to run special picture editing commands.
656 One of these keys, `C-c C-c', is pretty important. Often a picture
657 is part of a larger file that is usually edited in some other major
658 mode. `M-x edit-picture' records the name of the previous major mode.
659 You can then use the `C-c C-c' command (`picture-mode-exit') to restore
660 that mode. `C-c C-c' also deletes spaces from the ends of lines,
661 unless you give it a numeric argument.
663 The commands used in Picture mode all work in other modes (provided
664 the `picture' library is loaded), but are only bound to keys in
665 Picture mode. Note that the descriptions below talk of moving "one
666 column" and so on, but all the picture mode commands handle numeric
667 arguments as their normal equivalents do.
669 Turning on Picture mode calls the value of the variable
670 `picture-mode-hook' as a function, with no arguments, if that value
671 exists and is non-`nil'.
675 * Basic Picture:: Basic concepts and simple commands of Picture Mode.
676 * Insert in Picture:: Controlling direction of cursor motion
677 after "self-inserting" characters.
678 * Tabs in Picture:: Various features for tab stops and indentation.
679 * Rectangles in Picture:: Clearing and superimposing rectangles.
682 File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture
684 Basic Editing in Picture Mode
685 =============================
687 Most keys do the same thing in Picture mode that they usually do,
688 but do it in a quarter-plane style. For example, `C-f' is rebound to
689 run `picture-forward-column', which moves point one column to the
690 right, by inserting a space if necessary, so that the actual end of the
691 line makes no difference. `C-b' is rebound to run
692 `picture-backward-column', which always moves point left one column,
693 converting a tab to multiple spaces if necessary. `C-n' and `C-p' are
694 rebound to run `picture-move-down' and `picture-move-up', which can
695 either insert spaces or convert tabs as necessary to make sure that
696 point stays in exactly the same column. `C-e' runs
697 `picture-end-of-line', which moves to after the last non-blank
698 character on the line. There was no need to change `C-a', as the choice
699 of screen model does not affect beginnings of lines.
701 Insertion of text is adapted to the quarter-plane screen model
702 through the use of Overwrite mode (*note Minor Modes::).
703 Self-inserting characters replace existing text, column by column,
704 rather than pushing existing text to the right. <RET> runs
705 `picture-newline', which just moves to the beginning of the following
706 line so that new text will replace that line.
708 Text is erased instead of deleted and killed. <DEL>
709 (`picture-backward-clear-column') replaces the preceding character with
710 a space rather than removing it. `C-d' (`picture-clear-column') does
711 the same in a forward direction. `C-k' (`picture-clear-line') really
712 kills the contents of lines, but never removes the newlines from a
715 To do actual insertion, you must use special commands. `C-o'
716 (`picture-open-line') creates a blank line, but does so after the
717 current line; it never splits a line. `C-M-o', `split-line', makes
718 sense in Picture mode, so it remains unchanged. <LFD>
719 (`picture-duplicate-line') inserts another line with the same contents
720 below the current line.
722 To actually delete parts of the picture, use `C-w', or with `C-c
723 C-d' (which is defined as `delete-char', as `C-d' is in other modes),
724 or with one of the picture rectangle commands (*note Rectangles in
728 File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
730 Controlling Motion After Insert
731 ===============================
733 Since "self-inserting" characters just overwrite and move point in
734 Picture mode, there is no essential restriction on how point should be
735 moved. Normally point moves right, but you can specify any of the eight
736 orthogonal or diagonal directions for motion after a "self-inserting"
737 character. This is useful for drawing lines in the buffer.
740 Move left after insertion (`picture-movement-left').
743 Move right after insertion (`picture-movement-right').
746 Move up after insertion (`picture-movement-up').
749 Move down after insertion (`picture-movement-down').
752 Move up and left ("northwest") after insertion
753 (`picture-movement-nw').
756 Move up and right ("northeast") after insertion
757 (`picture-movement-ne').
760 Move down and left ("southwest") after insertion
761 (`picture-movement-sw').
764 Move down and right ("southeast") after insertion
765 (`picture-movement-se').
767 Two motion commands move based on the current Picture insertion
768 direction. The command `C-c C-f' (`picture-motion') moves in the same
769 direction as motion after "insertion" currently does, while `C-c C-b'
770 (`picture-motion-reverse') moves in the opposite direction.
773 File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture
778 Two kinds of tab-like action are provided in Picture mode.
779 Context-based tabbing is done with `M-<TAB>' (`picture-tab-search').
780 With no argument, it moves to a point underneath the next "interesting"
781 character that follows whitespace in the previous non-blank line.
782 "Next" here means "appearing at a horizontal position greater than the
783 one point starts out at". With an argument, as in `C-u M-<TAB>', the
784 command moves to the next such interesting character in the current
785 line. `M-<TAB>' does not change the text; it only moves point.
786 "Interesting" characters are defined by the variable
787 `picture-tab-chars', which contains a string of characters considered
788 interesting. Its default value is `"!-~"'.
790 <TAB> itself runs `picture-tab', which operates based on the current
791 tab stop settings; it is the Picture mode equivalent of
792 `tab-to-tab-stop'. Without arguments it just moves point, but with a
793 numeric argument it clears the text that it moves over.
795 The context-based and tab-stop-based forms of tabbing are brought
796 together by the command `C-c <TAB>' (`picture-set-tab-stops'.) This
797 command sets the tab stops to the positions which `M-<TAB>' would
798 consider significant in the current line. If you use this command with
799 <TAB>, you can get the effect of context-based tabbing. But `M-<TAB>'
800 is more convenient in the cases where it is sufficient.
803 File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
805 Picture Mode Rectangle Commands
806 ===============================
808 Picture mode defines commands for working on rectangular pieces of
809 the text in ways that fit with the quarter-plane model. The standard
810 rectangle commands may also be useful (*note Rectangles::).
813 Clear out the region-rectangle (`picture-clear-rectangle'). With
817 Similar but save rectangle contents in register R first
818 (`picture-clear-rectangle-to-register').
821 Copy last killed rectangle into the buffer by overwriting, with
822 upper left corner at point (`picture-yank-rectangle'). With
823 argument, insert instead.
826 Similar, but use the rectangle in register R
827 (`picture-yank-rectangle-from-register').
829 The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
830 and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
831 standard rectangle commands in that they normally clear the rectangle
832 instead of deleting it; this is analogous with the way `C-d' is changed
835 However, deletion of rectangles can be useful in Picture mode, so
836 these commands delete the rectangle if given a numeric argument.
838 The Picture mode commands for yanking rectangles differ from the
839 standard ones in overwriting instead of inserting. This is the same
840 way that Picture mode insertion of other text is different from other
841 modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
842 the rectangle that was most recently killed, while `C-c C-x'
843 (`picture-yank-rectangle-from-register') does for the rectangle found
844 in a specified register.
846 Since most region commands in Picture mode operate on rectangles,
847 when you select a region of text with the mouse in Picture mode, it is
848 highlighted as a rectangle.
851 File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top
856 To send a message in Emacs, start by typing the command (`C-x m') to
857 select and initialize the `*mail*' buffer. You can then edit the text
858 and headers of the message in the mail buffer, and type the command
859 (`C-c C-c') to send the message.
862 Begin composing a message to send (`mail').
865 Likewise, but display the message in another window
866 (`mail-other-window').
869 In Mail mode, send the message and switch to another buffer
870 (`mail-send-and-exit').
872 The command `C-x m' (`mail') selects a buffer named `*mail*' and
873 initializes it with the skeleton of an outgoing message. `C-x 4 m'
874 (`mail-other-window') selects the `*mail*' buffer in a different
875 window, leaving the previous current buffer visible.
877 Because the buffer for mail composition is an ordinary Emacs buffer,
878 you can switch to other buffers while in the middle of composing mail,
879 and switch back later (or never). If you use the `C-x m' command again
880 when you have been composing another message but have not sent it, a
881 new mail buffer will be created; in this way, you can compose multiple
882 messages at once. You can switch back to and complete an unsent
883 message by using the normal buffer selection mechanisms.
885 `C-u C-x m' is another way to switch back to a message in progress:
886 it will search for an existing, unsent mail message buffer and select
891 * Format: Mail Format. Format of the mail being composed.
892 * Headers: Mail Headers. Details of allowed mail header fields.
893 * Mode: Mail Mode. Special commands for editing mail being composed.
896 File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
898 The Format of the Mail Buffer
899 =============================
901 In addition to the "text" or contents, a message has "header
902 fields", which say who sent it, when, to whom, why, and so on. Some
903 header fields, such as the date and sender, are created automatically
904 after the message is sent. Others, such as the recipient names, must
905 be specified by you in order to send the message properly.
907 Mail mode provides a few commands to help you edit some header
908 fields, and some are preinitialized in the buffer automatically at
909 times. You can insert or edit any header fields using ordinary editing
912 The line in the buffer that says:
914 --text follows this line--
916 is a special delimiter that separates the headers you have specified
917 from the text. Whatever follows this line is the text of the message;
918 the headers precede it. The delimiter line itself does not appear in
919 the message actually sent. The text used for the delimiter line is
920 controlled by the variable `mail-header-separator'.
922 Here is an example of what the headers and text in the `*mail*'
923 buffer might look like.
927 Subject: The XEmacs User's Manual
928 --Text follows this line--
929 Please ignore this message.
932 File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
937 There are several header fields you can use in the `*mail*' buffer.
938 Each header field starts with a field name at the beginning of a line,
939 terminated by a colon. It does not matter whether you use upper or
940 lower case in the field name. After the colon and optional whitespace
941 comes the contents of the field.
944 This field contains the mailing addresses of the message.
947 The contents of the `Subject' field should be a piece of text that
948 says what the message is about. Subject fields are useful because
949 most mail-reading programs can provide a summary of messages,
950 listing the subject of each message but not its text.
953 This field contains additional mailing addresses to send the
954 message to, but whose readers should not regard the message as
958 This field contains additional mailing addresses to send the
959 message to, but which should not appear in the header of the
960 message actually sent.
963 This field contains the name of one file (in Unix mail file
964 format) to which a copy of the message should be appended when the
968 Use the `From' field to say who you are, when the account you are
969 using to send the mail is not your own. The contents of the
970 `From' field should be a valid mailing address, since replies will
974 Use the `Reply-To' field to direct replies to a different address,
975 not your own. `From' and `Reply-To' have the same effect on where
976 replies go, but they convey a different meaning to the person who
980 This field contains a piece of text describing a message you are
981 replying to. Some mail systems can use the information to
982 correlate related pieces of mail. This field is normally filled
983 in by your mail handling package when you are replying to a
984 message and you never need to think about it.
986 The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
987 to specify many places to send the message.
989 The `To', `CC', and `BCC', fields can have continuation lines. All the
990 lines starting with whitespace, following the line on which the field
991 starts, are considered part of the field. For example,
993 To: foo@here, this@there,
994 me@gnu.cambridge.mass.usa.earth.spiral3281
996 If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
997 first time you try to send mail in an Emacs session. Emacs expands
998 aliases found in the `To', `CC', and `BCC' fields where appropriate.
999 You can set the variable `mail-abbrev-mailrc-file' to the name of the
1000 file with mail aliases. If `nil', `~/.mailrc' is used.
1002 Your `.mailrc' file ensures that word-abbrevs are defined for each
1003 of your mail aliases when point is in a `To', `CC', `BCC', or `From'
1004 field. The aliases are defined in your `.mailrc' file or in a file
1005 specified by the MAILRC environment variable if it exists. Your mail
1006 aliases expand any time you type a word-delimiter at the end of an
1009 In this version of Emacs, what you see is what you get: in contrast
1010 to some other versions, no abbreviations are expanded after you have
1011 sent the mail. This means you don't suffer the annoyance of having the
1012 system do things behind your back--if the system rewrites an address
1013 you typed, you know it immediately, instead of after the mail has been
1014 sent and it's too late to do anything about it. For example, you will
1015 never again be in trouble because you forgot to delete an old alias
1016 from your `.mailrc' and a new local user is given a userid which
1017 conflicts with one of your aliases.
1019 Your mail alias abbrevs are in effect only when point is in an
1020 appropriate header field. The mail aliases will not expand in the body
1021 of the message, or in other header fields. The default mode-specific
1022 abbrev table `mail-mode-abbrev-table' is used instead if defined. That
1023 means if you have been using mail-mode specific abbrevs, this code will
1024 not adversely affect you. You can control which header fields the
1025 abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.
1027 If auto-fill mode is on, abbrevs wrap at commas instead of at word
1028 boundaries, and header continuation lines will be properly indented.
1030 You can also insert a mail alias with
1031 `mail-interactive-insert-alias'. This function, which is bound to `C-c
1032 C-a', prompts you for an alias (with completion) and inserts its
1035 In this version of Emacs, it is possible to have lines like the
1036 following in your `.mailrc' file:
1038 alias someone "John Doe <doe@quux.com>"
1040 That is, if you want an address to have embedded spaces, simply
1041 surround it with double-quotes. The quotes are necessary because the
1042 format of the `.mailrc' file uses spaces as address delimiters.
1044 Aliases in the `.mailrc' file may be nested. For example, assume you
1045 define aliases like:
1046 alias group1 fred ethel
1047 alias group2 larry curly moe
1048 alias everybody group1 group2
1050 When you now type `everybody' on the `To' line, it will expand to:
1051 fred, ethyl, larry, curly, moe
1053 Aliases may contain forward references; the alias of `everybody' in
1054 the example above can precede the aliases of `group1' and `group2'.
1056 In this version of Emacs, you can use the `source' `.mailrc' command
1057 for reading aliases from some other file as well.
1059 Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
1060 though word-abbrevs normally cannot contain hyphens.
1062 To read in the contents of another `.mailrc'-type file from Emacs,
1063 use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases'
1064 command is similar, but deletes existing aliases first.
1066 If you want multiple addresses separated by a string other than `,'
1067 (a comma), then set the variable `mail-alias-separator-string' to it.
1068 This has to be a comma bracketed by whitespace if you want any kind of
1069 reasonable behavior.
1071 If the variable `mail-archive-file-name' is non-`nil', it should be
1072 a string naming a file. Each time you start to edit a message to send,
1073 an `FCC' field is entered for that file. Unless you remove the `FCC'
1074 field, every message is written into that file when it is sent.
1077 File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail
1082 The major mode used in the `*mail*' buffer is Mail mode. Mail mode
1083 is similar to Text mode, but several commands are provided on the `C-c'
1084 prefix. These commands all deal specifically with editing or sending
1088 Send the message, and leave the `*mail*' buffer selected
1092 Send the message, and select some other buffer
1093 (`mail-send-and-exit').
1096 Move to the `To' header field, creating one if there is none
1100 Move to the `Subject' header field, creating one if there is none
1104 Move to the `CC' header field, creating one if there is none
1108 Insert the file `~/.signature' at the end of the message text
1112 Yank the selected message (`mail-yank-original').
1115 Fill all paragraphs of yanked old messages, each individually
1116 (`mail-fill-yanked-message').
1119 Pops up a menu of useful mail-mode commands.
1121 There are two ways to send a message. `C-c C-c'
1122 (`mail-send-and-exit') is the usual way to send the message. It sends
1123 the message and then deletes the window (if there is another window) or
1124 switches to another buffer. It puts the `*mail*' buffer at the lowest
1125 priority for automatic reselection, since you are finished with using
1126 it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*'
1127 buffer unmodified, but leaves that buffer selected so that you can
1128 modify the message (perhaps with new recipients) and send it again.
1130 Mail mode provides some other special commands that are useful for
1131 editing the headers and text of the message before you send it. There
1132 are three commands defined to move point to particular header fields,
1133 all based on the prefix `C-c C-f' (`C-f' is for "field"). They are
1134 `C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
1135 (`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
1136 for the `CC' field. These fields have special motion commands because
1137 they are edited most frequently.
1139 `C-c C-w' (`mail-signature') adds a standard piece of text at the
1140 end of the message to say more about who you are. The text comes from
1141 the file `.signature' in your home directory.
1143 When you use an Rmail command to send mail from the Rmail mail
1144 reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*'
1145 buffer to insert the text of the message you are replying to. Normally
1146 Rmail indents each line of that message four spaces and eliminates most
1147 header fields. A numeric argument specifies the number of spaces to
1148 indent. An argument of just `C-u' says not to indent at all and not to
1149 eliminate anything. `C-c C-y' always uses the current message from the
1150 `RMAIL' buffer, so you can insert several old messages by selecting one
1151 in `RMAIL', switching to `*mail*' and yanking it, then switching back
1152 to `RMAIL' to select another.
1154 After using `C-c C-y', you can use the command `C-c C-q'
1155 (`mail-fill-yanked-message') to fill the paragraphs of the yanked old
1156 message or messages. One use of `C-c C-q' fills all such paragraphs,
1157 each one separately.
1159 Clicking the right mouse button in a mail buffer pops up a menu of
1160 the above commands, for easy access.
1162 Turning on Mail mode (which `C-x m' does automatically) calls the
1163 value of `text-mode-hook', if it is not void or `nil', and then calls
1164 the value of `mail-mode-hook' if that is not void or `nil'.
1167 File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top
1172 XEmacs provides three separate mail-reading packages. Each one
1173 comes with its own manual, which is included standard with the XEmacs
1176 The recommended mail-reading package for new users is VM. VM works
1177 with standard Unix-mail-format folders and was designed as a replacement
1178 for the older Rmail.
1180 XEmacs also provides a sophisticated and comfortable front-end to the
1181 MH mail-processing system, called `mh-e'. Unlike in other mail
1182 programs, folders in MH are stored as file-system directories, with
1183 each message occupying one (numbered) file. This facilitates working
1184 with mail using shell commands, and many other features of MH are also
1185 designed to integrate well with the shell and with shell scripts. Keep
1186 in mind, however, that in order to use mh-e you must have the MH
1187 mail-processing system installed on your computer.
1189 Finally, XEmacs provides the Rmail package. Rmail is (currently) the
1190 only mail reading package distributed with FSF GNU Emacs, and is
1191 powerful in its own right. However, it stores mail folders in a special
1192 format called `Babyl', that is incompatible with all other
1193 frequently-used mail programs. A utility program is provided for
1194 converting Babyl folders to standard Unix-mail format; however, unless
1195 you already have mail in Babyl-format folders, you should consider
1196 using VM or mh-e instead. (If at times you have to use FSF Emacs, it is
1197 not hard to obtain and install VM for that editor.)
1200 File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top
1202 Calendar Mode and the Diary
1203 ===========================
1205 Emacs provides the functions of a desk calendar, with a diary of
1206 planned or past events. To enter the calendar, type `M-x calendar';
1207 this displays a three-month calendar centered on the current month, with
1208 point on the current date. With a numeric argument, as in `C-u M-x
1209 calendar', it prompts you for the month and year to be the center of the
1210 three-month calendar. The calendar uses its own buffer, whose major
1211 mode is Calendar mode.
1213 `Button2' in the calendar brings up a menu of operations on a
1214 particular date; `Buttons3' brings up a menu of commonly used calendar
1215 features that are independent of any particular date. To exit the
1216 calendar, type `q'. *Note Customizing the Calendar and Diary:
1217 (elisp)Calendar, for customization information about the calendar and
1222 * Calendar Motion:: Moving through the calendar; selecting a date.
1223 * Scroll Calendar:: Bringing earlier or later months onto the screen.
1224 * Mark and Region:: Remembering dates, the mark ring.
1225 * General Calendar:: Exiting or recomputing the calendar.
1226 * LaTeX Calendar:: Print a calendar using LaTeX.
1227 * Holidays:: Displaying dates of holidays.
1228 * Sunrise/Sunset:: Displaying local times of sunrise and sunset.
1229 * Lunar Phases:: Displaying phases of the moon.
1230 * Other Calendars:: Converting dates to other calendar systems.
1231 * Diary:: Displaying events from your diary.
1232 * Calendar Customization:: Altering the behavior of the features above.