From: Miles Bader Date: Mon, 15 Oct 2007 02:07:53 +0000 (+0000) Subject: Merge from emacs--rel--22 X-Git-Tag: emacs-pretest-23.0.90~10322 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b2529d56b5126319a1659dc1530d6fc102cc21d6;p=emacs.git Merge from emacs--rel--22 Patches applied: * emacs--rel--22 (patch 116-121) - Update from CVS Revision: emacs@sv.gnu.org/emacs--devo--0--patch-889 --- b2529d56b5126319a1659dc1530d6fc102cc21d6 diff --cc admin/FOR-RELEASE index 1d79682849f,96129ec22d4..8ad2fc3ae50 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@@ -36,59 -34,41 +36,52 @@@ to the hack introduced on 2005-07-01 t ** henman@it.to-be.co.jp 09 Aug 2006: ispell.el problem on Cygwin. (Did we decide that is unreproducible?) - ** set-frame-size for frame without minibuffer loses mode line - Probably a Windows only bug. Reported by Drew Adams on bug-gnu-emacs on - 2007-08-07. It seems that the bug manifests itself only if resizing the - frame makes the menu bar wrap before. On 2007-08-16 Glenn Morris - reported on emacs-devel that he was not able to reproduce the bug on a - GNU/Linux system. - * BUGS WAITING FOR MORE USER INPUT -** undefined reference getopt_long -Report by Daniel C. Bastos on bug-gnu-emacs -from 2007-08-27. Impossible to procede without more input from OP (as -of 20070912, emails are bouncing) or someone else who can reproduce this. -http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg01497.html +** raman@users.sf.net, sep 7: Emacs 23.0.50: Segfaults in alloc.c (batch process) +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg00690.html + +* BUGS -** TAGS buffer generates spurious undo warnings -Waiting for recipe to produce these warnings. -http://lists.gnu.org/archive/html/bug-gnu-emacs/2007-09/msg00070.html +** Document the changes introduced by multi-tty +http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg01639.html +http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg01602.html -** emacs-22.1 with GTK problems (with patches) -Only outstanding issue seems to be whether Solaris 2.6 GTK can be -supported in the absence of recursive mutexes, via a change to -alloc.c, or whether configure should abort. -http://lists.gnu.org/archive/html/bug-gnu-emacs/2007-09/msg00055.html +** Does deleting frames run Lisp code? If so, can we get rid of that? +It is a dangerous design. +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01330.html -* BUGS +** Why were the calls to x_fully_uncatch_errors commented out in eval.c? +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01987.html + +** grep et al should use font-lock to do highlighting, so that they respect font-lock-mode. +"can't turn off font-lock" +http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg00548.html + +** mah@everybody.org, Sep 18: erc causes emacs to hang with multi-tty +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01765.html + +** jbw@macs.hw.ac.uk, Sep 18: before-string property has no effect if display property is empty +http://lists.gnu.org/archive/html/bug-gnu-emacs/2007-09/msg00094.html +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01816.html + +** sdl.web@gmail.com, Sep 24: TLS infinite loop. +http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01720.html -** ams@gnu.org, 9 July: eshell and external commands -http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg00385.html +** herring@lanl.gov: find-func: can no longer find adviced subrs +This ought to work. -** jbw@macs.hw.ac.uk, Sep 19: redisplay goes horribly wrong when a -before-string contains multiple display properties -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg02442.html +** \\{...} produces duplicate entries +http://lists.gnu.org/archive/html/emacs-devel/2007-05/msg00209.html -** jbw@macs.hw.ac.uk, Sep 19: part of display property on before-string - property is not displayed -http://lists.gnu.org/archive/html/emacs-devel/2007-10/msg00138.html +** menu indications of key bindings for remapped commands +http://lists.gnu.org/archive/html/emacs-devel/2007-05/msg01339.html -** lekktu@gmail.com, Oct 11: frame-local variables weirdness -I proposed a patch, which fixed this and seemed right, but the patch -caused other problems. They are being investigated now. +** tromey@redhat.com: two View-mode "quit" bugs +http://lists.gnu.org/archive/html/emacs-devel/2007-07/msg00103.html +** rms: gnus-dired.el is a mistake. Those features should not +be part of Gnus. They should be moved to some other part of Emacs. * DOCUMENTATION diff --cc doc/emacs/ChangeLog index 544cdd8f676,00000000000..9d5e6158f3f mode 100644,000000..100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@@ -1,4966 -1,0 +1,4971 @@@ +2007-10-13 Eric S. Raymond + + * files.texi: Capitalize node names according to convention. + +2007-10-13 Glenn Morris + + * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference. + +2007-10-11 Eric S. Raymond + + * emacs.texi: + * files.texi (Version Systems): Minor fixes to version-control material + suggseted by RMS and Robert J. Chassell. + +2007-10-10 Eric S. Raymond + + * files.texi (Version Systems): + * vc-xtra.texi: + * vc1-xtra.texi: + * vc2-xtra.texi: Merge in changes for new VC with fileset-oriented + operations. Change of terminology from 'version' to `revision'. + Revise text for adequate description of VCSes with monotonic IDs. + * emacs.texi: Change of terminology from 'version' to `revision'. + +2007-10-09 Eric S. Raymond + + * files.texi (Version Systems): Describe newer VCses. + Reorder the descriptions to be chronological. + ++2007-10-09 Richard Stallman ++ ++ * display.texi (Cursor Display): Correct how cursor appears ++ in nonselected windows. ++ +2007-10-04 Nick Roberts + + * building.texi (GDB Graphical Interface): Remove references to gdba + and mention gud-gdb. + +2007-08-31 Eli Zaretskii + + * rmail.texi (Rmail Sorting): Improve indexing. + +2007-10-06 Juri Linkov + + * text.texi (Fill Commands): Document fill-paragraph-or-region. + (Fill Prefix, Format Indentation): Replace fill-paragraph with + fill-paragraph-or-region. + + * basic.texi (Arguments): Replace fill-paragraph with + fill-paragraph-or-region. + +2007-10-06 Eric S. Raymond + + * files.texi: Update the section on version control for 2007 + conditions. None of these changes are new-VC-specific; that + will come later. + +2007-09-15 Glenn Morris + + * calendar.texi (Holidays): Change all instances of `holiday-list' back + to `list-holidays'. + +2007-09-14 Glenn Morris + + * calendar.texi: Update all instances of mark-calendar-holidays, + list-calendar-holidays, list-holidays with the new names. + +2007-09-06 Glenn Morris + + * Move manual sources from man/ to subdirectories of doc/. + Split into the Emacs manual in emacs/, and other manuals in misc/. + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs + manual. + (infodir): New variable. + (info): Use $infodir. + (emacsman): Delete target, not needed any more. + Move all targets that are not the Emacs manual to misc/Makefile.in. + (mostlyclean): Remove `gnustmp'. + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs + manual. + (MULTI_INSTALL_INFO, ENVADD, infodir): Go up one more level. + (emacsman): Delete target, not needed any more. + (clean): Remove all info files but Emacs manual. + Move all targets that are not the Emacs manual to misc/Makefile.in. + * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. + + * Makefile.in (INFOSOURCES): Delete. + (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. + (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs + *.vrs *.toc here... + (maintainer-clean): ...from here. + +2007-09-05 Glenn Morris + + * custom.texi (Safe File Variables): Clarify `!' and risky variables. + +2007-08-29 Glenn Morris + + * emacs.texi (EMACSVER): Increase to 23.0.50. + +2007-08-27 Richard Stallman + + * emacs.texi (Top): Clarify menu item for Glossary. + + * display.texi (Faces): Change secn title. + Clarify not all fonts come from Font Lock. + +2007-08-17 Eli Zaretskii + + * basic.texi (Position Info): Add index entry for face at point. + Mention that character faces are also displayed by "C-u C-x =". + +2007-08-08 Glenn Morris + + * glossary.texi (Glossary): Deprecate `iff'. + +2007-08-07 Chong Yidong + + * files.texi (File Conveniences): Document point motion keys in Image + mode. + +2007-07-27 Glenn Morris + + * emacs.texi (Copying): Include license text from gpl.texi, rather than + in-line. + + * gpl.texi: New file with text of GPL. + * Makefile.in (EMACSSOURCES): Add gpl.texi. + +2007-07-26 Dan Nicolaescu + + * vc2-xtra.texi (Customizing VC): Add GIT and HG. + + * dired.texi (Wdired): Mention C-x C-q key binding. + +2007-07-28 Nick Roberts + + * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". + +2007-07-25 Glenn Morris + + * emacs.texi (Copying): Replace license with GPLv3. + + * Relicense all FSF files to GPLv3 or later. + +2007-07-24 Glenn Morris + + * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work + for some calendars. + +2007-07-23 Nick Roberts + + * screen.texi (Mode Line): Describe new mode-line flag that shows if + default-directory for the current buffer is on a remote machine. + +2007-07-21 Eli Zaretskii + + * vc2-xtra.texi (Customizing VC) : Update the + default value. + +2007-07-21 Richard Stallman + + * files.texi (Why Version Control?): Improve previous change. + +2007-07-18 Eric S. Raymond + + * files.texi (Why Version Control?): New node. + +2007-07-12 Nick Roberts + + * building.texi (Starting GUD): Add xref to this anchor. + +2007-06-24 Karl Berry + + * emacs.texi: new Back-Cover Text. + +2007-06-07 Alan Mackenzie + + * display.texi (Optional Mode Line): Document the new form of + line+column numbers, "(561,2)". + +2007-06-06 Juanma Barranquero + + * maintaining.texi (Create Tags Table): Fix typos. + +2007-06-02 Chong Yidong + + * Version 22.1 released. + +2007-05-07 Karl Berry + + * emacs.texi (EMACSVER): Back to 22. + +2007-05-06 Richard Stallman + + * maintaining.texi (Create Tags Table): Clean up previous change. + +2007-05-05 Francesco Potort,Al(B + + * maintaining.texi (Create Tags Table): Add text about the dangers of + making symbolic links to tags files. + +2007-05-04 Karl Berry + + * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. + +2007-05-03 Karl Berry + + * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. + + * .cvsignore (*.pdf): New entry. + + * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black + for printing. + +2007-05-01 Richard Stallman + + * cmdargs.texi (Initial Options): Under --batch, mention --eval. + +2007-04-28 Glenn Morris + + * ack.texi (Acknowledgments): + * anti.texi (Antinews): + * programs.texi (Program Modes): Restore mention of python.el pending + consideration of legal status. + +2007-04-28 Richard Stallman + + * files.texi (File Names): Fixes to ~ description on MS systems. + +2007-04-26 Glenn Morris + + * emacs.texi (EMACSVER): Increase to 22.1.50. + +2007-04-25 Karl Berry + + * emacs.texi: Improve line breaks on copyright page, + similar layout to lispref, 8.5x11 by default. + + * dired.texi (Image-Dired): Improve line break, fix typo. + +2007-04-24 Chong Yidong + + * programs.texi (Program Modes): + * anti.texi (Antinews): + * ack.texi (Acknowledgments): python.el removed. + +2007-04-23 Chong Yidong + + * display.texi (Highlight Interactively): Correct description of + hi-lock-file-patterns-policy. + + * files.texi (File Archives): Mention self-extracting executables. + +2007-04-23 Eli Zaretskii + + * search.texi (Unconditional Replace, Query Replace): Add xref to + "Replacement and Case". + +2007-04-22 Chong Yidong + + * dired.texi (Image-Dired): Move from Thumbnails node. + * misc.texi (Thumbnails): Node deleted. + * emacs.texi (Top): Update node listing. + + * files.texi (File Conveniences): + * ack.texi (Acknowledgments): Rename "tumme" to "image-dired". + +2007-04-21 Richard Stallman + + * display.texi (Highlight Interactively): Correct previous change. + Clarify doc of hi-lock-find-patterns, and move new features into it. + +2007-04-20 David Koppelman + + * display.texi (Highlight Interactively): Document + hi-lock-file-patterns-policy. + +2007-04-20 Martin Rudalics + + * display.texi (Scrolling): Fix typo. + +2007-04-15 Chong Yidong + + * doclicense.texi: Remove node heading, so that it can be included by + other files. + + * emacs.texi: Insert node heading for GFDL. + +2007-04-14 Eli Zaretskii + + * cmdargs.texi (Colors): Qualify "color of window" index entry by + "command line". + + * display.texi (Faces): Refer to "Creating Frames" for face + and other frame customizations in .emacs. + + * frames.texi (Creating Frames): Mention that face customizations can + be put in .emacs. Add index entries. + +2007-04-12 Richard Stallman + + * glossary.texi (Glossary): Explain `iff'. + +2007-04-11 Karl Berry + + * gnu.texi (Top), + * macos.texi (Mac Font Specs), + * anti.texi (Antinews), + * xresources.texi (Resources), + * misc.texi (Emulation), + * calendar.texi (Daylight Saving), + * dired.texi (Dired and Find), + * rmail.texi (Remote Mailboxes), + * sending.texi (Mail Headers), + * programs.texi (Which Function), + * files.texi (Recover), + * buffers.texi (Uniquify), + * frames.texi (Wheeled Mice), + * killing.texi (Rectangles): Wording to improve breaks in + 8.5x11 format. + * mule.texi (Language Environments): \hbadness=10000 since there's + no way to reword. + * emacs.texi (smallbook): New @set to more easily switch between + smallbook and 8.5x11. + +2007-04-11 Richard Stallman + + * files.texi (File Conveniences): Add xref to Tumme. + Delete text about Thumbnail mode. + +2007-04-09 Alan Mackenzie + + * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its + new name. Insert concept index entries. + +2007-04-08 Chong Yidong + + * display.texi (Standard Faces): Document prefix arg for + list-faces-display. + + * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. + +2007-04-07 Chong Yidong + + * killing.texi (Deletion): Rewrite description of M-\ prefix argument. + + * files.texi (Misc File Ops): Rewrite description of + insert-file-literally. + +2007-03-31 Eli Zaretskii + + * misc.texi (Printing): Postscript -> PostScript. + + * ack.texi (Acknowledgments): Postscript -> PostScript. + + * custom.texi (Init File, Init Non-ASCII): Fix last change. + + * emacs.texi (Top): Fix the menu due to the change in custom.texi + below. + +2007-03-30 Chong Yidong + + * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to + Init Non-ASCII. + (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. + (Init Non-ASCII): New node. + +2007-03-28 YAMAMOTO Mitsuharu + + * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. + +2007-03-12 Glenn Morris + + * calendar.texi, emacs.texi (Daylight Saving): Rename node from + "Daylight Savings". + + * calendar.texi: Replace "daylight savings" with "daylight + saving" in text throughout. + +2007-03-04 Richard Stallman + + * custom.texi (Safe File Variables): Minor correction. + +2007-02-28 Thien-Thi Nguyen + + * rmail.texi (Movemail): Add internal ref. + Don't indent the intro for the PROTO table. + Format PROTO table items with @code. + +2007-02-26 Nick Roberts + + * building.texi: Remove references to bashdb. + +2007-02-19 Juanma Barranquero + + * mule.texi (Language Environments): Update list of supported language + environments. + +2007-02-14 Kim F. Storm + + * building.texi (Grep Searching): Fix lgrep doc. + +2007-02-12 Chong Yidong + + * back.texi: Remove unused file. + +2007-02-05 Francesco Potort,Al(B + + * maintaining.texi (Tag Syntax): Now --members is the default for + etags, not for ctags yet. + +2007-02-03 Eli Zaretskii + + * emacs.texi (Top): Update the top-level menus. Make the detailed menu + headers compliant with Texinfo guidelines and with what texnfo-upd.el + expects. Add comments to prevent people from inadvertently modifying + the key parts needed by `texinfo-multiple-files-update'. + +2007-01-29 Chong Yidong + + * frames.texi (Secondary Selection): Window clicked does not matter + when mouse-yank-at-point is non-nil. + +2007-01-16 Glenn Morris + + * abbrevs.texi (Editing Abbrevs): Describe how to disable a + system abbrev. + +2007-01-11 Richard Stallman + + * msdog.texi (Windows Keyboard): Another small cleanup. + +2007-01-10 Richard Stallman + + * msdog.texi (Windows Keyboard): Yet another try to make + everyone happy with that passage. + +2007-01-05 Richard Stallman + + * anti.texi (Antinews): Mention M-x shell scrolling. + +2007-01-05 Nick Roberts + + * building.texi (Watch Expressions): Describe gdb-max-children. + +2007-01-04 Richard Stallman + + * msdog.texi (Windows Keyboard): Clarify previous change. + +2007-01-02 Richard Stallman + + * custom.texi (Changing a Variable): Minor clarification. + (Specific Customization): customize-customized => customize-unsaved. + + * entering.texi (Entering Emacs): Clean up text about restarting + Emacs for each file. + + * misc.texi (Shell Options): Minor cleanup. + + * msdog.texi (Windows Keyboard): Explain that Windows was incompatible + with Emacs, not vice versa. + + * programs.texi (Symbol Completion): Recommend customizing + window manager. + + * xresources.texi (Resources): Minor fix. + +2007-01-01 Jan Dj,Ad(Brv + + * xresources.texi (Table of Resources): Add scrollBarWidth resource. + +2007-01-01 Richard Stallman + + * commands.texi (User Input): Document keys stolen by window mangers. + +2006-12-31 Richard Stallman + + * custom.texi (Specific Customization): Document customize-option + instead of customize-variable. + +2006-12-31 Kim F. Storm + + * major.texi (Choosing Modes): Document auto-mode-case-fold. + +2006-12-30 Kim F. Storm + + * killing.texi (CUA Bindings): Fix typo. + + * xresources.texi (Table of Resources): Mention grow-only value for + auto-resize-tool-bars. + +2006-12-27 Eli Zaretskii + + * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, + and how to get them back. + +2006-12-26 Richard Stallman + + * calendar.texi (Holidays): Holiday listing is based on current + practice, but DST is not. + +2006-12-25 Richard Stallman + + * emacs.texi (Top): Update subnode menus. + + * mark.texi (Transient Mark): Fix xref. + + * killing.texi (Graphical Kill): Node deleted. + (Killing): Add xref to Cut and Paste. + (CUA Bindings): Update xref. + + * frames.texi (Cut and Paste): New section to hold other nodes. + (Mouse Commands): Node demoted. + (Cut/Paste Other App): Split out from Mouse Commands. + (Word and Line Mouse): Likewise. + (Secondary Selection, Clipboard): Nodes demoted. + +2006-12-24 Kevin Ryde + + * calendar.texi (Holidays): US daylight saving begins second Sunday + in March for 2007 onwards. + (Daylight Savings): Show new US default daylight saving rules, 2nd + Sun in Mar to 1st Sun in Nov, now in cal-dst.el. + +2006-12-23 Chong Yidong + + * calendar.texi (Scroll Calendar): < and > are switched. + +2006-12-23 Kevin Rodgers + + * killing.texi (Deletion): Describe M-\ prefix argument. + +2006-12-23 Richard Stallman + + * search.texi (Regexp Search): Explain why forward and reverse regexp + search are not mirror images. + +2006-12-19 Kim F. Storm + + * major.texi (Choosing Modes): Describe match-function elements for + magic-mode-alist. + +2006-12-18 Eli Zaretskii + + * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys + peculiarities. + +2006-12-18 Richard Stallman + + * abbrevs.texi (Editing Abbrevs): Fix previous change. + +2006-12-17 Alan Mackenzie + + * programs.texi (Left Margin Paren): Remove the bit which says + that CC Mode sets open-paren-in-column-0-is-defun-start to nil. + Discuss some of the issues of setting this option to nil. + +2006-12-17 Glenn Morris + + * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. + +2006-12-16 Eli Zaretskii + + * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. + (Windows Files): `w32-get-true-file-attributes' is only relevant for + NTFS volumes. + (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS + volumes. + +2006-12-15 Eli Zaretskii + + * text.texi (HTML Mode): Fix "C-c TAB". + +2006-12-09 Richard Stallman + + * misc.texi (Invoking emacsclient): Simplify TCP file text. + +2006-12-08 Kevin Rodgers + + * files.texi (Misc File Ops): Document insert-file-literally. + +2006-12-08 Eli Zaretskii + + * cmdargs.texi (Colors): Note that --color is intended for overriding + the terminal defaults, not for normal invocation. + + * misc.texi (Emacs Server): Improve wording. Don't mention the + ``server program''. Add a cross-reference to "Init File" node. + (Invoking emacsclient): Add index entries. Document both short and + long versions of command-line options. Document the -f option. + +2006-12-06 Richard Stallman + + * text.texi (Outline Format): Say to set outline-regexp + and outline-level with major modes and file local variables. + +2006-12-05 Micha,Ak(Bl Cadilhac + + * anti.texi (Antinews): Mention the alternative to + `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. + + * misc.texi (Interactive Shell): Ditto. + +2006-12-04 Eli Zaretskii + + * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. + + * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. + +2006-12-01 Eli Zaretskii + + * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a + colon in the mode line. + + * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. + +2006-11-26 Nick Roberts + + * building.texi (Watch Expressions): Mention SPC for expanding/ + contracting watch expressions. + +2006-11-26 Kim F. Storm + + * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. + +2006-11-26 Nick Roberts + + * building.texi (Debugger Operation): Define text command mode. + Clarify how tooltips work. + (GDB Graphical Interface): Explain how to run in text command mode + more clearly. + +2006-11-25 Juanma Barranquero + + * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. + +2006-11-22 Juanma Barranquero + + * anti.texi (Antinews): Mention --server-file and TCP sockets. + +2006-11-18 Chong Yidong + + * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, + and EMACS is deprecated. + +2006-11-18 Juanma Barranquero + + * makefile.w32-in (emacs.dvi): Remove xresmini.texi. + +2006-11-18 Jan Dj,Ad(Brv + + * Makefile.in (emacs.dvi): Remove xresmini.texi. + + * emacs.texi: Include xresources.texi both for info and dvi. + + * xresources.texi: Merge text from xresmini.texi. + +2006-11-12 Roberto Rodr,Am(Bguez (tiny change) + + * glossary.texi: Fix typos. + +2006-11-06 Richard Stallman + + * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. + + * ack.texi (Acknowledgments): Fix name spelling. + +2006-11-01 Juri Linkov + + * search.texi (Word Search): Document incremental word search. + +2006-10-28 Glenn Morris + + * ack.texi (Acknowledgments): Add cal-html author. + + * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX + Calendar"). Describe new package cal-html. + * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing + Calendar Files." + +2006-10-23 Richard Stallman + + * abbrevs.texi (Expanding Abbrevs): Expansion happens only when + Abbrev mode is enabled. + +2006-10-16 Richard Stallman + + * emacs.texi: Update ISBN. + +2006-10-11 Kim F. Storm + + * emacs.texi (Acknowledgments): Use @dotless{i}. + +2006-10-08 Nick Roberts + + * building.texi (Breakpoints Buffer): Mention catchpoints. + +2006-10-08 Kim F. Storm + + * ack.texi (Acknowledgments): Update. + + * emacs.texi (Acknowledgments): Fix bad @/ form. + +2006-10-05 Kim F. Storm + + * emacs.texi (Acknowledgments): Add more contributors. + +2006-10-03 Richard Stallman + + * emacs.texi (Acknowledgments): Update version and edition. + +2006-10-01 Karl Berry + + * custom.texi (Customization Groups): Page break to keep example buffer + on one page. + +2006-09-30 Karl Berry + + * programs.texi (Basic Indent): @need to improve page break. + * text.texi: Rewording to improve page breaks, and use @LaTeX{}. + +2006-09-29 Glenn Morris + + * calendar.texi (Date Formats): Doc fix for european-calendar-style. + +2006-09-29 Karl Berry + + * windows.texi (Basic Window): Remove forced @break, no longer + desirable. + * frames.texi (Frame Commands), + * mark.texi (Marking Objects): Reword to avoid bad page break. + * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. + +2006-09-19 Richard Stallman + + * frames.texi (Dialog Boxes): Clean up wording: avoid passive, + stick to present tense. + +2006-09-18 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog + to x-gtk-use-old-file-dialog. + (Dialog Boxes): Document x-gtk-file-dialog-help-text. + +2006-09-15 Jay Belanger + + * emacs.texi (GNU GENERAL PUBLIC LICENSE): + Change "Library Public License" to "Lesser Public License" + throughout. Use "yyyy" to represent year. + +2006-09-12 Reiner Steib + + * files.texi (Visiting): Add index entry "open file". + +2006-09-11 Richard Stallman + + * building.texi (Compilation Mode): Clarification. + (Grep Searching): Add xref to Compilation Mode. + +2006-09-08 Richard Stallman + + * search.texi (Search): Ref multi-file search commands here. + (Other Repeating Search): Not here. + +2006-08-28 Richard Stallman + + * windows.texi (Split Window): Update xref. + + * basic.texi (Continuation Lines): Update xref. + + * indent.texi (Tab Stops): Update xref. + + * emacs.texi (Top): Update subnode menu. + + * display.texi (Line Truncation, Displaying Boundaries): New nodes, + split out of Display Custom. + +2006-08-25 Kim F. Storm + + * display.texi (Display Custom): Add variables overline-margin + and x-underline-at-descent-line. + +2006-08-25 Richard Stallman + + * entering.texi (Exiting): Rewrite to give graphical displays + priority over text terminals. + + * search.texi (Incremental Search): Move index entries. + +2006-08-23 Chong Yidong + + * custom.texi (Init File): Reference Find Init to avoid "home + directory" confusion. + +2006-08-22 Nick Roberts + + * building.texi (Other GDB-UI Buffers): Describe how to edit + a value in the locals buffer. + +2006-08-21 Richard Stallman + + * search.texi (Basic Isearch): Add `isearch' index entry. + +2006-08-16 Richard Stallman + + * misc.texi (Saving Emacs Sessions): Clean up wording. + + * mark.texi (Marking Objects): Mention term "select all". + + * emacs.texi (Top): Update subnode menu. + + * help.texi (Help Mode): Move node up in file. + +2006-08-15 Nick Roberts + + * building.texi (Stack Buffer): Explain fringe arrow. + +2006-08-12 Eli Zaretskii + + * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored + on startup. + +2006-08-11 Romain Francoise + + * ack.texi (Acknowledgments): Delete mention to zone-mode.el. + +2006-08-10 Sven Joachim (tiny change) + + * mule.texi (Recognize Coding, Text Coding): Fix typos. + +2006-08-10 Richard Stallman + + * text.texi (Format Faces): Substantial rewrites to deal + with face merging. Empty regions don't count. Clarify + face property inheritance. + +2006-08-08 Romain Francoise + + * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen + . + +2006-08-04 Eli Zaretskii + + * cmdargs.texi (Window Size X) <--geometry>: Only width and height + apply to all frames. + +2006-08-01 Richard Stallman + + * help.texi (Name Help): Add index entries for describe-variable. + +2006-08-01 Nick Roberts + + * building.texi (GDB Graphical Interface): Shorten node names. + (GDB-UI Layout): Use GDB-related. + (Other GDB-UI Buffers): Simplify English. + +2006-07-31 Richard Stallman + + * search.texi (Query Replace): Add xref for Dired's Q command. + +2006-07-31 Nick Roberts + + * building.texi (GDB commands in Fringe): Rename to... + (Source Buffers): ..this and move forward. Describe hollow arrow and + new option gdb-find-source-frame. + +2006-07-29 Richard Stallman + + * dired.texi (Operating on Files): Simplify previous change + and fix Texinfo usage. + +2006-07-29 Eli Zaretskii + + * dired.texi (Operating on Files): Add cross-references. State the + Unix commands that do similar things. + +2006-07-28 Richard Stallman + + * mark.texi (Transient Mark): Clarify that region never disappears + when Transient Mark mode is off, and not when it is on. + +2006-07-27 Richard Stallman + + * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. + +2006-07-24 Richard Stallman + + * xresources.texi (GTK styles): Fix texinfo usage. + + * commands.texi (User Input): Explain why we teach keyboard cmds. + + * xresources.texi, xresmini.texi, search.texi, programs.texi: + * misc.texi, kmacro.texi, killing.texi, glossary.texi: + * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: + * doclicense.texi, display.texi, dired.texi, basic.texi: + * anti.texi, ack.texi: Move periods and commas inside quotes. + +2006-07-22 Eli Zaretskii + + * cmdargs.texi (General Variables): Document EMAIL. + +2006-07-21 Eli Zaretskii + + * frames.texi (Frame Commands): Mention that focus-follows-mouse + doesn't have effect on MS-Windows. + +2006-07-17 Richard Stallman + + * building.texi (Grep Searching): Explain about chaining grep commands. + +2006-07-10 Nick Roberts + + * killing.texi, mini.texi: Fix typos. + +2006-07-09 Chong Yidong + + * misc.texi (Invoking emacsclient): Document behavior when emacsclient + is invoked for multiple files. + +2006-07-08 Eli Zaretskii + + * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the + on-line manual for the rest of this node. + (Windows Mouse) : Include + unconditionally. + (Windows Processes) : Include unconditionally. + Improve wording. + (Windows Printing): Improve wording. + (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the + rest of this node. + +2006-07-05 Thien-Thi Nguyen + + * building.texi (Lisp Eval): Throughout, replace eval-current-buffer + with eval-buffer. + +2006-07-05 Nick Roberts + + * mule.texi (Coding Systems, Specify Coding): Link descriptions + of character translation. + +2006-07-04 Nick Roberts + + * rmail.texi (Remote Mailboxes): Add missing @code keyword. + +2006-07-03 Karl Berry + + * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by + not-too-underfull hboxes in the TeX output. + * abbrevs.texi, buffers.texi, building.texi, calendar.texi, + * cmdargs.texi, custom.texi, dired.texi, macos.texi, + * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, + * sending.texi, text.texi: Fix overfull/underfull boxes. + +2006-07-03 Romain Francoise + + * m-x.texi (M-x): Fix. + +2006-07-03 Richard Stallman + + * search.texi (Other Repeating Search): filename -> file name. + + * misc.texi (Narrowing): Minor cleanups. + + * files.texi (Visiting): filename -> file name. + + * emacs.texi (Top): Update subnode menus. + + * mule.texi (Coding Systems): Move char translation stuff here. + (Specify Coding, Output Coding): New nodes, out of Recognize Coding. + (Recognize Coding): Substantial local rewrites. + (International): Update menu. + + * display.texi (Auto Scrolling): New node, broken out of Scrolling. + (Scrolling): Substantial local rewrites. + (Display): Update menu and intro. + + * dired.texi: filename -> file name. + + * custom.texi (Safe File Variables): Texinfo usage fix. + +2006-07-03 Ted Zlatanov + + * help.texi, m-x.texi: Lots of cleanups. + +2006-06-30 Eli Zaretskii + + * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) + (Windows Processes, Windows Misc): Shorten the printed version by + selectively conditioning less important portions by @ifnottex. + +2006-06-27 Richard Stallman + + * mini.texi (Minibuffer File): Minor cleanup. + +2006-06-25 Nick Roberts + + * frames.texi (XTerm Mouse): Rename to... + (Text-Only Mouse): ...this. Mention t-mouse-mode. + + * emacs.texi (Top): Use new node name. + +2006-06-24 Eli Zaretskii + + * emacs.texi (Top): Update the detailed menu according to changes in + msdog.texi. + + * msdog.texi (Windows Keyboard): New section. + (Windows Mouse): New section. + (Windows System Menu): Remove section (text merged with "Windows + Keyboard"). + (Windows Misc): New section. + + * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. + + * msdog.texi (ls in Lisp): New section. + + * files.texi (Visiting): Document case-insensitive wildcard matching + under find-file-wildcards. + +2006-06-16 YAMAMOTO Mitsuharu + + * macos.texi (Mac Input): Add description of mac-function-modifier. + Now Unicode keyboard layouts work. + +2006-06-10 Richard Stallman + + * mule.texi (Recognize Coding): Clarify previous change. + +2006-06-09 Kenichi Handa + + * mule.texi (Recognize Coding): Describe the convention of "CODING!" + notation. + +2006-06-07 Kevin Ryde + + * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main + manual for @ifnottex, but in emacs-extra for @iftex. + + * cmdargs.texi (General Variables): Fix smtpmail xref. + +2006-05-29 Stefan Monnier + + * programs.texi (Comment Commands): + * custom.texi (Specifying File Variables): + Use ;; instead of ;;; to better follow coding conventions. + +2006-06-07 Nick Roberts + + * building.texi (Watch Expressions): Move node to end. + (GDB Graphical Interface): Move description of clicks in fringe... + (GDB commands in the Fringe): ...to here. New node. + +2006-06-05 Romain Francoise + + * xresmini.texi (GTK resources): Fix various typos. + +2006-06-05 Nick Roberts + + * building.texi (GDB Graphical Interface): Update bindings. + (Commands of GUD): Add gud-print. Remove gud-run. + Restate availability more generally. + +2006-06-03 Ted Zlatanov + + * mini.texi: Lots of cleanups. + +2006-06-01 Luc Teirlinck + + * misc.texi (Shell History Copying): Update descriptions of `C-c RET' + and Mouse-2. + +2006-06-01 Jan Dj,Ad(Brv + + * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. + +2006-05-31 Richard Stallman + + * basic.texi (Moving Point): Fix previous change. + +2006-05-29 Jan Dj,Ad(Brv + + * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. + +2006-05-28 Ted Zlatanov + + * basic.texi: Many simplifications and improvements in wording. + +2006-05-26 Nick Roberts + + * anti.texi (Antinews): Create a node for gdb-ui. + +2006-05-22 Reiner Steib + + * frames.texi (Menu Bars, Tool Bars): Add index entries. + +2006-05-20 Richard Stallman + + * dired.texi (Dired Navigation): dired-goto-file is now j. + +2006-05-20 Eli Zaretskii + + * mule.texi (Coding Systems): Mention the undecided-* coding systems + and their aliases. + + * msdog.texi (Windows Printing): Mention non-support of plain text + printing with some el-cheapo printers, and suggest a workaround. + +2006-05-20 Kevin Ryde + + * text.texi (TeX Print): tex-dvi-view-command has a default value, + remove the bit saying you must set it. + +2006-05-19 Luc Teirlinck + + * trouble.texi (Checklist): + * text.texi (Text, Auto Fill, Text Mode): + * search.texi (Nonincremental Search): + * rmail.texi (Rmail Labels): + * mule.texi (Input Methods, Multibyte Conversion): + * misc.texi (Gnus, Where to Look, PostScript): + * maintaining.texi (Create Tags Table): + * indent.texi (Indentation Commands): + * fixit.texi (Spelling): + * emacs.texi (Copying): + * custom.texi (Init File): ifinfo -> ifnottex. + +2006-05-17 Richard Stallman + + * files.texi (Diff Mode): Mention C-x `. + +2006-05-08 Richard Stallman + + * custom.texi (Disabling): Textual cleanups. + +2006-05-12 Glenn Morris + + * calendar.texi (Displaying the Diary, Format of Diary File): + Refer to diary-view-entries, diary-list-entries, + diary-show-all-entries rather than obsolete aliases. + +2006-05-12 Eli Zaretskii + + * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) + (Displaying the Diary, Special Diary Entries, Importing Diary): + * building.texi (Compilation Shell): + * buffers.texi (Several Buffers) [iftex]: Replace @xref's to + emacs-xtra with @inforef's. + + * files.texi (Visiting): Fix wording. + + * mule.texi (Coding Systems, Text Coding): More indexing. + Mention that C-x RET f can set eol conversion. + +2006-05-07 Jan Dj,Ad(Brv + + * xresmini.texi (GTK resources): Insert GTK description. + + * xresources.texi (GTK resources): metafont should be menufont. + +2006-05-06 Michael Albinus + + * mini.texi (Completion Options): Completion of remote files' + method, user name and host name is active only in partial + completion mode. + +2006-05-06 Eli Zaretskii + + * makefile.w32-in (emacs.dvi): + * Makefile.in (emacs.dvi): Add xresmini.texi. + + * xresmini.texi (Table of Resources): Remove xref to non-existent + node "LessTif Resources". + + * msdog.texi (Microsoft Windows): + * calendar.texi (Calendar/Diary, Displaying the Diary) + (Special Diary Entries, Importing Diary, Holidays): + * programs.texi (Program Modes): + * text.texi (Text): + * buffers.texi (Several Buffers): + * files.texi (Comparing Files): Fix cross-references to emacs-xtra. + +2006-05-06 Eli Zaretskii + + The following changes merge the emacs-xtra manual into the main + manual, but only for on-line version of the manual. + + * vc2-xtra.texi (Version Backups, Local Version Control) + (Making Snapshots, Change Logs and VC, Version Headers) + (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for + on-line manual. + + * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's + for on-line manual. + + * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) + (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) + (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's + for on-line manual. + + * fortran-xtra.texi (Fortran, Fortran Autofill) + (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's + for on-line manual. + + * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: + Conditional xref's for on-line manual. + + * emerge-xtra.texi (Emerge, Overview of Emerge) + (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line + manual. + + * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. + (EMACS_XTRA): New variable, lists the new *-xtra.texi files. + (EMACSSOURCES): Use EMACS_XTRA. + (../info/emacs-xtra): Remove. + (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. + + * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. + (EMACS_XTRA): New variable, lists the new *-xtra.texi files. + (EMACSSOURCES): Use EMACS_XTRA. + ($(infodir)/emacs-xtra): Remove. + (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. + + * trouble.texi (Quitting): + * text.texi (Text): + * programs.texi (Program Modes): + * msdog.texi (Microsoft Windows): + * frames.texi (Frames): + * files.texi (Backup, Version Control, VC Concepts) + (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) + (Registering, VC Status, VC Undo, Multi-User Branching) + (Comparing Files): + * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) + (Displaying the Diary, Special Diary Entries, Importing Diary): + * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by + conditional xref's, depending on @iftex/@ifnottex. + + * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for + "MS-DOS". @include msdog-xtra.texi. + + * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". + [ifnottex]: @include fortran-xtra.texi. + + * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries + for vc-xtra.texi subsections. + (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. + (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. + + * sending.texi (Sending Mail): A @node line without explicit Prev, + Next, and Up links. + + * abbrevs.texi (Abbrevs): A @node line without explicit Prev, + Next, and Up links. + + * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" + and its sections. @include picture-xtra.texi. + + * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for + "Emerge". + (List Tags) [ifnottex]: @include emerge-xtra.texi. + + * cal-xtra.texi (Daylight Savings): Remove this node: it is an + exact duplicate of its name-sake in calendar.texi. + + * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for + "Advanced Calendar/Diary Usage". + (Time Intervals) [ifnottex]: @include cal-xtra.texi. + + * dired.texi (Subdirectories in Dired) [ifnottex]: @include + dired-xtra.texi. + (Dired) [ifnottex]: Add menu entry for "Subdir Switches". + + * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. + (Files) [ifnottex]: Add menu entry for Autorevert. + + * emacs-xtra.texi (Introduction): Reword to make consistent with + printed version only. + : Remove the body of all chapters and move them to the + new *-xtra.texi files. Use @raisesections and @lowersections to + convert sections to chapters etc. + + * msdog-xtra.texi: + * fortran-xtra.texi: + * vc-xtra.texi: + * vc1-xtra.texi: + * vc2-xtra.texi: + * emerge-xtra.texi: + * cal-xtra.texi: + * dired-xtra.texi: + * arevert-xtra.texi: New files, with text from respective chapters + of emacs-xtra.texi. Convert each @chapter into @section, @section + into @subsection, etc. + + * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references + updated. + + * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft + Windows". All references updated. + +2006-05-06 YAMAMOTO Mitsuharu + + * macos.texi (Mac Input): Mention input from Character Palette. + (Mac Font Specs): Fix typo. + +2006-05-05 Richard Stallman + + * files.texi (Diff Mode): Minor cleanup. + +2006-05-05 Karl Berry + + * emacs.texi: Call @fonttextsize 10, inside @tex to avoid + errors from the current release of makeinfo (4.8). + * help.texi (Library Keywords): Change widest word in multitable + template from `emulations' to `convenience'. (Not sure if this is + related to the font change.) + +2006-05-05 Eli Zaretskii + + * files.texi (File Names): Add a footnote about limited support of + ~USER on MS-Windows. + + * cmdargs.texi (Initial Options): Add a footnote about limited + support of ~USER on MS-Windows. + +2006-05-03 Richard Stallman + + * files.texi (Diff Mode): Node moved here. + (Comparing Files): Delete what duplicates new node. + (Files): Put Diff Mode in menu. + + * misc.texi (Diff Mode): Moved to files.texi. + + * emacs.texi (Top): Update menu for Diff Mode. + + * trouble.texi (Emergency Escape): Simplify. + + * emacs.texi (Top): Minor clarification. + +2006-05-03 Teodor Zlatanov + + * commands.texi, entering.texi, screen.texi: Many simplifications. + +2006-05-03 Richard Stallman + + * commands.texi (Text Characters): Delete paragraph about unibyte + non-ASCII printing chars. + + * killing.texi (Killing): Say "graphical displays". + * display.texi: Say "graphical displays". + + * cmdargs.texi (Misc X): Say "graphical displays". + +2006-05-01 Richard Stallman + + * emacs.texi (Top): Add Diff Mode to menu. + +2006-05-01 Aaron S. Hawley + + * misc.texi (Diff Mode): New node. + +2006-05-01 YAMAMOTO Mitsuharu + + * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. + (Mac Environment Variables): Shorten example line. + (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. + +2006-05-01 Nick Roberts + + * building.texi (GUD Customization): Describe cases %d and %c. + Update description for %e. + +2006-04-30 Glenn Morris + + * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. + +2006-04-29 Dan Nicolaescu + + * custom.texi (Examining): Update C-h v output example. + +2006-04-29 Kim F. Storm + + * building.texi (Grep Searching): Add lgrep and rgrep. + +2006-04-23 Richard Stallman + + * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. + + * xresmini.texi: New file. + + * xresources.texi (Face Resources): Split table into font resources + and the rest. Combine similar attributes for brevity. + +2006-04-21 Eli Zaretskii + + * emacs-xtra.texi (MS-DOS File Names): Remove section about + backslashes and case-insensitivity in file names (moved to the + main manual). + (MS-DOS Printing): Move most of the text to the main manual. + + * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): + New nodes. + (Windows Processes, Windows System Menu): Add index entries and + fix wording. + +2006-04-18 J.D. Smith + + * misc.texi (Shell Ring): Add notes on saved input when + navigating off the end of the history list. + +2006-04-18 Chong Yidong + + * misc.texi (Shell Options): Correct default value of + comint-scroll-show-maximum-output. + +2006-04-18 Nick Roberts + + * building.texi (Watch Expressions): Update. + +2006-04-12 Richard Stallman + + * search.texi: Clean up previous change. + +2006-04-12 Eli Zaretskii + + * search.texi (Regexp Backslash, Regexp Replace): Add index + entries for ``back reference'' and mention the term itself in the + text. + +2006-04-11 Richard Stallman + + * custom.texi (Safe File Variables): + Document enable-local-variables = :safe. + +2006-04-11 Karl Berry + + * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) + (Remote Repositories, Version Backups, Local Version Control) + (Snapshots, Making and Using Snapshots, Snapshot Caveats) + (Miscellaneous Commands and Features of VC, Change Logs and VC) + (Renaming VC Work Files and Master Files) + (Inserting Version Control Headers, Customizing VC, General Options) + (Options for RCS and SCCS, Options specific for CVS): Move all + these nodes to emacs-xtra.texi, for brevity. + * cmdargs.texi, files.texi: Change cross-references. + +2006-04-11 J.D. Smith + + * files.texi (Old Versions): Update description of vc-annotate's + use of color to indicate date ranges. + +2006-04-09 Kevin Ryde + + * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, + put info and printed manual names the right way around. + +2006-04-09 Karl Berry + + * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to + emacs-xtra.texi, leaving only MS Windows information. + * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, + * msdog.texi, mule.texi, trouble.texi: Change cross-references and + node names. + + * emacs.texi: Move @summarycontents and @contents to the beginning + of the file. + +2006-04-08 Kevin Ryde + + * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. + +2006-04-07 Richard Stallman + + * programs.texi (Comments, Comment Commands, Options for Comments) + (Multi-Line Comments): "Align", not "indent". + (Basic Indent): C-j deletes trailing whitespace before the newline. + +2006-04-06 Richard Stallman + + * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. + +2006-04-06 Eli Zaretskii + + * killing.texi (Rectangles): Add index entry for marking a rectangle. + +2006-04-05 Richard Stallman + + * emacs.texi (Top): Update subnode menu. + + * trouble.texi (Unasked-for Search): Node deleted. + (Lossage): Delete from menu. + +2006-04-04 Richard Stallman + + * trouble.texi: Various cleanups. + (Checklist): Don't bother saying how to snail a bug report. + (Emergency Escape): Much rewriting. + (After a Crash): Rename the core dump immediately. + (Total Frustration): Call it a psychotherapist. + (Bug Criteria): Avoid "illegal instruction". + (Sending Patches): We always put the contributor's name in. + + * misc.texi (Thumbnails): Minor correction. + +2006-04-03 Richard Stallman + + * misc.texi (Thumbnails): Minor cleanup. + +2006-04-02 Karl Berry + + * sending.texi (Mail Sending): pxref to Top needs five args. + + * texinfo.tex: Update to current version (2006-03-21.13). + +2006-03-31 Richard Stallman + + * emacs.texi (Top): Update subnode menu. + + * help.texi (Help Mode): Cleanup. + + * dired.texi: Many cleanups. + (Dired Deletion): Describe dired-recursive-deletes. + (Operating on Files): dired-create-directory moved. + (Misc Dired Features): Move to here. + (Tumme): Node moved to misc.texi. + + * custom.texi: Many cleanups. + (Minor Modes): Don't mention ISO Accents Mode. + (Examining): Update C-h v output example. + (Hooks): Add index and xref for add-hook. + (Locals): Delete list of vars that are always per-buffer. Rearrange. + (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. + + * misc.texi: Many cleanups. + (beginning): Add to summary of topics. + (Shell): Put eshell xref at the end. Remove eshell from table. + (Thumbnails): New node. + +2006-03-28 Eli Zaretskii + + * files.texi (File Name Cache): Make it clear that the cache is + not persistent. + +2006-03-25 Karl Berry + + * emacs-xtra.texi, emacs.texi, gnu.texi: + (1) use @copyright{} instead of (C) in typeset text; + (2) do not indent copyright year list (or anything else). + +2006-03-21 Juanma Barranquero + + * files.texi (VC Dired Mode): Remove misplaced brackets. + +2006-03-21 Andre Spiegel + + * files.texi: Various updates and clarifications in the VC chapter. + +2006-03-19 Luc Teirlinck + + * help.texi (Help Mode): Document "C-c C-c". + +2006-03-16 Luc Teirlinck + + * emacs-xtra.texi (Top): Avoid ugly continuation line in + menu in the standalone Info reader. + +2006-03-15 Chong Yidong + + * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, + moved here from Emacs manual. + + * programs.texi (Fortran): Section moved to emacs-xtra. + (Program Modes): Xref to Fortran in emacs-xtra. + + * maintaining.texi (Emerge): Move to emacs-xtra. + * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. + + * picture.texi: File deleted. + * Makefile.in: + * makefile.w32-in: Remove picture.texi. + + * text.texi (Text): Xref to Picture Mode in emacs-xtra. + * abbrevs.texi (Abbrevs): + * sending.texi (Sending Mail): Picture node removed. + + * emacs.texi (Top): Update node listings. + +2006-03-12 Richard Stallman + + * calendar.texi: Various cleanups. + +2006-03-11 Luc Teirlinck + + * search.texi (Regexps): Use @samp for regexp that is not in Lisp + syntax. + +2006-03-08 Luc Teirlinck + + * search.texi (Regexps): More accurately describe which characters + are special in which situations. Recommend _not_ to quote `]' or + `-' when they are not special. + +2006-02-28 Andre Spiegel + + * files.texi (Old Versions): Clarify operation of C-x v =. + +2006-02-21 Nick Roberts + + * building.texi (Watch Expressions): Update and describe + gdb-speedbar-auto-raise. + +2006-02-19 Richard M. Stallman + + * emacs.texi: Use @smallbook. + (Top): Update ref to Emacs paper, delete ref to Cookbook. + Update subnode menu. + + * building.texi (Lisp Interaction): Minor addition. + +2006-02-18 Nick Roberts + + * building.texi (Watch Expressions): Update and be more precise. + +2006-02-15 Francesco Potort,Al(B + + * maintaining.texi (Create Tags Table): Explain why the + exception when etags writes to files under the /dev tree. + +2006-02-14 Richard M. Stallman + + * custom.texi (Safe File Variables): Lots of clarification. + Renamed from Unsafe File Variables. + +2006-02-14 Chong Yidong + + * custom.texi (Unsafe File Variables): File variable confirmation + assumed denied in batch mode. + +2006-02-14 Richard M. Stallman + + * building.texi (GDB User Interface Layout): Don't say `inferior' + for program being debugged. + +2006-02-15 Nick Roberts + + * building.texi (GDB Graphical Interface): + Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. + +2006-02-13 Chong Yidong + + * custom.texi (Specifying File Variables, Unsafe File Variables): + New nodes, split from File Variables. Document new file local + variable behavior. + +2006-02-13 YAMAMOTO Mitsuharu + + * display.texi (Standard Faces): + * files.texi (Visiting): + * frames.texi (Clipboard): + * glossary.texi (Glossary) : + * xresources.texi (X Resources): Mention Mac OS port. + +2006-02-12 Richard M. Stallman + + * building.texi (Building): Clarify topic in intro. + + * maintaining.texi (Maintaining): Change title; clarify topic. + Delete duplicate index entries. + + * building.texi (Other GDB User Interface Buffers): Clarifications. + + * text.texi (Cell Commands): Clarifications. + + * programs.texi (Defuns): Delete duplicate explanation of + left-margin paren convention. + (Hungry Delete): Minor cleanup. + +2006-02-11 Mathias Dahl + + * dired.texi (Tumme): More tumme documentation. + +2006-02-11 Alan Mackenzie + + * programs.texi ("Hungry Delete"): Correct the appellation of the + backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. + +2006-02-11 Mathias Dahl + + * dired.texi (Tumme): Fix small bug. + +2006-02-10 YAMAMOTO Mitsuharu + + * macos.texi (Mac International): Rename "fontset-mac" to + "fontset-standard". + +2006-02-09 Mathias Dahl + + * dired.texi (Tumme): Basic documentation for Tumme added. + +2006-02-07 Luc Teirlinck + + * mule.texi (International): + * programs.texi (Basic Indent): Fix typos. + + * custom.texi (Minor Modes): + * display.texi (Text Display): + * commands.texi (Text Characters): Update xrefs. + +2006-02-07 Richard M. Stallman + + * emacs.texi (Top): Update subnode menu. + Update info on old Emacs papers. + (Intro): "Graphical display", not window system. + + * xresources.texi (GTK styles): Minor clarifications. + + * trouble.texi: "Graphical display", not window system. + (Stuck Recursive): Minor clarification. + + * text.texi: Minor clarifications. + (Sentences): Explain why two-space convention is better. + Explain sentence-end-without-period here. + (Fill Commands): Not here. + (Refill): Node moved down. + (Filling): Update menu. + (Table Creation, Cell Justification, Column Commands): Clarify. + + * sending.texi: Minor clarifications. + + * search.texi (Regexp Backslash): Clarification. + + * rmail.texi: Minor cleanups. + (Rmail): Delete digression about `rmail-mode'. + (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. + (Rmail Files): Mention C-u M-x rmail. + (Rmail Reply): Mention References. + (Rmail Display): Mention rmail-nonignored-headers. + + * programs.texi: Minor cleanups. + (Comment Commands): Mention momentary Transient Mark mode. + (Matching): Be more specific about customizing show-paren-mode. + (Info Lookup): Don't list the modes that support C-h S. + Just say what it does in an unsupported mode. + (Man Page): Delete excessive info on customizing woman. + (Motion in C): Don't mention c-for/backward-into-nomenclature. + + * abbrevs.texi: Minor clarifications. + (Dabbrev Customization): Talk about "dynamic abbrev expansion", + not "dynamic abbrevs" as if they were a kind of abbrev. + + * picture.texi (Picture): Minor cleanup. + + * mule.texi (Communication Coding): Say "other applications". + (Fontsets): Not specific to X. Add xref to X Resources. + (Unibyte Mode): Rename from Single-Byte Character Support. + "Graphical display", not window system. + (International): Update menu. + + * maintaining.texi (Format of ChangeLog): + New node, split out from ChangeLog. + (ChangeLog): Clarifications in the remaining text. + (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. + (Find Tag): Add @w. + (Tags Search): Explain tag table order here. Simplify grep ref. + (List Tags): tags-tag-face is a variable, not a face. + (Emerge): Cleanups. + + * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. + (Keyboard Macros): Avoid "the user". + + * killing.texi: "Graphical display", not window system. + + * help.texi (Help Echo): "Graphical display", not window system. + + * glossary.texi: Say "you", not "the user". Say "graphical display". + + * frames.texi: Minor cleanups. "Graphical display", not window system. + + * files.texi (Visiting): Make drag-and-drop not X-specific. + + * custom.texi: Minor cleanups. "Graphical display", not window system. + + * cmdargs.texi: Minor cleanups. + + * building.texi (Compilation): Move and split kill-compilation para. + Add para about multiple compilers. + (Compilation Mode): Commands also available in grep mode and others. + Mention C-u C-x ` more tutorially. Clarify C-x `. + (Compilation Shell): Clarify. Put Bash example first. + (Grep Searching): Minor cleanups; add @w. + (Debuggers): Minor cleanups. + (Starting GUD): Make GDB xgraphical mode issue clearer. + (Debugger Operation): Lots of clarifications including + GDB tooltip side-effect issue. + (Commands of GUD): Clarify. + (GUD Customization): Add bashdb-mode-hook. + (GDB Graphical Interface): Rewrite for clarity. + (GDB User Interface Layout): Rewrite for clarity. + (Stack Buffer, Watch Expressions): Likewise. + (Other GDB User Interface Buffers): Cleanups. + (Lisp Libraries, External Lisp): Cleanup. + + * basic.texi (Position Info): "Graphical displays", rather than + window systems. + + * anti.texi: Minor cleanup. + +2006-02-03 Eli Zaretskii + + * custom.texi (Init File, Find Init): Add cross-references to + where $HOME is described. + +2006-02-01 Luc Teirlinck + + * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it + is not inside the @table. + + * emacs.texi (Top): Correct node name. + + * files.texi (File Names): Fix @xref. + (Reverting): Fix typo. + + * mule.texi (International): Correct node name. + + * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. + +2006-02-01 Richard M. Stallman + + * emacs.texi (Top): Update subnode menu. + + * mule.texi: Minor clarifications. + Reduce the specific references to X Windows. + Refer to "graphical" terminals, rather than window systems. + (Text Coding): Rename from Specify Coding. + (Communication Coding, File Name Coding, Terminal Coding): + New nodes split out from Text Coding. + + * kmacro.texi: Minor clarifications. + (Keyboard Macro Ring): Comment out some excessive commands. + (Basic Keyboard Macro): Split up the table, putting part in each node. + + * major.texi: Minor clarifications. + + * misc.texi (Single Shell, Interactive Shell): Fix xrefs. + + * windows.texi: Minor clarifications. + (Change Window): Don't describe mode-line mouse cmds here. + Add xref to Mode Line Mouse. + + * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. + + * macos.texi (Mac International): Fix xref. + + * indent.texi: Minor clarifications. + + * frames.texi: Minor clarifications. + Reduce the specific references to X Windows. + Refer to "graphical" terminals, rather than window systems. + (Frame Parameters): Don't mention commands like + set-foreground-color. Just say to customize a face. + (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. + + * files.texi: Minor clarifications. + (Numbered Backups): New node, split out from Backup Names. + + * display.texi (Font Lock): C mode no longer depends on (-in-col-0. + + * cmdargs.texi (General Variables): Fix xref. + + * buffers.texi: Minor clarifications. + +2006-01-31 Richard M. Stallman + + * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): + Nodes moved to top. + + * display.texi: Minor clarifications. + (Display): Rearrange menu. + (Standard Faces): Mention query-replace face. + (Faces): Simplify. + (Font Lock): Simplify face customization info. + (Highlight Changes): Node merged into Highlight Interactively. + (Highlight Interactively): Much rewriting and cleanup. + (Optional Mode Line): Narrowed line number not good for goto-line. + Simplify face customization advice. + (Text Display): Mention use of escape-glyph face. + Move ctl-arrow and tab-width here. + (Display Custom): Move no-redraw-on-reenter to end of node. + + * search.texi: Minor clarifications. + (Isearch Scroll): Simplify. + (Other Repeating Search): Document multi-occur-in-matching-buffers. + + * regs.texi (Registers): Mention bookmarks here. + + * mark.texi: Minor clarifications. + (Selective Undo): Node deleted. + + * m-x.texi: Minor clarifications. + + * killing.texi: Minor clarifications. + Refer to "graphical" terminals, rather than window systems. + + * help.texi: Clarifications. + (Help): Don't describe C-h F and C-h K here. + (Key Help): Describe C-h K here. + (Name Help): Mention Emacs Lisp Intro. + Describe C-h F here. + (Misc Help): Mention C-h F and C-h K only briefly. + + * fixit.texi (Undo): New node, mostly copied from basic.texi. + Selective undo text merged in. + (Spelling): Mention Aspell along with Ispell. + + * emacs.texi (Top): Update subnode menus. + + * basic.texi (Basic Undo): Rename from Undo. Most of text + moved to new Undo node. + +2006-01-29 Chong Yidong + + * basic.texi (Continuation Lines, Inserting Text): + Mention longlines mode. + +2006-01-29 Richard M. Stallman + + * screen.texi: Minor cleaups. + (Screen): Clean up the intro paragraphs. + (Mode Line): Lots of rewriting. Handle frame-name better. + eol-mnemonic-... vars moved out. + + * emacs.texi (Top): Change menu item for MS-DOS node. + Update subnode menu. + + * msdog.texi (MS-DOS): Rewrite intro to explain how this + chapter relates to Windows. Title changed. + + * mini.texi: Minor cleanups. + + * mark.texi (Selective Undo): New node, text moved from basic.texi. + (Mark): Put it in the menu. + + * entering.texi: Minor cleanups. + + * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. + (Intro): Refer to "graphical" terminals, rather than X. + + * display.texi (Display Custom): Add xref to Variables. + (Optional Mode Line): eol-mnemonic-... vars moved here. + + * commands.texi: Minor cleanups. Refer to "graphical" terminals, + rather than X. + + * basic.texi: Minor cleanups. + (Undo): selective-undo moved. + +2006-01-25 Luc Teirlinck + + * anti.texi (Antinews): Various corrections and additions. + +2006-01-23 Juri Linkov + + * custom.texi (Easy Customization, Customization Groups) + (Browsing Custom): Mention links along with buttons. + +2006-01-21 Eli Zaretskii + + * text.texi (TeX Print): Use @key for TAB. + + * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. + +2006-01-15 Sven Joachim (tiny change) + + * files.texi (File Aliases): Don't claim that usually separate + buffers are created for two file names that name the same data. + Mention additional situations where different names mean the same + file on disk. + +2006-01-19 Richard M. Stallman + + * killing.texi (Deletion): Upcase @key argument. + + * custom.texi (Custom Themes): Minor cleanup. + + * programs.texi (Hungry Delete): Upcase @key argument. + +2006-01-16 Juri Linkov + + * display.texi (Standard Faces): Add `mode-line-buffer-id'. + Move `mode-line-highlight' before `mode-line-buffer-id'. + +2006-01-14 Richard M. Stallman + + * basic.texi (Inserting Text): Minor cleanup. + +2006-01-11 Luc Teirlinck + + * custom.texi (Changing a Variable, Face Customization): + Update for changes in Custom menus. + +2006-01-05 YAMAMOTO Mitsuharu + + * macos.texi (Mac International): Undo last change. + +2006-01-02 Chong Yidong + + * custom.texi (Custom Themes): Describe the new + customize-create-theme interface. + +2005-12-30 Juri Linkov + + * basic.texi (Position Info): Update example. + +2005-12-27 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. + +2005-12-24 Chong Yidong + + * custom.texi (Custom Themes): `load-theme' always loads. + +2005-12-23 Juri Linkov + + * display.texi (Highlight Interactively): Use double space to + separate sentences. Replace C-p with M-p, and C-n with M-n. + +2005-12-22 Richard M. Stallman + + * custom.texi (Easy Customization and subnodes): + Replace "active field" with "button". + Use "user option" only for variables. + Use "setting" for variable-or-face. + +2005-12-22 Luc Teirlinck + + * buffers.texi (Select Buffer): Change order in table to make + "Similar" refer to the correct item. + (Indirect Buffers): Minor rewording. + +2005-12-20 Juri Linkov + + * files.texi (VC Status): Put P and N near p and n. + +2005-12-19 Richard M. Stallman + + * programs.texi (Electric C): Delete the info about newline control. + (Other C Commands): Minor cleanup. + (Left Margin Paren): Minor cleanup. + +2005-12-19 Luc Teirlinck + + * custom.texi (Easy Customization): Add "Browsing Custom" to menu. + (Customization Groups): Delete text moved to "Browsing Custom". + (Browsing Custom): New node. + (Specific Customization): Clarify which commands only work for + loaded options. + +2005-12-18 Bill Wohler + + * frames.texi (Tool Bars): Shorten text of previous change. + +2005-12-18 Aaron S. Hawley + + * files.texi (VC Status): Document log-view mode. + +2005-12-18 Bill Wohler + + * frames.texi (Tool Bars): Mention that you can turn off tool bars + permanently via the customize interface. + +2005-12-16 Ralf Angeli + + * killing.texi (Killing by Lines): Document `kill-whole-line' + function. + +2005-12-16 L$,1 q(Brentey K,Aa(Broly + + * buffers.texi (Select Buffer): Change `prev-buffer' to + `previous-buffer'. Indicate that these functions use a frame + local buffer list. + +2005-12-12 Richard M. Stallman + + * custom.texi (Easy Customization): Change menu comment. + (Prefix Keymaps): Fix spelling of Control-X-prefix. + + * help.texi (Apropos): Rewrite. Talk about "apropos patterns". + (Help): Among the Apropos commands, describe only C-h a here. + +2005-12-11 Richard M. Stallman + + * programs.texi (Options for Comments): Comment-end starts with space. + + * glossary.texi (Glossary): Minor cleanup. + + * files.texi (Old Versions): Use @table. + +2005-12-10 David Koppelman + + * display.texi (Highlight Interactively): Include + global-hi-lock-mode. Add miscellaneous details and elaborations. + +2005-12-09 Richard M. Stallman + + * display.texi (Font Lock): Delete the Global FL menu item. + +2005-12-09 Luc Teirlinck + + * custom.texi (Minibuffer Maps): Mention the maps for file name + completion. + +2005-12-09 Kim F. Storm + + * killing.texi (CUA Bindings): Describe how to use C-x and C-c as + prefix keys even when mark is active. Decribe that RET moves + cursor to next corner in rectangle; clarify insert around rectangle. + +2005-12-08 Luc Teirlinck + + * custom.texi (Customization): Use xref to elisp manual for + non-TeX output. + (Minor Modes): Update. + (Customization Groups, Changing a Variable, Face Customization): + Update for new appearance of Custom buffers. + (Changing a Variable): `custom-buffer-done-function' has been + replaced by `custom-buffer-done-kill'. + (Specific Customization): In the `customize-group' buffer, a + subgroup's contents are not "hidden". They are not included at + all. They have no [Show] button. + (Mouse Buttons): Add pxref to description of mouse event lists in + Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. + (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of + ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). + +2005-12-08 Richard M. Stallman + + * mini.texi (Completion Commands, Completion): + In file name input, SPC does not do completion. + +2005-12-08 Nick Roberts + + * building.texi (GDB Graphical Interface): Explain screen size + setting. + (Other GDB User Interface Buffers): Describe features specific to + GDB 6.4. + +2005-12-01 Nick Roberts + + * building.texi (GDB User Interface Layout): Describe how to + kill associated buffers. + (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. + (Watch Expressions): Be more precise. + (Other GDB User Interface Buffers): Describe how to change a + register value. + +2005-11-24 YAMAMOTO Mitsuharu + + * macos.texi (Mac Input): Remove description of + mac-command-key-is-meta. Add descriptions of + mac-control-modifier, mac-command-modifier, and + mac-option-modifier. + (Mac International): Fix description of conversion of clipboard data. + (Mac Font Specs): Add example of font customization by face attributes. + +2005-11-22 Nick Roberts + + * building.texi (Watch Expressions): Expand description. + (Other GDB User Interface Buffers): Describe local map for + gud-watch. + +2005-11-21 Chong Yidong + + * display.texi (Font Lock): Font lock is enabled by default now. + +2005-11-20 Juri Linkov + + * basic.texi (Position Info): Update examples of the output. + Remove the fact that examples are produced in the TeXinfo buffer, + because in the Info reader users will get a different output from + `C-x ='. + + * building.texi (Compilation Mode): Remove paragraph duplicated + from the node `Compilation'. Add `compilation-skip-threshold'. + + * display.texi (Font Lock): Suggest more user-friendly method of + finding all Font Lock faces (M-x customize-group RET font-lock-faces). + +2005-11-18 Richard M. Stallman + + * files.texi (Registering): Mention @@ in mode line. + + * mini.texi (Minibuffer File): Clarify previous change. Add @findex. + +2005-11-08 Aaron S. Hawley + + * files.texi (Renaming and VC): Some back-ends don't + handle renaming. + +2005-11-17 Juri Linkov + + * emacs.texi (Top): + * display.texi (Highlight Interactively): Put this font-lock based + mode near Font Lock node. + +2005-11-16 Chong Yidong + + * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs + icons. + +2005-11-12 Kim F. Storm + + * help.texi (Help): Fix C-h a entry. Add C-h d entry. + (Help Summary): Add C-h d and C-h e. + (Apropos): Clarify that all apropos commands may search for either + list of words or a regexp. Add C-h d for apropos-documentation. + Describe apropos-documentation-sort-by-scores user option. + +2005-11-09 Luc Teirlinck + + * killing.texi (CUA Bindings): Add @section. + +2005-11-10 Kim F. Storm + + * emacs.texi (Top): Add CUA Bindings entry to menu. + + * killing.texi (CUA Bindings): New node. Moved here from + misc.texi and extended with info on rectangle commands and + rectangle highlighting, interface to registers, and the global + mark feature. + + * misc.texi (Emulation): Move CUA bindings item to killing.texi. + + * regs.texi: Prev link points to CUA Bindings node. + +2005-11-07 Luc Teirlinck + + * help.texi (Help Echo): By default, help echos are only shown on + mouse-over, not on point-over. + +2005-11-04 J,Ai(Br,At(Bme Marant + + * misc.texi (Shell Mode): Describe how to activate password echoing. + +2005-11-04 Romain Francoise + + * mark.texi (Mark Ring): Fix typo. + +2005-11-03 Richard M. Stallman + + * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. + +2005-11-01 Bill Wohler + + * help.texi (Help Mode): Fix typo. + +2005-11-01 Nick Roberts + + * building.texi (Other GDB User Interface Buffers): Describe + the command gdb-use-inferior-io-buffer. + +2005-10-31 Romain Francoise + + * files.texi (Compressed Files): Fix typo. + + * buffers.texi (Misc Buffer): Downcase `*shell*'. + + * windows.texi (Force Same Window): Likewise. + +2005-10-30 Bill Wohler + + * help.texi (Help Mode): URLs viewed with browse-url. + +2005-10-31 Nick Roberts + + * building.texi (GDB Graphical Interface): Don't reference + gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until + must stay in same frame. + +2005-10-29 Chong Yidong + + * custom.texi (Init File): Document ~/.emacs.d/init.el. + + * anti.texi (Antinews): Likewise. + +2005-10-28 Bill Wohler + + * help.texi (Help): Help mode now creates hyperlinks for URLs. + +2005-10-28 Richard M. Stallman + + * files.texi (Visiting): Explain how to enter ? in a file name. + + * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. + +2005-10-25 Nick Roberts + + * building.texi (GDB Graphical Interface): Describe + gdb-mouse-until. + +2005-10-23 Richard M. Stallman + + * custom.texi (Init File): Recommend when to use site-start.el. + +2005-10-21 Juri Linkov + + * custom.texi (Examining): Mention accessing the old variable + value via M-n in set-variable. + +2005-10-18 Romain Francoise + + * files.texi (Version Systems): Capitalize GNU. + +2005-10-18 Nick Roberts + + * building.texi (Compilation Mode): Remove redundant paragraph. + (Watch Expressions): Remove paragraph to reflect code change. + +2005-10-16 Richard M. Stallman + + * building.texi (Compilation Mode, Compilation): Clarified. + +2005-10-15 Richard M. Stallman + + * misc.texi (Saving Emacs Sessions): Mention savehist library. + +2005-10-13 Kenichi Handa + + * basic.texi (Position Info): Fix previous change. + +2005-10-12 Jan Dj,Ad(Brv + + * cmdargs.texi (Icons X): Fix typo. + +2005-10-12 Kenichi Handa + + * basic.texi (Position Info): Describe the case that Emacs shows + "part of display ...". + +2005-10-10 Jan Dj,Ad(Brv + + * cmdargs.texi (Icons X): -nb => -nbi. + +2005-10-10 Chong Yidong + + * frames.texi (Speedbar): A couple more clarifications. + +2005-10-11 Nick Roberts + + * building.texi (GDB User Interface Layout): Improve diagram. + (Watch Expressions): Explain how to make speedbar global. + (Other GDB User Interface Buffers): Make references more precise. + +2005-10-09 Richard M. Stallman + + * frames.texi (Speedbar): Clarify the text. + +2005-10-09 Chong Yidong + + * frames.texi (Speedbar): Add information on keybindings, + dismissing the speedbar, and buffer display mode. Link to + speedbar manual. + +2005-10-09 Jan Dj,Ad(Brv + + * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type, + added -nb, --no-bitmap-icon. + +2005-10-07 Nick Roberts + + * building.texi (GDB Graphical Interface): Add variables and + functions to indices. Be more precise. + +2005-10-03 Jan Dj,Ad(Brv + + * frames.texi (Drag and Drop): Remove the x- from + x-dnd-open-file-other-window and xdnd-protocol-alist. + +2005-09-30 Romain Francoise + + * mini.texi (Minibuffer): The default value now appears before the + colon in minibuffer prompts. + +2005-09-25 Richard M. Stallman + + * search.texi (Regexp Search): Doc search-whitespace-regexp. + +2005-09-20 Emanuele Giaquinta (tiny change) + + * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. + +2005-09-21 YAMAMOTO Mitsuharu + + * emacs.texi (Top): Update submenus from macos.texi. + + * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. + (Mac OS): Update feature support status. + (Mac Input): List supported input scripts. Remove description + about `mac-keyboard-text-encoding'. Mention mouse button + emulation and related variables. + (Mac International): Mention Central European and Cyrillic + support. Now `keyboard-coding-system' is dynamically changed. + Add description about coding system for selection. Add + description about language environment. + (Mac Environment Variables): Mention + `~/.MacOSX/environment.plist'. Give example of command line + arguments. Add Preferences support. + (Mac Directories): Explicitly state that this node is for Mac OS + Classic only. + (Mac Font Specs): Mention specification for scalable fonts. List + supported charsets. Add preferred way of creating fontsets. Add + description about `mac-allow-anti-aliasing'. + (Mac Functions): Add descriptions about `mac-set-file-creator', + `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', + and `mac-get-preference'. + +2005-09-16 Romain Francoise + + Update all files to specify GFDL version 1.2. + + * doclicense.texi (GNU Free Documentation License): Update to + version 1.2. + +2005-09-15 Richard M. Stallman + + * buffers.texi (List Buffers): Fix xref. + + * rmail.texi (Rmail Basics): Fix xref. + + * emacs.texi (Top): Update subnode menus. + + * files.texi (Saving Commands): New node, broken out of Saving. + (Customize Save): New node, broken out of Saving. + Clarify effect of write-region-inhibit-fsync. + (Misc File Ops): Say write-region-inhibit-fsync affects write-region. + +2005-09-14 Romain Francoise + + * files.texi (Saving): Mention write-region-inhibit-fsync. + +2005-09-05 Chong Yidong + + * custom.texi (Custom Themes): New node. + +2005-09-03 Richard M. Stallman + + * search.texi (Search Case): Mention vars that control + case-fold-search for various operations. + +2005-08-22 Juri Linkov + + * display.texi (Standard Faces): Merge the text from + `(elisp)Standard Faces' into this node. + +2005-08-18 Luc Teirlinck + + * emacs.texi (Top): Delete menu item for deleted node + Keyboard Translations. + +2005-08-18 Richard M. Stallman + + * trouble.texi (Unasked-for Search): + Delete xref to Keyboard Translations. + + * glossary.texi (Glossary): Delete xref. + + * custom.texi (Minor Modes): Say that the list here is not complete. + (Keyboard Translations): Node deleted. + (Disabling): Delete xref to it. + (Customization Groups): Fix Custom buffer example. + (Hooks): Mention remove-hooks. + +2005-08-17 Luc Teirlinck + + * building.texi (GDB Graphical Interface): Improve filling of menu + item. + +2005-08-18 Nick Roberts + + * building.texi (GDB Graphical Interface): Use better node names. + +2005-08-14 Richard M. Stallman + + * text.texi (Sentences): Fix xref. + +2005-08-14 Juri Linkov + + * building.texi (Compilation, Grep Searching): Move grep command + headings from `Compilation' to `Grep Searching'. + + * dired.texi (Dired and Find): + * maintaining.texi (Tags Search): Replace grep xref to + `Compilation' node with `Grep Searching'. + + * files.texi (Comparing Files): Replace xref to `Compilation' with + `Compilation Mode'. + +2005-08-13 Alan Mackenzie + + * search.texi (Non-ASCII Isearch): Correct a typo. + (Replacement Commands): Mention query-replace key binding. + +2005-08-11 Richard M. Stallman + + * programs.texi (Options for Comments): Fix xref. + + * search.texi (Regexp Backslash, Regexp Example): New nodes split + out of Regexps. + +2005-08-09 Juri Linkov + + * building.texi (Compilation): Use `itemx' instead of `item'. + (Grep Searching): Simplify phrase. + + * display.texi (Standard Faces): Describe vertical-border on + window systems. + + * windows.texi (Split Window): Simplify phrase and mention + vertical-border face. + +2005-08-09 Richard M. Stallman + + * files.texi (Comparing Files): Clarify compare-windows. + + * calendar.texi (Scroll Calendar): Document < and > in calendar. + +2005-08-06 Eli Zaretskii + + * mule.texi (Coding Systems): Rephrase the paragraph about + codepages: no need for "M-x codepage-setup" anymore, except on + MS-DOS. + + * msdog.texi (MS-DOS and MULE): Clarify that this section is for + the MS-DOS port only. + +2005-07-30 Eli Zaretskii + + * makefile.w32-in (info): Don't run multi-install-info.bat. + ($(infodir)/dir): New target, produced by running + multi-install-info.bat. + +2005-07-22 Eli Zaretskii + + * files.texi (Quoted File Names): Add index entry. + +2005-07-19 Juri Linkov + + * files.texi (Comparing Files): Mention resync for `compare-windows'. + +2005-07-18 Juri Linkov + + * custom.texi (Easy Customization): + * files.texi (Old Versions): + * frames.texi (Wheeled Mice): + * mule.texi (Specify Coding): + * text.texi (Cell Justification): + * trouble.texi (After a Crash): + * xresources.texi (GTK styles): + Delete duplicate duplicate words. + +2005-07-17 Richard M. Stallman + + * frames.texi (Creating Frames): Fix foreground color example. + + * custom.texi (Init Examples): Clean up text about conditionals. + +2005-07-16 Richard M. Stallman + + * mini.texi (Completion Commands): Fix command name for ?. + +2005-07-16 Eli Zaretskii + + * display.texi (Standard Faces): Explain that customization of + `menu' face has no effect on w32 and with GTK. Add + cross-references. + + * cmdargs.texi (General Variables): Clarify the default location + of $HOME on w32 systems. + +2005-07-15 Jason Rumney + + * cmdargs.texi (General Variables): Default HOME on MS Windows has + changed. + +2005-07-08 Kenichi Handa + + * mule.texi (Recognize Coding): Recommend + revert-buffer-with-coding-system instead of revert-buffer. + +2005-07-07 Richard M. Stallman + + * anti.texi (Antinews): Mention mode-line-inverse-video. + + * files.texi (Saving): Minor correction about C-x C-w. + + * display.texi (Display Custom): Don't mention mode-line-inverse-video. + +2005-07-07 Luc Teirlinck + + * search.texi (Isearch Scroll): Add example of using the + `isearch-scroll' property. + (Slow Isearch): Reference anchor for `baud-rate' instead of entire + `Display Custom' node. + (Regexp Replace): Put text that requires Emacs Lisp knowledge last + and de-emphasize it. + (Other Repeating Search): `occur' currently can not correctly + handle multiline matches. Correct, clarify and update description + of `flush-lines' and `keep-lines'. + + * display.texi (Display Custom): Add anchor for `baud-rate'. + +2005-07-07 Richard M. Stallman + + * gnu.texi: Update where to get GNU status; add refs for how to help. + Add footnotes 6 and 7. + +2005-07-04 Lute Kamstra + + Update FSF's address in GPL notices. + + * doclicense.texi (GNU Free Documentation License): + * trouble.texi (Checklist): Update FSF's address. + +2005-06-24 Richard M. Stallman + + * display.texi (Text Display): Change index entries. + +2005-06-24 Eli Zaretskii + + * makefile.w32-in (MAKEINFO): Use --force. + (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in + Makefile.in. + +2005-06-23 Richard M. Stallman + + * anti.texi (Antinews): Renamed show-nonbreak-escape to + nobreak-char-display. + + * emacs.texi (Top): Update detailed node listing. + + * display.texi (Text Display): Renamed show-nonbreak-escape + to nobreak-char-display and no-break-space to nobreak-space. + (Standard Faces): Split up the list of standard faces + and put it in a separate node. Add nobreak-space and + escape-glyph. + +2005-06-23 Lute Kamstra + + * mule.texi (Select Input Method): Fix typo. + +2005-06-23 Kenichi Handa + + * mule.texi (International): List all supported scripts. Adjust + text for that leim is now included in the normal Emacs + distribution. + (Language Environments): List all language environments. + Intlfonts contains fonts for most supported scripts, not all.. + (Select Input Method): Refer to C-u C-x = to see how to type to + input a specifc character. + (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. + +2005-06-23 Juanma Barranquero + + * building.texi (Grep Searching): Texinfo usage fix. + +2005-06-22 Miles Bader + + * display.texi (Faces): Change `vertical-divider' to `vertical-border'. + +2005-06-20 Miles Bader + + * display.texi (Faces): Add `vertical-divider'. + +2005-06-17 Richard M. Stallman + + * text.texi (Adaptive Fill): Minor clarification. + +2005-06-10 Lute Kamstra + + * emacs.texi (Top): Correct version number. + * anti.texi (Antinews): Correct version number. Use EMACSVER to + refer to the current version of Emacs. + +2005-06-08 Luc Teirlinck + + * files.texi (Log Buffer): Document when there can be more than + one file to be committed. + +2005-06-08 Juri Linkov + + * display.texi (Faces): Add `shadow' face. + +2005-06-07 Masatake YAMATO + + * display.texi (Faces): Write about mode-line-highlight. + +2005-06-06 Richard M. Stallman + + * misc.texi (Printing Package): Explain how to initialize + printing package. + + * cmdargs.texi (Action Arguments): Clarify directory default for -l. + +2005-06-05 Chong Yidong + + * emacs.texi: Rename Hardcopy to Printing. + Make PostScript and PostScript Variables subnodes of it. + + * misc.texi (Printing): Rename node from Hardcopy. + Mention menu bar options. + Move PostScript and PostScript Variables to submenu. + (Printing package): New node. + + * mark.texi (Using Region): Change Hardcopy xref to Printing. + + * dired.texi (Operating on Files): Likewise. + + * calendar.texi (Displaying the Diary): Likewise. + + * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. + + * glossary.texi (Glossary): Likewise. + + * frames.texi (Mode Line Mouse): Mention mode-line-highlight + effect. + +2005-06-04 Richard M. Stallman + + * trouble.texi (After a Crash): Polish previous change. + +2005-05-30 Noah Friedman + + * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a + recovery mechanism. + +2005-05-28 Nick Roberts + + * building.texi (Other Buffers): SPC toggles display of + floating point registers. + +2005-05-27 Nick Roberts + + * files.texi (Log Buffer): Merge in description of Log Edit + mode from pcl-cvs.texi. + +2005-05-26 Richard M. Stallman + + * building.texi (Lisp Eval): C-M-x with arg runs Edebug. + +2005-05-24 Luc Teirlinck + + * fixit.texi (Spelling): Delete confusing sentence; flyspell is + not enabled by default. + When not on a word, `ispell-word' by default checks the word + before point. + +2005-05-24 Nick Roberts + + * building.texi (Debugger Operation): Simplify last sentence. + +2005-05-23 Lute Kamstra + + * emacs.texi: Update FSF's address throughout. + (Preface): Use @cite. + (Distrib): Add cross reference to the node "Copying". Mention the + FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of + printed manuals. + (Intro): Use @xref for the Emacs Lisp Intro. + +2005-05-18 Luc Teirlinck + + * buffers.texi (Select Buffer): Document `C-u M-g M-g'. + + * basic.texi (Moving Point): Mention default for `goto-line'. + + * programs.texi (Lisp Doc): Eldoc mode shows only the first line + of a variable's docstring. + +2005-05-18 Lute Kamstra + + * maintaining.texi (Overview of Emerge): Add cross reference. + Remove duplication. + + * emacs.texi (Top): Update to the current structure of the manual. + * misc.texi (Emacs Server): Add menu description. + * files.texi (Saving): Fix menu. + * custom.texi (Customization): Fix menu. + * mule.texi (International): Fix menu. + * kmacro.texi (Keyboard Macros): Fix menu. + +2005-05-16 Luc Teirlinck + + * display.texi: Various minor changes. + (Faces): Delete text that is repeated in the next section. + +2005-05-16 Nick Roberts + + * building.texi (Debugger Operation): Mention GUD tooltips are + disabled with GDB in text command mode. + +2005-05-16 Nick Roberts + + * building.texi: Replace toolbar with "tool bar" for consistency. + (Compilation Mode): Describe compilation-context-lines + and use of arrow in compilation buffer. + (Debugger Operation): Replace help text with variable's value. + + * frames.texi (Tooltips): Replace toolbar with "tool bar" for + consistency. + +2005-05-15 Luc Teirlinck + + * major.texi (Choosing Modes): normal-mode processes the -*- line. + Add xref. + +2005-05-14 Luc Teirlinck + + * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. + (Position Info): Delete discussion of `goto-line'. It is already + described in `Moving point'. + + * mini.texi (Completion Commands): Correct reference. + (Completion Options): Fix typo. + + * killing.texi (Deletion): Complete description of `C-x C-o'. + +2005-05-10 Richard M. Stallman + + * building.texi (Compilation): Clarify recompile's directory choice. + + * frames.texi (Tooltips): Cleanups. + + * basic.texi (Arguments): Fix punctuation. + +2005-05-09 Luc Teirlinck + + * screen.texi (Menu Bar): The up and down (not left and right) + arrow keys move through a keyboard menu. + +2005-05-08 Luc Teirlinck + + * basic.texi: Various typo and grammar fixes. + (Moving Point): C-a now runs move-beginning-of-line. + +2005-05-08 Nick Roberts + + * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. + + * frames.texi (Tooltips): Describe help tooltips and GUD tooltips + as different animals. + +2005-05-07 Luc Teirlinck + + * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. + Correct index entry. + +2005-05-07 Nick Roberts + + * building.texi (Debugger Operation): Update to reflect changes + in GUD tooltips. + +2005-04-30 Richard M. Stallman + + * files.texi (Compressed Files): Auto Compression normally enabled. + + * building.texi (Debugger Operation): Clarify previous change. + +2005-04-28 Nick Roberts + + * building.texi (Debugger Operation): Add description for + GUD tooltips when program is not running. + +2005-04-26 Luc Teirlinck + + * misc.texi (Shell): Add `Shell Prompts' to menu. + (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' + description. Delete remarks moved to new node. + (Shell Prompts): New node. + (History References): Replace remarks moved to `Shell Prompts' + with xref to that node. + (Remote Host): Clarify how to specify the terminal type when + logging in to a different machine. + +2005-04-26 Richard M. Stallman + + * emacs.texi (Top): Update submenus from files.texi. + + * files.texi (Filesets): Clarify previous change. + + * dired.texi (Misc Dired Features): Clarify previous change. + +2005-04-25 Chong Yidong + + * ack.texi (Acknowledgments): Delete info about iso-acc.el. + + * dired.texi (Misc Dired Features): Document + dired-compare-directories. + + * files.texi (Filesets): New node. + (File Conveniences): Document Image mode. + + * text.texi (TeX Print): Document tex-compile. + +2005-04-25 Luc Teirlinck + + * frames.texi (Tooltips): Tooltip mode is enabled by default. + Delete redundant reference to tooltip Custom group. It is + referred too again in the next paragraph. + +2005-04-24 Richard M. Stallman + + * ack.texi: Delete info about lazy-lock.el and fast-lock.el. + +2005-04-19 Kim F. Storm + + * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. + +2005-04-18 Lars Hansen + + * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now + turns off desktop-save-mode. + +2005-04-17 Luc Teirlinck + + * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled + by default in terminals compatible with xterm. Mention that + xterm-mouse-mode is a minor mode and put in pxref to Minor Modes + node. + +2005-04-12 Luc Teirlinck + + * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. + +2005-04-12 Jan Dj,Ad(Brv + + * xresources.texi (Table of Resources): Add cursorBlink. + +2005-04-11 Luc Teirlinck + + * rmail.texi (Rmail Summary Edit): Explain numeric arguments to + `d', `C-d' and `u'. + +2005-04-11 Richard M. Stallman + + * cmdargs.texi (Initial Options): -Q is now --quick, and does less. + (Misc X): Add -D, --basic-display. + + * maintaining.texi (Change Log): Correct the description of + the example. + + * major.texi (Choosing Modes): Document magic-mode-alist. + +2005-04-10 Luc Teirlinck + + * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. + (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. + (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. + (Rmail Output): Clarify which statements apply to `o', `C-o' and + `w', respectively. + (Rmail Labels): Mention `l'. + (Rmail Attributes): Correct pxref. Mention `stored' attribute. + (Rmail Summary Edit): Describe `j' and RET. + +2005-04-10 Jan Dj,Ad(Brv + + * xresources.texi (Lucid Resources): Add fontSet resource. + +2005-04-09 Luc Teirlinck + + * display.texi (Useless Whitespace): `indicate-unused-lines' is + now called `indicate-empty-lines'. + +2005-04-06 Kim F. Storm + + * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. + +2005-04-04 Luc Teirlinck + + * dired.texi (Dired Visiting): `dired-view-command-alist' has been + deleted. + (Marks vs Flags): Add some convenient key bindings. + (Hiding Subdirectories): Delete redundant and inaccurate sentence. + (Misc Dired Features): Correct and expand description of `w' command. + + * frames.texi (XTerm Mouse): Delete apparently false info. + The GNU/Linux console currently does not appear to support + `xterm-mouse-mode'. + +2005-04-03 Glenn Morris + + * calendar.texi (Diary): Mention shell utility `calendar'. + +2005-04-01 Richard M. Stallman + + * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. + +2005-04-01 Lute Kamstra + + * maintaining.texi (Change Log): add-change-log-entry uses + add-log-mailing-address. + +2005-03-31 Luc Teirlinck + + * files.texi (Reverting): Move `auto-revert-check-vc-info' to + `VC Mode Line' and put in an xref to that node. + (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify + its description. + +2005-03-31 Paul Eggert + + * calendar.texi (Calendar Systems): Say that the Persian calendar + implemented here is the arithmetical one championed by Birashk. + +2005-03-30 Glenn Morris + + * programs.texi (Fortran Motion): Fix previous change. + +2005-03-29 Richard M. Stallman + + * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. + +2005-03-29 Chong Yidong + + * text.texi (Refill): Refer to Long Lines Mode. + (Longlines): New node. + (Auto Fill): Don't index "word wrap" here. + (Filling): Add Longlines to menu. + +2005-03-29 Richard M. Stallman + + * xresources.texi: Minor fixes. + + * misc.texi (Emacs Server): Fix Texinfo usage. + + * emacs.texi (Top): Don't use a real section heading for + "Detailed Node Listing". Fake it instead. + + * basic.texi (Position Info): Minor cleanup. + + * mule.texi (Input Methods): Minor cleanup. + +2005-03-29 Glenn Morris + + * programs.texi (ForIndent Vars): `fortran-if-indent' does other + constructs as well. + (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. + +2005-03-29 Kenichi Handa + + * mule.texi (Input Methods): Refer to the command C-u C-x =. + + * basic.texi (Position Info): Update the description about the + command C-u C-x =. + +2005-03-28 Richard M. Stallman + + * emacs.texi (Top): Use @section for the detailed node listing. + + * calendar.texi: Minor fixes to previous change. + + * programs.texi (Fortran): Small fixes to previous changes. + + * emacs.texi (Top): Update list of subnodes of Dired. + Likewise for building.texi. + + * files.texi (File Conveniences): Delete Auto Image File mode. + +2005-03-28 Chong Yidong + + * building.texi (Flymake): New node. + + * custom.texi (Function Keys): Document kp- event types and + keypad-setup package. + + * dired.texi (Wdired): New node. + + * files.texi (File Conveniences): Reorder entries. + Explain how to turn on Auto-image-file mode. + Document Thumbs mode. + + * mule.texi (Specify Coding): Document recode-region and + recode-file-name. + + * programs.texi (Program Modes): Add Conf mode and DNS mode. + +2005-03-27 Luc Teirlinck + + * commands.texi (Keys): M-o is now a prefix key. + +2005-03-27 Glenn Morris + + * programs.texi: Reformat and update copyright years. + (Fortran): Update section. + +2005-03-26 Luc Teirlinck + + * files.texi: Several small changes in addition to: + (Visiting): Change xref for Dialog Boxes to ref. + (Version Headers): Replace references to obsolete var + `vc-header-alist' with `vc-BACKEND-header'. + (Customizing VC): Update value of `vc-handled-backends'. + +2005-03-26 Glenn Morris + + * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; + move here from Emacs Lisp Reference Manual. + * calendar.texi (Calendar/Diary, Diary Commands) + (Special Diary Entries, Importing Diary): Change some xrefs to + point to emacs-xtra rather than elisp. + + * emacs-xtra.texi (Calendar Customizing): + Move view-diary-entries-initially, view-calendar-holidays-initially, + mark-diary-entries-in-calendar, mark-holidays-in-calendar to main + Emacs Manual. + (Appt Customizing): Merge entire section into main Emacs Manual. + * calendar.texi (Holidays): Move view-calendar-holidays-initially, + mark-holidays-in-calendar here from emacs-xtra. + (Displaying the Diary): Move view-diary-entries-initially, + mark-diary-entries-in-calendar here from emacs-xtra. + (Appointments): Move appt-display-mode-line, + appt-display-duration, appt-disp-window-function, + appt-delete-window-function here from emacs-xtra. + + * calendar.texi: Update and reformat copyright. + Change all @xrefs to the non-printing emacs-xtra to @inforefs. + (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. + (Diary): Refer to `diary-file' rather than ~/diary. + (Diary Commands): Rename node to "Displaying the Diary". + * emacs.texi (Top): Rename "Diary Commands" section. + * misc.texi (Hardcopy): Rename "Diary Commands" xref. + +2005-03-26 Eli Zaretskii + + * misc.texi (Emacs Server): Fix the command for setting + server-name. Add an xref to Invoking emacsclient. + + * help.texi (Help Summary): Clarify when "C-h ." will do something + nontrivial. + (Apropos): Add cindex entry for apropos-sort-by-scores. + + * display.texi (Text Display): Add index entries for how no-break + characters are displayed. + +2005-03-26 Eli Zaretskii + + * files.texi (Visiting): Fix cross-references introduced with the + last change. + + * xresources.texi (GTK resources): Fix last change. + +2005-03-25 Chong Yidong + + * xresources.texi (X Resources): GTK options documented too. + (Resources): Clarify meaning of program name. + (Table of Resources): Add visualClass. + (GTK resources): Rewrite. + (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. + + * display.texi (Text Display): Mention non-breaking spaces. + + * files.texi (Reverting): Document auto-revert-check-vc-info. + + * frames.texi (Mouse Commands): Document + x-mouse-click-focus-ignore-position and mouse-drag-copy-region. + + * help.texi (Help Summary): Add `C-h .'. + (Apropos): Apropos accepts a list of search terms. + Document apropos-sort-by-scores. + (Help Echo): Document display-local-help. + + * misc.texi (Emacs Server): Document server-name. + (Invoking emacsclient): Document -s option for server names. + + * text.texi (Outline Visibility): Introduce "current heading + line" (commands can be called with point on a body line). + Re-order table to follow the sequence of discussion. + hide-body won't hide lines before first header line. + (TeX Mode): Add DocTeX mode. + +2005-03-24 Richard M. Stallman + + * mule.texi (Single-Byte Character Support): Delete mention + of iso-acc.el and iso-transl.el. + +2005-03-23 Lute Kamstra + + * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. + +2005-03-23 Richard M. Stallman + + * search.texi: Delete explicit node pointers. + (Incremental Search): New menu. + (Basic Isearch, Repeat Isearch, Error in Isearch) + (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) + (Slow Isearch): New subnodes. + (Configuring Scrolling): Node deleted. + (Search Case): Doc default-case-fold-search. + (Regexp Replace): Move replace-regexp doc here. + + * rmail.texi (Movemail): Put commas inside closequotes. + + * picture.texi (Insert in Picture): Document C-c arrow combos. + (Basic Picture): Clarify erasure. + + * display.texi (Font Lock): Put commas inside closequotes. + + * cmdargs.texi (General Variables): Put commas inside closequotes. + +2005-03-23 Nick Roberts + + * building.texi (Stack Buffer): Mention reverse contrast for + *selected* frame (might not be current frame). + +2005-03-21 Richard M. Stallman + + * building.texi (Starting GUD): Add bashdb. + +2005-03-20 Chong Yidong + + * basic.texi (Moving Point): Add M-g M-g binding. + (Undo): Document undo-only. + (Position Info): Document M-g M-g and C-u M-g M-g. + + * building.texi (Building): Put Grep Searching after Compilation + Shell. + (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. + Document next-error-highlight. + (Grep Searching): Document grep-highlight-matches. + (Lisp Eval): Typing C-x C-e twice prints integers specially. + + * calendar.texi (Importing Diary): Rename node from iCalendar. + Document diary-from-outlook. + + * dired.texi (Misc Dired Features): Rename node from Misc Dired + Commands. + Mention effect of X drag and drop on Dired buffers. + + * files.texi (Visiting): Document large-file-warning-threshold. + Move paragraph on file-selection dialog. + Mention visiting files using X drag and drop. + (Reverting): Mention using Auto-Revert mode to tail files. + Document auto-revert-tail-mode. + (Version Systems): Minor correction. + (Comparing Files): Diff-mode is no longer based on Compilation + mode. + Document compare-ignore-whitespace. + (Misc File Ops): Explain passing a directory to rename-file. + Likewise for copy-file and make-symbolic-link. + + * frames.texi (Wheeled Mice): Mouse wheel support on by default. + Document mouse-wheel-progressive speed. + + * help.texi (Misc Help): Document numeric argument for C-h i. + Correctly explain the effect of just C-u as argument. + + * killing.texi (Deletion): Document numeric argument for + just-one-space. + + * mini.texi (Completion): Completion acts on text before point. + + * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. + (Emulation): CUA mode replaces pc-bindings-mode, + pc-selection-mode, and s-region. + + * mule.texi (Input Methods): Leim is now built-in. + (Select Input Method): Document quail-show-key. + (Specify Coding): Document revert-buffer-with-coding-system. + + * programs.texi (Fortran Motion): Document f90-next-statement, + f90-previous-statement, f90-next-block, f90-previous-block, + f90-end-of-block, and f90-beginning-of-block. + + * text.texi (Format Faces): Replace old M-g key prefix with M-o. + + * emacs.texi (Acknowledgments): Updated. + + * anti.texi: Total rewrite. + +2005-03-19 Chong Yidong + + * ack.texi (Acknowledgments): Update. + +2005-03-19 Eli Zaretskii + + * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update + copyright years. + +2005-03-14 Nick Roberts + + * building.texi (Commands of GUD): Move paragraph on setting + breakpoints with mouse to the GDB Graphical Interface node. + +2005-03-07 Richard M. Stallman + + * misc.texi (Single Shell, Shell Options): Fix previous change. + + * building.texi (Debugger Operation): Update GUD tooltip enable info. + +2005-03-06 Richard M. Stallman + + * building.texi (Starting GUD): Don't explain text vs graphical + GDB here. Just mention it and xref. + Delete "just one debugger process". + (Debugger Operation): Move GUD tooltip info here. + (GUD Tooltips): Node deleted. + (GDB Graphical Interface): Explain the two GDB modes here. + + * sending.texi (Sending Mail): Minor cleanup. + (Mail Aliases): Explain quoting conventions. + Update key rebinding example. + (Header Editing): C-M-i is like M-TAB. + (Mail Mode Misc): mail-attach-file does not do MIME. + + * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes + that really belongs here. + (Remote Mailboxes): Text moved to Rmail Inbox. + (Rmail Display): Mention Mouse-1. + (Movemail): Clarify two movemail versions. + Clarify rmail-movemail-program. + + * misc.texi (Single Shell): Replace uudecode example with gpg example. + Document async shell commands. + (Shell History): Clarify. + (Shell Ring): Mention C-UP an C-DOWN. + (Shell Options): Add comint-prompt-read-only. + (Invoking emacsclient): Set EDITOR to run Emacs. + (Sorting): No need to explain what region is. + (Saving Emacs Sessions): Fix typo. + (Recursive Edit): Fix punctuation. + (Emulation): Don't mention "PC bindings" which are standard. + (Hyperlinking): Explain Mouse-1 convention here. + (Find Func): Node deleted. + + * help.texi (Name Help): Xref to Hyperlinking. + + * glossary.texi (Glossary): + Rename "Balance Parentheses" to "Balancing...". + Add "Byte Compilation". Correct "Copyleft". + New xref in "Customization". + Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". + Add "Graphical Terminal" "Keybinding", "Margin", "Window System". + Rename "Registers" to "Register". + Replace "Selecting" with "Selected Frame", + "Selected Window", and "Selecting a Buffer". + + * files.texi (Types of Log File): Explain how projects' + methods can vary. + + * display.texi (Faces): Delete "Emacs 21". + + * custom.texi (Changing a Variable): C-M-i like M-TAB. + * fixit.texi (Spelling): C-M-i like M-TAB. + * mini.texi (Completion Options): C-M-i like M-TAB. + * programs.texi (Symbol Completion): C-M-i like M-TAB. + * text.texi (Text Mode): C-M-i like M-TAB. + + * commands.texi (Keys): Mention F1 and F2 in list of prefixes. + + * calendar.texi (Specified Dates): Mention `g w'. + (Appointments): appt-activate toggles with no arg. + +2005-03-05 Juri Linkov + + * cmdargs.texi (Emacs Invocation): Add cindex + "invocation (command line arguments)" + (Misc X): Add -nbc, --no-blinking-cursor. + +2005-03-04 Ulf Jasper + + * calendar.texi (iCalendar): No need to require it now. + +2005-03-03 Nick Roberts + + * trouble.texi (Contributing): Mention Savannah. Direct users to + emacs-devel. + +2005-03-01 Glenn Morris + + * calendar.texi (Adding to Diary): Mention redrawing of calendar + window. + +2005-02-27 Richard M. Stallman + + * building.texi (Compilation): Update mode line status info. + +2005-02-27 Matt Hodges + + * calendar.texi (General Calendar): Document binding of + scroll-other-window-down. + (Mayan Calendar): Fix earliest date. + (Time Intervals): Document timeclock-change. + Fix timeclock-ask-before-exiting documentation. + +2005-02-26 Kim F. Storm + + * frames.texi (Mouse References): + Add mouse-1-click-in-non-selected-windows. + +2005-02-25 Richard M. Stallman + + * screen.texi (Screen): Explain better about cursors and mode lines; + don't presuppose text terminals. + (Point): Don't assume just one cursor. + Clarify explanation of cursors. + (Echo Area, Menu Bar): Cleanups. + + * mini.texi (Minibuffer): Prompts are highlighted. + (Minibuffer Edit): Newline = C-j only on text terminals. + Clarify resize-mini-windows values. + Mention M-PAGEUP and M-PAGEDOWN. + (Completion Commands): Mouse-1 like Mouse-2. + (Minibuffer History): Explain history commands better. + (Repetition): Add xref to Incremental Search. + + * mark.texi (Setting Mark): Clarify info about displaying mark. + Clarify explanation of C-@ and C-SPC. + (Transient Mark): Mention Delete Selection mode. + (Marking Objects): Clean up text about extending the region. + + * m-x.texi (M-x): One C-g doesn't always go to top level. + No delay before suggest-key-bindings output. + + * fixit.texi (Fixit): Mention C-/ for undo. + (Spelling): Mention ESC TAB like M-TAB. + Replacement words with r and R are rechecked. + Say where C-g leaves point. Mention ? as input. + +2005-02-23 Lute Kamstra + + * cmdargs.texi (Initial Options): Add cross reference. + +2005-02-16 Luc Teirlinck + + * emacs.texi (Top): Update menu for splitting of node in + msdog.texi. + * frames.texi (Frames): Update xref for splitting of node in + msdog.texi. + * trouble.texi (Quitting): Ditto. + +2005-02-16 Richard M. Stallman + + * windows.texi (Split Window): Simplify line truncation info + and xref to Display Custom. + + * trouble.texi (Quitting): Emergency escape only for text terminal. + (Screen Garbled): C-l for ungarbling is only for text terminal. + + * text.texi (Text Mode): ESC TAB alternative for M-TAB. + + * sending.texi (Header Editing): ESC TAB alternative for M-TAB. + + * programs.texi (Program Modes): Mention Python mode. + (Moving by Defuns): Repeating C-M-h extends region. + (Basic Indent): Clarify. + (Custom C Indent): Clarify. + (Expressions): Repeating C-M-@ extends region. + (Info Lookup): Clarify for C-h S. + (Symbol Completion): ESC TAB alternative for M-TAB. + (Electric C): Clarify. + + * emacs.texi (Top): Update display.texi and frames.texi submenu data. + + * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from + MS-DOS Input node. + (MS-DOS Keyboard): Start with explaining DEL and BREAK. + (MS-DOS and MULE): Clarify. + (MS-DOS Processes, Windows Processes): Fix typos. + + * major.texi (Choosing Modes): Clarify. + + * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. + (Keyboard Macro Step-Edit): Clarify. + + * indent.texi (Indentation): Clarifications. + + * help.texi (Help): Correct error about C-h in query-replace. + Clarify apropos vs C-h a. Fix how to search in FAQ. + (Key Help): Describe C-h w here. + (Name Help): Minor cleanup. C-h w moved to Key Help. + Clarify the "object" joke. + (Apropos): Clarify. Mouse-1 like Mouse-2. + (Help Mode): Mouse-1 like Mouse-2. + + * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. + + * display.texi (Display): Reorder menu. + (Faces): Cleanup. + (Font Lock): Cleanup. Mention Options menu. + Delete obsolete text. + (Scrolling): For C-l, don't presume text terminal. + (Horizontal Scrolling): Simplify intro. + (Follow Mode): Clarify. + (Cursor Display): Moved before Display Custom. + (Display Custom): Explain no-redraw-on-reenter is for text terminals. + Doc default-tab-width. Doc line truncation more thoroughly. + + * dired.texi (Dired Enter): C-x C-f can run Dired. + (Dired Visiting): Comment out `a' command. + Mouse-1 is like Mouse-2. + (Shell Commands in Dired): ? can be used more than once. + + * basic.texi (Continuation Lines): Simplify description of truncation, + and refer to Display Custom for the rest of it. + +2005-02-06 Lute Kamstra + + * basic.texi (Undo): Fix typo. + + * cmdargs.texi (Emacs Invocation): Fix typo. + + * custom.texi (Init Examples): Fix typo. + + * abbrevs.texi (Expanding Abbrevs): Fix typo. + +2005-02-06 Richard M. Stallman + + * regs.texi (Registers): Registers can hold numbers, too. + + * killing.texi (Other Kill Commands): Cleanup. + Delete redundant explanation of kill in read-only buffer. + (Yanking): Mention term "copying". + (Accumulating Text): Fix typo. + + * entering.texi (Entering Emacs): Update rationale at start. + (Exiting): Treat iconifying on a par with suspension. + + * custom.texi (Minor Modes): Fix typo. + (Easy Customization): Fix menu style. + (Variables): Add xref. + (Examining): Setting for future sessions works through .emacs. + (Keymaps): "Text terminals", not "Many". + (Init Rebinding): Explain \C-. Show example of \M-. + Fix minor wording errors. + (Function Keys): Explain vector syntax just once. + (Named ASCII Chars): Clarify history of TAB/C-i connection. + (Init File): Mention .emacs.d directory. + (Init Examples): Add xref. + (Find Init): Mention .emacs.d directory. + + * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. + (Action Arguments): Explain which kinds of -l args are found how. + (Initial Options): --batch does not inhibit site-start. + Add xrefs. + (Command Example): Use --batch, not -batch. + + * basic.texi (Inserting Text): Cleanup wording. + (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. + C-n is not error at end of buffer. + (Undo): Doc C-/ like C-_. Add xrefs. + (Arguments): META key may be labeled ALT. + Peculiar arg meanings are explained in doc strings. + + * abbrevs.texi (Expanding Abbrevs): Clarify. + +2005-02-05 Eli Zaretskii + + * frames.texi (Frame Parameters): Add an xref to the description + of list-colors-display. Add a pointer to the X docs about colors. + + * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. + Impove docs of list-colors-display. + +2005-02-03 Lute Kamstra + + * frames.texi (Frames, Drag and Drop): Fix typos. + +2005-02-03 Richard M. Stallman + + * windows.texi (Basic Window): Mention color-change in mode line. + (Change Window): Explain dragging vertical boundaries. + + * text.texi (Sentences): Clarify. + (Paragraphs): Explain M-a and blank lines. + (Outline Mode): Clarify text and menu. + (Hard and Soft Newlines): Mention use-hard-newlines. + + * frames.texi (Frames): Delete unnecessary mention of Windows. + (Mouse Commands): Likewise. Mention xterm mouse support. + (Clipboard): Clarify. + (Mouse References): Mention use of Mouse-1 for following links. + (Menu Mouse Clicks): Clarify. + (Mode Line Mouse): Clarify. + (Drag and Drop): Rewrite. + + * fixit.texi (Spelling): Fix typo. + + * files.texi (File Names): Clarify. + (Visiting): Update conditions for use of file dialog. Clarify. + (Saving): Doc d as answer in save-some-buffers. + (Remote Files): Clean up the text. + + * dired.texi (Misc Dired Commands): Delete dired-marked-files. + + * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. + (List Buffers): Clarify. + (Several Buffers): Doc T command. + (Buffer Convenience): Clarify menu. + + * basic.texi (Undo): Clarify last change. + +2005-02-02 Matt Hodges + + * fixit.texi (Spelling): Fix typo. + +2005-02-01 Luc Teirlinck + + * basic.texi (Undo): Update description of `undo-outer-limit'. + +2005-02-01 Nick Roberts + + * building.texi: Update documentation relating to GDB Graphical + Interface. + +2005-01-30 Luc Teirlinck + + * custom.texi (Easy Customization): Adapt menu to node name change. + +2005-01-30 Richard M. Stallman + + * custom.texi (Easy Customization): Defn of "User Option" now + includes faces. Don't say just "option" when talking about variables. + Do say just "options" to mean "anything customizable". + (Specific Customization): Describe `customize-variable', + not `customize-option'. + + * glossary.texi (Glossary) : Add xref. + : Change definition--include faces. Change xref. + + * picture.texi (Picture): Mention artist.el. + + * sending.texi, screen.texi, programs.texi, misc.texi: + * mini.texi, major.texi, maintaining.texi, macos.texi: + * help.texi, frames.texi, files.texi: + Don't say just "option" when talking about variables. + + * display.texi, mule.texi: Don't say just "option" when talking + about variables. Other minor cleanups. + +2005-01-26 Lute Kamstra + + * cmdargs.texi (Initial Options): Add a cross reference to `Init + File'. Mention the `-Q' option at the `--no-site-file' option. + +2005-01-22 David Kastrup + + * building.texi (Grep Searching): Mention alias `find-grep' for + `grep-find'. + +2005-01-20 Richard M. Stallman + + * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. + +2005-01-15 Sergey Poznyakoff + + * rmail.texi (Movemail): Explain differences + between standard and mailutils versions of movemail. + Describe command line and configuration options introduced + with the latter. + Explain the notion of mailbox URL, provide examples and + cross-references to mailutils documentation. + Describe various methods of specifying mailbox names, + user names and user passwords for rmail. + (Remote Mailboxes): New section. Describe + how movemail handles remote mailboxes. Describe configuration + options used to control its behavior. + (Other Mailbox Formats): Explain handling of various mailbox + formats. + +2005-01-13 Richard M. Stallman + + * commands.texi (Commands): Clarification. + +2005-01-11 Richard M. Stallman + + * programs.texi (Multi-line Indent): Fix previous change. + (Fortran Autofill): Simplify description of fortran-auto-fill-mode. + +2005-01-08 Richard M. Stallman + + * display.texi (Faces): isearch-lazy-highlight-face renamed to + lazy-highlight. + + * search.texi (Query Replace): Mention faces query-replace + and lazy-highlight. + (Incremental Search): Update isearch highlighting info. + +2005-01-04 Richard M. Stallman + + * custom.texi (Saving Customizations): Minor improvement. + +2005-01-03 Luc Teirlinck + + * custom.texi (Saving Customizations): Emacs no longer loads + `custom-file' after .emacs. No longer mention customizing through + Custom. + +2005-01-01 Andreas Schwab + + * killing.texi (Graphical Kill): Move up under node Killing, + change @section to @subsection. + +2005-01-01 Richard M. Stallman + + * custom.texi (Face Customization): Mention hex color specs. + + * emacs.texi (Top): Update Killing submenu. + + * killing.texi (Killing): Reorganize section. + No more TeX-only text; put the node command at start of chapter. + But the first section heading is used only in TeX. + Rewrite the text to read better in this mode. + (Graphical Kill): New subnode gets some of the text that + used to be in the first section. + +2004-12-31 Richard M. Stallman + + * dired.texi (Shell Commands in Dired): Delete the ? example. + + * display.texi (Scrolling): Correct scroll-preserve-screen-position. + + * files.texi (Saving): Describe new require-final-newline features + and mode-require-final-newline. + +2004-12-29 Richard M. Stallman + + * custom.texi (File Variables): Clarify previous change. + +2004-12-27 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is + out now. + +2004-12-27 Richard M. Stallman + + * Makefile.in (MAKEINFO): Specify --force. + + * basic.texi (Moving Point): C-e now runs move-end-of-line. + (Undo): Doc undo-outer-limit. + +2004-12-15 Juri Linkov + + * mark.texi (Transient Mark, Mark Ring): M-< and other + movement commands don't set mark in Transient Mark mode + if mark is active. + +2004-12-12 Juri Linkov + + * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, + C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. + + * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. + (Misc Dired Commands): Add @r{(Dired)} to w. + +2004-12-12 Juri Linkov + + * mark.texi (Marking Objects): Marking commands also extend the + region when mark is active in Transient Mark mode. + +2004-12-08 Luc Teirlinck + + * custom.texi (Saving Customizations): Emacs only loads the custom + file automatically after the init file in version 22.1 or later. + Adapt text and examples to this fact. + +2004-12-07 Luc Teirlinck + + * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to + be set through Custom. Otherwise, it has no effect. + +2004-12-05 Richard M. Stallman + + * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: + * entering.texi: Rename Command Line to Emacs Invocation. + + * misc.texi (Term Mode): Correcty describe C-c. + + * custom.texi (Easy Customization): Move up to section level, + before Variables. Avoid using the term "variable"; say "option". + New initial explanation. + (Variables): In initial explanation, connect "variable" to the + already-explained "user option". + + * emacs.texi (Top): Fix ref to Command Line. + Move reference to Easy Customization. + + * xresources.texi (X Resources): Fix From link. + + * doclicense.texi (GNU Free Documentation License): Fix To link. + + * entering.texi (Entering Emacs): Fix xref, now to Command Line. + + * cmdargs.texi (Command Line): Node renamed from Command Arguments. + +2004-12-03 Richard M. Stallman + + * cmdargs.texi (Initial Options): Clarify batch mode i/o. + +2004-12-01 Luc Teirlinck + + * kmacro.texi: Several small changes in addition to the following. + (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when + defining a keyboard macro. + Mention `kmacro-ring-max'. + (Keyboard Macro Counter): Clarify description of + `kmacro-insert-counter', `kmacro-set-counter', + `kmacro-add-counter' and `kmacro-set-format'. + +2004-11-29 Reiner Steib + + * custom.texi (File Variables): Add `unibyte' and make it more + clear that `unibyte' and `coding' are special. Suggested by Simon + Krahnke . + + * mule.texi (Enabling Multibyte): Refer to File Variables. + Suggested by Simon Krahnke . + +2004-11-26 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to + x-use-old-gtk-file-dialog. + +2004-11-20 Richard M. Stallman + + * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. + +2004-11-09 Lars Brinkhoff + + * building.texi (Lisp Eval): Delete hyphen in section name. + +2004-11-19 Thien-Thi Nguyen + + * files.texi (Old Versions): + No longer document annotation as "CVS only". + +2004-11-10 Andre Spiegel + + * files.texi (Version Control): Rewrite the introduction about + version systems, mentioning the new ones that we support. Thanks + to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for + suggestions. + +2004-11-03 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Replace non-nil with non-@code{nil}. + +2004-11-02 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. + +2004-10-23 Eli Zaretskii + + * text.texi (Text Based Tables, Table Definition) + (Table Creation, Table Recognition, Cell Commands) + (Cell Justification, Row Commands, Column Commands) + (Fixed Width Mode, Table Conversion, Measuring Tables) + (Table Misc): New nodes, documenting the Table Mode. + +2004-10-19 Jason Rumney + + * makefile.w32-in (info): Change order of arguments to makeinfo. + +2004-10-19 Ulf Jasper + + * calendar.texi (iCalendar): Update for package changes. + +2004-10-09 Luc Teirlinck + + * files.texi (Misc File Ops): View mode is a minor mode. + +2004-10-08 Glenn Morris + + * calendar.texi (iCalendar): Style changes. + +2004-10-07 Luc Teirlinck + + * search.texi (Regexps): The regexp described in the example is no + longer stored in the variable `sentence-end'. + +2004-10-06 Nick Roberts + + * building.texi (Starting GUD): Note that multiple debugging + sessions requires `gdb --fullname'. + +2004-10-05 Ulf Jasper + + * calendar.texi (iCalendar): New section for a new package. + +2004-10-05 Luc Teirlinck + + * text.texi: Various small changes in addition to the following. + (Text): Replace xref for autotype with inforef. + (Sentences): Explain nil value for `sentence-end'. + (Paragraphs): Update default values for `paragraph-start' and + `paragraph-separate'. + (Text Mode): Correct description of Text mode's effect on the + syntax table. + (Outline Visibility): `hide-other' does not hide top level headings. + `selective-display-ellipses' no longer has an effect on Outline mode. + (TeX Misc): Add missing @cindex. + Replace xref for RefTeX with inforef. + (Requesting Formatted Text): The variable + `enriched-fill-after-visiting' no longer exists. + (Editing Format Info): Update names of menu items and commands. + (Format Faces): Mention special effect of specifying the default face. + Describe inheritance of text properties. + Correct description of `fixed' face. + (Format Indentation): Correct description of effect of setting + margins. Mention `set-left-margin' and `set-right-margin'. + (Format Justification): Update names of menu items. + `set-justification-full' is now bound to `M-j b'. + Mention that `default-justification' is a per buffer variable. + (Format Properties): Update name of menu item. + (Forcing Enriched Mode): `format-decode-buffer' automatically + turns on Enriched mode if the buffer is in text/enriched format. + +2004-10-05 Emilio C. Lopes + + * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. + +2004-09-28 Kim F. Storm + + * display.texi (Display Custom) : + Align with new functionality. + +2004-09-22 Luc Teirlinck + + * display.texi (Display Custom): Remove stray `@end defvar'. + +2004-09-23 Kim F. Storm + + * display.texi (Display Custom): Add `overflow-newline-into-fringe', + `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. + +2004-09-20 Richard M. Stallman + + * custom.texi (Hooks): Explain using setq to clear out a hook. + (File Variables): Explain multiline string constants. + (Non-ASCII Rebinding): Explain when you need to update + non-ASCII char codes in .emacs. + + * building.texi (Compilation): Explain how to make a silent + subprocess that won't be terminated. Explain compilation-environment. + +2004-09-13 Kim F. Storm + + * mini.texi (Repetition): Rename isearch-resume-enabled to + isearch-resume-in-command-history and change default to disabled. + +2004-09-09 Kim F. Storm + + * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' + with new `kmacro-name-last-macro'. + +2004-09-08 Juri Linkov + + * mini.texi (Minibuffer History): Add `history-delete-duplicates'. + +2004-09-03 Juri Linkov + + * search.texi (Incremental Search): Update wording for M-%. + +2004-09-02 Luc Teirlinck + + * killing.texi (Killing): Correct description of kill commands in + read-only buffer. + +2004-09-02 Teodor Zlatanov + + * building.texi (Compilation Mode): Add a paragraph about rules + for finding the compilation buffer for `next-error'. + + * search.texi (Other Repeating Search): Mention that Occur mode + supports the next-error functionality. + +2004-09-02 Juri Linkov + + * search.texi (Regexp Replace): Add missing backslash to \footnote. + +2004-08-31 Luc Teirlinck + + * kmacro.texi (Basic Keyboard Macro): + `apply-macro-to-region-lines' now operates on all lines that begin + in the region, rather than on all complete lines in the region. + +2004-08-31 Jan Dj,Ad(Brv + + * frames.texi (Drag and drop): Add documentation about + x-dnd-test-function and x-dnd-known-types. + +2004-08-30 Luc Teirlinck + + * indent.texi: Various minor changes in addition to: + (Indentation Commands): Correct description of `indent-relative'. + (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text + mode. The *Tab Stops* buffer uses Overwrite Mode. + (Just Spaces): `tabify' converts sequences of at least two spaces + to tabs. + +2004-08-27 Luc Teirlinck + + * frames.texi (Secondary Selection): Setting the secondary + selection with M-Drag-Mouse-1 does not alter the kill ring, + setting it with M-Mouse-1 and M-Mouse-3 does. + (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for + toolkit scroll bars. + (Scroll Bars): Ditto. + + * windows.texi (Basic Window): When using a window system, the value + of point in a non-selected window is indicated by a hollow box. + (Split Window): Side by side windows are separated by a scroll bar, + if scroll bars are used. + C-Mouse-2 on scroll bar now also works for toolkit scroll bars. + (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. + (Window Convenience): Update bindings for `winner-undo' and + `winner-redo'. + + * ack.texi (Acknowledgments): Use `@unnumbered'. + * misc.texi : Adapt sectioning in Info to the node structure. + (Invoking emacsclient): Make "Invoking emacsclient" a subsection + of "Using Emacs as a Server". + * building.texi (Building): Interchange nodes (for correct numbering). + * programs.texi (Programs): Interchange nodes (for correct numbering). + * killing.texi, entering.texi, commands.texi: Adapt sectioning in + Info to the node structure. + * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. + Rearrange order of nodes and sections such that both "GNU GENERAL + PUBLIC LICENSE" and "GNU Free Documentation License" appear at the + end, as appropriate for appendices. + (Acknowledgments): Put inside @iftex instead of @ifnotinfo. + Use `@unnumberedsec'. + * trouble.texi: Adapt sectioning in Info to the node structure. + Adapt node pointers to change in emacs.texi. + * cmdargs.texi, doclicense.texi: Adapt node pointers. + +2004-08-25 Kenichi Handa + + * custom.texi (Non-ASCII Rebinding): Fix and simplify the + description for unibyte mode. + +2004-08-23 Luc Teirlinck + + * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. + + * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. + (Configuring Scrolling): Correct invalid (for hardcopy) @xref. + (Regexp Replace): Standardize reference to hardcopy Elisp Manual + in @pxref. + +2004-08-22 Luc Teirlinck + + * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): + Change section names. + +2004-08-21 Luc Teirlinck + + * kmacro.texi (Keyboard Macro Ring): Rename section. + Emacs treats the head of the macro ring as the `last keyboard macro'. + (Keyboard Macro Counter): Minor change. + (Save Keyboard Macro): Some clarifications. + (Edit Keyboard Macro): Rename section. + + * buffers.texi (Buffers): Maximum buffer size is now 256M on + 32-bit machines. + (Several Buffers): Clarify which buffer is selected if `2' is + pressed in the Buffer Menu. + Auto Revert mode can be used to update the Buffer Menu + automatically. + +2004-08-21 Eli Zaretskii + + * help.texi (Misc Help): Add an index entry for finding an Info + manual by its file name. + +2004-08-20 Luc Teirlinck + + * files.texi (Backup Deletion): Correct description of + `delete-old-versions'. + (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. + (Auto Save Files): Recommend `auto-save-mode' to reenable + auto-saving, rather than the abbreviation `auto-save'. + +2004-08-17 Luc Teirlinck + + * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms + for "killing" and "yanking" in main menu. + +2004-08-16 Richard M. Stallman + + * killing.texi (Yanking, Killing): Minor cleanups. + + * mark.texi (Momentary Mark): Minor cleanups. + +2004-08-15 Kenichi Handa + + * custom.texi (Non-ASCII Rebinding): + C-q always inserts the right code to pass to global-set-key. + +2004-08-13 Luc Teirlinck + + * regs.texi (RegNumbers): Mention `C-x r i' binding for + `insert-register', instead of `C-x r g' binding, for consistency. + +2004-08-12 Luc Teirlinck + + * fixit.texi (Spelling): Fix typo. + +2004-08-11 Luc Teirlinck + + * help.texi (Help): Fix Texinfo usage. + +2004-07-24 Richard M. Stallman + + * text.texi (Paragraphs): Update how paragraphs are separated + and the default for paragraph-separate. + + * search.texi (Regexp Replace): Further update text for new + replacement operators. + +2004-07-18 Luc Teirlinck + + * emacs-xtra.texi (Subdir switches): Dired does not remember the + `R' switch. + + * dired.texi (Dired Updating): `k' only deletes inserted + subdirectories from the Dired buffer if a prefix argument was given. + + * search.texi (Regexps): Delete redundant definition of `symbol' in + description of `\_>'. It already occurs in the description of `\_<'. + +2004-07-01 Juri Linkov + + * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. + (Regexp Search): Add M-r. + +2004-06-30 Luc Teirlinck + + * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. + +2004-06-29 Jesper Harder + + * search.texi, calendar.texi: Markup fixes. + +2004-06-25 Richard M. Stallman + + * search.texi (Regexp Replace): Rewrite description of \# \, and \?. + +2004-06-25 David Kastrup + + * search.texi (Regexp Replace): Some typo corrections and + rearrangement. + +2004-06-24 David Kastrup + + * search.texi (Unconditional Replace): Use replace-string instead + of query-replace in example. + (Regexp Replace): Add explanations for `\,', `\#' and `\?' + sequences. + (Query Replace): Correct explanation of `^' which does not use + the mark stack. + +2004-06-21 Nick Roberts + + * misc.texi (Shell History Copying): Document comint-insert-input. + (Shell Ring): Describe comint-dynamic-list-input-ring here. + +2004-06-20 Jesper Harder + + * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. + * custom.texi (Customization): Do. + * anti.texi (Antinews): Do. + * abbrevs.texi (Defining Abbrevs): Do. + + * programs.texi (Info Lookup): Fix keybinding for + info-lookup-symbol. + +2004-06-16 Juanma Barranquero + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): + Add emacs-xtra. + ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. + (clean): Add emacs-xtra and flymake. Remove redundancies. + +2004-06-15 Luc Teirlinck + + * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): + Add emacs-xtra. + * emacs-xtra.texi: New file. + +2004-06-14 Luc Teirlinck + + * dired.texi (Dired Enter): Mention conditions on `ls' switches. + (Dired and Find): Mention differences with ordinary Dired buffers. + +2004-06-13 Richard M. Stallman + + * custom.texi (Init Syntax): Explain about vars that do special + things when set with setq or with Custom. + (Init Examples): Add line-number-mode example. + +2004-06-12 Juri Linkov + + * dired.texi (Operating on Files): Add dired-do-touch. + +2004-06-10 Juri Linkov + + * building.texi (Lisp Eval): Add C-M-x on defface. + +2004-06-08 Luc Teirlinck + + * files.texi (Reverting): Auto-Revert mode and + Global Auto-Revert mode no longer revert remote files. + +2004-05-29 Richard M. Stallman + + * custom.texi (Init File): Two dashes start --no-site-file. + +2004-05-29 Alan Mackenzie + + * programs.texi: Update for CC Mode 5.30 and incidental amendments. + ("AWK"): Is consistently thus spelt throughout. + (AWK, Pike): Document as "C-like modes". + (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. + (M-x man): Supersedes M-x manual-entry. + Add numerous index entries. Correct "ESC a/e" to "M-a/e". + + ("Comments in C"): Delete node; the info is in CC Mode manual. + (c-comment-only-line-offset): Remove description. + + (C-c ., C-c C-c): Describe new C Mode bindings. + + (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) + (@dfn{Style}, c-default-style, comment-column, comment-padding) + (c-up-conditional, c-beginning-of-statement, c-end-of-statement): + Amend definitions. + + (c-beginning-of-defun, c-end-of-defun, c-context-line-break): + Describe functions. + + (c-comment-start-regexp, c-hanging-comment-ender-p) + (c-hanging-comment-starter-p): Remove obsolete definitions. + + * emacs.texi: Remove the menu entry "Comments in C". + +2004-05-27 Luc Teirlinck + + * dired.texi (Dired and Find): `find-ls-option' does not apply to + `M-x locate'. + +2004-05-16 Karl Berry + + * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, + makeinfo --html fails. + * help.texi (Help Summary) [@ifnottex]: Likewise. + +2004-05-13 Nick Roberts + + * building.texi (GDB Graphical Interface): Update and describe + layout first. + +2004-05-04 Jason Rumney + + * makefile.w32-in: Revert last change. + +2004-05-03 Jason Rumney + + * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. + +2004-04-23 Juanma Barranquero + + * makefile.w32-in: Add "-*- makefile -*-" mode tag. + +2004-04-18 Juri Linkov + + * fixit.texi (Spelling): Remove file extension from ispell xref. + +2004-04-15 Kim F. Storm + + * cmdargs.texi (Initial Options): Add -Q. + +2004-04-05 Kim F. Storm + + * custom.texi (File Variables): Add safe-local-eval-forms. + +2004-04-02 Luc Teirlinck + + * files.texi (Reverting): Correct description of revert-buffer's + handling of point. + +2004-03-22 Juri Linkov + + * emacs.texi (Top): Add `Misc X'. + + * trouble.texi: Fix help key bindings. + + * glossary.texi: Improve references. + + * help.texi: Sync keywords with finder.el. + + * mini.texi (Completion): Add description for menu items. + + * misc.texi (Browse-URL, FFAP): Add information about keywords. + + * sending.texi (Mail Methods): Fix xref to Message manual. + +2004-03-12 Richard M. Stallman + + * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. + +2004-03-04 Richard M. Stallman + + * search.texi (Regexps): Explain that ^ and $ have their + special meanings only in certain contexts. + + * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. + + * mule.texi (Specify Coding): Doc C-x RET F. + + * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely + for multiple compile and grep buffers. + (Indirect Buffers): Don't recommand clone-indirect-buffer + for multiple compile and grep buffers. + +2004-02-29 Juanma Barranquero + + * makefile.w32-in (mostlyclean, clean, maintainer-clean): + Use $(DEL) instead of rm, and ignore exit code. + +2004-02-23 Nick Roberts + + * building.texi (Watch Expressions): Update. + +2004-02-21 Juri Linkov + + * cmdargs.texi (Action Arguments): Add alias --find-file. Add + --directory, --help, --version. Move text about command-line-args + to Command Arguments. + (Initial Options): Add @cindex for --script. Fix @cindex for -q. + Add --no-desktop. Add alias --no-multibyte, --no-unibyte. + (Window Size X): Join -g and --geometry. Add @cindex. + (Borders X): Fix @cindex for -ib. Add @cindex for -bw. + (Title X): Remove alias -title. + (Misc X): New node. + +2004-02-15 Jan Dj,Ad(Brv + + * frames.texi (Drag and drop): Add Motif to list of supported + protocols. + +2004-02-03 Jan Dj,Ad(Brv + + * frames.texi (Drag and drop): New section. + +2004-01-24 Richard M. Stallman + + * emacs.texi (Acknowledgments): Renamed from Acknowledgements. + Include it only @ifnotinfo. Patch the preceding and following + node headers to point to each other. + +2004-01-11 Glenn Morris + + * calendar.texi (Appointments): Update section. + +2003-12-29 Kevin Ryde + + * programs.texi (C Modes): Fix the xref. + +2003-12-23 Nick Roberts + + * building.texi (Watch Expressions): Update. + (Commands of GUD): Include use of toolbar + breakpoints set from + fringe/margin. + +2003-12-03 Andre Spiegel + + * files.texi: Say how to disable VC. Suggested by Alan Mackenzie + . + +2003-11-29 Jan Dj,Ad(Brv + + * frames.texi (Dialog Boxes): Add use-file-dialog. + +2003-11-22 Martin Stjernholm + + * ack.texi: Note that Alan Mackenzie contributed the AWK support + in CC Mode. + +2003-11-02 Jesper Harder (tiny change) + + * man/ack.texi, man/basic.texi, man/cmdargs.texi: + * man/commands.texi, man/custom.texi, man/display.texi: + * man/emacs.texi, man/files.texi: + * man/frames.texi, man/glossary.texi, man/killing.texi: + * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: + * man/mule.texi, man/rmail.texi, man/search.texi: + * man/sending.texi, man/text.texi, man/trouble.texi: + Replace @sc{ascii} and ASCII with @acronym{ASCII}. + +2003-11-01 Alan Mackenzie + + * search.texi (Scrolling During Incremental Search): Document a + new scrolling facility in isearch mode. + +2003-10-22 Miles Bader + + * Makefile.in (info): Move before $(top_srcdir)/info. + +2003-10-22 Nick Roberts + + * building.texi (Watch Expressions): Update section on data display + to reflect code changes (GDB Graphical Interface). + +2003-10-13 Richard M. Stallman + + * xresources.texi (GTK resources): Clean up previous change. + +2003-10-12 Jan Dj,Ad(Brv + + * xresources.texi (GTK resources): Add a note that some themes + disallow customizations. Add scroll theme example. + +2003-09-30 Richard M. Stallman + + * cmdargs.texi (General Variables): Remove MAILRC envvar. + + * misc.texi (Saving Emacs Sessions): Shorten the section, + collapsing back into one node. + +2003-09-30 Lars Hansen + + * misc.texi: Section "Saving Emacs Sessions" rewritten. + +2003-09-29 Jan Dj,Ad(Brv. + + * xresources.texi (GTK names in Emacs): Correct typo. + +2003-09-24 Luc Teirlinck + + * cmdargs.texi (Font X): Mention new default font. More + fully describe long font names, wildcard patterns and the + problems involved. (Result of discussion on emacs-devel.) + +2003-09-22 Luc Teirlinck + + * emacs.texi (Acknowledgements): Correct typo. + +2003-09-22 Richard M. Stallman + + * dired.texi (Misc Dired Commands): New node. + (Dired Navigation): Add dired-goto-file. + + * files.texi (File Aliases, Misc File Ops): Add @cindex entries. + + * emacs.texi (Acknowledgements): New node, split from Distribution. + + * cmdargs.texi (Action Arguments): -f reads interactive args. + +2003-09-08 Lute Kamstra + + * screen.texi (Mode Line): Say that POS comes before LINE. + Mention `size-indication-mode'. + * display.texi (Optional Mode Line): Document + `size-indication-mode'. + * basic.texi (Position Info): Mention `size-indication-mode'. + +2003-09-07 Luc Teirlinck + + * xresources.texi (Resources): Refer to `editres' man page. + (Lucid Resources): Update defaults. Expand description of + `shadowThickness'. + +2003-09-04 Miles Bader + + * Makefile.in (top_srcdir): New variable. + ($(top_srcdir)/info): New rule. + (info): Depend on it. + +2003-09-03 Peter Runestig + + * makefile.w32-in: New file. + +2003-08-29 Richard M. Stallman + + * misc.texi (Saving Emacs Sessions): Correct previous change. + +2003-08-19 Luc Teirlinck + + * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. + (Intro): Include kmacro.texi after fixit.texi instead of after + custom.texi. (As suggested by Kim Storm.) + +2003-08-18 Luc Teirlinck + + * fixit.texi (Fixit): Update `Next' pointer. + * files.texi (Files): Update `Previous' pointer. + * kmacro.texi (Keyboard Macros): Remove redundant node and section. + * emacs.texi (Intro): Include kmacro.texi after custom.texi. + (Suggested by Kim Storm.) + * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) + +2003-08-18 Kim F. Storm + + * kmacro.texi: New file describing enhanced keyboard macro + functionality. Replaces old description in custom.texi. + + * custom.texi (Customization): Add xref to Keyboard Macros chapter. + (Keyboard Macros): Move to new kmacro.texi file. + + * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. + +2003-08-17 Edward M. Reingold + + * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. + +2003-08-17 Alex Schroeder + + * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not + required. + +2003-08-05 Richard M. Stallman + + * programs.texi (Lisp Indent): Don't describe + lisp-indent-function property here. Use xref to Lisp Manual. + +2003-08-03 Glenn Morris + + * calendar.texi (Date Formats): Document changed behaviour of + abbreviations. + +2003-07-24 Markus Rost + + * buffers.texi (List Buffers): Fix previous change. + +2003-07-13 Markus Rost + + * buffers.texi (List Buffers): Adjust to new format of *Buffer + List*. + +2003-07-07 Luc Teirlinck + + * display.texi (Font Lock): Fix typo. + +2003-07-07 Richard M. Stallman + + * display.texi (Font Lock): Add xref for format info on + font-lock-remove-keywords. + + * building.texi (Compilation): Document what happens with asynch + children of compiler process. + + * help.texi (Library Keywords): Use @multitable. + +2003-06-04 Richard M. Stallman + + * programs.texi (Expressions): Delete C-M-DEL. + + * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. + comint-move-point-for-output renamed from + comint-scroll-to-bottom-on-output. + + * custom.texi (Init Rebinding): Replace previous change with xref. + (Non-ASCII Rebinding): Explain that issue more briefly here. + +2003-05-28 Richard M. Stallman + + * indent.texi (Indentation): Condense, simplify, clarify prev change. + +2003-05-28 Nick Roberts + + * building.texi (GDB Graphical Interface): New node. + (Rewritten somewhat by RMS.) + +2003-05-28 Kai Gro,A_(Bjohann + + * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for + non-English letters. Explain how to set coding systems correctly + and how to include the right coding cookie in the file. + +2003-05-22 Kai Gro,A_(Bjohann + + * indent.texi (Indentation): Explain the concepts. + (Just Spaces): Explain why preventing tabs for indentation might + be useful. + +2003-04-16 Richard M. Stallman + + * search.texi (Regexps): Ref to Lisp manual for more regexp features. + +2003-02-22 Alex Schroeder + + * cmdargs.texi (General Variables): Document SMTPSERVER. + + * sending.texi: Remove SMTP node. + (Mail Sending): Describe `send-mail-function'. Link to SMTP + library. + +2003-02-22 Alex Schroeder + + * sending.texi (Sending via SMTP): Explain MTA/MUA. + +2003-02-22 Simon Josefsson + + * sending.texi (Mail Methods): Add node about SMTP. + +2003-02-17 Jan Dj,Ad(Brv + + * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. + +2003-02-01 Kevin Ryde + + * glossary.texi (Glossary): Correction to cl cross reference. + +2003-01-20 Richard M. Stallman + + * killing.texi (Rectangles): Document C-x c r. + +2003-01-19 Jan Dj,Ad(Brv + + * xresources.texi (GTK resources): New node. + (GTK widget names): New node. + (GTK names in Emacs): New node. + (GTK styles): New node. + +2003-01-09 Francesco Potort,Al(B + + * maintaining.texi (Create Tags Table): Add reference to the new + `etags --help --lang=LANG' option. + +2002-10-02 Karl Berry + + * emacs.texi: Per rms, update all manuals to use @copying instead of + @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, + where needed for the sake of the HTML output. + +2001-12-20 Eli Zaretskii + + * Makefile.in (EMACSSOURCES): Update the list of Emacs manual + source files. + +2001-11-16 Eli Zaretskii + + * Makefile.in (emacsman): New target. + +2001-10-20 Gerd Moellmann + + * (Version 21.1 released.) + +2001-10-05 Gerd Moellmann + + * Branch for 21.1. + +2001-03-05 Gerd Moellmann + + * Makefile.in (mostlyclean, maintainer-clean): Delete more files. + +2000-05-31 Stefan Monnier + + * .cvsignore (*.tmp): New entry. Seems to be used for @macro. + +1999-07-12 Richard Stallman + + * Version 20.4 released. + +1998-12-04 Markus Rost + + * Makefile.in (INFO_TARGETS): Delete customize.info. + (DVI_TARGETS): Delete customize.dvi. + (../info/customize, customize.dvi): Targets deleted. + +1998-08-19 Richard Stallman + + * Version 20.3 released. + +1998-05-06 Richard Stallman + + * Makefile.in (EMACSSOURCES): Add mule.texi. + Add msdog.texi, ack.texi. Remove gnu1.texi. + +1998-04-06 Andreas Schwab + + * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use + it in dvi targets. + +1997-09-23 Paul Eggert + + * Makefile.in: Merge changes mistakenly made to `Makefile'. + (INFO_TARGETS): Change ../info/custom to ../info/customize. + (../info/customize): Rename from ../info/custom. + +1997-09-19 Richard Stallman + + * Version 20.2 released. + +1997-09-15 Richard Stallman + + * Version 20.1 released. + +1997-08-24 Richard Stallman + + * Makefile (../info/customize, customize.dvi): New targets. + (INFO_TARGETS): Add ../info/customize. + (DVI_TARGETS): Add customize.dvi. + +1996-08-11 Richard Stallman + + * Version 19.33 released. + +1996-07-31 Richard Stallman + + * Version 19.32 released. + +1996-06-20 Richard Stallman + + * Makefile.in (All info targets): cd $(srcdir) to do the work. + +1996-06-19 Richard Stallman + + * Makefile.in (All info targets): Specify $(srcdir) in input files. + Specify -I option. + (All dvi targets): Set the TEXINPUTS variable. + +1996-05-25 Karl Heuer + + * Version 19.31 released. + +1995-11-24 Richard Stallman + + * Version 19.30 released. + +1995-02-07 Richard Stallman + + * Makefile.in (maintainer-clean): Rename from realclean. + +1994-11-23 Richard Stallman + + * Makefile.in: New file. + * Makefile: File deleted. + +1994-11-19 Richard Stallman + + * Makefile (TEXINDEX_OBJS): Variable deleted. + (texindex, texindex.o, getopt.o): Rules deleted. + All deps on texindex deleted. + (distclean): Don't delete texindex. + (mostlyclean): Don't delete *.o. + * texindex.c, getopt.c: Files deleted. + +1994-09-07 Richard Stallman + + * Version 19.26 released. + +1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) + + * Makefile (EMACSSOURCES): Exclude undo.texi. + +1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.25 released. + +1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.24 released. + +1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.23 released. + +1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile: Delete spurious tab. + +1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (.SUFFIXES): New rule. + +1993-12-04 Richard Stallman (rms@srarc2) + + * getopt.c: New file. + * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. + (getopt.o): New rule. + (dvi): Don't depend on texindex. + (emacs.dvi): Depend on texindex. + +1993-12-03 Richard Stallman (rms@srarc2) + + * Makefile (TEXI2DVI): New variable. + (emacs.dvi): Add explicit command. + (TEXINDEX_OBJS): Delete duplicate getopt.o. + +1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.22 released. + +1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (TEXINDEX_OBJS): Delete spurious period. + +1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.21 released. + +1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (realclean): Don't delete the Info files. + +1993-10-25 Brian Fox (bfox@albert.gnu.ai.mit.edu) + + * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x + 4' where appropriate. + +1993-10-20 Brian Fox (bfox@ai.mit.edu) + + * Makefile: Fix targets for texindex. + + * texindex.c: Include "../src/config.h" if building in emacs. + + * Makefile: Change all files to FILENAME.texi, force all targets + to be FILENAME, not FILENAME.info. + Add target to build texindex.c, defining `emacs'. + +1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.19 released. + +1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.18 released. + +1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile: Fix source file names of the separate manuals. + +1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.17 released. + +1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * split-man: Fix typos in last change. + +1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.16 released. + +1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * version 19.15 released. + +1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Makefile (distclean): It's rm, not rf. + +1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.14 released. + +1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile: New file. + +1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.13 released. + +1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.9 released. + +1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.8 released. + +1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * cmdargs.texi: Document the -i, -itype, and -iconic options. + + * trouble.texi: It's `enable-flow-control-on', not + `evade-flow-control-on'. + +1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * display.texi: Document standard-display-european. + +1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.7 released. + + * emacs.texi: Add a sentence to the top menu mentioning the + specific version of Emacs this manual applies to. + +1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * basic.texi: Document next-line-add-lines variable used to + implement down-arrow. + + * killing.texi: Document kill-whole-line. + +1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) + + * text.texi: Update unix TeX ordering information. + +1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) + + * news.texi: Mention fill-rectangle in keybinding list. + + * killing.texi: Document fill-rectangle. + +1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * vc.texi: Bring the docs up to date with VC 5.2. + +1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * emacs.tex: Mention blackbox and gomoku under Amusements. + Assembler mode is now mentioned and appropriately indexed + under Programming Modes. + +1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) + + * emacs.tex: Update TeX ordering information. + +1990-06-26 David Lawrence (tale@geech) + + * emacs.tex: Note that completion-ignored-extensions is not used + to filter out names when all completions are displayed in + *Completions*. + +1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) + + * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. + +1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) + + * emacs.tex: Add @findex grep. + +1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) + + * emacs.tex: Correct two typos. No other changes before + Version 19 will be made. + +1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) + + * emacs.tex: Update information for obtaining TeX distribution from the + University of Washington. + +;; Local Variables: +;; coding: iso-2022-7bit +;; fill-column: 79 +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, + 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + + This file is part of GNU Emacs. + + GNU Emacs is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3, or (at your option) + any later version. + + GNU Emacs is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNU Emacs; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd diff --cc doc/emacs/display.texi index d4d2945d584,00000000000..5e1e0056592 mode 100644,000000..100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@@ -1,1259 -1,0 +1,1259 @@@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Display, Search, Registers, Top +@chapter Controlling the Display + + Since only part of a large buffer fits in the window, Emacs tries to +show a part that is likely to be interesting. Display-control +commands allow you to specify which part of the text you want to see, +and how to display it. Many variables also affect the details of +redisplay. Unless otherwise stated, the variables described in this +chapter have their effect by customizing redisplay itself; therefore, +their values only make a difference at the time of redisplay. + +@menu +* Scrolling:: Commands to move text up and down in a window. +* Auto Scrolling:: Redisplay scrolls text automatically when needed. +* Horizontal Scrolling:: Moving text left and right in a window. +* Follow Mode:: Follow mode lets two windows scroll as one. +* Faces:: How to change the display style using faces. +* Standard Faces:: Emacs' predefined faces. +* Font Lock:: Minor mode for syntactic highlighting using faces. +* Highlight Interactively:: Tell Emacs what text to highlight. +* Fringes:: Enabling or disabling window fringes. +* Displaying Boundaries:: Displaying top and bottom of the buffer. +* Useless Whitespace:: Showing possibly-spurious trailing whitespace. +* Selective Display:: Hiding lines with lots of indentation. +* Optional Mode Line:: Optional mode line display features. +* Text Display:: How text characters are normally displayed. +* Cursor Display:: Features for displaying the cursor. +* Line Truncation:: Truncating lines to fit the screen width instead + of continuing them to multiple screen lines. +* Display Custom:: Information on variables for customizing display. +@end menu + +@node Scrolling +@section Scrolling + + If a buffer contains text that is too large to fit entirely within a +window that is displaying the buffer, Emacs shows a contiguous portion of +the text. The portion shown always contains point. + +@cindex scrolling + @dfn{Scrolling} means moving text up or down in the window so that +different parts of the text are visible. Scrolling ``forward'' or +``up'' means that text moves up, and new text appears at the bottom. +Scrolling ``backward'' or ``down'' moves text down, and new text +appears at the top. + + Scrolling happens automatically if you move point past the bottom or +top of the window. You can also scroll explicitly with the commands +in this section. + +@table @kbd +@item C-l +Clear screen and redisplay, scrolling the selected window to center +point vertically within it (@code{recenter}). +@item C-v +Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). +@item @key{NEXT} +@itemx @key{PAGEDOWN} +Likewise, scroll forward. +@item M-v +Scroll backward (@code{scroll-down}). +@item @key{PRIOR} +@itemx @key{PAGEUP} +Likewise, scroll backward. +@item @var{arg} C-l +Scroll so point is on line @var{arg} (@code{recenter}). +@item C-M-l +Scroll heuristically to bring useful information onto the screen +(@code{reposition-window}). +@end table + +@kindex C-l +@findex recenter + The most basic scrolling command is @kbd{C-l} (@code{recenter}) with +no argument. It scrolls the selected window so that point is halfway +down from the top of the window. On a text terminal, it also clears +the screen and redisplays all windows. That is useful in case the +screen is garbled (@pxref{Screen Garbled}). + +@kindex C-v +@kindex M-v +@kindex NEXT +@kindex PRIOR +@kindex PAGEDOWN +@kindex PAGEUP +@findex scroll-up +@findex scroll-down + To read the buffer a windowful at a time, use @kbd{C-v} +(@code{scroll-up}) with no argument. This scrolls forward by nearly +the whole window height. The effect is to take the two lines at the +bottom of the window and put them at the top, followed by nearly a +whole windowful of lines that were not previously visible. If point +was in the text that scrolled off the top, it ends up at the new top +of the window. + +@vindex next-screen-context-lines + @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in +a similar way, also with overlap. The number of lines of overlap that +the @kbd{C-v} or @kbd{M-v} commands leave is controlled by the +variable @code{next-screen-context-lines}; by default, it is 2. The +function keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and +@key{PAGEUP}, are equivalent to @kbd{C-v} and @kbd{M-v}. + + The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll +the text in the selected window up or down a few lines. @kbd{C-v} +with an argument moves the text and point up, together, that many +lines; it brings the same number of new lines into view at the bottom +of the window. @kbd{M-v} with numeric argument scrolls the text +downward, bringing that many new lines into view at the top of the +window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice +versa. + + The names of scroll commands are based on the direction that the +text moves in the window. Thus, the command to scroll forward is +called @code{scroll-up} because it moves the text upward on the +screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names +and customary meanings from a different convention that developed +elsewhere; hence the strange result that @key{PAGEDOWN} runs +@code{scroll-up}. + +@vindex scroll-preserve-screen-position + Some users like the full-screen scroll commands to keep point at the +same screen line. To enable this behavior, set the variable +@code{scroll-preserve-screen-position} to a non-@code{nil} value. In +this mode, when these commands would scroll the text around point off +the screen, or within @code{scroll-margin} lines of the edge, they +move point to keep the same vertical position within the window. +This mode is convenient for browsing through a file by scrolling by +screenfuls; if you come back to the screen where you started, point +goes back to the line where it started. However, this mode is +inconvenient when you move to the next screen in order to move point +to the text there. + + Another way to do scrolling is with @kbd{C-l} with a numeric argument. +@kbd{C-l} does not clear the screen when given an argument; it only scrolls +the selected window. With a positive argument @var{n}, it repositions text +to put point @var{n} lines down from the top. An argument of zero puts +point on the very top line. Point does not move with respect to the text; +rather, the text and point move rigidly on the screen. @kbd{C-l} with a +negative argument puts point that many lines from the bottom of the window. +For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u +- 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put +point at the center (vertically) of the selected window. + +@kindex C-M-l +@findex reposition-window + The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current +window heuristically in a way designed to get useful information onto +the screen. For example, in a Lisp file, this command tries to get the +entire current defun onto the screen if possible. + +@node Auto Scrolling +@section Automatic Scrolling + +@vindex scroll-conservatively + Redisplay scrolls the buffer automatically when point moves out of +the visible portion of the text. The purpose of automatic scrolling +is to make point visible, but you can customize many aspects of how +this is done. + + Normally, automatic scrolling centers point vertically within the +window. However, if you set @code{scroll-conservatively} to a small +number @var{n}, then if you move point just a little off the +screen---less than @var{n} lines---then Emacs scrolls the text just +far enough to bring point back on screen. By default, +@code{scroll-conservatively} is@tie{}0. + +@cindex aggressive scrolling +@vindex scroll-up-aggressively +@vindex scroll-down-aggressively + When the window does scroll by a longer distance, you can control +how aggressively it scrolls, by setting the variables +@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. +The value of @code{scroll-up-aggressively} should be either +@code{nil}, or a fraction @var{f} between 0 and 1. A fraction +specifies where on the screen to put point when scrolling upward. +More precisely, when a window scrolls up because point is above the +window start, the new start position is chosen to put point @var{f} +part of the window height from the top. The larger @var{f}, the more +aggressive the scrolling. + + @code{nil}, which is the default, scrolls to put point at the center. +So it is equivalent to .5. + + Likewise, @code{scroll-down-aggressively} is used for scrolling +down. The value, @var{f}, specifies how far point should be placed +from the bottom of the window; thus, as with +@code{scroll-up-aggressively}, a larger value is more aggressive. + +@vindex scroll-margin + The variable @code{scroll-margin} restricts how close point can come +to the top or bottom of a window. Its value is a number of screen +lines; if point comes within that many lines of the top or bottom of the +window, Emacs recenters the window. By default, @code{scroll-margin} is +0. + +@node Horizontal Scrolling +@section Horizontal Scrolling +@cindex horizontal scrolling + + @dfn{Horizontal scrolling} means shifting all the lines sideways +within a window---so that some of the text near the left margin is not +displayed at all. When the text in a window is scrolled horizontally, +text lines are truncated rather than continued (@pxref{Line +Truncation}). Whenever a window shows truncated lines, Emacs +automatically updates its horizontal scrolling whenever point moves +off the left or right edge of the screen. You can also use these +commands to do explicit horizontal scrolling. + +@table @kbd +@item C-x < +Scroll text in current window to the left (@code{scroll-left}). +@item C-x > +Scroll to the right (@code{scroll-right}). +@end table + +@kindex C-x < +@kindex C-x > +@findex scroll-left +@findex scroll-right + The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected +window to the left by @var{n} columns with argument @var{n}. This moves +part of the beginning of each line off the left edge of the window. +With no argument, it scrolls by almost the full width of the window (two +columns less, to be precise). + + @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The +window cannot be scrolled any farther to the right once it is displayed +normally (with each line starting at the window's left margin); +attempting to do so has no effect. This means that you don't have to +calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large +argument will restore the normal display. + + If you use those commands to scroll a window horizontally, that sets +a lower bound for automatic horizontal scrolling. Automatic scrolling +will continue to scroll the window, but never farther to the right +than the amount you previously set by @code{scroll-left}. + +@vindex hscroll-margin + The value of the variable @code{hscroll-margin} controls how close +to the window's edges point is allowed to get before the window will +be automatically scrolled. It is measured in columns. If the value +is 5, then moving point within 5 columns of the edge causes horizontal +scrolling away from that edge. + +@vindex hscroll-step + The variable @code{hscroll-step} determines how many columns to +scroll the window when point gets too close to the edge. If it's +zero, horizontal scrolling centers point horizontally within the +window. If it's a positive integer, it specifies the number of +columns to scroll by. If it's a floating-point number, it specifies +the fraction of the window's width to scroll by. The default is zero. + +@vindex auto-hscroll-mode + To disable automatic horizontal scrolling, set the variable +@code{auto-hscroll-mode} to @code{nil}. + +@node Follow Mode +@section Follow Mode +@cindex Follow mode +@cindex mode, Follow +@findex follow-mode +@cindex windows, synchronizing +@cindex synchronizing windows + + @dfn{Follow mode} is a minor mode that makes two windows, both +showing the same buffer, scroll as a single tall ``virtual window.'' +To use Follow mode, go to a frame with just one window, split it into +two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x +follow-mode}. From then on, you can edit the buffer in either of the +two windows, or scroll either one; the other window follows it. + + In Follow mode, if you move point outside the portion visible in one +window and into the portion visible in the other window, that selects +the other window---again, treating the two as if they were parts of +one large window. + + To turn off Follow mode, type @kbd{M-x follow-mode} a second time. + +@node Faces +@section Faces: Controlling Text Display Style +@cindex faces + + You can specify various styles for displaying text using +@dfn{faces}. Each face can specify various @dfn{face attributes}, +such as the font family, the height, weight and slant of the +characters, the foreground and background color, and underlining or +overlining. A face does not have to specify all of these attributes; +often it inherits most of them from another face. + + On graphical display, all the Emacs face attributes are meaningful. +On a text-only terminal, only some of them work. Some text-only +terminals support inverse video, bold, and underline attributes; some +support colors. Text-only terminals generally do not support changing +the height and width or the font family. + + Most major modes assign faces to the text automatically through the +work of Font Lock mode. @xref{Font Lock}, for more information about +Font Lock mode and syntactic highlighting. You can print the current +buffer with the highlighting that appears on your screen using the +command @code{ps-print-buffer-with-faces}. @xref{PostScript}. + + You control the appearance of a part of the text in the buffer by +specifying the face or faces to use for it. The style of display used +for any given character is determined by combining the attributes of +all the applicable faces specified for that character. Any attribute +that isn't specified by these faces is taken from the @code{default} face, +whose attributes reflect the default settings of the frame itself. + + Enriched mode, the mode for editing formatted text, includes several +commands and menus for specifying faces for text in the buffer. +@xref{Format Faces}, for how to specify the font for text in the +buffer. @xref{Format Colors}, for how to specify the foreground and +background color. + +@cindex face colors, setting +@findex set-face-foreground +@findex set-face-background + To alter the appearance of a face, use the customization buffer. +@xref{Face Customization}. You can also use X resources to specify +attributes of particular faces (@pxref{Resources}). Alternatively, +you can change the foreground and background colors of a specific face +with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. +These commands prompt in the minibuffer for a face name and a color +name, with completion, and then set that face to use the specified +color. Changing the colors of the @code{default} face also changes +the foreground and background colors on all frames, both existing and +those to be created in the future. (You can also set foreground and +background colors for the current frame only; see @ref{Frame +Parameters}.) + + If you want to alter the appearance of all Emacs frames, you need to +customize the frame parameters in the variable +@code{default-frame-alist}; see @ref{Creating Frames, +default-frame-alist}. + + Emacs can correctly display variable-width fonts, but Emacs commands +that calculate width and indentation do not know how to calculate +variable widths. This can sometimes lead to incorrect results when +you use variable-width fonts. In particular, indentation commands can +give inconsistent results, so we recommend you avoid variable-width +fonts for editing program source code. Filling will sometimes make +lines too long or too short. We plan to address these issues in +future Emacs versions. + +@node Standard Faces +@section Standard Faces + +@findex list-faces-display + To see what faces are currently defined, and what they look like, +type @kbd{M-x list-faces-display}. It's possible for a given face to +look different in different frames; this command shows the appearance +in the frame in which you type it. With a prefix argument, this +prompts for a regular expression, and displays only faces with names +matching that regular expression. + + Here are the standard faces for specifying text appearance. You can +apply them to specific text when you want the effects they produce. + +@table @code +@item default +This face is used for ordinary text that doesn't specify any face. +@item bold +This face uses a bold variant of the default font, if it has one. +It's up to you to choose a default font that has a bold variant, +if you want to use one. +@item italic +This face uses an italic variant of the default font, if it has one. +@item bold-italic +This face uses a bold italic variant of the default font, if it has one. +@item underline +This face underlines text. +@item fixed-pitch +This face forces use of a particular fixed-width font. +@item variable-pitch +This face forces use of a particular variable-width font. It's +reasonable to customize this face to use a different variable-width font, +if you like, but you should not make it a fixed-width font. +@item shadow +This face is used for making the text less noticeable than the surrounding +ordinary text. Usually this can be achieved by using shades of gray in +contrast with either black or white default foreground color. +@end table + + Here's an incomplete list of faces used to highlight parts of the +text temporarily for specific purposes. (Many other modes define +their own faces for this purpose.) + +@table @code +@item highlight +This face is used for highlighting portions of text, in various modes. +For example, mouse-sensitive text is highlighted using this face. +@item isearch +This face is used for highlighting the current Isearch match. +@item query-replace +This face is used for highlighting the current Query Replace match. +@item lazy-highlight +This face is used for lazy highlighting of Isearch and Query Replace +matches other than the current one. +@item region +This face is used for displaying a selected region (when Transient Mark +mode is enabled---see below). +@item secondary-selection +This face is used for displaying a secondary X selection (@pxref{Secondary +Selection}). +@item trailing-whitespace +The face for highlighting excess spaces and tabs at the end of a line +when @code{show-trailing-whitespace} is non-@code{nil}; see +@ref{Useless Whitespace}. +@item nobreak-space +The face for displaying the character ``nobreak space.'' +@item escape-glyph +The face for highlighting the @samp{\} or @samp{^} that indicates +a control character. It's also used when @samp{\} indicates a +nobreak space or nobreak (soft) hyphen. +@end table + +@cindex @code{region} face + When Transient Mark mode is enabled, the text of the region is +highlighted when the mark is active. This uses the face named +@code{region}; you can control the style of highlighting by changing the +style of this face (@pxref{Face Customization}). @xref{Transient Mark}, +for more information about Transient Mark mode and activation and +deactivation of the mark. + + These faces control the appearance of parts of the Emacs frame. +They exist as faces to provide a consistent way to customize the +appearance of these parts of the frame. + +@table @code +@item mode-line +@itemx modeline +This face is used for the mode line of the currently selected window, +and for menu bars when toolkit menus are not used. By default, it's +drawn with shadows for a ``raised'' effect on graphical displays, and +drawn as the inverse of the default face on non-windowed terminals. +@code{modeline} is an alias for the @code{mode-line} face, for +compatibility with old Emacs versions. +@item mode-line-inactive +Like @code{mode-line}, but used for mode lines of the windows other +than the selected one (if @code{mode-line-in-non-selected-windows} is +non-@code{nil}). This face inherits from @code{mode-line}, so changes +in that face affect mode lines in all windows. +@item mode-line-highlight +Like @code{highlight}, but used for portions of text on mode lines. +@item mode-line-buffer-id +This face is used for buffer identification parts in the mode line. +@item header-line +Similar to @code{mode-line} for a window's header line, which appears +at the top of a window just as the mode line appears at the bottom. +Most windows do not have a header line---only some special modes, such +Info mode, create one. +@item vertical-border +This face is used for the vertical divider between windows. +By default this face inherits from the @code{mode-line-inactive} face +on character terminals. On graphical displays the foreground color of +this face is used for the vertical line between windows without +scrollbars. +@item minibuffer-prompt +@cindex @code{minibuffer-prompt} face +@vindex minibuffer-prompt-properties +This face is used for the prompt strings displayed in the minibuffer. +By default, Emacs automatically adds this face to the value of +@code{minibuffer-prompt-properties}, which is a list of text +properties used to display the prompt text. (This variable takes +effect when you enter the minibuffer.) +@item fringe +@cindex @code{fringe} face +The face for the fringes to the left and right of windows on graphic +displays. (The fringes are the narrow portions of the Emacs frame +between the text area and the window's right and left borders.) +@xref{Fringes}. +@item scroll-bar +This face determines the visual appearance of the scroll bar. +@xref{Scroll Bars}. +@item border +This face determines the color of the frame border. +@item cursor +This face determines the color of the cursor. +@item mouse +This face determines the color of the mouse pointer. +@item tool-bar +This face determines the color of tool bar icons. @xref{Tool Bars}. +@item tooltip +This face is used for tooltips. @xref{Tooltips}. +@item menu +@cindex menu bar appearance +@cindex @code{menu} face, no effect if customized +@cindex customization of @code{menu} face +This face determines the colors and font of Emacs's menus. @xref{Menu +Bars}. Setting the font of LessTif/Motif menus is currently not +supported; attempts to set the font are ignored in this case. +Likewise, attempts to customize this face in Emacs built with GTK and +in the MS-Windows/Mac ports are ignored by the respective GUI toolkits; +you need to use system-wide styles and options to change the +appearance of the menus. +@end table + +@node Font Lock +@section Font Lock mode +@cindex Font Lock mode +@cindex mode, Font Lock +@cindex syntax highlighting and coloring + + Font Lock mode is a minor mode, always local to a particular buffer, +which highlights (or ``fontifies'') the buffer contents according to +the syntax of the text you are editing. It can recognize comments and +strings in most languages; in several languages, it can also recognize +and properly highlight various other important constructs---for +example, names of functions being defined or reserved keywords. +Some special modes, such as Occur mode and Info mode, have completely +specialized ways of assigning fonts for Font Lock mode. + +@findex font-lock-mode + Font Lock mode is turned on by default in all modes which support it. +You can toggle font-lock for each buffer with the command @kbd{M-x +font-lock-mode}. Using a positive argument unconditionally turns Font +Lock mode on, and a negative or zero argument turns it off. + +@findex global-font-lock-mode +@vindex global-font-lock-mode + If you do not wish Font Lock mode to be turned on by default, +customize the variable @code{global-font-lock-mode} using the Customize +interface (@pxref{Easy Customization}), or use the function +@code{global-font-lock-mode} in your @file{.emacs} file, like this: + +@example +(global-font-lock-mode 0) +@end example + +@noindent +This variable, like all the variables that control Font Lock mode, +take effect whenever fontification is done; that is, potentially at +any time. + +@findex turn-on-font-lock + If you have disabled Global Font Lock mode, you can still enable Font +Lock for specific major modes by adding the function +@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For +example, to enable Font Lock mode for editing C files, you can do this: + +@example +(add-hook 'c-mode-hook 'turn-on-font-lock) +@end example + + Font Lock mode uses several specifically named faces to do its job, +including @code{font-lock-string-face}, @code{font-lock-comment-face}, +and others. The easiest way to find them all is to use @kbd{M-x +customize-group @key{RET} font-lock-faces @key{RET}}. You can then +use that customization buffer to customize the appearance of these +faces. @xref{Face Customization}. + + You can also customize these faces using @kbd{M-x +set-face-foreground} or @kbd{M-x set-face-background}. @xref{Faces}. + +@vindex font-lock-maximum-decoration + The variable @code{font-lock-maximum-decoration} specifies the +preferred level of fontification, for modes that provide multiple +levels. Level 1 is the least amount of fontification; some modes +support levels as high as 3. The normal default is ``as high as +possible.'' You can specify an integer, which applies to all modes, or +you can specify different numbers for particular major modes; for +example, to use level 1 for C/C++ modes, and the default level +otherwise, use this: + +@example +(setq font-lock-maximum-decoration + '((c-mode . 1) (c++-mode . 1))) +@end example + +@vindex font-lock-maximum-size + Fontification can be too slow for large buffers, so you can suppress +it for buffers above a certain size. The variable +@code{font-lock-maximum-size} specifies a buffer size, beyond which +buffer fontification is suppressed. + +@c @w is used below to prevent a bad page-break. +@vindex font-lock-beginning-of-syntax-function +@cindex incorrect fontification +@cindex parenthesis in column zero and fontification +@cindex brace in column zero and fontification + Comment and string fontification (or ``syntactic'' fontification) +relies on analysis of the syntactic structure of the buffer text. For +the sake of speed, some modes, including Lisp mode, rely on a special +convention: an open-parenthesis or open-brace in the leftmost column +always defines the @w{beginning} of a defun, and is thus always +outside any string or comment. (@xref{Left Margin Paren}.) If you +don't follow this convention, Font Lock mode can misfontify the text +that follows an open-parenthesis or open-brace in the leftmost column +that is inside a string or comment. + +@cindex slow display during scrolling + The variable @code{font-lock-beginning-of-syntax-function} (always +buffer-local) specifies how Font Lock mode can find a position +guaranteed to be outside any comment or string. In modes which use the +leftmost column parenthesis convention, the default value of the variable +is @code{beginning-of-defun}---that tells Font Lock mode to use the +convention. If you set this variable to @code{nil}, Font Lock no longer +relies on the convention. This avoids incorrect results, but the price +is that, in some cases, fontification for a changed text must rescan +buffer text from the beginning of the buffer. This can considerably +slow down redisplay while scrolling, particularly if you are close to +the end of a large buffer. + +@findex font-lock-add-keywords + Font Lock highlighting patterns already exist for many modes, but you +may want to fontify additional patterns. You can use the function +@code{font-lock-add-keywords}, to add your own highlighting patterns for +a particular mode. For example, to highlight @samp{FIXME:} words in C +comments, use this: + +@example +(font-lock-add-keywords + 'c-mode + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))) +@end example + +@findex font-lock-remove-keywords + To remove keywords from the font-lock highlighting patterns, use the +function @code{font-lock-remove-keywords}. @xref{Search-based +Fontification,,, elisp, The Emacs Lisp Reference Manual}, for +documentation of the format of this list. + +@cindex just-in-time (JIT) font-lock +@cindex background syntax highlighting + Fontifying large buffers can take a long time. To avoid large +delays when a file is visited, Emacs fontifies only the visible +portion of a buffer. As you scroll through the buffer, each portion +that becomes visible is fontified as soon as it is displayed. The +parts of the buffer that are not displayed are fontified +``stealthily,'' in the background, i.e.@: when Emacs is idle. You can +control this background fontification, also called @dfn{Just-In-Time} +(or @dfn{JIT}) Lock, by customizing variables in the customization +group @samp{jit-lock}. @xref{Specific Customization}. + +@node Highlight Interactively +@section Interactive Highlighting +@cindex highlighting by matching +@cindex interactive highlighting +@cindex Highlight Changes mode + +@findex highlight-changes-mode + Use @kbd{M-x highlight-changes-mode} to enable (or disable) +Highlight Changes mode, a minor mode that uses faces (colors, +typically) to indicate which parts of the buffer were changed most +recently. + +@cindex Hi Lock mode +@findex hi-lock-mode + Hi Lock mode highlights text that matches regular expressions you +specify. For example, you might wish to see all the references to a +certain variable in a program source file, highlight certain parts in +a voluminous output of some program, or make certain names stand out +in an article. Use the @kbd{M-x hi-lock-mode} command to enable (or +disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use +@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)} +in your @file{.emacs} file. + + Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except +that you specify explicitly the regular expressions to highlight. You +control them with these commands: + +@table @kbd +@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} +@kindex C-x w h +@findex highlight-regexp +Highlight text that matches @var{regexp} using face @var{face} +(@code{highlight-regexp}). The highlighting will remain as long as +the buffer is loaded. For example, to highlight all occurrences of +the word ``whim'' using the default face (a yellow background) +@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for +highlighting, Hi Lock provides several of its own and these are +pre-loaded into a history list. While being prompted for a face use +@kbd{M-p} and @kbd{M-n} to cycle through them. + +You can use this command multiple times, specifying various regular +expressions to highlight in different ways. + +@item C-x w r @var{regexp} @key{RET} +@kindex C-x w r +@findex unhighlight-regexp +Unhighlight @var{regexp} (@code{unhighlight-regexp}). + +If you invoke this from the menu, you select the expression to +unhighlight from a list. If you invoke this from the keyboard, you +use the minibuffer. It will show the most recently added regular +expression; use @kbd{M-p} to show the next older expression and +@kbd{M-n} to select the next newer expression. (You can also type the +expression by hand, with completion.) When the expression you want to +unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit +the minibuffer and unhighlight it. + +@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} +@kindex C-x w l +@findex highlight-lines-matching-regexp +@cindex lines, highlighting +@cindex highlighting lines of text +Highlight entire lines containing a match for @var{regexp}, using face +@var{face} (@code{highlight-lines-matching-regexp}). + +@item C-x w b +@kindex C-x w b +@findex hi-lock-write-interactive-patterns +Insert all the current highlighting regexp/face pairs into the buffer +at point, with comment delimiters to prevent them from changing your +program. (This key binding runs the +@code{hi-lock-write-interactive-patterns} command.) + +These patterns are extracted from the comments, if appropriate, if you +invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while +Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). + +@item C-x w i +@kindex C-x w i +@findex hi-lock-find-patterns +Extract regexp/face pairs from comments in the current buffer +(@code{hi-lock-find-patterns}). Thus, you can enter patterns +interactively with @code{highlight-regexp}, store them into the file +with @code{hi-lock-write-interactive-patterns}, edit them (perhaps +including different faces for different parenthesized parts of the +match), and finally use this command (@code{hi-lock-find-patterns}) to +have Hi Lock highlight the edited patterns. + +@vindex hi-lock-file-patterns-policy +The variable @code{hi-lock-file-patterns-policy} controls whether Hi +Lock mode should automatically extract and highlight patterns found in +a file when it is visited. Its value can be @code{nil} (never +highlight), @code{t} (highlight the patterns), @code{ask} (query the +user), or a function. If it is a function, +@code{hi-lock-find-patterns} calls it with the patterns as argument; +if the function returns non-@code{nil}, the patterns are used. The +default is @code{nil}. Note that patterns are always highlighted if +you call @code{hi-lock-find-patterns} directly, regardless of the +value of this variable. + +@vindex hi-lock-exclude-modes +Also, @code{hi-lock-find-patterns} does nothing if the current major +mode's symbol is a member of the list @code{hi-lock-exclude-modes}. +@end table + +@node Fringes +@section Window Fringes +@cindex fringes + + On a graphical display, each Emacs window normally has narrow +@dfn{fringes} on the left and right edges. The fringes display +indications about the text in the window. + + The most common use of the fringes is to indicate a continuation +line, when one line of text is split into multiple lines on the +screen. The left fringe shows a curving arrow for each screen line +except the first, indicating that ``this is not the real beginning.'' +The right fringe shows a curving arrow for each screen line except the +last, indicating that ``this is not the real end.'' + + The fringes indicate line truncation with short horizontal arrows +meaning ``there's more text on this line which is scrolled +horizontally out of view;'' clicking the mouse on one of the arrows +scrolls the display horizontally in the direction of the arrow. The +fringes can also indicate other things, such as empty lines, or where a +program you are debugging is executing (@pxref{Debuggers}). + +@findex set-fringe-style +@findex fringe-mode + You can enable and disable the fringes for all frames using +@kbd{M-x fringe-mode}. To enable and disable the fringes +for the selected frame, use @kbd{M-x set-fringe-style}. + +@node Displaying Boundaries +@section Displaying Boundaries + +@vindex indicate-buffer-boundaries + On a graphical display, Emacs can indicate the buffer boundaries in +the fringes. It indicates the first line and the last line with +angle images in the fringes. This can be combined with up and down +arrow images which say whether it is possible to scroll the window up +and down. + + The buffer-local variable @code{indicate-buffer-boundaries} controls +how the buffer boundaries and window scrolling is indicated in the +fringes. If the value is @code{left} or @code{right}, both angle and +arrow bitmaps are displayed in the left or right fringe, respectively. + + If value is an alist, each element @code{(@var{indicator} . +@var{position})} specifies the position of one of the indicators. +The @var{indicator} must be one of @code{top}, @code{bottom}, +@code{up}, @code{down}, or @code{t} which specifies the default +position for the indicators not present in the alist. +The @var{position} is one of @code{left}, @code{right}, or @code{nil} +which specifies not to show this indicator. + + For example, @code{((top . left) (t . right))} places the top angle +bitmap in left fringe, the bottom angle bitmap in right fringe, and +both arrow bitmaps in right fringe. To show just the angle bitmaps in +the left fringe, but no arrow bitmaps, use @code{((top . left) +(bottom . left))}. + +@vindex default-indicate-buffer-boundaries + The value of the variable @code{default-indicate-buffer-boundaries} +is the default value for @code{indicate-buffer-boundaries} in buffers +that do not override it. + +@node Useless Whitespace +@section Useless Whitespace + +@cindex trailing whitespace +@cindex whitespace, trailing +@vindex show-trailing-whitespace + It is easy to leave unnecessary spaces at the end of a line, or +empty lines at the end of a file, without realizing it. In most +cases, this @dfn{trailing whitespace} has no effect, but there are +special circumstances where it matters. It can also be a nuisance +that the line has ``changed,'' when the change is just spaces added or +removed at the end. + + You can make trailing whitespace at the end of a line visible on the +screen by setting the buffer-local variable +@code{show-trailing-whitespace} to @code{t}. Then Emacs displays +trailing whitespace in the face @code{trailing-whitespace}. + + This feature does not apply when point is at the end of the line +containing the whitespace. Strictly speaking, that is ``trailing +whitespace'' nonetheless, but displaying it specially in that case +looks ugly while you are typing in new text. In this special case, +the location of point is enough to show you that the spaces are +present. + +@findex delete-trailing-whitespace + To delete all trailing whitespace within the current buffer's +accessible portion (@pxref{Narrowing}), type @kbd{M-x +delete-trailing-whitespace @key{RET}}. (This command does not remove +the form-feed characters.) + +@vindex indicate-empty-lines +@vindex default-indicate-empty-lines +@cindex unused lines +@cindex fringes, and unused line indication + Emacs can indicate unused lines at the end of the window with a +small image in the left fringe (@pxref{Fringes}). The image appears +for window lines that do not correspond to any buffer text. Blank +lines at the end of the buffer then stand out because they do not have +this image in the fringe. + + To enable this feature, set the buffer-local variable +@code{indicate-empty-lines} to a non-@code{nil} value. The default +value of this variable is controlled by the variable +@code{default-indicate-empty-lines}; by setting that variable, you +can enable or disable this feature for all new buffers. (This feature +currently doesn't work on text-only terminals.) + +@node Selective Display +@section Selective Display +@cindex selective display +@findex set-selective-display +@kindex C-x $ + + Emacs has the ability to hide lines indented more than a certain number +of columns (you specify how many columns). You can use this to get an +overview of a part of a program. + + To hide lines in the current buffer, type @kbd{C-x $} +(@code{set-selective-display}) with a numeric argument @var{n}. Then +lines with at least @var{n} columns of indentation disappear from the +screen. The only indication of their presence is that three dots +(@samp{@dots{}}) appear at the end of each visible line that is +followed by one or more hidden ones. + + The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as +if they were not there. + + The hidden lines are still present in the buffer, and most editing +commands see them as usual, so you may find point in the middle of the +hidden text. When this happens, the cursor appears at the end of the +previous line, after the three dots. If point is at the end of the +visible line, before the newline that ends it, the cursor appears before +the three dots. + + To make all lines visible again, type @kbd{C-x $} with no argument. + +@vindex selective-display-ellipses + If you set the variable @code{selective-display-ellipses} to +@code{nil}, the three dots do not appear at the end of a line that +precedes hidden lines. Then there is no visible indication of the +hidden lines. This variable becomes local automatically when set. + + See also @ref{Outline Mode} for another way to hide part of +the text in a buffer. + +@node Optional Mode Line +@section Optional Mode Line Features + +@cindex buffer size display +@cindex display of buffer size +@findex size-indication-mode + The buffer percentage @var{pos} indicates the percentage of the +buffer above the top of the window. You can additionally display the +size of the buffer by typing @kbd{M-x size-indication-mode} to turn on +Size Indication mode. The size will be displayed immediately +following the buffer percentage like this: + +@example +@var{POS} of @var{SIZE} +@end example + +@noindent +Here @var{SIZE} is the human readable representation of the number of +characters in the buffer, which means that @samp{k} for 10^3, @samp{M} +for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. + +@cindex narrowing, and buffer size display + If you have narrowed the buffer (@pxref{Narrowing}), the size of the +accessible part of the buffer is shown. + +@cindex line number display +@cindex display of line number +@findex line-number-mode + The current line number of point appears in the mode line when Line +Number mode is enabled. Use the command @kbd{M-x line-number-mode} to +turn this mode on and off; normally it is on. The line number appears +after the buffer percentage @var{pos}, with the letter @samp{L} to +indicate what it is. + +@cindex Column Number mode +@cindex mode, Column Number +@findex column-number-mode + Similarly, you can display the current column number by turning on +Column number mode with @kbd{M-x column-number-mode}. The column +number is indicated by the letter @samp{C}. However, when both of +these modes are enabled, the line and column numbers are displayed in +parentheses, the line number first, rather than with @samp{L} and +@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more +information about minor modes and about how to use these commands. + +@cindex narrowing, and line number display + If you have narrowed the buffer (@pxref{Narrowing}), the displayed +line number is relative to the accessible portion of the buffer. +Thus, it isn't suitable as an argument to @code{goto-line}. (Use +@code{what-line} command to see the line number relative to the whole +file.) + +@vindex line-number-display-limit + If the buffer is very large (larger than the value of +@code{line-number-display-limit}), then the line number doesn't appear. +Emacs doesn't compute the line number when the buffer is large, because +that would be too slow. Set it to @code{nil} to remove the limit. + +@vindex line-number-display-limit-width + Line-number computation can also be slow if the lines in the buffer +are too long. For this reason, Emacs normally doesn't display line +numbers if the average width, in characters, of lines near point is +larger than the value of the variable +@code{line-number-display-limit-width}. The default value is 200 +characters. + +@findex display-time +@cindex time (on mode line) + Emacs can optionally display the time and system load in all mode +lines. To enable this feature, type @kbd{M-x display-time} or customize +the option @code{display-time-mode}. The information added to the mode +line usually appears after the buffer name, before the mode names and +their parentheses. It looks like this: + +@example +@var{hh}:@var{mm}pm @var{l.ll} +@end example + +@noindent +@vindex display-time-24hr-format +Here @var{hh} and @var{mm} are the hour and minute, followed always by +@samp{am} or @samp{pm}. @var{l.ll} is the average number of running +processes in the whole system recently. (Some fields may be missing if +your operating system cannot support them.) If you prefer time display +in 24-hour format, set the variable @code{display-time-24hr-format} +to @code{t}. + +@cindex mail (on mode line) +@vindex display-time-use-mail-icon +@vindex display-time-mail-face +@vindex display-time-mail-file +@vindex display-time-mail-directory + The word @samp{Mail} appears after the load level if there is mail +for you that you have not read yet. On a graphical display you can use +an icon instead of @samp{Mail} by customizing +@code{display-time-use-mail-icon}; this may save some space on the mode +line. You can customize @code{display-time-mail-face} to make the mail +indicator prominent. Use @code{display-time-mail-file} to specify +the mail file to check, or set @code{display-time-mail-directory} +to specify the directory to check for incoming mail (any nonempty regular +file in the directory is considered as ``newly arrived mail''). + +@cindex mode line, 3D appearance +@cindex attributes of mode line, changing +@cindex non-integral number of lines in a window + By default, the mode line is drawn on graphics displays with +3D-style highlighting, like that of a button when it is not being +pressed. If you don't like this effect, you can disable the 3D +highlighting of the mode line, by customizing the attributes of the +@code{mode-line} face. @xref{Face Customization}. + +@cindex non-selected windows, mode line appearance + By default, the mode line of nonselected windows is displayed in a +different face, called @code{mode-line-inactive}. Only the selected +window is displayed in the @code{mode-line} face. This helps show +which window is selected. When the minibuffer is selected, since +it has no mode line, the window from which you activated the minibuffer +has its mode line displayed using @code{mode-line}; as a result, +ordinary entry to the minibuffer does not change any mode lines. + +@vindex mode-line-in-non-selected-windows + You can disable use of @code{mode-line-inactive} by setting variable +@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode +lines are displayed in the @code{mode-line} face. + +@vindex eol-mnemonic-unix +@vindex eol-mnemonic-dos +@vindex eol-mnemonic-mac +@vindex eol-mnemonic-undecided + You can customize the mode line display for each of the end-of-line +formats by setting each of the variables @code{eol-mnemonic-unix}, +@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and +@code{eol-mnemonic-undecided} to the strings you prefer. + +@node Text Display +@section How Text Is Displayed +@cindex characters (in text) + + @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs +buffers are displayed with their graphics, as are non-ASCII multibyte +printing characters (octal codes above 0400). + + Some @acronym{ASCII} control characters are displayed in special ways. The +newline character (octal code 012) is displayed by starting a new line. +The tab character (octal code 011) is displayed by moving to the next +tab stop column (normally every 8 columns). + + Other @acronym{ASCII} control characters are normally displayed as a caret +(@samp{^}) followed by the non-control version of the character; thus, +control-A is displayed as @samp{^A}. The caret appears in face +@code{escape-glyph}. + + Non-@acronym{ASCII} characters 0200 through 0237 (octal) are +displayed with octal escape sequences; thus, character code 0230 +(octal) is displayed as @samp{\230}. The backslash appears in face +@code{escape-glyph}. + +@vindex ctl-arrow + If the variable @code{ctl-arrow} is @code{nil}, control characters in +the buffer are displayed with octal escape sequences, except for newline +and tab. Altering the value of @code{ctl-arrow} makes it local to the +current buffer; until that time, the default value is in effect. The +default is initially @code{t}. + + The display of character codes 0240 through 0377 (octal) may be +either as escape sequences or as graphics. They do not normally occur +in multibyte buffers, but if they do, they are displayed as Latin-1 +graphics. In unibyte mode, if you enable European display they are +displayed using their graphics (assuming your terminal supports them), +otherwise as escape sequences. @xref{Unibyte Mode}. + +@vindex nobreak-char-display +@cindex no-break space, display +@cindex no-break hyphen, display +@cindex soft hyphen, display + Some character sets define ``no-break'' versions of the space and +hyphen characters, which are used where a line should not be broken. +Emacs normally displays these characters with special faces +(respectively, @code{nobreak-space} and @code{escape-glyph}) to +distinguish them from ordinary spaces and hyphens. You can turn off +this feature by setting the variable @code{nobreak-char-display} to +@code{nil}. If you set the variable to any other value, that means to +prefix these characters with an escape character. + +@vindex tab-width +@vindex default-tab-width + Normally, a tab character in the buffer is displayed as whitespace which +extends to the next display tab stop position, and display tab stops come +at intervals equal to eight spaces. The number of spaces per tab is +controlled by the variable @code{tab-width}, which is made local by +changing it. Note that how the tab character +in the buffer is displayed has nothing to do with the definition of +@key{TAB} as a command. The variable @code{tab-width} must have an +integer value between 1 and 1000, inclusive. The variable +@code{default-tab-width} controls the default value of this variable +for buffers where you have not set it locally. + + You can customize the way any particular character code is displayed +by means of a display table. @xref{Display Tables,, Display Tables, +elisp, The Emacs Lisp Reference Manual}. + +@node Cursor Display +@section Displaying the Cursor + +@findex blink-cursor-mode +@vindex blink-cursor-alist +@cindex cursor, locating visually +@cindex cursor, blinking + You can customize the cursor's color, and whether it blinks, using +the @code{cursor} Custom group (@pxref{Easy Customization}). On +a graphical display, the command @kbd{M-x blink-cursor-mode} enables +or disables the blinking of the cursor. (On text terminals, the +terminal itself blinks the cursor, and Emacs has no control over it.) +You can control how the cursor appears when it blinks off by setting +the variable @code{blink-cursor-alist}. + +@vindex visible-cursor + Some text terminals offer two different cursors: the normal cursor +and the very visible cursor, where the latter may be e.g. bigger or +blinking. By default Emacs uses the very visible cursor, and switches +to it when you start or resume Emacs. If the variable +@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it +doesn't switch, so it uses the normal cursor. + +@cindex cursor in non-selected windows +@vindex cursor-in-non-selected-windows - Normally, the cursor appears in non-selected windows in the ``off'' - state, with the same appearance as when the blinking cursor blinks ++ Normally, the cursor appears in non-selected windows without ++blinking, with the same appearance as when the blinking cursor blinks +``off.'' For a box cursor, this is a hollow box; for a bar cursor, +this is a thinner bar. To turn off cursors in non-selected windows, - customize the variable @code{cursor-in-non-selected-windows} and assign - it a @code{nil} value. ++customize the variable @code{cursor-in-non-selected-windows} and ++assign it a @code{nil} value. + +@vindex x-stretch-cursor +@cindex wide block cursor + On graphical displays, Emacs can optionally draw the block cursor +as wide as the character under the cursor---for example, if the cursor +is on a tab character, it would cover the full width occupied by that +tab character. To enable this feature, set the variable +@code{x-stretch-cursor} to a non-@code{nil} value. + +@findex hl-line-mode +@findex global-hl-line-mode +@cindex highlight current line + To make the cursor even more visible, you can use HL Line mode, a +minor mode that highlights the line containing point. Use @kbd{M-x +hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x +global-hl-line-mode} enables or disables the same mode globally. + +@node Line Truncation +@section Truncation of Lines + +@cindex truncation +@cindex line truncation, and fringes + As an alternative to continuation, Emacs can display long lines by +@dfn{truncation}. This means that all the characters that do not fit +in the width of the screen or window do not appear at all. On +graphical displays, a small straight arrow in the fringe indicates +truncation at either end of the line. On text-only terminals, @samp{$} +appears in the first column when there is text truncated to the left, +and in the last column when there is text truncated to the right. + +@vindex truncate-lines +@findex toggle-truncate-lines + Horizontal scrolling automatically causes line truncation +(@pxref{Horizontal Scrolling}). You can explicitly enable line +truncation for a particular buffer with the command @kbd{M-x +toggle-truncate-lines}. This works by locally changing the variable +@code{truncate-lines}. If that variable is non-@code{nil}, long lines +are truncated; if it is @code{nil}, they are continued onto multiple +screen lines. Setting the variable @code{truncate-lines} in any way +makes it local to the current buffer; until that time, the default +value is in effect. The default value is normally @code{nil}. + +@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows. + If the variable @code{truncate-partial-width-windows} is +non-@code{nil}, it forces truncation rather than continuation in any +window less than the full width of the screen or frame, regardless of +the value of @code{truncate-lines}. For information about side-by-side +windows, see @ref{Split Window}. See also @ref{Display,, Display, +elisp, The Emacs Lisp Reference Manual}. + +@vindex overflow-newline-into-fringe + If the variable @code{overflow-newline-into-fringe} is +non-@code{nil} on a graphical display, then Emacs does not continue or +truncate a line which is exactly as wide as the window. Instead, the +newline overflows into the right fringe, and the cursor appears in the +fringe when positioned on that newline. + +@node Display Custom +@section Customization of Display + + This section describes variables (@pxref{Variables}) that you can +change to customize how Emacs displays. Beginning users can skip +it. +@c the reason for that pxref is because an xref early in the +@c ``echo area'' section leads here. + +@vindex inverse-video + If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts +to invert all the lines of the display from what they normally are. + +@vindex visible-bell + If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts +to make the whole screen blink when it would normally make an audible bell +sound. This variable has no effect if your terminal does not have a way +to make the screen blink. + +@vindex echo-keystrokes + The variable @code{echo-keystrokes} controls the echoing of multi-character +keys; its value is the number of seconds of pause required to cause echoing +to start, or zero, meaning don't echo at all. The value takes effect when +there is someting to echo. @xref{Echo Area}. + +@vindex baud-rate + The variable @anchor{baud-rate}@code{baud-rate} holds the output +speed of the terminal, as far as Emacs knows. Setting this variable +does not change the speed of actual data transmission, but the value +is used for calculations. On text-only terminals, it affects padding, +and decisions about whether to scroll part of the screen or redraw it +instead. It also affects the behavior of incremental search. + + On graphical displays, @code{baud-rate} is only used to determine +how frequently to look for pending input during display updating. A +higher value of @code{baud-rate} means that check for pending input +will be done less frequently. + +@cindex hourglass pointer display +@vindex hourglass-delay + On graphical display, Emacs can optionally display the mouse pointer +in a special shape to say that Emacs is busy. To turn this feature on +or off, customize the group @code{cursor}. You can also control the +amount of time Emacs must remain busy before the busy indicator is +displayed, by setting the variable @code{hourglass-delay}. + +@vindex overline-margin + On graphical display, this variables specifies the vertical position +of an overline above the text, including the height of the overline +itself (1 pixel). The default value is 2 pixels. + +@vindex x-underline-at-descent-line + On graphical display, Emacs normally draws an underline at the +baseline level of the font. If @code{x-underline-at-descent-line} is +non-@code{nil}, Emacs draws the underline at the same height as the +font's descent line. + +@findex tty-suppress-bold-inverse-default-colors + On some text-only terminals, bold face and inverse video together +result in text that is hard to read. Call the function +@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} +argument to suppress the effect of bold-face in this case. + +@vindex no-redraw-on-reenter + On a text-only terminal, when you reenter Emacs after suspending, Emacs +normally clears the screen and redraws the entire display. On some +terminals with more than one page of memory, it is possible to arrange +the termcap entry so that the @samp{ti} and @samp{te} strings (output +to the terminal when Emacs is entered and exited, respectively) switch +between pages of memory so as to use one page for Emacs and another +page for other output. On such terminals, you might want to set the variable +@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to +assume, when resumed, that the screen page it is using still contains +what Emacs last wrote there. + +@ignore + arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4 +@end ignore diff --cc doc/lispref/ChangeLog index b4a9c045cd4,00000000000..d95597e940b mode 100644,000000..100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@@ -1,6348 -1,0 +1,6364 @@@ +2007-10-13 Karl Berry + + * elisp.texi (@dircategory): Move to after @copying, + since we want @copying as close as possible to the beginning of + the output. + ++2007-10-12 Richard Stallman ++ ++ * elisp.texi (Top): Add Distinguish Interactive to subnode menu. ++ ++ * commands.texi (Distinguish Interactive): New node, ++ broken out from Interactive Call and rewritten. ++ (Command Loop): Put Distinguish Interactive in menu. ++ ++2007-10-09 Richard Stallman ++ ++ * text.texi (Examining Properties): Mention overlay priority. ++ ++ * display.texi (Display Margins): Correct the description ++ of margin display specifications. ++ (Replacing Specs): New subnode broken out of Display Property. ++ +2007-10-06 Juri Linkov + + * text.texi (Filling): Document fill-paragraph-or-region. + +2007-10-05 Juanma Barranquero + + * display.texi (Auto Faces): Fix typo. + +2007-10-02 Richard Stallman + + * display.texi (Display Property): Explain some display specs + don't let you move point in. + + * frames.texi (Cursor Parameters): Describe + cursor-in-non-selected-windows here. Explain more values. + + * windows.texi (Basic Windows): Don't describe + cursor-in-non-selected-windows here. + +2007-10-01 Eli Zaretskii + + * processes.texi (Misc Network): Note that these functions are + supported only on some systems. + +2007-10-01 Richard Stallman + + * display.texi (Overlay Properties): Explain nil as priority. + Explain that conflicts are unpredictable if not resolved by + priorities. + +2007-09-23 Richard Stallman + + * macros.texi (Backquote): Minor clarification. + +2007-09-19 Richard Stallman + + * display.texi (Display Property): Explain multiple display specs. + Clarify when they work in parallel and when one overrides. + Fix error in example. + +2007-09-06 Glenn Morris + + * Move from lispref/ to doc/lispref/. Change all setfilename + commands to use ../../info. + * Makefile.in (infodir): Go up one more level. + (usermanualdir): Change from ../man to ../emacs. + (miscmanualdir): New. + (dist): Use new variable miscmanualdir. + * makefile.w32-in (infodir, texinputdir): Go up one more level. + (usermanualdir): Change from ../man to ../emacs. + +2007-08-30 Martin Rudalics + + * commands.texi (Command Loop Info): Advise against changing + most variables described here. Explain new variable + last-repeatable-command. + +2007-08-29 Glenn Morris + + * elisp.texi (EMACSVER): Increase to 23.0.50. + +2007-08-29 Dan Nicolaescu + + * frames.texi (Basic Parameters): Add display-environment-variable + and term-environment-variable. + +2007-08-28 Juri Linkov + + * display.texi (Image Formats, Other Image Types): Add SVG. + +2007-08-28 Juri Linkov + + * display.texi (Images): Move formats-related text to new node + "Image Formats". + (Image Formats): New node. + +2007-08-27 Richard Stallman + + * windows.texi (Window Configurations): Clarify what + a window configuration saves. + +2007-08-25 Richard Stallman + + * display.texi (Images): Delete redundant @findex. + +2007-08-16 Richard Stallman + + * processes.texi (Asynchronous Processes): Clarify + doc of start-file-process. + +2007-08-08 Martin Rudalics + + * modes.texi (Example Major Modes): Fix typo. + +2007-08-08 Glenn Morris + + * intro.texi (nil and t): Do not use `iff' in documentation. + + * tips.texi (Documentation Tips): Recommend against `iff'. + +2007-08-07 Chong Yidong + + * display.texi (Image Cache): Document image-refresh. + +2007-08-06 Martin Rudalics + + * windows.texi (Size of Window): Document window-full-width-p. + +2007-07-25 Glenn Morris + + * gpl.texi (GPL): Replace license with GPLv3. + + * Relicense all FSF files to GPLv3 or later. + +2007-07-24 Michael Albinus + + * processes.texi (Synchronous Processes): + Add `process-file-shell-command'. + (Asynchronous Processes): Mention restricted use of + `process-filter' and `process-sentinel' in + `start-file-process'. Add `start-file-process-shell-command'. + +2007-07-17 Michael Albinus + + * files.texi (Magic File Names): Introduce optional parameter + IDENTIFICATION for `file-remote-p'. + +2007-07-16 Richard Stallman + + * display.texi (Defining Faces): Fix previous change. + +2007-07-14 Richard Stallman + + * control.texi (Handling Errors): Document `debug' in handler list. + +2007-07-10 Richard Stallman + + * display.texi (Defining Faces): Explain C-M-x feature for defface. + +2007-07-09 Richard Stallman + + * files.texi (Magic File Names): Rewrite previous change. + +2007-07-08 Michael Albinus + + * files.texi (Magic File Names): Introduce optional parameter + CONNECTED for `file-remote-p'. + +2007-07-07 Michael Albinus + + * processes.texi (Asynchronous Processes): + * files.texi (Magic File Names): Add `start-file-process'. + +2007-06-27 Richard Stallman + + * files.texi (Format Conversion Piecemeal): Clarify + `after-insert-file-functions' calling convention. + +2007-06-27 Michael Albinus + + * files.texi (Magic File Names): Remove `dired-call-process'. + Add `process-file'. + +2007-06-27 Kenichi Handa + + * text.texi (Special Properties): Fix description about + `composition' property. + +2007-06-26 Kenichi Handa + + * nonascii.texi (Default Coding Systems): Document about the + return value `undecided'. + +2007-06-25 David Kastrup + + * keymaps.texi (Active Keymaps): Document new POSITION argument of + `current-active-maps'. + +2007-06-24 Karl Berry + + * elisp.texi, vol1.texi, vol2.texi: New Back-Cover Text. + +2007-06-15 Juanma Barranquero + + * display.texi (Overlay Arrow): Doc fix. + +2007-06-14 Karl Berry + + * anti.texi (Antinews): Typo. + +2007-06-14 Chong Yidong + + * display.texi (Image Cache): Document image-refresh. + +2007-06-12 Karl Berry + + * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. + * two-volume.make: New file. + * .cvsignore: Ignore two-volume files. + +2007-06-12 Tom Tromey + + * os.texi (Init File): Document user-emacs-directory. + +2007-06-03 Nick Roberts + + * commands.texi (Click Events): Describe width and height when + object is nil. + +2007-05-30 Nick Roberts + + * commands.texi (Click Events): Layout more logically. Describe + width and height. + (Drag Events, Motion Events): Update to new format for position. + +2007-06-02 Richard Stallman + + * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. + +2007-06-02 Chong Yidong + + * Version 22.1 released. + +2007-06-01 Stefan Monnier + + * text.texi (Special Properties): Correct meaning of fontified face. + +2007-05-30 Richard Stallman + + * text.texi (Special Properties): Add link to Adjusting Point. + +2007-05-12 Richard Stallman + + * text.texi (Margins): indent-to-left-margin is not the default. + (Mode-Specific Indent): For indent-line-function, the default + is indent-relative. + + * modes.texi (Example Major Modes): Explain last line of text-mode + is redundant. + +2007-05-10 Richard Stallman + + * keymaps.texi (Scanning Keymaps): Update where-is-internal example. + + * help.texi (Keys in Documentation): Add reference to + Documentation Tips. + + * files.texi (Format Conversion): TO-FN gets three arguments. + + * modes.texi (Auto Major Mode): Document file-start-mode-alist. + +2007-05-10 Thien-Thi Nguyen + + * elisp.texi (Top): Remove "Saving Properties" from detailed menu. + * files.texi (Format Conversion): Expand intro; add menu. + (Format Conversion Overview, Format Conversion Round-Trip) + (Format Conversion Piecemeal): New nodes/subsections. + * hooks.texi: Xref "Format Conversion" , not "Saving Properties". + * text.texi (Text Properties): Remove "Saving Properties" from menu. + (Saving Properties): Delete node/subsection. + +2007-05-07 Karl Berry + + * elisp.texi (EMACSVER): Back to 22. + +2007-05-06 Richard Stallman + + * processes.texi (Accepting Output): Revert most of previous change. + +2007-05-05 Richard Stallman + + * processes.texi (Accepting Output): accept-process-output + uses microseconds, not milliseconds. But that arg is obsolete. + +2007-05-04 Karl Berry + + * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. + +2007-05-04 Eli Zaretskii + + * tips.texi (Documentation Tips): Rearrange items to place the + more important ones first. Add an index entry for hyperlinks. + +2007-05-03 Karl Berry + + * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. + (EMACSVER) [smallbook]: 22 for printed version. + + * control.texi (Signaling Errors) : texinfo.tex is fixed, + so restore anchor to normal position after defun. Found by Kevin Ryde. + +2007-04-26 Glenn Morris + + * elisp.texi (EMACSVER): Increase to 22.1.50. + +2007-04-28 Karl Berry + + * elisp.texi: Improve line breaks on copyright page, + similar layout to emacs manual, 8.5x11 by default. + +2007-04-24 Richard Stallman + + * text.texi (Special Properties): Add xref to Overlay Properties. + + * display.texi (Overlay Properties): Add xref to Special Properties. + +2007-04-22 Richard Stallman + + * keymaps.texi (Extended Menu Items): Move the info about + format with cached keyboard binding. + +2007-04-21 Richard Stallman + + * text.texi (Special Properties): Clarify previous change. + + * files.texi (File Name Expansion): Clarify previous change. + + * display.texi (Attribute Functions): Fix example for + face-attribute-relative-p. + +2007-04-19 Kenichi Handa + + * text.texi (Special Properties): Document composition property. + +2007-04-19 Glenn Morris + + * files.texi (File Name Expansion): Mention "superroot". + +2007-04-15 Chong Yidong + + * frames.texi (Multiple Displays): Add note about "multi-monitor" + setups. + (Display Feature Testing): Note that display refers to all + physical monitors for multi-monitor setups. + +2007-04-14 Richard Stallman + + * lists.texi (Sets And Lists): Clarify `delete' examples. + Remove spurious xref to same node. + Clarify xref for add-to-list. + +2007-04-12 Nick Roberts + + * keymaps.texi (Format of Keymaps): Remove spurious ")" from + value of lisp-mode-map. + +2007-04-11 Karl Berry + + * anti.texi (Antinews): + * display.texi (Overlay Properties, Defining Images): + * processes.texi (Synchronous Processes, Sentinels): + * syntax.texi (Syntax Table Internals): + * searching.texi (Regexp Special): + * nonascii.texi (Default Coding Systems): + * text.texi (Special Properties): + * minibuf.texi (Basic Completion): Wording to improve breaks in + 8.5x11 format. + * elisp.texi (smallbook): New @set to more easily switch between + smallbook and 8.5x11. + +2007-04-11 Richard Stallman + + * text.texi (Lazy Properties): Minor fix. + +2007-04-08 Karl Berry + + * symbols.texi (Plists and Alists): Period after "vs" in index entries. + * macros.texi (Backquote): Downcase Backquote in index entries for + consistency. + +2007-04-08 Richard Stallman + + * text.texi (Adaptive Fill): Just describe default, + don't show it (since it contains non-ASCII chars). + +2007-04-07 Karl Berry + + * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in + adaptive-fill-regexp's value, since they are not in the standard + TeX fonts. + +2007-04-07 Guanpeng Xu + + * display.texi (Defining Faces): Fix example. + +2007-04-07 Karl Berry + + * display.texi (Button Buffer Commands): Improve page break. + +2007-04-07 Richard Stallman + + * advice.texi (Activation of Advice): Remove redundant index entry. + + * backups.texi: Improve index entries. Remove redundant ones. + + * compile.texi (Byte Compilation): Improve index entry. + + * hash.texi (Creating Hash): Improve index entry. + + * symbols.texi (Definitions): Improve index entry. + + * edebug.texi: Improve index entries. Remove redundant/useless ones. + + * maps.texi (Standard Keymaps): Remove useless index entry. + + * help.texi (Documentation Basics): Remove redundant index entries. + + * customize.texi: Improve index entries. + Remove redundant/useless ones. + + * locals.texi (Standard Buffer-Local Variables): Clarify intro text. + + * streams.texi (Output Variables): Improve index entry. + + * abbrevs.texi (Abbrevs): Remove useless index entry. + + * macros.texi (Expansion): Remove useless index entry. + + * text.texi: Improve index entries. Remove redundant/useless ones. + (Text Properties, Examining Properties) + (Special Properties): Use "property category" instead of "category" + to refer to the `category' property. + + * positions.texi: Improve index entries. Remove useless one. + + * lists.texi: Improve index entries. Remove redundant/useless ones. + + * os.texi: Improve index entries. + (Timers): Fix previous change. + + * buffers.texi: Improve index entries. + (Modification Time): Get rid of term "obsolete buffer". + + * debugging.texi: Improve index entries. + (Test Coverage): Add xref to other test coverage ftr. + + * eval.texi: Improve index entry. Remove redundant ones. + + * numbers.texi: Improve index entries. Remove redundant/useless ones. + + * files.texi: Improve index entries. Remove redundant/useless ones. + + * objects.texi: Improve index entries. + + * processes.texi: Improve index entries. + + * modes.texi: Improve index entry. Remove redundant one. + + * nonascii.texi: Improve index entries. + + * internals.texi: Improve index entries. + + * syntax.texi: Improve index entries. + + * keymaps.texi (Active Keymaps): Improve index entries. + + * commands.texi: Improve index entries. Remove redundant/useless ones. + + * frames.texi: Improve index entries. Remove redundant/useless ones. + + * markers.texi: Improve index entries. Remove redundant ones. + + * tips.texi: Improve index entries. + + * loading.texi (Unloading): Improve index entry. + + * variables.texi: Improve index entries. Remove redundant one. + + * sequences.texi: Improve index entry. + + * display.texi: Improve index entries. Remove redundant ones. + + * windows.texi: Improve index entries. + + * searching.texi: Improve index entries. Remove redundant one. + + * strings.texi (Case Tables): Improve last change. + +2007-04-04 Chong Yidong + + * strings.texi (Case Tables): Document with-case-table and + ascii-case-table. + +2007-04-03 Karl Berry + + * processes.texi (Network): Reword to improve page break. + +2007-04-03 Eli Zaretskii + + * functions.texi (Inline Functions): Describe more disadvantages + of defsubst, and make advice against it stronger. + +2007-04-02 Karl Berry + + * backups.texi (Backup Names): Avoid widow words. + * modes.texi (Example Major Modes): Align last comment. + +2007-04-01 Chong Yidong + + * keymaps.texi (Remapping Commands): Document new arg to + command-remapping. + +2007-04-01 Karl Berry + + * processes.texi (Low-Level Network): Typo. + * loading.texi (Hooks for Loading): Avoid double "the". + * keymaps.texi (Key Sequences): No double "and". + (Changing Key Bindings): Shorten to improve line break. + +2007-03-31 Glenn Morris + + * os.texi (Timers): Fix description of run-at-time TIME formats. + +2007-03-31 Richard Stallman + + * display.texi (Invisible Text): Correct buffer-invisibility-spec + regarding ellipsis. + +2007-03-31 Eli Zaretskii + + * intro.texi (nil and t): + * symbols.texi (Plists and Alists): + * variables.texi (Variable Aliases, Constant Variables): + * functions.texi (Defining Functions): + * advice.texi (Advising Primitives): + * debugging.texi (Syntax Errors, Compilation Errors): + * minibuf.texi (Minibuffer Windows): + * commands.texi (Adjusting Point): + * modes.texi (Syntactic Font Lock, Faces for Font Lock) + (Auto Major Mode, Major Mode Conventions): + * help.texi (Describing Characters): + * files.texi (Create/Delete Dirs, Information about Files) + (File Locks, Writing to Files, Reading from Files) + (Saving Buffers): + * windows.texi (Resizing Windows, Cyclic Window Ordering): + * frames.texi (Finding All Frames): + * positions.texi (Buffer End, Motion): + * markers.texi (The Region): + * text.texi (Deletion, Near Point): + * display.texi (Displaying Messages, Truncation): + * os.texi (Processor Run Time): + * tips.texi (Key Binding Conventions, Programming Tips) + (Warning Tips, Documentation Tips, Comment Tips): + * internals.texi (Memory Usage): Improve indexing. + + * variables.texi (Frame-Local Variables): + * functions.texi (Argument List): + * loading.texi (Library Search): + * streams.texi (Output Variables): + * keymaps.texi (Translation Keymaps, Searching Keymaps): + * searching.texi (Replacing Match, Search and Replace): + * processes.texi (Byte Packing, Decoding Output) + (Accepting Output, Network Servers, Shell Arguments): + * display.texi (Abstract Display, Image Cache, Scroll Bars): + * windows.texi (Window Point, Window Start): + * frames.texi (Management Parameters, Frame Parameters, Frame Titles): + * commands.texi (Reading Input, Keyboard Events): + * minibuf.texi (Reading File Names, Minibuffer Completion) + (Recursive Mini): + * positions.texi (List Motion): + * hash.texi (Hash Tables, Creating Hash, Defining Hash): + * numbers.texi (Arithmetic Operations, Math Functions) + (Predicates on Numbers, Comparison of Numbers): + (Numeric Conversions): + * locals.texi (Standard Buffer-Local Variables): + * maps.texi (Standard Keymaps): + * os.texi (User Identification, System Environment, Recording Input) + (X11 Keysyms): + * nonascii.texi (Non-ASCII Characters, Splitting Characters): + * backups.texi (Backups and Auto-Saving): + * customize.texi (Customization, Group Definitions) + (Variable Definitions): + * compile.texi (Byte Compilation): Improve index entries. + +2007-03-31 Karl Berry + + * macros.texi (Defining Macros): Avoid widow syllable. + +2007-03-31 Eli Zaretskii + + * elisp.texi (Top): Postscript -> PostScript. + + * display.texi (Images, Postscript Images): Postscript -> PostScript. + +2007-03-31 Markus Triska + + * internals.texi (Writing Emacs Primitives): Untabify `For'. + +2007-03-30 Karl Berry + + * lists.texi (List-related Predicates): Remove spurious @need. + (Setcdr): Use @smallexample to improve page break. + (Association Lists) : Reword to improve page break. + + * strings.texi (String Conversion): Insert blank line to improve + page break. + + * numbers.texi (Random Numbers): Use @minus{}. + (Math Functions): Use @minus{}. + + * intro.texi (Acknowledgements): Avoid line breaks before middle + initials. + +2007-03-24 Eli Zaretskii + + * errors.texi (Standard Errors): Add an index entry. + +2007-03-19 Richard Stallman + + * os.texi (Recording Input): recent-keys now gives 300 keys. + +2007-03-12 Glenn Morris + + * os.texi: Replace "daylight savings" with "daylight saving" + throughout. + +2007-03-05 Richard Stallman + + * variables.texi (File Local Variables): Update + enable-local-variables values. + +2007-03-04 Richard Stallman + + * syntax.texi (Control Parsing): Minor clarification. + + * strings.texi (Formatting Strings): Clarify width, precision, flags. + + * sequences.texi (Sequence Functions): Move string-bytes away, + add xref. + + * nonascii.texi (Text Representations): Move string-bytes here. + + * modes.texi (Major Mode Conventions): Fundamental mode is exception. + + * minibuf.texi (Basic Completion): Minor clarification. + + * markers.texi (The Mark): Clarify existence vs activation of mark. + Other cleanup. + + * display.texi (Finding Overlays): Write better example. + + * compile.texi (Eval During Compile): Clarify putting macros + in eval-when-compile. + +2007-02-25 Vinicius Jose Latorre + + * loading.texi (How Programs Do Loading): Fix anchor position at + load-read-function definition doc. (tiny change) + +2007-02-21 Kim F. Storm + + * strings.texi (Text Comparison): Mention that assoc-string + converts symbols to strings before testing. + +2007-02-17 Kim F. Storm + + * processes.texi (Bindat Spec): Vector types can have optional + element type. + (Bindat Examples): Fix example. Add vector with element type. + +2007-02-16 Andreas Schwab + + * strings.texi (Formatting Strings): Document '+' flag. + +2007-02-15 Juanma Barranquero + + * strings.texi (Modifying Strings): Clarify that `clear-string' + always converts the string to unibyte. + +2007-02-14 Kim F. Storm + + * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. + Rewrite glyph code description to refer to these functions. + Remove details of encoding face number and char into integer code. + +2007-02-03 Alan Mackenzie + + * loading.texi (Hooks for Loading): Make the description of + `eval-after-load' more detailed, and amend the description of + after-load-alist, in accordance with changes from 2006-05. + +2007-02-03 Chong Yidong + + * modes.texi (Defining Minor Modes): Document that a :require + keyword or similar may be required to make saved customization + variables work. + +2007-02-03 Eli Zaretskii + + * elisp.texi (Top): Make the detailed menu headers compliant with + Texinfo guidelines and with what texnfo-upd.el expects. Add + comments to prevent people from inadvertently modifying the key + parts needed by `texinfo-multiple-files-update'. + +2007-02-02 Eli Zaretskii + + * elisp.texi (Top): Update the top-level menus. + + * syntax.texi (Categories): Add index entries. + +2007-02-01 Juanma Barranquero + + * display.texi (Attribute Functions): Fix name and description of + the UNDERLINE arg of `set-face-underline-p'. + +2007-01-29 Eli Zaretskii + + * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local + Variables", and "Standard Keymaps" to the detailed menu. + + * variables.texi (Future Local Variables): Add index entry. + +2007-01-28 Richard Stallman + + * tips.texi (Coding Conventions): Clarify the tip about macros + that define a function or a variable. + + * files.texi (File Attributes): UID and GID can be floats. + (Magic File Names): Explain why deferring all operations to + the standard handler does not work. + +2007-01-23 Martin Rudalics + + * backups.texi (Reverting): Use "buffer" instead of "file" + when talking about major and minor modes. + +2007-01-21 Richard Stallman + + * help.texi (Documentation): Add xref to Documentation Tips. + +2007-01-14 Juanma Barranquero + + * tips.texi (Coding Conventions): Fix typos. + +2007-01-05 Richard Stallman + + * modes.texi (Defining Minor Modes): Fix previous change. + +2007-01-03 Richard Stallman + + * customize.texi (Variable Definitions, Customization Types): + Don't use * in doc string for defcustom. + +2007-01-02 Richard Stallman + + * variables.texi (Variable Aliases): Clarify that aliases vars + always have the same value. + + * processes.texi (Bindat Spec): Fix Texinfo usage. + + * modes.texi (Defining Minor Modes): Explain effect of command + defined with define-global-minor-mode on new buffers. + +2006-12-30 Kim F. Storm + + * keymaps.texi (Tool Bar): Describe `grow-only' value of + `auto-resize-tool-bars'. + +2006-12-30 Richard Stallman + + * keymaps.texi (Active Keymaps): Fix previous change. + +2006-12-30 Nick Roberts + + * keymaps.texi (Active Keymaps): Make xref to lookup-key. + +2006-12-30 Kim F. Storm + + * processes.texi (Bindat Spec): Clarify using field names in + length specifications. + +2006-12-29 Kim F. Storm + + * processes.texi (Bindat Spec): Explain eval forms and lengths better. + Add count and index variables for eval forms in repeat blocks. + +2006-12-24 Richard Stallman + + * customize.texi (Variable Definitions): Document + new name custom-add-frequent-value. + +2006-12-19 Kim F. Storm + + * commands.texi (Misc Events): User signals now result in sigusr1 + and sigusr2 events which are handled through special-event-map. + (Special Events): User signals and drag-n-drop are special. + +2006-12-17 Richard Stallman + + * loading.texi (Named Features): Explain subfeatures better. + + * customize.texi: Use "option" only for user options. + For the keyword values inside defcustom etc, say "keywords". + For :options value's elements, say "elements". + :group should not be omitted. + + * syntax.texi (Parsing Expressions): Split up node. + (Motion via Parsing, Position Parse, Parser State) + (Low-Level Parsing, Control Parsing): New subnodes. + (Parser State): Document syntax-ppss-toplevel-pos. + + * positions.texi (List Motion): Punctuation fix. + + * files.texi (File Name Completion): Document PREDICATE arg + to file-name-completion. + +2006-12-16 Eli Zaretskii + + * internals.texi (Building Emacs, Writing Emacs Primitives): + Add index entries. + +2006-12-11 Richard Stallman + + * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults + affects face menu. Explain how to make it non-nil without enabling + any fontification. + +2006-12-10 Chong Yidong + + * modes.texi (Font Lock Basics): Document nil value of + font-lock-defaults. + +2006-12-10 Glenn Morris + + * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force + value for system-flag argument. Abbrev tables may not be empty + when major modes are loaded. + +2006-12-08 Juanma Barranquero + + * makefile.w32-in (maintainer-clean): Partially revert last + change; delete "elisp-?" and "elisp-??" instead of "elisp-*" + to protect elisp-covers.texi. + +2006-12-07 Juanma Barranquero + + * makefile.w32-in (maintainer-clean): Depend on `distclean'. + Don't remove elisp* info files; they are already deleted by the + `clean' and `distclean' targets, and they are in the $(infodir) + directory, not the current one. + +2006-12-04 Kim F. Storm + + * commands.texi (Misc Events): Update signal events. + (Event Examples): Add signal example. + +2006-11-29 Richard Stallman + + * frames.texi (Visibility of Frames): Explain visible windows + can be covered by others. Add xref for raise-frame. + +2006-11-28 Richard Stallman + + * searching.texi (Regexp Special): Update when ^ is special. + +2006-11-27 Eli Zaretskii + + * customize.texi (Customization, Common Keywords) + (Group Definitions, Variable Definitions, Composite Types) + (Type Keywords, Customization Types): Add index entries for + various customization keywords. + +2006-11-23 Stefan Monnier + + * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. + +2006-11-10 Jan Dj,Ad(Brv + + * frames.texi (Window System Selections): Remove clipboard from + description of selection-coding-system. + +2006-11-06 Richard Stallman + + * lists.texi (List Variables): Document COMPARE-FN. + + * keymaps.texi: Avoid use of "binding" to mean a relation; + use it only to refer to the meaning associated with a key. + (Keymaps): Change menu node description. + + * elisp.texi (Top): Change menu node description. + + * display.texi (Managing Overlays): Document overlay-recenter. + +2006-10-29 Chong Yidong + + * Makefile.in: Use relative paths to avoid advertising filesystem + contents during compilation. + +2006-10-23 Kim F. Storm + + * commands.texi (Event Input Misc): Update unread-command-events. + +2006-10-23 Nick Roberts + + * lists.texi (Sets And Lists): Fix typos. + +2006-10-18 Juanma Barranquero + + * control.texi (Processing of Errors): Use @var for an argument, + not @code. + +2006-10-16 Richard Stallman + + * edebug.texi (Edebug Recursive Edit): Minor cleanup. + + * keymaps.texi (Format of Keymaps): Show all the keymap element + patterns that result from menu items. + (Key Lookup): Minor cleanups. + + * modes.texi (Precalculated Fontification): Don't say that + not setting font-lock-defaults avoids loading font-lock. + + * help.texi (Documentation): Move xref to Emacs Manual here. + (Documentation Basics): From here. + Also doc emacs-lisp-docstring-fill-column. + + * elisp.texi: Update version and ISBN. + + * commands.texi (Interactive Call): Clarify KEYS arg to + call-interactively is a vector. + (Command Loop Info): Delete anchor in this-command-keys. + Add anchor in this-command-keys-vector. + (Recursive Editing): Document how recursive-edit + handles the current buffer. + +2006-10-13 Chong Yidong + + * frames.texi (Frame Titles): %c and %l are ignored in + frame-title-format. + +2006-10-11 Richard Stallman + + * keymaps.texi (Key Sequences): Clarify use of kbd. + +2006-10-10 Kim F. Storm + + * lists.texi (Sets And Lists): Add memql. + +2006-10-03 Richard Stallman + + * searching.texi (Char Classes): Document :multibyte: and :unibyte:. + Clarify :ascii: and :nonascii:. + +2006-09-29 Juri Linkov + + * modes.texi (%-Constructs): Reorder coding systems in the + documentation of %z to the real order displayed in the modeline. + +2006-09-25 Richard Stallman + + * os.texi (Timers): Describe timer-max-repeats. + +2006-09-25 Chong Yidong + + * os.texi (Timers): Mention with-local-quit. + +2006-09-24 Richard Stallman + + * searching.texi (Searching and Matching): Mention property search. + + * commands.texi (Command Loop Info): Explain how read-event affects + this-command-keys. + +2006-09-20 Richard Stallman + + * os.texi (Timers): Clarify about REPEAT when timer is delayed. + + * windows.texi (Window Start): Minor cleanups. + +2006-09-20 Kim F. Storm + + * windows.texi (Window Start): pos-visible-in-window-p allows + specifying t for position to mean "end of window". + Add window-line-height. + + * anti.texi (Antinews): Mention window-line-height. + +2006-09-19 David Kastrup + + * keymaps.texi (Searching Keymaps): Small clarification. + +2006-09-18 Richard Stallman + + * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings + cause keyboard menus. + (Menu Keymaps): Likewise. + (Defining Menus, Keyboard Menus): Clarify. + + * text.texi (Fields): Clarify explanation of constrain-to-field. + +2006-09-16 Eli Zaretskii + + * variables.texi (Tips for Defining): Fix a typo. + +2006-09-15 Richard Stallman + + * keymaps.texi (Remapping Commands, Searching Keymaps) + (Active Keymaps): Clean up previous change. + +2006-09-15 Jay Belanger + + * gpl.texi: Replace "Library Public License" by "Lesser Public + License" throughout. + +2006-09-15 David Kastrup + + * keymaps.texi (Active Keymaps): Adapt description to use + `get-char-property' instead `get-text-property'. Explain how + mouse events change this. Explain the new optional argument of + `key-binding' and its mouse-dependent lookup. + (Searching Keymaps): Adapt description similarly. + (Remapping Commands): Explain the new optional argument of + `command-remapping'. + +2006-09-14 Richard Stallman + + * keymaps.texi (Searching Keymaps): Clarification. + (Active Keymaps): Refer to Searching Keymaps instead of duplication. + +2006-09-13 Richard Stallman + + * objects.texi (Character Type): Node split. + Add xref to Describing Characters. + (Basic Char Syntax, General Escape Syntax) + (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. + +2006-09-11 Richard Stallman + + * display.texi (Display Table Format): Wording clarification. + (Glyphs): Clarifications. + +2006-09-10 Chong Yidong + + * keymaps.texi (Active Keymaps): Mention that key-binding checks + local maps. + +2006-09-10 Kim F. Storm + + * display.texi (Forcing Redisplay): Document return value of + function redisplay. + +2006-09-09 Richard Stallman + + * windows.texi (Window Hooks): Explain limits of + window-scroll-functions. + + * display.texi (Fringe Indicators): Update for last change in + indicate-buffer-boundaries. + +2006-09-08 Richard Stallman + + * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. + +2006-09-06 Kim F. Storm + + * frames.texi (Display Feature Testing): display-mm-dimensions-alist. + + * windows.texi (Window Start): Update pos-visible-in-window-p. + +2006-09-04 Richard Stallman + + * processes.texi (Accepting Output): Explain SECONDS=0 for + accept-process-output. + + * os.texi (Idle Timers): Explain why timer functions should not + loop until (input-pending-p). + +2006-09-02 Eli Zaretskii + + * makefile.w32-in (usermanualdir): New variable. + (elisp.dvi): Use it. + +2006-09-01 Eli Zaretskii + + * buffers.texi (Buffer Modification): Fix last change. + +2006-09-01 Chong Yidong + + * buffers.texi (Buffer Modification): Document + buffer-chars-modified-tick. + +2006-08-31 Richard Stallman + + * modes.texi (Syntactic Font Lock): Mention specific faces once again. + +2006-08-31 Richard Bielawski (tiny change) + + * modes.texi (Syntactic Font Lock): + Mention font-lock-syntactic-face-function + instead of specific faces. + +2006-08-29 Chong Yidong + + * display.texi (Images): Add xrref to display-images-p. + +2006-08-28 Kenichi Handa + + * nonascii.texi (Lisp and Coding Systems): Fix description of + detect-coding-region. + +2006-08-27 Michael Olson + + * processes.texi (Transaction Queues): Remove stray quote + character. + +2006-08-25 Richard Stallman + + * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. + Add xref. + +2006-08-24 Chong Yidong + + * os.texi (Timers): Avoid waiting inside timers. + +2006-08-21 Lute Kamstra + + * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. + +2006-08-20 Richard Stallman + + * os.texi (Idle Timers): New node, split out from Timers. + Document current-idle-time. + * commands.texi (Reading One Event): Update xref. + * elisp.texi (Top): Update subnode menu. + +2006-08-16 Richard Stallman + + * keymaps.texi (Extended Menu Items): Show format of cached + bindings in extended menu items. + + * customize.texi (Variable Definitions): Explain when the + standard value expression is evaluated. + +2006-08-15 Chong Yidong + + * commands.texi (Reading One Event): Explain idleness in + `read-event'. + +2006-08-12 Chong Yidong + + * text.texi (Near Point): Say "cursor" not "terminal cursor". + (Commands for Insertion): Removed split-line since it's not + relevant for Lisp programming. + (Yank Commands): Rewrite introduction. + (Undo): Clarify. + (Maintaining Undo): Clarify. Document undo-ask-before-discard. + (Filling): Remove redundant comment. Clarify return value of + current-justification. + (Margins): Minor clarifications. + (Adaptive Fill): Update default value of adaptive-fill-regexp. + (Sorting): Update definition of sort-lines. + (Columns): Clarify behavior of sort-columns. + (Indent Tabs): Link to Tab Stops in Emacs manual. + (Special Properties): Clarify. + (Clickable Text): Mention Buttons package. + +2006-08-12 Kevin Ryde + + * os.texi (Time Parsing): Add %z to description of + format-time-string, as per docstring. Add cross reference to + glibc manual for strftime. + +2006-08-08 Richard Stallman + + * modes.texi: Clean up wording in previous change. + +2006-08-07 Chong Yidong + + * modes.texi (Hooks): Clarify. + (Major Mode Basics): Mention define-derived-mode explicitly. + (Major Mode Conventions): Rebinding RET is OK for some modes. + Mention change-major-mode-hook and after-change-major-mode-hook. + (Example Major Modes): Moved to end of Modes section. + (Mode Line Basics): Clarify. + (Mode Line Data): Mention help-echo and local-map in strings. + Explain reason for treatment of non-risky variables. + (Properties in Mode): Clarify. + (Faces for Font Lock): Add font-lock-negation-char-face. + +2006-08-04 Eli Zaretskii + + * strings.texi (Formatting Strings): Warn against arbitrary + strings as first arg to `format'. + +2006-07-31 Thien-Thi Nguyen + + * text.texi (Clickable Text): Mention `help-echo' text property. + Update intro, examples and associated explanations. + +2006-07-31 Richard Stallman + + * commands.texi: Update xrefs. + (Event Mod): New node, cut out from old Translating Input. + + * maps.texi: Update xrefs. + + * keymaps.texi (Translation Keymaps): New node. + Update xrefs from Translating Input to Translation Keymaps. + + * elisp.texi (Top): Update subnode menu. + + * display.texi (Face Functions): Fix explanations of FRAME=t or nil. + + * os.texi (System Interface): Fix menu descriptions of some nodes. + (Translating Input): Node deleted. + +2006-07-31 Nick Roberts + + * modes.texi (Minor Mode Conventions): Update xref for add-to-list. + + * lists.texi (Sets And Lists): Likewise. + +2006-07-30 Thien-Thi Nguyen + + * text.texi (Fields): Mention POS + requirement when narrowing is in effect. + +2006-07-28 Richard Stallman + + * display.texi (Face Attributes): Simplify wording. + (Attribute Functions): Clarify meaning of new-frame default + attribute settings. + + * customize.texi (Common Keywords): Document how to use + :package-version in a package not in Emacs. + +2006-07-28 Kim F. Storm + + * commands.texi (Reading One Event): Fix last change. + +2006-07-26 Chong Yidong + + * commands.texi (Reading One Event): Document SECONDS argument for + read-event, read-char, and read-char-exclusive. + +2006-07-25 Stefan Monnier + + * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline + to ensure correct identification. + +2006-07-24 Richard Stallman + + * text.texi (Clickable Text): Clarify. + + * sequences.texi (Vector Functions): Delete duplicate xref. + + * objects.texi (Function Type): Clarify. + + * modes.texi (Keymaps and Minor Modes): List punct chars for minor + modes. + + * lists.texi (List Variables): New node. + Material moved from other nodes. + + * variables.texi (Setting Variables): add-to-list and + add-to-ordered-list moved to List Variables node. + +2006-07-23 Thien-Thi Nguyen + + * text.texi (Links and Mouse-1): + For mouse-on-link-p, expand on arg POS. + +2006-07-21 Kim F. Storm + + * display.texi (Forcing Redisplay): Don't mention systems which + don't support sub-second timers for redisplay-preemption-period. + + * os.texi (Terminal Output): Clarify text vs graphical terminal. + +2006-07-21 Eli Zaretskii + + * frames.texi (Input Focus): Document that focus-follows-mouse has + no effect on MS-Windows. + +2006-07-18 Richard Stallman + + * display.texi (Forcing Redisplay): Cleanups in previous change. + + * processes.texi (Low-Level Network): Make menu more convenient. + +2006-07-18 Kim F. Storm + + * display.texi (Forcing Redisplay): redisplay-preemption-period + only used on window systems. Add xref to Terminal Output. + + * os.texi (Terminal Output): baud-rate only controls preemption on + non-window systems. Add xref to Forcing Redisplay. + + * processes.texi (Low-Level Network): Rename node "Make Network" + to "Network Processes". + +2006-07-18 Karl Berry + + * variables.texi, functions.texi, customize.texi, loading.texi: + * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. + +2006-07-17 Chong Yidong + + * commands.texi (Waiting): Document batch-mode sit-for behavior. + +2006-07-17 Richard Stallman + + * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. + Put period and comma inside quotes. + + * loading.texi, markers.texi: Use real doublequote inside menus. + + * windows.texi: Put point and comma inside quotes. + (Textual Scrolling): Use @samp for error message. + + * variables.texi, tips.texi, syntax.texi, symbols.texi: + * strings.texi, streams.texi, processes.texi, os.texi: + * objects.texi, numbers.texi, modes.texi, minibuf.texi: + * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: + * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: + * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: + Put point and comma inside quotes. + + * control.texi (Processing of Errors): Add command-error-function. + + * variables.texi (File Local Variables): Clarify that + file local variables make buffer-local bindings. + + * modes.texi (Syntactic Font Lock): Give default for + font-lock-syntax-table. + +2006-07-17 Nick Roberts + + * text.texi (Special Properties): Clean up previous change. + +2006-07-16 Karl Berry + + * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: + * control.texi: Fix bad page breaks through chapter 10 (control). + + * anti.texi (Antinews): Reorder face-attribute fns to avoid + underfull hbox. + +2006-07-15 Nick Roberts + + * text.texi (Special Properties): Describe fontified text property + in relation to a character (not text). + +2006-07-15 Kim F. Storm + + * maps.texi (Standard Keymaps): Add xref for minibuffer maps. + Add apropos-mode-map, custom-mode-map, esc-map, global-map, + grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. + + * anti.texi (Antinews): Mention redisplay function. + The kbd macro existed, but was not documented, before 22.x. + Function pos-visible-in-window-p is not new in 22.x, just enhanced. + +2006-07-14 Nick Roberts + + * display.texi (Displaying Messages): Add anchor. + + * frames.texi (Dialog Boxes): Use it. + +2006-07-12 Richard Stallman + + * objects.texi (Frame Type): Explain nature of frames better. + + * frames.texi (Frames): Explain nature of frames better. + +2006-07-12 Ken Manheimer + + * tips.texi (Coding Conventions): Explain why use cl at compile time. + +2006-07-12 YAMAMOTO Mitsuharu + + * frames.texi (Window System Selections): Mention scrap support for Mac. + Default value of x-select-enable-clipboard is t on Mac. + + * os.texi (Getting Out): Suspending is not allowed on Mac, either. + +2006-07-11 Kim F. Storm + + * display.texi (Forcing Redisplay): Add `redisplay' function. + Don't mention (sit-for -1) -- use (redisplay t) instead. + + * commands.texi (Waiting): (sit-for -1) is no longer special. + (sit-for 0) is equivalent to (redisplay). + Iconifying/deiconifying no longer makes sit-for return. + +2006-07-10 Nick Roberts + + * display.texi (Buttons): Fix typo. + + * index.texi, elisp.texi (New Symbols): Comment node out. + +2006-07-09 Richard Stallman + + * display.texi (Truncation): Clean up previous change. + +2006-07-08 Richard Stallman + + * commands.texi (Interactive Call): Use 3 as prefix in example + for execute-extended-command. + + * display.texi (Attribute Functions): Move paragraph about + compatibility with Emacs < 21. + +2006-07-09 Kim F. Storm + + * display.texi (Refresh Screen): Clarify force-window-update. + (Truncation): "Normally" indicated by fringe arrows. + +2006-07-08 Eli Zaretskii + + * windows.texi (Textual Scrolling, Resizing Windows): + * variables.texi (Constant Variables): + * text.texi (Buffer Contents, Deletion, Changing Properties) + (Property Search, Special Properties, Sticky Properties) + (Links and Mouse-1, Fields, Change Hooks): + * syntax.texi (Syntax Table Functions, Parsing Expressions) + (Categories): + * symbols.texi (Other Plists): + * streams.texi (Output Variables): + * processes.texi (Input to Processes, Query Before Exit): + * positions.texi (Word Motion, Text Lines, List Motion): + * os.texi (Init File, System Environment, Sound Output) + (Session Management): + * nonascii.texi (Text Representations, Character Sets) + (Chars and Bytes, Locales): + * modes.texi (Defining Minor Modes, Header Lines): + * minibuf.texi (Minibuffer Contents): + * markers.texi (Information from Markers): + * lists.texi (List Elements, Building Lists, Association Lists): + * keymaps.texi (Tool Bar): + * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): + * functions.texi (What Is a Function, Mapping Functions): + * frames.texi (Creating Frames, Parameter Access, Pointer Shape) + (Color Names, Text Terminal Colors, Display Feature Testing): + * files.texi (Visiting Functions, File Name Components) + (Unique File Names, Contents of Directories): + * display.texi (Forcing Redisplay, Displaying Messages) + (Temporary Displays, Font Selection, Auto Faces) + (Font Lookup, Fringe Indicators, Display Margins) + (Image Descriptors, Showing Images, Image Cache, Button Types) + (Making Buttons, Manipulating Buttons, Button Buffer Commands) + (Display Table Format, Glyphs): + * control.texi (Iteration): + * commands.texi (Command Loop Info, Adjusting Point): + * backups.texi (Making Backups, Auto-Saving): + Remove @tindex entries. + +2006-07-07 Kim F. Storm + + * display.texi (Fringe Cursors): Fix typo. + (Customizing Bitmaps): Fix define-fringe-bitmap entry. + (Overlay Arrow): Default is overlay-arrow fringe indicator. + +2006-07-05 Richard Stallman + + * text.texi (Buffer Contents): Add example of text props + in result of buffer-substring. + (Text Properties): Explain better about use of specific property names. + (Property Search): Some cleanups; reorder some functions. + + * keymaps.texi (Changing Key Bindings): Cleanup. + Add xref to Key Binding Conventions. + + * display.texi (Attribute Functions): Add examples for + face-attribute-relative-p. + + * tips.texi (Coding Conventions): Cleanup last change. + +2006-07-05 Karl Berry + + * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. + Remove @setchapternewpage odd. + Result is 1013 pages, down from 1100. + + * anti.texi, customize.texi, display.texi, internals.texi: + * minibuf.texi, modes.texi, tips.texi: + Fix overfull/underfull boxes. + +2006-07-05 Thien-Thi Nguyen + + * edebug.texi (Instrumenting): + Add Edebug-specific findex for eval-buffer. + * loading.texi (Loading): + Replace eval-current-buffer with eval-buffer. + +2006-06-30 Nick Roberts + + * locals.texi (Standard Buffer-Local Variables): Update the list + of variables. + +2006-06-26 Nick Roberts + + * files.texi (File Name Completion): Point user to the node + "Reading File Names". + +2006-06-24 Eli Zaretskii + + * files.texi (Contents of Directories): Document case-insensitive + behavior on respective filesystems. + + * objects.texi (Character Type): Document that Emacs signals an + error for unsupported Unicode characters specified as \uNNNN. + +2006-06-19 Richard Stallman + + * processes.texi (Bindat Spec): Clarify previous change. + +2006-06-16 Richard Stallman + + * tips.texi (Coding Conventions): Better explain conventions + for definition constructs. + + * text.texi (Special Properties): String value of `read-only' + serves as the error message. + + * objects.texi (Character Type): Clarify prev. change. + (Non-ASCII in Strings): Mention \u and \U. + + * commands.texi (Using Interactive): Explain problem of + markers, etc., in command-history. + +2006-06-14 Kim F. Storm + + * commands.texi (Waiting): Negative arg to sit-for forces + redisplay even if input is pending. + + * display.texi (Forcing Redisplay): Use (sit-for -1) to force a + redisplay. Remove incorrect example of binding redisplay-dont-pause + around (sit-for 0). + +2006-06-13 Richard Stallman + + * display.texi (Forcing Redisplay): Clarify previous change. + +2006-06-13 Romain Francoise + + * display.texi (Forcing Redisplay): Fix typo. + +2006-06-13 Kim F. Storm + + * display.texi (Forcing Redisplay): Add redisplay-preemption-period. + +2006-06-10 Luc Teirlinck + + * tips.texi (Coding Conventions): Add `@end itemize'. + +2006-06-10 Richard Stallman + + * tips.texi (Coding Conventions): Explain use of coding systems + to ensure one decoding for strings. + +2006-06-09 Aidan Kehoe + + * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF + syntax. + +2006-06-07 Eli Zaretskii + + * display.texi (Font Selection): Remove description of + clear-face-cache. + + * compile.texi (Eval During Compile): Fix a typo. Add index + entries for possible uses of eval-when-compile. + +2006-06-04 Thien-Thi Nguyen + + * display.texi (Abstract Display): Fix typo. + +2006-06-03 Eli Zaretskii + + * minibuf.texi (Minibuffer History) : + Reword variable's description. + +2006-06-01 Richard Stallman + + * windows.texi (Splitting Windows): Clarify splitting nonselected + window. + +2006-05-31 Juri Linkov + + * minibuf.texi (Minibuffer History): Add history-add-new-input. + +2006-05-30 Richard Stallman + + * display.texi (Line Height): Fix errors in description of + default line height and line-height properyty. + + * nonascii.texi (Default Coding Systems): Further clarification. + +2006-05-29 Luc Teirlinck + + * internals.texi (Pure Storage): Mention that an overflow in pure + space causes a memory leak. + (Garbage Collection): If there was an overflow in pure space, + `garbage-collect' returns nil. + +2006-05-30 Eli Zaretskii + + * nonascii.texi (Default Coding Systems): Fix it some more. + +2006-05-29 Eli Zaretskii + + * nonascii.texi (Default Coding Systems): Fix last change. + +2006-05-29 Kenichi Handa + + * nonascii.texi (find-operation-coding-system): Describe the new + argument format (FILENAME . BUFFER). + +2006-05-28 Richard Stallman + + * tips.texi (Coding Conventions): Better explain reasons not to + advise other packages or use `eval-after-load'. + +2006-05-29 Kim F. Storm + + * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to + `bindat-idx' and `bindat-raw' for clarity. + +2006-05-27 Thien-Thi Nguyen + + * processes.texi (Bindat Spec): Expand on `repeat' handler. + + * display.texi (Display): Add "Abstract Display" to menu. + (Abstract Display, Abstract Display Functions) + (Abstract Display Example): New nodes. + * elisp.texi (Top): Add "Abstract Display" to menu. + +2006-05-27 Chong Yidong + + * keymaps.texi (Key Sequences): Link to input events definition. + (Format of Keymaps): Delete material duplicated in Keymap Basics. + + * files.texi (Changing Files): Document updated argument list for + copy-file. + +2006-05-27 Thien-Thi Nguyen + + * processes.texi (Bindat Functions): Explain term "total length". + Use it in bindat-length and bindat-pack descriptions. + +2006-05-26 Eli Zaretskii + + * tips.texi (Coding Conventions): Advise against using + eval-after-load in packages. Add an index entry. + +2006-05-25 Juri Linkov + + * minibuf.texi (Text from Minibuffer): Undocument keep-all. + + * modes.texi (%-Constructs): Add %e, %z, %Z. + +2006-05-25 Richard Stallman + + * elisp.texi (Top): Update subnode menu. + + * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. + (Keymaps): Update menu. + +2006-05-25 Chong Yidong + + * keymaps.texi (Key Sequences): Some clarifications. + +2006-05-25 Thien-Thi Nguyen + + * processes.texi (Bindat Functions): Say "unibyte string" + explicitly for bindat-unpack and bindat-pack descriptions. + (Bindat Examples): Don't call `string-make-unibyte' in example. + +2006-05-25 Chong Yidong + + * keymaps.texi (Key Sequences): Renamed from Keymap Terminology. + Explain string and vector representations of key sequences + + * keymaps.texi (Changing Key Bindings): + * commands.texi (Interactive Codes, Interactive Codes): + * help.texi (Describing Characters): Refer to it. + +2006-05-23 Luc Teirlinck + + * frames.texi (Pointer Shape): @end table -> @end defvar. + +2006-05-22 Richard Stallman + + * elisp.texi (Top): Update subnode menus. + + * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. + Contents rewritten; material from old Pointer Shape node moved here. + + * display.texi (Pointer Shape): Node deleted. + (Image Descriptors): Minor cleanup. + +2006-05-21 Richard Stallman + + * syntax.texi (Parsing Expressions): Update info on which STATE + elements are ignored. + +2006-05-19 Luc Teirlinck + + * hooks.texi (Standard Hooks): Correct typo. + + * gpl.texi (GPL): ifinfo -> ifnottex. + +2006-05-19 Michael Ernst (tiny change) + + * searching.texi (Simple Match Data): Warn about match data being + set anew by every search. + +2006-05-17 Richard Stallman + + * minibuf.texi (Minibuffer History): Clarify. + + * searching.texi (Regexp Special): Clarify nested regexp warning. + +2006-05-16 Kim F. Storm + + * minibuf.texi (Minibuffer History): Update add-to-history. + +2006-05-15 Oliver Scholz (tiny change) + + * nonascii.texi (Explicit Encoding): Fix + typo (encoding<->decoding). + +2006-05-14 Richard Stallman + + * buffers.texi (Creating Buffers): Cleanup. + + * files.texi (Visiting Functions): Rewrite in find-file-noselect. + +2006-05-13 Eli Zaretskii + + * buffers.texi (Current Buffer): Document that with-temp-buffer + disables undo. + + * os.texi (Terminal-Specific): More accurate description of how + Emacs searches for the terminal-specific libraries. + +2006-05-12 Eli Zaretskii + + * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to + emacs-xtra to @inforef's. + + * text.texi (Undo): Document that undo is turned off in buffers + whose names begin with a space. + + * buffers.texi (Buffer Names): Add index entries for buffers whose + names begin with a space. + (Creating Buffers): Document that undo is turned off in buffers + whose names begin with a space. + + * files.texi (Visiting Functions, Reading from Files) + (Saving Buffers): Mention code and EOL conversions by file I/O + primitives and subroutines. + + * nonascii.texi (Lisp and Coding Systems): Document + coding-system-eol-type. Add index entries for eol conversion. + + * display.texi (Defining Faces): Mention `mac', and add an xref to + where window-system is described. + +2006-05-10 Richard Stallman + + * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. + +2006-05-10 Reiner Steib + + * variables.texi (File Local Variables): Recommend to quote lambda + expressions in safe-local-variable property. + +2006-05-09 Richard Stallman + + * variables.texi (File Local Variables): Document + safe-local-eval-forms and safe-local-eval-function. + +2006-05-07 Kim F. Storm + + * minibuf.texi (Minibuffer History): Remove keep-dups arg + from add-to-history. + +2006-05-07 Romain Francoise + + * commands.texi (Event Input Misc): + * compile.texi (Eval During Compile): + * internals.texi (Buffer Internals): + * minibuf.texi (Initial Input): + * nonascii.texi (Scanning Charsets): + * numbers.texi (Comparison of Numbers): + * windows.texi (Textual Scrolling, Vertical Scrolling): + Fix various typos. + +2006-05-06 Eli Zaretskii + + * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by + conditional xref's to either emacs or emacs-xtra, depending on + @iftex/@ifnottex. + + * minibuf.texi (Minibuffer History): Document add-to-history. + +2006-05-05 Eli Zaretskii + + * internals.texi (Pure Storage): Mention the pure overflow message + at startup. + +2006-05-05 Johan Bockg,Ae(Brd + + * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. + (Searching Keymaps): Fix pseudo-Lisp description of keymap + search. + +2006-05-01 Richard Stallman + + * intro.texi (nil and t): Clarify. + + * variables.texi (File Local Variables): Suggest using booleanp. + +2006-05-01 Juanma Barranquero + + * objects.texi (Type Predicates): Fix typos. + +2006-05-01 Stefan Monnier + + * intro.texi (nil and t): Add booleanp. + + * objects.texi (Type Predicates): Add links for booleanp and + string-or-null-p. + +2006-04-29 Richard Stallman + + * modes.texi (Multiline Font Lock): Rename from + Multi line Font Lock Elements. Much clarification. + (Font Lock Multiline, Region to Fontify): Much clarification. + +2006-04-29 Stefan Monnier + + * variables.texi (File Local Variables): Remove the special case t for + safe-local-variable. + +2006-04-26 Richard Stallman + + * syntax.texi (Parsing Expressions): Minor cleanup. + +2006-04-18 Richard Stallman + + * tips.texi (Coding Conventions): Explain when the package's + prefix should appear later on (not at the start of the name). + + * searching.texi (String Search): Clarify effect of NOERROR. + + * modes.texi (Imenu): Clarify what special items do. + + * hooks.texi (Standard Hooks): Delete text about old hook names. + +2006-04-17 Romain Francoise + + * variables.texi (Local Variables): Update the default value of + `max-specpdl-size'. + +2006-04-15 Michael Olson + + * processes.texi (Transaction Queues): Mention the new optional + `delay-question' argument for `tq-enqueue'. + +2006-04-13 Bill Wohler + + * customize.texi (Common Keywords): Use dotted notation for + :package-version value. Specify its values. Improve documentation + for customize-package-emacs-version-alist. + +2006-04-12 Bill Wohler + + * customize.texi (Common Keywords): Move description of + customize-package-emacs-version-alist to @defvar. + +2006-04-10 Bill Wohler + + * customize.texi (Common Keywords): Add :package-version. + +2006-04-10 Kim F. Storm + + * text.texi (Buffer Contents): Add NOPROPS arg to + filter-buffer-substring. + +2006-04-08 Kevin Ryde + + * os.texi (Command-Line Arguments): Update xref to emacs manual + "Command Arguments" -> "Emacs Invocation", per change there. + +2006-04-08 Thien-Thi Nguyen + + * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to + be on one line to help makeinfo not render two spaces after the dot. + +2006-04-07 Reiner Steib + + * strings.texi (Predicates for Strings): Add string-or-null-p. + +2006-03-28 Kim F. Storm + + * processes.texi (Accepting Output): Remove obsolete (and incorrect) + remarks about systems that don't support fractional seconds. + +2006-03-25 Karl Berry + + * elisp.texi: Use @copyright{} instead of (C), and do not indent + the year list. + +2006-03-21 Nick Roberts + + * display.texi (Fringe Indicators): Fix typos. + +2006-03-19 Luc Teirlinck + + * tips.texi (Documentation Tips): One can now also write `program' + in front of a quoted symbol in a docstring to prevent making a + hyperlink. + +2006-03-19 Alan Mackenzie + + * text.texi (Special Properties): Clarify `fontified' property. + +2006-03-16 Richard Stallman + + * display.texi (Defining Images): Minor cleanup. + +2006-03-16 Bill Wohler + + * display.texi (Defining Images): In image-load-path-for-library, + prefer user's images. + +2006-03-15 Stefan Monnier + + * modes.texi (Region to Fontify): Remove font-lock-lines-before. + +2006-03-15 Bill Wohler + + * display.texi (Defining Images): Fix example in + image-load-path-for-library by not recommending that one binds + image-load-path. Just defvar it to placate compiler and only use + it if previously defined. + +2006-03-14 Bill Wohler + + * display.texi (Defining Images): In image-load-path-for-library, + always return list of directories. Update example. + +2006-03-14 Alan Mackenzie + + * modes.texi: New node, "Region to Fontify" (for Font Lock). + This describes font-lock-extend-region-function. + ("Other Font Lock Variables"): Move "font-lock-lines-before" to + the new node "Region to Fontify". + +2006-03-13 Richard Stallman + + * display.texi (Invisible Text): The impossible position is + now before the invisible text, not after. + (Defining Images): Clean up last change. + +2006-03-11 Bill Wohler + + * display.texi (Defining Images): Add image-load-path-for-library. + +2006-03-11 Luc Teirlinck + + * text.texi (Adaptive Fill): Fix Texinfo usage. + + * strings.texi (Creating Strings): Fix Texinfo usage. + + * searching.texi (Regexp Special): Use @samp for regular + expressions that are not in Lisp syntax. + +2006-03-08 Luc Teirlinck + + * searching.texi (Regexp Special): Put remark between parentheses + to avoid misreading. + +2006-03-07 Luc Teirlinck + + * searching.texi (Syntax of Regexps): More accurately describe + which characters are special in which situations. + (Regexp Special): Recommend _not_ to quote `]' or `-' when they + are not special. Describe in detail when `[' and `]' are special. + (Regexp Backslash): Plenty of regexps with unbalanced square + brackets are valid, so reword that statement. + +2006-03-02 Kim F. Storm + + * keymaps.texi (Tool Bar): Add tool-bar-border. + +2006-02-28 Luc Teirlinck + + * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. + +2006-02-27 Luc Teirlinck + + * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. + + * files.texi (Locating Files): Suggest additional values for the + SUFFIXES arg of `locate-file'. Update pxref. + + * loading.texi (Loading): Include new node "Load Suffixes" in menu. + (How Programs Do Loading): Discuss the effects of Auto Compression + mode on `load'. + (Load Suffixes): New node. + (Library Search): Delete description of `load-suffixes'; it was + moved to "Load Suffixes". + (Autoload, Named Features): Mention `load-suffixes'. + +2006-02-21 Giorgos Keramidas (tiny change) + + * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. + + * windows.texi (Window Tree): Fix typo. + +2006-02-20 Kim F. Storm + + * display.texi (Fringe Indicators): New section. + Move indicate-empty-lines, indicate-buffer-boundaries, and + default-indicate-buffer-boundaries here. + Add fringe-indicator-alist and default-fringes-indicator-alist. + Add list of logical fringe indicator symbols. + Update list of standard bitmap names. + (Fringe Cursors): New section. + Move overflow-newline-into-fringe here. + Add fringe-cursor-alist and default-fringes-cursor-alist. + Add list of fringe cursor symbols. + +2006-02-20 Juanma Barranquero + + * commands.texi (Using Interactive): Fix reference to node + "Minibuffers". + +2006-02-19 Richard M. Stallman + + * minibuf.texi (High-Level Completion): + Add xref to read-input-method-name. + + * files.texi (Relative File Names): Move file-relative-name here. + (File Name Expansion): From here. Minor clarifications. + + * commands.texi (Using Interactive): Add xrefs about reading input. + Clarify remarks about that moving point and mark. + Put string case before list case. + +2006-02-16 Johan Bockg,Ae(Brd + + * display.texi (Other Display Specs, Image Descriptors): + Revert erroneous changes. The previous description of + image-descriptors as `(image . PROPS)' was correct. + +2006-02-14 Richard M. Stallman + + * variables.texi (File Local Variables): Clarifications. + +2006-02-14 Juanma Barranquero + + * variables.texi (File Local Variables): Use @code for a cons + cell, not @var. + +2006-02-13 Chong Yidong + + * variables.texi (File Local Variables): Document new file local + variable behavior. + +2006-02-10 Kim F. Storm + + * eval.texi (Function Indirection): Add NOERROR to indirect-function. + +2006-02-08 Juanma Barranquero + + * modes.texi (%-Constructs): Remove obsolete info about + `global-mode-string'. + +2006-02-07 Richard M. Stallman + + * commands.texi (Prefix Command Arguments): Minor cleanup. + + * display.texi: "Graphical display", not window system. + + * functions.texi (What Is a Function): Fix xref. + + * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. + (Changing Key Bindings): Clarify when remapping is better than + substitute-key-definition. + +2006-02-02 Richard M. Stallman + + * minibuf.texi (Basic Completion): Completion alists are risky. + + * keymaps.texi (Active Keymaps): Clarifications. + (Searching Keymaps): New node. + (Keymaps): Update menu. + + * frames.texi (Layout Parameters): Minor clarification. + (Drag and Drop): New node. + (Frames): Update menu. + +2006-01-29 Chong Yidong + + * display.texi (Other Display Specs, Image Descriptors): + Image description is a list, not a cons cell. + +2006-01-28 Luc Teirlinck + + * lists.texi (Cons Cells): Minor correction (the cdr of a dotted + list is not necessarily a list). + +2006-01-27 Eli Zaretskii + + * frames.texi (Layout Parameters): border-width and + internal-border-width belong to the frame, not the window. + +2006-01-19 Richard M. Stallman + + * nonascii.texi (Translation of Characters): Search cmds use + translation-table-for-input. Automatically made local. + + * markers.texi (Overview of Markers): Count insertion type + as one of a marker's attributes. + + * keymaps.texi (Controlling Active Maps): New node, split out of + Active Keymaps. + (Keymaps): Menu updated. + (Active Keymaps): Give pseudocode to explain how the active + maps are searched. current-active-maps and key-binding moved here. + (Functions for Key Lookup): current-active-maps and key-binding moved. + Clarifications. + (Searching the Keymaps): New subnode. + + * elisp.texi (Top): Menu clarification. + + * display.texi (Other Display Specs): Delete duplicate entry for + just a string as display spec. Move text about recursive display + specs on such a string. + + * commands.texi (Key Sequence Input): Clarify. + Move num-nonmacro-input-events out. + (Reading One Event): num-nonmacro-input-events moved here. + +2006-01-14 Nick Roberts + + * advice.texi (Simple Advice): Update example to fit argument + change in previous-line. + +2006-01-05 Richard M. Stallman + + * markers.texi (The Mark): Fix in `mark'. + +2006-01-04 Richard M. Stallman + + * processes.texi (Misc Network, Make Network): Minor cleanups. + +2006-01-04 Kim F. Storm + + * processes.texi (Make Network): Add IPv6 addresses and handling. + (Network Feature Testing): Mention (:family ipv6). + (Misc Network): Add IPv6 formats to format-network-address. + +2005-12-30 Richard M. Stallman + + * text.texi (Changing Properties): + Don't use return value of set-text-properties. + +2005-12-29 Luc Teirlinck + + * modes.texi (Mode Line Format): Correct typo in menu. + +2005-12-29 Richard M. Stallman + + * modes.texi (Mode Line Top): New node. + (Mode Line Data): Some text moved to new node. + Explain the data structure more concretely. + (Mode Line Basics): Clarifications. + (Mode Line Variables): Clarify intro paragraph. + (%-Constructs): Clarify intro paragraph. + (Mode Line Format): Update menu. + +2005-12-28 Luc Teirlinck + + * minibuf.texi (Basic Completion): Update lazy-completion-table + examples for removal of ARGS argument. + +2005-12-23 Richard M. Stallman + + * text.texi (Undo): Restore some explanation from the version + that was deleted. + +2005-12-23 Eli Zaretskii + + * text.texi (Undo): Remove duplicate descriptions of `apply + funname' and `apply delta' elements of the undo list. + +2005-12-20 Richard M. Stallman + + * help.texi (Help Functions): Update documentation of `apropos'. + +2005-12-20 Luc Teirlinck + + * customize.texi (Type Keywords): Delete xref to "Text help-echo", + because it is confusing. If the :help-echo keyword is a function, + it is not directly used as the :help-echo overlay property, as the + xref seems to suggest (it does not take the appropriate args). + +2005-12-19 Luc Teirlinck + + * customize.texi (Common Keywords): Fix Texinfo usage. + (Group Definitions, Variable Definitions): Update for new + conventions for using `*' in docstrings. + + * tips.texi (Documentation Tips): Update for new conventions for + using `*' in docstrings. + +2005-12-16 Richard M. Stallman + + * minibuf.texi (Minibuffer Contents): Minor cleanup. + +2005-12-16 Juri Linkov + + * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. + +2005-12-14 Romain Francoise + + * modes.texi (Customizing Keywords): Rename `append' to `how'. + Fix typo. + +2005-12-11 Juri Linkov + + * minibuf.texi (Completion Commands): Add mention of read-file-name + for filename completion keymaps. + (Reading File Names): Add mention of filename completion keymaps + for read-file-name and xref to `Completion Commands'. + +2005-12-10 Richard M. Stallman + + * customize.texi (Common Keywords): State caveats for use of :tag. + +2005-12-08 Richard M. Stallman + + * minibuf.texi (Intro to Minibuffers): Replace list of local maps + with xrefs and better explanation. + (Completion Commands): Add the filename completion maps. + + * objects.texi (Character Type): Clarify that \s is not space + if a dash follows. + +2005-12-05 Richard M. Stallman + + * windows.texi (Resizing Windows): Delete preserve-before args. + +2005-12-05 Stefan Monnier + + * keymaps.texi (Format of Keymaps): Remove mention of a quirk + in full keymaps, since the quirk has been fixed. + +2005-12-03 Eli Zaretskii + + * hooks.texi (Standard Hooks): Add index entries. Mention + `compilation-finish-functions'. + +2005-11-27 Richard M. Stallman + + * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. + +2005-11-21 Juri Linkov + + * customize.texi (Common Keywords): Update links types + custom-manual and url-link. Add link types emacs-library-link, + file-link, function-link, variable-link, custom-group-link. + +2005-11-20 Chong Yidong + + * display.texi: Revert 2005-11-20 change. + +2005-11-20 Thien-Thi Nguyen + + * processes.texi (Bindat Functions): + Say "third" to refer to zero-based index "2". + +2005-11-18 Luc Teirlinck + + * loading.texi (Library Search): Update the default value of + `load-suffixes'. + +2005-11-17 Chong Yidong + + * display.texi (Attribute Functions): Mention :ignore-defface. + +2005-11-16 Stefan Monnier + + * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. + (Minor Mode Conventions): Mention the use of a hook. + +2005-11-06 Richard M. Stallman + + * files.texi (Magic File Names): find-file-name-handler checks the + `operations' property of the handler. + +2005-11-03 Richard M. Stallman + + * variables.texi (Frame-Local Variables): Small clarification. + +2005-10-29 Chong Yidong + + * os.texi (Init File): Document ~/.emacs.d/init.el. + +2005-10-29 Richard M. Stallman + + * internals.texi (Garbage Collection): Document memory-full. + +2005-10-28 Bill Wohler + + * tips.texi (Documentation Tips): Help mode now creates hyperlinks + for URLs. + +2005-10-28 Richard M. Stallman + + * minibuf.texi (Completion Commands): Clean up prev change. + +2005-10-26 Kevin Ryde + + * compile.texi (Eval During Compile): Explain recommended uses + of eval-when-compile and eval-and-compile. + +2005-10-27 Masatake YAMATO + + * minibuf.texi (Completion Commands): + Write about new optional argument for `display-completion-list'. + +2005-10-23 Richard M. Stallman + + * display.texi (Overlay Arrow): Clarify about local bindings of + overlay-arrow-position. + +2005-10-22 Eli Zaretskii + + * internals.texi (Building Emacs): Fix last change. + +2005-10-22 Richard M. Stallman + + * internals.texi (Building Emacs): Document eval-at-startup. + +2005-10-21 Richard M. Stallman + + * loading.texi (Where Defined): load-history contains abs file names. + symbol-file returns abs file names. + +2005-10-19 Kim F. Storm + + * display.texi (Showing Images): Add max-image-size integer value. + +2005-10-18 Chong Yidong + + * display.texi (Showing Images): Document max-image-size. + +2005-10-17 Richard M. Stallman + + * commands.texi (Quitting): Minor clarification. + + * processes.texi (Sentinels): Clarify about output and quitting. + (Filter Functions): Mention with-local-quit. + +2005-10-17 Juri Linkov + + * buffers.texi (Current Buffer): + * commands.texi (Event Input Misc): + * compile.texi (Eval During Compile, Compiler Errors): + * customize.texi (Group Definitions): + * display.texi (Progress, Defining Faces): + * files.texi (Writing to Files): + * modes.texi (Mode Hooks, Defining Minor Modes): + * streams.texi (Output Functions): + * syntax.texi (Syntax Table Functions): + * text.texi (Change Hooks): + Replace `...' with `@dots{}' in `@defmac' and `@defspec'. + + * commands.texi (Quitting): Replace arg `forms' with `body' in + `with-local-quit'. + + * positions.texi (Excursions): Replace arg `forms' with `body' in + `save-excursion'. + +2005-10-08 Kim F. Storm + + * windows.texi (Window Tree): Rename window-split-tree to window-tree. + Rename manual section accordingly. + +2005-10-04 Kim F. Storm + + * windows.texi (Window Split Tree): New section describing + new function window-split-tree function. + +2005-10-03 Nick Roberts + + * display.texi (Fringe Size/Pos): Simplify and add detail. + +2005-09-30 Romain Francoise + + * minibuf.texi (High-Level Completion): Explain that the prompt + given to `read-buffer' should end with a colon and a space. + Update usage examples. + +2005-09-29 Juri Linkov + + * display.texi (Displaying Messages): Rename argument name + `string' to `format-string' in functions `message', `message-box', + `message-or-box'. + +2005-09-26 Chong Yidong + + * errors.texi (Standard Errors): Correct xrefs. + +2005-09-18 Chong Yidong + + * display.texi (Defining Images): Update documentation for + `image-load-path'. + +2005-09-17 Richard M. Stallman + + * display.texi (Defining Images): Clean up previous change. + +2005-09-16 Romain Francoise + + * elisp.texi: Specify GFDL version 1.2. + + * doclicense.texi (GNU Free Documentation License): Update to + version 1.2. + +2005-09-15 Chong Yidong + + * display.texi (Defining Images): Document `image-load-path'. + +2005-09-15 Richard M. Stallman + + * objects.texi (Printed Representation): Minor cleanup. + (Box Diagrams): Minor fix. + (Cons Cell Type): Move (...) index item here. + (Box Diagrams): From here. + (Array Type): Minor fix. + (Type Predicates): Delete index "predicates". + (Hash Table Type): Clarify xref. + (Dotted Pair Notation): Minor fix. + +2005-09-10 Chong Yidong + + * files.texi (Saving Buffers): Fix typo. + +2005-09-08 Richard M. Stallman + + * tips.texi (Programming Tips): Correct the "default" prompt spec. + +2005-09-08 Chong Yidong + + * locals.texi (Standard Buffer-Local Variables): Don't include + mode variables for minor modes. + Fix xrefs for buffer-display-count, buffer-display-table, + buffer-offer-save, buffer-saved-size, cache-long-line-scans, + enable-multibyte-characters, fill-column, header-line-format, + left-fringe-width, left-margin, and right-fringe-width. + + * hooks.texi (Standard Hooks): All hooks should conform to the + standard naming convention now. + Fix xref for `echo-area-clear-hook'. + + * display.texi (Usual Display): Note that indicate-empty-lines and + tab-width are buffer-local. + + * files.texi (Saving Buffers): Add xref to `Killing Buffers'. + + * modes.texi (Mode Help): Note that major-mode is buffer-local. + + * nonascii.texi (Encoding and I/O): Note that + buffer-file-coding-system is buffer-local. + + * positions.texi (List Motion): Note that defun-prompt-regexp is + buffer-local. + + * text.texi (Auto Filling): Note that auto-fill-function is + buffer-local. + (Undo): Note that buffer-undo-list is buffer-local. + + * windows.texi (Buffers and Windows): Document + buffer-display-count. + +2005-09-06 Richard M. Stallman + + * tips.texi (Coding Conventions): Sometimes it is ok to put the + package prefix elsewhere than at the start of the name. + +2005-09-03 Richard M. Stallman + + * tips.texi (Programming Tips): Add conventions for minibuffer + questions and prompts. + +2005-09-03 Joshua Varner (tiny change) + + * intro.texi (nil and t): Minor cleanup. + Delete spurious mention of keyword symbols. + (Evaluation Notation): Add index entry. + (A Sample Function Description): Minor cleanup. + (A Sample Variable Description): Not all vars can be set. + +2005-09-03 Thien-Thi Nguyen + + * text.texi (Buffer Contents): Use "\n" in examples' result strings. + + (Insertion): Document precise type of `insert-char' arg COUNT. + +2005-09-02 Stefan Monnier + + * modes.texi (Other Font Lock Variables): Sync the default of + font-lock-lines-before. + +2005-08-31 Michael Albinus + + * files.texi (Magic File Names): Add `make-auto-save-file-name'. + +2005-08-29 Richard M. Stallman + + * elisp.texi (Top): Update subnode menu. + + * searching.texi (Searching and Matching): Move node. + Rearrange contents and add overall explanation. + (Searching and Case): Move node. + (Searching and Matching): Update menu. + +2005-08-27 Eli Zaretskii + + * os.texi (Startup Summary): Fix the description of the initial + startup message display. + +2005-08-25 Richard M. Stallman + + * searching.texi (Search and Replace): Add replace-regexp-in-string. + +2005-08-25 Emilio C. Lopes + + * display.texi (Finding Overlays): Fix `find-overlay-prop' in + `next-overlay-change' example. + +2005-08-22 Juri Linkov + + * display.texi (Attribute Functions): Add set-face-inverse-video-p. + Fix invert-face. Fix args of face-background. + + * display.texi (Standard Faces): Delete node. + (Faces): Add xref to `(emacs)Standard Faces'. + (Displaying Faces): Fix xref to `Standard Faces'. + + * modes.texi (Mode Line Data): Fix xref to Standard Faces. + +2005-08-20 Alan Mackenzie + + * buffers.texi (The Buffer List): Clarify the manipulation of the + buffer list. + +2005-08-14 Richard M. Stallman + + * modes.texi (Auto Major Mode): interpreter-mode-alist key is not + a regexp. + +2005-08-11 Richard M. Stallman + + * elisp.texi (Top): Update subnode lists. + + * display.texi (Inverse Video): Node deleted. + + * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): + New nodes split out of Coding Conventions. + + * searching.texi (Regular Expressions): Document re-builder. + + * os.texi (Time Parsing): New node split out of Time Conversion. + + * processes.texi (Misc Network, Network Feature Testing) + (Network Options, Make Network): New nodes split out of + Low-Level Network. + +2005-08-09 Richard M. Stallman + + * frames.texi (Geometry): New node, split from Size and Position. + (Frame Parameters): Refer to Geometry. + + * buffers.texi (The Buffer List): Fix xrefs. + + * windows.texi (Splitting Windows): Fix xref. + + * frames.texi (Layout Parameters): Add xref. + + * display.texi (Line Height, Scroll Bars): Fix xrefs. + + * keymaps.texi (Menu Bar): Fix xref. + + * locals.texi (Standard Buffer-Local Variables): Fix xref. + + * modes.texi (%-Constructs): Fix xref. + + * frames.texi (Window Frame Parameters): Node split up. + (Basic Parameters, Position Parameters, Size Parameters) + (Layout Parameters, Buffer Parameters, Management Parameters) + (Cursor Parameters, Color Parameters): New subnodes. + +2005-08-09 Luc Teirlinck + + * positions.texi (Screen Lines): Update xref for previous change + in minibuf.texi. + + * minibuf.texi (Intro to Minibuffers): Update pxref for previous + change in minibuf.texi. + +2005-08-09 Richard M. Stallman + + * tips.texi (Coding Conventions): Minor cleanup. + + * modes.texi (Defining Minor Modes): Explain when init-value + can be non-nil. + + * elisp.texi (Top): Update submenu for Minibuffer. + + * minibuf.texi (Minibuffer Misc): Node split up. + (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) + (Recursive Mini): New nodes split out from Minibuffer Misc. + (Minibuffer Misc): Document max-mini-window-height. + + * hash.texi (Defining Hash): Delete stray paren in example. + + * display.texi (Echo Area Customization): Don't define + max-mini-window-height here; xref instead. + + * commands.texi (Event Input Misc): Update while-no-input. + + * advice.texi (Advising Functions): Explain when to use advice + and when to use a hook. + +2005-07-30 Eli Zaretskii + + * makefile.w32-in (info): Don't run install-info. + ($(infodir)/dir): New target, produced by running install-info. + +2005-07-27 Luc Teirlinck + + * modes.texi (Defining Minor Modes): The keyword for the initial + value is :init-value, not :initial-value. + +2005-07-23 Eli Zaretskii + + * loading.texi (Autoload): Make the `doctor' example be consistent + with what's in current loaddefs.el. Describe the "fn" magic in + the usage portion of the doc string. + +2005-07-22 Richard M. Stallman + + * internals.texi (Garbage Collection): Clarify previous change. + +2005-07-21 Stefan Monnier + + * internals.texi (Garbage Collection): Add gc-cons-percentage. + +2005-07-18 Juri Linkov + + * commands.texi (Accessing Events): + * frames.texi (Text Terminal Colors, Resources): + * markers.texi (The Mark): + * modes.texi (Defining Minor Modes): + Delete duplicate duplicate words. + +2005-07-16 Richard M. Stallman + + * display.texi (Managing Overlays): Clarify make-overlay + args for insertion types. + +2005-07-13 Luc Teirlinck + + * customize.texi (Variable Definitions): + Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. + `standard-value' is a list too. + (Defining New Types): Use @key{RET} instead of @key{ret}. + +2005-07-13 Francis Litterio (tiny change) + + * os.texi (Translating Input): Fix typo. + +2005-07-08 Richard M. Stallman + + * README: Update edition number and size estimate. + + * elisp.texi (VERSION): Set to 2.9. + +2005-07-07 Richard M. Stallman + + * book-spine.texinfo: Update Emacs version. + + * display.texi (Inverse Video): Delete mode-line-inverse-video. + +2005-07-06 Richard M. Stallman + + * searching.texi (Regexp Search): Clarify what re-search-forward + does when the search fails. + +2005-07-05 Lute Kamstra + + * Update FSF's address in GPL notices. + + * doclicense.texi (GNU Free Documentation License): + * gpl.texi (GPL): + * tips.texi (Coding Conventions, Library Headers): + * vol1.texi: + * vol2.texi: Update FSF's address. + +2005-07-04 Richard M. Stallman + + * hooks.texi (Standard Hooks): Add occur-hook. + +2005-07-03 Luc Teirlinck + + * display.texi (The Echo Area): Correct menu. + +2005-07-03 Richard M. Stallman + + * elisp.texi (Top): Update subnode menu for Display. + + * display.texi (Displaying Messages): New node, with most + of what was in The Echo Area. + (Progress): Moved under The Echo Area. + (Logging Messages): New node with new text. + (Echo Area Customization): New node, the rest of what was + in The Echo Area. Document message-truncate-lines with @defvar. + (Display): Update menu. + + * windows.texi (Textual Scrolling): Doc 3 values for + scroll-preserve-screen-position. + + * text.texi (Special Properties): Change hook functions + should bind inhibit-modification-hooks around altering buffer text. + + * keymaps.texi (Key Binding Commands): Call binding BINDING + rather than DEFINITION. + +2005-06-29 Juanma Barranquero + + * variables.texi (Defining Variables): `user-variable-p' returns t + for aliases of user options, nil for alias loops. + +2005-06-28 Richard M. Stallman + + * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before + make-keymap. + +2005-06-27 Luc Teirlinck + + * variables.texi (Setting Variables): Correct and clarify + description of `add-to-ordered-list'. + +2005-06-26 Richard M. Stallman + + * display.texi (Faces): Minor cleanup. + +2005-06-25 Luc Teirlinck + + * display.texi (Faces): `facep' returns t for strings that are + face names. + +2005-06-25 Richard M. Stallman + + * objects.texi (Equality Predicates): Clarify meaning of equal. + + * windows.texi (Selecting Windows): save-selected-window + and with-selected-window save and restore the current buffer. + +2005-06-24 Richard M. Stallman + + * numbers.texi (Float Basics): Explain how to test for NaN, + and printing the sign of NaNs. + +2005-06-24 Eli Zaretskii + + * makefile.w32-in (MAKEINFO): Use --force. + +2005-06-23 Richard M. Stallman + + * display.texi (Face Functions): Correct Texinfo usage. + +2005-06-23 Luc Teirlinck + + * lists.texi (Rings): `ring-elements' now returns the elements of + RING in order. + +2005-06-23 Juanma Barranquero + + * markers.texi (The Mark): Texinfo usage fix. + +2005-06-23 Kim F. Storm + + * searching.texi (Entire Match Data): Remove evaporate option for + match-data. Do not mention evaporate option for set-match-data. + +2005-06-22 Glenn Morris + + * display.texi (Face Functions): Mention face aliases. + +2005-06-21 Richard M. Stallman + + * anti.texi (Antinews): Texinfo usage fix. + +2005-06-21 Karl Berry + + * elisp.texi: Use @copying. + + * elisp.texi: Put @summarycontents and @contents before the Top + node, instead of the end of the file, so that the contents appear + in the right place in the dvi/pdf output. + +2005-06-21 Juri Linkov + + * display.texi (Defining Faces): Add `customized-face'. + +2005-06-20 Kim F. Storm + + * variables.texi (Setting Variables): Any type of element can be + given order in add-to-ordered-list. Compare elements with eq. + + * lists.texi (Rearrangement): Sort predicate may just return non-nil. + +2005-06-20 Karl Berry + + * syntax.texi (Syntax Flags): Make last column very slightly wider + to avoid "generic comment" breaking on two lines and causing an + underfull box. + +2005-06-19 Luc Teirlinck + + * lists.texi (Rings): Various minor clarifications and corrections. + +2005-06-18 Richard M. Stallman + + * functions.texi (Obsolete Functions): Simplify. + + * variables.texi (Variable Aliases): Simplify. + + * anti.texi, backups.texi, compile.texi, customization.texi: + * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: + * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: + * os.texi, processes.texi, searching.texi, strings.texi, text.texi: + * variables.texi: Fix formatting ugliness. + + * elisp.texi: Add links to Rings and Byte Packing. + Update version and copyright years. + + * minibuf.texi: Fix formatting ugliness. + (Completion Commands): Move keymap vars to the end + and vars completing-read binds to the top. + +2005-06-17 Luc Teirlinck + + * processes.texi: Fix typos. + (Bindat Spec): Correct Texinfo error. + (Byte Packing): Fix ungrammatical sentence. + +2005-06-17 Thien-Thi Nguyen + + * lists.texi (Rings): New node. + (Lists): Add it to menu. + + * processes.texi (Byte Packing): New node. + (Processes): Add it to menu. + +2005-06-17 Richard M. Stallman + + * syntax.texi (Parsing Expressions): Fix texinfo usage. + + * help.texi (Documentation Basics): Explain the xref to + Documentation Tips. + + * debugging.texi (Debugger Commands): Minor fix. + +2005-06-16 Luc Teirlinck + + * edebug.texi (Instrumenting): Eliminate duplicate link. + (Specification List): Replace references to "below", referring to + a later node, with one @ref to that node. + + * os.texi (Timers): Timers should save and restore the match data + if they change it. + + * debugging.texi (Debugger Commands): Mention that the Lisp + debugger can not step through primitive functions. + +2005-06-16 Juanma Barranquero + + * functions.texi (Obsolete Functions): Update argument names of + `make-obsolete' and `define-obsolete-function-alias'. + + * variables.texi (Variable Aliases): Update argument names of + `defvaralias', `make-obsolete-variable' and + `define-obsolete-variable-alias'. + +2005-06-15 Kim F. Storm + + * searching.texi (Entire Match Data): Rephrase warnings about + evaporate arg to match-data and set-match-data. + +2005-06-14 Luc Teirlinck + + * elisp.texi (Top): Update detailed menu. + + * edebug.texi (Edebug): Update menu. + (Instrumenting): Update xrefs. + (Edebug Execution Modes): Correct xref. + (Jumping): Clarify description of `h' command. + Eliminate redundant @ref. + (Breaks): New node. + (Breakpoints): Is now a subsubsection. + (Global Break Condition): Mention `C-x X X'. + (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. + (Trace Buffer): Clarify STRING arg of `edebug-tracing'. + (Edebug Display Update): Correct pxref. + (Edebug and Macros): New node. + (Instrumenting Macro Calls): Is now a subsubsection. + Neither arg of `def-edebug-spec' is evaluated. + (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. + (Specification Examples): Fix typo. + +2005-06-14 Lute Kamstra + + * debugging.texi (Function Debugging): Primitives can break on + entry too. + +2005-06-14 Kim F. Storm + + * variables.texi (Setting Variables): Add add-to-ordered-list. + +2005-06-13 Stefan Monnier + + * syntax.texi (Parsing Expressions): Document aux functions and vars of + syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. + +2005-06-13 Lute Kamstra + + * text.texi (Special Properties): Fix cross reference. + +2005-06-11 Luc Teirlinck + + * debugging.texi (Function Debugging): Delete mention of empty + string argument to `cancel-debug-on-entry'. Delete inaccurate + description of the return value of that command. + +2005-06-11 Alan Mackenzie + + * text.texi (Adaptive Fill): Amplify the description of + fill-context-prefix. + +2005-06-10 Luc Teirlinck + + * syntax.texi (Parsing Expressions): Fix Texinfo error. + +2005-06-10 Stefan Monnier + + * syntax.texi (Parsing Expressions): Document syntax-ppss. + +2005-06-10 Luc Teirlinck + + * debugging.texi (Error Debugging): Minor rewording. + (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' + is optional. + +2005-06-10 Lute Kamstra + + * elisp.texi: Use EMACSVER to refer to the current version of Emacs. + (Top): Give it a title. Correct version number. Give the + detailed node listing a more prominent header. + * intro.texi: Don't set VERSION here a second time. + Mention Emacs's version too. + * anti.texi (Antinews): Use EMACSVER to refer to the current + version of Emacs. + +2005-06-09 Kim F. Storm + + * searching.texi (Entire Match Data): Explain new `reseat' argument to + match-data and set-match-data. + +2005-06-08 Richard M. Stallman + + * searching.texi (Entire Match Data): Clarify when match-data + returns markers and when integers. + + * display.texi (Defining Faces): Explain that face name should not + end in `-face'. + + * modes.texi (Mode Line Data): Minor cleanup. + (Customizing Keywords): Node split out of Search-based Fontification. + Add example of using font-lock-add-keywords from a hook. + Clarify when MODE should be non-nil, and when nil. + +2005-06-06 Richard M. Stallman + + * modes.texi (Mode Line Data): Explain what happens when the car + of a list is a void symbol. + (Search-based Fontification): Explain MODE arg to + font-lock-add-keywords and warn about calls from major modes. + +2005-06-08 Juri Linkov + + * display.texi (Standard Faces): Add `shadow' face. + +2005-05-29 Luc Teirlinck + + * modes.texi (Major Mode Conventions): A derived mode only needs + to put the call to the parent mode inside `delay-mode-hooks'. + +2005-05-29 Richard M. Stallman + + * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is + new, and what that implies. Clarify. + + * files.texi (Locating Files): Clean up the text. + + * frames.texi (Window Frame Parameters): Document user-size. + Shorten entry for top by referring to left. + +2005-05-26 Richard M. Stallman + + * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook + is new, and what the implications are. Other clarifications. + +2005-05-24 Richard M. Stallman + + * frames.texi (Dialog Boxes): Minor fixes. + +2005-05-25 Masatake YAMATO + + * display.texi (Standard Faces): Write about `mode-line-highlight'. + +2005-05-24 Luc Teirlinck + + * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' + is optional. + +2005-05-24 Nick Roberts + + * frames.texi (Dialog Boxes): Descibe new optional argument. + +2005-05-23 Lute Kamstra + + * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend + syntax-begin-function over font-lock-beginning-of-syntax-function. + +2005-05-21 Luc Teirlinck + + * minibuf.texi (Reading File Names): Update description of + `read-directory-name'. + + * modes.texi (Derived Modes): Clarify :group keyword. + +2005-05-21 Eli Zaretskii + + * files.texi (Locating Files): New subsection. + Describe locate-file and executable-find. + +2005-05-21 Kevin Ryde + + * frames.texi (Initial Parameters): Update cross reference to + "Emacs Invocation". + +2005-05-19 Luc Teirlinck + + * keymaps.texi (Active Keymaps): Add anchor. + + * modes.texi (Hooks): Delete confusing and unnecessary sentence. + (Major Mode Conventions): Refer to `Auto Major Mode' in more + appropriate place. + (Derived Modes): Small clarifications. + (Minor Mode Conventions, Keymaps and Minor Modes): + Replace references to nodes with references to anchors. + (Mode Line Data): Warn that `(:eval FORM)' should not load any files. + Clarify description of lists whose first element is an integer. + (Mode Line Variables): Add anchor. + (%-Constructs): Clarify description of integer after %. + (Emulating Mode Line): Describe nil value for FACE. + +2005-05-18 Luc Teirlinck + + * modes.texi (Derived Modes): Correct references to non-existing + variable standard-syntax-table. + +2005-05-17 Lute Kamstra + + * modes.texi (Defining Minor Modes): Mention the mode hook. + +2005-05-15 Kim F. Storm + + * processes.texi (Network): Remove open-network-stream-nowait. + (Network Servers): Remove open-network-stream-server. + +2005-05-15 Luc Teirlinck + + * elisp.texi (Top): Update detailed menu. + + * variables.texi: Reorder nodes. + (Variables): Update menu. + (File Local Variables): Do not refer to the `-*-' line as + a "local variables list". Add pxref. + +2005-05-14 Luc Teirlinck + + * elisp.texi (Top): Update detailed menu for node changes. + + * modes.texi (Modes): Update Menu. + (Hooks): Move to beginning of chapter. + Most minor modes run mode hooks too. + `add-hook' can handle void hooks or hooks whose value is a single + function. + (Major Modes): Update Menu. + (Major Mode Basics): New node, split off from `Major Modes'. + (Major Mode Conventions): Correct xref. Explain how to handle + auto-mode-alist if the major mode command has an autoload cookie. + (Auto Major Mode): Major update. Add magic-mode-alist. + (Derived Modes): Major update. + (Mode Line Format): Update Menu. + (Mode Line Basics): New node, split off from `Mode Line Format'. + + * loading.texi (Autoload): Mention `autoload cookie' as synonym + for `magic autoload comment'. Add index entries and anchor. + +2005-05-14 Richard M. Stallman + + * tips.texi (Coding Conventions): Explain how important it is + that just loading certain files not change Emacs behavior. + + * modes.texi (Defining Minor Modes): Define define-global-minor-mode. + +2005-05-12 Lute Kamstra + + * modes.texi (Generic Modes): Update. + (Major Modes): Refer to node "Generic Modes". + + * elisp.texi (Top): Update to the current structure of the manual. + * processes.texi (Processes): Add menu description. + * customize.texi (Customization): Add menu descriptions. + +2005-05-11 Thien-Thi Nguyen + + * processes.texi (Signals to Processes) + (Low-Level Network): Fix typos. + +2005-05-11 Lute Kamstra + + * elisp.texi (Top): Add some nodes from the chapter "Major and + Minor Modes" to the detailed node listing. + +2005-05-10 Richard M. Stallman + + * keymaps.texi (Extended Menu Items): Menu item filter functions + can be called at any time. + +2005-05-08 Luc Teirlinck + + * variables.texi (File Local Variables): `(hack-local-variables t)' + now also checks whether a mode is specified in the local variables + list. + +2005-05-05 Kevin Ryde + + * display.texi (The Echo Area): Correct format function cross + reference. + +2005-05-05 Luc Teirlinck + + * variables.texi (Variable Aliases): Change description of + `define-obsolete-variable-alias'. + + * functions.texi (Functions): Add "Obsolete Functions" to menu. + (Defining Functions): Add xref. + (Obsolete Functions): New node. + (Function Safety): Standardize capitalization of section title. + + * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. + (Dialog Boxes): Complete description of `x-popup-dialog'. + +2005-05-04 Richard M. Stallman + + * commands.texi (Interactive Codes): Fix Texinfo usage. + Document U more clearly. + +2005-05-01 Luc Teirlinck + + * variables.texi (Variable Aliases): `make-obsolete-variable' is a + function and not a macro. + + * frames.texi (Pop-Up Menus): Correct and clarify description of + `x-popup-menu'. + (Dialog Boxes): Clarify description of `x-popup-dialog'. + +2005-05-01 Richard M. Stallman + + * edebug.texi (Checking Whether to Stop): Fix previous change. + +2005-05-01 Luc Teirlinck + + * display.texi: Fix typos and Texinfo usage. + + * edebug.texi (Checking Whether to Stop): executing-macro -> + executing-kbd-macro. + +2005-05-01 Richard M. Stallman + + * display.texi (Invisible Text): Correct add-to-invisibility-spec. + +2005-04-30 Richard M. Stallman + + * files.texi (Magic File Names): Document `operations' property. + +2005-04-29 Lute Kamstra + + * modes.texi (Generic Modes): New node. + (Major Modes): Add it to the menu. + (Derived Modes): Add "derived mode" to concept index. + +2005-04-28 Lute Kamstra + + * modes.texi (Defining Minor Modes): Fix previous change. + (Font Lock Mode): Simplify. + (Font Lock Basics): Say that font-lock-defaults is buffer-local + when set and that some parts are optional. Add cross references. + (Search-based Fontification): Say how to specify font-lock-keywords. + Add cross references. Add font-lock-multiline to index. + Move font-lock-keywords-case-fold-search here from node "Other Font + Lock Variables". Document font-lock-add-keywords and + font-lock-remove-keywords. + (Other Font Lock Variables): Move font-lock-keywords-only, + font-lock-syntax-table, font-lock-beginning-of-syntax-function, + and font-lock-syntactic-face-function to node "Syntactic Font + Lock". Move font-lock-keywords-case-fold-search to node + "Search-based Fontification". Document font-lock-inhibit-thing-lock + and font-lock-{,un}fontify-{buffer,region}-function. + (Precalculated Fontification): Remove reference to deleted variable + font-lock-core-only. + (Faces for Font Lock): Add font-lock-comment-delimiter-face. + (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, + font-lock-syntax-table, font-lock-beginning-of-syntax-function, + and font-lock-syntactic-face-function here from node "Other Font + Lock Variables". Move font-lock-syntactic-keywords to "Setting + Syntax Properties". Add cross references. + (Setting Syntax Properties): New node. + Move font-lock-syntactic-keywords here from "Syntactic Font Lock". + * syntax.texi (Syntax Properties): Add cross reference. + * hooks.texi (Standard Hooks): Add Font-Lock hooks. + +2005-04-26 Richard M. Stallman + + * display.texi (Defining Faces): + Document `default' elements of defface spec. + + * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. + + * variables.texi (Variable Aliases): Clarify text. + +2005-04-25 Chong Yidong + + * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. + +2005-04-25 Luc Teirlinck + + * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. + +2005-04-24 Eli Zaretskii + + * syntax.texi (Syntax Table Internals): Elaborate documentation of + syntax-after and syntax-class. + + * files.texi (Changing Files): Fix last change's cross-reference. + (Unique File Names): Don't mention "numbers" in the documentation + of make-temp-file and make-temp-name. + +2005-04-23 Richard M. Stallman + + * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. + +2005-04-22 Nick Roberts + + * windows.texi (Cyclic Window Ordering): Clarify window-list. + +2005-04-22 Nick Roberts + + * variables.texi (Variable Aliases): Describe make-obsolete-variable + and define-obsolete-variable-alias. + +2005-04-22 Kim F. Storm + + * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. + (Other Plists): Remove safe-plist-get, as plist-get is now safe. + +2005-04-21 Lute Kamstra + + * lists.texi (Association Lists): Document rassq-delete-all. + +2005-04-19 Richard M. Stallman + + * modes.texi (Search-based Fontification): Explain that + facespec is an expression to be evaluated. + +2005-04-19 Kevin Ryde + + * streams.texi (Output Functions): Fix xref. + * strings.texi (String Conversion): Fix xref. + +2005-04-19 Kim F. Storm + + * symbols.texi (Symbol Plists): Add safe-get. + Mention that `get' may signal an error. + +2005-04-18 Nick Roberts + + * customize.texi (Variable Definitions): Replace tooltip-mode + example with save-place. + +2005-04-17 Richard M. Stallman + + * buffers.texi (Indirect Buffers): Clarify. + + * positions.texi (Positions): Clarify converting marker to integer. + + * strings.texi (String Basics): Mention string-match; clarify. + +2005-04-08 Lute Kamstra + + * modes.texi (Search-based Fontification): Fix cross references. + Use consistent terminology. Document anchored highlighting. + +2005-04-05 Lute Kamstra + + * modes.texi (Defining Minor Modes): Document :group keyword + argument and its default value. + +2005-04-03 Lute Kamstra + + * hooks.texi (Standard Hooks): Add some hooks. Add cross + references and/or descriptions. Delete major mode hooks; mention + them as a category instead. Rename or delete obsolete hooks. + +2005-04-02 Richard M. Stallman + + * nonascii.texi (Coding System Basics): Another wording cleanup. + +2005-04-01 Richard M. Stallman + + * nonascii.texi (Coding System Basics): Clarify previous change. + +2005-04-01 Kenichi Handa + + * nonascii.texi (Coding System Basics): Describe about rondtrip + identity of coding systems. + +2005-03-29 Chong Yidong + + * text.texi (Buffer Contents): Add filter-buffer-substring and + buffer-substring-filters. + +2005-03-26 Chong Yidong + + * anti.texi (Antinews): Mention `G' interactive code. + + * tips.texi (Compilation Tips): Mention benchmark.el. + +2005-03-27 Luc Teirlinck + + * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' + is now bound to M-o M-o. + + * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. + +2005-03-26 Glenn Morris + + * calendar.texi: Delete file (and move contents to emacs-xtra.texi + in the Emacs Manual). + * Makefile.in (srcs): Remove calendar.texi. + * makefile.w32-in (srcs): Remove calendar.texi. + * display.texi (Display): Change name of next node. + * os.texi (System In): Change name of previous node. + * elisp.texi (Top): Remove Calendar references. + * vol1.texi (Top): Remove Calendar references. + * vol2.texi (Top): Remove Calendar references. + +2005-03-25 Richard M. Stallman + + * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): + Cleanup previous change. + +2005-03-25 Chong Yidong + + * display.texi (Face Attributes): Faces earlier in an :inherit + list take precedence. + (Scroll Bars): Fix description of vertical-scroll-bars. + Document frame-current-scroll-bars and window-current-scroll-bars. + + * markers.texi (The Mark): Document temporary Transient Mark mode. + + * minibuf.texi (Reading File Names): + Document read-file-name-completion-ignore-case. + + * positions.texi (Screen Lines): Document nil for width argument + to compute-motion. + +2005-03-23 Kim F. Storm + + * display.texi (Standard Faces): Other faces used in the fringe + implicitly inherits from the fringe face. + (Fringe Bitmaps): FACE in right-fringe and left-fringe display + properties implicitly inherits from fringe face. + (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. + +2005-03-20 Chong Yidong + + * display.texi (Invisible Text): State default value of + line-move-ignore-invisible. + (Managing Overlays): Document remove-overlays. + (Standard Faces): Document escape-glyph face. + + * minibuf.texi (Reading File Names): Document read-file-name-function. + + * modes.texi (Other Font Lock Variables): + Document font-lock-lines-before. + + * positions.texi (Skipping Characters): skip-chars-forward allows + character classes. + +2005-03-18 Lute Kamstra + + * edebug.texi (Instrumenting Macro Calls): Fix another typo. + +2005-03-17 Richard M. Stallman + + * text.texi (Undo): Document extensible undo entries. + + * searching.texi (String Search, Regexp Search, Regexp Search): + Cleanups. + + * nonascii.texi (Character Codes): Minor fix. + + * display.texi (Display Property): Explain the significance + of having text properties that are eq. + (Other Display Specs): Explain string as display spec. + + * commands.texi (Interactive Codes): Document G option. + +2005-03-17 Chong Yidong + + * text.texi (Filling): Add sentence-end-without-period and + sentence-end-without-space. + (Changing Properties): Minor fix. + + * anti.texi: Total rewrite. + +2005-03-15 Lute Kamstra + + * edebug.texi (Instrumenting Macro Calls): Fix typos. + +2005-03-08 Kim F. Storm + + * display.texi (Specified Space): Property :width is support on + non-graphic terminals, :height is not. + +2005-03-07 Richard M. Stallman + + * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): + Now subnodes of Fringes. + (Overlay Arrow): Document overlay-arrow-variable-list. + (Fringe Size/Pos): New node, broken out of Fringes. + (Display): Explain clearing vs redisplay better. + (Truncation): Clarify use of bitmaps. + (The Echo Area): Clarify the uses of the echo area. + Add max-mini-window-height. + (Progress): Clarify. + (Invisible Text): Explain that main loop moves point out. + (Selective Display): Say "hidden", not "invisible". + (Managing Overlays): Move up. Describe relation to Undo here. + (Overlay Properties): Clarify intro. + (Finding Overlays): Explain return values when nothing found. + (Width): truncate-string-to-width has added arg. + (Displaying Faces): Clarify and update mode line face handling. + (Face Functions): Minor cleanup. + (Conditional Display): Merge into Other Display Specs. + (Pixel Specification, Other Display Specs): Minor cleanups. + (Images, Image Descriptors): Minor cleanups. + (GIF Images): Patents have expired. + (Showing Images): Explain default text for insert-image. + (Manipulating Button Types): Merge into Manipulating Buttons. + (Making Buttons): Explain return values. + (Button Buffer Commands): Add xref. + (Inverse Video): Update mode-line-inverse-video. + (Display Table Format): Clarify. + (Active Display Table): Give defaults for window-display-table. + + * calendar.texi (Calendar Customizing): calendar-holiday-marker + and calendar-today-marker are strings, not chars. + (Holiday Customizing): Minor fix. + + * internals.texi (Writing Emacs Primitives): Update `or' example. + Update limit on # args of subr. + + * edebug.texi (Using Edebug): Arrow is in fringe. + (Instrumenting): Arg to eval-defun works without loading edebug. + (Edebug Execution Modes): Add xref. + + * customize.texi (Common Keywords): Clarify :require. + Mention :version here. + (Variable Definitions, Group Definitions): Not here. + (Variable Definitions): Clarify symbol arg to :initialize and :set fns. + +2005-03-07 Chong Yidong + * nonascii.texi (Text Representations): Clarify position-bytes. + (Character Sets): Add list-charset-chars. + (Scanning Charsets): Add charset-after. + (Encoding and I/O): Minor fix. + +2005-03-06 Richard M. Stallman + + * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". + (Resizing Windows): Likewise. + + * text.texi (Change Hooks): Get rid of "Emacs 21". + + * strings.texi (Formatting Strings): Get rid of "Emacs 21". + + * streams.texi (Output Variables): Get rid of "Emacs 21". + + * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". + + * os.texi (Translating Input): Replace flow-control example + with a less obsolete example that uses `keyboard-translate'. + + * objects.texi (Hash Table Type, Circular Objects): + Get rid of "Emacs 21". + + * modes.texi (Mode Line Format): Get rid of "Emacs 21". + (Mode Line Data, Properties in Mode, Header Lines): Likewise. + + * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". + + * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". + + * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". + (Menu Bar): Fix when menu-bar-update-hook is called. + + * hash.texi (Hash Tables): Get rid of "Emacs 21". + + * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", + and make it read better. + + * files.texi (Writing to Files): Get rid of "Emacs 21". + (Unique File Names): Likewise. + + * elisp.texi: Update Emacs version to 22. + + * display.texi (Forcing Redisplay): Get rid of "Emacs 21". + (Overlay Properties, Face Attributes): Likewise. + (Managing Overlays): Fix punctuation. + (Attribute Functions): Clarify set-face-font; get rid of + info about old Emacs versions. + (Auto Faces, Font Lookup, Display Property, Images): + Get rid of "Emacs 21". + + * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". + +2005-03-05 Richard M. Stallman + + * debugging.texi (Error Debugging): Remove stack-trace-on-error. + +2005-03-04 Lute Kamstra + + * debugging.texi (Error Debugging): Document stack-trace-on-error. + +2005-03-03 Lute Kamstra + + * edebug.texi (Instrumenting Macro Calls): Fix typo. + +2005-03-01 Lute Kamstra + + * debugging.texi (Debugger Commands): Update `j'. + +2005-02-28 Lute Kamstra + + * debugging.texi (Debugging): Fix typo. + (Error Debugging): Document eval-expression-debug-on-error. + (Function Debugging): Update example. + (Using Debugger): Mention starred stack frames. + (Debugger Commands): Document `j' and `l'. + (Invoking the Debugger): `d' and `j' exit recursive edit too. + Update the messages that the debugger displays. + (Internals of Debugger): Add cross reference. Update example. + (Excess Open): Minor improvement. + (Excess Close): Minor improvement. + +2005-02-26 Richard M. Stallman + + * tips.texi (Coding Conventions): Clarify. + Put all the major mode key reservations together. + Mention the Mouse-1 => Mouse-2 conventions. + + * syntax.texi (Syntax Class Table): Clarify. + (Syntax Table Functions): syntax-after moved from here. + (Syntax Table Internals): syntax-after moved to here. + (Parsing Expressions): Update info on number of values + and what's meaningful in the STATE argument. + (Categories): Fix typo. + + * sequences.texi (Arrays): Cleanup. + (Char-Tables): Clarify. + + * processes.texi (Deleting Processes): Cleanups, add xref. + (Subprocess Creation): Explain nil in exec-path. Cleanup. + (Process Information): set-process-coding-system, some args optional. + (Input to Processes): Explain various types for PROCESS args. + Rename them from PROCESS-NAME to PROCESS. + (Signals to Processes): Likewise. + (Decoding Output): Cleanup. + (Query Before Exit): Clarify. + + * os.texi (Startup Summary): Correct the options; add missing ones. + (Terminal Output, Batch Mode): Clarify. + (Flow Control): Node deleted. + + * markers.texi (The Mark): Clarify. + + * macros.texi (Expansion): Cleanup. + (Indenting Macros): indent-spec allows ints, not floats. + + * keymaps.texi (Keymaps): Clarify. + (Format of Keymaps): Update lisp-mode-map example. + (Active Keymaps, Key Lookup): Clarify. + (Changing Key Bindings): Add xref to `kbd'. + (Key Binding Commands, Simple Menu Items): Clarify. + (Mouse Menus, Menu Bar): Clarify. + (Menu Example): Replace print example with menu-bar-replace-menu. + + * help.texi (Documentation Basics): Add function-documentation prop. + + * elisp.texi (Top): Don't refer to Flow Control node. + + * commands.texi (Command Overview): Improve xrefs. + (Adjusting Point): Adjusting point applies to intangible and invis. + (Key Sequence Input): Doc extra read-key-sequence args. + Likewise for read-key-sequence-vector. + + * backups.texi (Rename or Copy): Minor fix. + (Numbered Backups): For version-control, say the default. + (Auto-Saving): make-auto-save-file-name example is simplified. + + * advice.texi (Advising Functions): Don't imply one part of Emacs + should advise another part. Markup changes. + (Defining Advice): Move transitional para. + (Activation of Advice): Cleanup. + Explain if COMPILE is nil or negative. + + * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. + +2005-02-24 Lute Kamstra + + * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, + LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. + +2005-02-23 Lute Kamstra + + * modes.texi (Defining Minor Modes): define-minor-mode can be used + to define global minor modes as well. + + * display.texi (Managing Overlays): overlay-buffer returns nil for + deleted overlays. + +2005-02-22 Kim F. Storm + + * minibuf.texi (Basic Completion): Allow symbols in addition to + strings in try-completion and all-completions. + +2005-02-14 Lute Kamstra + + * elisp.texi (Top): Remove reference to deleted node. + + * lists.texi (Lists): Remove reference to deleted node. + (Cons Cells): Fix typo. + + * loading.texi (Where Defined): Fix typo. + +2005-02-14 Richard M. Stallman + + * variables.texi (Creating Buffer-Local): change-major-mode-hook + is useful for discarding some minor modes. + + * symbols.texi (Symbol Components): Reorder examples. + + * streams.texi (Input Functions): State standard-input default. + (Output Variables): State standard-output default. + + * objects.texi (Printed Representation): Clarify read syntax vs print. + (Floating Point Type): Explain meaning better. + (Symbol Type): Explain uniqueness better. + (Cons Cell Type): Explain empty list sooner. CAR and CDR later. + List examples sooner. + (Box Diagrams): New subnode broken out. + Some examples moved from old Lists as Boxes node. + (Dotted Pair Notation): Clarify intro. + (Array Type): Clarify. + (Type Predicates): Add hash-table-p. + + * numbers.texi (Integer Basics): Clarify radix explanation. + (Predicates on Numbers): Minor clarification. + (Comparison of Numbers): Minor clarification. Clarify eql. + Typos in min, max. + (Math Functions): Clarify overflow in expt. + + * minibuf.texi (Text from Minibuffer): Minor clarification. + Mention arrow keys. + + * loading.texi (Autoload): defun's doc string overrides autoload's + doc string. + (Repeated Loading): Modernize "add to list" examples. + (Where Defined): Finish updating table of load-history elts. + + * lists.texi (List-related Predicates): Minor wording improvement. + (Lists as Boxes): Node deleted. + (Building Lists): Explain trivial cases of number-sequence. + + * hash.texi (Hash Tables): Add desc to menu items. + (Creating Hash): Expain "full" means "make larger", + (Hash Access): Any object can be a key. + State value of maphash. + + * functions.texi (What Is a Function): Wording cleanup. + (Function Documentation): Minor cleanup. + Explain purpose of calling convention at end of doc string. + (Function Names): Wording cleanup. + (Calling Functions): Wording cleanup. + Explain better how funcall calls the function. + (Function Cells): Delete example of saving and redefining function. + + * control.texi (Combining Conditions): Wording cleanup. + (Iteration): dolist and dotimes bind VAR locally. + (Cleanups): Xref to Atomic Changes. + + * compile.texi (Byte Compilation): Delete 19.29 info. + (Compilation Functions): Macros' difficulties don't affect defsubst. + (Docs and Compilation): Delete 19.29 info. + +2005-02-10 Richard M. Stallman + + * objects.texi (Symbol Type): Minor correction. + +2005-02-06 Lute Kamstra + + * modes.texi (Example Major Modes): Fix typos. + +2005-02-06 Richard M. Stallman + + * text.texi (Margins): fill-nobreak-predicate can be one function. + + * strings.texi (Modifying Strings): clear-string can make unibyte. + (Formatting Strings): format gives error if values missing. + + * positions.texi (Character Motion): Mention default arg + for forward-char. backward-char refers to forward-char. + (Word Motion): Mention default arg for forward-word. + (Buffer End Motion): Mention default arg for beginning-of-buffer. + Simplify end-of-buffer. + (Text Lines): Mention default arg for forward-line. + (List Motion): Mention default arg for beginning/end-of-defun. + (Skipping Characters): Minor fixes in explaining character-set. + + * modes.texi (Major Mode Conventions): Mention "system abbrevs". + Mode inheritance applies only when default-major-mode is nil. + Clarifications. + (Example Major Modes): Update Text mode and Lisp mode examples. + (Minor Mode Conventions): Mention define-minor-mode at top. + (Defining Minor Modes): In Hungry example, don't define C-M-DEL. + (Mode Line Format): Update mode line face display info. + (Properties in Mode): Mention effect of risky vars. + (Imenu): Define imenu-add-to-menubar. + (Font Lock Mode): Add descriptions to menu lines. + (Faces for Font Lock): Add font-lock-doc-face. + +2005-02-05 Lute Kamstra + + * text.texi (Maintaining Undo): Remove obsolete function. + +2005-02-05 Eli Zaretskii + + * frames.texi (Color Names): Add pointer to the X docs about RGB + color specifications. Improve indexing + (Text Terminal Colors): Replace the description of RGB values by + an xref to "Color Names". + +2005-02-03 Richard M. Stallman + + * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. + Clarify. + (Selecting Windows): Clarify save-selected-window. + (Cyclic Window Ordering): Clarify walk-windows. + (Window Point): Clarify. + (Window Start): Add comment to example. + (Resizing Windows): Add `interactive' specs in examples. + Document fit-window-to-buffer. + + * text.texi (User-Level Deletion): just-one-space takes numeric arg. + (Undo, Maintaining Undo): Clarify last change. + (Sorting): In sort-numeric-fields, explain about octal and hex. + Mention sort-numeric-base. + (Format Properties): Add xref for hard newlines. + + * frames.texi (Window Frame Parameters): Explain pixel=char on tty. + (Pop-Up Menus): Fix typo. + (Color Names): Explain all types of color names. + Explain color-values on B&W terminal. + (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. + + * files.texi (File Locks): Not supported on MS systems. + (Testing Accessibility): Clarify. + + * edebug.texi (Printing in Edebug): Fix edebug-print-circle. + (Coverage Testing): Fix typo. + + * commands.texi (Misc Events): Remove stray space. + + * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. + (Modification Time): Clarify when visited-file-modtime returns 0. + (The Buffer List): Clarify bury-buffer. + (Killing Buffers): Clarify. + (Indirect Buffers): Add clone-indirect-buffer. + +2005-02-02 Matt Hodges + + * edebug.texi (Printing in Edebug): Fix default value of + edebug-print-circle. + (Coverage Testing): Fix displayed frequency count data. + +2005-02-02 Luc Teirlinck + + * text.texi (Maintaining Undo): Add `undo-outer-limit'. + +2005-02-02 Kim F. Storm + + * text.texi (Undo) : Describe `apply' elements. + +2005-01-29 Eli Zaretskii + + * commands.texi (Misc Events): Describe the help-echo event. + + * text.texi (Special Properties) : Use `pos' + consistently in description of the help-echo property. + Use @code{nil} instead of @var{nil}. + + * display.texi (Overlay Properties): Fix the index entry for + help-echo overlay property. + + * customize.texi (Type Keywords): Uncomment the xref to the + help-echo property documentation. + +2005-01-23 Kim F. Storm + + * windows.texi (Window Start): Fix `pos-visible-in-window-p' + return value. Third element FULLY replaced by PARTIAL which + specifies number of invisible pixels if row is only partially visible. + (Textual Scrolling): Mention auto-window-vscroll. + (Vertical Scrolling): New defvar auto-window-vscroll. + +2005-01-16 Luc Teirlinck + + * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses + command remapping. + +2005-01-15 Richard M. Stallman + + * display.texi (Defining Images): Mention DATA-P arg of create-image. + +2005-01-14 Kim F. Storm + + * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. + + * text.texi (Links and Mouse-1): Fix string and vector item. + +2005-01-13 Richard M. Stallman + + * keymaps.texi (Active Keymaps): Rewrite the text, and update the + descriptions of overriding-local-map and overriding-terminal-local-map. + + * text.texi (Links and Mouse-1): Clarify text. + +2005-01-13 Kim F. Storm + + * modes.texi (Emulating Mode Line): Update format-mode-line entry. + +2005-01-13 Francis Litterio (tiny change) + + * keymaps.texi (Active Keymaps): Fix overriding-local-map description. + +2005-01-12 Kim F. Storm + + * text.texi (Links and Mouse-1): Rename section from Enabling + Mouse-1 to Following Links. Change xrefs. + Add examples for define-button-type and define-widget. + + * display.texi (Button Properties, Button Buffer Commands): + Clarify mouse-1 and follow-link functionality. + +2005-01-12 Richard M. Stallman + + * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. + + * display.texi (Beeping): Fix Texinfo usage. + + * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. + +2005-01-11 Kim F. Storm + + * display.texi (Button Properties, Button Buffer Commands): + Mention mouse-1 binding. Add follow-link keyword. + + * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. + (Enabling Mouse-1 to Follow Links): New subsection. + +2005-01-06 Richard M. Stallman + + * text.texi (Special Properties): Minor change. + + * os.texi (Timers): Clarify previous change. + + * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. + +2005-01-01 Luc Teirlinck + + * display.texi (Face Attributes): Correct xref to renamed node. + +2005-01-01 Richard M. Stallman + + * display.texi (Face Attributes): Describe hex color specs. + +2004-12-31 Richard M. Stallman + + * os.texi (Timers): Update previous change. + +2004-12-30 Kim F. Storm + + * display.texi (Line Height): Total line-height is now specified + in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) + in cons cells. (nil . RATIO) is relative to actual line height. + Use line-height `t' instead of `0' to get minimum height. + +2004-12-29 Richard M. Stallman + + * os.texi (Timers): Discuss timers vs editing the buffer and undo. + +2004-12-28 Richard M. Stallman + + * commands.texi (Quitting): Clarify value of with-local-quit. + + * elisp.texi (Top): Fix previous change. + + * loading.texi (Loading): Fix previous change. + +2004-12-27 Richard M. Stallman + + * Makefile.in (MAKEINFO): Specify --force. + + * buffers.texi (Killing Buffers): Add buffer-save-without-query. + + * modes.texi (Emulating Mode Line): Document format's BUFFER arg. + + * display.texi (Line Height): Further clarify. + + * elisp.texi (Top): Update Loading submenu. + + * loading.texi (Where Defined): New node. + (Unloading): load-history moved to Where Defined. + +2004-12-21 Richard M. Stallman + + * commands.texi (Event Input Misc): Add while-no-input. + +2004-12-11 Richard M. Stallman + + * display.texi (Line Height): Rewrite text for clarity. + +2004-12-11 Kim F. Storm + + * display.texi (Display): Add node "Line Height" to menu. + (Line Height): New node. Move full description of line-spacing + and line-height text properties here from text.texi. + (Scroll Bars): Add vertical-scroll-bar variable. + + * frames.texi (Window Frame Parameters): Remove line-height defvar. + + * locals.texi (Standard Buffer-Local Variables): Fix xref for + line-spacing and vertical-scroll-bar. + + * text.texi (Special Properties): Just mention line-spacing and + line-height here, add xref to new "Line Height" node. + +2004-12-09 Thien-Thi Nguyen + + * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. + + * locals.texi (Standard Buffer-Local Variables): + Add @xref for `line-spacing'. + +2004-12-05 Richard M. Stallman + + * Makefile.in (maintainer-clean): Remove the info files + in $(infodir) where they are created. + +2004-12-03 Richard M. Stallman + + * windows.texi (Selecting Windows): get-lru-window and + get-largest-window don't consider dedicated windows. + + * text.texi (Undo): Document undo-in-progress. + +2004-11-26 Richard M. Stallman + + * locals.texi (Standard Buffer-Local Variables): Undo prev change. + Remove a few vars that are not always buffer-local. + +2004-11-24 Luc Teirlinck + + * locals.texi (Standard Buffer-Local Variables): Comment out + xref's to non-existent node `Yet to be written'. + +2004-11-24 Richard M. Stallman + + * processes.texi (Synchronous Processes): Grammar fix. + + * numbers.texi (Comparison of Numbers): Add eql. + + * locals.texi (Standard Buffer-Local Variables): Add many vars. + + * intro.texi (Printing Notation): Fix previous change. + + * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries + and default-indicate-buffer-boundaries from here. + (Usual Display): To here. + (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. + (Usual Display): Move tab-width up. + + * customize.texi (Variable Definitions): Replace + show-paren-mode example with tooltip-mode. + (Simple Types, Composite Types, Defining New Types): + Minor cleanups. + +2004-11-21 Jesper Harder + + * processes.texi (Synchronous Processes, Output from Processes): + Markup fix. + +2004-11-20 Richard M. Stallman + + * positions.texi (Skipping Characters): skip-chars-forward + now handles char classes. + + * intro.texi (Printing Notation): Avoid confusion of `print' + when explaining @print. + + * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. + + * display.texi (Display Table Format): Minor fix. + + * streams.texi (Output Functions): Fix print example. + + * Makefile.in (elisp): New target. + (dist): Depend on $(infodir)/elisp, not elisp. + Copy the info files from $(infodir). + + * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in + read-from-minibuffer. + + * searching.texi (Regexp Search): Rename that to search-spaces-regexp. + +2004-11-19 Richard M. Stallman + + * searching.texi (Regexp Search): Add search-whitespace-regexp. + +2004-11-19 CHENG Gao (tiny change) + + * tips.texi (Coding Conventions): Fix typo. + +2004-11-16 Richard M. Stallman + + * tips.texi (Coding Conventions): Separate defvar and require + methods to avoid warnings. Use require only when there are many + functions and variables from that package. + + * minibuf.texi (Minibuffer Completion): When ignoring case, + predicate must not be case-sensitive. + + * debugging.texi (Function Debugging, Explicit Debug): Clarified. + (Test Coverage): Don't talk about "splotches". Clarified. + +2004-11-16 Thien-Thi Nguyen + + * frames.texi (Window Frame Parameters): Fix typo. + +2004-11-15 Kim F. Storm + + * symbols.texi (Other Plists): Note that plist-get may signal error. + Add safe-plist-get. + +2004-11-15 Thien-Thi Nguyen + + * modes.texi (Font Lock Basics): Fix typo. + +2004-11-08 Richard M. Stallman + + * syntax.texi (Syntax Table Functions): Add syntax-after. + +2004-11-06 Lars Brinkhoff + + * os.texi (Processor Run Time): New section documenting + get-internal-run-time. + +2004-11-06 Eli Zaretskii + + * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as + it nukes elisp-cover.texi. + (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no + elisp-0 etc. + +2004-11-05 Luc Teirlinck + + * commands.texi (Keyboard Macros): Document `append' return value + of `defining-kbd-macro'. + +2004-11-01 Richard M. Stallman + + * commands.texi (Interactive Call): Add called-interactively-p. + +2004-10-29 Simon Josefsson + + * minibuf.texi (Reading a Password): Revert. + +2004-10-28 Richard M. Stallman + + * frames.texi (Display Feature Testing): Explain about "vendor". + +2004-10-27 Richard M. Stallman + + * commands.texi (Interactive Codes): `N' uses numeric prefix, + not raw. Clarify `n'. + (Interactive Call): Rewrite interactive-p, focusing on when + and how to use it. + (Misc Events): Clarify previous change. + + * advice.texi (Simple Advice): Clarify what job the example does. + (Around-Advice): Clarify ad-do-it. + (Activation of Advice): An option of ad-default-compilation-action + is `never', not `nil'. + +2004-10-26 Kim F. Storm + + * commands.texi (Interactive Codes): Add U code letter. + +2004-10-25 Simon Josefsson + + * minibuf.texi (Reading a Password): Add. + +2004-10-24 Jason Rumney + + * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up + and wheel-down. + +2004-10-24 Kai Grossjohann + + * processes.texi (Synchronous Processes): Document process-file. + +2004-10-22 Kenichi Handa + + * text.texi (translate-region): Document that it accepts also a + char-table. + +2004-10-22 David Ponce + + * windows.texi (Resizing Windows): Document the `preserve-before' + argument of the functions `enlarge-window' and `shrink-window'. + +2004-10-19 Jason Rumney + + * makefile.w32-in (elisp): Change order of arguments to makeinfo. + +2004-10-09 Luc Teirlinck + + * text.texi (Filling): Add anchor for definition of + `sentence-end-double-space'. + + * searching.texi (Regexp Example): Update description of how + Emacs currently recognizes the end of a sentence. + (Standard Regexps): Update definition of the variable + `sentence-end'. Add definition of the function `sentence-end'. + +2004-10-08 Paul Pogonyshev + + * display.texi (Progress): New node. + +2004-10-05 Kim F. Storm + + * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. + +2004-09-29 Kim F. Storm + + * display.texi (Fringe Bitmaps): Use symbols rather than numbers + to identify bitmaps. Remove -fringe-bitmap suffix for standard + fringe bitmap symbols, as they now have their own namespace. + (Customizing Bitmaps) : Clarify bit ordering + vs. pixels. Signal error if no free bitmap slots. + (Pixel Specification): Change IMAGE to @var{image}. + +2004-09-28 Richard M. Stallman + + * text.texi (Special Properties): Clarify line-spacing and line-height. + + * searching.texi (Regexp Search): Add looking-back. + +2004-09-25 Luc Teirlinck + + * display.texi: Correct typos. + (Image Descriptors): Correct xref's. + +2004-09-25 Richard M. Stallman + + * text.texi (Special Properties): Cleanups in `cursor'. + Rewrites in `line-height' and `line-spacing'; exchange them. + + * display.texi (Fringes): Rewrite previous change. + (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. + (Display Fringe Bitmaps): Node deleted, text moved. + (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. + (Scroll Bars): Clarify set-window-scroll-bars. + (Pointer Shape): Rewrite. + (Specified Space): Clarify :align-to, etc. + (Pixel Specification): Use @var. Clarify new text. + (Other Display Specs): Clarify `slice'. + (Image Descriptors): Cleanups. + (Showing Images): Cleanups. + +2004-09-24 Luc Teirlinck + + * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. + + * modes.texi: Various minor changes in addition to: + (Major Mode Conventions): Final call to `run-mode-hooks' should + not be inside the `delay-mode-hooks' form. + (Mode Hooks): New node. + (Hooks): Delete obsolete example. + Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new + node "Mode Hooks". + +2004-09-22 Luc Teirlinck + + * display.texi: Correct various typos. + (Display): Rename node "Pointer Shapes" to "Pointer + Shape". (There is already a node called "Pointer Shapes" in + frames.texi.) + (Images): Remove non-existent node "Image Slices" from menu. + +2004-09-23 Kim F. Storm + + * text.texi (Special Properties): Add `cursor', `pointer', + `line-height', and `line-spacing' properties. + + * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer + Shapes' to menu. + (Standard Faces): Doc fix for fringe face. + (Fringes): Add `overflow-newline-into-fringe' and + 'indicate-buffer-boundaries'. + (Fringe Bitmaps, Pointer Shapes): New nodes. + (Display Property): Add 'Pixel Specification' and 'Display Fringe + Bitmaps' to menu. + (Specified Space): Describe pixel width and height. + (Pixel Specification): New node. + (Other Display Specs): Add `slice' property. + (Display Fringe Bitmaps): New node. + (Images): Add 'Image Slices' to menu. + (Image Descriptors): Add `:pointer' and `:map' properties. + (Showing Images): Add slice arg to `insert-image'. Add + 'insert-sliced-image'. + +2004-09-20 Richard M. Stallman + + * commands.texi (Key Sequence Input): + Clarify downcasing in read-key-sequence. + +2004-09-08 Juri Linkov + + * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. + +2004-09-07 Luc Teirlinck + + * locals.texi (Standard Buffer-Local Variables): Add + `buffer-auto-save-file-format'. + * internals.texi (Buffer Internals): Describe new + auto_save_file_format field of the buffer structure. + * files.texi (Format Conversion): `auto-save-file-format' has been + renamed `buffer-auto-save-file-format'. + +2004-08-27 Luc Teirlinck + + * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be + an integer or a marker. + (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. + +2004-08-22 Richard M. Stallman + + * modes.texi (Major Mode Conventions): Discuss rebinding of + standard key bindings. + +2004-08-18 Kim F. Storm + + * processes.texi (Accepting Output): Add `just-this-one' arg to + `accept-process-output'. + (Output from Processes): New var `process-adaptive-read-buffering'. + +2004-08-10 Luc Teirlinck + + * keymaps.texi: Various changes in addition to: + (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. + Give more varied examples for `kbd'. + (Creating Keymaps): Char tables have slots for all characters + without modifiers. + (Active Keymaps): `overriding-local-map' and + `overriding-terminal-local-map' also override text property and + overlay keymaps. + (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. + (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' + to denote a prefix of no events. + `map-keymap' includes parent's bindings _recursively_. + Clarify and correct description of `where-is-internal'. + Mention BUFFER-OR-NAME arg to `describe-bindings'. + (Menu Example): For menus intended for use with the keyboard, the + menu items should be bound to characters or real function keys. + +2004-08-08 Luc Teirlinck + + * objects.texi (Character Type): Reposition `@anchor' to prevent + double space inside sentence in Info. + + * hooks.texi (Standard Hooks): `disabled-command-hook' has been + renamed to `disabled-command-function'. + * commands.texi (Key Sequence Input): Remove unnecessary anchor. + (Command Loop Info): Replace reference to it. + (Disabling Commands): `disabled-command-hook' has been renamed to + `disabled-command-function'. + +2004-08-07 Luc Teirlinck + + * os.texi (Translating Input): Only non-prefix bindings in + `key-translation-map' override actual key bindings. Warn about + possible indirect effect of actual key bindings on non-prefix + bindings in `key-translation-map'. + +2004-08-06 Luc Teirlinck + + * minibuf.texi (High-Level Completion): Add anchor for definition + of `read-variable'. + + * commands.texi: Various changes in addition to: + (Using Interactive): Clarify description of `interactive-form'. + (Interactive Call): Mention default for KEYS argument to + `call-interactively'. + (Command Loop Info): Clarify description of `this-command-keys'. + Mention KEEP-RECORD argument to `clear-this-command-keys'. + Value of `last-event-frame' can be `macro'. + (Repeat Events): `double-click-fuzz' is also used to distinguish + clicks and drags. + (Classifying Events): Clarify descriptions of `event-modifiers' + `event-basic-type' and `event-convert-list'. + (Accessing Events): `posn-timestamp' takes POSITION argument. + (Quoted Character Input): Clarify description of + `read-quoted-char' and fix example. + (Quitting): Add `with-local-quit'. + (Disabling Commands): Correct and clarify descriptions of + `enable-command' and `disable-command'. + Mention what happens if `disabled-command-hook' is nil. + (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. + Describe `executing-kbd-macro' instead of obsolete `executing-macro'. + +2004-07-24 Luc Teirlinck + + * frames.texi: Various changes in addition to: + (Creating Frames): Expand and clarify description of `make-frame'. + (Window Frame Parameters): Either none or both of the `icon-left' + and `icon-top' parameters must be specified. Put descriptions of + `menu-bar-lines' and `toolbar-lines' closer together and change + them accordingly. + (Frame Titles): `multiple-frames' is not guaranteed to be accurate + except while processing `frame-title-format' or `icon-title-format'. + (Deleting Frames): Correct description of `delete-frame'. + Non-nil return values of `frame-live-p' are like those of `framep'. + (Frames and Windows): Mention return value of + `set-frame-selected-window'. + (Visibility of Frames): Mention `force' argument to + `make-frame-invisible'. `frame-visible-p' returns t for all + frames on text-only terminals. + (Frame Configurations): Restoring a frame configuration does not + restore deleted frames. + (Window System Selections): `x-set-selection' returns DATA. + (Resources): Add example. + (Display Feature Testing): Clarify descriptions of + `display-pixel-height', `display-pixel-width', `x-server-version' + and `x-server-vendor'. + + * windows.texi (Choosing Window): Add anchor. + * minibuf.texi (Minibuffer Misc): Add anchor. + +2004-07-23 John Paul Wallington + + * macros.texi (Defining Macros): Declaration keyword for setting + Edebug spec is `debug' not `edebug'. + +2004-07-19 Luc Teirlinck + + * windows.texi: Various small changes in addition to: + (Window Point): Mention return value of `set-window-point'. + (Window Start): `pos-visible-in-window-p' disregards horizontal + scrolling. Explain return value if PARTIALLY is non-nil. + (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' + and `set-window-vscroll'. + (Size of Window): The argument WINDOW to `window-inside-edges', + `window-pixel-edges' and `window-inside-pixel-edges' is optional. + (Resizing Windows): Explain return value of + `shrink-window-if-larger-than-buffer'. + `window-size-fixed' automatically becomes buffer local when set. + (Window Configurations): Explain return value of + `set-window-configuration'. + + * minibuf.texi (Minibuffer Misc): Add anchor for + `minibuffer-scroll-window'. + + * positions.texi (Text Lines): Add anchor for `count-lines'. + +2004-07-17 Richard M. Stallman + + * display.texi (Overlay Properties): Adding `evaporate' prop + deletes empty overlay immediately. + + * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, + fix example. + +2004-07-16 Jim Blandy + + * searching.texi (Regexp Backslash): Document new \_< and \_> + operators. + +2004-07-16 Juanma Barranquero + + * display.texi (Images): Fix Texinfo usage. + +2004-07-14 Luc Teirlinck + + * buffers.texi (Modification Time): `visited-file-modtime' now + returns a list of two integers, instead of a cons. + +2004-07-13 Luc Teirlinck + + * windows.texi: Various changes in addition to: + (Splitting Windows): Add `split-window-keep-point'. + +2004-07-09 Richard M. Stallman + + * frames.texi (Input Focus): Minor fix. + +2004-07-07 Luc Teirlinck + + * frames.texi (Input Focus): Clarify descriptions of + `select-frame-set-input-focus' and `select-frame'. + +2004-07-06 Luc Teirlinck + + * os.texi: Various small changes in addition to: + (Killing Emacs): Expand and clarify description of + `kill-emacs-query-functions' and `kill-emacs-hook'. + (System Environment): Expand and clarify description of `getenv' + and `setenv'. + (Timers): Clarify description of `run-at-time'. + (Translating Input): Correct description of + `extra-keyboard-modifiers'. + (Flow Control): Correct description of `enable-flow-control'. + +2004-07-06 Thien-Thi Nguyen + + * os.texi: Update copyright. + (Session Management): Grammar fix. + Clarify which Emacs does the restarting. + Use @samp for *scratch* buffer. + +2004-07-04 Alan Mackenzie + + * frames.texi (Input Focus): Add documentation for + `select-frame-set-input-focus'. Replace refs to non-existent + `switch-frame' with `select-frame'. Minor corrections and tidying + up of text-only terminal stuff. + +2004-07-02 Richard M. Stallman + + * files.texi (Saving Buffers): Cleanup write-contents-function. + (Magic File Names): Cleanup file-remote-p. + +2004-07-02 Kai Grossjohann + + * files.texi (Magic File Names): `file-remote-p' returns an + identifier of the remote system, not just t. + +2004-07-02 David Kastrup + + * searching.texi (Entire Match Data): Add explanation about new + match-data behavior when @var{integers} is non-nil. + +2004-06-24 Richard M. Stallman + + * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. + + * customize.texi (Variable Definitions): Note about doc strings + and :set. + + * keymaps.texi (Keymap Terminology): Document `kbd'. + (Changing Key Bindings, Key Binding Commands): Use kbd in examples. + + * display.texi (Invisible Text): Setting buffer-invisibility-spec + makes it buffer-local. + + * files.texi (Saving Buffers): Correct previous change. + + * commands.texi (Accessing Events): + Clarify posn-col-row and posn-actual-col-row. + +2004-06-24 David Ponce + + * commands.texi (Accessing Events): New functions + posn-at-point and posn-at-x-y. Add example to posn-x-y. + +2004-06-23 Luc Teirlinck + + * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: + * frames.texi, buffers.texi, backups.texi, variables.texi: + * loading.texi, eval.texi, functions.texi, control.texi: + * symbols.texi, minibuf.texi: Reposition @anchor's. + + * help.texi: Various small changes in addition to the following. + (Describing Characters): Describe PREFIX argument to + `key-description'. Correct and clarify definition of + `text-char-description'. Describe NEED-VECTOR argument to + `read-kbd-macro'. + (Help Functions): Clarify definition of `apropos'. + +2004-06-23 Lars Hansen + + * files.texi (Saving Buffers): Correct description of + `write-contents-functions'. + +2004-06-21 Juanma Barranquero + + * display.texi (Images): Remove redundant @vindex directives. + Rewrite `image-library-alist' doc in active voice. + +2004-06-14 Juanma Barranquero + + * display.texi (Images): Document new delayed library loading, + variable `image-library-alist' and (existing but undocumented) + function `image-type-available-p'. + +2004-06-05 Richard M. Stallman + + * minibuf.texi (Minibuffer Completion): For INITIAL arg, + refer the user to the Initial Input node. + (Text from Minibuffer): Likewise. + (Initial Input): New node. Document this feature + and say it is mostly deprecated. + +2004-05-30 Richard M. Stallman + + * loading.texi (Named Features): Clarify return value + and meaning of NOERROR. + + * variables.texi (File Local Variables): Minor cleanup. + +2004-05-30 Michael Albinus + + * files.texi (Magic File Names): Add `file-remote-p' as operation + of file name handlers. + +2004-05-29 Richard M. Stallman + + * modes.texi (Minor Mode Conventions): (-) has no special meaning + as arg to a minor mode command. + +2004-05-22 Richard M. Stallman + + * syntax.texi (Syntax Class Table): Word syntax not just for English. + + * streams.texi (Output Variables): Doc float-output-format. + + * searching.texi (Regexp Special): Nested repetition can be infloop. + + * eval.texi (Eval): Increasing max-lisp-eval-depth can cause + real stack overflow. + + * compile.texi: Minor cleanups. + +2004-05-22 Luc Teirlinck + + * lists.texi (Cons Cells): Explain dotted lists, true lists, + circular lists. + (List Elements): Explain handling of circular and dotted lists. + +2004-05-19 Thien-Thi Nguyen + + * modes.texi (Search-based Fontification): Fix typo. + +2004-05-10 Juanma Barranquero + + * modes.texi (Mode Line Variables): Fix description of + global-mode-string, which is now after which-func-mode, not the + buffer name. + +2004-05-07 Lars Hansen + + * modes.texi (Desktop Save Mode): Add. + (Modes): Add menu entry Desktop Save Mode. + + * hooks.texi: Add desktop-after-read-hook, + desktop-no-desktop-file-hook and desktop-save-hook. + + * locals.texi: Add desktop-save-buffer. + +2004-04-30 Jesper Harder + + * display.texi: emacs -> Emacs. + +2004-04-27 Matthew Mundell + + * files.texi (Changing Files): Document set-file-times. + +2004-04-23 Juanma Barranquero + + * makefile.w32-in: Add "-*- makefile -*-" mode tag. + +2004-04-18 Jesper Harder + + * tips.texi (Coding Conventions): defopt -> defcustom. + +2004-04-16 Luc Teirlinck + + * sequences.texi: Various clarifications. + +2004-04-14 Luc Teirlinck + + * buffers.texi (Read Only Buffers): Mention optional ARG to + `toggle-read-only'. + +2004-04-14 Nick Roberts + + * windows.texi (Selecting Windows): Note that get-lru-window + returns a full-width window if possible. + +2004-04-13 Luc Teirlinck + + * buffers.texi: Various changes in addition to: + (Buffer File Name): Add `find-buffer-visiting'. + (Buffer Modification): Mention optional ARG to `not-modified'. + (Indirect Buffers): Mention optional CLONE argument to + `make-indirect-buffer'. + + * files.texi: Various changes in addition to: + (Visiting Functions): `find-file-hook' is now a normal hook. + (File Name Expansion): Explain difference between the way that + `expand-file-name' and `file-truename' treat `..'. + (Contents of Directories): Mention optional ID-FORMAT argument to + `directory-files-and-attributes'. + (Format Conversion): Mention new optional CONFIRM argument to + `format-write-file'. + +2004-04-12 Miles Bader + + * macros.texi (Expansion): Add description of `macroexpand-all'. + +2004-04-05 Jesper Harder + + * variables.texi (Variable Aliases): Mention + cyclic-variable-indirection. + + * errors.texi (Standard Errors): Ditto. + +2004-04-04 Luc Teirlinck + + * backups.texi: Various small changes in addition to: + (Making Backups): Mention return value of `backup-buffer'. + (Auto-Saving): Mention optional FORCE argument to + `delete-auto-save-file-if-necessary'. + (Reverting): Mention optional PRESERVE-MODES argument to + `revert-buffer'. Correct description of `revert-buffer-function'. + +2004-03-22 Juri Linkov + + * sequences.texi (Sequence Functions): Replace xref to `Vectors' + with `Vector Functions'. + + * text.texi (Sorting): Add missing quote. + +2004-03-14 Luc Teirlinck + + * intro.texi (Lisp History): Replace xref to `cl' manual with + inforef. + +2004-03-12 Richard M. Stallman + + * intro.texi (Version Info): Add arg to emacs-version. + (Lisp History): Change xref to CL manual. + +2004-03-09 Luc Teirlinck + + * minibuf.texi (Completion Commands): Add xref to Emacs manual + for Partial Completion mode. + +2004-03-07 Thien-Thi Nguyen + + * customize.texi: Fix typo. Remove eol whitespace. + +2004-03-04 Richard M. Stallman + + * processes.texi: Fix typos. + + * lists.texi (Building Lists): Minor clarification. + + * hash.texi (Creating Hash): Correct the meaning of t for WEAK + in make-hash-table. + +2004-02-29 Juanma Barranquero + + * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of + rm, and ignore exit code. + +2004-02-27 Dan Nicolaescu + + * display.texi (Defining Faces): Add description for min-colors. + Update example. + +2004-02-23 Luc Teirlinck + + * abbrevs.texi: Various corrections and clarifications in addition + to the following: + (Abbrev Tables): Delete add-abbrev (as suggested by RMS). + +2004-02-22 Matthew Mundell (tiny change) + + * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. + +2004-02-21 Luc Teirlinck + + * text.texi: Various small changes in addition to the following: + (User-Level Deletion): Mention optional BACKWARD-ONLY argument + to delete-horizontal-space. + (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct + description of yank-handler text property at various places. + + * frames.texi (Window System Selections): Add anchor. + + * syntax.texi (Syntax Table Functions): Clarify and correct + descriptions of make-syntax-table and copy-syntax-table. + (Motion and Syntax): Clarify SYNTAXES argument to + skip-syntax-forward. + (Parsing Expressions): Mention that the return value of + parse-partial-sexp is currently a list of ten rather than nine + elements. + (Categories): Various corrections and clarifications. + +2004-02-17 Luc Teirlinck + + * markers.texi (Marker Insertion Types): Minor change. + + * locals.texi (Standard Buffer-Local Variables): + * commands.texi (Interactive Codes, Using Interactive): + * functions.texi (Related Topics): Fix xrefs. + +2004-02-16 Luc Teirlinck + + * lists.texi (Sets And Lists): Update description of delete-dups. + +2004-02-16 Jesper Harder (tiny change) + + * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. + +2004-02-16 Jan Dj,Ad(Brv + + * frames.texi (Parameter Access): frame-parameters arg is optional. + modify-frame-parameters handles nil for FRAME. + (Window Frame Parameters): menu-bar-lines and tool-bar-lines + are all-or-nothing for certain toolkits. + Mention parameter wait-for-wm. + (Frames and Windows): In frame-first-window and frame-selected-window + the arg is optional. + (Input Focus): In redirect-frame-focus the second arg is optional. + (Window System Selections): Mention selection type CLIPBOARD. + Mention data-type UTF8_STRING. + Mention numbering of cut buffers. + (Resources): Describe x-resource-name. + +2004-02-16 Richard M. Stallman + + * windows.texi (Buffers and Windows): Delete false table + about all-frames. + + * syntax.texi (Parsing Expressions): Delete old caveat + about parse-sexp-ignore-comments. + + * streams.texi (Output Variables): Add print-quoted. + + * lists.texi (Building Lists): Minor cleanup. + + * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. + + * display.texi (Overlays): Explain overlays use markers. + (Managing Overlays): Explain front-advance and rear-advance + in more detail. + + * loading.texi (Unloading): Document unload-feature-special-hooks. + Get rid of fns-NNN.el file. + +2004-02-16 Matthew Mundell (tiny change) + + * help.texi (Describing Characters): Fix text-char-description + example output. + + * edebug.texi (Using Edebug): Fix example. + + * debugging.texi (Internals of Debugger): Fix return value. + + * files.texi (Changing Files): Fix argname. + + * calendar.texi: Fix parens, and default values. + + * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. + * nonascii.texi, objects.texi, os.texi: Minor fixes. + * searching.texi, text.texi, tips.texi, windows.text: Minor fixes. + + * positions.texi (Text Lines): Don't add -1 in current-line. + +2004-02-16 Richard M. Stallman + + * compile.texi (Compiler Errors): if-boundp feature applies to cond. + +2004-02-16 Jesper Harder (tiny change) + + * processes.texi (Low-Level Network): Fix a typo. + +2004-02-12 Kim F. Storm + + * display.texi (Fringes): Use consistent wording. + Note that window-fringe's window arg is optional. + (Scroll Bars): Use consistent wording. + +2004-02-11 Luc Teirlinck + + * tips.texi (Comment Tips): Document the new conventions for + commenting out code. + +2004-02-07 Jan Dj,Ad(Brv + + * positions.texi (Text Lines): Added missing end defun. + +2004-02-07 Kim F. Storm + + * positions.texi (Text Lines): Add line-number-at-pos. + +2004-02-06 John Paul Wallington + + * display.texi (Button Properties, Button Buffer Commands): + mouse-2 invokes button, not down-mouse-1. + +2004-02-04 Jason Rumney + + * makefile.w32-in: Sync with Makefile.in changes. + +2004-02-03 Luc Teirlinck + + * minibuf.texi (Text from Minibuffer): Various corrections and + clarifications. + (Object from Minibuffer): Correct Lisp description of + read-minibuffer. + (Minibuffer History): Clarify description of cons values for + HISTORY arguments. + (Basic Completion): Various corrections and clarifications. Add + completion-regexp-list. + (Minibuffer Completion): Correct and clarify description of + completing-read. + (Completion Commands): Mention Partial Completion mode. Various + other minor changes. + (High-Level Completion): Various corrections and clarifications. + (Reading File Names): Ditto. + (Minibuffer Misc): Ditto. + +2004-01-26 Luc Teirlinck + + * strings.texi (Text Comparison): assoc-string also matches + elements of alists that are strings instead of conses. + (Formatting Strings): Standardize Texinfo usage. Update index + entries. + +2004-01-20 Luc Teirlinck + + * lists.texi (Sets And Lists): Add delete-dups. + +2004-01-15 Luc Teirlinck + + * edebug.texi (Instrumenting Macro Calls): `declare' is not a + special form. + * macros.texi (Defining Macros): Update description of `declare', + which now is a macro. + (Wrong Time): Fix typos. + +2004-01-14 Luc Teirlinck + + * compile.texi (Compilation Functions): Expand descriptions of + `compile-defun', `byte-compile-file', `byte-recompile-directory' + and `batch-byte-compile'. In particular, mention and describe + all optional arguments. + (Disassembly): Correct and clarify the description of `disassemble'. + +2004-01-11 Luc Teirlinck + + * searching.texi: Various small changes in addition to the + following. + (Regexp Example): Adapt to new value of `sentence-end'. + (Regexp Functions): The PAREN argument to `regexp-opt' can be + `words'. + (Search and Replace): Add usage note for `perform-replace'. + (Entire Match Data): Mention INTEGERS and REUSE arguments to + `match-data'. + (Standard Regexps): Update for new values of `paragraph-start' + and `sentence-end'. + +2004-01-07 Luc Teirlinck + + * files.texi (Saving Buffers): Clarify descriptions of + `write-contents-functions' and `before-save-hook'. + Make the defvar's for `before-save-hook' and `after-save-hook' + into defopt's. + +2004-01-07 Kim F. Storm + + * commands.texi (Click Events): Describe new image and + width/height elements of click events. + (Accessing Events): Add posn-string, posn-image, and + posn-object-width-height. Change posn-object to return either + image or string object. + +2004-01-01 Simon Josefsson + + * hooks.texi (Standard Hooks): Add before-save-hook. + * files.texi (Saving Buffers): Likewise. + +2004-01-03 Richard M. Stallman + + * frames.texi (Frames and Windows): Delete frame-root-window. + +2004-01-03 Luc Teirlinck + + * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. + + * functions.texi: Various small changes in addition to the + following. + (What Is a Function): `functionp' returns nil for macros. Clarify + behavior of this and following functions for symbol arguments. + (Function Documentation): Add `\' in front of (fn @var{arglist}) + and explain why. + (Defining Functions): Mention DOCSTRING argument to `defalias'. + Add anchor. + (Mapping Functions): Add anchor. Unquote nil in mapcar* example. + +2004-01-01 Miles Bader + + * display.texi (Buttons): New section. + +2003-12-31 Andreas Schwab + + * numbers.texi (Math Functions): sqrt reports a domain-error + error. + (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. + +2003-12-30 Luc Teirlinck + + * tips.texi (Documentation Tips): Update item on hyperlinks in + documentation strings. + + * errors.texi (Standard Errors): Various small corrections and + additions. + + * control.texi: Various small changes in addition to the + following. + (Signaling Errors): Provide some more details on how `signal' + constructs the error message. Add anchor to the definition of + `signal'. + (Error Symbols): Describe special treatment of `quit'. + (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM + to emphasize that it has to be a single form. + + * buffers.texi: Add anchor. + +2003-12-29 Richard M. Stallman + + * windows.texi (Choosing Window): Add same-window-p, special-display-p. + (Window Configurations): Add window-configuration-frame. + + * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. + + * text.texi (Examining Properties): Add get-char-property-and-overlay. + Change arg name in get-char-property. + (Special Properties): Update handling of keymap property. + + * strings.texi (Modifying Strings): Add clear-string. + (Text Comparison): Add assoc-string and remove + assoc-ignore-case, assoc-ignore-representation. + + * os.texi (Time of Day): Add set-time-zone-rule. + + * numbers.texi (Math Functions): asin, acos, log, log10 + report domain-error errors. + + * nonascii.texi (Converting Representations): + Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. + (Encoding and I/O): Add file-name-coding-system. + + * modes.texi (Search-based Fontification): Explain that + face specs are symbols with face names as values. + + * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. + + * lists.texi (Building Lists): remq moved elsewhere. + (Sets And Lists): remq moved here. + (Association Lists): Refer to assoc-string. + + * internals.texi (Garbage Collection): Add memory-use-counts. + + * frames.texi (Frames and Windows): Add set-frame-selected-window + and frame-root-window. + + * files.texi (Contents of Directories): + Add directory-files-and-attributes. + + * display.texi (Refresh Screen): Add force-window-update. + (Invisible Text): Explain about moving point out of invis text. + (Overlay Properties): Add overlay-properties. + (Managing Overlays): Add overlayp. + (GIF Images): Invalid image number displays a hollow box. + + * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. + (Killing Buffers): Add buffer-live-p. + +2003-12-25 Markus Rost + + * display.texi (Fringes): Fix typo "set-buffer-window". + +2003-12-24 Luc Teirlinck + + * display.texi, eval.texi, help.texi, internals.texi, loading.texi: + * nonascii.texi, processes.texi, tips.texi, variables.texi: + Add or change various xrefs and anchors. + + * commands.texi: Replace all occurrences of @acronym{CAR} with + @sc{car}, for consistency with the rest of the Elisp manual. + `car' and `cdr' are historically acronyms, but are no longer + widely thought of as such. + + * internals.texi (Pure Storage): Mention that `purecopy' does not + copy text properties. + (Object Internals): Now 29 bits are used (in most implementations) + to address Lisp objects. + + * variables.texi (Variables with Restricted Values): New node. + + * objects.texi (Lisp Data Types): Mention that certain variables + can only take on a restricted set of values and add an xref to + the new node "Variables with Restricted Values". + + * eval.texi (Function Indirection): Describe the errors that + `indirect-function' can signal. + (Eval): Clarify the descriptions of `eval-region' and `values'. + Describe `eval-buffer' instead of `eval-current-buffer' and + mention `eval-current-buffer' as an alias for `current-buffer'. + Correct the description and mention all optional arguments. + + * nonascii.texi: Various small changes in addition to the + following. + (Converting Representations): Clarify behavior of + `string-make-multibyte' and `string-to-multibyte' for unibyte all + ASCII arguments. + (Character Sets): Document the variable `charset-list' and adapt + the definition of the function `charset-list' accordingly. + (Translation of Characters): Clarify use of generic characters in + `make-translation-table'. Clarify and correct the description of + the use of translation tables in encoding and decoding. + (User-Chosen Coding Systems): Correct and clarify the description + of `select-safe-coding-system'. + (Default Coding Systems): Clarify description of + `file-coding-system-alist'. + +2003-11-30 Luc Teirlinck + + * strings.texi (Text Comparison): Correctly describe when two + strings are `equal'. Combine and clarify descriptions of + `assoc-ignore-case' and `assoc-ignore-representation'. + + * objects.texi (Non-ASCII in Strings): Clarify description of + when a string is unibyte or multibyte. + (Bool-Vector Type): Update examples. + (Equality Predicates): Correctly describe when two strings are + `equal'. + +2003-11-29 Luc Teirlinck + + * lists.texi (Building Lists): `append' no longer accepts integer + arguments. Update the description of `number-sequence' to reflect + recent changes. + (Sets And Lists): Describe `member-ignore-case' after `member'. + +2003-11-27 Kim F. Storm + + * commands.texi (Click Events): Click object may be an images. + Describe (dx . dy) element of click positions. + (Accessing Events): Remove duplicate posn-timestamp. + New functions posn-object and posn-object-x-y. + +2003-11-23 Kim F. Storm + + * commands.texi (Click Events): Describe enhancements to event + position lists, including new text-pos and (col . row) items. + Mention left-fringe and right-fringe area events. + (Accessing Events): New functions posn-area and + posn-actual-col-row. Mention posn-timestamp. Mention that + posn-point in non-text area still returns buffer position. + Clarify posn-col-row. + +2003-11-21 Lars Hansen + + * files.texi (File Attributes): Describe new parameter ID-FORMAT. + * anti.texi (File Attributes): Describe removed parameter + ID-FORMAT. + +2003-11-20 Luc Teirlinck + + * positions.texi (Positions): Mention that, if a marker is used as + a position, its buffer is ignored. + + * markers.texi (Overview of Markers): Mention it here too. + +2003-11-12 Luc Teirlinck + + * numbers.texi (Numeric Conversions): Not just `floor', but also + `truncate', `ceiling' and `round' accept optional argument DIVISOR. + +2003-11-10 Luc Teirlinck + + * markers.texi (Creating Markers): Specify insertion type of + created markers. Add xref to `Marker Insertion Types'. + Second argument to `copy-marker' is optional. + (Marker Insertion Types): Mention that most markers are created + with insertion type nil. + (The Mark): Correctly describe when `mark' signals an error. + (The Region): Correctly describe when `region-beginning' and + `region-end' signal an error. + +2003-11-08 Luc Teirlinck + + * hash.texi (Creating Hash): Clarify description of `eql'. + `makehash' is obsolete. + (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. + + * positions.texi (Point): Change description of `buffer-end', so + that it is also correct for floating point arguments. + (List Motion): Correct argument lists of `beginning-of-defun' and + `end-of-defun'. + (Excursions): Add xref to `Marker Insertion Types'. + (Narrowing): Argument to `narrow-to-page' is optional. + +2003-11-06 Luc Teirlinck + + * streams.texi (Output Streams): Clarify behavior of point for + marker output streams. + +2003-11-04 Luc Teirlinck + + * variables.texi (Defining Variables): Second argument to + `defconst' is not optional. + (Setting Variables): Mention optional argument APPEND to + `add-to-list'. + (Creating Buffer-Local): Expand description of + `make-variable-buffer-local'. + (Frame-Local Variables): Expand description of + `make-variable-frame-local'. + (Variable Aliases): Correct description of optional argument + DOCSTRING to `defvaralias'. Mention return value of + `defvaralias'. + (File Local Variables): Add xref to `File variables' in Emacs + Manual. Correct description of `hack-local-variables'. Mention + `safe-local-variable' property. Mention optional second argument + to `risky-local-variable-p'. + +2003-11-03 Luc Teirlinck + + * symbols.texi (Symbol Plists): Mention return value of `setplist'. + +2003-11-02 Jesper Harder (tiny change) + + * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi + lispref/customize.texi, lispref/display.texi, lispref/files.texi, + lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, + lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, + lispref/objects.texi, lispref/os.texi, lispref/positions.texi, + lispref/processes.texi, lispref/searching.texi, + lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, + lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with + @acronym{FOO}. + +2003-10-27 Luc Teirlinck + + * strings.texi (Creating Strings): Argument START to `substring' + can not be `nil'. Expand description of + `substring-no-properties'. Correct description of `split-string', + especially with respect to empty matches. Prevent very bad line + break in definition of `split-string-default-separators'. + (Text Comparison): `string=' and `string<' also accept symbols as + arguments. + (String Conversion): More completely describe argument BASE in + `string-to-number'. + (Formatting Strings): `%s' and `%S' in `format' do require + corresponding object. Clarify behavior of numeric prefix after + `%' in `format'. + (Case Conversion): The argument to `upcase-initials' can be a + character. + +2003-10-27 Kenichi Handa + + * display.texi (Fontsets): Fix texinfo usage. + +2003-10-25 Kenichi Handa + + * display.texi (Fontsets): Add description of the function + set-fontset-font. + +2003-10-23 Luc Teirlinck + + * display.texi (Temporary Displays): Add xref to `Documentation + Tips'. + + * functions.texi (Function Safety): Use inforef instead of pxref + for SES. + +2003-10-23 Andreas Schwab + + * Makefile.in (TEX, texinputdir): Don't define. + (TEXI2DVI): Define. + (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, + add $(srcdir)/index.texi. + ($(infodir)/elisp): Remove index.texi dependency. + (elisp.dvi): Likewise. Use $(TEXI2DVI). + (index.texi): Remove target. + (dist): Don't link $(srcdir)/permute-index. + (clean): Don't remove index.texi. + + * permute-index, index.perm: Remove. + * index.texi: Rename from index.unperm. + +2003-10-22 Luc Teirlinck + + * tips.texi (Documentation Tips): Document new behavior for face + and variable hyperlinks in Help mode. + +2003-10-21 Luc Teirlinck + + * objects.texi (Integer Type): Update for extra bit of integer range. + (Character Type): Ditto. + +2003-10-16 Eli Zaretskii + + * numbers.texi (Integer Basics): Add index entries for reading + numbers in hex, octal, and binary. + +2003-10-16 Lute Kamstra + + * modes.texi (Mode Line Format): Mention force-mode-line-update's + argument. + +2003-10-13 Luc Teirlinck + + * windows.texi (Choosing Window): Fix typo. + * edebug.texi (Edebug Execution Modes): Fix typo. + +2003-10-13 Richard M. Stallman + + * windows.texi (Basic Windows): A window has fringe settings, + display margins and scroll-bar settings. + (Splitting Windows): Doc split-window return value. + Clean up one-window-p. + (Selecting Windows): Fix typo. + (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. + (Buffers and Windows): In set-window-buffer, explain effect + on fringe settings and scroll bar settings. + (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. + (Choosing Window): Use defopt for pop-up-frame-function. + For special-display-buffer-names, explain same-window and same-frame. + Clarify window-dedicated-p return value. + (Textual Scrolling): scroll-up and scroll-down can get an error. + (Horizontal Scrolling): Clarify auto-hscroll-mode. + Clarify set-window-hscroll. + (Size of Window): Don't mention tool bar in window-height. + (Coordinates and Windows): Explain what coordinates-in-window-p + returns for fringes and display margins. + (Window Configurations): Explain saving fringes, etc. + + * tips.texi (Library Headers): Clean up Documentation. + + * syntax.texi (Parsing Expressions): Clean up forward-comment + and parse-sexp-lookup-properties. + + * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. + + * os.texi (System Environment): Clean up text for load-average errors. + + * modes.texi (Hooks): Don't explain local hook details at front. + Clarify run-hooks and run-hook-with-args a little. + Clean up add-hook and remove-hook. + + * edebug.texi (Edebug Execution Modes): Clarify t. + Document edebug-sit-for-seconds. + (Coverage Testing): Document C-x X = and =. + (Instrumenting Macro Calls): Fix typo. + (Specification List): Don't index the specification keywords. + +2003-10-10 Kim F. Storm + + * processes.texi (Network): Introduce make-network-process. + +2003-10-09 Luc Teirlinck + + * tips.texi (Library Headers): Fix typo. + +2003-10-07 Juri Linkov + + * modes.texi (Imenu): Mention imenu-create-index-function's + default value. Explain submenus better. + +2003-10-07 Lute Kamstra + + * modes.texi (Faces for Font Lock): Fix typo. + (Hooks): Explain how buffer-local hook variables can refer to + global hook variables. + Various minor clarifications. + +2003-10-06 Lute Kamstra + + * tips.texi (Coding Conventions): Mention naming conventions for + hooks. + +2003-10-05 Luc Teirlinck + + * loading.texi (Library Search): Correct default value of + load-suffixes. + (Named Features): Fix typo. + +2003-10-05 Richard M. Stallman + + * loading.texi (Named Features): In `provide', + say how to test for subfeatures. + (Unloading): In unload-feature, use new var name + unload-feature-special-hooks. + +2003-10-03 Lute Kamstra + + * modes.texi (Major Mode Conventions): Mention third way to set up + Imenu. + (Imenu): A number of small fixes. + Delete documentation of internal variable imenu--index-alist. + Document the return value format of imenu-create-index-function + functions. + +2003-09-30 Richard M. Stallman + + * processes.texi (Network): Say what stopped datagram connections do. + + * lists.texi (Association Lists): Clarify `assq-delete-all'. + + * display.texi (Overlay Properties): Clarify `evaporate' property. + +2003-09-29 Lute Kamstra + + * modes.texi (Mode Line Data): Explain when symbols in mode-line + constructs should be marked as risky. + Change cons cell into proper list. + (Mode Line Variables): Change cons cell into proper list. + +2003-09-26 Lute Kamstra + + * modes.texi (Mode Line Data): Document the :propertize construct. + (Mode Line Variables): Reorder the descriptions of the variables + to match their order in the default mode-line-format. + Describe the new variables mode-line-position and mode-line-modes. + Update the default values of mode-line-frame-identification, + minor-mode-alist, and default-mode-line-format. + (Properties in Mode): Mention the :propertize construct. + +2003-09-26 Richard M. Stallman + + * buffers.texi, commands.texi, debugging.texi, eval.texi: + * loading.texi, minibuf.texi, text.texi, variables.texi: + Avoid @strong{Note:}. + +2003-09-26 Richard M. Stallman + + * keymaps.texi (Remapping Commands): Fix typo. + +2003-09-23 Luc Teirlinck + + * processes.texi (Low-Level Network): Fix typo. + +2003-09-23 Kim F. Storm + + * processes.texi (Network, Network Servers): Fix typos. + (Low-Level Network): Add timeout value for :server keyword. + Add new option keywords to make-network-process. + Add set-network-process-options. + Explain how to test availability of network options. + +2003-09-19 Richard M. Stallman + + * text.texi (Motion by Indent): Arg to + backward-to-indentation and forward-to-indentation is optional. + + * strings.texi (Creating Strings): Add substring-no-properties. + + * processes.texi + (Process Information): Add list-processes arg QUERY-ONLY. + Delete process-contact from here. + Add new status values for process-status. + Add process-get, process-put, process-plist, set-process-plist. + (Synchronous Processes): Add call-process-shell-command. + (Signals to Processes): signal-process allows process objects. + (Network): Complete rewrite. + (Network Servers, Datagrams, Low-Level Network): New nodes. + + * positions.texi (Word Motion): forward-word, backward-word + arg is optional. Reword. + + * abbrevs.texi (Defining Abbrevs): Index no-self-insert. + + * variables.texi (Creating Buffer-Local): + Delete duplicate definition of buffer-local-value. + (File Local Variables): Explain about discarding text props. + +2003-09-11 Richard M. Stallman + + * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer + changes variables that record input events. + (Minibuffer Misc): Add minibuffer-selected-window. + + * lists.texi (Building Lists): Add copy-tree. + + * display.texi (Fontsets): Add char-displayable-p. + (Scroll Bars): New node. + +2003-09-08 Lute Kamstra + + * modes.texi (%-Constructs): Document new `%i' and `%I' + constructs. + +2003-09-03 Peter Runestig + + * makefile.w32-in: New file. + +2003-08-29 Richard M. Stallman + + * display.texi (Overlay Properties): Clarify how priorities + affect use of the properties. + +2003-08-19 Luc Teirlinck + + * customize.texi (Type Keywords): Correct the description of + `:help-echo' in the case where `motion-doc' is a function. + +2003-08-14 John Paul Wallington + + * modes.texi (Emulating Mode Line): Subsection, not section. + +2003-08-13 Richard M. Stallman + + * elisp.texi (Top): Update subnode lists in menu. + + * text.texi (Insertion): Add insert-buffer-substring-no-properties. + (Kill Functions): kill-region has new arg yank-handler. + (Yanking): New node. + (Yank Commands): Add yank-undo-function. + (Low-Level Kill Ring): + kill-new and kill-append have new arg yank-handler. + (Changing Properties): Add remove-list-of-text-properties. + (Atomic Changes): New node. + + * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. + + * streams.texi (Output Variables): Add eval-expression-print-length + and eval-expression-print-level. + + * os.texi (Time Conversion): For encode-time, explain limits on year. + + * objects.texi (Character Type): Define anchor "modifier bits". + + * modes.texi (Emulating Mode Line): New node. + (Search-based Fontification): Font Lock uses font-lock-face property. + (Other Font Lock Variables): Likewise. + + * keymaps.texi (Format of Keymaps): Keymaps contain char tables, + not vectors. + (Active Keymaps): Add emulation-mode-map-alists. + (Functions for Key Lookup): key-binding has new arg no-remap. + (Remapping Commands): New node. + (Scanning Keymaps): where-is-internal has new arg no-remap. + (Tool Bar): Add tool-bar-local-item-from-menu. + Clarify when to use tool-bar-add-item-from-menu. + + * commands.texi (Interactive Call): commandp has new arg. + (Command Loop Info): Add this-original-command. + +2003-08-06 John Paul Wallington + + * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. + + * display.texi (Warning Basics): Fix typo. + (Fringes): Add closing curly bracket and fix typo. + + * elisp.texi (Top): Fix typo. + +2003-08-05 Richard M. Stallman + + * elisp.texi: Update lists of subnodes. + + * windows.texi (Buffers and Windows): set-window-buffer has new arg. + + * variables.texi (Local Variables): Use lc for example variable names. + + * tips.texi (Library Headers): Explain where to put -*-. + + * strings.texi (Creating Strings): Fix xref for vconcat. + + * sequences.texi (Vector Functions): + vconcat no longer allows integer args. + + * minibuf.texi (Reading File Names): read-file-name has new + arg PREDICATE. New function read-directory-name. + + * macros.texi (Defining Macros): Give definition of `declare' + (Indenting Macros): New node. + + * frames.texi (Parameter Access): Add modify-all-frames-parameters. + (Window Frame Parameters): Make separate table of parameters + that are coupled with specific face attributes. + (Deleting Frames): delete-frame-hooks renamed to + delete-frame-functions. + + * files.texi (Magic File Names): Add file-remote-p. + Clarify file-local-copy. + + * edebug.texi (Instrumenting Macro Calls): Don't define `declare' + here; instead xref Defining Macros. + + * display.texi (Warnings): New node, and subnodes. + (Fringes): New node. + + * debugging.texi (Test Coverage): New node. + + * compile.texi (Compiler Errors): Explain with-no-warnings + and other ways to suppress warnings. + + * commands.texi (Interactive Call): Minor clarification. + + * buffers.texi (Buffer File Name): set-visited-file-name + renames the buffer too. + + * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. + +2003-07-24 Markus Rost + + * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. + +2003-07-22 Markus Rost + + * internals.texi (Garbage Collection): Fix previous change. + +2003-07-22 Richard M. Stallman + + * files.texi (Truenames): Add LIMIT arg to file-chase-links. + + * display.texi (Width): Use \s syntax in example. + (Font Selection): Add face-font-rescale-alist. + + * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. + Remove spurious indent in example. + + * lists.texi (Building Lists): Add number-sequence. + + * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. + + * functions.texi (Function Documentation): Explain how to + show calling convention explicitly in the doc string. + + * windows.texi (Selecting Windows): save-selected-window saves + selected window of each frame. + (Window Configurations): Minor change. + + * syntax.texi (Syntax Table Functions): Use \s syntax in examples. + + * streams.texi (Output Variables): Add print-continuous-numbering + and print-number-table. + + * processes.texi (Decoding Output): New node. + + * os.texi (Time Conversion): decode-time arg is optional. + + * objects.texi (Character Type): Don't use space as example for \. + Make list of char names and \-sequences correspond. + Explain that \s is not used in strings. `\ ' needs space after. + + * nonascii.texi (Converting Representations): Add string-to-multibyte. + (Translation of Characters): Add translation-table-for-input. + (Default Coding Systems): Add auto-coding-functions. + (Explicit Encoding): Add decode-coding-inserted-region. + (Locales): Add locale-info. + + * minibuf.texi (Basic Completion): Describe test-completion. + Collections can be lists of strings. + Clean up lazy-completion-table. + (Programmed Completion): Mention test-completion. + Clarify why lambda expressions are not accepted. + (Minibuffer Misc): Describe minibufferp. + +2003-07-14 Richard M. Stallman + + * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. + + * windows.texi (Selecting Windows): New arg to select-window. + (Selecting Windows): Add with-selected-window. + (Size of Window): Add window-inside-edges, etc. + + * internals.texi (Garbage Collection): Add post-gc-hook. + + * processes.texi (Subprocess Creation): Add exec-suffixes. + + * keymaps.texi (Functions for Key Lookup): Add current-active-maps. + (Scanning Keymaps): Add map-keymaps. + (Defining Menus): Add keymap-prompt. + + * numbers.texi (Integer Basics): Add most-positive-fixnum, + most-negative-fixnum. + + * compile.texi (Byte Compilation): Explain no-byte-compile + (Compiler Errors): New node. + + * os.texi (User Identification): user-uid, user-real-uid + can return float. + + * modes.texi (Major Mode Conventions): Explain about run-mode-hooks + and about derived modes. + (Minor Modes): Add minor-mode-list. + (Defining Minor Modes): Keyword args for define-minor-mode. + (Search-based Fontification): Explain managing other properties. + (Other Font Lock Variables): Add font-lock-extra-managed-props. + (Faces for Font Lock): Add font-locl-preprocessor-face. + (Hooks): Add run-mode-hooks and delay-mode-hooks. + + * variables.texi (Creating Buffer-Local): Add buffer-local-value. + (Variable Aliases): Clarify defvaralias. + + * loading.texi (Library Search): Add load-suffixes. + + * minibuf.texi (Basic Completion): Add lazy-completion-table. + (Programmed Completion): Add dynamic-completion-table. + + * files.texi (Changing Files): copy-file allows dir as NEWNAME. + (Magic File Names): Specify precedence order of handlers. + + * commands.texi (Command Overview): Emacs server runs pre-command-hook + and post-command-hook. + (Waiting): New calling convention for sit-for. + + * text.texi (Special Properties): local-map and keymap properties + apply based on their stickiness. + +2003-07-07 Richard M. Stallman + + * modes.texi (Minor Mode Conventions): Specify only some kinds + of list values as args to minor modes. + + * files.texi (File Name Expansion): Warn about iterative use + of substitute-in-file-name. + + * advice.texi (Activation of Advice): Clean up previous change. + +2003-07-06 Markus Rost + + * advice.texi (Activation of Advice): Note that ad-start-advice is + turned on by default. + +2003-06-30 Richard M. Stallman + + * text.texi (Buffer Contents): Document current-word. + (Change Hooks): Not called for *Messages*. + + * functions.texi (Defining Functions): Explain about redefining + primitives. + (Function Safety): Renamed. Minor changes. + Comment out the detailed criteria for what is safe. + +2003-06-22 Andreas Schwab + + * objects.texi (Symbol Type): Fix description of examples. + +2003-06-16 Andreas Schwab + + * hash.texi (Creating Hash): Fix description of :weakness. + +2003-06-13 Kai Gro,A_(Bjohann + + * files.texi (Changing Files): copy-file copies file modes, too. + +2003-05-28 Richard M. Stallman + + * strings.texi (Creating Strings): Clarify split-string. + +2003-05-22 Stephen J. Turnbull + + * strings.texi (Creating Strings): Update split-string specification + and examples. + +2003-05-19 Richard M. Stallman + + * elisp.texi: Correct invariant section names. + +2003-04-20 Richard M. Stallman + + * os.texi (Timers): Explain about timers and quitting. + +2003-04-19 Richard M. Stallman + + * internals.texi (Writing Emacs Primitives): Strings are + no longer special for GCPROs. Mention GCPRO5, GCPRO6. + Explain GCPRO convention for varargs function args. + +2003-04-16 Richard M. Stallman + + * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. + +2003-04-08 Richard M. Stallman + + * files.texi (Kinds of Files): Correct return value of file-symlink-p. + +2003-02-13 Kim F. Storm + + * objects.texi (Character Type): New \s escape for space. + +2003-01-31 Joe Buehler + + * os.texi (System Environment): Added cygwin system-type. + +2003-01-25 Richard M. Stallman + + * keymaps.texi: Document that a symbol can act as a keymap. + +2003-01-13 Richard M. Stallman + + * text.texi (Changing Properties): Say string indices are origin-0. + + * positions.texi (Screen Lines) : + Correct order of elts in return value. + + * keymaps.texi (Changing Key Bindings) : Mention + how to define a default binding. + +2002-12-07 Markus Rost + + * loading.texi (Unloading): Fix recent change for load-history. + + * customize.texi (Simple Types): Clarify description of custom + type 'number. Describe new custom type 'float. + +2002-12-04 Markus Rost + + * variables.texi (File Local Variables): Fix typo. + +2002-10-23 Kai Gro,A_(Bjohann + + From Michael Albinus . + + * README: Target for Info file is `make info'. + + * files.texi (File Name Components): Fixed typos in + `file-name-sans-extension'. + (Magic File Names): Complete list of operations for magic file + name handlers. + +2002-09-16 Jonathan Yavner + + * variables.texi (File Local Variables): New function + risky-local-variable-p. + +2002-09-15 Jonathan Yavner + + * functions.texi (Function safety): New node about unsafep. + +2002-08-05 Per Abrahamsen + + * customize.texi (Splicing into Lists): Fixed example. + Reported by Fabrice Bauzac + +2002-06-17 Juanma Barranquero + + * frames.texi (Display Feature Testing): Fix typo. + +2002-06-12 Andreas Schwab + + * frames.texi (Initial Parameters, Resources): Fix references to + the Emacs manual. + +2002-05-13 Kim F. Storm + + * variables.texi (Intro to Buffer-Local): Updated warning and + example relating to changing buffer inside let. + +2002-03-10 Jan Dj,Ad(Brv + + * os.texi (Session Management): New node about X Session management. + +2002-01-18 Eli Zaretskii + + * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs + to which the manual corresponds, and the copyright years. + + * Makefile.in (VERSION): Set to 2.9. + +2001-11-29 Eli Zaretskii + + * elisp.texi: Change the category in @dircategory to "Emacs", to + make it consistent with info/dir. + +2001-11-25 Miles Bader + + * text.texi (Fields): Describe new `limit' arg in + field-beginning/field-end. + +2001-11-17 Eli Zaretskii + + * permute-index: Don't depend on csh-specific features. Replace + the interpreter name with /bin/sh. + + * two-volume-cross-refs.txt: New file. + * two.el: New file. + * spellfile: New file. + +2001-11-16 Eli Zaretskii + + * permute-index: New file. + + * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and + elisp-vol2.texi, respectively, to avoid file-name clashes in DOS + 8+3 restricted namespace. + + * Makefile.in (infodir): Define relative to $(srcdir). + ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the + include directories list via -I switch to makeinfo. + (index.texi): Use cp if both hard and symbolic links fail. + +2001-11-10 Eli Zaretskii + + * Makefile.in (distclean): Add. + + The following changes make ELisp manual part of the Emacs + distribution: + + * Makefile.in: Add Copyright notice. + (prefix): Remove. + (infodir): Change value to "../info". + (VPATH): New variable. + (MAKE): Don't define. + (texmacrodir): Don't define. + (texinputdir): Append the existing value of TEXINPUTS. + ($(infodir)/elisp): Instead of just "elisp". Reformat the + command to be compatible with man/Makefile.in, and to put the + output into ../info. + (info): Add target. + (installall): Target removed. + +2001-10-31 Pavel Jan,Am(Bk + + * tips.texi (Coding Conventions): Fix typo. + +2001-10-23 Gerd Moellmann + + * Makefile.in (srcs): Add gpl.texi and doclicense.texi. + +2001-10-22 Eli Zaretskii + + * files.texi (File Name Components): Update the description of + file-name-sans-extension and file-name-extension, as they now + ignore leading dots. + +2001-10-20 Gerd Moellmann + + * (Version 21.1 released.) + +2001-10-19 Miles Bader + + * positions.texi (Text Lines): Describe behavior of + `beginning-of-line'/`end-of-line' in the presence of field properties. + +2001-10-17 Gerd Moellmann + + * Makefile.in (VERSION): Set to 2.8. + (manual): Use `manual-21'. + + * elisp.texi (VERSION): Add and use it where the version + number was used. Set it to 2.8. + + * intro.texi: Likewise. + +2001-10-13 Eli Zaretskii + + * files.texi (File Name Completion): Document the significance of + a trailing slash in elements of completion-ignored-extensions. + +2001-10-06 Miles Bader + + * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. + +2001-10-04 Gerd Moellmann + + * variables.texi (Variable Aliases): New node. + +2001-10-04 Gerd Moellmann + + * Branch for 21.1. + +2001-10-02 Miles Bader + + * minibuf.texi (Minibuffer Misc): Add entries for + `minibuffer-contents', `minibuffer-contents-no-properties', and + `delete-minibuffer-contents'. + Correct description for `minibuffer-prompt-end'. + + * text.texi (Property Search): Correct descriptions of + `next-char-property-change' and `previous-char-property-change'. + Add entries for `next-single-char-property-change' and + `previous-single-char-property-change'. + Make operand names a bit more consistent. + +2001-09-30 Eli Zaretskii + + * frames.texi (Finding All Frames): Document that next-frame and + previous-frame are local to current terminal. + +2001-09-26 Eli Zaretskii + + * keymaps.texi (Creating Keymaps): Fix the description of the + result of make-keymap. + +2001-09-23 Eli Zaretskii + + * display.texi (Font Lookup, Attribute Functions) + (Image Descriptors): Add cross-references to the definition of + selected frame. + + * buffers.texi (The Buffer List): Add cross-references to the + definition of selected frame. + + * frames.texi (Input Focus): Clarify which frame is _the_ selected + frame at any given time. + (Multiple Displays, Size and Position): Add a cross-reference to + the definition of the selected frame. + +2001-09-08 Eli Zaretskii + + * strings.texi (String Conversion) : Document + that a float is returned for integers that are too large. + + * frames.texi (Mouse Position): Document mouse-position-function. + (Display Feature Testing): Document display-images-p. + (Window Frame Parameters): Document the cursor-type variable. + + * numbers.texi (Integer Basics): Document CL style read syntax for + integers in bases other than 10. + + * positions.texi (List Motion): Document + open-paren-in-column-0-is-defun-start. + + * lists.texi (Sets And Lists): Document member-ignore-case. + + * internals.texi (Garbage Collection): Document the used and free + strings report. + (Memory Usage): Document strings-consed. + + * os.texi (Time of Day): Document float-time. + (Recording Input): Document that clear-this-command-keys clears + the vector to be returned by recent-keys. + + * keymaps.texi (Scanning Keymaps) : The + argument keymap can be a list. + + * nonascii.texi (User-Chosen Coding Systems) + : Document the new argument + accept-default-p and the variable + select-safe-coding-system-accept-default-p. Tell what happens if + buffer-file-coding-system is undecided. + (Default Coding Systems): Document auto-coding-regexp-alist. + + * display.texi (The Echo Area) : Document + message-truncate-lines. + (Glyphs): Document that the glyph table is unused on windowed + displays. + + * help.texi (Describing Characters) : + Document the new argument no-angles. + (Accessing Documentation) : Document that + a non-string property is evaluated. + : Document that the function-documentation property + is looked for. + + * windows.texi (Selecting Windows): Document some-window. + + * text.texi (MD5 Checksum): New node, documents the md5 primitive. + + * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and + apropos-mode-hook. + + * commands.texi (Using Interactive): Document interactive-form. + (Keyboard Macros): Document kbd-macro-termination-hook. + (Command Loop Info): Document that clear-this-command-keys clears + the vector to be returned by recent-keys. + +2001-09-04 Werner LEMBERG + + * Makefile.in (srcdir, texinputdir): New variables. + (srcs, index.texi, install): Use $(srcdir). + (.PHONY): Remove elisp.dvi. + (elisp): Use -I switch for makeinfo. + (elisp.dvi): Use $(srcdir) and $(texinputdir). + (installall, dist): Use $(srcdir). + Fix path to texinfo.tex. + (maintainer-clean): Add elisp.dvi and elisp.oaux. + +2001-08-30 Gerd Moellmann + + * display.texi (Conditional Display): Adjust to API change. + + * configure: New file. + +2001-07-30 Gerd Moellmann + + * commands.texi (Repeat Events): Add description of + double-click-fuzz. + +2001-05-08 Stefan Monnier + + * syntax.texi (Syntax Class Table): Add the missing designator for + comment and string fences. + (Syntax Properties): Add a xref to syntax table internals. + (Syntax Table Internals): Document string-to-syntax. + +2001-05-07 Gerd Moellmann + + * Makefile.in (install): Use install-info command line options + like in Emacs' Makefile.in. + +2000-12-09 Miles Bader + + * windows.texi (Window Start): Update documentation for + `pos-visible-in-window-p'. + +2000-11-12 Stefan Monnier + + * lists.texi (Building Lists): Add footnote to explain how to add + to the end of a list. + +2000-10-25 Gerd Moellmann + + * files.texi (Visiting Functions): Typos. + +2000-10-25 Kenichi Handa + + * files.texi (Visiting Functions): Return value of + find-file-noselect may be a list of buffers if wildcards are used. + +2000-10-24 Miles Bader + + * display.texi (Defining Faces): Document `graphic' display type + in face specs. + +2000-10-18 Kai Grossjohann + + * hooks.texi (Standard Hooks): Replace obsolete + `after-make-frame-hook' with `after-make-frame-functions'. + + * frames.texi (Creating Frames): Ditto. + + * variables.texi (Future Local Variables): Ditto. + +2000-10-16 Gerd Moellmann + + * display.texi (Other Image Types): Add description of :foreground + and :background properties of mono PBM images. + +2000-08-17 Werner LEMBERG + + * .cvsignore: New file. + +2000-01-05 Gerd Moellmann + + * tindex.pl: New script. + +1999-12-03 Dave Love + + * Makefile.in (MAKEINFO): New parameter. + +1999-09-17 Richard Stallman + + * Makefile.in (srcs): Add hash.texi. + (VERSION): Update to 20.6. + +1999-09-13 Richard Stallman + + * Makefile.in (index.texi): If cannot make a symlink, make a hard link. + +1998-08-29 Karl Heuer + + * configure.in: New file. + * Makefile.in: Renamed from Makefile. + (prefix, infodir): Use value obtained from configure. + (emacslibdir): Obsolete variable deleted. + (dist): Distribute configure.in, configure, Makefile.in. + +1998-06-12 Richard Stallman + + * Makefile (INSTALL_INFO): New variable. + (install): Run install-info. + +1998-05-09 Richard Stallman + + * Makefile (elisp.dvi): Add missing backslash. + +1998-05-02 Richard Stallman + + * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. + Run texindex without `./'. Always run texindex on elisp.tp. + (elisp.tps): Target deleted. + +1998-04-05 Richard Stallman + + * Makefile (srcs): Add nonascii.texi and customize.texi. + (dist): Start by deleting `temp'. + +1998-02-17 Richard Stallman + + * Makefile (makeinfo, texindex): Targets deleted. + (makeinfo.o, texindex.o): Targets deleted. + (clean, dist): Don't do anything with them or with getopt*. + +1998-01-30 Richard Stallman + + * Makefile (SHELL): Defined. + +1998-01-27 Richard Stallman + + * Makefile (elisp.tps): New target. + (elisp.dvi): Depend on elisp.tps. + +Wed Apr 3 15:24:25 1996 Karl Heuer + + * README: Update phone number. + + * Makefile (elisp): Make this be the default target. + Depend on makeinfo.c instead of makeinfo. + (install): Don't depend on elisp.dvi, since we don't install that. + Use mkinstalldirs. + (dist): Add mkinstalldirs. + +Mon Jun 19 14:35:26 1995 Richard Stallman + + * Makefile (VERSION): Update version number. + (maintainer-clean): Renamed from realclean. + +Wed Jun 7 17:04:59 1995 Karl Heuer + + * Makefile (realclean): New target. + (elisp): Remove any old elisp-* files first. + +Tue Nov 23 19:59:40 1993 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) + + * Makefile (VERSION): New variable. + (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. + Compressed file suffix should be `.gz', not `.z'. + +Mon Nov 22 15:06:19 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (elisp): Depend on makeinfo. + +Fri Nov 19 02:29:33 1993 Noah Friedman (friedman@gnu.ai.mit.edu) + + * Makefile (srcs): Add anti.texi. + +Fri May 28 18:04:53 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (infodir, prefix): New vars. + (install): Use infodir. + (emacsinfodir): Deleted. + +Thu May 27 02:11:25 1993 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (srcs): Add calendar.texi. + + * Makefile (dist): Copy texindex.c and makeinfo.c. + Limit elisp-* files to those with one or two digits. + +Sun May 16 17:58:21 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile (dist): Changed to use Gzip instead of compress. + +Fri Apr 23 01:05:23 1993 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * loading.texi (Unloading): define-function changed back to + defalias. It may not stay this way, but at least it's + consistent with the known-good version of the code patch. + +Fri Mar 26 21:14:54 1993 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) + + * modes.texi (Hooks): Document new optional arg of add-hook. + +Wed Mar 17 08:48:24 1993 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * variables.texi: Document nil initial value of buffer-local variables. + + * tips.texi: Add new section on standard library headers. + +Sat Feb 27 18:00:25 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile (srcs): Add frame.texi to the list of sources. + +Tue Feb 23 10:50:25 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile (dist): Don't bother excluding autosave files; they'll + never make it into the temp directory anyway, and the hash marks + in the name are problematic for make and the Bourne shell. + (srcs): + +Fri Feb 12 16:54:38 1993 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile (dist): Don't include backup files or autosave files in + the distribution tar file. + +Tue Nov 26 21:10:34 1991 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (srcs): Added index.perm. + (elisp.dvi): Remove erroneous shell comment. + Expect output of permute-index in permuted.fns. + Save old elisp.aux in elisp.oaux. + (clean): Added index.texi to be deleted. + +Sat Aug 11 17:39:10 1990 Richard Stallman (rms@sugar-bombs.ai.mit.edu) + + * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. + +Tue Jun 26 09:57:26 1990 David Lawrence (tale@geech) + + * files.texi: Noted that completion-ignored-extensions is ignored + when making *Completions*. + +Fri Jun 8 16:44:44 EDT 1990 Jay Fenlason (hack@ai.mit.edu) + + * Makefile make dist now depends on elisp.dvi, since it tries + to include it in the dist file. + +Wed Mar 28 22:57:35 1990 Jim Kingdon (kingdon@mole.ai.mit.edu) + + * functions.texinfo (Mapping Functions): Add missing quote + +Mon Jun 19 18:09:24 1989 Richard Stallman (rms@sugar-bombs.ai.mit.edu) + + * texinfo.tex (frenchspacing): Use decimal codes for char to be set. + (defunargs): Turn off \hyphenchar of \sl font temporarily. + +Wed May 10 18:01:17 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) + + * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, + and @error{} are the terms now being used. The files in the + directory have been changed to reflect this. + + * All instances of @indentedresultt{} have been changed to + ` @result{}', using 5 spaces at the begining of the line. + +Mon Apr 24 21:02:55 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) + + * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the + experimental @indentedresult{}, @indentedexpandsto{} are part of + the texinfo.tex in this directory. These TeX macros are not + stable yet. + +Mon Apr 17 18:56:50 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) + + * texinfo.tex: Temporarily added + \let\result=\dblarrow + \def\error{{\it ERROR} \longdblarrow} + We need to do this better soon. + +Tue Apr 11 12:23:28 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) + + * Applied Karl Berry's patches to *.texinfo files, but not to + texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's + new title page format is also not applied, since it requires + texinfo.tex changes.) + + * Cleaned up `Makefile' and defined the `emacslibdir' directory + for the Project GNU development environment. + +;; Local Variables: +;; coding: iso-2022-7bit +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, + 2005, 2006, 2007 Free Software Foundation, Inc. + + This file is part of GNU Emacs. + + GNU Emacs is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3, or (at your option) + any later version. + + GNU Emacs is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNU Emacs; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda diff --cc doc/lispref/commands.texi index aaad7ca82a7,00000000000..cdd627f6b52 mode 100644,000000..100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@@ -1,3298 -1,0 +1,3316 @@@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/commands +@node Command Loop, Keymaps, Minibuffers, Top +@chapter Command Loop +@cindex editor command loop +@cindex command loop + + When you run Emacs, it enters the @dfn{editor command loop} almost +immediately. This loop reads key sequences, executes their definitions, +and displays the results. In this chapter, we describe how these things +are done, and the subroutines that allow Lisp programs to do them. + +@menu +* Command Overview:: How the command loop reads commands. +* Defining Commands:: Specifying how a function should read arguments. +* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. +* Command Loop Info:: Variables set by the command loop for you to examine. +* Adjusting Point:: Adjustment of point after a command. +* Input Events:: What input looks like when you read it. +* Reading Input:: How to read input events from the keyboard or mouse. +* Special Events:: Events processed immediately and individually. +* Waiting:: Waiting for user input or elapsed time. +* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. +* Prefix Command Arguments:: How the commands to set prefix args work. +* Recursive Editing:: Entering a recursive edit, + and why you usually shouldn't. +* Disabling Commands:: How the command loop handles disabled commands. +* Command History:: How the command history is set up, and how accessed. +* Keyboard Macros:: How keyboard macros are implemented. +@end menu + +@node Command Overview +@section Command Loop Overview + + The first thing the command loop must do is read a key sequence, which +is a sequence of events that translates into a command. It does this by +calling the function @code{read-key-sequence}. Your Lisp code can also +call this function (@pxref{Key Sequence Input}). Lisp programs can also +do input at a lower level with @code{read-event} (@pxref{Reading One +Event}) or discard pending input with @code{discard-input} +(@pxref{Event Input Misc}). + + The key sequence is translated into a command through the currently +active keymaps. @xref{Key Lookup}, for information on how this is done. +The result should be a keyboard macro or an interactively callable +function. If the key is @kbd{M-x}, then it reads the name of another +command, which it then calls. This is done by the command +@code{execute-extended-command} (@pxref{Interactive Call}). + + To execute a command requires first reading the arguments for it. +This is done by calling @code{command-execute} (@pxref{Interactive +Call}). For commands written in Lisp, the @code{interactive} +specification says how to read the arguments. This may use the prefix +argument (@pxref{Prefix Command Arguments}) or may read with prompting +in the minibuffer (@pxref{Minibuffers}). For example, the command +@code{find-file} has an @code{interactive} specification which says to +read a file name using the minibuffer. The command's function body does +not use the minibuffer; if you call this command from Lisp code as a +function, you must supply the file name string as an ordinary Lisp +function argument. + + If the command is a string or vector (i.e., a keyboard macro) then +@code{execute-kbd-macro} is used to execute it. You can call this +function yourself (@pxref{Keyboard Macros}). + + To terminate the execution of a running command, type @kbd{C-g}. This +character causes @dfn{quitting} (@pxref{Quitting}). + +@defvar pre-command-hook +The editor command loop runs this normal hook before each command. At +that time, @code{this-command} contains the command that is about to +run, and @code{last-command} describes the previous command. +@xref{Command Loop Info}. +@end defvar + +@defvar post-command-hook +The editor command loop runs this normal hook after each command +(including commands terminated prematurely by quitting or by errors), +and also when the command loop is first entered. At that time, +@code{this-command} refers to the command that just ran, and +@code{last-command} refers to the command before that. +@end defvar + + Quitting is suppressed while running @code{pre-command-hook} and +@code{post-command-hook}. If an error happens while executing one of +these hooks, it terminates execution of the hook, and clears the hook +variable to @code{nil} so as to prevent an infinite loop of errors. + + A request coming into the Emacs server (@pxref{Emacs Server,,, +emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard +command does. + +@node Defining Commands +@section Defining Commands +@cindex defining commands +@cindex commands, defining +@cindex functions, making them interactive +@cindex interactive function + + A Lisp function becomes a command when its body contains, at top +level, a form that calls the special form @code{interactive}. This +form does nothing when actually executed, but its presence serves as a +flag to indicate that interactive calling is permitted. Its argument +controls the reading of arguments for an interactive call. + +@menu +* Using Interactive:: General rules for @code{interactive}. +* Interactive Codes:: The standard letter-codes for reading arguments + in various ways. +* Interactive Examples:: Examples of how to read interactive arguments. +@end menu + +@node Using Interactive +@subsection Using @code{interactive} +@cindex arguments, interactive entry + + This section describes how to write the @code{interactive} form that +makes a Lisp function an interactively-callable command, and how to +examine a command's @code{interactive} form. + +@defspec interactive arg-descriptor +This special form declares that the function in which it appears is a +command, and that it may therefore be called interactively (via +@kbd{M-x} or by entering a key sequence bound to it). The argument +@var{arg-descriptor} declares how to compute the arguments to the +command when the command is called interactively. + +A command may be called from Lisp programs like any other function, but +then the caller supplies the arguments and @var{arg-descriptor} has no +effect. + +The @code{interactive} form has its effect because the command loop +(actually, its subroutine @code{call-interactively}) scans through the +function definition looking for it, before calling the function. Once +the function is called, all its body forms including the +@code{interactive} form are executed, but at this time +@code{interactive} simply returns @code{nil} without even evaluating its +argument. +@end defspec + +There are three possibilities for the argument @var{arg-descriptor}: + +@itemize @bullet +@item +It may be omitted or @code{nil}; then the command is called with no +arguments. This leads quickly to an error if the command requires one +or more arguments. + +@item +It may be a string; then its contents should consist of a code character +followed by a prompt (which some code characters use and some ignore). +The prompt ends either with the end of the string or with a newline. +Here is a simple example: + +@smallexample +(interactive "bFrobnicate buffer: ") +@end smallexample + +@noindent +The code letter @samp{b} says to read the name of an existing buffer, +with completion. The buffer name is the sole argument passed to the +command. The rest of the string is a prompt. + +If there is a newline character in the string, it terminates the prompt. +If the string does not end there, then the rest of the string should +contain another code character and prompt, specifying another argument. +You can specify any number of arguments in this way. + +@c Emacs 19 feature +The prompt string can use @samp{%} to include previous argument values +(starting with the first argument) in the prompt. This is done using +@code{format} (@pxref{Formatting Strings}). For example, here is how +you could read the name of an existing buffer followed by a new name to +give to that buffer: + +@smallexample +@group +(interactive "bBuffer to rename: \nsRename buffer %s to: ") +@end group +@end smallexample + +@cindex @samp{*} in @code{interactive} +@cindex read-only buffers in interactive +If the first character in the string is @samp{*}, then an error is +signaled if the buffer is read-only. + +@cindex @samp{@@} in @code{interactive} +@c Emacs 19 feature +If the first character in the string is @samp{@@}, and if the key +sequence used to invoke the command includes any mouse events, then +the window associated with the first of those events is selected +before the command is run. + +You can use @samp{*} and @samp{@@} together; the order does not matter. +Actual reading of arguments is controlled by the rest of the prompt +string (starting with the first character that is not @samp{*} or +@samp{@@}). + +@item +It may be a Lisp expression that is not a string; then it should be a +form that is evaluated to get a list of arguments to pass to the +command. Usually this form will call various functions to read input +from the user, most often through the minibuffer (@pxref{Minibuffers}) +or directly from the keyboard (@pxref{Reading Input}). + +Providing point or the mark as an argument value is also common, but +if you do this @emph{and} read input (whether using the minibuffer or +not), be sure to get the integer values of point or the mark after +reading. The current buffer may be receiving subprocess output; if +subprocess output arrives while the command is waiting for input, it +could relocate point and the mark. + +Here's an example of what @emph{not} to do: + +@smallexample +(interactive + (list (region-beginning) (region-end) + (read-string "Foo: " nil 'my-history))) +@end smallexample + +@noindent +Here's how to avoid the problem, by examining point and the mark after +reading the keyboard input: + +@smallexample +(interactive + (let ((string (read-string "Foo: " nil 'my-history))) + (list (region-beginning) (region-end) string))) +@end smallexample + +@strong{Warning:} the argument values should not include any data +types that can't be printed and then read. Some facilities save +@code{command-history} in a file to be read in the subsequent +sessions; if a command's arguments contain a data type that prints +using @samp{#<@dots{}>} syntax, those facilities won't work. + +There are, however, a few exceptions: it is ok to use a limited set of +expressions such as @code{(point)}, @code{(mark)}, +@code{(region-beginning)}, and @code{(region-end)}, because Emacs +recognizes them specially and puts the expression (rather than its +value) into the command history. To see whether the expression you +wrote is one of these exceptions, run the command, then examine +@code{(car command-history)}. +@end itemize + +@cindex examining the @code{interactive} form +@defun interactive-form function +This function returns the @code{interactive} form of @var{function}. +If @var{function} is an interactively callable function +(@pxref{Interactive Call}), the value is the command's +@code{interactive} form @code{(interactive @var{spec})}, which +specifies how to compute its arguments. Otherwise, the value is +@code{nil}. If @var{function} is a symbol, its function definition is +used. +@end defun + +@node Interactive Codes +@comment node-name, next, previous, up +@subsection Code Characters for @code{interactive} +@cindex interactive code description +@cindex description for interactive codes +@cindex codes, interactive, description of +@cindex characters for interactive codes + + The code character descriptions below contain a number of key words, +defined here as follows: + +@table @b +@item Completion +@cindex interactive completion +Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name +completion because the argument is read using @code{completing-read} +(@pxref{Completion}). @kbd{?} displays a list of possible completions. + +@item Existing +Require the name of an existing object. An invalid name is not +accepted; the commands to exit the minibuffer do not exit if the current +input is not valid. + +@item Default +@cindex default argument string +A default value of some sort is used if the user enters no text in the +minibuffer. The default depends on the code character. + +@item No I/O +This code letter computes an argument without reading any input. +Therefore, it does not use a prompt string, and any prompt string you +supply is ignored. + +Even though the code letter doesn't use a prompt string, you must follow +it with a newline if it is not the last code character in the string. + +@item Prompt +A prompt immediately follows the code character. The prompt ends either +with the end of the string or with a newline. + +@item Special +This code character is meaningful only at the beginning of the +interactive string, and it does not look for a prompt or a newline. +It is a single, isolated character. +@end table + +@cindex reading interactive arguments + Here are the code character descriptions for use with @code{interactive}: + +@table @samp +@item * +Signal an error if the current buffer is read-only. Special. + +@item @@ +Select the window mentioned in the first mouse event in the key +sequence that invoked this command. Special. + +@item a +A function name (i.e., a symbol satisfying @code{fboundp}). Existing, +Completion, Prompt. + +@item b +The name of an existing buffer. By default, uses the name of the +current buffer (@pxref{Buffers}). Existing, Completion, Default, +Prompt. + +@item B +A buffer name. The buffer need not exist. By default, uses the name of +a recently used buffer other than the current buffer. Completion, +Default, Prompt. + +@item c +A character. The cursor does not move into the echo area. Prompt. + +@item C +A command name (i.e., a symbol satisfying @code{commandp}). Existing, +Completion, Prompt. + +@item d +@cindex position argument +The position of point, as an integer (@pxref{Point}). No I/O. + +@item D +A directory name. The default is the current default directory of the +current buffer, @code{default-directory} (@pxref{File Name Expansion}). +Existing, Completion, Default, Prompt. + +@item e +The first or next mouse event in the key sequence that invoked the command. +More precisely, @samp{e} gets events that are lists, so you can look at +the data in the lists. @xref{Input Events}. No I/O. + +You can use @samp{e} more than once in a single command's interactive +specification. If the key sequence that invoked the command has +@var{n} events that are lists, the @var{n}th @samp{e} provides the +@var{n}th such event. Events that are not lists, such as function keys +and @acronym{ASCII} characters, do not count where @samp{e} is concerned. + +@item f +A file name of an existing file (@pxref{File Names}). The default +directory is @code{default-directory}. Existing, Completion, Default, +Prompt. + +@item F +A file name. The file need not exist. Completion, Default, Prompt. + +@item G +A file name. The file need not exist. If the user enters just a +directory name, then the value is just that directory name, with no +file name within the directory added. Completion, Default, Prompt. + +@item i +An irrelevant argument. This code always supplies @code{nil} as +the argument's value. No I/O. + +@item k +A key sequence (@pxref{Key Sequences}). This keeps reading events +until a command (or undefined command) is found in the current key +maps. The key sequence argument is represented as a string or vector. +The cursor does not move into the echo area. Prompt. + +If @samp{k} reads a key sequence that ends with a down-event, it also +reads and discards the following up-event. You can get access to that +up-event with the @samp{U} code character. + +This kind of input is used by commands such as @code{describe-key} and +@code{global-set-key}. + +@item K +A key sequence, whose definition you intend to change. This works like +@samp{k}, except that it suppresses, for the last input event in the key +sequence, the conversions that are normally used (when necessary) to +convert an undefined key into a defined one. + +@item m +@cindex marker argument +The position of the mark, as an integer. No I/O. + +@item M +Arbitrary text, read in the minibuffer using the current buffer's input +method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU +Emacs Manual}). Prompt. + +@item n +A number, read with the minibuffer. If the input is not a number, the +user has to try again. @samp{n} never uses the prefix argument. +Prompt. + +@item N +The numeric prefix argument; but if there is no prefix argument, read +a number as with @kbd{n}. The value is always a number. @xref{Prefix +Command Arguments}. Prompt. + +@item p +@cindex numeric prefix argument usage +The numeric prefix argument. (Note that this @samp{p} is lower case.) +No I/O. + +@item P +@cindex raw prefix argument usage +The raw prefix argument. (Note that this @samp{P} is upper case.) No +I/O. + +@item r +@cindex region argument +Point and the mark, as two numeric arguments, smallest first. This is +the only code letter that specifies two successive arguments rather than +one. No I/O. + +@item s +Arbitrary text, read in the minibuffer and returned as a string +(@pxref{Text from Minibuffer}). Terminate the input with either +@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of +these characters in the input.) Prompt. + +@item S +An interned symbol whose name is read in the minibuffer. Any whitespace +character terminates the input. (Use @kbd{C-q} to include whitespace in +the string.) Other characters that normally terminate a symbol (e.g., +parentheses and brackets) do not do so here. Prompt. + +@item U +A key sequence or @code{nil}. Can be used after a @samp{k} or +@samp{K} argument to get the up-event that was discarded (if any) +after @samp{k} or @samp{K} read a down-event. If no up-event has been +discarded, @samp{U} provides @code{nil} as the argument. No I/O. + +@item v +A variable declared to be a user option (i.e., satisfying the +predicate @code{user-variable-p}). This reads the variable using +@code{read-variable}. @xref{Definition of read-variable}. Existing, +Completion, Prompt. + +@item x +A Lisp object, specified with its read syntax, terminated with a +@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from +Minibuffer}. Prompt. + +@item X +@cindex evaluated expression argument +A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates +the form so that its value becomes the argument for the command. +Prompt. + +@item z +A coding system name (a symbol). If the user enters null input, the +argument value is @code{nil}. @xref{Coding Systems}. Completion, +Existing, Prompt. + +@item Z +A coding system name (a symbol)---but only if this command has a prefix +argument. With no prefix argument, @samp{Z} provides @code{nil} as the +argument value. Completion, Existing, Prompt. +@end table + +@node Interactive Examples +@comment node-name, next, previous, up +@subsection Examples of Using @code{interactive} +@cindex examples of using @code{interactive} +@cindex @code{interactive}, examples of using + + Here are some examples of @code{interactive}: + +@example +@group +(defun foo1 () ; @r{@code{foo1} takes no arguments,} + (interactive) ; @r{just moves forward two words.} + (forward-word 2)) + @result{} foo1 +@end group + +@group +(defun foo2 (n) ; @r{@code{foo2} takes one argument,} + (interactive "p") ; @r{which is the numeric prefix.} + (forward-word (* 2 n))) + @result{} foo2 +@end group + +@group +(defun foo3 (n) ; @r{@code{foo3} takes one argument,} + (interactive "nCount:") ; @r{which is read with the Minibuffer.} + (forward-word (* 2 n))) + @result{} foo3 +@end group + +@group +(defun three-b (b1 b2 b3) + "Select three existing buffers. +Put them into three windows, selecting the last one." +@end group + (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") + (delete-other-windows) + (split-window (selected-window) 8) + (switch-to-buffer b1) + (other-window 1) + (split-window (selected-window) 8) + (switch-to-buffer b2) + (other-window 1) + (switch-to-buffer b3)) + @result{} three-b +@group +(three-b "*scratch*" "declarations.texi" "*mail*") + @result{} nil +@end group +@end example + +@node Interactive Call +@section Interactive Call +@cindex interactive call + + After the command loop has translated a key sequence into a command it +invokes that command using the function @code{command-execute}. If the +command is a function, @code{command-execute} calls +@code{call-interactively}, which reads the arguments and calls the +command. You can also call these functions yourself. + +@defun commandp object &optional for-call-interactively +Returns @code{t} if @var{object} is suitable for calling interactively; +that is, if @var{object} is a command. Otherwise, returns @code{nil}. + +The interactively callable objects include strings and vectors (treated +as keyboard macros), lambda expressions that contain a top-level call to +@code{interactive}, byte-code function objects made from such lambda +expressions, autoload objects that are declared as interactive +(non-@code{nil} fourth argument to @code{autoload}), and some of the +primitive functions. + +A symbol satisfies @code{commandp} if its function definition +satisfies @code{commandp}. Keys and keymaps are not commands. +Rather, they are used to look up commands (@pxref{Keymaps}). + +If @var{for-call-interactively} is non-@code{nil}, then +@code{commandp} returns @code{t} only for objects that +@code{call-interactively} could call---thus, not for keyboard macros. + +See @code{documentation} in @ref{Accessing Documentation}, for a +realistic example of using @code{commandp}. +@end defun + +@defun call-interactively command &optional record-flag keys +This function calls the interactively callable function @var{command}, +reading arguments according to its interactive calling specifications. +It returns whatever @var{command} returns. An error is signaled if +@var{command} is not a function or if it cannot be called +interactively (i.e., is not a command). Note that keyboard macros +(strings and vectors) are not accepted, even though they are +considered commands, because they are not functions. If @var{command} +is a symbol, then @code{call-interactively} uses its function definition. + +@cindex record command history +If @var{record-flag} is non-@code{nil}, then this command and its +arguments are unconditionally added to the list @code{command-history}. +Otherwise, the command is added only if it uses the minibuffer to read +an argument. @xref{Command History}. + +The argument @var{keys}, if given, should be a vector which specifies +the sequence of events to supply if the command inquires which events +were used to invoke it. If @var{keys} is omitted or @code{nil}, the +default is the return value of @code{this-command-keys-vector}. +@xref{Definition of this-command-keys-vector}. +@end defun + +@defun command-execute command &optional record-flag keys special +@cindex keyboard macro execution +This function executes @var{command}. The argument @var{command} must +satisfy the @code{commandp} predicate; i.e., it must be an interactively +callable function or a keyboard macro. + +A string or vector as @var{command} is executed with +@code{execute-kbd-macro}. A function is passed to +@code{call-interactively}, along with the optional @var{record-flag} +and @var{keys}. + +A symbol is handled by using its function definition in its place. A +symbol with an @code{autoload} definition counts as a command if it was +declared to stand for an interactively callable function. Such a +definition is handled by loading the specified library and then +rechecking the definition of the symbol. + +The argument @var{special}, if given, means to ignore the prefix +argument and not clear it. This is used for executing special events +(@pxref{Special Events}). +@end defun + +@deffn Command execute-extended-command prefix-argument +@cindex read command name +This function reads a command name from the minibuffer using +@code{completing-read} (@pxref{Completion}). Then it uses +@code{command-execute} to call the specified command. Whatever that +command returns becomes the value of @code{execute-extended-command}. + +@cindex execute with prefix argument +If the command asks for a prefix argument, it receives the value +@var{prefix-argument}. If @code{execute-extended-command} is called +interactively, the current raw prefix argument is used for +@var{prefix-argument}, and thus passed on to whatever command is run. + +@c !!! Should this be @kindex? +@cindex @kbd{M-x} +@code{execute-extended-command} is the normal definition of @kbd{M-x}, +so it uses the string @w{@samp{M-x }} as a prompt. (It would be better +to take the prompt from the events used to invoke +@code{execute-extended-command}, but that is painful to implement.) A +description of the value of the prefix argument, if any, also becomes +part of the prompt. + +@example +@group +(execute-extended-command 3) +---------- Buffer: Minibuffer ---------- +3 M-x forward-word RET +---------- Buffer: Minibuffer ---------- + @result{} t +@end group +@end example +@end deffn + - @defun interactive-p - This function returns @code{t} if the containing function (the one - whose code includes the call to @code{interactive-p}) was called in - direct response to user input. This means that it was called with the - function @code{call-interactively}, and that a keyboard macro is - not running, and that Emacs is not running in batch mode. ++@node Distinguish Interactive ++@section Distinguish Interactive Calls ++ ++ Sometimes a command should display additional visual feedback (such ++as an informative message in the echo area) for interactive calls ++only. There are three ways to do this. The recommended way to test ++whether the function was called using @code{call-interactively} is to ++give it an optional argument @code{print-message} and use the ++@code{interactive} spec to make it non-@code{nil} in interactive ++calls. Here's an example: ++ ++@example ++(defun foo (&optional print-message) ++ (interactive "p") ++ (when print-message ++ (message "foo"))) ++@end example ++ ++@noindent ++We use @code{"p"} because the numeric prefix argument is never ++@code{nil}. Defined in this way, the function does display the ++message when called from a keyboard macro. ++ ++ The above method with the additional argument is usually best, ++because it allows callers to say ``treat this call as interactive.'' ++But you can also do the job in a simpler way by testing ++@code{called-interactively-p}. ++ ++@defun called-interactively-p ++This function returns @code{t} when the calling function was called ++using @code{call-interactively}. + +If the containing function was called by Lisp evaluation (or with +@code{apply} or @code{funcall}), then it was not called interactively. +@end defun + - The most common use of @code{interactive-p} is for deciding whether - to give the user additional visual feedback (such as by printing an - informative message). For example: ++ Here's an example of using @code{called-interactively-p}: + +@example +@group - ;; @r{Here's the usual way to use @code{interactive-p}.} +(defun foo () + (interactive) - (when (interactive-p) - (message "foo"))) ++ (when (called-interactively-p) ++ (message "foo")) ++ 'haha) + @result{} foo +@end group + +@group - ;; @r{This function is just to illustrate the behavior.} - (defun bar () - (interactive) - (setq foobar (list (foo) (interactive-p)))) - @result{} bar ++;; @r{Type @kbd{M-x foo}.} ++ @print{} foo +@end group + +@group - ;; @r{Type @kbd{M-x foo}.} - @print{} foo ++(foo) ++ @result{} haha ++@end group ++@end example ++ ++ Here is another example that contrasts direct and indirect ++calls to @code{called-interactively-p}. ++ ++@example ++@group ++(defun bar () ++ (interactive) ++ (setq foobar (list (foo) (called-interactively-p)))) ++ @result{} bar +@end group + +@group +;; @r{Type @kbd{M-x bar}.} +;; @r{This does not display a message.} +@end group + +@group +foobar + @result{} (nil t) +@end group +@end example + - If you want to test @emph{only} whether the function was called - using @code{call-interactively}, add an optional argument - @code{print-message} which should be non-@code{nil} in an interactive - call, and use the @code{interactive} spec to make sure it is - non-@code{nil}. Here's an example: - - @example - (defun foo (&optional print-message) - (interactive "p") - (when print-message - (message "foo"))) - @end example - - @noindent - Defined in this way, the function does display the message when called - from a keyboard macro. We use @code{"p"} because the numeric prefix - argument is never @code{nil}. - - @defun called-interactively-p - This function returns @code{t} when the calling function was called - using @code{call-interactively}. ++ If you want to treat commands run in keyboard macros just like calls ++from Lisp programs, test @code{interactive-p} instead of ++@code{called-interactively-p}. + - When possible, instead of using this function, you should use the - method in the example above; that method makes it possible for a - caller to ``pretend'' that the function was called interactively. ++@defun interactive-p ++This function returns @code{t} if the containing function (the one ++whose code includes the call to @code{interactive-p}) was called in ++direct response to user input. This means that it was called with the ++function @code{call-interactively}, and that a keyboard macro is ++not running, and that Emacs is not running in batch mode. +@end defun + +@node Command Loop Info +@comment node-name, next, previous, up +@section Information from the Command Loop + +The editor command loop sets several Lisp variables to keep status +records for itself and for commands that are run. With the exception of +@code{this-command} and @code{last-command} it's generally a bad idea to +change any of these variables in a Lisp program. + +@defvar last-command +This variable records the name of the previous command executed by the +command loop (the one before the current command). Normally the value +is a symbol with a function definition, but this is not guaranteed. + +The value is copied from @code{this-command} when a command returns to +the command loop, except when the command has specified a prefix +argument for the following command. + +This variable is always local to the current terminal and cannot be +buffer-local. @xref{Multiple Displays}. +@end defvar + +@defvar real-last-command +This variable is set up by Emacs just like @code{last-command}, +but never altered by Lisp programs. +@end defvar + +@defvar last-repeatable-command +This variable stores the most recently executed command that was not +part of an input event. This is the command @code{repeat} will try to +repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}. +@end defvar + +@defvar this-command +@cindex current command +This variable records the name of the command now being executed by +the editor command loop. Like @code{last-command}, it is normally a symbol +with a function definition. + +The command loop sets this variable just before running a command, and +copies its value into @code{last-command} when the command finishes +(unless the command specified a prefix argument for the following +command). + +@cindex kill command repetition +Some commands set this variable during their execution, as a flag for +whatever command runs next. In particular, the functions for killing text +set @code{this-command} to @code{kill-region} so that any kill commands +immediately following will know to append the killed text to the +previous kill. +@end defvar + +If you do not want a particular command to be recognized as the previous +command in the case where it got an error, you must code that command to +prevent this. One way is to set @code{this-command} to @code{t} at the +beginning of the command, and set @code{this-command} back to its proper +value at the end, like this: + +@example +(defun foo (args@dots{}) + (interactive @dots{}) + (let ((old-this-command this-command)) + (setq this-command t) + @r{@dots{}do the work@dots{}} + (setq this-command old-this-command))) +@end example + +@noindent +We do not bind @code{this-command} with @code{let} because that would +restore the old value in case of error---a feature of @code{let} which +in this case does precisely what we want to avoid. + +@defvar this-original-command +This has the same value as @code{this-command} except when command +remapping occurs (@pxref{Remapping Commands}). In that case, +@code{this-command} gives the command actually run (the result of +remapping), and @code{this-original-command} gives the command that +was specified to run but remapped into another command. +@end defvar + +@defun this-command-keys +This function returns a string or vector containing the key sequence +that invoked the present command, plus any previous commands that +generated the prefix argument for this command. Any events read by the +command using @code{read-event} without a timeout get tacked on to the end. + +However, if the command has called @code{read-key-sequence}, it +returns the last read key sequence. @xref{Key Sequence Input}. The +value is a string if all events in the sequence were characters that +fit in a string. @xref{Input Events}. + +@example +@group +(this-command-keys) +;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} + @result{} "^U^X^E" +@end group +@end example +@end defun + +@defun this-command-keys-vector +@anchor{Definition of this-command-keys-vector} +Like @code{this-command-keys}, except that it always returns the events +in a vector, so you don't need to deal with the complexities of storing +input events in a string (@pxref{Strings of Events}). +@end defun + +@defun clear-this-command-keys &optional keep-record +This function empties out the table of events for +@code{this-command-keys} to return. Unless @var{keep-record} is +non-@code{nil}, it also empties the records that the function +@code{recent-keys} (@pxref{Recording Input}) will subsequently return. +This is useful after reading a password, to prevent the password from +echoing inadvertently as part of the next command in certain cases. +@end defun + +@defvar last-nonmenu-event +This variable holds the last input event read as part of a key sequence, +not counting events resulting from mouse menus. + +One use of this variable is for telling @code{x-popup-menu} where to pop +up a menu. It is also used internally by @code{y-or-n-p} +(@pxref{Yes-or-No Queries}). +@end defvar + +@defvar last-command-event +@defvarx last-command-char +This variable is set to the last input event that was read by the +command loop as part of a command. The principal use of this variable +is in @code{self-insert-command}, which uses it to decide which +character to insert. + +@example +@group +last-command-event +;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} + @result{} 5 +@end group +@end example + +@noindent +The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. + +The alias @code{last-command-char} exists for compatibility with +Emacs version 18. +@end defvar + +@c Emacs 19 feature +@defvar last-event-frame +This variable records which frame the last input event was directed to. +Usually this is the frame that was selected when the event was +generated, but if that frame has redirected input focus to another +frame, the value is the frame to which the event was redirected. +@xref{Input Focus}. + +If the last event came from a keyboard macro, the value is @code{macro}. +@end defvar + +@node Adjusting Point +@section Adjusting Point After Commands +@cindex adjusting point +@cindex invisible/intangible text, and point +@cindex @code{display} property, and point display +@cindex @code{composition} property, and point display + + It is not easy to display a value of point in the middle of a +sequence of text that has the @code{display}, @code{composition} or +@code{intangible} property, or is invisible. Therefore, after a +command finishes and returns to the command loop, if point is within +such a sequence, the command loop normally moves point to the edge of +the sequence. + + A command can inhibit this feature by setting the variable +@code{disable-point-adjustment}: + +@defvar disable-point-adjustment +If this variable is non-@code{nil} when a command returns to the +command loop, then the command loop does not check for those text +properties, and does not move point out of sequences that have them. + +The command loop sets this variable to @code{nil} before each command, +so if a command sets it, the effect applies only to that command. +@end defvar + +@defvar global-disable-point-adjustment +If you set this variable to a non-@code{nil} value, the feature of +moving point out of these sequences is completely turned off. +@end defvar + +@node Input Events +@section Input Events +@cindex events +@cindex input events + +The Emacs command loop reads a sequence of @dfn{input events} that +represent keyboard or mouse activity. The events for keyboard activity +are characters or symbols; mouse events are always lists. This section +describes the representation and meaning of input events in detail. + +@defun eventp object +This function returns non-@code{nil} if @var{object} is an input event +or event type. + +Note that any symbol might be used as an event or an event type. +@code{eventp} cannot distinguish whether a symbol is intended by Lisp +code to be used as an event. Instead, it distinguishes whether the +symbol has actually been used in an event that has been read as input in +the current Emacs session. If a symbol has not yet been so used, +@code{eventp} returns @code{nil}. +@end defun + +@menu +* Keyboard Events:: Ordinary characters--keys with symbols on them. +* Function Keys:: Function keys--keys with names, not symbols. +* Mouse Events:: Overview of mouse events. +* Click Events:: Pushing and releasing a mouse button. +* Drag Events:: Moving the mouse before releasing the button. +* Button-Down Events:: A button was pushed and not yet released. +* Repeat Events:: Double and triple click (or drag, or down). +* Motion Events:: Just moving the mouse, not pushing a button. +* Focus Events:: Moving the mouse between frames. +* Misc Events:: Other events the system can generate. +* Event Examples:: Examples of the lists for mouse events. +* Classifying Events:: Finding the modifier keys in an event symbol. + Event types. +* Accessing Events:: Functions to extract info from events. +* Strings of Events:: Special considerations for putting + keyboard character events in a string. +@end menu + +@node Keyboard Events +@subsection Keyboard Events +@cindex keyboard events + +There are two kinds of input you can get from the keyboard: ordinary +keys, and function keys. Ordinary keys correspond to characters; the +events they generate are represented in Lisp as characters. The event +type of a character event is the character itself (an integer); see +@ref{Classifying Events}. + +@cindex modifier bits (of input character) +@cindex basic code (of input character) +An input character event consists of a @dfn{basic code} between 0 and +524287, plus any or all of these @dfn{modifier bits}: + +@table @asis +@item meta +The +@tex +@math{2^{27}} +@end tex +@ifnottex +2**27 +@end ifnottex +bit in the character code indicates a character +typed with the meta key held down. + +@item control +The +@tex +@math{2^{26}} +@end tex +@ifnottex +2**26 +@end ifnottex +bit in the character code indicates a non-@acronym{ASCII} +control character. + +@sc{ascii} control characters such as @kbd{C-a} have special basic +codes of their own, so Emacs needs no special bit to indicate them. +Thus, the code for @kbd{C-a} is just 1. + +But if you type a control combination not in @acronym{ASCII}, such as +@kbd{%} with the control key, the numeric value you get is the code +for @kbd{%} plus +@tex +@math{2^{26}} +@end tex +@ifnottex +2**26 +@end ifnottex +(assuming the terminal supports non-@acronym{ASCII} +control characters). + +@item shift +The +@tex +@math{2^{25}} +@end tex +@ifnottex +2**25 +@end ifnottex +bit in the character code indicates an @acronym{ASCII} control +character typed with the shift key held down. + +For letters, the basic code itself indicates upper versus lower case; +for digits and punctuation, the shift key selects an entirely different +character with a different basic code. In order to keep within the +@acronym{ASCII} character set whenever possible, Emacs avoids using the +@tex +@math{2^{25}} +@end tex +@ifnottex +2**25 +@end ifnottex +bit for those characters. + +However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from +@kbd{C-a}, so Emacs uses the +@tex +@math{2^{25}} +@end tex +@ifnottex +2**25 +@end ifnottex +bit in @kbd{C-A} and not in +@kbd{C-a}. + +@item hyper +The +@tex +@math{2^{24}} +@end tex +@ifnottex +2**24 +@end ifnottex +bit in the character code indicates a character +typed with the hyper key held down. + +@item super +The +@tex +@math{2^{23}} +@end tex +@ifnottex +2**23 +@end ifnottex +bit in the character code indicates a character +typed with the super key held down. + +@item alt +The +@tex +@math{2^{22}} +@end tex +@ifnottex +2**22 +@end ifnottex +bit in the character code indicates a character typed with +the alt key held down. (On some terminals, the key labeled @key{ALT} +is actually the meta key.) +@end table + + It is best to avoid mentioning specific bit numbers in your program. +To test the modifier bits of a character, use the function +@code{event-modifiers} (@pxref{Classifying Events}). When making key +bindings, you can use the read syntax for characters with modifier bits +(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with +@code{define-key}, you can use lists such as @code{(control hyper ?x)} to +specify the characters (@pxref{Changing Key Bindings}). The function +@code{event-convert-list} converts such a list into an event type +(@pxref{Classifying Events}). + +@node Function Keys +@subsection Function Keys + +@cindex function keys +Most keyboards also have @dfn{function keys}---keys that have names or +symbols that are not characters. Function keys are represented in Emacs +Lisp as symbols; the symbol's name is the function key's label, in lower +case. For example, pressing a key labeled @key{F1} places the symbol +@code{f1} in the input stream. + +The event type of a function key event is the event symbol itself. +@xref{Classifying Events}. + +Here are a few special cases in the symbol-naming convention for +function keys: + +@table @asis +@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} +These keys correspond to common @acronym{ASCII} control characters that have +special keys on most keyboards. + +In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the +terminal can distinguish between them, Emacs conveys the distinction to +Lisp programs by representing the former as the integer 9, and the +latter as the symbol @code{tab}. + +Most of the time, it's not useful to distinguish the two. So normally +@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map +@code{tab} into 9. Thus, a key binding for character code 9 (the +character @kbd{C-i}) also applies to @code{tab}. Likewise for the other +symbols in this group. The function @code{read-char} likewise converts +these events into characters. + +In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} +converts into the character code 127 (@key{DEL}), not into code 8 +(@key{BS}). This is what most users prefer. + +@item @code{left}, @code{up}, @code{right}, @code{down} +Cursor arrow keys +@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} +Keypad keys (to the right of the regular keyboard). +@item @code{kp-0}, @code{kp-1}, @dots{} +Keypad keys with digits. +@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} +Keypad PF keys. +@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} +Keypad arrow keys. Emacs normally translates these into the +corresponding non-keypad keys @code{home}, @code{left}, @dots{} +@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} +Additional keypad duplicates of keys ordinarily found elsewhere. Emacs +normally translates these into the like-named non-keypad keys. +@end table + +You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, +@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to +represent them is with prefixes in the symbol name: + +@table @samp +@item A- +The alt modifier. +@item C- +The control modifier. +@item H- +The hyper modifier. +@item M- +The meta modifier. +@item S- +The shift modifier. +@item s- +The super modifier. +@end table + +Thus, the symbol for the key @key{F3} with @key{META} held down is +@code{M-f3}. When you use more than one prefix, we recommend you +write them in alphabetical order; but the order does not matter in +arguments to the key-binding lookup and modification functions. + +@node Mouse Events +@subsection Mouse Events + +Emacs supports four kinds of mouse events: click events, drag events, +button-down events, and motion events. All mouse events are represented +as lists. The @sc{car} of the list is the event type; this says which +mouse button was involved, and which modifier keys were used with it. +The event type can also distinguish double or triple button presses +(@pxref{Repeat Events}). The rest of the list elements give position +and time information. + +For key lookup, only the event type matters: two events of the same type +necessarily run the same command. The command can access the full +values of these events using the @samp{e} interactive code. +@xref{Interactive Codes}. + +A key sequence that starts with a mouse event is read using the keymaps +of the buffer in the window that the mouse was in, not the current +buffer. This does not imply that clicking in a window selects that +window or its buffer---that is entirely under the control of the command +binding of the key sequence. + +@node Click Events +@subsection Click Events +@cindex click event +@cindex mouse click event + +When the user presses a mouse button and releases it at the same +location, that generates a @dfn{click} event. All mouse click event +share the same format: + +@example +(@var{event-type} @var{position} @var{click-count}) +@end example + +@table @asis +@item @var{event-type} +This is a symbol that indicates which mouse button was used. It is +one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the +buttons are numbered left to right. + +You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, +@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift +and super, just as you would with function keys. + +This symbol also serves as the event type of the event. Key bindings +describe events by their types; thus, if there is a key binding for +@code{mouse-1}, that binding would apply to all events whose +@var{event-type} is @code{mouse-1}. + +@item @var{position} +This is the position where the mouse click occurred. The actual +format of @var{position} depends on what part of a window was clicked +on. + +For mouse click events in the text area, mode line, header line, or in +the marginal areas, @var{position} has this form: + +@example +(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} + @var{object} @var{text-pos} (@var{col} . @var{row}) + @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) +@end example + +@table @asis +@item @var{window} +This is the window in which the click occurred. + +@item @var{pos-or-area} +This is the buffer position of the character clicked on in the text +area, or if clicked outside the text area, it is the window area in +which the click occurred. It is one of the symbols @code{mode-line}, +@code{header-line}, @code{vertical-line}, @code{left-margin}, +@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. + +In one special case, @var{pos-or-area} is a list containing a symbol (one +of the symbols listed above) instead of just the symbol. This happens +after the imaginary prefix keys for the event are inserted into the +input stream. @xref{Key Sequence Input}. + + +@item @var{x}, @var{y} +These are the pixel coordinates of the click, relative to +the top left corner of @var{window}, which is @code{(0 . 0)}. +For the mode or header line, @var{y} does not have meaningful data. +For the vertical line, @var{x} does not have meaningful data. + +@item @var{timestamp} +This is the time at which the event occurred, in milliseconds. + +@item @var{object} +This is the object on which the click occurred. It is either +@code{nil} if there is no string property, or it has the form +(@var{string} . @var{string-pos}) when there is a string-type text +property at the click position. + +@table @asis +@item @var{string} +This is the string on which the click occurred, including any +properties. + +@item @var{string-pos} +This is the position in the string on which the click occurred, +relevant if properties at the click need to be looked up. +@end table + +@item @var{text-pos} +For clicks on a marginal area or on a fringe, this is the buffer +position of the first visible character in the corresponding line in +the window. For other events, it is the current buffer position in +the window. + +@item @var{col}, @var{row} +These are the actual coordinates of the glyph under the @var{x}, +@var{y} position, possibly padded with default character width +glyphs if @var{x} is beyond the last glyph on the line. + +@item @var{image} +This is the image object on which the click occurred. It is either +@code{nil} if there is no image at the position clicked on, or it is +an image object as returned by @code{find-image} if click was in an image. + +@item @var{dx}, @var{dy} +These are the pixel coordinates of the click, relative to +the top left corner of @var{object}, which is @code{(0 . 0)}. If +@var{object} is @code{nil}, the coordinates are relative to the top +left corner of the character glyph clicked on. + +@item @var{width}, @var{height} +These are the pixel width and height of @var{object} or, if this is +@code{nil}, those of the character glyph clicked on. +@end table + +@sp 1 +For mouse clicks on a scroll-bar, @var{position} has this form: + +@example +(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) +@end example + +@table @asis +@item @var{window} +This is the window whose scroll-bar was clicked on. + +@item @var{area} +This is the scroll bar where the click occurred. It is one of the +symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. + +@item @var{portion} +This is the distance of the click from the top or left end of +the scroll bar. + +@item @var{whole} +This is the length of the entire scroll bar. + +@item @var{timestamp} +This is the time at which the event occurred, in milliseconds. + +@item @var{part} +This is the part of the scroll-bar which was clicked on. It is one +of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, +@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. +@end table + +@item @var{click-count} +This is the number of rapid repeated presses so far of the same mouse +button. @xref{Repeat Events}. +@end table + +@node Drag Events +@subsection Drag Events +@cindex drag event +@cindex mouse drag event + +With Emacs, you can have a drag event without even changing your +clothes. A @dfn{drag event} happens every time the user presses a mouse +button and then moves the mouse to a different character position before +releasing the button. Like all mouse events, drag events are +represented in Lisp as lists. The lists record both the starting mouse +position and the final position, like this: + +@example +(@var{event-type} + (@var{window1} START-POSITION) + (@var{window2} END-POSITION)) +@end example + +For a drag event, the name of the symbol @var{event-type} contains the +prefix @samp{drag-}. For example, dragging the mouse with button 2 +held down generates a @code{drag-mouse-2} event. The second and third +elements of the event give the starting and ending position of the +drag. They have the same form as @var{position} in a click event +(@pxref{Click Events}) that is not on the scroll bar part of the +window. You can access the second element of any mouse event in the +same way, with no need to distinguish drag events from others. + +The @samp{drag-} prefix follows the modifier key prefixes such as +@samp{C-} and @samp{M-}. + +If @code{read-key-sequence} receives a drag event that has no key +binding, and the corresponding click event does have a binding, it +changes the drag event into a click event at the drag's starting +position. This means that you don't have to distinguish between click +and drag events unless you want to. + +@node Button-Down Events +@subsection Button-Down Events +@cindex button-down event + +Click and drag events happen when the user releases a mouse button. +They cannot happen earlier, because there is no way to distinguish a +click from a drag until the button is released. + +If you want to take action as soon as a button is pressed, you need to +handle @dfn{button-down} events.@footnote{Button-down is the +conservative antithesis of drag.} These occur as soon as a button is +pressed. They are represented by lists that look exactly like click +events (@pxref{Click Events}), except that the @var{event-type} symbol +name contains the prefix @samp{down-}. The @samp{down-} prefix follows +modifier key prefixes such as @samp{C-} and @samp{M-}. + +The function @code{read-key-sequence} ignores any button-down events +that don't have command bindings; therefore, the Emacs command loop +ignores them too. This means that you need not worry about defining +button-down events unless you want them to do something. The usual +reason to define a button-down event is so that you can track mouse +motion (by reading motion events) until the button is released. +@xref{Motion Events}. + +@node Repeat Events +@subsection Repeat Events +@cindex repeat events +@cindex double-click events +@cindex triple-click events +@cindex mouse events, repeated + +If you press the same mouse button more than once in quick succession +without moving the mouse, Emacs generates special @dfn{repeat} mouse +events for the second and subsequent presses. + +The most common repeat events are @dfn{double-click} events. Emacs +generates a double-click event when you click a button twice; the event +happens when you release the button (as is normal for all click +events). + +The event type of a double-click event contains the prefix +@samp{double-}. Thus, a double click on the second mouse button with +@key{meta} held down comes to the Lisp program as +@code{M-double-mouse-2}. If a double-click event has no binding, the +binding of the corresponding ordinary click event is used to execute +it. Thus, you need not pay attention to the double click feature +unless you really want to. + +When the user performs a double click, Emacs generates first an ordinary +click event, and then a double-click event. Therefore, you must design +the command binding of the double click event to assume that the +single-click command has already run. It must produce the desired +results of a double click, starting from the results of a single click. + +This is convenient, if the meaning of a double click somehow ``builds +on'' the meaning of a single click---which is recommended user interface +design practice for double clicks. + +If you click a button, then press it down again and start moving the +mouse with the button held down, then you get a @dfn{double-drag} event +when you ultimately release the button. Its event type contains +@samp{double-drag} instead of just @samp{drag}. If a double-drag event +has no binding, Emacs looks for an alternate binding as if the event +were an ordinary drag. + +Before the double-click or double-drag event, Emacs generates a +@dfn{double-down} event when the user presses the button down for the +second time. Its event type contains @samp{double-down} instead of just +@samp{down}. If a double-down event has no binding, Emacs looks for an +alternate binding as if the event were an ordinary button-down event. +If it finds no binding that way either, the double-down event is +ignored. + +To summarize, when you click a button and then press it again right +away, Emacs generates a down event and a click event for the first +click, a double-down event when you press the button again, and finally +either a double-click or a double-drag event. + +If you click a button twice and then press it again, all in quick +succession, Emacs generates a @dfn{triple-down} event, followed by +either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of +these events contain @samp{triple} instead of @samp{double}. If any +triple event has no binding, Emacs uses the binding that it would use +for the corresponding double event. + +If you click a button three or more times and then press it again, the +events for the presses beyond the third are all triple events. Emacs +does not have separate event types for quadruple, quintuple, etc.@: +events. However, you can look at the event list to find out precisely +how many times the button was pressed. + +@defun event-click-count event +This function returns the number of consecutive button presses that led +up to @var{event}. If @var{event} is a double-down, double-click or +double-drag event, the value is 2. If @var{event} is a triple event, +the value is 3 or greater. If @var{event} is an ordinary mouse event +(not a repeat event), the value is 1. +@end defun + +@defopt double-click-fuzz +To generate repeat events, successive mouse button presses must be at +approximately the same screen position. The value of +@code{double-click-fuzz} specifies the maximum number of pixels the +mouse may be moved (horizontally or vertically) between two successive +clicks to make a double-click. + +This variable is also the threshold for motion of the mouse to count +as a drag. +@end defopt + +@defopt double-click-time +To generate repeat events, the number of milliseconds between +successive button presses must be less than the value of +@code{double-click-time}. Setting @code{double-click-time} to +@code{nil} disables multi-click detection entirely. Setting it to +@code{t} removes the time limit; Emacs then detects multi-clicks by +position only. +@end defopt + +@node Motion Events +@subsection Motion Events +@cindex motion event +@cindex mouse motion events + +Emacs sometimes generates @dfn{mouse motion} events to describe motion +of the mouse without any button activity. Mouse motion events are +represented by lists that look like this: + +@example +(mouse-movement (POSITION)) +@end example + +The second element of the list describes the current position of the +mouse, just as in a click event (@pxref{Click Events}). + +The special form @code{track-mouse} enables generation of motion events +within its body. Outside of @code{track-mouse} forms, Emacs does not +generate events for mere motion of the mouse, and these events do not +appear. @xref{Mouse Tracking}. + +@node Focus Events +@subsection Focus Events +@cindex focus event + +Window systems provide general ways for the user to control which window +gets keyboard input. This choice of window is called the @dfn{focus}. +When the user does something to switch between Emacs frames, that +generates a @dfn{focus event}. The normal definition of a focus event, +in the global keymap, is to select a new frame within Emacs, as the user +would expect. @xref{Input Focus}. + +Focus events are represented in Lisp as lists that look like this: + +@example +(switch-frame @var{new-frame}) +@end example + +@noindent +where @var{new-frame} is the frame switched to. + +Most X window managers are set up so that just moving the mouse into a +window is enough to set the focus there. Emacs appears to do this, +because it changes the cursor to solid in the new frame. However, there +is no need for the Lisp program to know about the focus change until +some other kind of input arrives. So Emacs generates a focus event only +when the user actually types a keyboard key or presses a mouse button in +the new frame; just moving the mouse between frames does not generate a +focus event. + +A focus event in the middle of a key sequence would garble the +sequence. So Emacs never generates a focus event in the middle of a key +sequence. If the user changes focus in the middle of a key +sequence---that is, after a prefix key---then Emacs reorders the events +so that the focus event comes either before or after the multi-event key +sequence, and not within it. + +@node Misc Events +@subsection Miscellaneous System Events + +A few other event types represent occurrences within the system. + +@table @code +@cindex @code{delete-frame} event +@item (delete-frame (@var{frame})) +This kind of event indicates that the user gave the window manager +a command to delete a particular window, which happens to be an Emacs frame. + +The standard definition of the @code{delete-frame} event is to delete @var{frame}. + +@cindex @code{iconify-frame} event +@item (iconify-frame (@var{frame})) +This kind of event indicates that the user iconified @var{frame} using +the window manager. Its standard definition is @code{ignore}; since the +frame has already been iconified, Emacs has no work to do. The purpose +of this event type is so that you can keep track of such events if you +want to. + +@cindex @code{make-frame-visible} event +@item (make-frame-visible (@var{frame})) +This kind of event indicates that the user deiconified @var{frame} using +the window manager. Its standard definition is @code{ignore}; since the +frame has already been made visible, Emacs has no work to do. + +@cindex @code{wheel-up} event +@cindex @code{wheel-down} event +@item (wheel-up @var{position}) +@item (wheel-down @var{position}) +These kinds of event are generated by moving a mouse wheel. Their +usual meaning is a kind of scroll or zoom. + +The element @var{position} is a list describing the position of the +event, in the same format as used in a mouse-click event. + +This kind of event is generated only on some kinds of systems. On some +systems, @code{mouse-4} and @code{mouse-5} are used instead. For +portable code, use the variables @code{mouse-wheel-up-event} and +@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine +what event types to expect for the mouse wheel. + +@cindex @code{drag-n-drop} event +@item (drag-n-drop @var{position} @var{files}) +This kind of event is generated when a group of files is +selected in an application outside of Emacs, and then dragged and +dropped onto an Emacs frame. + +The element @var{position} is a list describing the position of the +event, in the same format as used in a mouse-click event, and +@var{files} is the list of file names that were dragged and dropped. +The usual way to handle this event is by visiting these files. + +This kind of event is generated, at present, only on some kinds of +systems. + +@cindex @code{help-echo} event +@item help-echo +This kind of event is generated when a mouse pointer moves onto a +portion of buffer text which has a @code{help-echo} text property. +The generated event has this form: + +@example +(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) +@end example + +@noindent +The precise meaning of the event parameters and the way these +parameters are used to display the help-echo text are described in +@ref{Text help-echo}. + +@cindex @code{sigusr1} event +@cindex @code{sigusr2} event +@cindex user signals +@item sigusr1 +@itemx sigusr2 +These events are generated when the Emacs process receives +the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no +additional data because signals do not carry additional information. + +To catch a user signal, bind the corresponding event to an interactive +command in the @code{special-event-map} (@pxref{Active Keymaps}). +The command is called with no arguments, and the specific signal event is +available in @code{last-input-event}. For example: + +@smallexample +(defun sigusr-handler () + (interactive) + (message "Caught signal %S" last-input-event)) + +(define-key special-event-map [sigusr1] 'sigusr-handler) +@end smallexample + +To test the signal handler, you can make Emacs send a signal to itself: + +@smallexample +(signal-process (emacs-pid) 'sigusr1) +@end smallexample +@end table + + If one of these events arrives in the middle of a key sequence---that +is, after a prefix key---then Emacs reorders the events so that this +event comes either before or after the multi-event key sequence, not +within it. + +@node Event Examples +@subsection Event Examples + +If the user presses and releases the left mouse button over the same +location, that generates a sequence of events like this: + +@smallexample +(down-mouse-1 (# 2613 (0 . 38) -864320)) +(mouse-1 (# 2613 (0 . 38) -864180)) +@end smallexample + +While holding the control key down, the user might hold down the +second mouse button, and drag the mouse from one line to the next. +That produces two events, as shown here: + +@smallexample +(C-down-mouse-2 (# 3440 (0 . 27) -731219)) +(C-drag-mouse-2 (# 3440 (0 . 27) -731219) + (# 3510 (0 . 28) -729648)) +@end smallexample + +While holding down the meta and shift keys, the user might press the +second mouse button on the window's mode line, and then drag the mouse +into another window. That produces a pair of events like these: + +@smallexample +(M-S-down-mouse-2 (# mode-line (33 . 31) -457844)) +(M-S-drag-mouse-2 (# mode-line (33 . 31) -457844) + (# 161 (33 . 3) + -453816)) +@end smallexample + +To handle a SIGUSR1 signal, define an interactive function, and +bind it to the @code{signal usr1} event sequence: + +@smallexample +(defun usr1-handler () + (interactive) + (message "Got USR1 signal")) +(global-set-key [signal usr1] 'usr1-handler) +@end smallexample + +@node Classifying Events +@subsection Classifying Events +@cindex event type + + Every event has an @dfn{event type}, which classifies the event for +key binding purposes. For a keyboard event, the event type equals the +event value; thus, the event type for a character is the character, and +the event type for a function key symbol is the symbol itself. For +events that are lists, the event type is the symbol in the @sc{car} of +the list. Thus, the event type is always a symbol or a character. + + Two events of the same type are equivalent where key bindings are +concerned; thus, they always run the same command. That does not +necessarily mean they do the same things, however, as some commands look +at the whole event to decide what to do. For example, some commands use +the location of a mouse event to decide where in the buffer to act. + + Sometimes broader classifications of events are useful. For example, +you might want to ask whether an event involved the @key{META} key, +regardless of which other key or mouse button was used. + + The functions @code{event-modifiers} and @code{event-basic-type} are +provided to get such information conveniently. + +@defun event-modifiers event +This function returns a list of the modifiers that @var{event} has. The +modifiers are symbols; they include @code{shift}, @code{control}, +@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, +the modifiers list of a mouse event symbol always contains one of +@code{click}, @code{drag}, and @code{down}. For double or triple +events, it also contains @code{double} or @code{triple}. + +The argument @var{event} may be an entire event object, or just an +event type. If @var{event} is a symbol that has never been used in an +event that has been read as input in the current Emacs session, then +@code{event-modifiers} can return @code{nil}, even when @var{event} +actually has modifiers. + +Here are some examples: + +@example +(event-modifiers ?a) + @result{} nil +(event-modifiers ?A) + @result{} (shift) +(event-modifiers ?\C-a) + @result{} (control) +(event-modifiers ?\C-%) + @result{} (control) +(event-modifiers ?\C-\S-a) + @result{} (control shift) +(event-modifiers 'f5) + @result{} nil +(event-modifiers 's-f5) + @result{} (super) +(event-modifiers 'M-S-f5) + @result{} (meta shift) +(event-modifiers 'mouse-1) + @result{} (click) +(event-modifiers 'down-mouse-1) + @result{} (down) +@end example + +The modifiers list for a click event explicitly contains @code{click}, +but the event symbol name itself does not contain @samp{click}. +@end defun + +@defun event-basic-type event +This function returns the key or mouse button that @var{event} +describes, with all modifiers removed. The @var{event} argument is as +in @code{event-modifiers}. For example: + +@example +(event-basic-type ?a) + @result{} 97 +(event-basic-type ?A) + @result{} 97 +(event-basic-type ?\C-a) + @result{} 97 +(event-basic-type ?\C-\S-a) + @result{} 97 +(event-basic-type 'f5) + @result{} f5 +(event-basic-type 's-f5) + @result{} f5 +(event-basic-type 'M-S-f5) + @result{} f5 +(event-basic-type 'down-mouse-1) + @result{} mouse-1 +@end example +@end defun + +@defun mouse-movement-p object +This function returns non-@code{nil} if @var{object} is a mouse movement +event. +@end defun + +@defun event-convert-list list +This function converts a list of modifier names and a basic event type +to an event type which specifies all of them. The basic event type +must be the last element of the list. For example, + +@example +(event-convert-list '(control ?a)) + @result{} 1 +(event-convert-list '(control meta ?a)) + @result{} -134217727 +(event-convert-list '(control super f1)) + @result{} C-s-f1 +@end example +@end defun + +@node Accessing Events +@subsection Accessing Events +@cindex mouse events, data in + + This section describes convenient functions for accessing the data in +a mouse button or motion event. + + These two functions return the starting or ending position of a +mouse-button event, as a list of this form: + +@example +(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} + @var{object} @var{text-pos} (@var{col} . @var{row}) + @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) +@end example + +@defun event-start event +This returns the starting position of @var{event}. + +If @var{event} is a click or button-down event, this returns the +location of the event. If @var{event} is a drag event, this returns the +drag's starting position. +@end defun + +@defun event-end event +This returns the ending position of @var{event}. + +If @var{event} is a drag event, this returns the position where the user +released the mouse button. If @var{event} is a click or button-down +event, the value is actually the starting position, which is the only +position such events have. +@end defun + +@cindex mouse position list, accessing + These functions take a position list as described above, and +return various parts of it. + +@defun posn-window position +Return the window that @var{position} is in. +@end defun + +@defun posn-area position +Return the window area recorded in @var{position}. It returns @code{nil} +when the event occurred in the text area of the window; otherwise, it +is a symbol identifying the area in which the event occurred. +@end defun + +@defun posn-point position +Return the buffer position in @var{position}. When the event occurred +in the text area of the window, in a marginal area, or on a fringe, +this is an integer specifying a buffer position. Otherwise, the value +is undefined. +@end defun + +@defun posn-x-y position +Return the pixel-based x and y coordinates in @var{position}, as a +cons cell @code{(@var{x} . @var{y})}. These coordinates are relative +to the window given by @code{posn-window}. + +This example shows how to convert these window-relative coordinates +into frame-relative coordinates: + +@example +(defun frame-relative-coordinates (position) + "Return frame-relative coordinates from POSITION." + (let* ((x-y (posn-x-y position)) + (window (posn-window position)) + (edges (window-inside-pixel-edges window))) + (cons (+ (car x-y) (car edges)) + (+ (cdr x-y) (cadr edges))))) +@end example +@end defun + +@defun posn-col-row position +Return the row and column (in units of the frame's default character +height and width) of @var{position}, as a cons cell @code{(@var{col} . +@var{row})}. These are computed from the @var{x} and @var{y} values +actually found in @var{position}. +@end defun + +@defun posn-actual-col-row position +Return the actual row and column in @var{position}, as a cons cell +@code{(@var{col} . @var{row})}. The values are the actual row number +in the window, and the actual character number in that row. It returns +@code{nil} if @var{position} does not include actual positions values. +You can use @code{posn-col-row} to get approximate values. +@end defun + +@defun posn-string position +Return the string object in @var{position}, either @code{nil}, or a +cons cell @code{(@var{string} . @var{string-pos})}. +@end defun + +@defun posn-image position +Return the image object in @var{position}, either @code{nil}, or an +image @code{(image ...)}. +@end defun + +@defun posn-object position +Return the image or string object in @var{position}, either +@code{nil}, an image @code{(image ...)}, or a cons cell +@code{(@var{string} . @var{string-pos})}. +@end defun + +@defun posn-object-x-y position +Return the pixel-based x and y coordinates relative to the upper left +corner of the object in @var{position} as a cons cell @code{(@var{dx} +. @var{dy})}. If the @var{position} is a buffer position, return the +relative position in the character at that position. +@end defun + +@defun posn-object-width-height position +Return the pixel width and height of the object in @var{position} as a +cons cell @code{(@var{width} . @var{height})}. If the @var{position} +is a buffer position, return the size of the character at that position. +@end defun + +@cindex timestamp of a mouse event +@defun posn-timestamp position +Return the timestamp in @var{position}. This is the time at which the +event occurred, in milliseconds. +@end defun + + These functions compute a position list given particular buffer +position or screen position. You can access the data in this position +list with the functions described above. + +@defun posn-at-point &optional pos window +This function returns a position list for position @var{pos} in +@var{window}. @var{pos} defaults to point in @var{window}; +@var{window} defaults to the selected window. + +@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in +@var{window}. +@end defun + +@defun posn-at-x-y x y &optional frame-or-window whole +This function returns position information corresponding to pixel +coordinates @var{x} and @var{y} in a specified frame or window, +@var{frame-or-window}, which defaults to the selected window. +The coordinates @var{x} and @var{y} are relative to the +frame or window used. +If @var{whole} is @code{nil}, the coordinates are relative +to the window text area, otherwise they are relative to +the entire window area including scroll bars, margins and fringes. +@end defun + + These functions are useful for decoding scroll bar events. + +@defun scroll-bar-event-ratio event +This function returns the fractional vertical position of a scroll bar +event within the scroll bar. The value is a cons cell +@code{(@var{portion} . @var{whole})} containing two integers whose ratio +is the fractional position. +@end defun + +@defun scroll-bar-scale ratio total +This function multiplies (in effect) @var{ratio} by @var{total}, +rounding the result to an integer. The argument @var{ratio} is not a +number, but rather a pair @code{(@var{num} . @var{denom})}---typically a +value returned by @code{scroll-bar-event-ratio}. + +This function is handy for scaling a position on a scroll bar into a +buffer position. Here's how to do that: + +@example +(+ (point-min) + (scroll-bar-scale + (posn-x-y (event-start event)) + (- (point-max) (point-min)))) +@end example + +Recall that scroll bar events have two integers forming a ratio, in place +of a pair of x and y coordinates. +@end defun + +@node Strings of Events +@subsection Putting Keyboard Events in Strings +@cindex keyboard events in strings +@cindex strings with keyboard events + + In most of the places where strings are used, we conceptualize the +string as containing text characters---the same kind of characters found +in buffers or files. Occasionally Lisp programs use strings that +conceptually contain keyboard characters; for example, they may be key +sequences or keyboard macro definitions. However, storing keyboard +characters in a string is a complex matter, for reasons of historical +compatibility, and it is not always possible. + + We recommend that new programs avoid dealing with these complexities +by not storing keyboard events in strings. Here is how to do that: + +@itemize @bullet +@item +Use vectors instead of strings for key sequences, when you plan to use +them for anything other than as arguments to @code{lookup-key} and +@code{define-key}. For example, you can use +@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and +@code{this-command-keys-vector} instead of @code{this-command-keys}. + +@item +Use vectors to write key sequence constants containing meta characters, +even when passing them directly to @code{define-key}. + +@item +When you have to look at the contents of a key sequence that might be a +string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) +first, to convert it to a list. +@end itemize + + The complexities stem from the modifier bits that keyboard input +characters can include. Aside from the Meta modifier, none of these +modifier bits can be included in a string, and the Meta modifier is +allowed only in special cases. + + The earliest GNU Emacs versions represented meta characters as codes +in the range of 128 to 255. At that time, the basic character codes +ranged from 0 to 127, so all keyboard character codes did fit in a +string. Many Lisp programs used @samp{\M-} in string constants to stand +for meta characters, especially in arguments to @code{define-key} and +similar functions, and key sequences and sequences of events were always +represented as strings. + + When we added support for larger basic character codes beyond 127, and +additional modifier bits, we had to change the representation of meta +characters. Now the flag that represents the Meta modifier in a +character is +@tex +@math{2^{27}} +@end tex +@ifnottex +2**27 +@end ifnottex +and such numbers cannot be included in a string. + + To support programs with @samp{\M-} in string constants, there are +special rules for including certain meta characters in a string. +Here are the rules for interpreting a string as a sequence of input +characters: + +@itemize @bullet +@item +If the keyboard character value is in the range of 0 to 127, it can go +in the string unchanged. + +@item +The meta variants of those characters, with codes in the range of +@tex +@math{2^{27}} +@end tex +@ifnottex +2**27 +@end ifnottex +to +@tex +@math{2^{27} + 127}, +@end tex +@ifnottex +2**27+127, +@end ifnottex +can also go in the string, but you must change their +numeric values. You must set the +@tex +@math{2^{7}} +@end tex +@ifnottex +2**7 +@end ifnottex +bit instead of the +@tex +@math{2^{27}} +@end tex +@ifnottex +2**27 +@end ifnottex +bit, resulting in a value between 128 and 255. Only a unibyte string +can include these codes. + +@item +Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. + +@item +Other keyboard character events cannot fit in a string. This includes +keyboard events in the range of 128 to 255. +@end itemize + + Functions such as @code{read-key-sequence} that construct strings of +keyboard input characters follow these rules: they construct vectors +instead of strings, when the events won't fit in a string. + + When you use the read syntax @samp{\M-} in a string, it produces a +code in the range of 128 to 255---the same code that you get if you +modify the corresponding keyboard event to put it in the string. Thus, +meta events in strings work consistently regardless of how they get into +the strings. + + However, most programs would do well to avoid these issues by +following the recommendations at the beginning of this section. + +@node Reading Input +@section Reading Input +@cindex read input +@cindex keyboard input + + The editor command loop reads key sequences using the function +@code{read-key-sequence}, which uses @code{read-event}. These and other +functions for event input are also available for use in Lisp programs. +See also @code{momentary-string-display} in @ref{Temporary Displays}, +and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for +functions and variables for controlling terminal input modes and +debugging terminal input. + + For higher-level input facilities, see @ref{Minibuffers}. + +@menu +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Event Mod:: How Emacs modifies events as they are read. +* Invoking the Input Method:: How reading an event uses the input method. +* Quoted Character Input:: Asking the user to specify a character. +* Event Input Misc:: How to reread or throw away input events. +@end menu + +@node Key Sequence Input +@subsection Key Sequence Input +@cindex key sequence input + + The command loop reads input a key sequence at a time, by calling +@code{read-key-sequence}. Lisp programs can also call this function; +for example, @code{describe-key} uses it to read the key to describe. + +@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop +This function reads a key sequence and returns it as a string or +vector. It keeps reading events until it has accumulated a complete key +sequence; that is, enough to specify a non-prefix command using the +currently active keymaps. (Remember that a key sequence that starts +with a mouse event is read using the keymaps of the buffer in the +window that the mouse was in, not the current buffer.) + +If the events are all characters and all can fit in a string, then +@code{read-key-sequence} returns a string (@pxref{Strings of Events}). +Otherwise, it returns a vector, since a vector can hold all kinds of +events---characters, symbols, and lists. The elements of the string or +vector are the events in the key sequence. + +Reading a key sequence includes translating the events in various +ways. @xref{Translation Keymaps}. + +The argument @var{prompt} is either a string to be displayed in the +echo area as a prompt, or @code{nil}, meaning not to display a prompt. +The argument @var{continue-echo}, if non-@code{nil}, means to echo +this key as a continuation of the previous key. + +Normally any upper case event is converted to lower case if the +original event is undefined and the lower case equivalent is defined. +The argument @var{dont-downcase-last}, if non-@code{nil}, means do not +convert the last event to lower case. This is appropriate for reading +a key sequence to be defined. + +The argument @var{switch-frame-ok}, if non-@code{nil}, means that this +function should process a @code{switch-frame} event if the user +switches frames before typing anything. If the user switches frames +in the middle of a key sequence, or at the start of the sequence but +@var{switch-frame-ok} is @code{nil}, then the event will be put off +until after the current key sequence. + +The argument @var{command-loop}, if non-@code{nil}, means that this +key sequence is being read by something that will read commands one +after another. It should be @code{nil} if the caller will read just +one key sequence. + +In the following example, Emacs displays the prompt @samp{?} in the +echo area, and then the user types @kbd{C-x C-f}. + +@example +(read-key-sequence "?") + +@group +---------- Echo Area ---------- +?@kbd{C-x C-f} +---------- Echo Area ---------- + + @result{} "^X^F" +@end group +@end example + +The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} +typed while reading with this function works like any other character, +and does not set @code{quit-flag}. @xref{Quitting}. +@end defun + +@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop +This is like @code{read-key-sequence} except that it always +returns the key sequence as a vector, never as a string. +@xref{Strings of Events}. +@end defun + +@cindex upper case key sequence +@cindex downcasing in @code{lookup-key} +If an input character is upper-case (or has the shift modifier) and +has no key binding, but its lower-case equivalent has one, then +@code{read-key-sequence} converts the character to lower case. Note +that @code{lookup-key} does not perform case conversion in this way. + +The function @code{read-key-sequence} also transforms some mouse events. +It converts unbound drag events into click events, and discards unbound +button-down events entirely. It also reshuffles focus events and +miscellaneous window events so that they never appear in a key sequence +with any other events. + +@cindex @code{header-line} prefix key +@cindex @code{mode-line} prefix key +@cindex @code{vertical-line} prefix key +@cindex @code{horizontal-scroll-bar} prefix key +@cindex @code{vertical-scroll-bar} prefix key +@cindex @code{menu-bar} prefix key +@cindex mouse events, in special parts of frame +When mouse events occur in special parts of a window, such as a mode +line or a scroll bar, the event type shows nothing special---it is the +same symbol that would normally represent that combination of mouse +button and modifier keys. The information about the window part is kept +elsewhere in the event---in the coordinates. But +@code{read-key-sequence} translates this information into imaginary +``prefix keys,'' all of which are symbols: @code{header-line}, +@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, +@code{vertical-line}, and @code{vertical-scroll-bar}. You can define +meanings for mouse clicks in special window parts by defining key +sequences using these imaginary prefix keys. + +For example, if you call @code{read-key-sequence} and then click the +mouse on the window's mode line, you get two events, like this: + +@example +(read-key-sequence "Click on the mode line: ") + @result{} [mode-line + (mouse-1 + (# mode-line + (40 . 63) 5959987))] +@end example + +@defvar num-input-keys +@c Emacs 19 feature +This variable's value is the number of key sequences processed so far in +this Emacs session. This includes key sequences read from the terminal +and key sequences read from keyboard macros being executed. +@end defvar + +@node Reading One Event +@subsection Reading One Event +@cindex reading a single event +@cindex event, reading only one + + The lowest level functions for command input are those that read a +single event. + +None of the three functions below suppresses quitting. + +@defun read-event &optional prompt inherit-input-method seconds +This function reads and returns the next event of command input, waiting +if necessary until an event is available. Events can come directly from +the user or from a keyboard macro. + +If the optional argument @var{prompt} is non-@code{nil}, it should be a +string to display in the echo area as a prompt. Otherwise, +@code{read-event} does not display any message to indicate it is waiting +for input; instead, it prompts by echoing: it displays descriptions of +the events that led to or were read by the current command. @xref{The +Echo Area}. + +If @var{inherit-input-method} is non-@code{nil}, then the current input +method (if any) is employed to make it possible to enter a +non-@acronym{ASCII} character. Otherwise, input method handling is disabled +for reading this event. + +If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} +moves the cursor temporarily to the echo area, to the end of any message +displayed there. Otherwise @code{read-event} does not move the cursor. + +If @var{seconds} is non-@code{nil}, it should be a number specifying +the maximum time to wait for input, in seconds. If no input arrives +within that time, @code{read-event} stops waiting and returns +@code{nil}. A floating-point value for @var{seconds} means to wait +for a fractional number of seconds. Some systems support only a whole +number of seconds; on these systems, @var{seconds} is rounded down. +If @var{seconds} is @code{nil}, @code{read-event} waits as long as +necessary for input to arrive. + +If @var{seconds} is @code{nil}, Emacs is considered idle while waiting +for user input to arrive. Idle timers---those created with +@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this +period. However, if @var{seconds} is non-@code{nil}, the state of +idleness remains unchanged. If Emacs is non-idle when +@code{read-event} is called, it remains non-idle throughout the +operation of @code{read-event}; if Emacs is idle (which can happen if +the call happens inside an idle timer), it remains idle. + +If @code{read-event} gets an event that is defined as a help character, +then in some cases @code{read-event} processes the event directly without +returning. @xref{Help Functions}. Certain other events, called +@dfn{special events}, are also processed directly within +@code{read-event} (@pxref{Special Events}). + +Here is what happens if you call @code{read-event} and then press the +right-arrow function key: + +@example +@group +(read-event) + @result{} right +@end group +@end example +@end defun + +@defun read-char &optional prompt inherit-input-method seconds +This function reads and returns a character of command input. If the +user generates an event which is not a character (i.e. a mouse click or +function key event), @code{read-char} signals an error. The arguments +work as in @code{read-event}. + +In the first example, the user types the character @kbd{1} (@acronym{ASCII} +code 49). The second example shows a keyboard macro definition that +calls @code{read-char} from the minibuffer using @code{eval-expression}. +@code{read-char} reads the keyboard macro's very next character, which +is @kbd{1}. Then @code{eval-expression} displays its return value in +the echo area. + +@example +@group +(read-char) + @result{} 49 +@end group + +@group +;; @r{We assume here you use @kbd{M-:} to evaluate this.} +(symbol-function 'foo) + @result{} "^[:(read-char)^M1" +@end group +@group +(execute-kbd-macro 'foo) + @print{} 49 + @result{} nil +@end group +@end example +@end defun + +@defun read-char-exclusive &optional prompt inherit-input-method seconds +This function reads and returns a character of command input. If the +user generates an event which is not a character, +@code{read-char-exclusive} ignores it and reads another event, until it +gets a character. The arguments work as in @code{read-event}. +@end defun + +@defvar num-nonmacro-input-events +This variable holds the total number of input events received so far +from the terminal---not counting those generated by keyboard macros. +@end defvar + +@node Event Mod +@subsection Modifying and Translating Input Events + + Emacs modifies every event it reads according to +@code{extra-keyboard-modifiers}, then translates it through +@code{keyboard-translate-table} (if applicable), before returning it +from @code{read-event}. + +@c Emacs 19 feature +@defvar extra-keyboard-modifiers +This variable lets Lisp programs ``press'' the modifier keys on the +keyboard. The value is a character. Only the modifiers of the +character matter. Each time the user types a keyboard key, it is +altered as if those modifier keys were held down. For instance, if +you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all +keyboard input characters typed during the scope of the binding will +have the control and meta modifiers applied to them. The character +@code{?\C-@@}, equivalent to the integer 0, does not count as a control +character for this purpose, but as a character with no modifiers. +Thus, setting @code{extra-keyboard-modifiers} to zero cancels any +modification. + +When using a window system, the program can ``press'' any of the +modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} +keys can be virtually pressed. + +Note that this variable applies only to events that really come from +the keyboard, and has no effect on mouse events or any other events. +@end defvar + +@defvar keyboard-translate-table +This variable is the translate table for keyboard characters. It lets +you reshuffle the keys on the keyboard without changing any command +bindings. Its value is normally a char-table, or else @code{nil}. +(It can also be a string or vector, but this is considered obsolete.) + +If @code{keyboard-translate-table} is a char-table +(@pxref{Char-Tables}), then each character read from the keyboard is +looked up in this char-table. If the value found there is +non-@code{nil}, then it is used instead of the actual input character. + +Note that this translation is the first thing that happens to a +character after it is read from the terminal. Record-keeping features +such as @code{recent-keys} and dribble files record the characters after +translation. + +Note also that this translation is done before the characters are +supplied to input methods (@pxref{Input Methods}). Use +@code{translation-table-for-input} (@pxref{Translation of Characters}), +if you want to translate characters after input methods operate. +@end defvar + +@defun keyboard-translate from to +This function modifies @code{keyboard-translate-table} to translate +character code @var{from} into character code @var{to}. It creates +the keyboard translate table if necessary. +@end defun + + Here's an example of using the @code{keyboard-translate-table} to +make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste +operations: + +@example +(keyboard-translate ?\C-x 'control-x) +(keyboard-translate ?\C-c 'control-c) +(keyboard-translate ?\C-v 'control-v) +(global-set-key [control-x] 'kill-region) +(global-set-key [control-c] 'kill-ring-save) +(global-set-key [control-v] 'yank) +@end example + +@noindent +On a graphical terminal that supports extended @acronym{ASCII} input, +you can still get the standard Emacs meanings of one of those +characters by typing it with the shift key. That makes it a different +character as far as keyboard translation is concerned, but it has the +same usual meaning. + + @xref{Translation Keymaps}, for mechanisms that translate event sequences +at the level of @code{read-key-sequence}. + +@node Invoking the Input Method +@subsection Invoking the Input Method + + The event-reading functions invoke the current input method, if any +(@pxref{Input Methods}). If the value of @code{input-method-function} +is non-@code{nil}, it should be a function; when @code{read-event} reads +a printing character (including @key{SPC}) with no modifier bits, it +calls that function, passing the character as an argument. + +@defvar input-method-function +If this is non-@code{nil}, its value specifies the current input method +function. + +@strong{Warning:} don't bind this variable with @code{let}. It is often +buffer-local, and if you bind it around reading input (which is exactly +when you @emph{would} bind it), switching buffers asynchronously while +Emacs is waiting will cause the value to be restored in the wrong +buffer. +@end defvar + + The input method function should return a list of events which should +be used as input. (If the list is @code{nil}, that means there is no +input, so @code{read-event} waits for another event.) These events are +processed before the events in @code{unread-command-events} +(@pxref{Event Input Misc}). Events +returned by the input method function are not passed to the input method +function again, even if they are printing characters with no modifier +bits. + + If the input method function calls @code{read-event} or +@code{read-key-sequence}, it should bind @code{input-method-function} to +@code{nil} first, to prevent recursion. + + The input method function is not called when reading the second and +subsequent events of a key sequence. Thus, these characters are not +subject to input method processing. The input method function should +test the values of @code{overriding-local-map} and +@code{overriding-terminal-local-map}; if either of these variables is +non-@code{nil}, the input method should put its argument into a list and +return that list with no further processing. + +@node Quoted Character Input +@subsection Quoted Character Input +@cindex quoted character input + + You can use the function @code{read-quoted-char} to ask the user to +specify a character, and allow the user to specify a control or meta +character conveniently, either literally or as an octal character code. +The command @code{quoted-insert} uses this function. + +@defun read-quoted-char &optional prompt +@cindex octal character input +@cindex control characters, reading +@cindex nonprinting characters, reading +This function is like @code{read-char}, except that if the first +character read is an octal digit (0-7), it reads any number of octal +digits (but stopping if a non-octal digit is found), and returns the +character represented by that numeric character code. If the +character that terminates the sequence of octal digits is @key{RET}, +it is discarded. Any other terminating character is used as input +after this function returns. + +Quitting is suppressed when the first character is read, so that the +user can enter a @kbd{C-g}. @xref{Quitting}. + +If @var{prompt} is supplied, it specifies a string for prompting the +user. The prompt string is always displayed in the echo area, followed +by a single @samp{-}. + +In the following example, the user types in the octal number 177 (which +is 127 in decimal). + +@example +(read-quoted-char "What character") + +@group +---------- Echo Area ---------- +What character @kbd{1 7 7}- +---------- Echo Area ---------- + + @result{} 127 +@end group +@end example +@end defun + +@need 2000 +@node Event Input Misc +@subsection Miscellaneous Event Input Features + +This section describes how to ``peek ahead'' at events without using +them up, how to check for pending input, and how to discard pending +input. See also the function @code{read-passwd} (@pxref{Reading a +Password}). + +@defvar unread-command-events +@cindex next input +@cindex peeking at input +This variable holds a list of events waiting to be read as command +input. The events are used in the order they appear in the list, and +removed one by one as they are used. + +The variable is needed because in some cases a function reads an event +and then decides not to use it. Storing the event in this variable +causes it to be processed normally, by the command loop or by the +functions to read command input. + +@cindex prefix argument unreading +For example, the function that implements numeric prefix arguments reads +any number of digits. When it finds a non-digit event, it must unread +the event so that it can be read normally by the command loop. +Likewise, incremental search uses this feature to unread events with no +special meaning in a search, because these events should exit the search +and then execute normally. + +The reliable and easy way to extract events from a key sequence so as to +put them in @code{unread-command-events} is to use +@code{listify-key-sequence} (@pxref{Strings of Events}). + +Normally you add events to the front of this list, so that the events +most recently unread will be reread first. + +Events read from this list are not normally added to the current +command's key sequence (as returned by e.g. @code{this-command-keys}), +as the events will already have been added once as they were read for +the first time. An element of the form @code{(@code{t} . @var{event})} +forces @var{event} to be added to the current command's key sequence. +@end defvar + +@defun listify-key-sequence key +This function converts the string or vector @var{key} to a list of +individual events, which you can put in @code{unread-command-events}. +@end defun + +@defvar unread-command-char +This variable holds a character to be read as command input. +A value of -1 means ``empty.'' + +This variable is mostly obsolete now that you can use +@code{unread-command-events} instead; it exists only to support programs +written for Emacs versions 18 and earlier. +@end defvar + +@defun input-pending-p +@cindex waiting for command key input +This function determines whether any command input is currently +available to be read. It returns immediately, with value @code{t} if +there is available input, @code{nil} otherwise. On rare occasions it +may return @code{t} when no input is available. +@end defun + +@defvar last-input-event +@defvarx last-input-char +This variable records the last terminal input event read, whether +as part of a command or explicitly by a Lisp program. + +In the example below, the Lisp program reads the character @kbd{1}, +@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, +while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate +this expression) remains the value of @code{last-command-event}. + +@example +@group +(progn (print (read-char)) + (print last-command-event) + last-input-event) + @print{} 49 + @print{} 5 + @result{} 49 +@end group +@end example + +The alias @code{last-input-char} exists for compatibility with +Emacs version 18. +@end defvar + +@defmac while-no-input body@dots{} +This construct runs the @var{body} forms and returns the value of the +last one---but only if no input arrives. If any input arrives during +the execution of the @var{body} forms, it aborts them (working much +like a quit). The @code{while-no-input} form returns @code{nil} if +aborted by a real quit, and returns @code{t} if aborted by arrival of +other input. + +If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, +arrival of input during those parts won't cause an abort until +the end of that part. + +If you want to be able to distinguish all possible values computed +by @var{body} from both kinds of abort conditions, write the code +like this: + +@example +(while-no-input + (list + (progn . @var{body}))) +@end example +@end defmac + +@defun discard-input +@cindex flushing input +@cindex discarding input +@cindex keyboard macro, terminating +This function discards the contents of the terminal input buffer and +cancels any keyboard macro that might be in the process of definition. +It returns @code{nil}. + +In the following example, the user may type a number of characters right +after starting the evaluation of the form. After the @code{sleep-for} +finishes sleeping, @code{discard-input} discards any characters typed +during the sleep. + +@example +(progn (sleep-for 2) + (discard-input)) + @result{} nil +@end example +@end defun + +@node Special Events +@section Special Events + +@cindex special events +Special events are handled at a very low level---as soon as they are +read. The @code{read-event} function processes these events itself, and +never returns them. Instead, it keeps waiting for the first event +that is not special and returns that one. + +Events that are handled in this way do not echo, they are never grouped +into key sequences, and they never appear in the value of +@code{last-command-event} or @code{(this-command-keys)}. They do not +discard a numeric argument, they cannot be unread with +@code{unread-command-events}, they may not appear in a keyboard macro, +and they are not recorded in a keyboard macro while you are defining +one. + +These events do, however, appear in @code{last-input-event} immediately +after they are read, and this is the way for the event's definition to +find the actual event. + +The events types @code{iconify-frame}, @code{make-frame-visible}, +@code{delete-frame}, @code{drag-n-drop}, and user signals like +@code{sigusr1} are normally handled in this way. The keymap which +defines how to handle special events---and which events are special---is +in the variable @code{special-event-map} (@pxref{Active Keymaps}). + +@node Waiting +@section Waiting for Elapsed Time or Input +@cindex waiting + + The wait functions are designed to wait for a certain amount of time +to pass or until there is input. For example, you may wish to pause in +the middle of a computation to allow the user time to view the display. +@code{sit-for} pauses and updates the screen, and returns immediately if +input comes in, while @code{sleep-for} pauses without updating the +screen. + +@defun sit-for seconds &optional nodisp +This function performs redisplay (provided there is no pending input +from the user), then waits @var{seconds} seconds, or until input is +available. The usual purpose of @code{sit-for} is to give the user +time to read text that you display. The value is @code{t} if +@code{sit-for} waited the full time with no input arriving +(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. + +The argument @var{seconds} need not be an integer. If it is a floating +point number, @code{sit-for} waits for a fractional number of seconds. +Some systems support only a whole number of seconds; on these systems, +@var{seconds} is rounded down. + +The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, +i.e. it requests a redisplay, without any delay, if there is no pending input. +@xref{Forcing Redisplay}. + +If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not +redisplay, but it still returns as soon as input is available (or when +the timeout elapses). + +In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be +interrupted, even by input from the standard input descriptor. It is +thus equivalent to @code{sleep-for}, which is described below. + +It is also possible to call @code{sit-for} with three arguments, +as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, +but that is considered obsolete. +@end defun + +@defun sleep-for seconds &optional millisec +This function simply pauses for @var{seconds} seconds without updating +the display. It pays no attention to available input. It returns +@code{nil}. + +The argument @var{seconds} need not be an integer. If it is a floating +point number, @code{sleep-for} waits for a fractional number of seconds. +Some systems support only a whole number of seconds; on these systems, +@var{seconds} is rounded down. + +The optional argument @var{millisec} specifies an additional waiting +period measured in milliseconds. This adds to the period specified by +@var{seconds}. If the system doesn't support waiting fractions of a +second, you get an error if you specify nonzero @var{millisec}. + +Use @code{sleep-for} when you wish to guarantee a delay. +@end defun + + @xref{Time of Day}, for functions to get the current time. + +@node Quitting +@section Quitting +@cindex @kbd{C-g} +@cindex quitting +@cindex interrupt Lisp functions + + Typing @kbd{C-g} while a Lisp function is running causes Emacs to +@dfn{quit} whatever it is doing. This means that control returns to the +innermost active command loop. + + Typing @kbd{C-g} while the command loop is waiting for keyboard input +does not cause a quit; it acts as an ordinary input character. In the +simplest case, you cannot tell the difference, because @kbd{C-g} +normally runs the command @code{keyboard-quit}, whose effect is to quit. +However, when @kbd{C-g} follows a prefix key, they combine to form an +undefined key. The effect is to cancel the prefix key as well as any +prefix argument. + + In the minibuffer, @kbd{C-g} has a different definition: it aborts out +of the minibuffer. This means, in effect, that it exits the minibuffer +and then quits. (Simply quitting would return to the command loop +@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit +directly when the command reader is reading input is so that its meaning +can be redefined in the minibuffer in this way. @kbd{C-g} following a +prefix key is not redefined in the minibuffer, and it has its normal +effect of canceling the prefix key and prefix argument. This too +would not be possible if @kbd{C-g} always quit directly. + + When @kbd{C-g} does directly quit, it does so by setting the variable +@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate +times and quits if it is not @code{nil}. Setting @code{quit-flag} +non-@code{nil} in any way thus causes a quit. + + At the level of C code, quitting cannot happen just anywhere; only at the +special places that check @code{quit-flag}. The reason for this is +that quitting at other places might leave an inconsistency in Emacs's +internal state. Because quitting is delayed until a safe place, quitting +cannot make Emacs crash. + + Certain functions such as @code{read-key-sequence} or +@code{read-quoted-char} prevent quitting entirely even though they wait +for input. Instead of quitting, @kbd{C-g} serves as the requested +input. In the case of @code{read-key-sequence}, this serves to bring +about the special behavior of @kbd{C-g} in the command loop. In the +case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used +to quote a @kbd{C-g}. + +@cindex preventing quitting + You can prevent quitting for a portion of a Lisp function by binding +the variable @code{inhibit-quit} to a non-@code{nil} value. Then, +although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the +usual result of this---a quit---is prevented. Eventually, +@code{inhibit-quit} will become @code{nil} again, such as when its +binding is unwound at the end of a @code{let} form. At that time, if +@code{quit-flag} is still non-@code{nil}, the requested quit happens +immediately. This behavior is ideal when you wish to make sure that +quitting does not happen within a ``critical section'' of the program. + +@cindex @code{read-quoted-char} quitting + In some functions (such as @code{read-quoted-char}), @kbd{C-g} is +handled in a special way that does not involve quitting. This is done +by reading the input with @code{inhibit-quit} bound to @code{t}, and +setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} +becomes @code{nil} again. This excerpt from the definition of +@code{read-quoted-char} shows how this is done; it also shows that +normal quitting is permitted after the first character of input. + +@example +(defun read-quoted-char (&optional prompt) + "@dots{}@var{documentation}@dots{}" + (let ((message-log-max nil) done (first t) (code 0) char) + (while (not done) + (let ((inhibit-quit first) + @dots{}) + (and prompt (message "%s-" prompt)) + (setq char (read-event)) + (if inhibit-quit (setq quit-flag nil))) + @r{@dots{}set the variable @code{code}@dots{}}) + code)) +@end example + +@defvar quit-flag +If this variable is non-@code{nil}, then Emacs quits immediately, unless +@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets +@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. +@end defvar + +@defvar inhibit-quit +This variable determines whether Emacs should quit when @code{quit-flag} +is set to a value other than @code{nil}. If @code{inhibit-quit} is +non-@code{nil}, then @code{quit-flag} has no special effect. +@end defvar + +@defmac with-local-quit body@dots{} +This macro executes @var{body} forms in sequence, but allows quitting, at +least locally, within @var{body} even if @code{inhibit-quit} was +non-@code{nil} outside this construct. It returns the value of the +last form in @var{body}, unless exited by quitting, in which case +it returns @code{nil}. + +If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, +it only executes the @var{body}, and setting @code{quit-flag} causes +a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so +that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} +triggers a special kind of local quit. This ends the execution of +@var{body} and exits the @code{with-local-quit} body with +@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit +will happen as soon as that is allowed. If @code{quit-flag} is +already non-@code{nil} at the beginning of @var{body}, the local quit +happens immediately and the body doesn't execute at all. + +This macro is mainly useful in functions that can be called from +timers, process filters, process sentinels, @code{pre-command-hook}, +@code{post-command-hook}, and other places where @code{inhibit-quit} is +normally bound to @code{t}. +@end defmac + +@deffn Command keyboard-quit +This function signals the @code{quit} condition with @code{(signal 'quit +nil)}. This is the same thing that quitting does. (See @code{signal} +in @ref{Errors}.) +@end deffn + + You can specify a character other than @kbd{C-g} to use for quitting. +See the function @code{set-input-mode} in @ref{Terminal Input}. + +@node Prefix Command Arguments +@section Prefix Command Arguments +@cindex prefix argument +@cindex raw prefix argument +@cindex numeric prefix argument + + Most Emacs commands can use a @dfn{prefix argument}, a number +specified before the command itself. (Don't confuse prefix arguments +with prefix keys.) The prefix argument is at all times represented by a +value, which may be @code{nil}, meaning there is currently no prefix +argument. Each command may use the prefix argument or ignore it. + + There are two representations of the prefix argument: @dfn{raw} and +@dfn{numeric}. The editor command loop uses the raw representation +internally, and so do the Lisp variables that store the information, but +commands can request either representation. + + Here are the possible values of a raw prefix argument: + +@itemize @bullet +@item +@code{nil}, meaning there is no prefix argument. Its numeric value is +1, but numerous commands make a distinction between @code{nil} and the +integer 1. + +@item +An integer, which stands for itself. + +@item +A list of one element, which is an integer. This form of prefix +argument results from one or a succession of @kbd{C-u}'s with no +digits. The numeric value is the integer in the list, but some +commands make a distinction between such a list and an integer alone. + +@item +The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was +typed, without following digits. The equivalent numeric value is +@minus{}1, but some commands make a distinction between the integer +@minus{}1 and the symbol @code{-}. +@end itemize + +We illustrate these possibilities by calling the following function with +various prefixes: + +@example +@group +(defun display-prefix (arg) + "Display the value of the raw prefix arg." + (interactive "P") + (message "%s" arg)) +@end group +@end example + +@noindent +Here are the results of calling @code{display-prefix} with various +raw prefix arguments: + +@example + M-x display-prefix @print{} nil + +C-u M-x display-prefix @print{} (4) + +C-u C-u M-x display-prefix @print{} (16) + +C-u 3 M-x display-prefix @print{} 3 + +M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} + +C-u - M-x display-prefix @print{} - + +M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} + +C-u - 7 M-x display-prefix @print{} -7 + +M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} +@end example + + Emacs uses two variables to store the prefix argument: +@code{prefix-arg} and @code{current-prefix-arg}. Commands such as +@code{universal-argument} that set up prefix arguments for other +commands store them in @code{prefix-arg}. In contrast, +@code{current-prefix-arg} conveys the prefix argument to the current +command, so setting it has no effect on the prefix arguments for future +commands. + + Normally, commands specify which representation to use for the prefix +argument, either numeric or raw, in the @code{interactive} specification. +(@xref{Using Interactive}.) Alternatively, functions may look at the +value of the prefix argument directly in the variable +@code{current-prefix-arg}, but this is less clean. + +@defun prefix-numeric-value arg +This function returns the numeric meaning of a valid raw prefix argument +value, @var{arg}. The argument may be a symbol, a number, or a list. +If it is @code{nil}, the value 1 is returned; if it is @code{-}, the +value @minus{}1 is returned; if it is a number, that number is returned; +if it is a list, the @sc{car} of that list (which should be a number) is +returned. +@end defun + +@defvar current-prefix-arg +This variable holds the raw prefix argument for the @emph{current} +command. Commands may examine it directly, but the usual method for +accessing it is with @code{(interactive "P")}. +@end defvar + +@defvar prefix-arg +The value of this variable is the raw prefix argument for the +@emph{next} editing command. Commands such as @code{universal-argument} +that specify prefix arguments for the following command work by setting +this variable. +@end defvar + +@defvar last-prefix-arg +The raw prefix argument value used by the previous command. +@end defvar + + The following commands exist to set up prefix arguments for the +following command. Do not call them for any other reason. + +@deffn Command universal-argument +This command reads input and specifies a prefix argument for the +following command. Don't call this command yourself unless you know +what you are doing. +@end deffn + +@deffn Command digit-argument arg +This command adds to the prefix argument for the following command. The +argument @var{arg} is the raw prefix argument as it was before this +command; it is used to compute the updated prefix argument. Don't call +this command yourself unless you know what you are doing. +@end deffn + +@deffn Command negative-argument arg +This command adds to the numeric argument for the next command. The +argument @var{arg} is the raw prefix argument as it was before this +command; its value is negated to form the new prefix argument. Don't +call this command yourself unless you know what you are doing. +@end deffn + +@node Recursive Editing +@section Recursive Editing +@cindex recursive command loop +@cindex recursive editing level +@cindex command loop, recursive + + The Emacs command loop is entered automatically when Emacs starts up. +This top-level invocation of the command loop never exits; it keeps +running as long as Emacs does. Lisp programs can also invoke the +command loop. Since this makes more than one activation of the command +loop, we call it @dfn{recursive editing}. A recursive editing level has +the effect of suspending whatever command invoked it and permitting the +user to do arbitrary editing before resuming that command. + + The commands available during recursive editing are the same ones +available in the top-level editing loop and defined in the keymaps. +Only a few special commands exit the recursive editing level; the others +return to the recursive editing level when they finish. (The special +commands for exiting are always available, but they do nothing when +recursive editing is not in progress.) + + All command loops, including recursive ones, set up all-purpose error +handlers so that an error in a command run from the command loop will +not exit the loop. + +@cindex minibuffer input + Minibuffer input is a special kind of recursive editing. It has a few +special wrinkles, such as enabling display of the minibuffer and the +minibuffer window, but fewer than you might suppose. Certain keys +behave differently in the minibuffer, but that is only because of the +minibuffer's local map; if you switch windows, you get the usual Emacs +commands. + +@cindex @code{throw} example +@kindex exit +@cindex exit recursive editing +@cindex aborting + To invoke a recursive editing level, call the function +@code{recursive-edit}. This function contains the command loop; it also +contains a call to @code{catch} with tag @code{exit}, which makes it +possible to exit the recursive editing level by throwing to @code{exit} +(@pxref{Catch and Throw}). If you throw a value other than @code{t}, +then @code{recursive-edit} returns normally to the function that called +it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. +Throwing a @code{t} value causes @code{recursive-edit} to quit, so that +control returns to the command loop one level up. This is called +@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). + + Most applications should not use recursive editing, except as part of +using the minibuffer. Usually it is more convenient for the user if you +change the major mode of the current buffer temporarily to a special +major mode, which should have a command to go back to the previous mode. +(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to +give the user different text to edit ``recursively,'' create and select +a new buffer in a special mode. In this mode, define a command to +complete the processing and go back to the previous buffer. (The +@kbd{m} command in Rmail does this.) + + Recursive edits are useful in debugging. You can insert a call to +@code{debug} into a function definition as a sort of breakpoint, so that +you can look around when the function gets there. @code{debug} invokes +a recursive edit but also provides the other features of the debugger. + + Recursive editing levels are also used when you type @kbd{C-r} in +@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). + +@defun recursive-edit +@cindex suspend evaluation +This function invokes the editor command loop. It is called +automatically by the initialization of Emacs, to let the user begin +editing. When called from a Lisp program, it enters a recursive editing +level. + +If the current buffer is not the same as the selected window's buffer, +@code{recursive-edit} saves and restores the current buffer. Otherwise, +if you switch buffers, the buffer you switched to is current after +@code{recursive-edit} returns. + +In the following example, the function @code{simple-rec} first +advances point one word, then enters a recursive edit, printing out a +message in the echo area. The user can then do any editing desired, and +then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. + +@example +(defun simple-rec () + (forward-word 1) + (message "Recursive edit in progress") + (recursive-edit) + (forward-word 1)) + @result{} simple-rec +(simple-rec) + @result{} nil +@end example +@end defun + +@deffn Command exit-recursive-edit +This function exits from the innermost recursive edit (including +minibuffer input). Its definition is effectively @code{(throw 'exit +nil)}. +@end deffn + +@deffn Command abort-recursive-edit +This function aborts the command that requested the innermost recursive +edit (including minibuffer input), by signaling @code{quit} +after exiting the recursive edit. Its definition is effectively +@code{(throw 'exit t)}. @xref{Quitting}. +@end deffn + +@deffn Command top-level +This function exits all recursive editing levels; it does not return a +value, as it jumps completely out of any computation directly back to +the main command loop. +@end deffn + +@defun recursion-depth +This function returns the current depth of recursive edits. When no +recursive edit is active, it returns 0. +@end defun + +@node Disabling Commands +@section Disabling Commands +@cindex disabled command + + @dfn{Disabling a command} marks the command as requiring user +confirmation before it can be executed. Disabling is used for commands +which might be confusing to beginning users, to prevent them from using +the commands by accident. + +@kindex disabled + The low-level mechanism for disabling a command is to put a +non-@code{nil} @code{disabled} property on the Lisp symbol for the +command. These properties are normally set up by the user's +init file (@pxref{Init File}) with Lisp expressions such as this: + +@example +(put 'upcase-region 'disabled t) +@end example + +@noindent +For a few commands, these properties are present by default (you can +remove them in your init file if you wish). + + If the value of the @code{disabled} property is a string, the message +saying the command is disabled includes that string. For example: + +@example +(put 'delete-region 'disabled + "Text deleted this way cannot be yanked back!\n") +@end example + + @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on +what happens when a disabled command is invoked interactively. +Disabling a command has no effect on calling it as a function from Lisp +programs. + +@deffn Command enable-command command +Allow @var{command} (a symbol) to be executed without special +confirmation from now on, and alter the user's init file (@pxref{Init +File}) so that this will apply to future sessions. +@end deffn + +@deffn Command disable-command command +Require special confirmation to execute @var{command} from now on, and +alter the user's init file so that this will apply to future sessions. +@end deffn + +@defvar disabled-command-function +The value of this variable should be a function. When the user +invokes a disabled command interactively, this function is called +instead of the disabled command. It can use @code{this-command-keys} +to determine what the user typed to run the command, and thus find the +command itself. + +The value may also be @code{nil}. Then all commands work normally, +even disabled ones. + +By default, the value is a function that asks the user whether to +proceed. +@end defvar + +@node Command History +@section Command History +@cindex command history +@cindex complex command +@cindex history of commands + + The command loop keeps a history of the complex commands that have +been executed, to make it convenient to repeat these commands. A +@dfn{complex command} is one for which the interactive argument reading +uses the minibuffer. This includes any @kbd{M-x} command, any +@kbd{M-:} command, and any command whose @code{interactive} +specification reads an argument from the minibuffer. Explicit use of +the minibuffer during the execution of the command itself does not cause +the command to be considered complex. + +@defvar command-history +This variable's value is a list of recent complex commands, each +represented as a form to evaluate. It continues to accumulate all +complex commands for the duration of the editing session, but when it +reaches the maximum size (@pxref{Minibuffer History}), the oldest +elements are deleted as new ones are added. + +@example +@group +command-history +@result{} ((switch-to-buffer "chistory.texi") + (describe-key "^X^[") + (visit-tags-table "~/emacs/src/") + (find-tag "repeat-complex-command")) +@end group +@end example +@end defvar + + This history list is actually a special case of minibuffer history +(@pxref{Minibuffer History}), with one special twist: the elements are +expressions rather than strings. + + There are a number of commands devoted to the editing and recall of +previous commands. The commands @code{repeat-complex-command}, and +@code{list-command-history} are described in the user manual +(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the +minibuffer, the usual minibuffer history commands are available. + +@node Keyboard Macros +@section Keyboard Macros +@cindex keyboard macros + + A @dfn{keyboard macro} is a canned sequence of input events that can +be considered a command and made the definition of a key. The Lisp +representation of a keyboard macro is a string or vector containing the +events. Don't confuse keyboard macros with Lisp macros +(@pxref{Macros}). + +@defun execute-kbd-macro kbdmacro &optional count loopfunc +This function executes @var{kbdmacro} as a sequence of events. If +@var{kbdmacro} is a string or vector, then the events in it are executed +exactly as if they had been input by the user. The sequence is +@emph{not} expected to be a single key sequence; normally a keyboard +macro definition consists of several key sequences concatenated. + +If @var{kbdmacro} is a symbol, then its function definition is used in +place of @var{kbdmacro}. If that is another symbol, this process repeats. +Eventually the result should be a string or vector. If the result is +not a symbol, string, or vector, an error is signaled. + +The argument @var{count} is a repeat count; @var{kbdmacro} is executed that +many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is +executed once. If it is 0, @var{kbdmacro} is executed over and over until it +encounters an error or a failing search. + +If @var{loopfunc} is non-@code{nil}, it is a function that is called, +without arguments, prior to each iteration of the macro. If +@var{loopfunc} returns @code{nil}, then this stops execution of the macro. + +@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. +@end defun + +@defvar executing-kbd-macro +This variable contains the string or vector that defines the keyboard +macro that is currently executing. It is @code{nil} if no macro is +currently executing. A command can test this variable so as to behave +differently when run from an executing macro. Do not set this variable +yourself. +@end defvar + +@defvar defining-kbd-macro +This variable is non-@code{nil} if and only if a keyboard macro is +being defined. A command can test this variable so as to behave +differently while a macro is being defined. The value is +@code{append} while appending to the definition of an existing macro. +The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and +@code{end-kbd-macro} set this variable---do not set it yourself. + +The variable is always local to the current terminal and cannot be +buffer-local. @xref{Multiple Displays}. +@end defvar + +@defvar last-kbd-macro +This variable is the definition of the most recently defined keyboard +macro. Its value is a string or vector, or @code{nil}. + +The variable is always local to the current terminal and cannot be +buffer-local. @xref{Multiple Displays}. +@end defvar + +@defvar kbd-macro-termination-hook +This normal hook (@pxref{Standard Hooks}) is run when a keyboard +macro terminates, regardless of what caused it to terminate (reaching +the macro end or an error which ended the macro prematurely). +@end defvar + +@ignore + arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1 +@end ignore diff --cc doc/lispref/display.texi index 90d94dbe6b3,00000000000..4c9df9c5ede mode 100644,000000..100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@@ -1,5456 -1,0 +1,5473 @@@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/display +@node Display, System Interface, Processes, Top +@chapter Emacs Display + + This chapter describes a number of features related to the display +that Emacs presents to the user. + +@menu +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* Forcing Redisplay:: Forcing redisplay. +* Truncation:: Folding or wrapping long text lines. +* The Echo Area:: Displaying messages at the bottom of the screen. +* Warnings:: Displaying warning messages for the user. +* Invisible Text:: Hiding part of the buffer text. +* Selective Display:: Hiding part of the buffer text (the old way). +* Temporary Displays:: Displays that go away automatically. +* Overlays:: Use overlays to highlight parts of the buffer. +* Width:: How wide a character or string is on the screen. +* Line Height:: Controlling the height of lines. +* Faces:: A face defines a graphics style for text characters: + font, colors, etc. +* Fringes:: Controlling window fringes. +* Scroll Bars:: Controlling vertical scroll bars. +* Display Property:: Enabling special display features. +* Images:: Displaying images in Emacs buffers. +* Buttons:: Adding clickable buttons to Emacs buffers. +* Abstract Display:: Emacs' Widget for Object Collections. +* Blinking:: How Emacs shows the matching open parenthesis. +* Usual Display:: The usual conventions for displaying nonprinting chars. +* Display Tables:: How to specify other conventions. +* Beeping:: Audible signal to the user. +* Window Systems:: Which window system is being used. +@end menu + +@node Refresh Screen +@section Refreshing the Screen + + The function @code{redraw-frame} clears and redisplays the entire +contents of a given frame (@pxref{Frames}). This is useful if the +screen is corrupted. + +@c Emacs 19 feature +@defun redraw-frame frame +This function clears and redisplays frame @var{frame}. +@end defun + + Even more powerful is @code{redraw-display}: + +@deffn Command redraw-display +This function clears and redisplays all visible frames. +@end deffn + + This function calls for redisplay of certain windows, the next time +redisplay is done, but does not clear them first. + +@defun force-window-update &optional object +This function forces some or all windows to be updated on next redisplay. +If @var{object} is a window, it forces redisplay of that window. If +@var{object} is a buffer or buffer name, it forces redisplay of all +windows displaying that buffer. If @var{object} is @code{nil} (or +omitted), it forces redisplay of all windows. +@end defun + + Processing user input takes absolute priority over redisplay. If you +call these functions when input is available, they do nothing +immediately, but a full redisplay does happen eventually---after all the +input has been processed. + + Normally, suspending and resuming Emacs also refreshes the screen. +Some terminal emulators record separate contents for display-oriented +programs such as Emacs and for ordinary sequential display. If you are +using such a terminal, you might want to inhibit the redisplay on +resumption. + +@defvar no-redraw-on-reenter +@cindex suspend (cf. @code{no-redraw-on-reenter}) +@cindex resume (cf. @code{no-redraw-on-reenter}) +This variable controls whether Emacs redraws the entire screen after it +has been suspended and resumed. Non-@code{nil} means there is no need +to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. +@end defvar + +@node Forcing Redisplay +@section Forcing Redisplay +@cindex forcing redisplay + + Emacs redisplay normally stops if input arrives, and does not happen +at all if input is available before it starts. Most of the time, this +is exactly what you want. However, you can prevent preemption by +binding @code{redisplay-dont-pause} to a non-@code{nil} value. + +@defvar redisplay-preemption-period +This variable specifies how many seconds Emacs waits between checks +for new input during redisplay. (The default is 0.1 seconds.) If +input has arrived when Emacs checks, it pre-empts redisplay and +processes the available input before trying again to redisplay. + +If this variable is @code{nil}, Emacs does not check for input during +redisplay, and redisplay cannot be preempted by input. + +This variable is only obeyed on graphical terminals. For +text terminals, see @ref{Terminal Output}. +@end defvar + +@defvar redisplay-dont-pause +If this variable is non-@code{nil}, pending input does not +prevent or halt redisplay; redisplay occurs, and finishes, +regardless of whether input is available. +@end defvar + +@defun redisplay &optional force +This function performs an immediate redisplay provided there are no +pending input events. This is equivalent to @code{(sit-for 0)}. + +If the optional argument @var{force} is non-@code{nil}, it forces an +immediate and complete redisplay even if input is available. + +Returns @code{t} if redisplay was performed, or @code{nil} otherwise. +@end defun + +@node Truncation +@section Truncation +@cindex line wrapping +@cindex line truncation +@cindex continuation lines +@cindex @samp{$} in display +@cindex @samp{\} in display + + When a line of text extends beyond the right edge of a window, Emacs +can @dfn{continue} the line (make it ``wrap'' to the next screen +line), or @dfn{truncate} the line (limit it to one screen line). The +additional screen lines used to display a long text line are called +@dfn{continuation} lines. Continuation is not the same as filling; +continuation happens on the screen only, not in the buffer contents, +and it breaks a line precisely at the right margin, not at a word +boundary. @xref{Filling}. + + On a graphical display, tiny arrow images in the window fringes +indicate truncated and continued lines (@pxref{Fringes}). On a text +terminal, a @samp{$} in the rightmost column of the window indicates +truncation; a @samp{\} on the rightmost column indicates a line that +``wraps.'' (The display table can specify alternate characters to use +for this; @pxref{Display Tables}). + +@defopt truncate-lines +This buffer-local variable controls how Emacs displays lines that extend +beyond the right edge of the window. The default is @code{nil}, which +specifies continuation. If the value is non-@code{nil}, then these +lines are truncated. + +If the variable @code{truncate-partial-width-windows} is non-@code{nil}, +then truncation is always used for side-by-side windows (within one +frame) regardless of the value of @code{truncate-lines}. +@end defopt + +@defopt default-truncate-lines +This variable is the default value for @code{truncate-lines}, for +buffers that do not have buffer-local values for it. +@end defopt + +@defopt truncate-partial-width-windows +This variable controls display of lines that extend beyond the right +edge of the window, in side-by-side windows (@pxref{Splitting Windows}). +If it is non-@code{nil}, these lines are truncated; otherwise, +@code{truncate-lines} says what to do with them. +@end defopt + + When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in +a window, that forces truncation. + + If your buffer contains @emph{very} long lines, and you use +continuation to display them, just thinking about them can make Emacs +redisplay slow. The column computation and indentation functions also +become slow. Then you might find it advisable to set +@code{cache-long-line-scans} to @code{t}. + +@defvar cache-long-line-scans +If this variable is non-@code{nil}, various indentation and motion +functions, and Emacs redisplay, cache the results of scanning the +buffer, and consult the cache to avoid rescanning regions of the buffer +unless they are modified. + +Turning on the cache slows down processing of short lines somewhat. + +This variable is automatically buffer-local in every buffer. +@end defvar + +@node The Echo Area +@section The Echo Area +@cindex error display +@cindex echo area + + The @dfn{echo area} is used for displaying error messages +(@pxref{Errors}), for messages made with the @code{message} primitive, +and for echoing keystrokes. It is not the same as the minibuffer, +despite the fact that the minibuffer appears (when active) in the same +place on the screen as the echo area. The @cite{GNU Emacs Manual} +specifies the rules for resolving conflicts between the echo area and +the minibuffer for use of that screen space (@pxref{Minibuffer,, The +Minibuffer, emacs, The GNU Emacs Manual}). + + You can write output in the echo area by using the Lisp printing +functions with @code{t} as the stream (@pxref{Output Functions}), or +explicitly. + +@menu +* Displaying Messages:: Explicitly displaying text in the echo area. +* Progress:: Informing user about progress of a long operation. +* Logging Messages:: Echo area messages are logged for the user. +* Echo Area Customization:: Controlling the echo area. +@end menu + +@node Displaying Messages +@subsection Displaying Messages in the Echo Area +@cindex display message in echo area + + This section describes the functions for explicitly producing echo +area messages. Many other Emacs features display messages there, too. + +@defun message format-string &rest arguments +This function displays a message in the echo area. The argument +@var{format-string} is similar to a C language @code{printf} format +string. See @code{format} in @ref{Formatting Strings}, for the details +on the conversion specifications. @code{message} returns the +constructed string. + +In batch mode, @code{message} prints the message text on the standard +error stream, followed by a newline. + +If @var{format-string}, or strings among the @var{arguments}, have +@code{face} text properties, these affect the way the message is displayed. + +@c Emacs 19 feature +If @var{format-string} is @code{nil} or the empty string, +@code{message} clears the echo area; if the echo area has been +expanded automatically, this brings it back to its normal size. +If the minibuffer is active, this brings the minibuffer contents back +onto the screen immediately. + +@example +@group +(message "Minibuffer depth is %d." + (minibuffer-depth)) + @print{} Minibuffer depth is 0. +@result{} "Minibuffer depth is 0." +@end group + +@group +---------- Echo Area ---------- +Minibuffer depth is 0. +---------- Echo Area ---------- +@end group +@end example + +To automatically display a message in the echo area or in a pop-buffer, +depending on its size, use @code{display-message-or-buffer} (see below). +@end defun + +@defmac with-temp-message message &rest body +This construct displays a message in the echo area temporarily, during +the execution of @var{body}. It displays @var{message}, executes +@var{body}, then returns the value of the last body form while restoring +the previous echo area contents. +@end defmac + +@defun message-or-box format-string &rest arguments +This function displays a message like @code{message}, but may display it +in a dialog box instead of the echo area. If this function is called in +a command that was invoked using the mouse---more precisely, if +@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either +@code{nil} or a list---then it uses a dialog box or pop-up menu to +display the message. Otherwise, it uses the echo area. (This is the +same criterion that @code{y-or-n-p} uses to make a similar decision; see +@ref{Yes-or-No Queries}.) + +You can force use of the mouse or of the echo area by binding +@code{last-nonmenu-event} to a suitable value around the call. +@end defun + +@defun message-box format-string &rest arguments +@anchor{message-box} +This function displays a message like @code{message}, but uses a dialog +box (or a pop-up menu) whenever that is possible. If it is impossible +to use a dialog box or pop-up menu, because the terminal does not +support them, then @code{message-box} uses the echo area, like +@code{message}. +@end defun + +@defun display-message-or-buffer message &optional buffer-name not-this-window frame +This function displays the message @var{message}, which may be either a +string or a buffer. If it is shorter than the maximum height of the +echo area, as defined by @code{max-mini-window-height}, it is displayed +in the echo area, using @code{message}. Otherwise, +@code{display-buffer} is used to show it in a pop-up buffer. + +Returns either the string shown in the echo area, or when a pop-up +buffer is used, the window used to display it. + +If @var{message} is a string, then the optional argument +@var{buffer-name} is the name of the buffer used to display it when a +pop-up buffer is used, defaulting to @samp{*Message*}. In the case +where @var{message} is a string and displayed in the echo area, it is +not specified whether the contents are inserted into the buffer anyway. + +The optional arguments @var{not-this-window} and @var{frame} are as for +@code{display-buffer}, and only used if a buffer is displayed. +@end defun + +@defun current-message +This function returns the message currently being displayed in the +echo area, or @code{nil} if there is none. +@end defun + +@node Progress +@subsection Reporting Operation Progress +@cindex progress reporting + + When an operation can take a while to finish, you should inform the +user about the progress it makes. This way the user can estimate +remaining time and clearly see that Emacs is busy working, not hung. + + Functions listed in this section provide simple and efficient way of +reporting operation progress. Here is a working example that does +nothing useful: + +@smallexample +(let ((progress-reporter + (make-progress-reporter "Collecting mana for Emacs..." + 0 500))) + (dotimes (k 500) + (sit-for 0.01) + (progress-reporter-update progress-reporter k)) + (progress-reporter-done progress-reporter)) +@end smallexample + +@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time +This function creates and returns a @dfn{progress reporter}---an +object you will use as an argument for all other functions listed +here. The idea is to precompute as much data as possible to make +progress reporting very fast. + +When this progress reporter is subsequently used, it will display +@var{message} in the echo area, followed by progress percentage. +@var{message} is treated as a simple string. If you need it to depend +on a filename, for instance, use @code{format} before calling this +function. + +@var{min-value} and @var{max-value} arguments stand for starting and +final states of your operation. For instance, if you scan a buffer, +they should be the results of @code{point-min} and @code{point-max} +correspondingly. It is required that @var{max-value} is greater than +@var{min-value}. If you create progress reporter when some part of +the operation has already been completed, then specify +@var{current-value} argument. But normally you should omit it or set +it to @code{nil}---it will default to @var{min-value} then. + +Remaining arguments control the rate of echo area updates. Progress +reporter will wait for at least @var{min-change} more percents of the +operation to be completed before printing next message. +@var{min-time} specifies the minimum time in seconds to pass between +successive prints. It can be fractional. Depending on Emacs and +system capabilities, progress reporter may or may not respect this +last argument or do it with varying precision. Default value for +@var{min-change} is 1 (one percent), for @var{min-time}---0.2 +(seconds.) + +This function calls @code{progress-reporter-update}, so the first +message is printed immediately. +@end defun + +@defun progress-reporter-update reporter value +This function does the main work of reporting progress of your +operation. It displays the message of @var{reporter}, followed by +progress percentage determined by @var{value}. If percentage is zero, +or close enough according to the @var{min-change} and @var{min-time} +arguments, then it is omitted from the output. + +@var{reporter} must be the result of a call to +@code{make-progress-reporter}. @var{value} specifies the current +state of your operation and must be between @var{min-value} and +@var{max-value} (inclusive) as passed to +@code{make-progress-reporter}. For instance, if you scan a buffer, +then @var{value} should be the result of a call to @code{point}. + +This function respects @var{min-change} and @var{min-time} as passed +to @code{make-progress-reporter} and so does not output new messages +on every invocation. It is thus very fast and normally you should not +try to reduce the number of calls to it: resulting overhead will most +likely negate your effort. +@end defun + +@defun progress-reporter-force-update reporter value &optional new-message +This function is similar to @code{progress-reporter-update} except +that it prints a message in the echo area unconditionally. + +The first two arguments have the same meaning as for +@code{progress-reporter-update}. Optional @var{new-message} allows +you to change the message of the @var{reporter}. Since this functions +always updates the echo area, such a change will be immediately +presented to the user. +@end defun + +@defun progress-reporter-done reporter +This function should be called when the operation is finished. It +prints the message of @var{reporter} followed by word ``done'' in the +echo area. + +You should always call this function and not hope for +@code{progress-reporter-update} to print ``100%.'' Firstly, it may +never print it, there are many good reasons for this not to happen. +Secondly, ``done'' is more explicit. +@end defun + +@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} +This is a convenience macro that works the same way as @code{dotimes} +does, but also reports loop progress using the functions described +above. It allows you to save some typing. + +You can rewrite the example in the beginning of this node using +this macro this way: + +@example +(dotimes-with-progress-reporter + (k 500) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +@end example +@end defmac + +@node Logging Messages +@subsection Logging Messages in @samp{*Messages*} +@cindex logging echo-area messages + + Almost all the messages displayed in the echo area are also recorded +in the @samp{*Messages*} buffer so that the user can refer back to +them. This includes all the messages that are output with +@code{message}. + +@defopt message-log-max +This variable specifies how many lines to keep in the @samp{*Messages*} +buffer. The value @code{t} means there is no limit on how many lines to +keep. The value @code{nil} disables message logging entirely. Here's +how to display a message and prevent it from being logged: + +@example +(let (message-log-max) + (message @dots{})) +@end example +@end defopt + + To make @samp{*Messages*} more convenient for the user, the logging +facility combines successive identical messages. It also combines +successive related messages for the sake of two cases: question +followed by answer, and a series of progress messages. + + A ``question followed by an answer'' means two messages like the +ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, +and the second is @samp{@var{question}...@var{answer}}. The first +message conveys no additional information beyond what's in the second, +so logging the second message discards the first from the log. + + A ``series of progress messages'' means successive messages like +those produced by @code{make-progress-reporter}. They have the form +@samp{@var{base}...@var{how-far}}, where @var{base} is the same each +time, while @var{how-far} varies. Logging each message in the series +discards the previous one, provided they are consecutive. + + The functions @code{make-progress-reporter} and @code{y-or-n-p} +don't have to do anything special to activate the message log +combination feature. It operates whenever two consecutive messages +are logged that share a common prefix ending in @samp{...}. + +@node Echo Area Customization +@subsection Echo Area Customization + + These variables control details of how the echo area works. + +@defvar cursor-in-echo-area +This variable controls where the cursor appears when a message is +displayed in the echo area. If it is non-@code{nil}, then the cursor +appears at the end of the message. Otherwise, the cursor appears at +point---not in the echo area at all. + +The value is normally @code{nil}; Lisp programs bind it to @code{t} +for brief periods of time. +@end defvar + +@defvar echo-area-clear-hook +This normal hook is run whenever the echo area is cleared---either by +@code{(message nil)} or for any other reason. +@end defvar + +@defvar echo-keystrokes +This variable determines how much time should elapse before command +characters echo. Its value must be an integer or floating point number, +which specifies the +number of seconds to wait before echoing. If the user types a prefix +key (such as @kbd{C-x}) and then delays this many seconds before +continuing, the prefix key is echoed in the echo area. (Once echoing +begins in a key sequence, all subsequent characters in the same key +sequence are echoed immediately.) + +If the value is zero, then command input is not echoed. +@end defvar + +@defvar message-truncate-lines +Normally, displaying a long message resizes the echo area to display +the entire message. But if the variable @code{message-truncate-lines} +is non-@code{nil}, the echo area does not resize, and the message is +truncated to fit it, as in Emacs 20 and before. +@end defvar + + The variable @code{max-mini-window-height}, which specifies the +maximum height for resizing minibuffer windows, also applies to the +echo area (which is really a special use of the minibuffer window. +@xref{Minibuffer Misc}. + +@node Warnings +@section Reporting Warnings +@cindex warnings + + @dfn{Warnings} are a facility for a program to inform the user of a +possible problem, but continue running. + +@menu +* Warning Basics:: Warnings concepts and functions to report them. +* Warning Variables:: Variables programs bind to customize their warnings. +* Warning Options:: Variables users set to control display of warnings. +@end menu + +@node Warning Basics +@subsection Warning Basics +@cindex severity level + + Every warning has a textual message, which explains the problem for +the user, and a @dfn{severity level} which is a symbol. Here are the +possible severity levels, in order of decreasing severity, and their +meanings: + +@table @code +@item :emergency +A problem that will seriously impair Emacs operation soon +if you do not attend to it promptly. +@item :error +A report of data or circumstances that are inherently wrong. +@item :warning +A report of data or circumstances that are not inherently wrong, but +raise suspicion of a possible problem. +@item :debug +A report of information that may be useful if you are debugging. +@end table + + When your program encounters invalid input data, it can either +signal a Lisp error by calling @code{error} or @code{signal} or report +a warning with severity @code{:error}. Signaling a Lisp error is the +easiest thing to do, but it means the program cannot continue +processing. If you want to take the trouble to implement a way to +continue processing despite the bad data, then reporting a warning of +severity @code{:error} is the right way to inform the user of the +problem. For instance, the Emacs Lisp byte compiler can report an +error that way and continue compiling other functions. (If the +program signals a Lisp error and then handles it with +@code{condition-case}, the user won't see the error message; it could +show the message to the user by reporting it as a warning.) + +@cindex warning type + Each warning has a @dfn{warning type} to classify it. The type is a +list of symbols. The first symbol should be the custom group that you +use for the program's user options. For example, byte compiler +warnings use the warning type @code{(bytecomp)}. You can also +subcategorize the warnings, if you wish, by using more symbols in the +list. + +@defun display-warning type message &optional level buffer-name +This function reports a warning, using @var{message} as the message +and @var{type} as the warning type. @var{level} should be the +severity level, with @code{:warning} being the default. + +@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer +for logging the warning. By default, it is @samp{*Warnings*}. +@end defun + +@defun lwarn type level message &rest args +This function reports a warning using the value of @code{(format +@var{message} @var{args}...)} as the message. In other respects it is +equivalent to @code{display-warning}. +@end defun + +@defun warn message &rest args +This function reports a warning using the value of @code{(format +@var{message} @var{args}...)} as the message, @code{(emacs)} as the +type, and @code{:warning} as the severity level. It exists for +compatibility only; we recommend not using it, because you should +specify a specific warning type. +@end defun + +@node Warning Variables +@subsection Warning Variables + + Programs can customize how their warnings appear by binding +the variables described in this section. + +@defvar warning-levels +This list defines the meaning and severity order of the warning +severity levels. Each element defines one severity level, +and they are arranged in order of decreasing severity. + +Each element has the form @code{(@var{level} @var{string} +@var{function})}, where @var{level} is the severity level it defines. +@var{string} specifies the textual description of this level. +@var{string} should use @samp{%s} to specify where to put the warning +type information, or it can omit the @samp{%s} so as not to include +that information. + +The optional @var{function}, if non-@code{nil}, is a function to call +with no arguments, to get the user's attention. + +Normally you should not change the value of this variable. +@end defvar + +@defvar warning-prefix-function +If non-@code{nil}, the value is a function to generate prefix text for +warnings. Programs can bind the variable to a suitable function. +@code{display-warning} calls this function with the warnings buffer +current, and the function can insert text in it. That text becomes +the beginning of the warning message. + +The function is called with two arguments, the severity level and its +entry in @code{warning-levels}. It should return a list to use as the +entry (this value need not be an actual member of +@code{warning-levels}). By constructing this value, the function can +change the severity of the warning, or specify different handling for +a given severity level. + +If the variable's value is @code{nil} then there is no function +to call. +@end defvar + +@defvar warning-series +Programs can bind this variable to @code{t} to say that the next +warning should begin a series. When several warnings form a series, +that means to leave point on the first warning of the series, rather +than keep moving it for each warning so that it appears on the last one. +The series ends when the local binding is unbound and +@code{warning-series} becomes @code{nil} again. + +The value can also be a symbol with a function definition. That is +equivalent to @code{t}, except that the next warning will also call +the function with no arguments with the warnings buffer current. The +function can insert text which will serve as a header for the series +of warnings. + +Once a series has begun, the value is a marker which points to the +buffer position in the warnings buffer of the start of the series. + +The variable's normal value is @code{nil}, which means to handle +each warning separately. +@end defvar + +@defvar warning-fill-prefix +When this variable is non-@code{nil}, it specifies a fill prefix to +use for filling each warning's text. +@end defvar + +@defvar warning-type-format +This variable specifies the format for displaying the warning type +in the warning message. The result of formatting the type this way +gets included in the message under the control of the string in the +entry in @code{warning-levels}. The default value is @code{" (%s)"}. +If you bind it to @code{""} then the warning type won't appear at +all. +@end defvar + +@node Warning Options +@subsection Warning Options + + These variables are used by users to control what happens +when a Lisp program reports a warning. + +@defopt warning-minimum-level +This user option specifies the minimum severity level that should be +shown immediately to the user. The default is @code{:warning}, which +means to immediately display all warnings except @code{:debug} +warnings. +@end defopt + +@defopt warning-minimum-log-level +This user option specifies the minimum severity level that should be +logged in the warnings buffer. The default is @code{:warning}, which +means to log all warnings except @code{:debug} warnings. +@end defopt + +@defopt warning-suppress-types +This list specifies which warning types should not be displayed +immediately for the user. Each element of the list should be a list +of symbols. If its elements match the first elements in a warning +type, then that warning is not displayed immediately. +@end defopt + +@defopt warning-suppress-log-types +This list specifies which warning types should not be logged in the +warnings buffer. Each element of the list should be a list of +symbols. If it matches the first few elements in a warning type, then +that warning is not logged. +@end defopt + +@node Invisible Text +@section Invisible Text + +@cindex invisible text +You can make characters @dfn{invisible}, so that they do not appear on +the screen, with the @code{invisible} property. This can be either a +text property (@pxref{Text Properties}) or a property of an overlay +(@pxref{Overlays}). Cursor motion also partly ignores these +characters; if the command loop finds point within them, it moves +point to the other side of them. + +In the simplest case, any non-@code{nil} @code{invisible} property makes +a character invisible. This is the default case---if you don't alter +the default value of @code{buffer-invisibility-spec}, this is how the +@code{invisible} property works. You should normally use @code{t} +as the value of the @code{invisible} property if you don't plan +to set @code{buffer-invisibility-spec} yourself. + +More generally, you can use the variable @code{buffer-invisibility-spec} +to control which values of the @code{invisible} property make text +invisible. This permits you to classify the text into different subsets +in advance, by giving them different @code{invisible} values, and +subsequently make various subsets visible or invisible by changing the +value of @code{buffer-invisibility-spec}. + +Controlling visibility with @code{buffer-invisibility-spec} is +especially useful in a program to display the list of entries in a +database. It permits the implementation of convenient filtering +commands to view just a part of the entries in the database. Setting +this variable is very fast, much faster than scanning all the text in +the buffer looking for properties to change. + +@defvar buffer-invisibility-spec +This variable specifies which kinds of @code{invisible} properties +actually make a character invisible. Setting this variable makes it +buffer-local. + +@table @asis +@item @code{t} +A character is invisible if its @code{invisible} property is +non-@code{nil}. This is the default. + +@item a list +Each element of the list specifies a criterion for invisibility; if a +character's @code{invisible} property fits any one of these criteria, +the character is invisible. The list can have two kinds of elements: + +@table @code +@item @var{atom} +A character is invisible if its @code{invisible} property value +is @var{atom} or if it is a list with @var{atom} as a member. + +@item (@var{atom} . t) +A character is invisible if its @code{invisible} property value is +@var{atom} or if it is a list with @var{atom} as a member. Moreover, +a sequence of such characters displays as an ellipsis. +@end table +@end table +@end defvar + + Two functions are specifically provided for adding elements to +@code{buffer-invisibility-spec} and removing elements from it. + +@defun add-to-invisibility-spec element +This function adds the element @var{element} to +@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} +was @code{t}, it changes to a list, @code{(t)}, so that text whose +@code{invisible} property is @code{t} remains invisible. +@end defun + +@defun remove-from-invisibility-spec element +This removes the element @var{element} from +@code{buffer-invisibility-spec}. This does nothing if @var{element} +is not in the list. +@end defun + + A convention for use of @code{buffer-invisibility-spec} is that a +major mode should use the mode's own name as an element of +@code{buffer-invisibility-spec} and as the value of the +@code{invisible} property: + +@example +;; @r{If you want to display an ellipsis:} +(add-to-invisibility-spec '(my-symbol . t)) +;; @r{If you don't want ellipsis:} +(add-to-invisibility-spec 'my-symbol) + +(overlay-put (make-overlay beginning end) + 'invisible 'my-symbol) + +;; @r{When done with the overlays:} +(remove-from-invisibility-spec '(my-symbol . t)) +;; @r{Or respectively:} +(remove-from-invisibility-spec 'my-symbol) +@end example + +@vindex line-move-ignore-invisible + Ordinarily, functions that operate on text or move point do not care +whether the text is invisible. The user-level line motion commands +explicitly ignore invisible newlines if +@code{line-move-ignore-invisible} is non-@code{nil} (the default), but +only because they are explicitly programmed to do so. + + However, if a command ends with point inside or immediately before +invisible text, the main editing loop moves point further forward or +further backward (in the same direction that the command already moved +it) until that condition is no longer true. Thus, if the command +moved point back into an invisible range, Emacs moves point back to +the beginning of that range, and then back one more character. If the +command moved point forward into an invisible range, Emacs moves point +forward up to the first visible character that follows the invisible +text. + + Incremental search can make invisible overlays visible temporarily +and/or permanently when a match includes invisible text. To enable +this, the overlay should have a non-@code{nil} +@code{isearch-open-invisible} property. The property value should be a +function to be called with the overlay as an argument. This function +should make the overlay visible permanently; it is used when the match +overlaps the overlay on exit from the search. + + During the search, such overlays are made temporarily visible by +temporarily modifying their invisible and intangible properties. If you +want this to be done differently for a certain overlay, give it an +@code{isearch-open-invisible-temporary} property which is a function. +The function is called with two arguments: the first is the overlay, and +the second is @code{nil} to make the overlay visible, or @code{t} to +make it invisible again. + +@node Selective Display +@section Selective Display +@c @cindex selective display Duplicates selective-display + + @dfn{Selective display} refers to a pair of related features for +hiding certain lines on the screen. + + The first variant, explicit selective display, is designed for use +in a Lisp program: it controls which lines are hidden by altering the +text. This kind of hiding in some ways resembles the effect of the +@code{invisible} property (@pxref{Invisible Text}), but the two +features are different and do not work the same way. + + In the second variant, the choice of lines to hide is made +automatically based on indentation. This variant is designed to be a +user-level feature. + + The way you control explicit selective display is by replacing a +newline (control-j) with a carriage return (control-m). The text that +was formerly a line following that newline is now hidden. Strictly +speaking, it is temporarily no longer a line at all, since only +newlines can separate lines; it is now part of the previous line. + + Selective display does not directly affect editing commands. For +example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly +into hidden text. However, the replacement of newline characters with +carriage return characters affects some editing commands. For +example, @code{next-line} skips hidden lines, since it searches only +for newlines. Modes that use selective display can also define +commands that take account of the newlines, or that control which +parts of the text are hidden. + + When you write a selectively displayed buffer into a file, all the +control-m's are output as newlines. This means that when you next read +in the file, it looks OK, with nothing hidden. The selective display +effect is seen only within Emacs. + +@defvar selective-display +This buffer-local variable enables selective display. This means that +lines, or portions of lines, may be made hidden. + +@itemize @bullet +@item +If the value of @code{selective-display} is @code{t}, then the character +control-m marks the start of hidden text; the control-m, and the rest +of the line following it, are not displayed. This is explicit selective +display. + +@item +If the value of @code{selective-display} is a positive integer, then +lines that start with more than that many columns of indentation are not +displayed. +@end itemize + +When some portion of a buffer is hidden, the vertical movement +commands operate as if that portion did not exist, allowing a single +@code{next-line} command to skip any number of hidden lines. +However, character movement commands (such as @code{forward-char}) do +not skip the hidden portion, and it is possible (if tricky) to insert +or delete text in an hidden portion. + +In the examples below, we show the @emph{display appearance} of the +buffer @code{foo}, which changes with the value of +@code{selective-display}. The @emph{contents} of the buffer do not +change. + +@example +@group +(setq selective-display nil) + @result{} nil + +---------- Buffer: foo ---------- +1 on this column + 2on this column + 3n this column + 3n this column + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group + +@group +(setq selective-display 2) + @result{} 2 + +---------- Buffer: foo ---------- +1 on this column + 2on this column + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group +@end example +@end defvar + +@defvar selective-display-ellipses +If this buffer-local variable is non-@code{nil}, then Emacs displays +@samp{@dots{}} at the end of a line that is followed by hidden text. +This example is a continuation of the previous one. + +@example +@group +(setq selective-display-ellipses t) + @result{} t + +---------- Buffer: foo ---------- +1 on this column + 2on this column ... + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group +@end example + +You can use a display table to substitute other text for the ellipsis +(@samp{@dots{}}). @xref{Display Tables}. +@end defvar + +@node Temporary Displays +@section Temporary Displays + + Temporary displays are used by Lisp programs to put output into a +buffer and then present it to the user for perusal rather than for +editing. Many help commands use this feature. + +@defspec with-output-to-temp-buffer buffer-name forms@dots{} +This function executes @var{forms} while arranging to insert any output +they print into the buffer named @var{buffer-name}, which is first +created if necessary, and put into Help mode. Finally, the buffer is +displayed in some window, but not selected. + +If the @var{forms} do not change the major mode in the output buffer, +so that it is still Help mode at the end of their execution, then +@code{with-output-to-temp-buffer} makes this buffer read-only at the +end, and also scans it for function and variable names to make them +into clickable cross-references. @xref{Docstring hyperlinks, , Tips +for Documentation Strings}, in particular the item on hyperlinks in +documentation strings, for more details. + +The string @var{buffer-name} specifies the temporary buffer, which +need not already exist. The argument must be a string, not a buffer. +The buffer is erased initially (with no questions asked), and it is +marked as unmodified after @code{with-output-to-temp-buffer} exits. + +@code{with-output-to-temp-buffer} binds @code{standard-output} to the +temporary buffer, then it evaluates the forms in @var{forms}. Output +using the Lisp output functions within @var{forms} goes by default to +that buffer (but screen display and messages in the echo area, although +they are ``output'' in the general sense of the word, are not affected). +@xref{Output Functions}. + +Several hooks are available for customizing the behavior +of this construct; they are listed below. + +The value of the last form in @var{forms} is returned. + +@example +@group +---------- Buffer: foo ---------- + This is the contents of foo. +---------- Buffer: foo ---------- +@end group + +@group +(with-output-to-temp-buffer "foo" + (print 20) + (print standard-output)) +@result{} # + +---------- Buffer: foo ---------- +20 + +# + +---------- Buffer: foo ---------- +@end group +@end example +@end defspec + +@defvar temp-buffer-show-function +If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} +calls it as a function to do the job of displaying a help buffer. The +function gets one argument, which is the buffer it should display. + +It is a good idea for this function to run @code{temp-buffer-show-hook} +just as @code{with-output-to-temp-buffer} normally would, inside of +@code{save-selected-window} and with the chosen window and buffer +selected. +@end defvar + +@defvar temp-buffer-setup-hook +This normal hook is run by @code{with-output-to-temp-buffer} before +evaluating @var{body}. When the hook runs, the temporary buffer is +current. This hook is normally set up with a function to put the +buffer in Help mode. +@end defvar + +@defvar temp-buffer-show-hook +This normal hook is run by @code{with-output-to-temp-buffer} after +displaying the temporary buffer. When the hook runs, the temporary buffer +is current, and the window it was displayed in is selected. This hook +is normally set up with a function to make the buffer read only, and +find function names and variable names in it, provided the major mode +is Help mode. +@end defvar + +@defun momentary-string-display string position &optional char message +This function momentarily displays @var{string} in the current buffer at +@var{position}. It has no effect on the undo list or on the buffer's +modification status. + +The momentary display remains until the next input event. If the next +input event is @var{char}, @code{momentary-string-display} ignores it +and returns. Otherwise, that event remains buffered for subsequent use +as input. Thus, typing @var{char} will simply remove the string from +the display, while typing (say) @kbd{C-f} will remove the string from +the display and later (presumably) move point forward. The argument +@var{char} is a space by default. + +The return value of @code{momentary-string-display} is not meaningful. + +If the string @var{string} does not contain control characters, you can +do the same job in a more general way by creating (and then subsequently +deleting) an overlay with a @code{before-string} property. +@xref{Overlay Properties}. + +If @var{message} is non-@code{nil}, it is displayed in the echo area +while @var{string} is displayed in the buffer. If it is @code{nil}, a +default message says to type @var{char} to continue. + +In this example, point is initially located at the beginning of the +second line: + +@example +@group +---------- Buffer: foo ---------- +This is the contents of foo. +@point{}Second line. +---------- Buffer: foo ---------- +@end group + +@group +(momentary-string-display + "**** Important Message! ****" + (point) ?\r + "Type RET when done reading") +@result{} t +@end group + +@group +---------- Buffer: foo ---------- +This is the contents of foo. +**** Important Message! ****Second line. +---------- Buffer: foo ---------- + +---------- Echo Area ---------- +Type RET when done reading +---------- Echo Area ---------- +@end group +@end example +@end defun + +@node Overlays +@section Overlays +@cindex overlays + +You can use @dfn{overlays} to alter the appearance of a buffer's text on +the screen, for the sake of presentation features. An overlay is an +object that belongs to a particular buffer, and has a specified +beginning and end. It also has properties that you can examine and set; +these affect the display of the text within the overlay. + +An overlay uses markers to record its beginning and end; thus, +editing the text of the buffer adjusts the beginning and end of each +overlay so that it stays with the text. When you create the overlay, +you can specify whether text inserted at the beginning should be +inside the overlay or outside, and likewise for the end of the overlay. + +@menu +* Managing Overlays:: Creating and moving overlays. +* Overlay Properties:: How to read and set properties. + What properties do to the screen display. +* Finding Overlays:: Searching for overlays. +@end menu + +@node Managing Overlays +@subsection Managing Overlays + + This section describes the functions to create, delete and move +overlays, and to examine their contents. Overlay changes are not +recorded in the buffer's undo list, since the overlays are not +part of the buffer's contents. + +@defun overlayp object +This function returns @code{t} if @var{object} is an overlay. +@end defun + +@defun make-overlay start end &optional buffer front-advance rear-advance +This function creates and returns an overlay that belongs to +@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} +and @var{end} must specify buffer positions; they may be integers or +markers. If @var{buffer} is omitted, the overlay is created in the +current buffer. + +The arguments @var{front-advance} and @var{rear-advance} specify the +marker insertion type for the start of the overlay and for the end of +the overlay, respectively. @xref{Marker Insertion Types}. If they +are both @code{nil}, the default, then the overlay extends to include +any text inserted at the beginning, but not text inserted at the end. +If @var{front-advance} is non-@code{nil}, text inserted at the +beginning of the overlay is excluded from the overlay. If +@var{rear-advance} is non-@code{nil}, text inserted at the end of the +overlay is included in the overlay. +@end defun + +@defun overlay-start overlay +This function returns the position at which @var{overlay} starts, +as an integer. +@end defun + +@defun overlay-end overlay +This function returns the position at which @var{overlay} ends, +as an integer. +@end defun + +@defun overlay-buffer overlay +This function returns the buffer that @var{overlay} belongs to. It +returns @code{nil} if @var{overlay} has been deleted. +@end defun + +@defun delete-overlay overlay +This function deletes @var{overlay}. The overlay continues to exist as +a Lisp object, and its property list is unchanged, but it ceases to be +attached to the buffer it belonged to, and ceases to have any effect on +display. + +A deleted overlay is not permanently disconnected. You can give it a +position in a buffer again by calling @code{move-overlay}. +@end defun + +@defun move-overlay overlay start end &optional buffer +This function moves @var{overlay} to @var{buffer}, and places its bounds +at @var{start} and @var{end}. Both arguments @var{start} and @var{end} +must specify buffer positions; they may be integers or markers. + +If @var{buffer} is omitted, @var{overlay} stays in the same buffer it +was already associated with; if @var{overlay} was deleted, it goes into +the current buffer. + +The return value is @var{overlay}. + +This is the only valid way to change the endpoints of an overlay. Do +not try modifying the markers in the overlay by hand, as that fails to +update other vital data structures and can cause some overlays to be +``lost.'' +@end defun + +@defun remove-overlays &optional start end name value +This function removes all the overlays between @var{start} and +@var{end} whose property @var{name} has the value @var{value}. It can +move the endpoints of the overlays in the region, or split them. + +If @var{name} is omitted or @code{nil}, it means to delete all overlays in +the specified region. If @var{start} and/or @var{end} are omitted or +@code{nil}, that means the beginning and end of the buffer respectively. +Therefore, @code{(remove-overlays)} removes all the overlays in the +current buffer. +@end defun + + Here are some examples: + +@example +;; @r{Create an overlay.} +(setq foo (make-overlay 1 10)) + @result{} # +(overlay-start foo) + @result{} 1 +(overlay-end foo) + @result{} 10 +(overlay-buffer foo) + @result{} # +;; @r{Give it a property we can check later.} +(overlay-put foo 'happy t) + @result{} t +;; @r{Verify the property is present.} +(overlay-get foo 'happy) + @result{} t +;; @r{Move the overlay.} +(move-overlay foo 5 20) + @result{} # +(overlay-start foo) + @result{} 5 +(overlay-end foo) + @result{} 20 +;; @r{Delete the overlay.} +(delete-overlay foo) + @result{} nil +;; @r{Verify it is deleted.} +foo + @result{} # +;; @r{A deleted overlay has no position.} +(overlay-start foo) + @result{} nil +(overlay-end foo) + @result{} nil +(overlay-buffer foo) + @result{} nil +;; @r{Undelete the overlay.} +(move-overlay foo 1 20) + @result{} # +;; @r{Verify the results.} +(overlay-start foo) + @result{} 1 +(overlay-end foo) + @result{} 20 +(overlay-buffer foo) + @result{} # +;; @r{Moving and deleting the overlay does not change its properties.} +(overlay-get foo 'happy) + @result{} t +@end example + + Emacs stores the overlays of each buffer in two lists, divided +around an arbitrary ``center position.'' One list extends backwards +through the buffer from that center position, and the other extends +forwards from that center position. The center position can be anywhere +in the buffer. + +@defun overlay-recenter pos +This function recenters the overlays of the current buffer around +position @var{pos}. That makes overlay lookup faster for positions +near @var{pos}, but slower for positions far away from @var{pos}. +@end defun + + A loop that scans the buffer forwards, creating overlays, can run +faster if you do @code{(overlay-recenter (point-max))} first. + +@node Overlay Properties +@subsection Overlay Properties + + Overlay properties are like text properties in that the properties that +alter how a character is displayed can come from either source. But in +most respects they are different. @xref{Text Properties}, for comparison. + + Text properties are considered a part of the text; overlays and +their properties are specifically considered not to be part of the +text. Thus, copying text between various buffers and strings +preserves text properties, but does not try to preserve overlays. +Changing a buffer's text properties marks the buffer as modified, +while moving an overlay or changing its properties does not. Unlike +text property changes, overlay property changes are not recorded in +the buffer's undo list. + + Since more than one overlay can specify a property value for the +same character, Emacs lets you specify a priority value of each +overlay. You should not make assumptions about which overlay will +prevail when there is a conflict and they have the same priority. + + These functions read and set the properties of an overlay: + +@defun overlay-get overlay prop +This function returns the value of property @var{prop} recorded in +@var{overlay}, if any. If @var{overlay} does not record any value for +that property, but it does have a @code{category} property which is a +symbol, that symbol's @var{prop} property is used. Otherwise, the value +is @code{nil}. +@end defun + +@defun overlay-put overlay prop value +This function sets the value of property @var{prop} recorded in +@var{overlay} to @var{value}. It returns @var{value}. +@end defun + +@defun overlay-properties overlay +This returns a copy of the property list of @var{overlay}. +@end defun + + See also the function @code{get-char-property} which checks both +overlay properties and text properties for a given character. +@xref{Examining Properties}. + + Many overlay properties have special meanings; here is a table +of them: + +@table @code +@item priority +@kindex priority @r{(overlay property)} +This property's value (which should be a nonnegative integer number) +determines the priority of the overlay. No priority, or @code{nil}, +means zero. + +The priority matters when two or more overlays cover the same +character and both specify the same property; the one whose +@code{priority} value is larger overrides the other. For the +@code{face} property, the higher priority overlay's value does not +completely override the other value; instead, its face attributes +override the face attributes of the lower priority @code{face} +property. + +Currently, all overlays take priority over text properties. Please +avoid using negative priority values, as we have not yet decided just +what they should mean. + +@item window +@kindex window @r{(overlay property)} +If the @code{window} property is non-@code{nil}, then the overlay +applies only on that window. + +@item category +@kindex category @r{(overlay property)} +If an overlay has a @code{category} property, we call it the +@dfn{category} of the overlay. It should be a symbol. The properties +of the symbol serve as defaults for the properties of the overlay. + +@item face +@kindex face @r{(overlay property)} +This property controls the way text is displayed---for example, which +font and which colors. @xref{Faces}, for more information. + +In the simplest case, the value is a face name. It can also be a list; +then each element can be any of these possibilities: + +@itemize @bullet +@item +A face name (a symbol or string). + +@item +A property list of face attributes. This has the form (@var{keyword} +@var{value} @dots{}), where each @var{keyword} is a face attribute +name and @var{value} is a meaningful value for that attribute. With +this feature, you do not need to create a face each time you want to +specify a particular attribute for certain text. @xref{Face +Attributes}. + +@item +A cons cell, either of the form @code{(foreground-color . @var{color-name})} or +@code{(background-color . @var{color-name})}. These elements specify +just the foreground color or just the background color. + +@code{(foreground-color . @var{color-name})} has the same effect as +@code{(:foreground @var{color-name})}; likewise for the background. +@end itemize + +@item mouse-face +@kindex mouse-face @r{(overlay property)} +This property is used instead of @code{face} when the mouse is within +the range of the overlay. + +@item display +@kindex display @r{(overlay property)} +This property activates various features that change the +way text is displayed. For example, it can make text appear taller +or shorter, higher or lower, wider or narrower, or replaced with an image. +@xref{Display Property}. + +@item help-echo +@kindex help-echo @r{(overlay property)} +If an overlay has a @code{help-echo} property, then when you move the +mouse onto the text in the overlay, Emacs displays a help string in the +echo area, or in the tooltip window. For details see @ref{Text +help-echo}. + +@item modification-hooks +@kindex modification-hooks @r{(overlay property)} +This property's value is a list of functions to be called if any +character within the overlay is changed or if text is inserted strictly +within the overlay. + +The hook functions are called both before and after each change. +If the functions save the information they receive, and compare notes +between calls, they can determine exactly what change has been made +in the buffer text. + +When called before a change, each function receives four arguments: the +overlay, @code{nil}, and the beginning and end of the text range to be +modified. + +When called after a change, each function receives five arguments: the +overlay, @code{t}, the beginning and end of the text range just +modified, and the length of the pre-change text replaced by that range. +(For an insertion, the pre-change length is zero; for a deletion, that +length is the number of characters deleted, and the post-change +beginning and end are equal.) + +If these functions modify the buffer, they should bind +@code{inhibit-modification-hooks} to @code{t} around doing so, to +avoid confusing the internal mechanism that calls these hooks. + +Text properties also support the @code{modification-hooks} property, +but the details are somewhat different (@pxref{Special Properties}). + +@item insert-in-front-hooks +@kindex insert-in-front-hooks @r{(overlay property)} +This property's value is a list of functions to be called before and +after inserting text right at the beginning of the overlay. The calling +conventions are the same as for the @code{modification-hooks} functions. + +@item insert-behind-hooks +@kindex insert-behind-hooks @r{(overlay property)} +This property's value is a list of functions to be called before and +after inserting text right at the end of the overlay. The calling +conventions are the same as for the @code{modification-hooks} functions. + +@item invisible +@kindex invisible @r{(overlay property)} +The @code{invisible} property can make the text in the overlay +invisible, which means that it does not appear on the screen. +@xref{Invisible Text}, for details. + +@item intangible +@kindex intangible @r{(overlay property)} +The @code{intangible} property on an overlay works just like the +@code{intangible} text property. @xref{Special Properties}, for details. + +@item isearch-open-invisible +This property tells incremental search how to make an invisible overlay +visible, permanently, if the final match overlaps it. @xref{Invisible +Text}. + +@item isearch-open-invisible-temporary +This property tells incremental search how to make an invisible overlay +visible, temporarily, during the search. @xref{Invisible Text}. + +@item before-string +@kindex before-string @r{(overlay property)} +This property's value is a string to add to the display at the beginning +of the overlay. The string does not appear in the buffer in any +sense---only on the screen. + +@item after-string +@kindex after-string @r{(overlay property)} +This property's value is a string to add to the display at the end of +the overlay. The string does not appear in the buffer in any +sense---only on the screen. + +@item evaporate +@kindex evaporate @r{(overlay property)} +If this property is non-@code{nil}, the overlay is deleted automatically +if it becomes empty (i.e., if its length becomes zero). If you give +an empty overlay a non-@code{nil} @code{evaporate} property, that deletes +it immediately. + +@item local-map +@cindex keymap of character (and overlays) +@kindex local-map @r{(overlay property)} +If this property is non-@code{nil}, it specifies a keymap for a portion +of the text. The property's value replaces the buffer's local map, when +the character after point is within the overlay. @xref{Active Keymaps}. + +@item keymap +@kindex keymap @r{(overlay property)} +The @code{keymap} property is similar to @code{local-map} but overrides the +buffer's local map (and the map specified by the @code{local-map} +property) rather than replacing it. +@end table + +@node Finding Overlays +@subsection Searching for Overlays + +@defun overlays-at pos +This function returns a list of all the overlays that cover the +character at position @var{pos} in the current buffer. The list is in +no particular order. An overlay contains position @var{pos} if it +begins at or before @var{pos}, and ends after @var{pos}. + +To illustrate usage, here is a Lisp function that returns a list of the +overlays that specify property @var{prop} for the character at point: + +@smallexample +(defun find-overlays-specifying (prop) + (let ((overlays (overlays-at (point))) + found) + (while overlays + (let ((overlay (car overlays))) + (if (overlay-get overlay prop) + (setq found (cons overlay found)))) + (setq overlays (cdr overlays))) + found)) +@end smallexample +@end defun + +@defun overlays-in beg end +This function returns a list of the overlays that overlap the region +@var{beg} through @var{end}. ``Overlap'' means that at least one +character is contained within the overlay and also contained within the +specified region; however, empty overlays are included in the result if +they are located at @var{beg}, or strictly between @var{beg} and @var{end}. +@end defun + +@defun next-overlay-change pos +This function returns the buffer position of the next beginning or end +of an overlay, after @var{pos}. If there is none, it returns +@code{(point-max)}. +@end defun + +@defun previous-overlay-change pos +This function returns the buffer position of the previous beginning or +end of an overlay, before @var{pos}. If there is none, it returns +@code{(point-min)}. +@end defun + + As an example, here's a simplified (and inefficient) version of the +primitive function @code{next-single-char-property-change} +(@pxref{Property Search}). It searches forward from position +@var{pos} for the next position where the value of a given property +@code{prop}, as obtained from either overlays or text properties, +changes. + +@smallexample +(defun next-single-char-property-change (position prop) + (save-excursion + (goto-char position) + (let ((propval (get-char-property (point) prop))) + (while (and (not (eobp)) + (eq (get-char-property (point) prop) propval)) + (goto-char (min (next-overlay-change (point)) + (next-single-property-change (point) prop))))) + (point))) +@end smallexample + +@node Width +@section Width + +Since not all characters have the same width, these functions let you +check the width of a character. @xref{Primitive Indent}, and +@ref{Screen Lines}, for related functions. + +@defun char-width char +This function returns the width in columns of the character @var{char}, +if it were displayed in the current buffer and the selected window. +@end defun + +@defun string-width string +This function returns the width in columns of the string @var{string}, +if it were displayed in the current buffer and the selected window. +@end defun + +@defun truncate-string-to-width string width &optional start-column padding ellipsis +This function returns the part of @var{string} that fits within +@var{width} columns, as a new string. + +If @var{string} does not reach @var{width}, then the result ends where +@var{string} ends. If one multi-column character in @var{string} +extends across the column @var{width}, that character is not included in +the result. Thus, the result can fall short of @var{width} but cannot +go beyond it. + +The optional argument @var{start-column} specifies the starting column. +If this is non-@code{nil}, then the first @var{start-column} columns of +the string are omitted from the value. If one multi-column character in +@var{string} extends across the column @var{start-column}, that +character is not included. + +The optional argument @var{padding}, if non-@code{nil}, is a padding +character added at the beginning and end of the result string, to extend +it to exactly @var{width} columns. The padding character is used at the +end of the result if it falls short of @var{width}. It is also used at +the beginning of the result if one multi-column character in +@var{string} extends across the column @var{start-column}. + +If @var{ellipsis} is non-@code{nil}, it should be a string which will +replace the end of @var{str} (including any padding) if it extends +beyond @var{end-column}, unless the display width of @var{str} is +equal to or less than the display width of @var{ellipsis}. If +@var{ellipsis} is non-@code{nil} and not a string, it stands for +@code{"..."}. + +@example +(truncate-string-to-width "\tab\t" 12 4) + @result{} "ab" +(truncate-string-to-width "\tab\t" 12 4 ?\s) + @result{} " ab " +@end example +@end defun + +@node Line Height +@section Line Height +@cindex line height + + The total height of each display line consists of the height of the +contents of the line, plus optional additional vertical line spacing +above or below the display line. + + The height of the line contents is the maximum height of any +character or image on that display line, including the final newline +if there is one. (A display line that is continued doesn't include a +final newline.) That is the default line height, if you do nothing to +specify a greater height. (In the most common case, this equals the +height of the default frame font.) + + There are several ways to explicitly specify a larger line height, +either by specifying an absolute height for the display line, or by +specifying vertical space. However, no matter what you specify, the +actual line height can never be less than the default. + +@kindex line-height @r{(text property)} + A newline can have a @code{line-height} text or overlay property +that controls the total height of the display line ending in that +newline. + + If the property value is @code{t}, the newline character has no +effect on the displayed height of the line---the visible contents +alone determine the height. This is useful for tiling small images +(or image slices) without adding blank areas between the images. + + If the property value is a list of the form @code{(@var{height} +@var{total})}, that adds extra space @emph{below} the display line. +First Emacs uses @var{height} as a height spec to control extra space +@emph{above} the line; then it adds enough space @emph{below} the line +to bring the total line height up to @var{total}. In this case, the +other ways to specify the line spacing are ignored. + + Any other kind of property value is a height spec, which translates +into a number---the specified line height. There are several ways to +write a height spec; here's how each of them translates into a number: + +@table @code +@item @var{integer} +If the height spec is a positive integer, the height value is that integer. +@item @var{float} +If the height spec is a float, @var{float}, the numeric height value +is @var{float} times the frame's default line height. +@item (@var{face} . @var{ratio}) +If the height spec is a cons of the format shown, the numeric height +is @var{ratio} times the height of face @var{face}. @var{ratio} can +be any type of number, or @code{nil} which means a ratio of 1. +If @var{face} is @code{t}, it refers to the current face. +@item (nil . @var{ratio}) +If the height spec is a cons of the format shown, the numeric height +is @var{ratio} times the height of the contents of the line. +@end table + + Thus, any valid height spec determines the height in pixels, one way +or another. If the line contents' height is less than that, Emacs +adds extra vertical space above the line to achieve the specified +total height. + + If you don't specify the @code{line-height} property, the line's +height consists of the contents' height plus the line spacing. +There are several ways to specify the line spacing for different +parts of Emacs text. + +@vindex default-line-spacing + You can specify the line spacing for all lines in a frame with the +@code{line-spacing} frame parameter (@pxref{Layout Parameters}). +However, if the variable @code{default-line-spacing} is +non-@code{nil}, it overrides the frame's @code{line-spacing} +parameter. An integer value specifies the number of pixels put below +lines on graphical displays. A floating point number specifies the +spacing relative to the frame's default line height. + +@vindex line-spacing + You can specify the line spacing for all lines in a buffer via the +buffer-local @code{line-spacing} variable. An integer value specifies +the number of pixels put below lines on graphical displays. A floating +point number specifies the spacing relative to the default frame line +height. This overrides line spacings specified for the frame. + +@kindex line-spacing @r{(text property)} + Finally, a newline can have a @code{line-spacing} text or overlay +property that overrides the default frame line spacing and the buffer +local @code{line-spacing} variable, for the display line ending in +that newline. + + One way or another, these mechanisms specify a Lisp value for the +spacing of each line. The value is a height spec, and it translates +into a Lisp value as described above. However, in this case the +numeric height value specifies the line spacing, rather than the line +height. + +@node Faces +@section Faces +@cindex faces + + A @dfn{face} is a named collection of graphical attributes: font +family, foreground color, background color, optional underlining, and +many others. Faces are used in Emacs to control the style of display of +particular parts of the text or the frame. @xref{Standard Faces,,, +emacs, The GNU Emacs Manual}, for the list of faces Emacs normally +comes with. + +@cindex face id +Each face has its own @dfn{face number}, which distinguishes faces at +low levels within Emacs. However, for most purposes, you refer to +faces in Lisp programs by the symbols that name them. + +@defun facep object +This function returns @code{t} if @var{object} is a face name string +or symbol (or if it is a vector of the kind used internally to record +face data). It returns @code{nil} otherwise. +@end defun + +Each face name is meaningful for all frames, and by default it has the +same meaning in all frames. But you can arrange to give a particular +face name a special meaning in one frame if you wish. + +@menu +* Defining Faces:: How to define a face with @code{defface}. +* Face Attributes:: What is in a face? +* Attribute Functions:: Functions to examine and set face attributes. +* Displaying Faces:: How Emacs combines the faces specified for a character. +* Font Selection:: Finding the best available font for a face. +* Face Functions:: How to define and examine faces. +* Auto Faces:: Hook for automatic face assignment. +* Font Lookup:: Looking up the names of available fonts + and information about them. +* Fontsets:: A fontset is a collection of fonts + that handle a range of character sets. +@end menu + +@node Defining Faces +@subsection Defining Faces + + The way to define a new face is with @code{defface}. This creates a +kind of customization item (@pxref{Customization}) which the user can +customize using the Customization buffer (@pxref{Easy Customization,,, +emacs, The GNU Emacs Manual}). + +@defmac defface face spec doc [keyword value]@dots{} +This declares @var{face} as a customizable face that defaults +according to @var{spec}. You should not quote the symbol @var{face}, +and it should not end in @samp{-face} (that would be redundant). The +argument @var{doc} specifies the face documentation. The keywords you +can use in @code{defface} are the same as in @code{defgroup} and +@code{defcustom} (@pxref{Common Keywords}). + +When @code{defface} executes, it defines the face according to +@var{spec}, then uses any customizations that were read from the +init file (@pxref{Init File}) to override that specification. + +When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs +Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} +overrides any customizations of the face. This way, the face reflects +exactly what the @code{defface} says. + +The purpose of @var{spec} is to specify how the face should appear on +different kinds of terminals. It should be an alist whose elements +have the form @code{(@var{display} @var{atts})}. Each element's +@sc{car}, @var{display}, specifies a class of terminals. (The first +element, if its @sc{car} is @code{default}, is special---it specifies +defaults for the remaining elements). The element's @sc{cadr}, +@var{atts}, is a list of face attributes and their values; it +specifies what the face should look like on that kind of terminal. +The possible attributes are defined in the value of +@code{custom-face-attributes}. + +The @var{display} part of an element of @var{spec} determines which +frames the element matches. If more than one element of @var{spec} +matches a given frame, the first element that matches is the one used +for that frame. There are three possibilities for @var{display}: + +@table @asis +@item @code{default} +This element of @var{spec} doesn't match any frames; instead, it +specifies defaults that apply to all frames. This kind of element, if +used, must be the first element of @var{spec}. Each of the following +elements can override any or all of these defaults. + +@item @code{t} +This element of @var{spec} matches all frames. Therefore, any +subsequent elements of @var{spec} are never used. Normally +@code{t} is used in the last (or only) element of @var{spec}. + +@item a list +If @var{display} is a list, each element should have the form +@code{(@var{characteristic} @var{value}@dots{})}. Here +@var{characteristic} specifies a way of classifying frames, and the +@var{value}s are possible classifications which @var{display} should +apply to. Here are the possible values of @var{characteristic}: + +@table @code +@item type +The kind of window system the frame uses---either @code{graphic} (any +graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), +@code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh +display), or @code{tty} (a non-graphics-capable display). +@xref{Window Systems, window-system}. + +@item class +What kinds of colors the frame supports---either @code{color}, +@code{grayscale}, or @code{mono}. + +@item background +The kind of background---either @code{light} or @code{dark}. + +@item min-colors +An integer that represents the minimum number of colors the frame +should support. This matches a frame if its +@code{display-color-cells} value is at least the specified integer. + +@item supports +Whether or not the frame can display the face attributes given in +@var{value}@dots{} (@pxref{Face Attributes}). See the documentation +for the function @code{display-supports-face-attributes-p} for more +information on exactly how this testing is done. @xref{Display Face +Attribute Testing}. +@end table + +If an element of @var{display} specifies more than one @var{value} for a +given @var{characteristic}, any of those values is acceptable. If +@var{display} has more than one element, each element should specify a +different @var{characteristic}; then @emph{each} characteristic of the +frame must match one of the @var{value}s specified for it in +@var{display}. +@end table +@end defmac + + Here's how the standard face @code{region} is defined: + +@example +@group +(defface region + '((((class color) (min-colors 88) (background dark)) + :background "blue3") +@end group + (((class color) (min-colors 88) (background light)) + :background "lightgoldenrod2") + (((class color) (min-colors 16) (background dark)) + :background "blue3") + (((class color) (min-colors 16) (background light)) + :background "lightgoldenrod2") + (((class color) (min-colors 8)) + :background "blue" :foreground "white") + (((type tty) (class mono)) + :inverse-video t) + (t :background "gray")) +@group + "Basic face for highlighting the region." + :group 'basic-faces) +@end group +@end example + + Internally, @code{defface} uses the symbol property +@code{face-defface-spec} to record the face attributes specified in +@code{defface}, @code{saved-face} for the attributes saved by the user +with the customization buffer, @code{customized-face} for the +attributes customized by the user for the current session, but not +saved, and @code{face-documentation} for the documentation string. + +@defopt frame-background-mode +This option, if non-@code{nil}, specifies the background type to use for +interpreting face definitions. If it is @code{dark}, then Emacs treats +all frames as if they had a dark background, regardless of their actual +background colors. If it is @code{light}, then Emacs treats all frames +as if they had a light background. +@end defopt + +@node Face Attributes +@subsection Face Attributes +@cindex face attributes + + The effect of using a face is determined by a fixed set of @dfn{face +attributes}. This table lists all the face attributes, and what they +mean. You can specify more than one face for a given piece of text; +Emacs merges the attributes of all the faces to determine how to +display the text. @xref{Displaying Faces}. + + Any attribute in a face can have the value @code{unspecified}. This +means the face doesn't specify that attribute. In face merging, when +the first face fails to specify a particular attribute, that means the +next face gets a chance. However, the @code{default} face must +specify all attributes. + + Some of these font attributes are meaningful only on certain kinds of +displays---if your display cannot handle a certain attribute, the +attribute is ignored. (The attributes @code{:family}, @code{:width}, +@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of +an X Logical Font Descriptor.) + +@table @code +@item :family +Font family name, or fontset name (@pxref{Fontsets}). If you specify a +font family name, the wild-card characters @samp{*} and @samp{?} are +allowed. + +@item :width +Relative proportionate width, also known as the character set width or +set width. This should be one of the symbols @code{ultra-condensed}, +@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, +@code{normal}, @code{semi-expanded}, @code{expanded}, +@code{extra-expanded}, or @code{ultra-expanded}. + +@item :height +Either the font height, an integer in units of 1/10 point, a floating +point number specifying the amount by which to scale the height of any +underlying face, or a function, which is called with the old height +(from the underlying face), and should return the new height. + +@item :weight +Font weight---a symbol from this series (from most dense to most faint): +@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, +@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, +or @code{ultra-light}. + +On a text-only terminal, any weight greater than normal is displayed as +extra bright, and any weight less than normal is displayed as +half-bright (provided the terminal supports the feature). + +@item :slant +Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal}, +@code{reverse-italic}, or @code{reverse-oblique}. + +On a text-only terminal, slanted text is displayed as half-bright, if +the terminal supports the feature. + +@item :foreground +Foreground color, a string. The value can be a system-defined color +name, or a hexadecimal color specification of the form +@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black, +@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is +blue, and @samp{#ffffff} is white.) + +@item :background +Background color, a string, like the foreground color. + +@item :inverse-video +Whether or not characters should be displayed in inverse video. The +value should be @code{t} (yes) or @code{nil} (no). + +@item :stipple +The background stipple, a bitmap. + +The value can be a string; that should be the name of a file containing +external-format X bitmap data. The file is found in the directories +listed in the variable @code{x-bitmap-file-path}. + +Alternatively, the value can specify the bitmap directly, with a list +of the form @code{(@var{width} @var{height} @var{data})}. Here, +@var{width} and @var{height} specify the size in pixels, and +@var{data} is a string containing the raw bits of the bitmap, row by +row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes +in the string (which should be a unibyte string for best results). +This means that each row always occupies at least one whole byte. + +If the value is @code{nil}, that means use no stipple pattern. + +Normally you do not need to set the stipple attribute, because it is +used automatically to handle certain shades of gray. + +@item :underline +Whether or not characters should be underlined, and in what color. If +the value is @code{t}, underlining uses the foreground color of the +face. If the value is a string, underlining uses that color. The +value @code{nil} means do not underline. + +@item :overline +Whether or not characters should be overlined, and in what color. +The value is used like that of @code{:underline}. + +@item :strike-through +Whether or not characters should be strike-through, and in what +color. The value is used like that of @code{:underline}. + +@item :inherit +The name of a face from which to inherit attributes, or a list of face +names. Attributes from inherited faces are merged into the face like an +underlying face would be, with higher priority than underlying faces. +If a list of faces is used, attributes from faces earlier in the list +override those from later faces. + +@item :box +Whether or not a box should be drawn around characters, its color, the +width of the box lines, and 3D appearance. +@end table + + Here are the possible values of the @code{:box} attribute, and what +they mean: + +@table @asis +@item @code{nil} +Don't draw a box. + +@item @code{t} +Draw a box with lines of width 1, in the foreground color. + +@item @var{color} +Draw a box with lines of width 1, in color @var{color}. + +@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} +This way you can explicitly specify all aspects of the box. The value +@var{width} specifies the width of the lines to draw; it defaults to 1. + +The value @var{color} specifies the color to draw with. The default is +the foreground color of the face for simple boxes, and the background +color of the face for 3D boxes. + +The value @var{style} specifies whether to draw a 3D box. If it is +@code{released-button}, the box looks like a 3D button that is not being +pressed. If it is @code{pressed-button}, the box looks like a 3D button +that is being pressed. If it is @code{nil} or omitted, a plain 2D box +is used. +@end table + + In older versions of Emacs, before @code{:family}, @code{:height}, +@code{:width}, @code{:weight}, and @code{:slant} existed, these +attributes were used to specify the type face. They are now +semi-obsolete, but they still work: + +@table @code +@item :font +This attribute specifies the font name. + +@item :bold +A non-@code{nil} value specifies a bold font. + +@item :italic +A non-@code{nil} value specifies an italic font. +@end table + + For compatibility, you can still set these ``attributes,'' even +though they are not real face attributes. Here is what that does: + +@table @code +@item :font +You can specify an X font name as the ``value'' of this ``attribute''; +that sets the @code{:family}, @code{:width}, @code{:height}, +@code{:weight}, and @code{:slant} attributes according to the font name. + +If the value is a pattern with wildcards, the first font that matches +the pattern is used to set these attributes. + +@item :bold +A non-@code{nil} makes the face bold; @code{nil} makes it normal. +This actually works by setting the @code{:weight} attribute. + +@item :italic +A non-@code{nil} makes the face italic; @code{nil} makes it normal. +This actually works by setting the @code{:slant} attribute. +@end table + +@defvar x-bitmap-file-path +This variable specifies a list of directories for searching +for bitmap files, for the @code{:stipple} attribute. +@end defvar + +@defun bitmap-spec-p object +This returns @code{t} if @var{object} is a valid bitmap specification, +suitable for use with @code{:stipple} (see above). It returns +@code{nil} otherwise. +@end defun + +@node Attribute Functions +@subsection Face Attribute Functions + + This section describes the functions for accessing and modifying the +attributes of an existing face. + +@defun set-face-attribute face frame &rest arguments +This function sets one or more attributes of face @var{face} for frame +@var{frame}. The attributes you specify this way override whatever +the @code{defface} says. + +The extra arguments @var{arguments} specify the attributes to set, and +the values for them. They should consist of alternating attribute names +(such as @code{:family} or @code{:underline}) and corresponding values. +Thus, + +@example +(set-face-attribute 'foo nil + :width 'extended + :weight 'bold + :underline "red") +@end example + +@noindent +sets the attributes @code{:width}, @code{:weight} and @code{:underline} +to the corresponding values. + +If @var{frame} is @code{t}, this function sets the default attributes +for new frames. Default attribute values specified this way override +the @code{defface} for newly created frames. + +If @var{frame} is @code{nil}, this function sets the attributes for +all existing frames, and the default for new frames. +@end defun + +@defun face-attribute face attribute &optional frame inherit +This returns the value of the @var{attribute} attribute of face +@var{face} on @var{frame}. If @var{frame} is @code{nil}, +that means the selected frame (@pxref{Input Focus}). + +If @var{frame} is @code{t}, this returns whatever new-frames default +value you previously specified with @code{set-face-attribute} for the +@var{attribute} attribute of @var{face}. If you have not specified +one, it returns @code{nil}. + +If @var{inherit} is @code{nil}, only attributes directly defined by +@var{face} are considered, so the return value may be +@code{unspecified}, or a relative value. If @var{inherit} is +non-@code{nil}, @var{face}'s definition of @var{attribute} is merged +with the faces specified by its @code{:inherit} attribute; however the +return value may still be @code{unspecified} or relative. If +@var{inherit} is a face or a list of faces, then the result is further +merged with that face (or faces), until it becomes specified and +absolute. + +To ensure that the return value is always specified and absolute, use +a value of @code{default} for @var{inherit}; this will resolve any +unspecified or relative values by merging with the @code{default} face +(which is always completely specified). + +For example, + +@example +(face-attribute 'bold :weight) + @result{} bold +@end example +@end defun + +@defun face-attribute-relative-p attribute value +This function returns non-@code{nil} if @var{value}, when used as the +value of the face attribute @var{attribute}, is relative. This means +it would modify, rather than completely override, any value that comes +from a subsequent face in the face list or that is inherited from +another face. + +@code{unspecified} is a relative value for all attributes. +For @code{:height}, floating point values are also relative. + +For example: + +@example +(face-attribute-relative-p :height 2.0) + @result{} t +@end example +@end defun + +@defun merge-face-attribute attribute value1 value2 +If @var{value1} is a relative value for the face attribute +@var{attribute}, returns it merged with the underlying value +@var{value2}; otherwise, if @var{value1} is an absolute value for the +face attribute @var{attribute}, returns @var{value1} unchanged. +@end defun + + The functions above did not exist before Emacs 21. For compatibility +with older Emacs versions, you can use the following functions to set +and examine the face attributes which existed in those versions. +They use values of @code{t} and @code{nil} for @var{frame} +just like @code{set-face-attribute} and @code{face-attribute}. + +@defun set-face-foreground face color &optional frame +@defunx set-face-background face color &optional frame +These functions set the foreground (or background, respectively) color +of face @var{face} to @var{color}. The argument @var{color} should be a +string, the name of a color. + +Certain shades of gray are implemented by stipple patterns on +black-and-white screens. +@end defun + +@defun set-face-stipple face pattern &optional frame +This function sets the background stipple pattern of face @var{face} +to @var{pattern}. The argument @var{pattern} should be the name of a +stipple pattern defined by the X server, or actual bitmap data +(@pxref{Face Attributes}), or @code{nil} meaning don't use stipple. + +Normally there is no need to pay attention to stipple patterns, because +they are used automatically to handle certain shades of gray. +@end defun + +@defun set-face-font face font &optional frame +This function sets the font of face @var{face}. This actually sets +the attributes @code{:family}, @code{:width}, @code{:height}, +@code{:weight}, and @code{:slant} according to the font name +@var{font}. +@end defun + +@defun set-face-bold-p face bold-p &optional frame +This function specifies whether @var{face} should be bold. If +@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no. +This actually sets the @code{:weight} attribute. +@end defun + +@defun set-face-italic-p face italic-p &optional frame +This function specifies whether @var{face} should be italic. If +@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no. +This actually sets the @code{:slant} attribute. +@end defun + +@defun set-face-underline-p face underline &optional frame +This function sets the underline attribute of face @var{face}. +Non-@code{nil} means do underline; @code{nil} means don't. +If @var{underline} is a string, underline with that color. +@end defun + +@defun set-face-inverse-video-p face inverse-video-p &optional frame +This function sets the @code{:inverse-video} attribute of face +@var{face}. +@end defun + +@defun invert-face face &optional frame +This function swaps the foreground and background colors of face +@var{face}. +@end defun + + These functions examine the attributes of a face. If you don't +specify @var{frame}, they refer to the selected frame; @code{t} refers +to the default data for new frames. They return the symbol +@code{unspecified} if the face doesn't define any value for that +attribute. + +@defun face-foreground face &optional frame inherit +@defunx face-background face &optional frame inherit +These functions return the foreground color (or background color, +respectively) of face @var{face}, as a string. + +If @var{inherit} is @code{nil}, only a color directly defined by the face is +returned. If @var{inherit} is non-@code{nil}, any faces specified by its +@code{:inherit} attribute are considered as well, and if @var{inherit} +is a face or a list of faces, then they are also considered, until a +specified color is found. To ensure that the return value is always +specified, use a value of @code{default} for @var{inherit}. +@end defun + +@defun face-stipple face &optional frame inherit +This function returns the name of the background stipple pattern of face +@var{face}, or @code{nil} if it doesn't have one. + +If @var{inherit} is @code{nil}, only a stipple directly defined by the +face is returned. If @var{inherit} is non-@code{nil}, any faces +specified by its @code{:inherit} attribute are considered as well, and +if @var{inherit} is a face or a list of faces, then they are also +considered, until a specified stipple is found. To ensure that the +return value is always specified, use a value of @code{default} for +@var{inherit}. +@end defun + +@defun face-font face &optional frame +This function returns the name of the font of face @var{face}. +@end defun + +@defun face-bold-p face &optional frame +This function returns @code{t} if @var{face} is bold---that is, if it is +bolder than normal. It returns @code{nil} otherwise. +@end defun + +@defun face-italic-p face &optional frame +This function returns @code{t} if @var{face} is italic or oblique, +@code{nil} otherwise. +@end defun + +@defun face-underline-p face &optional frame +This function returns the @code{:underline} attribute of face @var{face}. +@end defun + +@defun face-inverse-video-p face &optional frame +This function returns the @code{:inverse-video} attribute of face @var{face}. +@end defun + +@node Displaying Faces +@subsection Displaying Faces + + Here are the ways to specify which faces to use for display of text: + +@itemize @bullet +@item +With defaults. The @code{default} face is used as the ultimate +default for all text. (In Emacs 19 and 20, the @code{default} +face is used only when no other face is specified.) + +@item +For a mode line or header line, the face @code{mode-line} or +@code{mode-line-inactive}, or @code{header-line}, is merged in just +before @code{default}. + +@item +With text properties. A character can have a @code{face} property; if +so, the faces and face attributes specified there apply. @xref{Special +Properties}. + +If the character has a @code{mouse-face} property, that is used instead +of the @code{face} property when the mouse is ``near enough'' to the +character. + +@item +With overlays. An overlay can have @code{face} and @code{mouse-face} +properties too; they apply to all the text covered by the overlay. + +@item +With a region that is active. In Transient Mark mode, the region is +highlighted with the face @code{region} (@pxref{Standard Faces,,, +emacs, The GNU Emacs Manual}). + +@item +With special glyphs. Each glyph can specify a particular face +number. @xref{Glyphs}. +@end itemize + + If these various sources together specify more than one face for a +particular character, Emacs merges the attributes of the various faces +specified. For each attribute, Emacs tries first the face of any +special glyph; then the face for region highlighting, if appropriate; +then the faces specified by overlays, followed by those specified by +text properties, then the @code{mode-line} or +@code{mode-line-inactive} or @code{header-line} face (if in a mode +line or a header line), and last the @code{default} face. + + When multiple overlays cover one character, an overlay with higher +priority overrides those with lower priority. @xref{Overlays}. + +@node Font Selection +@subsection Font Selection + + @dfn{Selecting a font} means mapping the specified face attributes for +a character to a font that is available on a particular display. The +face attributes, as determined by face merging, specify most of the +font choice, but not all. Part of the choice depends on what character +it is. + + If the face specifies a fontset name, that fontset determines a +pattern for fonts of the given charset. If the face specifies a font +family, a font pattern is constructed. + + Emacs tries to find an available font for the given face attributes +and character's registry and encoding. If there is a font that matches +exactly, it is used, of course. The hard case is when no available font +exactly fits the specification. Then Emacs looks for one that is +``close''---one attribute at a time. You can specify the order to +consider the attributes. In the case where a specified font family is +not available, you can specify a set of mappings for alternatives to +try. + +@defvar face-font-selection-order +This variable specifies the order of importance of the face attributes +@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The +value should be a list containing those four symbols, in order of +decreasing importance. + +Font selection first finds the best available matches for the first +attribute listed; then, among the fonts which are best in that way, it +searches for the best matches in the second attribute, and so on. + +The attributes @code{:weight} and @code{:width} have symbolic values in +a range centered around @code{normal}. Matches that are more extreme +(farther from @code{normal}) are somewhat preferred to matches that are +less extreme (closer to @code{normal}); this is designed to ensure that +non-normal faces contrast with normal ones, whenever possible. + +The default is @code{(:width :height :weight :slant)}, which means first +find the fonts closest to the specified @code{:width}, then---among the +fonts with that width---find a best match for the specified font height, +and so on. + +One example of a case where this variable makes a difference is when the +default font has no italic equivalent. With the default ordering, the +@code{italic} face will use a non-italic font that is similar to the +default one. But if you put @code{:slant} before @code{:height}, the +@code{italic} face will use an italic font, even if its height is not +quite right. +@end defvar + +@defvar face-font-family-alternatives +This variable lets you specify alternative font families to try, if a +given family is specified and doesn't exist. Each element should have +this form: + +@example +(@var{family} @var{alternate-families}@dots{}) +@end example + +If @var{family} is specified but not available, Emacs will try the other +families given in @var{alternate-families}, one by one, until it finds a +family that does exist. +@end defvar + +@defvar face-font-registry-alternatives +This variable lets you specify alternative font registries to try, if a +given registry is specified and doesn't exist. Each element should have +this form: + +@example +(@var{registry} @var{alternate-registries}@dots{}) +@end example + +If @var{registry} is specified but not available, Emacs will try the +other registries given in @var{alternate-registries}, one by one, +until it finds a registry that does exist. +@end defvar + + Emacs can make use of scalable fonts, but by default it does not use +them, since the use of too many or too big scalable fonts can crash +XFree86 servers. + +@defvar scalable-fonts-allowed +This variable controls which scalable fonts to use. A value of +@code{nil}, the default, means do not use scalable fonts. @code{t} +means to use any scalable font that seems appropriate for the text. + +Otherwise, the value must be a list of regular expressions. Then a +scalable font is enabled for use if its name matches any regular +expression in the list. For example, + +@example +(setq scalable-fonts-allowed '("muleindian-2$")) +@end example + +@noindent +allows the use of scalable fonts with registry @code{muleindian-2}. +@end defvar + +@defvar face-font-rescale-alist +This variable specifies scaling for certain faces. Its value should +be a list of elements of the form + +@example +(@var{fontname-regexp} . @var{scale-factor}) +@end example + +If @var{fontname-regexp} matches the font name that is about to be +used, this says to choose a larger similar font according to the +factor @var{scale-factor}. You would use this feature to normalize +the font size if certain fonts are bigger or smaller than their +nominal heights and widths would suggest. +@end defvar + +@node Face Functions +@subsection Functions for Working with Faces + + Here are additional functions for creating and working with faces. + +@defun make-face name +This function defines a new face named @var{name}, initially with all +attributes @code{nil}. It does nothing if there is already a face named +@var{name}. +@end defun + +@defun face-list +This function returns a list of all defined face names. +@end defun + +@defun copy-face old-face new-name &optional frame new-frame +This function defines a face named @var{new-name} as a copy of the existing +face named @var{old-face}. It creates the face @var{new-name} if that +doesn't already exist. + +If the optional argument @var{frame} is given, this function applies +only to that frame. Otherwise it applies to each frame individually, +copying attributes from @var{old-face} in each frame to @var{new-face} +in the same frame. + +If the optional argument @var{new-frame} is given, then @code{copy-face} +copies the attributes of @var{old-face} in @var{frame} to @var{new-name} +in @var{new-frame}. +@end defun + +@defun face-id face +This function returns the face number of face @var{face}. +@end defun + +@defun face-documentation face +This function returns the documentation string of face @var{face}, or +@code{nil} if none was specified for it. +@end defun + +@defun face-equal face1 face2 &optional frame +This returns @code{t} if the faces @var{face1} and @var{face2} have the +same attributes for display. +@end defun + +@defun face-differs-from-default-p face &optional frame +This returns non-@code{nil} if the face @var{face} displays +differently from the default face. +@end defun + +@cindex face alias +A @dfn{face alias} provides an equivalent name for a face. You can +define a face alias by giving the alias symbol the @code{face-alias} +property, with a value of the target face name. The following example +makes @code{modeline} an alias for the @code{mode-line} face. + +@example +(put 'modeline 'face-alias 'mode-line) +@end example + + +@node Auto Faces +@subsection Automatic Face Assignment +@cindex automatic face assignment +@cindex faces, automatic choice + + This hook is used for automatically assigning faces to text in the +buffer. It is part of the implementation of Jit-Lock mode, used by +Font-Lock. + +@defvar fontification-functions +This variable holds a list of functions that are called by Emacs +redisplay as needed to assign faces automatically to text in the buffer. + +The functions are called in the order listed, with one argument, a +buffer position @var{pos}. Each function should attempt to assign faces +to the text in the current buffer starting at @var{pos}. + +Each function should record the faces they assign by setting the +@code{face} property. It should also add a non-@code{nil} +@code{fontified} property for all the text it has assigned faces to. +That property tells redisplay that faces have been assigned to that text +already. + +It is probably a good idea for each function to do nothing if the +character after @var{pos} already has a non-@code{nil} @code{fontified} +property, but this is not required. If one function overrides the +assignments made by a previous one, the properties as they are +after the last function finishes are the ones that really matter. + +For efficiency, we recommend writing these functions so that they +usually assign faces to around 400 to 600 characters at each call. +@end defvar + +@node Font Lookup +@subsection Looking Up Fonts + +@defun x-list-fonts pattern &optional face frame maximum +This function returns a list of available font names that match +@var{pattern}. If the optional arguments @var{face} and @var{frame} are +specified, then the list is limited to fonts that are the same size as +@var{face} currently is on @var{frame}. + +The argument @var{pattern} should be a string, perhaps with wildcard +characters: the @samp{*} character matches any substring, and the +@samp{?} character matches any single character. Pattern matching +of font names ignores case. + +If you specify @var{face} and @var{frame}, @var{face} should be a face name +(a symbol) and @var{frame} should be a frame. + +The optional argument @var{maximum} sets a limit on how many fonts to +return. If this is non-@code{nil}, then the return value is truncated +after the first @var{maximum} matching fonts. Specifying a small value +for @var{maximum} can make this function much faster, in cases where +many fonts match the pattern. +@end defun + +@defun x-family-fonts &optional family frame +This function returns a list describing the available fonts for family +@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, +this list applies to all families, and therefore, it contains all +available fonts. Otherwise, @var{family} must be a string; it may +contain the wildcards @samp{?} and @samp{*}. + +The list describes the display that @var{frame} is on; if @var{frame} is +omitted or @code{nil}, it applies to the selected frame's display +(@pxref{Input Focus}). + +The list contains a vector of the following form for each font: + +@example +[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} + @var{fixed-p} @var{full} @var{registry-and-encoding}] +@end example + +The first five elements correspond to face attributes; if you +specify these attributes for a face, it will use this font. + +The last three elements give additional information about the font. +@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. +@var{full} is the full name of the font, and +@var{registry-and-encoding} is a string giving the registry and +encoding of the font. + +The result list is sorted according to the current face font sort order. +@end defun + +@defun x-font-family-list &optional frame +This function returns a list of the font families available for +@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it +describes the selected frame's display (@pxref{Input Focus}). + +The value is a list of elements of this form: + +@example +(@var{family} . @var{fixed-p}) +@end example + +@noindent +Here @var{family} is a font family, and @var{fixed-p} is +non-@code{nil} if fonts of that family are fixed-pitch. +@end defun + +@defvar font-list-limit +This variable specifies maximum number of fonts to consider in font +matching. The function @code{x-family-fonts} will not return more than +that many fonts, and font selection will consider only that many fonts +when searching a matching font for face attributes. The default is +currently 100. +@end defvar + +@node Fontsets +@subsection Fontsets + + A @dfn{fontset} is a list of fonts, each assigned to a range of +character codes. An individual font cannot display the whole range of +characters that Emacs supports, but a fontset can. Fontsets have names, +just as fonts do, and you can use a fontset name in place of a font name +when you specify the ``font'' for a frame or a face. Here is +information about defining a fontset under Lisp program control. + +@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror +This function defines a new fontset according to the specification +string @var{fontset-spec}. The string should have this format: + +@smallexample +@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}} +@end smallexample + +@noindent +Whitespace characters before and after the commas are ignored. + +The first part of the string, @var{fontpattern}, should have the form of +a standard X font name, except that the last two fields should be +@samp{fontset-@var{alias}}. + +The new fontset has two names, one long and one short. The long name is +@var{fontpattern} in its entirety. The short name is +@samp{fontset-@var{alias}}. You can refer to the fontset by either +name. If a fontset with the same name already exists, an error is +signaled, unless @var{noerror} is non-@code{nil}, in which case this +function does nothing. + +If optional argument @var{style-variant-p} is non-@code{nil}, that says +to create bold, italic and bold-italic variants of the fontset as well. +These variant fontsets do not have a short name, only a long one, which +is made by altering @var{fontpattern} to indicate the bold or italic +status. + +The specification string also says which fonts to use in the fontset. +See below for the details. +@end defun + + The construct @samp{@var{charset}:@var{font}} specifies which font to +use (in this fontset) for one particular character set. Here, +@var{charset} is the name of a character set, and @var{font} is the font +to use for that character set. You can use this construct any number of +times in the specification string. + + For the remaining character sets, those that you don't specify +explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces +@samp{fontset-@var{alias}} with a value that names one character set. +For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced +with @samp{ISO8859-1}. + + In addition, when several consecutive fields are wildcards, Emacs +collapses them into a single wildcard. This is to prevent use of +auto-scaled fonts. Fonts made by scaling larger fonts are not usable +for editing, and scaling a smaller font is not useful because it is +better to use the smaller font in its own size, which Emacs does. + + Thus if @var{fontpattern} is this, + +@example +-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 +@end example + +@noindent +the font specification for @acronym{ASCII} characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-ISO8859-1 +@end example + +@noindent +and the font specification for Chinese GB2312 characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-gb2312*-* +@end example + + You may not have any Chinese font matching the above font +specification. Most X distributions include only Chinese fonts that +have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In +such a case, @samp{Fontset-@var{n}} can be specified as below: + +@smallexample +Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ + chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* +@end smallexample + +@noindent +Then, the font specifications for all but Chinese GB2312 characters have +@samp{fixed} in the @var{family} field, and the font specification for +Chinese GB2312 characters has a wild card @samp{*} in the @var{family} +field. + +@defun set-fontset-font name character fontname &optional frame +This function modifies the existing fontset @var{name} to +use the font name @var{fontname} for the character @var{character}. + +If @var{name} is @code{nil}, this function modifies the default +fontset, whose short name is @samp{fontset-default}. + +@var{character} may be a cons; @code{(@var{from} . @var{to})}, where +@var{from} and @var{to} are non-generic characters. In that case, use +@var{fontname} for all characters in the range @var{from} and @var{to} +(inclusive). + +@var{character} may be a charset. In that case, use +@var{fontname} for all character in the charsets. + +@var{fontname} may be a cons; @code{(@var{family} . @var{registry})}, +where @var{family} is a family name of a font (possibly including a +foundry name at the head), @var{registry} is a registry name of a font +(possibly including an encoding name at the tail). + +For instance, this changes the default fontset to use a font of which +registry name is @samp{JISX0208.1983} for all characters belonging to +the charset @code{japanese-jisx0208}. + +@smallexample +(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983")) +@end smallexample +@end defun + +@defun char-displayable-p char +This function returns @code{t} if Emacs ought to be able to display +@var{char}. More precisely, if the selected frame's fontset has a +font to display the character set that @var{char} belongs to. + +Fontsets can specify a font on a per-character basis; when the fontset +does that, this function's value may not be accurate. +@end defun + +@node Fringes +@section Fringes +@cindex fringes + + The @dfn{fringes} of a window are thin vertical strips down the +sides that are used for displaying bitmaps that indicate truncation, +continuation, horizontal scrolling, and the overlay arrow. + +@menu +* Fringe Size/Pos:: Specifying where to put the window fringes. +* Fringe Indicators:: Displaying indicator icons in the window fringes. +* Fringe Cursors:: Displaying cursors in the right fringe. +* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. +* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. +* Overlay Arrow:: Display of an arrow to indicate position. +@end menu + +@node Fringe Size/Pos +@subsection Fringe Size and Position + + The following buffer-local variables control the position and width +of the window fringes. + +@defvar fringes-outside-margins +The fringes normally appear between the display margins and the window +text. If the value is non-@code{nil}, they appear outside the display +margins. @xref{Display Margins}. +@end defvar + +@defvar left-fringe-width +This variable, if non-@code{nil}, specifies the width of the left +fringe in pixels. A value of @code{nil} means to use the left fringe +width from the window's frame. +@end defvar + +@defvar right-fringe-width +This variable, if non-@code{nil}, specifies the width of the right +fringe in pixels. A value of @code{nil} means to use the right fringe +width from the window's frame. +@end defvar + + The values of these variables take effect when you display the +buffer in a window. If you change them while the buffer is visible, +you can call @code{set-window-buffer} to display it once again in the +same window, to make the changes take effect. + +@defun set-window-fringes window left &optional right outside-margins +This function sets the fringe widths of window @var{window}. +If @var{window} is @code{nil}, the selected window is used. + +The argument @var{left} specifies the width in pixels of the left +fringe, and likewise @var{right} for the right fringe. A value of +@code{nil} for either one stands for the default width. If +@var{outside-margins} is non-@code{nil}, that specifies that fringes +should appear outside of the display margins. +@end defun + +@defun window-fringes &optional window +This function returns information about the fringes of a window +@var{window}. If @var{window} is omitted or @code{nil}, the selected +window is used. The value has the form @code{(@var{left-width} +@var{right-width} @var{outside-margins})}. +@end defun + + +@node Fringe Indicators +@subsection Fringe Indicators +@cindex fringe indicators +@cindex indicators, fringe + + The @dfn{fringe indicators} are tiny icons Emacs displays in the +window fringe (on a graphic display) to indicate truncated or +continued lines, buffer boundaries, overlay arrow, etc. + +@defopt indicate-empty-lines +@cindex fringes, and empty line indication +When this is non-@code{nil}, Emacs displays a special glyph in the +fringe of each empty line at the end of the buffer, on graphical +displays. @xref{Fringes}. This variable is automatically +buffer-local in every buffer. +@end defopt + +@defvar indicate-buffer-boundaries +This buffer-local variable controls how the buffer boundaries and +window scrolling are indicated in the window fringes. + +Emacs can indicate the buffer boundaries---that is, the first and last +line in the buffer---with angle icons when they appear on the screen. +In addition, Emacs can display an up-arrow in the fringe to show +that there is text above the screen, and a down-arrow to show +there is text below the screen. + +There are three kinds of basic values: + +@table @asis +@item @code{nil} +Don't display any of these fringe icons. +@item @code{left} +Display the angle icons and arrows in the left fringe. +@item @code{right} +Display the angle icons and arrows in the right fringe. +@item any non-alist +Display the angle icons in the left fringe +and don't display the arrows. +@end table + +Otherwise the value should be an alist that specifies which fringe +indicators to display and where. Each element of the alist should +have the form @code{(@var{indicator} . @var{position})}. Here, +@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, +@code{down}, and @code{t} (which covers all the icons not yet +specified), while @var{position} is one of @code{left}, @code{right} +and @code{nil}. + +For example, @code{((top . left) (t . right))} places the top angle +bitmap in left fringe, and the bottom angle bitmap as well as both +arrow bitmaps in right fringe. To show the angle bitmaps in the left +fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. +@end defvar + +@defvar default-indicate-buffer-boundaries +The value of this variable is the default value for +@code{indicate-buffer-boundaries} in buffers that do not override it. +@end defvar + +@defvar fringe-indicator-alist +This buffer-local variable specifies the mapping from logical fringe +indicators to the actual bitmaps displayed in the window fringes. + +These symbols identify the logical fringe indicators: + +@table @asis +@item Truncation and continuation line indicators: +@code{truncation}, @code{continuation}. + +@item Buffer position indicators: +@code{up}, @code{down}, +@code{top}, @code{bottom}, +@code{top-bottom}. + +@item Empty line indicator: +@code{empty-line}. + +@item Overlay arrow indicator: +@code{overlay-arrow}. + +@item Unknown bitmap indicator: +@code{unknown}. +@end table + + The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})} +specifies the fringe bitmaps used to display a specific logical +fringe indicator. + +Here, @var{indicator} specifies the logical indicator type, and +@var{bitmaps} is list of symbols @code{(@var{left} @var{right} +[@var{left1} @var{right1}])} which specifies the actual bitmap shown +in the left or right fringe for the logical indicator. + +The @var{left} and @var{right} symbols specify the bitmaps shown in +the left and/or right fringe for the specific indicator. The +@var{left1} or @var{right1} bitmaps are used only for the `bottom' and +`top-bottom indicators when the last (only) line in has no final +newline. Alternatively, @var{bitmaps} may be a single symbol which is +used in both left and right fringes. + +When @code{fringe-indicator-alist} has a buffer-local value, and there +is no bitmap defined for a logical indicator, or the bitmap is +@code{t}, the corresponding value from the (non-local) +@code{default-fringe-indicator-alist} is used. + +To completely hide a specific indicator, set the bitmap to @code{nil}. +@end defvar + +@defvar default-fringe-indicator-alist +The value of this variable is the default value for +@code{fringe-indicator-alist} in buffers that do not override it. +@end defvar + +Standard fringe bitmaps for indicators: +@example +left-arrow right-arrow up-arrow down-arrow +left-curly-arrow right-curly-arrow +left-triangle right-triangle +top-left-angle top-right-angle +bottom-left-angle bottom-right-angle +left-bracket right-bracket +filled-rectangle hollow-rectangle +filled-square hollow-square +vertical-bar horizontal-bar +empty-line question-mark +@end example + +@node Fringe Cursors +@subsection Fringe Cursors +@cindex fringe cursors +@cindex cursor, fringe + + When a line is exactly as wide as the window, Emacs displays the +cursor in the right fringe instead of using two lines. Different +bitmaps are used to represent the cursor in the fringe depending on +the current buffer's cursor type. + +@table @asis +@item Logical cursor types: +@code{box} , @code{hollow}, @code{bar}, +@code{hbar}, @code{hollow-small}. +@end table + +The @code{hollow-small} type is used instead of @code{hollow} when the +normal @code{hollow-rectangle} bitmap is too tall to fit on a specific +display line. + +@defvar overflow-newline-into-fringe +If this is non-@code{nil}, lines exactly as wide as the window (not +counting the final newline character) are not continued. Instead, +when point is at the end of the line, the cursor appears in the right +fringe. +@end defvar + +@defvar fringe-cursor-alist +This variable specifies the mapping from logical cursor type to the +actual fringe bitmaps displayed in the right fringe. The value is an +alist where each element @code{(@var{cursor} . @var{bitmap})} specifies +the fringe bitmaps used to display a specific logical cursor type in +the fringe. Here, @var{cursor} specifies the logical cursor type and +@var{bitmap} is a symbol specifying the fringe bitmap to be displayed +for that logical cursor type. + +When @code{fringe-cursor-alist} has a buffer-local value, and there is +no bitmap defined for a cursor type, the corresponding value from the +(non-local) @code{default-fringes-indicator-alist} is used. +@end defvar + +@defvar default-fringes-cursor-alist +The value of this variable is the default value for +@code{fringe-cursor-alist} in buffers that do not override it. +@end defvar + +Standard bitmaps for displaying the cursor in right fringe: +@example +filled-rectangle hollow-rectangle filled-square hollow-square +vertical-bar horizontal-bar +@end example + + +@node Fringe Bitmaps +@subsection Fringe Bitmaps +@cindex fringe bitmaps +@cindex bitmaps, fringe + + The @dfn{fringe bitmaps} are the actual bitmaps which represent the +logical fringe indicators for truncated or continued lines, buffer +boundaries, overlay arrow, etc. Fringe bitmap symbols have their own +name space. The fringe bitmaps are shared by all frames and windows. +You can redefine the built-in fringe bitmaps, and you can define new +fringe bitmaps. + + The way to display a bitmap in the left or right fringes for a given +line in a window is by specifying the @code{display} property for one +of the characters that appears in it. Use a display specification of +the form @code{(left-fringe @var{bitmap} [@var{face}])} or +@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display +Property}). Here, @var{bitmap} is a symbol identifying the bitmap you +want, and @var{face} (which is optional) is the name of the face whose +colors should be used for displaying the bitmap, instead of the +default @code{fringe} face. @var{face} is automatically merged with +the @code{fringe} face, so normally @var{face} need only specify the +foreground color for the bitmap. + +@defun fringe-bitmaps-at-pos &optional pos window +This function returns the fringe bitmaps of the display line +containing position @var{pos} in window @var{window}. The return +value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} +is the symbol for the fringe bitmap in the left fringe (or @code{nil} +if no bitmap), @var{right} is similar for the right fringe, and @var{ov} +is non-@code{nil} if there is an overlay arrow in the left fringe. + +The value is @code{nil} if @var{pos} is not visible in @var{window}. +If @var{window} is @code{nil}, that stands for the selected window. +If @var{pos} is @code{nil}, that stands for the value of point in +@var{window}. +@end defun + +@node Customizing Bitmaps +@subsection Customizing Fringe Bitmaps + +@defun define-fringe-bitmap bitmap bits &optional height width align +This function defines the symbol @var{bitmap} as a new fringe bitmap, +or replaces an existing bitmap with that name. + +The argument @var{bits} specifies the image to use. It should be +either a string or a vector of integers, where each element (an +integer) corresponds to one row of the bitmap. Each bit of an integer +corresponds to one pixel of the bitmap, where the low bit corresponds +to the rightmost pixel of the bitmap. + +The height is normally the length of @var{bits}. However, you +can specify a different height with non-@code{nil} @var{height}. The width +is normally 8, but you can specify a different width with non-@code{nil} +@var{width}. The width must be an integer between 1 and 16. + +The argument @var{align} specifies the positioning of the bitmap +relative to the range of rows where it is used; the default is to +center the bitmap. The allowed values are @code{top}, @code{center}, +or @code{bottom}. + +The @var{align} argument may also be a list @code{(@var{align} +@var{periodic})} where @var{align} is interpreted as described above. +If @var{periodic} is non-@code{nil}, it specifies that the rows in +@code{bits} should be repeated enough times to reach the specified +height. +@end defun + +@defun destroy-fringe-bitmap bitmap +This function destroy the fringe bitmap identified by @var{bitmap}. +If @var{bitmap} identifies a standard fringe bitmap, it actually +restores the standard definition of that bitmap, instead of +eliminating it entirely. +@end defun + +@defun set-fringe-bitmap-face bitmap &optional face +This sets the face for the fringe bitmap @var{bitmap} to @var{face}. +If @var{face} is @code{nil}, it selects the @code{fringe} face. The +bitmap's face controls the color to draw it in. + +@var{face} is merged with the @code{fringe} face, so normally +@var{face} should specify only the foreground color. +@end defun + +@node Overlay Arrow +@subsection The Overlay Arrow +@c @cindex overlay arrow Duplicates variable names + + The @dfn{overlay arrow} is useful for directing the user's attention +to a particular line in a buffer. For example, in the modes used for +interface to debuggers, the overlay arrow indicates the line of code +about to be executed. This feature has nothing to do with +@dfn{overlays} (@pxref{Overlays}). + +@defvar overlay-arrow-string +This variable holds the string to display to call attention to a +particular line, or @code{nil} if the arrow feature is not in use. +On a graphical display the contents of the string are ignored; instead a +glyph is displayed in the fringe area to the left of the display area. +@end defvar + +@defvar overlay-arrow-position +This variable holds a marker that indicates where to display the overlay +arrow. It should point at the beginning of a line. On a non-graphical +display the arrow text +appears at the beginning of that line, overlaying any text that would +otherwise appear. Since the arrow is usually short, and the line +usually begins with indentation, normally nothing significant is +overwritten. + +The overlay-arrow string is displayed in any given buffer if the value +of @code{overlay-arrow-position} in that buffer points into that +buffer. Thus, it is possible to display multiple overlay arrow strings +by creating buffer-local bindings of @code{overlay-arrow-position}. +However, it is usually cleaner to use +@code{overlay-arrow-variable-list} to achieve this result. +@c !!! overlay-arrow-position: but the overlay string may remain in the display +@c of some other buffer until an update is required. This should be fixed +@c now. Is it? +@end defvar + + You can do a similar job by creating an overlay with a +@code{before-string} property. @xref{Overlay Properties}. + + You can define multiple overlay arrows via the variable +@code{overlay-arrow-variable-list}. + +@defvar overlay-arrow-variable-list +This variable's value is a list of variables, each of which specifies +the position of an overlay arrow. The variable +@code{overlay-arrow-position} has its normal meaning because it is on +this list. +@end defvar + +Each variable on this list can have properties +@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that +specify an overlay arrow string (for text-only terminals) or fringe +bitmap (for graphical terminals) to display at the corresponding +overlay arrow position. If either property is not set, the default +@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator +is used. + +@node Scroll Bars +@section Scroll Bars +@cindex scroll bars + +Normally the frame parameter @code{vertical-scroll-bars} controls +whether the windows in the frame have vertical scroll bars, and +whether they are on the left or right. The frame parameter +@code{scroll-bar-width} specifies how wide they are (@code{nil} +meaning the default). @xref{Layout Parameters}. + +@defun frame-current-scroll-bars &optional frame +This function reports the scroll bar type settings for frame +@var{frame}. The value is a cons cell +@code{(@var{vertical-type} .@: @var{horizontal-type})}, where +@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} +(which means no scroll bar.) @var{horizontal-type} is meant to +specify the horizontal scroll bar type, but since they are not +implemented, it is always @code{nil}. +@end defun + +@vindex vertical-scroll-bar + You can enable or disable scroll bars for a particular buffer, +by setting the variable @code{vertical-scroll-bar}. This variable +automatically becomes buffer-local when set. The possible values are +@code{left}, @code{right}, @code{t}, which means to use the +frame's default, and @code{nil} for no scroll bar. + + You can also control this for individual windows. Call the function +@code{set-window-scroll-bars} to specify what to do for a specific window: + +@defun set-window-scroll-bars window width &optional vertical-type horizontal-type +This function sets the width and type of scroll bars for window +@var{window}. + +@var{width} specifies the scroll bar width in pixels (@code{nil} means +use the width specified for the frame). @var{vertical-type} specifies +whether to have a vertical scroll bar and, if so, where. The possible +values are @code{left}, @code{right} and @code{nil}, just like the +values of the @code{vertical-scroll-bars} frame parameter. + +The argument @var{horizontal-type} is meant to specify whether and +where to have horizontal scroll bars, but since they are not +implemented, it has no effect. If @var{window} is @code{nil}, the +selected window is used. +@end defun + +@defun window-scroll-bars &optional window +Report the width and type of scroll bars specified for @var{window}. +If @var{window} is omitted or @code{nil}, the selected window is used. +The value is a list of the form @code{(@var{width} +@var{cols} @var{vertical-type} @var{horizontal-type})}. The value +@var{width} is the value that was specified for the width (which may +be @code{nil}); @var{cols} is the number of columns that the scroll +bar actually occupies. + +@var{horizontal-type} is not actually meaningful. +@end defun + +If you don't specify these values for a window with +@code{set-window-scroll-bars}, the buffer-local variables +@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being +displayed control the window's vertical scroll bars. The function +@code{set-window-buffer} examines these variables. If you change them +in a buffer that is already visible in a window, you can make the +window take note of the new values by calling @code{set-window-buffer} +specifying the same buffer that is already displayed. + +@defvar scroll-bar-mode +This variable, always local in all buffers, controls whether and where +to put scroll bars in windows displaying the buffer. The possible values +are @code{nil} for no scroll bar, @code{left} to put a scroll bar on +the left, and @code{right} to put a scroll bar on the right. +@end defvar + +@defun window-current-scroll-bars &optional window +This function reports the scroll bar type for window @var{window}. +If @var{window} is omitted or @code{nil}, the selected window is used. +The value is a cons cell +@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike +@code{window-scroll-bars}, this reports the scroll bar type actually +used, once frame defaults and @code{scroll-bar-mode} are taken into +account. +@end defun + +@defvar scroll-bar-width +This variable, always local in all buffers, specifies the width of the +buffer's scroll bars, measured in pixels. A value of @code{nil} means +to use the value specified by the frame. +@end defvar + +@node Display Property +@section The @code{display} Property +@cindex display specification +@kindex display @r{(text property)} + + The @code{display} text property (or overlay property) is used to +insert images into text, and also control other aspects of how text +displays. The value of the @code{display} property should be a +display specification, or a list or vector containing several display - specifications. Display specifications generally apply in parallel to - the text they cover. ++specifications. Display specifications in the same @code{display} ++property value generally apply in parallel to the text they cover. ++ ++ If several sources (overlays and/or a text property) specify values ++for the @code{display} property, only one of the values takes effect, ++following the rules of @code{get-char-property}. @xref{Examining ++Properties}. ++ ++ The rest of this section describes several kinds of ++display specifications and what they mean. ++ ++@menu ++* Replacing Specs:: Display specs that replace the text. ++* Specified Space:: Displaying one space with a specified width. ++* Pixel Specification:: Specifying space width or height in pixels. ++* Other Display Specs:: Displaying an image; magnifying text; moving it ++ up or down on the page; adjusting the width ++ of spaces within text. ++* Display Margins:: Displaying text or images to the side of the main text. ++@end menu ++ ++@node Replacing Specs ++@subsection Display Specs That Replace The Text + + Some kinds of @code{display} specifications specify something to - display instead of the text that has the property. If a list of - display specifications includes more than one of this kind, the first - is effective and the rest are ignored. You cannot interactively move - point into the middle of the text that is thus replaced. - - For these specifications, ``the text that has the property'' means - all the consecutive characters that have the same Lisp object as their - @code{display} property; these characters are replaced as a single - unit. By contrast, characters that have similar but distinct Lisp - objects as their @code{display} properties are handled separately. - Here's a function that illustrates this point: ++display instead of the text that has the property. These are called ++@dfn{replacing} display specifications. Emacs does not allow the user ++to interactively move point into the middle of buffer text that is ++replaced in this way. ++ ++ If a list of display specifications includes more than one replacing ++display specification, the first overrides the rest. Replacing ++display specifications make most other display specifications ++irrelevant, since those don't apply to the replacement. ++ ++ For replacing display specifications, ``the text that has the ++property'' means all the consecutive characters that have the same ++Lisp object as their @code{display} property; these characters are ++replaced as a single unit. By contrast, characters that have similar ++but distinct Lisp objects as their @code{display} properties are ++handled separately. Here's a function that illustrates this point: + +@smallexample +(defun foo () + (goto-char (point-min)) + (dotimes (i 5) + (let ((string (concat "A"))) + (put-text-property (point) (1+ (point)) 'display string) + (forward-char 1) + (put-text-property (point) (1+ (point)) 'display string) + (forward-char 1)))) +@end smallexample + +@noindent +It gives each of the first ten characters in the buffer string +@code{"A"} as the @code{display} property, but they don't all get the +same string. The first two characters get the same string, so they +together are replaced with one @samp{A}. The next two characters get +a second string, so they together are replaced with one @samp{A}. +Likewise for each following pair of characters. Thus, the ten +characters appear as five A's. This function would have the same +results: + +@smallexample +(defun foo () + (goto-char (point-min)) + (dotimes (i 5) + (let ((string (concat "A"))) + (put-text-property (point) (+ 2 (point)) 'display string) + (put-text-property (point) (1+ (point)) 'display string) + (forward-char 2)))) +@end smallexample + +@noindent +This illustrates that what matters is the property value for +each character. If two consecutive characters have the same +object as the @code{display} property value, it's irrelevant +whether they got this property from a single call to +@code{put-text-property} or from two different calls. + - The rest of this section describes several kinds of - display specifications and what they mean. - - @menu - * Specified Space:: Displaying one space with a specified width. - * Pixel Specification:: Specifying space width or height in pixels. - * Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. - * Display Margins:: Displaying text or images to the side of the main text. - @end menu - +@node Specified Space +@subsection Specified Spaces +@cindex spaces, specified height or width +@cindex variable-width spaces + + To display a space of specified width and/or height, use a display +specification of the form @code{(space . @var{props})}, where +@var{props} is a property list (a list of alternating properties and +values). You can put this property on one or more consecutive +characters; a space of the specified height and width is displayed in +place of @emph{all} of those characters. These are the properties you +can use in @var{props} to specify the weight of the space: + +@table @code +@item :width @var{width} +If @var{width} is an integer or floating point number, it specifies +that the space width should be @var{width} times the normal character +width. @var{width} can also be a @dfn{pixel width} specification +(@pxref{Pixel Specification}). + +@item :relative-width @var{factor} +Specifies that the width of the stretch should be computed from the +first character in the group of consecutive characters that have the +same @code{display} property. The space width is the width of that +character, multiplied by @var{factor}. + +@item :align-to @var{hpos} +Specifies that the space should be wide enough to reach @var{hpos}. +If @var{hpos} is a number, it is measured in units of the normal +character width. @var{hpos} can also be a @dfn{pixel width} +specification (@pxref{Pixel Specification}). +@end table + + You should use one and only one of the above properties. You can +also specify the height of the space, with these properties: + +@table @code +@item :height @var{height} +Specifies the height of the space. +If @var{height} is an integer or floating point number, it specifies +that the space height should be @var{height} times the normal character +height. The @var{height} may also be a @dfn{pixel height} specification +(@pxref{Pixel Specification}). + +@item :relative-height @var{factor} +Specifies the height of the space, multiplying the ordinary height +of the text having this display specification by @var{factor}. + +@item :ascent @var{ascent} +If the value of @var{ascent} is a non-negative number no greater than +100, it specifies that @var{ascent} percent of the height of the space +should be considered as the ascent of the space---that is, the part +above the baseline. The ascent may also be specified in pixel units +with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). + +@end table + + Don't use both @code{:height} and @code{:relative-height} together. + + The @code{:width} and @code{:align-to} properties are supported on +non-graphic terminals, but the other space properties in this section +are not. + +@node Pixel Specification +@subsection Pixel Specification for Spaces +@cindex spaces, pixel specification + + The value of the @code{:width}, @code{:align-to}, @code{:height}, +and @code{:ascent} properties can be a special kind of expression that +is evaluated during redisplay. The result of the evaluation is used +as an absolute number of pixels. + + The following expressions are supported: + +@smallexample +@group + @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} + @var{num} ::= @var{integer} | @var{float} | @var{symbol} + @var{unit} ::= in | mm | cm | width | height +@end group +@group + @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin + | scroll-bar | text + @var{pos} ::= left | center | right + @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) + @var{op} ::= + | - +@end group +@end smallexample + + The form @var{num} specifies a fraction of the default frame font +height or width. The form @code{(@var{num})} specifies an absolute +number of pixels. If @var{num} is a symbol, @var{symbol}, its +buffer-local variable binding is used. + + The @code{in}, @code{mm}, and @code{cm} units specify the number of +pixels per inch, millimeter, and centimeter, respectively. The +@code{width} and @code{height} units correspond to the default width +and height of the current face. An image specification @code{image} +corresponds to the width or height of the image. + + The @code{left-fringe}, @code{right-fringe}, @code{left-margin}, +@code{right-margin}, @code{scroll-bar}, and @code{text} elements +specify to the width of the corresponding area of the window. + + The @code{left}, @code{center}, and @code{right} positions can be +used with @code{:align-to} to specify a position relative to the left +edge, center, or right edge of the text area. + + Any of the above window elements (except @code{text}) can also be +used with @code{:align-to} to specify that the position is relative to +the left edge of the given area. Once the base offset for a relative +position has been set (by the first occurrence of one of these +symbols), further occurrences of these symbols are interpreted as the +width of the specified area. For example, to align to the center of +the left-margin, use + +@example +:align-to (+ left-margin (0.5 . left-margin)) +@end example + + If no specific base offset is set for alignment, it is always relative +to the left edge of the text area. For example, @samp{:align-to 0} in a +header-line aligns with the first text column in the text area. + + A value of the form @code{(@var{num} . @var{expr})} stands for the +product of the values of @var{num} and @var{expr}. For example, +@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . +@var{image})} specifies half the width (or height) of the specified +image. + + The form @code{(+ @var{expr} ...)} adds up the value of the +expressions. The form @code{(- @var{expr} ...)} negates or subtracts +the value of the expressions. + +@node Other Display Specs +@subsection Other Display Specifications + + Here are the other sorts of display specifications that you can use +in the @code{display} text property. + +@table @code +@item @var{string} +Display @var{string} instead of the text that has this property. + +Recursive display specifications are not supported---@var{string}'s +@code{display} properties, if any, are not used. + +@item (image . @var{image-props}) +This kind of display specification is an image descriptor (@pxref{Images}). +When used as a display specification, it means to display the image +instead of the text that has the display specification. + +@item (slice @var{x} @var{y} @var{width} @var{height}) +This specification together with @code{image} specifies a @dfn{slice} +(a partial area) of the image to display. The elements @var{y} and +@var{x} specify the top left corner of the slice, within the image; +@var{width} and @var{height} specify the width and height of the +slice. Integer values are numbers of pixels. A floating point number +in the range 0.0--1.0 stands for that fraction of the width or height +of the entire image. + +@item ((margin nil) @var{string}) +A display specification of this form means to display @var{string} +instead of the text that has the display specification, at the same +position as that text. It is equivalent to using just @var{string}, +but it is done as a special case of marginal display (@pxref{Display +Margins}). + +@item (space-width @var{factor}) +This display specification affects all the space characters within the +text that has the specification. It displays all of these spaces +@var{factor} times as wide as normal. The element @var{factor} should +be an integer or float. Characters other than spaces are not affected +at all; in particular, this has no effect on tab characters. + +@item (height @var{height}) +This display specification makes the text taller or shorter. +Here are the possibilities for @var{height}: + +@table @asis +@item @code{(+ @var{n})} +This means to use a font that is @var{n} steps larger. A ``step'' is +defined by the set of available fonts---specifically, those that match +what was otherwise specified for this text, in all attributes except +height. Each size for which a suitable font is available counts as +another step. @var{n} should be an integer. + +@item @code{(- @var{n})} +This means to use a font that is @var{n} steps smaller. + +@item a number, @var{factor} +A number, @var{factor}, means to use a font that is @var{factor} times +as tall as the default font. + +@item a symbol, @var{function} +A symbol is a function to compute the height. It is called with the +current height as argument, and should return the new height to use. + +@item anything else, @var{form} +If the @var{height} value doesn't fit the previous possibilities, it is +a form. Emacs evaluates it to get the new height, with the symbol +@code{height} bound to the current specified font height. +@end table + +@item (raise @var{factor}) +This kind of display specification raises or lowers the text +it applies to, relative to the baseline of the line. + +@var{factor} must be a number, which is interpreted as a multiple of the +height of the affected text. If it is positive, that means to display +the characters raised. If it is negative, that means to display them +lower down. + +If the text also has a @code{height} display specification, that does +not affect the amount of raising or lowering, which is based on the +faces used for the text. +@end table + +@c We put all the `@code{(when ...)}' on one line to encourage +@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot +@c was at eol; the info file ended up w/ two spaces rendered after it. + You can make any display specification conditional. To do that, +package it in another list of the form +@code{(when @var{condition} . @var{spec})}. +Then the specification @var{spec} applies only when +@var{condition} evaluates to a non-@code{nil} value. During the +evaluation, @code{object} is bound to the string or buffer having the +conditional @code{display} property. @code{position} and +@code{buffer-position} are bound to the position within @code{object} +and the buffer position where the @code{display} property was found, +respectively. Both positions can be different when @code{object} is a +string. + +@node Display Margins +@subsection Displaying in the Margins +@cindex display margins +@cindex margins, display + - A buffer can have blank areas called @dfn{display margins} on the left - and on the right. Ordinary text never appears in these areas, but you - can put things into the display margins using the @code{display} - property. - - To put text in the left or right display margin of the window, use a - display specification of the form @code{(margin right-margin)} or - @code{(margin left-margin)} on it. To put an image in a display margin, - use that display specification along with the display specification for - the image. Unfortunately, there is currently no way to make - text or images in the margin mouse-sensitive. - - If you put such a display specification directly on text in the - buffer, the specified margin display appears @emph{instead of} that - buffer text itself. To put something in the margin @emph{in - association with} certain buffer text without preventing or altering - the display of that text, put a @code{before-string} property on the - text and put the display specification on the contents of the - before-string. ++ A buffer can have blank areas called @dfn{display margins} on the ++left and on the right. Ordinary text never appears in these areas, ++but you can put things into the display margins using the ++@code{display} property. There is currently no way to make text or ++images in the margin mouse-sensitive. ++ ++ The way to display something in the margins is to specify it in a ++margin display specification in the @code{display} property of some ++text. This is a replacing display specification, meaning that the ++text you put it on does not get displayed; the margin display appears, ++but that text does not. ++ ++ A margin display specification looks like @code{((margin ++right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}. ++Here, @var{spec} is another display specification that says what to ++display in the margin. Typically it is a string of text to display, ++or an image descriptor. ++ ++ To display something in the margin @emph{in association with} ++certain buffer text, without altering or preventing the display of ++that text, put a @code{before-string} property on the text and put the ++margin display specification on the contents of the before-string. + + Before the display margins can display anything, you must give +them a nonzero width. The usual way to do that is to set these +variables: + +@defvar left-margin-width +This variable specifies the width of the left margin. +It is buffer-local in all buffers. +@end defvar + +@defvar right-margin-width +This variable specifies the width of the right margin. +It is buffer-local in all buffers. +@end defvar + + Setting these variables does not immediately affect the window. These +variables are checked when a new buffer is displayed in the window. +Thus, you can make changes take effect by calling +@code{set-window-buffer}. + + You can also set the margin widths immediately. + +@defun set-window-margins window left &optional right +This function specifies the margin widths for window @var{window}. +The argument @var{left} controls the left margin and +@var{right} controls the right margin (default @code{0}). +@end defun + +@defun window-margins &optional window +This function returns the left and right margins of @var{window} +as a cons cell of the form @code{(@var{left} . @var{right})}. +If @var{window} is @code{nil}, the selected window is used. +@end defun + +@node Images +@section Images +@cindex images in buffers + + To display an image in an Emacs buffer, you must first create an image +descriptor, then use it as a display specifier in the @code{display} +property of text that is displayed (@pxref{Display Property}). + + Emacs is usually able to display images when it is run on a +graphical terminal. Images cannot be displayed in a text terminal, on +certain graphical terminals that lack the support for this, or if +Emacs is compiled without image support. You can use the function +@code{display-images-p} to determine if images can in principle be +displayed (@pxref{Display Feature Testing}). + +@menu +* Image Formats:: Supported image formats. +* Image Descriptors:: How to specify an image for use in @code{:display}. +* XBM Images:: Special features for XBM format. +* XPM Images:: Special features for XPM format. +* GIF Images:: Special features for GIF format. +* PostScript Images:: Special features for PostScript format. +* Other Image Types:: Various other formats are supported. +* Defining Images:: Convenient ways to define an image for later use. +* Showing Images:: Convenient ways to display an image once it is defined. +* Image Cache:: Internal mechanisms of image display. +@end menu + +@node Image Formats +@subsection Image Formats +@cindex image formats +@cindex image types + + Emacs can display a number of different image formats; some of them +are supported only if particular support libraries are installed on +your machine. In some environments, Emacs can load image +libraries on demand; if so, the variable @code{image-library-alist} +can be used to modify the set of known names for these dynamic +libraries (though it is not possible to add new image formats). + + The supported image formats include XBM, XPM (this requires the +libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring +@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the +@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff} +v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring +@code{librsvg} 2.0.0). + + You specify one of these formats with an image type symbol. The image +type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, +@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. + +@defvar image-types +This variable contains a list of those image type symbols that are +potentially supported in the current configuration. +@emph{Potentially} here means that Emacs knows about the image types, +not necessarily that they can be loaded (they could depend on +unavailable dynamic libraries, for example). + +To know which image types are really available, use +@code{image-type-available-p}. +@end defvar + +@defvar image-library-alist +This in an alist of image types vs external libraries needed to +display them. + +Each element is a list @code{(@var{image-type} @var{library}...)}, +where the car is a supported image format from @code{image-types}, and +the rest are strings giving alternate filenames for the corresponding +external libraries to load. + +Emacs tries to load the libraries in the order they appear on the +list; if none is loaded, the running session of Emacs won't support +the image type. @code{pbm} and @code{xbm} don't need to be listed; +they're always supported. + +This variable is ignored if the image libraries are statically linked +into Emacs. +@end defvar + +@defun image-type-available-p type +This function returns non-@code{nil} if image type @var{type} is +available, i.e., if images of this type can be loaded and displayed in +Emacs. @var{type} should be one of the types contained in +@code{image-types}. + +For image types whose support libraries are statically linked, this +function always returns @code{t}; for other image types, it returns +@code{t} if the dynamic library could be loaded, @code{nil} otherwise. +@end defun + +@node Image Descriptors +@subsection Image Descriptors +@cindex image descriptor + + An image description is a list of the form @code{(image . @var{props})}, +where @var{props} is a property list containing alternating keyword +symbols (symbols whose names start with a colon) and their values. +You can use any Lisp object as a property, but the only properties +that have any special meaning are certain symbols, all of them keywords. + + Every image descriptor must contain the property @code{:type +@var{type}} to specify the format of the image. The value of @var{type} +should be an image type symbol; for example, @code{xpm} for an image in +XPM format. + + Here is a list of other properties that are meaningful for all image +types: + +@table @code +@item :file @var{file} +The @code{:file} property says to load the image from file +@var{file}. If @var{file} is not an absolute file name, it is expanded +in @code{data-directory}. + +@item :data @var{data} +The @code{:data} property says the actual contents of the image. +Each image must use either @code{:data} or @code{:file}, but not both. +For most image types, the value of the @code{:data} property should be a +string containing the image data; we recommend using a unibyte string. + +Before using @code{:data}, look for further information in the section +below describing the specific image format. For some image types, +@code{:data} may not be supported; for some, it allows other data types; +for some, @code{:data} alone is not enough, so you need to use other +image properties along with @code{:data}. + +@item :margin @var{margin} +The @code{:margin} property specifies how many pixels to add as an +extra margin around the image. The value, @var{margin}, must be a +non-negative number, or a pair @code{(@var{x} . @var{y})} of such +numbers. If it is a pair, @var{x} specifies how many pixels to add +horizontally, and @var{y} specifies how many pixels to add vertically. +If @code{:margin} is not specified, the default is zero. + +@item :ascent @var{ascent} +The @code{:ascent} property specifies the amount of the image's +height to use for its ascent---that is, the part above the baseline. +The value, @var{ascent}, must be a number in the range 0 to 100, or +the symbol @code{center}. + +If @var{ascent} is a number, that percentage of the image's height is +used for its ascent. + +If @var{ascent} is @code{center}, the image is vertically centered +around a centerline which would be the vertical centerline of text drawn +at the position of the image, in the manner specified by the text +properties and overlays that apply to the image. + +If this property is omitted, it defaults to 50. + +@item :relief @var{relief} +The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle +around the image. The value, @var{relief}, specifies the width of the +shadow lines, in pixels. If @var{relief} is negative, shadows are drawn +so that the image appears as a pressed button; otherwise, it appears as +an unpressed button. + +@item :conversion @var{algorithm} +The @code{:conversion} property, if non-@code{nil}, specifies a +conversion algorithm that should be applied to the image before it is +displayed; the value, @var{algorithm}, specifies which algorithm. + +@table @code +@item laplace +@itemx emboss +Specifies the Laplace edge detection algorithm, which blurs out small +differences in color while highlighting larger differences. People +sometimes consider this useful for displaying the image for a +``disabled'' button. + +@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) +Specifies a general edge-detection algorithm. @var{matrix} must be +either a nine-element list or a nine-element vector of numbers. A pixel +at position @math{x/y} in the transformed image is computed from +original pixels around that position. @var{matrix} specifies, for each +pixel in the neighborhood of @math{x/y}, a factor with which that pixel +will influence the transformed pixel; element @math{0} specifies the +factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for +the pixel at @math{x/y-1} etc., as shown below: +@iftex +@tex +$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr + x-1/y & x/y & x+1/y \cr + x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ +@end tex +@end iftex +@ifnottex +@display + (x-1/y-1 x/y-1 x+1/y-1 + x-1/y x/y x+1/y + x-1/y+1 x/y+1 x+1/y+1) +@end display +@end ifnottex + +The resulting pixel is computed from the color intensity of the color +resulting from summing up the RGB values of surrounding pixels, +multiplied by the specified factors, and dividing that sum by the sum +of the factors' absolute values. + +Laplace edge-detection currently uses a matrix of +@iftex +@tex +$$\pmatrix{1 & 0 & 0 \cr + 0& 0 & 0 \cr + 9 & 9 & -1 \cr}$$ +@end tex +@end iftex +@ifnottex +@display + (1 0 0 + 0 0 0 + 9 9 -1) +@end display +@end ifnottex + +Emboss edge-detection uses a matrix of +@iftex +@tex +$$\pmatrix{ 2 & -1 & 0 \cr + -1 & 0 & 1 \cr + 0 & 1 & -2 \cr}$$ +@end tex +@end iftex +@ifnottex +@display + ( 2 -1 0 + -1 0 1 + 0 1 -2) +@end display +@end ifnottex + +@item disabled +Specifies transforming the image so that it looks ``disabled.'' +@end table + +@item :mask @var{mask} +If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build +a clipping mask for the image, so that the background of a frame is +visible behind the image. If @var{bg} is not specified, or if @var{bg} +is @code{t}, determine the background color of the image by looking at +the four corners of the image, assuming the most frequently occurring +color from the corners is the background color of the image. Otherwise, +@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} +specifying the color to assume for the background of the image. + +If @var{mask} is @code{nil}, remove a mask from the image, if it has +one. Images in some formats include a mask which can be removed by +specifying @code{:mask nil}. + +@item :pointer @var{shape} +This specifies the pointer shape when the mouse pointer is over this +image. @xref{Pointer Shape}, for available pointer shapes. + +@item :map @var{map} +This associates an image map of @dfn{hot spots} with this image. + +An image map is an alist where each element has the format +@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified +as either a rectangle, a circle, or a polygon. + +A rectangle is a cons +@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} +which specifies the pixel coordinates of the upper left and bottom right +corners of the rectangle area. + +A circle is a cons +@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} +which specifies the center and the radius of the circle; @var{r} may +be a float or integer. + +A polygon is a cons +@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} +where each pair in the vector describes one corner in the polygon. + +When the mouse pointer lies on a hot-spot area of an image, the +@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} +property, that defines a tool-tip for the hot-spot, and if it contains +a @code{pointer} property, that defines the shape of the mouse cursor when +it is on the hot-spot. +@xref{Pointer Shape}, for available pointer shapes. + +When you click the mouse when the mouse pointer is over a hot-spot, an +event is composed by combining the @var{id} of the hot-spot with the +mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's +@var{id} is @code{area4}. +@end table + +@defun image-mask-p spec &optional frame +This function returns @code{t} if image @var{spec} has a mask bitmap. +@var{frame} is the frame on which the image will be displayed. +@var{frame} @code{nil} or omitted means to use the selected frame +(@pxref{Input Focus}). +@end defun + +@node XBM Images +@subsection XBM Images +@cindex XBM + + To use XBM format, specify @code{xbm} as the image type. This image +format doesn't require an external library, so images of this type are +always supported. + + Additional image properties supported for the @code{xbm} image type are: + +@table @code +@item :foreground @var{foreground} +The value, @var{foreground}, should be a string specifying the image +foreground color, or @code{nil} for the default color. This color is +used for each pixel in the XBM that is 1. The default is the frame's +foreground color. + +@item :background @var{background} +The value, @var{background}, should be a string specifying the image +background color, or @code{nil} for the default color. This color is +used for each pixel in the XBM that is 0. The default is the frame's +background color. +@end table + + If you specify an XBM image using data within Emacs instead of an +external file, use the following three properties: + +@table @code +@item :data @var{data} +The value, @var{data}, specifies the contents of the image. +There are three formats you can use for @var{data}: + +@itemize @bullet +@item +A vector of strings or bool-vectors, each specifying one line of the +image. Do specify @code{:height} and @code{:width}. + +@item +A string containing the same byte sequence as an XBM file would contain. +You must not specify @code{:height} and @code{:width} in this case, +because omitting them is what indicates the data has the format of an +XBM file. The file contents specify the height and width of the image. + +@item +A string or a bool-vector containing the bits of the image (plus perhaps +some extra bits at the end that will not be used). It should contain at +least @var{width} * @code{height} bits. In this case, you must specify +@code{:height} and @code{:width}, both to indicate that the string +contains just the bits rather than a whole XBM file, and to specify the +size of the image. +@end itemize + +@item :width @var{width} +The value, @var{width}, specifies the width of the image, in pixels. + +@item :height @var{height} +The value, @var{height}, specifies the height of the image, in pixels. +@end table + +@node XPM Images +@subsection XPM Images +@cindex XPM + + To use XPM format, specify @code{xpm} as the image type. The +additional image property @code{:color-symbols} is also meaningful with +the @code{xpm} image type: + +@table @code +@item :color-symbols @var{symbols} +The value, @var{symbols}, should be an alist whose elements have the +form @code{(@var{name} . @var{color})}. In each element, @var{name} is +the name of a color as it appears in the image file, and @var{color} +specifies the actual color to use for displaying that name. +@end table + +@node GIF Images +@subsection GIF Images +@cindex GIF + + For GIF images, specify image type @code{gif}. + +@table @code +@item :index @var{index} +You can use @code{:index} to specify one image from a GIF file that +contains more than one image. This property specifies use of image +number @var{index} from the file. If the GIF file doesn't contain an +image with index @var{index}, the image displays as a hollow box. +@end table + +@ignore +This could be used to implement limited support for animated GIFs. +For example, the following function displays a multi-image GIF file +at point-min in the current buffer, switching between sub-images +every 0.1 seconds. + +(defun show-anim (file max) + "Display multi-image GIF file FILE which contains MAX subimages." + (display-anim (current-buffer) file 0 max t)) + +(defun display-anim (buffer file idx max first-time) + (when (= idx max) + (setq idx 0)) + (let ((img (create-image file nil :image idx))) + (save-excursion + (set-buffer buffer) + (goto-char (point-min)) + (unless first-time (delete-char 1)) + (insert-image img)) + (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) +@end ignore + +@node PostScript Images +@subsection PostScript Images +@cindex postscript images + + To use PostScript for an image, specify image type @code{postscript}. +This works only if you have Ghostscript installed. You must always use +these three properties: + +@table @code +@item :pt-width @var{width} +The value, @var{width}, specifies the width of the image measured in +points (1/72 inch). @var{width} must be an integer. + +@item :pt-height @var{height} +The value, @var{height}, specifies the height of the image in points +(1/72 inch). @var{height} must be an integer. + +@item :bounding-box @var{box} +The value, @var{box}, must be a list or vector of four integers, which +specifying the bounding box of the PostScript image, analogous to the +@samp{BoundingBox} comment found in PostScript files. + +@example +%%BoundingBox: 22 171 567 738 +@end example +@end table + + Displaying PostScript images from Lisp data is not currently +implemented, but it may be implemented by the time you read this. +See the @file{etc/NEWS} file to make sure. + +@node Other Image Types +@subsection Other Image Types +@cindex PBM + + For PBM images, specify image type @code{pbm}. Color, gray-scale and +monochromatic images are supported. For mono PBM images, two additional +image properties are supported. + +@table @code +@item :foreground @var{foreground} +The value, @var{foreground}, should be a string specifying the image +foreground color, or @code{nil} for the default color. This color is +used for each pixel in the XBM that is 1. The default is the frame's +foreground color. + +@item :background @var{background} +The value, @var{background}, should be a string specifying the image +background color, or @code{nil} for the default color. This color is +used for each pixel in the XBM that is 0. The default is the frame's +background color. +@end table + + For JPEG images, specify image type @code{jpeg}. + + For TIFF images, specify image type @code{tiff}. + + For PNG images, specify image type @code{png}. + + For SVG images, specify image type @code{svg}. + +@node Defining Images +@subsection Defining Images + + The functions @code{create-image}, @code{defimage} and +@code{find-image} provide convenient ways to create image descriptors. + +@defun create-image file-or-data &optional type data-p &rest props +This function creates and returns an image descriptor which uses the +data in @var{file-or-data}. @var{file-or-data} can be a file name or +a string containing the image data; @var{data-p} should be @code{nil} +for the former case, non-@code{nil} for the latter case. + +The optional argument @var{type} is a symbol specifying the image type. +If @var{type} is omitted or @code{nil}, @code{create-image} tries to +determine the image type from the file's first few bytes, or else +from the file's name. + +The remaining arguments, @var{props}, specify additional image +properties---for example, + +@example +(create-image "foo.xpm" 'xpm nil :heuristic-mask t) +@end example + +The function returns @code{nil} if images of this type are not +supported. Otherwise it returns an image descriptor. +@end defun + +@defmac defimage symbol specs &optional doc +This macro defines @var{symbol} as an image name. The arguments +@var{specs} is a list which specifies how to display the image. +The third argument, @var{doc}, is an optional documentation string. + +Each argument in @var{specs} has the form of a property list, and each +one should specify at least the @code{:type} property and either the +@code{:file} or the @code{:data} property. The value of @code{:type} +should be a symbol specifying the image type, the value of +@code{:file} is the file to load the image from, and the value of +@code{:data} is a string containing the actual image data. Here is an +example: + +@example +(defimage test-image + ((:type xpm :file "~/test1.xpm") + (:type xbm :file "~/test1.xbm"))) +@end example + +@code{defimage} tests each argument, one by one, to see if it is +usable---that is, if the type is supported and the file exists. The +first usable argument is used to make an image descriptor which is +stored in @var{symbol}. + +If none of the alternatives will work, then @var{symbol} is defined +as @code{nil}. +@end defmac + +@defun find-image specs +This function provides a convenient way to find an image satisfying one +of a list of image specifications @var{specs}. + +Each specification in @var{specs} is a property list with contents +depending on image type. All specifications must at least contain the +properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} +or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying +the image type, e.g.@: @code{xbm}, @var{file} is the file to load the +image from, and @var{data} is a string containing the actual image data. +The first specification in the list whose @var{type} is supported, and +@var{file} exists, is used to construct the image specification to be +returned. If no specification is satisfied, @code{nil} is returned. + +The image is looked for in @code{image-load-path}. +@end defun + +@defvar image-load-path +This variable's value is a list of locations in which to search for +image files. If an element is a string or a variable symbol whose +value is a string, the string is taken to be the name of a directory +to search. If an element is a variable symbol whose value is a list, +that is taken to be a list of directory names to search. + +The default is to search in the @file{images} subdirectory of the +directory specified by @code{data-directory}, then the directory +specified by @code{data-directory}, and finally in the directories in +@code{load-path}. Subdirectories are not automatically included in +the search, so if you put an image file in a subdirectory, you have to +supply the subdirectory name explicitly. For example, to find the +image @file{images/foo/bar.xpm} within @code{data-directory}, you +should specify the image as follows: + +@example +(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) +@end example +@end defvar + +@defun image-load-path-for-library library image &optional path no-error +This function returns a suitable search path for images used by the +Lisp package @var{library}. + +The function searches for @var{image} first using @code{image-load-path}, +excluding @file{@code{data-directory}/images}, and then in +@code{load-path}, followed by a path suitable for @var{library}, which +includes @file{../../etc/images} and @file{../etc/images} relative to +the library file itself, and finally in +@file{@code{data-directory}/images}. + +Then this function returns a list of directories which contains first +the directory in which @var{image} was found, followed by the value of +@code{load-path}. If @var{path} is given, it is used instead of +@code{load-path}. + +If @var{no-error} is non-@code{nil} and a suitable path can't be +found, don't signal an error. Instead, return a list of directories as +before, except that @code{nil} appears in place of the image directory. + +Here is an example that uses a common idiom to provide compatibility +with versions of Emacs that lack the variable @code{image-load-path}: + +@example +(defvar image-load-path) ; shush compiler +(let* ((load-path (image-load-path-for-library + "mh-e" "mh-logo.xpm")) + (image-load-path (cons (car load-path) + (when (boundp 'image-load-path) + image-load-path)))) + (mh-tool-bar-folder-buttons-init)) +@end example +@end defun + +@node Showing Images +@subsection Showing Images + + You can use an image descriptor by setting up the @code{display} +property yourself, but it is easier to use the functions in this +section. + +@defun insert-image image &optional string area slice +This function inserts @var{image} in the current buffer at point. The +value @var{image} should be an image descriptor; it could be a value +returned by @code{create-image}, or the value of a symbol defined with +@code{defimage}. The argument @var{string} specifies the text to put +in the buffer to hold the image. If it is omitted or @code{nil}, +@code{insert-image} uses @code{" "} by default. + +The argument @var{area} specifies whether to put the image in a margin. +If it is @code{left-margin}, the image appears in the left margin; +@code{right-margin} specifies the right margin. If @var{area} is +@code{nil} or omitted, the image is displayed at point within the +buffer's text. + +The argument @var{slice} specifies a slice of the image to insert. If +@var{slice} is @code{nil} or omitted the whole image is inserted. +Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} +@var{height})} which specifies the @var{x} and @var{y} positions and +@var{width} and @var{height} of the image area to insert. Integer +values are in units of pixels. A floating point number in the range +0.0--1.0 stands for that fraction of the width or height of the entire +image. + +Internally, this function inserts @var{string} in the buffer, and gives +it a @code{display} property which specifies @var{image}. @xref{Display +Property}. +@end defun + +@defun insert-sliced-image image &optional string area rows cols +This function inserts @var{image} in the current buffer at point, like +@code{insert-image}, but splits the image into @var{rows}x@var{cols} +equally sized slices. +@end defun + +@defun put-image image pos &optional string area +This function puts image @var{image} in front of @var{pos} in the +current buffer. The argument @var{pos} should be an integer or a +marker. It specifies the buffer position where the image should appear. +The argument @var{string} specifies the text that should hold the image +as an alternative to the default. + +The argument @var{image} must be an image descriptor, perhaps returned +by @code{create-image} or stored by @code{defimage}. + +The argument @var{area} specifies whether to put the image in a margin. +If it is @code{left-margin}, the image appears in the left margin; +@code{right-margin} specifies the right margin. If @var{area} is +@code{nil} or omitted, the image is displayed at point within the +buffer's text. + +Internally, this function creates an overlay, and gives it a +@code{before-string} property containing text that has a @code{display} +property whose value is the image. (Whew!) +@end defun + +@defun remove-images start end &optional buffer +This function removes images in @var{buffer} between positions +@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, +images are removed from the current buffer. + +This removes only images that were put into @var{buffer} the way +@code{put-image} does it, not images that were inserted with +@code{insert-image} or in other ways. +@end defun + +@defun image-size spec &optional pixels frame +This function returns the size of an image as a pair +@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image +specification. @var{pixels} non-@code{nil} means return sizes +measured in pixels, otherwise return sizes measured in canonical +character units (fractions of the width/height of the frame's default +font). @var{frame} is the frame on which the image will be displayed. +@var{frame} null or omitted means use the selected frame (@pxref{Input +Focus}). +@end defun + +@defvar max-image-size +This variable is used to define the maximum size of image that Emacs +will load. Emacs will refuse to load (and display) any image that is +larger than this limit. + +If the value is an integer, it directly specifies the maximum +image height and width, measured in pixels. If it is a floating +point number, it specifies the maximum image height and width +as a ratio to the frame height and width. If the value is +non-numeric, there is no explicit limit on the size of images. + +The purpose of this variable is to prevent unreasonably large images +from accidentally being loaded into Emacs. It only takes effect the +first time an image is loaded. Once an image is placed in the image +cache, it can always be displayed, even if the value of +@var{max-image-size} is subsequently changed (@pxref{Image Cache}). +@end defvar + +@node Image Cache +@subsection Image Cache +@cindex image cache + + Emacs stores images in an image cache so that it can display them +again more efficiently. When Emacs displays an image, it searches the +image cache for an existing image specification @code{equal} to the +desired specification. If a match is found, the image is displayed +from the cache; otherwise, Emacs loads the image normally. + + Occasionally, you may need to tell Emacs to refresh the images +associated with a given image specification. For example, suppose you +display an image using a specification that contains a @code{:file} +property. The image is loaded from the given file and stored in the +image cache. If you later display the image again, using the same +image specification, the image is displayed from the image cache. +Normally, this is not a problem. However, if the image file has +changed in the meantime, Emacs would be displaying the old version of +the image. In such a situation, it is necessary to ``refresh'' the +image using @code{image-refresh}. + +@defun image-refresh spec &optional frame +This function refreshes any images having image specifications +@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is +@code{nil}, the selected frame is used. If @var{frame} is @code{t}, +the refresh is applied to all existing frames. + +This works by removing all image with image specifications matching +@var{spec} from the image cache. Thus, the next time the image is +displayed, Emacs will load the image again. +@end defun + +@defun clear-image-cache &optional frame +This function clears the entire image cache. If @var{frame} is +non-@code{nil}, only the cache for that frame is cleared. Otherwise, +all frames' caches are cleared. +@end defun + +If an image in the image cache has not been displayed for a specified +period of time, Emacs removes it from the cache and frees the +associated memory. + +@defvar image-cache-eviction-delay +This variable specifies the number of seconds an image can remain in the +cache without being displayed. When an image is not displayed for this +length of time, Emacs removes it from the image cache. + +If the value is @code{nil}, Emacs does not remove images from the cache +except when you explicitly clear it. This mode can be useful for +debugging. +@end defvar + +@node Buttons +@section Buttons +@cindex buttons in buffers +@cindex clickable buttons in buffers + + The @emph{button} package defines functions for inserting and +manipulating clickable (with the mouse, or via keyboard commands) +buttons in Emacs buffers, such as might be used for help hyper-links, +etc. Emacs uses buttons for the hyper-links in help text and the like. + + A button is essentially a set of properties attached (via text +properties or overlays) to a region of text in an Emacs buffer. These +properties are called @dfn{button properties}. + + One of these properties (@code{action}) is a function, which will +be called when the user invokes it using the keyboard or the mouse. +The invoked function may then examine the button and use its other +properties as desired. + + In some ways the Emacs button package duplicates functionality offered +by the widget package (@pxref{Top, , Introduction, widget, The Emacs +Widget Library}), but the button package has the advantage that it is +much faster, much smaller, and much simpler to use (for elisp +programmers---for users, the result is about the same). The extra +speed and space savings are useful mainly if you need to create many +buttons in a buffer (for instance an @code{*Apropos*} buffer uses +buttons to make entries clickable, and may contain many thousands of +entries). + +@menu +* Button Properties:: Button properties with special meanings. +* Button Types:: Defining common properties for classes of buttons. +* Making Buttons:: Adding buttons to Emacs buffers. +* Manipulating Buttons:: Getting and setting properties of buttons. +* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. +@end menu + +@node Button Properties +@subsection Button Properties +@cindex button properties + + Buttons have an associated list of properties defining their +appearance and behavior, and other arbitrary properties may be used +for application specific purposes. Some properties that have special +meaning to the button package include: + +@table @code +@item action +@kindex action @r{(button property)} +The function to call when the user invokes the button, which is passed +the single argument @var{button}. By default this is @code{ignore}, +which does nothing. + +@item mouse-action +@kindex mouse-action @r{(button property)} +This is similar to @code{action}, and when present, will be used +instead of @code{action} for button invocations resulting from +mouse-clicks (instead of the user hitting @key{RET}). If not +present, mouse-clicks use @code{action} instead. + +@item face +@kindex face @r{(button property)} +This is an Emacs face controlling how buttons of this type are +displayed; by default this is the @code{button} face. + +@item mouse-face +@kindex mouse-face @r{(button property)} +This is an additional face which controls appearance during +mouse-overs (merged with the usual button face); by default this is +the usual Emacs @code{highlight} face. + +@item keymap +@kindex keymap @r{(button property)} +The button's keymap, defining bindings active within the button +region. By default this is the usual button region keymap, stored +in the variable @code{button-map}, which defines @key{RET} and +@key{mouse-2} to invoke the button. + +@item type +@kindex type @r{(button property)} +The button-type of the button. When creating a button, this is +usually specified using the @code{:type} keyword argument. +@xref{Button Types}. + +@item help-echo +@kindex help-index @r{(button property)} +A string displayed by the Emacs tool-tip help system; by default, +@code{"mouse-2, RET: Push this button"}. + +@item follow-link +@kindex follow-link @r{(button property)} +The follow-link property, defining how a @key{Mouse-1} click behaves +on this button, @xref{Links and Mouse-1}. + +@item button +@kindex button @r{(button property)} +All buttons have a non-@code{nil} @code{button} property, which may be useful +in finding regions of text that comprise buttons (which is what the +standard button functions do). +@end table + + There are other properties defined for the regions of text in a +button, but these are not generally interesting for typical uses. + +@node Button Types +@subsection Button Types +@cindex button types + + Every button has a button @emph{type}, which defines default values +for the button's properties. Button types are arranged in a +hierarchy, with specialized types inheriting from more general types, +so that it's easy to define special-purpose types of buttons for +specific tasks. + +@defun define-button-type name &rest properties +Define a `button type' called @var{name}. The remaining arguments +form a sequence of @var{property value} pairs, specifying default +property values for buttons with this type (a button's type may be set +by giving it a @code{type} property when creating the button, using +the @code{:type} keyword argument). + +In addition, the keyword argument @code{:supertype} may be used to +specify a button-type from which @var{name} inherits its default +property values. Note that this inheritance happens only when +@var{name} is defined; subsequent changes to a supertype are not +reflected in its subtypes. +@end defun + + Using @code{define-button-type} to define default properties for +buttons is not necessary---buttons without any specified type use the +built-in button-type @code{button}---but it is encouraged, since +doing so usually makes the resulting code clearer and more efficient. + +@node Making Buttons +@subsection Making Buttons +@cindex making buttons + + Buttons are associated with a region of text, using an overlay or +text properties to hold button-specific information, all of which are +initialized from the button's type (which defaults to the built-in +button type @code{button}). Like all Emacs text, the appearance of +the button is governed by the @code{face} property; by default (via +the @code{face} property inherited from the @code{button} button-type) +this is a simple underline, like a typical web-page link. + + For convenience, there are two sorts of button-creation functions, +those that add button properties to an existing region of a buffer, +called @code{make-...button}, and those that also insert the button +text, called @code{insert-...button}. + + The button-creation functions all take the @code{&rest} argument +@var{properties}, which should be a sequence of @var{property value} +pairs, specifying properties to add to the button; see @ref{Button +Properties}. In addition, the keyword argument @code{:type} may be +used to specify a button-type from which to inherit other properties; +see @ref{Button Types}. Any properties not explicitly specified +during creation will be inherited from the button's type (if the type +defines such a property). + + The following functions add a button using an overlay +(@pxref{Overlays}) to hold the button properties: + +@defun make-button beg end &rest properties +This makes a button from @var{beg} to @var{end} in the +current buffer, and returns it. +@end defun + +@defun insert-button label &rest properties +This insert a button with the label @var{label} at point, +and returns it. +@end defun + + The following functions are similar, but use Emacs text properties +(@pxref{Text Properties}) to hold the button properties, making the +button actually part of the text instead of being a property of the +buffer. Buttons using text properties do not create markers into the +buffer, which is important for speed when you use extremely large +numbers of buttons. Both functions return the position of the start +of the new button: + +@defun make-text-button beg end &rest properties +This makes a button from @var{beg} to @var{end} in the current buffer, using +text properties. +@end defun + +@defun insert-text-button label &rest properties +This inserts a button with the label @var{label} at point, using text +properties. +@end defun + +@node Manipulating Buttons +@subsection Manipulating Buttons +@cindex manipulating buttons + +These are functions for getting and setting properties of buttons. +Often these are used by a button's invocation function to determine +what to do. + +Where a @var{button} parameter is specified, it means an object +referring to a specific button, either an overlay (for overlay +buttons), or a buffer-position or marker (for text property buttons). +Such an object is passed as the first argument to a button's +invocation function when it is invoked. + +@defun button-start button +Return the position at which @var{button} starts. +@end defun + +@defun button-end button +Return the position at which @var{button} ends. +@end defun + +@defun button-get button prop +Get the property of button @var{button} named @var{prop}. +@end defun + +@defun button-put button prop val +Set @var{button}'s @var{prop} property to @var{val}. +@end defun + +@defun button-activate button &optional use-mouse-action +Call @var{button}'s @code{action} property (i.e., invoke it). If +@var{use-mouse-action} is non-@code{nil}, try to invoke the button's +@code{mouse-action} property instead of @code{action}; if the button +has no @code{mouse-action} property, use @code{action} as normal. +@end defun + +@defun button-label button +Return @var{button}'s text label. +@end defun + +@defun button-type button +Return @var{button}'s button-type. +@end defun + +@defun button-has-type-p button type +Return @code{t} if @var{button} has button-type @var{type}, or one of +@var{type}'s subtypes. +@end defun + +@defun button-at pos +Return the button at position @var{pos} in the current buffer, or @code{nil}. +@end defun + +@defun button-type-put type prop val +Set the button-type @var{type}'s @var{prop} property to @var{val}. +@end defun + +@defun button-type-get type prop +Get the property of button-type @var{type} named @var{prop}. +@end defun + +@defun button-type-subtype-p type supertype +Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. +@end defun + +@node Button Buffer Commands +@subsection Button Buffer Commands +@cindex button buffer commands + +These are commands and functions for locating and operating on +buttons in an Emacs buffer. + +@code{push-button} is the command that a user uses to actually `push' +a button, and is bound by default in the button itself to @key{RET} +and to @key{mouse-2} using a region-specific keymap. Commands +that are useful outside the buttons itself, such as +@code{forward-button} and @code{backward-button} are additionally +available in the keymap stored in @code{button-buffer-map}; a mode +which uses buttons may want to use @code{button-buffer-map} as a +parent keymap for its keymap. + +If the button has a non-@code{nil} @code{follow-link} property, and +@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click +will also activate the @code{push-button} command. +@xref{Links and Mouse-1}. + +@deffn Command push-button &optional pos use-mouse-action +Perform the action specified by a button at location @var{pos}. +@var{pos} may be either a buffer position or a mouse-event. If +@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a +mouse-event (@pxref{Mouse Events}), try to invoke the button's +@code{mouse-action} property instead of @code{action}; if the button +has no @code{mouse-action} property, use @code{action} as normal. +@var{pos} defaults to point, except when @code{push-button} is invoked +interactively as the result of a mouse-event, in which case, the mouse +event's position is used. If there's no button at @var{pos}, do +nothing and return @code{nil}, otherwise return @code{t}. +@end deffn + +@deffn Command forward-button n &optional wrap display-message +Move to the @var{n}th next button, or @var{n}th previous button if +@var{n} is negative. If @var{n} is zero, move to the start of any +button at point. If @var{wrap} is non-@code{nil}, moving past either +end of the buffer continues from the other end. If +@var{display-message} is non-@code{nil}, the button's help-echo string +is displayed. Any button with a non-@code{nil} @code{skip} property +is skipped over. Returns the button found. +@end deffn + +@deffn Command backward-button n &optional wrap display-message +Move to the @var{n}th previous button, or @var{n}th next button if +@var{n} is negative. If @var{n} is zero, move to the start of any +button at point. If @var{wrap} is non-@code{nil}, moving past either +end of the buffer continues from the other end. If +@var{display-message} is non-@code{nil}, the button's help-echo string +is displayed. Any button with a non-@code{nil} @code{skip} property +is skipped over. Returns the button found. +@end deffn + +@defun next-button pos &optional count-current +@defunx previous-button pos &optional count-current +Return the next button after (for @code{next-button} or before (for +@code{previous-button}) position @var{pos} in the current buffer. If +@var{count-current} is non-@code{nil}, count any button at @var{pos} +in the search, instead of starting at the next button. +@end defun + +@node Abstract Display +@section Abstract Display +@cindex ewoc +@cindex display, abstract +@cindex display, arbitrary objects +@cindex model/view/controller +@cindex view part, model/view/controller + + The Ewoc package constructs buffer text that represents a structure +of Lisp objects, and updates the text to follow changes in that +structure. This is like the ``view'' component in the +``model/view/controller'' design paradigm. + + An @dfn{ewoc} is a structure that organizes information required to +construct buffer text that represents certain Lisp data. The buffer +text of the ewoc has three parts, in order: first, fixed @dfn{header} +text; next, textual descriptions of a series of data elements (Lisp +objects that you specify); and last, fixed @dfn{footer} text. +Specifically, an ewoc contains information on: + +@itemize @bullet +@item +The buffer which its text is generated in. + +@item +The text's start position in the buffer. + +@item +The header and footer strings. + +@item +A doubly-linked chain of @dfn{nodes}, each of which contains: + +@itemize +@item +A @dfn{data element}, a single Lisp object. + +@item +Links to the preceding and following nodes in the chain. +@end itemize + +@item +A @dfn{pretty-printer} function which is responsible for +inserting the textual representation of a data +element value into the current buffer. +@end itemize + + Typically, you define an ewoc with @code{ewoc-create}, and then pass +the resulting ewoc structure to other functions in the Ewoc package to +build nodes within it, and display it in the buffer. Once it is +displayed in the buffer, other functions determine the correspondance +between buffer positions and nodes, move point from one node's textual +representation to another, and so forth. @xref{Abstract Display +Functions}. + + A node @dfn{encapsulates} a data element much the way a variable +holds a value. Normally, encapsulation occurs as a part of adding a +node to the ewoc. You can retrieve the data element value and place a +new value in its place, like so: + +@lisp +(ewoc-data @var{node}) +@result{} value + +(ewoc-set-data @var{node} @var{new-value}) +@result{} @var{new-value} +@end lisp + +@noindent +You can also use, as the data element value, a Lisp object (list or +vector) that is a container for the ``real'' value, or an index into +some other structure. The example (@pxref{Abstract Display Example}) +uses the latter approach. + + When the data changes, you will want to update the text in the +buffer. You can update all nodes by calling @code{ewoc-refresh}, or +just specific nodes using @code{ewoc-invalidate}, or all nodes +satisfying a predicate using @code{ewoc-map}. Alternatively, you can +delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, +and add new nodes in their place. Deleting a node from an ewoc deletes +its associated textual description from buffer, as well. + +@menu +* Abstract Display Functions:: +* Abstract Display Example:: +@end menu + +@node Abstract Display Functions +@subsection Abstract Display Functions + + In this subsection, @var{ewoc} and @var{node} stand for the +structures described above (@pxref{Abstract Display}), while +@var{data} stands for an arbitrary Lisp object used as a data element. + +@defun ewoc-create pretty-printer &optional header footer nosep +This constructs and returns a new ewoc, with no nodes (and thus no data +elements). @var{pretty-printer} should be a function that takes one +argument, a data element of the sort you plan to use in this ewoc, and +inserts its textual description at point using @code{insert} (and never +@code{insert-before-markers}, because that would interfere with the +Ewoc package's internal mechanisms). + +Normally, a newline is automatically inserted after the header, +the footer and every node's textual description. If @var{nosep} +is non-@code{nil}, no newline is inserted. This may be useful for +displaying an entire ewoc on a single line, for example, or for +making nodes ``invisible'' by arranging for @var{pretty-printer} +to do nothing for those nodes. + +An ewoc maintains its text in the buffer that is current when +you create it, so switch to the intended buffer before calling +@code{ewoc-create}. +@end defun + +@defun ewoc-buffer ewoc +This returns the buffer where @var{ewoc} maintains its text. +@end defun + +@defun ewoc-get-hf ewoc +This returns a cons cell @code{(@var{header} . @var{footer})} +made from @var{ewoc}'s header and footer. +@end defun + +@defun ewoc-set-hf ewoc header footer +This sets the header and footer of @var{ewoc} to the strings +@var{header} and @var{footer}, respectively. +@end defun + +@defun ewoc-enter-first ewoc data +@defunx ewoc-enter-last ewoc data +These add a new node encapsulating @var{data}, putting it, respectively, +at the beginning or end of @var{ewoc}'s chain of nodes. +@end defun + +@defun ewoc-enter-before ewoc node data +@defunx ewoc-enter-after ewoc node data +These add a new node encapsulating @var{data}, adding it to +@var{ewoc} before or after @var{node}, respectively. +@end defun + +@defun ewoc-prev ewoc node +@defunx ewoc-next ewoc node +These return, respectively, the previous node and the next node of @var{node} +in @var{ewoc}. +@end defun + +@defun ewoc-nth ewoc n +This returns the node in @var{ewoc} found at zero-based index @var{n}. +A negative @var{n} means count from the end. @code{ewoc-nth} returns +@code{nil} if @var{n} is out of range. +@end defun + +@defun ewoc-data node +This extracts the data encapsulated by @var{node} and returns it. +@end defun + +@defun ewoc-set-data node data +This sets the data encapsulated by @var{node} to @var{data}. +@end defun + +@defun ewoc-locate ewoc &optional pos guess +This determines the node in @var{ewoc} which contains point (or +@var{pos} if specified), and returns that node. If @var{ewoc} has no +nodes, it returns @code{nil}. If @var{pos} is before the first node, +it returns the first node; if @var{pos} is after the last node, it returns +the last node. The optional third arg @var{guess} +should be a node that is likely to be near @var{pos}; this doesn't +alter the result, but makes the function run faster. +@end defun + +@defun ewoc-location node +This returns the start position of @var{node}. +@end defun + +@defun ewoc-goto-prev ewoc arg +@defunx ewoc-goto-next ewoc arg +These move point to the previous or next, respectively, @var{arg}th node +in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at +the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} +moves past the last node, returning @code{nil}. Excepting this special +case, these functions return the node moved to. +@end defun + +@defun ewoc-goto-node ewoc node +This moves point to the start of @var{node} in @var{ewoc}. +@end defun + +@defun ewoc-refresh ewoc +This function regenerates the text of @var{ewoc}. It works by +deleting the text between the header and the footer, i.e., all the +data elements' representations, and then calling the pretty-printer +function for each node, one by one, in order. +@end defun + +@defun ewoc-invalidate ewoc &rest nodes +This is similar to @code{ewoc-refresh}, except that only @var{nodes} in +@var{ewoc} are updated instead of the entire set. +@end defun + +@defun ewoc-delete ewoc &rest nodes +This deletes each node in @var{nodes} from @var{ewoc}. +@end defun + +@defun ewoc-filter ewoc predicate &rest args +This calls @var{predicate} for each data element in @var{ewoc} and +deletes those nodes for which @var{predicate} returns @code{nil}. +Any @var{args} are passed to @var{predicate}. +@end defun + +@defun ewoc-collect ewoc predicate &rest args +This calls @var{predicate} for each data element in @var{ewoc} +and returns a list of those elements for which @var{predicate} +returns non-@code{nil}. The elements in the list are ordered +as in the buffer. Any @var{args} are passed to @var{predicate}. +@end defun + +@defun ewoc-map map-function ewoc &rest args +This calls @var{map-function} for each data element in @var{ewoc} and +updates those nodes for which @var{map-function} returns non-@code{nil}. +Any @var{args} are passed to @var{map-function}. +@end defun + +@node Abstract Display Example +@subsection Abstract Display Example + + Here is a simple example using functions of the ewoc package to +implement a ``color components display,'' an area in a buffer that +represents a vector of three integers (itself representing a 24-bit RGB +value) in various ways. + +@example +(setq colorcomp-ewoc nil + colorcomp-data nil + colorcomp-mode-map nil + colorcomp-labels ["Red" "Green" "Blue"]) + +(defun colorcomp-pp (data) + (if data + (let ((comp (aref colorcomp-data data))) + (insert (aref colorcomp-labels data) "\t: #x" + (format "%02X" comp) " " + (make-string (ash comp -2) ?#) "\n")) + (let ((cstr (format "#%02X%02X%02X" + (aref colorcomp-data 0) + (aref colorcomp-data 1) + (aref colorcomp-data 2))) + (samp " (sample text) ")) + (insert "Color\t: " + (propertize samp 'face `(foreground-color . ,cstr)) + (propertize samp 'face `(background-color . ,cstr)) + "\n")))) + +(defun colorcomp (color) + "Allow fiddling with COLOR in a new buffer. +The buffer is in Color Components mode." + (interactive "sColor (name or #RGB or #RRGGBB): ") + (when (string= "" color) + (setq color "green")) + (unless (color-values color) + (error "No such color: %S" color)) + (switch-to-buffer + (generate-new-buffer (format "originally: %s" color))) + (kill-all-local-variables) + (setq major-mode 'colorcomp-mode + mode-name "Color Components") + (use-local-map colorcomp-mode-map) + (erase-buffer) + (buffer-disable-undo) + (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) + (color-values color)))) + (ewoc (ewoc-create 'colorcomp-pp + "\nColor Components\n\n" + (substitute-command-keys + "\n\\@{colorcomp-mode-map@}")))) + (set (make-local-variable 'colorcomp-data) data) + (set (make-local-variable 'colorcomp-ewoc) ewoc) + (ewoc-enter-last ewoc 0) + (ewoc-enter-last ewoc 1) + (ewoc-enter-last ewoc 2) + (ewoc-enter-last ewoc nil))) +@end example + +@cindex controller part, model/view/controller + This example can be extended to be a ``color selection widget'' (in +other words, the controller part of the ``model/view/controller'' +design paradigm) by defining commands to modify @code{colorcomp-data} +and to ``finish'' the selection process, and a keymap to tie it all +together conveniently. + +@smallexample +(defun colorcomp-mod (index limit delta) + (let ((cur (aref colorcomp-data index))) + (unless (= limit cur) + (aset colorcomp-data index (+ cur delta))) + (ewoc-invalidate + colorcomp-ewoc + (ewoc-nth colorcomp-ewoc index) + (ewoc-nth colorcomp-ewoc -1)))) + +(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) +(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) +(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) +(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) +(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) +(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) + +(defun colorcomp-copy-as-kill-and-exit () + "Copy the color components into the kill ring and kill the buffer. +The string is formatted #RRGGBB (hash followed by six hex digits)." + (interactive) + (kill-new (format "#%02X%02X%02X" + (aref colorcomp-data 0) + (aref colorcomp-data 1) + (aref colorcomp-data 2))) + (kill-buffer nil)) + +(setq colorcomp-mode-map + (let ((m (make-sparse-keymap))) + (suppress-keymap m) + (define-key m "i" 'colorcomp-R-less) + (define-key m "o" 'colorcomp-R-more) + (define-key m "k" 'colorcomp-G-less) + (define-key m "l" 'colorcomp-G-more) + (define-key m "," 'colorcomp-B-less) + (define-key m "." 'colorcomp-B-more) + (define-key m " " 'colorcomp-copy-as-kill-and-exit) + m)) +@end smallexample + +Note that we never modify the data in each node, which is fixed when the +ewoc is created to be either @code{nil} or an index into the vector +@code{colorcomp-data}, the actual color components. + +@node Blinking +@section Blinking Parentheses +@cindex parenthesis matching +@cindex blinking parentheses +@cindex balancing parentheses + + This section describes the mechanism by which Emacs shows a matching +open parenthesis when the user inserts a close parenthesis. + +@defvar blink-paren-function +The value of this variable should be a function (of no arguments) to +be called whenever a character with close parenthesis syntax is inserted. +The value of @code{blink-paren-function} may be @code{nil}, in which +case nothing is done. +@end defvar + +@defopt blink-matching-paren +If this variable is @code{nil}, then @code{blink-matching-open} does +nothing. +@end defopt + +@defopt blink-matching-paren-distance +This variable specifies the maximum distance to scan for a matching +parenthesis before giving up. +@end defopt + +@defopt blink-matching-delay +This variable specifies the number of seconds for the cursor to remain +at the matching parenthesis. A fraction of a second often gives +good results, but the default is 1, which works on all systems. +@end defopt + +@deffn Command blink-matching-open +This function is the default value of @code{blink-paren-function}. It +assumes that point follows a character with close parenthesis syntax and +moves the cursor momentarily to the matching opening character. If that +character is not already on the screen, it displays the character's +context in the echo area. To avoid long delays, this function does not +search farther than @code{blink-matching-paren-distance} characters. + +Here is an example of calling this function explicitly. + +@smallexample +@group +(defun interactive-blink-matching-open () +@c Do not break this line! -- rms. +@c The first line of a doc string +@c must stand alone. + "Indicate momentarily the start of sexp before point." + (interactive) +@end group +@group + (let ((blink-matching-paren-distance + (buffer-size)) + (blink-matching-paren t)) + (blink-matching-open))) +@end group +@end smallexample +@end deffn + +@node Usual Display +@section Usual Display Conventions + + The usual display conventions define how to display each character +code. You can override these conventions by setting up a display table +(@pxref{Display Tables}). Here are the usual display conventions: + +@itemize @bullet +@item +Character codes 32 through 126 map to glyph codes 32 through 126. +Normally this means they display as themselves. + +@item +Character code 9 is a horizontal tab. It displays as whitespace +up to a position determined by @code{tab-width}. + +@item +Character code 10 is a newline. + +@item +All other codes in the range 0 through 31, and code 127, display in one +of two ways according to the value of @code{ctl-arrow}. If it is +non-@code{nil}, these codes map to sequences of two glyphs, where the +first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can +specify a glyph to use instead of @samp{^}.) Otherwise, these codes map +just like the codes in the range 128 to 255. + +On MS-DOS terminals, Emacs arranges by default for the character code +127 to be mapped to the glyph code 127, which normally displays as an +empty polygon. This glyph is used to display non-@acronym{ASCII} characters +that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, +emacs, The GNU Emacs Manual}. + +@item +Character codes 128 through 255 map to sequences of four glyphs, where +the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are +digit characters representing the character code in octal. (A display +table can specify a glyph to use instead of @samp{\}.) + +@item +Multibyte character codes above 256 are displayed as themselves, or as a +question mark or empty box if the terminal cannot display that +character. +@end itemize + + The usual display conventions apply even when there is a display +table, for any character whose entry in the active display table is +@code{nil}. Thus, when you set up a display table, you need only +specify the characters for which you want special behavior. + + These display rules apply to carriage return (character code 13), when +it appears in the buffer. But that character may not appear in the +buffer where you expect it, if it was eliminated as part of end-of-line +conversion (@pxref{Coding System Basics}). + + These variables affect the way certain characters are displayed on the +screen. Since they change the number of columns the characters occupy, +they also affect the indentation functions. These variables also affect +how the mode line is displayed; if you want to force redisplay of the +mode line using the new values, call the function +@code{force-mode-line-update} (@pxref{Mode Line Format}). + +@defopt ctl-arrow +@cindex control characters in display +This buffer-local variable controls how control characters are +displayed. If it is non-@code{nil}, they are displayed as a caret +followed by the character: @samp{^A}. If it is @code{nil}, they are +displayed as a backslash followed by three octal digits: @samp{\001}. +@end defopt + +@c Following may have overfull hbox. +@defvar default-ctl-arrow +The value of this variable is the default value for @code{ctl-arrow} in +buffers that do not override it. @xref{Default Value}. +@end defvar + +@defopt tab-width +The value of this buffer-local variable is the spacing between tab +stops used for displaying tab characters in Emacs buffers. The value +is in units of columns, and the default is 8. Note that this feature +is completely independent of the user-settable tab stops used by the +command @code{tab-to-tab-stop}. @xref{Indent Tabs}. +@end defopt + +@node Display Tables +@section Display Tables + +@cindex display table +You can use the @dfn{display table} feature to control how all possible +character codes display on the screen. This is useful for displaying +European languages that have letters not in the @acronym{ASCII} character +set. + +The display table maps each character code into a sequence of +@dfn{glyphs}, each glyph being a graphic that takes up one character +position on the screen. You can also define how to display each glyph +on your terminal, using the @dfn{glyph table}. + +Display tables affect how the mode line is displayed; if you want to +force redisplay of the mode line using a new display table, call +@code{force-mode-line-update} (@pxref{Mode Line Format}). + +@menu +* Display Table Format:: What a display table consists of. +* Active Display Table:: How Emacs selects a display table to use. +* Glyphs:: How to define a glyph, and what glyphs mean. +@end menu + +@node Display Table Format +@subsection Display Table Format + + A display table is actually a char-table (@pxref{Char-Tables}) with +@code{display-table} as its subtype. + +@defun make-display-table +This creates and returns a display table. The table initially has +@code{nil} in all elements. +@end defun + + The ordinary elements of the display table are indexed by character +codes; the element at index @var{c} says how to display the character +code @var{c}. The value should be @code{nil} or a vector of the +glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the +character @var{c} according to the usual display conventions +(@pxref{Usual Display}). + + @strong{Warning:} if you use the display table to change the display +of newline characters, the whole buffer will be displayed as one long +``line.'' + + The display table also has six ``extra slots'' which serve special +purposes. Here is a table of their meanings; @code{nil} in any slot +means to use the default for that slot, as stated below. + +@table @asis +@item 0 +The glyph for the end of a truncated screen line (the default for this +is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses +arrows in the fringes to indicate truncation, so the display table has +no effect. + +@item 1 +The glyph for the end of a continued line (the default is @samp{\}). +On graphical terminals, Emacs uses curved arrows in the fringes to +indicate continuation, so the display table has no effect. + +@item 2 +The glyph for indicating a character displayed as an octal character +code (the default is @samp{\}). + +@item 3 +The glyph for indicating a control character (the default is @samp{^}). + +@item 4 +A vector of glyphs for indicating the presence of invisible lines (the +default is @samp{...}). @xref{Selective Display}. + +@item 5 +The glyph used to draw the border between side-by-side windows (the +default is @samp{|}). @xref{Splitting Windows}. This takes effect only +when there are no scroll bars; if scroll bars are supported and in use, +a scroll bar separates the two windows. +@end table + + For example, here is how to construct a display table that mimics the +effect of setting @code{ctl-arrow} to a non-@code{nil} value: + +@example +(setq disptab (make-display-table)) +(let ((i 0)) + (while (< i 32) + (or (= i ?\t) (= i ?\n) + (aset disptab i (vector ?^ (+ i 64)))) + (setq i (1+ i))) + (aset disptab 127 (vector ?^ ??))) +@end example + +@defun display-table-slot display-table slot +This function returns the value of the extra slot @var{slot} of +@var{display-table}. The argument @var{slot} may be a number from 0 to +5 inclusive, or a slot name (symbol). Valid symbols are +@code{truncation}, @code{wrap}, @code{escape}, @code{control}, +@code{selective-display}, and @code{vertical-border}. +@end defun + +@defun set-display-table-slot display-table slot value +This function stores @var{value} in the extra slot @var{slot} of +@var{display-table}. The argument @var{slot} may be a number from 0 to +5 inclusive, or a slot name (symbol). Valid symbols are +@code{truncation}, @code{wrap}, @code{escape}, @code{control}, +@code{selective-display}, and @code{vertical-border}. +@end defun + +@defun describe-display-table display-table +This function displays a description of the display table +@var{display-table} in a help buffer. +@end defun + +@deffn Command describe-current-display-table +This command displays a description of the current display table in a +help buffer. +@end deffn + +@node Active Display Table +@subsection Active Display Table +@cindex active display table + + Each window can specify a display table, and so can each buffer. When +a buffer @var{b} is displayed in window @var{w}, display uses the +display table for window @var{w} if it has one; otherwise, the display +table for buffer @var{b} if it has one; otherwise, the standard display +table if any. The display table chosen is called the @dfn{active} +display table. + +@defun window-display-table &optional window +This function returns @var{window}'s display table, or @code{nil} +if @var{window} does not have an assigned display table. The default +for @var{window} is the selected window. +@end defun + +@defun set-window-display-table window table +This function sets the display table of @var{window} to @var{table}. +The argument @var{table} should be either a display table or +@code{nil}. +@end defun + +@defvar buffer-display-table +This variable is automatically buffer-local in all buffers; its value in +a particular buffer specifies the display table for that buffer. If it +is @code{nil}, that means the buffer does not have an assigned display +table. +@end defvar + +@defvar standard-display-table +This variable's value is the default display table, used whenever a +window has no display table and neither does the buffer displayed in +that window. This variable is @code{nil} by default. +@end defvar + + If there is no display table to use for a particular window---that is, +if the window specifies none, its buffer specifies none, and +@code{standard-display-table} is @code{nil}---then Emacs uses the usual +display conventions for all character codes in that window. @xref{Usual +Display}. + +A number of functions for changing the standard display table +are defined in the library @file{disp-table}. + +@node Glyphs +@subsection Glyphs + +@cindex glyph + A @dfn{glyph} is a generalization of a character; it stands for an +image that takes up a single character position on the screen. Normally +glyphs come from vectors in the display table (@pxref{Display Tables}). + + A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code +can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A +simple glyph code is just a way of specifying a character and a face +to output it in. @xref{Faces}. + + The following functions are used to manipulate simple glyph codes: + +@defun make-glyph-code char &optional face +This function returns a simple glyph code representing char @var{char} +with face @var{face}. +@end defun + +@defun glyph-char glyph +This function returns the character of simple glyph code @var{glyph}. +@end defun + +@defun glyph-face glyph +This function returns face of simple glyph code @var{glyph}, or +@code{nil} if @var{glyph} has the default face (face-id 0). +@end defun + + On character terminals, you can set up a @dfn{glyph table} to define +the meaning of glyph codes (represented as small integers). + +@defvar glyph-table +The value of this variable is the current glyph table. It should be +@code{nil} or a vector whose @var{g}th element defines glyph code +@var{g}. + +If a glyph code is greater than or equal to the length of the glyph +table, that code is automatically simple. If @code{glyph-table} is +@code{nil} then all glyph codes are simple. + +The glyph table is used only on character terminals. On graphical +displays, all glyph codes are simple. +@end defvar + + Here are the meaningful types of elements in the glyph table: + +@table @asis +@item @var{string} +Send the characters in @var{string} to the terminal to output +this glyph code. + +@item @var{code} +Define this glyph code as an alias for glyph code @var{code} created +by @code{make-glyph-code}. You can use such an alias to define a +small-numbered glyph code which specifies a character with a face. + +@item @code{nil} +This glyph code is simple. +@end table + +@defun create-glyph string +This function returns a newly-allocated glyph code which is set up to +display by sending @var{string} to the terminal. +@end defun + +@node Beeping +@section Beeping +@c @cindex beeping "beep" is adjacent +@cindex bell + + This section describes how to make Emacs ring the bell (or blink the +screen) to attract the user's attention. Be conservative about how +often you do this; frequent bells can become irritating. Also be +careful not to use just beeping when signaling an error is more +appropriate. (@xref{Errors}.) + +@defun ding &optional do-not-terminate +@cindex keyboard macro termination +This function beeps, or flashes the screen (see @code{visible-bell} below). +It also terminates any keyboard macro currently executing unless +@var{do-not-terminate} is non-@code{nil}. +@end defun + +@defun beep &optional do-not-terminate +This is a synonym for @code{ding}. +@end defun + +@defopt visible-bell +This variable determines whether Emacs should flash the screen to +represent a bell. Non-@code{nil} means yes, @code{nil} means no. This +is effective on graphical displays, and on text-only terminals +provided the terminal's Termcap entry defines the visible bell +capability (@samp{vb}). +@end defopt + +@defvar ring-bell-function +If this is non-@code{nil}, it specifies how Emacs should ``ring the +bell.'' Its value should be a function of no arguments. If this is +non-@code{nil}, it takes precedence over the @code{visible-bell} +variable. +@end defvar + +@node Window Systems +@section Window Systems + + Emacs works with several window systems, most notably the X Window +System. Both Emacs and X use the term ``window,'' but use it +differently. An Emacs frame is a single window as far as X is +concerned; the individual Emacs windows are not known to X at all. + +@defvar window-system +This variable tells Lisp programs what window system Emacs is running +under. The possible values are + +@table @code +@item x +@cindex X Window System +Emacs is displaying using X. +@item pc +Emacs is displaying using MS-DOS. +@item w32 +Emacs is displaying using Windows. +@item mac +Emacs is displaying using a Macintosh. +@item nil +Emacs is using a character-based terminal. +@end table +@end defvar + +@defvar window-setup-hook +This variable is a normal hook which Emacs runs after handling the +initialization files. Emacs runs this hook after it has completed +loading your init file, the default initialization file (if +any), and the terminal-specific Lisp code, and running the hook +@code{term-setup-hook}. + +This hook is used for internal purposes: setting up communication with +the window system, and creating the initial window. Users should not +interfere with it. +@end defvar + +@ignore + arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6 +@end ignore diff --cc doc/lispref/elisp.texi index f9d11a5dd1f,00000000000..8cd25ed59d3 mode 100644,000000..100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@@ -1,1483 -1,0 +1,1484 @@@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename elisp +@settitle GNU Emacs Lisp Reference Manual +@c %**end of header + +@c Version of the manual and of Emacs. +@c Please remember to update the edition number in README as well. +@set VERSION 2.9 +@set EMACSVER 23.0.50 + +@c in general, keep the following line commented out, unless doing a +@c copy of this manual that will be published. The manual should go +@c onto the distribution in the full, 8.5 x 11" size. +@c set smallbook + +@ifset smallbook +@smallbook +@end ifset + +@c per rms and peterb, use 10pt fonts for the main text, mostly to +@c save on paper cost. +@c Do this inside @tex for now, so current makeinfo does not complain. +@tex +@ifset smallbook +@fonttextsize 10 +@set EMACSVER 22.1 +\global\let\urlcolor=\Black % don't print links in grayscale +\global\let\linkcolor=\Black +@end ifset +\global\hbadness=6666 % don't worry about not-too-underfull boxes +@end tex + +@c Combine indices. +@synindex cp fn +@syncodeindex vr fn +@syncodeindex ky fn +@syncodeindex pg fn +@c We use the "type index" to index new functions and variables. +@c @syncodeindex tp fn + +@copying +This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* +corresponding to Emacs version @value{EMACSVER}. + +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, +1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software +Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License,'' with the +Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover +Texts as in (a) below. A copy of the license is included in the +section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Elisp: (elisp). The Emacs Lisp Reference Manual. +@end direntry + +@titlepage +@title GNU Emacs Lisp Reference Manual +@subtitle For Emacs Version @value{EMACSVER} +@subtitle Revision @value{VERSION}, April 2007 + +@author by Bil Lewis, Dan LaLiberte, Richard Stallman +@author and the GNU Manual Group +@page +@vskip 0pt plus 1filll +@insertcopying + +@sp 2 +Published by the Free Software Foundation @* +51 Franklin St, Fifth Floor @* +Boston, MA 02110-1301 @* +USA @* +ISBN 1-882114-74-4 + +@sp 2 +Cover art by Etienne Suvasa. +@end titlepage + + +@c Print the tables of contents +@summarycontents +@contents + + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Emacs Lisp + +This Info file contains edition @value{VERSION} of the GNU Emacs Lisp +Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. +@end ifnottex + +@menu +* Introduction:: Introduction and conventions used. + +* Lisp Data Types:: Data types of objects in Emacs Lisp. +* Numbers:: Numbers and arithmetic functions. +* Strings and Characters:: Strings, and functions that work on them. +* Lists:: Lists, cons cells, and related functions. +* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. + Certain functions act on any kind of sequence. + The description of vectors is here as well. +* Hash Tables:: Very fast lookup-tables. +* Symbols:: Symbols represent names, uniquely. + +* Evaluation:: How Lisp expressions are evaluated. +* Control Structures:: Conditionals, loops, nonlocal exits. +* Variables:: Using symbols in programs to stand for values. +* Functions:: A function is a Lisp program + that can be invoked from other functions. +* Macros:: Macros are a way to extend the Lisp language. +* Customization:: Writing customization declarations. + +* Loading:: Reading files of Lisp code into Lisp. +* Byte Compilation:: Compilation makes programs run faster. +* Advising Functions:: Adding to the definition of a function. +* Debugging:: Tools and tips for debugging Lisp programs. + +* Read and Print:: Converting Lisp objects to text and back. +* Minibuffers:: Using the minibuffer to read input. +* Command Loop:: How the editor command loop works, + and how you can call its subroutines. +* Keymaps:: Defining the bindings from keys to commands. +* Modes:: Defining major and minor modes. +* Documentation:: Writing and using documentation strings. + +* Files:: Accessing files. +* Backups and Auto-Saving:: Controlling how backups and auto-save + files are made. +* Buffers:: Creating and using buffer objects. +* Windows:: Manipulating windows and displaying buffers. +* Frames:: Making multiple system-level windows. +* Positions:: Buffer positions and motion functions. +* Markers:: Markers represent positions and update + automatically when the text is changed. + +* Text:: Examining and changing text in buffers. +* Non-ASCII Characters:: Non-ASCII text in buffers and strings. +* Searching and Matching:: Searching buffers for strings or regexps. +* Syntax Tables:: The syntax table controls word and list parsing. +* Abbrevs:: How Abbrev mode works, and its data structures. + +* Processes:: Running and communicating with subprocesses. +* Display:: Features for controlling the screen display. +* System Interface:: Getting the user id, system type, environment + variables, and other such things. + +Appendices + +* Antinews:: Info for users downgrading to Emacs 21. +* GNU Free Documentation License:: The license for this documentation +* GPL:: Conditions for copying and changing GNU Emacs. +* Tips:: Advice and coding conventions for Emacs Lisp. +* GNU Emacs Internals:: Building and dumping Emacs; + internal data structures. +* Standard Errors:: List of all error symbols. +* Standard Buffer-Local Variables:: + List of variables buffer-local in all buffers. +* Standard Keymaps:: List of standard keymaps. +* Standard Hooks:: List of standard hook variables. + +* Index:: Index including concepts, functions, variables, + and other terms. + +@ignore +* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. +@end ignore + +@c Do NOT modify the following 3 lines! They must have this form to +@c be correctly identified by `texinfo-multiple-files-update'. In +@c particular, the detailed menu header line MUST be identical to the +@c value of `texinfo-master-menu-header'. See texnfo-upd.el. + +@detailmenu + --- The Detailed Node Listing --- + --------------------------------- + +Here are other nodes that are inferiors of those already listed, +mentioned here so you can get to them in one step: + +Introduction + +* Caveats:: Flaws and a request for help. +* Lisp History:: Emacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Version Info:: Which Emacs version is running? +* Acknowledgements:: The authors, editors, and sponsors of this manual. + +Conventions + +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols @code{nil} and @code{t} are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use for examples that print output. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. + +Format of Descriptions + +* A Sample Function Description:: A description of an imaginary + function, @code{foo}. +* A Sample Variable Description:: A description of an imaginary + variable, @code{electric-future-map}. + +Lisp Data Types + +* Printed Representation:: How Lisp objects are represented as text. +* Comments:: Comments and their formatting conventions. +* Programming Types:: Types found in all Lisp systems. +* Editing Types:: Types specific to Emacs. +* Circular Objects:: Read syntax for circular structure. +* Type Predicates:: Tests related to types. +* Equality Predicates:: Tests of equality between any two objects. + +Programming Types + +* Integer Type:: Numbers without fractional parts. +* Floating Point Type:: Numbers with fractional parts and with a large range. +* Character Type:: The representation of letters, numbers and + control characters. +* Symbol Type:: A multi-use object that refers to a function, + variable, property list, or itself. +* Sequence Type:: Both lists and arrays are classified as sequences. +* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). +* Array Type:: Arrays include strings and vectors. +* String Type:: An (efficient) array of characters. +* Vector Type:: One-dimensional arrays. +* Char-Table Type:: One-dimensional sparse arrays indexed by characters. +* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. +* Hash Table Type:: Super-fast lookup tables. +* Function Type:: A piece of executable code you can call from elsewhere. +* Macro Type:: A method of expanding an expression into another + expression, more fundamental but less pretty. +* Primitive Function Type:: A function written in C, callable from Lisp. +* Byte-Code Type:: A function written in Lisp, then compiled. +* Autoload Type:: A type used for automatically loading seldom-used + functions. + +Character Type + +* Basic Char Syntax:: Syntax for regular characters. +* General Escape Syntax:: How to specify characters by their codes. +* Ctl-Char Syntax:: Syntax for control characters. +* Meta-Char Syntax:: Syntax for meta-characters. +* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. + +Cons Cell and List Types + +* Box Diagrams:: Drawing pictures of lists. +* Dotted Pair Notation:: An alternative syntax for lists. +* Association List Type:: A specially constructed list. + +String Type + +* Syntax for Strings:: How to specify Lisp strings. +* Non-ASCII in Strings:: International characters in strings. +* Nonprinting Characters:: Literal unprintable characters in strings. +* Text Props and Strings:: Strings with text properties. + +Editing Types + +* Buffer Type:: The basic object of editing. +* Marker Type:: A position in a buffer. +* Window Type:: What makes buffers visible. +* Frame Type:: Windows subdivide frames. +* Window Configuration Type:: Recording the way a frame is subdivided. +* Frame Configuration Type:: Recording the status of all frames. +* Process Type:: A process running on the underlying OS. +* Stream Type:: Receive or send characters. +* Keymap Type:: What function a keystroke invokes. +* Overlay Type:: How an overlay is represented. + +Numbers + +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Numeric Conversions:: Converting float to integer and vice versa. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Rounding Operations:: Explicitly rounding floating point numbers. +* Bitwise Operations:: Logical and, or, not, shifting. +* Math Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. + +Strings and Characters + +* String Basics:: Basic properties of strings and characters. +* Predicates for Strings:: Testing whether an object is a string or char. +* Creating Strings:: Functions to allocate new strings. +* Modifying Strings:: Altering the contents of an existing string. +* Text Comparison:: Comparing characters or strings. +* String Conversion:: Converting characters to strings and vice versa. +* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. +* Case Conversion:: Case conversion functions. +* Case Tables:: Customizing case conversion. + +Lists + +* Cons Cells:: How lists are made out of cons cells. +* List-related Predicates:: Is this object a list? Comparing two lists. +* List Elements:: Extracting the pieces of a list. +* Building Lists:: Creating list structure. +* List Variables:: Modifying lists stored in variables. +* Modifying Lists:: Storing new pieces into an existing list. +* Sets And Lists:: A list can represent a finite mathematical set. +* Association Lists:: A list can represent a finite relation or mapping. +* Rings:: Managing a fixed-size ring of objects. + +Modifying Existing List Structure + +* Setcar:: Replacing an element in a list. +* Setcdr:: Replacing part of the list backbone. + This can be used to remove or add elements. +* Rearrangement:: Reordering the elements in a list; combining lists. + +Sequences, Arrays, and Vectors + +* Sequence Functions:: Functions that accept any kind of sequence. +* Arrays:: Characteristics of arrays in Emacs Lisp. +* Array Functions:: Functions specifically for arrays. +* Vectors:: Special characteristics of Emacs Lisp vectors. +* Vector Functions:: Functions specifically for vectors. +* Char-Tables:: How to work with char-tables. +* Bool-Vectors:: How to work with bool-vectors. + +Hash Tables + +* Creating Hash:: Functions to create hash tables. +* Hash Access:: Reading and writing the hash table contents. +* Defining Hash:: Defining new comparison methods +* Other Hash:: Miscellaneous. + +Symbols + +* Symbol Components:: Symbols have names, values, function definitions + and property lists. +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Property Lists:: Each symbol has a property list + for recording miscellaneous information. + +Property Lists + +* Plists and Alists:: Comparison of the advantages of property + lists and association lists. +* Symbol Plists:: Functions to access symbols' property lists. +* Other Plists:: Accessing property lists stored elsewhere. + +Evaluation + +* Intro Eval:: Evaluation in the scheme of things. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in + the program). +* Eval:: How to invoke the Lisp interpreter explicitly. + +Kinds of Forms + +* Self-Evaluating Forms:: Forms that evaluate to themselves. +* Symbol Forms:: Symbols evaluate as variables. +* Classifying Lists:: How to distinguish various sorts of list forms. +* Function Indirection:: When a symbol appears as the car of a list, + we find the real function via the symbol. +* Function Forms:: Forms that call functions. +* Macro Forms:: Forms that call macros. +* Special Forms:: "Special forms" are idiosyncratic primitives, + most of them extremely important. +* Autoloading:: Functions set up to load files + containing their real definitions. + +Control Structures + +* Sequencing:: Evaluation in textual order. +* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. +* Combining Conditions:: @code{and}, @code{or}, @code{not}. +* Iteration:: @code{while} loops. +* Nonlocal Exits:: Jumping out of a sequence. + +Nonlocal Exits + +* Catch and Throw:: Nonlocal exits for the program's own purposes. +* Examples of Catch:: Showing how such nonlocal exits can be written. +* Errors:: How errors are signaled and handled. +* Cleanups:: Arranging to run a cleanup form if an + error happens. + +Errors + +* Signaling Errors:: How to report an error. +* Processing of Errors:: What Emacs does when you report an error. +* Handling Errors:: How you can trap errors and continue execution. +* Error Symbols:: How errors are classified for trapping them. +* Standard Errors:: List of all error symbols. + +Variables + +* Global Variables:: Variable values that exist permanently, everywhere. +* Constant Variables:: Certain "variables" have values that never change. +* Local Variables:: Variable values that exist only temporarily. +* Void Variables:: Symbols that lack values. +* Defining Variables:: A definition says a symbol is used as a variable. +* Tips for Defining:: Things you should think about when you + define a variable. +* Accessing Variables:: Examining values of variables whose names + are known only at run time. +* Setting Variables:: Storing new values in variables. +* Variable Scoping:: How Lisp chooses among local and global values. +* Buffer-Local Variables:: Variable values in effect only in one buffer. +* Frame-Local Variables:: Variable values in effect only in one frame. +* Future Local Variables:: New kinds of local values we might add some day. +* File Local Variables:: Handling local variable lists in files. +* Variable Aliases:: Variables that are aliases for other variables. +* Variables with Restricted Values:: Non-constant variables whose value can + @emph{not} be an arbitrary Lisp object. +* Standard Buffer-Local Variables:: + List of variables buffer-local in all buffers. + +Scoping Rules for Variable Bindings + +* Scope:: Scope means where in the program a value + is visible. Comparison with other languages. +* Extent:: Extent means how long in time a value exists. +* Impl of Scope:: Two ways to implement dynamic scoping. +* Using Scoping:: How to use dynamic scoping carefully and + avoid problems. + +Buffer-Local Variables + +* Intro to Buffer-Local:: Introduction and concepts. +* Creating Buffer-Local:: Creating and destroying buffer-local bindings. +* Default Value:: The default value is seen in buffers + that don't have their own buffer-local values. + +Functions + +* What Is a Function:: Lisp functions vs primitives; terminology. +* Lambda Expressions:: How functions are expressed as Lisp objects. +* Function Names:: A symbol can serve as the name of a function. +* Defining Functions:: Lisp expressions for defining functions. +* Calling Functions:: How to use an existing function. +* Mapping Functions:: Applying a function to each element of a list, etc. +* Anonymous Functions:: Lambda-expressions are functions with no names. +* Function Cells:: Accessing or setting the function definition + of a symbol. +* Obsolete Functions:: Declaring functions obsolete. +* Inline Functions:: Defining functions that the compiler will open code. +* Function Safety:: Determining whether a function is safe to call. +* Related Topics:: Cross-references to specific Lisp primitives + that have a special bearing on how + functions work. + +Lambda Expressions + +* Lambda Components:: The parts of a lambda expression. +* Simple Lambda:: A simple example. +* Argument List:: Details and special features of argument lists. +* Function Documentation:: How to put documentation in a function. + +Macros + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. +* Indenting Macros:: Specifying how to indent macro calls. + +Common Problems Using Macros + +* Wrong Time:: Do the work in the expansion, not in the macro. +* Argument Evaluation:: The expansion should evaluate each macro arg once. +* Surprising Local Vars:: Local variable bindings in the expansion + require special care. +* Eval During Expansion:: Don't evaluate them; put them in the expansion. +* Repeated Expansion:: Avoid depending on how many times expansion is done. + +Writing Customization Definitions + +* Common Keywords:: Common keyword arguments for all kinds of + customization declarations. +* Group Definitions:: Writing customization group definitions. +* Variable Definitions:: Declaring user options. +* Customization Types:: Specifying the type of a user option. + +Customization Types + +* Simple Types:: Simple customization types: sexp, integer, number, + string, file, directory, alist. +* Composite Types:: Build new types from other types or data. +* Splicing into Lists:: Splice elements into list with @code{:inline}. +* Type Keywords:: Keyword-argument pairs in a customization type. +* Defining New Types:: Give your type a name. + +Loading + +* How Programs Do Loading:: The @code{load} function and others. +* Load Suffixes:: Details about the suffixes that @code{load} tries. +* Library Search:: Finding a library to load. +* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. +* Autoload:: Setting up a function to autoload. +* Repeated Loading:: Precautions about loading a file twice. +* Named Features:: Loading a library if it isn't already loaded. +* Where Defined:: Finding which file defined a certain symbol. +* Unloading:: How to "unload" a library that was loaded. +* Hooks for Loading:: Providing code to be run when + particular libraries are loaded. + +Byte Compilation + +* Speed of Byte-Code:: An example of speedup from byte compilation. +* Compilation Functions:: Byte compilation functions. +* Docs and Compilation:: Dynamic loading of documentation strings. +* Dynamic Loading:: Dynamic loading of individual functions. +* Eval During Compile:: Code to be evaluated when you compile. +* Compiler Errors:: Handling compiler error messages. +* Byte-Code Objects:: The data type used for byte-compiled functions. +* Disassembly:: Disassembling byte-code; how to read byte-code. + +Advising Emacs Lisp Functions + +* Simple Advice:: A simple example to explain the basics of advice. +* Defining Advice:: Detailed description of @code{defadvice}. +* Around-Advice:: Wrapping advice around a function's definition. +* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. +* Activation of Advice:: Advice doesn't do anything until you activate it. +* Enabling Advice:: You can enable or disable each piece of advice. +* Preactivation:: Preactivation is a way of speeding up the + loading of compiled advice. +* Argument Access in Advice:: How advice can access the function's arguments. +* Advising Primitives:: Accessing arguments when advising a primitive. +* Combined Definition:: How advice is implemented. + +Debugging Lisp Programs + +* Debugger:: How the Emacs Lisp debugger is implemented. +* Edebug:: A source-level Emacs Lisp debugger. +* Syntax Errors:: How to find syntax errors. +* Test Coverage:: Ensuring you have tested all branches in your code. +* Compilation Errors:: How to find errors that show up in + byte compilation. + +The Lisp Debugger + +* Error Debugging:: Entering the debugger when an error happens. +* Infinite Loops:: Stopping and debugging a program that doesn't exit. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function @code{debug}. +* Internals of Debugger:: Subroutines of the debugger, and global variables. + +Edebug + +* Using Edebug:: Introduction to use of Edebug. +* Instrumenting:: You must instrument your code + in order to debug it with Edebug. +* Edebug Execution Modes:: Execution modes, stopping more or less often. +* Jumping:: Commands to jump to a specified place. +* Edebug Misc:: Miscellaneous commands. +* Breaks:: Setting breakpoints to make the program stop. +* Trapping Errors:: Trapping errors with Edebug. +* Edebug Views:: Views inside and outside of Edebug. +* Edebug Eval:: Evaluating expressions within Edebug. +* Eval List:: Expressions whose values are displayed + each time you enter Edebug. +* Printing in Edebug:: Customization of printing. +* Trace Buffer:: How to produce trace output in a buffer. +* Coverage Testing:: How to test evaluation coverage. +* The Outside Context:: Data that Edebug saves and restores. +* Edebug and Macros:: Specifying how to handle macro calls. +* Edebug Options:: Option variables for customizing Edebug. + +Debugging Invalid Lisp Syntax + +* Excess Open:: How to find a spurious open paren or missing close. +* Excess Close:: How to find a spurious close paren or missing open. + +Reading and Printing Lisp Objects + +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as + input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as + output streams. +* Output Functions:: Functions to print Lisp objects as text. +* Output Variables:: Variables that control what the printing + functions do. + +Minibuffers + +* Intro to Minibuffers:: Basic information about minibuffers. +* Text from Minibuffer:: How to read a straight text string. +* Object from Minibuffer:: How to read a Lisp object or expression. +* Minibuffer History:: Recording previous minibuffer inputs + so the user can reuse them. +* Initial Input:: Specifying initial contents for the minibuffer. +* Completion:: How to invoke and customize completion. +* Yes-or-No Queries:: Asking a question with a simple answer. +* Multiple Queries:: Asking a series of similar questions. +* Reading a Password:: Reading a password from the terminal. +* Minibuffer Commands:: Commands used as key bindings in minibuffers. +* Minibuffer Contents:: How such commands access the minibuffer text. +* Minibuffer Windows:: Operating on the special minibuffer windows. +* Recursive Mini:: Whether recursive entry to minibuffer is allowed. +* Minibuffer Misc:: Various customization hooks and variables. + +Completion + +* Basic Completion:: Low-level functions for completing strings. + (These are too low level to use the minibuffer.) +* Minibuffer Completion:: Invoking the minibuffer with completion. +* Completion Commands:: Minibuffer commands that do completion. +* High-Level Completion:: Convenient special cases of completion + (reading buffer name, file name, etc.) +* Reading File Names:: Using completion to read file names. +* Programmed Completion:: Finding the completions for a given file name. + +Command Loop + +* Command Overview:: How the command loop reads commands. +* Defining Commands:: Specifying how a function should read arguments. +* Interactive Call:: Calling a command, so that it will read arguments. ++* Distinguish Interactive:: Making a command distinguish interactive calls. +* Command Loop Info:: Variables set by the command loop for you to examine. +* Adjusting Point:: Adjustment of point after a command. +* Input Events:: What input looks like when you read it. +* Reading Input:: How to read input events from the keyboard or mouse. +* Special Events:: Events processed immediately and individually. +* Waiting:: Waiting for user input or elapsed time. +* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. +* Prefix Command Arguments:: How the commands to set prefix args work. +* Recursive Editing:: Entering a recursive edit, + and why you usually shouldn't. +* Disabling Commands:: How the command loop handles disabled commands. +* Command History:: How the command history is set up, and how accessed. +* Keyboard Macros:: How keyboard macros are implemented. + +Defining Commands + +* Using Interactive:: General rules for @code{interactive}. +* Interactive Codes:: The standard letter-codes for reading arguments + in various ways. +* Interactive Examples:: Examples of how to read interactive arguments. + +Input Events + +* Keyboard Events:: Ordinary characters--keys with symbols on them. +* Function Keys:: Function keys--keys with names, not symbols. +* Mouse Events:: Overview of mouse events. +* Click Events:: Pushing and releasing a mouse button. +* Drag Events:: Moving the mouse before releasing the button. +* Button-Down Events:: A button was pushed and not yet released. +* Repeat Events:: Double and triple click (or drag, or down). +* Motion Events:: Just moving the mouse, not pushing a button. +* Focus Events:: Moving the mouse between frames. +* Misc Events:: Other events the system can generate. +* Event Examples:: Examples of the lists for mouse events. +* Classifying Events:: Finding the modifier keys in an event symbol. +* Accessing Events:: Functions to extract info from events. +* Strings of Events:: Special considerations for putting + keyboard character events in a string. + +Reading Input + +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Event Mod:: How Emacs modifies events as they are read. +* Invoking the Input Method:: How reading an event uses the input method. +* Quoted Character Input:: Asking the user to specify a character. +* Event Input Misc:: How to reread or throw away input events. + +Keymaps + +* Key Sequences:: Key sequences as Lisp objects. +* Keymap Basics:: Basic concepts of keymaps. +* Format of Keymaps:: What a keymap looks like as a Lisp object. +* Creating Keymaps:: Functions to create and copy keymaps. +* Inheritance and Keymaps:: How one keymap can inherit the bindings + of another keymap. +* Prefix Keys:: Defining a key with a keymap as its definition. +* Active Keymaps:: How Emacs searches the active keymaps + for a key binding. +* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. +* Controlling Active Maps:: Each buffer has a local keymap + to override the standard (global) bindings. + A minor mode can also override them. +* Key Lookup:: How extracting elements from keymaps works. +* Functions for Key Lookup:: How to request key lookup. +* Changing Key Bindings:: Redefining a key in a keymap. +* Remapping Commands:: A keymap can translate one command to another. +* Translation Keymaps:: Keymaps for translating sequences of events. +* Key Binding Commands:: Interactive interfaces for redefining keys. +* Scanning Keymaps:: Looking through all keymaps, for printing help. +* Menu Keymaps:: A keymap can define a menu for X + or for use from the terminal. +* Standard Keymaps:: List of standard keymaps. + +Major and Minor Modes + +* Hooks:: How to use hooks; how to write code that + provides hooks. +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Mode Line Format:: Customizing the text that appears in the mode line. +* Imenu:: How a mode can provide a menu + of definitions in the buffer. +* Font Lock Mode:: How modes can highlight text according to syntax. +* Desktop Save Mode:: How modes can have buffer state saved between + Emacs sessions. + +Menu Keymaps + +* Defining Menus:: How to make a keymap that defines a menu. +* Mouse Menus:: How users actuate the menu with the mouse. +* Keyboard Menus:: How users actuate the menu with the keyboard. +* Menu Example:: Making a simple menu. +* Menu Bar:: How to customize the menu bar. +* Tool Bar:: A tool bar is a row of images. +* Modifying Menus:: How to add new items to a menu. + +Defining Menus + +* Simple Menu Items:: A simple kind of menu key binding, + limited in capabilities. +* Extended Menu Items:: More powerful menu item definitions + let you specify keywords to enable + various features. +* Menu Separators:: Drawing a horizontal line through a menu. +* Alias Menu Items:: Using command aliases in menu items. + +Major and Minor Modes + +* Hooks:: How to use hooks; how to write code that provides hooks. +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Mode Line Format:: Customizing the text that appears in the mode line. +* Imenu:: How a mode can provide a menu + of definitions in the buffer. +* Font Lock Mode:: How modes can highlight text according to syntax. +* Desktop Save Mode:: How modes can have buffer state saved between + Emacs sessions. + +Major Modes + +* Major Mode Basics:: +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Example Major Modes:: Text mode and Lisp modes. +* Auto Major Mode:: How Emacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. +* Derived Modes:: Defining a new major mode based on another major + mode. +* Generic Modes:: Defining a simple major mode that supports + comment syntax and Font Lock mode. +* Mode Hooks:: Hooks run at the end of major mode functions. + +Minor Modes + +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. +* Defining Minor Modes:: A convenient facility for defining minor modes. + +Mode Line Format + +* Mode Line Basics:: +* Mode Line Data:: The data structure that controls the mode line. +* Mode Line Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a mode line. +* Properties in Mode:: Using text properties in the mode line. +* Header Lines:: Like a mode line, but at the top. +* Emulating Mode Line:: Formatting text as the mode line would. + +Font Lock Mode + +* Font Lock Basics:: Overview of customizing Font Lock. +* Search-based Fontification:: Fontification based on regexps. +* Customizing Keywords:: Customizing search-based fontification. +* Other Font Lock Variables:: Additional customization facilities. +* Levels of Font Lock:: Each mode can define alternative levels + so that the user can select more or less. +* Precalculated Fontification:: How Lisp programs that produce the buffer + contents can also specify how to fontify it. +* Faces for Font Lock:: Special faces specifically for Font Lock. +* Syntactic Font Lock:: Fontification based on syntax tables. +* Setting Syntax Properties:: Defining character syntax based on context + using the Font Lock mechanism. +* Multiline Font Lock:: How to coerce Font Lock into properly + highlighting multiline constructs. + +Multiline Font Lock Constructs + +* Font Lock Multiline:: Marking multiline chunks with a text property +* Region to Fontify:: Controlling which region gets refontified + after a buffer change. + +Documentation + +* Documentation Basics:: Good style for doc strings. + Where to put them. How Emacs stores them. +* Accessing Documentation:: How Lisp programs can access doc strings. +* Keys in Documentation:: Substituting current key bindings. +* Describing Characters:: Making printable descriptions of + non-printing characters and key sequences. +* Help Functions:: Subroutines used by Emacs help facilities. + +Files + +* Visiting Files:: Reading files into Emacs buffers for editing. +* Saving Buffers:: Writing changed buffers back into files. +* Reading from Files:: Reading files into other buffers. +* Writing to Files:: Writing new files from parts of buffers. +* File Locks:: Locking and unlocking files, to prevent + simultaneous editing by two people. +* Information about Files:: Testing existence, accessibility, size of files. +* Changing Files:: Renaming files, changing protection, etc. +* File Names:: Decomposing and expanding file names. +* Contents of Directories:: Getting a list of the files in a directory. +* Create/Delete Dirs:: Creating and Deleting Directories. +* Magic File Names:: Defining "magic" special handling + for certain file names. +* Format Conversion:: Conversion to and from various file formats. + +Visiting Files + +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use. + +Information about Files + +* Testing Accessibility:: Is a given file readable? Writable? +* Kinds of Files:: Is it a directory? A symbolic link? +* Truenames:: Eliminating symbolic links from a file name. +* File Attributes:: How large is it? Any other names? Etc. +* Locating Files:: How to find a file in standard places. + +File Names + +* File Name Components:: The directory part of a file name, and the rest. +* Relative File Names:: Some file names are relative to a + current directory. +* Directory Names:: A directory's name as a directory + is different from its name as a file. +* File Name Expansion:: Converting relative file names to absolute ones. +* Unique File Names:: Generating names for temporary files. +* File Name Completion:: Finding the completions for a given file name. +* Standard File Names:: If your package uses a fixed file name, + how to handle various operating systems simply. + +Backups and Auto-Saving + +* Backup Files:: How backup files are made; how their names + are chosen. +* Auto-Saving:: How auto-save files are made; how their + names are chosen. +* Reverting:: @code{revert-buffer}, and how to customize + what it does. + +Backup Files + +* Making Backups:: How Emacs makes backup files, and when. +* Rename or Copy:: Two alternatives: renaming the old file + or copying it. +* Numbered Backups:: Keeping multiple backups for each source file. +* Backup Names:: How backup file names are computed; customization. + +Buffers + +* Buffer Basics:: What is a buffer? +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file + is visited. +* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind Emacs's back''. +* Read Only Buffers:: Modifying text is not allowed in a + read-only buffer. +* The Buffer List:: How to look at all the existing buffers. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Indirect Buffers:: An indirect buffer shares text with some + other buffer. +* Buffer Gap:: The gap in the buffer. + +Windows + +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-level functions for displaying a buffer + and choosing a window for it. +* Choosing Window:: How to choose a window for displaying a buffer. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Textual Scrolling:: Moving text up and down through the window. +* Vertical Scrolling:: Moving the contents up and down on the window. +* Horizontal Scrolling:: Moving the contents sideways on the window. +* Size of Window:: Accessing the size of a window. +* Resizing Windows:: Changing the size of a window. +* Coordinates and Windows:: Converting coordinates to windows. +* Window Tree:: The layout and sizes of all windows in a frame. +* Window Configurations:: Saving and restoring the state of the screen. +* Window Hooks:: Hooks for scrolling, window size changes, + redisplay going past a certain point, + or window configuration changes. + +Frames + +* Creating Frames:: Creating additional frames. +* Multiple Displays:: Creating frames on other displays. +* Frame Parameters:: Controlling frame size, position, font, etc. +* Frame Titles:: Automatic updating of frame titles. +* Deleting Frames:: Frames last until explicitly deleted. +* Finding All Frames:: How to examine all existing frames. +* Frames and Windows:: A frame contains windows; + display of text always works through windows. +* Minibuffers and Frames:: How a frame finds the minibuffer to use. +* Input Focus:: Specifying the selected frame. +* Visibility of Frames:: Frames may be visible or invisible, or icons. +* Raising and Lowering:: Raising a frame makes it hide other windows; + lowering it puts it underneath the others. +* Frame Configurations:: Saving the state of all frames. +* Mouse Tracking:: Getting events that say when the mouse moves. +* Mouse Position:: Asking where the mouse is, or moving it. +* Pop-Up Menus:: Displaying a menu for the user to select from. +* Dialog Boxes:: Displaying a box to ask yes or no. +* Pointer Shape:: Specifying the shape of the mouse pointer. +* Window System Selections::Transferring text to and from other windows. +* Drag and Drop:: Internals of Drag-and-Drop implementation. +* Color Names:: Getting the definitions of color names. +* Text Terminal Colors:: Defining colors for text-only terminals. +* Resources:: Getting resource values from the server. +* Display Feature Testing:: Determining the features of a terminal. + +Frame Parameters + +* Parameter Access:: How to change a frame's parameters. +* Initial Parameters:: Specifying frame parameters when you make a frame. +* Window Frame Parameters:: List of frame parameters for window systems. +* Size and Position:: Changing the size and position of a frame. +* Geometry:: Parsing geometry specifications. + +Window Frame Parameters + +* Basic Parameters:: Parameters that are fundamental. +* Position Parameters:: The position of the frame on the screen. +* Size Parameters:: Frame's size. +* Layout Parameters:: Size of parts of the frame, and + enabling or disabling some parts. +* Buffer Parameters:: Which buffers have been or should be shown. +* Management Parameters:: Communicating with the window manager. +* Cursor Parameters:: Controlling the cursor appearance. +* Color Parameters:: Colors of various parts of the frame. + +Positions + +* Point:: The special position where editing takes place. +* Motion:: Changing point. +* Excursions:: Temporary motion and buffer changes. +* Narrowing:: Restricting editing to a portion of the buffer. + +Motion + +* Character Motion:: Moving in terms of characters. +* Word Motion:: Moving in terms of words. +* Buffer End Motion:: Moving to the beginning or end of the buffer. +* Text Lines:: Moving in terms of lines of text. +* Screen Lines:: Moving in terms of lines as displayed. +* List Motion:: Moving by parsing lists and sexps. +* Skipping Characters:: Skipping characters belonging to a certain set. + +Markers + +* Overview of Markers:: The components of a marker, and how it relocates. +* Predicates on Markers:: Testing whether an object is a marker. +* Creating Markers:: Making empty markers or markers at certain places. +* Information from Markers::Finding the marker's buffer or character + position. +* Marker Insertion Types:: Two ways a marker can relocate when you + insert where it points. +* Moving Markers:: Moving the marker to a new buffer or position. +* The Mark:: How "the mark" is implemented with a marker. +* The Region:: How to access "the region". + +Text + +* Near Point:: Examining text in the vicinity of point. +* Buffer Contents:: Examining text in a general fashion. +* Comparing Text:: Comparing substrings of buffers. +* Insertion:: Adding new text to a buffer. +* Commands for Insertion:: User-level commands to insert text. +* Deletion:: Removing text from a buffer. +* User-Level Deletion:: User-level commands to delete text. +* The Kill Ring:: Where removed text sometimes is saved for + later use. +* Undo:: Undoing changes to the text of a buffer. +* Maintaining Undo:: How to enable and disable undo information. + How to control how much information is kept. +* Filling:: Functions for explicit filling. +* Margins:: How to specify margins for filling commands. +* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix + from context. +* Auto Filling:: How auto-fill mode is implemented to break lines. +* Sorting:: Functions for sorting parts of the buffer. +* Columns:: Computing horizontal positions, and using them. +* Indentation:: Functions to insert or adjust indentation. +* Case Changes:: Case conversion of parts of the buffer. +* Text Properties:: Assigning Lisp property lists to text characters. +* Substitution:: Replacing a given character wherever it appears. +* Transposition:: Swapping two portions of a buffer. +* Registers:: How registers are implemented. Accessing + the text or position stored in a register. +* Base 64:: Conversion to or from base 64 encoding. +* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Atomic Changes:: Installing several buffer changes "atomically". +* Change Hooks:: Supplying functions to be run when text is changed. + +The Kill Ring + +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yanking:: How yanking is done. +* Yank Commands:: Commands that access the kill ring. +* Low-Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill-ring data. + +Indentation + +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. + +Text Properties + +* Examining Properties:: Looking at the properties of one character. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. +* Format Properties:: Properties for representing formatting of text. +* Sticky Properties:: How inserted text gets properties from + neighboring text. +* Lazy Properties:: Computing text properties in a lazy fashion + only when text is examined. +* Clickable Text:: Using text properties to make regions of text + do something when you click on them. +* Links and Mouse-1:: How to make @key{Mouse-1} follow a link. +* Fields:: The @code{field} property defines + fields within the buffer. +* Not Intervals:: Why text properties do not use + Lisp-visible text intervals. + +Non-ASCII Characters + +* Text Representations:: Unibyte and multibyte representations +* Converting Representations:: Converting unibyte to multibyte and vice versa. +* Selecting a Representation:: Treating a byte sequence as unibyte or multi. +* Character Codes:: How unibyte and multibyte relate to + codes of individual characters. +* Character Sets:: The space of possible character codes + is divided into various character sets. +* Chars and Bytes:: More information about multibyte encodings. +* Splitting Characters:: Converting a character to its byte sequence. +* Scanning Charsets:: Which character sets are used in a buffer? +* Translation of Characters:: Translation tables are used for conversion. +* Coding Systems:: Coding systems are conversions for saving files. +* Input Methods:: Input methods allow users to enter various + non-ASCII characters without special keyboards. +* Locales:: Interacting with the POSIX locale. + +Coding Systems + +* Coding System Basics:: Basic concepts. +* Encoding and I/O:: How file I/O functions handle coding systems. +* Lisp and Coding Systems:: Functions to operate on coding system names. +* User-Chosen Coding Systems:: Asking the user to choose a coding system. +* Default Coding Systems:: Controlling the default choices. +* Specifying Coding Systems:: Requesting a particular coding system + for a single file operation. +* Explicit Encoding:: Encoding or decoding text without doing I/O. +* Terminal I/O Encoding:: Use of encoding for terminal I/O. +* MS-DOS File Types:: How DOS "text" and "binary" files + relate to coding systems. + +Searching and Matching + +* String Search:: Search for an exact match. +* Searching and Case:: Case-independent or case-significant searching. +* Regular Expressions:: Describing classes of strings. +* Regexp Search:: Searching for a match for a regexp. +* POSIX Regexps:: Searching POSIX-style for the longest match. +* Match Data:: Finding out which part of the text matched, + after a string or regexp search. +* Search and Replace:: Commands that loop, searching and replacing. +* Standard Regexps:: Useful regexps for finding sentences, pages,... + +Regular Expressions + +* Syntax of Regexps:: Rules for writing regular expressions. +* Regexp Example:: Illustrates regular expression syntax. +* Regexp Functions:: Functions for operating on regular expressions. + +Syntax of Regular Expressions + +* Regexp Special:: Special characters in regular expressions. +* Char Classes:: Character classes used in regular expressions. +* Regexp Backslash:: Backslash-sequences in regular expressions. + +The Match Data + +* Replacing Match:: Replacing a substring that was matched. +* Simple Match Data:: Accessing single items of match data, + such as where a particular subexpression started. +* Entire Match Data:: Accessing the entire match data at once, as a list. +* Saving Match Data:: Saving and restoring the match data. + +Syntax Tables + +* Syntax Basics:: Basic concepts of syntax tables. +* Syntax Descriptors:: How characters are classified. +* Syntax Table Functions:: How to create, examine and alter syntax tables. +* Syntax Properties:: Overriding syntax with text properties. +* Motion and Syntax:: Moving over characters with certain syntaxes. +* Parsing Expressions:: Parsing balanced expressions + using the syntax table. +* Standard Syntax Tables:: Syntax tables used by various major modes. +* Syntax Table Internals:: How syntax table information is stored. +* Categories:: Another way of classifying character syntax. + +Syntax Descriptors + +* Syntax Class Table:: Table of syntax classes. +* Syntax Flags:: Additional flags each character can have. + +Parsing Expressions + +* Motion via Parsing:: Motion functions that work by parsing. +* Position Parse:: Determining the syntactic state of a position. +* Parser State:: How Emacs represents a syntactic state. +* Low-Level Parsing:: Parsing across a specified region. +* Control Parsing:: Parameters that affect parsing. + +Abbrevs And Abbrev Expansion + +* Abbrev Mode:: Setting up Emacs for abbreviation. +* Abbrev Tables:: Creating and working with abbrev tables. +* Defining Abbrevs:: Specifying abbreviations and their expansions. +* Abbrev Files:: Saving abbrevs in files. +* Abbrev Expansion:: Controlling expansion; expansion subroutines. +* Standard Abbrev Tables:: Abbrev tables used by various major modes. + +Processes + +* Subprocess Creation:: Functions that start subprocesses. +* Shell Arguments:: Quoting an argument to pass it to a shell. +* Synchronous Processes:: Details of using synchronous subprocesses. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Query Before Exit:: Whether to query if exiting will kill a process. +* Transaction Queues:: Transaction-based communication with subprocesses. +* Network:: Opening network connections. +* Network Servers:: Network servers let Emacs accept net connections. +* Datagrams:: UDP network connections. +* Low-Level Network:: Lower-level but more general function + to create connections and servers. +* Misc Network:: Additional relevant functions for network connections. +* Byte Packing:: Using bindat to pack and unpack binary data. + +Receiving Output from Processes + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Decoding Output:: Filters can get unibyte or multibyte strings. +* Accepting Output:: How to wait until process output arrives. + +Low-Level Network Access + +* Proc: Network Processes. Using @code{make-network-process}. +* Options: Network Options. Further control over network connections. +* Features: Network Feature Testing. + Determining which network features work on + the machine you are using. + +Packing and Unpacking Byte Arrays + +* Bindat Spec:: Describing data layout. +* Bindat Functions:: Doing the unpacking and packing. +* Bindat Examples:: Samples of what bindat.el can do for you! + +Emacs Display + +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* Forcing Redisplay:: Forcing redisplay. +* Truncation:: Folding or wrapping long text lines. +* The Echo Area:: Displaying messages at the bottom of the screen. +* Warnings:: Displaying warning messages for the user. +* Invisible Text:: Hiding part of the buffer text. +* Selective Display:: Hiding part of the buffer text (the old way). +* Temporary Displays:: Displays that go away automatically. +* Overlays:: Use overlays to highlight parts of the buffer. +* Width:: How wide a character or string is on the screen. +* Line Height:: Controlling the height of lines. +* Faces:: A face defines a graphics style + for text characters: font, colors, etc. +* Fringes:: Controlling window fringes. +* Scroll Bars:: Controlling vertical scroll bars. +* Display Property:: Enabling special display features. +* Images:: Displaying images in Emacs buffers. +* Buttons:: Adding clickable buttons to Emacs buffers. +* Abstract Display:: Emacs' Widget for Object Collections. +* Blinking:: How Emacs shows the matching open parenthesis. +* Usual Display:: The usual conventions for displaying nonprinting chars. +* Display Tables:: How to specify other conventions. +* Beeping:: Audible signal to the user. +* Window Systems:: Which window system is being used. + +The Echo Area + +* Displaying Messages:: Explicitly displaying text in the echo area. +* Progress:: Informing user about progress of a long operation. +* Logging Messages:: Echo area messages are logged for the user. +* Echo Area Customization:: Controlling the echo area. + +Reporting Warnings + +* Warning Basics:: Warnings concepts and functions to report them. +* Warning Variables:: Variables programs bind to customize their warnings. +* Warning Options:: Variables users set to control display of warnings. + +Overlays + +* Managing Overlays:: Creating and moving overlays. +* Overlay Properties:: How to read and set properties. + What properties do to the screen display. +* Finding Overlays:: Searching for overlays. + +Faces + +* Defining Faces:: How to define a face with @code{defface}. +* Face Attributes:: What is in a face? +* Attribute Functions:: Functions to examine and set face attributes. +* Displaying Faces:: How Emacs combines the faces specified for + a character. +* Font Selection:: Finding the best available font for a face. +* Face Functions:: How to define and examine faces. +* Auto Faces:: Hook for automatic face assignment. +* Font Lookup:: Looking up the names of available fonts + and information about them. +* Fontsets:: A fontset is a collection of fonts + that handle a range of character sets. + +Fringes + +* Fringe Size/Pos:: Specifying where to put the window fringes. +* Fringe Indicators:: Displaying indicator icons in the window fringes. +* Fringe Cursors:: Displaying cursors in the right fringe. +* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. +* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. +* Overlay Arrow:: Display of an arrow to indicate position. + +The @code{display} Property + +* Specified Space:: Displaying one space with a specified width. +* Pixel Specification:: Specifying space width or height in pixels. +* Other Display Specs:: Displaying an image; magnifying text; moving it + up or down on the page; adjusting the width + of spaces within text. +* Display Margins:: Displaying text or images to the side of + the main text. + +Images + +* Image Descriptors:: How to specify an image for use in @code{:display}. +* XBM Images:: Special features for XBM format. +* XPM Images:: Special features for XPM format. +* GIF Images:: Special features for GIF format. +* PostScript Images:: Special features for PostScript format. +* Other Image Types:: Various other formats are supported. +* Defining Images:: Convenient ways to define an image for later use. +* Showing Images:: Convenient ways to display an image once + it is defined. +* Image Cache:: Internal mechanisms of image display. + +Buttons + +* Button Properties:: Button properties with special meanings. +* Button Types:: Defining common properties for classes of buttons. +* Making Buttons:: Adding buttons to Emacs buffers. +* Manipulating Buttons:: Getting and setting properties of buttons. +* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. + +Abstract Display + +* Abstract Display Functions:: Functions in the Ewoc package. +* Abstract Display Example:: Example of using Ewoc. + +Display Tables + +* Display Table Format:: What a display table consists of. +* Active Display Table:: How Emacs selects a display table to use. +* Glyphs:: How to define a glyph, and what glyphs mean. + +Operating System Interface + +* Starting Up:: Customizing Emacs start-up processing. +* Getting Out:: How exiting works (permanent or temporary). +* System Environment:: Distinguish the name and kind of system. +* User Identification:: Finding the name and user id of the user. +* Time of Day:: Getting the current time. +* Time Conversion:: Converting a time from numeric form to a string, or + to calendrical data (or vice versa). +* Time Parsing:: Converting a time from numeric form to text + and vice versa. +* Processor Run Time:: Getting the run time used by Emacs. +* Time Calculations:: Adding, subtracting, comparing times, etc. +* Timers:: Setting a timer to call a function at a certain time. +* Idle Timers:: Setting a timer to call a function when Emacs has + been idle for a certain length of time. +* Terminal Input:: Accessing and recording terminal input. +* Terminal Output:: Controlling and recording terminal output. +* Sound Output:: Playing sounds on the computer's speaker. +* X11 Keysyms:: Operating on key symbols for X Windows +* Batch Mode:: Running Emacs without terminal interaction. +* Session Management:: Saving and restoring state with X Session Management. + +Starting Up Emacs + +* Startup Summary:: Sequence of actions Emacs performs at start-up. +* Init File:: Details on reading the init file (@file{.emacs}). +* Terminal-Specific:: How the terminal-specific Lisp file is read. +* Command-Line Arguments:: How command-line arguments are processed, + and how you can customize them. + +Getting Out of Emacs + +* Killing Emacs:: Exiting Emacs irreversibly. +* Suspending Emacs:: Exiting Emacs reversibly. + +Terminal Input + +* Input Modes:: Options for how input is processed. +* Recording Input:: Saving histories of recent or all input events. + +Tips and Conventions + +* Coding Conventions:: Conventions for clean and robust programs. +* Key Binding Conventions:: Which keys should be bound by which programs. +* Programming Tips:: Making Emacs code fit smoothly in Emacs. +* Compilation Tips:: Making compiled code run fast. +* Warning Tips:: Turning off compiler warnings. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Library Headers:: Standard headers for library packages. + +GNU Emacs Internals + +* Building Emacs:: How the dumped Emacs is made. +* Pure Storage:: A kludge to make preloaded Lisp functions sharable. +* Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Memory Usage:: Info about total size of Lisp objects made so far. +* Writing Emacs Primitives:: Writing C code for Emacs. +* Object Internals:: Data formats of buffers, windows, processes. + +Object Internals + +* Buffer Internals:: Components of a buffer structure. +* Window Internals:: Components of a window structure. +* Process Internals:: Components of a process structure. +@end detailmenu +@end menu + +@include intro.texi +@include objects.texi +@include numbers.texi +@include strings.texi + +@include lists.texi +@include sequences.texi +@include hash.texi +@include symbols.texi +@include eval.texi + +@include control.texi +@include variables.texi +@include functions.texi +@include macros.texi + +@include customize.texi +@include loading.texi +@include compile.texi +@include advice.texi + +@include debugging.texi +@include streams.texi +@include minibuf.texi +@include commands.texi + +@include keymaps.texi +@include modes.texi +@include help.texi +@include files.texi + +@include backups.texi +@include buffers.texi +@include windows.texi +@include frames.texi + +@include positions.texi +@include markers.texi +@include text.texi +@include nonascii.texi + +@include searching.texi +@include syntax.texi +@include abbrevs.texi +@include processes.texi + +@include display.texi +@include os.texi + +@c MOVE to Emacs Manual: include misc-modes.texi + +@c appendices + +@c REMOVE this: include non-hacker.texi + +@include anti.texi +@include doclicense.texi +@include gpl.texi +@include tips.texi +@include internals.texi +@include errors.texi +@include locals.texi +@include maps.texi +@include hooks.texi + +@include index.texi + +@ignore +@node New Symbols, , Index, Top +@unnumbered New Symbols Since the Previous Edition + +@printindex tp +@end ignore + +@bye + + +These words prevent "local variables" above from confusing Emacs. + +@ignore + arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34 +@end ignore diff --cc doc/lispref/text.texi index c6da06b4a13,00000000000..daaaf6c9b9d mode 100644,000000..100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@@ -1,4309 -1,0 +1,4309 @@@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/text +@node Text, Non-ASCII Characters, Markers, Top +@chapter Text +@cindex text + + This chapter describes the functions that deal with the text in a +buffer. Most examine, insert, or delete text in the current buffer, +often operating at point or on text adjacent to point. Many are +interactive. All the functions that change the text provide for undoing +the changes (@pxref{Undo}). + + Many text-related functions operate on a region of text defined by two +buffer positions passed in arguments named @var{start} and @var{end}. +These arguments should be either markers (@pxref{Markers}) or numeric +character positions (@pxref{Positions}). The order of these arguments +does not matter; it is all right for @var{start} to be the end of the +region and @var{end} the beginning. For example, @code{(delete-region 1 +10)} and @code{(delete-region 10 1)} are equivalent. An +@code{args-out-of-range} error is signaled if either @var{start} or +@var{end} is outside the accessible portion of the buffer. In an +interactive call, point and the mark are used for these arguments. + +@cindex buffer contents + Throughout this chapter, ``text'' refers to the characters in the +buffer, together with their properties (when relevant). Keep in mind +that point is always between two characters, and the cursor appears on +the character after point. + +@menu +* Near Point:: Examining text in the vicinity of point. +* Buffer Contents:: Examining text in a general fashion. +* Comparing Text:: Comparing substrings of buffers. +* Insertion:: Adding new text to a buffer. +* Commands for Insertion:: User-level commands to insert text. +* Deletion:: Removing text from a buffer. +* User-Level Deletion:: User-level commands to delete text. +* The Kill Ring:: Where removed text sometimes is saved for later use. +* Undo:: Undoing changes to the text of a buffer. +* Maintaining Undo:: How to enable and disable undo information. + How to control how much information is kept. +* Filling:: Functions for explicit filling. +* Margins:: How to specify margins for filling commands. +* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. +* Auto Filling:: How auto-fill mode is implemented to break lines. +* Sorting:: Functions for sorting parts of the buffer. +* Columns:: Computing horizontal positions, and using them. +* Indentation:: Functions to insert or adjust indentation. +* Case Changes:: Case conversion of parts of the buffer. +* Text Properties:: Assigning Lisp property lists to text characters. +* Substitution:: Replacing a given character wherever it appears. +* Transposition:: Swapping two portions of a buffer. +* Registers:: How registers are implemented. Accessing the text or + position stored in a register. +* Base 64:: Conversion to or from base 64 encoding. +* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Atomic Changes:: Installing several buffer changes "atomically". +* Change Hooks:: Supplying functions to be run when text is changed. +@end menu + +@node Near Point +@section Examining Text Near Point +@cindex text near point + + Many functions are provided to look at the characters around point. +Several simple functions are described here. See also @code{looking-at} +in @ref{Regexp Search}. + +In the following four functions, ``beginning'' or ``end'' of buffer +refers to the beginning or end of the accessible portion. + +@defun char-after &optional position +This function returns the character in the current buffer at (i.e., +immediately after) position @var{position}. If @var{position} is out of +range for this purpose, either before the beginning of the buffer, or at +or beyond the end, then the value is @code{nil}. The default for +@var{position} is point. + +In the following example, assume that the first character in the +buffer is @samp{@@}: + +@example +@group +(char-to-string (char-after 1)) + @result{} "@@" +@end group +@end example +@end defun + +@defun char-before &optional position +This function returns the character in the current buffer immediately +before position @var{position}. If @var{position} is out of range for +this purpose, either at or before the beginning of the buffer, or beyond +the end, then the value is @code{nil}. The default for +@var{position} is point. +@end defun + +@defun following-char +This function returns the character following point in the current +buffer. This is similar to @code{(char-after (point))}. However, if +point is at the end of the buffer, then @code{following-char} returns 0. + +Remember that point is always between characters, and the cursor +normally appears over the character following point. Therefore, the +character returned by @code{following-char} is the character the +cursor is over. + +In this example, point is between the @samp{a} and the @samp{c}. + +@example +@group +---------- Buffer: foo ---------- +Gentlemen may cry ``Pea@point{}ce! Peace!,'' +but there is no peace. +---------- Buffer: foo ---------- +@end group + +@group +(char-to-string (preceding-char)) + @result{} "a" +(char-to-string (following-char)) + @result{} "c" +@end group +@end example +@end defun + +@defun preceding-char +This function returns the character preceding point in the current +buffer. See above, under @code{following-char}, for an example. If +point is at the beginning of the buffer, @code{preceding-char} returns +0. +@end defun + +@defun bobp +This function returns @code{t} if point is at the beginning of the +buffer. If narrowing is in effect, this means the beginning of the +accessible portion of the text. See also @code{point-min} in +@ref{Point}. +@end defun + +@defun eobp +This function returns @code{t} if point is at the end of the buffer. +If narrowing is in effect, this means the end of accessible portion of +the text. See also @code{point-max} in @xref{Point}. +@end defun + +@defun bolp +This function returns @code{t} if point is at the beginning of a line. +@xref{Text Lines}. The beginning of the buffer (or of its accessible +portion) always counts as the beginning of a line. +@end defun + +@defun eolp +This function returns @code{t} if point is at the end of a line. The +end of the buffer (or of its accessible portion) is always considered +the end of a line. +@end defun + +@node Buffer Contents +@section Examining Buffer Contents + + This section describes functions that allow a Lisp program to +convert any portion of the text in the buffer into a string. + +@defun buffer-substring start end +This function returns a string containing a copy of the text of the +region defined by positions @var{start} and @var{end} in the current +buffer. If the arguments are not positions in the accessible portion of +the buffer, @code{buffer-substring} signals an @code{args-out-of-range} +error. + +It is not necessary for @var{start} to be less than @var{end}; the +arguments can be given in either order. But most often the smaller +argument is written first. + +Here's an example which assumes Font-Lock mode is not enabled: + +@example +@group +---------- Buffer: foo ---------- +This is the contents of buffer foo + +---------- Buffer: foo ---------- +@end group + +@group +(buffer-substring 1 10) + @result{} "This is t" +@end group +@group +(buffer-substring (point-max) 10) + @result{} "he contents of buffer foo\n" +@end group +@end example + +If the text being copied has any text properties, these are copied into +the string along with the characters they belong to. @xref{Text +Properties}. However, overlays (@pxref{Overlays}) in the buffer and +their properties are ignored, not copied. + +For example, if Font-Lock mode is enabled, you might get results like +these: + +@example +@group +(buffer-substring 1 10) + @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) +@end group +@end example +@end defun + +@defun buffer-substring-no-properties start end +This is like @code{buffer-substring}, except that it does not copy text +properties, just the characters themselves. @xref{Text Properties}. +@end defun + +@defun filter-buffer-substring start end &optional delete noprops +This function passes the buffer text between @var{start} and @var{end} +through the filter functions specified by the variable +@code{buffer-substring-filters}, and returns the value from the last +filter function. If @code{buffer-substring-filters} is @code{nil}, +the value is the unaltered text from the buffer, what +@code{buffer-substring} would return. + +If @var{delete} is non-@code{nil}, this function deletes the text +between @var{start} and @var{end} after copying it, like +@code{delete-and-extract-region}. + +If @var{noprops} is non-@code{nil}, the final string returned does not +include text properties, while the string passed through the filters +still includes text properties from the buffer text. + +Lisp code should use this function instead of @code{buffer-substring}, +@code{buffer-substring-no-properties}, +or @code{delete-and-extract-region} when copying into user-accessible +data structures such as the kill-ring, X clipboard, and registers. +Major and minor modes can add functions to +@code{buffer-substring-filters} to alter such text as it is copied out +of the buffer. +@end defun + +@defvar buffer-substring-filters +This variable should be a list of functions that accept a single +argument, a string, and return a string. +@code{filter-buffer-substring} passes the buffer substring to the +first function in this list, and the return value of each function is +passed to the next function. The return value of the last function is +used as the return value of @code{filter-buffer-substring}. + +As a special convention, point is set to the start of the buffer text +being operated on (i.e., the @var{start} argument for +@code{filter-buffer-substring}) before these functions are called. + +If this variable is @code{nil}, no filtering is performed. +@end defvar + +@defun buffer-string +This function returns the contents of the entire accessible portion of +the current buffer as a string. It is equivalent to + +@example +(buffer-substring (point-min) (point-max)) +@end example + +@example +@group +---------- Buffer: foo ---------- +This is the contents of buffer foo + +---------- Buffer: foo ---------- + +(buffer-string) + @result{} "This is the contents of buffer foo\n" +@end group +@end example +@end defun + +@defun current-word &optional strict really-word +This function returns the symbol (or word) at or near point, as a string. +The return value includes no text properties. + +If the optional argument @var{really-word} is non-@code{nil}, it finds a +word; otherwise, it finds a symbol (which includes both word +characters and symbol constituent characters). + +If the optional argument @var{strict} is non-@code{nil}, then point +must be in or next to the symbol or word---if no symbol or word is +there, the function returns @code{nil}. Otherwise, a nearby symbol or +word on the same line is acceptable. +@end defun + +@defun thing-at-point thing +Return the @var{thing} around or next to point, as a string. + +The argument @var{thing} is a symbol which specifies a kind of syntactic +entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, +@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, +@code{whitespace}, @code{line}, @code{page}, and others. + +@example +---------- Buffer: foo ---------- +Gentlemen may cry ``Pea@point{}ce! Peace!,'' +but there is no peace. +---------- Buffer: foo ---------- + +(thing-at-point 'word) + @result{} "Peace" +(thing-at-point 'line) + @result{} "Gentlemen may cry ``Peace! Peace!,''\n" +(thing-at-point 'whitespace) + @result{} nil +@end example +@end defun + +@node Comparing Text +@section Comparing Text +@cindex comparing buffer text + + This function lets you compare portions of the text in a buffer, without +copying them into strings first. + +@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 +This function lets you compare two substrings of the same buffer or two +different buffers. The first three arguments specify one substring, +giving a buffer (or a buffer name) and two positions within the +buffer. The last three arguments specify the other substring in the +same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or +both to stand for the current buffer. + +The value is negative if the first substring is less, positive if the +first is greater, and zero if they are equal. The absolute value of +the result is one plus the index of the first differing characters +within the substrings. + +This function ignores case when comparing characters +if @code{case-fold-search} is non-@code{nil}. It always ignores +text properties. + +Suppose the current buffer contains the text @samp{foobarbar +haha!rara!}; then in this example the two substrings are @samp{rbar } +and @samp{rara!}. The value is 2 because the first substring is greater +at the second character. + +@example +(compare-buffer-substrings nil 6 11 nil 16 21) + @result{} 2 +@end example +@end defun + +@node Insertion +@section Inserting Text +@cindex insertion of text +@cindex text insertion + +@cindex insertion before point +@cindex before point, insertion + @dfn{Insertion} means adding new text to a buffer. The inserted text +goes at point---between the character before point and the character +after point. Some insertion functions leave point before the inserted +text, while other functions leave it after. We call the former +insertion @dfn{after point} and the latter insertion @dfn{before point}. + + Insertion relocates markers that point at positions after the +insertion point, so that they stay with the surrounding text +(@pxref{Markers}). When a marker points at the place of insertion, +insertion may or may not relocate the marker, depending on the marker's +insertion type (@pxref{Marker Insertion Types}). Certain special +functions such as @code{insert-before-markers} relocate all such markers +to point after the inserted text, regardless of the markers' insertion +type. + + Insertion functions signal an error if the current buffer is +read-only or if they insert within read-only text. + + These functions copy text characters from strings and buffers along +with their properties. The inserted characters have exactly the same +properties as the characters they were copied from. By contrast, +characters specified as separate arguments, not part of a string or +buffer, inherit their text properties from the neighboring text. + + The insertion functions convert text from unibyte to multibyte in +order to insert in a multibyte buffer, and vice versa---if the text +comes from a string or from a buffer. However, they do not convert +unibyte character codes 128 through 255 to multibyte characters, not +even if the current buffer is a multibyte buffer. @xref{Converting +Representations}. + +@defun insert &rest args +This function inserts the strings and/or characters @var{args} into the +current buffer, at point, moving point forward. In other words, it +inserts the text before point. An error is signaled unless all +@var{args} are either strings or characters. The value is @code{nil}. +@end defun + +@defun insert-before-markers &rest args +This function inserts the strings and/or characters @var{args} into the +current buffer, at point, moving point forward. An error is signaled +unless all @var{args} are either strings or characters. The value is +@code{nil}. + +This function is unlike the other insertion functions in that it +relocates markers initially pointing at the insertion point, to point +after the inserted text. If an overlay begins at the insertion point, +the inserted text falls outside the overlay; if a nonempty overlay +ends at the insertion point, the inserted text falls inside that +overlay. +@end defun + +@defun insert-char character count &optional inherit +This function inserts @var{count} instances of @var{character} into the +current buffer before point. The argument @var{count} should be an +integer, and @var{character} must be a character. The value is @code{nil}. + +This function does not convert unibyte character codes 128 through 255 +to multibyte characters, not even if the current buffer is a multibyte +buffer. @xref{Converting Representations}. + +If @var{inherit} is non-@code{nil}, then the inserted characters inherit +sticky text properties from the two characters before and after the +insertion point. @xref{Sticky Properties}. +@end defun + +@defun insert-buffer-substring from-buffer-or-name &optional start end +This function inserts a portion of buffer @var{from-buffer-or-name} +(which must already exist) into the current buffer before point. The +text inserted is the region between @var{start} and @var{end}. (These +arguments default to the beginning and end of the accessible portion of +that buffer.) This function returns @code{nil}. + +In this example, the form is executed with buffer @samp{bar} as the +current buffer. We assume that buffer @samp{bar} is initially empty. + +@example +@group +---------- Buffer: foo ---------- +We hold these truths to be self-evident, that all +---------- Buffer: foo ---------- +@end group + +@group +(insert-buffer-substring "foo" 1 20) + @result{} nil + +---------- Buffer: bar ---------- +We hold these truth@point{} +---------- Buffer: bar ---------- +@end group +@end example +@end defun + +@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end +This is like @code{insert-buffer-substring} except that it does not +copy any text properties. +@end defun + + @xref{Sticky Properties}, for other insertion functions that inherit +text properties from the nearby text in addition to inserting it. +Whitespace inserted by indentation functions also inherits text +properties. + +@node Commands for Insertion +@section User-Level Insertion Commands + + This section describes higher-level commands for inserting text, +commands intended primarily for the user but useful also in Lisp +programs. + +@deffn Command insert-buffer from-buffer-or-name +This command inserts the entire accessible contents of +@var{from-buffer-or-name} (which must exist) into the current buffer +after point. It leaves the mark after the inserted text. The value +is @code{nil}. +@end deffn + +@deffn Command self-insert-command count +@cindex character insertion +@cindex self-insertion +This command inserts the last character typed; it does so @var{count} +times, before point, and returns @code{nil}. Most printing characters +are bound to this command. In routine use, @code{self-insert-command} +is the most frequently called function in Emacs, but programs rarely use +it except to install it on a keymap. + +In an interactive call, @var{count} is the numeric prefix argument. + +Self-insertion translates the input character through +@code{translation-table-for-input}. @xref{Translation of Characters}. + +This command calls @code{auto-fill-function} whenever that is +non-@code{nil} and the character inserted is in the table +@code{auto-fill-chars} (@pxref{Auto Filling}). + +@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 +This command performs abbrev expansion if Abbrev mode is enabled and +the inserted character does not have word-constituent +syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also +responsible for calling @code{blink-paren-function} when the inserted +character has close parenthesis syntax (@pxref{Blinking}). + +Do not try substituting your own definition of +@code{self-insert-command} for the standard one. The editor command +loop handles this function specially. +@end deffn + +@deffn Command newline &optional number-of-newlines +This command inserts newlines into the current buffer before point. +If @var{number-of-newlines} is supplied, that many newline characters +are inserted. + +@cindex newline and Auto Fill mode +This function calls @code{auto-fill-function} if the current column +number is greater than the value of @code{fill-column} and +@var{number-of-newlines} is @code{nil}. Typically what +@code{auto-fill-function} does is insert a newline; thus, the overall +result in this case is to insert two newlines at different places: one +at point, and another earlier in the line. @code{newline} does not +auto-fill if @var{number-of-newlines} is non-@code{nil}. + +This command indents to the left margin if that is not zero. +@xref{Margins}. + +The value returned is @code{nil}. In an interactive call, @var{count} +is the numeric prefix argument. +@end deffn + +@defvar overwrite-mode +This variable controls whether overwrite mode is in effect. The value +should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, +or @code{nil}. @code{overwrite-mode-textual} specifies textual +overwrite mode (treats newlines and tabs specially), and +@code{overwrite-mode-binary} specifies binary overwrite mode (treats +newlines and tabs like any other characters). +@end defvar + +@node Deletion +@section Deleting Text +@cindex text deletion + +@cindex deleting text vs killing + Deletion means removing part of the text in a buffer, without saving +it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be +yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). +Some deletion functions do save text in the kill ring in some special +cases. + + All of the deletion functions operate on the current buffer. + +@deffn Command erase-buffer +This function deletes the entire text of the current buffer +(@emph{not} just the accessible portion), leaving it +empty. If the buffer is read-only, it signals a @code{buffer-read-only} +error; if some of the text in it is read-only, it signals a +@code{text-read-only} error. Otherwise, it deletes the text without +asking for any confirmation. It returns @code{nil}. + +Normally, deleting a large amount of text from a buffer inhibits further +auto-saving of that buffer ``because it has shrunk.'' However, +@code{erase-buffer} does not do this, the idea being that the future +text is not really related to the former text, and its size should not +be compared with that of the former text. +@end deffn + +@deffn Command delete-region start end +This command deletes the text between positions @var{start} and +@var{end} in the current buffer, and returns @code{nil}. If point was +inside the deleted region, its value afterward is @var{start}. +Otherwise, point relocates with the surrounding text, as markers do. +@end deffn + +@defun delete-and-extract-region start end +This function deletes the text between positions @var{start} and +@var{end} in the current buffer, and returns a string containing the +text just deleted. + +If point was inside the deleted region, its value afterward is +@var{start}. Otherwise, point relocates with the surrounding text, as +markers do. +@end defun + +@deffn Command delete-char count &optional killp +This command deletes @var{count} characters directly after point, or +before point if @var{count} is negative. If @var{killp} is +non-@code{nil}, then it saves the deleted characters in the kill ring. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@deffn Command delete-backward-char count &optional killp +@cindex deleting previous char +This command deletes @var{count} characters directly before point, or +after point if @var{count} is negative. If @var{killp} is +non-@code{nil}, then it saves the deleted characters in the kill ring. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@deffn Command backward-delete-char-untabify count &optional killp +@cindex tab deletion +This command deletes @var{count} characters backward, changing tabs +into spaces. When the next character to be deleted is a tab, it is +first replaced with the proper number of spaces to preserve alignment +and then one of those spaces is deleted instead of the tab. If +@var{killp} is non-@code{nil}, then the command saves the deleted +characters in the kill ring. + +Conversion of tabs to spaces happens only if @var{count} is positive. +If it is negative, exactly @minus{}@var{count} characters after point +are deleted. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@defopt backward-delete-char-untabify-method +This option specifies how @code{backward-delete-char-untabify} should +deal with whitespace. Possible values include @code{untabify}, the +default, meaning convert a tab to many spaces and delete one; +@code{hungry}, meaning delete all tabs and spaces before point with +one command; @code{all} meaning delete all tabs, spaces and newlines +before point, and @code{nil}, meaning do nothing special for +whitespace characters. +@end defopt + +@node User-Level Deletion +@section User-Level Deletion Commands + + This section describes higher-level commands for deleting text, +commands intended primarily for the user but useful also in Lisp +programs. + +@deffn Command delete-horizontal-space &optional backward-only +@cindex deleting whitespace +This function deletes all spaces and tabs around point. It returns +@code{nil}. + +If @var{backward-only} is non-@code{nil}, the function deletes +spaces and tabs before point, but not after point. + +In the following examples, we call @code{delete-horizontal-space} four +times, once on each line, with point between the second and third +characters on the line each time. + +@example +@group +---------- Buffer: foo ---------- +I @point{}thought +I @point{} thought +We@point{} thought +Yo@point{}u thought +---------- Buffer: foo ---------- +@end group + +@group +(delete-horizontal-space) ; @r{Four times.} + @result{} nil + +---------- Buffer: foo ---------- +Ithought +Ithought +Wethought +You thought +---------- Buffer: foo ---------- +@end group +@end example +@end deffn + +@deffn Command delete-indentation &optional join-following-p +This function joins the line point is on to the previous line, deleting +any whitespace at the join and in some cases replacing it with one +space. If @var{join-following-p} is non-@code{nil}, +@code{delete-indentation} joins this line to the following line +instead. The function returns @code{nil}. + +If there is a fill prefix, and the second of the lines being joined +starts with the prefix, then @code{delete-indentation} deletes the +fill prefix before joining the lines. @xref{Margins}. + +In the example below, point is located on the line starting +@samp{events}, and it makes no difference if there are trailing spaces +in the preceding line. + +@smallexample +@group +---------- Buffer: foo ---------- +When in the course of human +@point{} events, it becomes necessary +---------- Buffer: foo ---------- +@end group + +(delete-indentation) + @result{} nil + +@group +---------- Buffer: foo ---------- +When in the course of human@point{} events, it becomes necessary +---------- Buffer: foo ---------- +@end group +@end smallexample + +After the lines are joined, the function @code{fixup-whitespace} is +responsible for deciding whether to leave a space at the junction. +@end deffn + +@deffn Command fixup-whitespace +This function replaces all the horizontal whitespace surrounding point +with either one space or no space, according to the context. It +returns @code{nil}. + +At the beginning or end of a line, the appropriate amount of space is +none. Before a character with close parenthesis syntax, or after a +character with open parenthesis or expression-prefix syntax, no space is +also appropriate. Otherwise, one space is appropriate. @xref{Syntax +Class Table}. + +In the example below, @code{fixup-whitespace} is called the first time +with point before the word @samp{spaces} in the first line. For the +second invocation, point is directly after the @samp{(}. + +@smallexample +@group +---------- Buffer: foo ---------- +This has too many @point{}spaces +This has too many spaces at the start of (@point{} this list) +---------- Buffer: foo ---------- +@end group + +@group +(fixup-whitespace) + @result{} nil +(fixup-whitespace) + @result{} nil +@end group + +@group +---------- Buffer: foo ---------- +This has too many spaces +This has too many spaces at the start of (this list) +---------- Buffer: foo ---------- +@end group +@end smallexample +@end deffn + +@deffn Command just-one-space &optional n +@comment !!SourceFile simple.el +This command replaces any spaces and tabs around point with a single +space, or @var{n} spaces if @var{n} is specified. It returns +@code{nil}. +@end deffn + +@deffn Command delete-blank-lines +This function deletes blank lines surrounding point. If point is on a +blank line with one or more blank lines before or after it, then all but +one of them are deleted. If point is on an isolated blank line, then it +is deleted. If point is on a nonblank line, the command deletes all +blank lines immediately following it. + +A blank line is defined as a line containing only tabs and spaces. + +@code{delete-blank-lines} returns @code{nil}. +@end deffn + +@node The Kill Ring +@section The Kill Ring +@cindex kill ring + + @dfn{Kill functions} delete text like the deletion functions, but save +it so that the user can reinsert it by @dfn{yanking}. Most of these +functions have @samp{kill-} in their name. By contrast, the functions +whose names start with @samp{delete-} normally do not save text for +yanking (though they can still be undone); these are ``deletion'' +functions. + + Most of the kill commands are primarily for interactive use, and are +not described here. What we do describe are the functions provided for +use in writing such commands. You can use these functions to write +commands for killing text. When you need to delete text for internal +purposes within a Lisp function, you should normally use deletion +functions, so as not to disturb the kill ring contents. +@xref{Deletion}. + + Killed text is saved for later yanking in the @dfn{kill ring}. This +is a list that holds a number of recent kills, not just the last text +kill. We call this a ``ring'' because yanking treats it as having +elements in a cyclic order. The list is kept in the variable +@code{kill-ring}, and can be operated on with the usual functions for +lists; there are also specialized functions, described in this section, +that treat it as a ring. + + Some people think this use of the word ``kill'' is unfortunate, since +it refers to operations that specifically @emph{do not} destroy the +entities ``killed.'' This is in sharp contrast to ordinary life, in +which death is permanent and ``killed'' entities do not come back to +life. Therefore, other metaphors have been proposed. For example, the +term ``cut ring'' makes sense to people who, in pre-computer days, used +scissors and paste to cut up and rearrange manuscripts. However, it +would be difficult to change the terminology now. + +@menu +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yanking:: How yanking is done. +* Yank Commands:: Commands that access the kill ring. +* Low-Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill ring data. +@end menu + +@node Kill Ring Concepts +@comment node-name, next, previous, up +@subsection Kill Ring Concepts + + The kill ring records killed text as strings in a list, most recent +first. A short kill ring, for example, might look like this: + +@example +("some text" "a different piece of text" "even older text") +@end example + +@noindent +When the list reaches @code{kill-ring-max} entries in length, adding a +new entry automatically deletes the last entry. + + When kill commands are interwoven with other commands, each kill +command makes a new entry in the kill ring. Multiple kill commands in +succession build up a single kill ring entry, which would be yanked as a +unit; the second and subsequent consecutive kill commands add text to +the entry made by the first one. + + For yanking, one entry in the kill ring is designated the ``front'' of +the ring. Some yank commands ``rotate'' the ring by designating a +different element as the ``front.'' But this virtual rotation doesn't +change the list itself---the most recent entry always comes first in the +list. + +@node Kill Functions +@comment node-name, next, previous, up +@subsection Functions for Killing + + @code{kill-region} is the usual subroutine for killing text. Any +command that calls this function is a ``kill command'' (and should +probably have @samp{kill} in its name). @code{kill-region} puts the +newly killed text in a new element at the beginning of the kill ring or +adds it to the most recent element. It determines automatically (using +@code{last-command}) whether the previous command was a kill command, +and if so appends the killed text to the most recent entry. + +@deffn Command kill-region start end &optional yank-handler +This function kills the text in the region defined by @var{start} and +@var{end}. The text is deleted but saved in the kill ring, along with +its text properties. The value is always @code{nil}. + +In an interactive call, @var{start} and @var{end} are point and +the mark. + +@c Emacs 19 feature +If the buffer or text is read-only, @code{kill-region} modifies the kill +ring just the same, then signals an error without modifying the buffer. +This is convenient because it lets the user use a series of kill +commands to copy text from a read-only buffer into the kill ring. + +If @var{yank-handler} is non-@code{nil}, this puts that value onto +the string of killed text, as a @code{yank-handler} text property. +@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any +@code{yank-handler} properties present on the killed text are copied +onto the kill ring, like other text properties. +@end deffn + +@defopt kill-read-only-ok +If this option is non-@code{nil}, @code{kill-region} does not signal an +error if the buffer or text is read-only. Instead, it simply returns, +updating the kill ring but not changing the buffer. +@end defopt + +@deffn Command copy-region-as-kill start end +This command saves the region defined by @var{start} and @var{end} on +the kill ring (including text properties), but does not delete the text +from the buffer. It returns @code{nil}. + +The command does not set @code{this-command} to @code{kill-region}, so a +subsequent kill command does not append to the same kill ring entry. + +Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to +support Emacs 18. For newer Emacs versions, it is better to use +@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill +Ring}. +@end deffn + +@node Yanking +@subsection Yanking + + Yanking means inserting text from the kill ring, but it does +not insert the text blindly. Yank commands and some other commands +use @code{insert-for-yank} to perform special processing on the +text that they copy into the buffer. + +@defun insert-for-yank string +This function normally works like @code{insert} except that it doesn't +insert the text properties in the @code{yank-excluded-properties} +list. However, if any part of @var{string} has a non-@code{nil} +@code{yank-handler} text property, that property can do various +special processing on that part of the text being inserted. +@end defun + +@defun insert-buffer-substring-as-yank buf &optional start end +This function resembles @code{insert-buffer-substring} except that it +doesn't insert the text properties in the +@code{yank-excluded-properties} list. +@end defun + + You can put a @code{yank-handler} text property on all or part of +the text to control how it will be inserted if it is yanked. The +@code{insert-for-yank} function looks for that property. The property +value must be a list of one to four elements, with the following +format (where elements after the first may be omitted): + +@example +(@var{function} @var{param} @var{noexclude} @var{undo}) +@end example + + Here is what the elements do: + +@table @var +@item function +When @var{function} is present and non-@code{nil}, it is called instead of +@code{insert} to insert the string. @var{function} takes one +argument---the string to insert. + +@item param +If @var{param} is present and non-@code{nil}, it replaces @var{string} +(or the part of @var{string} being processed) as the object passed to +@var{function} (or @code{insert}); for example, if @var{function} is +@code{yank-rectangle}, @var{param} should be a list of strings to +insert as a rectangle. + +@item noexclude +If @var{noexclude} is present and non-@code{nil}, the normal removal of the +yank-excluded-properties is not performed; instead @var{function} is +responsible for removing those properties. This may be necessary +if @var{function} adjusts point before or after inserting the object. + +@item undo +If @var{undo} is present and non-@code{nil}, it is a function that will be +called by @code{yank-pop} to undo the insertion of the current object. +It is called with two arguments, the start and end of the current +region. @var{function} can set @code{yank-undo-function} to override +the @var{undo} value. +@end table + +@node Yank Commands +@comment node-name, next, previous, up +@subsection Functions for Yanking + + This section describes higher-level commands for yanking, which are +intended primarily for the user but useful also in Lisp programs. +Both @code{yank} and @code{yank-pop} honor the +@code{yank-excluded-properties} variable and @code{yank-handler} text +property (@pxref{Yanking}). + +@deffn Command yank &optional arg +@cindex inserting killed text +This command inserts before point the text at the front of the +kill ring. It positions the mark at the beginning of that text, and +point at the end. + +If @var{arg} is a non-@code{nil} list (which occurs interactively when +the user types @kbd{C-u} with no digits), then @code{yank} inserts the +text as described above, but puts point before the yanked text and +puts the mark after it. + +If @var{arg} is a number, then @code{yank} inserts the @var{arg}th +most recently killed text---the @var{arg}th element of the kill ring +list, counted cyclically from the front, which is considered the +first element for this purpose. + +@code{yank} does not alter the contents of the kill ring, unless it +used text provided by another program, in which case it pushes that text +onto the kill ring. However if @var{arg} is an integer different from +one, it rotates the kill ring to place the yanked string at the front. + +@code{yank} returns @code{nil}. +@end deffn + +@deffn Command yank-pop &optional arg +This command replaces the just-yanked entry from the kill ring with a +different entry from the kill ring. + +This is allowed only immediately after a @code{yank} or another +@code{yank-pop}. At such a time, the region contains text that was just +inserted by yanking. @code{yank-pop} deletes that text and inserts in +its place a different piece of killed text. It does not add the deleted +text to the kill ring, since it is already in the kill ring somewhere. +It does however rotate the kill ring to place the newly yanked string at +the front. + +If @var{arg} is @code{nil}, then the replacement text is the previous +element of the kill ring. If @var{arg} is numeric, the replacement is +the @var{arg}th previous kill. If @var{arg} is negative, a more recent +kill is the replacement. + +The sequence of kills in the kill ring wraps around, so that after the +oldest one comes the newest one, and before the newest one goes the +oldest. + +The return value is always @code{nil}. +@end deffn + +@defvar yank-undo-function +If this variable is non-@code{nil}, the function @code{yank-pop} uses +its value instead of @code{delete-region} to delete the text +inserted by the previous @code{yank} or +@code{yank-pop} command. The value must be a function of two +arguments, the start and end of the current region. + +The function @code{insert-for-yank} automatically sets this variable +according to the @var{undo} element of the @code{yank-handler} +text property, if there is one. +@end defvar + +@node Low-Level Kill Ring +@subsection Low-Level Kill Ring + + These functions and variables provide access to the kill ring at a +lower level, but still convenient for use in Lisp programs, because they +take care of interaction with window system selections +(@pxref{Window System Selections}). + +@defun current-kill n &optional do-not-move +The function @code{current-kill} rotates the yanking pointer, which +designates the ``front'' of the kill ring, by @var{n} places (from newer +kills to older ones), and returns the text at that place in the ring. + +If the optional second argument @var{do-not-move} is non-@code{nil}, +then @code{current-kill} doesn't alter the yanking pointer; it just +returns the @var{n}th kill, counting from the current yanking pointer. + +If @var{n} is zero, indicating a request for the latest kill, +@code{current-kill} calls the value of +@code{interprogram-paste-function} (documented below) before +consulting the kill ring. If that value is a function and calling it +returns a string, @code{current-kill} pushes that string onto the kill +ring and returns it. It also sets the yanking pointer to point to +that new entry, regardless of the value of @var{do-not-move}. +Otherwise, @code{current-kill} does not treat a zero value for @var{n} +specially: it returns the entry pointed at by the yanking pointer and +does not move the yanking pointer. +@end defun + +@defun kill-new string &optional replace yank-handler +This function pushes the text @var{string} onto the kill ring and +makes the yanking pointer point to it. It discards the oldest entry +if appropriate. It also invokes the value of +@code{interprogram-cut-function} (see below). + +If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the +first element of the kill ring with @var{string}, rather than pushing +@var{string} onto the kill ring. + +If @var{yank-handler} is non-@code{nil}, this puts that value onto +the string of killed text, as a @code{yank-handler} property. +@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then +@code{kill-new} copies any @code{yank-handler} properties present on +@var{string} onto the kill ring, as it does with other text properties. +@end defun + +@defun kill-append string before-p &optional yank-handler +This function appends the text @var{string} to the first entry in the +kill ring and makes the yanking pointer point to the combined entry. +Normally @var{string} goes at the end of the entry, but if +@var{before-p} is non-@code{nil}, it goes at the beginning. This +function also invokes the value of @code{interprogram-cut-function} +(see below). This handles @var{yank-handler} just like +@code{kill-new}, except that if @var{yank-handler} is different from +the @code{yank-handler} property of the first entry of the kill ring, +@code{kill-append} pushes the concatenated string onto the kill ring, +instead of replacing the original first entry with it. +@end defun + +@defvar interprogram-paste-function +This variable provides a way of transferring killed text from other +programs, when you are using a window system. Its value should be +@code{nil} or a function of no arguments. + +If the value is a function, @code{current-kill} calls it to get the +``most recent kill.'' If the function returns a non-@code{nil} value, +then that value is used as the ``most recent kill.'' If it returns +@code{nil}, then the front of the kill ring is used. + +The normal use of this hook is to get the window system's primary +selection as the most recent kill, even if the selection belongs to +another application. @xref{Window System Selections}. +@end defvar + +@defvar interprogram-cut-function +This variable provides a way of communicating killed text to other +programs, when you are using a window system. Its value should be +@code{nil} or a function of one required and one optional argument. + +If the value is a function, @code{kill-new} and @code{kill-append} call +it with the new first element of the kill ring as the first argument. +The second, optional, argument has the same meaning as the @var{push} +argument to @code{x-set-cut-buffer} (@pxref{Definition of +x-set-cut-buffer}) and only affects the second and later cut buffers. + +The normal use of this hook is to set the window system's primary +selection (and first cut buffer) from the newly killed text. +@xref{Window System Selections}. +@end defvar + +@node Internals of Kill Ring +@comment node-name, next, previous, up +@subsection Internals of the Kill Ring + + The variable @code{kill-ring} holds the kill ring contents, in the +form of a list of strings. The most recent kill is always at the front +of the list. + + The @code{kill-ring-yank-pointer} variable points to a link in the +kill ring list, whose @sc{car} is the text to yank next. We say it +identifies the ``front'' of the ring. Moving +@code{kill-ring-yank-pointer} to a different link is called +@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because +the functions that move the yank pointer wrap around from the end of the +list to the beginning, or vice-versa. Rotation of the kill ring is +virtual; it does not change the value of @code{kill-ring}. + + Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp +variables whose values are normally lists. The word ``pointer'' in the +name of the @code{kill-ring-yank-pointer} indicates that the variable's +purpose is to identify one element of the list for use by the next yank +command. + + The value of @code{kill-ring-yank-pointer} is always @code{eq} to one +of the links in the kill ring list. The element it identifies is the +@sc{car} of that link. Kill commands, which change the kill ring, also +set this variable to the value of @code{kill-ring}. The effect is to +rotate the ring so that the newly killed text is at the front. + + Here is a diagram that shows the variable @code{kill-ring-yank-pointer} +pointing to the second entry in the kill ring @code{("some text" "a +different piece of text" "yet older text")}. + +@example +@group +kill-ring ---- kill-ring-yank-pointer + | | + | v + | --- --- --- --- --- --- + --> | | |------> | | |--> | | |--> nil + --- --- --- --- --- --- + | | | + | | | + | | -->"yet older text" + | | + | --> "a different piece of text" + | + --> "some text" +@end group +@end example + +@noindent +This state of affairs might occur after @kbd{C-y} (@code{yank}) +immediately followed by @kbd{M-y} (@code{yank-pop}). + +@defvar kill-ring +This variable holds the list of killed text sequences, most recently +killed first. +@end defvar + +@defvar kill-ring-yank-pointer +This variable's value indicates which element of the kill ring is at the +``front'' of the ring for yanking. More precisely, the value is a tail +of the value of @code{kill-ring}, and its @sc{car} is the kill string +that @kbd{C-y} should yank. +@end defvar + +@defopt kill-ring-max +The value of this variable is the maximum length to which the kill +ring can grow, before elements are thrown away at the end. The default +value for @code{kill-ring-max} is 60. +@end defopt + +@node Undo +@comment node-name, next, previous, up +@section Undo +@cindex redo + + Most buffers have an @dfn{undo list}, which records all changes made +to the buffer's text so that they can be undone. (The buffers that +don't have one are usually special-purpose buffers for which Emacs +assumes that undoing is not useful. In particular, any buffer whose +name begins with a space has its undo recording off by default; +see @ref{Buffer Names}.) All the primitives that modify the +text in the buffer automatically add elements to the front of the undo +list, which is in the variable @code{buffer-undo-list}. + +@defvar buffer-undo-list +This buffer-local variable's value is the undo list of the current +buffer. A value of @code{t} disables the recording of undo information. +@end defvar + +Here are the kinds of elements an undo list can have: + +@table @code +@item @var{position} +This kind of element records a previous value of point; undoing this +element moves point to @var{position}. Ordinary cursor motion does not +make any sort of undo record, but deletion operations use these entries +to record where point was before the command. + +@item (@var{beg} . @var{end}) +This kind of element indicates how to delete text that was inserted. +Upon insertion, the text occupied the range @var{beg}--@var{end} in the +buffer. + +@item (@var{text} . @var{position}) +This kind of element indicates how to reinsert text that was deleted. +The deleted text itself is the string @var{text}. The place to +reinsert it is @code{(abs @var{position})}. If @var{position} is +positive, point was at the beginning of the deleted text, otherwise it +was at the end. + +@item (t @var{high} . @var{low}) +This kind of element indicates that an unmodified buffer became +modified. The elements @var{high} and @var{low} are two integers, each +recording 16 bits of the visited file's modification time as of when it +was previously visited or saved. @code{primitive-undo} uses those +values to determine whether to mark the buffer as unmodified once again; +it does so only if the file's modification time matches those numbers. + +@item (nil @var{property} @var{value} @var{beg} . @var{end}) +This kind of element records a change in a text property. +Here's how you might undo the change: + +@example +(put-text-property @var{beg} @var{end} @var{property} @var{value}) +@end example + +@item (@var{marker} . @var{adjustment}) +This kind of element records the fact that the marker @var{marker} was +relocated due to deletion of surrounding text, and that it moved +@var{adjustment} character positions. Undoing this element moves +@var{marker} @minus{} @var{adjustment} characters. + +@item (apply @var{funname} . @var{args}) +This is an extensible undo item, which is undone by calling +@var{funname} with arguments @var{args}. + +@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) +This is an extensible undo item, which records a change limited to the +range @var{beg} to @var{end}, which increased the size of the buffer +by @var{delta}. It is undone by calling @var{funname} with arguments +@var{args}. + +This kind of element enables undo limited to a region to determine +whether the element pertains to that region. + +@item nil +This element is a boundary. The elements between two boundaries are +called a @dfn{change group}; normally, each change group corresponds to +one keyboard command, and undo commands normally undo an entire group as +a unit. +@end table + +@defun undo-boundary +This function places a boundary element in the undo list. The undo +command stops at such a boundary, and successive undo commands undo +to earlier and earlier boundaries. This function returns @code{nil}. + +The editor command loop automatically creates an undo boundary before +each key sequence is executed. Thus, each undo normally undoes the +effects of one command. Self-inserting input characters are an +exception. The command loop makes a boundary for the first such +character; the next 19 consecutive self-inserting input characters do +not make boundaries, and then the 20th does, and so on as long as +self-inserting characters continue. + +All buffer modifications add a boundary whenever the previous undoable +change was made in some other buffer. This is to ensure that +each command makes a boundary in each buffer where it makes changes. + +Calling this function explicitly is useful for splitting the effects of +a command into more than one unit. For example, @code{query-replace} +calls @code{undo-boundary} after each replacement, so that the user can +undo individual replacements one by one. +@end defun + +@defvar undo-in-progress +This variable is normally @code{nil}, but the undo commands bind it to +@code{t}. This is so that various kinds of change hooks can tell when +they're being called for the sake of undoing. +@end defvar + +@defun primitive-undo count list +This is the basic function for undoing elements of an undo list. +It undoes the first @var{count} elements of @var{list}, returning +the rest of @var{list}. + +@code{primitive-undo} adds elements to the buffer's undo list when it +changes the buffer. Undo commands avoid confusion by saving the undo +list value at the beginning of a sequence of undo operations. Then the +undo operations use and update the saved value. The new elements added +by undoing are not part of this saved value, so they don't interfere with +continuing to undo. + +This function does not bind @code{undo-in-progress}. +@end defun + +@node Maintaining Undo +@section Maintaining Undo Lists + + This section describes how to enable and disable undo information for +a given buffer. It also explains how the undo list is truncated +automatically so it doesn't get too big. + + Recording of undo information in a newly created buffer is normally +enabled to start with; but if the buffer name starts with a space, the +undo recording is initially disabled. You can explicitly enable or +disable undo recording with the following two functions, or by setting +@code{buffer-undo-list} yourself. + +@deffn Command buffer-enable-undo &optional buffer-or-name +This command enables recording undo information for buffer +@var{buffer-or-name}, so that subsequent changes can be undone. If no +argument is supplied, then the current buffer is used. This function +does nothing if undo recording is already enabled in the buffer. It +returns @code{nil}. + +In an interactive call, @var{buffer-or-name} is the current buffer. +You cannot specify any other buffer. +@end deffn + +@deffn Command buffer-disable-undo &optional buffer-or-name +@cindex disabling undo +This function discards the undo list of @var{buffer-or-name}, and disables +further recording of undo information. As a result, it is no longer +possible to undo either previous changes or any subsequent changes. If +the undo list of @var{buffer-or-name} is already disabled, this function +has no effect. + +This function returns @code{nil}. +@end deffn + + As editing continues, undo lists get longer and longer. To prevent +them from using up all available memory space, garbage collection trims +them back to size limits you can set. (For this purpose, the ``size'' +of an undo list measures the cons cells that make up the list, plus the +strings of deleted text.) Three variables control the range of acceptable +sizes: @code{undo-limit}, @code{undo-strong-limit} and +@code{undo-outer-limit}. In these variables, size is counted as the +number of bytes occupied, which includes both saved text and other +data. + +@defopt undo-limit +This is the soft limit for the acceptable size of an undo list. The +change group at which this size is exceeded is the last one kept. +@end defopt + +@defopt undo-strong-limit +This is the upper limit for the acceptable size of an undo list. The +change group at which this size is exceeded is discarded itself (along +with all older change groups). There is one exception: the very latest +change group is only discarded if it exceeds @code{undo-outer-limit}. +@end defopt + +@defopt undo-outer-limit +If at garbage collection time the undo info for the current command +exceeds this limit, Emacs discards the info and displays a warning. +This is a last ditch limit to prevent memory overflow. +@end defopt + +@defopt undo-ask-before-discard +If this variable is non-@code{nil}, when the undo info exceeds +@code{undo-outer-limit}, Emacs asks in the echo area whether to +discard the info. The default value is @code{nil}, which means to +discard it automatically. + +This option is mainly intended for debugging. Garbage collection is +inhibited while the question is asked, which means that Emacs might +leak memory if the user waits too long before answering the question. +@end defopt + +@node Filling +@comment node-name, next, previous, up +@section Filling +@cindex filling text + + @dfn{Filling} means adjusting the lengths of lines (by moving the line +breaks) so that they are nearly (but no greater than) a specified +maximum width. Additionally, lines can be @dfn{justified}, which means +inserting spaces to make the left and/or right margins line up +precisely. The width is controlled by the variable @code{fill-column}. +For ease of reading, lines should be no longer than 70 or so columns. + + You can use Auto Fill mode (@pxref{Auto Filling}) to fill text +automatically as you insert it, but changes to existing text may leave +it improperly filled. Then you must fill the text explicitly. + + Most of the commands in this section return values that are not +meaningful. All the functions that do filling take note of the current +left margin, current right margin, and current justification style +(@pxref{Margins}). If the current justification style is +@code{none}, the filling functions don't actually do anything. + + Several of the filling functions have an argument @var{justify}. +If it is non-@code{nil}, that requests some kind of justification. It +can be @code{left}, @code{right}, @code{full}, or @code{center}, to +request a specific style of justification. If it is @code{t}, that +means to use the current justification style for this part of the text +(see @code{current-justification}, below). Any other value is treated +as @code{full}. + + When you call the filling functions interactively, using a prefix +argument implies the value @code{full} for @var{justify}. + +@deffn Command fill-paragraph justify +This command fills the paragraph at or after point. If +@var{justify} is non-@code{nil}, each line is justified as well. +It uses the ordinary paragraph motion commands to find paragraph +boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. +@end deffn + +@deffn Command fill-region start end &optional justify nosqueeze to-eop +This command fills each of the paragraphs in the region from @var{start} +to @var{end}. It justifies as well if @var{justify} is +non-@code{nil}. + +If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace +other than line breaks untouched. If @var{to-eop} is non-@code{nil}, +that means to keep filling to the end of the paragraph---or the next hard +newline, if @code{use-hard-newlines} is enabled (see below). + +The variable @code{paragraph-separate} controls how to distinguish +paragraphs. @xref{Standard Regexps}. +@end deffn + +@deffn Command fill-paragraph-or-region justify +In Transient Mark mode, when the mark is active, this command calls +@code{fill-region} on the active region. Otherwise, it calls +@code{fill-paragraph}. +@end deffn + +@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp +This command fills each paragraph in the region according to its +individual fill prefix. Thus, if the lines of a paragraph were indented +with spaces, the filled paragraph will remain indented in the same +fashion. + +The first two arguments, @var{start} and @var{end}, are the beginning +and end of the region to be filled. The third and fourth arguments, +@var{justify} and @var{citation-regexp}, are optional. If +@var{justify} is non-@code{nil}, the paragraphs are justified as +well as filled. If @var{citation-regexp} is non-@code{nil}, it means the +function is operating on a mail message and therefore should not fill +the header lines. If @var{citation-regexp} is a string, it is used as +a regular expression; if it matches the beginning of a line, that line +is treated as a citation marker. + +Ordinarily, @code{fill-individual-paragraphs} regards each change in +indentation as starting a new paragraph. If +@code{fill-individual-varying-indent} is non-@code{nil}, then only +separator lines separate paragraphs. That mode can handle indented +paragraphs with additional indentation on the first line. +@end deffn + +@defopt fill-individual-varying-indent +This variable alters the action of @code{fill-individual-paragraphs} as +described above. +@end defopt + +@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after +This command considers a region of text as a single paragraph and fills +it. If the region was made up of many paragraphs, the blank lines +between paragraphs are removed. This function justifies as well as +filling when @var{justify} is non-@code{nil}. + +If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace +other than line breaks untouched. If @var{squeeze-after} is +non-@code{nil}, it specifies a position in the region, and means don't +canonicalize spaces before that position. + +In Adaptive Fill mode, this command calls @code{fill-context-prefix} to +choose a fill prefix by default. @xref{Adaptive Fill}. +@end deffn + +@deffn Command justify-current-line &optional how eop nosqueeze +This command inserts spaces between the words of the current line so +that the line ends exactly at @code{fill-column}. It returns +@code{nil}. + +The argument @var{how}, if non-@code{nil} specifies explicitly the style +of justification. It can be @code{left}, @code{right}, @code{full}, +@code{center}, or @code{none}. If it is @code{t}, that means to do +follow specified justification style (see @code{current-justification}, +below). @code{nil} means to do full justification. + +If @var{eop} is non-@code{nil}, that means do only left-justification +if @code{current-justification} specifies full justification. This is +used for the last line of a paragraph; even if the paragraph as a +whole is fully justified, the last line should not be. + +If @var{nosqueeze} is non-@code{nil}, that means do not change interior +whitespace. +@end deffn + +@defopt default-justification +This variable's value specifies the style of justification to use for +text that doesn't specify a style with a text property. The possible +values are @code{left}, @code{right}, @code{full}, @code{center}, or +@code{none}. The default value is @code{left}. +@end defopt + +@defun current-justification +This function returns the proper justification style to use for filling +the text around point. + +This returns the value of the @code{justification} text property at +point, or the variable @var{default-justification} if there is no such +text property. However, it returns @code{nil} rather than @code{none} +to mean ``don't justify''. +@end defun + +@defopt sentence-end-double-space +@anchor{Definition of sentence-end-double-space} +If this variable is non-@code{nil}, a period followed by just one space +does not count as the end of a sentence, and the filling functions +avoid breaking the line at such a place. +@end defopt + +@defopt sentence-end-without-period +If this variable is non-@code{nil}, a sentence can end without a +period. This is used for languages like Thai, where sentences end +with a double space but without a period. +@end defopt + +@defopt sentence-end-without-space +If this variable is non-@code{nil}, it should be a string of +characters that can end a sentence without following spaces. +@end defopt + +@defvar fill-paragraph-function +This variable provides a way for major modes to override the filling of +paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls +this function to do the work. If the function returns a non-@code{nil} +value, @code{fill-paragraph} assumes the job is done, and immediately +returns that value. + +The usual use of this feature is to fill comments in programming +language modes. If the function needs to fill a paragraph in the usual +way, it can do so as follows: + +@example +(let ((fill-paragraph-function nil)) + (fill-paragraph arg)) +@end example +@end defvar + +@defvar use-hard-newlines +If this variable is non-@code{nil}, the filling functions do not delete +newlines that have the @code{hard} text property. These ``hard +newlines'' act as paragraph separators. +@end defvar + +@node Margins +@section Margins for Filling + +@defopt fill-prefix +This buffer-local variable, if non-@code{nil}, specifies a string of +text that appears at the beginning of normal text lines and should be +disregarded when filling them. Any line that fails to start with the +fill prefix is considered the start of a paragraph; so is any line +that starts with the fill prefix followed by additional whitespace. +Lines that start with the fill prefix but no additional whitespace are +ordinary text lines that can be filled together. The resulting filled +lines also start with the fill prefix. + +The fill prefix follows the left margin whitespace, if any. +@end defopt + +@defopt fill-column +This buffer-local variable specifies the maximum width of filled lines. +Its value should be an integer, which is a number of columns. All the +filling, justification, and centering commands are affected by this +variable, including Auto Fill mode (@pxref{Auto Filling}). + +As a practical matter, if you are writing text for other people to +read, you should set @code{fill-column} to no more than 70. Otherwise +the line will be too long for people to read comfortably, and this can +make the text seem clumsy. +@end defopt + +@defvar default-fill-column +The value of this variable is the default value for @code{fill-column} in +buffers that do not override it. This is the same as +@code{(default-value 'fill-column)}. + +The default value for @code{default-fill-column} is 70. +@end defvar + +@deffn Command set-left-margin from to margin +This sets the @code{left-margin} property on the text from @var{from} to +@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this +command also refills the region to fit the new margin. +@end deffn + +@deffn Command set-right-margin from to margin +This sets the @code{right-margin} property on the text from @var{from} +to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, +this command also refills the region to fit the new margin. +@end deffn + +@defun current-left-margin +This function returns the proper left margin value to use for filling +the text around point. The value is the sum of the @code{left-margin} +property of the character at the start of the current line (or zero if +none), and the value of the variable @code{left-margin}. +@end defun + +@defun current-fill-column +This function returns the proper fill column value to use for filling +the text around point. The value is the value of the @code{fill-column} +variable, minus the value of the @code{right-margin} property of the +character after point. +@end defun + +@deffn Command move-to-left-margin &optional n force +This function moves point to the left margin of the current line. The +column moved to is determined by calling the function +@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, +@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. + +If @var{force} is non-@code{nil}, that says to fix the line's +indentation if that doesn't match the left margin value. +@end deffn + +@defun delete-to-left-margin &optional from to +This function removes left margin indentation from the text between +@var{from} and @var{to}. The amount of indentation to delete is +determined by calling @code{current-left-margin}. In no case does this +function delete non-whitespace. If @var{from} and @var{to} are omitted, +they default to the whole buffer. +@end defun + +@defun indent-to-left-margin +This function adjusts the indentation at the beginning of the current +line to the value specified by the variable @code{left-margin}. (That +may involve either inserting or deleting whitespace.) This function +is value of @code{indent-line-function} in Paragraph-Indent Text mode. +@end defun + +@defvar left-margin +This variable specifies the base left margin column. In Fundamental +mode, @kbd{C-j} indents to this column. This variable automatically +becomes buffer-local when set in any fashion. +@end defvar + +@defvar fill-nobreak-predicate +This variable gives major modes a way to specify not to break a line +at certain places. Its value should be a list of functions. Whenever +filling considers breaking the line at a certain place in the buffer, +it calls each of these functions with no arguments and with point +located at that place. If any of the functions returns +non-@code{nil}, then the line won't be broken there. +@end defvar + +@node Adaptive Fill +@section Adaptive Fill Mode +@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. + + When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill +prefix automatically from the text in each paragraph being filled +rather than using a predetermined value. During filling, this fill +prefix gets inserted at the start of the second and subsequent lines +of the paragraph as described in @ref{Filling}, and in @ref{Auto +Filling}. + +@defopt adaptive-fill-mode +Adaptive Fill mode is enabled when this variable is non-@code{nil}. +It is @code{t} by default. +@end defopt + +@defun fill-context-prefix from to +This function implements the heart of Adaptive Fill mode; it chooses a +fill prefix based on the text between @var{from} and @var{to}, +typically the start and end of a paragraph. It does this by looking +at the first two lines of the paragraph, based on the variables +described below. +@c The optional argument first-line-regexp is not documented +@c because it exists for internal purposes and might be eliminated +@c in the future. + +Usually, this function returns the fill prefix, a string. However, +before doing this, the function makes a final check (not specially +mentioned in the following) that a line starting with this prefix +wouldn't look like the start of a paragraph. Should this happen, the +function signals the anomaly by returning @code{nil} instead. + +In detail, @code{fill-context-prefix} does this: + +@enumerate +@item +It takes a candidate for the fill prefix from the first line---it +tries first the function in @code{adaptive-fill-function} (if any), +then the regular expression @code{adaptive-fill-regexp} (see below). +The first non-@code{nil} result of these, or the empty string if +they're both @code{nil}, becomes the first line's candidate. +@item +If the paragraph has as yet only one line, the function tests the +validity of the prefix candidate just found. The function then +returns the candidate if it's valid, or a string of spaces otherwise. +(see the description of @code{adaptive-fill-first-line-regexp} below). +@item +When the paragraph already has two lines, the function next looks for +a prefix candidate on the second line, in just the same way it did for +the first line. If it doesn't find one, it returns @code{nil}. +@item +The function now compares the two candidate prefixes heuristically: if +the non-whitespace characters in the line 2 candidate occur in the +same order in the line 1 candidate, the function returns the line 2 +candidate. Otherwise, it returns the largest initial substring which +is common to both candidates (which might be the empty string). +@end enumerate +@end defun + +@defopt adaptive-fill-regexp +Adaptive Fill mode matches this regular expression against the text +starting after the left margin whitespace (if any) on a line; the +characters it matches are that line's candidate for the fill prefix. + +The default value matches whitespace with certain punctuation +characters intermingled. +@end defopt + +@defopt adaptive-fill-first-line-regexp +Used only in one-line paragraphs, this regular expression acts as an +additional check of the validity of the one available candidate fill +prefix: the candidate must match this regular expression, or match +@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} +replaces the candidate with a string of spaces ``of the same width'' +as it. + +The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which +matches only a string of whitespace. The effect of this default is to +force the fill prefixes found in one-line paragraphs always to be pure +whitespace. +@end defopt + +@defopt adaptive-fill-function +You can specify more complex ways of choosing a fill prefix +automatically by setting this variable to a function. The function is +called with point after the left margin (if any) of a line, and it +must preserve point. It should return either ``that line's'' fill +prefix or @code{nil}, meaning it has failed to determine a prefix. +@end defopt + +@node Auto Filling +@comment node-name, next, previous, up +@section Auto Filling +@cindex filling, automatic +@cindex Auto Fill mode + + Auto Fill mode is a minor mode that fills lines automatically as text +is inserted. This section describes the hook used by Auto Fill mode. +For a description of functions that you can call explicitly to fill and +justify existing text, see @ref{Filling}. + + Auto Fill mode also enables the functions that change the margins and +justification style to refill portions of the text. @xref{Margins}. + +@defvar auto-fill-function +The value of this buffer-local variable should be a function (of no +arguments) to be called after self-inserting a character from the table +@code{auto-fill-chars}. It may be @code{nil}, in which case nothing +special is done in that case. + +The value of @code{auto-fill-function} is @code{do-auto-fill} when +Auto-Fill mode is enabled. That is a function whose sole purpose is to +implement the usual strategy for breaking a line. + +@quotation +In older Emacs versions, this variable was named @code{auto-fill-hook}, +but since it is not called with the standard convention for hooks, it +was renamed to @code{auto-fill-function} in version 19. +@end quotation +@end defvar + +@defvar normal-auto-fill-function +This variable specifies the function to use for +@code{auto-fill-function}, if and when Auto Fill is turned on. Major +modes can set buffer-local values for this variable to alter how Auto +Fill works. +@end defvar + +@defvar auto-fill-chars +A char table of characters which invoke @code{auto-fill-function} when +self-inserted---space and newline in most language environments. They +have an entry @code{t} in the table. +@end defvar + +@node Sorting +@section Sorting Text +@cindex sorting text + + The sorting functions described in this section all rearrange text in +a buffer. This is in contrast to the function @code{sort}, which +rearranges the order of the elements of a list (@pxref{Rearrangement}). +The values returned by these functions are not meaningful. + +@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate +This function is the general text-sorting routine that subdivides a +buffer into records and then sorts them. Most of the commands in this +section use this function. + +To understand how @code{sort-subr} works, consider the whole accessible +portion of the buffer as being divided into disjoint pieces called +@dfn{sort records}. The records may or may not be contiguous, but they +must not overlap. A portion of each sort record (perhaps all of it) is +designated as the sort key. Sorting rearranges the records in order by +their sort keys. + +Usually, the records are rearranged in order of ascending sort key. +If the first argument to the @code{sort-subr} function, @var{reverse}, +is non-@code{nil}, the sort records are rearranged in order of +descending sort key. + +The next four arguments to @code{sort-subr} are functions that are +called to move point across a sort record. They are called many times +from within @code{sort-subr}. + +@enumerate +@item +@var{nextrecfun} is called with point at the end of a record. This +function moves point to the start of the next record. The first record +is assumed to start at the position of point when @code{sort-subr} is +called. Therefore, you should usually move point to the beginning of +the buffer before calling @code{sort-subr}. + +This function can indicate there are no more sort records by leaving +point at the end of the buffer. + +@item +@var{endrecfun} is called with point within a record. It moves point to +the end of the record. + +@item +@var{startkeyfun} is called to move point from the start of a record to +the start of the sort key. This argument is optional; if it is omitted, +the whole record is the sort key. If supplied, the function should +either return a non-@code{nil} value to be used as the sort key, or +return @code{nil} to indicate that the sort key is in the buffer +starting at point. In the latter case, @var{endkeyfun} is called to +find the end of the sort key. + +@item +@var{endkeyfun} is called to move point from the start of the sort key +to the end of the sort key. This argument is optional. If +@var{startkeyfun} returns @code{nil} and this argument is omitted (or +@code{nil}), then the sort key extends to the end of the record. There +is no need for @var{endkeyfun} if @var{startkeyfun} returns a +non-@code{nil} value. +@end enumerate + +The argument @var{predicate} is the function to use to compare keys. +If keys are numbers, it defaults to @code{<}; otherwise it defaults to +@code{string<}. + +As an example of @code{sort-subr}, here is the complete function +definition for @code{sort-lines}: + +@example +@group +;; @r{Note that the first two lines of doc string} +;; @r{are effectively one line when viewed by a user.} +(defun sort-lines (reverse beg end) + "Sort lines in region alphabetically;\ + argument means descending order. +Called from a program, there are three arguments: +@end group +@group +REVERSE (non-nil means reverse order),\ + BEG and END (region to sort). +The variable `sort-fold-case' determines\ + whether alphabetic case affects +the sort order." +@end group +@group + (interactive "P\nr") + (save-excursion + (save-restriction + (narrow-to-region beg end) + (goto-char (point-min)) + (let ((inhibit-field-text-motion t)) + (sort-subr reverse 'forward-line 'end-of-line))))) +@end group +@end example + +Here @code{forward-line} moves point to the start of the next record, +and @code{end-of-line} moves point to the end of record. We do not pass +the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire +record is used as the sort key. + +The @code{sort-paragraphs} function is very much the same, except that +its @code{sort-subr} call looks like this: + +@example +@group +(sort-subr reverse + (function + (lambda () + (while (and (not (eobp)) + (looking-at paragraph-separate)) + (forward-line 1)))) + 'forward-paragraph) +@end group +@end example + +Markers pointing into any sort records are left with no useful +position after @code{sort-subr} returns. +@end defun + +@defopt sort-fold-case +If this variable is non-@code{nil}, @code{sort-subr} and the other +buffer sorting functions ignore case when comparing strings. +@end defopt + +@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end +This command sorts the region between @var{start} and @var{end} +alphabetically as specified by @var{record-regexp} and @var{key-regexp}. +If @var{reverse} is a negative integer, then sorting is in reverse +order. + +Alphabetical sorting means that two sort keys are compared by +comparing the first characters of each, the second characters of each, +and so on. If a mismatch is found, it means that the sort keys are +unequal; the sort key whose character is less at the point of first +mismatch is the lesser sort key. The individual characters are compared +according to their numerical character codes in the Emacs character set. + +The value of the @var{record-regexp} argument specifies how to divide +the buffer into sort records. At the end of each record, a search is +done for this regular expression, and the text that matches it is taken +as the next record. For example, the regular expression @samp{^.+$}, +which matches lines with at least one character besides a newline, would +make each such line into a sort record. @xref{Regular Expressions}, for +a description of the syntax and meaning of regular expressions. + +The value of the @var{key-regexp} argument specifies what part of each +record is the sort key. The @var{key-regexp} could match the whole +record, or only a part. In the latter case, the rest of the record has +no effect on the sorted order of records, but it is carried along when +the record moves to its new position. + +The @var{key-regexp} argument can refer to the text matched by a +subexpression of @var{record-regexp}, or it can be a regular expression +on its own. + +If @var{key-regexp} is: + +@table @asis +@item @samp{\@var{digit}} +then the text matched by the @var{digit}th @samp{\(...\)} parenthesis +grouping in @var{record-regexp} is the sort key. + +@item @samp{\&} +then the whole record is the sort key. + +@item a regular expression +then @code{sort-regexp-fields} searches for a match for the regular +expression within the record. If such a match is found, it is the sort +key. If there is no match for @var{key-regexp} within a record then +that record is ignored, which means its position in the buffer is not +changed. (The other records may move around it.) +@end table + +For example, if you plan to sort all the lines in the region by the +first word on each line starting with the letter @samp{f}, you should +set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to +@samp{\}. The resulting expression looks like this: + +@example +@group +(sort-regexp-fields nil "^.*$" "\\" + (region-beginning) + (region-end)) +@end group +@end example + +If you call @code{sort-regexp-fields} interactively, it prompts for +@var{record-regexp} and @var{key-regexp} in the minibuffer. +@end deffn + +@deffn Command sort-lines reverse start end +This command alphabetically sorts lines in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-paragraphs reverse start end +This command alphabetically sorts paragraphs in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-pages reverse start end +This command alphabetically sorts pages in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-fields field start end +This command sorts lines in the region between @var{start} and +@var{end}, comparing them alphabetically by the @var{field}th field +of each line. Fields are separated by whitespace and numbered starting +from 1. If @var{field} is negative, sorting is by the +@w{@minus{}@var{field}th} field from the end of the line. This command +is useful for sorting tables. +@end deffn + +@deffn Command sort-numeric-fields field start end +This command sorts lines in the region between @var{start} and +@var{end}, comparing them numerically by the @var{field}th field of +each line. Fields are separated by whitespace and numbered starting +from 1. The specified field must contain a number in each line of the +region. Numbers starting with 0 are treated as octal, and numbers +starting with @samp{0x} are treated as hexadecimal. + +If @var{field} is negative, sorting is by the +@w{@minus{}@var{field}th} field from the end of the line. This +command is useful for sorting tables. +@end deffn + +@defopt sort-numeric-base +This variable specifies the default radix for +@code{sort-numeric-fields} to parse numbers. +@end defopt + +@deffn Command sort-columns reverse &optional beg end +This command sorts the lines in the region between @var{beg} and +@var{end}, comparing them alphabetically by a certain range of +columns. The column positions of @var{beg} and @var{end} bound the +range of columns to sort on. + +If @var{reverse} is non-@code{nil}, the sort is in reverse order. + +One unusual thing about this command is that the entire line +containing position @var{beg}, and the entire line containing position +@var{end}, are included in the region sorted. + +Note that @code{sort-columns} rejects text that contains tabs, because +tabs could be split across the specified columns. Use @kbd{M-x +untabify} to convert tabs to spaces before sorting. + +When possible, this command actually works by calling the @code{sort} +utility program. +@end deffn + +@node Columns +@comment node-name, next, previous, up +@section Counting Columns +@cindex columns +@cindex counting columns +@cindex horizontal position + + The column functions convert between a character position (counting +characters from the beginning of the buffer) and a column position +(counting screen characters from the beginning of a line). + + These functions count each character according to the number of +columns it occupies on the screen. This means control characters count +as occupying 2 or 4 columns, depending upon the value of +@code{ctl-arrow}, and tabs count as occupying a number of columns that +depends on the value of @code{tab-width} and on the column where the tab +begins. @xref{Usual Display}. + + Column number computations ignore the width of the window and the +amount of horizontal scrolling. Consequently, a column value can be +arbitrarily high. The first (or leftmost) column is numbered 0. They +also ignore overlays and text properties, aside from invisibility. + +@defun current-column +This function returns the horizontal position of point, measured in +columns, counting from 0 at the left margin. The column position is the +sum of the widths of all the displayed representations of the characters +between the start of the current line and point. + +For an example of using @code{current-column}, see the description of +@code{count-lines} in @ref{Text Lines}. +@end defun + +@defun move-to-column column &optional force +This function moves point to @var{column} in the current line. The +calculation of @var{column} takes into account the widths of the +displayed representations of the characters between the start of the +line and point. + +If column @var{column} is beyond the end of the line, point moves to the +end of the line. If @var{column} is negative, point moves to the +beginning of the line. + +If it is impossible to move to column @var{column} because that is in +the middle of a multicolumn character such as a tab, point moves to the +end of that character. However, if @var{force} is non-@code{nil}, and +@var{column} is in the middle of a tab, then @code{move-to-column} +converts the tab into spaces so that it can move precisely to column +@var{column}. Other multicolumn characters can cause anomalies despite +@var{force}, since there is no way to split them. + +The argument @var{force} also has an effect if the line isn't long +enough to reach column @var{column}; if it is @code{t}, that means to +add whitespace at the end of the line to reach that column. + +If @var{column} is not an integer, an error is signaled. + +The return value is the column number actually moved to. +@end defun + +@node Indentation +@section Indentation +@cindex indentation + + The indentation functions are used to examine, move to, and change +whitespace that is at the beginning of a line. Some of the functions +can also change whitespace elsewhere on a line. Columns and indentation +count from zero at the left margin. + +@menu +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. +@end menu + +@node Primitive Indent +@subsection Indentation Primitives + + This section describes the primitive functions used to count and +insert indentation. The functions in the following sections use these +primitives. @xref{Width}, for related functions. + +@defun current-indentation +@comment !!Type Primitive Function +@comment !!SourceFile indent.c +This function returns the indentation of the current line, which is +the horizontal position of the first nonblank character. If the +contents are entirely blank, then this is the horizontal position of the +end of the line. +@end defun + +@deffn Command indent-to column &optional minimum +@comment !!Type Primitive Function +@comment !!SourceFile indent.c +This function indents from point with tabs and spaces until @var{column} +is reached. If @var{minimum} is specified and non-@code{nil}, then at +least that many spaces are inserted even if this requires going beyond +@var{column}. Otherwise the function does nothing if point is already +beyond @var{column}. The value is the column at which the inserted +indentation ends. + +The inserted whitespace characters inherit text properties from the +surrounding text (usually, from the preceding text only). @xref{Sticky +Properties}. +@end deffn + +@defopt indent-tabs-mode +@comment !!SourceFile indent.c +If this variable is non-@code{nil}, indentation functions can insert +tabs as well as spaces. Otherwise, they insert only spaces. Setting +this variable automatically makes it buffer-local in the current buffer. +@end defopt + +@node Mode-Specific Indent +@subsection Indentation Controlled by Major Mode + + An important function of each major mode is to customize the @key{TAB} +key to indent properly for the language being edited. This section +describes the mechanism of the @key{TAB} key and how to control it. +The functions in this section return unpredictable values. + +@defvar indent-line-function +This variable's value is the function to be used by @key{TAB} (and +various commands) to indent the current line. The command +@code{indent-according-to-mode} does no more than call this function. + +In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C +mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. +The default value is @code{indent-relative}. +@end defvar + +@deffn Command indent-according-to-mode +This command calls the function in @code{indent-line-function} to +indent the current line in a way appropriate for the current major mode. +@end deffn + +@deffn Command indent-for-tab-command +This command calls the function in @code{indent-line-function} to indent +the current line; however, if that function is +@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That +is a trivial command that inserts a tab character.) +@end deffn + +@deffn Command newline-and-indent +@comment !!SourceFile simple.el +This function inserts a newline, then indents the new line (the one +following the newline just inserted) according to the major mode. + +It does indentation by calling the current @code{indent-line-function}. +In programming language modes, this is the same thing @key{TAB} does, +but in some text modes, where @key{TAB} inserts a tab, +@code{newline-and-indent} indents to the column specified by +@code{left-margin}. +@end deffn + +@deffn Command reindent-then-newline-and-indent +@comment !!SourceFile simple.el +This command reindents the current line, inserts a newline at point, +and then indents the new line (the one following the newline just +inserted). + +This command does indentation on both lines according to the current +major mode, by calling the current value of @code{indent-line-function}. +In programming language modes, this is the same thing @key{TAB} does, +but in some text modes, where @key{TAB} inserts a tab, +@code{reindent-then-newline-and-indent} indents to the column specified +by @code{left-margin}. +@end deffn + +@node Region Indent +@subsection Indenting an Entire Region + + This section describes commands that indent all the lines in the +region. They return unpredictable values. + +@deffn Command indent-region start end to-column +This command indents each nonblank line starting between @var{start} +(inclusive) and @var{end} (exclusive). If @var{to-column} is +@code{nil}, @code{indent-region} indents each nonblank line by calling +the current mode's indentation function, the value of +@code{indent-line-function}. + +If @var{to-column} is non-@code{nil}, it should be an integer +specifying the number of columns of indentation; then this function +gives each line exactly that much indentation, by either adding or +deleting whitespace. + +If there is a fill prefix, @code{indent-region} indents each line +by making it start with the fill prefix. +@end deffn + +@defvar indent-region-function +The value of this variable is a function that can be used by +@code{indent-region} as a short cut. It should take two arguments, the +start and end of the region. You should design the function so +that it will produce the same results as indenting the lines of the +region one by one, but presumably faster. + +If the value is @code{nil}, there is no short cut, and +@code{indent-region} actually works line by line. + +A short-cut function is useful in modes such as C mode and Lisp mode, +where the @code{indent-line-function} must scan from the beginning of +the function definition: applying it to each line would be quadratic in +time. The short cut can update the scan information as it moves through +the lines indenting them; this takes linear time. In a mode where +indenting a line individually is fast, there is no need for a short cut. + +@code{indent-region} with a non-@code{nil} argument @var{to-column} has +a different meaning and does not use this variable. +@end defvar + +@deffn Command indent-rigidly start end count +@comment !!SourceFile indent.el +This command indents all lines starting between @var{start} +(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. +This ``preserves the shape'' of the affected region, moving it as a +rigid unit. Consequently, this command is useful not only for indenting +regions of unindented text, but also for indenting regions of formatted +code. + +For example, if @var{count} is 3, this command adds 3 columns of +indentation to each of the lines beginning in the region specified. + +In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses +@code{indent-rigidly} to indent the text copied from the message being +replied to. +@end deffn + +@defun indent-code-rigidly start end columns &optional nochange-regexp +This is like @code{indent-rigidly}, except that it doesn't alter lines +that start within strings or comments. + +In addition, it doesn't alter a line if @var{nochange-regexp} matches at +the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). +@end defun + +@node Relative Indent +@subsection Indentation Relative to Previous Lines + + This section describes two commands that indent the current line +based on the contents of previous lines. + +@deffn Command indent-relative &optional unindented-ok +This command inserts whitespace at point, extending to the same +column as the next @dfn{indent point} of the previous nonblank line. An +indent point is a non-whitespace character following whitespace. The +next indent point is the first one at a column greater than the current +column of point. For example, if point is underneath and to the left of +the first non-blank character of a line of text, it moves to that column +by inserting whitespace. + +If the previous nonblank line has no next indent point (i.e., none at a +great enough column position), @code{indent-relative} either does +nothing (if @var{unindented-ok} is non-@code{nil}) or calls +@code{tab-to-tab-stop}. Thus, if point is underneath and to the right +of the last column of a short line of text, this command ordinarily +moves point to the next tab stop by inserting whitespace. + +The return value of @code{indent-relative} is unpredictable. + +In the following example, point is at the beginning of the second +line: + +@example +@group + This line is indented twelve spaces. +@point{}The quick brown fox jumped. +@end group +@end example + +@noindent +Evaluation of the expression @code{(indent-relative nil)} produces the +following: + +@example +@group + This line is indented twelve spaces. + @point{}The quick brown fox jumped. +@end group +@end example + + In this next example, point is between the @samp{m} and @samp{p} of +@samp{jumped}: + +@example +@group + This line is indented twelve spaces. +The quick brown fox jum@point{}ped. +@end group +@end example + +@noindent +Evaluation of the expression @code{(indent-relative nil)} produces the +following: + +@example +@group + This line is indented twelve spaces. +The quick brown fox jum @point{}ped. +@end group +@end example +@end deffn + +@deffn Command indent-relative-maybe +@comment !!SourceFile indent.el +This command indents the current line like the previous nonblank line, +by calling @code{indent-relative} with @code{t} as the +@var{unindented-ok} argument. The return value is unpredictable. + +If the previous nonblank line has no indent points beyond the current +column, this command does nothing. +@end deffn + +@node Indent Tabs +@comment node-name, next, previous, up +@subsection Adjustable ``Tab Stops'' +@cindex tabs stops for indentation + + This section explains the mechanism for user-specified ``tab stops'' +and the mechanisms that use and set them. The name ``tab stops'' is +used because the feature is similar to that of the tab stops on a +typewriter. The feature works by inserting an appropriate number of +spaces and tab characters to reach the next tab stop column; it does not +affect the display of tab characters in the buffer (@pxref{Usual +Display}). Note that the @key{TAB} character as input uses this tab +stop feature only in a few major modes, such as Text mode. +@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. + +@deffn Command tab-to-tab-stop +This command inserts spaces or tabs before point, up to the next tab +stop column defined by @code{tab-stop-list}. It searches the list for +an element greater than the current column number, and uses that element +as the column to indent to. It does nothing if no such element is +found. +@end deffn + +@defopt tab-stop-list +This variable is the list of tab stop columns used by +@code{tab-to-tab-stops}. The elements should be integers in increasing +order. The tab stop columns need not be evenly spaced. + +Use @kbd{M-x edit-tab-stops} to edit the location of tab stops +interactively. +@end defopt + +@node Motion by Indent +@subsection Indentation-Based Motion Commands + + These commands, primarily for interactive use, act based on the +indentation in the text. + +@deffn Command back-to-indentation +@comment !!SourceFile simple.el +This command moves point to the first non-whitespace character in the +current line (which is the line in which point is located). It returns +@code{nil}. +@end deffn + +@deffn Command backward-to-indentation &optional arg +@comment !!SourceFile simple.el +This command moves point backward @var{arg} lines and then to the +first nonblank character on that line. It returns @code{nil}. +If @var{arg} is omitted or @code{nil}, it defaults to 1. +@end deffn + +@deffn Command forward-to-indentation &optional arg +@comment !!SourceFile simple.el +This command moves point forward @var{arg} lines and then to the first +nonblank character on that line. It returns @code{nil}. +If @var{arg} is omitted or @code{nil}, it defaults to 1. +@end deffn + +@node Case Changes +@comment node-name, next, previous, up +@section Case Changes +@cindex case conversion in buffers + + The case change commands described here work on text in the current +buffer. @xref{Case Conversion}, for case conversion functions that work +on strings and characters. @xref{Case Tables}, for how to customize +which characters are upper or lower case and how to convert them. + +@deffn Command capitalize-region start end +This function capitalizes all words in the region defined by +@var{start} and @var{end}. To capitalize means to convert each word's +first character to upper case and convert the rest of each word to lower +case. The function returns @code{nil}. + +If one end of the region is in the middle of a word, the part of the +word within the region is treated as an entire word. + +When @code{capitalize-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. + +@example +@group +---------- Buffer: foo ---------- +This is the contents of the 5th foo. +---------- Buffer: foo ---------- +@end group + +@group +(capitalize-region 1 44) +@result{} nil + +---------- Buffer: foo ---------- +This Is The Contents Of The 5th Foo. +---------- Buffer: foo ---------- +@end group +@end example +@end deffn + +@deffn Command downcase-region start end +This function converts all of the letters in the region defined by +@var{start} and @var{end} to lower case. The function returns +@code{nil}. + +When @code{downcase-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. +@end deffn + +@deffn Command upcase-region start end +This function converts all of the letters in the region defined by +@var{start} and @var{end} to upper case. The function returns +@code{nil}. + +When @code{upcase-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. +@end deffn + +@deffn Command capitalize-word count +This function capitalizes @var{count} words after point, moving point +over as it does. To capitalize means to convert each word's first +character to upper case and convert the rest of each word to lower case. +If @var{count} is negative, the function capitalizes the +@minus{}@var{count} previous words but does not move point. The value +is @code{nil}. + +If point is in the middle of a word, the part of the word before point +is ignored when moving forward. The rest is treated as an entire word. + +When @code{capitalize-word} is called interactively, @var{count} is +set to the numeric prefix argument. +@end deffn + +@deffn Command downcase-word count +This function converts the @var{count} words after point to all lower +case, moving point over as it does. If @var{count} is negative, it +converts the @minus{}@var{count} previous words but does not move point. +The value is @code{nil}. + +When @code{downcase-word} is called interactively, @var{count} is set +to the numeric prefix argument. +@end deffn + +@deffn Command upcase-word count +This function converts the @var{count} words after point to all upper +case, moving point over as it does. If @var{count} is negative, it +converts the @minus{}@var{count} previous words but does not move point. +The value is @code{nil}. + +When @code{upcase-word} is called interactively, @var{count} is set to +the numeric prefix argument. +@end deffn + +@node Text Properties +@section Text Properties +@cindex text properties +@cindex attributes of text +@cindex properties of text + + Each character position in a buffer or a string can have a @dfn{text +property list}, much like the property list of a symbol (@pxref{Property +Lists}). The properties belong to a particular character at a +particular place, such as, the letter @samp{T} at the beginning of this +sentence or the first @samp{o} in @samp{foo}---if the same character +occurs in two different places, the two occurrences in general have +different properties. + + Each property has a name and a value. Both of these can be any Lisp +object, but the name is normally a symbol. Typically each property +name symbol is used for a particular purpose; for instance, the text +property @code{face} specifies the faces for displaying the character +(@pxref{Special Properties}). The usual way to access the property +list is to specify a name and ask what value corresponds to it. + + If a character has a @code{category} property, we call it the +@dfn{property category} of the character. It should be a symbol. The +properties of the symbol serve as defaults for the properties of the +character. + + Copying text between strings and buffers preserves the properties +along with the characters; this includes such diverse functions as +@code{substring}, @code{insert}, and @code{buffer-substring}. + +@menu +* Examining Properties:: Looking at the properties of one character. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. +* Format Properties:: Properties for representing formatting of text. +* Sticky Properties:: How inserted text gets properties from + neighboring text. +* Lazy Properties:: Computing text properties in a lazy fashion + only when text is examined. +* Clickable Text:: Using text properties to make regions of text + do something when you click on them. +* Links and Mouse-1:: How to make @key{Mouse-1} follow a link. +* Fields:: The @code{field} property defines + fields within the buffer. +* Not Intervals:: Why text properties do not use + Lisp-visible text intervals. +@end menu + +@node Examining Properties +@subsection Examining Text Properties + + The simplest way to examine text properties is to ask for the value of +a particular property of a particular character. For that, use +@code{get-text-property}. Use @code{text-properties-at} to get the +entire property list of a character. @xref{Property Search}, for +functions to examine the properties of a number of characters at once. + + These functions handle both strings and buffers. Keep in mind that +positions in a string start from 0, whereas positions in a buffer start +from 1. + +@defun get-text-property pos prop &optional object +This function returns the value of the @var{prop} property of the +character after position @var{pos} in @var{object} (a buffer or +string). The argument @var{object} is optional and defaults to the +current buffer. + +If there is no @var{prop} property strictly speaking, but the character +has a property category that is a symbol, then @code{get-text-property} returns +the @var{prop} property of that symbol. +@end defun + +@defun get-char-property position prop &optional object +This function is like @code{get-text-property}, except that it checks +overlays first and then text properties. @xref{Overlays}. + - The argument @var{object} may be a string, a buffer, or a window. If it - is a window, then the buffer displayed in that window is used for text - properties and overlays, but only the overlays active for that window - are considered. If @var{object} is a buffer, then all overlays in that - buffer are considered, as well as text properties. If @var{object} is a - string, only text properties are considered, since strings never have - overlays. ++The argument @var{object} may be a string, a buffer, or a window. If ++it is a window, then the buffer displayed in that window is used for ++text properties and overlays, but only the overlays active for that ++window are considered. If @var{object} is a buffer, then overlays in ++that buffer are considered first, in order of decreasing priority, ++followed by the text properties. If @var{object} is a string, only ++text properties are considered, since strings never have overlays. +@end defun + +@defun get-char-property-and-overlay position prop &optional object +This is like @code{get-char-property}, but gives extra information +about the overlay that the property value comes from. + +Its value is a cons cell whose @sc{car} is the property value, the +same value @code{get-char-property} would return with the same +arguments. Its @sc{cdr} is the overlay in which the property was +found, or @code{nil}, if it was found as a text property or not found +at all. + +If @var{position} is at the end of @var{object}, both the @sc{car} and +the @sc{cdr} of the value are @code{nil}. +@end defun + +@defvar char-property-alias-alist +This variable holds an alist which maps property names to a list of +alternative property names. If a character does not specify a direct +value for a property, the alternative property names are consulted in +order; the first non-@code{nil} value is used. This variable takes +precedence over @code{default-text-properties}, and @code{category} +properties take precedence over this variable. +@end defvar + +@defun text-properties-at position &optional object +This function returns the entire property list of the character at +@var{position} in the string or buffer @var{object}. If @var{object} is +@code{nil}, it defaults to the current buffer. +@end defun + +@defvar default-text-properties +This variable holds a property list giving default values for text +properties. Whenever a character does not specify a value for a +property, neither directly, through a category symbol, or through +@code{char-property-alias-alist}, the value stored in this list is +used instead. Here is an example: + +@example +(setq default-text-properties '(foo 69) + char-property-alias-alist nil) +;; @r{Make sure character 1 has no properties of its own.} +(set-text-properties 1 2 nil) +;; @r{What we get, when we ask, is the default value.} +(get-text-property 1 'foo) + @result{} 69 +@end example +@end defvar + +@node Changing Properties +@subsection Changing Text Properties + + The primitives for changing properties apply to a specified range of +text in a buffer or string. The function @code{set-text-properties} +(see end of section) sets the entire property list of the text in that +range; more often, it is useful to add, change, or delete just certain +properties specified by name. + + Since text properties are considered part of the contents of the +buffer (or string), and can affect how a buffer looks on the screen, +any change in buffer text properties marks the buffer as modified. +Buffer text property changes are undoable also (@pxref{Undo}). +Positions in a string start from 0, whereas positions in a buffer +start from 1. + +@defun put-text-property start end prop value &optional object +This function sets the @var{prop} property to @var{value} for the text +between @var{start} and @var{end} in the string or buffer @var{object}. +If @var{object} is @code{nil}, it defaults to the current buffer. +@end defun + +@defun add-text-properties start end props &optional object +This function adds or overrides text properties for the text between +@var{start} and @var{end} in the string or buffer @var{object}. If +@var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} specifies which properties to add. It should +have the form of a property list (@pxref{Property Lists}): a list whose +elements include the property names followed alternately by the +corresponding values. + +The return value is @code{t} if the function actually changed some +property's value; @code{nil} otherwise (if @var{props} is @code{nil} or +its values agree with those in the text). + +For example, here is how to set the @code{comment} and @code{face} +properties of a range of text: + +@example +(add-text-properties @var{start} @var{end} + '(comment t face highlight)) +@end example +@end defun + +@defun remove-text-properties start end props &optional object +This function deletes specified text properties from the text between +@var{start} and @var{end} in the string or buffer @var{object}. If +@var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} specifies which properties to delete. It +should have the form of a property list (@pxref{Property Lists}): a list +whose elements are property names alternating with corresponding values. +But only the names matter---the values that accompany them are ignored. +For example, here's how to remove the @code{face} property. + +@example +(remove-text-properties @var{start} @var{end} '(face nil)) +@end example + +The return value is @code{t} if the function actually changed some +property's value; @code{nil} otherwise (if @var{props} is @code{nil} or +if no character in the specified text had any of those properties). + +To remove all text properties from certain text, use +@code{set-text-properties} and specify @code{nil} for the new property +list. +@end defun + +@defun remove-list-of-text-properties start end list-of-properties &optional object +Like @code{remove-text-properties} except that +@var{list-of-properties} is a list of property names only, not an +alternating list of property names and values. +@end defun + +@defun set-text-properties start end props &optional object +This function completely replaces the text property list for the text +between @var{start} and @var{end} in the string or buffer @var{object}. +If @var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} is the new property list. It should be a list +whose elements are property names alternating with corresponding values. + +After @code{set-text-properties} returns, all the characters in the +specified range have identical properties. + +If @var{props} is @code{nil}, the effect is to get rid of all properties +from the specified range of text. Here's an example: + +@example +(set-text-properties @var{start} @var{end} nil) +@end example + +Do not rely on the return value of this function. +@end defun + + The easiest way to make a string with text properties +is with @code{propertize}: + +@defun propertize string &rest properties +This function returns a copy of @var{string} which has the text +properties @var{properties}. These properties apply to all the +characters in the string that is returned. Here is an example that +constructs a string with a @code{face} property and a @code{mouse-face} +property: + +@smallexample +(propertize "foo" 'face 'italic + 'mouse-face 'bold-italic) + @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) +@end smallexample + +To put different properties on various parts of a string, you can +construct each part with @code{propertize} and then combine them with +@code{concat}: + +@smallexample +(concat + (propertize "foo" 'face 'italic + 'mouse-face 'bold-italic) + " and " + (propertize "bar" 'face 'italic + 'mouse-face 'bold-italic)) + @result{} #("foo and bar" + 0 3 (face italic mouse-face bold-italic) + 3 8 nil + 8 11 (face italic mouse-face bold-italic)) +@end smallexample +@end defun + + See also the function @code{buffer-substring-no-properties} +(@pxref{Buffer Contents}) which copies text from the buffer +but does not copy its properties. + +@node Property Search +@subsection Text Property Search Functions + + In typical use of text properties, most of the time several or many +consecutive characters have the same value for a property. Rather than +writing your programs to examine characters one by one, it is much +faster to process chunks of text that have the same property value. + + Here are functions you can use to do this. They use @code{eq} for +comparing property values. In all cases, @var{object} defaults to the +current buffer. + + For high performance, it's very important to use the @var{limit} +argument to these functions, especially the ones that search for a +single property---otherwise, they may spend a long time scanning to the +end of the buffer, if the property you are interested in does not change. + + These functions do not move point; instead, they return a position (or +@code{nil}). Remember that a position is always between two characters; +the position returned by these functions is between two characters with +different properties. + +@defun next-property-change pos &optional object limit +The function scans the text forward from position @var{pos} in the +string or buffer @var{object} till it finds a change in some text +property, then returns the position of the change. In other words, it +returns the position of the first character beyond @var{pos} whose +properties are not identical to those of the character just after +@var{pos}. + +If @var{limit} is non-@code{nil}, then the scan ends at position +@var{limit}. If there is no property change before that point, +@code{next-property-change} returns @var{limit}. + +The value is @code{nil} if the properties remain unchanged all the way +to the end of @var{object} and @var{limit} is @code{nil}. If the value +is non-@code{nil}, it is a position greater than or equal to @var{pos}. +The value equals @var{pos} only when @var{limit} equals @var{pos}. + +Here is an example of how to scan the buffer by chunks of text within +which all properties are constant: + +@smallexample +(while (not (eobp)) + (let ((plist (text-properties-at (point))) + (next-change + (or (next-property-change (point) (current-buffer)) + (point-max)))) + @r{Process text from point to @var{next-change}@dots{}} + (goto-char next-change))) +@end smallexample +@end defun + +@defun previous-property-change pos &optional object limit +This is like @code{next-property-change}, but scans back from @var{pos} +instead of forward. If the value is non-@code{nil}, it is a position +less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} +equals @var{pos}. +@end defun + +@defun next-single-property-change pos prop &optional object limit +The function scans text for a change in the @var{prop} property, then +returns the position of the change. The scan goes forward from +position @var{pos} in the string or buffer @var{object}. In other +words, this function returns the position of the first character +beyond @var{pos} whose @var{prop} property differs from that of the +character just after @var{pos}. + +If @var{limit} is non-@code{nil}, then the scan ends at position +@var{limit}. If there is no property change before that point, +@code{next-single-property-change} returns @var{limit}. + +The value is @code{nil} if the property remains unchanged all the way to +the end of @var{object} and @var{limit} is @code{nil}. If the value is +non-@code{nil}, it is a position greater than or equal to @var{pos}; it +equals @var{pos} only if @var{limit} equals @var{pos}. +@end defun + +@defun previous-single-property-change pos prop &optional object limit +This is like @code{next-single-property-change}, but scans back from +@var{pos} instead of forward. If the value is non-@code{nil}, it is a +position less than or equal to @var{pos}; it equals @var{pos} only if +@var{limit} equals @var{pos}. +@end defun + +@defun next-char-property-change pos &optional limit +This is like @code{next-property-change} except that it considers +overlay properties as well as text properties, and if no change is +found before the end of the buffer, it returns the maximum buffer +position rather than @code{nil} (in this sense, it resembles the +corresponding overlay function @code{next-overlay-change}, rather than +@code{next-property-change}). There is no @var{object} operand +because this function operates only on the current buffer. It returns +the next address at which either kind of property changes. +@end defun + +@defun previous-char-property-change pos &optional limit +This is like @code{next-char-property-change}, but scans back from +@var{pos} instead of forward, and returns the minimum buffer +position if no change is found. +@end defun + +@defun next-single-char-property-change pos prop &optional object limit +This is like @code{next-single-property-change} except that it +considers overlay properties as well as text properties, and if no +change is found before the end of the @var{object}, it returns the +maximum valid position in @var{object} rather than @code{nil}. Unlike +@code{next-char-property-change}, this function @emph{does} have an +@var{object} operand; if @var{object} is not a buffer, only +text-properties are considered. +@end defun + +@defun previous-single-char-property-change pos prop &optional object limit +This is like @code{next-single-char-property-change}, but scans back +from @var{pos} instead of forward, and returns the minimum valid +position in @var{object} if no change is found. +@end defun + +@defun text-property-any start end prop value &optional object +This function returns non-@code{nil} if at least one character between +@var{start} and @var{end} has a property @var{prop} whose value is +@var{value}. More precisely, it returns the position of the first such +character. Otherwise, it returns @code{nil}. + +The optional fifth argument, @var{object}, specifies the string or +buffer to scan. Positions are relative to @var{object}. The default +for @var{object} is the current buffer. +@end defun + +@defun text-property-not-all start end prop value &optional object +This function returns non-@code{nil} if at least one character between +@var{start} and @var{end} does not have a property @var{prop} with value +@var{value}. More precisely, it returns the position of the first such +character. Otherwise, it returns @code{nil}. + +The optional fifth argument, @var{object}, specifies the string or +buffer to scan. Positions are relative to @var{object}. The default +for @var{object} is the current buffer. +@end defun + +@node Special Properties +@subsection Properties with Special Meanings + + Here is a table of text property names that have special built-in +meanings. The following sections list a few additional special property +names that control filling and property inheritance. All other names +have no standard meaning, and you can use them as you like. + + Note: the properties @code{composition}, @code{display}, +@code{invisible} and @code{intangible} can also cause point to move to +an acceptable place, after each Emacs command. @xref{Adjusting +Point}. + +@table @code +@cindex property category of text character +@kindex category @r{(text property)} +@item category +If a character has a @code{category} property, we call it the +@dfn{property category} of the character. It should be a symbol. The +properties of this symbol serve as defaults for the properties of the +character. + +@item face +@cindex face codes of text +@kindex face @r{(text property)} +You can use the property @code{face} to control the font and color of +text. @xref{Faces}, for more information. + +In the simplest case, the value is a face name. It can also be a list; +then each element can be any of these possibilities; + +@itemize @bullet +@item +A face name (a symbol or string). + +@item +A property list of face attributes. This has the +form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a +face attribute name and @var{value} is a meaningful value for that +attribute. With this feature, you do not need to create a face each +time you want to specify a particular attribute for certain text. +@xref{Face Attributes}. + +@item +A cons cell with the form @code{(foreground-color . @var{color-name})} or +@code{(background-color . @var{color-name})}. These elements specify +just the foreground color or just the background color. @xref{Color +Names}, for the supported forms of @var{color-name}. + +A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to +specifying @code{(:foreground @var{color-name})}; likewise for the +background. +@end itemize + +You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically +update @code{face} properties based on the contents of the text. + +@item font-lock-face +@kindex font-lock-face @r{(text property)} +The @code{font-lock-face} property is the same in all respects as the +@code{face} property, but its state of activation is controlled by +@code{font-lock-mode}. This can be advantageous for special buffers +which are not intended to be user-editable, or for static areas of +text which are always fontified in the same way. +@xref{Precalculated Fontification}. + +Strictly speaking, @code{font-lock-face} is not a built-in text +property; rather, it is implemented in Font Lock mode using +@code{char-property-alias-alist}. @xref{Examining Properties}. + +This property is new in Emacs 22.1. + +@item mouse-face +@kindex mouse-face @r{(text property)} +The property @code{mouse-face} is used instead of @code{face} when the +mouse is on or near the character. For this purpose, ``near'' means +that all text between the character and where the mouse is have the same +@code{mouse-face} property value. + +@item fontified +@kindex fontified @r{(text property)} +This property says whether the text is ready for display. If +@code{nil}, Emacs's redisplay routine calls the functions in +@code{fontification-functions} (@pxref{Auto Faces}) to prepare this +part of the buffer before it is displayed. It is used internally by +the ``just in time'' font locking code. + +@item display +This property activates various features that change the +way text is displayed. For example, it can make text appear taller +or shorter, higher or lower, wider or narrow, or replaced with an image. +@xref{Display Property}. + +@item help-echo +@kindex help-echo @r{(text property)} +@cindex tooltip +@anchor{Text help-echo} +If text has a string as its @code{help-echo} property, then when you +move the mouse onto that text, Emacs displays that string in the echo +area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs +Manual}). + +If the value of the @code{help-echo} property is a function, that +function is called with three arguments, @var{window}, @var{object} and +@var{pos} and should return a help string or @code{nil} for +none. The first argument, @var{window} is the window in which +the help was found. The second, @var{object}, is the buffer, overlay or +string which had the @code{help-echo} property. The @var{pos} +argument is as follows: + +@itemize @bullet{} +@item +If @var{object} is a buffer, @var{pos} is the position in the buffer. +@item +If @var{object} is an overlay, that overlay has a @code{help-echo} +property, and @var{pos} is the position in the overlay's buffer. +@item +If @var{object} is a string (an overlay string or a string displayed +with the @code{display} property), @var{pos} is the position in that +string. +@end itemize + +If the value of the @code{help-echo} property is neither a function nor +a string, it is evaluated to obtain a help string. + +You can alter the way help text is displayed by setting the variable +@code{show-help-function} (@pxref{Help display}). + +This feature is used in the mode line and for other active text. + +@item keymap +@cindex keymap of character +@kindex keymap @r{(text property)} +The @code{keymap} property specifies an additional keymap for +commands. When this keymap applies, it is used for key lookup before +the minor mode keymaps and before the buffer's local map. +@xref{Active Keymaps}. If the property value is a symbol, the +symbol's function definition is used as the keymap. + +The property's value for the character before point applies if it is +non-@code{nil} and rear-sticky, and the property's value for the +character after point applies if it is non-@code{nil} and +front-sticky. (For mouse clicks, the position of the click is used +instead of the position of point.) + +@item local-map +@kindex local-map @r{(text property)} +This property works like @code{keymap} except that it specifies a +keymap to use @emph{instead of} the buffer's local map. For most +purposes (perhaps all purposes), it is better to use the @code{keymap} +property. + +@item syntax-table +The @code{syntax-table} property overrides what the syntax table says +about this particular character. @xref{Syntax Properties}. + +@item read-only +@cindex read-only character +@kindex read-only @r{(text property)} +If a character has the property @code{read-only}, then modifying that +character is not allowed. Any command that would do so gets an error, +@code{text-read-only}. If the property value is a string, that string +is used as the error message. + +Insertion next to a read-only character is an error if inserting +ordinary text there would inherit the @code{read-only} property due to +stickiness. Thus, you can control permission to insert next to +read-only text by controlling the stickiness. @xref{Sticky Properties}. + +Since changing properties counts as modifying the buffer, it is not +possible to remove a @code{read-only} property unless you know the +special trick: bind @code{inhibit-read-only} to a non-@code{nil} value +and then remove the property. @xref{Read Only Buffers}. + +@item invisible +@kindex invisible @r{(text property)} +A non-@code{nil} @code{invisible} property can make a character invisible +on the screen. @xref{Invisible Text}, for details. + +@item intangible +@kindex intangible @r{(text property)} +If a group of consecutive characters have equal and non-@code{nil} +@code{intangible} properties, then you cannot place point between them. +If you try to move point forward into the group, point actually moves to +the end of the group. If you try to move point backward into the group, +point actually moves to the start of the group. + +If consecutive characters have unequal non-@code{nil} +@code{intangible} properties, they belong to separate groups; each +group is separately treated as described above. + +When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, +the @code{intangible} property is ignored. + +@item field +@kindex field @r{(text property)} +Consecutive characters with the same @code{field} property constitute a +@dfn{field}. Some motion functions including @code{forward-word} and +@code{beginning-of-line} stop moving at a field boundary. +@xref{Fields}. + +@item cursor +@kindex cursor @r{(text property)} +Normally, the cursor is displayed at the end of any overlay and text +property strings present at the current window position. You can +place the cursor on any desired character of these strings by giving +that character a non-@code{nil} @var{cursor} text property. + +@item pointer +@kindex pointer @r{(text property)} +This specifies a specific pointer shape when the mouse pointer is over +this text or image. @xref{Pointer Shape}, for possible pointer +shapes. + +@item line-spacing +@kindex line-spacing @r{(text property)} +A newline can have a @code{line-spacing} text or overlay property that +controls the height of the display line ending with that newline. The +property value overrides the default frame line spacing and the buffer +local @code{line-spacing} variable. @xref{Line Height}. + +@item line-height +@kindex line-height @r{(text property)} +A newline can have a @code{line-height} text or overlay property that +controls the total height of the display line ending in that newline. +@xref{Line Height}. + +@item modification-hooks +@cindex change hooks for a character +@cindex hooks for changing a character +@kindex modification-hooks @r{(text property)} +If a character has the property @code{modification-hooks}, then its +value should be a list of functions; modifying that character calls all +of those functions. Each function receives two arguments: the beginning +and end of the part of the buffer being modified. Note that if a +particular modification hook function appears on several characters +being modified by a single primitive, you can't predict how many times +the function will be called. + +If these functions modify the buffer, they should bind +@code{inhibit-modification-hooks} to @code{t} around doing so, to +avoid confusing the internal mechanism that calls these hooks. + +Overlays also support the @code{modification-hooks} property, but the +details are somewhat different (@pxref{Overlay Properties}). + +@item insert-in-front-hooks +@itemx insert-behind-hooks +@kindex insert-in-front-hooks @r{(text property)} +@kindex insert-behind-hooks @r{(text property)} +The operation of inserting text in a buffer also calls the functions +listed in the @code{insert-in-front-hooks} property of the following +character and in the @code{insert-behind-hooks} property of the +preceding character. These functions receive two arguments, the +beginning and end of the inserted text. The functions are called +@emph{after} the actual insertion takes place. + +See also @ref{Change Hooks}, for other hooks that are called +when you change text in a buffer. + +@item point-entered +@itemx point-left +@cindex hooks for motion of point +@kindex point-entered @r{(text property)} +@kindex point-left @r{(text property)} +The special properties @code{point-entered} and @code{point-left} +record hook functions that report motion of point. Each time point +moves, Emacs compares these two property values: + +@itemize @bullet +@item +the @code{point-left} property of the character after the old location, +and +@item +the @code{point-entered} property of the character after the new +location. +@end itemize + +@noindent +If these two values differ, each of them is called (if not @code{nil}) +with two arguments: the old value of point, and the new one. + +The same comparison is made for the characters before the old and new +locations. The result may be to execute two @code{point-left} functions +(which may be the same function) and/or two @code{point-entered} +functions (which may be the same function). In any case, all the +@code{point-left} functions are called first, followed by all the +@code{point-entered} functions. + +It is possible with @code{char-after} to examine characters at various +buffer positions without moving point to those positions. Only an +actual change in the value of point runs these hook functions. + +@defvar inhibit-point-motion-hooks +When this variable is non-@code{nil}, @code{point-left} and +@code{point-entered} hooks are not run, and the @code{intangible} +property has no effect. Do not set this variable globally; bind it with +@code{let}. +@end defvar + +@defvar show-help-function +@anchor{Help display} If this variable is non-@code{nil}, it specifies a +function called to display help strings. These may be @code{help-echo} +properties, menu help strings (@pxref{Simple Menu Items}, +@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool +Bar}). The specified function is called with one argument, the help +string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs +Manual}) provides an example. +@end defvar + +@item composition +@kindex composition @r{(text property)} +This text property is used to display a sequence of characters as a +single glyph composed from components. But the value of the property +itself is completely internal to Emacs and should not be manipulated +directly by, for instance, @code{put-text-property}. + +@end table + +@node Format Properties +@subsection Formatted Text Properties + + These text properties affect the behavior of the fill commands. They +are used for representing formatted text. @xref{Filling}, and +@ref{Margins}. + +@table @code +@item hard +If a newline character has this property, it is a ``hard'' newline. +The fill commands do not alter hard newlines and do not move words +across them. However, this property takes effect only if the +@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft +Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. + +@item right-margin +This property specifies an extra right margin for filling this part of the +text. + +@item left-margin +This property specifies an extra left margin for filling this part of the +text. + +@item justification +This property specifies the style of justification for filling this part +of the text. +@end table + +@node Sticky Properties +@subsection Stickiness of Text Properties +@cindex sticky text properties +@cindex inheritance of text properties + + Self-inserting characters normally take on the same properties as the +preceding character. This is called @dfn{inheritance} of properties. + + In a Lisp program, you can do insertion with inheritance or without, +depending on your choice of insertion primitive. The ordinary text +insertion functions such as @code{insert} do not inherit any properties. +They insert text with precisely the properties of the string being +inserted, and no others. This is correct for programs that copy text +from one context to another---for example, into or out of the kill ring. +To insert with inheritance, use the special primitives described in this +section. Self-inserting characters inherit properties because they work +using these primitives. + + When you do insertion with inheritance, @emph{which} properties are +inherited, and from where, depends on which properties are @dfn{sticky}. +Insertion after a character inherits those of its properties that are +@dfn{rear-sticky}. Insertion before a character inherits those of its +properties that are @dfn{front-sticky}. When both sides offer different +sticky values for the same property, the previous character's value +takes precedence. + + By default, a text property is rear-sticky but not front-sticky; thus, +the default is to inherit all the properties of the preceding character, +and nothing from the following character. + + You can control the stickiness of various text properties with two +specific text properties, @code{front-sticky} and @code{rear-nonsticky}, +and with the variable @code{text-property-default-nonsticky}. You can +use the variable to specify a different default for a given property. +You can use those two text properties to make any specific properties +sticky or nonsticky in any particular part of the text. + + If a character's @code{front-sticky} property is @code{t}, then all +its properties are front-sticky. If the @code{front-sticky} property is +a list, then the sticky properties of the character are those whose +names are in the list. For example, if a character has a +@code{front-sticky} property whose value is @code{(face read-only)}, +then insertion before the character can inherit its @code{face} property +and its @code{read-only} property, but no others. + + The @code{rear-nonsticky} property works the opposite way. Most +properties are rear-sticky by default, so the @code{rear-nonsticky} +property says which properties are @emph{not} rear-sticky. If a +character's @code{rear-nonsticky} property is @code{t}, then none of its +properties are rear-sticky. If the @code{rear-nonsticky} property is a +list, properties are rear-sticky @emph{unless} their names are in the +list. + +@defvar text-property-default-nonsticky +This variable holds an alist which defines the default rear-stickiness +of various text properties. Each element has the form +@code{(@var{property} . @var{nonstickiness})}, and it defines the +stickiness of a particular text property, @var{property}. + +If @var{nonstickiness} is non-@code{nil}, this means that the property +@var{property} is rear-nonsticky by default. Since all properties are +front-nonsticky by default, this makes @var{property} nonsticky in both +directions by default. + +The text properties @code{front-sticky} and @code{rear-nonsticky}, when +used, take precedence over the default @var{nonstickiness} specified in +@code{text-property-default-nonsticky}. +@end defvar + + Here are the functions that insert text with inheritance of properties: + +@defun insert-and-inherit &rest strings +Insert the strings @var{strings}, just like the function @code{insert}, +but inherit any sticky properties from the adjoining text. +@end defun + +@defun insert-before-markers-and-inherit &rest strings +Insert the strings @var{strings}, just like the function +@code{insert-before-markers}, but inherit any sticky properties from the +adjoining text. +@end defun + + @xref{Insertion}, for the ordinary insertion functions which do not +inherit. + +@node Lazy Properties +@subsection Lazy Computation of Text Properties + + Instead of computing text properties for all the text in the buffer, +you can arrange to compute the text properties for parts of the text +when and if something depends on them. + + The primitive that extracts text from the buffer along with its +properties is @code{buffer-substring}. Before examining the properties, +this function runs the abnormal hook @code{buffer-access-fontify-functions}. + +@defvar buffer-access-fontify-functions +This variable holds a list of functions for computing text properties. +Before @code{buffer-substring} copies the text and text properties for a +portion of the buffer, it calls all the functions in this list. Each of +the functions receives two arguments that specify the range of the +buffer being accessed. (The buffer itself is always the current +buffer.) +@end defvar + + The function @code{buffer-substring-no-properties} does not call these +functions, since it ignores text properties anyway. + + In order to prevent the hook functions from being called more than +once for the same part of the buffer, you can use the variable +@code{buffer-access-fontified-property}. + +@defvar buffer-access-fontified-property +If this variable's value is non-@code{nil}, it is a symbol which is used +as a text property name. A non-@code{nil} value for that text property +means, ``the other text properties for this character have already been +computed.'' + +If all the characters in the range specified for @code{buffer-substring} +have a non-@code{nil} value for this property, @code{buffer-substring} +does not call the @code{buffer-access-fontify-functions} functions. It +assumes these characters already have the right text properties, and +just copies the properties they already have. + +The normal way to use this feature is that the +@code{buffer-access-fontify-functions} functions add this property, as +well as others, to the characters they operate on. That way, they avoid +being called over and over for the same text. +@end defvar + +@node Clickable Text +@subsection Defining Clickable Text +@cindex clickable text + + @dfn{Clickable text} is text that can be clicked, with either the +the mouse or via keyboard commands, to produce some result. Many +major modes use clickable text to implement features such as +hyper-links. The @code{button} package provides an easy way to insert +and manipulate clickable text. @xref{Buttons}. + + In this section, we will explain how to manually set up clickable +text in a buffer using text properties. This involves two things: (1) +indicating clickability when the mouse moves over the text, and (2) +making @kbd{RET} or a mouse click on that text do something. + + Indicating clickability usually involves highlighting the text, and +often involves displaying helpful information about the action, such +as which mouse button to press, or a short summary of the action. +This can be done with the @code{mouse-face} and @code{help-echo} +text properties. @xref{Special Properties}. +Here is an example of how Dired does it: + +@smallexample +(condition-case nil + (if (dired-move-to-filename) + (add-text-properties + (point) + (save-excursion + (dired-move-to-end-of-filename) + (point)) + '(mouse-face highlight + help-echo "mouse-2: visit this file in other window"))) + (error nil)) +@end smallexample + +@noindent +The first two arguments to @code{add-text-properties} specify the +beginning and end of the text. + + The usual way to make the mouse do something when you click it +on this text is to define @code{mouse-2} in the major mode's +keymap. The job of checking whether the click was on clickable text +is done by the command definition. Here is how Dired does it: + +@smallexample +(defun dired-mouse-find-file-other-window (event) + "In Dired, visit the file or directory name you click on." + (interactive "e") + (let (window pos file) + (save-excursion + (setq window (posn-window (event-end event)) + pos (posn-point (event-end event))) + (if (not (windowp window)) + (error "No file chosen")) + (set-buffer (window-buffer window)) + (goto-char pos) + (setq file (dired-get-file-for-visit))) + (if (file-directory-p file) + (or (and (cdr dired-subdir-alist) + (dired-goto-subdir file)) + (progn + (select-window window) + (dired-other-window file))) + (select-window window) + (find-file-other-window (file-name-sans-versions file t))))) +@end smallexample + +@noindent +The reason for the @code{save-excursion} construct is to avoid +changing the current buffer. In this case, +Dired uses the functions @code{posn-window} and @code{posn-point} +to determine which buffer the click happened in and where, and +in that buffer, @code{dired-get-file-for-visit} to determine which +file to visit. + + Instead of defining a mouse command for the major mode, you can define +a key binding for the clickable text itself, using the @code{keymap} +text property: + +@example +(let ((map (make-sparse-keymap))) + (define-key map [mouse-2] 'operate-this-button) + (put-text-property (point) + (save-excursion + (dired-move-to-end-of-filename) + (point)) + 'keymap map)) +@end example + +@noindent +This method makes it possible to define different commands for various +clickable pieces of text. Also, the major mode definition (or the +global definition) remains available for the rest of the text in the +buffer. + +@node Links and Mouse-1 +@subsection Links and Mouse-1 +@cindex follow links +@cindex mouse-1 + + The normal Emacs command for activating text in read-only buffers is +@key{Mouse-2}, which includes following textual links. However, most +graphical applications use @key{Mouse-1} for following links. For +compatibility, @key{Mouse-1} follows links in Emacs too, when you +click on a link quickly without moving the mouse. The user can +customize this behavior through the variable +@code{mouse-1-click-follows-link}. + + To define text as a link at the Lisp level, you should bind the +@code{mouse-2} event to a command to follow the link. Then, to indicate that +@key{Mouse-1} should also follow the link, you should specify a +@code{follow-link} condition either as a text property or as a key +binding: + +@table @asis +@item @code{follow-link} property +If the clickable text has a non-@code{nil} @code{follow-link} text or overlay +property, that specifies the condition. + +@item @code{follow-link} event +If there is a binding for the @code{follow-link} event, either on the +clickable text or in the local keymap, the binding is the condition. +@end table + + Regardless of how you set the @code{follow-link} condition, its +value is used as follows to determine whether the given position is +inside a link, and (if so) to compute an @dfn{action code} saying how +@key{Mouse-1} should handle the link. + +@table @asis +@item @code{mouse-face} +If the condition is @code{mouse-face}, a position is inside a link if +there is a non-@code{nil} @code{mouse-face} property at that position. +The action code is always @code{t}. + +For example, here is how Info mode handles @key{Mouse-1}: + +@smallexample +(define-key Info-mode-map [follow-link] 'mouse-face) +@end smallexample + +@item a function +If the condition is a valid function, @var{func}, then a position +@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates +to non-@code{nil}. The value returned by @var{func} serves as the +action code. + +For example, here is how pcvs enables @key{Mouse-1} to follow links on +file names only: + +@smallexample +(define-key map [follow-link] + (lambda (pos) + (eq (get-char-property pos 'face) 'cvs-filename-face))) +@end smallexample + +@item anything else +If the condition value is anything else, then the position is inside a +link and the condition itself is the action code. Clearly you should +only specify this kind of condition on the text that constitutes a +link. +@end table + +@noindent +The action code tells @key{Mouse-1} how to follow the link: + +@table @asis +@item a string or vector +If the action code is a string or vector, the @key{Mouse-1} event is +translated into the first element of the string or vector; i.e., the +action of the @key{Mouse-1} click is the local or global binding of +that character or symbol. Thus, if the action code is @code{"foo"}, +@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, +@key{Mouse-1} translates into @key{foo}. + +@item anything else +For any other non-@code{nil} action code, the @code{mouse-1} event is +translated into a @code{mouse-2} event at the same position. +@end table + + To define @key{Mouse-1} to activate a button defined with +@code{define-button-type}, give the button a @code{follow-link} +property with a value as specified above to determine how to follow +the link. For example, here is how Help mode handles @key{Mouse-1}: + +@smallexample +(define-button-type 'help-xref + 'follow-link t + 'action #'help-button-action) +@end smallexample + + To define @key{Mouse-1} on a widget defined with +@code{define-widget}, give the widget a @code{:follow-link} property +with a value as specified above to determine how to follow the link. + +For example, here is how the @code{link} widget specifies that +a @key{Mouse-1} click shall be translated to @key{RET}: + +@smallexample +(define-widget 'link 'item + "An embedded link." + :button-prefix 'widget-link-prefix + :button-suffix 'widget-link-suffix + :follow-link "\C-m" + :help-echo "Follow the link." + :format "%[%t%]") +@end smallexample + +@defun mouse-on-link-p pos +This function returns non-@code{nil} if position @var{pos} in the +current buffer is on a link. @var{pos} can also be a mouse event +location, as returned by @code{event-start} (@pxref{Accessing Events}). +@end defun + +@node Fields +@subsection Defining and Using Fields +@cindex fields + + A field is a range of consecutive characters in the buffer that are +identified by having the same value (comparing with @code{eq}) of the +@code{field} property (either a text-property or an overlay property). +This section describes special functions that are available for +operating on fields. + + You specify a field with a buffer position, @var{pos}. We think of +each field as containing a range of buffer positions, so the position +you specify stands for the field containing that position. + + When the characters before and after @var{pos} are part of the same +field, there is no doubt which field contains @var{pos}: the one those +characters both belong to. When @var{pos} is at a boundary between +fields, which field it belongs to depends on the stickiness of the +@code{field} properties of the two surrounding characters (@pxref{Sticky +Properties}). The field whose property would be inherited by text +inserted at @var{pos} is the field that contains @var{pos}. + + There is an anomalous case where newly inserted text at @var{pos} +would not inherit the @code{field} property from either side. This +happens if the previous character's @code{field} property is not +rear-sticky, and the following character's @code{field} property is not +front-sticky. In this case, @var{pos} belongs to neither the preceding +field nor the following field; the field functions treat it as belonging +to an empty field whose beginning and end are both at @var{pos}. + + In all of these functions, if @var{pos} is omitted or @code{nil}, the +value of point is used by default. If narrowing is in effect, then +@var{pos} should fall within the accessible portion. @xref{Narrowing}. + +@defun field-beginning &optional pos escape-from-edge limit +This function returns the beginning of the field specified by @var{pos}. + +If @var{pos} is at the beginning of its field, and +@var{escape-from-edge} is non-@code{nil}, then the return value is +always the beginning of the preceding field that @emph{ends} at @var{pos}, +regardless of the stickiness of the @code{field} properties around +@var{pos}. + +If @var{limit} is non-@code{nil}, it is a buffer position; if the +beginning of the field is before @var{limit}, then @var{limit} will be +returned instead. +@end defun + +@defun field-end &optional pos escape-from-edge limit +This function returns the end of the field specified by @var{pos}. + +If @var{pos} is at the end of its field, and @var{escape-from-edge} is +non-@code{nil}, then the return value is always the end of the following +field that @emph{begins} at @var{pos}, regardless of the stickiness of +the @code{field} properties around @var{pos}. + +If @var{limit} is non-@code{nil}, it is a buffer position; if the end +of the field is after @var{limit}, then @var{limit} will be returned +instead. +@end defun + +@defun field-string &optional pos +This function returns the contents of the field specified by @var{pos}, +as a string. +@end defun + +@defun field-string-no-properties &optional pos +This function returns the contents of the field specified by @var{pos}, +as a string, discarding text properties. +@end defun + +@defun delete-field &optional pos +This function deletes the text of the field specified by @var{pos}. +@end defun + +@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property +This function ``constrains'' @var{new-pos} to the field that +@var{old-pos} belongs to---in other words, it returns the position +closest to @var{new-pos} that is in the same field as @var{old-pos}. + +If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses +the value of point instead, and moves point to the resulting position +as well as returning it. + +If @var{old-pos} is at the boundary of two fields, then the acceptable +final positions depend on the argument @var{escape-from-edge}. If +@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in +the field whose @code{field} property equals what new characters +inserted at @var{old-pos} would inherit. (This depends on the +stickiness of the @code{field} property for the characters before and +after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, +@var{new-pos} can be anywhere in the two adjacent fields. +Additionally, if two fields are separated by another field with the +special value @code{boundary}, then any point within this special +field is also considered to be ``on the boundary.'' + +Commands like @kbd{C-a} with no argumemt, that normally move backward +to a specific kind of location and stay there once there, probably +should specify @code{nil} for @var{escape-from-edge}. Other motion +commands that check fields should probably pass @code{t}. + +If the optional argument @var{only-in-line} is non-@code{nil}, and +constraining @var{new-pos} in the usual way would move it to a different +line, @var{new-pos} is returned unconstrained. This used in commands +that move by line, such as @code{next-line} and +@code{beginning-of-line}, so that they respect field boundaries only in +the case where they can still move to the right line. + +If the optional argument @var{inhibit-capture-property} is +non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that +name, then any field boundaries are ignored. + +You can cause @code{constrain-to-field} to ignore all field boundaries +(and so never constrain anything) by binding the variable +@code{inhibit-field-text-motion} to a non-@code{nil} value. +@end defun + +@node Not Intervals +@subsection Why Text Properties are not Intervals +@cindex intervals + + Some editors that support adding attributes to text in the buffer do +so by letting the user specify ``intervals'' within the text, and adding +the properties to the intervals. Those editors permit the user or the +programmer to determine where individual intervals start and end. We +deliberately provided a different sort of interface in Emacs Lisp to +avoid certain paradoxical behavior associated with text modification. + + If the actual subdivision into intervals is meaningful, that means you +can distinguish between a buffer that is just one interval with a +certain property, and a buffer containing the same text subdivided into +two intervals, both of which have that property. + + Suppose you take the buffer with just one interval and kill part of +the text. The text remaining in the buffer is one interval, and the +copy in the kill ring (and the undo list) becomes a separate interval. +Then if you yank back the killed text, you get two intervals with the +same properties. Thus, editing does not preserve the distinction +between one interval and two. + + Suppose we ``fix'' this problem by coalescing the two intervals when +the text is inserted. That works fine if the buffer originally was a +single interval. But suppose instead that we have two adjacent +intervals with the same properties, and we kill the text of one interval +and yank it back. The same interval-coalescence feature that rescues +the other case causes trouble in this one: after yanking, we have just +one interval. One again, editing does not preserve the distinction +between one interval and two. + + Insertion of text at the border between intervals also raises +questions that have no satisfactory answer. + + However, it is easy to arrange for editing to behave consistently for +questions of the form, ``What are the properties of this character?'' +So we have decided these are the only questions that make sense; we have +not implemented asking questions about where intervals start or end. + + In practice, you can usually use the text property search functions in +place of explicit interval boundaries. You can think of them as finding +the boundaries of intervals, assuming that intervals are always +coalesced whenever possible. @xref{Property Search}. + + Emacs also provides explicit intervals as a presentation feature; see +@ref{Overlays}. + +@node Substitution +@section Substituting for a Character Code + + The following functions replace characters within a specified region +based on their character codes. + +@defun subst-char-in-region start end old-char new-char &optional noundo +@cindex replace characters +This function replaces all occurrences of the character @var{old-char} +with the character @var{new-char} in the region of the current buffer +defined by @var{start} and @var{end}. + +@cindex undo avoidance +If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does +not record the change for undo and does not mark the buffer as modified. +This was useful for controlling the old selective display feature +(@pxref{Selective Display}). + +@code{subst-char-in-region} does not move point and returns +@code{nil}. + +@example +@group +---------- Buffer: foo ---------- +This is the contents of the buffer before. +---------- Buffer: foo ---------- +@end group + +@group +(subst-char-in-region 1 20 ?i ?X) + @result{} nil + +---------- Buffer: foo ---------- +ThXs Xs the contents of the buffer before. +---------- Buffer: foo ---------- +@end group +@end example +@end defun + +@defun translate-region start end table +This function applies a translation table to the characters in the +buffer between positions @var{start} and @var{end}. + +The translation table @var{table} is a string or a char-table; +@code{(aref @var{table} @var{ochar})} gives the translated character +corresponding to @var{ochar}. If @var{table} is a string, any +characters with codes larger than the length of @var{table} are not +altered by the translation. + +The return value of @code{translate-region} is the number of +characters that were actually changed by the translation. This does +not count characters that were mapped into themselves in the +translation table. +@end defun + +@node Registers +@section Registers +@cindex registers + + A register is a sort of variable used in Emacs editing that can hold a +variety of different kinds of values. Each register is named by a +single character. All @acronym{ASCII} characters and their meta variants +(but with the exception of @kbd{C-g}) can be used to name registers. +Thus, there are 255 possible registers. A register is designated in +Emacs Lisp by the character that is its name. + +@defvar register-alist +This variable is an alist of elements of the form @code{(@var{name} . +@var{contents})}. Normally, there is one element for each Emacs +register that has been used. + +The object @var{name} is a character (an integer) identifying the +register. +@end defvar + + The @var{contents} of a register can have several possible types: + +@table @asis +@item a number +A number stands for itself. If @code{insert-register} finds a number +in the register, it converts the number to decimal. + +@item a marker +A marker represents a buffer position to jump to. + +@item a string +A string is text saved in the register. + +@item a rectangle +A rectangle is represented by a list of strings. + +@item @code{(@var{window-configuration} @var{position})} +This represents a window configuration to restore in one frame, and a +position to jump to in the current buffer. + +@item @code{(@var{frame-configuration} @var{position})} +This represents a frame configuration to restore, and a position +to jump to in the current buffer. + +@item (file @var{filename}) +This represents a file to visit; jumping to this value visits file +@var{filename}. + +@item (file-query @var{filename} @var{position}) +This represents a file to visit and a position in it; jumping to this +value visits file @var{filename} and goes to buffer position +@var{position}. Restoring this type of position asks the user for +confirmation first. +@end table + + The functions in this section return unpredictable values unless +otherwise stated. + +@defun get-register reg +This function returns the contents of the register +@var{reg}, or @code{nil} if it has no contents. +@end defun + +@defun set-register reg value +This function sets the contents of register @var{reg} to @var{value}. +A register can be set to any value, but the other register functions +expect only certain data types. The return value is @var{value}. +@end defun + +@deffn Command view-register reg +This command displays what is contained in register @var{reg}. +@end deffn + +@ignore +@deffn Command point-to-register reg +This command stores both the current location of point and the current +buffer in register @var{reg} as a marker. +@end deffn + +@deffn Command jump-to-register reg +@deffnx Command register-to-point reg +@comment !!SourceFile register.el +This command restores the status recorded in register @var{reg}. + +If @var{reg} contains a marker, it moves point to the position stored in +the marker. Since both the buffer and the location within the buffer +are stored by the @code{point-to-register} function, this command can +switch you to another buffer. + +If @var{reg} contains a window configuration or a frame configuration. +@code{jump-to-register} restores that configuration. +@end deffn +@end ignore + +@deffn Command insert-register reg &optional beforep +This command inserts contents of register @var{reg} into the current +buffer. + +Normally, this command puts point before the inserted text, and the +mark after it. However, if the optional second argument @var{beforep} +is non-@code{nil}, it puts the mark before and point after. +You can pass a non-@code{nil} second argument @var{beforep} to this +function interactively by supplying any prefix argument. + +If the register contains a rectangle, then the rectangle is inserted +with its upper left corner at point. This means that text is inserted +in the current line and underneath it on successive lines. + +If the register contains something other than saved text (a string) or +a rectangle (a list), currently useless things happen. This may be +changed in the future. +@end deffn + +@ignore +@deffn Command copy-to-register reg start end &optional delete-flag +This command copies the region from @var{start} to @var{end} into +register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes +the region from the buffer after copying it into the register. +@end deffn + +@deffn Command prepend-to-register reg start end &optional delete-flag +This command prepends the region from @var{start} to @var{end} into +register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes +the region from the buffer after copying it to the register. +@end deffn + +@deffn Command append-to-register reg start end &optional delete-flag +This command appends the region from @var{start} to @var{end} to the +text already in register @var{reg}. If @var{delete-flag} is +non-@code{nil}, it deletes the region from the buffer after copying it +to the register. +@end deffn + +@deffn Command copy-rectangle-to-register reg start end &optional delete-flag +This command copies a rectangular region from @var{start} to @var{end} +into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it +deletes the region from the buffer after copying it to the register. +@end deffn + +@deffn Command window-configuration-to-register reg +This function stores the window configuration of the selected frame in +register @var{reg}. +@end deffn + +@deffn Command frame-configuration-to-register reg +This function stores the current frame configuration in register +@var{reg}. +@end deffn +@end ignore + +@node Transposition +@section Transposition of Text + + This subroutine is used by the transposition commands. + +@defun transpose-regions start1 end1 start2 end2 &optional leave-markers +This function exchanges two nonoverlapping portions of the buffer. +Arguments @var{start1} and @var{end1} specify the bounds of one portion +and arguments @var{start2} and @var{end2} specify the bounds of the +other portion. + +Normally, @code{transpose-regions} relocates markers with the transposed +text; a marker previously positioned within one of the two transposed +portions moves along with that portion, thus remaining between the same +two characters in their new position. However, if @var{leave-markers} +is non-@code{nil}, @code{transpose-regions} does not do this---it leaves +all markers unrelocated. +@end defun + +@node Base 64 +@section Base 64 Encoding +@cindex base 64 encoding + + Base 64 code is used in email to encode a sequence of 8-bit bytes as +a longer sequence of @acronym{ASCII} graphic characters. It is defined in +Internet RFC@footnote{ +An RFC, an acronym for @dfn{Request for Comments}, is a numbered +Internet informational document describing a standard. RFCs are +usually written by technical experts acting on their own initiative, +and are traditionally written in a pragmatic, experience-driven +manner. +}2045. This section describes the functions for +converting to and from this code. + +@defun base64-encode-region beg end &optional no-line-break +This function converts the region from @var{beg} to @var{end} into base +64 code. It returns the length of the encoded text. An error is +signaled if a character in the region is multibyte, i.e.@: in a +multibyte buffer the region must contain only characters from the +charsets @code{ascii}, @code{eight-bit-control} and +@code{eight-bit-graphic}. + +Normally, this function inserts newline characters into the encoded +text, to avoid overlong lines. However, if the optional argument +@var{no-line-break} is non-@code{nil}, these newlines are not added, so +the output is just one long line. +@end defun + +@defun base64-encode-string string &optional no-line-break +This function converts the string @var{string} into base 64 code. It +returns a string containing the encoded text. As for +@code{base64-encode-region}, an error is signaled if a character in the +string is multibyte. + +Normally, this function inserts newline characters into the encoded +text, to avoid overlong lines. However, if the optional argument +@var{no-line-break} is non-@code{nil}, these newlines are not added, so +the result string is just one long line. +@end defun + +@defun base64-decode-region beg end +This function converts the region from @var{beg} to @var{end} from base +64 code into the corresponding decoded text. It returns the length of +the decoded text. + +The decoding functions ignore newline characters in the encoded text. +@end defun + +@defun base64-decode-string string +This function converts the string @var{string} from base 64 code into +the corresponding decoded text. It returns a unibyte string containing the +decoded text. + +The decoding functions ignore newline characters in the encoded text. +@end defun + +@node MD5 Checksum +@section MD5 Checksum +@cindex MD5 checksum +@cindex message digest computation + + MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit +``fingerprints'' of a document or program. They are used to verify +that you have an exact and unaltered copy of the data. The algorithm +to calculate the MD5 message digest is defined in Internet +RFC@footnote{ +For an explanation of what is an RFC, see the footnote in @ref{Base +64}. +}1321. This section describes the Emacs facilities for computing +message digests. + +@defun md5 object &optional start end coding-system noerror +This function returns the MD5 message digest of @var{object}, which +should be a buffer or a string. + +The two optional arguments @var{start} and @var{end} are character +positions specifying the portion of @var{object} to compute the +message digest for. If they are @code{nil} or omitted, the digest is +computed for the whole of @var{object}. + +The function @code{md5} does not compute the message digest directly +from the internal Emacs representation of the text (@pxref{Text +Representations}). Instead, it encodes the text using a coding +system, and computes the message digest from the encoded text. The +optional fourth argument @var{coding-system} specifies which coding +system to use for encoding the text. It should be the same coding +system that you used to read the text, or that you used or will use +when saving or sending the text. @xref{Coding Systems}, for more +information about coding systems. + +If @var{coding-system} is @code{nil} or omitted, the default depends +on @var{object}. If @var{object} is a buffer, the default for +@var{coding-system} is whatever coding system would be chosen by +default for writing this text into a file. If @var{object} is a +string, the user's most preferred coding system (@pxref{Recognize +Coding, prefer-coding-system, the description of +@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used. + +Normally, @code{md5} signals an error if the text can't be encoded +using the specified or chosen coding system. However, if +@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} +coding instead. +@end defun + +@node Atomic Changes +@section Atomic Change Groups +@cindex atomic changes + + In data base terminology, an @dfn{atomic} change is an indivisible +change---it can succeed entirely or it can fail entirely, but it +cannot partly succeed. A Lisp program can make a series of changes to +one or several buffers as an @dfn{atomic change group}, meaning that +either the entire series of changes will be installed in their buffers +or, in case of an error, none of them will be. + + To do this for one buffer, the one already current, simply write a +call to @code{atomic-change-group} around the code that makes the +changes, like this: + +@example +(atomic-change-group + (insert foo) + (delete-region x y)) +@end example + +@noindent +If an error (or other nonlocal exit) occurs inside the body of +@code{atomic-change-group}, it unmakes all the changes in that buffer +that were during the execution of the body. This kind of change group +has no effect on any other buffers---any such changes remain. + + If you need something more sophisticated, such as to make changes in +various buffers constitute one atomic group, you must directly call +lower-level functions that @code{atomic-change-group} uses. + +@defun prepare-change-group &optional buffer +This function sets up a change group for buffer @var{buffer}, which +defaults to the current buffer. It returns a ``handle'' that +represents the change group. You must use this handle to activate the +change group and subsequently to finish it. +@end defun + + To use the change group, you must @dfn{activate} it. You must do +this before making any changes in the text of @var{buffer}. + +@defun activate-change-group handle +This function activates the change group that @var{handle} designates. +@end defun + + After you activate the change group, any changes you make in that +buffer become part of it. Once you have made all the desired changes +in the buffer, you must @dfn{finish} the change group. There are two +ways to do this: you can either accept (and finalize) all the changes, +or cancel them all. + +@defun accept-change-group handle +This function accepts all the changes in the change group specified by +@var{handle}, making them final. +@end defun + +@defun cancel-change-group handle +This function cancels and undoes all the changes in the change group +specified by @var{handle}. +@end defun + + Your code should use @code{unwind-protect} to make sure the group is +always finished. The call to @code{activate-change-group} should be +inside the @code{unwind-protect}, in case the user types @kbd{C-g} +just after it runs. (This is one reason why +@code{prepare-change-group} and @code{activate-change-group} are +separate functions, because normally you would call +@code{prepare-change-group} before the start of that +@code{unwind-protect}.) Once you finish the group, don't use the +handle again---in particular, don't try to finish the same group +twice. + + To make a multibuffer change group, call @code{prepare-change-group} +once for each buffer you want to cover, then use @code{nconc} to +combine the returned values, like this: + +@example +(nconc (prepare-change-group buffer-1) + (prepare-change-group buffer-2)) +@end example + +You can then activate the multibuffer change group with a single call +to @code{activate-change-group}, and finish it with a single call to +@code{accept-change-group} or @code{cancel-change-group}. + + Nested use of several change groups for the same buffer works as you +would expect. Non-nested use of change groups for the same buffer +will get Emacs confused, so don't let it happen; the first change +group you start for any given buffer should be the last one finished. + +@node Change Hooks +@section Change Hooks +@cindex change hooks +@cindex hooks for text changes + + These hook variables let you arrange to take notice of all changes in +all buffers (or in a particular buffer, if you make them buffer-local). +See also @ref{Special Properties}, for how to detect changes to specific +parts of the text. + + The functions you use in these hooks should save and restore the match +data if they do anything that uses regular expressions; otherwise, they +will interfere in bizarre ways with the editing operations that call +them. + +@defvar before-change-functions +This variable holds a list of functions to call before any buffer +modification. Each function gets two arguments, the beginning and end +of the region that is about to change, represented as integers. The +buffer that is about to change is always the current buffer. +@end defvar + +@defvar after-change-functions +This variable holds a list of functions to call after any buffer +modification. Each function receives three arguments: the beginning and +end of the region just changed, and the length of the text that existed +before the change. All three arguments are integers. The buffer that's +about to change is always the current buffer. + +The length of the old text is the difference between the buffer positions +before and after that text as it was before the change. As for the +changed text, its length is simply the difference between the first two +arguments. +@end defvar + + Output of messages into the @samp{*Messages*} buffer does not +call these functions. + +@defmac combine-after-change-calls body@dots{} +The macro executes @var{body} normally, but arranges to call the +after-change functions just once for a series of several changes---if +that seems safe. + +If a program makes several text changes in the same area of the buffer, +using the macro @code{combine-after-change-calls} around that part of +the program can make it run considerably faster when after-change hooks +are in use. When the after-change hooks are ultimately called, the +arguments specify a portion of the buffer including all of the changes +made within the @code{combine-after-change-calls} body. + +@strong{Warning:} You must not alter the values of +@code{after-change-functions} within +the body of a @code{combine-after-change-calls} form. + +@strong{Warning:} if the changes you combine occur in widely scattered +parts of the buffer, this will still work, but it is not advisable, +because it may lead to inefficient behavior for some change hook +functions. +@end defmac + +@defvar first-change-hook +This variable is a normal hook that is run whenever a buffer is changed +that was previously in the unmodified state. +@end defvar + +@defvar inhibit-modification-hooks +If this variable is non-@code{nil}, all of the change hooks are +disabled; none of them run. This affects all the hook variables +described above in this section, as well as the hooks attached to +certain special text properties (@pxref{Special Properties}) and overlay +properties (@pxref{Overlay Properties}). + +Also, this variable is bound to non-@code{nil} while running those +same hook variables, so that by default modifying the buffer from +a modification hook does not cause other modification hooks to be run. +If you do want modification hooks to be run in a particular piece of +code that is itself run from a modification hook, then rebind locally +@code{inhibit-modification-hooks} to @code{nil}. +@end defvar + +@ignore + arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b +@end ignore diff --cc lisp/ChangeLog index 10164e2e8d5,33ed2702a04..3a68b694a34 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@@ -40,6 -3,13 +40,40 @@@ * progmodes/etags.el (select-tags-table): Disable undo in the `*Tags Table List*' buffer. + 2007-10-13 Eli Zaretskii + + * dired.el (dired-warn-writable): New face. + (dired-warn-writable-face): New variable. + (dired-font-lock-keywords): Use dired-warn-writable-face, instead + of dired-warning-face, for group- and world-writable files. + ++2007-10-13 Richard Stallman ++ ++ * files.el (directory-abbrev-alist): Doc fix. ++ ++2007-10-13 Jari Aalto ++ ++ * comint.el (comint-password-prompt-regexp): Add 'LDAP'. ++ ++2007-10-12 Martin Rudalics ++ ++ * frame.el (set-frame-configuration): Assign name parameter only ++ if it has been set explicitly before. ++ ++2007-10-11 Tom Tromey ++ ++ * progmodes/gdb-ui.el (gdb-info-stack-custom): Ensure current ++ frame is visible. ++ ++2007-10-10 Richard Stallman ++ ++ * emacs-lisp/debug.el (debugger-setup-buffer): Disable undo ++ in *Backtrace*. ++ ++ * faces.el (face-font-selection-order): Doc fix. ++ ++ * loadhist.el (unload-feature): Doc fix. ++ 2007-10-13 Glenn Morris * progmodes/octave-mod.el (octave-looking-at-kw): Add doc string. diff --cc lisp/frame.el index 30573db9e66,cbdfa45d4f7..1c11829475b --- a/lisp/frame.el +++ b/lisp/frame.el @@@ -941,28 -797,36 +941,35 @@@ is given and non-nil, the unwanted fram (list 'frame-configuration-p configuration))) (let ((config-alist (cdr configuration)) frames-to-delete) - (mapcar (function - (lambda (frame) - (let ((parameters (assq frame config-alist))) - (if parameters - (progn - (modify-frame-parameters - frame - ;; Since we can't set a frame's minibuffer status, - ;; we might as well omit the parameter altogether. - (let* ((parms (nth 1 parameters)) - (mini (assq 'minibuffer parms)) - (name (assq 'name parms)) - (explicit-name (cdr (assq 'explicit-name parms)))) - (when mini (setq parms (delq mini parms))) - ;; Leave name in iff it was set explicitly. - ;; This should fix the behavior reported in - ;; http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg01632.html - (when (and name (not explicit-name)) - (setq parms (delq name parms))) - parms)) - (set-window-configuration (nth 2 parameters))) - (setq frames-to-delete (cons frame frames-to-delete)))))) - (frame-list)) - (if nodelete - ;; Note: making frames invisible here was tried - ;; but led to some strange behavior--each time the frame - ;; was made visible again, the window manager asked afresh - ;; for where to put it. - (mapcar 'iconify-frame frames-to-delete) - (mapcar 'delete-frame frames-to-delete)))) + (dolist (frame (frame-list)) + (let ((parameters (assq frame config-alist))) + (if parameters + (progn + (modify-frame-parameters + frame + ;; Since we can't set a frame's minibuffer status, + ;; we might as well omit the parameter altogether. + (let* ((parms (nth 1 parameters)) - (mini (assq 'minibuffer parms))) - (if mini (setq parms (delq mini parms))) ++ (mini (assq 'minibuffer parms)) ++ (name (assq 'name parms)) ++ (explicit-name (cdr (assq 'explicit-name parms)))) ++ (when mini (setq parms (delq mini parms))) ++ ;; Leave name in iff it was set explicitly. ++ ;; This should fix the behavior reported in ++ ;; http://lists.gnu.org/archive/html/emacs-devel/2007-08/msg01632.html ++ (when (and name (not explicit-name)) ++ (setq parms (delq name parms))) + parms)) + (set-window-configuration (nth 2 parameters))) + (setq frames-to-delete (cons frame frames-to-delete))))) + (mapc (if nodelete + ;; Note: making frames invisible here was tried + ;; but led to some strange behavior--each time the frame + ;; was made visible again, the window manager asked afresh + ;; for where to put it. + 'iconify-frame + 'delete-frame) + frames-to-delete))) ;;;; Convenience functions for accessing and interactively changing ;;;; frame parameters. diff --cc lisp/url/ChangeLog index 0e4362bce31,146d224435b..8f3979debcf --- a/lisp/url/ChangeLog +++ b/lisp/url/ChangeLog @@@ -3,11 -14,14 +14,19 @@@ * url-auth.el (url-basic-auth): Set path to "/" when URL has an empty string filename. + 2007-10-09 Richard Stallman + + * url-parse.el (url-type, url-user, url-password, url-host) + (url-port, url-filename, url-target, url-attributes) + (url-fullness, url-set-type, url-set-user, url-set-password) + (url-set-host, url-set-port, url-set-filename, url-set-target) + (url-set-attributes, url-set-full): Change macros to defuns. + +2007-09-26 Juanma Barranquero + + * url-dav.el (top): + * url-vars.el (top): Use `mapc' rather than `mapcar'. + 2007-09-22 Diane Murray * url-misc.el (url-generic-emulator-loader): Send the port as a diff --cc lisp/url/url-expand.el index df4de29a619,b7efd75b4b6..bebdbd9e04b --- a/lisp/url/url-expand.el +++ b/lisp/url/url-expand.el @@@ -135,9 -135,9 +135,10 @@@ path components followed by `..' are re sepchar (substring (url-filename urlobj) (match-beginning 0) (match-end 0))) (setq file (url-filename urlobj))) (setq file (url-expander-remove-relative-links - (concat (url-basepath (url-filename defobj)) file))) + (expand-file-name file + (url-file-directory (url-filename defobj))))) - (url-set-filename urlobj (if query (concat file sepchar query) file)))))) + (setf (url-filename urlobj) + (if query (concat file sepchar query) file)))))) (provide 'url-expand)