3 @c Copyright (C) 2002, 2003 Free Software Foundation, Inc.
4 @c Copyright (C) 2003 Jake Colman
6 @c @setfilename edit-utils.info
7 @settitle Editing Utilities for XEmacs
9 @dircategory XEmacs Editor
11 * Edit Utilities: (edit-utils). Editing Utilities for XEmacs.
16 This manual is part of XEmacs.
18 XEmacs is free software; you can redistribute it and/or modify it
19 under the terms of the GNU General Public License as published by
20 the Free Software Foundation; either version 2, or (at your option)
23 XEmacs is distributed in the hope that it will be useful, but
24 WITHOUT ANY WARRANTY; without even the implied warranty of
25 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
26 General Public License for more details.
28 You should have received a copy of the GNU General Public License
29 along with XEmacs; see the file COPYING. If not, write to the Free
30 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
34 @node Top, Copying, (dir), (dir)
35 @chapter The Editing Utilities Package
38 This Info file contains the manual for the Editing Utilities package.
41 The node name for each entry in the menu is the name of the elisp file
42 containing the code that implements the functionality described. It is
43 highly recommended that you briefly peruse the elisp source code since it can
44 provide valuable information on usage and technique. This can easily be done
45 by typing @code{C-x 4 l <filename> RET} where <filename> is the name of the
46 elisp file to be loaded.
49 * Copying:: Why this manual is GPL, and what that means
51 Buffer and Window Management
52 * compare-w:: Comparing Windows
53 * detached-minibuf:: Detached Minibuffers
54 * iswitchb:: Convenient Buffer Switching
55 * permanent-buffers:: Permanent Buffers
56 * rsz-minibuf:: Self-Resizing Minibuffer
57 * search-buffers:: Searching Many Buffers
58 * uniquify:: Meaningful Unique Names
59 * winring:: Window Configuration Rings
60 * autorevert:: Reverting Buffers
63 * foldout:: Folding Extensions for Outline-Mode
64 * func-menu:: Jump to a Function Within a Buffer.
65 * id-select:: Select Syntax-Driven Regions in a Buffer
66 * outl-mouse:: Outline-Mode Mouse Commands
67 * page-ext:: Extended Page Handling Commands
68 * power-macros:: Power Macros - Keyboard Macros Made Easy
69 * redo:: Redo/Undo System
70 * scroll-in-place:: Scrolling In Place
71 * setnu:: VI-style Line Number Mode
72 * vertical-mode:: Vertical Mode - Editing of Vertical Text
73 * align:: Align Text to a Specific Column, By Regexp
74 * allout:: Extensive Outline Mode
75 * narrow-stack:: Extending the built-in narrowing functions
76 * register-menu:: Menu for easier register interaction
77 * register-toolbar:: Toolbar for easier register interaction
80 * backup-dir:: Specify Directories to be Used for Backup Files
83 * bookmark:: Create annotated bookmarks
84 * desktop:: Save Partial Status of Emacs When Killed
85 * recent-files:: Recent File Navigation
86 * resume:: Resuming a Suspended Emacs Job
87 * saveconf:: Save Buffer/Window Configuration Between Sessions
88 * savehist:: Save Minibuffer History
89 * saveplace:: Automatically Save Place in Files
90 * where-was-i-db:: Keep Persistent State in Visited Files
93 * completion:: Completion
94 * dabbrev:: Dynamic Abbreviations
95 * hippie-exp:: Hippie Expand
96 * icomplete:: Interactive Minibuffer Completion
97 * tempo:: Flexible Template Insertion
99 Display, Faces, and Highlighting:
100 * avoid:: Move Mouse Pointer Out of the Way of Editing
101 * blink-cursor:: Blinking Cursor
102 * fast-lock:: Speeding Up Font Lock Mode
103 * lazy-lock:: Lazy Demand-Driven Fontification
104 * lazy-shot:: Another Lazy Demand-Driven Fontification
105 * mic-paren:: Advanced Highlighting of Matching Parentheses
106 * paren:: Highlight (Un)matching Parens and Whole Expressions
107 * shell-font:: Decorate a Shell Buffer With Fonts
108 * highline:: Highlight the Current Line in the Buffer
109 * buffer-colors:: System for Buffer-Local Color Schemes
111 Low-Level Editing Hacks:
112 * after-save-commands:: Hooks Invoked After Saving a File
113 * atomic-extents:: Indivisible Blocks of Text
114 * array:: Table and Array Editor
116 Menu and Toolbar Support:
117 * floating-toolbar:: Floating Toolbar
118 * The Toolbar Utilities:: Creating and Managing Toolbars and Buttons.
121 * flow-ctrl:: Flow Control
122 * makesum:: Generate Summary of All Key Binding
123 * man:: Browse UNIX manual pages
126 * abbrevlist:: Abbreviation List
127 * file-part:: Treat a Section of a Buffer as a Separate File
128 * info-look:: Major-Mode-Sensitive Info Index Lookup Facility
129 * live-icon:: Make Frame Icons Represent Current Frame Contents
130 * mode-motion+:: Per Mode/Buffer Mouse Tracking With Highlighting
131 * popper:: Shrink-Wrapped Temporary Windows
132 * reportmail:: Display Time and Load in Mode Line
133 * balloon-help:: Balloon Help and Tooltips
134 * blink-paren:: Blinking Parentheses
135 * edit-faces:: Face Editor
136 * lispm-fonts:: lispm-fonts
137 * big-menubar:: Big Menubar
138 * tree-menu:: tree-menu.el
141 * XEmacs License:: The GNU General Public License
144 @node Copying, compare-w, Top, Top
147 This document may be redistributed, verbatim or in modified form, under
148 the terms of the GNU General Public License, version 2 or any later
149 version. The same terms apply to the libraries it documents. A copy
150 of the General Public License is provided as an Appendix.
152 Most XEmacs documentation has its own license, which is an ancestor of
153 the GNU Free Documentation License (@dfn{FDL}), and whose terms are
154 quite similar to those imposed by GNU on Emacs documentation. Why is
155 this manual licensed differently (under the GNU General Public License,
156 or @dfn{GPL}), and why does it have to be distributed separately from
157 the XEmacs User's Guide and the XEmacs Lisp Reference Manual?
159 Taking the second question first, XEmacs is @dfn{community-owned}
160 software. That is, unlike GNU Emacs, there is no monopoly copyright
161 holder. Many of us, including the original Lucid authors, have
162 contributed our copyrights to the Free Software Foundation (FSF), and of
163 course much content is derived from GNU Emacs, and therefore is held by
164 the FSF. Another large chunk is held by Sun Microsystems, and a few
165 individual authors hold copyright to thousands of lines each. But many
166 individuals hold copyright to only a few dozen lines. Like the Linux
167 kernel, copyright ownership is distributed throughout a community.
169 However, its license is ``copyleft,'' @emph{i.e.}, it @emph{requires}
170 that you redistribute it under terms @emph{identical} to those under
171 which you received it, unless you have explicit permission of the
172 copyright holder. Because of the multiple owners, determining the
173 ownership of any given part of XEmacs is tedious, and perhaps
174 impossible. For practical purposes, then, the license of any
175 substantial chunk of existing XEmacs content cannot be changed, except
176 to a later version of the GPL, for those parts under GPL. (That is due
177 to the @emph{explicit} permission to change to a later version of the
178 GPL, present in every file of XEmacs.)
180 Unfortunately, this severe restriction means that the GPL, FDL, and the
181 XEmacs documentation license (@dfn{XDL}) are @emph{mutually
182 incompatible}. That is, content licensed under any of the GPL, FDL, or
183 XDL @emph{may not} be mixed with content licensed under either of the
184 other two without changing the license of some of the content. But this
185 requires permission of the copyright holder, which is often difficult or
188 For example, you @emph{may not} take comments or docstrings from XEmacs
189 code and add them to the Lispref to mend a gap in the latter's coverage.
190 You @emph{may not} copy text from the Lispref into docstrings in the
191 code. And you @emph{may not} copy text from the GNU Emacs Lisp
192 Reference to the XEmacs Lisp Reference Manual. (In this case it is at
193 least trivial to ask permission, although it is rather unclear whether
194 it would be granted.)
196 In fact, parts of this document were derived by copying from XEmacs code
197 under the GPL, without any further permission from the authors. Thus,
198 this document must be distributed under the GPL, as a ``volume''
199 separate from the XEmacs documentation under the XDL. Note that the
200 ``mere aggregation'' clauses allow us to distribute in the same
201 tarball. But incorporating it as a node in the Lispref is prohibited,
202 even if done by inclusion.
206 If you look carefully at the additional restrictions imposed by the
207 soi-disant "free" documentation licenses, you discover that they are
208 simply proprietary restrictions guaranteeing a certain amount of
209 @emph{unpaid} political advertising to the Free Software Foundation and
210 GNU Project (and in the case of the FDL, this is extended to commercial
211 advertising by authors of original or derived works). Whether this is
212 ``ethically justified'' or not is a difficult question. What is certain
213 is that there is little social benefit to these terms (since the license
214 documents themselves contain the advocacy and must be included with any
217 I conclude it makes sense for XEmacs to reduce its restrictions, where
218 possible, to the ``least common denominator,'' the GNU General Public
221 @node compare-w, detached-minibuf, Copying, Top
222 @chapter Comparing Windows
224 This package provides one entry point, compare-windows. It compares text
225 starting from point in two adjacent windows, advancing point until it finds a
226 difference. There are variables to permit ignoring of whitespace
227 differences, or case differences, or both.
229 @node detached-minibuf, iswitchb, compare-w, Top
230 @chapter Detached Minibuffers
232 This package creates a standalone minibuffer in its own frame.
234 To configure this package, type:
237 M-x customize-group RET detached-minibuf RET
240 @node iswitchb, permanent-buffers, detached-minibuf, Top
241 @chapter Convenient Buffer Switching
243 With this package installed, as you type in a substring, the list of buffers
244 currently matching the substring are displayed as you type. The list is
245 ordered so that the most recent buffers visited come at the start of the
246 list. The buffer at the start of the list will be the one visited when you
247 press return. By typing more of the substring, the list is narrowed down so
248 that gradually the buffer you want will be at the top of the list.
249 Alternatively, you can use @kbd{C-s} and @kbd{C-r} to rotate buffer names in
250 the list until the one you want is at the top of the list. Completion is
251 also available so that you can see what is common to all of the matching
254 For example, let's say we have two buffers called "123456" and "123", with
255 "123456" the most recent. When I use @samp{iswitchb}, I first of all get
256 presented with the list of all the buffers
258 @samp{iswitch @{123456,123@}}
260 If I then press @kbd{2}:
262 @samp{iswitch 2[3]@{123456,123@}}
264 The list in @{@} are the matching buffers, most recent first (buffers visible
265 in the current frame are put at the end of the list by default). At any time
266 I can select the item at the head of the list by pressing @kbd{RET}. I can
267 also bring the put the first element at the end of the list by pressing
268 @kbd{C-s}, or put the last element at the head of the list by pressing
269 @kbd{C-r}. The item in [] indicates what can be added to my input by
270 pressing @kbd{TAB}. In this case, I will get @samp{3} added to my input.
273 @samp{iswitch 23@{123456,123@}}
275 At this point, I still have two matching buffers. If I want the first buffer
276 in the list, I simply press @kbd{RET}. If I wanted the second in the list, I
277 could press @kbd{C-s} to move it to the top of the list and then @kbd{RET} to
280 However, If I type @kbd{4}, I only have one match left:
282 @samp{iswitch 234[123456] [Matched]}
284 Since there is only one matching buffer left, it is given in @samp{[]} and we
285 see the text @samp{[Matched]} afterwards. I can now press @kbd{TAB} or
286 @kbd{RET} to go to that buffer.
288 If however, I now type @kbd{a}:
290 @samp{iswitch 234a [No match]}
292 There are no matching buffers. If I press @kbd{RET} or @kbd{TAB}, I can be
293 prompted to create a new buffer called "234a".
295 Of course, where this function comes in really useful is when you can specify
296 the buffer using only a few keystrokes. In the above example, the quickest
297 way to get to the "123456" buffer would be just to type @kbd{4} and then
298 @kbd{RET} (assuming there isn't any newer buffer with "4" in its name).
300 To see a full list of all matching buffers in a separate buffer, hit @kbd{?}
301 or press @kbd{TAB} when there are no further completions to the substring.
302 Repeated @kbd{TAB} presses will scroll you through this separate buffer.
304 The buffer at the head of the list can be killed by pressing @kbd{C-k}. If
305 the buffer needs saving, you will be queried before the buffer is killed.
307 If you find that the file you are after is not in a buffer, you can press
308 @kbd{C-x C-f} to immediately drop into find-file.
310 To see the doc string of iswitchb for full keybindings and features, type:
313 M-x describe-function RET iswitchb
317 * Customization: iswitchb-cust.
318 * Changing the Display::
320 * Replacement for read-buffer::
323 @node iswitchb-cust, Changing the Display, iswitchb, iswitchb
324 @section Customization
326 To configure the package, type:
329 M-x customize-group RET iswitchb RET
332 To install this package on the default keys used for buffer switching, type:
335 M-x iswitchb-default-keybindings RET
338 To modify the default keybindings, use the hook provided. For example, the
339 following code can be added to your initialization file:
342 (add-hook 'iswitchb-define-mode-map-hook 'iswitchb-my-keys)
344 (defun iswitchb-my-keys ()
345 "Add my keybindings for iswitchb."
346 (define-key iswitchb-mode-map " " 'iswitchb-next-match)
350 @node Changing the Display, Regexp Matching, iswitchb-cust, iswitchb
351 @section Changing the Display
353 If you have many matching buffers, they may not all fit onto one line of the
354 minibuffer. In this case, you should use @code{(resize-minibuffer-mode)}
355 @xref{rsz-minibuf}. You can also limit iswitchb so that it only shows a
356 certain number of lines. To do this, see the documentation for
357 @code{iswitchb-minibuffer-setup-hook}.
359 By default, the list of current buffers is most recent first, oldest last,
360 with the exception that the buffers visible in the current frame are put at
361 the end of the list. A hook exists to allow other functions to order the
362 list. For example, if you add:
365 (add-hook 'iswitchb-make-buflist-hook 'iswitchb-summaries-to-end)
368 then all buffers matching "Summary" are moved to the end of the list. (I
369 find this handy for keeping the INBOX Summary and so on out of the way.) It
370 also moves buffers matching "output\*$" to the end of the list (these are
371 created by AUC TeX when compiling.) Other functions could be made available
372 which alter the list of matching buffers (either deleting or rearranging
375 If you have font-lock loaded, the first matching buffer is highlighted. To
376 switch this off, set @code{(setq iswitchb-use-fonts nil)}. I don't use
377 font-lock that much, so I've hardcoded the faces. If this is too harsh, let
378 me know. Colouring of the matching buffer name was suggested by Carsten
379 Dominik (dominik@@strw.leidenuniv.nl)
381 @node Regexp Matching, Replacement for read-buffer, Changing the Display, iswitchb
382 @section Regexp Matching
384 There is limited provision for regexp matching within @code{iswitchb},
385 enabled through @code{iswitchb-regexp}. This allows you to type @kbd{c$} for
386 example and see all buffer names ending in `c'. This facility is quite
387 limited though in two respects. First, you can't currently type in
388 expressions like `[0-9]' directly -- you have to type them in when
389 @code{iswitchb-regexp} is @code{nil} and then toggle on the regexp
390 functionality. Likewise, don't enter an expression containing `\' in regexp
391 mode. If you try, iswitchb gets confused, so just hit @kbd{C-g} and try
392 again. Secondly, no completion mechanism is currently offered when regexp
395 @node Replacement for read-buffer, , Regexp Matching, iswitchb
396 @section Replacement for read-buffer
398 iswitchb-read-buffer has been written to be a drop in replacement for the
399 normal buffer selection routine @code{read-buffer}. To use iswitch for all
400 buffer selections in Emacs, add: @code{(setq read-buffer-function
401 'iswitchb-read-buffer)} (This variable should be present in Emacs 20.3+)
402 XEmacs users can get the same behaviour by doing: @code{(defalias
403 'read-buffer 'iswitchb-read-buffer)} since @code{read-buffer} is defined in
406 @node permanent-buffers, rsz-minibuf, iswitchb, Top
407 @chapter Permanent Buffers
409 A permanent buffer is a buffer that you don't want to kill, mainly used for
410 testing or temporary stuff. The *scratch* buffer is the most famous example
411 of what could be a permanent buffer. This package allows you to define
412 several permanent buffers (the scratch buffer can be one of them) that will
413 never disappear. If you kill them or save their contents, they will be
414 regenerated. You can also specify a set of lisp forms to eval in the buffer
415 when it is (re)generated.
417 This package is implemented in a minor-mode fashion. You can customize the
418 default value of @code{permanent-buffers-mode} or use
419 @code{turn-on-permanent-buffers} at startup. Within an XEmacs session, use
420 @code{permanent-buffers-mode} or @code{turn-o[n|ff]-permanent-buffers}. You
421 might also want to customize @code{permanent-buffers-alist}.
423 To configure this package, type:
426 M-x customize-group RET permanent-buffers RET
429 @node rsz-minibuf, search-buffers, permanent-buffers, Top
430 @chapter Self-Resizing Minibuffer
432 This package allows the entire contents (or as much as possible) of the
433 minibuffer to be visible at once when typing. As the end of a line is
434 reached, the minibuffer will resize itself. When the user is done typing,
435 the minibuffer will return to its original size.
437 In window systems where it is possible to have a frame in which the
438 minibuffer is the only window, the frame itself can be resized.
440 Note that the minibuffer and echo area are not the same! They simply happen
441 to occupy roughly the same place on the frame. Messages put in the echo area
442 will not cause any resizing by this package.
444 This package is considered a minor mode but it doesn't put anything in
445 minor-mode-alist because this mode is specific to the minibuffer, which has
448 To invoke this mode, type:
451 M-x resize-minibuffer-mode RET
454 To configure this package, type:
457 M-x customize-group RET resize-minibuffer RET
460 @node search-buffers, uniquify, rsz-minibuf, Top
461 @chapter Searching Many Buffers
463 This package searches all live buffers for REGEXP and presents matching lines
464 in a separate buffer with hyperlinks to their occurrences.
466 After creating countless buffers in an XEmacs session, the user can execute
470 M-x list-matches-in-buffers RET \<problem\> RET .* RET
473 to find all matches of the single word "problem" in any of them. The result
474 is presented in a buffer named "*Matches for "\<problem\>" in buffers*" with
475 hyperlinks to any occurrence. User may navigate to the next (@kbd{n}) or
476 previous (@kbd{p}) match.
478 @node uniquify, winring, search-buffers, Top
479 @chapter Meaningful Unique Names
481 Emacs' standard method for making buffer names unique adds <2>, <3>, etc. to
482 the end of (all but one of) the buffers. This file replaces that behavior,
483 for buffers visiting files and dired buffers, with a uniquification that adds
484 parts of the file name until the buffer names are unique. For instance,
485 buffers visiting @file{/u/mernst/tmp/Makefile} and
486 @file{/usr/projects/zaphod/Makefile} would be named @samp{Makefile|tmp} and
487 @samp{Makefile|zaphod}, respectively (instead of @samp{Makefile} and
488 @samp{Makefile<2>}). Other buffer name styles are also available.
490 To configure this package, type:
493 M-x customize-group RET uniquify RET
496 @node winring, autorevert, uniquify, Top
497 @chapter Window Configuration Rings
499 This package provides lightweight support for circular rings of window
500 configurations. A window configuration is the layout of windows and
501 associated buffers within a frame. There is always at least one
502 configuration on the ring, the current configuration. You can create new
503 configurations and cycle through the layouts in either direction. You can
504 also delete configurations from the ring (except the last one of course!).
505 Window configurations are named, and you can jump to and delete named
508 Window configuration rings are frame specific. That is, each frame has its
509 own ring which can be cycled through independently of other frames.
511 You are always looking at the current window configuration for each frame,
512 which consists of the windows in the frame, the buffers in those windows, and
513 point in the current buffer. As you run commands such as @kbd{C-x 4 b},
514 @kbd{C-x 2}, and @kbd{C-x 0} you are modifying the current window
515 configuration. When you jump to a new configuration, the layout that existed
516 before the jump is captured, and the ring is rotated to the selected
517 configuration. Window configurations are captured with
518 @code{current-window-configuration}, however winring also saves point for the
521 To use, add the following to your initialization file:
527 Note that by default, this binds the winring keymap to the @kbd{C-x 7}
528 prefix, but you can change this by setting the value of
529 @code{winring-keymap-prefix}, before you call @code{winring-initialize}.
531 The following commands are defined:
537 Create a new window configuration. The new configuration will contain a
538 single buffer, the one named in the variable
539 @code{winring-new-config-buffer-name}.
541 With @kbd{C-u}, winring prompts for the name of the new configuration. If
542 you don't use @kbd{C-u} the function in @code{winring-name-generator} will be
543 called to get the new configuration's name.
547 Create a duplicate of the current window configuration. C-u
548 has the same semantics as with @kbd{C-x 7 c}.
552 Jump to a named configuration (prompts for the name).
556 Kill the current window configuration and rotate to the previous layout on
557 the ring. You cannot delete the last configuration in the ring. With
558 @kbd{C-u}, prompts for the name of the configuration to kill.
562 Go to the next configuration on the ring.
566 Go to the previous configuration on the ring.
568 Note that the sequence `C-x 7 o C-x 7 p' is a no-op; it leaves you in the
569 same configuration you were in before the sequence.
573 Rename the current window configuration.
577 Submit a bug report on winring.
581 Echo the winring version.
585 As mentioned, window configuration names can be displayed in the modeline.
586 The default value of @code{winring-show-names} is currently @code{nil} by
587 default. Set it to @code{t} to activate. If you don't like the position in
588 the modeline where winring names are shown, you can change this by passing in
589 your own modeline hacker function to @code{winring-initialize}.
596 @node History, Related Packages, winring, winring
599 A long long time ago there was a package called `wicos' written by Heikki
600 Suopanki, which was based on yet another earlier package called `screens'
601 also written by Suopanki. This in turn was based on the Unix tty session
602 manager `screen' (unrelated to Emacs) by Oliver Laumann, Juergen Weigert, and
605 Wicos essentially provided fancy handling for window configurations. I liked
606 the basic ideas, but wicos broke with later versions of Emacs and XEmacs. I
607 re-implemented just the functionality I wanted, simplifying things in the
608 process, and porting the code to run with XEmacs 19 and 20, and Emacs 20 (I
609 don't know if winring works in Emacs 19.34).
611 Wicos used the M-o prefix which I've recently changed to C-x 7 as the
612 default, by suggestion of RMS. Wicos also had some support for multiple
613 frames, and saving configurations on all visible frames, but it didn't work
614 too well, and I like frame independent rings better.
616 @node Related Packages, , History, winring
617 @section Related Packages
619 I know of a few other related packages:
625 `escreen' by Noah Friedman. A much more ambitious package that does Emacs
626 window session management. Very cool, but I wanted something more
631 `wconfig' by Bob Weiner as part of Hyperbole. I think wconfig is similar in
632 spirit to winring; it seems to have also have named window configurations,
633 but not frame-specific window rings.
637 `winner' by Ivar Rummelhoff. This package comes with Emacs 20, and appears
638 to differ from winring by providing undo/redo semantics to window
639 configuration changes. winner is a minor mode and does seem to support
640 frame-specific window rings.
644 window-xemacs' by the XEmacs Development Team. It appears that this package,
645 which is specific to XEmacs (and perhaps just XEmacs 20) implements stacks of
646 window configurations which are frame independent.
650 Please feel free to email me if my rendition of history, or my
651 explanation of the related packages, is inaccurate.
653 @node autorevert, backup-dir, winring, Top
654 @chapter Reverting Buffers
656 Whenever a file that Emacs is editing has been changed by another program the
657 user normally has to execute the command `revert-buffer' to load the new
658 content of the file into Emacs.
660 This package is defined in autorevert.el and contains two minor modes: Global
661 Auto-Revert Mode and Auto-Revert Mode. Both modes automatically revert
662 buffers whenever the corresponding files have been changed on disk.
664 Auto-Revert Mode can be activated for individual buffers. Global Auto-Revert
665 Mode applies to all file buffers.
667 Both modes operate by checking the time stamp of all files at intervals of
668 `auto-revert-interval'. The default is every five seconds. The check is
669 aborted whenever the user actually uses Emacs. You should never even notice
670 that this package is active (except that your buffers will be reverted, of
674 * Auto-Revert Usage:: How to use the package.
677 @node Auto-Revert Usage, , autorevert, autorevert
678 @section Auto-Revert Usage
680 To configure the package, type:
683 M-x customize-group RET auto-revert RET
686 To activate Auto-Revert for a specific buffer, go to the buffer and type:
689 M-x auto-revert-mode RET
692 To activate Global Auto-Revert Mode, type:
695 M-x global-auto-revert-mode RET
698 To activate Global Auto-Revert Mode every time Emacs is started customize the
699 option `global-auto-revert-mode' or the following line could be added to your
703 (global-auto-revert-mode 1)
706 The function `turn-on-auto-revert-mode' could be added to any major mode hook
707 to activate Auto-Revert Mode for all buffers in that mode. For example, the
708 following line will activate Auto-Revert Mode in all C mode buffers:
711 (add-hook 'c-mode-hook 'turn-on-auto-revert-mode)
714 @node backup-dir, bookmark, autorevert, Top
715 @chapter Specify Directories to be Used for Backup Files
717 Allows backup files to be optionally stored in some directories, based on the
718 value of the alist, @code{bkup-backup-directory-info}. This variable is a
719 list of lists of the form @code{(FILE-REGEXP BACKUP-DIR OPTIONS ...)}. If
720 the filename to be backed up matches @code{FILE-REGEXP}, or
721 @code{FILE-REGEXP} is @code{t}, then @code{BACKUP-DIR} is used as the path
722 for its backups. Directories may begin with "/" to specify an absolute
725 If @code{BACKUP-DIR} does not exist and @code{OPTIONS} contains the symbol
726 @code{ok-create}, then it is created if possible. Otherwise the usual
727 behavior (backup in the same directory as the file) results.
729 If @code{OPTIONS} contains the symbol @code{full-path}, then the full path of
730 the file being backed up is prepended to the backup file name, with each "/"
731 replaced by a "!". This is intended for cases where an absolute backup path
732 is used. If @code{OPTIONS} contains @code{prepend-name} in addition to
733 @code{full-path}, then the file name is prepended rather than appended to the
734 path component when forming the backup name.
736 If @code{OPTIONS} contains the symbol @code{search-upward} and the backup
737 directory @code{BACKUP-DIR} is a relative path, then a directory with that
738 name is searched for starting at the current directory and proceeding upward
739 (.., ../.., etc) until one is found of that name or the root is reached, and
740 if one is found it is used as the backup directory.
742 Finally, if no @code{FILE-REGEXP} matches the file name being backed up, then
743 the usual behavior results.
745 These lines from my initialization file load this library and set the values
749 (require 'backup-dir)
750 (setq bkup-backup-directory-info
751 '(("/home/greg/.*" "/~/.backups/" ok-create full-path prepend-name)
752 ("^/[^/:]+:" ".backups/") ; handle EFS files specially: don't
753 ("^/[^/:]+:" "./") ; search-upward... its very slow
755 full-path prepend-name search-upward)))
758 The package also provides a new function, @code{find-file-latest-backup} to
759 find the latest backup file for the current buffer's file.
761 This package is based on @file{files.el} from XEmacs 20.3 and overrides
762 functions defined there.
764 @node bookmark, desktop, backup-dir, Top
765 @chapter Create annotated bookmarks
767 This package is for setting "bookmarks" in files. A bookmark associates a
768 string with a location in a certain file. Thus, you can navigate your way to
769 that location by providing the string.
771 To configure this package, type:
774 M-x customize-group RET bookmark RET
777 @node desktop, recent-files, bookmark, Top
778 @chapter Save Partial Status of Emacs When Killed
780 Save the Desktop, i.e.,
785 some global variables
788 the list of buffers with associated files. For each buffer also
796 the default directory
802 the mark & mark-active
814 To use this, first put these two lines at the bottom of your initialization
815 file (the later the better):
818 (desktop-load-default)
822 Between these two lines you may wish to add something that updates the
823 variables @code{desktop-globals-to-save} and/or
824 @code{desktop-locals-to-save}. If for instance you want to save the local
825 variable @code{foobar} for every buffer in which it is local, you could add
829 (setq desktop-locals-to-save (cons 'foobar desktop-locals-to-save))
832 To avoid saving excessive amounts of data you may also wish to add something
836 (add-hook 'kill-emacs-hook
838 (desktop-truncate search-ring 3)
839 (desktop-truncate regexp-search-ring 3)))
842 which will make sure that no more than three search items are saved. You
843 must place this line @emph{after} the @code{(desktop-load-default)} line.
844 See also the variable @code{desktop-save-hook}.
846 Start Emacs in the root directory of your "project". The desktop saver is
847 inactive by default. You activate it by typing @code{M-x desktop-save RET}.
848 When you exit the next time the above data will be saved. This ensures that
849 all the files you were editing will be reloaded the next time you start Emacs
850 from the same directory and that points will be set where you left them. If
851 you save a desktop file in your home directory it will act as a default
852 desktop when you start Emacs from a directory that doesn't have its own. I
853 never do this, but you may want to.
855 Some words on minor modes: Most minor modes are controlled by buffer-local
856 variables, which have a standard save / restore mechanism. To handle all
857 minor modes, we take the following approach: (1) check whether the variable
858 name from @code{minor-mode-alist} is also a function; and (2) use translation
859 table @code{desktop-minor-mode-table} in the case where the two names are not
862 By the way: don't use @file{desktop.el} to customize Emacs -- the standard
863 XEmacs initialization file is used for that. Saving global default values
864 for buffers is an example of misuse.
866 PLEASE NOTE: The kill ring can be saved as specified by the variable
867 @code{desktop-globals-to-save} (by default it isn't). This may result in saving
868 things you did not mean to keep. Use @code{M-x desktop-clear RET}.
870 To configure this package, type:
873 M-x customize-group RET desktop RET
876 @node recent-files, resume, desktop, Top
877 @chapter Recent File Navigation
879 To install @file{recent-files}, put the following statements into your
883 (recent-files-initialize)
886 @file{recent-files} adds the menu "Recent Files" (or whatever name you
887 choose, (@pxref{recentf-cust,Customization}) to Emacs's menubar. Its entries
888 are the files (and directories) that have recently been opened by Emacs. You
889 can open one of these files again by selecting its entry in the "Recent
890 Files" menu. The list of file entries in this menu is preserved from one
891 Emacs session to another. You can prevent Emacs from saving this list by
892 selecting "Don't save recent-files list on exit" from the menu. If you have
893 disabled saving, you can re-enable it by selecting "Save recent-files list on
896 The menu has permanent and non-permanent entries. Permanent entries are
897 marked with an asterisk in front of the filename. The non-permanent entries
898 are hidden in a submenu.
900 Each time you open a file in Emacs, it is added as a non-permanent entry to
901 the menu. The value of @code{recent-files-number-of-entries} determines how
902 many non-permanent entries are held in the menu. When the number of
903 non-permanent entries reaches this value, the least recently added
904 non-permanent entry is removed from the menu when another non-permanent entry
905 is added. It is not removed from the list, though; it may reappear when
906 entries are deleted from the list. The number of entries saved to disk is the
907 value of the variable @code{recent-files-number-of-saved-entries}.
909 Permanent entries are not removed from the menu. You can make a file entry
910 permanent by selecting "Make <buffer> permanent" (where <buffer> is the name
911 of the current buffer) when the current buffer holds this file. "Make
912 <buffer> non-permanent" makes the file entry of the current buffer
915 The command "Kill buffer <buffer> and delete entry" is handy when you have
916 accidentally opened a file but want to keep neither the buffer nor the entry.
918 You can erase the list of non-permanent entries by selecting "Erase
919 non-permanent entries" from the menu.
922 * Customization: recentf-cust.
925 @node recentf-cust, , recent-files, recent-files
926 @section Customization
928 There are lots of variables to control the behaviour of
929 recent-files. You do not have to change any of them if you like it
930 as it comes out of the box. However, you may want to look at these
931 options to make it behave different.
935 @item recent-files-number-of-entries
936 Controls how many non-permanent entries are shown in the
937 recent-files list. The default is 15.
939 @item recent-files-number-of-saved-entries
940 Controls how many non-permanent entries are saved to disk when
941 Emacs exits or recent-files-save-the-list is called. The
944 @item recent-files-save-file
945 The name of the file where the recent-files list is saved
946 between Emacs session. You probably don't need to change this.
947 The default is ".recent-files.el" in your home directory.
949 @item recent-files-dont-include
950 A list of regular expressions for files that should not be
951 included into the recent-files list. This list is empty by
952 default. For instance, a list to exclude all .newsrc
953 files, all auto-save-files, and all files in the /tmp
954 directory (but not the /tmp directory itself) would look
958 (setq recent-files-dont-include
959 '("/\\.newsrc" "~$" "^/tmp/."))
962 The default is empty.
964 @item recent-files-use-full-names
965 If the value of this variable is non-nil, the full pathnames of
966 the files are shown in the recent-files menu. Otherwise only
967 the filename part (or the last name component if it is a
968 directory) is shown in the menu. The default it t, i.e. show
971 @item recent-files-filename-replacements
972 This is a list of pairs of regular expressions and replacement
973 strings. If a filename matches one of the regular expressions,
974 the matching part is replaced by the replacement string for
975 display in the recent-files menu.
976 Example: My home directory is "/users/mmc/nickel/". I want to
977 replace it with "~/". I also want to replace the directory
978 "/imports/teleservices/mmc/avc2/", where I work a lot, with
979 ".../avc2/". The list then looks like
982 (setq recent-files-filename-replacements
983 '(("/users/mmc/nickel/" . "~/")
984 ("/imports/teleservices/mmc/avc2/" . ".../avc2/")))
987 Only the first match is replaced. So, if you have several
988 entries in this list that may match a filename simultaneously,
989 put the one you want to match (usually the most special) in
990 front of the others. The default is to replace the home
993 @item recent-files-sort-function
994 Contains a function symbol to sort the display of filenames in
995 the recent-files menu. Supplied are two functions,
996 @code{recent-files-dont-sort} and @code{recent-files-sort-alphabetically}.
997 The first, which is the default, preserves the order of "most
1000 @item recent-files-permanent-submenu
1001 If this variable is non-nil, the permanent entries are put into
1002 a separate submenu of the recent-files menu. The default is
1005 @item recent-files-non-permanent-submenu
1006 If this variable is non-nil, the non-permanent entries are put
1007 into a separate submenu of the recent-files menu. The default
1008 is currently t, but probably should be nil, and we may change it
1009 back. (You can set both @code{recent-files-permanent-submenu} and
1010 @code{recent-files-non-permanent-submenu} to t to have both lists in
1013 @item recent-files-commands-submenu
1014 If this variable is non-nil, the commands if recent-files are
1015 placed in a submenu of the recent-files menu. The default is
1018 @item recent-files-commands-submenu-title
1019 If the commands are placed in a submenu, this string is used as
1020 the title of the submenu. The default is "Commands...".
1022 @item recent-files-actions-on-top
1023 If this variable is non-nil, the "action" menu entries ("Make
1024 <buffer> permanent" etc.) are put on top of the menu. Otherwise
1025 they appear below the file entries or submenus. The default is
1028 @item recent-files-permanent-first
1029 If this variable is t, the permanent entries are put first in
1030 the recent-files menu, i.e. above the non-permanent entries. If
1031 the value is nil, non-permanent entries appear first. If the
1032 value is neither t nor nil, the entries are sorted according to
1033 recent-files-sort-function. The default is 'sort.
1035 @item recent-files-find-file-command
1036 This variable contains the command to execute when a file entry
1037 is selected from the menu. Usually this will be @code{find-file},
1038 which is the default.
1042 @node resume, saveconf, recent-files, Top
1043 @chapter Resuming a Suspended Emacs Job
1045 This library not documented. Please contribute!
1047 @node saveconf, savehist, resume, Top
1048 @chapter Save Buffer/Window Configuration Between Sessions
1050 This package of functions gives Emacs the ability to remember which files
1051 were being visited, the windows that were on them, and the value of point in
1052 their buffers the last Emacs session in the same directory. This is an
1053 emulation of an old Gosling Emacs feature.
1055 The relevant commands are @code{save-context} and @code{recover-context}.
1057 Most of the time you'll want an Emacs session's context saved even if you
1058 choose not to recover it later. To avoid having to manually @code{M-x
1059 save-context} at each emacs exit, put the line:
1062 (setq auto-save-and-recover-context t)
1065 in your initialization file or in @file{default.el} in the lisp directory of
1066 the Emacs distribution. The context will then automatically be saved when
1069 By default only the contexts of visible buffers (buffers with windows on
1070 them) are saved. Setting the variable save-buffer-context to t causes the
1071 contexts of all buffers to be saved.
1073 To use the package put these lines
1077 (if (null (cdr command-line-args))
1078 (setq inihibit-startup-message (recover-context)))
1081 at the end of your initialization file or the @file{default.el} file in the
1082 lisp directory of the Emacs distribution. This causes the context saved in
1083 the current directory to be recovered whenever Emacs is invoked without any
1086 @node savehist, saveplace, saveconf, Top
1087 @chapter Save Minibuffer History
1089 Many editors (e.g. Vim) have the feature of saving minibuffer history to an
1090 external file after exit. This package provides the same feature in Emacs.
1091 When Emacs is about the exit, @code{savehist-save} will dump the contents of
1092 various minibuffer histories (as determined by
1093 @code{savehist-history-variables}) to a save file (@file{~/.emacs-history} by
1094 default). Although the package was designed for saving the minibuffer
1095 histories, any variables can be saved that way.
1097 To use savehist, put the following in your initialization file:
1103 To configure this package, type:
1106 M-x customize-group RET savehist RET
1109 @node saveplace, where-was-i-db, savehist, Top
1110 @chapter Automatically Save Place in Files
1112 Automatically save place in files, so that visiting them later (even during a
1113 different Emacs session) automatically moves point to the saved position,
1114 when the file is first found. Uses the value of buffer-local variable
1115 @code{save-place} to determine whether to save position or not.
1117 To use this package, put the following in your initialization file:
1120 (require 'saveplace)
1123 To configure this package, type:
1126 M-x customize-group RET saveplace RET
1129 @node where-was-i-db, completion, saveplace, Top
1130 @chapter Keep Persistent State in Visited Files
1132 This library will make XEmacs keep track of where you were last time you
1133 visited a file. It hopes to become a standard and favored XEmacs feature on
1134 setups with Berkeley DB installed.
1136 It works by installing functions on the @code{find-file-hooks} and on the
1137 buffer-local @code{kill-buffer-hook}. When a buffer is killed, if it was
1138 visiting a file, and place saving has been enabled for it, a database entry
1139 is made, saving the location of @code{point}. When you visit a file, the
1140 database is queried, keyed on @code{buffer-file-name}, and if an entry is
1141 found, point is set to the value retrieved, and place saving is enabled again
1144 There is a command, which is initially not bound to a keystroke in
1145 this incarnation; and may never be, since I think completion works
1149 M-x toggle-where-was-i
1152 which, using auto-completion, can be entered as
1158 that will turn place saving on and off on a per-file, buffer- local basis.
1159 If @code{where-was-i-db} has been turned off in a buffer and then you kill
1160 it, or exit XEmacs, any record for that file will be purged from the
1161 database, and you'll start at the top of the file next time you open it, with
1162 place saving turned off there.
1164 Place saving is automatically still `on' when you visit a file you'd toggled
1165 it on for in a previous session or visitation. (That's the point of it,
1168 Toggling place saving on in a buffer visiting a file is all that is required
1169 to cause the @code{where-was-i-db} feature to be autoloaded, as
1170 @code{toggle-where-was-i} will call on @code{install-where-was-i} if the
1171 `wwi-ffh' has not yet been installed. That WILL NOT cause this feature to be
1172 automatically enabled in your next XEmacs invocation, however. For that, you
1173 must customize and save @code{wwi-auto-install-on-startup-flag}. There is
1174 more information about this in its docstring.
1176 This feature can be unloaded with:
1179 C-u M-x install-where-was-i
1182 which will call @code{unload-feature}, as well as traverse the
1183 @code{buffer-list} removing the buffer-local @code{kill-buffer-hook}
1184 installed by this program. Note that any buffers that got place saving
1185 enabled by having had an entry in the database for them when they were first
1186 visited (thus restoring point to where it was the last time you had visited
1187 the file), will not have an updated entry made, nor the old entry removed (as
1188 would happen if you @code{toggle-where-was-i} to off in just that buffer),
1189 after you uninstall this feature like that.
1191 If you toggle it on again in a buffer visiting a file, then kill that buffer,
1192 the point will be saved for it. When you kill the other buffers that had
1193 place saving enabled before you uninstalled the feature with @kbd{C-u M-x
1194 install-where-was-i}, no @code{where-was-i-db} database update will happen
1195 for them, since their buffer-local @code{kill-buffer-hook} will have been
1196 cleaned of the member @code{wwi-save-where-i-am}, the function that writes
1197 the @code{point} entry to the database when a buffer is killed. If you then
1198 re-visit one of those files, point will get restored to the location it did
1199 the last time you visited that file with @code{where-was-i-db} installed.
1201 To remove a file from the place saving database, simply visit it, @kbd{M-x
1202 toggle-where-was-i} to switch @code{where-was-i-db} off, then kill that
1203 buffer. You can see how this works by looking at the definition of
1204 @code{wwi-save-where-i-am}.
1206 After a period of time, the database of saved file positions will become
1207 cluttered with the names of files that no longer exist. You may vacume out
1211 M-x wwi-vacume-where-was-i-db
1214 which will prompt you for an optional regular expression to match files you
1215 want records removed for. It will traverse the database and remove entries
1216 for file names that either match the regexp, or that are @code{(not
1217 (file-exists-p file-name))}. The main reason for this command is the removal
1218 of stale entries, for files that no longer exist on the filesystem.
1220 Note also that running @code{wwi-vacume-where-was-i-db} will cause EFS
1221 traffic, if you've saved your place in any remote files. Don't be surprised
1222 if your dialing daemon picks up the phone when you run the vacume function.
1223 You should be able to purge the database of all EFS entries with a simple
1224 regular expression passed to @code{wwi-vacume-where-was-i-db}. Of course,
1225 you might not want to do that, for obvious reasons.
1227 To configure this package, type:
1230 M-x customize-group RET where-was-i RET
1234 @node completion, dabbrev, where-was-i-db, Top
1237 To load this package, add the following to your initialization file:
1240 (require 'completion)
1243 After you type a few characters, pressing the "complete" key inserts the rest
1244 of the word you are likely to type.
1246 This watches all the words that you type and remembers them. When typing a
1247 new word, pressing "complete" (@kbd{C-return}) "completes" the word by
1248 inserting the most recently used word that begins with the same characters.
1249 If you press meta-return repeatedly, it cycles through all the words it knows
1252 If you like the completion then just continue typing, it is as if you entered
1253 the text by hand. If you want the inserted extra characters to go away, type
1254 @kbd{C-w} or delete. More options are described below.
1256 The guesses are made in the order of the most recently "used". Typing in a
1257 word and then typing a separator character (such as a space) "uses" the word.
1258 So does moving a cursor over the word. If no words are found, it uses an
1259 extended version of dynamic abbreviation @xref{dabbrev}.
1261 Completions are automatically saved to a file between sessions.
1263 Completion enables programmers to enter longer, more descriptive variable
1264 names while typing fewer keystrokes than they normally would.
1266 To configure this package, type:
1269 M-x customize-group RET completion RET
1272 @node dabbrev, hippie-exp, completion, Top
1273 @chapter Dynamic Abbreviations
1275 The purpose with this package is to let you write just a few characters of
1276 words you've written earlier to be able to expand them.
1278 To expand a word, just put the point right after the word and press @kbd{M-/}
1279 (@code{dabbrev-expand}) or @kbd{M-C-/} (@code{dabbrev-completion}).
1281 Check out the customizable variables to learn about all the features of this
1284 To configure this package, type:
1287 M-x customize-group RET dabbrev RET
1290 @node hippie-exp, icomplete, dabbrev, Top
1291 @chapter Hippie Expand
1293 @code{hippie-expand} is a single function for a lot of different kinds of
1294 completions and expansions. Called repeatedly it tries all possible
1295 completions in succession. Which kinds of completions to try, and in which
1296 order, is determined by the contents of
1297 @code{hippie-expand-try-functions-list}. Much customization of
1298 @code{hippie-expand} can be made by changing the order of, removing, or
1299 inserting new functions in this list. Given a positive numeric argument,
1300 @code{hippie-expand} jumps directly ARG functions forward in this list.
1301 Given some other argument (a negative argument or just @kbd{C-u}) it undoes
1302 the tried completion.
1304 If the variable @code{hippie-expand-verbose} is non-nil, @code{hippie-expand}
1305 outputs in a message which try-function in the list that is used
1306 currently (ie. was used currently and will be tried first the next time).
1308 The variable @code{hippie-expand-max-buffers} determines in how many buffers,
1309 apart from the current, to search for expansions in. It is used by the
1310 try-functions named "-all-buffers". The variable
1311 @code{hippie-expand-ignore-buffers} is a list of regexps matching buffer
1312 names (as strings) or major modes (as atoms) of buffers that should not be
1313 searched by the try-functions named "-all-buffers". See also the macro
1314 @code{make-hippie-expand-function} below.
1316 A short description of the current try-functions in this file:
1320 @item try-complete-file-name
1321 Very convenient to have in any buffer, and not just in the minibuffer or
1322 (some) shell-mode. It goes through all possible completions instead of just
1323 completing as much as is unique.
1325 @item try-complete-file-name-partially
1326 To insert in the list just before @code{try-complete-file-name} for those who
1327 want first to get a file name completed only as many characters as is unique.
1329 @item try-expand-all-abbrevs
1330 Can be removed if you don't use abbrevs. Otherwise it looks through all
1331 abbrev-tables, starting with the local followed by the global.
1333 @item try-expand-line
1334 Searches the buffer for an entire line that begins exactly as the current
1335 line. Convenient sometimes, for example as a substitute for (or complement
1336 to) the history list in shell-like buffers. At other times, only confusing.
1338 @item try-expand-line-all-buffers
1339 Like @code{try-expand-line} but searches in all buffers (except the current).
1340 (This may be a little slow, don't use it unless you are really fond of
1341 @code{hippie-expand}.)
1343 @item `try-expand-list
1344 Tries to expand the text back to the nearest open delimiter, to a whole list
1345 from the buffer. Convenient for example when writing lisp or TeX.
1347 @item try-expand-list-all-buffers
1348 Like @code{try-expand-list} but searches in all buffers (except the current).
1350 @item try-expand-dabbrev
1351 Works exactly as @code{dabbrev-expand} (but of course in a way compatible
1352 with the other try-functions).
1354 @item try-expand-dabbrev-all-buffers
1355 Perhaps the most useful of them, like @code{dabbrev-expand} but searches all
1356 Emacs buffers (except the current) for matching words. (No, I don't find
1357 this one particularly slow.)
1359 @item try-expand-dabbrev-visible
1360 Searches the currently visible parts of all windows. Can be put before
1361 @code{try-expand-dabbrev-all-buffers} to first try the expansions you can
1364 @item try-expand-dabbrev-from-kill
1365 Searches the kill ring for a suitable completion of the word. Good to have,
1366 just in case the word was not found elsewhere.
1368 @item try-expand-whole-kill
1369 Tries to complete text with a whole entry from the kill ring. May be good if
1370 you don't know how far up in the kill-ring the required entry is, and don't
1371 want to mess with "Choose Next Paste".
1373 @item try-complete-lisp-symbol
1374 Like @code{lisp-complete-symbol}, but goes through all possibilities instead
1375 of completing what is unique. Might be tedious (usually a lot of possible
1376 completions) and since its function is much like @code{lisp-complete-symbol},
1377 which already has a key of its own, you might want to remove this.
1379 @item try-complete-lisp-symbol-partially
1380 To insert in the list just before @code{try-complete-lisp-symbol} for those
1381 who first want to get completion of what is unique in the name.
1385 Not all of the above functions are by default in
1386 @code{hippie-expand-try-functions-list}. This variable is better set in your
1387 initialization file to make @code{hippie-expand} behave maximally convenient
1388 according to personal taste. Also, instead of loading the variable with all
1389 kinds of try-functions above, it might be an idea to use
1390 @code{make-hippie-expand-function} to construct different
1391 @code{hippie-expand}-like functions, with different try-lists and bound to
1392 different keys. It is also possible to make
1393 @code{hippie-expand-try-functions-list} a buffer local variable, and let it
1394 depend on the mode (by setting it in the mode-hooks).
1396 @node icomplete, tempo, hippie-exp, Top
1397 @chapter Interactive Minibuffer Completion
1399 Loading this package implements a more fine-grained minibuffer completion
1400 feedback scheme. Prospective completions are concisely indicated within the
1401 minibuffer itself, with each successive keystroke.
1403 See @code{icomplete-completions} docstring for a description of the icomplete
1406 See the @code{icomplete-minibuffer-setup-hook} docstring for a means to
1407 customize icomplete setup for interoperation with other minibuffer-oriented
1410 To activate @code{icomplete mode}, load the package and use the
1411 @code{icomplete-mode} function. You can subsequently deactivate it by
1412 invoking the function @code{icomplete-mode} with a negative prefix-arg
1413 @kbd{(C-U -1 ESC-x icomplete-mode}). Also, you can prevent activation of the
1414 mode during package load by first setting the variable @code{icomplete-mode}
1415 to nil. Icompletion can be enabled any time after the package is loaded by
1416 invoking @code{icomplete-mode} without a prefix arg.
1418 To configure this package, type:
1421 M-x customize-group RET icomplete RET
1424 @node tempo, avoid, icomplete, Top
1425 @chapter Flexible Template Insertion
1427 This file provides a simple way to define powerful templates, or macros, if
1428 you wish. It is mainly intended for, but not limited to, other programmers to
1429 be used for creating shortcuts for editing certain kind of documents. It was
1430 originally written to be used by a HTML editing mode written by Nelson Minar
1431 <nelson@@santafe.edu>, and his @file{html-helper-mode.el} is probably the
1432 best example of how to use this program.
1434 A template is defined as a list of items to be inserted in the current buffer
1435 at point. Some of the items can be simple strings, while other can control
1436 formatting or define special points of interest in the inserted text.
1438 If a template defines a "point of interest" that point is inserted in a
1439 buffer-local list of "points of interest" that the user can jump between with
1440 the commands @code{tempo-backward-mark} and @code{tempo-forward-mark}. If the
1441 template definer provides a prompt for the point, and the variable
1442 @code{tempo-interactive} is non-nil, the user will be prompted for a string
1443 to be inserted in the buffer, using the minibuffer.
1445 The template can also define one point to be replaced with the current region
1446 if the template command is called with a prefix (or a non-nil argument).
1448 More flexible templates can be created by including lisp symbols, which will
1449 be evaluated as variables, or lists, which will be evaluated as lisp
1452 See the documentation for @code{tempo-define-template} for the different
1453 items that can be used to define a tempo template.
1455 One of the more powerful features of tempo templates are automatic
1456 completion. With every template can be assigned a special tag that should be
1457 recognized by @code{tempo-complete-tag} and expanded to the complete
1458 template. By default the tags are added to a global list of template tags,
1459 and are matched against the last word before point. But if you assign your
1460 tags to a specific list, you can also specify another method for matching
1461 text in the buffer against the tags. In the HTML mode, for instance, the tags
1462 are matched against the text between the last `<' and point.
1464 When defining a template named @code{foo}, a symbol named
1465 @code{tempo-template-foo} will be created whose value as a variable will be
1466 the template definition, and its function value will be an interactive
1467 function that inserts the template at the point.
1469 To configure this package, type:
1472 M-x customize-group RET tempo RET
1475 @node avoid, blink-cursor, tempo, Top
1476 @chapter Move Mouse Pointer Out of the Way of Editing
1478 For those who are annoyed by the mouse pointer obscuring text, this mode
1479 moves the mouse pointer - either just a little out of the way, or all the way
1480 to the corner of the frame. To use, type @code{M-x mouse-avoidance-mode}.
1481 To set up permanently, add the following to your initialization file:
1484 (if window-system (mouse-avoidance-mode 'animate))
1487 The @code{'animate} can be @code{'jump} or @code{'banish} or @code{'exile} or
1488 @code{'protean} if you prefer. See the documentation for function
1489 @code{mouse-avoidance-mode} for details of the different modes.
1491 For added silliness, make the animatee animate by put something similar to
1492 the following into your initialization file:
1496 (mouse-avoidance-set-pointer-shape
1497 (eval (nth (random 4)
1498 '(x-pointer-man x-pointer-spider
1499 x-pointer-gobbler x-pointer-gumby)))))
1502 For completely random pointer shape, replace the @code{setq} above with
1503 @code{(setq x-pointer-shape (mouse-avoidance-random-shape))}.
1505 To configure this package, type:
1508 M-x customize-group RET avoid RET
1511 @node blink-cursor, fast-lock, avoid, Top
1512 @chapter Blinking Cursor
1514 To activate this package, type:
1517 M-x blink-cursor-mode RET
1520 To configure this package, type:
1523 M-x customize-group RET blink-cursor RET
1526 @node fast-lock, lazy-lock, blink-cursor, Top
1527 @chapter Speeding Up Font Lock Mode
1529 Lazy Lock mode is a Font Lock support mode. It makes visiting a file in Font
1530 Lock mode faster by restoring its face text properties from automatically
1531 saved associated Font Lock cache files.
1533 See also the lazy-lock package. (But don't use the two at the same time!)
1535 To use this package, add the following to your initialization file:
1538 (setq font-lock-support-mode 'fast-lock-mode)
1541 Start up a new Emacs and use font-lock as usual (except that you can use the
1542 so-called "gaudier" fontification regexps on big files without frustration).
1544 When you visit a file (which has @code{font-lock-mode} enabled) that has a
1545 corresponding Font Lock cache file associated with it, the Font Lock cache
1546 will be loaded from that file instead of being generated by Font Lock code.
1548 To configure this package, type:
1551 M-x customize-group RET fast-lock RET
1554 @node lazy-lock, lazy-shot, fast-lock, Top
1555 @chapter Lazy Demand-Driven Fontification
1557 The purpose of this library is to make visiting buffers in
1558 @code{font-lock-mode} faster by making fontification demand-driven and
1559 stealthy. Fontification only occurs when, and where, necessary.
1561 See also the fast-lock and lazy-shot packages. (But don't use them at the
1562 same time as lazy-lock!)
1564 To use this package, add the following to your initialization file:
1567 (setq font-lock-support-mode 'lazy-lock-mode)
1570 Start up a new XEmacs and use font-lock as usual (except that you can use the
1571 so-called "gaudier" fontification regexps on big files without frustration).
1573 In a buffer (which has @code{font-lock-mode} enabled) which is at least
1574 @code{lazy-lock-minimum-size} characters long, only the visible portion of
1575 the buffer will be fontified. Motion around the buffer will fontify those
1576 visible portions that were not previous fontified.
1578 If stealth fontification is enabled, fontification will occur in invisible
1579 parts of the buffer after @code{lazy-lock-stealth-time} seconds of idle time.
1581 To configure this package, type:
1584 M-x customize-group RET lazy-lock RET
1587 @node lazy-shot, mic-paren, lazy-lock, Top
1588 @chapter Another Lazy Demand-Driven Fontification
1590 This is an experimental demand based font-lock implementation. It is
1591 experimental in the sense that it relies on C support from the redisplay
1592 engine, that is experimental. The code in this file is more or less
1593 finished. The C code support experimental because the current design is
1594 rumoured to be ugly. Secondly because XEmacs does actually display the
1595 "un-font-locked" parts of the buffer first, the user notices flashing as the
1596 buffer is repainted with color/fonts.
1598 To use this package, add the following to your initialization file:
1601 (add-hook 'font-lock-mode-hook 'turn-on-lazy-shot)
1604 Do not use in combination with @code{lazy-lock}.
1607 M-x customize-group RET lazy-shot RET
1610 @node mic-paren, paren, lazy-shot, Top
1611 @chapter Advanced Highlighting of Matching Parentheses
1613 Load this file, activate it and Emacs will display highlighting on whatever
1614 parenthesis (and paired delimiter if you like this) matches the one before or
1615 after point. This is an extension to the paren.el file distributed with
1616 Emacs. The default behaviour is similar to paren.el but more
1617 sophisticated. Normally you can try all default settings to enjoy mic-paren.
1619 Or - if you are a LaTeX writer like the current maintainer - try the
1620 following additional setup in your initialization file:
1623 ;; In LaTeX-mode we want this
1624 (add-hook 'LaTeX-mode-hook
1625 (function (lambda ()
1626 (paren-toggle-matching-quoted-paren 1)
1627 (paren-toggle-matching-paired-delimiter 1))))
1630 Or - if you are programming in C like languages - try also:
1633 (add-hook 'c-mode-common-hook
1634 (function (lambda ()
1635 (paren-toggle-open-paren-context 1))))
1638 @file{mic-paren.el} is an extension and replacement to the packages
1639 @file{paren.el} and @file{stig-paren.el} for Emacs. When mic-paren is active
1640 Emacs normal parenthesis matching is deactivated. Instead parenthesis
1641 matching will be performed as soon as the cursor is positioned at a
1642 parenthesis. The matching parenthesis (or the entire expression between the
1643 parentheses) is highlighted until the cursor is moved away from the
1652 Both forward and backward parenthesis matching (simultaneously if cursor is
1653 between two expressions).
1657 Indication of mismatched parentheses.
1661 Recognition of "escaped" (also often called "quoted") parentheses.
1665 Option to match "escaped" parens too, especially in (La)TeX-mode
1666 (e.g. matches expressions like "\(foo bar\)" properly).
1670 Offers two functions as replacement for @code{forward-sexp} and
1671 @code{backward-sexp} which handle properly quoted parens (s.a.). These new
1672 functions can automatically be bounded to the original binding of the
1673 standard @code{forward-sexp} and @code{backward-sexp} functions.
1677 Option to activate matching of paired delimiter (i.e. characters with syntax
1678 '$'). This is useful for writing in LaTeX-mode for example.
1682 Option to select in which situations (always, never, if match, if mismatch)
1683 the entire expression should be highlighted or only the matching parenthesis.
1687 Message describing the match when the matching parenthesis is off-screen
1688 (vertical and/or horizontal). Message contains either the linenumber or the
1689 number of lines between the two matching parens. Option to select in which
1690 cases this message should be displayed.
1694 Optional delayed highlighting (useful on slow systems),
1698 Functions to activate/deactivate @file{mic-paren.el} are provided.
1702 Numerous options to control the behaviour and appearance of
1703 @file{mic-paren.el}.
1707 To configure this package, type:
1710 M-x customize-group RET mic-paren-matching RET
1713 @node paren, shell-font, mic-paren, Top
1714 @chapter Highlight (Un)matching Parens and Whole Expressions
1716 This package highlights matching parens (or whole sexps) for easier editing
1717 of source code, particularly lisp source code.
1719 The @code{paren-highlight} hook function runs after each command and checks
1720 to see if the cursor is at a parenthesis. If so, then it highlights, in one
1721 of several ways, the matching parenthesis.
1723 Priority is given to matching parentheses right before the cursor because
1724 that's what makes sense when you're typing a lot of closed parentheses. This
1725 is especially intuitive if you frequently use @code{forward-sexp}
1726 (@kbd{M-C-f}) and @code{backward-sexp} (@kbd{M-C-b}) to maneuver around in
1729 Different faces are used for matching and mismatching parens so that it is
1730 easier to see mistakes as you type them. Audible feedback is optional.
1732 If a (mis)matching paren is offscreen, then a message is sent to the
1735 If @code{paren-mode} is @code{sexp}, entire S-expressions are highlighted
1736 instead of just matching parens.
1738 To configure this package, type:
1741 M-x customize-group RET paren-matching RET
1744 @node shell-font, highline, paren, Top
1745 @chapter Decorate a Shell Buffer With Fonts
1747 Do this: @code{(add-hook 'shell-mode-hook 'install-shell-fonts)}
1748 and the prompt in your shell-buffers will appear bold-italic, process
1749 output will appear in normal face, and typein will appear in bold.
1751 The faces @code{shell-prompt}, @code{shell-input} and @code{shell-output} can
1752 be modified as desired, for example, @code{(copy-face 'italic
1755 @node highline, highline-keys, shell-font, Top
1756 @chapter Highlight the Current Line in the Buffer
1758 This package is a minor mode to highlight the current line in buffer.
1760 The mode supports the following modes of operation:
1764 @item LOCAL highline
1765 @item GLOBAL highline
1766 @item INDIRECT highline
1770 Both Local and Global minor modes may be in use at the same time.
1772 Indirect highline (@code{highline-view-on}, @code{highline-view-off} and
1773 @code{highline-view-mode}) is useful when you wish to have various "visions"
1774 of the same buffer. Indirect highline uses an indirect buffer to get the
1775 "vision" of the buffer. So, if you kill an indirect buffer, the base buffer
1776 is not affected; if you kill the base buffer, all indirect buffer related
1777 with the base buffer is automagically killed. Also, any text
1778 insertion/deletion in any indirect or base buffer is updated in all related
1782 * Key Bindings and Example Usage: highline-keys.
1783 * Hooks: highline-hooks.
1784 * Options: highline-options.
1787 @node highline-keys, highline-hooks, highline, highline
1788 @section Key Bindings and Example Usage
1790 It might be useful to set up some global key bindings as follows:
1793 (global-set-key "\C-c\C-a" 'highline-on)
1794 (global-set-key "\C-c\C-b" 'highline-off)
1795 (global-set-key "\C-c\C-l" 'highline-local-mode)
1796 (global-set-key "\C-c\C-d" 'highline-mode-on)
1797 (global-set-key "\C-c\C-e" 'highline-mode-off)
1798 (global-set-key "\C-c\C-g" 'highline-mode)
1799 (global-set-key "\C-c\C-c" 'highline-customize)
1800 (global-set-key "\C-c\C-v\C-n" 'highline-view-on)
1801 (global-set-key "\C-c\C-v\C-f" 'highline-view-off)
1802 (global-set-key "\C-c\C-v\C-t" 'highline-view-mode)
1805 As an example, try to insert this in your .emacs file:
1809 ;; Turn on local highlighting for Dired (C-x d)
1810 (add-hook 'dired-after-readin-hook 'highline-on)
1811 ;; Turn on local highlighting for list-buffers (C-x C-b)
1812 (defadvice list-buffers (after highlight-line activate)
1814 (set-buffer "*Buffer List*")
1818 @node highline-hooks, highline-options, highline-keys, highline
1821 highline has the following hook variables:
1826 It is evaluated always when highline is turned on globally.
1828 @item highline-local-hook
1829 It is evaluated always when highline is turned on locally.
1831 @item highline-view-hook
1832 It is evaluated always when indirect highline is turned on.
1834 @item highline-load-hook
1835 It is evaluated after highline package is loaded.
1839 @node highline-options, buffer-colors, highline-hooks, highline
1842 This is a brief description of highline options. Please see the options
1843 declarations in the code for more detail.
1848 Specify face used to highlight the current line.
1850 @item highline-vertical-face
1851 Specify face used to highlight other than current line.
1854 Specify which part of line should be highlighted.
1856 @item highline-vertical
1857 Specify how many vertical lines should be highlighted.
1859 @item highline-verbose
1860 Non-nil means generate messages.
1862 @item highline-ignore-regexp
1863 Specify regexp for buffers to ignore.
1865 @item highline-priority
1866 Specify highline overlay priority.
1868 @item highline-selected-window
1869 Non-nil means highlight current line on current window.
1873 To configure this package, type:
1876 M-x highline-customize RET
1879 @node buffer-colors, after-save-commands, highline-options, Top
1881 Buffer colors provides an easy interface to implementing buffer-local
1882 default color schemes. This can be used automatically based on mode or
1883 filename extension (for instance, all .c-files could be lime green on
1884 black, and all .h files could be amber on black) or manually
1885 settable. An option is provided for defining additional custom color
1886 schemes, and defining the buffer-colors by window instead of
1887 buffer. All configuration can be done through the buffer-colors
1891 @node after-save-commands, atomic-extents, buffer-colors, Top
1892 @chapter Hooks Invoked After Saving a File
1894 Set up a list of file-name matching regular expressions associated with shell
1895 commands or lisp forms to run after saving the file.
1897 This is good for things like running @code{newaliases(1)} on
1898 @file{/etc/aliases}, @code{xrdb(1)} on @file{~/.Xresources}, installing a new
1899 @file{~/.crontab}, as well as for sending signals to daemons whose
1900 configuration files you've just finished editing.
1902 It is much safer and more powerful than using exec statements in "Local
1903 Variables" sections, and can safely be used by root for system administration
1904 tasks. The shell command can run about anything you can think of.
1906 See variable @code{After-save-alist} for more information.
1908 @node atomic-extents, array, after-save-commands, Top
1909 @chapter Indivisible Blocks of Text
1911 Point is not allowed to fall inside of an atomic extent. This has the effect
1912 of making all text covered by an atomic extent be treated as a single object.
1913 Normally point will be adjusted to an end of an atomic extent in the
1914 direction of motion. If point appears inside of an atomic extent (via
1915 @code{goto-char} for example), point will be adjusted to the side closest to
1918 To make this feature available, add the following to your initialization
1922 (require 'atomic-extents)
1925 To make an extent atomic use the command:
1928 (set-extent-property #<extent obj> 'atomic t)
1931 @node array, floating-toolbar, atomic-extents, Top
1932 @chapter Table and Array Editor
1934 Commands for editing a buffer interpreted as a rectangular array or matrix of
1935 whitespace-separated strings. You specify the array dimensions and some
1936 other parameters at startup time.
1938 @node floating-toolbar, The Toolbar Utilities, array, Top
1939 @chapter Floating Toolbar
1941 The command @code{floating-toolbar} pops up a small frame containing a
1942 toolbar. The command should be bound to a button-press event. If the mouse
1943 press happens over an extent that has a non-nil @code{'floating-toolbar}
1944 property, the value of that property is the toolbar instantiator that will be
1945 displayed. Otherwise the toolbar displayed is taken from the variable
1946 @code{floating-toolbar}. This variable can be made buffer local to produce
1947 buffer local floating toolbars.
1949 @code{floating-toolbar-or-popup-mode-menu} works like @code{floating-toolbar}
1950 except that if no toolbar is found, @code{popup-mode-menu} is called.
1952 @code{floating-toolbar-from-extent-or-popup-mode-menu} works like
1953 @code{floating-toolbar-or-popup-mode-menu} except only extent local toolbars
1954 are used; the value of floating-toolbar is not used.
1956 Add the following line to your initialization file:
1959 (require 'floating-toolbar)
1962 You will also need to bind a mouse click to @code{floating-toolbar} or to
1963 @code{floating-toolbar-or-popup-mode-menu}.
1965 @node The Toolbar Utilities, foldout, floating-toolbar, Top
1966 @chapter The Toolbar Utilities
1969 The toolbar utilities are a set of Emacs commands and Lisp functions for
1970 convenient creation and management of toolbars. Common usages such as
1971 creating and adding toolbar buttons to invoke commands and keyboard
1972 macros are implemented as user commands. Convenience APIs are provided
1973 to create buttons, add them to toolbars, kill them from toolbars, and
1974 finding a particular button, or a button with certain content, in a
1977 The toolbar utilities are implemented in three files:
1980 @item toolbar-utils.el
1982 The toolbar utility APIs and user commands.
1984 @item edit-toolbar.el
1986 The near-WYSIWYG toolbar editor by Peter D. Pezaris.
1988 @item xemacs-toolbar.el
1990 The XEmacs compatibility API for programs that should also run under GNU
1994 The author would like to thank Jeff Miller and Peter D. Pezaris for the
1995 original API and the toolbar editor, respectively, and David Kastrup and
1996 Jamie Zawinski for the pedal-gluteal impetus that resulted in the recent
1997 revision of these libraries described in this manual.
2000 * Adding Buttons on the Fly:: Quick and convenient.
2001 * The Toolbar Editor:: Power tools for customization.
2002 * APIs for Adding and Killing:: For Lisp programmers.
2003 * APIs for Search:: Button, button, who's got the button?
2004 * Toolbar Portability:: The @file{xemacs-toolbar.el} library.
2007 @node Adding Buttons on the Fly, The Toolbar Editor, The Toolbar Utilities, The Toolbar Utilities
2008 @section Adding Buttons on the Fly
2010 @defvr Group edit-toolbar
2012 Customize group of tools for interactive editing and non-interactive
2013 management of toolbars.
2016 @defvar toolbar-button-default-position
2017 Default position for adding toolbar
2018 buttons on the fly. The value may be a non-negative integer (0 is
2019 leftmost), or one of the symbols @code{left}, @code{right}, or
2020 @code{extreme-right}. @code{left} is synonymous with 0, and
2021 @code{extreme-right} is synonymous with @code{(length toolbar)}.
2022 @code{right} specifies placing a new item at the right end of the
2023 flush-left group of buttons.
2025 Default value: @code{right}. Customize type: sexp.
2027 See also @samp{toolbar-add-button}, @ref{APIs for Adding and Killing}.
2030 @deffn Command toolbar-add-button-on-the-fly description command label &optional position locale
2032 Add an button at @var{position} to the default toolbar of the selected
2033 window. Returns @code{t}.
2035 The return value may change. Tell stephen@@xemacs.org what value you
2036 think would be (most) useful.
2040 A string describing the action, and displayed as help.
2043 An interactive command (ie, a symbol with an interactive function
2044 definition) implementing the action.
2047 A string used to label the button.
2050 Optional. A position (a non-negative integer, or one of the
2051 symbols @code{left}, @code{right}, or @code{extreme-right}.
2053 Default: @code{right}.
2056 Optional. A specifier locale, defaulting to the current buffer. If
2057 current-buffer-only is not what you want, and you don't understand
2058 specifier locales, use @code{global}. It's safe and probably does what
2063 @deffn Command toolbar-add-kbd-macro mac icon is-file
2064 Add a button invoking a keyboard macro to the toolbar.
2065 The button is added at the end of the left group.
2069 A keyboard macro name, or the empty string or nil to use a copy of
2070 the last keyboard macro defined.
2073 A string specifying the icon to be used. If @var{is-file} is
2074 non-@code{nil}, it is interpreted as the name of an image file, and
2075 searched for using @code{locate-data-file}. Otherwise it is used
2076 verbatim as a label.
2079 Determines the treatment of @var{icon} (q.v.).
2082 Used interactively, prompts for the macro name @var{mac} and an
2083 @var{icon}. @var{is-file} is non-@code{nil} if a prefix argument was
2087 @defun toolbar-add-execute-macro-button
2089 Add a button to the global toolbar to execute the last keyboard macro.
2091 Unlike @code{toolbar-add-kbd-macro}, this does not copy the macro. The
2092 macro executed will change with redefinitions.
2094 Due to a simple implementation, this button will not appear in buffers with
2095 local toolbars if invoked after the toolbar is installed. If you like this
2096 button, it's probably best to invoke this function in your init file.
2099 @defun toolbar-execute-last-kbd-macro
2100 Toolbar thunk which executes the most recently defined keyboard macro.
2103 @deffn Command restore-initial-toolbar
2104 Restores the default toolbar defined by @code{initial-toolbar-spec}.
2106 There is also a cache of killed buttons in @code{button-palette}.
2109 @node The Toolbar Editor, APIs for Adding and Killing, Adding Buttons on the Fly, The Toolbar Utilities
2110 @section The Toolbar Editor
2112 To use @file{edit-toolbar.el}, simply type @kbd{M-x edit-toolbar RET}.
2114 For help on the various commands you can type @key{?} in a
2115 @samp{edit-toolbar} buffer. To save a modified toolbar type @kbd{C-x
2116 C-s} in an @samp{edit-toolbar} buffer. If you want to use a saved
2117 toolbar in your future XEmacs sessions, add the following line of code
2121 (load "~/.xemacs/.toolbar")
2124 Here is a table of commands and bindings available in
2125 @samp{edit-toolbar-mode}. These commands are also available from the
2126 @samp{Edit Toolbar} menu.
2131 @samp{edit-toolbar-quit}: Bury the @samp{edit-toolbar} buffer.
2136 @samp{edit-toolbar-previous}: Select the previous item (line).
2142 @samp{edit-toolbar-next}: Select the next item (line).
2146 @samp{describe-mode}: Help.
2150 @samp{edit-toolbar-set-function}: Set the command for the current button.
2154 @samp{edit-toolbar-set-help}: Set the help string for the current button.
2158 @samp{edit-toolbar-add-button}: Add a new empty button.
2162 @samp{edit-toolbar-add-separator-2D-narrow}: Add a new narrow 2D
2167 @samp{edit-toolbar-add-separator-2D-wide}: Add a new wide 2D fixed-width
2172 @samp{edit-toolbar-add-separator-3D-narrow}: Add a new narrow 3D
2177 @samp{edit-toolbar-add-separator-3D-wide}: Add a new wide 3D fixed-width
2182 @samp{edit-toolbar-add-separator-right-left}: Place the filler
2183 separator, which expands to create a flush-left group of buttons and
2184 spacers and a flush-right group.
2188 @samp{edit-toolbar-copy}: Copy the selected button.
2192 @samp{edit-toolbar-down}: Reorder the buttons by moving the selected
2193 button down (to the right on a horizontal toolbar).
2197 @samp{edit-toolbar-up}: Reorder the buttons by moving the selected
2198 button up (to the left on a horizontal toolbar).
2202 @samp{edit-toolbar-kill}: Kill the selected button.
2207 @samp{edit-toolbar-save}: Save the current buffer to
2208 @file{~/.xemacs/.toolbar} in a format that allows it to be reloaded.
2212 @samp{edit-toolbar-restore}: Restore the original toolbar (ie, before
2213 this editing session started).
2217 @node APIs for Adding and Killing, APIs for Search, The Toolbar Editor, The Toolbar Utilities
2218 @section APIs for Adding and Killing
2220 @defvar button-palette
2221 List of buttons cut from toolbars.
2223 Note this is actually a toolbar descriptor.
2226 @defun toolbar-add-item toolbar-spec item &optional position
2227 Add @var{item} to @var{toolbar-spec} at @var{position}, and return
2228 @var{toolbar-spec}. Uses functions that alter list structure.
2232 A toolbar button or spacer specification (eg, from
2233 @code{toolbar-new-button} or @code{toolbar-new-spacer}).
2235 A toolbar descriptor (eg, from @code{toolbar-new-toolbar}).
2237 Optional. A non-negative integer, with 0 being the extreme left and
2238 \(length @var{toolbar-spec}) the extreme right. The symbols
2239 @code{left}, @code{right}, and @code{extreme-right} are also accepted.
2240 @code{left} is synonymous with 0. @code{right} places @var{item} at the
2241 right end of the left group of buttons. @code{extreme-right} places
2242 @var{item} at the extreme right of the toolbar, creating a right group
2243 if one does not exist.
2246 #### This function does not yet support inserting the group delimiter nil
2247 as an explicit item.
2249 @var{position} may be greater than (length @var{toolbar-spec}), in which
2250 case it is truncated to (length @var{toolbar-spec}). Note that
2251 @code{(length @var{toolbar-spec})} is not synonymous with @code{right}
2252 or @code{extreme-right} (@code{extreme-right} will create a right group
2253 if it doesn't already exist).
2256 @defun toolbar-new-button icon-spec command help-string &optional initially-disabled
2257 Return a checked toolbar button specification.
2261 A list of glyphs (from @code{make-glyph}), a glyph, or a
2262 string to use as the button's icon. If a string or single glyph, it will
2263 be used for the button-up glyph. If a list, it may contain 1 to 6 glyphs,
2264 which XEmacs will use for button up, button down, button disabled, button
2265 up with caption, button down with caption, and button disabled with caption,
2266 in that order. Missing or nil glyphs will be defaulted. (#### Strings as
2267 list elements are not supported but could be.)
2270 The (interactive) command to invoke when the button is pressed.
2273 A string briefly describing the command, displayed in the echo area or
2274 as balloon help when the pointer enters the button.
2276 @item initially-disabled
2277 Optional. If non-@code{nil}, specifies that the button should initially
2280 See @code{default-toolbar} or the Lispref (@pxref{Toolbars, , ,
2281 lispref}) for more information.
2285 @defun toolbar-new-spacer style &optional size
2286 Returns a checked toolbar spacer ``button''.
2290 One of the symbols @code{2d} or @code{3d}, indicating whether the area is
2291 displayed without shadows (giving it a flat appearance), or with shadows
2292 (giving it a raised, 3-D appearance). There is no default.
2293 #### We may set a default style. Tell stephen@@xemacs.org which you use.
2296 Specifies the length, in pixels, of the blank area. If omitted,
2297 it defaults to a device-specific value (8 pixels for X devices).
2301 @defun make-toolbar-instantiator &optional toolbar-spec domain
2302 Return a checked toolbar instantiator, a list of vectors.
2306 May be a list of buttons (ie, a toolbar descriptor, see
2307 @code{default-toolbar}), a toolbar specifier object, a symbol whose
2308 value is a toolbar specifier object, or @code{nil}. If @code{nil},
2309 returns a null list. If a toolbar specifier object or variable
2310 containing one, the specification for DOMAIN is used. If non-nil, DOMAIN
2311 must be a window, a frame, or a device, otherwise it defaults to the selected
2312 window (see @code{specifier-instance}). The list thus generated is checked and
2315 If @var{toolbar-spec} is a list, it is copied; it is safe to pass other
2316 packages' toolbar initializers to this function. However, you probably
2317 do not want to change any of the objects in the returned specification.
2318 They are returned as is, not copied.
2320 See @code{default-toolbar} or the Lispref (@pxref{Toolbars, , ,
2321 lispref}) for more information.
2325 @defun toolbar-kill-item-pos pos &optional toolbar locale
2326 Kill the item at position @var{pos} of @var{toolbar} in @var{locale}.
2327 Killed buttons are prepended to @code{button-palette}.
2329 @var{locale} defaults to @code{global}. If there are multiple specs for
2330 @var{locale}, take the first one.
2332 This function currently does not accept symbolic positions a la
2333 @code{toolbar-add-item}. Use @code{toolbar-find-item} to locate whole
2334 buttons and spacers, and @code{toolbar-find-button} to locate buttons by
2335 characteristics. See also @code{toolbar-find-button-by-icon},
2336 @code{toolbar-find-button-by-command}, and
2337 @code{toolbar-find-button-by-help-string}.
2340 @node APIs for Search, Toolbar Portability, APIs for Adding and Killing, The Toolbar Utilities
2341 @section APIs for Search
2343 @defun toolbar-find-button item &optional toolbar locale
2344 Return the position of a button containing @var{item} in its
2349 May specify a button, spacer, icon, command, help string, or nil. If
2350 @var{item} is nil, find the separator between the group of buttons to be
2351 left justified, and the group to be right justified. (Distinctions
2352 among the various ``search key types'' are somewhat heuristic but are
2353 probably reliable enough to use in library code.)
2356 If non-@code{nil}, search it; otherwise search the default toolbar.
2359 If non-@code{nil}, get @var{toolbar}'s descriptor in that locale,
2360 otherwise use the @code{global} locale.
2364 @defun toolbar-find-item item &optional toolbar locale
2365 Return the position of @var{item}, a button, spacer, or nil.
2366 @var{toolbar} and @var{locale} determine the descriptor to be searched.
2368 If @var{item} is nil, find the separator between the group of buttons to
2369 be left justified, and the group to be right justified. If there are
2370 several matching items, the first is returned. If none is found, return
2374 @defun toolbar-find-button-by-icon icon &optional toolbar locale
2375 Return the position of a button with icon @var{icon}.
2376 @var{icon} must be a list of glyphs or a symbols whose value is a list
2378 @var{toolbar} and @var{locale} determine the descriptor to be searched.
2380 If there are several matching buttons, the first is returned.
2383 @defun toolbar-find-button-by-command cmd &optional toolbar locale
2384 Return the position of a button invoking command CMD. @var{toolbar} and
2385 @var{locale} determine the descriptor to be searched.
2387 If there are several matching buttons, the first is returned.
2390 @defun toolbar-find-button-by-help-string str &optional toolbar locale
2392 Return the position of a button with help-string @var{str}.
2393 @var{toolbar} and @var{locale} determine the descriptor to be searched.
2395 If there are several matching buttons, the first is returned.
2396 This function will not find spacers.
2399 @defun toolbar-find-button-by-element object index toolbar locale &optional thunk
2400 Return the position of a button containing @var{object} in element
2401 @var{index}. @var{toolbar} and @var{locale} determine the descriptor to
2404 Optional argument @var{thunk} is a function of one argument which is
2405 used to normalize @var{object} for comparison.
2407 If there are several matching buttons, the first is returned.
2408 This function will not find spacers.
2411 @node Toolbar Portability, , APIs for Search, The Toolbar Utilities
2412 @section Toolbar API Portability to GNU Emacs
2413 @cindex GNU Emacs compatibility
2414 @cindex compatibility libraries, GNU Emacs
2416 The @file{xemacs-toolbar.el} library provides XEmacs toolbar
2417 compatibility functions for GNU Emacs.
2419 Third-party maintainers may use the same APIs in GNU Emacs as in XEmacs.
2420 Simply provide this library with your own code, and load it
2424 (if (featurep 'xemacs)
2425 (require 'toolbar-utils)
2426 (require 'toolbar-utils "xemacs-toolbar"))
2429 XEmacs features that are not present in GNU Emacs will be ignored, and
2430 various arguments with different semantics will be defaulted appropriately.
2432 User commands such as @code{toolbar-add-kbd-macro} and advanced features
2433 such as the toolbar editor and the button cache are not presently
2436 @node foldout, func-menu, The Toolbar Utilities, Top
2437 @chapter Folding Extensions for Outline-Mode
2439 This file provides folding editor extensions for @code{outline-mode} and
2440 @code{outline-minor-mode} buffers. What's a "folding editor"? Read on...
2442 Imagine you're in an @code{outline-mode} buffer and you've hidden all the
2443 text and subheadings under your level-1 headings. You now want to look at
2444 the stuff hidden under one of these headings. Normally you'd do @kbd{C-c
2445 C-e} @code{(show-entry)} to expose the body or @kbd{C-c C-i} to expose the
2446 child (level-2) headings.
2448 With foldout, you do @kbd{C-c C-z} (@code{foldout-zoom-subtree}). This
2449 exposes the body and child subheadings and narrows the buffer so that only
2450 the level-1 heading, the body and the level-2 headings are visible. If you
2451 now want to look under one of the level-2 headings, position the cursor on it
2452 and do @kbd{C-c C-z} again. This exposes the level-2 body and its level-3
2453 child subheadings and narrows the buffer again. You can keep on zooming in
2454 on successive subheadings as much as you like. A string in the modeline
2455 tells you how deep you've gone.
2457 When zooming in on a heading you might only want to see the child
2458 subheadings. You do this by specifying a numeric argument: @kbd{C-u C-c C-z}.
2459 You can specify the number of levels of children too (c.f. @code{show-children}):
2460 e.g. @kbd{M-2 C-c C-z} exposes two levels of child subheadings. Alternatively,
2461 you might only be interested in the body. You do this by specifying a
2462 negative argument: @kbd{M-- C-c C-z}. You can also cause the whole subtree
2463 to be expanded, similar to @kbd{C-c C-s} (@code{show-subtree}), by specifying
2464 a zero argument: @kbd{M-0 C-c C-z}.
2466 While you're zoomed in you can still use outline-mode's exposure and hiding
2467 functions. It won't upset foldout at all. Also, since the buffer is
2468 narrowed, "global" editing actions will only affect the stuff under the
2469 zoomed-in heading. This is useful for restricting changes to a particular
2470 chapter or section of your document.
2472 You unzoom (exit) a fold by doing @kbd{C-c C-x} (@code{foldout-exit-fold}).
2473 This hides all the text and subheadings under the top-level heading and
2474 returns you to the previous view of the buffer. Specifying a numeric
2475 argument exits that many folds. Specifying a zero argument exits *all*
2478 You might want to exit a fold *without* hiding the text and subheadings. You
2479 do this by specifying a negative argument. For example, @kbd{M--2 C-c C-x}
2480 exits two folds and leaves the text and subheadings exposed.
2482 Foldout also provides mouse bindings for entering and exiting folds and for
2483 showing and hiding text. Hold down Meta and Control, then click a mouse
2488 @item mouse-1 (@code{foldout-mouse-zoom}) zooms in on the heading clicked on:
2492 @item single click -- expose body
2494 @item double click -- expose subheadings
2496 @item triple click -- expose body and subheadings
2498 @item quad click -- expose entire subtree
2502 @item mouse-2 (@code{foldout-mouse-show}) exposes text under the heading clicked on:
2506 @item single click -- expose body
2508 @item double click -- expose subheadings
2510 @item triple click -- expose body and subheadings
2512 @item quad click -- expose entire subtree
2516 @item mouse-3 (@code{foldout-mouse-hide-or-exit}) hides text under the
2517 heading clicked on or exits the fold:
2521 @item single click -- hide subtree
2523 @item double click -- exit fold and hide text
2525 @item triple click -- exit fold without hiding text
2527 @item quad click -- exit all folds and hide text
2533 You can change the modifier keys used by setting
2534 @code{foldout-mouse-modifiers}.
2536 To use foldout, put this in your initialization file:
2542 If you don't want it loaded until you need it, try this instead:
2545 (eval-after-load "outline" '(require 'foldout))
2548 @node func-menu, id-select, foldout, Top
2549 @chapter Jump to a Function Within a Buffer.
2551 Suppose you have a file with a lot of functions in it. Well, this package
2552 makes it easy to jump to any of those functions. The names of the functions
2553 in the current buffer are automatically put into a menubar menu, you select
2554 one of the function-names and the point is moved to that very function. The
2555 mark is pushed on the mark-ring, so you can easily go back to where you
2556 were. Alternatively, you can use enter the name of the desired function via
2557 the minibuffer which offers completing read input. In addition, the name of
2558 the function before point is optionally displayed in the modeline.
2560 The following modes are supported:
2562 Ada, Assembly, BibTex, C++, C, Dired, Ehdm, ELisp, FORTRAN, Ksh, Latex,
2563 Lelisp, Makefile, Maple, Modula2, Modula3, Outline, Objective-C, Pascal,
2564 Perl, Postscript, Prolog, PVS, Python, SGML, Scheme, Tcl, Verilog, Manual,
2567 To install this package, add the following to your initialization file:
2570 (add-hook 'find-file-hooks 'fume-setup-buffer)
2571 (add-hook 'Manual-mode-hook 'turn-on-fume-mode)
2574 @node id-select, outl-mouse, func-menu, Top
2575 @chapter Select Syntax-Driven Regions in a Buffer
2577 This is a radically cool, drop in mouse and keyboard-based library for
2578 selecting successively bigger syntactical regions within a buffer. Simply
2579 load this library and you are ready to try it out by double-clicking on
2580 various kinds of characters in different buffer major modes. You'll quickly
2581 get the hang of it. (It also provides a command to jump between beginning
2582 and end tags within HTML and SGML buffers.)
2584 A great deal of smarts are built-in so that it does the right thing almost
2585 all of the time; many other attempts at similar behavior such as
2586 @file{thing.el} fail to deal with many file format complexities.
2588 Double clicks of the Selection Key (left mouse key) at the same point will
2589 select bigger and bigger regions with each successive use. The first double
2590 click selects a region based upon the character at the point of the click.
2591 For example, with the point over an opening or closing grouping character,
2592 such as @{ or @}, the whole grouping is selected, e.g. a C function. When on
2593 an _ or - within a programming language variable name, the whole name is
2594 selected. The type of selection is displayed in the minibuffer as feedback.
2595 When using a language based mainly on indenting, like Bourne shell, a double
2596 click on the first alpha character of a line, such as an if statement,
2597 selects the whole statement.
2599 This whole package is driven by a single function, available in mouse and
2600 keyboard forms, that first marks a region based on the syntax category of the
2601 character following point. Successive invocations mark larger and larger
2602 regions until the whole buffer is marked. See the documentation for the
2603 function, @code{id-select-syntactical-region}, for the kinds of syntax
2606 Loading this package automatically installs its functionality on double-clicks
2607 (or higher) of the left mouse key. (See the documentation for the variable,
2608 @code{mouse-track-click-hook}, for how this is done.) A single click of the
2609 left button will remove the region and reset point.
2611 The function, @code{id-select-thing}, may be bound to a key to provide the
2612 same syntax-driven region selection functionality. @kbd{C-c C-m} is a
2613 reasonable site-wide choice since this key is seldom used and it mnemonically
2614 indicates marking something. @kbd{C-c s} may be preferred as a personal
2617 Use @kbd{C-g} to unmark the region when done. Use,
2618 @code{id-select-thing-with-mouse}, if you want to bind this to a mouse key
2619 and thereby use single clicks instead of double clicks.
2621 Three other commands are also provided:
2625 @item id-select-and-copy-thing
2626 mark and copy the syntactical unit to the kill ring
2628 @item id-select-and-kill-thing
2629 kill the syntactical unit at point
2631 @item id-select-goto-matching-tag
2632 In HTML and SGML modes (actually any listed in the variable,
2633 `id-select-markup-modes'), moves point to the start of the tag paired with
2634 the closest tag that point is within or which it precedes, so you can quickly
2635 jump back and forth between open and close tags.
2639 To autoload this package via mouse usage, add the following line to one of
2640 your initialization files:
2643 (add-hook 'mouse-track-click-hook 'id-select-double-click-hook)
2646 To configure this package, type:
2649 M-x customize-group RET id-select RET
2652 @node outl-mouse, page-ext, id-select, Top
2653 @chapter Outline-Mode Mouse Commands
2655 Defines @kbd{mouse button one} to hide blocks when clicked on
2656 outline-up-arrow and expand blocks when clicked on outline-down-arrow.
2657 Features are activated when @code{outline-minor-mode} or @code{outline-mode}
2658 are turned on. There is also a menu for each glyph on @kbd{mouse button 3}.
2660 To use, add the following to your initialization file:
2663 (require 'outl-mouse)
2666 If you use func-menu all the time and want outl-mouse on all the time as well
2667 then specify @code{(setq outline-sync-with-func-menu t)}. Outlining will
2668 then be turned on when func-menu is activated.
2670 If you want mac-style outlining then set @code{outline-mac-style} to t. If
2671 you want the outline arrows on the left then set
2672 @code{outline-glyphs-on-left} to t. If you have xpm then arrows are much
2675 To configure this package, type:
2678 M-x customize-group RET outl-mouse RET
2681 @node page-ext, power-macros, outl-mouse, Top
2682 @chapter Extended Page Handling Commands
2684 The page commands are helpful in several different contexts. For example,
2685 programmers often divide source files into sections using the
2686 @code{page-delimiter}; you can use the @code{pages-directory} command to list
2689 You may use the page commands to handle an address list or other small data
2690 base. Put each address or entry on its own page. The first line of text in
2691 each page is a `header line' and is listed by the @code{pages-directory} or
2692 @code{pages-directory-for-addresses} command.
2695 * Key Assignments: page-ext-keys.
2696 * Using the Page Commands: page-ext-using.
2697 * Address List or Small Database: page-ext-addr.
2700 @node page-ext-keys, page-ext-using, page-ext, page-ext
2701 @section Key Assignments
2703 The current page commands are:
2705 @multitable {pages-directory-for-addresses} {C-x C-p (change this to C-x C-p C-m)}
2707 @item forward-page @tab C-x ]
2708 @item backward-page @tab C-x [
2709 @item narrow-to-page @tab C-x p
2710 @item count-lines-page @tab C-x l
2711 @item mark-page @tab C-x C-p (change this to C-x C-p C-m)
2712 @item sort-pages @tab not bound
2713 @item what-page @tab not bound
2717 The new page handling commands all use @kbd{C-x C-p} as a prefix. This means
2718 that the key binding for @code{mark-page} must be changed. Otherwise, no
2719 other changes are made to the current commands or their bindings.
2721 The extended page handling commands are:
2723 @multitable {pages-directory-for-addresses} {C-x C-p (change this to C-x C-p C-m)}
2725 @item next-page @tab C-x C-p C-n
2726 @item previous-page @tab C-x C-p C-p
2727 @item search-pages @tab C-x C-p C-s
2728 @item add-new-page @tab C-x C-p C-a
2729 @item sort-pages-buffer @tab C-x C-p s
2730 @item set-page-delimiter @tab C-x C-p C-l
2731 @item pages-directory @tab C-x C-p C-d
2732 @item pages-directory-for-addresses @tab C-x C-p d
2733 @item pages-directory-goto @tab C-c C-c
2737 @node page-ext-using, page-ext-addr, page-ext-keys, page-ext
2738 @section Using the Page Commands
2740 The page commands are helpful in several different contexts. For example,
2741 programmers often divide source files into sections using the
2742 @code{page-delimiter}; you can use the @code{pages-directory} command to list
2745 You may change the buffer local value of the @code{page-delimiter} with the
2746 @code{set-page-delimiter} command. This command is bound to @kbd{C-x C-p
2747 C-l}. The command prompts you for a new value for the @code{page-delimiter}.
2748 Called with a prefix-arg, the command resets the value of the page-delimiter
2749 to its original value.
2751 You may set several user options:
2755 @item pages-directory-buffer-narrowing-p
2756 Causes the @code{pages-directory-goto} command to narrow to the destination
2759 @item pages-directory-for-adding-page-narrowing-p
2760 Causes the @code{add-new-page} command to narrow to the new entry.
2762 @item pages-directory-for-adding-new-page-before-current-page-p
2763 Causes the @code{add-new-page} command to insert a new page before current
2768 These variables are all true by default.
2770 @node page-ext-addr, , page-ext-using, page-ext
2771 @section Address List or Small Database
2773 You may use the page commands to handle an address list or other small data
2774 base. Put each address or entry on its own page. The first line of text in
2775 each page is a `header line' and is listed by the @code{pages-directory} or
2776 @code{pages-directory-for-addresses} command.
2784 Begin each entry with a `page-delimiter' (which is, by default, `^L' at the
2785 beginning of the line).
2789 The first line of text in each entry is the `heading line'; it will appear in
2790 the pages-directory-buffer which is constructed using the @kbd{C-x C-p C-d}
2791 (@code{pages-directory}) command or the @kbd{C-x C-p d}
2792 (@code{pages-directory-for-addresses}) command.
2794 The heading line may be on the same line as the page-delimiter or it may
2795 follow after. It is the first non-blank line on the page. Conventionally,
2796 the heading line is placed on the line immediately following the line
2797 containing page-delimiter.
2801 Follow the heading line with the body of the entry. The body extends up to
2802 the next `page-delimiter'. The body may be of any length. It is
2803 conventional to place a blank line after the last line of the body.
2807 For example, a file might look like this:
2811 Free Software Foundation
2812 59 Temple Place - Suite 330
2813 Boston, MA 02111-1307 USA.
2815 gnu@@prep.ai.mit.edu
2818 House Subcommittee on Intellectual Property,
2819 U.S. House of Representatives,
2820 Washington, DC 20515
2822 Congressional committee concerned with permitting or preventing
2823 monopolistic restrictions on the use of software technology.
2827 ``Women, Fire, and Dangerous Things:
2828 What Categories Reveal about the Mind''
2829 1987, Univ. of Chicago Press
2831 About philosophy, Whorfian effects, and linguistics.
2834 OBI (On line text collection.)
2835 Open Book Initiative
2836 c/o Software Tool & Die
2837 1330 Beacon St, Brookline, MA 02146 USA
2842 In this example, the heading lines are:
2846 House Subcommittee on Intellectual Property
2848 OBI (On line text collection.)
2851 The @kbd{C-x C-p s} (@code{sort-pages-buffer}) command sorts the entries in
2852 the buffer alphabetically.
2854 You may use any of the page commands, including the @code{next-page},
2855 @code{previous-page}, @code{add-new-page}, @code{mark-page}, and
2856 @code{search-pages} commands.
2858 You may use either the @kbd{C-x C-p d} (@code{pages-directory-for-addresses})
2859 or the @kbd{C-x C-p C-d} (@code{pages-directory}) command to construct and
2860 display a directory of all the heading lines.
2862 In the directory, you may position the cursor over a heading line and type
2863 @kbd{C-c C-c} (@code{pages-directory-goto}) to go to the entry to which it
2864 refers in the pages buffer.
2866 You can type @kbd{C-c C-p C-a} (@code{add-new-page}) to add a new entry in
2867 the pages buffer or address file. This is the same command you use to add a
2868 new entry when you are in the pages buffer or address file.
2870 If you wish, you may create several different directories, one for each
2873 @code{`pages-directory-for-addresses} assumes a default addresses file. You
2874 do not need to specify the addresses file but merely type @kbd{C-x C-p d}
2875 from any buffer. The command finds the file, constructs a directory for it,
2876 and switches you to the directory. If you call the command with a prefix
2877 arg, @kbd{C-u C-x C-p d}, it prompts you for a file name.
2879 You may customize the addresses commands:
2883 @item pages-addresses-file-name
2884 Determines the name of the addresses file; by default it is "~/addresses".
2886 @item pages-directory-for-addresses-goto-narrowing-p
2887 Determines whether @code{pages-directory-goto} narrows the addresses
2888 buffer to the entry, which it does by default.
2890 @item pages-directory-for-addresses-buffer-keep-windows-p
2891 Determines whether @code{pages-directory-for-addresses} deletes other windows
2892 to show as many lines as possible on the screen or works in the usual Emacs
2893 manner and keeps other windows. Default is to keep other windows.
2895 @item pages-directory-for-adding-addresses-narrowing-p
2896 Determines whether @code{pages-directory-for-addresses} narrows the addresses
2897 buffer to a new entry when you are adding that entry. Default is to narrow
2898 to new entry, which means you see a blank screen before you write the new
2903 Call the @code{pages-directory} command from the buffer for which you want a
2904 directory created; it creates a directory for the buffer and pops you to the
2907 The @code{pages-directory} command has several options:
2913 Called with a prefix arg, @kbd{C-u C-x C-p C-d}, the @code{pages-directory}
2914 prompts you for a regular expression and only lists only those header lines
2915 that are part of pages that contain matches to the regexp. In the example
2916 above, @kbd{C-u C-x C-p C-d 617 RET} would match the telephone area code of
2917 the first and fourth entries, so only the header lines of those two entries
2918 would appear in the pages-directory-buffer.
2922 Called with a numeric argument, the @code{pages-directory} command lists the
2923 number of lines in each page. This is helpful when you are printing
2928 Called with a negative numeric argument, the @code{pages-directory} command
2929 lists the lengths of pages whose contents match a regexp.
2933 To configure this package, type:
2936 M-x customize-group RET pages RET
2939 @node power-macros, redo, page-ext, Top
2940 @chapter Power Macros - Keyboard Macros Made Easy
2942 Keyboard Macros are a very powerful tool, if you know how to use them the
2943 right way! Without this extension it is, however, a bit difficult in Emacs
2944 to define and maintain several macros at a time. This problem is solved with
2947 When you have loaded this package Emacs will, upon completion of macro
2948 definition, ask you which key you want to assign this macro to and ask for a
2949 description of the macro. If something is already bound to this key, Emacs
2950 will ask you whether you want to override this binding. Furthermore, this
2951 package also takes care of saving the macro to your initialization file for
2952 later Emacs sessions.
2954 The description for all the defined macros may be obtained with the function
2955 `pm-manage-macros'. Using this function you can also manage your
2958 To execute this function, type:
2961 M-x pm-manage-macros RET
2964 To configure the package, type:
2967 M-x customize-group RET power-macros RET
2970 @node redo, scroll-in-place, power-macros, Top
2971 @chapter Redo/Undo System
2973 Emacs' normal undo system allows you to undo an arbitrary number of buffer
2974 changes. These undos are recorded as ordinary buffer changes themselves. So
2975 when you break the chain of undos by issuing some other command, you can then
2976 undo all the undos. The chain of recorded buffer modifications therefore
2977 grows without bound, truncated only at garbage collection time.
2979 The redo/undo system is different in two ways:
2985 The undo/redo command chain is only broken by a buffer modification. You can
2986 move around the buffer or switch buffers and still come back and do more
2991 The @code{redo} command rescinds the most recent undo without recording the
2992 change as a _new_ buffer change. It completely reverses the effect of the
2993 undo, which includes making the chain of buffer modification records shorter
2994 by one, to counteract the effect of the undo command making the record list
2999 To use this package, add the following to your initialization file:
3005 @node scroll-in-place, setnu, redo, Top
3006 @chapter Scrolling In Place
3008 This library provides improved vertical scrolling commands for GNU Emacs.
3011 * Features: sip-features.
3012 * Commands and Functions: sip-commands.
3013 * Installation: sip-install.
3014 * Advanced Customization: sip-customize
3017 @node sip-features, sip-commands, scroll-in-place, scroll-in-place
3020 The new vertical scrolling commands offer the following features:
3026 When a scrolling command is executed, GNU Emacs tries to keep point as close
3027 as possible to its original window position (window line and column). This
3028 is what "scroll in place" means: point stays "in place" within the window.
3029 (There are times when point must be moved from its original window position
3030 in order to execute the scroll; see below.)
3032 The variable @code{scroll-in-place}, which is true by default, determines
3033 whether or not the standard GNU Emacs scrolling commands (@code{scroll-down},
3034 @code{scroll-up}, @code{scroll-other-window-down}, and
3035 @code{scroll-other-window}) use the "in place" features listed here. When
3036 @code{scroll-in-place} is nil the standard GNU Emacs scrolling commands
3037 essentially just call the original versions of themselves. (Note that even
3038 when @code{scroll-in-place} is nil the new versions of @code{scroll-down} and
3039 @code{scroll-up} have slightly different behavior when a minibuffer window is
3040 the selected window. See below.)
3042 It is possible to turn off (or turn on) "in place" scrolling for certain
3043 buffers by making buffer-local bindings of the variable
3044 @code{scroll-in-place} for those buffers. The variable
3045 @code{scroll-in-place} is not usually buffer-local, but you can make it so if
3050 Because the improved scrolling commands keep point at its original window
3051 position, these scrolling commands are "reversible." The @code{scroll-up}
3052 command undoes the effect of the immediately previous @code{scroll-down}
3053 command (if any) and vice versa. In other words, if you scroll up and then
3054 immediately scroll back down, the window configuration is restored to its
3055 exact original state. This allows you to browse through a buffer more
3056 easily, as you can always get back to the original configuration.
3058 Note, however, that the improved scrolling commands are guaranteed to be
3059 reversible only if there are no intervening non-scrolling commands. Also, if
3060 you give a prefix argument to a scrolling command (in order to specify the
3061 number of lines to scroll by), previous scrolling commands may no longer be
3062 reversible. More specifically, if the new prefix argument has a different
3063 magnitude than the previous scrolling distance, then any previous scrolling
3064 commands are not reversible. The new prefix argument takes precedence.
3066 You might find it useful to think of the scrolling commands as forming
3067 "chains." A scrolling command either starts or continues a chain. By
3068 issuing a non-scrolling command or by changing the number of lines to be
3069 scrolled, you break the chain. (Note that simply changing the scrolling
3070 direction won't break the chain; changing the absolute number of lines to be
3071 scrolled is what breaks the chain.) Scrolling commands are guaranteed to be
3072 reversible only within the current chain. Hopefully that's clear enough.
3076 When a scrolling command is given a prefix argument (which specifies the
3077 number of lines to scroll by), then that argument becomes the default
3078 scrolling distance for all immediately subsequent scrolling commands. This
3079 means that you can easily set the scrolling distance for a chain of scrolling
3080 commands. Note that a new prefix argument or any non- scrolling command
3081 breaks the chain (as described above), and any further scrolling commands
3082 will use the usual defaults (or the prefix argument you specify at that time,
3085 However, there are cases in which one doesn't want the current scrolling
3086 command to use the default scrolling distance that was set by the previous
3087 scrolling command. For example, suppose that you had special commands that
3088 scrolled one line up and one line down. When you invoke one of these
3089 commands, the "in place" scrolling routines set the default scrolling
3090 distance to be just one line. Now suppose that you use one of your special
3091 commands and then immediately invoke @code{scroll-up} (@kbd{C-v}), expecting
3092 it to scroll by a near windowful of text. You would be disappointed ---
3093 because the previous command set the default scrolling distance to be just
3094 one line, @code{scroll-up} just scrolls by one line.
3096 To solve this problem, "scroll-in-place" allows you to divide scrolling
3097 commands into separate "groups." Commands in a group can only form chains
3098 with (and therefore, inherit defaults from) commands in the same group.
3099 (Note that no command can be in more than one group.) If you invoke a
3100 scrolling command that is not in the same group as that of the immediately
3101 previous scrolling command, then the previous chain is broken and you start a
3102 new chain --- with a new set of defaults.
3104 So to solve the problem described above, you could put your one-line
3105 scrolling commands in their own group. Once that is done, the standard
3106 scrolling commands will not form chains with your one-line scrolling
3107 commands, and therefore will not use the default scrolling distance set by
3108 those commands. Problem solved!
3110 By default, all "in place" scrolling commands are in a single group. If you
3111 want to partition some commands into separate groups, you must do that
3112 yourself @emph{before} any "in place" commands are invoked. For more
3113 information about grouping commands, see the documentation for the variables
3114 @code{scroll-command-groups} and @code{scroll-default-command-group}.
3118 The improved scrolling commands will avoid displaying empty lines past the
3119 end of the buffer when possible. In other words, just as you can't see "dead
3120 space" before the beginning of the buffer text, the new scrolling commands
3121 try to avoid displaying "dead space" past the end of the buffer text. This
3122 behavior is somewhat configurable; see the documentation for the variable
3123 @code{scroll-allow-blank-lines-past-eob}.
3125 Dead space will be displayed if it is necessary in order to make a previous
3126 scrolling action reversible, however.
3130 If the scrolling commands cannot keep point at its initial window position
3131 (because a buffer boundary is on screen and the window can't be scrolled as
3132 far as necessary to keep point at the right place), point is allowed to
3133 temporarily stray from its initial window position. That is, point moves the
3134 correct number of window lines, even if it means that it has to stray from
3135 its desired window position. This straying is undone when (and if) the
3136 scrolling action is reversed.
3140 If a scrolling command tries to move point past a buffer boundary, point is
3141 instead moved to the boundary (the beginning or the end of the buffer as
3142 appropriate) and an appropriate message is displayed. This motion is
3143 reversible, of course.
3145 However, if point was already at the buffer boundary when the scrolling
3146 command was invoked, the command signals an appropriate error instead.
3150 When a minibuffer window is the selected window, the new versions of
3151 @code{scroll-up} and @code{scroll-down} either scroll the window in the
3152 variable @code{minibuffer-scroll-window} (which is usually the window of
3153 completions) or the @code{next-window} if there is no
3154 @code{minibuffer-scroll-window}. This is usually much more useful than
3155 scrolling the minibuffer itself. (Note that this feature is available even
3156 when the variable @code{scroll-in-place} is nil.)
3160 When a scrolling command is scrolling a window other than the selected
3161 window, it will signal an appropriate buffer boundary error if the window
3162 cannot be scrolled (because the appropriate buffer boundary is already
3163 visible). This means that an error is signalled even in cases that would be
3164 allowed (by "straying" point or by moving it to the buffer boundary) if the
3165 window were selected.
3167 (If an error were not signalled in these cases, then there would be many
3168 cases in which the last scroll in a particular direction would appear to do
3169 nothing because only the point position would change --- the displayed text
3170 would stay the same! To avoid these cases the scrolling commands signal
3171 boundary errors "prematurely" when the window to be scrolled is not
3176 @node sip-commands, sip-install, sip-features, scroll-in-place
3177 @section Command and Functions
3179 This library provides the following "in place" versions of GNU Emacs'
3180 standard vertical scrolling commands:
3183 @item scroll-down-in-place
3184 @item scroll-up-in-place
3185 @item scroll-other-window-down-in-place
3186 @item scroll-other-window-in-place
3189 The variable @code{scroll-in-place}, which is true by default, determines
3190 whether or not the new versions of the standard GNU Emacs scrolling commands
3191 (@code{scroll-down}, @code{scroll-up}, @code{scroll-other-window-down}, and
3192 @code{scroll-other-window}) use the "in place" features listed above. When
3193 @code{scroll-in-place} is nil the standard GNU Emacs scrolling commands
3194 essentially just call the original versions of themselves. (Note that even
3195 when @code{scroll-in-place} is nil the new versions of @code{scroll-down} and
3196 @code{scroll-up} have slightly different behavior when a minibuffer window is
3197 the selected window. See the feature list above.)
3199 NOTE that this package redefines the standard GNU Emacs commands
3200 @code{scroll-down}, @code{scroll-up}, @code{scroll-other-window-down}, and
3201 @code{scroll-other-window} (in order to check the variable
3202 @code{scroll-in-place}, as described above). The command
3203 @code{scroll-other-window-down} first appeared as a standard command in the
3204 FSF's GNU Emacs 19.26.
3206 This package also provides the following functions and variables which are
3207 of use to programmers:
3211 @item scroll-window-in-place
3212 @item scroll-window-in-place-continue-sequence
3213 @item scroll-default-lines (variable)
3214 @item scroll-command-groups (variable)
3217 The @code{scroll-window-in-place} function is the heart of the "in place"
3218 scrolling commands. @code{scroll-window} is a function that checks the
3219 variable @code{scroll-in-place} and calls the appropriate scrolling function
3220 (either @code{scroll-window-in-place} or one of the original versions of
3221 @code{scroll-down} and @code{scroll-up}). The function
3222 @code{scroll-window-in-place-continue-sequence} is provided in order to
3223 preserve running "chains" of scrolling commands as described above.
3225 The variable @code{scroll-default-lines} determines the default scrolling
3226 distance when a new chain of "in place" scrolling commands begins. If this
3227 variable is not a number, then the default distance is the height of the
3228 window to be scrolled minus @code{next-screen-context-lines}. The variable
3229 @code{scroll-command-groups} contains the explicit groups of "in place"
3230 scrolling commands; for more information read the variable documentation.
3232 @node sip-install, sip-customize, sip-commands, scroll-in-place
3233 @section Installation
3235 To use this package, you simply need to load it from within your
3236 initialization file:
3239 (require 'scroll-in-place)
3242 By default, this package provides for the standard GNU Emacs vertical
3243 scrolling commands (@code{scroll-down}, @code{scroll-up},
3244 @code{scroll-other-window-down}, and @code{scroll-other-window}) to use the
3245 "in place" features. If you would rather not have this, set the variable
3246 @code{(setq scroll-in-place nil)}.
3248 When @code{scroll-in-place} is nil you will have to bind keys in order to
3249 call the "in place" scrolling commands. For example, you might want to do
3253 (global-set-key "\M-v" 'scroll-down-in-place)
3254 (global-set-key "\C-v" 'scroll-up-in-place)
3257 @node sip-customize, , sip-install, scroll-in-place
3258 @section Advanced Customization
3260 If you want to partition certain "in place" scrolling commands into separate
3261 groups, you should do something like the following:
3264 ;; Make one group containing the commands `scroll-down-one-line' and
3265 ;; `scroll-up-one-line'. (These are not standard GNU Emacs commands.)
3266 (setq scroll-command-groups
3267 (list '(scroll-down-one-line scroll-up-one-line)))
3270 You could write the `scroll-down-one-line' command like this:
3273 (defun scroll-down-one-line (arg)
3274 "Scroll down one line, or number of lines specified by prefix arg."
3276 (let ((scroll-default-lines 1))
3277 (scroll-down-in-place arg)))
3280 If you want to disable "in place" scrolling for windows that display a
3281 particular buffer (while leaving it available in other windows), you can make
3282 @code{scroll-in-place} a buffer-local variable for that buffer and then bind
3283 that local copy of @code{scroll-in-place} to nil. This is the kind of thing
3284 that one generally does in a major mode hook. For example, you can disable
3285 "in place" scrolling of GNUS article windows with the following code:
3288 (setq gnus-article-mode-hook
3289 (function (lambda ()
3290 (make-local-variable 'scroll-in-place)
3291 (setq scroll-in-place nil))))
3292 ;; Set the variable `gnus-Article-mode-hook' instead if you are using
3293 ;; an old version of GNUS, say version 3.13 or 3.14.
3296 The variable @code{scroll-allow-blank-lines-past-eob} can also be made local
3297 to particular buffers, if you desire. (But why would you want to do that?)
3299 @node setnu, vertical-mode, scroll-in-place, Top
3300 @chapter VI-style Line Number Mode
3302 This library activates VI-style line numbering for a buffer.
3304 @code{M-x setnu-mode} toggles the line number mode on and off.
3306 @code{turn-on-setnu-mode} is useful for adding to a major-mode hook variable.
3309 (add-hook 'text-mode-hook 'turn-on-setnu-mode)
3312 to automatically turn on line numbering when entering text-mode.
3314 @node vertical-mode, align, setnu, Top
3315 @chapter Vertical Mode - Editing of Vertical Text
3317 This minor mode allows you to conveniently edit things that are oriented
3318 vertically (like tables in computer programs): after each action, cursor
3319 moves down. Therefore, to move block of text to the right, you simply enter
3320 vertical mode and then hold @kbd{spacebar}, waiting for autorepeat to do the
3323 @node align, allout, vertical-mode, Top
3324 @chapter Align Text to a Specific Column, By Regexp
3326 This mode allows you to align regions in a context-sensitive fashion. The
3327 classic use is to align assignments:
3344 * Align Usage:: How to use the package.
3347 @node Align Usage, , align, align
3348 @section Align Usage
3350 To configure the package, type:
3353 M-x customize-group RET align RET
3356 There are several variables which define how certain "categories" of syntax
3357 are to be treated. These variables go by the name `align-CATEGORY-modes'.
3358 For example, "c++" is such a category. There are several rules which apply
3359 to c++, but since several other languages have a syntax similar to c++ (e.g.,
3360 c, java, etc), these modes are treated as belonging to the same category.
3362 If you want to add a new mode under a certain category, just customize that
3363 list, or add the new mode manually. For example, to make jde-mode a c++
3364 category mode, use this code in your initialization file:
3367 (setq align-c++-modes (cons 'jde-mode align-c++-modes))
3370 In some programming modes, it's useful to have the aligner run only after
3371 indentation is performed. To achieve this, customize or set the variable
3372 `align-indent-before-aligning' to t.
3374 @node allout, narrow-stack, align, Top
3375 @chapter Extensive Outline Mode
3377 Allout outline mode provides extensive outline formatting and manipulation
3378 beyond standard emacs outline mode (@pxref{Outline Mode,,,xemacs}). It
3379 provides for structured editing of outlines, as well as navigation and
3380 exposure. It also provides for syntax-sensitive text like programming
3381 languages. (For an example, see the allout code itself, which is organized
3382 in ;; an outline framework.)
3384 In addition to outline navigation and exposure, allout includes:
3388 @item topic-oriented repositioning, cut, and paste
3390 @item integral outline exposure-layout
3392 @item incremental search with dynamic exposure and reconcealment of hidden
3395 @item automatic topic-number maintenance
3397 @item "Hot-spot" operation, for single-keystroke maneuvering and exposure
3398 control. (See the outline-mode docstring.)
3402 and many other features.
3404 To configure the package, type:
3407 M-x customize-group RET allout RET
3410 To use the allout package in place of the standard outline package, add the
3411 following bit of code
3414 (require 'outline "allout")
3417 to your initialization file. This will ensure that all the functions
3418 provided by the outline package will be loaded from the new allout package
3421 The outline menubar additions provide quick reference to many of the
3422 features, and see the docstring of the variable `outline-init' for
3423 instructions on priming your emacs session for automatic activation of
3426 See the docstring of the variables `outline-layout' and
3427 `outline-auto-activation' for details on automatic activation of allout
3428 outline-mode as a minor mode.
3430 By default, allout mode does not fontify the buffer. To get Font Lock to work
3431 put the following into your initialization file (adapted from the standard
3435 (defvar rf-allout-font-lock-keywords
3437 ;; Highlight headings according to the level.
3438 (eval . (list (concat "^\\(" outline-regexp "\\).+")
3439 0 '(or (cdr (assq (outline-depth)
3440 '((1 . font-lock-function-name-face)
3441 (2 . font-lock-variable-name-face)
3442 (3 . font-lock-keyword-face)
3443 (4 . font-lock-builtin-face)
3444 (5 . font-lock-comment-face)
3445 (6 . font-lock-constant-face)
3446 (7 . font-lock-type-face)
3447 (8 . font-lock-string-face))))
3448 font-lock-warning-face)
3450 "Additional expressions to highlight in Outline mode.")
3452 ;; add font-lock to allout mode
3453 (defun rf-allout-font-lock-hook ()
3454 (set (make-local-variable 'font-lock-defaults)
3455 '(rf-allout-font-lock-keywords t nil nil outline-back-to-current-heading)))
3457 (add-hook 'outline-mode-hook 'rf-allout-font-lock-hook)
3460 @node narrow-stack, register-menu, allout, Top
3461 @chapter Extending the built-in narrowing functions
3463 Narrowing, as implemented in Emacs has one limitation, namely that it is not
3464 possible to narrow within a narrowing, and then widen again to the previous
3465 narrowing. This package implements an extension to narrowing, which makes
3468 To activate this extension type @code{M-x narrow-stack-mode} or add
3469 @code{(narrow-stack-mode)} to your initialization file.
3471 @node register-menu, register-toolbar, narrow-stack, Top
3473 Registers in XEmacs are limited in easy accessibility to a handful of
3474 functions in the default keyboard layout. This menu provides a
3475 top-level menu interface to most of the functionality provided by
3476 registers, including columnar copying, bookmarking, and real-time
3477 in-menu previews of the contents of registers.
3479 This menu can be configured through the register-menu configure group. Type @code{M-x
3480 customize-group RET register-menu RET}
3482 @node register-toolbar, flow-ctrl, register-menu, Top
3484 The current XEmacs interface for registers is either deep in the
3485 menus, requiring multiple clicks for a single copy/paste command, or
3486 on a handful of keyboard bindings. The register toolbar minor mode
3487 provides a simple click interface for cut, copy and paste
3488 functionality to the digit registers (0-9). Modes are also available
3489 for columnar copy/cut operations.
3491 This minor mode can be enabled through button 3 on the modeline or the
3492 command: @code{M-x register-toolbar-mode}.
3494 @node flow-ctrl, makesum, register-toolbar, Top
3495 @chapter Flow Control
3497 Terminals that use XON/XOFF flow control can cause problems with GNU Emacs
3498 users. This file contains Emacs Lisp code that makes it easy for a user to
3499 deal with this problem, when using such a terminal.
3501 To invoke these adjustments, a user need only invoke the function
3502 @code{enable-flow-control-on} with a list of terminal types specified in the
3503 initialization file. As arguments, give it the names of one or more terminal
3504 types in use by that user which require flow control adjustments. Here's an
3508 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
3511 Portability note: This uses @code{(getenv "TERM")}, and therefore probably
3512 won't work outside of UNIX-like environments.
3514 @node makesum, man, flow-ctrl, Top
3515 @chapter Generate Summary of All Key Binding
3517 Displays a nice human-readable summary of all keybindings in a two-column
3520 To invoke this command, type:
3523 M-x make-command-summary RET
3526 @node man, abbrevlist, makesum, Top
3527 @chapter Browse UNIX manual pages
3529 This library defines the command @code{manual-entry} to browse Unix manual
3532 To invoke this command, type:
3535 M-x manual-entry RET
3538 For ease of use, autocompletion on @code{M-x man} will work just fine.
3540 To configure this package, type:
3543 M-x customize-group RET man RET
3546 @node abbrevlist, file-part, man, Top
3547 @chapter Abbreviation List
3549 This library not documented. Please contribute!
3551 @node file-part, info-look, abbrevlist, Top
3552 @chapter Treat a Section of a Buffer as a Separate File
3554 This library not documented. Please contribute!
3556 @node info-look, live-icon, file-part, Top
3557 @chapter Major-Mode-Sensitive Info Index Lookup Facility
3559 This library not documented. Please contribute!
3561 @node live-icon, mode-motion+, info-look, Top
3562 @chapter Make Frame Icons Represent Current Frame Contents
3564 This library not documented. Please contribute!
3566 @node mode-motion+, popper, live-icon, Top
3567 @chapter Per Mode/Buffer Mouse Tracking With Highlighting
3569 This library not documented. Please contribute!
3571 @node popper, reportmail, mode-motion+, Top
3572 @chapter Shrink-Wrapped Temporary Windows
3574 This library not documented. Please contribute!
3576 @node reportmail, balloon-help, popper, Top
3577 @chapter Display Time and Load in Mode Line
3579 This library not documented. Please contribute!
3581 @node balloon-help, blink-paren, reportmail, Top
3582 @chapter Balloon Help and Tooltips
3584 This library not documented. Please contribute!
3586 @node blink-paren, edit-faces, balloon-help, Top
3587 @chapter Blinking Parentheses
3589 This library not documented. Please contribute!
3591 @node edit-faces, lispm-fonts, blink-paren, Top
3592 @chapter Face Editor
3594 This library not documented. Please contribute!
3596 @node lispm-fonts, big-menubar, edit-faces, Top
3597 @chapter lispm-fonts
3599 This library not documented. Please contribute!
3601 @node big-menubar, tree-menu, lispm-fonts, Top
3602 @chapter Big Menubar
3604 This library not documented. Please contribute!
3606 @node tree-menu, XEmacs License, big-menubar, Top
3609 This library not documented. Please contribute!
3611 @node XEmacs License, , tree-menu, Top
3612 @chapter XEmacs License
3613 @unnumbered GNU GENERAL PUBLIC LICENSE
3614 @center Version 2, June 1991
3617 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
3618 675 Mass Ave, Cambridge, MA 02139, USA
3620 Everyone is permitted to copy and distribute verbatim copies
3621 of this license document, but changing it is not allowed.
3624 @unnumberedsec Preamble
3626 The licenses for most software are designed to take away your
3627 freedom to share and change it. By contrast, the GNU General Public
3628 License is intended to guarantee your freedom to share and change free
3629 software---to make sure the software is free for all its users. This
3630 General Public License applies to most of the Free Software
3631 Foundation's software and to any other program whose authors commit to
3632 using it. (Some other Free Software Foundation software is covered by
3633 the GNU Library General Public License instead.) You can apply it to
3636 When we speak of free software, we are referring to freedom, not
3637 price. Our General Public Licenses are designed to make sure that you
3638 have the freedom to distribute copies of free software (and charge for
3639 this service if you wish), that you receive source code or can get it
3640 if you want it, that you can change the software or use pieces of it
3641 in new free programs; and that you know you can do these things.
3643 To protect your rights, we need to make restrictions that forbid
3644 anyone to deny you these rights or to ask you to surrender the rights.
3645 These restrictions translate to certain responsibilities for you if you
3646 distribute copies of the software, or if you modify it.
3648 For example, if you distribute copies of such a program, whether
3649 gratis or for a fee, you must give the recipients all the rights that
3650 you have. You must make sure that they, too, receive or can get the
3651 source code. And you must show them these terms so they know their
3654 We protect your rights with two steps: (1) copyright the software, and
3655 (2) offer you this license which gives you legal permission to copy,
3656 distribute and/or modify the software.
3658 Also, for each author's protection and ours, we want to make certain
3659 that everyone understands that there is no warranty for this free
3660 software. If the software is modified by someone else and passed on, we
3661 want its recipients to know that what they have is not the original, so
3662 that any problems introduced by others will not reflect on the original
3663 authors' reputations.
3665 Finally, any free program is threatened constantly by software
3666 patents. We wish to avoid the danger that redistributors of a free
3667 program will individually obtain patent licenses, in effect making the
3668 program proprietary. To prevent this, we have made it clear that any
3669 patent must be licensed for everyone's free use or not licensed at all.
3671 The precise terms and conditions for copying, distribution and
3672 modification follow.
3675 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3678 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3683 This License applies to any program or other work which contains
3684 a notice placed by the copyright holder saying it may be distributed
3685 under the terms of this General Public License. The ``Program'', below,
3686 refers to any such program or work, and a ``work based on the Program''
3687 means either the Program or any derivative work under copyright law:
3688 that is to say, a work containing the Program or a portion of it,
3689 either verbatim or with modifications and/or translated into another
3690 language. (Hereinafter, translation is included without limitation in
3691 the term ``modification''.) Each licensee is addressed as ``you''.
3693 Activities other than copying, distribution and modification are not
3694 covered by this License; they are outside its scope. The act of
3695 running the Program is not restricted, and the output from the Program
3696 is covered only if its contents constitute a work based on the
3697 Program (independent of having been made by running the Program).
3698 Whether that is true depends on what the Program does.
3701 You may copy and distribute verbatim copies of the Program's
3702 source code as you receive it, in any medium, provided that you
3703 conspicuously and appropriately publish on each copy an appropriate
3704 copyright notice and disclaimer of warranty; keep intact all the
3705 notices that refer to this License and to the absence of any warranty;
3706 and give any other recipients of the Program a copy of this License
3707 along with the Program.
3709 You may charge a fee for the physical act of transferring a copy, and
3710 you may at your option offer warranty protection in exchange for a fee.
3713 You may modify your copy or copies of the Program or any portion
3714 of it, thus forming a work based on the Program, and copy and
3715 distribute such modifications or work under the terms of Section 1
3716 above, provided that you also meet all of these conditions:
3720 You must cause the modified files to carry prominent notices
3721 stating that you changed the files and the date of any change.
3724 You must cause any work that you distribute or publish, that in
3725 whole or in part contains or is derived from the Program or any
3726 part thereof, to be licensed as a whole at no charge to all third
3727 parties under the terms of this License.
3730 If the modified program normally reads commands interactively
3731 when run, you must cause it, when started running for such
3732 interactive use in the most ordinary way, to print or display an
3733 announcement including an appropriate copyright notice and a
3734 notice that there is no warranty (or else, saying that you provide
3735 a warranty) and that users may redistribute the program under
3736 these conditions, and telling the user how to view a copy of this
3737 License. (Exception: if the Program itself is interactive but
3738 does not normally print such an announcement, your work based on
3739 the Program is not required to print an announcement.)
3742 These requirements apply to the modified work as a whole. If
3743 identifiable sections of that work are not derived from the Program,
3744 and can be reasonably considered independent and separate works in
3745 themselves, then this License, and its terms, do not apply to those
3746 sections when you distribute them as separate works. But when you
3747 distribute the same sections as part of a whole which is a work based
3748 on the Program, the distribution of the whole must be on the terms of
3749 this License, whose permissions for other licensees extend to the
3750 entire whole, and thus to each and every part regardless of who wrote it.
3752 Thus, it is not the intent of this section to claim rights or contest
3753 your rights to work written entirely by you; rather, the intent is to
3754 exercise the right to control the distribution of derivative or
3755 collective works based on the Program.
3757 In addition, mere aggregation of another work not based on the Program
3758 with the Program (or with a work based on the Program) on a volume of
3759 a storage or distribution medium does not bring the other work under
3760 the scope of this License.
3763 You may copy and distribute the Program (or a work based on it,
3764 under Section 2) in object code or executable form under the terms of
3765 Sections 1 and 2 above provided that you also do one of the following:
3769 Accompany it with the complete corresponding machine-readable
3770 source code, which must be distributed under the terms of Sections
3771 1 and 2 above on a medium customarily used for software interchange; or,
3774 Accompany it with a written offer, valid for at least three
3775 years, to give any third party, for a charge no more than your
3776 cost of physically performing source distribution, a complete
3777 machine-readable copy of the corresponding source code, to be
3778 distributed under the terms of Sections 1 and 2 above on a medium
3779 customarily used for software interchange; or,
3782 Accompany it with the information you received as to the offer
3783 to distribute corresponding source code. (This alternative is
3784 allowed only for noncommercial distribution and only if you
3785 received the program in object code or executable form with such
3786 an offer, in accord with Subsection b above.)
3789 The source code for a work means the preferred form of the work for
3790 making modifications to it. For an executable work, complete source
3791 code means all the source code for all modules it contains, plus any
3792 associated interface definition files, plus the scripts used to
3793 control compilation and installation of the executable. However, as a
3794 special exception, the source code distributed need not include
3795 anything that is normally distributed (in either source or binary
3796 form) with the major components (compiler, kernel, and so on) of the
3797 operating system on which the executable runs, unless that component
3798 itself accompanies the executable.
3800 If distribution of executable or object code is made by offering
3801 access to copy from a designated place, then offering equivalent
3802 access to copy the source code from the same place counts as
3803 distribution of the source code, even though third parties are not
3804 compelled to copy the source along with the object code.
3807 You may not copy, modify, sublicense, or distribute the Program
3808 except as expressly provided under this License. Any attempt
3809 otherwise to copy, modify, sublicense or distribute the Program is
3810 void, and will automatically terminate your rights under this License.
3811 However, parties who have received copies, or rights, from you under
3812 this License will not have their licenses terminated so long as such
3813 parties remain in full compliance.
3816 You are not required to accept this License, since you have not
3817 signed it. However, nothing else grants you permission to modify or
3818 distribute the Program or its derivative works. These actions are
3819 prohibited by law if you do not accept this License. Therefore, by
3820 modifying or distributing the Program (or any work based on the
3821 Program), you indicate your acceptance of this License to do so, and
3822 all its terms and conditions for copying, distributing or modifying
3823 the Program or works based on it.
3826 Each time you redistribute the Program (or any work based on the
3827 Program), the recipient automatically receives a license from the
3828 original licensor to copy, distribute or modify the Program subject to
3829 these terms and conditions. You may not impose any further
3830 restrictions on the recipients' exercise of the rights granted herein.
3831 You are not responsible for enforcing compliance by third parties to
3835 If, as a consequence of a court judgment or allegation of patent
3836 infringement or for any other reason (not limited to patent issues),
3837 conditions are imposed on you (whether by court order, agreement or
3838 otherwise) that contradict the conditions of this License, they do not
3839 excuse you from the conditions of this License. If you cannot
3840 distribute so as to satisfy simultaneously your obligations under this
3841 License and any other pertinent obligations, then as a consequence you
3842 may not distribute the Program at all. For example, if a patent
3843 license would not permit royalty-free redistribution of the Program by
3844 all those who receive copies directly or indirectly through you, then
3845 the only way you could satisfy both it and this License would be to
3846 refrain entirely from distribution of the Program.
3848 If any portion of this section is held invalid or unenforceable under
3849 any particular circumstance, the balance of the section is intended to
3850 apply and the section as a whole is intended to apply in other
3853 It is not the purpose of this section to induce you to infringe any
3854 patents or other property right claims or to contest validity of any
3855 such claims; this section has the sole purpose of protecting the
3856 integrity of the free software distribution system, which is
3857 implemented by public license practices. Many people have made
3858 generous contributions to the wide range of software distributed
3859 through that system in reliance on consistent application of that
3860 system; it is up to the author/donor to decide if he or she is willing
3861 to distribute software through any other system and a licensee cannot
3864 This section is intended to make thoroughly clear what is believed to
3865 be a consequence of the rest of this License.
3868 If the distribution and/or use of the Program is restricted in
3869 certain countries either by patents or by copyrighted interfaces, the
3870 original copyright holder who places the Program under this License
3871 may add an explicit geographical distribution limitation excluding
3872 those countries, so that distribution is permitted only in or among
3873 countries not thus excluded. In such case, this License incorporates
3874 the limitation as if written in the body of this License.
3877 The Free Software Foundation may publish revised and/or new versions
3878 of the General Public License from time to time. Such new versions will
3879 be similar in spirit to the present version, but may differ in detail to
3880 address new problems or concerns.
3882 Each version is given a distinguishing version number. If the Program
3883 specifies a version number of this License which applies to it and ``any
3884 later version'', you have the option of following the terms and conditions
3885 either of that version or of any later version published by the Free
3886 Software Foundation. If the Program does not specify a version number of
3887 this License, you may choose any version ever published by the Free Software
3891 If you wish to incorporate parts of the Program into other free
3892 programs whose distribution conditions are different, write to the author
3893 to ask for permission. For software which is copyrighted by the Free
3894 Software Foundation, write to the Free Software Foundation; we sometimes
3895 make exceptions for this. Our decision will be guided by the two goals
3896 of preserving the free status of all derivatives of our free software and
3897 of promoting the sharing and reuse of software generally.
3900 @heading NO WARRANTY
3907 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
3908 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
3909 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
3910 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
3911 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
3912 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS
3913 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE
3914 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
3915 REPAIR OR CORRECTION.
3918 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
3919 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
3920 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
3921 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
3922 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
3923 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
3924 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
3925 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
3926 POSSIBILITY OF SUCH DAMAGES.
3930 @heading END OF TERMS AND CONDITIONS
3933 @center END OF TERMS AND CONDITIONS
3937 @unnumberedsec How to Apply These Terms to Your New Programs
3939 If you develop a new program, and you want it to be of the greatest
3940 possible use to the public, the best way to achieve this is to make it
3941 free software which everyone can redistribute and change under these terms.
3943 To do so, attach the following notices to the program. It is safest
3944 to attach them to the start of each source file to most effectively
3945 convey the exclusion of warranty; and each file should have at least
3946 the ``copyright'' line and a pointer to where the full notice is found.
3949 @var{one line to give the program's name and an idea of what it does.}
3950 Copyright (C) 19@var{yy} @var{name of author}
3952 This program is free software; you can redistribute it and/or
3953 modify it under the terms of the GNU General Public License
3954 as published by the Free Software Foundation; either version 2
3955 of the License, or (at your option) any later version.
3957 This program is distributed in the hope that it will be useful,
3958 but WITHOUT ANY WARRANTY; without even the implied warranty of
3959 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the
3960 GNU General Public License for more details.
3962 You should have received a copy of the GNU General Public License
3963 along with this program; if not, write to the Free Software
3964 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
3967 Also add information on how to contact you by electronic and paper mail.
3969 If the program is interactive, make it output a short notice like this
3970 when it starts in an interactive mode:
3973 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
3974 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
3975 type `show w'. This is free software, and you are welcome
3976 to redistribute it under certain conditions; type `show c'
3980 The hypothetical commands @samp{show w} and @samp{show c} should show
3981 the appropriate parts of the General Public License. Of course, the
3982 commands you use may be called something other than @samp{show w} and
3983 @samp{show c}; they could even be mouse-clicks or menu items---whatever
3986 You should also get your employer (if you work as a programmer) or your
3987 school, if any, to sign a ``copyright disclaimer'' for the program, if
3988 necessary. Here is a sample; alter the names:
3992 Yoyodyne, Inc., hereby disclaims all copyright
3993 interest in the program `Gnomovision'
3994 (which makes passes at compilers) written
3997 @var{signature of Ty Coon}, 1 April 1989
3998 Ty Coon, President of Vice
4002 This General Public License does not permit incorporating your program into
4003 proprietary programs. If your program is a subroutine library, you may
4004 consider it more useful to permit linking proprietary applications with the
4005 library. If this is what you want to do, use the GNU Library General
4006 Public License instead of this License.