+++ /dev/null
-# Generated files
-precious ^(config\.status|config\.cache)$
-
-# arch-tag: dde817a2-94ff-4c6e-838c-bb5b33e7f0df
+++ /dev/null
-texput.log
-elisp.??
-elisp.???
-configure
-config.log
-config.cache
-config.status
-Makefile
-makefile
-index.texi
-elisp
-elisp-?
-elisp-??
-vol1.*
-vol2.*
-elisp1*
-elisp2*
+++ /dev/null
-2007-08-29 Glenn Morris <rgm@gnu.org>
-
- * elisp.texi (EMACSVER): Increase to 23.0.50.
-
-2007-08-29 Dan Nicolaescu <dann@ics.uci.edu>
-
- * frames.texi (Basic Parameters): Add display-environment-variable
- and term-environment-variable.
-
-2007-08-28 Juri Linkov <juri@jurta.org>
-
- * display.texi (Image Formats, Other Image Types): Add SVG.
-
-2007-08-28 Juri Linkov <juri@jurta.org>
-
- * display.texi (Images): Move formats-related text to new node
- "Image Formats".
- (Image Formats): New node.
-
-2007-08-25 Richard Stallman <rms@gnu.org>
-
- * display.texi (Images): Delete redundant @findex.
-
-2007-08-16 Richard Stallman <rms@gnu.org>
-
- * processes.texi (Asynchronous Processes): Clarify
- doc of start-file-process.
-
-2007-08-08 Martin Rudalics <rudalics@gmx.at>
-
- * modes.texi (Example Major Modes): Fix typo.
-
-2007-08-08 Glenn Morris <rgm@gnu.org>
-
- * intro.texi (nil and t): Do not use `iff' in documentation.
-
- * tips.texi (Documentation Tips): Recommend against `iff'.
-
-2007-08-07 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Image Cache): Document image-refresh.
-
-2007-08-06 Martin Rudalics <rudalics@gmx.at>
-
- * windows.texi (Size of Window): Document window-full-width-p.
-
-2007-07-25 Glenn Morris <rgm@gnu.org>
-
- * gpl.texi (GPL): Replace license with GPLv3.
-
- * Relicense all FSF files to GPLv3 or later.
-
-2007-07-24 Michael Albinus <michael.albinus@gmx.de>
-
- * 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 <michael.albinus@gmx.de>
-
- * files.texi (Magic File Names): Introduce optional parameter
- IDENTIFICATION for `file-remote-p'.
-
-2007-07-16 Richard Stallman <rms@gnu.org>
-
- * display.texi (Defining Faces): Fix previous change.
-
-2007-07-14 Richard Stallman <rms@gnu.org>
-
- * control.texi (Handling Errors): Document `debug' in handler list.
-
-2007-07-10 Richard Stallman <rms@gnu.org>
-
- * display.texi (Defining Faces): Explain C-M-x feature for defface.
-
-2007-07-09 Richard Stallman <rms@gnu.org>
-
- * files.texi (Magic File Names): Rewrite previous change.
-
-2007-07-08 Michael Albinus <michael.albinus@gmx.de>
-
- * files.texi (Magic File Names): Introduce optional parameter
- CONNECTED for `file-remote-p'.
-
-2007-07-07 Michael Albinus <michael.albinus@gmx.de>
-
- * processes.texi (Asynchronous Processes):
- * files.texi (Magic File Names): Add `start-file-process'.
-
-2007-06-27 Richard Stallman <rms@gnu.org>
-
- * files.texi (Format Conversion Piecemeal): Clarify
- `after-insert-file-functions' calling convention.
-
-2007-06-27 Michael Albinus <michael.albinus@gmx.de>
-
- * files.texi (Magic File Names): Remove `dired-call-process'. Add
- `process-file'.
-
-2007-06-27 Kenichi Handa <handa@m17n.org>
-
- * text.texi (Special Properties): Fix description about
- `compostion' property.
-
-2007-06-26 Kenichi Handa <handa@m17n.org>
-
- * nonascii.texi (Default Coding Systems): Document about the
- return value `undecided'.
-
-2007-06-25 David Kastrup <dak@gnu.org>
-
- * keymaps.texi (Active Keymaps): Document new POSITION argument of
- `current-active-maps'.
-
-2007-06-24 Karl Berry <karl@gnu.org>
-
- * elisp.texi, vol1.texi, vol2.texi: new Back-Cover Text.
-
-2007-06-15 Juanma Barranquero <lekktu@gmail.com>
-
- * display.texi (Overlay Arrow): Doc fix.
-
-2007-06-14 Karl Berry <karl@tug.org>
-
- * anti.texi (Antinews): Typo.
-
-2007-06-14 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Image Cache): Document image-refresh.
-
-2007-06-12 Karl Berry <karl@gnu.org>
-
- * 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 <tromey@redhat.com>
-
- * os.texi (Init File): Document user-emacs-directory.
-
-2007-06-03 Nick Roberts <nickrob@snap.net.nz>
-
- * commands.texi (Click Events): Describe width and height when
- object is nil.
-
-2007-05-30 Nick Roberts <nickrob@snap.net.nz>
-
- * 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 <rms@gnu.org>
-
- * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces.
-
-2007-06-02 Chong Yidong <cyd@stupidchicken.com>
-
- * Version 22.1 released.
-
-2007-06-01 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * text.texi (Special Properties): Correct meaning of fontified face.
-
-2007-05-30 Richard Stallman <rms@gnu.org>
-
- * text.texi (Special Properties): Add link to Adjusting Point.
-
-2007-05-12 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <ttn@gnuvola.org>
-
- * 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 <karl@gnu.org>
-
- * elisp.texi (EMACSVER): Back to 22.
-
-2007-05-06 Richard Stallman <rms@gnu.org>
-
- * processes.texi (Accepting Output): Revert most of previous change.
-
-2007-05-05 Richard Stallman <rms@gnu.org>
-
- * processes.texi (Accepting Output): accept-process-output
- uses microseconds, not milliseconds. But that arg is obsolete.
-
-2007-05-04 Karl Berry <karl@tug.org>
-
- * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22.
-
-2007-05-04 Eli Zaretskii <eliz@gnu.org>
-
- * tips.texi (Documentation Tips): Rearrange items to place the
- more important ones first. Add an index entry for hyperlinks.
-
-2007-05-03 Karl Berry <karl@gnu.org>
-
- * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing.
- (EMACSVER) [smallbook]: 22 for printed version.
-
- * control.texi (Signaling Errors) <signal>: texinfo.tex is fixed,
- so restore anchor to normal position after defun. Found by Kevin Ryde.
-
-2007-04-26 Glenn Morris <rgm@gnu.org>
-
- * elisp.texi (EMACSVER): Increase to 22.1.50.
-
-2007-04-28 Karl Berry <karl@gnu.org>
-
- * elisp.texi: Improve line breaks on copyright page,
- similar layout to emacs manual, 8.5x11 by default.
-
-2007-04-24 Richard Stallman <rms@gnu.org>
-
- * text.texi (Special Properties): Add xref to Overlay Properties.
-
- * display.texi (Overlay Properties): Add xref to Special Properties.
-
-2007-04-22 Richard Stallman <rms@gnu.org>
-
- * keymaps.texi (Extended Menu Items): Move the info about
- format with cached keyboard binding.
-
-2007-04-21 Richard Stallman <rms@gnu.org>
-
- * 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 <handa@m17n.org>
-
- * text.texi (Special Properties): Document composition property.
-
-2007-04-19 Glenn Morris <rgm@gnu.org>
-
- * files.texi (File Name Expansion): Mention "superroot".
-
-2007-04-15 Chong Yidong <cyd@stupidchicken.com>
-
- * 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 <rms@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * keymaps.texi (Format of Keymaps): Remove spurious ")" from
- value of lisp-mode-map.
-
-2007-04-11 Karl Berry <karl@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * text.texi (Lazy Properties): Minor fix.
-
-2007-04-08 Karl Berry <karl@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * text.texi (Adaptive Fill): Just describe default,
- don't show it (since it contains non-ASCII chars).
-
-2007-04-07 Karl Berry <karl@gnu.org>
-
- * 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 <herberteuler@hotmail.com>
-
- * display.texi (Defining Faces): Fix example.
-
-2007-04-07 Karl Berry <karl@gnu.org>
-
- * display.texi (Button Buffer Commands): Improve page break.
-
-2007-04-07 Richard Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * strings.texi (Case Tables): Document with-case-table and
- ascii-case-table.
-
-2007-04-03 Karl Berry <karl@gnu.org>
-
- * processes.texi (Network): Reword to improve page break.
-
-2007-04-03 Eli Zaretskii <eliz@gnu.org>
-
- * functions.texi (Inline Functions): Describe more disadvantages
- of defsubst, and make advice against it stronger.
-
-2007-04-02 Karl Berry <karl@gnu.org>
-
- * backups.texi (Backup Names): Avoid widow words.
- * modes.texi (Example Major Modes): Align last comment.
-
-2007-04-01 Chong Yidong <cyd@stupidchicken.com>
-
- * keymaps.texi (Remapping Commands): Document new arg to
- command-remapping.
-
-2007-04-01 Karl Berry <karl@gnu.org>
-
- * 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 <rgm@gnu.org>
-
- * os.texi (Timers): Fix description of run-at-time TIME formats.
-
-2007-03-31 Richard Stallman <rms@gnu.org>
-
- * display.texi (Invisible Text): Correct buffer-invisibility-spec
- regarding ellipsis.
-
-2007-03-31 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <karl@gnu.org>
-
- * macros.texi (Defining Macros): Avoid widow syllable.
-
-2007-03-31 Eli Zaretskii <eliz@gnu.org>
-
- * elisp.texi (Top): Postscript -> PostScript.
-
- * display.texi (Images, Postscript Images): Postscript -> PostScript.
-
-2007-03-31 Markus Triska <markus.triska@gmx.at>
-
- * internals.texi (Writing Emacs Primitives): Untabify `For'.
-
-2007-03-30 Karl Berry <karl@gnu.org>
-
- * lists.texi (List-related Predicates): Remove spurious @need.
- (Setcdr): Use @smallexample to improve page break.
- (Association Lists) <assoc>: 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 <eliz@gnu.org>
-
- * errors.texi (Standard Errors): Add an index entry.
-
-2007-03-19 Richard Stallman <rms@gnu.org>
-
- * os.texi (Recording Input): recent-keys now gives 300 keys.
-
-2007-03-12 Glenn Morris <rgm@gnu.org>
-
- * os.texi: Replace "daylight savings" with "daylight saving"
- throughout.
-
-2007-03-05 Richard Stallman <rms@gnu.org>
-
- * variables.texi (File Local Variables): Update
- enable-local-variables values.
-
-2007-03-04 Richard Stallman <rms@gnu.org>
-
- * 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 <viniciusjl@ig.com.br>
-
- * loading.texi (How Programs Do Loading): Fix anchor position at
- load-read-function definition doc. (tiny change)
-
-2007-02-21 Kim F. Storm <storm@cua.dk>
-
- * strings.texi (Text Comparison): Mention that assoc-string
- converts symbols to strings before testing.
-
-2007-02-17 Kim F. Storm <storm@cua.dk>
-
- * 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 <schwab@suse.de>
-
- * strings.texi (Formatting Strings): Document '+' flag.
-
-2007-02-15 Juanma Barranquero <lekktu@gmail.com>
-
- * strings.texi (Modifying Strings): Clarify that `clear-string'
- always converts the string to unibyte.
-
-2007-02-14 Kim F. Storm <storm@cua.dk>
-
- * 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 <acm@muc.de>
-
- * 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 <cyd@stupidchicken.com>
-
- * 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 <eliz@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * elisp.texi (Top): Update the top-level menus.
-
- * syntax.texi (Categories): Add index entries.
-
-2007-02-01 Juanma Barranquero <lekktu@gmail.com>
-
- * display.texi (Attribute Functions): Fix name and description of
- the UNDERLINE arg of `set-face-underline-p'.
-
-2007-01-29 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rudalics@gmx.at>
-
- * backups.texi (Reverting): Use "buffer" instead of "file"
- when talking about major and minor modes.
-
-2007-01-21 Richard Stallman <rms@gnu.org>
-
- * help.texi (Documentation): Add xref to Documentation Tips.
-
-2007-01-14 Juanma Barranquero <lekktu@gmail.com>
-
- * tips.texi (Coding Conventions): Fix typos.
-
-2007-01-05 Richard Stallman <rms@gnu.org>
-
- * modes.texi (Defining Minor Modes): Fix previous change.
-
-2007-01-03 Richard Stallman <rms@gnu.org>
-
- * customize.texi (Variable Definitions, Customization Types):
- Don't use * in doc string for defcustom.
-
-2007-01-02 Richard Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * keymaps.texi (Tool Bar): Describe `grow-only' value of
- `auto-resize-tool-bars'.
-
-2006-12-30 Richard Stallman <rms@gnu.org>
-
- * keymaps.texi (Active Keymaps): Fix previous change.
-
-2006-12-30 Nick Roberts <nickrob@snap.net.nz>
-
- * keymaps.texi (Active Keymaps): Make xref to lookup-key.
-
-2006-12-30 Kim F. Storm <storm@cua.dk>
-
- * processes.texi (Bindat Spec): Clarify using field names in
- length specifications.
-
-2006-12-29 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * customize.texi (Variable Definitions): Document
- new name custom-add-frequent-value.
-
-2006-12-19 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * internals.texi (Building Emacs, Writing Emacs Primitives):
- Add index entries.
-
-2006-12-11 Richard Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * modes.texi (Font Lock Basics): Document nil value of
- font-lock-defaults.
-
-2006-12-10 Glenn Morris <rgm@gnu.org>
-
- * 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 <lekktu@gmail.com>
-
- * 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 <lekktu@gmail.com>
-
- * 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 <storm@cua.dk>
-
- * commands.texi (Misc Events): Update signal events.
- (Event Examples): Add signal example.
-
-2006-11-29 Richard Stallman <rms@gnu.org>
-
- * frames.texi (Visibility of Frames): Explain visible windows
- can be covered by others. Add xref for raise-frame.
-
-2006-11-28 Richard Stallman <rms@gnu.org>
-
- * searching.texi (Regexp Special): Update when ^ is special.
-
-2006-11-27 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <monnier@iro.umontreal.ca>
-
- * modes.texi (Multiline Font Lock): Rephrase some parts for clarity.
-
-2006-11-10 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * frames.texi (Window System Selections): Remove clipboard from
- description of selection-coding-system.
-
-2006-11-06 Richard Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * Makefile.in: Use relative paths to avoid advertising filesystem
- contents during compilation.
-
-2006-10-23 Kim F. Storm <storm@cua.dk>
-
- * commands.texi (Event Input Misc): Update unread-command-events.
-
-2006-10-23 Nick Roberts <nickrob@snap.net.nz>
-
- * lists.texi (Sets And Lists): Fix typos.
-
-2006-10-18 Juanma Barranquero <lekktu@gmail.com>
-
- * control.texi (Processing of Errors): Use @var for an argument,
- not @code.
-
-2006-10-16 Richard Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * frames.texi (Frame Titles): %c and %l are ignored in
- frame-title-format.
-
-2006-10-11 Richard Stallman <rms@gnu.org>
-
- * keymaps.texi (Key Sequences): Clarify use of kbd.
-
-2006-10-10 Kim F. Storm <storm@cua.dk>
-
- * lists.texi (Sets And Lists): Add memql.
-
-2006-10-03 Richard Stallman <rms@gnu.org>
-
- * searching.texi (Char Classes): Document :multibyte: and :unibyte:.
- Clarify :ascii: and :nonascii:.
-
-2006-09-29 Juri Linkov <juri@jurta.org>
-
- * modes.texi (%-Constructs): Reorder coding systems in the
- documentation of %z to the real order displayed in the modeline.
-
-2006-09-25 Richard Stallman <rms@gnu.org>
-
- * os.texi (Timers): Describe timer-max-repeats.
-
-2006-09-25 Chong Yidong <cyd@stupidchicken.com>
-
- * os.texi (Timers): Mention with-local-quit.
-
-2006-09-24 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * os.texi (Timers): Clarify about REPEAT when timer is delayed.
-
- * windows.texi (Window Start): Minor cleanups.
-
-2006-09-20 Kim F. Storm <storm@cua.dk>
-
- * 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 <dak@gnu.org>
-
- * keymaps.texi (Searching Keymaps): Small clarification.
-
-2006-09-18 Richard Stallman <rms@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * variables.texi (Tips for Defining): Fix a typo.
-
-2006-09-15 Richard Stallman <rms@gnu.org>
-
- * keymaps.texi (Remapping Commands, Searching Keymaps)
- (Active Keymaps): Clean up previous change.
-
-2006-09-15 Jay Belanger <belanger@truman.edu>
-
- * gpl.texi: Replace "Library Public License" by "Lesser Public
- License" throughout.
-
-2006-09-15 David Kastrup <dak@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * keymaps.texi (Searching Keymaps): Clarification.
- (Active Keymaps): Refer to Searching Keymaps instead of duplication.
-
-2006-09-13 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * display.texi (Display Table Format): Wording clarification.
- (Glyphs): Clarifications.
-
-2006-09-10 Chong Yidong <cyd@stupidchicken.com>
-
- * keymaps.texi (Active Keymaps): Mention that key-binding checks
- local maps.
-
-2006-09-10 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Forcing Redisplay): Document return value of
- function redisplay.
-
-2006-09-09 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec.
-
-2006-09-06 Kim F. Storm <storm@cua.dk>
-
- * frames.texi (Display Feature Testing): display-mm-dimensions-alist.
-
- * windows.texi (Window Start): Update pos-visible-in-window-p.
-
-2006-09-04 Richard Stallman <rms@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * makefile.w32-in (usermanualdir): New variable.
- (elisp.dvi): Use it.
-
-2006-09-01 Eli Zaretskii <eliz@gnu.org>
-
- * buffers.texi (Buffer Modification): Fix last change.
-
-2006-09-01 Chong Yidong <cyd@stupidchicken.com>
-
- * buffers.texi (Buffer Modification): Document
- buffer-chars-modified-tick.
-
-2006-08-31 Richard Stallman <rms@gnu.org>
-
- * modes.texi (Syntactic Font Lock): Mention specific faces once again.
-
-2006-08-31 Richard Bielawski <RBielawski@moneygram.com> (tiny change)
-
- * modes.texi (Syntactic Font Lock):
- Mention font-lock-syntactic-face-function
- instead of specific faces.
-
-2006-08-29 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Images): Add xrref to display-images-p.
-
-2006-08-28 Kenichi Handa <handa@m17n.org>
-
- * nonascii.texi (Lisp and Coding Systems): Fix description of
- detect-coding-region.
-
-2006-08-27 Michael Olson <mwolson@gnu.org>
-
- * processes.texi (Transaction Queues): Remove stray quote
- character.
-
-2006-08-25 Richard Stallman <rms@gnu.org>
-
- * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value.
- Add xref.
-
-2006-08-24 Chong Yidong <cyd@stupidchicken.com>
-
- * os.texi (Timers): Avoid waiting inside timers.
-
-2006-08-21 Lute Kamstra <lute@gnu.org>
-
- * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi.
-
-2006-08-20 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * commands.texi (Reading One Event): Explain idleness in
- `read-event'.
-
-2006-08-12 Chong Yidong <cyd@stupidchicken.com>
-
- * 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 <user42@zip.com.au>
-
- * 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 <rms@gnu.org>
-
- * modes.texi: Clean up wording in previous change.
-
-2006-08-07 Chong Yidong <cyd@stupidchicken.com>
-
- * 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 <eliz@gnu.org>
-
- * strings.texi (Formatting Strings): Warn against arbitrary
- strings as first arg to `format'.
-
-2006-07-31 Thien-Thi Nguyen <ttn@gnu.org>
-
- * text.texi (Clickable Text): Mention `help-echo' text property.
- Update intro, examples and associated explanations.
-
-2006-07-31 Richard Stallman <rms@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * modes.texi (Minor Mode Conventions): Update xref for add-to-list.
-
- * lists.texi (Sets And Lists): Likewise.
-
-2006-07-30 Thien-Thi Nguyen <ttn@gnu.org>
-
- * text.texi (Fields): Mention POS
- requirement when narrowing is in effect.
-
-2006-07-28 Richard Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * commands.texi (Reading One Event): Fix last change.
-
-2006-07-26 Chong Yidong <cyd@stupidchicken.com>
-
- * commands.texi (Reading One Event): Document SECONDS argument for
- read-event, read-char, and read-char-exclusive.
-
-2006-07-25 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline
- to ensure correct identification.
-
-2006-07-24 Richard Stallman <rms@gnu.org>
-
- * 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 <ttn@gnu.org>
-
- * text.texi (Links and Mouse-1):
- For mouse-on-link-p, expand on arg POS.
-
-2006-07-21 Kim F. Storm <storm@cua.dk>
-
- * 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 <eliz@gnu.org>
-
- * frames.texi (Input Focus): Document that focus-follows-mouse has
- no effect on MS-Windows.
-
-2006-07-18 Richard Stallman <rms@gnu.org>
-
- * display.texi (Forcing Redisplay): Cleanups in previous change.
-
- * processes.texi (Low-Level Network): Make menu more convenient.
-
-2006-07-18 Kim F. Storm <storm@cua.dk>
-
- * 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 <karl@gnu.org>
-
- * variables.texi, functions.texi, customize.texi, loading.texi:
- * edebug.texi, minibuf.texi: Fix page breaks through chapter 20.
-
-2006-07-17 Chong Yidong <cyd@stupidchicken.com>
-
- * commands.texi (Waiting): Document batch-mode sit-for behavior.
-
-2006-07-17 Richard Stallman <rms@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * text.texi (Special Properties): Clean up previous change.
-
-2006-07-16 Karl Berry <karl@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * text.texi (Special Properties): Describe fontified text property
- in relation to a character (not text).
-
-2006-07-15 Kim F. Storm <storm@cua.dk>
-
- * 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 <nickrob@snap.net.nz>
-
- * display.texi (Displaying Messages): Add anchor.
-
- * frames.texi (Dialog Boxes): Use it.
-
-2006-07-12 Richard Stallman <rms@gnu.org>
-
- * objects.texi (Frame Type): Explain nature of frames better.
-
- * frames.texi (Frames): Explain nature of frames better.
-
-2006-07-12 Ken Manheimer <ken.manheimer@gmail.com>
-
- * tips.texi (Coding Conventions): Explain why use cl at compile time.
-
-2006-07-12 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
-
- * 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 <storm@cua.dk>
-
- * 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 <nickrob@snap.net.nz>
-
- * display.texi (Buttons): Fix typo.
-
- * index.texi, elisp.texi (New Symbols): Comment node out.
-
-2006-07-09 Richard Stallman <rms@gnu.org>
-
- * display.texi (Truncation): Clean up previous change.
-
-2006-07-08 Richard Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * display.texi (Refresh Screen): Clarify force-window-update.
- (Truncation): "Normally" indicated by fringe arrows.
-
-2006-07-08 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <karl@gnu.org>
-
- * 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 <ttn@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * locals.texi (Standard Buffer-Local Variables): Update the list
- of variables.
-
-2006-06-26 Nick Roberts <nickrob@snap.net.nz>
-
- * files.texi (File Name Completion): Point user to the node
- "Reading File Names".
-
-2006-06-24 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * processes.texi (Bindat Spec): Clarify previous change.
-
-2006-06-16 Richard Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * display.texi (Forcing Redisplay): Clarify previous change.
-
-2006-06-13 Romain Francoise <romain@orebokech.com>
-
- * display.texi (Forcing Redisplay): Fix typo.
-
-2006-06-13 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Forcing Redisplay): Add redisplay-preemption-period.
-
-2006-06-10 Luc Teirlinck <teirllm@auburn.edu>
-
- * tips.texi (Coding Conventions): Add `@end itemize'.
-
-2006-06-10 Richard Stallman <rms@gnu.org>
-
- * tips.texi (Coding Conventions): Explain use of coding systems
- to ensure one decoding for strings.
-
-2006-06-09 Aidan Kehoe <kehoea@parhasard.net>
-
- * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF
- syntax.
-
-2006-06-07 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <ttn@gnu.org>
-
- * display.texi (Abstract Display): Fix typo.
-
-2006-06-03 Eli Zaretskii <eliz@gnu.org>
-
- * minibuf.texi (Minibuffer History) <history-add-new-input>:
- Reword variable's description.
-
-2006-06-01 Richard Stallman <rms@gnu.org>
-
- * windows.texi (Splitting Windows): Clarify splitting nonselected
- window.
-
-2006-05-31 Juri Linkov <juri@jurta.org>
-
- * minibuf.texi (Minibuffer History): Add history-add-new-input.
-
-2006-05-30 Richard Stallman <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <eliz@gnu.org>
-
- * nonascii.texi (Default Coding Systems): Fix it some more.
-
-2006-05-29 Eli Zaretskii <eliz@gnu.org>
-
- * nonascii.texi (Default Coding Systems): Fix last change.
-
-2006-05-29 Kenichi Handa <handa@m17n.org>
-
- * nonascii.texi (find-operation-coding-system): Describe the new
- argument format (FILENAME . BUFFER).
-
-2006-05-28 Richard Stallman <rms@gnu.org>
-
- * tips.texi (Coding Conventions): Better explain reasons not to
- advise other packages or use `eval-after-load'.
-
-2006-05-29 Kim F. Storm <storm@cua.dk>
-
- * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to
- `bindat-idx' and `bindat-raw' for clarity.
-
-2006-05-27 Thien-Thi Nguyen <ttn@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * 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 <ttn@gnu.org>
-
- * processes.texi (Bindat Functions): Explain term "total length".
- Use it in bindat-length and bindat-pack descriptions.
-
-2006-05-26 Eli Zaretskii <eliz@gnu.org>
-
- * tips.texi (Coding Conventions): Advise against using
- eval-after-load in packages. Add an index entry.
-
-2006-05-25 Juri Linkov <juri@jurta.org>
-
- * minibuf.texi (Text from Minibuffer): Undocument keep-all.
-
- * modes.texi (%-Constructs): Add %e, %z, %Z.
-
-2006-05-25 Richard Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * keymaps.texi (Key Sequences): Some clarifications.
-
-2006-05-25 Thien-Thi Nguyen <ttn@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * 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 <teirllm@auburn.edu>
-
- * frames.texi (Pointer Shape): @end table -> @end defvar.
-
-2006-05-22 Richard Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * syntax.texi (Parsing Expressions): Update info on which STATE
- elements are ignored.
-
-2006-05-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * hooks.texi (Standard Hooks): Correct typo.
-
- * gpl.texi (GPL): ifinfo -> ifnottex.
-
-2006-05-19 Michael Ernst <mernst@alum.mit.edu> (tiny change)
-
- * searching.texi (Simple Match Data): Warn about match data being
- set anew by every search.
-
-2006-05-17 Richard Stallman <rms@gnu.org>
-
- * minibuf.texi (Minibuffer History): Clarify.
-
- * searching.texi (Regexp Special): Clarify nested regexp warning.
-
-2006-05-16 Kim F. Storm <storm@cua.dk>
-
- * minibuf.texi (Minibuffer History): Update add-to-history.
-
-2006-05-15 Oliver Scholz <epameinondas@gmx.de> (tiny change)
-
- * nonascii.texi (Explicit Encoding): Fix
- typo (encoding<->decoding).
-
-2006-05-14 Richard Stallman <rms@gnu.org>
-
- * buffers.texi (Creating Buffers): Cleanup.
-
- * files.texi (Visiting Functions): Rewrite in find-file-noselect.
-
-2006-05-13 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules.
-
-2006-05-10 Reiner Steib <Reiner.Steib@gmx.de>
-
- * variables.texi (File Local Variables): Recommend to quote lambda
- expressions in safe-local-variable property.
-
-2006-05-09 Richard Stallman <rms@gnu.org>
-
- * variables.texi (File Local Variables): Document
- safe-local-eval-forms and safe-local-eval-function.
-
-2006-05-07 Kim F. Storm <storm@cua.dk>
-
- * minibuf.texi (Minibuffer History): Remove keep-dups arg
- from add-to-history.
-
-2006-05-07 Romain Francoise <romain@orebokech.com>
-
- * 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 <eliz@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * internals.texi (Pure Storage): Mention the pure overflow message
- at startup.
-
-2006-05-05 Johan Bockg\e,Ae\e(Brd <bojohan@dd.chalmers.se>
-
- * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax.
- (Searching Keymaps): Fix pseudo-Lisp description of keymap
- search.
-
-2006-05-01 Richard Stallman <rms@gnu.org>
-
- * intro.texi (nil and t): Clarify.
-
- * variables.texi (File Local Variables): Suggest using booleanp.
-
-2006-05-01 Juanma Barranquero <lekktu@gmail.com>
-
- * objects.texi (Type Predicates): Fix typos.
-
-2006-05-01 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * 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 <rms@gnu.org>
-
- * 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 <monnier@iro.umontreal.ca>
-
- * variables.texi (File Local Variables): Remove the special case t for
- safe-local-variable.
-
-2006-04-26 Richard Stallman <rms@gnu.org>
-
- * syntax.texi (Parsing Expressions): Minor cleanup.
-
-2006-04-18 Richard Stallman <rms@gnu.org>
-
- * 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 <romain@orebokech.com>
-
- * variables.texi (Local Variables): Update the default value of
- `max-specpdl-size'.
-
-2006-04-15 Michael Olson <mwolson@gnu.org>
-
- * processes.texi (Transaction Queues): Mention the new optional
- `delay-question' argument for `tq-enqueue'.
-
-2006-04-13 Bill Wohler <wohler@newt.com>
-
- * 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 <wohler@newt.com>
-
- * customize.texi (Common Keywords): Move description of
- customize-package-emacs-version-alist to @defvar.
-
-2006-04-10 Bill Wohler <wohler@newt.com>
-
- * customize.texi (Common Keywords): Add :package-version.
-
-2006-04-10 Kim F. Storm <storm@cua.dk>
-
- * text.texi (Buffer Contents): Add NOPROPS arg to
- filter-buffer-substring.
-
-2006-04-08 Kevin Ryde <user42@zip.com.au>
-
- * os.texi (Command-Line Arguments): Update xref to emacs manual
- "Command Arguments" -> "Emacs Invocation", per change there.
-
-2006-04-08 Thien-Thi Nguyen <ttn@gnu.org>
-
- * 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 <Reiner.Steib@gmx.de>
-
- * strings.texi (Predicates for Strings): Add string-or-null-p.
-
-2006-03-28 Kim F. Storm <storm@cua.dk>
-
- * processes.texi (Accepting Output): Remove obsolete (and incorrect)
- remarks about systems that don't support fractional seconds.
-
-2006-03-25 Karl Berry <karl@gnu.org>
-
- * elisp.texi: Use @copyright{} instead of (C), and do not indent
- the year list.
-
-2006-03-21 Nick Roberts <nickrob@snap.net.nz>
-
- * display.texi (Fringe Indicators): Fix typos.
-
-2006-03-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <acm@muc.de>
-
- * text.texi (Special Properties): Clarify `fontified' property.
-
-2006-03-16 Richard Stallman <rms@gnu.org>
-
- * display.texi (Defining Images): Minor cleanup.
-
-2006-03-16 Bill Wohler <wohler@newt.com>
-
- * display.texi (Defining Images): In image-load-path-for-library,
- prefer user's images.
-
-2006-03-15 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * modes.texi (Region to Fontify): Remove font-lock-lines-before.
-
-2006-03-15 Bill Wohler <wohler@newt.com>
-
- * 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 <wohler@newt.com>
-
- * display.texi (Defining Images): In image-load-path-for-library,
- always return list of directories. Update example.
-
-2006-03-14 Alan Mackenzie <acm@muc.de>
-
- * 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 <rms@gnu.org>
-
- * 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 <wohler@newt.com>
-
- * display.texi (Defining Images): Add image-load-path-for-library.
-
-2006-03-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * searching.texi (Regexp Special): Put remark between parentheses
- to avoid misreading.
-
-2006-03-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <storm@cua.dk>
-
- * keymaps.texi (Tool Bar): Add tool-bar-border.
-
-2006-02-28 Luc Teirlinck <teirllm@auburn.edu>
-
- * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos.
-
-2006-02-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <keramida@ceid.upatras.gr> (tiny change)
-
- * display.texi (Fringe Indicators, Fringe Cursors): Fix typos.
-
- * windows.texi (Window Tree): Fix typo.
-
-2006-02-20 Kim F. Storm <storm@cua.dk>
-
- * 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 <lekktu@gmail.com>
-
- * commands.texi (Using Interactive): Fix reference to node
- "Minibuffers".
-
-2006-02-19 Richard M. Stallman <rms@gnu.org>
-
- * 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\e,Ae\e(Brd <bojohan@dd.chalmers.se>
-
- * 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 <rms@gnu.org>
-
- * variables.texi (File Local Variables): Clarifications.
-
-2006-02-14 Juanma Barranquero <lekktu@gmail.com>
-
- * variables.texi (File Local Variables): Use @code for a cons
- cell, not @var.
-
-2006-02-13 Chong Yidong <cyd@stupidchicken.com>
-
- * variables.texi (File Local Variables): Document new file local
- variable behavior.
-
-2006-02-10 Kim F. Storm <storm@cua.dk>
-
- * eval.texi (Function Indirection): Add NOERROR to indirect-function.
-
-2006-02-08 Juanma Barranquero <lekktu@gmail.com>
-
- * modes.texi (%-Constructs): Remove obsolete info about
- `global-mode-string'.
-
-2006-02-07 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * display.texi (Other Display Specs, Image Descriptors):
- Image description is a list, not a cons cell.
-
-2006-01-28 Luc Teirlinck <teirllm@auburn.edu>
-
- * lists.texi (Cons Cells): Minor correction (the cdr of a dotted
- list is not necessarily a list).
-
-2006-01-27 Eli Zaretskii <eliz@gnu.org>
-
- * frames.texi (Layout Parameters): border-width and
- internal-border-width belong to the frame, not the window.
-
-2006-01-19 Richard M. Stallman <rms@gnu.org>
-
- * 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 <nickrob@snap.net.nz>
-
- * advice.texi (Simple Advice): Update example to fit argument
- change in previous-line.
-
-2006-01-05 Richard M. Stallman <rms@gnu.org>
-
- * markers.texi (The Mark): Fix in `mark'.
-
-2006-01-04 Richard M. Stallman <rms@gnu.org>
-
- * processes.texi (Misc Network, Make Network): Minor cleanups.
-
-2006-01-04 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * text.texi (Changing Properties):
- Don't use return value of set-text-properties.
-
-2005-12-29 Luc Teirlinck <teirllm@auburn.edu>
-
- * modes.texi (Mode Line Format): Correct typo in menu.
-
-2005-12-29 Richard M. Stallman <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * minibuf.texi (Basic Completion): Update lazy-completion-table
- examples for removal of ARGS argument.
-
-2005-12-23 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Undo): Restore some explanation from the version
- that was deleted.
-
-2005-12-23 Eli Zaretskii <eliz@gnu.org>
-
- * text.texi (Undo): Remove duplicate descriptions of `apply
- funname' and `apply delta' elements of the undo list.
-
-2005-12-20 Richard M. Stallman <rms@gnu.org>
-
- * help.texi (Help Functions): Update documentation of `apropos'.
-
-2005-12-20 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * minibuf.texi (Minibuffer Contents): Minor cleanup.
-
-2005-12-16 Juri Linkov <juri@jurta.org>
-
- * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents.
-
-2005-12-14 Romain Francoise <romain@orebokech.com>
-
- * modes.texi (Customizing Keywords): Rename `append' to `how'.
- Fix typo.
-
-2005-12-11 Juri Linkov <juri@jurta.org>
-
- * 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 <rms@gnu.org>
-
- * customize.texi (Common Keywords): State caveats for use of :tag.
-
-2005-12-08 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * windows.texi (Resizing Windows): Delete preserve-before args.
-
-2005-12-05 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * keymaps.texi (Format of Keymaps): Remove mention of a quirk
- in full keymaps, since the quirk has been fixed.
-
-2005-12-03 Eli Zaretskii <eliz@gnu.org>
-
- * hooks.texi (Standard Hooks): Add index entries. Mention
- `compilation-finish-functions'.
-
-2005-11-27 Richard M. Stallman <rms@gnu.org>
-
- * windows.texi (Resizing Windows): Add adjust-window-trailing-edge.
-
-2005-11-21 Juri Linkov <juri@jurta.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * display.texi: Revert 2005-11-20 change.
-
-2005-11-20 Thien-Thi Nguyen <ttn@gnu.org>
-
- * processes.texi (Bindat Functions):
- Say "third" to refer to zero-based index "2".
-
-2005-11-18 Luc Teirlinck <teirllm@auburn.edu>
-
- * loading.texi (Library Search): Update the default value of
- `load-suffixes'.
-
-2005-11-17 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Attribute Functions): Mention :ignore-defface.
-
-2005-11-16 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * 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 <rms@gnu.org>
-
- * files.texi (Magic File Names): find-file-name-handler checks the
- `operations' property of the handler.
-
-2005-11-03 Richard M. Stallman <rms@gnu.org>
-
- * variables.texi (Frame-Local Variables): Small clarification.
-
-2005-10-29 Chong Yidong <cyd@stupidchicken.com>
-
- * os.texi (Init File): Document ~/.emacs.d/init.el.
-
-2005-10-29 Richard M. Stallman <rms@gnu.org>
-
- * internals.texi (Garbage Collection): Document memory-full.
-
-2005-10-28 Bill Wohler <wohler@newt.com>
-
- * tips.texi (Documentation Tips): Help mode now creates hyperlinks
- for URLs.
-
-2005-10-28 Richard M. Stallman <rms@gnu.org>
-
- * minibuf.texi (Completion Commands): Clean up prev change.
-
-2005-10-26 Kevin Ryde <user42@zip.com.au>
-
- * compile.texi (Eval During Compile): Explain recommended uses
- of eval-when-compile and eval-and-compile.
-
-2005-10-27 Masatake YAMATO <jet@gyve.org>
-
- * minibuf.texi (Completion Commands):
- Write about new optional argument for `display-completion-list'.
-
-2005-10-23 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Overlay Arrow): Clarify about local bindings of
- overlay-arrow-position.
-
-2005-10-22 Eli Zaretskii <eliz@gnu.org>
-
- * internals.texi (Building Emacs): Fix last change.
-
-2005-10-22 Richard M. Stallman <rms@gnu.org>
-
- * internals.texi (Building Emacs): Document eval-at-startup.
-
-2005-10-21 Richard M. Stallman <rms@gnu.org>
-
- * loading.texi (Where Defined): load-history contains abs file names.
- symbol-file returns abs file names.
-
-2005-10-19 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Showing Images): Add max-image-size integer value.
-
-2005-10-18 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Showing Images): Document max-image-size.
-
-2005-10-17 Richard M. Stallman <rms@gnu.org>
-
- * commands.texi (Quitting): Minor clarification.
-
- * processes.texi (Sentinels): Clarify about output and quitting.
- (Filter Functions): Mention with-local-quit.
-
-2005-10-17 Juri Linkov <juri@jurta.org>
-
- * 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 <storm@cua.dk>
-
- * windows.texi (Window Tree): Rename window-split-tree to window-tree.
- Rename manual section accordingly.
-
-2005-10-04 Kim F. Storm <storm@cua.dk>
-
- * windows.texi (Window Split Tree): New section describing
- new function window-split-tree function.
-
-2005-10-03 Nick Roberts <nickrob@snap.net.nz>
-
- * display.texi (Fringe Size/Pos): Simplify and add detail.
-
-2005-09-30 Romain Francoise <romain@orebokech.com>
-
- * 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 <juri@jurta.org>
-
- * display.texi (Displaying Messages): Rename argument name
- `string' to `format-string' in functions `message', `message-box',
- `message-or-box'.
-
-2005-09-26 Chong Yidong <cyd@stupidchicken.com>
-
- * errors.texi (Standard Errors): Correct xrefs.
-
-2005-09-18 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Defining Images): Update documentation for
- `image-load-path'.
-
-2005-09-17 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Defining Images): Clean up previous change.
-
-2005-09-16 Romain Francoise <romain@orebokech.com>
-
- * elisp.texi: Specify GFDL version 1.2.
-
- * doclicense.texi (GNU Free Documentation License): Update to
- version 1.2.
-
-2005-09-15 Chong Yidong <cyd@stupidchicken.com>
-
- * display.texi (Defining Images): Document `image-load-path'.
-
-2005-09-15 Richard M. Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * files.texi (Saving Buffers): Fix typo.
-
-2005-09-08 Richard M. Stallman <rms@gnu.org>
-
- * tips.texi (Programming Tips): Correct the "default" prompt spec.
-
-2005-09-08 Chong Yidong <cyd@stupidchicken.com>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * tips.texi (Programming Tips): Add conventions for minibuffer
- questions and prompts.
-
-2005-09-03 Joshua Varner <jlvarner@gmail.com> (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 <ttn@gnu.org>
-
- * text.texi (Buffer Contents): Use "\n" in examples' result strings.
-
- (Insertion): Document precise type of `insert-char' arg COUNT.
-
-2005-09-02 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * modes.texi (Other Font Lock Variables): Sync the default of
- font-lock-lines-before.
-
-2005-08-31 Michael Albinus <michael.albinus@gmx.de>
-
- * files.texi (Magic File Names): Add `make-auto-save-file-name'.
-
-2005-08-29 Richard M. Stallman <rms@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * os.texi (Startup Summary): Fix the description of the initial
- startup message display.
-
-2005-08-25 Richard M. Stallman <rms@gnu.org>
-
- * searching.texi (Search and Replace): Add replace-regexp-in-string.
-
-2005-08-25 Emilio C. Lopes <eclig@gmx.net>
-
- * display.texi (Finding Overlays): Fix `find-overlay-prop' in
- `next-overlay-change' example.
-
-2005-08-22 Juri Linkov <juri@jurta.org>
-
- * 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 <acm@muc.de>
-
- * buffers.texi (The Buffer List): Clarify the manipulation of the
- buffer list.
-
-2005-08-14 Richard M. Stallman <rms@gnu.org>
-
- * modes.texi (Auto Major Mode): interpreter-mode-alist key is not
- a regexp.
-
-2005-08-11 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * 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 <eliz@gnu.org>
-
- * makefile.w32-in (info): Don't run install-info.
- ($(infodir)/dir): New target, produced by running install-info.
-
-2005-07-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * modes.texi (Defining Minor Modes): The keyword for the initial
- value is :init-value, not :initial-value.
-
-2005-07-23 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * internals.texi (Garbage Collection): Clarify previous change.
-
-2005-07-21 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * internals.texi (Garbage Collection): Add gc-cons-percentage.
-
-2005-07-18 Juri Linkov <juri@jurta.org>
-
- * 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 <rms@gnu.org>
-
- * display.texi (Managing Overlays): Clarify make-overlay
- args for insertion types.
-
-2005-07-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <franl@world.std.com> (tiny change)
-
- * os.texi (Translating Input): Fix typo.
-
-2005-07-08 Richard M. Stallman <rms@gnu.org>
-
- * README: Update edition number and size estimate.
-
- * elisp.texi (VERSION): Set to 2.9.
-
-2005-07-07 Richard M. Stallman <rms@gnu.org>
-
- * book-spine.texinfo: Update Emacs version.
-
- * display.texi (Inverse Video): Delete mode-line-inverse-video.
-
-2005-07-06 Richard M. Stallman <rms@gnu.org>
-
- * searching.texi (Regexp Search): Clarify what re-search-forward
- does when the search fails.
-
-2005-07-05 Lute Kamstra <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * hooks.texi (Standard Hooks): Add occur-hook.
-
-2005-07-03 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi (The Echo Area): Correct menu.
-
-2005-07-03 Richard M. Stallman <rms@gnu.org>
-
- * 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 <lekktu@gmail.com>
-
- * variables.texi (Defining Variables): `user-variable-p' returns t
- for aliases of user options, nil for alias loops.
-
-2005-06-28 Richard M. Stallman <rms@gnu.org>
-
- * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before
- make-keymap.
-
-2005-06-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * variables.texi (Setting Variables): Correct and clarify
- description of `add-to-ordered-list'.
-
-2005-06-26 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Faces): Minor cleanup.
-
-2005-06-25 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi (Faces): `facep' returns t for strings that are
- face names.
-
-2005-06-25 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * numbers.texi (Float Basics): Explain how to test for NaN,
- and printing the sign of NaNs.
-
-2005-06-24 Eli Zaretskii <eliz@gnu.org>
-
- * makefile.w32-in (MAKEINFO): Use --force.
-
-2005-06-23 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Face Functions): Correct Texinfo usage.
-
-2005-06-23 Luc Teirlinck <teirllm@auburn.edu>
-
- * lists.texi (Rings): `ring-elements' now returns the elements of
- RING in order.
-
-2005-06-23 Juanma Barranquero <lekktu@gmail.com>
-
- * markers.texi (The Mark): Texinfo usage fix.
-
-2005-06-23 Kim F. Storm <storm@cua.dk>
-
- * 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 <gmorris@ast.cam.ac.uk>
-
- * display.texi (Face Functions): Mention face aliases.
-
-2005-06-21 Richard M. Stallman <rms@gnu.org>
-
- * anti.texi (Antinews): Texinfo usage fix.
-
-2005-06-21 Karl Berry <karl@gnu.org>
-
- * 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 <juri@jurta.org>
-
- * display.texi (Defining Faces): Add `customized-face'.
-
-2005-06-20 Kim F. Storm <storm@cua.dk>
-
- * 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 <karl@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * lists.texi (Rings): Various minor clarifications and corrections.
-
-2005-06-18 Richard M. Stallman <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * processes.texi: Fix typos.
- (Bindat Spec): Correct Texinfo error.
- (Byte Packing): Fix ungrammatical sentence.
-
-2005-06-17 Thien-Thi Nguyen <ttn@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <lekktu@gmail.com>
-
- * 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 <storm@cua.dk>
-
- * searching.texi (Entire Match Data): Rephrase warnings about
- evaporate arg to match-data and set-match-data.
-
-2005-06-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <lute@gnu.org>
-
- * debugging.texi (Function Debugging): Primitives can break on
- entry too.
-
-2005-06-14 Kim F. Storm <storm@cua.dk>
-
- * variables.texi (Setting Variables): Add add-to-ordered-list.
-
-2005-06-13 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * 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 <lute@gnu.org>
-
- * text.texi (Special Properties): Fix cross reference.
-
-2005-06-11 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <acm@muc.de>
-
- * text.texi (Adaptive Fill): Amplify the description of
- fill-context-prefix.
-
-2005-06-10 Luc Teirlinck <teirllm@auburn.edu>
-
- * syntax.texi (Parsing Expressions): Fix Texinfo error.
-
-2005-06-10 Stefan Monnier <monnier@iro.umontreal.ca>
-
- * syntax.texi (Parsing Expressions): Document syntax-ppss.
-
-2005-06-10 Luc Teirlinck <teirllm@auburn.edu>
-
- * debugging.texi (Error Debugging): Minor rewording.
- (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry'
- is optional.
-
-2005-06-10 Lute Kamstra <lute@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * searching.texi (Entire Match Data): Explain new `reseat' argument to
- match-data and set-match-data.
-
-2005-06-08 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <juri@jurta.org>
-
- * display.texi (Standard Faces): Add `shadow' face.
-
-2005-05-29 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * frames.texi (Dialog Boxes): Minor fixes.
-
-2005-05-25 Masatake YAMATO <jet@gyve.org>
-
- * display.texi (Standard Faces): Write about `mode-line-highlight'.
-
-2005-05-24 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog'
- is optional.
-
-2005-05-24 Nick Roberts <nickrob@snap.net.nz>
-
- * frames.texi (Dialog Boxes): Descibe new optional argument.
-
-2005-05-23 Lute Kamstra <lute@gnu.org>
-
- * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend
- syntax-begin-function over font-lock-beginning-of-syntax-function.
-
-2005-05-21 Luc Teirlinck <teirllm@auburn.edu>
-
- * minibuf.texi (Reading File Names): Update description of
- `read-directory-name'.
-
- * modes.texi (Derived Modes): Clarify :group keyword.
-
-2005-05-21 Eli Zaretskii <eliz@gnu.org>
-
- * files.texi (Locating Files): New subsection.
- Describe locate-file and executable-find.
-
-2005-05-21 Kevin Ryde <user42@zip.com.au>
-
- * frames.texi (Initial Parameters): Update cross reference to
- "Emacs Invocation".
-
-2005-05-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * modes.texi (Derived Modes): Correct references to non-existing
- variable standard-syntax-table.
-
-2005-05-17 Lute Kamstra <lute@gnu.org>
-
- * modes.texi (Defining Minor Modes): Mention the mode hook.
-
-2005-05-15 Kim F. Storm <storm@cua.dk>
-
- * processes.texi (Network): Remove open-network-stream-nowait.
- (Network Servers): Remove open-network-stream-server.
-
-2005-05-15 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <ttn@gnu.org>
-
- * processes.texi (Signals to Processes)
- (Low-Level Network): Fix typos.
-
-2005-05-11 Lute Kamstra <lute@gnu.org>
-
- * elisp.texi (Top): Add some nodes from the chapter "Major and
- Minor Modes" to the detailed node listing.
-
-2005-05-10 Richard M. Stallman <rms@gnu.org>
-
- * keymaps.texi (Extended Menu Items): Menu item filter functions
- can be called at any time.
-
-2005-05-08 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <user42@zip.com.au>
-
- * display.texi (The Echo Area): Correct format function cross
- reference.
-
-2005-05-05 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * commands.texi (Interactive Codes): Fix Texinfo usage.
- Document U more clearly.
-
-2005-05-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * edebug.texi (Checking Whether to Stop): Fix previous change.
-
-2005-05-01 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi: Fix typos and Texinfo usage.
-
- * edebug.texi (Checking Whether to Stop): executing-macro ->
- executing-kbd-macro.
-
-2005-05-01 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Invisible Text): Correct add-to-invisibility-spec.
-
-2005-04-30 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Magic File Names): Document `operations' property.
-
-2005-04-29 Lute Kamstra <lute@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock.
-
-2005-04-25 Luc Teirlinck <teirllm@auburn.edu>
-
- * hooks.texi (Standard Hooks): Most minor modes have mode hooks too.
-
-2005-04-24 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * files.texi (Changing Files): Document MUSTBENEW arg in copy-file.
-
-2005-04-22 Nick Roberts <nickrob@snap.net.nz>
-
- * windows.texi (Cyclic Window Ordering): Clarify window-list.
-
-2005-04-22 Nick Roberts <nickrob@snap.net.nz>
-
- * variables.texi (Variable Aliases): Describe make-obsolete-variable
- and define-obsolete-variable-alias.
-
-2005-04-22 Kim F. Storm <storm@cua.dk>
-
- * 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 <lute@gnu.org>
-
- * lists.texi (Association Lists): Document rassq-delete-all.
-
-2005-04-19 Richard M. Stallman <rms@gnu.org>
-
- * modes.texi (Search-based Fontification): Explain that
- facespec is an expression to be evaluated.
-
-2005-04-19 Kevin Ryde <user42@zip.com.au>
-
- * streams.texi (Output Functions): Fix xref.
- * strings.texi (String Conversion): Fix xref.
-
-2005-04-19 Kim F. Storm <storm@cua.dk>
-
- * symbols.texi (Symbol Plists): Add safe-get.
- Mention that `get' may signal an error.
-
-2005-04-18 Nick Roberts <nickrob@snap.net.nz>
-
- * customize.texi (Variable Definitions): Replace tooltip-mode
- example with save-place.
-
-2005-04-17 Richard M. Stallman <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * modes.texi (Search-based Fontification): Fix cross references.
- Use consistent terminology. Document anchored highlighting.
-
-2005-04-05 Lute Kamstra <lute@gnu.org>
-
- * modes.texi (Defining Minor Modes): Document :group keyword
- argument and its default value.
-
-2005-04-03 Lute Kamstra <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * nonascii.texi (Coding System Basics): Another wording cleanup.
-
-2005-04-01 Richard M. Stallman <rms@gnu.org>
-
- * nonascii.texi (Coding System Basics): Clarify previous change.
-
-2005-04-01 Kenichi Handa <handa@m17n.org>
-
- * nonascii.texi (Coding System Basics): Describe about rondtrip
- identity of coding systems.
-
-2005-03-29 Chong Yidong <cyd@stupidchicken.com>
-
- * text.texi (Buffer Contents): Add filter-buffer-substring and
- buffer-substring-filters.
-
-2005-03-26 Chong Yidong <cyd@stupidchicken.com>
-
- * anti.texi (Antinews): Mention `G' interactive code.
-
- * tips.texi (Compilation Tips): Mention benchmark.el.
-
-2005-03-27 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <gmorris@ast.cam.ac.uk>
-
- * 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 <rms@gnu.org>
-
- * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps):
- Cleanup previous change.
-
-2005-03-25 Chong Yidong <cyd@stupidchicken.com>
-
- * 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 <storm@cua.dk>
-
- * 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 <cyd@stupidchicken.com>
-
- * 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 <lute@gnu.org>
-
- * edebug.texi (Instrumenting Macro Calls): Fix another typo.
-
-2005-03-17 Richard M. Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
-
- * 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 <lute@gnu.org>
-
- * edebug.texi (Instrumenting Macro Calls): Fix typos.
-
-2005-03-08 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Specified Space): Property :width is support on
- non-graphic terminals, :height is not.
-
-2005-03-07 Richard M. Stallman <rms@gnu.org>
-
- * 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 <cyd@stupidchicken.com>
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * debugging.texi (Error Debugging): Remove stack-trace-on-error.
-
-2005-03-04 Lute Kamstra <lute@gnu.org>
-
- * debugging.texi (Error Debugging): Document stack-trace-on-error.
-
-2005-03-03 Lute Kamstra <lute@gnu.org>
-
- * edebug.texi (Instrumenting Macro Calls): Fix typo.
-
-2005-03-01 Lute Kamstra <lute@gnu.org>
-
- * debugging.texi (Debugger Commands): Update `j'.
-
-2005-02-28 Lute Kamstra <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * minibuf.texi (Basic Completion): Allow symbols in addition to
- strings in try-completion and all-completions.
-
-2005-02-14 Lute Kamstra <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * objects.texi (Symbol Type): Minor correction.
-
-2005-02-06 Lute Kamstra <lute@gnu.org>
-
- * modes.texi (Example Major Modes): Fix typos.
-
-2005-02-06 Richard M. Stallman <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * text.texi (Maintaining Undo): Remove obsolete function.
-
-2005-02-05 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <MPHodges@member.fsf.org>
-
- * edebug.texi (Printing in Edebug): Fix default value of
- edebug-print-circle.
- (Coverage Testing): Fix displayed frequency count data.
-
-2005-02-02 Luc Teirlinck <teirllm@auburn.edu>
-
- * text.texi (Maintaining Undo): Add `undo-outer-limit'.
-
-2005-02-02 Kim F. Storm <storm@cua.dk>
-
- * text.texi (Undo) <buffer-undo-list>: Describe `apply' elements.
-
-2005-01-29 Eli Zaretskii <eliz@gnu.org>
-
- * commands.texi (Misc Events): Describe the help-echo event.
-
- * text.texi (Special Properties) <help-echo>: 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 <storm@cua.dk>
-
- * 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 <teirllm@auburn.edu>
-
- * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses
- command remapping.
-
-2005-01-15 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Defining Images): Mention DATA-P arg of create-image.
-
-2005-01-14 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * modes.texi (Emulating Mode Line): Update format-mode-line entry.
-
-2005-01-13 Francis Litterio <franl@world.std.com> (tiny change)
-
- * keymaps.texi (Active Keymaps): Fix overriding-local-map description.
-
-2005-01-12 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * display.texi (Face Attributes): Correct xref to renamed node.
-
-2005-01-01 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Face Attributes): Describe hex color specs.
-
-2004-12-31 Richard M. Stallman <rms@gnu.org>
-
- * os.texi (Timers): Update previous change.
-
-2004-12-30 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * os.texi (Timers): Discuss timers vs editing the buffer and undo.
-
-2004-12-28 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * commands.texi (Event Input Misc): Add while-no-input.
-
-2004-12-11 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Line Height): Rewrite text for clarity.
-
-2004-12-11 Kim F. Storm <storm@cua.dk>
-
- * 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 <ttn@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * Makefile.in (maintainer-clean): Remove the info files
- in $(infodir) where they are created.
-
-2004-12-03 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * locals.texi (Standard Buffer-Local Variables): Undo prev change.
- Remove a few vars that are not always buffer-local.
-
-2004-11-24 Luc Teirlinck <teirllm@auburn.edu>
-
- * locals.texi (Standard Buffer-Local Variables): Comment out
- xref's to non-existent node `Yet to be written'.
-
-2004-11-24 Richard M. Stallman <rms@gnu.org>
-
- * 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 <harder@ifa.au.dk>
-
- * processes.texi (Synchronous Processes, Output from Processes):
- Markup fix.
-
-2004-11-20 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * searching.texi (Regexp Search): Add search-whitespace-regexp.
-
-2004-11-19 CHENG Gao <chenggao@gmail.com> (tiny change)
-
- * tips.texi (Coding Conventions): Fix typo.
-
-2004-11-16 Richard M. Stallman <rms@gnu.org>
-
- * 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 <ttn@gnu.org>
-
- * frames.texi (Window Frame Parameters): Fix typo.
-
-2004-11-15 Kim F. Storm <storm@cua.dk>
-
- * symbols.texi (Other Plists): Note that plist-get may signal error.
- Add safe-plist-get.
-
-2004-11-15 Thien-Thi Nguyen <ttn@gnu.org>
-
- * modes.texi (Font Lock Basics): Fix typo.
-
-2004-11-08 Richard M. Stallman <rms@gnu.org>
-
- * syntax.texi (Syntax Table Functions): Add syntax-after.
-
-2004-11-06 Lars Brinkhoff <lars@nocrew.org>
-
- * os.texi (Processor Run Time): New section documenting
- get-internal-run-time.
-
-2004-11-06 Eli Zaretskii <eliz@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * commands.texi (Keyboard Macros): Document `append' return value
- of `defining-kbd-macro'.
-
-2004-11-01 Richard M. Stallman <rms@gnu.org>
-
- * commands.texi (Interactive Call): Add called-interactively-p.
-
-2004-10-29 Simon Josefsson <jas@extundo.com>
-
- * minibuf.texi (Reading a Password): Revert.
-
-2004-10-28 Richard M. Stallman <rms@gnu.org>
-
- * frames.texi (Display Feature Testing): Explain about "vendor".
-
-2004-10-27 Richard M. Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * commands.texi (Interactive Codes): Add U code letter.
-
-2004-10-25 Simon Josefsson <jas@extundo.com>
-
- * minibuf.texi (Reading a Password): Add.
-
-2004-10-24 Jason Rumney <jasonr@gnu.org>
-
- * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up
- and wheel-down.
-
-2004-10-24 Kai Grossjohann <kai.grossjohann@gmx.net>
-
- * processes.texi (Synchronous Processes): Document process-file.
-
-2004-10-22 Kenichi Handa <handa@m17n.org>
-
- * text.texi (translate-region): Document that it accepts also a
- char-table.
-
-2004-10-22 David Ponce <david@dponce.com>
-
- * windows.texi (Resizing Windows): Document the `preserve-before'
- argument of the functions `enlarge-window' and `shrink-window'.
-
-2004-10-19 Jason Rumney <jasonr@gnu.org>
-
- * makefile.w32-in (elisp): Change order of arguments to makeinfo.
-
-2004-10-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <pogonyshev@gmx.net>
-
- * display.texi (Progress): New node.
-
-2004-10-05 Kim F. Storm <storm@cua.dk>
-
- * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos.
-
-2004-09-29 Kim F. Storm <storm@cua.dk>
-
- * 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) <define-fringe-bitmap>: 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 <rms@gnu.org>
-
- * text.texi (Special Properties): Clarify line-spacing and line-height.
-
- * searching.texi (Regexp Search): Add looking-back.
-
-2004-09-25 Luc Teirlinck <teirllm@auburn.edu>
-
- * display.texi: Correct typos.
- (Image Descriptors): Correct xref's.
-
-2004-09-25 Richard M. Stallman <rms@gnu.org>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * commands.texi (Key Sequence Input):
- Clarify downcasing in read-key-sequence.
-
-2004-09-08 Juri Linkov <juri@jurta.org>
-
- * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'.
-
-2004-09-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * modes.texi (Major Mode Conventions): Discuss rebinding of
- standard key bindings.
-
-2004-08-18 Kim F. Storm <storm@cua.dk>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <jpw@gnu.org>
-
- * macros.texi (Defining Macros): Declaration keyword for setting
- Edebug spec is `debug' not `edebug'.
-
-2004-07-19 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * 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 <jimb@redhat.com>
-
- * searching.texi (Regexp Backslash): Document new \_< and \_>
- operators.
-
-2004-07-16 Juanma Barranquero <lektu@terra.es>
-
- * display.texi (Images): Fix Texinfo usage.
-
-2004-07-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * buffers.texi (Modification Time): `visited-file-modtime' now
- returns a list of two integers, instead of a cons.
-
-2004-07-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * windows.texi: Various changes in addition to:
- (Splitting Windows): Add `split-window-keep-point'.
-
-2004-07-09 Richard M. Stallman <rms@gnu.org>
-
- * frames.texi (Input Focus): Minor fix.
-
-2004-07-07 Luc Teirlinck <teirllm@auburn.edu>
-
- * frames.texi (Input Focus): Clarify descriptions of
- `select-frame-set-input-focus' and `select-frame'.
-
-2004-07-06 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <ttn@gnu.org>
-
- * os.texi: Update copyright.
- (Session Management): Grammar fix.
- Clarify which Emacs does the restarting.
- Use @samp for *scratch* buffer.
-
-2004-07-04 Alan Mackenzie <acm@muc.de>
-
- * 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 <rms@gnu.org>
-
- * files.texi (Saving Buffers): Cleanup write-contents-function.
- (Magic File Names): Cleanup file-remote-p.
-
-2004-07-02 Kai Grossjohann <kai@emptydomain.de>
-
- * files.texi (Magic File Names): `file-remote-p' returns an
- identifier of the remote system, not just t.
-
-2004-07-02 David Kastrup <dak@gnu.org>
-
- * searching.texi (Entire Match Data): Add explanation about new
- match-data behavior when @var{integers} is non-nil.
-
-2004-06-24 Richard M. Stallman <rms@gnu.org>
-
- * 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 <david.ponce@wanadoo.fr>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <larsh@math.ku.dk>
-
- * files.texi (Saving Buffers): Correct description of
- `write-contents-functions'.
-
-2004-06-21 Juanma Barranquero <lektu@terra.es>
-
- * display.texi (Images): Remove redundant @vindex directives.
- Rewrite `image-library-alist' doc in active voice.
-
-2004-06-14 Juanma Barranquero <lektu@terra.es>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * loading.texi (Named Features): Clarify return value
- and meaning of NOERROR.
-
- * variables.texi (File Local Variables): Minor cleanup.
-
-2004-05-30 Michael Albinus <michael.albinus@gmx.de>
-
- * files.texi (Magic File Names): Add `file-remote-p' as operation
- of file name handlers.
-
-2004-05-29 Richard M. Stallman <rms@gnu.org>
-
- * modes.texi (Minor Mode Conventions): (-) has no special meaning
- as arg to a minor mode command.
-
-2004-05-22 Richard M. Stallman <rms@gnu.org>
-
- * 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 <teirllm@dms.auburn.edu>
-
- * 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 <ttn@gnu.org>
-
- * modes.texi (Search-based Fontification): Fix typo.
-
-2004-05-10 Juanma Barranquero <lektu@terra.es>
-
- * 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 <larsh@math.ku.dk>
-
- * 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 <harder@ifa.au.dk>
-
- * display.texi: emacs -> Emacs.
-
-2004-04-27 Matthew Mundell <matt@mundell.ukfsn.org>
-
- * files.texi (Changing Files): Document set-file-times.
-
-2004-04-23 Juanma Barranquero <lektu@terra.es>
-
- * makefile.w32-in: Add "-*- makefile -*-" mode tag.
-
-2004-04-18 Jesper Harder <harder@ifa.au.dk>
-
- * tips.texi (Coding Conventions): defopt -> defcustom.
-
-2004-04-16 Luc Teirlinck <teirllm@auburn.edu>
-
- * sequences.texi: Various clarifications.
-
-2004-04-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * buffers.texi (Read Only Buffers): Mention optional ARG to
- `toggle-read-only'.
-
-2004-04-14 Nick Roberts <nick@nick.uklinux.net>
-
- * windows.texi (Selecting Windows): Note that get-lru-window
- returns a full-width window if possible.
-
-2004-04-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <miles@gnu.org>
-
- * macros.texi (Expansion): Add description of `macroexpand-all'.
-
-2004-04-05 Jesper Harder <harder@ifa.au.dk>
-
- * variables.texi (Variable Aliases): Mention
- cyclic-variable-indirection.
-
- * errors.texi (Standard Errors): Ditto.
-
-2004-04-04 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <juri@jurta.org>
-
- * sequences.texi (Sequence Functions): Replace xref to `Vectors'
- with `Vector Functions'.
-
- * text.texi (Sorting): Add missing quote.
-
-2004-03-14 Luc Teirlinck <teirllm@auburn.edu>
-
- * intro.texi (Lisp History): Replace xref to `cl' manual with
- inforef.
-
-2004-03-12 Richard M. Stallman <rms@gnu.org>
-
- * intro.texi (Version Info): Add arg to emacs-version.
- (Lisp History): Change xref to CL manual.
-
-2004-03-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * minibuf.texi (Completion Commands): Add xref to Emacs manual
- for Partial Completion mode.
-
-2004-03-07 Thien-Thi Nguyen <ttn@gnu.org>
-
- * customize.texi: Fix typo. Remove eol whitespace.
-
-2004-03-04 Richard M. Stallman <rms@gnu.org>
-
- * 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 <lektu@terra.es>
-
- * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of
- rm, and ignore exit code.
-
-2004-02-27 Dan Nicolaescu <dann@ics.uci.edu>
-
- * display.texi (Defining Faces): Add description for min-colors.
- Update example.
-
-2004-02-23 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <matt@mundell.ukfsn.org> (tiny change)
-
- * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp.
-
-2004-02-21 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * lists.texi (Sets And Lists): Update description of delete-dups.
-
-2004-02-16 Jesper Harder <harder@ifa.au.dk> (tiny change)
-
- * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button.
-
-2004-02-16 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * 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 <rms@gnu.org>
-
- * 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 <matt@mundell.ukfsn.org> (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 <rms@gnu.org>
-
- * compile.texi (Compiler Errors): if-boundp feature applies to cond.
-
-2004-02-16 Jesper Harder <harder@ifa.au.dk> (tiny change)
-
- * processes.texi (Low-Level Network): Fix a typo.
-
-2004-02-12 Kim F. Storm <storm@cua.dk>
-
- * 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 <teirllm@auburn.edu>
-
- * tips.texi (Comment Tips): Document the new conventions for
- commenting out code.
-
-2004-02-07 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * positions.texi (Text Lines): Added missing end defun.
-
-2004-02-07 Kim F. Storm <storm@cua.dk>
-
- * positions.texi (Text Lines): Add line-number-at-pos.
-
-2004-02-06 John Paul Wallington <jpw@gnu.org>
-
- * display.texi (Button Properties, Button Buffer Commands):
- mouse-2 invokes button, not down-mouse-1.
-
-2004-02-04 Jason Rumney <jasonr@gnu.org>
-
- * makefile.w32-in: Sync with Makefile.in changes.
-
-2004-02-03 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * lists.texi (Sets And Lists): Add delete-dups.
-
-2004-01-15 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <storm@cua.dk>
-
- * 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 <jas@extundo.com>
-
- * hooks.texi (Standard Hooks): Add before-save-hook.
- * files.texi (Saving Buffers): Likewise.
-
-2004-01-03 Richard M. Stallman <rms@gnu.org>
-
- * frames.texi (Frames and Windows): Delete frame-root-window.
-
-2004-01-03 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <miles@gnu.org>
-
- * display.texi (Buttons): New section.
-
-2003-12-31 Andreas Schwab <schwab@suse.de>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <rms@gnu.org>
-
- * 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 <rost@mathematik.uni-bielefeld.de>
-
- * display.texi (Fringes): Fix typo "set-buffer-window".
-
-2003-12-24 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <storm@cua.dk>
-
- * 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 <storm@cua.dk>
-
- * 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 <larsh@math.ku.dk>
-
- * files.texi (File Attributes): Describe new parameter ID-FORMAT.
- * anti.texi (File Attributes): Describe removed parameter
- ID-FORMAT.
-
-2003-11-20 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * numbers.texi (Numeric Conversions): Not just `floor', but also
- `truncate', `ceiling' and `round' accept optional argument DIVISOR.
-
-2003-11-10 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * streams.texi (Output Streams): Clarify behavior of point for
- marker output streams.
-
-2003-11-04 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <teirllm@auburn.edu>
-
- * symbols.texi (Symbol Plists): Mention return value of `setplist'.
-
-2003-11-02 Jesper Harder <harder@ifa.au.dk> (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 <teirllm@auburn.edu>
-
- * 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 <handa@m17n.org>
-
- * display.texi (Fontsets): Fix texinfo usage.
-
-2003-10-25 Kenichi Handa <handa@m17n.org>
-
- * display.texi (Fontsets): Add description of the function
- set-fontset-font.
-
-2003-10-23 Luc Teirlinck <teirllm@auburn.edu>
-
- * 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 <schwab@suse.de>
-
- * 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 <teirllm@auburn.edu>
-
- * tips.texi (Documentation Tips): Document new behavior for face
- and variable hyperlinks in Help mode.
-
-2003-10-21 Luc Teirlinck <teirllm@auburn.edu>
-
- * objects.texi (Integer Type): Update for extra bit of integer range.
- (Character Type): Ditto.
-
-2003-10-16 Eli Zaretskii <eliz@gnu.org>
-
- * numbers.texi (Integer Basics): Add index entries for reading
- numbers in hex, octal, and binary.
-
-2003-10-16 Lute Kamstra <lute@gnu.org>
-
- * modes.texi (Mode Line Format): Mention force-mode-line-update's
- argument.
-
-2003-10-13 Luc Teirlinck <teirllm@auburn.edu>
-
- * windows.texi (Choosing Window): Fix typo.
- * edebug.texi (Edebug Execution Modes): Fix typo.
-
-2003-10-13 Richard M. Stallman <rms@gnu.org>
-
- * 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 <storm@cua.dk>
-
- * processes.texi (Network): Introduce make-network-process.
-
-2003-10-09 Luc Teirlinck <teirllm@auburn.edu>
-
- * tips.texi (Library Headers): Fix typo.
-
-2003-10-07 Juri Linkov <juri@jurta.org>
-
- * modes.texi (Imenu): Mention imenu-create-index-function's
- default value. Explain submenus better.
-
-2003-10-07 Lute Kamstra <lute@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * tips.texi (Coding Conventions): Mention naming conventions for
- hooks.
-
-2003-10-05 Luc Teirlinck <teirllm@auburn.edu>
-
- * loading.texi (Library Search): Correct default value of
- load-suffixes.
- (Named Features): Fix typo.
-
-2003-10-05 Richard M. Stallman <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * keymaps.texi (Remapping Commands): Fix typo.
-
-2003-09-23 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * processes.texi (Low-Level Network): Fix typo.
-
-2003-09-23 Kim F. Storm <storm@cua.dk>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <lute@gnu.org>
-
- * modes.texi (%-Constructs): Document new `%i' and `%I'
- constructs.
-
-2003-09-03 Peter Runestig <peter@runestig.com>
-
- * makefile.w32-in: New file.
-
-2003-08-29 Richard M. Stallman <rms@gnu.org>
-
- * display.texi (Overlay Properties): Clarify how priorities
- affect use of the properties.
-
-2003-08-19 Luc Teirlinck <teirllm@mail.auburn.edu>
-
- * 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 <jpw@gnu.org>
-
- * modes.texi (Emulating Mode Line): Subsection, not section.
-
-2003-08-13 Richard M. Stallman <rms@gnu.org>
-
- * 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 <jpw@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rost@math.ohio-state.edu>
-
- * abbrevs.texi (Abbrev Expansion): Use \s syntax in example.
-
-2003-07-22 Markus Rost <rost@math.ohio-state.edu>
-
- * internals.texi (Garbage Collection): Fix previous change.
-
-2003-07-22 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * 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 <rost@math.ohio-state.edu>
-
- * advice.texi (Activation of Advice): Note that ad-start-advice is
- turned on by default.
-
-2003-06-30 Richard M. Stallman <rms@gnu.org>
-
- * 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 <schwab@suse.de>
-
- * objects.texi (Symbol Type): Fix description of examples.
-
-2003-06-16 Andreas Schwab <schwab@suse.de>
-
- * hash.texi (Creating Hash): Fix description of :weakness.
-
-2003-06-13 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@gmx.net>
-
- * files.texi (Changing Files): copy-file copies file modes, too.
-
-2003-05-28 Richard M. Stallman <rms@gnu.org>
-
- * strings.texi (Creating Strings): Clarify split-string.
-
-2003-05-22 Stephen J. Turnbull <stephen@xemacs.org>
-
- * strings.texi (Creating Strings): Update split-string specification
- and examples.
-
-2003-05-19 Richard M. Stallman <rms@gnu.org>
-
- * elisp.texi: Correct invariant section names.
-
-2003-04-20 Richard M. Stallman <rms@gnu.org>
-
- * os.texi (Timers): Explain about timers and quitting.
-
-2003-04-19 Richard M. Stallman <rms@gnu.org>
-
- * 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 <rms@gnu.org>
-
- * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message.
-
-2003-04-08 Richard M. Stallman <rms@gnu.org>
-
- * files.texi (Kinds of Files): Correct return value of file-symlink-p.
-
-2003-02-13 Kim F. Storm <storm@cua.dk>
-
- * objects.texi (Character Type): New \s escape for space.
-
-2003-01-31 Joe Buehler <jhpb@draco.hekimian.com>
-
- * os.texi (System Environment): Added cygwin system-type.
-
-2003-01-25 Richard M. Stallman <rms@gnu.org>
-
- * keymaps.texi: Document that a symbol can act as a keymap.
-
-2003-01-13 Richard M. Stallman <rms@gnu.org>
-
- * text.texi (Changing Properties): Say string indices are origin-0.
-
- * positions.texi (Screen Lines) <compute-motion>:
- Correct order of elts in return value.
-
- * keymaps.texi (Changing Key Bindings) <define-key>: Mention
- how to define a default binding.
-
-2002-12-07 Markus Rost <rost@math.ohio-state.edu>
-
- * 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 <rost@math.ohio-state.edu>
-
- * variables.texi (File Local Variables): Fix typo.
-
-2002-10-23 Kai Gro\e,A_\e(Bjohann <kai.grossjohann@uni-duisburg.de>
-
- From Michael Albinus <Michael.Albinus@alcatel.de>.
-
- * 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 <jyavner@engineer.com>
-
- * variables.texi (File Local Variables): New function
- risky-local-variable-p.
-
-2002-09-15 Jonathan Yavner <jyavner@engineer.com>
-
- * functions.texi (Function safety): New node about unsafep.
-
-2002-08-05 Per Abrahamsen <abraham@dina.kvl.dk>
-
- * customize.texi (Splicing into Lists): Fixed example.
- Reported by Fabrice Bauzac <fabrice.bauzac@wanadoo.fr>
-
-2002-06-17 Juanma Barranquero <lektu@terra.es>
-
- * frames.texi (Display Feature Testing): Fix typo.
-
-2002-06-12 Andreas Schwab <schwab@suse.de>
-
- * frames.texi (Initial Parameters, Resources): Fix references to
- the Emacs manual.
-
-2002-05-13 Kim F. Storm <storm@cua.dk>
-
- * variables.texi (Intro to Buffer-Local): Updated warning and
- example relating to changing buffer inside let.
-
-2002-03-10 Jan Dj\e,Ad\e(Brv <jan.h.d@swipnet.se>
-
- * os.texi (Session Management): New node about X Session management.
-
-2002-01-18 Eli Zaretskii <eliz@is.elta.co.il>
-
- * 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 <eliz@is.elta.co.il>
-
- * elisp.texi: Change the category in @dircategory to "Emacs", to
- make it consistent with info/dir.
-
-2001-11-25 Miles Bader <miles@gnu.org>
-
- * text.texi (Fields): Describe new `limit' arg in
- field-beginning/field-end.
-
-2001-11-17 Eli Zaretskii <eliz@is.elta.co.il>
-
- * 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 <eliz@is.elta.co.il>
-
- * 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 <eliz@is.elta.co.il>
-
- * 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
\e,Am
\e(Bk <Pavel@Janik.cz>
-
- * tips.texi (Coding Conventions): Fix typo.
-
-2001-10-23 Gerd Moellmann <gerd@gnu.org>
-
- * Makefile.in (srcs): Add gpl.texi and doclicense.texi.
-
-2001-10-22 Eli Zaretskii <eliz@is.elta.co.il>
-
- * 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 <gerd@gnu.org>
-
- * (Version 21.1 released.)
-
-2001-10-19 Miles Bader <miles@gnu.org>
-
- * positions.texi (Text Lines): Describe behavior of
- `beginning-of-line'/`end-of-line' in the presence of field properties.
-
-2001-10-17 Gerd Moellmann <gerd@gnu.org>
-
- * 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 <eliz@is.elta.co.il>
-
- * files.texi (File Name Completion): Document the significance of
- a trailing slash in elements of completion-ignored-extensions.
-
-2001-10-06 Miles Bader <miles@gnu.org>
-
- * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'.
-
-2001-10-04 Gerd Moellmann <gerd@gnu.org>
-
- * variables.texi (Variable Aliases): New node.
-
-2001-10-04 Gerd Moellmann <gerd@gnu.org>
-
- * Branch for 21.1.
-
-2001-10-02 Miles Bader <miles@gnu.org>
-
- * 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 <eliz@is.elta.co.il>
-
- * frames.texi (Finding All Frames): Document that next-frame and
- previous-frame are local to current terminal.
-
-2001-09-26 Eli Zaretskii <eliz@is.elta.co.il>
-
- * keymaps.texi (Creating Keymaps): Fix the description of the
- result of make-keymap.
-
-2001-09-23 Eli Zaretskii <eliz@is.elta.co.il>
-
- * 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 <eliz@is.elta.co.il>
-
- * strings.texi (String Conversion) <string-to-number>: 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) <where-is-internal>: The
- argument keymap can be a list.
-
- * nonascii.texi (User-Chosen Coding Systems)
- <select-safe-coding-system>: 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) <message>: Document
- message-truncate-lines.
- (Glyphs): Document that the glyph table is unused on windowed
- displays.
-
- * help.texi (Describing Characters) <single-key-description>:
- Document the new argument no-angles.
- (Accessing Documentation) <documentation-property>: Document that
- a non-string property is evaluated.
- <documentation>: 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 <wl@gnu.org>
-
- * 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 <gerd@gnu.org>
-
- * display.texi (Conditional Display): Adjust to API change.
-
- * configure: New file.
-
-2001-07-30 Gerd Moellmann <gerd@gnu.org>
-
- * commands.texi (Repeat Events): Add description of
- double-click-fuzz.
-
-2001-05-08 Stefan Monnier <monnier@cs.yale.edu>
-
- * 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 <gerd@gnu.org>
-
- * Makefile.in (install): Use install-info command line options
- like in Emacs' Makefile.in.
-
-2000-12-09 Miles Bader <miles@gnu.org>
-
- * windows.texi (Window Start): Update documentation for
- `pos-visible-in-window-p'.
-
-2000-11-12 Stefan Monnier <monnier@cs.yale.edu>
-
- * lists.texi (Building Lists): Add footnote to explain how to add
- to the end of a list.
-
-2000-10-25 Gerd Moellmann <gerd@gnu.org>
-
- * files.texi (Visiting Functions): Typos.
-
-2000-10-25 Kenichi Handa <handa@etl.go.jp>
-
- * 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 <miles@lsi.nec.co.jp>
-
- * display.texi (Defining Faces): Document `graphic' display type
- in face specs.
-
-2000-10-18 Kai Grossjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE>
-
- * 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 <gerd@gnu.org>
-
- * display.texi (Other Image Types): Add description of :foreground
- and :background properties of mono PBM images.
-
-2000-08-17 Werner LEMBERG <wl@gnu.org>
-
- * .cvsignore: New file.
-
-2000-01-05 Gerd Moellmann <gerd@gnu.org>
-
- * tindex.pl: New script.
-
-1999-12-03 Dave Love <fx@gnu.org>
-
- * Makefile.in (MAKEINFO): New parameter.
-
-1999-09-17 Richard Stallman <rms@gnu.org>
-
- * Makefile.in (srcs): Add hash.texi.
- (VERSION): Update to 20.6.
-
-1999-09-13 Richard Stallman <rms@gnu.org>
-
- * Makefile.in (index.texi): If cannot make a symlink, make a hard link.
-
-1998-08-29 Karl Heuer <kwzh@gnu.org>
-
- * 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 <rms@psilocin.ai.mit.edu>
-
- * Makefile (INSTALL_INFO): New variable.
- (install): Run install-info.
-
-1998-05-09 Richard Stallman <rms@psilocin.ai.mit.edu>
-
- * Makefile (elisp.dvi): Add missing backslash.
-
-1998-05-02 Richard Stallman <rms@psilocin.gnu.org>
-
- * 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 <rms@psilocin.gnu.org>
-
- * Makefile (srcs): Add nonascii.texi and customize.texi.
- (dist): Start by deleting `temp'.
-
-1998-02-17 Richard Stallman <rms@psilocin.gnu.org>
-
- * 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 <rms@psilocin.gnu.org>
-
- * Makefile (SHELL): Defined.
-
-1998-01-27 Richard Stallman <rms@psilocin.gnu.org>
-
- * Makefile (elisp.tps): New target.
- (elisp.dvi): Depend on elisp.tps.
-
-Wed Apr 3 15:24:25 1996 Karl Heuer <kwzh@gnu.ai.mit.edu>
-
- * 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 <rms@mole.gnu.ai.mit.edu>
-
- * Makefile (VERSION): Update version number.
- (maintainer-clean): Renamed from realclean.
-
-Wed Jun 7 17:04:59 1995 Karl Heuer <kwzh@nutrimat.gnu.ai.mit.edu>
-
- * 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
+++ /dev/null
-# Makefile for the GNU Emacs Lisp Reference Manual.
-
-# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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.
-
-# Standard configure variables.
-srcdir = @srcdir@
-
-# Tell make where to find source files; this is needed for the makefiles.
-VPATH=@srcdir@
-
-infodir = ../info
-usermanualdir = $(srcdir)/../man
-
-TEXI2DVI = texi2dvi
-SHELL = /bin/sh
-INSTALL_INFO = install-info
-MAKEINFO = makeinfo --force
-
-# The name of the manual:
-VERSION=2.9
-manual = elisp-manual-21-$(VERSION)
-
-# List of all the texinfo files in the manual:
-
-srcs = \
- $(srcdir)/abbrevs.texi \
- $(srcdir)/advice.texi \
- $(srcdir)/anti.texi \
- $(srcdir)/back.texi \
- $(srcdir)/backups.texi \
- $(srcdir)/buffers.texi \
- $(srcdir)/commands.texi \
- $(srcdir)/compile.texi \
- $(srcdir)/control.texi \
- $(srcdir)/customize.texi \
- $(srcdir)/debugging.texi \
- $(srcdir)/display.texi \
- $(srcdir)/edebug.texi \
- $(srcdir)/elisp.texi \
- $(srcdir)/errors.texi \
- $(srcdir)/eval.texi \
- $(srcdir)/files.texi \
- $(srcdir)/frames.texi \
- $(srcdir)/functions.texi \
- $(srcdir)/hash.texi \
- $(srcdir)/help.texi \
- $(srcdir)/hooks.texi \
- $(srcdir)/internals.texi \
- $(srcdir)/intro.texi \
- $(srcdir)/keymaps.texi \
- $(srcdir)/lists.texi \
- $(srcdir)/loading.texi \
- $(srcdir)/locals.texi \
- $(srcdir)/macros.texi \
- $(srcdir)/maps.texi \
- $(srcdir)/markers.texi \
- $(srcdir)/minibuf.texi \
- $(srcdir)/modes.texi \
- $(srcdir)/nonascii.texi \
- $(srcdir)/numbers.texi \
- $(srcdir)/objects.texi \
- $(srcdir)/os.texi \
- $(srcdir)/positions.texi \
- $(srcdir)/processes.texi \
- $(srcdir)/searching.texi \
- $(srcdir)/sequences.texi \
- $(srcdir)/streams.texi \
- $(srcdir)/strings.texi \
- $(srcdir)/symbols.texi \
- $(srcdir)/syntax.texi \
- $(srcdir)/text.texi \
- $(srcdir)/tips.texi \
- $(srcdir)/variables.texi \
- $(srcdir)/windows.texi \
- $(srcdir)/index.texi \
- $(srcdir)/gpl.texi \
- $(srcdir)/doclicense.texi
-
-
-.PHONY: clean
-
-# The info file is named `elisp'.
-info: $(infodir)/elisp
-
-$(infodir)/elisp: $(srcs)
- cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp
-
-elisp.dvi: $(srcs)
- $(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/elisp.texi
-
-# This is for use in a separate distro of the Emacs Lisp manual.
-install: elisp
- $(srcdir)/mkinstalldirs $(infodir)
- cp elisp elisp-[1-9] elisp-[1-9][0-9] $(infodir)
- ${INSTALL_INFO} --info-dir=${infodir} ${infodir}/elisp
-
-# This is for use in a separate distro of the Emacs Lisp manual.
-elisp: $(srcs)
- $(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi
-
-clean:
- rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
- *.vr *.vrs *.pg *.pgs *.ky *.kys
- rm -f make.out core
-
-distclean: clean
-
-maintainer-clean: clean
- rm -f elisp.dvi elisp.oaux
- cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9]
-
-dist: $(infodir)/elisp elisp.dvi
- -rm -rf temp
- -mkdir temp
- -mkdir temp/$(manual)
- -ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \
- $(srcdir)/Makefile.in $(srcs) \
- $(srcdir)/../man/texinfo.tex \
- elisp.dvi elisp.aux elisp.??s \
- $(infodir)/elisp $(infodir)/elisp-[1-9] $(infodir)/elisp-[1-9][0-9] \
- temp/$(manual)
- -(cd temp/$(manual); rm -f mkinstalldirs)
- cp $(srcdir)/mkinstalldirs temp/$(manual)
- (cd temp/$(manual); rm -f *~)
- (cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
- -rm -rf temp
+++ /dev/null
-Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
- Free Software Foundation, Inc.
-See the end of the file for license conditions.
-
-
-README for Edition 2.9 of the Emacs Lisp Reference Manual.
-
-* This directory contains the texinfo source files for the Reference
-Manual, make-permuted-index, and the latest version of texinfo.tex,
-which handles forms that cannot be handled by the older versions of
-texinfo.tex.
-
-* Report Lisp Manual bugs to bug-lisp-manual@gnu.org. We don't read
-these bug reports until it's time for a new edition. To report other
-Emacs bugs, use bug-gnu-emacs@gnu.org. To ask questions, use the
-newsgroup gnu.emacs.help.
-
-* The Emacs Lisp Reference Manual is quite large. It totals around
-1100 pages in smallbook format; the info files total over
-2.5 megabytes.
-
-* You can format this manual either for Info or for printing hardcopy
-using TeX.
-
-* You can buy nicely printed copies from the Free Software Foundation.
-For info, send mail to gnu@gnu.org or phone 617-542-5942. Buying a
-manual from the Free Software Foundation helps support our GNU
-development work.
-
-** This distribution contains a Makefile that you can use with GNU Make.
-Otherwise, here are detailed instructions:
-
-** HARDCOPY: A copy of the version of `texinfo.tex' that formats this
-manual is included in this distribution.
-
-The master file for formatting this manual for Tex is called
-`elisp.texi'. It contains @include commands to include all the
-chapters that make up the manual. In addition, `elisp.texi' has
-the title page in a new format designed by Karl Berry, using the
-@titlespec command.
-
-To create a DVI file with a sorted index, execute the following
-commands in the shell:
-
-% ./configure
-% make index.texi
-% make elisp.dvi
-
-*** To create a DVI file with a permuted index, you may experiment
-with `make-permuted-index'.
-
-** To make an Info file, you need to install Texinfo, then run
-`./configure' and `make info'. To install the Info files, run
-`make install'.
-
-\f
-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.
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/abbrevs
-@node Abbrevs, Processes, Syntax Tables, Top
-@chapter Abbrevs and Abbrev Expansion
-@cindex abbrev
-@c @cindex abbrev table Redundant with "abbrev".
-
- An abbreviation or @dfn{abbrev} is a string of characters that may be
-expanded to a longer string. The user can insert the abbrev string and
-find it replaced automatically with the expansion of the abbrev. This
-saves typing.
-
- The set of abbrevs currently in effect is recorded in an @dfn{abbrev
-table}. Each buffer has a local abbrev table, but normally all buffers
-in the same major mode share one abbrev table. There is also a global
-abbrev table. Normally both are used.
-
- An abbrev table is represented as an obarray containing a symbol for
-each abbreviation. The symbol's name is the abbreviation; its value
-is the expansion; its function definition is the hook function to do
-the expansion (@pxref{Defining Abbrevs}); its property list cell
-typically contains the use count, the number of times the abbreviation
-has been expanded. Alternatively, the use count is on the
-@code{count} property and the system-abbrev flag is on the
-@code{system-type} property. Abbrevs with a non-@code{nil}
-@code{system-type} property are called ``system'' abbrevs. They are
-usually defined by modes or packages, instead of by the user, and are
-treated specially in certain respects.
-
-Because the symbols used for abbrevs are not interned in the usual
-obarray, they will never appear as the result of reading a Lisp
-expression; in fact, normally they are never used except by the code
-that handles abbrevs. Therefore, it is safe to use them in an
-extremely nonstandard way. @xref{Creating Symbols}.
-
- For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
-Mode, emacs, The GNU Emacs Manual}.
-
-@menu
-* Abbrev Mode:: Setting up Emacs for abbreviation.
-* Tables: Abbrev Tables. Creating and working with abbrev tables.
-* Defining Abbrevs:: Specifying abbreviations and their expansions.
-* Files: Abbrev Files. Saving abbrevs in files.
-* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
-* Standard Abbrev Tables:: Abbrev tables used by various major modes.
-@end menu
-
-@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
-@comment node-name, next, previous, up
-@section Setting Up Abbrev Mode
-
- Abbrev mode is a minor mode controlled by the value of the variable
-@code{abbrev-mode}.
-
-@defvar abbrev-mode
-A non-@code{nil} value of this variable turns on the automatic expansion
-of abbrevs when their abbreviations are inserted into a buffer.
-If the value is @code{nil}, abbrevs may be defined, but they are not
-expanded automatically.
-
-This variable automatically becomes buffer-local when set in any fashion.
-@end defvar
-
-@defvar default-abbrev-mode
-This is the value of @code{abbrev-mode} for buffers that do not override it.
-This is the same as @code{(default-value 'abbrev-mode)}.
-@end defvar
-
-@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
-@section Abbrev Tables
-
- This section describes how to create and manipulate abbrev tables.
-
-@defun make-abbrev-table
-This function creates and returns a new, empty abbrev table---an obarray
-containing no symbols. It is a vector filled with zeros.
-@end defun
-
-@defun clear-abbrev-table table
-This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty. It always returns @code{nil}.
-@end defun
-
-@defun copy-abbrev-table table
-This function returns a copy of abbrev table @var{table}---a new
-abbrev table that contains the same abbrev definitions. The only
-difference between @var{table} and the returned copy is that this
-function sets the property lists of all copied abbrevs to 0.
-@end defun
-
-@defun define-abbrev-table tabname definitions
-This function defines @var{tabname} (a symbol) as an abbrev table
-name, i.e., as a variable whose value is an abbrev table. It defines
-abbrevs in the table according to @var{definitions}, a list of
-elements of the form @code{(@var{abbrevname} @var{expansion}
-@var{hook} @var{usecount} @var{system-flag})}. If an element of
-@var{definitions} has length less than five, omitted elements default
-to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent
-to zero. The return value is always @code{nil}.
-
-If this function is called more than once for the same @var{tabname},
-subsequent calls add the definitions in @var{definitions} to
-@var{tabname}, rather than overriding the entire original contents.
-(A subsequent call only overrides abbrevs explicitly redefined or
-undefined in @var{definitions}.)
-@end defun
-
-@defvar abbrev-table-name-list
-This is a list of symbols whose values are abbrev tables.
-@code{define-abbrev-table} adds the new abbrev table name to this list.
-@end defvar
-
-@defun insert-abbrev-table-description name &optional human
-This function inserts before point a description of the abbrev table
-named @var{name}. The argument @var{name} is a symbol whose value is an
-abbrev table. The return value is always @code{nil}.
-
-If @var{human} is non-@code{nil}, the description is human-oriented.
-System abbrevs are listed and identified as such. Otherwise the
-description is a Lisp expression---a call to @code{define-abbrev-table}
-that would define @var{name} as it is currently defined, but without
-the system abbrevs. (The mode or package using @var{name} is supposed
-to add these to @var{name} separately.)
-@end defun
-
-@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
-@comment node-name, next, previous, up
-@section Defining Abbrevs
- @code{define-abbrev} is the low-level basic function for defining an
-abbrev in a specified abbrev table. When major modes predefine standard
-abbrevs, they should call @code{define-abbrev} and specify @code{t} for
-@var{system-flag}. Be aware that any saved non-``system'' abbrevs are
-restored at startup, i.e. before some major modes are loaded. Major modes
-should therefore not assume that when they are first loaded their abbrev
-tables are empty.
-
-@defun define-abbrev table name expansion &optional hook count system-flag
-This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}. The return value is
-@var{name}.
-
-The value of @var{count}, if specified, initializes the abbrev's
-usage-count. If @var{count} is not specified or @code{nil}, the use
-count is initialized to zero.
-
-The argument @var{name} should be a string. The argument
-@var{expansion} is normally the desired expansion (a string), or
-@code{nil} to undefine the abbrev. If it is anything but a string or
-@code{nil}, then the abbreviation ``expands'' solely by running
-@var{hook}.
-
-The argument @var{hook} is a function or @code{nil}. If @var{hook} is
-non-@code{nil}, then it is called with no arguments after the abbrev is
-replaced with @var{expansion}; point is located at the end of
-@var{expansion} when @var{hook} is called.
-
-@cindex @code{no-self-insert} property
-If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
-property is non-@code{nil}, @var{hook} can explicitly control whether
-to insert the self-inserting input character that triggered the
-expansion. If @var{hook} returns non-@code{nil} in this case, that
-inhibits insertion of the character. By contrast, if @var{hook}
-returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
-if expansion had not really occurred.
-
-If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
-``system'' abbrev with the @code{system-type} property. Unless
-@var{system-flag} has the value @code{force}, a ``system'' abbrev will
-not overwrite an existing definition for a non-``system'' abbrev of the
-same name.
-
-Normally the function @code{define-abbrev} sets the variable
-@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
-(This is so that some commands will offer to save the abbrevs.) It
-does not do this for a ``system'' abbrev, since those won't be saved
-anyway.
-@end defun
-
-@defopt only-global-abbrevs
-If this variable is non-@code{nil}, it means that the user plans to use
-global abbrevs only. This tells the commands that define mode-specific
-abbrevs to define global ones instead. This variable does not alter the
-behavior of the functions in this section; it is examined by their
-callers.
-@end defopt
-
-@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
-@section Saving Abbrevs in Files
-
- A file of saved abbrev definitions is actually a file of Lisp code.
-The abbrevs are saved in the form of a Lisp program to define the same
-abbrev tables with the same contents. Therefore, you can load the file
-with @code{load} (@pxref{How Programs Do Loading}). However, the
-function @code{quietly-read-abbrev-file} is provided as a more
-convenient interface.
-
- User-level facilities such as @code{save-some-buffers} can save
-abbrevs in a file automatically, under the control of variables
-described here.
-
-@defopt abbrev-file-name
-This is the default file name for reading and saving abbrevs.
-@end defopt
-
-@defun quietly-read-abbrev-file &optional filename
-This function reads abbrev definitions from a file named @var{filename},
-previously written with @code{write-abbrev-file}. If @var{filename} is
-omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
-used. @code{save-abbrevs} is set to @code{t} so that changes will be
-saved.
-
-This function does not display any messages. It returns @code{nil}.
-@end defun
-
-@defopt save-abbrevs
-A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
-offer the user to save abbrevs when files are saved. If the value is
-@code{silently}, Emacs saves the abbrevs without asking the user.
-@code{abbrev-file-name} specifies the file to save the abbrevs in.
-@end defopt
-
-@defvar abbrevs-changed
-This variable is set non-@code{nil} by defining or altering any
-abbrevs (except ``system'' abbrevs). This serves as a flag for
-various Emacs commands to offer to save your abbrevs.
-@end defvar
-
-@deffn Command write-abbrev-file &optional filename
-Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
-tables listed in @code{abbrev-table-name-list}, in the file
-@var{filename}, in the form of a Lisp program that when loaded will
-define the same abbrevs. If @var{filename} is @code{nil} or omitted,
-@code{abbrev-file-name} is used. This function returns @code{nil}.
-@end deffn
-
-@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
-@comment node-name, next, previous, up
-@section Looking Up and Expanding Abbreviations
-
- Abbrevs are usually expanded by certain interactive commands,
-including @code{self-insert-command}. This section describes the
-subroutines used in writing such commands, as well as the variables they
-use for communication.
-
-@defun abbrev-symbol abbrev &optional table
-This function returns the symbol representing the abbrev named
-@var{abbrev}. The value returned is @code{nil} if that abbrev is not
-defined. The optional second argument @var{table} is the abbrev table
-to look it up in. If @var{table} is @code{nil}, this function tries
-first the current buffer's local abbrev table, and second the global
-abbrev table.
-@end defun
-
-@defun abbrev-expansion abbrev &optional table
-This function returns the string that @var{abbrev} would expand into (as
-defined by the abbrev tables used for the current buffer). If
-@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
-The optional argument @var{table} specifies the abbrev table to use,
-as in @code{abbrev-symbol}.
-@end defun
-
-@deffn Command expand-abbrev
-This command expands the abbrev before point, if any. If point does not
-follow an abbrev, this command does nothing. The command returns the
-abbrev symbol if it did expansion, @code{nil} otherwise.
-
-If the abbrev symbol has a hook function which is a symbol whose
-@code{no-self-insert} property is non-@code{nil}, and if the hook
-function returns @code{nil} as its value, then @code{expand-abbrev}
-returns @code{nil} even though expansion did occur.
-@end deffn
-
-@deffn Command abbrev-prefix-mark &optional arg
-This command marks the current location of point as the beginning of
-an abbrev. The next call to @code{expand-abbrev} will use the text
-from here to point (where it is then) as the abbrev to expand, rather
-than using the previous word as usual.
-
-First, this command expands any abbrev before point, unless @var{arg}
-is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.)
-Then it inserts a hyphen before point, to indicate the start of the
-next abbrev to be expanded. The actual expansion removes the hyphen.
-@end deffn
-
-@defopt abbrev-all-caps
-When this is set non-@code{nil}, an abbrev entered entirely in upper
-case is expanded using all upper case. Otherwise, an abbrev entered
-entirely in upper case is expanded by capitalizing each word of the
-expansion.
-@end defopt
-
-@defvar abbrev-start-location
-The value of this variable is a buffer position (an integer or a marker)
-for @code{expand-abbrev} to use as the start of the next abbrev to be
-expanded. The value can also be @code{nil}, which means to use the
-word before point instead. @code{abbrev-start-location} is set to
-@code{nil} each time @code{expand-abbrev} is called. This variable is
-also set by @code{abbrev-prefix-mark}.
-@end defvar
-
-@defvar abbrev-start-location-buffer
-The value of this variable is the buffer for which
-@code{abbrev-start-location} has been set. Trying to expand an abbrev
-in any other buffer clears @code{abbrev-start-location}. This variable
-is set by @code{abbrev-prefix-mark}.
-@end defvar
-
-@defvar last-abbrev
-This is the @code{abbrev-symbol} of the most recent abbrev expanded. This
-information is left by @code{expand-abbrev} for the sake of the
-@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
-Abbrevs, emacs, The GNU Emacs Manual}).
-@end defvar
-
-@defvar last-abbrev-location
-This is the location of the most recent abbrev expanded. This contains
-information left by @code{expand-abbrev} for the sake of the
-@code{unexpand-abbrev} command.
-@end defvar
-
-@defvar last-abbrev-text
-This is the exact expansion text of the most recent abbrev expanded,
-after case conversion (if any). Its value is @code{nil} if the abbrev
-has already been unexpanded. This contains information left by
-@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
-@end defvar
-
-@c Emacs 19 feature
-@defvar pre-abbrev-expand-hook
-This is a normal hook whose functions are executed, in sequence, just
-before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
-hook, the hook functions receive no arguments. However, they can find
-the abbrev to be expanded by looking in the buffer before point.
-Running the hook is the first thing that @code{expand-abbrev} does, and
-so a hook function can be used to change the current abbrev table before
-abbrev lookup happens. (Although you have to do this carefully. See
-the example below.)
-@end defvar
-
- The following sample code shows a simple use of
-@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a
-mode for editing certain files in which lines that start with @samp{#}
-are comments. You want to use Text mode abbrevs for those lines. The
-regular local abbrev table, @code{foo-mode-abbrev-table} is
-appropriate for all other lines. Then you can put the following code
-in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the
-definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
-
-@smallexample
-(defun foo-mode-pre-abbrev-expand ()
- (when (save-excursion (forward-line 0) (eq (char-after) ?#))
- (let ((local-abbrev-table text-mode-abbrev-table)
- ;; Avoid infinite loop.
- (pre-abbrev-expand-hook nil))
- (expand-abbrev))
- ;; We have already called `expand-abbrev' in this hook.
- ;; Hence we want the "actual" call following this hook to be a no-op.
- (setq abbrev-start-location (point-max)
- abbrev-start-location-buffer (current-buffer))))
-
-(add-hook 'foo-mode-hook
- #'(lambda ()
- (add-hook 'pre-abbrev-expand-hook
- 'foo-mode-pre-abbrev-expand
- nil t)))
-@end smallexample
-
-Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
-without doing anything for lines not starting with @samp{#}. Hence
-abbrevs expand normally using @code{foo-mode-abbrev-table} as local
-abbrev table for such lines.
-
-@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs
-@comment node-name, next, previous, up
-@section Standard Abbrev Tables
-
- Here we list the variables that hold the abbrev tables for the
-preloaded major modes of Emacs.
-
-@defvar global-abbrev-table
-This is the abbrev table for mode-independent abbrevs. The abbrevs
-defined in it apply to all buffers. Each buffer may also have a local
-abbrev table, whose abbrev definitions take precedence over those in the
-global table.
-@end defvar
-
-@defvar local-abbrev-table
-The value of this buffer-local variable is the (mode-specific)
-abbreviation table of the current buffer.
-@end defvar
-
-@defvar fundamental-mode-abbrev-table
-This is the local abbrev table used in Fundamental mode; in other words,
-it is the local abbrev table in all buffers in Fundamental mode.
-@end defvar
-
-@defvar text-mode-abbrev-table
-This is the local abbrev table used in Text mode.
-@end defvar
-
-@defvar lisp-mode-abbrev-table
-This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
-@end defvar
-
-@ignore
- arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/advising
-@node Advising Functions, Debugging, Byte Compilation, Top
-@chapter Advising Emacs Lisp Functions
-@cindex advising functions
-
- The @dfn{advice} feature lets you add to the existing definition of
-a function, by @dfn{advising the function}. This is a cleaner method
-for a library to customize functions defined within Emacs---cleaner
-than redefining the whole function.
-
-@cindex piece of advice
- Each function can have multiple @dfn{pieces of advice}, separately
-defined. Each defined piece of advice can be @dfn{enabled} or
-@dfn{disabled} explicitly. All the enabled pieces of advice for any given
-function actually take effect when you @dfn{activate} advice for that
-function, or when you define or redefine the function. Note that
-enabling a piece of advice and activating advice for a function
-are not the same thing.
-
- @strong{Usage Note:} Advice is useful for altering the behavior of
-existing calls to an existing function. If you want the new behavior
-for new calls, or for key bindings, you should define a new function
-(or a new command) which uses the existing function.
-
- @strong{Usage note:} Advising a function can cause confusion in
-debugging, since people who debug calls to the original function may
-not notice that it has been modified with advice. Therefore, if you
-have the possibility to change the code of that function (or ask
-someone to do so) to run a hook, please solve the problem that way.
-Advice should be reserved for the cases where you cannot get the
-function changed.
-
- In particular, this means that a file in Emacs should not put advice
-on a function in Emacs. There are currently a few exceptions to this
-convention, but we aim to correct them.
-
-@menu
-* 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.
-@end menu
-
-@node Simple Advice
-@section A Simple Advice Example
-
- The command @code{next-line} moves point down vertically one or more
-lines; it is the standard binding of @kbd{C-n}. When used on the last
-line of the buffer, this command inserts a newline to create a line to
-move to if @code{next-line-add-newlines} is non-@code{nil} (its default
-is @code{nil}.)
-
- Suppose you wanted to add a similar feature to @code{previous-line},
-which would insert a new line at the beginning of the buffer for the
-command to move to (when @code{next-line-add-newlines} is
-non-@code{nil}). How could you do this?
-
- You could do it by redefining the whole function, but that is not
-modular. The advice feature provides a cleaner alternative: you can
-effectively add your code to the existing function definition, without
-actually changing or even seeing that definition. Here is how to do
-this:
-
-@example
-(defadvice previous-line (before next-line-at-end
- (&optional arg try-vscroll))
- "Insert an empty line when moving up from the top line."
- (if (and next-line-add-newlines (= arg 1)
- (save-excursion (beginning-of-line) (bobp)))
- (progn
- (beginning-of-line)
- (newline))))
-@end example
-
- This expression defines a @dfn{piece of advice} for the function
-@code{previous-line}. This piece of advice is named
-@code{next-line-at-end}, and the symbol @code{before} says that it is
-@dfn{before-advice} which should run before the regular definition of
-@code{previous-line}. @code{(&optional arg try-vscroll)} specifies
-how the advice code can refer to the function's arguments.
-
- When this piece of advice runs, it creates an additional line, in the
-situation where that is appropriate, but does not move point to that
-line. This is the correct way to write the advice, because the normal
-definition will run afterward and will move back to the newly inserted
-line.
-
- Defining the advice doesn't immediately change the function
-@code{previous-line}. That happens when you @dfn{activate} the advice,
-like this:
-
-@example
-(ad-activate 'previous-line)
-@end example
-
-@noindent
-This is what actually begins to use the advice that has been defined so
-far for the function @code{previous-line}. Henceforth, whenever that
-function is run, whether invoked by the user with @kbd{C-p} or
-@kbd{M-x}, or called from Lisp, it runs the advice first, and its
-regular definition second.
-
- This example illustrates before-advice, which is one @dfn{class} of
-advice: it runs before the function's base definition. There are two
-other advice classes: @dfn{after-advice}, which runs after the base
-definition, and @dfn{around-advice}, which lets you specify an
-expression to wrap around the invocation of the base definition.
-
-@node Defining Advice
-@section Defining Advice
-@cindex defining advice
-@cindex advice, defining
-
- To define a piece of advice, use the macro @code{defadvice}. A call
-to @code{defadvice} has the following syntax, which is based on the
-syntax of @code{defun} and @code{defmacro}, but adds more:
-
-@findex defadvice
-@example
-(defadvice @var{function} (@var{class} @var{name}
- @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]}
- @var{flags}...)
- @r{[}@var{documentation-string}@r{]}
- @r{[}@var{interactive-form}@r{]}
- @var{body-forms}...)
-@end example
-
-@noindent
-Here, @var{function} is the name of the function (or macro or special
-form) to be advised. From now on, we will write just ``function'' when
-describing the entity being advised, but this always includes macros and
-special forms.
-
- In place of the argument list in an ordinary definition, an advice
-definition calls for several different pieces of information.
-
-@cindex class of advice
-@cindex before-advice
-@cindex after-advice
-@cindex around-advice
-@var{class} specifies the @dfn{class} of the advice---one of @code{before},
-@code{after}, or @code{around}. Before-advice runs before the function
-itself; after-advice runs after the function itself; around-advice is
-wrapped around the execution of the function itself. After-advice and
-around-advice can override the return value by setting
-@code{ad-return-value}.
-
-@defvar ad-return-value
-While advice is executing, after the function's original definition has
-been executed, this variable holds its return value, which will
-ultimately be returned to the caller after finishing all the advice.
-After-advice and around-advice can arrange to return some other value
-by storing it in this variable.
-@end defvar
-
-The argument @var{name} is the name of the advice, a non-@code{nil}
-symbol. The advice name uniquely identifies one piece of advice, within all
-the pieces of advice in a particular class for a particular
-@var{function}. The name allows you to refer to the piece of
-advice---to redefine it, or to enable or disable it.
-
-The optional @var{position} specifies where, in the current list of
-advice of the specified @var{class}, this new advice should be placed.
-It should be either @code{first}, @code{last} or a number that specifies
-a zero-based position (@code{first} is equivalent to 0). If no position
-is specified, the default is @code{first}. Position values outside the
-range of existing positions in this class are mapped to the beginning or
-the end of the range, whichever is closer. The @var{position} value is
-ignored when redefining an existing piece of advice.
-
-The optional @var{arglist} can be used to define the argument list for
-the sake of advice. This becomes the argument list of the combined
-definition that is generated in order to run the advice (@pxref{Combined
-Definition}). Therefore, the advice expressions can use the argument
-variables in this list to access argument values.
-
-The argument list used in advice need not be the same as the argument
-list used in the original function, but must be compatible with it, so
-that it can handle the ways the function is actually called. If two
-pieces of advice for a function both specify an argument list, they must
-specify the same argument list.
-
-@xref{Argument Access in Advice}, for more information about argument
-lists and advice, and a more flexible way for advice to access the
-arguments.
-
-The remaining elements, @var{flags}, are symbols that specify further
-information about how to use this piece of advice. Here are the valid
-symbols and their meanings:
-
-@table @code
-@item activate
-Activate the advice for @var{function} now. Changes in a function's
-advice always take effect the next time you activate advice for the
-function; this flag says to do so, for @var{function}, immediately after
-defining this piece of advice.
-
-@cindex forward advice
-This flag has no immediate effect if @var{function} itself is not defined yet (a
-situation known as @dfn{forward advice}), because it is impossible to
-activate an undefined function's advice. However, defining
-@var{function} will automatically activate its advice.
-
-@item protect
-Protect this piece of advice against non-local exits and errors in
-preceding code and advice. Protecting advice places it as a cleanup in
-an @code{unwind-protect} form, so that it will execute even if the
-previous code gets an error or uses @code{throw}. @xref{Cleanups}.
-
-@item compile
-Compile the combined definition that is used to run the advice. This
-flag is ignored unless @code{activate} is also specified.
-@xref{Combined Definition}.
-
-@item disable
-Initially disable this piece of advice, so that it will not be used
-unless subsequently explicitly enabled. @xref{Enabling Advice}.
-
-@item preactivate
-Activate advice for @var{function} when this @code{defadvice} is
-compiled or macroexpanded. This generates a compiled advised definition
-according to the current advice state, which will be used during
-activation if appropriate. @xref{Preactivation}.
-
-This is useful only if this @code{defadvice} is byte-compiled.
-@end table
-
-The optional @var{documentation-string} serves to document this piece of
-advice. When advice is active for @var{function}, the documentation for
-@var{function} (as returned by @code{documentation}) combines the
-documentation strings of all the advice for @var{function} with the
-documentation string of its original function definition.
-
-The optional @var{interactive-form} form can be supplied to change the
-interactive behavior of the original function. If more than one piece
-of advice has an @var{interactive-form}, then the first one (the one
-with the smallest position) found among all the advice takes precedence.
-
-The possibly empty list of @var{body-forms} specifies the body of the
-advice. The body of an advice can access or change the arguments, the
-return value, the binding environment, and perform any other kind of
-side effect.
-
-@strong{Warning:} When you advise a macro, keep in mind that macros are
-expanded when a program is compiled, not when a compiled program is run.
-All subroutines used by the advice need to be available when the byte
-compiler expands the macro.
-
-@deffn Command ad-unadvise function
-This command deletes the advice from @var{function}.
-@end deffn
-
-@deffn Command ad-unadvise-all
-This command deletes all pieces of advice from all functions.
-@end deffn
-
-@node Around-Advice
-@section Around-Advice
-
- Around-advice lets you ``wrap'' a Lisp expression ``around'' the
-original function definition. You specify where the original function
-definition should go by means of the special symbol @code{ad-do-it}.
-Where this symbol occurs inside the around-advice body, it is replaced
-with a @code{progn} containing the forms of the surrounded code. Here
-is an example:
-
-@example
-(defadvice foo (around foo-around)
- "Ignore case in `foo'."
- (let ((case-fold-search t))
- ad-do-it))
-@end example
-
-@noindent
-Its effect is to make sure that case is ignored in
-searches when the original definition of @code{foo} is run.
-
-@defvar ad-do-it
-This is not really a variable, rather a place-holder that looks like a
-variable. You use it in around-advice to specify the place to run the
-function's original definition and other ``earlier'' around-advice.
-@end defvar
-
-If the around-advice does not use @code{ad-do-it}, then it does not run
-the original function definition. This provides a way to override the
-original definition completely. (It also overrides lower-positioned
-pieces of around-advice).
-
-If the around-advice uses @code{ad-do-it} more than once, the original
-definition is run at each place. In this way, around-advice can execute
-the original definition (and lower-positioned pieces of around-advice)
-several times. Another way to do that is by using @code{ad-do-it}
-inside of a loop.
-
-@node Computed Advice
-@section Computed Advice
-
-The macro @code{defadvice} resembles @code{defun} in that the code for
-the advice, and all other information about it, are explicitly stated in
-the source code. You can also create advice whose details are computed,
-using the function @code{ad-add-advice}.
-
-@defun ad-add-advice function advice class position
-Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to
-@var{function} in class @var{class}. The argument @var{advice} has
-this form:
-
-@example
-(@var{name} @var{protected} @var{enabled} @var{definition})
-@end example
-
-Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is the expression that says what the advice should do. If @var{enabled}
-is @code{nil}, this piece of advice is initially disabled
-(@pxref{Enabling Advice}).
-
-If @var{function} already has one or more pieces of advice in the
-specified @var{class}, then @var{position} specifies where in the list
-to put the new piece of advice. The value of @var{position} can either
-be @code{first}, @code{last}, or a number (counting from 0 at the
-beginning of the list). Numbers outside the range are mapped to the
-beginning or the end of the range, whichever is closer. The
-@var{position} value is ignored when redefining an existing piece of
-advice.
-
-If @var{function} already has a piece of @var{advice} with the same
-name, then the position argument is ignored and the old advice is
-replaced with the new one.
-@end defun
-
-@node Activation of Advice
-@section Activation of Advice
-@cindex activating advice
-@cindex advice, activating
-
-By default, advice does not take effect when you define it---only when
-you @dfn{activate} advice for the function that was advised. However,
-the advice will be activated automatically if you define or redefine
-the function later. You can request the activation of advice for a
-function when you define the advice, by specifying the @code{activate}
-flag in the @code{defadvice}. But normally you activate the advice
-for a function by calling the function @code{ad-activate} or one of
-the other activation commands listed below.
-
-Separating the activation of advice from the act of defining it permits
-you to add several pieces of advice to one function efficiently, without
-redefining the function over and over as each advice is added. More
-importantly, it permits defining advice for a function before that
-function is actually defined.
-
-When a function's advice is first activated, the function's original
-definition is saved, and all enabled pieces of advice for that function
-are combined with the original definition to make a new definition.
-(Pieces of advice that are currently disabled are not used; see
-@ref{Enabling Advice}.) This definition is installed, and optionally
-byte-compiled as well, depending on conditions described below.
-
-In all of the commands to activate advice, if @var{compile} is
-@code{t} (or anything but @code{nil} or a negative number), the
-command also compiles the combined definition which implements the
-advice. If it is @code{nil} or a negative number, what happens
-depends on @code{ad-default-compilation-action} as described below.
-
-@deffn Command ad-activate function &optional compile
-This command activates all the advice defined for @var{function}.
-@end deffn
-
- Activating advice does nothing if @var{function}'s advice is already
-active. But if there is new advice, added since the previous time you
-activated advice for @var{function}, it activates the new advice.
-
-@deffn Command ad-deactivate function
-This command deactivates the advice for @var{function}.
-@cindex deactivating advice
-@c @cindex advice, deactivating "advice, activating" is just above
-@end deffn
-
-@deffn Command ad-update function &optional compile
-This command activates the advice for @var{function}
-if its advice is already activated. This is useful
-if you change the advice.
-@end deffn
-
-@deffn Command ad-activate-all &optional compile
-This command activates the advice for all functions.
-@end deffn
-
-@deffn Command ad-deactivate-all
-This command deactivates the advice for all functions.
-@end deffn
-
-@deffn Command ad-update-all &optional compile
-This command activates the advice for all functions
-whose advice is already activated. This is useful
-if you change the advice of some functions.
-@end deffn
-
-@deffn Command ad-activate-regexp regexp &optional compile
-This command activates all pieces of advice whose names match
-@var{regexp}. More precisely, it activates all advice for any function
-which has at least one piece of advice that matches @var{regexp}.
-@end deffn
-
-@deffn Command ad-deactivate-regexp regexp
-This command deactivates all pieces of advice whose names match
-@var{regexp}. More precisely, it deactivates all advice for any
-function which has at least one piece of advice that matches
-@var{regexp}.
-@end deffn
-
-@deffn Command ad-update-regexp regexp &optional compile
-This command activates pieces of advice whose names match @var{regexp},
-but only those for functions whose advice is already activated.
-@cindex reactivating advice
-
-Reactivating a function's advice is useful for putting into effect all
-the changes that have been made in its advice (including enabling and
-disabling specific pieces of advice; @pxref{Enabling Advice}) since the
-last time it was activated.
-@end deffn
-
-@deffn Command ad-start-advice
-Turn on automatic advice activation when a function is defined or
-redefined. This is the default mode.
-@end deffn
-
-@deffn Command ad-stop-advice
-Turn off automatic advice activation when a function is defined or
-redefined.
-@end deffn
-
-@defopt ad-default-compilation-action
-This variable controls whether to compile the combined definition
-that results from activating advice for a function.
-
-A value of @code{always} specifies to compile unconditionally.
-A value of @code{never} specifies never compile the advice.
-
-A value of @code{maybe} specifies to compile if the byte-compiler is
-already loaded. A value of @code{like-original} specifies to compile
-the advice if the original definition of the advised function is
-compiled or a built-in function.
-
-This variable takes effect only if the @var{compile} argument of
-@code{ad-activate} (or any of the above functions) did not force
-compilation.
-@end defopt
-
- If the advised definition was constructed during ``preactivation''
-(@pxref{Preactivation}), then that definition must already be compiled,
-because it was constructed during byte-compilation of the file that
-contained the @code{defadvice} with the @code{preactivate} flag.
-
-@node Enabling Advice
-@section Enabling and Disabling Advice
-@cindex enabling advice
-@cindex advice, enabling and disabling
-@cindex disabling advice
-
- Each piece of advice has a flag that says whether it is enabled or
-not. By enabling or disabling a piece of advice, you can turn it on
-and off without having to undefine and redefine it. For example, here is
-how to disable a particular piece of advice named @code{my-advice} for
-the function @code{foo}:
-
-@example
-(ad-disable-advice 'foo 'before 'my-advice)
-@end example
-
- This function by itself only changes the enable flag for a piece of
-advice. To make the change take effect in the advised definition, you
-must activate the advice for @code{foo} again:
-
-@example
-(ad-activate 'foo)
-@end example
-
-@deffn Command ad-disable-advice function class name
-This command disables the piece of advice named @var{name} in class
-@var{class} on @var{function}.
-@end deffn
-
-@deffn Command ad-enable-advice function class name
-This command enables the piece of advice named @var{name} in class
-@var{class} on @var{function}.
-@end deffn
-
- You can also disable many pieces of advice at once, for various
-functions, using a regular expression. As always, the changes take real
-effect only when you next reactivate advice for the functions in
-question.
-
-@deffn Command ad-disable-regexp regexp
-This command disables all pieces of advice whose names match
-@var{regexp}, in all classes, on all functions.
-@end deffn
-
-@deffn Command ad-enable-regexp regexp
-This command enables all pieces of advice whose names match
-@var{regexp}, in all classes, on all functions.
-@end deffn
-
-@node Preactivation
-@section Preactivation
-@cindex preactivating advice
-@cindex advice, preactivating
-
- Constructing a combined definition to execute advice is moderately
-expensive. When a library advises many functions, this can make loading
-the library slow. In that case, you can use @dfn{preactivation} to
-construct suitable combined definitions in advance.
-
- To use preactivation, specify the @code{preactivate} flag when you
-define the advice with @code{defadvice}. This @code{defadvice} call
-creates a combined definition which embodies this piece of advice
-(whether enabled or not) plus any other currently enabled advice for the
-same function, and the function's own definition. If the
-@code{defadvice} is compiled, that compiles the combined definition
-also.
-
- When the function's advice is subsequently activated, if the enabled
-advice for the function matches what was used to make this combined
-definition, then the existing combined definition is used, thus avoiding
-the need to construct one. Thus, preactivation never causes wrong
-results---but it may fail to do any good, if the enabled advice at the
-time of activation doesn't match what was used for preactivation.
-
- Here are some symptoms that can indicate that a preactivation did not
-work properly, because of a mismatch.
-
-@itemize @bullet
-@item
-Activation of the advised
-function takes longer than usual.
-@item
-The byte-compiler gets
-loaded while an advised function gets activated.
-@item
-@code{byte-compile} is included in the value of @code{features} even
-though you did not ever explicitly use the byte-compiler.
-@end itemize
-
-Compiled preactivated advice works properly even if the function itself
-is not defined until later; however, the function needs to be defined
-when you @emph{compile} the preactivated advice.
-
-There is no elegant way to find out why preactivated advice is not being
-used. What you can do is to trace the function
-@code{ad-cache-id-verification-code} (with the function
-@code{trace-function-background}) before the advised function's advice
-is activated. After activation, check the value returned by
-@code{ad-cache-id-verification-code} for that function: @code{verified}
-means that the preactivated advice was used, while other values give
-some information about why they were considered inappropriate.
-
- @strong{Warning:} There is one known case that can make preactivation
-fail, in that a preconstructed combined definition is used even though
-it fails to match the current state of advice. This can happen when two
-packages define different pieces of advice with the same name, in the
-same class, for the same function. But you should avoid that anyway.
-
-@node Argument Access in Advice
-@section Argument Access in Advice
-
- The simplest way to access the arguments of an advised function in the
-body of a piece of advice is to use the same names that the function
-definition uses. To do this, you need to know the names of the argument
-variables of the original function.
-
- While this simple method is sufficient in many cases, it has a
-disadvantage: it is not robust, because it hard-codes the argument names
-into the advice. If the definition of the original function changes,
-the advice might break.
-
- Another method is to specify an argument list in the advice itself.
-This avoids the need to know the original function definition's argument
-names, but it has a limitation: all the advice on any particular
-function must use the same argument list, because the argument list
-actually used for all the advice comes from the first piece of advice
-for that function.
-
- A more robust method is to use macros that are translated into the
-proper access forms at activation time, i.e., when constructing the
-advised definition. Access macros access actual arguments by position
-regardless of how these actual arguments get distributed onto the
-argument variables of a function. This is robust because in Emacs Lisp
-the meaning of an argument is strictly determined by its position in the
-argument list.
-
-@defmac ad-get-arg position
-This returns the actual argument that was supplied at @var{position}.
-@end defmac
-
-@defmac ad-get-args position
-This returns the list of actual arguments supplied starting at
-@var{position}.
-@end defmac
-
-@defmac ad-set-arg position value
-This sets the value of the actual argument at @var{position} to
-@var{value}
-@end defmac
-
-@defmac ad-set-args position value-list
-This sets the list of actual arguments starting at @var{position} to
-@var{value-list}.
-@end defmac
-
- Now an example. Suppose the function @code{foo} is defined as
-
-@example
-(defun foo (x y &optional z &rest r) ...)
-@end example
-
-@noindent
-and is then called with
-
-@example
-(foo 0 1 2 3 4 5 6)
-@end example
-
-@noindent
-which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is
-@code{(3 4 5 6)} within the body of @code{foo}. Here is what
-@code{ad-get-arg} and @code{ad-get-args} return in this case:
-
-@example
-(ad-get-arg 0) @result{} 0
-(ad-get-arg 1) @result{} 1
-(ad-get-arg 2) @result{} 2
-(ad-get-arg 3) @result{} 3
-(ad-get-args 2) @result{} (2 3 4 5 6)
-(ad-get-args 4) @result{} (4 5 6)
-@end example
-
- Setting arguments also makes sense in this example:
-
-@example
-(ad-set-arg 5 "five")
-@end example
-
-@noindent
-has the effect of changing the sixth argument to @code{"five"}. If this
-happens in advice executed before the body of @code{foo} is run, then
-@var{r} will be @code{(3 4 "five" 6)} within that body.
-
- Here is an example of setting a tail of the argument list:
-
-@example
-(ad-set-args 0 '(5 4 3 2 1 0))
-@end example
-
-@noindent
-If this happens in advice executed before the body of @code{foo} is run,
-then within that body, @var{x} will be 5, @var{y} will be 4, @var{z}
-will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
-@code{foo}.
-
- These argument constructs are not really implemented as Lisp macros.
-Instead they are implemented specially by the advice mechanism.
-
-@node Advising Primitives
-@section Advising Primitives
-@cindex advising primitives
-
- Advising a primitive function (also called a ``subr'') is risky.
-Some primitive functions are used by the advice mechanism; advising
-them could cause an infinite recursion. Also, many primitive
-functions are called directly from C code. Calls to the primitive
-from Lisp code will take note of the advice, but calls from C code
-will ignore the advice.
-
-When the advice facility constructs the combined definition, it needs
-to know the argument list of the original function. This is not
-always possible for primitive functions. When advice cannot determine
-the argument list, it uses @code{(&rest ad-subr-args)}, which always
-works but is inefficient because it constructs a list of the argument
-values. You can use @code{ad-define-subr-args} to declare the proper
-argument names for a primitive function:
-
-@defun ad-define-subr-args function arglist
-This function specifies that @var{arglist} should be used as the
-argument list for function @var{function}.
-@end defun
-
-For example,
-
-@example
-(ad-define-subr-args 'fset '(sym newdef))
-@end example
-
-@noindent
-specifies the argument list for the function @code{fset}.
-
-@node Combined Definition
-@section The Combined Definition
-
- Suppose that a function has @var{n} pieces of before-advice
-(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of
-around-advice and @var{k} pieces of after-advice. Assuming no piece
-of advice is protected, the combined definition produced to implement
-the advice for a function looks like this:
-
-@example
-(lambda @var{arglist}
- @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]}
- (let (ad-return-value)
- @r{before-0-body-form}...
- ....
- @r{before-@var{n}@minus{}1-body-form}...
- @r{around-0-body-form}...
- @r{around-1-body-form}...
- ....
- @r{around-@var{m}@minus{}1-body-form}...
- (setq ad-return-value
- @r{apply original definition to @var{arglist}})
- @r{end-of-around-@var{m}@minus{}1-body-form}...
- ....
- @r{end-of-around-1-body-form}...
- @r{end-of-around-0-body-form}...
- @r{after-0-body-form}...
- ....
- @r{after-@var{k}@minus{}1-body-form}...
- ad-return-value))
-@end example
-
-Macros are redefined as macros, which means adding @code{macro} to
-the beginning of the combined definition.
-
-The interactive form is present if the original function or some piece
-of advice specifies one. When an interactive primitive function is
-advised, advice uses a special method: it calls the primitive with
-@code{call-interactively} so that it will read its own arguments.
-In this case, the advice cannot access the arguments.
-
-The body forms of the various advice in each class are assembled
-according to their specified order. The forms of around-advice @var{l}
-are included in one of the forms of around-advice @var{l} @minus{} 1.
-
-The innermost part of the around advice onion is
-
-@display
-apply original definition to @var{arglist}
-@end display
-
-@noindent
-whose form depends on the type of the original function. The variable
-@code{ad-return-value} is set to whatever this returns. The variable is
-visible to all pieces of advice, which can access and modify it before
-it is actually returned from the advised function.
-
-The semantic structure of advised functions that contain protected
-pieces of advice is the same. The only difference is that
-@code{unwind-protect} forms ensure that the protected advice gets
-executed even if some previous piece of advice had an error or a
-non-local exit. If any around-advice is protected, then the whole
-around-advice onion is protected as a result.
-
-@ignore
- arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1999, 2002, 2003, 2004, 2005,
-@c 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-
-@c This node must have no pointers.
-
-@node Antinews, GNU Free Documentation License, System Interface, Top
-@appendix Emacs 21 Antinews
-
-For those users who live backwards in time, here is information about
-downgrading to Emacs version 21.4. We hope you will enjoy the greater
-simplicity that results from the absence of many Emacs @value{EMACSVER}
-features.
-
-@section Old Lisp Features in Emacs 21
-
-@itemize @bullet
-@item
-Many unnecessary features of redisplay have been eliminated. (The
-earlier major release, Emacs 20, will have a completely rewritten
-redisplay engine, which will be even simpler.)
-
-@itemize @minus
-@item
-The function @code{redisplay} has been removed. To update the display
-without delay, call @code{(sit-for 0)}. Since it is generally
-considered wasteful to update the display if there are any pending
-input events, no replacement for @code{(redisplay t)} is provided.
-
-@item
-The function @code{force-window-update} has been removed. It
-shouldn't be needed, since changes in window contents are detected
-automatically. In case they aren't, call @code{redraw-display} to
-redraw everything.
-
-@item
-Point no longer moves out from underneath invisible text at the end of
-each command. This allows the user to detect invisible text by moving
-the cursor around---if the cursor gets stuck, there is something
-invisible in the way. If you really want cursor motion to ignore the
-text, try marking it as intangible.
-
-@item
-Support for image maps and image slices has been removed. Emacs was
-always meant for editing text, anyway.
-
-@item
-The mode line now accepts all text properties, as well as
-@code{:propertize} and @code{:eval} forms, regardless of the
-@code{risky-local-variable} property.
-
-@item
-The @code{line-height} and @code{line-spacing} properties no longer
-have any meaning for newline characters. Such properties wouldn't
-make sense, since newlines are not really characters; they just tell
-you where to break a line.
-
-@item
-Considerable simplifications have been made to the display
-specification @code{(space . @var{props})}, which is used for
-displaying a space of specified width and height. Pixel-based
-specifications and Lisp expressions are no longer accepted.
-
-@item
-Many features associated with the fringe areas have been removed, to
-encourage people to concentrate on the main editing area (the fringe
-will be completely removed in Emacs 20.) Arbitrary bitmaps can no
-longer be displayed in the fringe; an overlay arrow can still be
-displayed, but there can only be one overlay arrow at a time (any more
-would be confusing.) The fringe widths cannot be adjusted, and
-individual windows cannot have their own fringe settings. A mouse
-click on the fringe no longer generates a special event.
-
-@item
-Individual windows cannot have their own scroll-bar settings.
-
-@item
-You can no longer use @samp{default} in a @code{defface} to specify
-defaults for subsequent faces.
-
-@item
-The function @code{display-supports-face-attributes-p} has been
-removed. In @code{defface} specifications, the @code{supports}
-predicate is no longer supported.
-
-@item
-The functions @code{merge-face-attribute} and
-@code{face-attribute-relative-p} have been removed.
-
-@item
-The priority of faces in a list supplied by the @code{:inherit} face
-attribute has been reversed. We like to make changes like this once
-in a while, to keep Emacs Lisp programmers on their toes.
-
-@item
-The @code{min-colors} face attribute, used for tailoring faces to
-limited-color displays, does not exist. If in doubt, use colors like
-``white'' and ``black,'' which ought to be defined everywhere.
-
-@item
-The @code{tty-color-mode} frame parameter does not exist. You should
-just trust the terminal capabilities database.
-@end itemize
-
-@item
-Several simplifications have been made to mouse support:
-
-@itemize @minus
-@item
-Clicking @kbd{mouse-1} won't follow links, as that is alien to the
-spirit of Emacs. Therefore, the @code{follow-link} property doesn't
-have any special meaning, and the function @code{mouse-on-link-p} has
-been removed.
-
-@item
-The variable @code{void-text-area-pointer} has been removed, so the
-mouse pointer shape remains unchanged when moving between valid text
-areas and void text areas. The @code{pointer} image and text
-properties are no longer supported.
-
-@item
-Mouse events will no longer specify the timestamp, the object clicked,
-equivalent buffer positions (for marginal or fringe areas), glyph
-coordinates, or relative pixel coordinates.
-@end itemize
-
-@item
-Simplifications have also been made to the way Emacs handles keymaps
-and key sequences:
-
-@itemize @minus
-@item
-The @code{kbd} macro is now obsolete and is no longer documented.
-It isn't that difficult to write key sequences using the string and
-vector representations, and we want to encourage users to learn.
-
-@item
-Emacs no longer supports key remapping. You can do pretty much the
-same thing with @code{substitute-key-definition}, or by advising the
-relevant command.
-
-@item
-The @code{keymap} text and overlay property is now overridden by minor
-mode keymaps, and will not work at the ends of text properties and
-overlays.
-
-@item
-The functions @code{map-keymap}, @code{keymap-prompt}, and
-@code{current-active-maps} have been removed.
-@end itemize
-
-@item
-Process support has been pared down to a functional minimum. The
-functions @code{call-process-shell-command} and @code{process-file}
-have been deleted. Processes no longer maintain property lists, and
-they won't ask any questions when the user tries to exit Emacs (which
-would simply be rude.) The function @code{signal-process} won't
-accept a process object, only the process id; determining the process
-id from a process object is left as an exercise to the programmer.
-
-@item
-Networking has also been simplified: @code{make-network-process} and
-its various associated function have all been replaced with a single
-easy-to-use function, @code{open-network-stream}, which can't use UDP,
-can't act as a server, and can't set up non-blocking connections.
-Also, deleting a network process with @code{delete-process} won't call
-the sentinel.
-
-@item
-Many programming shortcuts have been deleted, to provide you with the
-enjoyment of ``rolling your own.'' The macros @code{while-no-input},
-@code{with-local-quit}, and @code{with-selected-window}, along with
-@code{dynamic-completion-table} and @code{lazy-completion-table} no
-longer exist. Also, there are no built-in progress reporters;
-with Emacs, you can take progress for granted.
-
-@item
-Variable aliases are no longer supported. Aliases are for functions,
-not for variables.
-
-@item
-The variables @code{most-positive-fixnum} and
-@code{most-negative-fixnum} do not exist. On 32 bit machines, the
-most positive integer is probably 134217727, and the most negative
-integer is probably -134217728.
-
-@item
-The functions @code{eql} and @code{macroexpand-all} are no longer
-available. However, you can find similar functions in the @code{cl}
-package.
-
-@item
-The list returned by @code{split-string} won't include null substrings
-for separators at the beginning or end of a string. If you want to
-check for such separators, do it separately.
-
-@item
-The function @code{assoc-string} has been removed. Use
-@code{assoc-ignore-case} or @code{assoc-ignore-representation} (which
-are no longer obsolete.)
-
-@item
-The escape sequence @samp{\s} is always interpreted as a super
-modifier, never a space.
-
-@item
-The variable @code{buffer-save-without-query} has been removed, to
-prevent Emacs from sneakily saving buffers. Also, the hook
-@code{before-save-hook} has been removed, so if you want something to
-be done before saving, advise or redefine @code{basic-save-buffer}.
-
-@item
-The variable @code{buffer-auto-save-file-format} has been renamed to
-@code{auto-save-file-format}, and is no longer a permanent local.
-
-@item
-The function @code{visited-file-modtime} now returns a cons, instead
-of a list of two integers. The primitive @code{set-file-times} has
-been eliminated.
-
-@item
-The function @code{file-remote-p} is no longer available.
-
-@item
-When determining the filename extension, a leading dot in a filename
-is no longer ignored. Thus, @file{.emacs} is considered to have
-extension @file{emacs}, rather than being extensionless.
-
-@item
-Emacs looks for special file handlers in a more efficient manner: it
-will choose the first matching handler in
-@code{file-name-handler-alist}, rather than trying to figure out which
-provides the closest match.
-
-@item
-The @code{predicate} argument for @code{read-file-name} has been
-removed, and so have the variables @code{read-file-name-function} and
-@code{read-file-name-completion-ignore-case}. The function
-@code{read-directory-name} has also been removed.
-
-@item
-The functions @code{all-completions} and @code{try-completion} will no
-longer accept lists of strings or hash tables (it will still accept
-alists, obarrays, and functions.) In addition, the function
-@code{test-completion} is no longer available.
-
-@item
-The @samp{G} interactive code character is no longer supported.
-Use @samp{F} instead.
-
-@item
-Arbitrary Lisp functions can no longer be recorded into
-@code{buffer-undo-list}. As a consequence, @code{yank-undo-function}
-is obsolete, and has been removed.
-
-@item
-Emacs will never complain about commands that accumulate too much undo
-information, so you no longer have to worry about binding
-@code{buffer-undo-list} to @code{t} for such commands (though you may
-want to do that anyway, to avoid taking up unnecessary memory space.)
-
-@item
-Atomic change groups are no longer supported.
-
-@item
-The list returned by @code{(match-data t)} no longer records the
-buffer as a final element.
-
-@item
-The function @code{looking-back} has been removed, so we no longer
-have the benefit of hindsight.
-
-@item
-The variable @code{search-spaces-regexp} does not exist. Spaces
-always stand for themselves in regular expression searches.
-
-@item
-The functions @code{skip-chars-forward} and @code{skip-chars-backward}
-no longer accepts character classes such as @samp{[:alpha:]}. All
-characters are created equal.
-
-@item
-The @code{yank-handler} text property no longer has any meaning.
-Also, @code{yank-excluded-properties}, @code{insert-for-yank}, and
-@code{insert-buffer-substring-as-yank} have all been removed.
-
-@item
-The variable @code{char-property-alias-alist} has been deleted.
-Aliases are for functions, not for properties.
-
-@item
-The function @code{get-char-property-and-overlay} has been deleted.
-If you want the properties at a point, find the text properties at the
-point; then, find the overlays at the point, and find the properties
-on those overlays.
-
-@item
-Font Lock mode only manages @code{face} properties; you can't use
-font-lock keywords to specify arbitrary text properties for it to
-manage. After all, it is called Font Lock mode, not Arbitrary
-Properties Lock mode.
-
-@item
-The arguments to @code{remove-overlays} are no longer optional.
-
-@item
-In @code{replace-match}, the replacement text now inherits properties
-from the surrounding text.
-
-@item
-The variable @code{mode-line-format} no longer supports the @code{:propertize},
-@code{%i}, and @code{%I} constructs. The function
-@code{format-mode-line} has been removed.
-
-@item
-The functions @code{window-inside-edges} and @code{window-body-height}
-have been removed. You should do the relevant calculations yourself,
-starting with @code{window-width} and @code{window-height}.
-
-@item
-The functions @code{window-pixel-edges} and
-@code{window-inside-pixel-edges} have been removed. We prefer to
-think in terms of lines and columns, not pixel coordinates. (Sometime
-in the distant past, we will do away with graphical terminals
-entirely, in favor of text terminals.) For similar reasons, the
-functions @code{posn-at-point}, @code{posn-at-x-y}, and
-@code{window-line-height} have been removed, and
-@code{pos-visible-in-window-p} no longer worries about partially
-visible rows.
-
-@item
-The macro @code{save-selected-window} only saves the selected window
-of the selected frame, so don't try selecting windows in other frames.
-
-@item
-The function @code{minibufferp} is no longer available.
-
-@item
-The function @code{modify-all-frames-parameters} has been removed (we
-always suspected the name was ungrammatical, anyway.)
-
-@item
-The @code{line-spacing} variable no longer accepts float values.
-
-@item
-The function @code{tool-bar-local-item-from-menu} has been deleted.
-If you need to make an entry in the tool bar, you can still use
-@code{tool-bar-add-item-from-menu}, but that modifies the binding in
-the source keymap instead of copying it into the local keymap.
-
-@item
-When determining the major mode, the file name takes precedence over
-the interpreter magic line. The variable @code{magic-mode-alist},
-which associates certain buffer beginnings with major modes, has been
-eliminated.
-
-@item
-The hook @code{after-change-major-mode-hook} is not defined, and
-neither are @code{run-mode-hooks} and @code{delay-mode-hooks}.
-
-@item
-The variable @code{minor-mode-list} has been removed.
-
-@item
-@code{define-derived-mode} will copy abbrevs from the parent mode's
-abbrev table, instead of creating a new, empty abbrev table.
-
-@item
-There are no ``system'' abbrevs. When the user saves into the abbrevs
-file, all abbrevs are saved.
-
-@item
-The Warnings facility has been removed. Just use @code{error}.
-
-@item
-Several hook variables have been renamed to flout the Emacs naming
-conventions. We feel that consistency is boring, and having
-non-standard hook names encourages users to check the documentation
-before using a hook. For instance, the normal hook
-@code{find-file-hook} has been renamed to @code{find-file-hooks}, and
-the abnormal hook @code{delete-frame-functions} has been renamed to
-@code{delete-frame-hook}.
-
-@item
-The function @code{symbol-file} does not exist. If you want to know
-which file defined a function or variable, try grepping for it.
-
-@item
-The variable @code{load-history} records function definitions just
-like variable definitions, instead of indicating which functions were
-previously autoloaded.
-
-@item
-There is a new variable, @code{recursive-load-depth-limit}, which
-specifies how many times files can recursively load themselves; it is
-50 by default, and @code{nil} means infinity. Previously, Emacs signaled an
-error after just 3 recursive loads, which was boring.
-
-@item
-Byte-compiler warnings and error messages will leave out the line and
-character positions, in order to exercise your debugging skills.
-Also, there is no @code{with-no-warnings} macro---instead of
-suppressing compiler warnings, fix your code to avoid them!
-
-@item
-The function @code{unsafep} has been removed.
-
-@item
-File local variables can now specify a string with text properties.
-Since arbitrary Lisp expressions can be embedded in text properties,
-this can provide you with a great deal of flexibility and power. On
-the other hand, @code{safe-local-eval-forms} and the
-@code{safe-local-eval-function} function property have no special
-meaning.
-
-@item
-You can no longer use @code{char-displayable-p} to test if Emacs can
-display a certain character.
-
-@item
-The function @code{string-to-multibyte} is no longer available.
-
-@item
-The @code{translation-table-for-input} translation table has been
-removed. Also, translation hash tables are no longer available, so we
-don't need the functions @code{lookup-character} and
-@code{lookup-integer}.
-
-@item
-The @code{table} argument to @code{translate-region} can no longer be
-a char-table; it has to be a string.
-
-@item
-The variable @code{auto-coding-functions} and the two functions
-@code{merge-coding-systems} and @code{decode-coding-inserted-region}
-have been deleted. The coding system property
-@code{mime-text-unsuitable} no longer has any special meaning.
-
-@item
-If pure storage overflows while dumping, Emacs won't tell you how much
-additional pure storage it needs. Try adding in increments of 20000,
-until you have enough.
-
-@item
-The variables @code{gc-elapsed}, @code{gcs-done}, and
-@code{post-gc-hook} have been garbage-collected.
-@end itemize
-
-@ignore
- arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6
-@end ignore
+++ /dev/null
-\input /home/gd/gnu/doc/texinfo.tex @c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
-@c Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@c
-@c %**start of header
-@setfilename back-cover
-@settitle GNU Emacs Lisp Reference Manual
-@c %**end of header
-.
-@sp 7
-@center @titlefont {GNU Emacs Lisp}
-@sp 1
-
-@quotation
- Most of the GNU Emacs text editor is written in the programming
-language called Emacs Lisp. You can write new code in Emacs Lisp and
-install it as an extension to the editor. However, Emacs Lisp is more
-than a mere ``extension language''; it is a full computer programming
-language in its own right. You can use it as you would any other
-programming language.
-
- Because Emacs Lisp is designed for use in an editor, it has special
-features for scanning and parsing text as well as features for handling
-files, buffers, displays, subprocesses, and so on. Emacs Lisp is
-closely integrated with the editing facilities; thus, editing commands
-are functions that can also conveniently be called from Lisp programs,
-and parameters for customization are ordinary Lisp variables.
-
- This manual describes Emacs Lisp. Generally speaking, the earlier
-chapters describe features of Emacs Lisp that have counterparts in
-many programming languages, and later chapters describe features that
-are peculiar to Emacs Lisp or relate specifically to editing.
-@end quotation
-
-@hfil
-@bye
-
-@ignore
- arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/backups
-@node Backups and Auto-Saving, Buffers, Files, Top
-@chapter Backups and Auto-Saving
-@cindex backups and auto-saving
-
- Backup files and auto-save files are two methods by which Emacs tries
-to protect the user from the consequences of crashes or of the user's
-own errors. Auto-saving preserves the text from earlier in the current
-editing session; backup files preserve file contents prior to the
-current session.
-
-@menu
-* 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.
-@end menu
-
-@node Backup Files
-@section Backup Files
-@cindex backup file
-
- A @dfn{backup file} is a copy of the old contents of a file you are
-editing. Emacs makes a backup file the first time you save a buffer
-into its visited file. Thus, normally, the backup file contains the
-contents of the file as it was before the current editing session.
-The contents of the backup file normally remain unchanged once it
-exists.
-
- Backups are usually made by renaming the visited file to a new name.
-Optionally, you can specify that backup files should be made by copying
-the visited file. This choice makes a difference for files with
-multiple names; it also can affect whether the edited file remains owned
-by the original owner or becomes owned by the user editing it.
-
- By default, Emacs makes a single backup file for each file edited.
-You can alternatively request numbered backups; then each new backup
-file gets a new name. You can delete old numbered backups when you
-don't want them any more, or Emacs can delete them automatically.
-
-@menu
-* 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.
-@end menu
-
-@node Making Backups
-@subsection Making Backup Files
-
-@defun backup-buffer
- This function makes a backup of the file visited by the current
-buffer, if appropriate. It is called by @code{save-buffer} before
-saving the buffer the first time.
-
-If a backup was made by renaming, the return value is a cons cell of
-the form (@var{modes} . @var{backupname}), where @var{modes} are the
-mode bits of the original file, as returned by @code{file-modes}
-(@pxref{File Attributes,, Other Information about Files}), and
-@var{backupname} is the name of the backup. In all other cases, that
-is, if a backup was made by copying or if no backup was made, this
-function returns @code{nil}.
-@end defun
-
-@defvar buffer-backed-up
- This buffer-local variable says whether this buffer's file has
-been backed up on account of this buffer. If it is non-@code{nil},
-the backup file has been written. Otherwise, the file should be backed
-up when it is next saved (if backups are enabled). This is a
-permanent local; @code{kill-all-local-variables} does not alter@tie{}it.
-@end defvar
-
-@defopt make-backup-files
-This variable determines whether or not to make backup files. If it
-is non-@code{nil}, then Emacs creates a backup of each file when it is
-saved for the first time---provided that @code{backup-inhibited}
-is @code{nil} (see below).
-
-The following example shows how to change the @code{make-backup-files}
-variable only in the Rmail buffers and not elsewhere. Setting it
-@code{nil} stops Emacs from making backups of these files, which may
-save disk space. (You would put this code in your init file.)
-
-@smallexample
-@group
-(add-hook 'rmail-mode-hook
- (function (lambda ()
- (make-local-variable
- 'make-backup-files)
- (setq make-backup-files nil))))
-@end group
-@end smallexample
-@end defopt
-
-@defvar backup-enable-predicate
-This variable's value is a function to be called on certain occasions to
-decide whether a file should have backup files. The function receives
-one argument, an absolute file name to consider. If the function returns
-@code{nil}, backups are disabled for that file. Otherwise, the other
-variables in this section say whether and how to make backups.
-
-@findex normal-backup-enable-predicate
-The default value is @code{normal-backup-enable-predicate}, which checks
-for files in @code{temporary-file-directory} and
-@code{small-temporary-file-directory}.
-@end defvar
-
-@defvar backup-inhibited
-If this variable is non-@code{nil}, backups are inhibited. It records
-the result of testing @code{backup-enable-predicate} on the visited file
-name. It can also coherently be used by other mechanisms that inhibit
-backups based on which file is visited. For example, VC sets this
-variable non-@code{nil} to prevent making backups for files managed
-with a version control system.
-
-This is a permanent local, so that changing the major mode does not lose
-its value. Major modes should not set this variable---they should set
-@code{make-backup-files} instead.
-@end defvar
-
-@defvar backup-directory-alist
-This variable's value is an alist of filename patterns and backup
-directory names. Each element looks like
-@smallexample
-(@var{regexp} . @var{directory})
-@end smallexample
-
-@noindent
-Backups of files with names matching @var{regexp} will be made in
-@var{directory}. @var{directory} may be relative or absolute. If it is
-absolute, so that all matching files are backed up into the same
-directory, the file names in this directory will be the full name of the
-file backed up with all directory separators changed to @samp{!} to
-prevent clashes. This will not work correctly if your filesystem
-truncates the resulting name.
-
-For the common case of all backups going into one directory, the alist
-should contain a single element pairing @samp{"."} with the appropriate
-directory name.
-
-If this variable is @code{nil}, or it fails to match a filename, the
-backup is made in the original file's directory.
-
-On MS-DOS filesystems without long names this variable is always
-ignored.
-@end defvar
-
-@defvar make-backup-file-name-function
-This variable's value is a function to use for making backups instead
-of the default @code{make-backup-file-name}. A value of @code{nil}
-gives the default @code{make-backup-file-name} behavior.
-@xref{Backup Names,, Naming Backup Files}.
-
-This could be buffer-local to do something special for specific
-files. If you define it, you may need to change
-@code{backup-file-name-p} and @code{file-name-sans-versions} too.
-@end defvar
-
-
-@node Rename or Copy
-@subsection Backup by Renaming or by Copying?
-@cindex backup files, rename or copy
-
- There are two ways that Emacs can make a backup file:
-
-@itemize @bullet
-@item
-Emacs can rename the original file so that it becomes a backup file, and
-then write the buffer being saved into a new file. After this
-procedure, any other names (i.e., hard links) of the original file now
-refer to the backup file. The new file is owned by the user doing the
-editing, and its group is the default for new files written by the user
-in that directory.
-
-@item
-Emacs can copy the original file into a backup file, and then overwrite
-the original file with new contents. After this procedure, any other
-names (i.e., hard links) of the original file continue to refer to the
-current (updated) version of the file. The file's owner and group will
-be unchanged.
-@end itemize
-
- The first method, renaming, is the default.
-
- The variable @code{backup-by-copying}, if non-@code{nil}, says to use
-the second method, which is to copy the original file and overwrite it
-with the new buffer contents. The variable @code{file-precious-flag},
-if non-@code{nil}, also has this effect (as a sideline of its main
-significance). @xref{Saving Buffers}.
-
-@defopt backup-by-copying
-If this variable is non-@code{nil}, Emacs always makes backup files by
-copying.
-@end defopt
-
- The following three variables, when non-@code{nil}, cause the second
-method to be used in certain special cases. They have no effect on the
-treatment of files that don't fall into the special cases.
-
-@defopt backup-by-copying-when-linked
-If this variable is non-@code{nil}, Emacs makes backups by copying for
-files with multiple names (hard links).
-
-This variable is significant only if @code{backup-by-copying} is
-@code{nil}, since copying is always used when that variable is
-non-@code{nil}.
-@end defopt
-
-@defopt backup-by-copying-when-mismatch
-If this variable is non-@code{nil}, Emacs makes backups by copying in cases
-where renaming would change either the owner or the group of the file.
-
-The value has no effect when renaming would not alter the owner or
-group of the file; that is, for files which are owned by the user and
-whose group matches the default for a new file created there by the
-user.
-
-This variable is significant only if @code{backup-by-copying} is
-@code{nil}, since copying is always used when that variable is
-non-@code{nil}.
-@end defopt
-
-@defopt backup-by-copying-when-privileged-mismatch
-This variable, if non-@code{nil}, specifies the same behavior as
-@code{backup-by-copying-when-mismatch}, but only for certain user-id
-values: namely, those less than or equal to a certain number. You set
-this variable to that number.
-
-Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
-to 0, backup by copying is done for the superuser only,
-when necessary to prevent a change in the owner of the file.
-
-The default is 200.
-@end defopt
-
-@node Numbered Backups
-@subsection Making and Deleting Numbered Backup Files
-
- If a file's name is @file{foo}, the names of its numbered backup
-versions are @file{foo.~@var{v}~}, for various integers @var{v}, like
-this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{},
-@file{foo.~259~}, and so on.
-
-@defopt version-control
-This variable controls whether to make a single non-numbered backup
-file or multiple numbered backups.
-
-@table @asis
-@item @code{nil}
-Make numbered backups if the visited file already has numbered backups;
-otherwise, do not. This is the default.
-
-@item @code{never}
-Do not make numbered backups.
-
-@item @var{anything else}
-Make numbered backups.
-@end table
-@end defopt
-
- The use of numbered backups ultimately leads to a large number of
-backup versions, which must then be deleted. Emacs can do this
-automatically or it can ask the user whether to delete them.
-
-@defopt kept-new-versions
-The value of this variable is the number of newest versions to keep
-when a new numbered backup is made. The newly made backup is included
-in the count. The default value is@tie{}2.
-@end defopt
-
-@defopt kept-old-versions
-The value of this variable is the number of oldest versions to keep
-when a new numbered backup is made. The default value is@tie{}2.
-@end defopt
-
- If there are backups numbered 1, 2, 3, 5, and 7, and both of these
-variables have the value 2, then the backups numbered 1 and 2 are kept
-as old versions and those numbered 5 and 7 are kept as new versions;
-backup version 3 is excess. The function @code{find-backup-file-name}
-(@pxref{Backup Names}) is responsible for determining which backup
-versions to delete, but does not delete them itself.
-
-@defopt delete-old-versions
-If this variable is @code{t}, then saving a file deletes excess
-backup versions silently. If it is @code{nil}, that means
-to ask for confirmation before deleting excess backups.
-Otherwise, they are not deleted at all.
-@end defopt
-
-@defopt dired-kept-versions
-This variable specifies how many of the newest backup versions to keep
-in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the
-same thing @code{kept-new-versions} specifies when you make a new backup
-file. The default is@tie{}2.
-@end defopt
-
-@node Backup Names
-@subsection Naming Backup Files
-
- The functions in this section are documented mainly because you can
-customize the naming conventions for backup files by redefining them.
-If you change one, you probably need to change the rest.
-
-@defun backup-file-name-p filename
-This function returns a non-@code{nil} value if @var{filename} is a
-possible name for a backup file. It just checks the name, not whether
-a file with the name @var{filename} exists.
-
-@smallexample
-@group
-(backup-file-name-p "foo")
- @result{} nil
-@end group
-@group
-(backup-file-name-p "foo~")
- @result{} 3
-@end group
-@end smallexample
-
-The standard definition of this function is as follows:
-
-@smallexample
-@group
-(defun backup-file-name-p (file)
- "Return non-nil if FILE is a backup file \
-name (numeric or not)..."
- (string-match "~\\'" file))
-@end group
-@end smallexample
-
-@noindent
-Thus, the function returns a non-@code{nil} value if the file name ends
-with a @samp{~}. (We use a backslash to split the documentation
-string's first line into two lines in the text, but produce just one
-line in the string itself.)
-
-This simple expression is placed in a separate function to make it easy
-to redefine for customization.
-@end defun
-
-@defun make-backup-file-name filename
-This function returns a string that is the name to use for a
-non-numbered backup file for file @var{filename}. On Unix, this is just
-@var{filename} with a tilde appended.
-
-The standard definition of this function, on most operating systems, is
-as follows:
-
-@smallexample
-@group
-(defun make-backup-file-name (file)
- "Create the non-numeric backup file name for FILE..."
- (concat file "~"))
-@end group
-@end smallexample
-
-You can change the backup-file naming convention by redefining this
-function. The following example redefines @code{make-backup-file-name}
-to prepend a @samp{.} in addition to appending a tilde:
-
-@smallexample
-@group
-(defun make-backup-file-name (filename)
- (expand-file-name
- (concat "." (file-name-nondirectory filename) "~")
- (file-name-directory filename)))
-@end group
-
-@group
-(make-backup-file-name "backups.texi")
- @result{} ".backups.texi~"
-@end group
-@end smallexample
-
-Some parts of Emacs, including some Dired commands, assume that backup
-file names end with @samp{~}. If you do not follow that convention, it
-will not cause serious problems, but these commands may give
-less-than-desirable results.
-@end defun
-
-@defun find-backup-file-name filename
-This function computes the file name for a new backup file for
-@var{filename}. It may also propose certain existing backup files for
-deletion. @code{find-backup-file-name} returns a list whose @sc{car} is
-the name for the new backup file and whose @sc{cdr} is a list of backup
-files whose deletion is proposed. The value can also be @code{nil},
-which means not to make a backup.
-
-Two variables, @code{kept-old-versions} and @code{kept-new-versions},
-determine which backup versions should be kept. This function keeps
-those versions by excluding them from the @sc{cdr} of the value.
-@xref{Numbered Backups}.
-
-In this example, the value says that @file{~rms/foo.~5~} is the name
-to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess''
-version that the caller should consider deleting now.
-
-@smallexample
-@group
-(find-backup-file-name "~rms/foo")
- @result{} ("~rms/foo.~5~" "~rms/foo.~3~")
-@end group
-@end smallexample
-@end defun
-
-@c Emacs 19 feature
-@defun file-newest-backup filename
-This function returns the name of the most recent backup file for
-@var{filename}, or @code{nil} if that file has no backup files.
-
-Some file comparison commands use this function so that they can
-automatically compare a file with its most recent backup.
-@end defun
-
-@node Auto-Saving
-@section Auto-Saving
-@c @cindex auto-saving Lots of symbols starting with auto-save here.
-
- Emacs periodically saves all files that you are visiting; this is
-called @dfn{auto-saving}. Auto-saving prevents you from losing more
-than a limited amount of work if the system crashes. By default,
-auto-saves happen every 300 keystrokes, or after around 30 seconds of
-idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against
-Disasters, emacs, The GNU Emacs Manual}, for information on auto-save
-for users. Here we describe the functions used to implement auto-saving
-and the variables that control them.
-
-@defvar buffer-auto-save-file-name
-This buffer-local variable is the name of the file used for
-auto-saving the current buffer. It is @code{nil} if the buffer
-should not be auto-saved.
-
-@example
-@group
-buffer-auto-save-file-name
- @result{} "/xcssun/users/rms/lewis/#backups.texi#"
-@end group
-@end example
-@end defvar
-
-@deffn Command auto-save-mode arg
-When used interactively without an argument, this command is a toggle
-switch: it turns on auto-saving of the current buffer if it is off, and
-vice versa. With an argument @var{arg}, the command turns auto-saving
-on if the value of @var{arg} is @code{t}, a nonempty list, or a positive
-integer. Otherwise, it turns auto-saving off.
-@end deffn
-
-@defun auto-save-file-name-p filename
-This function returns a non-@code{nil} value if @var{filename} is a
-string that could be the name of an auto-save file. It assumes
-the usual naming convention for auto-save files: a name that
-begins and ends with hash marks (@samp{#}) is a possible auto-save file
-name. The argument @var{filename} should not contain a directory part.
-
-@example
-@group
-(make-auto-save-file-name)
- @result{} "/xcssun/users/rms/lewis/#backups.texi#"
-@end group
-@group
-(auto-save-file-name-p "#backups.texi#")
- @result{} 0
-@end group
-@group
-(auto-save-file-name-p "backups.texi")
- @result{} nil
-@end group
-@end example
-
-The standard definition of this function is as follows:
-
-@example
-@group
-(defun auto-save-file-name-p (filename)
- "Return non-nil if FILENAME can be yielded by..."
- (string-match "^#.*#$" filename))
-@end group
-@end example
-
-This function exists so that you can customize it if you wish to
-change the naming convention for auto-save files. If you redefine it,
-be sure to redefine the function @code{make-auto-save-file-name}
-correspondingly.
-@end defun
-
-@defun make-auto-save-file-name
-This function returns the file name to use for auto-saving the current
-buffer. This is just the file name with hash marks (@samp{#}) prepended
-and appended to it. This function does not look at the variable
-@code{auto-save-visited-file-name} (described below); callers of this
-function should check that variable first.
-
-@example
-@group
-(make-auto-save-file-name)
- @result{} "/xcssun/users/rms/lewis/#backups.texi#"
-@end group
-@end example
-
-Here is a simplified version of the standard definition of this
-function:
-
-@example
-@group
-(defun make-auto-save-file-name ()
- "Return file name to use for auto-saves \
-of current buffer.."
- (if buffer-file-name
-@end group
-@group
- (concat
- (file-name-directory buffer-file-name)
- "#"
- (file-name-nondirectory buffer-file-name)
- "#")
- (expand-file-name
- (concat "#%" (buffer-name) "#"))))
-@end group
-@end example
-
-This exists as a separate function so that you can redefine it to
-customize the naming convention for auto-save files. Be sure to
-change @code{auto-save-file-name-p} in a corresponding way.
-@end defun
-
-@defopt auto-save-visited-file-name
-If this variable is non-@code{nil}, Emacs auto-saves buffers in
-the files they are visiting. That is, the auto-save is done in the same
-file that you are editing. Normally, this variable is @code{nil}, so
-auto-save files have distinct names that are created by
-@code{make-auto-save-file-name}.
-
-When you change the value of this variable, the new value does not take
-effect in an existing buffer until the next time auto-save mode is
-reenabled in it. If auto-save mode is already enabled, auto-saves
-continue to go in the same file name until @code{auto-save-mode} is
-called again.
-@end defopt
-
-@defun recent-auto-save-p
-This function returns @code{t} if the current buffer has been
-auto-saved since the last time it was read in or saved.
-@end defun
-
-@defun set-buffer-auto-saved
-This function marks the current buffer as auto-saved. The buffer will
-not be auto-saved again until the buffer text is changed again. The
-function returns @code{nil}.
-@end defun
-
-@defopt auto-save-interval
-The value of this variable specifies how often to do auto-saving, in
-terms of number of input events. Each time this many additional input
-events are read, Emacs does auto-saving for all buffers in which that is
-enabled. Setting this to zero disables autosaving based on the
-number of characters typed.
-@end defopt
-
-@defopt auto-save-timeout
-The value of this variable is the number of seconds of idle time that
-should cause auto-saving. Each time the user pauses for this long,
-Emacs does auto-saving for all buffers in which that is enabled. (If
-the current buffer is large, the specified timeout is multiplied by a
-factor that increases as the size increases; for a million-byte
-buffer, the factor is almost 4.)
-
-If the value is zero or @code{nil}, then auto-saving is not done as a
-result of idleness, only after a certain number of input events as
-specified by @code{auto-save-interval}.
-@end defopt
-
-@defvar auto-save-hook
-This normal hook is run whenever an auto-save is about to happen.
-@end defvar
-
-@defopt auto-save-default
-If this variable is non-@code{nil}, buffers that are visiting files
-have auto-saving enabled by default. Otherwise, they do not.
-@end defopt
-
-@deffn Command do-auto-save &optional no-message current-only
-This function auto-saves all buffers that need to be auto-saved. It
-saves all buffers for which auto-saving is enabled and that have been
-changed since the previous auto-save.
-
-If any buffers are auto-saved, @code{do-auto-save} normally displays a
-message saying @samp{Auto-saving...} in the echo area while
-auto-saving is going on. However, if @var{no-message} is
-non-@code{nil}, the message is inhibited.
-
-If @var{current-only} is non-@code{nil}, only the current buffer
-is auto-saved.
-@end deffn
-
-@defun delete-auto-save-file-if-necessary &optional force
-This function deletes the current buffer's auto-save file if
-@code{delete-auto-save-files} is non-@code{nil}. It is called every
-time a buffer is saved.
-
-Unless @var{force} is non-@code{nil}, this function only deletes the
-file if it was written by the current Emacs session since the last
-true save.
-@end defun
-
-@defopt delete-auto-save-files
-This variable is used by the function
-@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil},
-Emacs deletes auto-save files when a true save is done (in the visited
-file). This saves disk space and unclutters your directory.
-@end defopt
-
-@defun rename-auto-save-file
-This function adjusts the current buffer's auto-save file name if the
-visited file name has changed. It also renames an existing auto-save
-file, if it was made in the current Emacs session. If the visited
-file name has not changed, this function does nothing.
-@end defun
-
-@defvar buffer-saved-size
-The value of this buffer-local variable is the length of the current
-buffer, when it was last read in, saved, or auto-saved. This is
-used to detect a substantial decrease in size, and turn off auto-saving
-in response.
-
-If it is @minus{}1, that means auto-saving is temporarily shut off in
-this buffer due to a substantial decrease in size. Explicitly saving
-the buffer stores a positive value in this variable, thus reenabling
-auto-saving. Turning auto-save mode off or on also updates this
-variable, so that the substantial decrease in size is forgotten.
-@end defvar
-
-@defvar auto-save-list-file-name
-This variable (if non-@code{nil}) specifies a file for recording the
-names of all the auto-save files. Each time Emacs does auto-saving, it
-writes two lines into this file for each buffer that has auto-saving
-enabled. The first line gives the name of the visited file (it's empty
-if the buffer has none), and the second gives the name of the auto-save
-file.
-
-When Emacs exits normally, it deletes this file; if Emacs crashes, you
-can look in the file to find all the auto-save files that might contain
-work that was otherwise lost. The @code{recover-session} command uses
-this file to find them.
-
-The default name for this file specifies your home directory and starts
-with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the
-host name.
-@end defvar
-
-@defvar auto-save-list-file-prefix
-After Emacs reads your init file, it initializes
-@code{auto-save-list-file-name} (if you have not already set it
-non-@code{nil}) based on this prefix, adding the host name and process
-ID. If you set this to @code{nil} in your init file, then Emacs does
-not initialize @code{auto-save-list-file-name}.
-@end defvar
-
-@node Reverting
-@section Reverting
-
- If you have made extensive changes to a file and then change your mind
-about them, you can get rid of them by reading in the previous version
-of the file with the @code{revert-buffer} command. @xref{Reverting, ,
-Reverting a Buffer, emacs, The GNU Emacs Manual}.
-
-@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
-This command replaces the buffer text with the text of the visited
-file on disk. This action undoes all changes since the file was visited
-or saved.
-
-By default, if the latest auto-save file is more recent than the visited
-file, and the argument @var{ignore-auto} is @code{nil},
-@code{revert-buffer} asks the user whether to use that auto-save
-instead. When you invoke this command interactively, @var{ignore-auto}
-is @code{t} if there is no numeric prefix argument; thus, the
-interactive default is not to check the auto-save file.
-
-Normally, @code{revert-buffer} asks for confirmation before it changes
-the buffer; but if the argument @var{noconfirm} is non-@code{nil},
-@code{revert-buffer} does not ask for confirmation.
-
-Normally, this command reinitializes the buffer's major and minor modes
-using @code{normal-mode}. But if @var{preserve-modes} is
-non-@code{nil}, the modes remain unchanged.
-
-Reverting tries to preserve marker positions in the buffer by using the
-replacement feature of @code{insert-file-contents}. If the buffer
-contents and the file contents are identical before the revert
-operation, reverting preserves all the markers. If they are not
-identical, reverting does change the buffer; in that case, it preserves
-the markers in the unchanged text (if any) at the beginning and end of
-the buffer. Preserving any additional markers would be problematical.
-@end deffn
-
-You can customize how @code{revert-buffer} does its work by setting
-the variables described in the rest of this section.
-
-@defopt revert-without-query
-This variable holds a list of files that should be reverted without
-query. The value is a list of regular expressions. If the visited file
-name matches one of these regular expressions, and the file has changed
-on disk but the buffer is not modified, then @code{revert-buffer}
-reverts the file without asking the user for confirmation.
-@end defopt
-
- Some major modes customize @code{revert-buffer} by making
-buffer-local bindings for these variables:
-
-@defvar revert-buffer-function
-@anchor{Definition of revert-buffer-function}
-The value of this variable is the function to use to revert this
-buffer. If non-@code{nil}, it should be a function with two optional
-arguments to do the work of reverting. The two optional arguments,
-@var{ignore-auto} and @var{noconfirm}, are the arguments that
-@code{revert-buffer} received. If the value is @code{nil}, reverting
-works the usual way.
-
-Modes such as Dired mode, in which the text being edited does not
-consist of a file's contents but can be regenerated in some other
-fashion, can give this variable a buffer-local value that is a function to
-regenerate the contents.
-@end defvar
-
-@defvar revert-buffer-insert-file-contents-function
-The value of this variable, if non-@code{nil}, specifies the function to use to
-insert the updated contents when reverting this buffer. The function
-receives two arguments: first the file name to use; second, @code{t} if
-the user has asked to read the auto-save file.
-
-The reason for a mode to set this variable instead of
-@code{revert-buffer-function} is to avoid duplicating or replacing the
-rest of what @code{revert-buffer} does: asking for confirmation,
-clearing the undo list, deciding the proper major mode, and running the
-hooks listed below.
-@end defvar
-
-@defvar before-revert-hook
-This normal hook is run by @code{revert-buffer} before
-inserting the modified contents---but only if
-@code{revert-buffer-function} is @code{nil}.
-@end defvar
-
-@defvar after-revert-hook
-This normal hook is run by @code{revert-buffer} after inserting
-the modified contents---but only if @code{revert-buffer-function} is
-@code{nil}.
-@end defvar
-
-@ignore
- arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@setfilename book-spine
-@settitle book-spine
-@c %**end of header
-
-@c need dot in text so first space command works!
-.
-@sp 7
-
-@center @titlefont{GNU Emacs Lisp Reference Manual}
-@sp 5
-@center GNU
-@center Emacs Version 22.1
-@center for Unix Users
-@sp 5
-
-@center by
-@center Bil Lewis,
-@center Dan LaLiberte,
-@center and the
-@center GNU Manual Group
-@sp 5
-@center Free Software Foundation
-@bye
-
-@ignore
- arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87
-@end ignore
+++ /dev/null
-@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/buffers
-@node Buffers, Windows, Backups and Auto-Saving, Top
-@chapter Buffers
-@cindex buffer
-
- A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
-are used to hold the contents of files that are being visited; there may
-also be buffers that are not visiting files. While several buffers may
-exist at one time, only one buffer is designated the @dfn{current
-buffer} at any time. Most editing commands act on the contents of the
-current buffer. Each buffer, including the current buffer, may or may
-not be displayed in any windows.
-
-@menu
-* Buffer Basics:: What is a buffer?
-* Current Buffer:: Designating a buffer as current
- so that 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.
-@end menu
-
-@node Buffer Basics
-@comment node-name, next, previous, up
-@section Buffer Basics
-
-@ifnottex
- A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
-are used to hold the contents of files that are being visited; there may
-also be buffers that are not visiting files. Although several buffers
-normally exist, only one buffer is designated the @dfn{current
-buffer} at any time. Most editing commands act on the contents of the
-current buffer. Each buffer, including the current buffer, may or may
-not be displayed in any windows.
-@end ifnottex
-
- Buffers in Emacs editing are objects that have distinct names and hold
-text that can be edited. Buffers appear to Lisp programs as a special
-data type. You can think of the contents of a buffer as a string that
-you can extend; insertions and deletions may occur in any part of the
-buffer. @xref{Text}.
-
- A Lisp buffer object contains numerous pieces of information. Some of
-this information is directly accessible to the programmer through
-variables, while other information is accessible only through
-special-purpose functions. For example, the visited file name is
-directly accessible through a variable, while the value of point is
-accessible only through a primitive function.
-
- Buffer-specific information that is directly accessible is stored in
-@dfn{buffer-local} variable bindings, which are variable values that are
-effective only in a particular buffer. This feature allows each buffer
-to override the values of certain variables. Most major modes override
-variables such as @code{fill-column} or @code{comment-column} in this
-way. For more information about buffer-local variables and functions
-related to them, see @ref{Buffer-Local Variables}.
-
- For functions and variables related to visiting files in buffers, see
-@ref{Visiting Files} and @ref{Saving Buffers}. For functions and
-variables related to the display of buffers in windows, see
-@ref{Buffers and Windows}.
-
-@defun bufferp object
-This function returns @code{t} if @var{object} is a buffer,
-@code{nil} otherwise.
-@end defun
-
-@node Current Buffer
-@section The Current Buffer
-@cindex selecting a buffer
-@cindex changing to another buffer
-@cindex current buffer
-
- There are, in general, many buffers in an Emacs session. At any time,
-one of them is designated as the @dfn{current buffer}. This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (@pxref{Text}). Normally the buffer that is displayed on
-the screen in the selected window is the current buffer, but this is not
-always so: a Lisp program can temporarily designate any buffer as
-current in order to operate on its contents, without changing what is
-displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-@code{set-buffer}. The specified buffer remains current until a new one
-is designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-that, you must use the functions described in @ref{Displaying Buffers}.
-
- @strong{Warning:} Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in Emacs Lisp can be called from other programs
-as well as from the command loop; it is convenient for the caller if
-the subroutine does not change which buffer is current (unless, of
-course, that is the subroutine's purpose). Therefore, you should
-normally use @code{set-buffer} within a @code{save-current-buffer} or
-@code{save-excursion} (@pxref{Excursions}) form that will restore the
-current buffer when your function is done. Here is an example, the
-code for the command @code{append-to-buffer} (with the documentation
-string abridged):
-
-@example
-@group
-(defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
-@dots{}"
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-current-buffer
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-@end group
-@end example
-
-@noindent
-This function binds a local variable to record the current buffer, and
-then @code{save-current-buffer} arranges to make it current again.
-Next, @code{set-buffer} makes the specified buffer current. Finally,
-@code{insert-buffer-substring} copies the string from the original
-current buffer to the specified (and now current) buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with @code{let} or function arguments) for
-a variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use @code{save-current-buffer} or
-@code{save-excursion} to make sure that the buffer current at the
-beginning is current again whenever the variable is unbound.
-
- Do not rely on using @code{set-buffer} to change the current buffer
-back, because that won't do the job if a quit happens while the wrong
-buffer is current. Here is what @emph{not} to do:
-
-@example
-@group
-(let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer @dots{})
- @dots{}
- (set-buffer obuf))
-@end group
-@end example
-
-@noindent
-Using @code{save-current-buffer}, as shown here, handles quitting,
-errors, and @code{throw}, as well as ordinary evaluation.
-
-@example
-@group
-(let (buffer-read-only)
- (save-current-buffer
- (set-buffer @dots{})
- @dots{}))
-@end group
-@end example
-
-@defun current-buffer
-This function returns the current buffer.
-
-@example
-@group
-(current-buffer)
- @result{} #<buffer buffers.texi>
-@end group
-@end example
-@end defun
-
-@defun set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer. This does
-not display the buffer in any window, so the user cannot necessarily see
-the buffer. But Lisp programs will now operate on it.
-
-This function returns the buffer identified by @var{buffer-or-name}.
-An error is signaled if @var{buffer-or-name} does not identify an
-existing buffer.
-@end defun
-
-@defspec save-current-buffer body@dots{}
-The @code{save-current-buffer} special form saves the identity of the
-current buffer, evaluates the @var{body} forms, and finally restores
-that buffer as current. The return value is the value of the last
-form in @var{body}. The current buffer is restored even in case of an
-abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
-
-If the buffer that used to be current has been killed by the time of
-exit from @code{save-current-buffer}, then it is not made current again,
-of course. Instead, whichever buffer was current just before exit
-remains current.
-@end defspec
-
-@defmac with-current-buffer buffer-or-name body@dots{}
-The @code{with-current-buffer} macro saves the identity of the current
-buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
-forms, and finally restores the buffer. The return value is the value
-of the last form in @var{body}. The current buffer is restored even
-in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
-Exits}).
-
-An error is signaled if @var{buffer-or-name} does not identify an
-existing buffer.
-@end defmac
-
-@defmac with-temp-buffer body@dots{}
-@anchor{Definition of with-temp-buffer}
-The @code{with-temp-buffer} macro evaluates the @var{body} forms
-with a temporary buffer as the current buffer. It saves the identity of
-the current buffer, creates a temporary buffer and makes it current,
-evaluates the @var{body} forms, and finally restores the previous
-current buffer while killing the temporary buffer. By default, undo
-information (@pxref{Undo}) is not recorded in the buffer created by
-this macro (but @var{body} can enable that, if needed).
-
-The return value is the value of the last form in @var{body}. You can
-return the contents of the temporary buffer by using
-@code{(buffer-string)} as the last form.
-
-The current buffer is restored even in case of an abnormal exit via
-@code{throw} or error (@pxref{Nonlocal Exits}).
-
-See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
-Writing to Files}.
-@end defmac
-
-@node Buffer Names
-@section Buffer Names
-@cindex buffer names
-
- Each buffer has a unique name, which is a string. Many of the
-functions that work on buffers accept either a buffer or a buffer name
-as an argument. Any argument called @var{buffer-or-name} is of this
-sort, and an error is signaled if it is neither a string nor a buffer.
-Any argument called @var{buffer} must be an actual buffer
-object, not a name.
-
-@cindex hidden buffers
-@cindex buffers without undo information
- Buffers that are ephemeral and generally uninteresting to the user
-have names starting with a space, so that the @code{list-buffers} and
-@code{buffer-menu} commands don't mention them (but if such a buffer
-visits a file, it @strong{is} mentioned). A name starting with
-space also initially disables recording undo information; see
-@ref{Undo}.
-
-@defun buffer-name &optional buffer
-This function returns the name of @var{buffer} as a string. If
-@var{buffer} is not supplied, it defaults to the current buffer.
-
-If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
-has been killed. @xref{Killing Buffers}.
-
-@example
-@group
-(buffer-name)
- @result{} "buffers.texi"
-@end group
-
-@group
-(setq foo (get-buffer "temp"))
- @result{} #<buffer temp>
-@end group
-@group
-(kill-buffer foo)
- @result{} nil
-@end group
-@group
-(buffer-name foo)
- @result{} nil
-@end group
-@group
-foo
- @result{} #<killed buffer>
-@end group
-@end example
-@end defun
-
-@deffn Command rename-buffer newname &optional unique
-This function renames the current buffer to @var{newname}. An error
-is signaled if @var{newname} is not a string.
-
-@c Emacs 19 feature
-Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
-already in use. However, if @var{unique} is non-@code{nil}, it modifies
-@var{newname} to make a name that is not in use. Interactively, you can
-make @var{unique} non-@code{nil} with a numeric prefix argument.
-(This is how the command @code{rename-uniquely} is implemented.)
-
-This function returns the name actually given to the buffer.
-@end deffn
-
-@defun get-buffer buffer-or-name
-This function returns the buffer specified by @var{buffer-or-name}.
-If @var{buffer-or-name} is a string and there is no buffer with that
-name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it
-is returned as given; that is not very useful, so the argument is usually
-a name. For example:
-
-@example
-@group
-(setq b (get-buffer "lewis"))
- @result{} #<buffer lewis>
-@end group
-@group
-(get-buffer b)
- @result{} #<buffer lewis>
-@end group
-@group
-(get-buffer "Frazzle-nots")
- @result{} nil
-@end group
-@end example
-
-See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
-@end defun
-
-@c Emacs 19 feature
-@defun generate-new-buffer-name starting-name &optional ignore
-This function returns a name that would be unique for a new buffer---but
-does not create the buffer. It starts with @var{starting-name}, and
-produces a name not currently in use for any buffer by appending a
-number inside of @samp{<@dots{}>}. It starts at 2 and keeps
-incrementing the number until it is not the name of an existing buffer.
-
-If the optional second argument @var{ignore} is non-@code{nil}, it
-should be a string, a potential buffer name. It means to consider
-that potential buffer acceptable, if it is tried, even it is the name
-of an existing buffer (which would normally be rejected). Thus, if
-buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and
-@samp{foo<4>} exist,
-
-@example
-(generate-new-buffer-name "foo")
- @result{} "foo<5>"
-(generate-new-buffer-name "foo" "foo<3>")
- @result{} "foo<3>"
-(generate-new-buffer-name "foo" "foo<6>")
- @result{} "foo<5>"
-@end example
-
-See the related function @code{generate-new-buffer} in @ref{Creating
-Buffers}.
-@end defun
-
-@node Buffer File Name
-@section Buffer File Name
-@cindex visited file
-@cindex buffer file name
-@cindex file name of buffer
-
- The @dfn{buffer file name} is the name of the file that is visited in
-that buffer. When a buffer is not visiting a file, its buffer file name
-is @code{nil}. Most of the time, the buffer name is the same as the
-nondirectory part of the buffer file name, but the buffer file name and
-the buffer name are distinct and can be set independently.
-@xref{Visiting Files}.
-
-@defun buffer-file-name &optional buffer
-This function returns the absolute file name of the file that
-@var{buffer} is visiting. If @var{buffer} is not visiting any file,
-@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not
-supplied, it defaults to the current buffer.
-
-@example
-@group
-(buffer-file-name (other-buffer))
- @result{} "/usr/user/lewis/manual/files.texi"
-@end group
-@end example
-@end defun
-
-@defvar buffer-file-name
-This buffer-local variable contains the name of the file being visited
-in the current buffer, or @code{nil} if it is not visiting a file. It
-is a permanent local variable, unaffected by
-@code{kill-all-local-variables}.
-
-@example
-@group
-buffer-file-name
- @result{} "/usr/user/lewis/manual/buffers.texi"
-@end group
-@end example
-
-It is risky to change this variable's value without doing various other
-things. Normally it is better to use @code{set-visited-file-name} (see
-below); some of the things done there, such as changing the buffer name,
-are not strictly necessary, but others are essential to avoid confusing
-Emacs.
-@end defvar
-
-@defvar buffer-file-truename
-This buffer-local variable holds the abbreviated truename of the file
-visited in the current buffer, or @code{nil} if no file is visited.
-It is a permanent local, unaffected by
-@code{kill-all-local-variables}. @xref{Truenames}, and
-@ref{Definition of abbreviate-file-name}.
-@end defvar
-
-@defvar buffer-file-number
-This buffer-local variable holds the file number and directory device
-number of the file visited in the current buffer, or @code{nil} if no
-file or a nonexistent file is visited. It is a permanent local,
-unaffected by @code{kill-all-local-variables}.
-
-The value is normally a list of the form @code{(@var{filenum}
-@var{devnum})}. This pair of numbers uniquely identifies the file among
-all files accessible on the system. See the function
-@code{file-attributes}, in @ref{File Attributes}, for more information
-about them.
-
-If @code{buffer-file-name} is the name of a symbolic link, then both
-numbers refer to the recursive target.
-@end defvar
-
-@defun get-file-buffer filename
-This function returns the buffer visiting file @var{filename}. If
-there is no such buffer, it returns @code{nil}. The argument
-@var{filename}, which must be a string, is expanded (@pxref{File Name
-Expansion}), then compared against the visited file names of all live
-buffers. Note that the buffer's @code{buffer-file-name} must match
-the expansion of @var{filename} exactly. This function will not
-recognize other names for the same file.
-
-@example
-@group
-(get-file-buffer "buffers.texi")
- @result{} #<buffer buffers.texi>
-@end group
-@end example
-
-In unusual circumstances, there can be more than one buffer visiting
-the same file name. In such cases, this function returns the first
-such buffer in the buffer list.
-@end defun
-
-@defun find-buffer-visiting filename &optional predicate
-This is like @code{get-file-buffer}, except that it can return any
-buffer visiting the file @emph{possibly under a different name}. That
-is, the buffer's @code{buffer-file-name} does not need to match the
-expansion of @var{filename} exactly, it only needs to refer to the
-same file. If @var{predicate} is non-@code{nil}, it should be a
-function of one argument, a buffer visiting @var{filename}. The
-buffer is only considered a suitable return value if @var{predicate}
-returns non-@code{nil}. If it can not find a suitable buffer to
-return, @code{find-buffer-visiting} returns @code{nil}.
-@end defun
-
-@deffn Command set-visited-file-name filename &optional no-query along-with-file
-If @var{filename} is a non-empty string, this function changes the
-name of the file visited in the current buffer to @var{filename}. (If the
-buffer had no visited file, this gives it one.) The @emph{next time}
-the buffer is saved it will go in the newly-specified file.
-
-This command marks the buffer as modified, since it does not (as far
-as Emacs knows) match the contents of @var{filename}, even if it
-matched the former visited file. It also renames the buffer to
-correspond to the new file name, unless the new name is already in
-use.
-
-If @var{filename} is @code{nil} or the empty string, that stands for
-``no visited file.'' In this case, @code{set-visited-file-name} marks
-the buffer as having no visited file, without changing the buffer's
-modified flag.
-
-Normally, this function asks the user for confirmation if there
-already is a buffer visiting @var{filename}. If @var{no-query} is
-non-@code{nil}, that prevents asking this question. If there already
-is a buffer visiting @var{filename}, and the user confirms or
-@var{query} is non-@code{nil}, this function makes the new buffer name
-unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
-
-If @var{along-with-file} is non-@code{nil}, that means to assume that
-the former visited file has been renamed to @var{filename}. In this
-case, the command does not change the buffer's modified flag, nor the
-buffer's recorded last file modification time as reported by
-@code{visited-file-modtime} (@pxref{Modification Time}). If
-@var{along-with-file} is @code{nil}, this function clears the recorded
-last file modification time, after which @code{visited-file-modtime}
-returns zero.
-
-@c Wordy to avoid overfull hbox. --rjc 16mar92
-When the function @code{set-visited-file-name} is called interactively, it
-prompts for @var{filename} in the minibuffer.
-@end deffn
-
-@defvar list-buffers-directory
-This buffer-local variable specifies a string to display in a buffer
-listing where the visited file name would go, for buffers that don't
-have a visited file name. Dired buffers use this variable.
-@end defvar
-
-@node Buffer Modification
-@section Buffer Modification
-@cindex buffer modification
-@cindex modification flag (of buffer)
-
- Emacs keeps a flag called the @dfn{modified flag} for each buffer, to
-record whether you have changed the text of the buffer. This flag is
-set to @code{t} whenever you alter the contents of the buffer, and
-cleared to @code{nil} when you save it. Thus, the flag shows whether
-there are unsaved changes. The flag value is normally shown in the mode
-line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving
-Buffers}) and auto-saving (@pxref{Auto-Saving}).
-
- Some Lisp programs set the flag explicitly. For example, the function
-@code{set-visited-file-name} sets the flag to @code{t}, because the text
-does not match the newly-visited file, even if it is unchanged from the
-file formerly visited.
-
- The functions that modify the contents of buffers are described in
-@ref{Text}.
-
-@defun buffer-modified-p &optional buffer
-This function returns @code{t} if the buffer @var{buffer} has been modified
-since it was last read in from a file or saved, or @code{nil}
-otherwise. If @var{buffer} is not supplied, the current buffer
-is tested.
-@end defun
-
-@defun set-buffer-modified-p flag
-This function marks the current buffer as modified if @var{flag} is
-non-@code{nil}, or as unmodified if the flag is @code{nil}.
-
-Another effect of calling this function is to cause unconditional
-redisplay of the mode line for the current buffer. In fact, the
-function @code{force-mode-line-update} works by doing this:
-
-@example
-@group
-(set-buffer-modified-p (buffer-modified-p))
-@end group
-@end example
-@end defun
-
-@defun restore-buffer-modified-p flag
-Like @code{set-buffer-modified-p}, but does not force redisplay
-of mode lines.
-@end defun
-
-@deffn Command not-modified &optional arg
-This command marks the current buffer as unmodified, and not needing
-to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as
-modified, so that it will be saved at the next suitable occasion.
-Interactively, @var{arg} is the prefix argument.
-
-Don't use this function in programs, since it prints a message in the
-echo area; use @code{set-buffer-modified-p} (above) instead.
-@end deffn
-
-@defun buffer-modified-tick &optional buffer
-This function returns @var{buffer}'s modification-count. This is a
-counter that increments every time the buffer is modified. If
-@var{buffer} is @code{nil} (or omitted), the current buffer is used.
-The counter can wrap around occasionally.
-@end defun
-
-@defun buffer-chars-modified-tick &optional buffer
-This function returns @var{buffer}'s character-change modification-count.
-Changes to text properties leave this counter unchanged; however, each
-time text is inserted or removed from the buffer, the counter is reset
-to the value that would be returned @code{buffer-modified-tick}.
-By comparing the values returned by two @code{buffer-chars-modified-tick}
-calls, you can tell whether a character change occurred in that buffer
-in between the calls. If @var{buffer} is @code{nil} (or omitted), the
-current buffer is used.
-@end defun
-
-@node Modification Time
-@comment node-name, next, previous, up
-@section Buffer Modification Time
-@cindex comparing file modification time
-@cindex modification time of buffer
-
- Suppose that you visit a file and make changes in its buffer, and
-meanwhile the file itself is changed on disk. At this point, saving the
-buffer would overwrite the changes in the file. Occasionally this may
-be what you want, but usually it would lose valuable information. Emacs
-therefore checks the file's modification time using the functions
-described below before saving the file. (@xref{File Attributes},
-for how to examine a file's modification time.)
-
-@defun verify-visited-file-modtime buffer
-This function compares what @var{buffer} has recorded for the
-modification time of its visited file against the actual modification
-time of the file as recorded by the operating system. The two should be
-the same unless some other process has written the file since Emacs
-visited or saved it.
-
-The function returns @code{t} if the last actual modification time and
-Emacs's recorded modification time are the same, @code{nil} otherwise.
-It also returns @code{t} if the buffer has no recorded last
-modification time, that is if @code{visited-file-modtime} would return
-zero.
-
-It always returns @code{t} for buffers that are not visiting a file,
-even if @code{visited-file-modtime} returns a non-zero value. For
-instance, it always returns @code{t} for dired buffers. It returns
-@code{t} for buffers that are visiting a file that does not exist and
-never existed, but @code{nil} for file-visiting buffers whose file has
-been deleted.
-@end defun
-
-@defun clear-visited-file-modtime
-This function clears out the record of the last modification time of
-the file being visited by the current buffer. As a result, the next
-attempt to save this buffer will not complain of a discrepancy in
-file modification times.
-
-This function is called in @code{set-visited-file-name} and other
-exceptional places where the usual test to avoid overwriting a changed
-file should not be done.
-@end defun
-
-@c Emacs 19 feature
-@defun visited-file-modtime
-This function returns the current buffer's recorded last file
-modification time, as a list of the form @code{(@var{high} @var{low})}.
-(This is the same format that @code{file-attributes} uses to return
-time values; see @ref{File Attributes}.)
-
-If the buffer has no recorded last modification time, this function
-returns zero. This case occurs, for instance, if the buffer is not
-visiting a file or if the time has been explicitly cleared by
-@code{clear-visited-file-modtime}. Note, however, that
-@code{visited-file-modtime} returns a list for some non-file buffers
-too. For instance, in a Dired buffer listing a directory, it returns
-the last modification time of that directory, as recorded by Dired.
-
-For a new buffer visiting a not yet existing file, @var{high} is
-@minus{}1 and @var{low} is 65535, that is,
-@ifnottex
-@w{2**16 - 1.}
-@end ifnottex
-@tex
-@math{2^{16}-1}.
-@end tex
-@end defun
-
-@c Emacs 19 feature
-@defun set-visited-file-modtime &optional time
-This function updates the buffer's record of the last modification time
-of the visited file, to the value specified by @var{time} if @var{time}
-is not @code{nil}, and otherwise to the last modification time of the
-visited file.
-
-If @var{time} is neither @code{nil} nor zero, it should have the form
-@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
-either case containing two integers, each of which holds 16 bits of the
-time.
-
-This function is useful if the buffer was not read from the file
-normally, or if the file itself has been changed for some known benign
-reason.
-@end defun
-
-@defun ask-user-about-supersession-threat filename
-This function is used to ask a user how to proceed after an attempt to
-modify an buffer visiting file @var{filename} when the file is newer
-than the buffer text. Emacs detects this because the modification
-time of the file on disk is newer than the last save-time of the
-buffer. This means some other program has probably altered the file.
-
-@kindex file-supersession
-Depending on the user's answer, the function may return normally, in
-which case the modification of the buffer proceeds, or it may signal a
-@code{file-supersession} error with data @code{(@var{filename})}, in which
-case the proposed buffer modification is not allowed.
-
-This function is called automatically by Emacs on the proper
-occasions. It exists so you can customize Emacs by redefining it.
-See the file @file{userlock.el} for the standard definition.
-
-See also the file locking mechanism in @ref{File Locks}.
-@end defun
-
-@node Read Only Buffers
-@section Read-Only Buffers
-@cindex read-only buffer
-@cindex buffer, read-only
-
- If a buffer is @dfn{read-only}, then you cannot change its contents,
-although you may change your view of the contents by scrolling and
-narrowing.
-
- Read-only buffers are used in two kinds of situations:
-
-@itemize @bullet
-@item
-A buffer visiting a write-protected file is normally read-only.
-
-Here, the purpose is to inform the user that editing the buffer with the
-aim of saving it in the file may be futile or undesirable. The user who
-wants to change the buffer text despite this can do so after clearing
-the read-only flag with @kbd{C-x C-q}.
-
-@item
-Modes such as Dired and Rmail make buffers read-only when altering the
-contents with the usual editing commands would probably be a mistake.
-
-The special commands of these modes bind @code{buffer-read-only} to
-@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
-@code{t} around the places where they themselves change the text.
-@end itemize
-
-@defvar buffer-read-only
-This buffer-local variable specifies whether the buffer is read-only.
-The buffer is read-only if this variable is non-@code{nil}.
-@end defvar
-
-@defvar inhibit-read-only
-If this variable is non-@code{nil}, then read-only buffers and,
-depending on the actual value, some or all read-only characters may be
-modified. Read-only characters in a buffer are those that have
-non-@code{nil} @code{read-only} properties (either text properties or
-overlay properties). @xref{Special Properties}, for more information
-about text properties. @xref{Overlays}, for more information about
-overlays and their properties.
-
-If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
-properties have no effect. If @code{inhibit-read-only} is a list, then
-@code{read-only} character properties have no effect if they are members
-of the list (comparison is done with @code{eq}).
-@end defvar
-
-@deffn Command toggle-read-only &optional arg
-This command toggles whether the current buffer is read-only. It is
-intended for interactive use; do not use it in programs. At any given
-point in a program, you should know whether you want the read-only flag
-on or off; so you can set @code{buffer-read-only} explicitly to the
-proper value, @code{t} or @code{nil}.
-
-If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
-@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
-@code{nil} otherwise. @xref{Prefix Command Arguments}.
-@end deffn
-
-@defun barf-if-buffer-read-only
-This function signals a @code{buffer-read-only} error if the current
-buffer is read-only. @xref{Using Interactive}, for another way to
-signal an error if the current buffer is read-only.
-@end defun
-
-@node The Buffer List
-@section The Buffer List
-@cindex buffer list
-
- The @dfn{buffer list} is a list of all live buffers. The order of
-the buffers in the list is based primarily on how recently each buffer
-has been displayed in a window. Several functions, notably
-@code{other-buffer}, use this ordering. A buffer list displayed for
-the user also follows this order.
-
- Creating a buffer adds it to the end of the buffer list, and killing
-a buffer removes it. Buffers move to the front of the list when they
-are selected for display in a window (@pxref{Displaying Buffers}), and
-to the end when they are buried (see @code{bury-buffer}, below).
-There are no functions available to the Lisp programmer which directly
-manipulate the buffer list.
-
- In addition to the fundamental Emacs buffer list, each frame has its
-own version of the buffer list, in which the buffers that have been
-selected in that frame come first, starting with the buffers most
-recently selected @emph{in that frame}. (This order is recorded in
-@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer
-Parameters}.) The buffers that were never selected in @var{frame} come
-afterward, ordered according to the fundamental Emacs buffer list.
-
-@defun buffer-list &optional frame
-This function returns the buffer list, including all buffers, even those
-whose names begin with a space. The elements are actual buffers, not
-their names.
-
-If @var{frame} is a frame, this returns @var{frame}'s buffer list. If
-@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
-all the buffers appear in order of most recent selection, regardless of
-which frames they were selected in.
-
-@example
-@group
-(buffer-list)
- @result{} (#<buffer buffers.texi>
- #<buffer *Minibuf-1*> #<buffer buffer.c>
- #<buffer *Help*> #<buffer TAGS>)
-@end group
-
-@group
-;; @r{Note that the name of the minibuffer}
-;; @r{begins with a space!}
-(mapcar (function buffer-name) (buffer-list))
- @result{} ("buffers.texi" " *Minibuf-1*"
- "buffer.c" "*Help*" "TAGS")
-@end group
-@end example
-@end defun
-
- The list that @code{buffer-list} returns is constructed specifically
-by @code{buffer-list}; it is not an internal Emacs data structure, and
-modifying it has no effect on the order of buffers. If you want to
-change the order of buffers in the frame-independent buffer list, here
-is an easy way:
-
-@example
-(defun reorder-buffer-list (new-list)
- (while new-list
- (bury-buffer (car new-list))
- (setq new-list (cdr new-list))))
-@end example
-
- With this method, you can specify any order for the list, but there is
-no danger of losing a buffer or adding something that is not a valid
-live buffer.
-
- To change the order or value of a frame's buffer list, set the frame's
-@code{buffer-list} frame parameter with @code{modify-frame-parameters}
-(@pxref{Parameter Access}).
-
-@defun other-buffer &optional buffer visible-ok frame
-This function returns the first buffer in the buffer list other than
-@var{buffer}. Usually this is the buffer selected most recently (in
-frame @var{frame} or else the currently selected frame, @pxref{Input
-Focus}), aside from @var{buffer}. Buffers whose names start with a
-space are not considered at all.
-
-If @var{buffer} is not supplied (or if it is not a buffer), then
-@code{other-buffer} returns the first buffer in the selected frame's
-buffer list that is not now visible in any window in a visible frame.
-
-If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
-then @code{other-buffer} uses that predicate to decide which buffers to
-consider. It calls the predicate once for each buffer, and if the value
-is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}.
-
-@c Emacs 19 feature
-If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
-a buffer visible in any window on any visible frame, except as a last
-resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
-whether a buffer is displayed somewhere or not.
-
-If no suitable buffer exists, the buffer @samp{*scratch*} is returned
-(and created, if necessary).
-@end defun
-
-@deffn Command bury-buffer &optional buffer-or-name
-This function puts @var{buffer-or-name} at the end of the buffer list,
-without changing the order of any of the other buffers on the list.
-This buffer therefore becomes the least desirable candidate for
-@code{other-buffer} to return. The argument can be either a buffer
-itself or the name of one.
-
-@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
-as well as the frame-independent Emacs buffer list; therefore, the
-buffer that you bury will come last in the value of @code{(buffer-list
-@var{frame})} and in the value of @code{(buffer-list nil)}.
-
-If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer. In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window. But if the buffer is
-displayed in some other window, it remains displayed there.
-
-To replace a buffer in all the windows that display it, use
-@code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
-@end deffn
-
-@node Creating Buffers
-@section Creating Buffers
-@cindex creating buffers
-@cindex buffers, creating
-
- This section describes the two primitives for creating buffers.
-@code{get-buffer-create} creates a buffer if it finds no existing buffer
-with the specified name; @code{generate-new-buffer} always creates a new
-buffer and gives it a unique name.
-
- Other functions you can use to create buffers include
-@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
-@code{create-file-buffer} (@pxref{Visiting Files}). Starting a
-subprocess can also create a buffer (@pxref{Processes}).
-
-@defun get-buffer-create name
-This function returns a buffer named @var{name}. It returns a live
-buffer with that name, if one exists; otherwise, it creates a new
-buffer. The buffer does not become the current buffer---this function
-does not change which buffer is current.
-
-If @var{name} is a buffer instead of a string, it is returned, even if
-it is dead. An error is signaled if @var{name} is neither a string
-nor a buffer.
-
-@example
-@group
-(get-buffer-create "foo")
- @result{} #<buffer foo>
-@end group
-@end example
-
-The major mode for a newly created buffer is set to Fundamental mode.
-(The variable @code{default-major-mode} is handled at a higher level;
-see @ref{Auto Major Mode}.) If the name begins with a space, the
-buffer initially disables undo information recording (@pxref{Undo}).
-@end defun
-
-@defun generate-new-buffer name
-This function returns a newly created, empty buffer, but does not make
-it current. If there is no buffer named @var{name}, then that is the
-name of the new buffer. If that name is in use, this function adds
-suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
-integer. It tries successive integers starting with 2 until it finds an
-available name.
-
-An error is signaled if @var{name} is not a string.
-
-@example
-@group
-(generate-new-buffer "bar")
- @result{} #<buffer bar>
-@end group
-@group
-(generate-new-buffer "bar")
- @result{} #<buffer bar<2>>
-@end group
-@group
-(generate-new-buffer "bar")
- @result{} #<buffer bar<3>>
-@end group
-@end example
-
-The major mode for the new buffer is set to Fundamental mode. The
-variable @code{default-major-mode} is handled at a higher level.
-@xref{Auto Major Mode}.
-
-See the related function @code{generate-new-buffer-name} in @ref{Buffer
-Names}.
-@end defun
-
-@node Killing Buffers
-@section Killing Buffers
-@cindex killing buffers
-@cindex buffers, killing
-
- @dfn{Killing a buffer} makes its name unknown to Emacs and makes the
-memory space it occupied available for other use.
-
- The buffer object for the buffer that has been killed remains in
-existence as long as anything refers to it, but it is specially marked
-so that you cannot make it current or display it. Killed buffers retain
-their identity, however; if you kill two distinct buffers, they remain
-distinct according to @code{eq} although both are dead.
-
- If you kill a buffer that is current or displayed in a window, Emacs
-automatically selects or displays some other buffer instead. This means
-that killing a buffer can in general change the current buffer.
-Therefore, when you kill a buffer, you should also take the precautions
-associated with changing the current buffer (unless you happen to know
-that the buffer being killed isn't current). @xref{Current Buffer}.
-
- If you kill a buffer that is the base buffer of one or more indirect
-buffers, the indirect buffers are automatically killed as well.
-
- The @code{buffer-name} of a killed buffer is @code{nil}. You can use
-this feature to test whether a buffer has been killed:
-
-@example
-@group
-(defun buffer-killed-p (buffer)
- "Return t if BUFFER is killed."
- (not (buffer-name buffer)))
-@end group
-@end example
-
-@deffn Command kill-buffer buffer-or-name
-This function kills the buffer @var{buffer-or-name}, freeing all its
-memory for other uses or to be returned to the operating system. If
-@var{buffer-or-name} is @code{nil}, it kills the current buffer.
-
-Any processes that have this buffer as the @code{process-buffer} are
-sent the @code{SIGHUP} signal, which normally causes them to terminate.
-(The basic meaning of @code{SIGHUP} is that a dialup line has been
-disconnected.) @xref{Signals to Processes}.
-
-If the buffer is visiting a file and contains unsaved changes,
-@code{kill-buffer} asks the user to confirm before the buffer is killed.
-It does this even if not called interactively. To prevent the request
-for confirmation, clear the modified flag before calling
-@code{kill-buffer}. @xref{Buffer Modification}.
-
-Killing a buffer that is already dead has no effect.
-
-This function returns @code{t} if it actually killed the buffer. It
-returns @code{nil} if the user refuses to confirm or if
-@var{buffer-or-name} was already dead.
-
-@smallexample
-(kill-buffer "foo.unchanged")
- @result{} t
-(kill-buffer "foo.changed")
-
----------- Buffer: Minibuffer ----------
-Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
----------- Buffer: Minibuffer ----------
-
- @result{} t
-@end smallexample
-@end deffn
-
-@defvar kill-buffer-query-functions
-After confirming unsaved changes, @code{kill-buffer} calls the functions
-in the list @code{kill-buffer-query-functions}, in order of appearance,
-with no arguments. The buffer being killed is the current buffer when
-they are called. The idea of this feature is that these functions will
-ask for confirmation from the user. If any of them returns @code{nil},
-@code{kill-buffer} spares the buffer's life.
-@end defvar
-
-@defvar kill-buffer-hook
-This is a normal hook run by @code{kill-buffer} after asking all the
-questions it is going to ask, just before actually killing the buffer.
-The buffer to be killed is current when the hook functions run.
-@xref{Hooks}. This variable is a permanent local, so its local binding
-is not cleared by changing major modes.
-@end defvar
-
-@defvar buffer-offer-save
-This variable, if non-@code{nil} in a particular buffer, tells
-@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the
-second optional argument to that function is @code{t}) to offer to
-save that buffer, just as they offer to save file-visiting buffers.
-@xref{Definition of save-some-buffers}. The variable
-@code{buffer-offer-save} automatically becomes buffer-local when set
-for any reason. @xref{Buffer-Local Variables}.
-@end defvar
-
-@defvar buffer-save-without-query
-This variable, if non-@code{nil} in a particular buffer, tells
-@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save
-this buffer (if it's modified) without asking the user. The variable
-automatically becomes buffer-local when set for any reason.
-@end defvar
-
-@defun buffer-live-p object
-This function returns @code{t} if @var{object} is a buffer which has
-not been killed, @code{nil} otherwise.
-@end defun
-
-@node Indirect Buffers
-@section Indirect Buffers
-@cindex indirect buffers
-@cindex base buffer
-
- An @dfn{indirect buffer} shares the text of some other buffer, which
-is called the @dfn{base buffer} of the indirect buffer. In some ways it
-is the analogue, for buffers, of a symbolic link among files. The base
-buffer may not itself be an indirect buffer.
-
- The text of the indirect buffer is always identical to the text of its
-base buffer; changes made by editing either one are visible immediately
-in the other. This includes the text properties as well as the characters
-themselves.
-
- In all other respects, the indirect buffer and its base buffer are
-completely separate. They have different names, independent values of
-point, independent narrowing, independent markers and overlays (though
-inserting or deleting text in either buffer relocates the markers and
-overlays for both), independent major modes, and independent
-buffer-local variable bindings.
-
- An indirect buffer cannot visit a file, but its base buffer can. If
-you try to save the indirect buffer, that actually saves the base
-buffer.
-
- Killing an indirect buffer has no effect on its base buffer. Killing
-the base buffer effectively kills the indirect buffer in that it cannot
-ever again be the current buffer.
-
-@deffn Command make-indirect-buffer base-buffer name &optional clone
-This creates and returns an indirect buffer named @var{name} whose
-base buffer is @var{base-buffer}. The argument @var{base-buffer} may
-be a live buffer or the name (a string) of an existing buffer. If
-@var{name} is the name of an existing buffer, an error is signaled.
-
-If @var{clone} is non-@code{nil}, then the indirect buffer originally
-shares the ``state'' of @var{base-buffer} such as major mode, minor
-modes, buffer local variables and so on. If @var{clone} is omitted
-or @code{nil} the indirect buffer's state is set to the default state
-for new buffers.
-
-If @var{base-buffer} is an indirect buffer, its base buffer is used as
-the base for the new buffer. If, in addition, @var{clone} is
-non-@code{nil}, the initial state is copied from the actual base
-buffer, not from @var{base-buffer}.
-@end deffn
-
-@defun clone-indirect-buffer newname display-flag &optional norecord
-This function creates and returns a new indirect buffer that shares
-the current buffer's base buffer and copies the rest of the current
-buffer's attributes. (If the current buffer is not indirect, it is
-used as the base buffer.)
-
-If @var{display-flag} is non-@code{nil}, that means to display the new
-buffer by calling @code{pop-to-buffer}. If @var{norecord} is
-non-@code{nil}, that means not to put the new buffer to the front of
-the buffer list.
-@end defun
-
-@defun buffer-base-buffer &optional buffer
-This function returns the base buffer of @var{buffer}, which defaults
-to the current buffer. If @var{buffer} is not indirect, the value is
-@code{nil}. Otherwise, the value is another buffer, which is never an
-indirect buffer.
-@end defun
-
-@node Buffer Gap
-@section The Buffer Gap
-
- Emacs buffers are implemented using an invisible @dfn{gap} to make
-insertion and deletion faster. Insertion works by filling in part of
-the gap, and deletion adds to the gap. Of course, this means that the
-gap must first be moved to the locus of the insertion or deletion.
-Emacs moves the gap only when you try to insert or delete. This is why
-your first editing command in one part of a large buffer, after
-previously editing in another far-away part, sometimes involves a
-noticeable delay.
-
- This mechanism works invisibly, and Lisp code should never be affected
-by the gap's current location, but these functions are available for
-getting information about the gap status.
-
-@defun gap-position
-This function returns the current gap position in the current buffer.
-@end defun
-
-@defun gap-size
-This function returns the current gap size of the current buffer.
-@end defun
-
-@ignore
- arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
-@end ignore
+++ /dev/null
-@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.
-* 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.
-
-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:
-
-@example
-@group
-;; @r{Here's the usual way to use @code{interactive-p}.}
-(defun foo ()
- (interactive)
- (when (interactive-p)
- (message "foo")))
- @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
-@end group
-
-@group
-;; @r{Type @kbd{M-x foo}.}
- @print{} foo
-@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}.
-
-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.
-@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.
-
-@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 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 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
-(mouse-1 (#<window 18 on NEWS> 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 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
-(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
- (#<window 18 on NEWS> 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 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
-(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
- (#<window 20 on carlton-sanskrit.tex> 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
- (#<window 6 on NEWS> 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
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/compile
-@node Byte Compilation, Advising Functions, Loading, Top
-@chapter Byte Compilation
-@cindex byte compilation
-@cindex byte-code
-@cindex compilation (Emacs Lisp)
-
- Emacs Lisp has a @dfn{compiler} that translates functions written
-in Lisp into a special representation called @dfn{byte-code} that can be
-executed more efficiently. The compiler replaces Lisp function
-definitions with byte-code. When a byte-code function is called, its
-definition is evaluated by the @dfn{byte-code interpreter}.
-
- Because the byte-compiled code is evaluated by the byte-code
-interpreter, instead of being executed directly by the machine's
-hardware (as true compiled code is), byte-code is completely
-transportable from machine to machine without recompilation. It is not,
-however, as fast as true compiled code.
-
- Compiling a Lisp file with the Emacs byte compiler always reads the
-file as multibyte text, even if Emacs was started with @samp{--unibyte},
-unless the file specifies otherwise. This is so that compilation gives
-results compatible with running the same file without compilation.
-@xref{Loading Non-ASCII}.
-
- In general, any version of Emacs can run byte-compiled code produced
-by recent earlier versions of Emacs, but the reverse is not true.
-
-@vindex no-byte-compile
- If you do not want a Lisp file to be compiled, ever, put a file-local
-variable binding for @code{no-byte-compile} into it, like this:
-
-@example
-;; -*-no-byte-compile: t; -*-
-@end example
-
- @xref{Compilation Errors}, for how to investigate errors occurring in
-byte compilation.
-
-@menu
-* 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.
-@end menu
-
-@node Speed of Byte-Code
-@section Performance of Byte-Compiled Code
-
- A byte-compiled function is not as efficient as a primitive function
-written in C, but runs much faster than the version written in Lisp.
-Here is an example:
-
-@example
-@group
-(defun silly-loop (n)
- "Return time before and after N iterations of a loop."
- (let ((t1 (current-time-string)))
- (while (> (setq n (1- n))
- 0))
- (list t1 (current-time-string))))
-@result{} silly-loop
-@end group
-
-@group
-(silly-loop 100000)
-@result{} ("Fri Mar 18 17:25:57 1994"
- "Fri Mar 18 17:26:28 1994") ; @r{31 seconds}
-@end group
-
-@group
-(byte-compile 'silly-loop)
-@result{} @r{[Compiled code not shown]}
-@end group
-
-@group
-(silly-loop 100000)
-@result{} ("Fri Mar 18 17:26:52 1994"
- "Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
-@end group
-@end example
-
- In this example, the interpreted code required 31 seconds to run,
-whereas the byte-compiled code required 6 seconds. These results are
-representative, but actual results will vary greatly.
-
-@node Compilation Functions
-@comment node-name, next, previous, up
-@section The Compilation Functions
-@cindex compilation functions
-
- You can byte-compile an individual function or macro definition with
-the @code{byte-compile} function. You can compile a whole file with
-@code{byte-compile-file}, or several files with
-@code{byte-recompile-directory} or @code{batch-byte-compile}.
-
- The byte compiler produces error messages and warnings about each file
-in a buffer called @samp{*Compile-Log*}. These report things in your
-program that suggest a problem but are not necessarily erroneous.
-
-@cindex macro compilation
- Be careful when writing macro calls in files that you may someday
-byte-compile. Macro calls are expanded when they are compiled, so the
-macros must already be defined for proper compilation. For more
-details, see @ref{Compiling Macros}. If a program does not work the
-same way when compiled as it does when interpreted, erroneous macro
-definitions are one likely cause (@pxref{Problems with Macros}).
-Inline (@code{defsubst}) functions are less troublesome; if you
-compile a call to such a function before its definition is known, the
-call will still work right, it will just run slower.
-
- Normally, compiling a file does not evaluate the file's contents or
-load the file. But it does execute any @code{require} calls at top
-level in the file. One way to ensure that necessary macro definitions
-are available during compilation is to require the file that defines
-them (@pxref{Named Features}). To avoid loading the macro definition files
-when someone @emph{runs} the compiled program, write
-@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
-During Compile}).
-
-@defun byte-compile symbol
-This function byte-compiles the function definition of @var{symbol},
-replacing the previous definition with the compiled one. The function
-definition of @var{symbol} must be the actual code for the function;
-i.e., the compiler does not follow indirection to another symbol.
-@code{byte-compile} returns the new, compiled definition of
-@var{symbol}.
-
- If @var{symbol}'s definition is a byte-code function object,
-@code{byte-compile} does nothing and returns @code{nil}. Lisp records
-only one function definition for any symbol, and if that is already
-compiled, non-compiled code is not available anywhere. So there is no
-way to ``compile the same definition again.''
-
-@example
-@group
-(defun factorial (integer)
- "Compute factorial of INTEGER."
- (if (= 1 integer) 1
- (* integer (factorial (1- integer)))))
-@result{} factorial
-@end group
-
-@group
-(byte-compile 'factorial)
-@result{}
-#[(integer)
- "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
- [integer 1 * factorial]
- 4 "Compute factorial of INTEGER."]
-@end group
-@end example
-
-@noindent
-The result is a byte-code function object. The string it contains is
-the actual byte-code; each character in it is an instruction or an
-operand of an instruction. The vector contains all the constants,
-variable names and function names used by the function, except for
-certain primitives that are coded as special instructions.
-
-If the argument to @code{byte-compile} is a @code{lambda} expression,
-it returns the corresponding compiled code, but does not store
-it anywhere.
-@end defun
-
-@deffn Command compile-defun &optional arg
-This command reads the defun containing point, compiles it, and
-evaluates the result. If you use this on a defun that is actually a
-function definition, the effect is to install a compiled version of that
-function.
-
-@code{compile-defun} normally displays the result of evaluation in the
-echo area, but if @var{arg} is non-@code{nil}, it inserts the result
-in the current buffer after the form it compiled.
-@end deffn
-
-@deffn Command byte-compile-file filename &optional load
-This function compiles a file of Lisp code named @var{filename} into a
-file of byte-code. The output file's name is made by changing the
-@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
-@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
-
-Compilation works by reading the input file one form at a time. If it
-is a definition of a function or macro, the compiled function or macro
-definition is written out. Other forms are batched together, then each
-batch is compiled, and written so that its compiled code will be
-executed when the file is read. All comments are discarded when the
-input file is read.
-
-This command returns @code{t} if there were no errors and @code{nil}
-otherwise. When called interactively, it prompts for the file name.
-
-If @var{load} is non-@code{nil}, this command loads the compiled file
-after compiling it. Interactively, @var{load} is the prefix argument.
-
-@example
-@group
-% ls -l push*
--rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-@end group
-
-@group
-(byte-compile-file "~/emacs/push.el")
- @result{} t
-@end group
-
-@group
-% ls -l push*
--rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
--rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
-@end group
-@end example
-@end deffn
-
-@deffn Command byte-recompile-directory directory &optional flag force
-@cindex library compilation
-This command recompiles every @samp{.el} file in @var{directory} (or
-its subdirectories) that needs recompilation. A file needs
-recompilation if a @samp{.elc} file exists but is older than the
-@samp{.el} file.
-
-When a @samp{.el} file has no corresponding @samp{.elc} file,
-@var{flag} says what to do. If it is @code{nil}, this command ignores
-these files. If @var{flag} is 0, it compiles them. If it is neither
-@code{nil} nor 0, it asks the user whether to compile each such file,
-and asks about each subdirectory as well.
-
-Interactively, @code{byte-recompile-directory} prompts for
-@var{directory} and @var{flag} is the prefix argument.
-
-If @var{force} is non-@code{nil}, this command recompiles every
-@samp{.el} file that has a @samp{.elc} file.
-
-The returned value is unpredictable.
-@end deffn
-
-@defun batch-byte-compile &optional noforce
-This function runs @code{byte-compile-file} on files specified on the
-command line. This function must be used only in a batch execution of
-Emacs, as it kills Emacs on completion. An error in one file does not
-prevent processing of subsequent files, but no output file will be
-generated for it, and the Emacs process will terminate with a nonzero
-status code.
-
-If @var{noforce} is non-@code{nil}, this function does not recompile
-files that have an up-to-date @samp{.elc} file.
-
-@example
-% emacs -batch -f batch-byte-compile *.el
-@end example
-@end defun
-
-@defun byte-code code-string data-vector max-stack
-@cindex byte-code interpreter
-This function actually interprets byte-code. A byte-compiled function
-is actually defined with a body that calls @code{byte-code}. Don't call
-this function yourself---only the byte compiler knows how to generate
-valid calls to this function.
-
-In Emacs version 18, byte-code was always executed by way of a call to
-the function @code{byte-code}. Nowadays, byte-code is usually executed
-as part of a byte-code function object, and only rarely through an
-explicit call to @code{byte-code}.
-@end defun
-
-@node Docs and Compilation
-@section Documentation Strings and Compilation
-@cindex dynamic loading of documentation
-
- Functions and variables loaded from a byte-compiled file access their
-documentation strings dynamically from the file whenever needed. This
-saves space within Emacs, and makes loading faster because the
-documentation strings themselves need not be processed while loading the
-file. Actual access to the documentation strings becomes slower as a
-result, but this normally is not enough to bother users.
-
- Dynamic access to documentation strings does have drawbacks:
-
-@itemize @bullet
-@item
-If you delete or move the compiled file after loading it, Emacs can no
-longer access the documentation strings for the functions and variables
-in the file.
-
-@item
-If you alter the compiled file (such as by compiling a new version),
-then further access to documentation strings in this file will
-probably give nonsense results.
-@end itemize
-
- If your site installs Emacs following the usual procedures, these
-problems will never normally occur. Installing a new version uses a new
-directory with a different name; as long as the old version remains
-installed, its files will remain unmodified in the places where they are
-expected to be.
-
- However, if you have built Emacs yourself and use it from the
-directory where you built it, you will experience this problem
-occasionally if you edit and recompile Lisp files. When it happens, you
-can cure the problem by reloading the file after recompiling it.
-
- You can turn off this feature at compile time by setting
-@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
-mainly if you expect to change the file, and you want Emacs processes
-that have already loaded it to keep working when the file changes.
-You can do this globally, or for one source file by specifying a
-file-local binding for the variable. One way to do that is by adding
-this string to the file's first line:
-
-@example
--*-byte-compile-dynamic-docstrings: nil;-*-
-@end example
-
-@defvar byte-compile-dynamic-docstrings
-If this is non-@code{nil}, the byte compiler generates compiled files
-that are set up for dynamic loading of documentation strings.
-@end defvar
-
-@cindex @samp{#@@@var{count}}
-@cindex @samp{#$}
- The dynamic documentation string feature writes compiled files that
-use a special Lisp reader construct, @samp{#@@@var{count}}. This
-construct skips the next @var{count} characters. It also uses the
-@samp{#$} construct, which stands for ``the name of this file, as a
-string.'' It is usually best not to use these constructs in Lisp source
-files, since they are not designed to be clear to humans reading the
-file.
-
-@node Dynamic Loading
-@section Dynamic Loading of Individual Functions
-
-@cindex dynamic loading of functions
-@cindex lazy loading
- When you compile a file, you can optionally enable the @dfn{dynamic
-function loading} feature (also known as @dfn{lazy loading}). With
-dynamic function loading, loading the file doesn't fully read the
-function definitions in the file. Instead, each function definition
-contains a place-holder which refers to the file. The first time each
-function is called, it reads the full definition from the file, to
-replace the place-holder.
-
- The advantage of dynamic function loading is that loading the file
-becomes much faster. This is a good thing for a file which contains
-many separate user-callable functions, if using one of them does not
-imply you will probably also use the rest. A specialized mode which
-provides many keyboard commands often has that usage pattern: a user may
-invoke the mode, but use only a few of the commands it provides.
-
- The dynamic loading feature has certain disadvantages:
-
-@itemize @bullet
-@item
-If you delete or move the compiled file after loading it, Emacs can no
-longer load the remaining function definitions not already loaded.
-
-@item
-If you alter the compiled file (such as by compiling a new version),
-then trying to load any function not already loaded will usually yield
-nonsense results.
-@end itemize
-
- These problems will never happen in normal circumstances with
-installed Emacs files. But they are quite likely to happen with Lisp
-files that you are changing. The easiest way to prevent these problems
-is to reload the new compiled file immediately after each recompilation.
-
- The byte compiler uses the dynamic function loading feature if the
-variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
-time. Do not set this variable globally, since dynamic loading is
-desirable only for certain files. Instead, enable the feature for
-specific source files with file-local variable bindings. For example,
-you could do it by writing this text in the source file's first line:
-
-@example
--*-byte-compile-dynamic: t;-*-
-@end example
-
-@defvar byte-compile-dynamic
-If this is non-@code{nil}, the byte compiler generates compiled files
-that are set up for dynamic function loading.
-@end defvar
-
-@defun fetch-bytecode function
-If @var{function} is a byte-code function object, this immediately
-finishes loading the byte code of @var{function} from its
-byte-compiled file, if it is not fully loaded already. Otherwise,
-it does nothing. It always returns @var{function}.
-@end defun
-
-@node Eval During Compile
-@section Evaluation During Compilation
-
- These features permit you to write code to be evaluated during
-compilation of a program.
-
-@defspec eval-and-compile body@dots{}
-This form marks @var{body} to be evaluated both when you compile the
-containing code and when you run it (whether compiled or not).
-
-You can get a similar result by putting @var{body} in a separate file
-and referring to that file with @code{require}. That method is
-preferable when @var{body} is large. Effectively @code{require} is
-automatically @code{eval-and-compile}, the package is loaded both when
-compiling and executing.
-
-@code{autoload} is also effectively @code{eval-and-compile} too. It's
-recognized when compiling, so uses of such a function don't produce
-``not known to be defined'' warnings.
-
-Most uses of @code{eval-and-compile} are fairly sophisticated.
-
-If a macro has a helper function to build its result, and that macro
-is used both locally and outside the package, then
-@code{eval-and-compile} should be used to get the helper both when
-compiling and then later when running.
-
-If functions are defined programmatically (with @code{fset} say), then
-@code{eval-and-compile} can be used to have that done at compile-time
-as well as run-time, so calls to those functions are checked (and
-warnings about ``not known to be defined'' suppressed).
-@end defspec
-
-@defspec eval-when-compile body@dots{}
-This form marks @var{body} to be evaluated at compile time but not when
-the compiled program is loaded. The result of evaluation by the
-compiler becomes a constant which appears in the compiled program. If
-you load the source file, rather than compiling it, @var{body} is
-evaluated normally.
-
-@cindex compile-time constant
-If you have a constant that needs some calculation to produce,
-@code{eval-when-compile} can do that at compile-time. For example,
-
-@lisp
-(defvar my-regexp
- (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
-@end lisp
-
-@cindex macros, at compile time
-If you're using another package, but only need macros from it (the
-byte compiler will expand those), then @code{eval-when-compile} can be
-used to load it for compiling, but not executing. For example,
-
-@lisp
-(eval-when-compile
- (require 'my-macro-package)) ;; only macros needed from this
-@end lisp
-
-The same sort of thing goes for macros and @code{defsubst} functions
-defined locally and only for use within the file. They are needed for
-compiling the file, but in most cases they are not needed for
-execution of the compiled file. For example,
-
-@lisp
-(eval-when-compile
- (unless (fboundp 'some-new-thing)
- (defmacro 'some-new-thing ()
- (compatibility code))))
-@end lisp
-
-@noindent
-This is often good for code that's only a fallback for compatibility
-with other versions of Emacs.
-
-@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common
-Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the
-Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
-to what @code{eval-when-compile} does.
-@end defspec
-
-@node Compiler Errors
-@section Compiler Errors
-@cindex compiler errors
-
- Byte compilation outputs all errors and warnings into the buffer
-@samp{*Compile-Log*}. The messages include file names and line
-numbers that identify the location of the problem. The usual Emacs
-commands for operating on compiler diagnostics work properly on
-these messages.
-
- However, the warnings about functions that were used but not
-defined are always ``located'' at the end of the file, so these
-commands won't find the places they are really used. To do that,
-you must search for the function names.
-
- You can suppress the compiler warning for calling an undefined
-function @var{func} by conditionalizing the function call on an
-@code{fboundp} test, like this:
-
-@example
-(if (fboundp '@var{func}) ...(@var{func} ...)...)
-@end example
-
-@noindent
-The call to @var{func} must be in the @var{then-form} of the
-@code{if}, and @var{func} must appear quoted in the call to
-@code{fboundp}. (This feature operates for @code{cond} as well.)
-
- Likewise, you can suppress a compiler warning for an unbound variable
-@var{variable} by conditionalizing its use on a @code{boundp} test,
-like this:
-
-@example
-(if (boundp '@var{variable}) ...@var{variable}...)
-@end example
-
-@noindent
-The reference to @var{variable} must be in the @var{then-form} of the
-@code{if}, and @var{variable} must appear quoted in the call to
-@code{boundp}.
-
- You can suppress any compiler warnings using the construct
-@code{with-no-warnings}:
-
-@c This is implemented with a defun, but conceptually it is
-@c a special form.
-
-@defspec with-no-warnings body@dots{}
-In execution, this is equivalent to @code{(progn @var{body}...)},
-but the compiler does not issue warnings for anything that occurs
-inside @var{body}.
-
-We recommend that you use this construct around the smallest
-possible piece of code.
-@end defspec
-
-@node Byte-Code Objects
-@section Byte-Code Function Objects
-@cindex compiled function
-@cindex byte-code function
-
- Byte-compiled functions have a special data type: they are
-@dfn{byte-code function objects}.
-
- Internally, a byte-code function object is much like a vector;
-however, the evaluator handles this data type specially when it appears
-as a function to be called. The printed representation for a byte-code
-function object is like that for a vector, with an additional @samp{#}
-before the opening @samp{[}.
-
- A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements have any normal use.
-They are:
-
-@table @var
-@item arglist
-The list of argument symbols.
-
-@item byte-code
-The string containing the byte-code instructions.
-
-@item constants
-The vector of Lisp objects referenced by the byte code. These include
-symbols used as function names and variable names.
-
-@item stacksize
-The maximum stack size this function needs.
-
-@item docstring
-The documentation string (if any); otherwise, @code{nil}. The value may
-be a number or a list, in case the documentation string is stored in a
-file. Use the function @code{documentation} to get the real
-documentation string (@pxref{Accessing Documentation}).
-
-@item interactive
-The interactive spec (if any). This can be a string or a Lisp
-expression. It is @code{nil} for a function that isn't interactive.
-@end table
-
-Here's an example of a byte-code function object, in printed
-representation. It is the definition of the command
-@code{backward-sexp}.
-
-@example
-#[(&optional arg)
- "^H\204^F^@@\301^P\302^H[!\207"
- [arg 1 forward-sexp]
- 2
- 254435
- "p"]
-@end example
-
- The primitive way to create a byte-code object is with
-@code{make-byte-code}:
-
-@defun make-byte-code &rest elements
-This function constructs and returns a byte-code function object
-with @var{elements} as its elements.
-@end defun
-
- You should not try to come up with the elements for a byte-code
-function yourself, because if they are inconsistent, Emacs may crash
-when you call the function. Always leave it to the byte compiler to
-create these objects; it makes the elements consistent (we hope).
-
- You can access the elements of a byte-code object using @code{aref};
-you can also use @code{vconcat} to create a vector with the same
-elements.
-
-@node Disassembly
-@section Disassembled Byte-Code
-@cindex disassembled byte-code
-
- People do not write byte-code; that job is left to the byte compiler.
-But we provide a disassembler to satisfy a cat-like curiosity. The
-disassembler converts the byte-compiled code into humanly readable
-form.
-
- The byte-code interpreter is implemented as a simple stack machine.
-It pushes values onto a stack of its own, then pops them off to use them
-in calculations whose results are themselves pushed back on the stack.
-When a byte-code function returns, it pops a value off the stack and
-returns it as the value of the function.
-
- In addition to the stack, byte-code functions can use, bind, and set
-ordinary Lisp variables, by transferring values between variables and
-the stack.
-
-@deffn Command disassemble object &optional buffer-or-name
-This command displays the disassembled code for @var{object}. In
-interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
-the output goes in a buffer named @samp{*Disassemble*}. If
-@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
-name of an existing buffer. Then the output goes there, at point, and
-point is left before the output.
-
-The argument @var{object} can be a function name, a lambda expression
-or a byte-code object. If it is a lambda expression, @code{disassemble}
-compiles it and disassembles the resulting compiled code.
-@end deffn
-
- Here are two examples of using the @code{disassemble} function. We
-have added explanatory comments to help you relate the byte-code to the
-Lisp source; these do not appear in the output of @code{disassemble}.
-These examples show unoptimized byte-code. Nowadays byte-code is
-usually optimized, but we did not want to rewrite these examples, since
-they still serve their purpose.
-
-@example
-@group
-(defun factorial (integer)
- "Compute factorial of an integer."
- (if (= 1 integer) 1
- (* integer (factorial (1- integer)))))
- @result{} factorial
-@end group
-
-@group
-(factorial 4)
- @result{} 24
-@end group
-
-@group
-(disassemble 'factorial)
- @print{} byte-code for factorial:
- doc: Compute factorial of an integer.
- args: (integer)
-@end group
-
-@group
-0 constant 1 ; @r{Push 1 onto stack.}
-
-1 varref integer ; @r{Get value of @code{integer}}
- ; @r{from the environment}
- ; @r{and push the value}
- ; @r{onto the stack.}
-@end group
-
-@group
-2 eqlsign ; @r{Pop top two values off stack,}
- ; @r{compare them,}
- ; @r{and push result onto stack.}
-@end group
-
-@group
-3 goto-if-nil 10 ; @r{Pop and test top of stack;}
- ; @r{if @code{nil}, go to 10,}
- ; @r{else continue.}
-@end group
-
-@group
-6 constant 1 ; @r{Push 1 onto top of stack.}
-
-7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
- ; @r{returned by the function).}
-@end group
-
-@group
-10 constant * ; @r{Push symbol @code{*} onto stack.}
-
-11 varref integer ; @r{Push value of @code{integer} onto stack.}
-@end group
-
-@group
-12 constant factorial ; @r{Push @code{factorial} onto stack.}
-
-13 varref integer ; @r{Push value of @code{integer} onto stack.}
-
-14 sub1 ; @r{Pop @code{integer}, decrement value,}
- ; @r{push new value onto stack.}
-@end group
-
-@group
- ; @r{Stack now contains:}
- ; @minus{} @r{decremented value of @code{integer}}
- ; @minus{} @r{@code{factorial}}
- ; @minus{} @r{value of @code{integer}}
- ; @minus{} @r{@code{*}}
-@end group
-
-@group
-15 call 1 ; @r{Call function @code{factorial} using}
- ; @r{the first (i.e., the top) element}
- ; @r{of the stack as the argument;}
- ; @r{push returned value onto stack.}
-@end group
-
-@group
- ; @r{Stack now contains:}
- ; @minus{} @r{result of recursive}
- ; @r{call to @code{factorial}}
- ; @minus{} @r{value of @code{integer}}
- ; @minus{} @r{@code{*}}
-@end group
-
-@group
-16 call 2 ; @r{Using the first two}
- ; @r{(i.e., the top two)}
- ; @r{elements of the stack}
- ; @r{as arguments,}
- ; @r{call the function @code{*},}
- ; @r{pushing the result onto the stack.}
-@end group
-
-@group
-17 return ; @r{Return the top element}
- ; @r{of the stack.}
- @result{} nil
-@end group
-@end example
-
-The @code{silly-loop} function is somewhat more complex:
-
-@example
-@group
-(defun silly-loop (n)
- "Return time before and after N iterations of a loop."
- (let ((t1 (current-time-string)))
- (while (> (setq n (1- n))
- 0))
- (list t1 (current-time-string))))
- @result{} silly-loop
-@end group
-
-@group
-(disassemble 'silly-loop)
- @print{} byte-code for silly-loop:
- doc: Return time before and after N iterations of a loop.
- args: (n)
-
-0 constant current-time-string ; @r{Push}
- ; @r{@code{current-time-string}}
- ; @r{onto top of stack.}
-@end group
-
-@group
-1 call 0 ; @r{Call @code{current-time-string}}
- ; @r{ with no argument,}
- ; @r{ pushing result onto stack.}
-@end group
-
-@group
-2 varbind t1 ; @r{Pop stack and bind @code{t1}}
- ; @r{to popped value.}
-@end group
-
-@group
-3 varref n ; @r{Get value of @code{n} from}
- ; @r{the environment and push}
- ; @r{the value onto the stack.}
-@end group
-
-@group
-4 sub1 ; @r{Subtract 1 from top of stack.}
-@end group
-
-@group
-5 dup ; @r{Duplicate the top of the stack;}
- ; @r{i.e., copy the top of}
- ; @r{the stack and push the}
- ; @r{copy onto the stack.}
-@end group
-
-@group
-6 varset n ; @r{Pop the top of the stack,}
- ; @r{and bind @code{n} to the value.}
-
- ; @r{In effect, the sequence @code{dup varset}}
- ; @r{copies the top of the stack}
- ; @r{into the value of @code{n}}
- ; @r{without popping it.}
-@end group
-
-@group
-7 constant 0 ; @r{Push 0 onto stack.}
-@end group
-
-@group
-8 gtr ; @r{Pop top two values off stack,}
- ; @r{test if @var{n} is greater than 0}
- ; @r{and push result onto stack.}
-@end group
-
-@group
-9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
- ; @r{(this exits the while loop).}
- ; @r{else pop top of stack}
- ; @r{and continue}
-@end group
-
-@group
-12 constant nil ; @r{Push @code{nil} onto stack}
- ; @r{(this is the body of the loop).}
-@end group
-
-@group
-13 discard ; @r{Discard result of the body}
- ; @r{of the loop (a while loop}
- ; @r{is always evaluated for}
- ; @r{its side effects).}
-@end group
-
-@group
-14 goto 3 ; @r{Jump back to beginning}
- ; @r{of while loop.}
-@end group
-
-@group
-17 discard ; @r{Discard result of while loop}
- ; @r{by popping top of stack.}
- ; @r{This result is the value @code{nil} that}
- ; @r{was not popped by the goto at 9.}
-@end group
-
-@group
-18 varref t1 ; @r{Push value of @code{t1} onto stack.}
-@end group
-
-@group
-19 constant current-time-string ; @r{Push}
- ; @r{@code{current-time-string}}
- ; @r{onto top of stack.}
-@end group
-
-@group
-20 call 0 ; @r{Call @code{current-time-string} again.}
-@end group
-
-@group
-21 list2 ; @r{Pop top two elements off stack,}
- ; @r{create a list of them,}
- ; @r{and push list onto stack.}
-@end group
-
-@group
-22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
-
-23 return ; @r{Return value of the top of stack.}
-
- @result{} nil
-@end group
-@end example
-
-
-@ignore
- arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
-@end ignore
+++ /dev/null
-#! /bin/sh
-
-# Guess values for system-dependent variables and create Makefiles.
-# Generated automatically using autoconf version 2.13
-# Copyright (C) 1992, 1993, 1994, 1995, 1996, 2001, 2002, 2003, 2004,
-# 2005, 2006, 2007 Free Software Foundation, Inc.
-#
-# This configure script is free software; the Free Software Foundation
-# gives unlimited permission to copy, distribute and modify it.
-
-# Defaults:
-ac_help=
-ac_default_prefix=/usr/local
-# Any additions from configure.in:
-
-# Initialize some variables set by options.
-# The variables have the same names as the options, with
-# dashes changed to underlines.
-build=NONE
-cache_file=./config.cache
-exec_prefix=NONE
-host=NONE
-no_create=
-nonopt=NONE
-no_recursion=
-prefix=NONE
-program_prefix=NONE
-program_suffix=NONE
-program_transform_name=s,x,x,
-silent=
-site=
-srcdir=
-target=NONE
-verbose=
-x_includes=NONE
-x_libraries=NONE
-bindir='${exec_prefix}/bin'
-sbindir='${exec_prefix}/sbin'
-libexecdir='${exec_prefix}/libexec'
-datadir='${prefix}/share'
-sysconfdir='${prefix}/etc'
-sharedstatedir='${prefix}/com'
-localstatedir='${prefix}/var'
-libdir='${exec_prefix}/lib'
-includedir='${prefix}/include'
-oldincludedir='/usr/include'
-infodir='${prefix}/info'
-mandir='${prefix}/man'
-
-# Initialize some other variables.
-subdirs=
-MFLAGS= MAKEFLAGS=
-SHELL=${CONFIG_SHELL-/bin/sh}
-# Maximum number of lines to put in a shell here document.
-ac_max_here_lines=12
-
-ac_prev=
-for ac_option
-do
-
- # If the previous option needs an argument, assign it.
- if test -n "$ac_prev"; then
- eval "$ac_prev=\$ac_option"
- ac_prev=
- continue
- fi
-
- case "$ac_option" in
- -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
- *) ac_optarg= ;;
- esac
-
- # Accept the important Cygnus configure options, so we can diagnose typos.
-
- case "$ac_option" in
-
- -bindir | --bindir | --bindi | --bind | --bin | --bi)
- ac_prev=bindir ;;
- -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
- bindir="$ac_optarg" ;;
-
- -build | --build | --buil | --bui | --bu)
- ac_prev=build ;;
- -build=* | --build=* | --buil=* | --bui=* | --bu=*)
- build="$ac_optarg" ;;
-
- -cache-file | --cache-file | --cache-fil | --cache-fi \
- | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
- ac_prev=cache_file ;;
- -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
- | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
- cache_file="$ac_optarg" ;;
-
- -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
- ac_prev=datadir ;;
- -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
- | --da=*)
- datadir="$ac_optarg" ;;
-
- -disable-* | --disable-*)
- ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
- { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
- fi
- ac_feature=`echo $ac_feature| sed 's/-/_/g'`
- eval "enable_${ac_feature}=no" ;;
-
- -enable-* | --enable-*)
- ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
- { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
- fi
- ac_feature=`echo $ac_feature| sed 's/-/_/g'`
- case "$ac_option" in
- *=*) ;;
- *) ac_optarg=yes ;;
- esac
- eval "enable_${ac_feature}='$ac_optarg'" ;;
-
- -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
- | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
- | --exec | --exe | --ex)
- ac_prev=exec_prefix ;;
- -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
- | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
- | --exec=* | --exe=* | --ex=*)
- exec_prefix="$ac_optarg" ;;
-
- -gas | --gas | --ga | --g)
- # Obsolete; use --with-gas.
- with_gas=yes ;;
-
- -help | --help | --hel | --he)
- # Omit some internal or obsolete options to make the list less imposing.
- # This message is too long to be a string in the A/UX 3.1 sh.
- cat << EOF
-Usage: configure [options] [host]
-Options: [defaults in brackets after descriptions]
-Configuration:
- --cache-file=FILE cache test results in FILE
- --help print this message
- --no-create do not create output files
- --quiet, --silent do not print \`checking...' messages
- --version print the version of autoconf that created configure
-Directory and file names:
- --prefix=PREFIX install architecture-independent files in PREFIX
- [$ac_default_prefix]
- --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
- [same as prefix]
- --bindir=DIR user executables in DIR [EPREFIX/bin]
- --sbindir=DIR system admin executables in DIR [EPREFIX/sbin]
- --libexecdir=DIR program executables in DIR [EPREFIX/libexec]
- --datadir=DIR read-only architecture-independent data in DIR
- [PREFIX/share]
- --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc]
- --sharedstatedir=DIR modifiable architecture-independent data in DIR
- [PREFIX/com]
- --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var]
- --libdir=DIR object code libraries in DIR [EPREFIX/lib]
- --includedir=DIR C header files in DIR [PREFIX/include]
- --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include]
- --infodir=DIR info documentation in DIR [PREFIX/info]
- --mandir=DIR man documentation in DIR [PREFIX/man]
- --srcdir=DIR find the sources in DIR [configure dir or ..]
- --program-prefix=PREFIX prepend PREFIX to installed program names
- --program-suffix=SUFFIX append SUFFIX to installed program names
- --program-transform-name=PROGRAM
- run sed PROGRAM on installed program names
-EOF
- cat << EOF
-Host type:
- --build=BUILD configure for building on BUILD [BUILD=HOST]
- --host=HOST configure for HOST [guessed]
- --target=TARGET configure for TARGET [TARGET=HOST]
-Features and packages:
- --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
- --enable-FEATURE[=ARG] include FEATURE [ARG=yes]
- --with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
- --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
- --x-includes=DIR X include files are in DIR
- --x-libraries=DIR X library files are in DIR
-EOF
- if test -n "$ac_help"; then
- echo "--enable and --with options recognized:$ac_help"
- fi
- exit 0 ;;
-
- -host | --host | --hos | --ho)
- ac_prev=host ;;
- -host=* | --host=* | --hos=* | --ho=*)
- host="$ac_optarg" ;;
-
- -includedir | --includedir | --includedi | --included | --include \
- | --includ | --inclu | --incl | --inc)
- ac_prev=includedir ;;
- -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
- | --includ=* | --inclu=* | --incl=* | --inc=*)
- includedir="$ac_optarg" ;;
-
- -infodir | --infodir | --infodi | --infod | --info | --inf)
- ac_prev=infodir ;;
- -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
- infodir="$ac_optarg" ;;
-
- -libdir | --libdir | --libdi | --libd)
- ac_prev=libdir ;;
- -libdir=* | --libdir=* | --libdi=* | --libd=*)
- libdir="$ac_optarg" ;;
-
- -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
- | --libexe | --libex | --libe)
- ac_prev=libexecdir ;;
- -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
- | --libexe=* | --libex=* | --libe=*)
- libexecdir="$ac_optarg" ;;
-
- -localstatedir | --localstatedir | --localstatedi | --localstated \
- | --localstate | --localstat | --localsta | --localst \
- | --locals | --local | --loca | --loc | --lo)
- ac_prev=localstatedir ;;
- -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
- | --localstate=* | --localstat=* | --localsta=* | --localst=* \
- | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
- localstatedir="$ac_optarg" ;;
-
- -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
- ac_prev=mandir ;;
- -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
- mandir="$ac_optarg" ;;
-
- -nfp | --nfp | --nf)
- # Obsolete; use --without-fp.
- with_fp=no ;;
-
- -no-create | --no-create | --no-creat | --no-crea | --no-cre \
- | --no-cr | --no-c)
- no_create=yes ;;
-
- -no-recursion | --no-recursion | --no-recursio | --no-recursi \
- | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
- no_recursion=yes ;;
-
- -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
- | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
- | --oldin | --oldi | --old | --ol | --o)
- ac_prev=oldincludedir ;;
- -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
- | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
- | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
- oldincludedir="$ac_optarg" ;;
-
- -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
- ac_prev=prefix ;;
- -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
- prefix="$ac_optarg" ;;
-
- -program-prefix | --program-prefix | --program-prefi | --program-pref \
- | --program-pre | --program-pr | --program-p)
- ac_prev=program_prefix ;;
- -program-prefix=* | --program-prefix=* | --program-prefi=* \
- | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
- program_prefix="$ac_optarg" ;;
-
- -program-suffix | --program-suffix | --program-suffi | --program-suff \
- | --program-suf | --program-su | --program-s)
- ac_prev=program_suffix ;;
- -program-suffix=* | --program-suffix=* | --program-suffi=* \
- | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
- program_suffix="$ac_optarg" ;;
-
- -program-transform-name | --program-transform-name \
- | --program-transform-nam | --program-transform-na \
- | --program-transform-n | --program-transform- \
- | --program-transform | --program-transfor \
- | --program-transfo | --program-transf \
- | --program-trans | --program-tran \
- | --progr-tra | --program-tr | --program-t)
- ac_prev=program_transform_name ;;
- -program-transform-name=* | --program-transform-name=* \
- | --program-transform-nam=* | --program-transform-na=* \
- | --program-transform-n=* | --program-transform-=* \
- | --program-transform=* | --program-transfor=* \
- | --program-transfo=* | --program-transf=* \
- | --program-trans=* | --program-tran=* \
- | --progr-tra=* | --program-tr=* | --program-t=*)
- program_transform_name="$ac_optarg" ;;
-
- -q | -quiet | --quiet | --quie | --qui | --qu | --q \
- | -silent | --silent | --silen | --sile | --sil)
- silent=yes ;;
-
- -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
- ac_prev=sbindir ;;
- -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
- | --sbi=* | --sb=*)
- sbindir="$ac_optarg" ;;
-
- -sharedstatedir | --sharedstatedir | --sharedstatedi \
- | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
- | --sharedst | --shareds | --shared | --share | --shar \
- | --sha | --sh)
- ac_prev=sharedstatedir ;;
- -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
- | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
- | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
- | --sha=* | --sh=*)
- sharedstatedir="$ac_optarg" ;;
-
- -site | --site | --sit)
- ac_prev=site ;;
- -site=* | --site=* | --sit=*)
- site="$ac_optarg" ;;
-
- -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
- ac_prev=srcdir ;;
- -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
- srcdir="$ac_optarg" ;;
-
- -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
- | --syscon | --sysco | --sysc | --sys | --sy)
- ac_prev=sysconfdir ;;
- -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
- | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
- sysconfdir="$ac_optarg" ;;
-
- -target | --target | --targe | --targ | --tar | --ta | --t)
- ac_prev=target ;;
- -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
- target="$ac_optarg" ;;
-
- -v | -verbose | --verbose | --verbos | --verbo | --verb)
- verbose=yes ;;
-
- -version | --version | --versio | --versi | --vers)
- echo "configure generated by autoconf version 2.13"
- exit 0 ;;
-
- -with-* | --with-*)
- ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
- { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
- fi
- ac_package=`echo $ac_package| sed 's/-/_/g'`
- case "$ac_option" in
- *=*) ;;
- *) ac_optarg=yes ;;
- esac
- eval "with_${ac_package}='$ac_optarg'" ;;
-
- -without-* | --without-*)
- ac_package=`echo $ac_option|sed -e 's/-*without-//'`
- # Reject names that are not valid shell variable names.
- if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
- { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
- fi
- ac_package=`echo $ac_package| sed 's/-/_/g'`
- eval "with_${ac_package}=no" ;;
-
- --x)
- # Obsolete; use --with-x.
- with_x=yes ;;
-
- -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
- | --x-incl | --x-inc | --x-in | --x-i)
- ac_prev=x_includes ;;
- -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
- | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
- x_includes="$ac_optarg" ;;
-
- -x-libraries | --x-libraries | --x-librarie | --x-librari \
- | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
- ac_prev=x_libraries ;;
- -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
- | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
- x_libraries="$ac_optarg" ;;
-
- -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
- ;;
-
- *)
- if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
- echo "configure: warning: $ac_option: invalid host type" 1>&2
- fi
- if test "x$nonopt" != xNONE; then
- { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
- fi
- nonopt="$ac_option"
- ;;
-
- esac
-done
-
-if test -n "$ac_prev"; then
- { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
-fi
-
-trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
-
-# File descriptor usage:
-# 0 standard input
-# 1 file creation
-# 2 errors and warnings
-# 3 some systems may open it to /dev/tty
-# 4 used on the Kubota Titan
-# 6 checking for... messages and results
-# 5 compiler messages saved in config.log
-if test "$silent" = yes; then
- exec 6>/dev/null
-else
- exec 6>&1
-fi
-exec 5>./config.log
-
-echo "\
-This file contains any messages produced by compilers while
-running configure, to aid debugging if configure makes a mistake.
-" 1>&5
-
-# Strip out --no-create and --no-recursion so they do not pile up.
-# Also quote any args containing shell metacharacters.
-ac_configure_args=
-for ac_arg
-do
- case "$ac_arg" in
- -no-create | --no-create | --no-creat | --no-crea | --no-cre \
- | --no-cr | --no-c) ;;
- -no-recursion | --no-recursion | --no-recursio | --no-recursi \
- | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
- *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
- ac_configure_args="$ac_configure_args '$ac_arg'" ;;
- *) ac_configure_args="$ac_configure_args $ac_arg" ;;
- esac
-done
-
-# NLS nuisances.
-# Only set these to C if already set. These must not be set unconditionally
-# because not all systems understand e.g. LANG=C (notably SCO).
-# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
-# Non-C LC_CTYPE values break the ctype check.
-if test "${LANG+set}" = set; then LANG=C; export LANG; fi
-if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
-if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
-if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi
-
-# confdefs.h avoids OS command line length limits that DEFS can exceed.
-rm -rf conftest* confdefs.h
-# AIX cpp loses on an empty file, so make sure it contains at least a newline.
-echo > confdefs.h
-
-# A filename unique to this package, relative to the directory that
-# configure is in, which we can look for to find out if srcdir is correct.
-ac_unique_file=elisp.texi
-
-# Find the source files, if location was not specified.
-if test -z "$srcdir"; then
- ac_srcdir_defaulted=yes
- # Try the directory containing this script, then its parent.
- ac_prog=$0
- ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
- test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
- srcdir=$ac_confdir
- if test ! -r $srcdir/$ac_unique_file; then
- srcdir=..
- fi
-else
- ac_srcdir_defaulted=no
-fi
-if test ! -r $srcdir/$ac_unique_file; then
- if test "$ac_srcdir_defaulted" = yes; then
- { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
- else
- { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
- fi
-fi
-srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
-
-# Prefer explicitly selected file to automatically selected ones.
-if test -z "$CONFIG_SITE"; then
- if test "x$prefix" != xNONE; then
- CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
- else
- CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
- fi
-fi
-for ac_site_file in $CONFIG_SITE; do
- if test -r "$ac_site_file"; then
- echo "loading site script $ac_site_file"
- . "$ac_site_file"
- fi
-done
-
-if test -r "$cache_file"; then
- echo "loading cache $cache_file"
- . $cache_file
-else
- echo "creating cache $cache_file"
- > $cache_file
-fi
-
-ac_ext=c
-# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
-ac_cpp='$CPP $CPPFLAGS'
-ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
-ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
-cross_compiling=$ac_cv_prog_cc_cross
-
-ac_exeext=
-ac_objext=o
-if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
- # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
- if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
- ac_n= ac_c='
-' ac_t=' '
- else
- ac_n=-n ac_c= ac_t=
- fi
-else
- ac_n= ac_c='\c' ac_t=
-fi
-
-
-trap '' 1 2 15
-cat > confcache <<\EOF
-# This file is a shell script that caches the results of configure
-# tests run on this system so they can be shared between configure
-# scripts and configure runs. It is not useful on other systems.
-# If it contains results you don't want to keep, you may remove or edit it.
-#
-# By default, configure uses ./config.cache as the cache file,
-# creating it if it does not exist already. You can give configure
-# the --cache-file=FILE option to use a different cache file; that is
-# what configure does when it calls configure scripts in
-# subdirectories, so they share the cache.
-# Giving --cache-file=/dev/null disables caching, for debugging configure.
-# config.status only pays attention to the cache file if you give it the
-# --recheck option to rerun configure.
-#
-EOF
-# The following way of writing the cache mishandles newlines in values,
-# but we know of no workaround that is simple, portable, and efficient.
-# So, don't put newlines in cache variables' values.
-# Ultrix sh set writes to stderr and can't be redirected directly,
-# and sets the high bit in the cache file unless we assign to the vars.
-(set) 2>&1 |
- case `(ac_space=' '; set | grep ac_space) 2>&1` in
- *ac_space=\ *)
- # `set' does not quote correctly, so add quotes (double-quote substitution
- # turns \\\\ into \\, and sed turns \\ into \).
- sed -n \
- -e "s/'/'\\\\''/g" \
- -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
- ;;
- *)
- # `set' quotes correctly as required by POSIX, so do not add quotes.
- sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
- ;;
- esac >> confcache
-if cmp -s $cache_file confcache; then
- :
-else
- if test -w $cache_file; then
- echo "updating cache $cache_file"
- cat confcache > $cache_file
- else
- echo "not updating unwritable cache $cache_file"
- fi
-fi
-rm -f confcache
-
-trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
-
-test "x$prefix" = xNONE && prefix=$ac_default_prefix
-# Let make expand exec_prefix.
-test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
-
-# Any assignment to VPATH causes Sun make to only execute
-# the first set of double-colon rules, so remove it if not needed.
-# If there is a colon in the path, we need to keep it.
-if test "x$srcdir" = x.; then
- ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d'
-fi
-
-trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
-
-# Transform confdefs.h into DEFS.
-# Protect against shell expansion while executing Makefile rules.
-# Protect against Makefile macro expansion.
-cat > conftest.defs <<\EOF
-s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
-s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g
-s%\[%\\&%g
-s%\]%\\&%g
-s%\$%$$%g
-EOF
-DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
-rm -f conftest.defs
-
-
-# Without the "./", some shells look in PATH for config.status.
-: ${CONFIG_STATUS=./config.status}
-
-echo creating $CONFIG_STATUS
-rm -f $CONFIG_STATUS
-cat > $CONFIG_STATUS <<EOF
-#! /bin/sh
-# Generated automatically by configure.
-# Run this file to recreate the current configuration.
-# This directory was configured as follows,
-# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
-#
-# $0 $ac_configure_args
-#
-# Compiler output produced by configure, useful for debugging
-# configure, is in ./config.log if it exists.
-
-ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
-for ac_option
-do
- case "\$ac_option" in
- -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
- echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
- exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
- -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
- echo "$CONFIG_STATUS generated by autoconf version 2.13"
- exit 0 ;;
- -help | --help | --hel | --he | --h)
- echo "\$ac_cs_usage"; exit 0 ;;
- *) echo "\$ac_cs_usage"; exit 1 ;;
- esac
-done
-
-ac_given_srcdir=$srcdir
-
-trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
-EOF
-cat >> $CONFIG_STATUS <<EOF
-
-# Protect against being on the right side of a sed subst in config.status.
-sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
- s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
-$ac_vpsub
-$extrasub
-s%@SHELL@%$SHELL%g
-s%@CFLAGS@%$CFLAGS%g
-s%@CPPFLAGS@%$CPPFLAGS%g
-s%@CXXFLAGS@%$CXXFLAGS%g
-s%@FFLAGS@%$FFLAGS%g
-s%@DEFS@%$DEFS%g
-s%@LDFLAGS@%$LDFLAGS%g
-s%@LIBS@%$LIBS%g
-s%@exec_prefix@%$exec_prefix%g
-s%@prefix@%$prefix%g
-s%@program_transform_name@%$program_transform_name%g
-s%@bindir@%$bindir%g
-s%@sbindir@%$sbindir%g
-s%@libexecdir@%$libexecdir%g
-s%@datadir@%$datadir%g
-s%@sysconfdir@%$sysconfdir%g
-s%@sharedstatedir@%$sharedstatedir%g
-s%@localstatedir@%$localstatedir%g
-s%@libdir@%$libdir%g
-s%@includedir@%$includedir%g
-s%@oldincludedir@%$oldincludedir%g
-s%@infodir@%$infodir%g
-s%@mandir@%$mandir%g
-
-CEOF
-EOF
-
-cat >> $CONFIG_STATUS <<\EOF
-
-# Split the substitutions into bite-sized pieces for seds with
-# small command number limits, like on Digital OSF/1 and HP-UX.
-ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
-ac_file=1 # Number of current file.
-ac_beg=1 # First line for current file.
-ac_end=$ac_max_sed_cmds # Line after last line for current file.
-ac_more_lines=:
-ac_sed_cmds=""
-while $ac_more_lines; do
- if test $ac_beg -gt 1; then
- sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
- else
- sed "${ac_end}q" conftest.subs > conftest.s$ac_file
- fi
- if test ! -s conftest.s$ac_file; then
- ac_more_lines=false
- rm -f conftest.s$ac_file
- else
- if test -z "$ac_sed_cmds"; then
- ac_sed_cmds="sed -f conftest.s$ac_file"
- else
- ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
- fi
- ac_file=`expr $ac_file + 1`
- ac_beg=$ac_end
- ac_end=`expr $ac_end + $ac_max_sed_cmds`
- fi
-done
-if test -z "$ac_sed_cmds"; then
- ac_sed_cmds=cat
-fi
-EOF
-
-cat >> $CONFIG_STATUS <<EOF
-
-CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
-EOF
-cat >> $CONFIG_STATUS <<\EOF
-for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
- # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
- case "$ac_file" in
- *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
- ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
- *) ac_file_in="${ac_file}.in" ;;
- esac
-
- # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
-
- # Remove last slash and all that follows it. Not all systems have dirname.
- ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
- if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
- # The file is in a subdirectory.
- test ! -d "$ac_dir" && mkdir "$ac_dir"
- ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
- # A "../" for each directory in $ac_dir_suffix.
- ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
- else
- ac_dir_suffix= ac_dots=
- fi
-
- case "$ac_given_srcdir" in
- .) srcdir=.
- if test -z "$ac_dots"; then top_srcdir=.
- else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
- /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
- *) # Relative path.
- srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
- top_srcdir="$ac_dots$ac_given_srcdir" ;;
- esac
-
-
- echo creating "$ac_file"
- rm -f "$ac_file"
- configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
- case "$ac_file" in
- *Makefile*) ac_comsub="1i\\
-# $configure_input" ;;
- *) ac_comsub= ;;
- esac
-
- ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
- sed -e "$ac_comsub
-s%@configure_input@%$configure_input%g
-s%@srcdir@%$srcdir%g
-s%@top_srcdir@%$top_srcdir%g
-" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
-fi; done
-rm -f conftest.s*
-
-EOF
-cat >> $CONFIG_STATUS <<EOF
-
-EOF
-cat >> $CONFIG_STATUS <<\EOF
-
-exit 0
-EOF
-chmod +x $CONFIG_STATUS
-rm -fr confdefs* $ac_clean_files
-test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
-
+++ /dev/null
-dnl Process this file with autoconf to produce a configure script.
-AC_INIT(elisp.texi)
-AC_OUTPUT(Makefile)
-
-m4_if(dnl Do not change this comment
- arch-tag: 61db4227-0d2b-4c4d-ad54-ca9a1ee518ea
-)dnl
+++ /dev/null
-@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/control
-@node Control Structures, Variables, Evaluation, Top
-@chapter Control Structures
-@cindex special forms for control structures
-@cindex control structures
-
- A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
-We control the order of execution of these forms by enclosing them in
-@dfn{control structures}. Control structures are special forms which
-control when, whether, or how many times to execute the forms they
-contain.
-
- The simplest order of execution is sequential execution: first form
-@var{a}, then form @var{b}, and so on. This is what happens when you
-write several forms in succession in the body of a function, or at top
-level in a file of Lisp code---the forms are executed in the order
-written. We call this @dfn{textual order}. For example, if a function
-body consists of two forms @var{a} and @var{b}, evaluation of the
-function evaluates first @var{a} and then @var{b}. The result of
-evaluating @var{b} becomes the value of the function.
-
- Explicit control structures make possible an order of execution other
-than sequential.
-
- Emacs Lisp provides several kinds of control structure, including
-other varieties of sequencing, conditionals, iteration, and (controlled)
-jumps---all discussed below. The built-in control structures are
-special forms since their subforms are not necessarily evaluated or not
-evaluated sequentially. You can use macros to define your own control
-structure constructs (@pxref{Macros}).
-
-@menu
-* 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.
-@end menu
-
-@node Sequencing
-@section Sequencing
-
- Evaluating forms in the order they appear is the most common way
-control passes from one form to another. In some contexts, such as in a
-function body, this happens automatically. Elsewhere you must use a
-control structure construct to do this: @code{progn}, the simplest
-control construct of Lisp.
-
- A @code{progn} special form looks like this:
-
-@example
-@group
-(progn @var{a} @var{b} @var{c} @dots{})
-@end group
-@end example
-
-@noindent
-and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
-that order. These forms are called the @dfn{body} of the @code{progn} form.
-The value of the last form in the body becomes the value of the entire
-@code{progn}. @code{(progn)} returns @code{nil}.
-
-@cindex implicit @code{progn}
- In the early days of Lisp, @code{progn} was the only way to execute
-two or more forms in succession and use the value of the last of them.
-But programmers found they often needed to use a @code{progn} in the
-body of a function, where (at that time) only one form was allowed. So
-the body of a function was made into an ``implicit @code{progn}'':
-several forms are allowed just as in the body of an actual @code{progn}.
-Many other control structures likewise contain an implicit @code{progn}.
-As a result, @code{progn} is not used as much as it was many years ago.
-It is needed now most often inside an @code{unwind-protect}, @code{and},
-@code{or}, or in the @var{then}-part of an @code{if}.
-
-@defspec progn forms@dots{}
-This special form evaluates all of the @var{forms}, in textual
-order, returning the result of the final form.
-
-@example
-@group
-(progn (print "The first form")
- (print "The second form")
- (print "The third form"))
- @print{} "The first form"
- @print{} "The second form"
- @print{} "The third form"
-@result{} "The third form"
-@end group
-@end example
-@end defspec
-
- Two other control constructs likewise evaluate a series of forms but return
-a different value:
-
-@defspec prog1 form1 forms@dots{}
-This special form evaluates @var{form1} and all of the @var{forms}, in
-textual order, returning the result of @var{form1}.
-
-@example
-@group
-(prog1 (print "The first form")
- (print "The second form")
- (print "The third form"))
- @print{} "The first form"
- @print{} "The second form"
- @print{} "The third form"
-@result{} "The first form"
-@end group
-@end example
-
-Here is a way to remove the first element from a list in the variable
-@code{x}, then return the value of that former element:
-
-@example
-(prog1 (car x) (setq x (cdr x)))
-@end example
-@end defspec
-
-@defspec prog2 form1 form2 forms@dots{}
-This special form evaluates @var{form1}, @var{form2}, and all of the
-following @var{forms}, in textual order, returning the result of
-@var{form2}.
-
-@example
-@group
-(prog2 (print "The first form")
- (print "The second form")
- (print "The third form"))
- @print{} "The first form"
- @print{} "The second form"
- @print{} "The third form"
-@result{} "The second form"
-@end group
-@end example
-@end defspec
-
-@node Conditionals
-@section Conditionals
-@cindex conditional evaluation
-
- Conditional control structures choose among alternatives. Emacs Lisp
-has four conditional forms: @code{if}, which is much the same as in
-other languages; @code{when} and @code{unless}, which are variants of
-@code{if}; and @code{cond}, which is a generalized case statement.
-
-@defspec if condition then-form else-forms@dots{}
-@code{if} chooses between the @var{then-form} and the @var{else-forms}
-based on the value of @var{condition}. If the evaluated @var{condition} is
-non-@code{nil}, @var{then-form} is evaluated and the result returned.
-Otherwise, the @var{else-forms} are evaluated in textual order, and the
-value of the last one is returned. (The @var{else} part of @code{if} is
-an example of an implicit @code{progn}. @xref{Sequencing}.)
-
-If @var{condition} has the value @code{nil}, and no @var{else-forms} are
-given, @code{if} returns @code{nil}.
-
-@code{if} is a special form because the branch that is not selected is
-never evaluated---it is ignored. Thus, in the example below,
-@code{true} is not printed because @code{print} is never called.
-
-@example
-@group
-(if nil
- (print 'true)
- 'very-false)
-@result{} very-false
-@end group
-@end example
-@end defspec
-
-@defmac when condition then-forms@dots{}
-This is a variant of @code{if} where there are no @var{else-forms},
-and possibly several @var{then-forms}. In particular,
-
-@example
-(when @var{condition} @var{a} @var{b} @var{c})
-@end example
-
-@noindent
-is entirely equivalent to
-
-@example
-(if @var{condition} (progn @var{a} @var{b} @var{c}) nil)
-@end example
-@end defmac
-
-@defmac unless condition forms@dots{}
-This is a variant of @code{if} where there is no @var{then-form}:
-
-@example
-(unless @var{condition} @var{a} @var{b} @var{c})
-@end example
-
-@noindent
-is entirely equivalent to
-
-@example
-(if @var{condition} nil
- @var{a} @var{b} @var{c})
-@end example
-@end defmac
-
-@defspec cond clause@dots{}
-@code{cond} chooses among an arbitrary number of alternatives. Each
-@var{clause} in the @code{cond} must be a list. The @sc{car} of this
-list is the @var{condition}; the remaining elements, if any, the
-@var{body-forms}. Thus, a clause looks like this:
-
-@example
-(@var{condition} @var{body-forms}@dots{})
-@end example
-
-@code{cond} tries the clauses in textual order, by evaluating the
-@var{condition} of each clause. If the value of @var{condition} is
-non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its
-@var{body-forms}, and the value of the last of @var{body-forms} becomes
-the value of the @code{cond}. The remaining clauses are ignored.
-
-If the value of @var{condition} is @code{nil}, the clause ``fails,'' so
-the @code{cond} moves on to the following clause, trying its
-@var{condition}.
-
-If every @var{condition} evaluates to @code{nil}, so that every clause
-fails, @code{cond} returns @code{nil}.
-
-A clause may also look like this:
-
-@example
-(@var{condition})
-@end example
-
-@noindent
-Then, if @var{condition} is non-@code{nil} when tested, the value of
-@var{condition} becomes the value of the @code{cond} form.
-
-The following example has four clauses, which test for the cases where
-the value of @code{x} is a number, string, buffer and symbol,
-respectively:
-
-@example
-@group
-(cond ((numberp x) x)
- ((stringp x) x)
- ((bufferp x)
- (setq temporary-hack x) ; @r{multiple body-forms}
- (buffer-name x)) ; @r{in one clause}
- ((symbolp x) (symbol-value x)))
-@end group
-@end example
-
-Often we want to execute the last clause whenever none of the previous
-clauses was successful. To do this, we use @code{t} as the
-@var{condition} of the last clause, like this: @code{(t
-@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is
-never @code{nil}, so this clause never fails, provided the @code{cond}
-gets to it at all.
-
-For example,
-
-@example
-@group
-(setq a 5)
-(cond ((eq a 'hack) 'foo)
- (t "default"))
-@result{} "default"
-@end group
-@end example
-
-@noindent
-This @code{cond} expression returns @code{foo} if the value of @code{a}
-is @code{hack}, and returns the string @code{"default"} otherwise.
-@end defspec
-
-Any conditional construct can be expressed with @code{cond} or with
-@code{if}. Therefore, the choice between them is a matter of style.
-For example:
-
-@example
-@group
-(if @var{a} @var{b} @var{c})
-@equiv{}
-(cond (@var{a} @var{b}) (t @var{c}))
-@end group
-@end example
-
-@node Combining Conditions
-@section Constructs for Combining Conditions
-
- This section describes three constructs that are often used together
-with @code{if} and @code{cond} to express complicated conditions. The
-constructs @code{and} and @code{or} can also be used individually as
-kinds of multiple conditional constructs.
-
-@defun not condition
-This function tests for the falsehood of @var{condition}. It returns
-@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise.
-The function @code{not} is identical to @code{null}, and we recommend
-using the name @code{null} if you are testing for an empty list.
-@end defun
-
-@defspec and conditions@dots{}
-The @code{and} special form tests whether all the @var{conditions} are
-true. It works by evaluating the @var{conditions} one by one in the
-order written.
-
-If any of the @var{conditions} evaluates to @code{nil}, then the result
-of the @code{and} must be @code{nil} regardless of the remaining
-@var{conditions}; so @code{and} returns @code{nil} right away, ignoring
-the remaining @var{conditions}.
-
-If all the @var{conditions} turn out non-@code{nil}, then the value of
-the last of them becomes the value of the @code{and} form. Just
-@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
-because all the @var{conditions} turned out non-@code{nil}. (Think
-about it; which one did not?)
-
-Here is an example. The first condition returns the integer 1, which is
-not @code{nil}. Similarly, the second condition returns the integer 2,
-which is not @code{nil}. The third condition is @code{nil}, so the
-remaining condition is never evaluated.
-
-@example
-@group
-(and (print 1) (print 2) nil (print 3))
- @print{} 1
- @print{} 2
-@result{} nil
-@end group
-@end example
-
-Here is a more realistic example of using @code{and}:
-
-@example
-@group
-(if (and (consp foo) (eq (car foo) 'x))
- (message "foo is a list starting with x"))
-@end group
-@end example
-
-@noindent
-Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
-@code{nil}, thus avoiding an error.
-
-@code{and} expressions can also be written using either @code{if} or
-@code{cond}. Here's how:
-
-@example
-@group
-(and @var{arg1} @var{arg2} @var{arg3})
-@equiv{}
-(if @var{arg1} (if @var{arg2} @var{arg3}))
-@equiv{}
-(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
-@end group
-@end example
-@end defspec
-
-@defspec or conditions@dots{}
-The @code{or} special form tests whether at least one of the
-@var{conditions} is true. It works by evaluating all the
-@var{conditions} one by one in the order written.
-
-If any of the @var{conditions} evaluates to a non-@code{nil} value, then
-the result of the @code{or} must be non-@code{nil}; so @code{or} returns
-right away, ignoring the remaining @var{conditions}. The value it
-returns is the non-@code{nil} value of the condition just evaluated.
-
-If all the @var{conditions} turn out @code{nil}, then the @code{or}
-expression returns @code{nil}. Just @code{(or)}, with no
-@var{conditions}, returns @code{nil}, appropriate because all the
-@var{conditions} turned out @code{nil}. (Think about it; which one
-did not?)
-
-For example, this expression tests whether @code{x} is either
-@code{nil} or the integer zero:
-
-@example
-(or (eq x nil) (eq x 0))
-@end example
-
-Like the @code{and} construct, @code{or} can be written in terms of
-@code{cond}. For example:
-
-@example
-@group
-(or @var{arg1} @var{arg2} @var{arg3})
-@equiv{}
-(cond (@var{arg1})
- (@var{arg2})
- (@var{arg3}))
-@end group
-@end example
-
-You could almost write @code{or} in terms of @code{if}, but not quite:
-
-@example
-@group
-(if @var{arg1} @var{arg1}
- (if @var{arg2} @var{arg2}
- @var{arg3}))
-@end group
-@end example
-
-@noindent
-This is not completely equivalent because it can evaluate @var{arg1} or
-@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2}
-@var{arg3})} never evaluates any argument more than once.
-@end defspec
-
-@node Iteration
-@section Iteration
-@cindex iteration
-@cindex recursion
-
- Iteration means executing part of a program repetitively. For
-example, you might want to repeat some computation once for each element
-of a list, or once for each integer from 0 to @var{n}. You can do this
-in Emacs Lisp with the special form @code{while}:
-
-@defspec while condition forms@dots{}
-@code{while} first evaluates @var{condition}. If the result is
-non-@code{nil}, it evaluates @var{forms} in textual order. Then it
-reevaluates @var{condition}, and if the result is non-@code{nil}, it
-evaluates @var{forms} again. This process repeats until @var{condition}
-evaluates to @code{nil}.
-
-There is no limit on the number of iterations that may occur. The loop
-will continue until either @var{condition} evaluates to @code{nil} or
-until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}).
-
-The value of a @code{while} form is always @code{nil}.
-
-@example
-@group
-(setq num 0)
- @result{} 0
-@end group
-@group
-(while (< num 4)
- (princ (format "Iteration %d." num))
- (setq num (1+ num)))
- @print{} Iteration 0.
- @print{} Iteration 1.
- @print{} Iteration 2.
- @print{} Iteration 3.
- @result{} nil
-@end group
-@end example
-
-To write a ``repeat...until'' loop, which will execute something on each
-iteration and then do the end-test, put the body followed by the
-end-test in a @code{progn} as the first argument of @code{while}, as
-shown here:
-
-@example
-@group
-(while (progn
- (forward-line 1)
- (not (looking-at "^$"))))
-@end group
-@end example
-
-@noindent
-This moves forward one line and continues moving by lines until it
-reaches an empty line. It is peculiar in that the @code{while} has no
-body, just the end test (which also does the real work of moving point).
-@end defspec
-
- The @code{dolist} and @code{dotimes} macros provide convenient ways to
-write two common kinds of loops.
-
-@defmac dolist (var list [result]) body@dots{}
-This construct executes @var{body} once for each element of
-@var{list}, binding the variable @var{var} locally to hold the current
-element. Then it returns the value of evaluating @var{result}, or
-@code{nil} if @var{result} is omitted. For example, here is how you
-could use @code{dolist} to define the @code{reverse} function:
-
-@example
-(defun reverse (list)
- (let (value)
- (dolist (elt list value)
- (setq value (cons elt value)))))
-@end example
-@end defmac
-
-@defmac dotimes (var count [result]) body@dots{}
-This construct executes @var{body} once for each integer from 0
-(inclusive) to @var{count} (exclusive), binding the variable @var{var}
-to the integer for the current iteration. Then it returns the value
-of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
-Here is an example of using @code{dotimes} to do something 100 times:
-
-@example
-(dotimes (i 100)
- (insert "I will not obey absurd orders\n"))
-@end example
-@end defmac
-
-@node Nonlocal Exits
-@section Nonlocal Exits
-@cindex nonlocal exits
-
- A @dfn{nonlocal exit} is a transfer of control from one point in a
-program to another remote point. Nonlocal exits can occur in Emacs Lisp
-as a result of errors; you can also use them under explicit control.
-Nonlocal exits unbind all variable bindings made by the constructs being
-exited.
-
-@menu
-* 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.
-@end menu
-
-@node Catch and Throw
-@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw}
-
- Most control constructs affect only the flow of control within the
-construct itself. The function @code{throw} is the exception to this
-rule of normal program execution: it performs a nonlocal exit on
-request. (There are other exceptions, but they are for error handling
-only.) @code{throw} is used inside a @code{catch}, and jumps back to
-that @code{catch}. For example:
-
-@example
-@group
-(defun foo-outer ()
- (catch 'foo
- (foo-inner)))
-
-(defun foo-inner ()
- @dots{}
- (if x
- (throw 'foo t))
- @dots{})
-@end group
-@end example
-
-@noindent
-The @code{throw} form, if executed, transfers control straight back to
-the corresponding @code{catch}, which returns immediately. The code
-following the @code{throw} is not executed. The second argument of
-@code{throw} is used as the return value of the @code{catch}.
-
- The function @code{throw} finds the matching @code{catch} based on the
-first argument: it searches for a @code{catch} whose first argument is
-@code{eq} to the one specified in the @code{throw}. If there is more
-than one applicable @code{catch}, the innermost one takes precedence.
-Thus, in the above example, the @code{throw} specifies @code{foo}, and
-the @code{catch} in @code{foo-outer} specifies the same symbol, so that
-@code{catch} is the applicable one (assuming there is no other matching
-@code{catch} in between).
-
- Executing @code{throw} exits all Lisp constructs up to the matching
-@code{catch}, including function calls. When binding constructs such as
-@code{let} or function calls are exited in this way, the bindings are
-unbound, just as they are when these constructs exit normally
-(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer
-and position saved by @code{save-excursion} (@pxref{Excursions}), and
-the narrowing status saved by @code{save-restriction} and the window
-selection saved by @code{save-window-excursion} (@pxref{Window
-Configurations}). It also runs any cleanups established with the
-@code{unwind-protect} special form when it exits that form
-(@pxref{Cleanups}).
-
- The @code{throw} need not appear lexically within the @code{catch}
-that it jumps to. It can equally well be called from another function
-called within the @code{catch}. As long as the @code{throw} takes place
-chronologically after entry to the @code{catch}, and chronologically
-before exit from it, it has access to that @code{catch}. This is why
-@code{throw} can be used in commands such as @code{exit-recursive-edit}
-that throw back to the editor command loop (@pxref{Recursive Editing}).
-
-@cindex CL note---only @code{throw} in Emacs
-@quotation
-@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp,
-have several ways of transferring control nonsequentially: @code{return},
-@code{return-from}, and @code{go}, for example. Emacs Lisp has only
-@code{throw}.
-@end quotation
-
-@defspec catch tag body@dots{}
-@cindex tag on run time stack
-@code{catch} establishes a return point for the @code{throw} function.
-The return point is distinguished from other such return points by
-@var{tag}, which may be any Lisp object except @code{nil}. The argument
-@var{tag} is evaluated normally before the return point is established.
-
-With the return point in effect, @code{catch} evaluates the forms of the
-@var{body} in textual order. If the forms execute normally (without
-error or nonlocal exit) the value of the last body form is returned from
-the @code{catch}.
-
-If a @code{throw} is executed during the execution of @var{body},
-specifying the same value @var{tag}, the @code{catch} form exits
-immediately; the value it returns is whatever was specified as the
-second argument of @code{throw}.
-@end defspec
-
-@defun throw tag value
-The purpose of @code{throw} is to return from a return point previously
-established with @code{catch}. The argument @var{tag} is used to choose
-among the various existing return points; it must be @code{eq} to the value
-specified in the @code{catch}. If multiple return points match @var{tag},
-the innermost one is used.
-
-The argument @var{value} is used as the value to return from that
-@code{catch}.
-
-@kindex no-catch
-If no return point is in effect with tag @var{tag}, then a @code{no-catch}
-error is signaled with data @code{(@var{tag} @var{value})}.
-@end defun
-
-@node Examples of Catch
-@subsection Examples of @code{catch} and @code{throw}
-
- One way to use @code{catch} and @code{throw} is to exit from a doubly
-nested loop. (In most languages, this would be done with a ``go to.'')
-Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
-varying from 0 to 9:
-
-@example
-@group
-(defun search-foo ()
- (catch 'loop
- (let ((i 0))
- (while (< i 10)
- (let ((j 0))
- (while (< j 10)
- (if (foo i j)
- (throw 'loop (list i j)))
- (setq j (1+ j))))
- (setq i (1+ i))))))
-@end group
-@end example
-
-@noindent
-If @code{foo} ever returns non-@code{nil}, we stop immediately and return a
-list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the
-@code{catch} returns normally, and the value is @code{nil}, since that
-is the result of the @code{while}.
-
- Here are two tricky examples, slightly different, showing two
-return points at once. First, two return points with the same tag,
-@code{hack}:
-
-@example
-@group
-(defun catch2 (tag)
- (catch tag
- (throw 'hack 'yes)))
-@result{} catch2
-@end group
-
-@group
-(catch 'hack
- (print (catch2 'hack))
- 'no)
-@print{} yes
-@result{} no
-@end group
-@end example
-
-@noindent
-Since both return points have tags that match the @code{throw}, it goes to
-the inner one, the one established in @code{catch2}. Therefore,
-@code{catch2} returns normally with value @code{yes}, and this value is
-printed. Finally the second body form in the outer @code{catch}, which is
-@code{'no}, is evaluated and returned from the outer @code{catch}.
-
- Now let's change the argument given to @code{catch2}:
-
-@example
-@group
-(catch 'hack
- (print (catch2 'quux))
- 'no)
-@result{} yes
-@end group
-@end example
-
-@noindent
-We still have two return points, but this time only the outer one has
-the tag @code{hack}; the inner one has the tag @code{quux} instead.
-Therefore, @code{throw} makes the outer @code{catch} return the value
-@code{yes}. The function @code{print} is never called, and the
-body-form @code{'no} is never evaluated.
-
-@node Errors
-@subsection Errors
-@cindex errors
-
- When Emacs Lisp attempts to evaluate a form that, for some reason,
-cannot be evaluated, it @dfn{signals} an @dfn{error}.
-
- When an error is signaled, Emacs's default reaction is to print an
-error message and terminate execution of the current command. This is
-the right thing to do in most cases, such as if you type @kbd{C-f} at
-the end of the buffer.
-
- In complicated programs, simple termination may not be what you want.
-For example, the program may have made temporary changes in data
-structures, or created temporary buffers that should be deleted before
-the program is finished. In such cases, you would use
-@code{unwind-protect} to establish @dfn{cleanup expressions} to be
-evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may
-wish the program to continue execution despite an error in a subroutine.
-In these cases, you would use @code{condition-case} to establish
-@dfn{error handlers} to recover control in case of error.
-
- Resist the temptation to use error handling to transfer control from
-one part of the program to another; use @code{catch} and @code{throw}
-instead. @xref{Catch and Throw}.
-
-@menu
-* 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.
-@end menu
-
-@node Signaling Errors
-@subsubsection How to Signal an Error
-@cindex signaling errors
-
- @dfn{Signaling} an error means beginning error processing. Error
-processing normally aborts all or part of the running program and
-returns to a point that is set up to handle the error
-(@pxref{Processing of Errors}). Here we describe how to signal an
-error.
-
- Most errors are signaled ``automatically'' within Lisp primitives
-which you call for other purposes, such as if you try to take the
-@sc{car} of an integer or move forward a character at the end of the
-buffer. You can also signal errors explicitly with the functions
-@code{error} and @code{signal}.
-
- Quitting, which happens when the user types @kbd{C-g}, is not
-considered an error, but it is handled almost like an error.
-@xref{Quitting}.
-
- Every error specifies an error message, one way or another. The
-message should state what is wrong (``File does not exist''), not how
-things ought to be (``File must exist''). The convention in Emacs
-Lisp is that error messages should start with a capital letter, but
-should not end with any sort of punctuation.
-
-@defun error format-string &rest args
-This function signals an error with an error message constructed by
-applying @code{format} (@pxref{Formatting Strings}) to
-@var{format-string} and @var{args}.
-
-These examples show typical uses of @code{error}:
-
-@example
-@group
-(error "That is an error -- try something else")
- @error{} That is an error -- try something else
-@end group
-
-@group
-(error "You have committed %d errors" 10)
- @error{} You have committed 10 errors
-@end group
-@end example
-
-@code{error} works by calling @code{signal} with two arguments: the
-error symbol @code{error}, and a list containing the string returned by
-@code{format}.
-
-@strong{Warning:} If you want to use your own string as an error message
-verbatim, don't just write @code{(error @var{string})}. If @var{string}
-contains @samp{%}, it will be interpreted as a format specifier, with
-undesirable results. Instead, use @code{(error "%s" @var{string})}.
-@end defun
-
-@defun signal error-symbol data
-@anchor{Definition of signal}
-This function signals an error named by @var{error-symbol}. The
-argument @var{data} is a list of additional Lisp objects relevant to
-the circumstances of the error.
-
-The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
-bearing a property @code{error-conditions} whose value is a list of
-condition names. This is how Emacs Lisp classifies different sorts of
-errors. @xref{Error Symbols}, for a description of error symbols,
-error conditions and condition names.
-
-If the error is not handled, the two arguments are used in printing
-the error message. Normally, this error message is provided by the
-@code{error-message} property of @var{error-symbol}. If @var{data} is
-non-@code{nil}, this is followed by a colon and a comma separated list
-of the unevaluated elements of @var{data}. For @code{error}, the
-error message is the @sc{car} of @var{data} (that must be a string).
-Subcategories of @code{file-error} are handled specially.
-
-The number and significance of the objects in @var{data} depends on
-@var{error-symbol}. For example, with a @code{wrong-type-arg} error,
-there should be two objects in the list: a predicate that describes the type
-that was expected, and the object that failed to fit that type.
-
-Both @var{error-symbol} and @var{data} are available to any error
-handlers that handle the error: @code{condition-case} binds a local
-variable to a list of the form @code{(@var{error-symbol} .@:
-@var{data})} (@pxref{Handling Errors}).
-
-The function @code{signal} never returns (though in older Emacs versions
-it could sometimes return).
-
-@smallexample
-@group
-(signal 'wrong-number-of-arguments '(x y))
- @error{} Wrong number of arguments: x, y
-@end group
-
-@group
-(signal 'no-such-error '("My unknown error condition"))
- @error{} peculiar error: "My unknown error condition"
-@end group
-@end smallexample
-@end defun
-
-@cindex CL note---no continuable errors
-@quotation
-@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp
-concept of continuable errors.
-@end quotation
-
-@node Processing of Errors
-@subsubsection How Emacs Processes Errors
-
-When an error is signaled, @code{signal} searches for an active
-@dfn{handler} for the error. A handler is a sequence of Lisp
-expressions designated to be executed if an error happens in part of the
-Lisp program. If the error has an applicable handler, the handler is
-executed, and control resumes following the handler. The handler
-executes in the environment of the @code{condition-case} that
-established it; all functions called within that @code{condition-case}
-have already been exited, and the handler cannot return to them.
-
-If there is no applicable handler for the error, it terminates the
-current command and returns control to the editor command loop. (The
-command loop has an implicit handler for all kinds of errors.) The
-command loop's handler uses the error symbol and associated data to
-print an error message. You can use the variable
-@code{command-error-function} to control how this is done:
-
-@defvar command-error-function
-This variable, if non-@code{nil}, specifies a function to use to
-handle errors that return control to the Emacs command loop. The
-function should take three arguments: @var{data}, a list of the same
-form that @code{condition-case} would bind to its variable;
-@var{context}, a string describing the situation in which the error
-occurred, or (more often) @code{nil}; and @var{caller}, the Lisp
-function which called the primitive that signaled the error.
-@end defvar
-
-@cindex @code{debug-on-error} use
-An error that has no explicit handler may call the Lisp debugger. The
-debugger is enabled if the variable @code{debug-on-error} (@pxref{Error
-Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs
-in the environment of the error, so that you can examine values of
-variables precisely as they were at the time of the error.
-
-@node Handling Errors
-@subsubsection Writing Code to Handle Errors
-@cindex error handler
-@cindex handling errors
-
- The usual effect of signaling an error is to terminate the command
-that is running and return immediately to the Emacs editor command loop.
-You can arrange to trap errors occurring in a part of your program by
-establishing an error handler, with the special form
-@code{condition-case}. A simple example looks like this:
-
-@example
-@group
-(condition-case nil
- (delete-file filename)
- (error nil))
-@end group
-@end example
-
-@noindent
-This deletes the file named @var{filename}, catching any error and
-returning @code{nil} if an error occurs.
-
- The @code{condition-case} construct is often used to trap errors that
-are predictable, such as failure to open a file in a call to
-@code{insert-file-contents}. It is also used to trap errors that are
-totally unpredictable, such as when the program evaluates an expression
-read from the user.
-
- The second argument of @code{condition-case} is called the
-@dfn{protected form}. (In the example above, the protected form is a
-call to @code{delete-file}.) The error handlers go into effect when
-this form begins execution and are deactivated when this form returns.
-They remain in effect for all the intervening time. In particular, they
-are in effect during the execution of functions called by this form, in
-their subroutines, and so on. This is a good thing, since, strictly
-speaking, errors can be signaled only by Lisp primitives (including
-@code{signal} and @code{error}) called by the protected form, not by the
-protected form itself.
-
- The arguments after the protected form are handlers. Each handler
-lists one or more @dfn{condition names} (which are symbols) to specify
-which errors it will handle. The error symbol specified when an error
-is signaled also defines a list of condition names. A handler applies
-to an error if they have any condition names in common. In the example
-above, there is one handler, and it specifies one condition name,
-@code{error}, which covers all errors.
-
- The search for an applicable handler checks all the established handlers
-starting with the most recently established one. Thus, if two nested
-@code{condition-case} forms offer to handle the same error, the inner of
-the two gets to handle it.
-
- If an error is handled by some @code{condition-case} form, this
-ordinarily prevents the debugger from being run, even if
-@code{debug-on-error} says this error should invoke the debugger.
-
- If you want to be able to debug errors that are caught by a
-@code{condition-case}, set the variable @code{debug-on-signal} to a
-non-@code{nil} value. You can also specify that a particular handler
-should let the debugger run first, by writing @code{debug} among the
-conditions, like this:
-
-@example
-@group
-(condition-case nil
- (delete-file filename)
- ((debug error) nil))
-@end group
-@end example
-
-@noindent
-The effect of @code{debug} here is only to prevent
-@code{condition-case} from suppressing the call to the debugger. Any
-given error will invoke the debugger only if @code{debug-on-error} and
-the other usual filtering mechanisms say it should. @xref{Error Debugging}.
-
- Once Emacs decides that a certain handler handles the error, it
-returns control to that handler. To do so, Emacs unbinds all variable
-bindings made by binding constructs that are being exited, and
-executes the cleanups of all @code{unwind-protect} forms that are
-being exited. Once control arrives at the handler, the body of the
-handler executes normally.
-
- After execution of the handler body, execution returns from the
-@code{condition-case} form. Because the protected form is exited
-completely before execution of the handler, the handler cannot resume
-execution at the point of the error, nor can it examine variable
-bindings that were made within the protected form. All it can do is
-clean up and proceed.
-
- Error signaling and handling have some resemblance to @code{throw} and
-@code{catch} (@pxref{Catch and Throw}), but they are entirely separate
-facilities. An error cannot be caught by a @code{catch}, and a
-@code{throw} cannot be handled by an error handler (though using
-@code{throw} when there is no suitable @code{catch} signals an error
-that can be handled).
-
-@defspec condition-case var protected-form handlers@dots{}
-This special form establishes the error handlers @var{handlers} around
-the execution of @var{protected-form}. If @var{protected-form} executes
-without error, the value it returns becomes the value of the
-@code{condition-case} form; in this case, the @code{condition-case} has
-no effect. The @code{condition-case} form makes a difference when an
-error occurs during @var{protected-form}.
-
-Each of the @var{handlers} is a list of the form @code{(@var{conditions}
-@var{body}@dots{})}. Here @var{conditions} is an error condition name
-to be handled, or a list of condition names (which can include @code{debug}
-to allow the debugger to run before the handler); @var{body} is one or more
-Lisp expressions to be executed when this handler handles an error.
-Here are examples of handlers:
-
-@smallexample
-@group
-(error nil)
-
-(arith-error (message "Division by zero"))
-
-((arith-error file-error)
- (message
- "Either division by zero or failure to open a file"))
-@end group
-@end smallexample
-
-Each error that occurs has an @dfn{error symbol} that describes what
-kind of error it is. The @code{error-conditions} property of this
-symbol is a list of condition names (@pxref{Error Symbols}). Emacs
-searches all the active @code{condition-case} forms for a handler that
-specifies one or more of these condition names; the innermost matching
-@code{condition-case} handles the error. Within this
-@code{condition-case}, the first applicable handler handles the error.
-
-After executing the body of the handler, the @code{condition-case}
-returns normally, using the value of the last form in the handler body
-as the overall value.
-
-@cindex error description
-The argument @var{var} is a variable. @code{condition-case} does not
-bind this variable when executing the @var{protected-form}, only when it
-handles an error. At that time, it binds @var{var} locally to an
-@dfn{error description}, which is a list giving the particulars of the
-error. The error description has the form @code{(@var{error-symbol}
-. @var{data})}. The handler can refer to this list to decide what to
-do. For example, if the error is for failure opening a file, the file
-name is the second element of @var{data}---the third element of the
-error description.
-
-If @var{var} is @code{nil}, that means no variable is bound. Then the
-error symbol and associated data are not available to the handler.
-@end defspec
-
-@defun error-message-string error-description
-This function returns the error message string for a given error
-descriptor. It is useful if you want to handle an error by printing the
-usual error message for that error. @xref{Definition of signal}.
-@end defun
-
-@cindex @code{arith-error} example
-Here is an example of using @code{condition-case} to handle the error
-that results from dividing by zero. The handler displays the error
-message (but without a beep), then returns a very large number.
-
-@smallexample
-@group
-(defun safe-divide (dividend divisor)
- (condition-case err
- ;; @r{Protected form.}
- (/ dividend divisor)
-@end group
-@group
- ;; @r{The handler.}
- (arith-error ; @r{Condition.}
- ;; @r{Display the usual message for this error.}
- (message "%s" (error-message-string err))
- 1000000)))
-@result{} safe-divide
-@end group
-
-@group
-(safe-divide 5 0)
- @print{} Arithmetic error: (arith-error)
-@result{} 1000000
-@end group
-@end smallexample
-
-@noindent
-The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus,
-
-@smallexample
-@group
-(safe-divide nil 3)
- @error{} Wrong type argument: number-or-marker-p, nil
-@end group
-@end smallexample
-
- Here is a @code{condition-case} that catches all kinds of errors,
-including those signaled with @code{error}:
-
-@smallexample
-@group
-(setq baz 34)
- @result{} 34
-@end group
-
-@group
-(condition-case err
- (if (eq baz 35)
- t
- ;; @r{This is a call to the function @code{error}.}
- (error "Rats! The variable %s was %s, not 35" 'baz baz))
- ;; @r{This is the handler; it is not a form.}
- (error (princ (format "The error was: %s" err))
- 2))
-@print{} The error was: (error "Rats! The variable baz was 34, not 35")
-@result{} 2
-@end group
-@end smallexample
-
-@node Error Symbols
-@subsubsection Error Symbols and Condition Names
-@cindex error symbol
-@cindex error name
-@cindex condition name
-@cindex user-defined error
-@kindex error-conditions
-
- When you signal an error, you specify an @dfn{error symbol} to specify
-the kind of error you have in mind. Each error has one and only one
-error symbol to categorize it. This is the finest classification of
-errors defined by the Emacs Lisp language.
-
- These narrow classifications are grouped into a hierarchy of wider
-classes called @dfn{error conditions}, identified by @dfn{condition
-names}. The narrowest such classes belong to the error symbols
-themselves: each error symbol is also a condition name. There are also
-condition names for more extensive classes, up to the condition name
-@code{error} which takes in all kinds of errors (but not @code{quit}).
-Thus, each error has one or more condition names: @code{error}, the
-error symbol if that is distinct from @code{error}, and perhaps some
-intermediate classifications.
-
- In order for a symbol to be an error symbol, it must have an
-@code{error-conditions} property which gives a list of condition names.
-This list defines the conditions that this kind of error belongs to.
-(The error symbol itself, and the symbol @code{error}, should always be
-members of this list.) Thus, the hierarchy of condition names is
-defined by the @code{error-conditions} properties of the error symbols.
-Because quitting is not considered an error, the value of the
-@code{error-conditions} property of @code{quit} is just @code{(quit)}.
-
-@cindex peculiar error
- In addition to the @code{error-conditions} list, the error symbol
-should have an @code{error-message} property whose value is a string to
-be printed when that error is signaled but not handled. If the
-error symbol has no @code{error-message} property or if the
-@code{error-message} property exists, but is not a string, the error
-message @samp{peculiar error} is used. @xref{Definition of signal}.
-
- Here is how we define a new error symbol, @code{new-error}:
-
-@example
-@group
-(put 'new-error
- 'error-conditions
- '(error my-own-errors new-error))
-@result{} (error my-own-errors new-error)
-@end group
-@group
-(put 'new-error 'error-message "A new error")
-@result{} "A new error"
-@end group
-@end example
-
-@noindent
-This error has three condition names: @code{new-error}, the narrowest
-classification; @code{my-own-errors}, which we imagine is a wider
-classification; and @code{error}, which is the widest of all.
-
- The error string should start with a capital letter but it should
-not end with a period. This is for consistency with the rest of Emacs.
-
- Naturally, Emacs will never signal @code{new-error} on its own; only
-an explicit call to @code{signal} (@pxref{Definition of signal}) in
-your code can do this:
-
-@example
-@group
-(signal 'new-error '(x y))
- @error{} A new error: x, y
-@end group
-@end example
-
- This error can be handled through any of the three condition names.
-This example handles @code{new-error} and any other errors in the class
-@code{my-own-errors}:
-
-@example
-@group
-(condition-case foo
- (bar nil t)
- (my-own-errors nil))
-@end group
-@end example
-
- The significant way that errors are classified is by their condition
-names---the names used to match errors with handlers. An error symbol
-serves only as a convenient way to specify the intended error message
-and list of condition names. It would be cumbersome to give
-@code{signal} a list of condition names rather than one error symbol.
-
- By contrast, using only error symbols without condition names would
-seriously decrease the power of @code{condition-case}. Condition names
-make it possible to categorize errors at various levels of generality
-when you write an error handler. Using error symbols alone would
-eliminate all but the narrowest level of classification.
-
- @xref{Standard Errors}, for a list of all the standard error symbols
-and their conditions.
-
-@node Cleanups
-@subsection Cleaning Up from Nonlocal Exits
-
- The @code{unwind-protect} construct is essential whenever you
-temporarily put a data structure in an inconsistent state; it permits
-you to make the data consistent again in the event of an error or
-throw. (Another more specific cleanup construct that is used only for
-changes in buffer contents is the atomic change group; @ref{Atomic
-Changes}.)
-
-@defspec unwind-protect body-form cleanup-forms@dots{}
-@cindex cleanup forms
-@cindex protected forms
-@cindex error cleanup
-@cindex unwinding
-@code{unwind-protect} executes @var{body-form} with a guarantee that
-the @var{cleanup-forms} will be evaluated if control leaves
-@var{body-form}, no matter how that happens. @var{body-form} may
-complete normally, or execute a @code{throw} out of the
-@code{unwind-protect}, or cause an error; in all cases, the
-@var{cleanup-forms} will be evaluated.
-
-If @var{body-form} finishes normally, @code{unwind-protect} returns the
-value of @var{body-form}, after it evaluates the @var{cleanup-forms}.
-If @var{body-form} does not finish, @code{unwind-protect} does not
-return any value in the normal sense.
-
-Only @var{body-form} is protected by the @code{unwind-protect}. If any
-of the @var{cleanup-forms} themselves exits nonlocally (via a
-@code{throw} or an error), @code{unwind-protect} is @emph{not}
-guaranteed to evaluate the rest of them. If the failure of one of the
-@var{cleanup-forms} has the potential to cause trouble, then protect
-it with another @code{unwind-protect} around that form.
-
-The number of currently active @code{unwind-protect} forms counts,
-together with the number of local variable bindings, against the limit
-@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local
-Variables}).
-@end defspec
-
- For example, here we make an invisible buffer for temporary use, and
-make sure to kill it before finishing:
-
-@smallexample
-@group
-(save-excursion
- (let ((buffer (get-buffer-create " *temp*")))
- (set-buffer buffer)
- (unwind-protect
- @var{body-form}
- (kill-buffer buffer))))
-@end group
-@end smallexample
-
-@noindent
-You might think that we could just as well write @code{(kill-buffer
-(current-buffer))} and dispense with the variable @code{buffer}.
-However, the way shown above is safer, if @var{body-form} happens to
-get an error after switching to a different buffer! (Alternatively,
-you could write another @code{save-excursion} around @var{body-form},
-to ensure that the temporary buffer becomes current again in time to
-kill it.)
-
- Emacs includes a standard macro called @code{with-temp-buffer} which
-expands into more or less the code shown above (@pxref{Definition of
-with-temp-buffer,, Current Buffer}). Several of the macros defined in
-this manual use @code{unwind-protect} in this way.
-
-@findex ftp-login
- Here is an actual example derived from an FTP package. It creates a
-process (@pxref{Processes}) to try to establish a connection to a remote
-machine. As the function @code{ftp-login} is highly susceptible to
-numerous problems that the writer of the function cannot anticipate, it
-is protected with a form that guarantees deletion of the process in the
-event of failure. Otherwise, Emacs might fill up with useless
-subprocesses.
-
-@smallexample
-@group
-(let ((win nil))
- (unwind-protect
- (progn
- (setq process (ftp-setup-buffer host file))
- (if (setq win (ftp-login process host user password))
- (message "Logged in")
- (error "Ftp login failed")))
- (or win (and process (delete-process process)))))
-@end group
-@end smallexample
-
- This example has a small bug: if the user types @kbd{C-g} to
-quit, and the quit happens immediately after the function
-@code{ftp-setup-buffer} returns but before the variable @code{process} is
-set, the process will not be killed. There is no easy way to fix this bug,
-but at least it is very unlikely.
-
-@ignore
- arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/customize
-@node Customization, Loading, Macros, Top
-@chapter Writing Customization Definitions
-
-@cindex customization definitions
- This chapter describes how to declare user options for customization,
-and also customization groups for classifying them. We use the term
-@dfn{customization item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
-
-@menu
-* 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.
-@end menu
-
-@node Common Keywords
-@section Common Item Keywords
-
-@cindex customization keywords
- All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
-
- All of these keywords, except @code{:tag}, can be used more than once
-in a given item. Each use of the keyword has an independent effect.
-The keyword @code{:tag} is an exception because any given item can only
-display one name.
-
-@table @code
-@item :tag @var{label}
-@kindex tag@r{, customization keyword}
-Use @var{label}, a string, instead of the item's name, to label the
-item in customization menus and buffers. @strong{Don't use a tag
-which is substantially different from the item's real name; that would
-cause confusion.} One legitimate case for use of @code{:tag} is to
-specify a dash where normally a hyphen would be converted to a space:
-
-@example
-(defcustom cursor-in-non-selected-windows @dots{}
- :tag "Cursor In Non-selected Windows"
-@end example
-
-@kindex group@r{, customization keyword}
-@item :group @var{group}
-Put this customization item in group @var{group}. When you use
-@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
-@var{group}.
-
-If you use this keyword more than once, you can put a single item into
-more than one group. Displaying any of those groups will show this
-item. Please don't overdo this, since the result would be annoying.
-
-@item :link @var{link-data}
-@kindex link@r{, customization keyword}
-Include an external link after the documentation string for this item.
-This is a sentence containing an active field which references some
-other documentation.
-
-There are several alternatives you can use for @var{link-data}:
-
-@table @code
-@item (custom-manual @var{info-node})
-Link to an Info node; @var{info-node} is a string which specifies the
-node name, as in @code{"(emacs)Top"}. The link appears as
-@samp{[Manual]} in the customization buffer and enters the built-in
-Info reader on @var{info-node}.
-
-@item (info-link @var{info-node})
-Like @code{custom-manual} except that the link appears
-in the customization buffer with the Info node name.
-
-@item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the
-@acronym{URL}. The link appears in the customization buffer as
-@var{url} and invokes the WWW browser specified by
-@code{browse-url-browser-function}.
-
-@item (emacs-commentary-link @var{library})
-Link to the commentary section of a library; @var{library} is a string
-which specifies the library name.
-
-@item (emacs-library-link @var{library})
-Link to an Emacs Lisp library file; @var{library} is a string which
-specifies the library name.
-
-@item (file-link @var{file})
-Link to a file; @var{file} is a string which specifies the name of the
-file to visit with @code{find-file} when the user invokes this link.
-
-@item (function-link @var{function})
-Link to the documentation of a function; @var{function} is a string
-which specifies the name of the function to describe with
-@code{describe-function} when the user invokes this link.
-
-@item (variable-link @var{variable})
-Link to the documentation of a variable; @var{variable} is a string
-which specifies the name of the variable to describe with
-@code{describe-variable} when the user invokes this link.
-
-@item (custom-group-link @var{group})
-Link to another customization group. Invoking it creates a new
-customization buffer for @var{group}.
-@end table
-
-You can specify the text to use in the customization buffer by adding
-@code{:tag @var{name}} after the first element of the @var{link-data};
-for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
-the Emacs manual which appears in the buffer as @samp{foo}.
-
-An item can have more than one external link; however, most items have
-none at all.
-
-@item :load @var{file}
-@kindex load@r{, customization keyword}
-Load file @var{file} (a string) before displaying this customization
-item. Loading is done with @code{load-library}, and only if the file is
-not already loaded.
-
-@item :require @var{feature}
-@kindex require@r{, customization keyword}
-Execute @code{(require '@var{feature})} when your saved customizations
-set the value of this item. @var{feature} should be a symbol.
-
-The most common reason to use @code{:require} is when a variable enables
-a feature such as a minor mode, and just setting the variable won't have
-any effect unless the code which implements the mode is loaded.
-
-@item :version @var{version}
-@kindex version@r{, customization keyword}
-This keyword specifies that the item was first introduced in Emacs
-version @var{version}, or that its default value was changed in that
-version. The value @var{version} must be a string.
-
-@item :package-version '(@var{package} . @var{version})
-@kindex package-version@r{, customization keyword}
-This keyword specifies that the item was first introduced in
-@var{package} version @var{version}, or that its meaning or default
-value was changed in that version. The value of @var{package} is a
-symbol and @var{version} is a string.
-
-This keyword takes priority over @code{:version}.
-
-@var{package} should be the official name of the package, such as MH-E
-or Gnus. If the package @var{package} is released as part of Emacs,
-@var{package} and @var{version} should appear in the value of
-@code{customize-package-emacs-version-alist}.
-@end table
-
-Packages distributed as part of Emacs that use the
-@code{:package-version} keyword must also update the
-@code{customize-package-emacs-version-alist} variable.
-
-@defvar customize-package-emacs-version-alist
-This alist provides a mapping for the versions of Emacs that are
-associated with versions of a package listed in the
-@code{:package-version} keyword. Its elements look like this:
-
-@example
-(@var{package} (@var{pversion} . @var{eversion})@dots{})
-@end example
-
-For each @var{package}, which is a symbol, there are one or more
-elements that contain a package version @var{pversion} with an
-associated Emacs version @var{eversion}. These versions are strings.
-For example, the MH-E package updates this alist with the following:
-
-@smallexample
-(add-to-list 'customize-package-emacs-version-alist
- '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
- ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
- ("7.4" . "22.1") ("8.0" . "22.1")))
-@end smallexample
-
-The value of @var{package} needs to be unique and it needs to match
-the @var{package} value appearing in the @code{:package-version}
-keyword. Since the user might see the value in a error message, a good
-choice is the official name of the package, such as MH-E or Gnus.
-@end defvar
-
-@node Group Definitions
-@section Defining Customization Groups
-@cindex define customization group
-@cindex customization groups, defining
-
- Each Emacs Lisp package should have one main customization group which
-contains all the options, faces and other groups in the package. If the
-package has a small number of options and faces, use just one group and
-put everything in it. When there are more than twelve or so options and
-faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group. It is OK to
-put some of the options and faces in the package's main group alongside
-the subgroups.
-
- The package's main or only group should be a member of one or more of
-the standard customization groups. (To display the full list of them,
-use @kbd{M-x customize}.) Choose one or more of them (but not too
-many), and add your group to each of them using the @code{:group}
-keyword.
-
- The way to declare new customization groups is with @code{defgroup}.
-
-@defmac defgroup group members doc [keyword value]@dots{}
-Declare @var{group} as a customization group containing @var{members}.
-Do not quote the symbol @var{group}. The argument @var{doc} specifies
-the documentation string for the group.
-
-The argument @var{members} is a list specifying an initial set of
-customization items to be members of the group. However, most often
-@var{members} is @code{nil}, and you specify the group's members by
-using the @code{:group} keyword when defining those members.
-
-If you want to specify group members through @var{members}, each element
-should have the form @code{(@var{name} @var{widget})}. Here @var{name}
-is a symbol, and @var{widget} is a widget type for editing that symbol.
-Useful widgets are @code{custom-variable} for a variable,
-@code{custom-face} for a face, and @code{custom-group} for a group.
-
-When you introduce a new group into Emacs, use the @code{:version}
-keyword in the @code{defgroup}; then you need not use it for
-the individual members of the group.
-
-In addition to the common keywords (@pxref{Common Keywords}), you can
-also use this keyword in @code{defgroup}:
-
-@table @code
-@item :prefix @var{prefix}
-@kindex prefix@r{, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
-@end table
-@end defmac
-
- The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect. We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options. This happened because the people who wrote the
-@code{defgroup} definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
-
- In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation. If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
-
- It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
-
-@node Variable Definitions
-@section Defining Customization Variables
-@cindex define customization options
-@cindex customization variables, how to define
-
- Use @code{defcustom} to declare user-customizable variables.
-
-@defmac defcustom option standard doc [keyword value]@dots{}
-This construct declares @var{option} as a customizable user option
-variable. You should not quote @var{option}. The argument @var{doc}
-specifies the documentation string for the variable. There is no need
-to start it with a @samp{*}, because @code{defcustom} automatically
-marks @var{option} as a @dfn{user option} (@pxref{Defining
-Variables}).
-
-The argument @var{standard} is an expression that specifies the
-standard value for @var{option}. Evaluating the @code{defcustom} form
-evaluates @var{standard}, but does not necessarily install the
-standard value. If @var{option} already has a default value,
-@code{defcustom} does not change it. If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value. If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
-@var{standard} as the default value.
-
-The expression @var{standard} can be evaluated at various other times,
-too---whenever the customization facility needs to know @var{option}'s
-standard value. So be sure to use an expression which is harmless to
-evaluate at any time. We recommend avoiding backquotes in
-@var{standard}, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
-
-Every @code{defcustom} should specify @code{:group} at least once.
-
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
-
-When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
-mode (@code{eval-defun}), a special feature of @code{eval-defun}
-arranges to set the variable unconditionally, without testing whether
-its value is void. (The same feature applies to @code{defvar}.)
-@xref{Defining Variables}.
-@end defmac
-
- @code{defcustom} accepts the following additional keywords:
-
-@table @code
-@item :type @var{type}
-Use @var{type} as the data type for this option. It specifies which
-values are legitimate, and how to display the value.
-@xref{Customization Types}, for more information.
-
-@item :options @var{value-list}
-@kindex options@r{, @code{defcustom} keyword}
-Specify the list of reasonable values for use in this
-option. The user is not restricted to using only these values, but they
-are offered as convenient alternatives.
-
-This is meaningful only for certain types, currently including
-@code{hook}, @code{plist} and @code{alist}. See the definition of the
-individual types for a description of how to use @code{:options}.
-
-@item :set @var{setfunction}
-@kindex set@r{, @code{defcustom} keyword}
-Specify @var{setfunction} as the way to change the value of this
-option. The function @var{setfunction} should take two arguments, a
-symbol (the option name) and the new value, and should do whatever is
-necessary to update the value properly for this option (which may not
-mean simply setting the option as a Lisp variable). The default for
-@var{setfunction} is @code{set-default}.
-
-@item :get @var{getfunction}
-@kindex get@r{, @code{defcustom} keyword}
-Specify @var{getfunction} as the way to extract the value of this
-option. The function @var{getfunction} should take one argument, a
-symbol, and should return whatever customize should use as the
-``current value'' for that symbol (which need not be the symbol's Lisp
-value). The default is @code{default-value}.
-
-You have to really understand the workings of Custom to use
-@code{:get} correctly. It is meant for values that are treated in
-Custom as variables but are not actually stored in Lisp variables. It
-is almost surely a mistake to specify @code{getfunction} for a value
-that really is stored in a Lisp variable.
-
-@item :initialize @var{function}
-@kindex initialize@r{, @code{defcustom} keyword}
-@var{function} should be a function used to initialize the variable
-when the @code{defcustom} is evaluated. It should take two arguments,
-the option name (a symbol) and the value. Here are some predefined
-functions meant for use in this way:
-
-@table @code
-@item custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable, but
-do not reinitialize it if it is already non-void.
-
-@item custom-initialize-default
-Like @code{custom-initialize-set}, but use the function
-@code{set-default} to set the variable, instead of the variable's
-@code{:set} function. This is the usual choice for a variable whose
-@code{:set} function enables or disables a minor mode; with this choice,
-defining the variable will not call the minor mode function, but
-customizing the variable will do so.
-
-@item custom-initialize-reset
-Always use the @code{:set} function to initialize the variable. If
-the variable is already non-void, reset it by calling the @code{:set}
-function using the current value (returned by the @code{:get} method).
-This is the default @code{:initialize} function.
-
-@item custom-initialize-changed
-Use the @code{:set} function to initialize the variable, if it is
-already set or has been customized; otherwise, just use
-@code{set-default}.
-
-@item custom-initialize-safe-set
-@itemx custom-initialize-safe-default
-These functions behave like @code{custom-initialize-set}
-(@code{custom-initialize-default}, respectively), but catch errors.
-If an error occurs during initialization, they set the variable to
-@code{nil} using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined. The option normally gets updated in
-@file{startup.el}, ignoring the previously computed value. Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom. By that time, the necessary
-variables and functions will be defined, so there will not be an error.
-@end table
-
-@item :set-after @var{variables}
-@kindex set-after@r{, @code{defcustom} keyword}
-When setting variables according to saved customizations, make sure to
-set the variables @var{variables} before this one; in other words, delay
-setting this variable until after those others have been handled. Use
-@code{:set-after} if setting this variable won't work properly unless
-those other variables already have their intended values.
-@end table
-
- The @code{:require} keyword is useful for an option that turns on the
-operation of a certain feature. Assuming that the package is coded to
-check the value of the option, you still need to arrange for the package
-to be loaded. You can do that with @code{:require}. @xref{Common
-Keywords}. Here is an example, from the library @file{saveplace.el}:
-
-@example
-(defcustom save-place nil
- "Non-nil means automatically save place in each file..."
- :type 'boolean
- :require 'saveplace
- :group 'save-place)
-@end example
-
-If a customization item has a type such as @code{hook} or
-@code{alist}, which supports @code{:options}, you can add additional
-values to the list from outside the @code{defcustom} declaration by
-calling @code{custom-add-frequent-value}. For example, if you define a
-function @code{my-lisp-mode-initialization} intended to be called from
-@code{emacs-lisp-mode-hook}, you might want to add that to the list of
-reasonable values for @code{emacs-lisp-mode-hook}, but not by editing
-its definition. You can do it thus:
-
-@example
-(custom-add-frequent-value 'emacs-lisp-mode-hook
- 'my-lisp-mode-initialization)
-@end example
-
-@defun custom-add-frequent-value symbol value
-For the customization option @var{symbol}, add @var{value} to the
-list of reasonable values.
-
-The precise effect of adding a value depends on the customization type
-of @var{symbol}.
-@end defun
-
-Internally, @code{defcustom} uses the symbol property
-@code{standard-value} to record the expression for the standard value,
-and @code{saved-value} to record the value saved by the user with the
-customization buffer. Both properties are actually lists whose car is
-an expression which evaluates to the value.
-
-@node Customization Types
-@section Customization Types
-
-@cindex customization types
- When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}. That is a Lisp object which describes (1)
-which values are legitimate and (2) how to display the value in the
-customization buffer for editing.
-
-@kindex type@r{, @code{defcustom} keyword}
- You specify the customization type in @code{defcustom} with the
-@code{:type} keyword. The argument of @code{:type} is evaluated, but
-only once when the @code{defcustom} is executed, so it isn't useful
-for the value to vary. Normally we use a quoted constant. For
-example:
-
-@example
-(defcustom diff-command "diff"
- "The command to use to run diff."
- :type '(string)
- :group 'diff)
-@end example
-
- In general, a customization type is a list whose first element is a
-symbol, one of the customization type names defined in the following
-sections. After this symbol come a number of arguments, depending on
-the symbol. Between the type symbol and its arguments, you can
-optionally write keyword-value pairs (@pxref{Type Keywords}).
-
- Some of the type symbols do not use any arguments; those are called
-@dfn{simple types}. For a simple type, if you do not use any
-keyword-value pairs, you can omit the parentheses around the type
-symbol. For example just @code{string} as a customization type is
-equivalent to @code{(string)}.
-
-@menu
-* Simple Types::
-* Composite Types::
-* Splicing into Lists::
-* Type Keywords::
-* Defining New Types::
-@end menu
-
-All customization types are implemented as widgets; see @ref{Top, ,
-Introduction, widget, The Emacs Widget Library}, for details.
-
-@node Simple Types
-@subsection Simple Types
-
- This section describes all the simple customization types.
-
-@table @code
-@item sexp
-The value may be any Lisp object that can be printed and read back. You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
-
-@item integer
-The value must be an integer, and is represented textually
-in the customization buffer.
-
-@item number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
-
-@item float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
-
-@item string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
-@samp{\}.
-
-@item regexp
-Like @code{string} except that the string must be a valid regular
-expression.
-
-@item character
-The value must be a character code. A character code is actually an
-integer, but this type shows the value by inserting the character in the
-buffer, rather than by showing the number.
-
-@item file
-The value must be a file name, and you can do completion with
-@kbd{M-@key{TAB}}.
-
-@item (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @kbd{M-@key{TAB}}.
-
-@item directory
-The value must be a directory name, and you can do completion with
-@kbd{M-@key{TAB}}.
-
-@item hook
-The value must be a list of functions (or a single function, but that is
-obsolete usage). This customization type is used for hook variables.
-You can use the @code{:options} keyword in a hook variable's
-@code{defcustom} to specify a list of functions recommended for use in
-the hook; see @ref{Variable Definitions}.
-
-@item alist
-The value must be a list of cons-cells, the @sc{car} of each cell
-representing a key, and the @sc{cdr} of the same cell representing an
-associated value. The user can add and delete key/value pairs, and
-edit both the key and the value of each pair.
-
-You can specify the key and value types like this:
-
-@smallexample
-(alist :key-type @var{key-type} :value-type @var{value-type})
-@end smallexample
-
-@noindent
-where @var{key-type} and @var{value-type} are customization type
-specifications. The default key type is @code{sexp}, and the default
-value type is @code{sexp}.
-
-The user can add any key matching the specified key type, but you can
-give some keys a preferential treatment by specifying them with the
-@code{:options} (see @ref{Variable Definitions}). The specified keys
-will always be shown in the customize buffer (together with a suitable
-value), with a checkbox to include or exclude or disable the key/value
-pair from the alist. The user will not be able to edit the keys
-specified by the @code{:options} keyword argument.
-
-The argument to the @code{:options} keywords should be a list of
-specifications for reasonable keys in the alist. Ordinarily, they are
-simply atoms, which stand for themselves as. For example:
-
-@smallexample
-:options '("foo" "bar" "baz")
-@end smallexample
-
-@noindent
-specifies that there are three ``known'' keys, namely @code{"foo"},
-@code{"bar"} and @code{"baz"}, which will always be shown first.
-
-You may want to restrict the value type for specific keys, for
-example, the value associated with the @code{"bar"} key can only be an
-integer. You can specify this by using a list instead of an atom in
-the list. The first element will specify the key, like before, while
-the second element will specify the value type. For example:
-
-@smallexample
-:options '("foo" ("bar" integer) "baz")
-@end smallexample
-
-Finally, you may want to change how the key is presented. By default,
-the key is simply shown as a @code{const}, since the user cannot change
-the special keys specified with the @code{:options} keyword. However,
-you may want to use a more specialized type for presenting the key, like
-@code{function-item} if you know it is a symbol with a function binding.
-This is done by using a customization type specification instead of a
-symbol for the key.
-
-@smallexample
-:options '("foo" ((function-item some-function) integer)
- "baz")
-@end smallexample
-
-Many alists use lists with two elements, instead of cons cells. For
-example,
-
-@smallexample
-(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
- "Each element is a list of the form (KEY VALUE).")
-@end smallexample
-
-@noindent
-instead of
-
-@smallexample
-(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
- "Each element is a cons-cell (KEY . VALUE).")
-@end smallexample
-
-Because of the way lists are implemented on top of cons cells, you can
-treat @code{list-alist} in the example above as a cons cell alist, where
-the value type is a list with a single element containing the real
-value.
-
-@smallexample
-(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
- "Each element is a list of the form (KEY VALUE)."
- :type '(alist :value-type (group integer)))
-@end smallexample
-
-The @code{group} widget is used here instead of @code{list} only because
-the formatting is better suited for the purpose.
-
-Similarly, you can have alists with more values associated with each
-key, using variations of this trick:
-
-@smallexample
-(defcustom person-data '(("brian" 50 t)
- ("dorith" 55 nil)
- ("ken" 52 t))
- "Alist of basic info about people.
-Each element has the form (NAME AGE MALE-FLAG)."
- :type '(alist :value-type (group integer boolean)))
-
-(defcustom pets '(("brian")
- ("dorith" "dog" "guppy")
- ("ken" "cat"))
- "Alist of people's pets.
-In an element (KEY . VALUE), KEY is the person's name,
-and the VALUE is a list of that person's pets."
- :type '(alist :value-type (repeat string)))
-@end smallexample
-
-@item plist
-The @code{plist} custom type is similar to the @code{alist} (see above),
-except that the information is stored as a property list, i.e. a list of
-this form:
-
-@smallexample
-(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
-@end smallexample
-
-The default @code{:key-type} for @code{plist} is @code{symbol},
-rather than @code{sexp}.
-
-@item symbol
-The value must be a symbol. It appears in the customization buffer as
-the name of the symbol.
-
-@item function
-The value must be either a lambda expression or a function name. When
-it is a function name, you can do completion with @kbd{M-@key{TAB}}.
-
-@item variable
-The value must be a variable name, and you can do completion with
-@kbd{M-@key{TAB}}.
-
-@item face
-The value must be a symbol which is a face name, and you can do
-completion with @kbd{M-@key{TAB}}.
-
-@item boolean
-The value is boolean---either @code{nil} or @code{t}. Note that by
-using @code{choice} and @code{const} together (see the next section),
-you can specify that the value must be @code{nil} or @code{t}, but also
-specify the text to describe each value in a way that fits the specific
-meaning of the alternative.
-
-@item coding-system
-The value must be a coding-system name, and you can do completion with
-@kbd{M-@key{TAB}}.
-
-@item color
-The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}. A sample is provided.
-@end table
-
-@node Composite Types
-@subsection Composite Types
-@cindex Composite Types (customization)
-
- When none of the simple types is appropriate, you can use composite
-types, which build new types from other types or from specified data.
-The specified types or data are called the @dfn{arguments} of the
-composite type. The composite type normally looks like this:
-
-@example
-(@var{constructor} @var{arguments}@dots{})
-@end example
-
-@noindent
-but you can also add keyword-value pairs before the arguments, like
-this:
-
-@example
-(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{})
-@end example
-
- Here is a table of constructors and how to use them to write
-composite types:
-
-@table @code
-@item (cons @var{car-type} @var{cdr-type})
-The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
-its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
-symbol)} is a customization type which matches values such as
-@code{("foo" . foo)}.
-
-In the customization buffer, the @sc{car} and the @sc{cdr} are
-displayed and edited separately, each according to the type
-that you specify for it.
-
-@item (list @var{element-types}@dots{})
-The value must be a list with exactly as many elements as the
-@var{element-types} given; and each element must fit the
-corresponding @var{element-type}.
-
-For example, @code{(list integer string function)} describes a list of
-three elements; the first element must be an integer, the second a
-string, and the third a function.
-
-In the customization buffer, each element is displayed and edited
-separately, according to the type specified for it.
-
-@item (vector @var{element-types}@dots{})
-Like @code{list} except that the value must be a vector instead of a
-list. The elements work the same as in @code{list}.
-
-@item (choice @var{alternative-types}@dots{})
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
-
-In the customization buffer, the user selects an alternative
-using a menu, and can then edit the value in the usual way for that
-alternative.
-
-Normally the strings in this menu are determined automatically from the
-choices; however, you can specify different strings for the menu by
-including the @code{:tag} keyword in the alternatives. For example, if
-an integer stands for a number of spaces, while a string is text to use
-verbatim, you might write the customization type this way,
-
-@example
-(choice (integer :tag "Number of spaces")
- (string :tag "Literal text"))
-@end example
-
-@noindent
-so that the menu offers @samp{Number of spaces} and @samp{Literal text}.
-
-In any alternative for which @code{nil} is not a valid value, other than
-a @code{const}, you should specify a valid default for that alternative
-using the @code{:value} keyword. @xref{Type Keywords}.
-
-If some values are covered by more than one of the alternatives,
-customize will choose the first alternative that the value fits. This
-means you should always list the most specific types first, and the
-most general last. Here's an example of proper usage:
-
-@example
-(choice (const :tag "Off" nil)
- symbol (sexp :tag "Other"))
-@end example
-
-@noindent
-This way, the special value @code{nil} is not treated like other
-symbols, and symbols are not treated like other Lisp expressions.
-
-@item (radio @var{element-types}@dots{})
-This is similar to @code{choice}, except that the choices are displayed
-using `radio buttons' rather than a menu. This has the advantage of
-displaying documentation for the choices when applicable and so is often
-a good choice for a choice between constant functions
-(@code{function-item} customization types).
-
-@item (const @var{value})
-The value must be @var{value}---nothing else is allowed.
-
-The main use of @code{const} is inside of @code{choice}. For example,
-@code{(choice integer (const nil))} allows either an integer or
-@code{nil}.
-
-@code{:tag} is often used with @code{const}, inside of @code{choice}.
-For example,
-
-@example
-(choice (const :tag "Yes" t)
- (const :tag "No" nil)
- (const :tag "Ask" foo))
-@end example
-
-@noindent
-describes a variable for which @code{t} means yes, @code{nil} means no,
-and @code{foo} means ``ask.''
-
-@item (other @var{value})
-This alternative can match any Lisp value, but if the user chooses this
-alternative, that selects the value @var{value}.
-
-The main use of @code{other} is as the last element of @code{choice}.
-For example,
-
-@example
-(choice (const :tag "Yes" t)
- (const :tag "No" nil)
- (other :tag "Ask" foo))
-@end example
-
-@noindent
-describes a variable for which @code{t} means yes, @code{nil} means no,
-and anything else means ``ask.'' If the user chooses @samp{Ask} from
-the menu of alternatives, that specifies the value @code{foo}; but any
-other value (not @code{t}, @code{nil} or @code{foo}) displays as
-@samp{Ask}, just like @code{foo}.
-
-@item (function-item @var{function})
-Like @code{const}, but used for values which are functions. This
-displays the documentation string as well as the function name.
-The documentation string is either the one you specify with
-@code{:doc}, or @var{function}'s own documentation string.
-
-@item (variable-item @var{variable})
-Like @code{const}, but used for values which are variable names. This
-displays the documentation string as well as the variable name. The
-documentation string is either the one you specify with @code{:doc}, or
-@var{variable}'s own documentation string.
-
-@item (set @var{types}@dots{})
-The value must be a list, and each element of the list must match one of
-the @var{types} specified.
-
-This appears in the customization buffer as a checklist, so that each of
-@var{types} may have either one corresponding element or none. It is
-not possible to specify two different elements that match the same one
-of @var{types}. For example, @code{(set integer symbol)} allows one
-integer and/or one symbol in the list; it does not allow multiple
-integers or multiple symbols. As a result, it is rare to use
-nonspecific types such as @code{integer} in a @code{set}.
-
-Most often, the @var{types} in a @code{set} are @code{const} types, as
-shown here:
-
-@example
-(set (const :bold) (const :italic))
-@end example
-
-Sometimes they describe possible elements in an alist:
-
-@example
-(set (cons :tag "Height" (const height) integer)
- (cons :tag "Width" (const width) integer))
-@end example
-
-@noindent
-That lets the user specify a height value optionally
-and a width value optionally.
-
-@item (repeat @var{element-type})
-The value must be a list and each element of the list must fit the type
-@var{element-type}. This appears in the customization buffer as a
-list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding
-more elements or removing elements.
-
-@item (restricted-sexp :match-alternatives @var{criteria})
-This is the most general composite type construct. The value may be
-any Lisp object that satisfies one of @var{criteria}. @var{criteria}
-should be a list, and each element should be one of these
-possibilities:
-
-@itemize @bullet
-@item
-A predicate---that is, a function of one argument that has no side
-effects, and returns either @code{nil} or non-@code{nil} according to
-the argument. Using a predicate in the list says that objects for which
-the predicate returns non-@code{nil} are acceptable.
-
-@item
-A quoted constant---that is, @code{'@var{object}}. This sort of element
-in the list says that @var{object} itself is an acceptable value.
-@end itemize
-
-For example,
-
-@example
-(restricted-sexp :match-alternatives
- (integerp 't 'nil))
-@end example
-
-@noindent
-allows integers, @code{t} and @code{nil} as legitimate values.
-
-The customization buffer shows all legitimate values using their read
-syntax, and the user edits them textually.
-@end table
-
- Here is a table of the keywords you can use in keyword-value pairs
-in a composite type:
-
-@table @code
-@item :tag @var{tag}
-Use @var{tag} as the name of this alternative, for user communication
-purposes. This is useful for a type that appears inside of a
-@code{choice}.
-
-@item :match-alternatives @var{criteria}
-@kindex match-alternatives@r{, customization keyword}
-Use @var{criteria} to match possible values. This is used only in
-@code{restricted-sexp}.
-
-@item :args @var{argument-list}
-@kindex args@r{, customization keyword}
-Use the elements of @var{argument-list} as the arguments of the type
-construct. For instance, @code{(const :args (foo))} is equivalent to
-@code{(const foo)}. You rarely need to write @code{:args} explicitly,
-because normally the arguments are recognized automatically as
-whatever follows the last keyword-value pair.
-@end table
-
-@node Splicing into Lists
-@subsection Splicing into Lists
-
- The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector. You use it in a
-@code{set}, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
- Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector. Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
- But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using @samp{,@@} in the backquote
-construct.
-
- For example, to specify a list whose first element must be @code{baz}
-and whose remaining arguments should be zero or more of @code{foo} and
-@code{bar}, use this customization type:
-
-@example
-(list (const baz) (set :inline t (const foo) (const bar)))
-@end example
-
-@noindent
-This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)}
-and @code{(baz foo bar)}.
-
- When the element-type is a @code{choice}, you use @code{:inline} not
-in the @code{choice} itself, but in (some of) the alternatives of the
-@code{choice}. For example, to match a list which must start with a
-file name, followed either by the symbol @code{t} or two strings, use
-this customization type:
-
-@example
-(list file
- (choice (const t)
- (list :inline t string string)))
-@end example
-
-@noindent
-If the user chooses the first alternative in the choice, then the
-overall list has two elements and the second element is @code{t}. If
-the user chooses the second alternative, then the overall list has three
-elements and the second and third must be strings.
-
-@node Type Keywords
-@subsection Type Keywords
-
-You can specify keyword-argument pairs in a customization type after the
-type name symbol. Here are the keywords you can use, and their
-meanings:
-
-@table @code
-@item :value @var{default}
-This is used for a type that appears as an alternative inside of
-@code{choice}; it specifies the default value to use, at first, if and
-when the user selects this alternative with the menu in the
-customization buffer.
-
-Of course, if the actual value of the option fits this alternative, it
-will appear showing the actual value, not @var{default}.
-
-If @code{nil} is not a valid value for the alternative, then it is
-essential to specify a valid default with @code{:value}.
-
-@item :format @var{format-string}
-@kindex format@r{, customization keyword}
-This string will be inserted in the buffer to represent the value
-corresponding to the type. The following @samp{%} escapes are available
-for use in @var{format-string}:
-
-@table @samp
-@item %[@var{button}%]
-Display the text @var{button} marked as a button. The @code{:action}
-attribute specifies what the button will do if the user invokes it;
-its value is a function which takes two arguments---the widget which
-the button appears in, and the event.
-
-There is no way to specify two different buttons with different
-actions.
-
-@item %@{@var{sample}%@}
-Show @var{sample} in a special face specified by @code{:sample-face}.
-
-@item %v
-Substitute the item's value. How the value is represented depends on
-the kind of item, and (for variables) on the customization type.
-
-@item %d
-Substitute the item's documentation string.
-
-@item %h
-Like @samp{%d}, but if the documentation string is more than one line,
-add an active field to control whether to show all of it or just the
-first line.
-
-@item %t
-Substitute the tag here. You specify the tag with the @code{:tag}
-keyword.
-
-@item %%
-Display a literal @samp{%}.
-@end table
-
-@item :action @var{action}
-@kindex action@r{, customization keyword}
-Perform @var{action} if the user clicks on a button.
-
-@item :button-face @var{face}
-@kindex button-face@r{, customization keyword}
-Use the face @var{face} (a face name or a list of face names) for button
-text displayed with @samp{%[@dots{}%]}.
-
-@item :button-prefix @var{prefix}
-@itemx :button-suffix @var{suffix}
-@kindex button-prefix@r{, customization keyword}
-@kindex button-suffix@r{, customization keyword}
-These specify the text to display before and after a button.
-Each can be:
-
-@table @asis
-@item @code{nil}
-No text is inserted.
-
-@item a string
-The string is inserted literally.
-
-@item a symbol
-The symbol's value is used.
-@end table
-
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for the value (or part of the value)
-that corresponds to this type.
-
-@item :doc @var{doc}
-@kindex doc@r{, customization keyword}
-Use @var{doc} as the documentation string for this value (or part of the
-value) that corresponds to this type. In order for this to work, you
-must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
-in that value.
-
-The usual reason to specify a documentation string for a type is to
-provide more information about the meanings of alternatives inside a
-@code{:choice} type or the parts of some other composite type.
-
-@item :help-echo @var{motion-doc}
-@kindex help-echo@r{, customization keyword}
-When you move to this item with @code{widget-forward} or
-@code{widget-backward}, it will display the string @var{motion-doc} in
-the echo area. In addition, @var{motion-doc} is used as the mouse
-@code{help-echo} string and may actually be a function or form evaluated
-to yield a help string. If it is a function, it is called with one
-argument, the widget.
-
-@item :match @var{function}
-@kindex match@r{, customization keyword}
-Specify how to decide whether a value matches the type. The
-corresponding value, @var{function}, should be a function that accepts
-two arguments, a widget and a value; it should return non-@code{nil} if
-the value is acceptable.
-
-@ignore
-@item :indent @var{columns}
-Indent this item by @var{columns} columns. The indentation is used for
-@samp{%n}, and automatically for group names, for checklists and radio
-buttons, and for editable lists. It affects the whole of the
-item except for the first line.
-
-@item :offset @var{columns}
-An integer indicating how many extra spaces to indent the subitems of
-this item. By default, subitems are indented the same as their parent.
-
-@item :extra-offset
-An integer indicating how many extra spaces to add to this item's
-indentation, compared to its parent.
-
-@item :notify
-A function called each time the item or a subitem is changed. The
-function is called with two or three arguments. The first argument is
-the item itself, the second argument is the item that was changed, and
-the third argument is the event leading to the change, if any.
-
-@item :menu-tag
-A tag used in the menu when the widget is used as an option in a
-@code{menu-choice} widget.
-
-@item :menu-tag-get
-A function used for finding the tag when the widget is used as an option
-in a @code{menu-choice} widget. By default, the tag used will be either the
-@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
-representation of the @code{:value} property if not.
-
-@item :validate
-A function which takes a widget as an argument, and return @code{nil}
-if the widget's current value is valid for the widget. Otherwise, it
-should return the widget containing the invalid data, and set that
-widget's @code{:error} property to a string explaining the error.
-
-You can use the function @code{widget-children-validate} for this job;
-it tests that all children of @var{widget} are valid.
-
-@item :tab-order
-Specify the order in which widgets are traversed with
-@code{widget-forward} or @code{widget-backward}. This is only partially
-implemented.
-
-@enumerate a
-@item
-Widgets with tabbing order @code{-1} are ignored.
-
-@item
-(Unimplemented) When on a widget with tabbing order @var{n}, go to the
-next widget in the buffer with tabbing order @var{n+1} or @code{nil},
-whichever comes first.
-
-@item
-When on a widget with no tabbing order specified, go to the next widget
-in the buffer with a positive tabbing order, or @code{nil}
-@end enumerate
-
-@item :parent
-The parent of a nested widget (e.g., a @code{menu-choice} item or an
-element of a @code{editable-list} widget).
-
-@item :sibling-args
-This keyword is only used for members of a @code{radio-button-choice} or
-@code{checklist}. The value should be a list of extra keyword
-arguments, which will be used when creating the @code{radio-button} or
-@code{checkbox} associated with this item.
-@end ignore
-@end table
-
-@node Defining New Types
-@subsection Defining New Types
-
-In the previous sections we have described how to construct elaborate
-type specifications for @code{defcustom}. In some cases you may want
-to give such a type specification a name. The obvious case is when
-you are using the same type for many user options: rather than repeat
-the specification for each option, you can give the type specification
-a name, and use that name each @code{defcustom}. The other case is
-when a user option's value is a recursive data structure. To make it
-possible for a datatype to refer to itself, it needs to have a name.
-
-Since custom types are implemented as widgets, the way to define a new
-customize type is to define a new widget. We are not going to describe
-the widget interface here in details, see @ref{Top, , Introduction,
-widget, The Emacs Widget Library}, for that. Instead we are going to
-demonstrate the minimal functionality needed for defining new customize
-types by a simple example.
-
-@example
-(define-widget 'binary-tree-of-string 'lazy
- "A binary tree made of cons-cells and strings."
- :offset 4
- :tag "Node"
- :type '(choice (string :tag "Leaf" :value "")
- (cons :tag "Interior"
- :value ("" . "")
- binary-tree-of-string
- binary-tree-of-string)))
-
-(defcustom foo-bar ""
- "Sample variable holding a binary tree of strings."
- :type 'binary-tree-of-string)
-@end example
-
-The function to define a new widget is called @code{define-widget}. The
-first argument is the symbol we want to make a new widget type. The
-second argument is a symbol representing an existing widget, the new
-widget is going to be defined in terms of difference from the existing
-widget. For the purpose of defining new customization types, the
-@code{lazy} widget is perfect, because it accepts a @code{:type} keyword
-argument with the same syntax as the keyword argument to
-@code{defcustom} with the same name. The third argument is a
-documentation string for the new widget. You will be able to see that
-string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string
-@key{RET}} command.
-
-After these mandatory arguments follow the keyword arguments. The most
-important is @code{:type}, which describes the data type we want to match
-with this widget. Here a @code{binary-tree-of-string} is described as
-being either a string, or a cons-cell whose car and cdr are themselves
-both @code{binary-tree-of-string}. Note the reference to the widget
-type we are currently in the process of defining. The @code{:tag}
-attribute is a string to name the widget in the user interface, and the
-@code{:offset} argument is there to ensure that child nodes are
-indented four spaces relative to the parent node, making the tree
-structure apparent in the customization buffer.
-
-The @code{defcustom} shows how the new widget can be used as an ordinary
-customization type.
-
-The reason for the name @code{lazy} is that the other composite
-widgets convert their inferior widgets to internal form when the
-widget is instantiated in a buffer. This conversion is recursive, so
-the inferior widgets will convert @emph{their} inferior widgets. If
-the data structure is itself recursive, this conversion is an infinite
-recursion. The @code{lazy} widget prevents the recursion: it convert
-its @code{:type} argument only when needed.
-
-@ignore
- arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/debugging
-@node Debugging, Read and Print, Advising Functions, Top
-@chapter Debugging Lisp Programs
-
- There are three ways to investigate a problem in an Emacs Lisp program,
-depending on what you are doing with the program when the problem appears.
-
-@itemize @bullet
-@item
-If the problem occurs when you run the program, you can use a Lisp
-debugger to investigate what is happening during execution. In addition
-to the ordinary debugger, Emacs comes with a source-level debugger,
-Edebug. This chapter describes both of them.
-
-@item
-If the problem is syntactic, so that Lisp cannot even read the program,
-you can use the Emacs facilities for editing Lisp to localize it.
-
-@item
-If the problem occurs when trying to compile the program with the byte
-compiler, you need to know how to examine the compiler's input buffer.
-@end itemize
-
-@menu
-* 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.
-@end menu
-
- Another useful debugging tool is the dribble file. When a dribble
-file is open, Emacs copies all keyboard input characters to that file.
-Afterward, you can examine the file to find out what input was used.
-@xref{Terminal Input}.
-
- For debugging problems in terminal descriptions, the
-@code{open-termscript} function can be useful. @xref{Terminal Output}.
-
-@node Debugger
-@section The Lisp Debugger
-@cindex debugger for Emacs Lisp
-@cindex Lisp debugger
-@cindex break
-
- The ordinary @dfn{Lisp debugger} provides the ability to suspend
-evaluation of a form. While evaluation is suspended (a state that is
-commonly known as a @dfn{break}), you may examine the run time stack,
-examine the values of local or global variables, or change those values.
-Since a break is a recursive edit, all the usual editing facilities of
-Emacs are available; you can even run programs that will enter the
-debugger recursively. @xref{Recursive Editing}.
-
-@menu
-* 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.
-@end menu
-
-@node Error Debugging
-@subsection Entering the Debugger on an Error
-@cindex error debugging
-@cindex debugging errors
-
- The most important time to enter the debugger is when a Lisp error
-happens. This allows you to investigate the immediate causes of the
-error.
-
- However, entry to the debugger is not a normal consequence of an
-error. Many commands frequently cause Lisp errors when invoked
-inappropriately (such as @kbd{C-f} at the end of the buffer), and during
-ordinary editing it would be very inconvenient to enter the debugger
-each time this happens. So if you want errors to enter the debugger, set
-the variable @code{debug-on-error} to non-@code{nil}. (The command
-@code{toggle-debug-on-error} provides an easy way to do this.)
-
-@defopt debug-on-error
-This variable determines whether the debugger is called when an error is
-signaled and not handled. If @code{debug-on-error} is @code{t}, all
-kinds of errors call the debugger (except those listed in
-@code{debug-ignored-errors}). If it is @code{nil}, none call the
-debugger.
-
-The value can also be a list of error conditions that should call the
-debugger. For example, if you set it to the list
-@code{(void-variable)}, then only errors about a variable that has no
-value invoke the debugger.
-
-When this variable is non-@code{nil}, Emacs does not create an error
-handler around process filter functions and sentinels. Therefore,
-errors in these functions also invoke the debugger. @xref{Processes}.
-@end defopt
-
-@defopt debug-ignored-errors
-This variable specifies certain kinds of errors that should not enter
-the debugger. Its value is a list of error condition symbols and/or
-regular expressions. If the error has any of those condition symbols,
-or if the error message matches any of the regular expressions, then
-that error does not enter the debugger, regardless of the value of
-@code{debug-on-error}.
-
-The normal value of this variable lists several errors that happen often
-during editing but rarely result from bugs in Lisp programs. However,
-``rarely'' is not ``never''; if your program fails with an error that
-matches this list, you will need to change this list in order to debug
-the error. The easiest way is usually to set
-@code{debug-ignored-errors} to @code{nil}.
-@end defopt
-
-@defopt eval-expression-debug-on-error
-If this variable has a non-@code{nil} value, then
-@code{debug-on-error} is set to @code{t} when evaluating with the
-command @code{eval-expression}. If
-@code{eval-expression-debug-on-error} is @code{nil}, then the value of
-@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating
-Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
-@end defopt
-
-@defopt debug-on-signal
-Normally, errors that are caught by @code{condition-case} never run the
-debugger, even if @code{debug-on-error} is non-@code{nil}. In other
-words, @code{condition-case} gets a chance to handle the error before
-the debugger gets a chance.
-
-If you set @code{debug-on-signal} to a non-@code{nil} value, then the
-debugger gets the first chance at every error; an error will invoke the
-debugger regardless of any @code{condition-case}, if it fits the
-criteria specified by the values of @code{debug-on-error} and
-@code{debug-ignored-errors}.
-
-@strong{Warning:} This variable is strong medicine! Various parts of
-Emacs handle errors in the normal course of affairs, and you may not
-even realize that errors happen there. If you set
-@code{debug-on-signal} to a non-@code{nil} value, those errors will
-enter the debugger.
-
-@strong{Warning:} @code{debug-on-signal} has no effect when
-@code{debug-on-error} is @code{nil}.
-@end defopt
-
- To debug an error that happens during loading of the init
-file, use the option @samp{--debug-init}. This binds
-@code{debug-on-error} to @code{t} while loading the init file, and
-bypasses the @code{condition-case} which normally catches errors in the
-init file.
-
- If your init file sets @code{debug-on-error}, the effect may
-not last past the end of loading the init file. (This is an undesirable
-byproduct of the code that implements the @samp{--debug-init} command
-line option.) The best way to make the init file set
-@code{debug-on-error} permanently is with @code{after-init-hook}, like
-this:
-
-@example
-(add-hook 'after-init-hook
- (lambda () (setq debug-on-error t)))
-@end example
-
-@node Infinite Loops
-@subsection Debugging Infinite Loops
-@cindex infinite loops
-@cindex loops, infinite
-@cindex quitting from infinite loop
-@cindex stopping an infinite loop
-
- When a program loops infinitely and fails to return, your first
-problem is to stop the loop. On most operating systems, you can do this
-with @kbd{C-g}, which causes a @dfn{quit}.
-
- Ordinary quitting gives no information about why the program was
-looping. To get more information, you can set the variable
-@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
-considered an error, and @code{debug-on-error} has no effect on the
-handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on
-errors.
-
- Once you have the debugger running in the middle of the infinite loop,
-you can proceed from the debugger using the stepping commands. If you
-step through the entire loop, you will probably get enough information
-to solve the problem.
-
-@defopt debug-on-quit
-This variable determines whether the debugger is called when @code{quit}
-is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
-then the debugger is called whenever you quit (that is, type @kbd{C-g}).
-If @code{debug-on-quit} is @code{nil}, then the debugger is not called
-when you quit. @xref{Quitting}.
-@end defopt
-
-@node Function Debugging
-@subsection Entering the Debugger on a Function Call
-@cindex function call debugging
-@cindex debugging specific functions
-
- To investigate a problem that happens in the middle of a program, one
-useful technique is to enter the debugger whenever a certain function is
-called. You can do this to the function in which the problem occurs,
-and then step through the function, or you can do this to a function
-called shortly before the problem, step quickly over the call to that
-function, and then step through its caller.
-
-@deffn Command debug-on-entry function-name
-This function requests @var{function-name} to invoke the debugger each
-time it is called. It works by inserting the form
-@code{(implement-debug-on-entry)} into the function definition as the
-first form.
-
-Any function or macro defined as Lisp code may be set to break on
-entry, regardless of whether it is interpreted code or compiled code.
-If the function is a command, it will enter the debugger when called
-from Lisp and when called interactively (after the reading of the
-arguments). You can also set debug-on-entry for primitive functions
-(i.e., those written in C) this way, but it only takes effect when the
-primitive is called from Lisp code. Debug-on-entry is not allowed for
-special forms.
-
-When @code{debug-on-entry} is called interactively, it prompts for
-@var{function-name} in the minibuffer. If the function is already set
-up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
-@code{debug-on-entry} always returns @var{function-name}.
-
-@strong{Warning:} if you redefine a function after using
-@code{debug-on-entry} on it, the code to enter the debugger is
-discarded by the redefinition. In effect, redefining the function
-cancels the break-on-entry feature for that function.
-
-Here's an example to illustrate use of this function:
-
-@example
-@group
-(defun fact (n)
- (if (zerop n) 1
- (* n (fact (1- n)))))
- @result{} fact
-@end group
-@group
-(debug-on-entry 'fact)
- @result{} fact
-@end group
-@group
-(fact 3)
-@end group
-
-@group
------- Buffer: *Backtrace* ------
-Debugger entered--entering a function:
-* fact(3)
- eval((fact 3))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
------- Buffer: *Backtrace* ------
-@end group
-
-@group
-(symbol-function 'fact)
- @result{} (lambda (n)
- (debug (quote debug))
- (if (zerop n) 1 (* n (fact (1- n)))))
-@end group
-@end example
-@end deffn
-
-@deffn Command cancel-debug-on-entry &optional function-name
-This function undoes the effect of @code{debug-on-entry} on
-@var{function-name}. When called interactively, it prompts for
-@var{function-name} in the minibuffer. If @var{function-name} is
-omitted or @code{nil}, it cancels break-on-entry for all functions.
-Calling @code{cancel-debug-on-entry} does nothing to a function which is
-not currently set up to break on entry.
-@end deffn
-
-@node Explicit Debug
-@subsection Explicit Entry to the Debugger
-
- You can cause the debugger to be called at a certain point in your
-program by writing the expression @code{(debug)} at that point. To do
-this, visit the source file, insert the text @samp{(debug)} at the
-proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key
-binding). @strong{Warning:} if you do this for temporary debugging
-purposes, be sure to undo this insertion before you save the file!
-
- The place where you insert @samp{(debug)} must be a place where an
-additional form can be evaluated and its value ignored. (If the value
-of @code{(debug)} isn't ignored, it will alter the execution of the
-program!) The most common suitable places are inside a @code{progn} or
-an implicit @code{progn} (@pxref{Sequencing}).
-
-@node Using Debugger
-@subsection Using the Debugger
-
- When the debugger is entered, it displays the previously selected
-buffer in one window and a buffer named @samp{*Backtrace*} in another
-window. The backtrace buffer contains one line for each level of Lisp
-function execution currently going on. At the beginning of this buffer
-is a message describing the reason that the debugger was invoked (such
-as the error message and associated data, if it was invoked due to an
-error).
-
- The backtrace buffer is read-only and uses a special major mode,
-Debugger mode, in which letters are defined as debugger commands. The
-usual Emacs editing commands are available; thus, you can switch windows
-to examine the buffer that was being edited at the time of the error,
-switch buffers, visit files, or do any other sort of editing. However,
-the debugger is a recursive editing level (@pxref{Recursive Editing})
-and it is wise to go back to the backtrace buffer and exit the debugger
-(with the @kbd{q} command) when you are finished with it. Exiting
-the debugger gets out of the recursive edit and kills the backtrace
-buffer.
-
-@cindex current stack frame
- The backtrace buffer shows you the functions that are executing and
-their argument values. It also allows you to specify a stack frame by
-moving point to the line describing that frame. (A stack frame is the
-place where the Lisp interpreter records information about a particular
-invocation of a function.) The frame whose line point is on is
-considered the @dfn{current frame}. Some of the debugger commands
-operate on the current frame. If a line starts with a star, that means
-that exiting that frame will call the debugger again. This is useful
-for examining the return value of a function.
-
- If a function name is underlined, that means the debugger knows
-where its source code is located. You can click @kbd{Mouse-2} on that
-name, or move to it and type @key{RET}, to visit the source code.
-
- The debugger itself must be run byte-compiled, since it makes
-assumptions about how many stack frames are used for the debugger
-itself. These assumptions are false if the debugger is running
-interpreted.
-
-@node Debugger Commands
-@subsection Debugger Commands
-@cindex debugger command list
-
- The debugger buffer (in Debugger mode) provides special commands in
-addition to the usual Emacs commands. The most important use of
-debugger commands is for stepping through code, so that you can see
-how control flows. The debugger can step through the control
-structures of an interpreted function, but cannot do so in a
-byte-compiled function. If you would like to step through a
-byte-compiled function, replace it with an interpreted definition of
-the same function. (To do this, visit the source for the function and
-type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
-to step through a primitive function.
-
- Here is a list of Debugger mode commands:
-
-@table @kbd
-@item c
-Exit the debugger and continue execution. When continuing is possible,
-it resumes execution of the program as if the debugger had never been
-entered (aside from any side-effects that you caused by changing
-variable values or data structures while inside the debugger).
-
-Continuing is possible after entry to the debugger due to function entry
-or exit, explicit invocation, or quitting. You cannot continue if the
-debugger was entered because of an error.
-
-@item d
-Continue execution, but enter the debugger the next time any Lisp
-function is called. This allows you to step through the
-subexpressions of an expression, seeing what values the subexpressions
-compute, and what else they do.
-
-The stack frame made for the function call which enters the debugger in
-this way will be flagged automatically so that the debugger will be
-called again when the frame is exited. You can use the @kbd{u} command
-to cancel this flag.
-
-@item b
-Flag the current frame so that the debugger will be entered when the
-frame is exited. Frames flagged in this way are marked with stars
-in the backtrace buffer.
-
-@item u
-Don't enter the debugger when the current frame is exited. This
-cancels a @kbd{b} command on that frame. The visible effect is to
-remove the star from the line in the backtrace buffer.
-
-@item j
-Flag the current frame like @kbd{b}. Then continue execution like
-@kbd{c}, but temporarily disable break-on-entry for all functions that
-are set up to do so by @code{debug-on-entry}.
-
-@item e
-Read a Lisp expression in the minibuffer, evaluate it, and print the
-value in the echo area. The debugger alters certain important
-variables, and the current buffer, as part of its operation; @kbd{e}
-temporarily restores their values from outside the debugger, so you can
-examine and change them. This makes the debugger more transparent. By
-contrast, @kbd{M-:} does nothing special in the debugger; it shows you
-the variable values within the debugger.
-
-@item R
-Like @kbd{e}, but also save the result of evaluation in the
-buffer @samp{*Debugger-record*}.
-
-@item q
-Terminate the program being debugged; return to top-level Emacs
-command execution.
-
-If the debugger was entered due to a @kbd{C-g} but you really want
-to quit, and not debug, use the @kbd{q} command.
-
-@item r
-Return a value from the debugger. The value is computed by reading an
-expression with the minibuffer and evaluating it.
-
-The @kbd{r} command is useful when the debugger was invoked due to exit
-from a Lisp call frame (as requested with @kbd{b} or by entering the
-frame with @kbd{d}); then the value specified in the @kbd{r} command is
-used as the value of that frame. It is also useful if you call
-@code{debug} and use its return value. Otherwise, @kbd{r} has the same
-effect as @kbd{c}, and the specified return value does not matter.
-
-You can't use @kbd{r} when the debugger was entered due to an error.
-
-@item l
-Display a list of functions that will invoke the debugger when called.
-This is a list of functions that are set to break on entry by means of
-@code{debug-on-entry}. @strong{Warning:} if you redefine such a
-function and thus cancel the effect of @code{debug-on-entry}, it may
-erroneously show up in this list.
-@end table
-
-@node Invoking the Debugger
-@subsection Invoking the Debugger
-
- Here we describe in full detail the function @code{debug} that is used
-to invoke the debugger.
-
-@defun debug &rest debugger-args
-This function enters the debugger. It switches buffers to a buffer
-named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
-recursive entry to the debugger, etc.), and fills it with information
-about the stack of Lisp function calls. It then enters a recursive
-edit, showing the backtrace buffer in Debugger mode.
-
-The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
-the recursive edit; then @code{debug} switches back to the previous
-buffer and returns to whatever called @code{debug}. This is the only
-way the function @code{debug} can return to its caller.
-
-The use of the @var{debugger-args} is that @code{debug} displays the
-rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
-that the user can see them. Except as described below, this is the
-@emph{only} way these arguments are used.
-
-However, certain values for first argument to @code{debug} have a
-special significance. (Normally, these values are used only by the
-internals of Emacs, and not by programmers calling @code{debug}.) Here
-is a table of these special values:
-
-@table @code
-@item lambda
-@cindex @code{lambda} in debug
-A first argument of @code{lambda} means @code{debug} was called
-because of entry to a function when @code{debug-on-next-call} was
-non-@code{nil}. The debugger displays @samp{Debugger
-entered--entering a function:} as a line of text at the top of the
-buffer.
-
-@item debug
-@code{debug} as first argument means @code{debug} was called because
-of entry to a function that was set to debug on entry. The debugger
-displays the string @samp{Debugger entered--entering a function:},
-just as in the @code{lambda} case. It also marks the stack frame for
-that function so that it will invoke the debugger when exited.
-
-@item t
-When the first argument is @code{t}, this indicates a call to
-@code{debug} due to evaluation of a function call form when
-@code{debug-on-next-call} is non-@code{nil}. The debugger displays
-@samp{Debugger entered--beginning evaluation of function call form:}
-as the top line in the buffer.
-
-@item exit
-When the first argument is @code{exit}, it indicates the exit of a
-stack frame previously marked to invoke the debugger on exit. The
-second argument given to @code{debug} in this case is the value being
-returned from the frame. The debugger displays @samp{Debugger
-entered--returning value:} in the top line of the buffer, followed by
-the value being returned.
-
-@item error
-@cindex @code{error} in debug
-When the first argument is @code{error}, the debugger indicates that
-it is being entered because an error or @code{quit} was signaled and
-not handled, by displaying @samp{Debugger entered--Lisp error:}
-followed by the error signaled and any arguments to @code{signal}.
-For example,
-
-@example
-@group
-(let ((debug-on-error t))
- (/ 1 0))
-@end group
-
-@group
------- Buffer: *Backtrace* ------
-Debugger entered--Lisp error: (arith-error)
- /(1 0)
-...
------- Buffer: *Backtrace* ------
-@end group
-@end example
-
-If an error was signaled, presumably the variable
-@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled,
-then presumably the variable @code{debug-on-quit} is non-@code{nil}.
-
-@item nil
-Use @code{nil} as the first of the @var{debugger-args} when you want
-to enter the debugger explicitly. The rest of the @var{debugger-args}
-are printed on the top line of the buffer. You can use this feature to
-display messages---for example, to remind yourself of the conditions
-under which @code{debug} is called.
-@end table
-@end defun
-
-@node Internals of Debugger
-@subsection Internals of the Debugger
-
- This section describes functions and variables used internally by the
-debugger.
-
-@defvar debugger
-The value of this variable is the function to call to invoke the
-debugger. Its value must be a function of any number of arguments, or,
-more typically, the name of a function. This function should invoke
-some kind of debugger. The default value of the variable is
-@code{debug}.
-
-The first argument that Lisp hands to the function indicates why it
-was called. The convention for arguments is detailed in the description
-of @code{debug} (@pxref{Invoking the Debugger}).
-@end defvar
-
-@deffn Command backtrace
-@cindex run time stack
-@cindex call stack
-This function prints a trace of Lisp function calls currently active.
-This is the function used by @code{debug} to fill up the
-@samp{*Backtrace*} buffer. It is written in C, since it must have access
-to the stack to determine which function calls are active. The return
-value is always @code{nil}.
-
-In the following example, a Lisp expression calls @code{backtrace}
-explicitly. This prints the backtrace to the stream
-@code{standard-output}, which, in this case, is the buffer
-@samp{backtrace-output}.
-
-Each line of the backtrace represents one function call. The line shows
-the values of the function's arguments if they are all known; if they
-are still being computed, the line says so. The arguments of special
-forms are elided.
-
-@smallexample
-@group
-(with-output-to-temp-buffer "backtrace-output"
- (let ((var 1))
- (save-excursion
- (setq var (eval '(progn
- (1+ var)
- (list 'testing (backtrace))))))))
-
- @result{} (testing nil)
-@end group
-
-@group
------------ Buffer: backtrace-output ------------
- backtrace()
- (list ...computing arguments...)
-@end group
- (progn ...)
- eval((progn (1+ var) (list (quote testing) (backtrace))))
- (setq ...)
- (save-excursion ...)
- (let ...)
- (with-output-to-temp-buffer ...)
- eval((with-output-to-temp-buffer ...))
- eval-last-sexp-1(nil)
-@group
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
------------ Buffer: backtrace-output ------------
-@end group
-@end smallexample
-@end deffn
-
-@ignore @c Not worth mentioning
-@defopt stack-trace-on-error
-@cindex stack trace
-This variable controls whether Lisp automatically displays a
-backtrace buffer after every error that is not handled. A quit signal
-counts as an error for this variable. If it is non-@code{nil} then a
-backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
-error. If it is @code{nil}, then a backtrace is not shown.
-
-When a backtrace is shown, that buffer is not selected. If either
-@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
-a backtrace is shown in one buffer, and the debugger is popped up in
-another buffer with its own backtrace.
-
-We consider this feature to be obsolete and superseded by the debugger
-itself.
-@end defopt
-@end ignore
-
-@defvar debug-on-next-call
-@cindex @code{eval}, and debugging
-@cindex @code{apply}, and debugging
-@cindex @code{funcall}, and debugging
-If this variable is non-@code{nil}, it says to call the debugger before
-the next @code{eval}, @code{apply} or @code{funcall}. Entering the
-debugger sets @code{debug-on-next-call} to @code{nil}.
-
-The @kbd{d} command in the debugger works by setting this variable.
-@end defvar
-
-@defun backtrace-debug level flag
-This function sets the debug-on-exit flag of the stack frame @var{level}
-levels down the stack, giving it the value @var{flag}. If @var{flag} is
-non-@code{nil}, this will cause the debugger to be entered when that
-frame later exits. Even a nonlocal exit through that frame will enter
-the debugger.
-
-This function is used only by the debugger.
-@end defun
-
-@defvar command-debug-status
-This variable records the debugging status of the current interactive
-command. Each time a command is called interactively, this variable is
-bound to @code{nil}. The debugger can set this variable to leave
-information for future debugger invocations during the same command
-invocation.
-
-The advantage of using this variable rather than an ordinary global
-variable is that the data will never carry over to a subsequent command
-invocation.
-@end defvar
-
-@defun backtrace-frame frame-number
-The function @code{backtrace-frame} is intended for use in Lisp
-debuggers. It returns information about what computation is happening
-in the stack frame @var{frame-number} levels down.
-
-If that frame has not evaluated the arguments yet, or is a special
-form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
-
-If that frame has evaluated its arguments and called its function
-already, the return value is @code{(t @var{function}
-@var{arg-values}@dots{})}.
-
-In the return value, @var{function} is whatever was supplied as the
-@sc{car} of the evaluated list, or a @code{lambda} expression in the
-case of a macro call. If the function has a @code{&rest} argument, that
-is represented as the tail of the list @var{arg-values}.
-
-If @var{frame-number} is out of range, @code{backtrace-frame} returns
-@code{nil}.
-@end defun
-
-@include edebug.texi
-
-@node Syntax Errors
-@section Debugging Invalid Lisp Syntax
-@cindex debugging invalid Lisp syntax
-
- The Lisp reader reports invalid syntax, but cannot say where the real
-problem is. For example, the error ``End of file during parsing'' in
-evaluating an expression indicates an excess of open parentheses (or
-square brackets). The reader detects this imbalance at the end of the
-file, but it cannot figure out where the close parenthesis should have
-been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close
-parenthesis or missing open parenthesis, but does not say where the
-missing parenthesis belongs. How, then, to find what to change?
-
- If the problem is not simply an imbalance of parentheses, a useful
-technique is to try @kbd{C-M-e} at the beginning of each defun, and see
-if it goes to the place where that defun appears to end. If it does
-not, there is a problem in that defun.
-
-@cindex unbalanced parentheses
-@cindex parenthesis mismatch, debugging
- However, unmatched parentheses are the most common syntax errors in
-Lisp, and we can give further advice for those cases. (In addition,
-just moving point through the code with Show Paren mode enabled might
-find the mismatch.)
-
-@menu
-* Excess Open:: How to find a spurious open paren or missing close.
-* Excess Close:: How to find a spurious close paren or missing open.
-@end menu
-
-@node Excess Open
-@subsection Excess Open Parentheses
-
- The first step is to find the defun that is unbalanced. If there is
-an excess open parenthesis, the way to do this is to go to the end of
-the file and type @kbd{C-u C-M-u}. This will move you to the
-beginning of the first defun that is unbalanced.
-
- The next step is to determine precisely what is wrong. There is no
-way to be sure of this except by studying the program, but often the
-existing indentation is a clue to where the parentheses should have
-been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
-and see what moves. @strong{But don't do this yet!} Keep reading,
-first.
-
- Before you do this, make sure the defun has enough close parentheses.
-Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
-of the file until the end. So move to the end of the defun and insert a
-close parenthesis there. Don't use @kbd{C-M-e} to move there, since
-that too will fail to work until the defun is balanced.
-
- Now you can go to the beginning of the defun and type @kbd{C-M-q}.
-Usually all the lines from a certain point to the end of the function
-will shift to the right. There is probably a missing close parenthesis,
-or a superfluous open parenthesis, near that point. (However, don't
-assume this is true; study the code to make sure.) Once you have found
-the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
-indentation is probably appropriate to the intended parentheses.
-
- After you think you have fixed the problem, use @kbd{C-M-q} again. If
-the old indentation actually fit the intended nesting of parentheses,
-and you have put back those parentheses, @kbd{C-M-q} should not change
-anything.
-
-@node Excess Close
-@subsection Excess Close Parentheses
-
- To deal with an excess close parenthesis, first go to the beginning
-of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
-unbalanced defun.
-
- Then find the actual matching close parenthesis by typing @kbd{C-M-f}
-at the beginning of that defun. This will leave you somewhere short of
-the place where the defun ought to end. It is possible that you will
-find a spurious close parenthesis in that vicinity.
-
- If you don't see a problem at that point, the next thing to do is to
-type @kbd{C-M-q} at the beginning of the defun. A range of lines will
-probably shift left; if so, the missing open parenthesis or spurious
-close parenthesis is probably near the first of those lines. (However,
-don't assume this is true; study the code to make sure.) Once you have
-found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
-old indentation is probably appropriate to the intended parentheses.
-
- After you think you have fixed the problem, use @kbd{C-M-q} again. If
-the old indentation actually fits the intended nesting of parentheses,
-and you have put back those parentheses, @kbd{C-M-q} should not change
-anything.
-
-@node Test Coverage
-@section Test Coverage
-@cindex coverage testing
-
-@findex testcover-start
-@findex testcover-mark-all
-@findex testcover-next-mark
- You can do coverage testing for a file of Lisp code by loading the
-@code{testcover} library and using the command @kbd{M-x
-testcover-start @key{RET} @var{file} @key{RET}} to instrument the
-code. Then test your code by calling it one or more times. Then use
-the command @kbd{M-x testcover-mark-all} to display colored highlights
-on the code to show where coverage is insufficient. The command
-@kbd{M-x testcover-next-mark} will move point forward to the next
-highlighted spot.
-
- Normally, a red highlight indicates the form was never completely
-evaluated; a brown highlight means it always evaluated to the same
-value (meaning there has been little testing of what is done with the
-result). However, the red highlight is skipped for forms that can't
-possibly complete their evaluation, such as @code{error}. The brown
-highlight is skipped for forms that are expected to always evaluate to
-the same value, such as @code{(setq x 14)}.
-
- For difficult cases, you can add do-nothing macros to your code to
-give advice to the test coverage tool.
-
-@defmac 1value form
-Evaluate @var{form} and return its value, but inform coverage testing
-that @var{form}'s value should always be the same.
-@end defmac
-
-@defmac noreturn form
-Evaluate @var{form}, informing coverage testing that @var{form} should
-never return. If it ever does return, you get a run-time error.
-@end defmac
-
- Edebug also has a coverage testing feature (@pxref{Coverage
-Testing}). These features partly duplicate each other, and it would
-be cleaner to combine them.
-
-@node Compilation Errors
-@section Debugging Problems in Compilation
-@cindex debugging byte compilation problems
-
- When an error happens during byte compilation, it is normally due to
-invalid syntax in the program you are compiling. The compiler prints a
-suitable error message in the @samp{*Compile-Log*} buffer, and then
-stops. The message may state a function name in which the error was
-found, or it may not. Either way, here is how to find out where in the
-file the error occurred.
-
- What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
-(Note that the buffer name starts with a space, so it does not show
-up in @kbd{M-x list-buffers}.) This buffer contains the program being
-compiled, and point shows how far the byte compiler was able to read.
-
- If the error was due to invalid Lisp syntax, point shows exactly where
-the invalid syntax was @emph{detected}. The cause of the error is not
-necessarily near by! Use the techniques in the previous section to find
-the error.
-
- If the error was detected while compiling a form that had been read
-successfully, then point is located at the end of the form. In this
-case, this technique can't localize the error precisely, but can still
-show you which function to check.
-
-@ignore
- arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7
-@end ignore
+++ /dev/null
-@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>
-
----------- Buffer: foo ----------
-20
-
-#<buffer foo>
-
----------- 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 from 1 to 10 in display.texi>
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 10
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @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 from 5 to 20 in display.texi>
-(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{} #<overlay in no buffer>
-;; @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{} #<overlay from 1 to 20 in display.texi>
-;; @r{Verify the results.}
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 20
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @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.
-
- 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. 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 takes priority
-over the other. For the @code{face} property, the higher priority
-value does not completely replace the other; 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 facesto 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.
-
- Some kinds of @code{display} properties specify something to display
-instead of the text that has the property. In this case, ``the text''
-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.
-
- 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
+++ /dev/null
-@c -*-texinfo-*-
-@node GNU Free Documentation License, GPL, Antinews, Top
-
-@appendix GNU Free Documentation License
-@center Version 1.2, November 2002
-
-@display
-Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-@sp 1
-@enumerate 0
-@item
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document ``free'' in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of ``copyleft,'' which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
-@sp 1
-@item
-APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The ``Document,'' below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as ``you.'' You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not ``Transparent'' is called ``Opaque.''
-
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification. Examples of
-transparent image formats include PNG, XCF and JPG. Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-A section ``Entitled XYZ'' means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as ``Acknowledgements,''
-``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title''
-of such a section when you modify the Document means that it remains a
-section ``Entitled XYZ'' according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-@sp 1
-@item
-VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-@sp 1
-@item
-COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-@sp 1
-@item
-MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
-A. Use in the Title Page (and on the covers, if any) a title distinct
- from that of the Document, and from those of previous versions
- (which should, if there were any, be listed in the History section
- of the Document). You may use the same title as a previous version
- if the original publisher of that version gives permission.@*
-B. List on the Title Page, as authors, one or more persons or entities
- responsible for authorship of the modifications in the Modified
- Version, together with at least five of the principal authors of the
- Document (all of its principal authors, if it has fewer than five),
- unless they release you from this requirement.@*
-C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.@*
-D. Preserve all the copyright notices of the Document.@*
-E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.@*
-F. Include, immediately after the copyright notices, a license notice
- giving the public permission to use the Modified Version under the
- terms of this License, in the form shown in the Addendum below.@*
-G. Preserve in that license notice the full lists of Invariant Sections
- and required Cover Texts given in the Document's license notice.@*
-H. Include an unaltered copy of this License.@*
-I. Preserve the section Entitled ``History,'' Preserve its Title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section Entitled ``History'' in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.@*
-J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions
- it was based on. These may be placed in the ``History'' section.
- You may omit a network location for a work that was published at
- least four years before the Document itself, or if the original
- publisher of the version it refers to gives permission.@*
-K. For any section Entitled ``Acknowledgements'' or ``Dedications,''
- Preserve the Title of the section, and preserve in the section all
- the substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.@*
-L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.@*
-M. Delete any section Entitled ``Endorsements.'' Such a section
- may not be included in the Modified Version.@*
-N. Do not retitle any existing section to be Entitled ``Endorsements''
- or to conflict in title with any Invariant Section.@*
-O. Preserve any Warranty Disclaimers.@*
-@sp 1
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled ``Endorsements,'' provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-@sp 1
-@item
-COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled ``History''
-in the various original documents, forming one section Entitled
-``History''; likewise combine any sections Entitled ``Acknowledgements,''
-and any sections Entitled ``Dedications.'' You must delete all sections
-Entitled ``Endorsements.''
-@sp 1
-@item
-COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-@sp 1
-@item
-AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an ``aggregate'' if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-@sp 1
-@item
-TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled ``Acknowledgements,''
-``Dedications,'' or ``History,'' the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-@sp 1
-@item
-TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-@sp 1
-@item
-FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-http://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-@end enumerate
-
-@unnumberedsec ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@smallexample
-@group
-Copyright (C) @var{year} @var{your name}.
-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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
-A copy of the license is included in the section entitled ``GNU
-Free Documentation License.''
-@end group
-@end smallexample
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the ``with...Texts.'' line with this:
-
-@smallexample
-@group
-with the Invariant Sections being @var{list their titles}, with the
-Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
-@var{list}.
-@end group
-@end smallexample
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@ignore
- arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c
-@end ignore
+++ /dev/null
-@comment -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-
-@c This file can also be used by an independent Edebug User
-@c Manual in which case the Edebug node below should be used
-@c with the following links to the Bugs section and to the top level:
-
-@c , Bugs and Todo List, Top, Top
-
-@node Edebug, Syntax Errors, Debugger, Debugging
-@section Edebug
-@cindex Edebug debugging facility
-
- Edebug is a source-level debugger for Emacs Lisp programs with which
-you can:
-
-@itemize @bullet
-@item
-Step through evaluation, stopping before and after each expression.
-
-@item
-Set conditional or unconditional breakpoints.
-
-@item
-Stop when a specified condition is true (the global break event).
-
-@item
-Trace slow or fast, stopping briefly at each stop point, or
-at each breakpoint.
-
-@item
-Display expression results and evaluate expressions as if outside of
-Edebug.
-
-@item
-Automatically re-evaluate a list of expressions and
-display their results each time Edebug updates the display.
-
-@item
-Output trace info on function enter and exit.
-
-@item
-Stop when an error occurs.
-
-@item
-Display a backtrace, omitting Edebug's own frames.
-
-@item
-Specify argument evaluation for macros and defining forms.
-
-@item
-Obtain rudimentary coverage testing and frequency counts.
-@end itemize
-
-The first three sections below should tell you enough about Edebug to
-enable you to use it.
-
-@menu
-* Using Edebug:: Introduction to use of Edebug.
-* Instrumenting:: You must instrument your code
- in order to debug it with Edebug.
-* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
-* Jumping:: Commands to jump to a specified place.
-* Misc: Edebug Misc. Miscellaneous commands.
-* Breaks:: Setting breakpoints to make the program stop.
-* Trapping Errors:: Trapping errors with Edebug.
-* Views: Edebug Views. Views inside and outside of Edebug.
-* Eval: 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.
-* Options: Edebug Options. Option variables for customizing Edebug.
-@end menu
-
-@node Using Edebug
-@subsection Using Edebug
-
- To debug a Lisp program with Edebug, you must first @dfn{instrument}
-the Lisp code that you want to debug. A simple way to do this is to
-first move point into the definition of a function or macro and then do
-@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See
-@ref{Instrumenting}, for alternative ways to instrument code.
-
- Once a function is instrumented, any call to the function activates
-Edebug. Depending on which Edebug execution mode you have selected,
-activating Edebug may stop execution and let you step through the
-function, or it may update the display and continue execution while
-checking for debugging commands. The default execution mode is step,
-which stops execution. @xref{Edebug Execution Modes}.
-
- Within Edebug, you normally view an Emacs buffer showing the source of
-the Lisp code you are debugging. This is referred to as the @dfn{source
-code buffer}, and it is temporarily read-only.
-
- An arrow in the left fringe indicates the line where the function is
-executing. Point initially shows where within the line the function is
-executing, but this ceases to be true if you move point yourself.
-
- If you instrument the definition of @code{fac} (shown below) and then
-execute @code{(fac 3)}, here is what you would normally see. Point is
-at the open-parenthesis before @code{if}.
-
-@example
-(defun fac (n)
-=>@point{}(if (< 0 n)
- (* n (fac (1- n)))
- 1))
-@end example
-
-@cindex stop points
-The places within a function where Edebug can stop execution are called
-@dfn{stop points}. These occur both before and after each subexpression
-that is a list, and also after each variable reference.
-Here we use periods to show the stop points in the function
-@code{fac}:
-
-@example
-(defun fac (n)
- .(if .(< 0 n.).
- .(* n. .(fac .(1- n.).).).
- 1).)
-@end example
-
-The special commands of Edebug are available in the source code buffer
-in addition to the commands of Emacs Lisp mode. For example, you can
-type the Edebug command @key{SPC} to execute until the next stop point.
-If you type @key{SPC} once after entry to @code{fac}, here is the
-display you will see:
-
-@example
-(defun fac (n)
-=>(if @point{}(< 0 n)
- (* n (fac (1- n)))
- 1))
-@end example
-
-When Edebug stops execution after an expression, it displays the
-expression's value in the echo area.
-
-Other frequently used commands are @kbd{b} to set a breakpoint at a stop
-point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
-exit Edebug and return to the top-level command loop. Type @kbd{?} to
-display a list of all Edebug commands.
-
-@node Instrumenting
-@subsection Instrumenting for Edebug
-
- In order to use Edebug to debug Lisp code, you must first
-@dfn{instrument} the code. Instrumenting code inserts additional code
-into it, to invoke Edebug at the proper places.
-
-@kindex C-M-x
-@findex eval-defun (Edebug)
- When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
-prefix argument on a function definition, it instruments the
-definition before evaluating it. (This does not modify the source
-code itself.) If the variable @code{edebug-all-defs} is
-non-@code{nil}, that inverts the meaning of the prefix argument: in
-this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
-a prefix argument. The default value of @code{edebug-all-defs} is
-@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value
-of the variable @code{edebug-all-defs}.
-
-@findex eval-region @r{(Edebug)}
-@findex eval-buffer @r{(Edebug)}
-@findex eval-current-buffer @r{(Edebug)}
- If @code{edebug-all-defs} is non-@code{nil}, then the commands
-@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
-also instrument any definitions they evaluate. Similarly,
-@code{edebug-all-forms} controls whether @code{eval-region} should
-instrument @emph{any} form, even non-defining forms. This doesn't apply
-to loading or evaluations in the minibuffer. The command @kbd{M-x
-edebug-all-forms} toggles this option.
-
-@findex edebug-eval-top-level-form
- Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
-instrument any top-level form regardless of the values of
-@code{edebug-all-defs} and @code{edebug-all-forms}.
-
- While Edebug is active, the command @kbd{I}
-(@code{edebug-instrument-callee}) instruments the definition of the
-function or macro called by the list form after point, if is not already
-instrumented. This is possible only if Edebug knows where to find the
-source for that function; for this reading, after loading Edebug,
-@code{eval-region} records the position of every definition it
-evaluates, even if not instrumenting it. See also the @kbd{i} command
-(@pxref{Jumping}), which steps into the call after instrumenting the
-function.
-
- Edebug knows how to instrument all the standard special forms,
-@code{interactive} forms with an expression argument, anonymous lambda
-expressions, and other defining forms. However, Edebug cannot determine
-on its own what a user-defined macro will do with the arguments of a
-macro call, so you must provide that information using Edebug
-specifications; see @ref{Edebug and Macros}, for details.
-
- When Edebug is about to instrument code for the first time in a
-session, it runs the hook @code{edebug-setup-hook}, then sets it to
-@code{nil}. You can use this to load Edebug specifications
-associated with a package you are using, but only when you use Edebug.
-
-@findex eval-expression @r{(Edebug)}
- To remove instrumentation from a definition, simply re-evaluate its
-definition in a way that does not instrument. There are two ways of
-evaluating forms that never instrument them: from a file with
-@code{load}, and from the minibuffer with @code{eval-expression}
-(@kbd{M-:}).
-
- If Edebug detects a syntax error while instrumenting, it leaves point
-at the erroneous code and signals an @code{invalid-read-syntax} error.
-
- @xref{Edebug Eval}, for other evaluation functions available
-inside of Edebug.
-
-@node Edebug Execution Modes
-@subsection Edebug Execution Modes
-
-@cindex Edebug execution modes
-Edebug supports several execution modes for running the program you are
-debugging. We call these alternatives @dfn{Edebug execution modes}; do
-not confuse them with major or minor modes. The current Edebug execution mode
-determines how far Edebug continues execution before stopping---whether
-it stops at each stop point, or continues to the next breakpoint, for
-example---and how much Edebug displays the progress of the evaluation
-before it stops.
-
-Normally, you specify the Edebug execution mode by typing a command to
-continue the program in a certain mode. Here is a table of these
-commands; all except for @kbd{S} resume execution of the program, at
-least for a certain distance.
-
-@table @kbd
-@item S
-Stop: don't execute any more of the program, but wait for more
-Edebug commands (@code{edebug-stop}).
-
-@item @key{SPC}
-Step: stop at the next stop point encountered (@code{edebug-step-mode}).
-
-@item n
-Next: stop at the next stop point encountered after an expression
-(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
-@ref{Jumping}.
-
-@item t
-Trace: pause (normally one second) at each Edebug stop point
-(@code{edebug-trace-mode}).
-
-@item T
-Rapid trace: update the display at each stop point, but don't actually
-pause (@code{edebug-Trace-fast-mode}).
-
-@item g
-Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
-
-@item c
-Continue: pause one second at each breakpoint, and then continue
-(@code{edebug-continue-mode}).
-
-@item C
-Rapid continue: move point to each breakpoint, but don't pause
-(@code{edebug-Continue-fast-mode}).
-
-@item G
-Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
-can still stop the program by typing @kbd{S}, or any editing command.
-@end table
-
-In general, the execution modes earlier in the above list run the
-program more slowly or stop sooner than the modes later in the list.
-
-While executing or tracing, you can interrupt the execution by typing
-any Edebug command. Edebug stops the program at the next stop point and
-then executes the command you typed. For example, typing @kbd{t} during
-execution switches to trace mode at the next stop point. You can use
-@kbd{S} to stop execution without doing anything else.
-
-If your function happens to read input, a character you type intending
-to interrupt execution may be read by the function instead. You can
-avoid such unintended results by paying attention to when your program
-wants input.
-
-@cindex keyboard macros (Edebug)
-Keyboard macros containing the commands in this section do not
-completely work: exiting from Edebug, to resume the program, loses track
-of the keyboard macro. This is not easy to fix. Also, defining or
-executing a keyboard macro outside of Edebug does not affect commands
-inside Edebug. This is usually an advantage. See also the
-@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
-
-When you enter a new Edebug level, the initial execution mode comes
-from the value of the variable @code{edebug-initial-mode}.
-(@xref{Edebug Options}.) By default, this specifies step mode. Note
-that you may reenter the same Edebug level several times if, for
-example, an instrumented function is called several times from one
-command.
-
-@defopt edebug-sit-for-seconds
-This option specifies how many seconds to wait between execution steps
-in trace mode. The default is 1 second.
-@end defopt
-
-@node Jumping
-@subsection Jumping
-
- The commands described in this section execute until they reach a
-specified location. All except @kbd{i} make a temporary breakpoint to
-establish the place to stop, then switch to go mode. Any other
-breakpoint reached before the intended stop point will also stop
-execution. @xref{Breakpoints}, for the details on breakpoints.
-
- These commands may fail to work as expected in case of nonlocal exit,
-as that can bypass the temporary breakpoint where you expected the
-program to stop.
-
-@table @kbd
-@item h
-Proceed to the stop point near where point is (@code{edebug-goto-here}).
-
-@item f
-Run the program for one expression
-(@code{edebug-forward-sexp}).
-
-@item o
-Run the program until the end of the containing sexp.
-
-@item i
-Step into the function or macro called by the form after point.
-@end table
-
-The @kbd{h} command proceeds to the stop point at or after the current
-location of point, using a temporary breakpoint.
-
-The @kbd{f} command runs the program forward over one expression. More
-precisely, it sets a temporary breakpoint at the position that
-@kbd{C-M-f} would reach, then executes in go mode so that the program
-will stop at breakpoints.
-
-With a prefix argument @var{n}, the temporary breakpoint is placed
-@var{n} sexps beyond point. If the containing list ends before @var{n}
-more elements, then the place to stop is after the containing
-expression.
-
-You must check that the position @kbd{C-M-f} finds is a place that the
-program will really get to. In @code{cond}, for example, this may not
-be true.
-
-For flexibility, the @kbd{f} command does @code{forward-sexp} starting
-at point, rather than at the stop point. If you want to execute one
-expression @emph{from the current stop point}, first type @kbd{w}, to
-move point there, and then type @kbd{f}.
-
-The @kbd{o} command continues ``out of'' an expression. It places a
-temporary breakpoint at the end of the sexp containing point. If the
-containing sexp is a function definition itself, @kbd{o} continues until
-just before the last sexp in the definition. If that is where you are
-now, it returns from the function and then stops. In other words, this
-command does not exit the currently executing function unless you are
-positioned after the last sexp.
-
-The @kbd{i} command steps into the function or macro called by the list
-form after point, and stops at its first stop point. Note that the form
-need not be the one about to be evaluated. But if the form is a
-function call about to be evaluated, remember to use this command before
-any of the arguments are evaluated, since otherwise it will be too late.
-
-The @kbd{i} command instruments the function or macro it's supposed to
-step into, if it isn't instrumented already. This is convenient, but keep
-in mind that the function or macro remains instrumented unless you explicitly
-arrange to deinstrument it.
-
-@node Edebug Misc
-@subsection Miscellaneous Edebug Commands
-
- Some miscellaneous Edebug commands are described here.
-
-@table @kbd
-@item ?
-Display the help message for Edebug (@code{edebug-help}).
-
-@item C-]
-Abort one level back to the previous command level
-(@code{abort-recursive-edit}).
-
-@item q
-Return to the top level editor command loop (@code{top-level}). This
-exits all recursive editing levels, including all levels of Edebug
-activity. However, instrumented code protected with
-@code{unwind-protect} or @code{condition-case} forms may resume
-debugging.
-
-@item Q
-Like @kbd{q}, but don't stop even for protected code
-(@code{top-level-nonstop}).
-
-@item r
-Redisplay the most recently known expression result in the echo area
-(@code{edebug-previous-result}).
-
-@item d
-Display a backtrace, excluding Edebug's own functions for clarity
-(@code{edebug-backtrace}).
-
-You cannot use debugger commands in the backtrace buffer in Edebug as
-you would in the standard debugger.
-
-The backtrace buffer is killed automatically when you continue
-execution.
-@end table
-
-You can invoke commands from Edebug that activate Edebug again
-recursively. Whenever Edebug is active, you can quit to the top level
-with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
-display a backtrace of all the pending evaluations with @kbd{d}.
-
-@node Breaks
-@subsection Breaks
-
-Edebug's step mode stops execution when the next stop point is reached.
-There are three other ways to stop Edebug execution once it has started:
-breakpoints, the global break condition, and source breakpoints.
-
-@menu
-* Breakpoints:: Breakpoints at stop points.
-* Global Break Condition:: Breaking on an event.
-* Source Breakpoints:: Embedding breakpoints in source code.
-@end menu
-
-@node Breakpoints
-@subsubsection Edebug Breakpoints
-
-@cindex breakpoints (Edebug)
-While using Edebug, you can specify @dfn{breakpoints} in the program you
-are testing: these are places where execution should stop. You can set a
-breakpoint at any stop point, as defined in @ref{Using Edebug}. For
-setting and unsetting breakpoints, the stop point that is affected is
-the first one at or after point in the source code buffer. Here are the
-Edebug commands for breakpoints:
-
-@table @kbd
-@item b
-Set a breakpoint at the stop point at or after point
-(@code{edebug-set-breakpoint}). If you use a prefix argument, the
-breakpoint is temporary---it turns off the first time it stops the
-program.
-
-@item u
-Unset the breakpoint (if any) at the stop point at or after
-point (@code{edebug-unset-breakpoint}).
-
-@item x @var{condition} @key{RET}
-Set a conditional breakpoint which stops the program only if
-evaluating @var{condition} produces a non-@code{nil} value
-(@code{edebug-set-conditional-breakpoint}). With a prefix argument,
-the breakpoint is temporary.
-
-@item B
-Move point to the next breakpoint in the current definition
-(@code{edebug-next-breakpoint}).
-@end table
-
-While in Edebug, you can set a breakpoint with @kbd{b} and unset one
-with @kbd{u}. First move point to the Edebug stop point of your choice,
-then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
-Unsetting a breakpoint where none has been set has no effect.
-
-Re-evaluating or reinstrumenting a definition removes all of its
-previous breakpoints.
-
-A @dfn{conditional breakpoint} tests a condition each time the program
-gets there. Any errors that occur as a result of evaluating the
-condition are ignored, as if the result were @code{nil}. To set a
-conditional breakpoint, use @kbd{x}, and specify the condition
-expression in the minibuffer. Setting a conditional breakpoint at a
-stop point that has a previously established conditional breakpoint puts
-the previous condition expression in the minibuffer so you can edit it.
-
-You can make a conditional or unconditional breakpoint
-@dfn{temporary} by using a prefix argument with the command to set the
-breakpoint. When a temporary breakpoint stops the program, it is
-automatically unset.
-
-Edebug always stops or pauses at a breakpoint, except when the Edebug
-mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
-
-To find out where your breakpoints are, use the @kbd{B} command, which
-moves point to the next breakpoint following point, within the same
-function, or to the first breakpoint if there are no following
-breakpoints. This command does not continue execution---it just moves
-point in the buffer.
-
-@node Global Break Condition
-@subsubsection Global Break Condition
-
-@cindex stopping on events
-@cindex global break condition
- A @dfn{global break condition} stops execution when a specified
-condition is satisfied, no matter where that may occur. Edebug
-evaluates the global break condition at every stop point; if it
-evaluates to a non-@code{nil} value, then execution stops or pauses
-depending on the execution mode, as if a breakpoint had been hit. If
-evaluating the condition gets an error, execution does not stop.
-
-@findex edebug-set-global-break-condition
- The condition expression is stored in
-@code{edebug-global-break-condition}. You can specify a new expression
-using the @kbd{X} command from the source code buffer while Edebug is
-active, or using @kbd{C-x X X} from any buffer at any time, as long as
-Edebug is loaded (@code{edebug-set-global-break-condition}).
-
- The global break condition is the simplest way to find where in your
-code some event occurs, but it makes code run much more slowly. So you
-should reset the condition to @code{nil} when not using it.
-
-@node Source Breakpoints
-@subsubsection Source Breakpoints
-
-@findex edebug
-@cindex source breakpoints
- All breakpoints in a definition are forgotten each time you
-reinstrument it. If you wish to make a breakpoint that won't be
-forgotten, you can write a @dfn{source breakpoint}, which is simply a
-call to the function @code{edebug} in your source code. You can, of
-course, make such a call conditional. For example, in the @code{fac}
-function, you can insert the first line as shown below, to stop when the
-argument reaches zero:
-
-@example
-(defun fac (n)
- (if (= n 0) (edebug))
- (if (< 0 n)
- (* n (fac (1- n)))
- 1))
-@end example
-
- When the @code{fac} definition is instrumented and the function is
-called, the call to @code{edebug} acts as a breakpoint. Depending on
-the execution mode, Edebug stops or pauses there.
-
- If no instrumented code is being executed when @code{edebug} is called,
-that function calls @code{debug}.
-@c This may not be a good idea anymore.
-
-@node Trapping Errors
-@subsection Trapping Errors
-
- Emacs normally displays an error message when an error is signaled and
-not handled with @code{condition-case}. While Edebug is active and
-executing instrumented code, it normally responds to all unhandled
-errors. You can customize this with the options @code{edebug-on-error}
-and @code{edebug-on-quit}; see @ref{Edebug Options}.
-
- When Edebug responds to an error, it shows the last stop point
-encountered before the error. This may be the location of a call to a
-function which was not instrumented, and within which the error actually
-occurred. For an unbound variable error, the last known stop point
-might be quite distant from the offending variable reference. In that
-case, you might want to display a full backtrace (@pxref{Edebug Misc}).
-
-@c Edebug should be changed for the following: -- dan
- If you change @code{debug-on-error} or @code{debug-on-quit} while
-Edebug is active, these changes will be forgotten when Edebug becomes
-inactive. Furthermore, during Edebug's recursive edit, these variables
-are bound to the values they had outside of Edebug.
-
-@node Edebug Views
-@subsection Edebug Views
-
- These Edebug commands let you view aspects of the buffer and window
-status as they were before entry to Edebug. The outside window
-configuration is the collection of windows and contents that were in
-effect outside of Edebug.
-
-@table @kbd
-@item v
-Switch to viewing the outside window configuration
-(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
-
-@item p
-Temporarily display the outside current buffer with point at its
-outside position (@code{edebug-bounce-point}), pausing for one second
-before returning to Edebug. With a prefix argument @var{n}, pause for
-@var{n} seconds instead.
-
-@item w
-Move point back to the current stop point in the source code buffer
-(@code{edebug-where}).
-
-If you use this command in a different window displaying the same
-buffer, that window will be used instead to display the current
-definition in the future.
-
-@item W
-@c Its function is not simply to forget the saved configuration -- dan
-Toggle whether Edebug saves and restores the outside window
-configuration (@code{edebug-toggle-save-windows}).
-
-With a prefix argument, @code{W} only toggles saving and restoring of
-the selected window. To specify a window that is not displaying the
-source code buffer, you must use @kbd{C-x X W} from the global keymap.
-@end table
-
- You can view the outside window configuration with @kbd{v} or just
-bounce to the point in the current buffer with @kbd{p}, even if
-it is not normally displayed.
-
- After moving point, you may wish to jump back to the stop point.
-You can do that with @kbd{w} from a source code buffer. You can jump
-back to the stop point in the source code buffer from any buffer using
-@kbd{C-x X w}.
-
- Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
-saved outside window configuration---so that even if you turn saving
-back @emph{on}, the current window configuration remains unchanged when
-you next exit Edebug (by continuing the program). However, the
-automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
-conflict with the buffers you wish to see unless you have enough windows
-open.
-
-@node Edebug Eval
-@subsection Evaluation
-
- While within Edebug, you can evaluate expressions ``as if'' Edebug
-were not running. Edebug tries to be invisible to the expression's
-evaluation and printing. Evaluation of expressions that cause side
-effects will work as expected, except for changes to data that Edebug
-explicitly saves and restores. @xref{The Outside Context}, for details
-on this process.
-
-@table @kbd
-@item e @var{exp} @key{RET}
-Evaluate expression @var{exp} in the context outside of Edebug
-(@code{edebug-eval-expression}). That is, Edebug tries to minimize its
-interference with the evaluation.
-
-@item M-: @var{exp} @key{RET}
-Evaluate expression @var{exp} in the context of Edebug itself.
-
-@item C-x C-e
-Evaluate the expression before point, in the context outside of Edebug
-(@code{edebug-eval-last-sexp}).
-@end table
-
-@cindex lexical binding (Edebug)
- Edebug supports evaluation of expressions containing references to
-lexically bound symbols created by the following constructs in
-@file{cl.el} (version 2.03 or later): @code{lexical-let},
-@code{macrolet}, and @code{symbol-macrolet}.
-
-@node Eval List
-@subsection Evaluation List Buffer
-
- You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
-evaluate expressions interactively. You can also set up the
-@dfn{evaluation list} of expressions to be evaluated automatically each
-time Edebug updates the display.
-
-@table @kbd
-@item E
-Switch to the evaluation list buffer @samp{*edebug*}
-(@code{edebug-visit-eval-list}).
-@end table
-
- In the @samp{*edebug*} buffer you can use the commands of Lisp
-Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
-Manual}) as well as these special commands:
-
-@table @kbd
-@item C-j
-Evaluate the expression before point, in the outside context, and insert
-the value in the buffer (@code{edebug-eval-print-last-sexp}).
-
-@item C-x C-e
-Evaluate the expression before point, in the context outside of Edebug
-(@code{edebug-eval-last-sexp}).
-
-@item C-c C-u
-Build a new evaluation list from the contents of the buffer
-(@code{edebug-update-eval-list}).
-
-@item C-c C-d
-Delete the evaluation list group that point is in
-(@code{edebug-delete-eval-item}).
-
-@item C-c C-w
-Switch back to the source code buffer at the current stop point
-(@code{edebug-where}).
-@end table
-
- You can evaluate expressions in the evaluation list window with
-@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
-but they are evaluated in the context outside of Edebug.
-
- The expressions you enter interactively (and their results) are lost
-when you continue execution; but you can set up an @dfn{evaluation list}
-consisting of expressions to be evaluated each time execution stops.
-
-@cindex evaluation list group
- To do this, write one or more @dfn{evaluation list groups} in the
-evaluation list buffer. An evaluation list group consists of one or
-more Lisp expressions. Groups are separated by comment lines.
-
- The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
-evaluation list, scanning the buffer and using the first expression of
-each group. (The idea is that the second expression of the group is the
-value previously computed and displayed.)
-
- Each entry to Edebug redisplays the evaluation list by inserting each
-expression in the buffer, followed by its current value. It also
-inserts comment lines so that each expression becomes its own group.
-Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
-the evaluation list is effectively unchanged.
-
- If an error occurs during an evaluation from the evaluation list, the
-error message is displayed in a string as if it were the result.
-Therefore, expressions that use variables not currently valid do not
-interrupt your debugging.
-
- Here is an example of what the evaluation list window looks like after
-several expressions have been added to it:
-
-@smallexample
-(current-buffer)
-#<buffer *scratch*>
-;---------------------------------------------------------------
-(selected-window)
-#<window 16 on *scratch*>
-;---------------------------------------------------------------
-(point)
-196
-;---------------------------------------------------------------
-bad-var
-"Symbol's value as variable is void: bad-var"
-;---------------------------------------------------------------
-(recursion-depth)
-0
-;---------------------------------------------------------------
-this-command
-eval-last-sexp
-;---------------------------------------------------------------
-@end smallexample
-
-To delete a group, move point into it and type @kbd{C-c C-d}, or simply
-delete the text for the group and update the evaluation list with
-@kbd{C-c C-u}. To add a new expression to the evaluation list, insert
-the expression at a suitable place, insert a new comment line, then type
-@kbd{C-c C-u}. You need not insert dashes in the comment line---its
-contents don't matter.
-
-After selecting @samp{*edebug*}, you can return to the source code
-buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
-you continue execution, and recreated next time it is needed.
-
-@node Printing in Edebug
-@subsection Printing in Edebug
-
-@cindex printing (Edebug)
-@cindex printing circular structures
-@pindex cust-print
- If an expression in your program produces a value containing circular
-list structure, you may get an error when Edebug attempts to print it.
-
- One way to cope with circular structure is to set @code{print-length}
-or @code{print-level} to truncate the printing. Edebug does this for
-you; it binds @code{print-length} and @code{print-level} to 50 if they
-were @code{nil}. (Actually, the variables @code{edebug-print-length}
-and @code{edebug-print-level} specify the values to use within Edebug.)
-@xref{Output Variables}.
-
-@defopt edebug-print-length
-If non-@code{nil}, Edebug binds @code{print-length} to this value while
-printing results. The default value is @code{50}.
-@end defopt
-
-@defopt edebug-print-level
-If non-@code{nil}, Edebug binds @code{print-level} to this value while
-printing results. The default value is @code{50}.
-@end defopt
-
- You can also print circular structures and structures that share
-elements more informatively by binding @code{print-circle}
-to a non-@code{nil} value.
-
- Here is an example of code that creates a circular structure:
-
-@example
-(setq a '(x y))
-(setcar a a)
-@end example
-
-@noindent
-Custom printing prints this as @samp{Result: #1=(#1# y)}. The
-@samp{#1=} notation labels the structure that follows it with the label
-@samp{1}, and the @samp{#1#} notation references the previously labeled
-structure. This notation is used for any shared elements of lists or
-vectors.
-
-@defopt edebug-print-circle
-If non-@code{nil}, Edebug binds @code{print-circle} to this value while
-printing results. The default value is @code{t}.
-@end defopt
-
- Other programs can also use custom printing; see @file{cust-print.el}
-for details.
-
-@node Trace Buffer
-@subsection Trace Buffer
-@cindex trace buffer
-
- Edebug can record an execution trace, storing it in a buffer named
-@samp{*edebug-trace*}. This is a log of function calls and returns,
-showing the function names and their arguments and values. To enable
-trace recording, set @code{edebug-trace} to a non-@code{nil} value.
-
- Making a trace buffer is not the same thing as using trace execution
-mode (@pxref{Edebug Execution Modes}).
-
- When trace recording is enabled, each function entry and exit adds
-lines to the trace buffer. A function entry record consists of
-@samp{::::@{}, followed by the function name and argument values. A
-function exit record consists of @samp{::::@}}, followed by the function
-name and result of the function.
-
- The number of @samp{:}s in an entry shows its recursion depth. You
-can use the braces in the trace buffer to find the matching beginning or
-end of function calls.
-
-@findex edebug-print-trace-before
-@findex edebug-print-trace-after
- You can customize trace recording for function entry and exit by
-redefining the functions @code{edebug-print-trace-before} and
-@code{edebug-print-trace-after}.
-
-@defmac edebug-tracing string body@dots{}
-This macro requests additional trace information around the execution
-of the @var{body} forms. The argument @var{string} specifies text
-to put in the trace buffer, after the @samp{@{} or @samp{@}}. All
-the arguments are evaluated, and @code{edebug-tracing} returns the
-value of the last form in @var{body}.
-@end defmac
-
-@defun edebug-trace format-string &rest format-args
-This function inserts text in the trace buffer. It computes the text
-with @code{(apply 'format @var{format-string} @var{format-args})}.
-It also appends a newline to separate entries.
-@end defun
-
- @code{edebug-tracing} and @code{edebug-trace} insert lines in the
-trace buffer whenever they are called, even if Edebug is not active.
-Adding text to the trace buffer also scrolls its window to show the last
-lines inserted.
-
-@node Coverage Testing
-@subsection Coverage Testing
-
-@cindex coverage testing (Edebug)
-@cindex frequency counts
-@cindex performance analysis
- Edebug provides rudimentary coverage testing and display of execution
-frequency.
-
- Coverage testing works by comparing the result of each expression with
-the previous result; each form in the program is considered ``covered''
-if it has returned two different values since you began testing coverage
-in the current Emacs session. Thus, to do coverage testing on your
-program, execute it under various conditions and note whether it behaves
-correctly; Edebug will tell you when you have tried enough different
-conditions that each form has returned two different values.
-
- Coverage testing makes execution slower, so it is only done if
-@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is
-performed for all execution of an instrumented function, even if the
-execution mode is Go-nonstop, and regardless of whether coverage testing
-is enabled.
-
-@kindex C-x X =
-@findex edebug-temp-display-freq-count
- Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
-the coverage information and the frequency counts for a definition.
-Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
-information temporarily, only until you type another key.
-
-@deffn Command edebug-display-freq-count
-This command displays the frequency count data for each line of the
-current definition.
-
-The frequency counts appear as comment lines after each line of code,
-and you can undo all insertions with one @code{undo} command. The
-counts appear under the @samp{(} before an expression or the @samp{)}
-after an expression, or on the last character of a variable. To
-simplify the display, a count is not shown if it is equal to the
-count of an earlier expression on the same line.
-
-The character @samp{=} following the count for an expression says that
-the expression has returned the same value each time it was evaluated.
-In other words, it is not yet ``covered'' for coverage testing purposes.
-
-To clear the frequency count and coverage data for a definition,
-simply reinstrument it with @code{eval-defun}.
-@end deffn
-
-For example, after evaluating @code{(fac 5)} with a source
-breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
-the breakpoint is reached, the frequency data looks like this:
-
-@example
-(defun fac (n)
- (if (= n 0) (edebug))
-;#6 1 = =5
- (if (< 0 n)
-;#5 =
- (* n (fac (1- n)))
-;# 5 0
- 1))
-;# 0
-@end example
-
-The comment lines show that @code{fac} was called 6 times. The
-first @code{if} statement returned 5 times with the same result each
-time; the same is true of the condition on the second @code{if}.
-The recursive call of @code{fac} did not return at all.
-
-
-@node The Outside Context
-@subsection The Outside Context
-
-Edebug tries to be transparent to the program you are debugging, but it
-does not succeed completely. Edebug also tries to be transparent when
-you evaluate expressions with @kbd{e} or with the evaluation list
-buffer, by temporarily restoring the outside context. This section
-explains precisely what context Edebug restores, and how Edebug fails to
-be completely transparent.
-
-@menu
-* Checking Whether to Stop:: When Edebug decides what to do.
-* Edebug Display Update:: When Edebug updates the display.
-* Edebug Recursive Edit:: When Edebug stops execution.
-@end menu
-
-@node Checking Whether to Stop
-@subsubsection Checking Whether to Stop
-
-Whenever Edebug is entered, it needs to save and restore certain data
-before even deciding whether to make trace information or stop the
-program.
-
-@itemize @bullet
-@item
-@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
-incremented once to reduce Edebug's impact on the stack. You could,
-however, still run out of stack space when using Edebug.
-
-@item
-The state of keyboard macro execution is saved and restored. While
-Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
-unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
-@end itemize
-
-
-@node Edebug Display Update
-@subsubsection Edebug Display Update
-
-@c This paragraph is not filled, because LaLiberte's conversion script
-@c needs an xref to be on just one line.
-When Edebug needs to display something (e.g., in trace mode), it saves
-the current window configuration from ``outside'' Edebug
-(@pxref{Window Configurations}). When you exit Edebug (by continuing
-the program), it restores the previous window configuration.
-
-Emacs redisplays only when it pauses. Usually, when you continue
-execution, the program re-enters Edebug at a breakpoint or after
-stepping, without pausing or reading input in between. In such cases,
-Emacs never gets a chance to redisplay the ``outside'' configuration.
-Consequently, what you see is the same window configuration as the last
-time Edebug was active, with no interruption.
-
-Entry to Edebug for displaying something also saves and restores the
-following data (though some of them are deliberately not restored if an
-error or quit signal occurs).
-
-@itemize @bullet
-@item
-@cindex current buffer point and mark (Edebug)
-Which buffer is current, and the positions of point and the mark in the
-current buffer, are saved and restored.
-
-@item
-@cindex window configuration (Edebug)
-The outside window configuration is saved and restored if
-@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
-
-The window configuration is not restored on error or quit, but the
-outside selected window @emph{is} reselected even on error or quit in
-case a @code{save-excursion} is active. If the value of
-@code{edebug-save-windows} is a list, only the listed windows are saved
-and restored.
-
-The window start and horizontal scrolling of the source code buffer are
-not restored, however, so that the display remains coherent within Edebug.
-
-@item
-The value of point in each displayed buffer is saved and restored if
-@code{edebug-save-displayed-buffer-points} is non-@code{nil}.
-
-@item
-The variables @code{overlay-arrow-position} and
-@code{overlay-arrow-string} are saved and restored. So you can safely
-invoke Edebug from the recursive edit elsewhere in the same buffer.
-
-@item
-@code{cursor-in-echo-area} is locally bound to @code{nil} so that
-the cursor shows up in the window.
-@end itemize
-
-@node Edebug Recursive Edit
-@subsubsection Edebug Recursive Edit
-
-When Edebug is entered and actually reads commands from the user, it
-saves (and later restores) these additional data:
-
-@itemize @bullet
-@item
-The current match data. @xref{Match Data}.
-
-@item
-The variables @code{last-command}, @code{this-command},
-@code{last-command-char}, @code{last-input-char},
-@code{last-input-event}, @code{last-command-event},
-@code{last-event-frame}, @code{last-nonmenu-event}, and
-@code{track-mouse}. Commands used within Edebug do not affect these
-variables outside of Edebug.
-
-Executing commands within Edebug can change the key sequence that
-would be returned by @code{this-command-keys}, and there is no way to
-reset the key sequence from Lisp.
-
-Edebug cannot save and restore the value of
-@code{unread-command-events}. Entering Edebug while this variable has a
-nontrivial value can interfere with execution of the program you are
-debugging.
-
-@item
-Complex commands executed while in Edebug are added to the variable
-@code{command-history}. In rare cases this can alter execution.
-
-@item
-Within Edebug, the recursion depth appears one deeper than the recursion
-depth outside Edebug. This is not true of the automatically updated
-evaluation list window.
-
-@item
-@code{standard-output} and @code{standard-input} are bound to @code{nil}
-by the @code{recursive-edit}, but Edebug temporarily restores them during
-evaluations.
-
-@item
-The state of keyboard macro definition is saved and restored. While
-Edebug is active, @code{defining-kbd-macro} is bound to
-@code{edebug-continue-kbd-macro}.
-@end itemize
-
-@node Edebug and Macros
-@subsection Edebug and Macros
-
-To make Edebug properly instrument expressions that call macros, some
-extra care is needed. This subsection explains the details.
-
-@menu
-* Instrumenting Macro Calls:: The basic problem.
-* Specification List:: How to specify complex patterns of evaluation.
-* Backtracking:: What Edebug does when matching fails.
-* Specification Examples:: To help understand specifications.
-@end menu
-
-@node Instrumenting Macro Calls
-@subsubsection Instrumenting Macro Calls
-
- When Edebug instruments an expression that calls a Lisp macro, it needs
-additional information about the macro to do the job properly. This is
-because there is no a-priori way to tell which subexpressions of the
-macro call are forms to be evaluated. (Evaluation may occur explicitly
-in the macro body, or when the resulting expansion is evaluated, or any
-time later.)
-
- Therefore, you must define an Edebug specification for each macro
-that Edebug will encounter, to explain the format of calls to that
-macro. To do this, add a @code{debug} declaration to the macro
-definition. Here is a simple example that shows the specification for
-the @code{for} example macro (@pxref{Argument Evaluation}).
-
-@smallexample
-(defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
-For example, (for i from 1 to 10 do (print i))."
- (declare (debug (symbolp "from" form "to" form "do" &rest form)))
- ...)
-@end smallexample
-
- The Edebug specification says which parts of a call to the macro are
-forms to be evaluated. For simple macros, the @var{specification}
-often looks very similar to the formal argument list of the macro
-definition, but specifications are much more general than macro
-arguments. @xref{Defining Macros}, for more explanation of
-the @code{declare} form.
-
- You can also define an edebug specification for a macro separately
-from the macro definition with @code{def-edebug-spec}. Adding
-@code{debug} declarations is preferred, and more convenient, for macro
-definitions in Lisp, but @code{def-edebug-spec} makes it possible to
-define Edebug specifications for special forms implemented in C.
-
-@deffn Macro def-edebug-spec macro specification
-Specify which expressions of a call to macro @var{macro} are forms to be
-evaluated. @var{specification} should be the edebug specification.
-Neither argument is evaluated.
-
-The @var{macro} argument can actually be any symbol, not just a macro
-name.
-@end deffn
-
-Here is a table of the possibilities for @var{specification} and how each
-directs processing of arguments.
-
-@table @asis
-@item @code{t}
-All arguments are instrumented for evaluation.
-
-@item @code{0}
-None of the arguments is instrumented.
-
-@item a symbol
-The symbol must have an Edebug specification which is used instead.
-This indirection is repeated until another kind of specification is
-found. This allows you to inherit the specification from another macro.
-
-@item a list
-The elements of the list describe the types of the arguments of a
-calling form. The possible elements of a specification list are
-described in the following sections.
-@end table
-
-@vindex edebug-eval-macro-args
-If a macro has no Edebug specification, neither through a @code{debug}
-declaration nor through a @code{def-edebug-spec} call, the variable
-@code{edebug-eval-macro-args} comes into play. If it is @code{nil},
-the default, none of the arguments is instrumented for evaluation.
-If it is non-@code{nil}, all arguments are instrumented.
-
-@node Specification List
-@subsubsection Specification List
-
-@cindex Edebug specification list
-A @dfn{specification list} is required for an Edebug specification if
-some arguments of a macro call are evaluated while others are not. Some
-elements in a specification list match one or more arguments, but others
-modify the processing of all following elements. The latter, called
-@dfn{specification keywords}, are symbols beginning with @samp{&} (such
-as @code{&optional}).
-
-A specification list may contain sublists which match arguments that are
-themselves lists, or it may contain vectors used for grouping. Sublists
-and groups thus subdivide the specification list into a hierarchy of
-levels. Specification keywords apply only to the remainder of the
-sublist or group they are contained in.
-
-When a specification list involves alternatives or repetition, matching
-it against an actual macro call may require backtracking.
-@xref{Backtracking}, for more details.
-
-Edebug specifications provide the power of regular expression matching,
-plus some context-free grammar constructs: the matching of sublists with
-balanced parentheses, recursive processing of forms, and recursion via
-indirect specifications.
-
-Here's a table of the possible elements of a specification list, with
-their meanings (see @ref{Specification Examples}, for the referenced
-examples):
-
-@table @code
-@item sexp
-A single unevaluated Lisp object, which is not instrumented.
-@c an "expression" is not necessarily intended for evaluation.
-
-@item form
-A single evaluated expression, which is instrumented.
-
-@item place
-@findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
-
-@item body
-Short for @code{&rest form}. See @code{&rest} below.
-
-@item function-form
-A function form: either a quoted function symbol, a quoted lambda
-expression, or a form (that should evaluate to a function symbol or
-lambda expression). This is useful when an argument that's a lambda
-expression might be quoted with @code{quote} rather than
-@code{function}, since it instruments the body of the lambda expression
-either way.
-
-@item lambda-expr
-A lambda expression with no quoting.
-
-@item &optional
-@c @kindex &optional @r{(Edebug)}
-All following elements in the specification list are optional; as soon
-as one does not match, Edebug stops matching at this level.
-
-To make just a few elements optional followed by non-optional elements,
-use @code{[&optional @var{specs}@dots{}]}. To specify that several
-elements must all match or none, use @code{&optional
-[@var{specs}@dots{}]}. See the @code{defun} example.
-
-@item &rest
-@c @kindex &rest @r{(Edebug)}
-All following elements in the specification list are repeated zero or
-more times. In the last repetition, however, it is not a problem if the
-expression runs out before matching all of the elements of the
-specification list.
-
-To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
-To specify several elements that must all match on every repetition, use
-@code{&rest [@var{specs}@dots{}]}.
-
-@item &or
-@c @kindex &or @r{(Edebug)}
-Each of the following elements in the specification list is an
-alternative. One of the alternatives must match, or the @code{&or}
-specification fails.
-
-Each list element following @code{&or} is a single alternative. To
-group two or more list elements as a single alternative, enclose them in
-@code{[@dots{}]}.
-
-@item ¬
-@c @kindex ¬ @r{(Edebug)}
-Each of the following elements is matched as alternatives as if by using
-@code{&or}, but if any of them match, the specification fails. If none
-of them match, nothing is matched, but the @code{¬} specification
-succeeds.
-
-@item &define
-@c @kindex &define @r{(Edebug)}
-Indicates that the specification is for a defining form. The defining
-form itself is not instrumented (that is, Edebug does not stop before and
-after the defining form), but forms inside it typically will be
-instrumented. The @code{&define} keyword should be the first element in
-a list specification.
-
-@item nil
-This is successful when there are no more arguments to match at the
-current argument list level; otherwise it fails. See sublist
-specifications and the backquote example.
-
-@item gate
-@cindex preventing backtracking
-No argument is matched but backtracking through the gate is disabled
-while matching the remainder of the specifications at this level. This
-is primarily used to generate more specific syntax error messages. See
-@ref{Backtracking}, for more details. Also see the @code{let} example.
-
-@item @var{other-symbol}
-@cindex indirect specifications
-Any other symbol in a specification list may be a predicate or an
-indirect specification.
-
-If the symbol has an Edebug specification, this @dfn{indirect
-specification} should be either a list specification that is used in
-place of the symbol, or a function that is called to process the
-arguments. The specification may be defined with @code{def-edebug-spec}
-just as for macros. See the @code{defun} example.
-
-Otherwise, the symbol should be a predicate. The predicate is called
-with the argument and the specification fails if the predicate returns
-@code{nil}. In either case, that argument is not instrumented.
-
-Some suitable predicates include @code{symbolp}, @code{integerp},
-@code{stringp}, @code{vectorp}, and @code{atom}.
-
-@item [@var{elements}@dots{}]
-@cindex [@dots{}] (Edebug)
-A vector of elements groups the elements into a single @dfn{group
-specification}. Its meaning has nothing to do with vectors.
-
-@item "@var{string}"
-The argument should be a symbol named @var{string}. This specification
-is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
-of @var{symbol} is the @var{string}, but the string form is preferred.
-
-@item (vector @var{elements}@dots{})
-The argument should be a vector whose elements must match the
-@var{elements} in the specification. See the backquote example.
-
-@item (@var{elements}@dots{})
-Any other list is a @dfn{sublist specification} and the argument must be
-a list whose elements match the specification @var{elements}.
-
-@cindex dotted lists (Edebug)
-A sublist specification may be a dotted list and the corresponding list
-argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
-dotted list specification may be another sublist specification (via a
-grouping or an indirect specification, e.g., @code{(spec . [(more
-specs@dots{})])}) whose elements match the non-dotted list arguments.
-This is useful in recursive specifications such as in the backquote
-example. Also see the description of a @code{nil} specification
-above for terminating such recursion.
-
-Note that a sublist specification written as @code{(specs . nil)}
-is equivalent to @code{(specs)}, and @code{(specs .
-(sublist-elements@dots{}))} is equivalent to @code{(specs
-sublist-elements@dots{})}.
-@end table
-
-@c Need to document extensions with &symbol and :symbol
-
-Here is a list of additional specifications that may appear only after
-@code{&define}. See the @code{defun} example.
-
-@table @code
-@item name
-The argument, a symbol, is the name of the defining form.
-
-A defining form is not required to have a name field; and it may have
-multiple name fields.
-
-@item :name
-This construct does not actually match an argument. The element
-following @code{:name} should be a symbol; it is used as an additional
-name component for the definition. You can use this to add a unique,
-static component to the name of the definition. It may be used more
-than once.
-
-@item arg
-The argument, a symbol, is the name of an argument of the defining form.
-However, lambda-list keywords (symbols starting with @samp{&})
-are not allowed.
-
-@item lambda-list
-@cindex lambda-list (Edebug)
-This matches a lambda list---the argument list of a lambda expression.
-
-@item def-body
-The argument is the body of code in a definition. This is like
-@code{body}, described above, but a definition body must be instrumented
-with a different Edebug call that looks up information associated with
-the definition. Use @code{def-body} for the highest level list of forms
-within the definition.
-
-@item def-form
-The argument is a single, highest-level form in a definition. This is
-like @code{def-body}, except use this to match a single form rather than
-a list of forms. As a special case, @code{def-form} also means that
-tracing information is not output when the form is executed. See the
-@code{interactive} example.
-@end table
-
-@node Backtracking
-@subsubsection Backtracking in Specifications
-
-@cindex backtracking
-@cindex syntax error (Edebug)
-If a specification fails to match at some point, this does not
-necessarily mean a syntax error will be signaled; instead,
-@dfn{backtracking} will take place until all alternatives have been
-exhausted. Eventually every element of the argument list must be
-matched by some element in the specification, and every required element
-in the specification must match some argument.
-
-When a syntax error is detected, it might not be reported until much
-later after higher-level alternatives have been exhausted, and with the
-point positioned further from the real error. But if backtracking is
-disabled when an error occurs, it can be reported immediately. Note
-that backtracking is also reenabled automatically in several situations;
-it is reenabled when a new alternative is established by
-@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
-processing a sublist, group, or indirect specification. The effect of
-enabling or disabling backtracking is limited to the remainder of the
-level currently being processed and lower levels.
-
-Backtracking is disabled while matching any of the
-form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
-@code{def-body}). These specifications will match any form so any error
-must be in the form itself rather than at a higher level.
-
-Backtracking is also disabled after successfully matching a quoted
-symbol or string specification, since this usually indicates a
-recognized construct. But if you have a set of alternative constructs that
-all begin with the same symbol, you can usually work around this
-constraint by factoring the symbol out of the alternatives, e.g.,
-@code{["foo" &or [first case] [second case] ...]}.
-
-Most needs are satisfied by these two ways that backtracking is
-automatically disabled, but occasionally it is useful to explicitly
-disable backtracking by using the @code{gate} specification. This is
-useful when you know that no higher alternatives could apply. See the
-example of the @code{let} specification.
-
-@node Specification Examples
-@subsubsection Specification Examples
-
-It may be easier to understand Edebug specifications by studying
-the examples provided here.
-
-A @code{let} special form has a sequence of bindings and a body. Each
-of the bindings is either a symbol or a sublist with a symbol and
-optional expression. In the specification below, notice the @code{gate}
-inside of the sublist to prevent backtracking once a sublist is found.
-
-@example
-(def-edebug-spec let
- ((&rest
- &or symbolp (gate symbolp &optional form))
- body))
-@end example
-
-Edebug uses the following specifications for @code{defun} and
-@code{defmacro} and the associated argument list and @code{interactive}
-specifications. It is necessary to handle interactive forms specially
-since an expression argument is actually evaluated outside of the
-function body.
-
-@smallexample
-(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
-(def-edebug-spec defun
- (&define name lambda-list
- [&optional stringp] ; @r{Match the doc string, if present.}
- [&optional ("interactive" interactive)]
- def-body))
-
-(def-edebug-spec lambda-list
- (([&rest arg]
- [&optional ["&optional" arg &rest arg]]
- &optional ["&rest" arg]
- )))
-
-(def-edebug-spec interactive
- (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
-@end smallexample
-
-The specification for backquote below illustrates how to match
-dotted lists and use @code{nil} to terminate recursion. It also
-illustrates how components of a vector may be matched. (The actual
-specification defined by Edebug does not support dotted lists because
-doing so causes very deep recursion that could fail.)
-
-@smallexample
-(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
-
-(def-edebug-spec backquote-form
- (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
- (backquote-form . [&or nil backquote-form])
- (vector &rest backquote-form)
- sexp))
-@end smallexample
-
-
-@node Edebug Options
-@subsection Edebug Options
-
- These options affect the behavior of Edebug:
-
-@defopt edebug-setup-hook
-Functions to call before Edebug is used. Each time it is set to a new
-value, Edebug will call those functions once and then
-@code{edebug-setup-hook} is reset to @code{nil}. You could use this to
-load up Edebug specifications associated with a package you are using
-but only when you also use Edebug.
-@xref{Instrumenting}.
-@end defopt
-
-@defopt edebug-all-defs
-If this is non-@code{nil}, normal evaluation of defining forms such as
-@code{defun} and @code{defmacro} instruments them for Edebug. This
-applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
-and @code{eval-current-buffer}.
-
-Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
-option. @xref{Instrumenting}.
-@end defopt
-
-@defopt edebug-all-forms
-If this is non-@code{nil}, the commands @code{eval-defun},
-@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
-instrument all forms, even those that don't define anything.
-This doesn't apply to loading or evaluations in the minibuffer.
-
-Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
-option. @xref{Instrumenting}.
-@end defopt
-
-@defopt edebug-save-windows
-If this is non-@code{nil}, Edebug saves and restores the window
-configuration. That takes some time, so if your program does not care
-what happens to the window configurations, it is better to set this
-variable to @code{nil}.
-
-If the value is a list, only the listed windows are saved and
-restored.
-
-You can use the @kbd{W} command in Edebug to change this variable
-interactively. @xref{Edebug Display Update}.
-@end defopt
-
-@defopt edebug-save-displayed-buffer-points
-If this is non-@code{nil}, Edebug saves and restores point in all
-displayed buffers.
-
-Saving and restoring point in other buffers is necessary if you are
-debugging code that changes the point of a buffer which is displayed in
-a non-selected window. If Edebug or the user then selects the window,
-point in that buffer will move to the window's value of point.
-
-Saving and restoring point in all buffers is expensive, since it
-requires selecting each window twice, so enable this only if you need
-it. @xref{Edebug Display Update}.
-@end defopt
-
-@defopt edebug-initial-mode
-If this variable is non-@code{nil}, it specifies the initial execution
-mode for Edebug when it is first activated. Possible values are
-@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
-@code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
-
-The default value is @code{step}.
-@xref{Edebug Execution Modes}.
-@end defopt
-
-@defopt edebug-trace
-If this is non-@code{nil}, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
-function entry or exit per line, indented by the recursion level.
-
-Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
-@end defopt
-
-@defopt edebug-test-coverage
-If non-@code{nil}, Edebug tests coverage of all expressions debugged.
-@xref{Coverage Testing}.
-@end defopt
-
-@defopt edebug-continue-kbd-macro
-If non-@code{nil}, continue defining or executing any keyboard macro
-that is executing outside of Edebug. Use this with caution since it is not
-debugged.
-@xref{Edebug Execution Modes}.
-@end defopt
-
-@defopt edebug-on-error
-Edebug binds @code{debug-on-error} to this value, if
-@code{debug-on-error} was previously @code{nil}. @xref{Trapping
-Errors}.
-@end defopt
-
-@defopt edebug-on-quit
-Edebug binds @code{debug-on-quit} to this value, if
-@code{debug-on-quit} was previously @code{nil}. @xref{Trapping
-Errors}.
-@end defopt
-
- If you change the values of @code{edebug-on-error} or
-@code{edebug-on-quit} while Edebug is active, their values won't be used
-until the @emph{next} time Edebug is invoked via a new command.
-@c Not necessarily a deeper command level.
-@c A new command is not precisely true, but that is close enough -- dan
-
-@defopt edebug-global-break-condition
-If non-@code{nil}, an expression to test for at every stop point. If
-the result is non-@code{nil}, then break. Errors are ignored.
-@xref{Global Break Condition}.
-@end defopt
-
-@ignore
- arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
-@c Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@c
-@comment %**start of header
-@setfilename covers.info
-@settitle GNU Emacs Lisp Reference Manual
-@comment %**end of header
-
-@titlepage
-@c ================ Volume 1 ================
-@w{ }
-@sp 2
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 1}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@page
-@c ================ Volume 2 ================
-@w{ }
-@sp 5
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 2}
-@sp 2
-@center by Bil Lewis,
-@center Dan LaLiberte, and
-@center the GNU Manual Group
-
-@page
-@c ================ Volume 1 with baseline skip 16pt ================
-
-@tex
-\global\baselineskip = 16pt
-@end tex
-
-16 pts baseline skip:
-
-@w{ }
-@sp 2
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 1}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@page
-@c ================ Volume 1 with baseline skip 18pt ================
-
-@tex
-\global\baselineskip = 18pt
-@end tex
-
-18 pts baseline skip, with 15pts between sections
-
-@w{ }
-@sp 2
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@tex
-\global\baselineskip = 15pt
-@end tex
-
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 1}
-@sp 2
-@center by Bil Lewis,
-@center Dan LaLiberte, and
-@center the GNU Manual Group
-
-@page
-@c ================ Volume 1 with more baseline skip 24 pts ================
-
-@tex
-\global\baselineskip = 24pt
-@end tex
-
-24 pts baseline skip:
-
-@w{ }
-@sp 2
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 1}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@page
-@c ================ Volume 2 with more baseline skip 18 pts ================
-
-@tex
-\global\baselineskip = 18pt
-@end tex
-
-18 pts baseline skip:
-
-@w{ }
-@sp 5
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 2}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@page
-@c ================ Volume 2 with more baseline skip 24 pts ================
-
-@tex
-\global\baselineskip = 24pt
-@end tex
-
-24 pts baseline skip:
-
-@w{ }
-@sp 5
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 2
-@center @titlefont{Volume 2}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-
-@page
-@c ================ Spine 1 ================
-
-@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}}
-@sp 4
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 4
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@sp 4
-@author The GNU Emacs Lisp Reference Manual --- Vol. 1
-@sp 3
-@author FSF
-
-@author
-
-@page
-@c ================ Spine 2 ================
-
-@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}}
-@sp 4
-@center GNU Emacs Version 19
-@center for Unix Users
-@center Edition 2.3, June 1994
-@sp 4
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-
-@sp 4
-@author The GNU Emacs Lisp Reference Manual --- Vol. 2
-@sp 3
-@author FSF
-
-@end titlepage
-@bye
-
-@ignore
- arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98
-@end ignore
+++ /dev/null
-\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
-
-@dircategory Emacs
-@direntry
-* Elisp: (elisp). The Emacs Lisp Reference Manual.
-@end direntry
-
-@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
-
-@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.
-* 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
-
-\f
-These words prevent "local variables" above from confusing Emacs.
-
-@ignore
- arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/errors
-@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top
-@appendix Standard Errors
-@cindex standard errors
-
- Here is the complete list of the error symbols in standard Emacs,
-grouped by concept. The list includes each symbol's message (on the
-@code{error-message} property of the symbol) and a cross reference to a
-description of how the error can occur.
-
- Each error symbol has an @code{error-conditions} property that is a
-list of symbols. Normally this list includes the error symbol itself
-and the symbol @code{error}. Occasionally it includes additional
-symbols, which are intermediate classifications, narrower than
-@code{error} but broader than a single error symbol. For example, all
-the errors in accessing files have the condition @code{file-error}. If
-we do not say here that a certain error symbol has additional error
-conditions, that means it has none.
-
- As a special exception, the error symbol @code{quit} does not have the
-condition @code{error}, because quitting is not considered an error.
-
- @xref{Errors}, for an explanation of how errors are generated and
-handled.
-
-@table @code
-@item @var{symbol}
-@var{string}; @var{reference}.
-
-@item error
-@code{"error"}@*
-@xref{Errors}.
-
-@item quit
-@code{"Quit"}@*
-@xref{Quitting}.
-
-@item args-out-of-range
-@code{"Args out of range"}@*
-This happens when trying to access an element beyond the range of a
-sequence or buffer.@*
-@xref{Sequences Arrays Vectors}, @xref{Text}.
-
-@item arith-error
-@code{"Arithmetic error"}@*
-@xref{Arithmetic Operations}.
-
-@item beginning-of-buffer
-@code{"Beginning of buffer"}@*
-@xref{Character Motion}.
-
-@item buffer-read-only
-@code{"Buffer is read-only"}@*
-@xref{Read Only Buffers}.
-
-@item coding-system-error
-@code{"Invalid coding system"}@*
-@xref{Lisp and Coding Systems}.
-
-@item cyclic-function-indirection
-@code{"Symbol's chain of function indirections\@* contains a loop"}@*
-@xref{Function Indirection}.
-
-@item cyclic-variable-indirection
-@code{"Symbol's chain of variable indirections\@* contains a loop"}@*
-@xref{Variable Aliases}.
-
-@item end-of-buffer
-@code{"End of buffer"}@*
-@xref{Character Motion}.
-
-@item end-of-file
-@code{"End of file during parsing"}@*
-Note that this is not a subcategory of @code{file-error},
-because it pertains to the Lisp reader, not to file I/O.@*
-@xref{Input Functions}.
-
-@item file-already-exists
-This is a subcategory of @code{file-error}.@*
-@xref{Writing to Files}.
-
-@item file-date-error
-This is a subcategory of @code{file-error}. It occurs when
-@code{copy-file} tries and fails to set the last-modification time of
-the output file.@*
-@xref{Changing Files}.
-
-@item file-error
-We do not list the error-strings of this error and its subcategories,
-because the error message is normally constructed from the data items
-alone when the error condition @code{file-error} is present. Thus,
-the error-strings are not very relevant. However, these error symbols
-do have @code{error-message} properties, and if no data is provided,
-the @code{error-message} property @emph{is} used.@*
-@xref{Files}.
-
-@item file-locked
-This is a subcategory of @code{file-error}.@*
-@xref{File Locks}.
-
-@item file-supersession
-This is a subcategory of @code{file-error}.@*
-@xref{Modification Time}.
-
-@item ftp-error
-This is a subcategory of @code{file-error}, which results from problems
-in accessing a remote file using ftp.@*
-@xref{Remote Files,,, emacs, The GNU Emacs Manual}.
-
-@item invalid-function
-@code{"Invalid function"}@*
-@xref{Function Indirection}.
-
-@item invalid-read-syntax
-@code{"Invalid read syntax"}@*
-@xref{Printed Representation}.
-
-@item invalid-regexp
-@code{"Invalid regexp"}@*
-@xref{Regular Expressions}.
-
-@item mark-inactive
-@code{"The mark is not active now"}@*
-@xref{The Mark}.
-
-@item no-catch
-@code{"No catch for tag"}@*
-@xref{Catch and Throw}.
-
-@item scan-error
-@code{"Scan error"}@*
-This happens when certain syntax-parsing functions
-find invalid syntax or mismatched parentheses.@*
-@xref{List Motion}, and @ref{Parsing Expressions}.
-
-@item search-failed
-@code{"Search failed"}@*
-@xref{Searching and Matching}.
-
-@item setting-constant
-@code{"Attempt to set a constant symbol"}@*
-The values of the symbols @code{nil} and @code{t},
-and any symbols that start with @samp{:},
-may not be changed.@*
-@xref{Constant Variables, , Variables that Never Change}.
-
-@item text-read-only
-@code{"Text is read-only"}@*
-This is a subcategory of @code{buffer-read-only}.@*
-@xref{Special Properties}.
-
-@item undefined-color
-@code{"Undefined color"}@*
-@xref{Color Names}.
-
-@item void-function
-@code{"Symbol's function definition is void"}@*
-@xref{Function Cells}.
-
-@item void-variable
-@code{"Symbol's value as variable is void"}@*
-@xref{Accessing Variables}.
-
-@item wrong-number-of-arguments
-@code{"Wrong number of arguments"}@*
-@xref{Classifying Lists}.
-
-@item wrong-type-argument
-@code{"Wrong type argument"}@*
-@xref{Type Predicates}.
-@end table
-
- These kinds of error, which are classified as special cases of
-@code{arith-error}, can occur on certain systems for invalid use of
-mathematical functions.
-
-@table @code
-@item domain-error
-@code{"Arithmetic domain error"}@*
-@xref{Math Functions}.
-
-@item overflow-error
-@code{"Arithmetic overflow error"}@*
-This is a subcategory of @code{domain-error}.@*
-@xref{Math Functions}.
-
-@item range-error
-@code{"Arithmetic range error"}@*
-@xref{Math Functions}.
-
-@item singularity-error
-@code{"Arithmetic singularity error"}@*
-This is a subcategory of @code{domain-error}.@*
-@xref{Math Functions}.
-
-@item underflow-error
-@code{"Arithmetic underflow error"}@*
-This is a subcategory of @code{domain-error}.@*
-@xref{Math Functions}.
-@end table
-
-@ignore
- arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/eval
-@node Evaluation, Control Structures, Symbols, Top
-@chapter Evaluation
-@cindex evaluation
-@cindex interpreter
-@cindex interpreter
-@cindex value of expression
-
- The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
-@dfn{Lisp interpreter}---a program that receives a Lisp object as input
-and computes its @dfn{value as an expression}. How it does this depends
-on the data type of the object, according to rules described in this
-chapter. The interpreter runs automatically to evaluate portions of
-your program, but can also be called explicitly via the Lisp primitive
-function @code{eval}.
-
-@ifnottex
-@menu
-* 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.
-@end menu
-
-@node Intro Eval
-@section Introduction to Evaluation
-
- The Lisp interpreter, or evaluator, is the program that computes
-the value of an expression that is given to it. When a function
-written in Lisp is called, the evaluator computes the value of the
-function by evaluating the expressions in the function body. Thus,
-running any Lisp program really means running the Lisp interpreter.
-
- How the evaluator handles an object depends primarily on the data
-type of the object.
-@end ifnottex
-
-@cindex forms
-@cindex expression
- A Lisp object that is intended for evaluation is called an
-@dfn{expression} or a @dfn{form}. The fact that expressions are data
-objects and not merely text is one of the fundamental differences
-between Lisp-like languages and typical programming languages. Any
-object can be evaluated, but in practice only numbers, symbols, lists
-and strings are evaluated very often.
-
- It is very common to read a Lisp expression and then evaluate the
-expression, but reading and evaluation are separate activities, and
-either can be performed alone. Reading per se does not evaluate
-anything; it converts the printed representation of a Lisp object to the
-object itself. It is up to the caller of @code{read} whether this
-object is a form to be evaluated, or serves some entirely different
-purpose. @xref{Input Functions}.
-
- Do not confuse evaluation with command key interpretation. The
-editor command loop translates keyboard input into a command (an
-interactively callable function) using the active keymaps, and then
-uses @code{call-interactively} to invoke the command. The execution of
-the command itself involves evaluation if the command is written in
-Lisp, but that is not a part of command key interpretation itself.
-@xref{Command Loop}.
-
-@cindex recursive evaluation
- Evaluation is a recursive process. That is, evaluation of a form may
-call @code{eval} to evaluate parts of the form. For example, evaluation
-of a function call first evaluates each argument of the function call,
-and then evaluates each form in the function body. Consider evaluation
-of the form @code{(car x)}: the subform @code{x} must first be evaluated
-recursively, so that its value can be passed as an argument to the
-function @code{car}.
-
- Evaluation of a function call ultimately calls the function specified
-in it. @xref{Functions}. The execution of the function may itself work
-by evaluating the function definition; or the function may be a Lisp
-primitive implemented in C, or it may be a byte-compiled function
-(@pxref{Byte Compilation}).
-
-@cindex environment
- The evaluation of forms takes place in a context called the
-@dfn{environment}, which consists of the current values and bindings of
-all Lisp variables.@footnote{This definition of ``environment'' is
-specifically not intended to include all the data that can affect the
-result of a program.} Whenever a form refers to a variable without
-creating a new binding for it, the value of the variable's binding in
-the current environment is used. @xref{Variables}.
-
-@cindex side effect
- Evaluation of a form may create new environments for recursive
-evaluation by binding variables (@pxref{Local Variables}). These
-environments are temporary and vanish by the time evaluation of the form
-is complete. The form may also make changes that persist; these changes
-are called @dfn{side effects}. An example of a form that produces side
-effects is @code{(setq foo 1)}.
-
- The details of what evaluation means for each kind of form are
-described below (@pxref{Forms}).
-
-@node Forms
-@section Kinds of Forms
-
- A Lisp object that is intended to be evaluated is called a @dfn{form}.
-How Emacs evaluates a form depends on its data type. Emacs has three
-different kinds of form that are evaluated differently: symbols, lists,
-and ``all other types.'' This section describes all three kinds, one by
-one, starting with the ``all other types'' which are self-evaluating
-forms.
-
-@menu
-* 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.
-@end menu
-
-@node Self-Evaluating Forms
-@subsection Self-Evaluating Forms
-@cindex vector evaluation
-@cindex literal evaluation
-@cindex self-evaluating form
-
- A @dfn{self-evaluating form} is any form that is not a list or symbol.
-Self-evaluating forms evaluate to themselves: the result of evaluation
-is the same object that was evaluated. Thus, the number 25 evaluates to
-25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
-Likewise, evaluation of a vector does not cause evaluation of the
-elements of the vector---it returns the same vector with its contents
-unchanged.
-
-@example
-@group
-'123 ; @r{A number, shown without evaluation.}
- @result{} 123
-@end group
-@group
-123 ; @r{Evaluated as usual---result is the same.}
- @result{} 123
-@end group
-@group
-(eval '123) ; @r{Evaluated ``by hand''---result is the same.}
- @result{} 123
-@end group
-@group
-(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
- @result{} 123
-@end group
-@end example
-
- It is common to write numbers, characters, strings, and even vectors
-in Lisp code, taking advantage of the fact that they self-evaluate.
-However, it is quite unusual to do this for types that lack a read
-syntax, because there's no way to write them textually. It is possible
-to construct Lisp expressions containing these types by means of a Lisp
-program. Here is an example:
-
-@example
-@group
-;; @r{Build an expression containing a buffer object.}
-(setq print-exp (list 'print (current-buffer)))
- @result{} (print #<buffer eval.texi>)
-@end group
-@group
-;; @r{Evaluate it.}
-(eval print-exp)
- @print{} #<buffer eval.texi>
- @result{} #<buffer eval.texi>
-@end group
-@end example
-
-@node Symbol Forms
-@subsection Symbol Forms
-@cindex symbol evaluation
-
- When a symbol is evaluated, it is treated as a variable. The result
-is the variable's value, if it has one. If it has none (if its value
-cell is void), an error is signaled. For more information on the use of
-variables, see @ref{Variables}.
-
- In the following example, we set the value of a symbol with
-@code{setq}. Then we evaluate the symbol, and get back the value that
-@code{setq} stored.
-
-@example
-@group
-(setq a 123)
- @result{} 123
-@end group
-@group
-(eval 'a)
- @result{} 123
-@end group
-@group
-a
- @result{} 123
-@end group
-@end example
-
- The symbols @code{nil} and @code{t} are treated specially, so that the
-value of @code{nil} is always @code{nil}, and the value of @code{t} is
-always @code{t}; you cannot set or bind them to any other values. Thus,
-these two symbols act like self-evaluating forms, even though
-@code{eval} treats them like any other symbol. A symbol whose name
-starts with @samp{:} also self-evaluates in the same way; likewise,
-its value ordinarily cannot be changed. @xref{Constant Variables}.
-
-@node Classifying Lists
-@subsection Classification of List Forms
-@cindex list form evaluation
-
- A form that is a nonempty list is either a function call, a macro
-call, or a special form, according to its first element. These three
-kinds of forms are evaluated in different ways, described below. The
-remaining list elements constitute the @dfn{arguments} for the function,
-macro, or special form.
-
- The first step in evaluating a nonempty list is to examine its first
-element. This element alone determines what kind of form the list is
-and how the rest of the list is to be processed. The first element is
-@emph{not} evaluated, as it would be in some Lisp dialects such as
-Scheme.
-
-@node Function Indirection
-@subsection Symbol Function Indirection
-@cindex symbol function indirection
-@cindex indirection for functions
-@cindex void function
-
- If the first element of the list is a symbol then evaluation examines
-the symbol's function cell, and uses its contents instead of the
-original symbol. If the contents are another symbol, this process,
-called @dfn{symbol function indirection}, is repeated until it obtains a
-non-symbol. @xref{Function Names}, for more information about using a
-symbol as a name for a function stored in the function cell of the
-symbol.
-
- One possible consequence of this process is an infinite loop, in the
-event that a symbol's function cell refers to the same symbol. Or a
-symbol may have a void function cell, in which case the subroutine
-@code{symbol-function} signals a @code{void-function} error. But if
-neither of these things happens, we eventually obtain a non-symbol,
-which ought to be a function or other suitable object.
-
-@kindex invalid-function
- More precisely, we should now have a Lisp function (a lambda
-expression), a byte-code function, a primitive function, a Lisp macro, a
-special form, or an autoload object. Each of these types is a case
-described in one of the following sections. If the object is not one of
-these types, the error @code{invalid-function} is signaled.
-
- The following example illustrates the symbol indirection process. We
-use @code{fset} to set the function cell of a symbol and
-@code{symbol-function} to get the function cell contents
-(@pxref{Function Cells}). Specifically, we store the symbol @code{car}
-into the function cell of @code{first}, and the symbol @code{first} into
-the function cell of @code{erste}.
-
-@smallexample
-@group
-;; @r{Build this function cell linkage:}
-;; ------------- ----- ------- -------
-;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
-;; ------------- ----- ------- -------
-@end group
-@end smallexample
-
-@smallexample
-@group
-(symbol-function 'car)
- @result{} #<subr car>
-@end group
-@group
-(fset 'first 'car)
- @result{} car
-@end group
-@group
-(fset 'erste 'first)
- @result{} first
-@end group
-@group
-(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
- @result{} 1
-@end group
-@end smallexample
-
- By contrast, the following example calls a function without any symbol
-function indirection, because the first element is an anonymous Lisp
-function, not a symbol.
-
-@smallexample
-@group
-((lambda (arg) (erste arg))
- '(1 2 3))
- @result{} 1
-@end group
-@end smallexample
-
-@noindent
-Executing the function itself evaluates its body; this does involve
-symbol function indirection when calling @code{erste}.
-
- The built-in function @code{indirect-function} provides an easy way to
-perform symbol function indirection explicitly.
-
-@c Emacs 19 feature
-@defun indirect-function function &optional noerror
-@anchor{Definition of indirect-function}
-This function returns the meaning of @var{function} as a function. If
-@var{function} is a symbol, then it finds @var{function}'s function
-definition and starts over with that value. If @var{function} is not a
-symbol, then it returns @var{function} itself.
-
-This function signals a @code{void-function} error if the final symbol
-is unbound and optional argument @var{noerror} is @code{nil} or
-omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
-@code{nil} if the final symbol is unbound.
-
-It signals a @code{cyclic-function-indirection} error if there is a
-loop in the chain of symbols.
-
-Here is how you could define @code{indirect-function} in Lisp:
-
-@smallexample
-(defun indirect-function (function)
- (if (symbolp function)
- (indirect-function (symbol-function function))
- function))
-@end smallexample
-@end defun
-
-@node Function Forms
-@subsection Evaluation of Function Forms
-@cindex function form evaluation
-@cindex function call
-
- If the first element of a list being evaluated is a Lisp function
-object, byte-code object or primitive function object, then that list is
-a @dfn{function call}. For example, here is a call to the function
-@code{+}:
-
-@example
-(+ 1 x)
-@end example
-
- The first step in evaluating a function call is to evaluate the
-remaining elements of the list from left to right. The results are the
-actual argument values, one value for each list element. The next step
-is to call the function with this list of arguments, effectively using
-the function @code{apply} (@pxref{Calling Functions}). If the function
-is written in Lisp, the arguments are used to bind the argument
-variables of the function (@pxref{Lambda Expressions}); then the forms
-in the function body are evaluated in order, and the value of the last
-body form becomes the value of the function call.
-
-@node Macro Forms
-@subsection Lisp Macro Evaluation
-@cindex macro call evaluation
-
- If the first element of a list being evaluated is a macro object, then
-the list is a @dfn{macro call}. When a macro call is evaluated, the
-elements of the rest of the list are @emph{not} initially evaluated.
-Instead, these elements themselves are used as the arguments of the
-macro. The macro definition computes a replacement form, called the
-@dfn{expansion} of the macro, to be evaluated in place of the original
-form. The expansion may be any sort of form: a self-evaluating
-constant, a symbol, or a list. If the expansion is itself a macro call,
-this process of expansion repeats until some other sort of form results.
-
- Ordinary evaluation of a macro call finishes by evaluating the
-expansion. However, the macro expansion is not necessarily evaluated
-right away, or at all, because other programs also expand macro calls,
-and they may or may not evaluate the expansions.
-
- Normally, the argument expressions are not evaluated as part of
-computing the macro expansion, but instead appear as part of the
-expansion, so they are computed when the expansion is evaluated.
-
- For example, given a macro defined as follows:
-
-@example
-@group
-(defmacro cadr (x)
- (list 'car (list 'cdr x)))
-@end group
-@end example
-
-@noindent
-an expression such as @code{(cadr (assq 'handler list))} is a macro
-call, and its expansion is:
-
-@example
-(car (cdr (assq 'handler list)))
-@end example
-
-@noindent
-Note that the argument @code{(assq 'handler list)} appears in the
-expansion.
-
-@xref{Macros}, for a complete description of Emacs Lisp macros.
-
-@node Special Forms
-@subsection Special Forms
-@cindex special form evaluation
-
- A @dfn{special form} is a primitive function specially marked so that
-its arguments are not all evaluated. Most special forms define control
-structures or perform variable bindings---things which functions cannot
-do.
-
- Each special form has its own rules for which arguments are evaluated
-and which are used without evaluation. Whether a particular argument is
-evaluated may depend on the results of evaluating other arguments.
-
- Here is a list, in alphabetical order, of all of the special forms in
-Emacs Lisp with a reference to where each is described.
-
-@table @code
-@item and
-@pxref{Combining Conditions}
-
-@item catch
-@pxref{Catch and Throw}
-
-@item cond
-@pxref{Conditionals}
-
-@item condition-case
-@pxref{Handling Errors}
-
-@item defconst
-@pxref{Defining Variables}
-
-@item defmacro
-@pxref{Defining Macros}
-
-@item defun
-@pxref{Defining Functions}
-
-@item defvar
-@pxref{Defining Variables}
-
-@item function
-@pxref{Anonymous Functions}
-
-@item if
-@pxref{Conditionals}
-
-@item interactive
-@pxref{Interactive Call}
-
-@item let
-@itemx let*
-@pxref{Local Variables}
-
-@item or
-@pxref{Combining Conditions}
-
-@item prog1
-@itemx prog2
-@itemx progn
-@pxref{Sequencing}
-
-@item quote
-@pxref{Quoting}
-
-@item save-current-buffer
-@pxref{Current Buffer}
-
-@item save-excursion
-@pxref{Excursions}
-
-@item save-restriction
-@pxref{Narrowing}
-
-@item save-window-excursion
-@pxref{Window Configurations}
-
-@item setq
-@pxref{Setting Variables}
-
-@item setq-default
-@pxref{Creating Buffer-Local}
-
-@item track-mouse
-@pxref{Mouse Tracking}
-
-@item unwind-protect
-@pxref{Nonlocal Exits}
-
-@item while
-@pxref{Iteration}
-
-@item with-output-to-temp-buffer
-@pxref{Temporary Displays}
-@end table
-
-@cindex CL note---special forms compared
-@quotation
-@b{Common Lisp note:} Here are some comparisons of special forms in
-GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
-@code{catch} are special forms in both Emacs Lisp and Common Lisp.
-@code{defun} is a special form in Emacs Lisp, but a macro in Common
-Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
-doesn't exist in Common Lisp. @code{throw} is a special form in
-Common Lisp (because it must be able to throw multiple values), but it
-is a function in Emacs Lisp (which doesn't have multiple
-values).@refill
-@end quotation
-
-@node Autoloading
-@subsection Autoloading
-
- The @dfn{autoload} feature allows you to call a function or macro
-whose function definition has not yet been loaded into Emacs. It
-specifies which file contains the definition. When an autoload object
-appears as a symbol's function definition, calling that symbol as a
-function automatically loads the specified file; then it calls the real
-definition loaded from that file. @xref{Autoload}.
-
-@node Quoting
-@section Quoting
-
- The special form @code{quote} returns its single argument, as written,
-without evaluating it. This provides a way to include constant symbols
-and lists, which are not self-evaluating objects, in a program. (It is
-not necessary to quote self-evaluating objects such as numbers, strings,
-and vectors.)
-
-@defspec quote object
-This special form returns @var{object}, without evaluating it.
-@end defspec
-
-@cindex @samp{'} for quoting
-@cindex quoting using apostrophe
-@cindex apostrophe for quoting
-Because @code{quote} is used so often in programs, Lisp provides a
-convenient read syntax for it. An apostrophe character (@samp{'})
-followed by a Lisp object (in read syntax) expands to a list whose first
-element is @code{quote}, and whose second element is the object. Thus,
-the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
-
-Here are some examples of expressions that use @code{quote}:
-
-@example
-@group
-(quote (+ 1 2))
- @result{} (+ 1 2)
-@end group
-@group
-(quote foo)
- @result{} foo
-@end group
-@group
-'foo
- @result{} foo
-@end group
-@group
-''foo
- @result{} (quote foo)
-@end group
-@group
-'(quote foo)
- @result{} (quote foo)
-@end group
-@group
-['foo]
- @result{} [(quote foo)]
-@end group
-@end example
-
- Other quoting constructs include @code{function} (@pxref{Anonymous
-Functions}), which causes an anonymous lambda expression written in Lisp
-to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
-only part of a list, while computing and substituting other parts.
-
-@node Eval
-@section Eval
-
- Most often, forms are evaluated automatically, by virtue of their
-occurrence in a program being run. On rare occasions, you may need to
-write code that evaluates a form that is computed at run time, such as
-after reading a form from text being edited or getting one from a
-property list. On these occasions, use the @code{eval} function.
-
- The functions and variables described in this section evaluate forms,
-specify limits to the evaluation process, or record recently returned
-values. Loading a file also does evaluation (@pxref{Loading}).
-
- It is generally cleaner and more flexible to store a function in a
-data structure, and call it with @code{funcall} or @code{apply}, than
-to store an expression in the data structure and evaluate it. Using
-functions provides the ability to pass information to them as
-arguments.
-
-@defun eval form
-This is the basic function evaluating an expression. It evaluates
-@var{form} in the current environment and returns the result. How the
-evaluation proceeds depends on the type of the object (@pxref{Forms}).
-
-Since @code{eval} is a function, the argument expression that appears
-in a call to @code{eval} is evaluated twice: once as preparation before
-@code{eval} is called, and again by the @code{eval} function itself.
-Here is an example:
-
-@example
-@group
-(setq foo 'bar)
- @result{} bar
-@end group
-@group
-(setq bar 'baz)
- @result{} baz
-;; @r{Here @code{eval} receives argument @code{foo}}
-(eval 'foo)
- @result{} bar
-;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
-(eval foo)
- @result{} baz
-@end group
-@end example
-
-The number of currently active calls to @code{eval} is limited to
-@code{max-lisp-eval-depth} (see below).
-@end defun
-
-@deffn Command eval-region start end &optional stream read-function
-@anchor{Definition of eval-region}
-This function evaluates the forms in the current buffer in the region
-defined by the positions @var{start} and @var{end}. It reads forms from
-the region and calls @code{eval} on them until the end of the region is
-reached, or until an error is signaled and not handled.
-
-By default, @code{eval-region} does not produce any output. However,
-if @var{stream} is non-@code{nil}, any output produced by output
-functions (@pxref{Output Functions}), as well as the values that
-result from evaluating the expressions in the region are printed using
-@var{stream}. @xref{Output Streams}.
-
-If @var{read-function} is non-@code{nil}, it should be a function,
-which is used instead of @code{read} to read expressions one by one.
-This function is called with one argument, the stream for reading
-input. You can also use the variable @code{load-read-function}
-(@pxref{Definition of load-read-function,, How Programs Do Loading})
-to specify this function, but it is more robust to use the
-@var{read-function} argument.
-
-@code{eval-region} does not move point. It always returns @code{nil}.
-@end deffn
-
-@cindex evaluation of buffer contents
-@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
-This is similar to @code{eval-region}, but the arguments provide
-different optional features. @code{eval-buffer} operates on the
-entire accessible portion of buffer @var{buffer-or-name}.
-@var{buffer-or-name} can be a buffer, a buffer name (a string), or
-@code{nil} (or omitted), which means to use the current buffer.
-@var{stream} is used as in @code{eval-region}, unless @var{stream} is
-@code{nil} and @var{print} non-@code{nil}. In that case, values that
-result from evaluating the expressions are still discarded, but the
-output of the output functions is printed in the echo area.
-@var{filename} is the file name to use for @code{load-history}
-(@pxref{Unloading}), and defaults to @code{buffer-file-name}
-(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
-@code{read} converts strings to unibyte whenever possible.
-
-@findex eval-current-buffer
-@code{eval-current-buffer} is an alias for this command.
-@end deffn
-
-@defvar max-lisp-eval-depth
-@anchor{Definition of max-lisp-eval-depth}
-This variable defines the maximum depth allowed in calls to @code{eval},
-@code{apply}, and @code{funcall} before an error is signaled (with error
-message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
-
-This limit, with the associated error when it is exceeded, is one way
-Emacs Lisp avoids infinite recursion on an ill-defined function. If
-you increase the value of @code{max-lisp-eval-depth} too much, such
-code can cause stack overflow instead.
-@cindex Lisp nesting error
-
-The depth limit counts internal uses of @code{eval}, @code{apply}, and
-@code{funcall}, such as for calling the functions mentioned in Lisp
-expressions, and recursive evaluation of function call arguments and
-function body forms, as well as explicit calls in Lisp code.
-
-The default value of this variable is 300. If you set it to a value
-less than 100, Lisp will reset it to 100 if the given value is reached.
-Entry to the Lisp debugger increases the value, if there is little room
-left, to make sure the debugger itself has room to execute.
-
-@code{max-specpdl-size} provides another limit on nesting.
-@xref{Definition of max-specpdl-size,, Local Variables}.
-@end defvar
-
-@defvar values
-The value of this variable is a list of the values returned by all the
-expressions that were read, evaluated, and printed from buffers
-(including the minibuffer) by the standard Emacs commands which do
-this. (Note that this does @emph{not} include evaluation in
-@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
-@code{lisp-interaction-mode}.) The elements are ordered most recent
-first.
-
-@example
-@group
-(setq x 1)
- @result{} 1
-@end group
-@group
-(list 'A (1+ 2) auto-save-default)
- @result{} (A 3 t)
-@end group
-@group
-values
- @result{} ((A 3 t) 1 @dots{})
-@end group
-@end example
-
-This variable is useful for referring back to values of forms recently
-evaluated. It is generally a bad idea to print the value of
-@code{values} itself, since this may be very long. Instead, examine
-particular elements, like this:
-
-@example
-@group
-;; @r{Refer to the most recent evaluation result.}
-(nth 0 values)
- @result{} (A 3 t)
-@end group
-@group
-;; @r{That put a new element on,}
-;; @r{so all elements move back one.}
-(nth 1 values)
- @result{} (A 3 t)
-@end group
-@group
-;; @r{This gets the element that was next-to-most-recent}
-;; @r{before this example.}
-(nth 3 values)
- @result{} 1
-@end group
-@end example
-@end defvar
-
-@ignore
- arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/files
-@node Files, Backups and Auto-Saving, Documentation, Top
-@comment node-name, next, previous, up
-@chapter Files
-
- In Emacs, you can find, create, view, save, and otherwise work with
-files and file directories. This chapter describes most of the
-file-related functions of Emacs Lisp, but a few others are described in
-@ref{Buffers}, and those related to backups and auto-saving are
-described in @ref{Backups and Auto-Saving}.
-
- Many of the file functions take one or more arguments that are file
-names. A file name is actually a string. Most of these functions
-expand file name arguments by calling @code{expand-file-name}, so that
-@file{~} is handled correctly, as are relative file names (including
-@samp{../}). These functions don't recognize environment variable
-substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
-
- When file I/O functions signal Lisp errors, they usually use the
-condition @code{file-error} (@pxref{Handling Errors}). The error
-message is in most cases obtained from the operating system, according
-to locale @code{system-message-locale}, and decoded using coding system
-@code{locale-coding-system} (@pxref{Locales}).
-
-@menu
-* Visiting Files:: Reading files into Emacs buffers for editing.
-* Saving Buffers:: Writing changed buffers back into files.
-* Reading from Files:: Reading files into buffers without visiting.
-* 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.
-@end menu
-
-@node Visiting Files
-@section Visiting Files
-@cindex finding files
-@cindex visiting files
-
- Visiting a file means reading a file into a buffer. Once this is
-done, we say that the buffer is @dfn{visiting} that file, and call the
-file ``the visited file'' of the buffer.
-
- A file and a buffer are two different things. A file is information
-recorded permanently in the computer (unless you delete it). A buffer,
-on the other hand, is information inside of Emacs that will vanish at
-the end of the editing session (or when you kill the buffer). Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file. The copy in the buffer is what
-you modify with editing commands. Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
-@dfn{save} the buffer, which means copying the altered buffer contents
-back into the file.
-
- In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.'' Humans do not usually need
-to make the distinction explicit. When dealing with a computer program,
-however, it is good to keep the distinction in mind.
-
-@menu
-* Visiting Functions:: The usual interface functions for visiting.
-* Subroutines of Visiting:: Lower-level subroutines that they use.
-@end menu
-
-@node Visiting Functions
-@subsection Functions for Visiting Files
-
- This section describes the functions normally used to visit files.
-For historical reasons, these functions have names starting with
-@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
-functions and variables that access the visited file name of a buffer or
-that find an existing buffer by its visited file name.
-
- In a Lisp program, if you want to look at the contents of a file but
-not alter it, the fastest way is to use @code{insert-file-contents} in a
-temporary buffer. Visiting the file is not necessary and takes longer.
-@xref{Reading from Files}.
-
-@deffn Command find-file filename &optional wildcards
-This command selects a buffer visiting the file @var{filename},
-using an existing buffer if there is one, and otherwise creating a
-new buffer and reading the file into it. It also returns that buffer.
-
-Aside from some technical details, the body of the @code{find-file}
-function is basically equivalent to:
-
-@smallexample
-(switch-to-buffer (find-file-noselect filename nil nil wildcards))
-@end smallexample
-
-@noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
-
-If @var{wildcards} is non-@code{nil}, which is always true in an
-interactive call, then @code{find-file} expands wildcard characters in
-@var{filename} and visits all the matching files.
-
-When @code{find-file} is called interactively, it prompts for
-@var{filename} in the minibuffer.
-@end deffn
-
-@defun find-file-noselect filename &optional nowarn rawfile wildcards
-This function is the guts of all the file-visiting functions. It
-returns a buffer visiting the file @var{filename}. You may make the
-buffer current or display it in a window if you wish, but this
-function does not do so.
-
-The function returns an existing buffer if there is one; otherwise it
-creates a new buffer and reads the file into it. When
-@code{find-file-noselect} uses an existing buffer, it first verifies
-that the file has not changed since it was last visited or saved in
-that buffer. If the file has changed, this function asks the user
-whether to reread the changed file. If the user says @samp{yes}, any
-edits previously made in the buffer are lost.
-
-Reading the file involves decoding the file's contents (@pxref{Coding
-Systems}), including end-of-line conversion, and format conversion
-(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
-then @code{find-file-noselect} expands wildcard characters in
-@var{filename} and visits all the matching files.
-
-This function displays warning or advisory messages in various peculiar
-cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
-example, if it needs to create a buffer, and there is no file named
-@var{filename}, it displays the message @samp{(New file)} in the echo
-area, and leaves the buffer empty.
-
-The @code{find-file-noselect} function normally calls
-@code{after-find-file} after reading the file (@pxref{Subroutines of
-Visiting}). That function sets the buffer major mode, parses local
-variables, warns the user if there exists an auto-save file more recent
-than the file just visited, and finishes by running the functions in
-@code{find-file-hook}.
-
-If the optional argument @var{rawfile} is non-@code{nil}, then
-@code{after-find-file} is not called, and the
-@code{find-file-not-found-functions} are not run in case of failure.
-What's more, a non-@code{nil} @var{rawfile} value suppresses coding
-system conversion and format conversion.
-
-The @code{find-file-noselect} function usually returns the buffer that
-is visiting the file @var{filename}. But, if wildcards are actually
-used and expanded, it returns a list of buffers that are visiting the
-various files.
-
-@example
-@group
-(find-file-noselect "/etc/fstab")
- @result{} #<buffer fstab>
-@end group
-@end example
-@end defun
-
-@deffn Command find-file-other-window filename &optional wildcards
-This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window. It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
-
-When this command is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@deffn Command find-file-read-only filename &optional wildcards
-This command selects a buffer visiting the file @var{filename}, like
-@code{find-file}, but it marks the buffer as read-only. @xref{Read Only
-Buffers}, for related functions and variables.
-
-When this command is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@deffn Command view-file filename
-This command visits @var{filename} using View mode, returning to the
-previous buffer when you exit View mode. View mode is a minor mode that
-provides commands to skim rapidly through the file, but does not let you
-modify the text. Entering View mode runs the normal hook
-@code{view-mode-hook}. @xref{Hooks}.
-
-When @code{view-file} is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@defopt find-file-wildcards
-If this variable is non-@code{nil}, then the various @code{find-file}
-commands check for wildcard characters and visit all the files that
-match them (when invoked interactively or when their @var{wildcards}
-argument is non-@code{nil}). If this option is @code{nil}, then
-the @code{find-file} commands ignore their @var{wildcards} argument
-and never treat wildcard characters specially.
-@end defopt
-
-@defvar find-file-hook
-The value of this variable is a list of functions to be called after a
-file is visited. The file's local-variables specification (if any) will
-have been processed before the hooks are run. The buffer visiting the
-file is current when the hook functions are run.
-
-This variable is a normal hook. @xref{Hooks}.
-@end defvar
-
-@defvar find-file-not-found-functions
-The value of this variable is a list of functions to be called when
-@code{find-file} or @code{find-file-noselect} is passed a nonexistent
-file name. @code{find-file-noselect} calls these functions as soon as
-it detects a nonexistent file. It calls them in the order of the list,
-until one of them returns non-@code{nil}. @code{buffer-file-name} is
-already set up.
-
-This is not a normal hook because the values of the functions are
-used, and in many cases only some of the functions are called.
-@end defvar
-
-@node Subroutines of Visiting
-@comment node-name, next, previous, up
-@subsection Subroutines of Visiting
-
- The @code{find-file-noselect} function uses two important subroutines
-which are sometimes useful in user Lisp code: @code{create-file-buffer}
-and @code{after-find-file}. This section explains how to use them.
-
-@defun create-file-buffer filename
-This function creates a suitably named buffer for visiting
-@var{filename}, and returns it. It uses @var{filename} (sans directory)
-as the name if that name is free; otherwise, it appends a string such as
-@samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
-
-@strong{Please note:} @code{create-file-buffer} does @emph{not}
-associate the new buffer with a file and does not select the buffer.
-It also does not use the default major mode.
-
-@example
-@group
-(create-file-buffer "foo")
- @result{} #<buffer foo>
-@end group
-@group
-(create-file-buffer "foo")
- @result{} #<buffer foo<2>>
-@end group
-@group
-(create-file-buffer "foo")
- @result{} #<buffer foo<3>>
-@end group
-@end example
-
-This function is used by @code{find-file-noselect}.
-It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
-@end defun
-
-@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
-This function sets the buffer major mode, and parses local variables
-(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
-and by the default revert function (@pxref{Reverting}).
-
-@cindex new file message
-@cindex file open error
-If reading the file got an error because the file does not exist, but
-its directory does exist, the caller should pass a non-@code{nil} value
-for @var{error}. In that case, @code{after-find-file} issues a warning:
-@samp{(New file)}. For more serious errors, the caller should usually not
-call @code{after-find-file}.
-
-If @var{warn} is non-@code{nil}, then this function issues a warning
-if an auto-save file exists and is more recent than the visited file.
-
-If @var{noauto} is non-@code{nil}, that says not to enable or disable
-Auto-Save mode. The mode remains enabled if it was enabled before.
-
-If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
-means this call was from @code{revert-buffer}. This has no direct
-effect, but some mode functions and hook functions check the value
-of this variable.
-
-If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
-major mode, don't process local variables specifications in the file,
-and don't run @code{find-file-hook}. This feature is used by
-@code{revert-buffer} in some cases.
-
-The last thing @code{after-find-file} does is call all the functions
-in the list @code{find-file-hook}.
-@end defun
-
-@node Saving Buffers
-@section Saving Buffers
-@cindex saving buffers
-
- When you edit a file in Emacs, you are actually working on a buffer
-that is visiting that file---that is, the contents of the file are
-copied into the buffer and the copy is what you edit. Changes to the
-buffer do not change the file until you @dfn{save} the buffer, which
-means copying the contents of the buffer into the file.
-
-@deffn Command save-buffer &optional backup-option
-This function saves the contents of the current buffer in its visited
-file if the buffer has been modified since it was last visited or saved.
-Otherwise it does nothing.
-
-@code{save-buffer} is responsible for making backup files. Normally,
-@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
-file only if this is the first save since visiting the file. Other
-values for @var{backup-option} request the making of backup files in
-other circumstances:
-
-@itemize @bullet
-@item
-With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
-@code{save-buffer} function marks this version of the file to be
-backed up when the buffer is next saved.
-
-@item
-With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
-@code{save-buffer} function unconditionally backs up the previous
-version of the file before saving it.
-
-@item
-With an argument of 0, unconditionally do @emph{not} make any backup file.
-@end itemize
-@end deffn
-
-@deffn Command save-some-buffers &optional save-silently-p pred
-@anchor{Definition of save-some-buffers}
-This command saves some modified file-visiting buffers. Normally it
-asks the user about each buffer. But if @var{save-silently-p} is
-non-@code{nil}, it saves all the file-visiting buffers without querying
-the user.
-
-The optional @var{pred} argument controls which buffers to ask about
-(or to save silently if @var{save-silently-p} is non-@code{nil}).
-If it is @code{nil}, that means to ask only about file-visiting buffers.
-If it is @code{t}, that means also offer to save certain other non-file
-buffers---those that have a non-@code{nil} buffer-local value of
-@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
-@samp{yes} to saving a non-file buffer is asked to specify the file
-name to use. The @code{save-buffers-kill-emacs} function passes the
-value @code{t} for @var{pred}.
-
-If @var{pred} is neither @code{t} nor @code{nil}, then it should be
-a function of no arguments. It will be called in each buffer to decide
-whether to offer to save that buffer. If it returns a non-@code{nil}
-value in a certain buffer, that means do offer to save that buffer.
-@end deffn
-
-@deffn Command write-file filename &optional confirm
-@anchor{Definition of write-file}
-This function writes the current buffer into file @var{filename}, makes
-the buffer visit that file, and marks it not modified. Then it renames
-the buffer based on @var{filename}, appending a string like @samp{<2>}
-if necessary to make a unique buffer name. It does most of this work by
-calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
-@code{save-buffer}.
-
-If @var{confirm} is non-@code{nil}, that means to ask for confirmation
-before overwriting an existing file. Interactively, confirmation is
-required, unless the user supplies a prefix argument.
-
-If @var{filename} is an existing directory, or a symbolic link to one,
-@code{write-file} uses the name of the visited file, in directory
-@var{filename}. If the buffer is not visiting a file, it uses the
-buffer name instead.
-@end deffn
-
- Saving a buffer runs several hooks. It also performs format
-conversion (@pxref{Format Conversion}).
-
-@defvar write-file-functions
-The value of this variable is a list of functions to be called before
-writing out a buffer to its visited file. If one of them returns
-non-@code{nil}, the file is considered already written and the rest of
-the functions are not called, nor is the usual code for writing the file
-executed.
-
-If a function in @code{write-file-functions} returns non-@code{nil}, it
-is responsible for making a backup file (if that is appropriate).
-To do so, execute the following code:
-
-@example
-(or buffer-backed-up (backup-buffer))
-@end example
-
-You might wish to save the file modes value returned by
-@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
-bits of the file that you write. This is what @code{save-buffer}
-normally does. @xref{Making Backups,, Making Backup Files}.
-
-The hook functions in @code{write-file-functions} are also responsible
-for encoding the data (if desired): they must choose a suitable coding
-system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
-perform the encoding (@pxref{Explicit Encoding}), and set
-@code{last-coding-system-used} to the coding system that was used
-(@pxref{Encoding and I/O}).
-
-If you set this hook locally in a buffer, it is assumed to be
-associated with the file or the way the contents of the buffer were
-obtained. Thus the variable is marked as a permanent local, so that
-changing the major mode does not alter a buffer-local value. On the
-other hand, calling @code{set-visited-file-name} will reset it.
-If this is not what you want, you might like to use
-@code{write-contents-functions} instead.
-
-Even though this is not a normal hook, you can use @code{add-hook} and
-@code{remove-hook} to manipulate the list. @xref{Hooks}.
-@end defvar
-
-@c Emacs 19 feature
-@defvar write-contents-functions
-This works just like @code{write-file-functions}, but it is intended
-for hooks that pertain to the buffer's contents, not to the particular
-visited file or its location. Such hooks are usually set up by major
-modes, as buffer-local bindings for this variable. This variable
-automatically becomes buffer-local whenever it is set; switching to a
-new major mode always resets this variable, but calling
-@code{set-visited-file-name} does not.
-
-If any of the functions in this hook returns non-@code{nil}, the file
-is considered already written and the rest are not called and neither
-are the functions in @code{write-file-functions}.
-@end defvar
-
-@defopt before-save-hook
-This normal hook runs before a buffer is saved in its visited file,
-regardless of whether that is done normally or by one of the hooks
-described above. For instance, the @file{copyright.el} program uses
-this hook to make sure the file you are saving has the current year in
-its copyright notice.
-@end defopt
-
-@c Emacs 19 feature
-@defopt after-save-hook
-This normal hook runs after a buffer has been saved in its visited file.
-One use of this hook is in Fast Lock mode; it uses this hook to save the
-highlighting information in a cache file.
-@end defopt
-
-@defopt file-precious-flag
-If this variable is non-@code{nil}, then @code{save-buffer} protects
-against I/O errors while saving by writing the new file to a temporary
-name instead of the name it is supposed to have, and then renaming it to
-the intended name after it is clear there are no errors. This procedure
-prevents problems such as a lack of disk space from resulting in an
-invalid file.
-
-As a side effect, backups are necessarily made by copying. @xref{Rename
-or Copy}. Yet, at the same time, saving a precious file always breaks
-all hard links between the file you save and other file names.
-
-Some modes give this variable a non-@code{nil} buffer-local value
-in particular buffers.
-@end defopt
-
-@defopt require-final-newline
-This variable determines whether files may be written out that do
-@emph{not} end with a newline. If the value of the variable is
-@code{t}, then @code{save-buffer} silently adds a newline at the end of
-the file whenever the buffer being saved does not already end in one.
-If the value of the variable is non-@code{nil}, but not @code{t}, then
-@code{save-buffer} asks the user whether to add a newline each time the
-case arises.
-
-If the value of the variable is @code{nil}, then @code{save-buffer}
-doesn't add newlines at all. @code{nil} is the default value, but a few
-major modes set it to @code{t} in particular buffers.
-@end defopt
-
- See also the function @code{set-visited-file-name} (@pxref{Buffer File
-Name}).
-
-@node Reading from Files
-@comment node-name, next, previous, up
-@section Reading from Files
-@cindex reading from files
-
- You can copy a file from the disk and insert it into a buffer
-using the @code{insert-file-contents} function. Don't use the user-level
-command @code{insert-file} in a Lisp program, as that sets the mark.
-
-@defun insert-file-contents filename &optional visit beg end replace
-This function inserts the contents of file @var{filename} into the
-current buffer after point. It returns a list of the absolute file name
-and the length of the data inserted. An error is signaled if
-@var{filename} is not the name of a file that can be read.
-
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate and also calls the functions in
-the list @code{after-insert-file-functions}. @xref{Format Conversion}.
-Normally, one of the functions in the
-@code{after-insert-file-functions} list determines the coding system
-(@pxref{Coding Systems}) used for decoding the file's contents,
-including end-of-line conversion.
-
-If @var{visit} is non-@code{nil}, this function additionally marks the
-buffer as unmodified and sets up various fields in the buffer so that it
-is visiting the file @var{filename}: these include the buffer's visited
-file name and its last save file modtime. This feature is used by
-@code{find-file-noselect} and you probably should not use it yourself.
-
-If @var{beg} and @var{end} are non-@code{nil}, they should be integers
-specifying the portion of the file to insert. In this case, @var{visit}
-must be @code{nil}. For example,
-
-@example
-(insert-file-contents filename nil 0 500)
-@end example
-
-@noindent
-inserts the first 500 characters of a file.
-
-If the argument @var{replace} is non-@code{nil}, it means to replace the
-contents of the buffer (actually, just the accessible portion) with the
-contents of the file. This is better than simply deleting the buffer
-contents and inserting the whole file, because (1) it preserves some
-marker positions and (2) it puts less data in the undo list.
-
-It is possible to read a special file (such as a FIFO or an I/O device)
-with @code{insert-file-contents}, as long as @var{replace} and
-@var{visit} are @code{nil}.
-@end defun
-
-@defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it does
-not do format decoding (@pxref{Format Conversion}), does not do
-character code conversion (@pxref{Coding Systems}), does not run
-@code{find-file-hook}, does not perform automatic uncompression, and so
-on.
-@end defun
-
-If you want to pass a file name to another process so that another
-program can read the file, use the function @code{file-local-copy}; see
-@ref{Magic File Names}.
-
-@node Writing to Files
-@comment node-name, next, previous, up
-@section Writing to Files
-@cindex writing to files
-
- You can write the contents of a buffer, or part of a buffer, directly
-to a file on disk using the @code{append-to-file} and
-@code{write-region} functions. Don't use these functions to write to
-files that are being visited; that could cause confusion in the
-mechanisms for visiting.
-
-@deffn Command append-to-file start end filename
-This function appends the contents of the region delimited by
-@var{start} and @var{end} in the current buffer to the end of file
-@var{filename}. If that file does not exist, it is created. This
-function returns @code{nil}.
-
-An error is signaled if @var{filename} specifies a nonwritable file,
-or a nonexistent file in a directory where files cannot be created.
-
-When called from Lisp, this function is completely equivalent to:
-
-@example
-(write-region start end filename t)
-@end example
-@end deffn
-
-@deffn Command write-region start end filename &optional append visit lockname mustbenew
-This function writes the region delimited by @var{start} and @var{end}
-in the current buffer into the file specified by @var{filename}.
-
-If @var{start} is @code{nil}, then the command writes the entire buffer
-contents (@emph{not} just the accessible portion) to the file and
-ignores @var{end}.
-
-@c Emacs 19 feature
-If @var{start} is a string, then @code{write-region} writes or appends
-that string, rather than text from the buffer. @var{end} is ignored in
-this case.
-
-If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any). If @var{append} is an
-integer, @code{write-region} seeks to that byte offset from the start
-of the file and writes the data from there.
-
-If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
-for confirmation if @var{filename} names an existing file. If
-@var{mustbenew} is the symbol @code{excl}, then @code{write-region}
-does not ask for confirmation, but instead it signals an error
-@code{file-already-exists} if the file already exists.
-
-The test for an existing file, when @var{mustbenew} is @code{excl}, uses
-a special system feature. At least for files on a local disk, there is
-no chance that some other program could create a file of the same name
-before Emacs does, without Emacs's noticing.
-
-If @var{visit} is @code{t}, then Emacs establishes an association
-between the buffer and the file: the buffer is then visiting that file.
-It also sets the last file modification time for the current buffer to
-@var{filename}'s modtime, and marks the buffer as not modified. This
-feature is used by @code{save-buffer}, but you probably should not use
-it yourself.
-
-@c Emacs 19 feature
-If @var{visit} is a string, it specifies the file name to visit. This
-way, you can write the data to one file (@var{filename}) while recording
-the buffer as visiting another file (@var{visit}). The argument
-@var{visit} is used in the echo area message and also for file locking;
-@var{visit} is stored in @code{buffer-file-name}. This feature is used
-to implement @code{file-precious-flag}; don't use it yourself unless you
-really know what you're doing.
-
-The optional argument @var{lockname}, if non-@code{nil}, specifies the
-file name to use for purposes of locking and unlocking, overriding
-@var{filename} and @var{visit} for that purpose.
-
-The function @code{write-region} converts the data which it writes to
-the appropriate file formats specified by @code{buffer-file-format}
-and also calls the functions in the list
-@code{write-region-annotate-functions}.
-@xref{Format Conversion}.
-
-Normally, @code{write-region} displays the message @samp{Wrote
-@var{filename}} in the echo area. If @var{visit} is neither @code{t}
-nor @code{nil} nor a string, then this message is inhibited. This
-feature is useful for programs that use files for internal purposes,
-files that the user does not need to know about.
-@end deffn
-
-@defmac with-temp-file file body@dots{}
-@anchor{Definition of with-temp-file}
-The @code{with-temp-file} macro evaluates the @var{body} forms with a
-temporary buffer as the current buffer; then, at the end, it writes the
-buffer contents into file @var{file}. It kills the temporary buffer
-when finished, restoring the buffer that was current before the
-@code{with-temp-file} form. Then it returns the value of the last form
-in @var{body}.
-
-The current buffer is restored even in case of an abnormal exit via
-@code{throw} or error (@pxref{Nonlocal Exits}).
-
-See also @code{with-temp-buffer} in @ref{Definition of
-with-temp-buffer,, The Current Buffer}.
-@end defmac
-
-@node File Locks
-@section File Locks
-@cindex file locks
-@cindex lock file
-
- When two users edit the same file at the same time, they are likely
-to interfere with each other. Emacs tries to prevent this situation
-from arising by recording a @dfn{file lock} when a file is being
-modified. (File locks are not implemented on Microsoft systems.)
-Emacs can then detect the first attempt to modify a buffer visiting a
-file that is locked by another Emacs job, and ask the user what to do.
-The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.
-
- When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously.''
-If this happens, it is possible for the two users to make changes
-simultaneously, but Emacs will still warn the user who saves second.
-Also, the detection of modification of a buffer visiting a file changed
-on disk catches some cases of simultaneous editing; see
-@ref{Modification Time}.
-
-@defun file-locked-p filename
-This function returns @code{nil} if the file @var{filename} is not
-locked. It returns @code{t} if it is locked by this Emacs process, and
-it returns the name of the user who has locked it if it is locked by
-some other job.
-
-@example
-@group
-(file-locked-p "foo")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun lock-buffer &optional filename
-This function locks the file @var{filename}, if the current buffer is
-modified. The argument @var{filename} defaults to the current buffer's
-visited file. Nothing is done if the current buffer is not visiting a
-file, or is not modified, or if the system does not support locking.
-@end defun
-
-@defun unlock-buffer
-This function unlocks the file being visited in the current buffer,
-if the buffer is modified. If the buffer is not modified, then
-the file should not be locked, so this function does nothing. It also
-does nothing if the current buffer is not visiting a file, or if the
-system does not support locking.
-@end defun
-
- File locking is not supported on some systems. On systems that do not
-support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
-@code{file-locked-p} do nothing and return @code{nil}.
-
-@defun ask-user-about-lock file other-user
-This function is called when the user tries to modify @var{file}, but it
-is locked by another user named @var{other-user}. The default
-definition of this function asks the user to say what to do. The value
-this function returns determines what Emacs does next:
-
-@itemize @bullet
-@item
-A value of @code{t} says to grab the lock on the file. Then
-this user may edit the file and @var{other-user} loses the lock.
-
-@item
-A value of @code{nil} says to ignore the lock and let this
-user edit the file anyway.
-
-@item
-@kindex file-locked
-This function may instead signal a @code{file-locked} error, in which
-case the change that the user was about to make does not take place.
-
-The error message for this error looks like this:
-
-@example
-@error{} File is locked: @var{file} @var{other-user}
-@end example
-
-@noindent
-where @code{file} is the name of the file and @var{other-user} is the
-name of the user who has locked the file.
-@end itemize
-
-If you wish, you can replace the @code{ask-user-about-lock} function
-with your own version that makes the decision in another way. The code
-for its usual definition is in @file{userlock.el}.
-@end defun
-
-@node Information about Files
-@section Information about Files
-@cindex file, information about
-
- The functions described in this section all operate on strings that
-designate file names. With a few exceptions, all the functions have
-names that begin with the word @samp{file}. These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
-
-@menu
-* 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.
-@end menu
-
-@node Testing Accessibility
-@comment node-name, next, previous, up
-@subsection Testing Accessibility
-@cindex accessibility of a file
-@cindex file accessibility
-
- These functions test for permission to access a file in specific
-ways. Unless explicitly stated otherwise, they recursively follow
-symbolic links for their file name arguments, at all levels (at the
-level of the file itself and at all levels of parent directories).
-
-@defun file-exists-p filename
-This function returns @code{t} if a file named @var{filename} appears
-to exist. This does not mean you can necessarily read the file, only
-that you can find out its attributes. (On Unix and GNU/Linux, this is
-true if the file exists and you have execute permission on the
-containing directories, regardless of the protection of the file
-itself.)
-
-If the file does not exist, or if fascist access control policies
-prevent you from finding the attributes of the file, this function
-returns @code{nil}.
-
-Directories are files, so @code{file-exists-p} returns @code{t} when
-given a directory name. However, symbolic links are treated
-specially; @code{file-exists-p} returns @code{t} for a symbolic link
-name only if the target file exists.
-@end defun
-
-@defun file-readable-p filename
-This function returns @code{t} if a file named @var{filename} exists
-and you can read it. It returns @code{nil} otherwise.
-
-@example
-@group
-(file-readable-p "files.texi")
- @result{} t
-@end group
-@group
-(file-exists-p "/usr/spool/mqueue")
- @result{} t
-@end group
-@group
-(file-readable-p "/usr/spool/mqueue")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@c Emacs 19 feature
-@defun file-executable-p filename
-This function returns @code{t} if a file named @var{filename} exists and
-you can execute it. It returns @code{nil} otherwise. On Unix and
-GNU/Linux, if the file is a directory, execute permission means you can
-check the existence and attributes of files inside the directory, and
-open those files if their modes permit.
-@end defun
-
-@defun file-writable-p filename
-This function returns @code{t} if the file @var{filename} can be written
-or created by you, and @code{nil} otherwise. A file is writable if the
-file exists and you can write it. It is creatable if it does not exist,
-but the specified directory does exist and you can write in that
-directory.
-
-In the third example below, @file{foo} is not writable because the
-parent directory does not exist, even though the user could create such
-a directory.
-
-@example
-@group
-(file-writable-p "~/foo")
- @result{} t
-@end group
-@group
-(file-writable-p "/foo")
- @result{} nil
-@end group
-@group
-(file-writable-p "~/no-such-dir/foo")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@c Emacs 19 feature
-@defun file-accessible-directory-p dirname
-This function returns @code{t} if you have permission to open existing
-files in the directory whose name as a file is @var{dirname};
-otherwise (or if there is no such directory), it returns @code{nil}.
-The value of @var{dirname} may be either a directory name (such as
-@file{/foo/}) or the file name of a file which is a directory
-(such as @file{/foo}, without the final slash).
-
-Example: after the following,
-
-@example
-(file-accessible-directory-p "/foo")
- @result{} nil
-@end example
-
-@noindent
-we can deduce that any attempt to read a file in @file{/foo/} will
-give an error.
-@end defun
-
-@defun access-file filename string
-This function opens file @var{filename} for reading, then closes it and
-returns @code{nil}. However, if the open fails, it signals an error
-using @var{string} as the error message text.
-@end defun
-
-@defun file-ownership-preserved-p filename
-This function returns @code{t} if deleting the file @var{filename} and
-then creating it anew would keep the file's owner unchanged. It also
-returns @code{t} for nonexistent files.
-
-If @var{filename} is a symbolic link, then, unlike the other functions
-discussed here, @code{file-ownership-preserved-p} does @emph{not}
-replace @var{filename} with its target. However, it does recursively
-follow symbolic links at all levels of parent directories.
-@end defun
-
-@defun file-newer-than-file-p filename1 filename2
-@cindex file age
-@cindex file modification time
-This function returns @code{t} if the file @var{filename1} is
-newer than file @var{filename2}. If @var{filename1} does not
-exist, it returns @code{nil}. If @var{filename1} does exist, but
-@var{filename2} does not, it returns @code{t}.
-
-In the following example, assume that the file @file{aug-19} was written
-on the 19th, @file{aug-20} was written on the 20th, and the file
-@file{no-file} doesn't exist at all.
-
-@example
-@group
-(file-newer-than-file-p "aug-19" "aug-20")
- @result{} nil
-@end group
-@group
-(file-newer-than-file-p "aug-20" "aug-19")
- @result{} t
-@end group
-@group
-(file-newer-than-file-p "aug-19" "no-file")
- @result{} t
-@end group
-@group
-(file-newer-than-file-p "no-file" "aug-19")
- @result{} nil
-@end group
-@end example
-
-You can use @code{file-attributes} to get a file's last modification
-time as a list of two numbers. @xref{File Attributes}.
-@end defun
-
-@node Kinds of Files
-@comment node-name, next, previous, up
-@subsection Distinguishing Kinds of Files
-
- This section describes how to distinguish various kinds of files, such
-as directories, symbolic links, and ordinary files.
-
-@defun file-symlink-p filename
-@cindex file symbolic links
-If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} function returns the (non-recursive) link target
-as a string. (Determining the file name that the link points to from
-the target is nontrivial.) First, this function recursively follows
-symbolic links at all levels of parent directories.
-
-If the file @var{filename} is not a symbolic link (or there is no such file),
-@code{file-symlink-p} returns @code{nil}.
-
-@example
-@group
-(file-symlink-p "foo")
- @result{} nil
-@end group
-@group
-(file-symlink-p "sym-link")
- @result{} "foo"
-@end group
-@group
-(file-symlink-p "sym-link2")
- @result{} "sym-link"
-@end group
-@group
-(file-symlink-p "/bin")
- @result{} "/pub/bin"
-@end group
-@end example
-
-@c !!! file-symlink-p: should show output of ls -l for comparison
-@end defun
-
-The next two functions recursively follow symbolic links at
-all levels for @var{filename}.
-
-@defun file-directory-p filename
-This function returns @code{t} if @var{filename} is the name of an
-existing directory, @code{nil} otherwise.
-
-@example
-@group
-(file-directory-p "~rms")
- @result{} t
-@end group
-@group
-(file-directory-p "~rms/lewis/files.texi")
- @result{} nil
-@end group
-@group
-(file-directory-p "~rms/lewis/no-such-file")
- @result{} nil
-@end group
-@group
-(file-directory-p "$HOME")
- @result{} nil
-@end group
-@group
-(file-directory-p
- (substitute-in-file-name "$HOME"))
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun file-regular-p filename
-This function returns @code{t} if the file @var{filename} exists and is
-a regular file (not a directory, named pipe, terminal, or
-other I/O device).
-@end defun
-
-@node Truenames
-@subsection Truenames
-@cindex truename (of file)
-
-@c Emacs 19 features
- The @dfn{truename} of a file is the name that you get by following
-symbolic links at all levels until none remain, then simplifying away
-@samp{.}@: and @samp{..}@: appearing as name components. This results
-in a sort of canonical name for the file. A file does not always have a
-unique truename; the number of distinct truenames a file has is equal to
-the number of hard links to the file. However, truenames are useful
-because they eliminate symbolic links as a cause of name variation.
-
-@defun file-truename filename
-The function @code{file-truename} returns the truename of the file
-@var{filename}. The argument must be an absolute file name.
-
-This function does not expand environment variables. Only
-@code{substitute-in-file-name} does that. @xref{Definition of
-substitute-in-file-name}.
-
-If you may need to follow symbolic links preceding @samp{..}@:
-appearing as a name component, you should make sure to call
-@code{file-truename} without prior direct or indirect calls to
-@code{expand-file-name}, as otherwise the file name component
-immediately preceding @samp{..} will be ``simplified away'' before
-@code{file-truename} is called. To eliminate the need for a call to
-@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
-same way that @code{expand-file-name} does. @xref{File Name
-Expansion,, Functions that Expand Filenames}.
-@end defun
-
-@defun file-chase-links filename &optional limit
-This function follows symbolic links, starting with @var{filename},
-until it finds a file name which is not the name of a symbolic link.
-Then it returns that file name. This function does @emph{not} follow
-symbolic links at the level of parent directories.
-
-If you specify a number for @var{limit}, then after chasing through
-that many links, the function just returns what it has even if that is
-still a symbolic link.
-@end defun
-
- To illustrate the difference between @code{file-chase-links} and
-@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
-the directory @file{/home/foo}, and @file{/home/foo/hello} is an
-ordinary file (or at least, not a symbolic link) or nonexistent. Then
-we would have:
-
-@example
-(file-chase-links "/usr/foo/hello")
- ;; @r{This does not follow the links in the parent directories.}
- @result{} "/usr/foo/hello"
-(file-truename "/usr/foo/hello")
- ;; @r{Assuming that @file{/home} is not a symbolic link.}
- @result{} "/home/foo/hello"
-@end example
-
- @xref{Buffer File Name}, for related information.
-
-@node File Attributes
-@comment node-name, next, previous, up
-@subsection Other Information about Files
-
- This section describes the functions for getting detailed information
-about a file, other than its contents. This information includes the
-mode bits that control access permission, the owner and group numbers,
-the number of names, the inode number, the size, and the times of access
-and modification.
-
-@defun file-modes filename
-@cindex permission
-@cindex file attributes
-This function returns the mode bits of @var{filename}, as an integer.
-The mode bits are also called the file permissions, and they specify
-access control in the usual Unix fashion. If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order bit
-is 1, then the file is writable by all users, etc.
-
-The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @acronym{SUID} bit
-is set for both others and group, and that the sticky bit is set.
-
-If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
-
-This function recursively follows symbolic links at all levels.
-
-@example
-@group
-(file-modes "~/junk/diffs")
- @result{} 492 ; @r{Decimal integer.}
-@end group
-@group
-(format "%o" 492)
- @result{} "754" ; @r{Convert to octal.}
-@end group
-
-@group
-(set-file-modes "~/junk/diffs" 438)
- @result{} nil
-@end group
-
-@group
-(format "%o" 438)
- @result{} "666" ; @r{Convert to octal.}
-@end group
-
-@group
-% ls -l diffs
- -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
-@end group
-@end example
-@end defun
-
-If the @var{filename} argument to the next two functions is a symbolic
-link, then these function do @emph{not} replace it with its target.
-However, they both recursively follow symbolic links at all levels of
-parent directories.
-
-@defun file-nlinks filename
-This functions returns the number of names (i.e., hard links) that
-file @var{filename} has. If the file does not exist, then this function
-returns @code{nil}. Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files they
-link to.
-
-@example
-@group
-% ls -l foo*
--rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
--rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
-@end group
-
-@group
-(file-nlinks "foo")
- @result{} 2
-@end group
-@group
-(file-nlinks "doesnt-exist")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun file-attributes filename &optional id-format
-@anchor{Definition of file-attributes}
-This function returns a list of attributes of file @var{filename}. If
-the specified file cannot be opened, it returns @code{nil}.
-The optional parameter @var{id-format} specifies the preferred format
-of attributes @acronym{UID} and @acronym{GID} (see below)---the
-valid values are @code{'string} and @code{'integer}. The latter is
-the default, but we plan to change that, so you should specify a
-non-@code{nil} value for @var{id-format} if you use the returned
-@acronym{UID} or @acronym{GID}.
-
-The elements of the list, in order, are:
-
-@enumerate 0
-@item
-@code{t} for a directory, a string for a symbolic link (the name
-linked to), or @code{nil} for a text file.
-
-@c Wordy so as to prevent an overfull hbox. --rjc 15mar92
-@item
-The number of names the file has. Alternate names, also known as hard
-links, can be created by using the @code{add-name-to-file} function
-(@pxref{Changing Files}).
-
-@item
-The file's @acronym{UID}, normally as a string. However, if it does
-not correspond to a named user, the value is an integer or a floating
-point number.
-
-@item
-The file's @acronym{GID}, likewise.
-
-@item
-The time of last access, as a list of two integers.
-The first integer has the high-order 16 bits of time,
-the second has the low 16 bits. (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.)
-
-@item
-The time of last modification as a list of two integers (as above).
-@cindex modification time of file
-
-@item
-The time of last status change as a list of two integers (as above).
-
-@item
-The size of the file in bytes. If the size is too large to fit in a
-Lisp integer, this is a floating point number.
-
-@item
-The file's modes, as a string of ten letters or dashes,
-as in @samp{ls -l}.
-
-@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
-
-@item
-The file's inode number. If possible, this is an integer. If the inode
-number is too large to be represented as an integer in Emacs Lisp, then
-the value has the form @code{(@var{high} . @var{low})}, where @var{low}
-holds the low 16 bits.
-
-@item
-The file system number of the file system that the file is in.
-Depending on the magnitude of the value, this can be either an integer
-or a cons cell, in the same manner as the inode number. This element
-and the file's inode number together give enough information to
-distinguish any two files on the system---no two files can have the same
-values for both of these numbers.
-@end enumerate
-
-For example, here are the file attributes for @file{files.texi}:
-
-@example
-@group
-(file-attributes "files.texi" 'string)
- @result{} (nil 1 "lh" "users"
- (8489 20284)
- (8489 20284)
- (8489 20285)
- 14906 "-rw-rw-rw-"
- nil 129500 -32252)
-@end group
-@end example
-
-@noindent
-and here is how the result is interpreted:
-
-@table @code
-@item nil
-is neither a directory nor a symbolic link.
-
-@item 1
-has only one name (the name @file{files.texi} in the current default
-directory).
-
-@item "lh"
-is owned by the user with name "lh".
-
-@item "users"
-is in the group with name "users".
-
-@item (8489 20284)
-was last accessed on Aug 19 00:09.
-
-@item (8489 20284)
-was last modified on Aug 19 00:09.
-
-@item (8489 20285)
-last had its inode changed on Aug 19 00:09.
-
-@item 14906
-is 14906 bytes long. (It may not contain 14906 characters, though,
-if some of the bytes belong to multibyte sequences.)
-
-@item "-rw-rw-rw-"
-has a mode of read and write access for the owner, group, and world.
-
-@item nil
-would retain the same @acronym{GID} if it were recreated.
-
-@item 129500
-has an inode number of 129500.
-@item -32252
-is on file system number -32252.
-@end table
-@end defun
-
-@node Locating Files
-@subsection How to Locate Files in Standard Places
-@cindex locate file in path
-@cindex find file in path
-
- This section explains how to search for a file in a list of
-directories (a @dfn{path}). One example is when you need to look for
-a program's executable file, e.g., to find out whether a given program
-is installed on the user's system. Another example is the search for
-Lisp libraries (@pxref{Library Search}). Such searches generally need
-to try various possible file name extensions, in addition to various
-possible directories. Emacs provides a function for such a
-generalized search for a file.
-
-@defun locate-file filename path &optional suffixes predicate
-This function searches for a file whose name is @var{filename} in a
-list of directories given by @var{path}, trying the suffixes in
-@var{suffixes}. If it finds such a file, it returns the full
-@dfn{absolute file name} of the file (@pxref{Relative File Names});
-otherwise it returns @code{nil}.
-
-The optional argument @var{suffixes} gives the list of file-name
-suffixes to append to @var{filename} when searching.
-@code{locate-file} tries each possible directory with each of these
-suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
-are no suffixes, and @var{filename} is used only as-is. Typical
-values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
-Creation, exec-suffixes}), @code{load-suffixes},
-@code{load-file-rep-suffixes} and the return value of the function
-@code{get-load-suffixes} (@pxref{Load Suffixes}).
-
-Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
-Creation, exec-path}) when looking for executable programs or
-@code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files. If @var{filename} is absolute, @var{path} has no effect,
-but the suffixes in @var{suffixes} are still tried.
-
-The optional argument @var{predicate}, if non-@code{nil}, specifies
-the predicate function to use for testing whether a candidate file is
-suitable. The predicate function is passed the candidate file name as
-its single argument. If @var{predicate} is @code{nil} or unspecified,
-@code{locate-file} uses @code{file-readable-p} as the default
-predicate. Useful non-default predicates include
-@code{file-executable-p}, @code{file-directory-p}, and other
-predicates described in @ref{Kinds of Files}.
-
-For compatibility, @var{predicate} can also be one of the symbols
-@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
-a list of one or more of these symbols.
-@end defun
-
-@defun executable-find program
-This function searches for the executable file of the named
-@var{program} and returns the full absolute name of the executable,
-including its file-name extensions, if any. It returns @code{nil} if
-the file is not found. The functions searches in all the directories
-in @code{exec-path} and tries all the file-name extensions in
-@code{exec-suffixes}.
-@end defun
-
-@node Changing Files
-@section Changing File Names and Attributes
-@c @cindex renaming files Duplicates rename-file
-@cindex copying files
-@cindex deleting files
-@cindex linking files
-@cindex setting modes of files
-
- The functions in this section rename, copy, delete, link, and set the
-modes of files.
-
- In the functions that have an argument @var{newname}, if a file by the
-name of @var{newname} already exists, the actions taken depend on the
-value of the argument @var{ok-if-already-exists}:
-
-@itemize @bullet
-@item
-Signal a @code{file-already-exists} error if
-@var{ok-if-already-exists} is @code{nil}.
-
-@item
-Request confirmation if @var{ok-if-already-exists} is a number.
-
-@item
-Replace the old file without confirmation if @var{ok-if-already-exists}
-is any other value.
-@end itemize
-
-The next four commands all recursively follow symbolic links at all
-levels of parent directories for their first argument, but, if that
-argument is itself a symbolic link, then only @code{copy-file}
-replaces it with its (recursive) target.
-
-@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
-@cindex file with multiple names
-@cindex file hard link
-This function gives the file named @var{oldname} the additional name
-@var{newname}. This means that @var{newname} becomes a new ``hard
-link'' to @var{oldname}.
-
-In the first part of the following example, we list two files,
-@file{foo} and @file{foo3}.
-
-@example
-@group
-% ls -li fo*
-81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-@end group
-@end example
-
-Now we create a hard link, by calling @code{add-name-to-file}, then list
-the files again. This shows two names for one file, @file{foo} and
-@file{foo2}.
-
-@example
-@group
-(add-name-to-file "foo" "foo2")
- @result{} nil
-@end group
-
-@group
-% ls -li fo*
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-@end group
-@end example
-
-Finally, we evaluate the following:
-
-@example
-(add-name-to-file "foo" "foo3" t)
-@end example
-
-@noindent
-and list the files again. Now there are three names
-for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
-contents of @file{foo3} are lost.
-
-@example
-@group
-(add-name-to-file "foo1" "foo3")
- @result{} nil
-@end group
-
-@group
-% ls -li fo*
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
-@end group
-@end example
-
-This function is meaningless on operating systems where multiple names
-for one file are not allowed. Some systems implement multiple names
-by copying the file instead.
-
-See also @code{file-nlinks} in @ref{File Attributes}.
-@end deffn
-
-@deffn Command rename-file filename newname &optional ok-if-already-exists
-This command renames the file @var{filename} as @var{newname}.
-
-If @var{filename} has additional names aside from @var{filename}, it
-continues to have those names. In fact, adding the name @var{newname}
-with @code{add-name-to-file} and then deleting @var{filename} has the
-same effect as renaming, aside from momentary intermediate states.
-@end deffn
-
-@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
-This command copies the file @var{oldname} to @var{newname}. An
-error is signaled if @var{oldname} does not exist. If @var{newname}
-names a directory, it copies @var{oldname} into that directory,
-preserving its final name component.
-
-If @var{time} is non-@code{nil}, then this function gives the new file
-the same last-modified time that the old one has. (This works on only
-some operating systems.) If setting the time gets an error,
-@code{copy-file} signals a @code{file-date-error} error. In an
-interactive call, a prefix argument specifies a non-@code{nil} value
-for @var{time}.
-
-This function copies the file modes, too.
-
-If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
-system decide the user and group ownership of the new file (this is
-usually set to the user running Emacs). If @var{preserve-uid-gid} is
-non-@code{nil}, we attempt to copy the user and group ownership of the
-file. This works only on some operating systems, and only if you have
-the correct permissions to do so.
-@end deffn
-
-@deffn Command make-symbolic-link filename newname &optional ok-if-exists
-@pindex ln
-@kindex file-already-exists
-This command makes a symbolic link to @var{filename}, named
-@var{newname}. This is like the shell command @samp{ln -s
-@var{filename} @var{newname}}.
-
-This function is not available on systems that don't support symbolic
-links.
-@end deffn
-
-@deffn Command delete-file filename
-@pindex rm
-This command deletes the file @var{filename}, like the shell command
-@samp{rm @var{filename}}. If the file has multiple names, it continues
-to exist under the other names.
-
-A suitable kind of @code{file-error} error is signaled if the file does
-not exist, or is not deletable. (On Unix and GNU/Linux, a file is
-deletable if its directory is writable.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
-
-See also @code{delete-directory} in @ref{Create/Delete Dirs}.
-@end deffn
-
-@defun define-logical-name varname string
-This function defines the logical name @var{varname} to have the value
-@var{string}. It is available only on VMS.
-@end defun
-
-@defun set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer). Only the low 12 bits of @var{mode} are used.
-This function recursively follows symbolic links at all levels for
-@var{filename}.
-@end defun
-
-@c Emacs 19 feature
-@defun set-default-file-modes mode
-@cindex umask
-This function sets the default file protection for new files created by
-Emacs and its subprocesses. Every file created with Emacs initially has
-this protection, or a subset of it (@code{write-region} will not give a
-file execute permission even if the default file protection allows
-execute permission). On Unix and GNU/Linux, the default protection is
-the bitwise complement of the ``umask'' value.
-
-The argument @var{mode} must be an integer. On most systems, only the
-low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
-for octal character codes to enter @var{mode}; for example,
-
-@example
-(set-default-file-modes ?\644)
-@end example
-
-Saving a modified version of an existing file does not count as creating
-the file; it preserves the existing file's mode, whatever that is. So
-the default file protection has no effect.
-@end defun
-
-@defun default-file-modes
-This function returns the current default protection value.
-@end defun
-
-@defun set-file-times filename &optional time
-This function sets the access and modification times of @var{filename}
-to @var{time}. The return value is @code{t} if the times are successfully
-set, otherwise it is @code{nil}. @var{time} defaults to the current
-time and must be in the format returned by @code{current-time}
-(@pxref{Time of Day}).
-@end defun
-
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
- On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others. Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files. This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}. Directories are also
-reported with executable bit set, for compatibility with Unix.
-
-@node File Names
-@section File Names
-@cindex file names
-
- Files are generally referred to by their names, in Emacs as elsewhere.
-File names in Emacs are represented as strings. The functions that
-operate on a file all expect a file name argument.
-
- In addition to operating on files themselves, Emacs Lisp programs
-often need to operate on file names; i.e., to take them apart and to use
-part of a name to construct related file names. This section describes
-how to manipulate file names.
-
- The functions in this section do not actually access files, so they
-can operate on file names that do not refer to an existing file or
-directory.
-
- On MS-DOS and MS-Windows, these functions (like the function that
-actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
-where backslashes separate the components, as well as Unix syntax; but
-they always return Unix syntax. On VMS, these functions (and the ones
-that operate on files) understand both VMS file-name syntax and Unix
-syntax. This enables Lisp programs to specify file names in Unix syntax
-and work properly on all systems without change.
-
-@menu
-* 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.
-@end menu
-
-@node File Name Components
-@subsection File Name Components
-@cindex directory part (of file name)
-@cindex nondirectory part (of file name)
-@cindex version number (in file name)
-
- The operating system groups files into directories. To specify a
-file, you must specify the directory and the file's name within that
-directory. Therefore, Emacs considers a file name as having two main
-parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
-(or @dfn{file name within the directory}). Either part may be empty.
-Concatenating these two parts reproduces the original file name.
-
- On most systems, the directory part is everything up to and including
-the last slash (backslash is also allowed in input on MS-DOS or
-MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
-are complicated.
-
- For some purposes, the nondirectory part is further subdivided into
-the name proper and the @dfn{version number}. On most systems, only
-backup files have version numbers in their names. On VMS, every file
-has a version number, but most of the time the file name actually used
-in Emacs omits the version number, so that version numbers in Emacs are
-found mostly in directory lists.
-
-@defun file-name-directory filename
-This function returns the directory part of @var{filename}, as a
-directory name (@pxref{Directory Names}), or @code{nil} if
-@var{filename} does not include a directory part.
-
-On GNU and Unix systems, a string returned by this function always
-ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
-returns a string ending in one of the three characters @samp{:},
-@samp{]}, or @samp{>}.
-
-@example
-@group
-(file-name-directory "lewis/foo") ; @r{Unix example}
- @result{} "lewis/"
-@end group
-@group
-(file-name-directory "foo") ; @r{Unix example}
- @result{} nil
-@end group
-@group
-(file-name-directory "[X]FOO.TMP") ; @r{VMS example}
- @result{} "[X]"
-@end group
-@end example
-@end defun
-
-@defun file-name-nondirectory filename
-This function returns the nondirectory part of @var{filename}.
-
-@example
-@group
-(file-name-nondirectory "lewis/foo")
- @result{} "foo"
-@end group
-@group
-(file-name-nondirectory "foo")
- @result{} "foo"
-@end group
-@group
-(file-name-nondirectory "lewis/")
- @result{} ""
-@end group
-@group
-;; @r{The following example is accurate only on VMS.}
-(file-name-nondirectory "[X]FOO.TMP")
- @result{} "FOO.TMP"
-@end group
-@end example
-@end defun
-
-@defun file-name-sans-versions filename &optional keep-backup-version
-This function returns @var{filename} with any file version numbers,
-backup version numbers, or trailing tildes discarded.
-
-If @var{keep-backup-version} is non-@code{nil}, then true file version
-numbers understood as such by the file system are discarded from the
-return value, but backup version numbers are kept.
-
-@example
-@group
-(file-name-sans-versions "~rms/foo.~1~")
- @result{} "~rms/foo"
-@end group
-@group
-(file-name-sans-versions "~rms/foo~")
- @result{} "~rms/foo"
-@end group
-@group
-(file-name-sans-versions "~rms/foo")
- @result{} "~rms/foo"
-@end group
-@group
-;; @r{The following example applies to VMS only.}
-(file-name-sans-versions "foo;23")
- @result{} "foo"
-@end group
-@end example
-@end defun
-
-@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
-after applying @code{file-name-sans-versions} to remove any
-version/backup part. The extension, in a file name, is the part that
-starts with the last @samp{.} in the last name component (minus
-any version/backup part).
-
-This function returns @code{nil} for extensionless file names such as
-@file{foo}. It returns @code{""} for null extensions, as in
-@file{foo.}. If the last component of a file name begins with a
-@samp{.}, that @samp{.} doesn't count as the beginning of an
-extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
-@samp{.emacs}.
-
-If @var{period} is non-@code{nil}, then the returned value includes
-the period that delimits the extension, and if @var{filename} has no
-extension, the value is @code{""}.
-@end defun
-
-@defun file-name-sans-extension filename
-This function returns @var{filename} minus its extension, if any. The
-version/backup part, if present, is only removed if the file has an
-extension. For example,
-
-@example
-(file-name-sans-extension "foo.lose.c")
- @result{} "foo.lose"
-(file-name-sans-extension "big.hack/foo")
- @result{} "big.hack/foo"
-(file-name-sans-extension "/my/home/.emacs")
- @result{} "/my/home/.emacs"
-(file-name-sans-extension "/my/home/.emacs.el")
- @result{} "/my/home/.emacs"
-(file-name-sans-extension "~/foo.el.~3~")
- @result{} "~/foo"
-(file-name-sans-extension "~/foo.~3~")
- @result{} "~/foo.~3~"
-@end example
-
-Note that the @samp{.~3~} in the two last examples is the backup part,
-not an extension.
-@end defun
-
-@ignore
-Andrew Innes says that this
-
-@c @defvar directory-sep-char
-This variable holds the character that Emacs normally uses to separate
-file name components. The default value is @code{?/}, but on MS-Windows
-you can set it to @code{?\\}; then the functions that transform file names
-use backslashes in their output.
-
-File names using backslashes work as input to Lisp primitives even on
-MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
-value of @code{?/}.
-@end defvar
-@end ignore
-
-@node Relative File Names
-@subsection Absolute and Relative File Names
-@cindex absolute file name
-@cindex relative file name
-
- All the directories in the file system form a tree starting at the
-root directory. A file name can specify all the directory names
-starting from the root of the tree; then it is called an @dfn{absolute}
-file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a @dfn{relative} file
-name. On Unix and GNU/Linux, an absolute file name starts with a slash
-or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
-MS-Windows, an absolute file name starts with a slash or a backslash, or
-with a drive specification @samp{@var{x}:/}, where @var{x} is the
-@dfn{drive letter}. The rules on VMS are complicated.
-
-@defun file-name-absolute-p filename
-This function returns @code{t} if file @var{filename} is an absolute
-file name, @code{nil} otherwise. On VMS, this function understands both
-Unix syntax and VMS syntax.
-
-@example
-@group
-(file-name-absolute-p "~rms/foo")
- @result{} t
-@end group
-@group
-(file-name-absolute-p "rms/foo")
- @result{} nil
-@end group
-@group
-(file-name-absolute-p "/user/rms/foo")
- @result{} t
-@end group
-@end example
-@end defun
-
- Given a possibly relative file name, you can convert it to an
-absolute name using @code{expand-file-name} (@pxref{File Name
-Expansion}). This function converts absolute file names to relative
-names:
-
-@defun file-relative-name filename &optional directory
-This function tries to return a relative name that is equivalent to
-@var{filename}, assuming the result will be interpreted relative to
-@var{directory} (an absolute directory name or directory file name).
-If @var{directory} is omitted or @code{nil}, it defaults to the
-current buffer's default directory.
-
-On some operating systems, an absolute file name begins with a device
-name. On such systems, @var{filename} has no relative equivalent based
-on @var{directory} if they start with two different device names. In
-this case, @code{file-relative-name} returns @var{filename} in absolute
-form.
-
-@example
-(file-relative-name "/foo/bar" "/foo/")
- @result{} "bar"
-(file-relative-name "/foo/bar" "/hack/")
- @result{} "../foo/bar"
-@end example
-@end defun
-
-@node Directory Names
-@comment node-name, next, previous, up
-@subsection Directory Names
-@cindex directory name
-@cindex file name of directory
-
- A @dfn{directory name} is the name of a directory. A directory is
-actually a kind of file, so it has a file name, which is related to
-the directory name but not identical to it. (This is not quite the
-same as the usual Unix terminology.) These two different names for
-the same entity are related by a syntactic transformation. On GNU and
-Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash. On MS-DOS and
-VMS, the relationship is more complicated.
-
- The difference between a directory name and its name as a file is
-subtle but crucial. When an Emacs variable or function argument is
-described as being a directory name, a file name of a directory is not
-acceptable. When @code{file-name-directory} returns a string, that is
-always a directory name.
-
- The following two functions convert between directory names and file
-names. They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
-
-@defun file-name-as-directory filename
-This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory. On
-most systems, this means appending a slash to the string (if it does not
-already end in one). On VMS, the function converts a string of the form
-@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
-
-@example
-@group
-(file-name-as-directory "~rms/lewis")
- @result{} "~rms/lewis/"
-@end group
-@end example
-@end defun
-
-@defun directory-file-name dirname
-This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file. On most
-systems, this means removing the final slash (or backslash) from the
-string. On VMS, the function converts a string of the form @file{[X.Y]}
-to @file{[X]Y.DIR.1}.
-
-@example
-@group
-(directory-file-name "~lewis/")
- @result{} "~lewis"
-@end group
-@end example
-@end defun
-
- Given a directory name, you can combine it with a relative file name
-using @code{concat}:
-
-@example
-(concat @var{dirname} @var{relfile})
-@end example
-
-@noindent
-Be sure to verify that the file name is relative before doing that.
-If you use an absolute file name, the results could be syntactically
-invalid or refer to the wrong file.
-
- If you want to use a directory file name in making such a
-combination, you must first convert it to a directory name using
-@code{file-name-as-directory}:
-
-@example
-(concat (file-name-as-directory @var{dirfile}) @var{relfile})
-@end example
-
-@noindent
-Don't try concatenating a slash by hand, as in
-
-@example
-;;; @r{Wrong!}
-(concat @var{dirfile} "/" @var{relfile})
-@end example
-
-@noindent
-because this is not portable. Always use
-@code{file-name-as-directory}.
-
-@cindex directory name abbreviation
- Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links. Sometimes the users recognize
-primarily the link's name as ``the name'' of the directory, and find it
-annoying to see the directory's ``real'' name. If you define the link
-name as an abbreviation for the ``real'' name, Emacs shows users the
-abbreviation instead.
-
-@defvar directory-abbrev-alist
-The variable @code{directory-abbrev-alist} contains an alist of
-abbreviations to use for file directories. Each element has the form
-@code{(@var{from} . @var{to})}, and says to replace @var{from} with
-@var{to} when it appears in a directory name. The @var{from} string is
-actually a regular expression; it should always start with @samp{^}.
-The @var{to} string should be an ordinary absolute directory name. Do
-not use @samp{~} to stand for a home directory in that string. The
-function @code{abbreviate-file-name} performs these substitutions.
-
-You can set this variable in @file{site-init.el} to describe the
-abbreviations appropriate for your site.
-
-Here's an example, from a system on which file system @file{/home/fsf}
-and so on are normally accessed through symbolic links named @file{/fsf}
-and so on.
-
-@example
-(("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
-@end example
-@end defvar
-
- To convert a directory name to its abbreviation, use this
-function:
-
-@defun abbreviate-file-name filename
-@anchor{Definition of abbreviate-file-name}
-This function applies abbreviations from @code{directory-abbrev-alist}
-to its argument, and substitutes @samp{~} for the user's home
-directory. You can use it for directory names and for file names,
-because it recognizes abbreviations even as part of the name.
-@end defun
-
-@node File Name Expansion
-@subsection Functions that Expand Filenames
-@cindex expansion of file names
-
- @dfn{Expansion} of a file name means converting a relative file name
-to an absolute one. Since this is done relative to a default directory,
-you must specify the default directory name as well as the file name to
-be expanded. Expansion also simplifies file names by eliminating
-redundancies such as @file{./} and @file{@var{name}/../}.
-
-@defun expand-file-name filename &optional directory
-This function converts @var{filename} to an absolute file name. If
-@var{directory} is supplied, it is the default directory to start with
-if @var{filename} is relative. (The value of @var{directory} should
-itself be an absolute directory name or directory file name; it may
-start with @samp{~}.) Otherwise, the current buffer's value of
-@code{default-directory} is used. For example:
-
-@example
-@group
-(expand-file-name "foo")
- @result{} "/xcssun/users/rms/lewis/foo"
-@end group
-@group
-(expand-file-name "../foo")
- @result{} "/xcssun/users/rms/foo"
-@end group
-@group
-(expand-file-name "foo" "/usr/spool/")
- @result{} "/usr/spool/foo"
-@end group
-@group
-(expand-file-name "$HOME/foo")
- @result{} "/xcssun/users/rms/lewis/$HOME/foo"
-@end group
-@end example
-
-If the part of the combined file name before the first slash is
-@samp{~}, it expands to the value of the @env{HOME} environment
-variable (usually your home directory). If the part before the first
-slash is @samp{~@var{user}} and if @var{user} is a valid login name,
-it expands to @var{user}'s home directory.
-
-Filenames containing @samp{.} or @samp{..} are simplified to their
-canonical form:
-
-@example
-@group
-(expand-file-name "bar/../foo")
- @result{} "/xcssun/users/rms/lewis/foo"
-@end group
-@end example
-
-In some cases, a leading @samp{..} component can remain in the output:
-
-@example
-@group
-(expand-file-name "../home" "/")
- @result{} "/../home"
-@end group
-@end example
-
-@noindent
-This is for the sake of filesystems that have the concept of a
-``superroot'' above the root directory @file{/}. On other filesystems,
-@file{/../} is interpreted exactly the same as @file{/}.
-
-Note that @code{expand-file-name} does @emph{not} expand environment
-variables; only @code{substitute-in-file-name} does that.
-
-Note also that @code{expand-file-name} does not follow symbolic links
-at any level. This results in a difference between the way
-@code{file-truename} and @code{expand-file-name} treat @samp{..}.
-Assuming that @samp{/tmp/bar} is a symbolic link to the directory
-@samp{/tmp/foo/bar} we get:
-
-@example
-@group
-(file-truename "/tmp/bar/../myfile")
- @result{} "/tmp/foo/myfile"
-@end group
-@group
-(expand-file-name "/tmp/bar/../myfile")
- @result{} "/tmp/myfile"
-@end group
-@end example
-
-If you may need to follow symbolic links preceding @samp{..}, you
-should make sure to call @code{file-truename} without prior direct or
-indirect calls to @code{expand-file-name}. @xref{Truenames}.
-@end defun
-
-@defvar default-directory
-The value of this buffer-local variable is the default directory for the
-current buffer. It should be an absolute directory name; it may start
-with @samp{~}. This variable is buffer-local in every buffer.
-
-@code{expand-file-name} uses the default directory when its second
-argument is @code{nil}.
-
-Aside from VMS, the value is always a string ending with a slash.
-
-@example
-@group
-default-directory
- @result{} "/user/lewis/manual/"
-@end group
-@end example
-@end defvar
-
-@defun substitute-in-file-name filename
-@anchor{Definition of substitute-in-file-name}
-This function replaces environment variable references in
-@var{filename} with the environment variable values. Following
-standard Unix shell syntax, @samp{$} is the prefix to substitute an
-environment variable value. If the input contains @samp{$$}, that is
-converted to @samp{$}; this gives the user a way to ``quote'' a
-@samp{$}.
-
-The environment variable name is the series of alphanumeric characters
-(including underscores) that follow the @samp{$}. If the character following
-the @samp{$} is a @samp{@{}, then the variable name is everything up to the
-matching @samp{@}}.
-
-Calling @code{substitute-in-file-name} on output produced by
-@code{substitute-in-file-name} tends to give incorrect results. For
-instance, use of @samp{$$} to quote a single @samp{$} won't work
-properly, and @samp{$} in an environment variable's value could lead
-to repeated substitution. Therefore, programs that call this function
-and put the output where it will be passed to this function need to
-double all @samp{$} characters to prevent subsequent incorrect
-results.
-
-@c Wordy to avoid overfull hbox. --rjc 15mar92
-Here we assume that the environment variable @code{HOME}, which holds
-the user's home directory name, has value @samp{/xcssun/users/rms}.
-
-@example
-@group
-(substitute-in-file-name "$HOME/foo")
- @result{} "/xcssun/users/rms/foo"
-@end group
-@end example
-
-After substitution, if a @samp{~} or a @samp{/} appears immediately
-after another @samp{/}, the function discards everything before it (up
-through the immediately preceding @samp{/}).
-
-@example
-@group
-(substitute-in-file-name "bar/~/foo")
- @result{} "~/foo"
-@end group
-@group
-(substitute-in-file-name "/usr/local/$HOME/foo")
- @result{} "/xcssun/users/rms/foo"
- ;; @r{@file{/usr/local/} has been discarded.}
-@end group
-@end example
-
-On VMS, @samp{$} substitution is not done, so this function does nothing
-on VMS except discard superfluous initial components as shown above.
-@end defun
-
-@node Unique File Names
-@subsection Generating Unique File Names
-
- Some programs need to write temporary files. Here is the usual way to
-construct a name for such a file:
-
-@example
-(make-temp-file @var{name-of-application})
-@end example
-
-@noindent
-The job of @code{make-temp-file} is to prevent two different users or
-two different jobs from trying to use the exact same file name.
-
-@defun make-temp-file prefix &optional dir-flag suffix
-This function creates a temporary file and returns its name. Emacs
-creates the temporary file's name by adding to @var{prefix} some
-random characters that are different in each Emacs job. The result is
-guaranteed to be a newly created empty file. On MS-DOS, this function
-can truncate the @var{string} prefix to fit into the 8+3 file-name
-limits. If @var{prefix} is a relative file name, it is expanded
-against @code{temporary-file-directory}.
-
-@example
-@group
-(make-temp-file "foo")
- @result{} "/tmp/foo232J6v"
-@end group
-@end example
-
-When @code{make-temp-file} returns, the file has been created and is
-empty. At that point, you should write the intended contents into the
-file.
-
-If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
-empty directory instead of an empty file. It returns the file name,
-not the directory name, of that directory. @xref{Directory Names}.
-
-If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
-the end of the file name.
-
-To prevent conflicts among different libraries running in the same
-Emacs, each Lisp program that uses @code{make-temp-file} should have its
-own @var{prefix}. The number added to the end of @var{prefix}
-distinguishes between the same application running in different Emacs
-jobs. Additional added characters permit a large number of distinct
-names even in one Emacs job.
-@end defun
-
- The default directory for temporary files is controlled by the
-variable @code{temporary-file-directory}. This variable gives the user
-a uniform way to specify the directory for all temporary files. Some
-programs use @code{small-temporary-file-directory} instead, if that is
-non-@code{nil}. To use it, you should expand the prefix against
-the proper directory before calling @code{make-temp-file}.
-
- In older Emacs versions where @code{make-temp-file} does not exist,
-you should use @code{make-temp-name} instead:
-
-@example
-(make-temp-name
- (expand-file-name @var{name-of-application}
- temporary-file-directory))
-@end example
-
-@defun make-temp-name string
-This function generates a string that can be used as a unique file
-name. The name starts with @var{string}, and has several random
-characters appended to it, which are different in each Emacs job. It
-is like @code{make-temp-file} except that it just constructs a name,
-and does not create a file. Another difference is that @var{string}
-should be an absolute file name. On MS-DOS, this function can
-truncate the @var{string} prefix to fit into the 8+3 file-name limits.
-@end defun
-
-@defvar temporary-file-directory
-@cindex @code{TMPDIR} environment variable
-@cindex @code{TMP} environment variable
-@cindex @code{TEMP} environment variable
-This variable specifies the directory name for creating temporary files.
-Its value should be a directory name (@pxref{Directory Names}), but it
-is good for Lisp programs to cope if the value is a directory's file
-name instead. Using the value as the second argument to
-@code{expand-file-name} is a good way to achieve that.
-
-The default value is determined in a reasonable way for your operating
-system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
-environment variables, with a fall-back to a system-dependent name if
-none of these variables is defined.
-
-Even if you do not use @code{make-temp-file} to create the temporary
-file, you should still use this variable to decide which directory to
-put the file in. However, if you expect the file to be small, you
-should use @code{small-temporary-file-directory} first if that is
-non-@code{nil}.
-@end defvar
-
-@defvar small-temporary-file-directory
-This variable specifies the directory name for
-creating certain temporary files, which are likely to be small.
-
-If you want to write a temporary file which is likely to be small, you
-should compute the directory like this:
-
-@example
-(make-temp-file
- (expand-file-name @var{prefix}
- (or small-temporary-file-directory
- temporary-file-directory)))
-@end example
-@end defvar
-
-@node File Name Completion
-@subsection File Name Completion
-@cindex file name completion subroutines
-@cindex completion, file name
-
- This section describes low-level subroutines for completing a file
-name. For higher level functions, see @ref{Reading File Names}.
-
-@defun file-name-all-completions partial-filename directory
-This function returns a list of all possible completions for a file
-whose name starts with @var{partial-filename} in directory
-@var{directory}. The order of the completions is the order of the files
-in the directory, which is unpredictable and conveys no useful
-information.
-
-The argument @var{partial-filename} must be a file name containing no
-directory part and no slash (or backslash on some systems). The current
-buffer's default directory is prepended to @var{directory}, if
-@var{directory} is not absolute.
-
-In the following example, suppose that @file{~rms/lewis} is the current
-default directory, and has five files whose names begin with @samp{f}:
-@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
-
-@example
-@group
-(file-name-all-completions "f" "")
- @result{} ("foo" "file~" "file.c.~2~"
- "file.c.~1~" "file.c")
-@end group
-
-@group
-(file-name-all-completions "fo" "")
- @result{} ("foo")
-@end group
-@end example
-@end defun
-
-@defun file-name-completion filename directory &optional predicate
-This function completes the file name @var{filename} in directory
-@var{directory}. It returns the longest prefix common to all file names
-in directory @var{directory} that start with @var{filename}. If
-@var{predicate} is non-@code{nil} then it ignores possible completions
-that don't satisfy @var{predicate}, after calling that function
-with one argument, the expanded absolute file name.
-
-If only one match exists and @var{filename} matches it exactly, the
-function returns @code{t}. The function returns @code{nil} if directory
-@var{directory} contains no name starting with @var{filename}.
-
-In the following example, suppose that the current default directory
-has five files whose names begin with @samp{f}: @file{foo},
-@file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
-
-@example
-@group
-(file-name-completion "fi" "")
- @result{} "file"
-@end group
-
-@group
-(file-name-completion "file.c.~1" "")
- @result{} "file.c.~1~"
-@end group
-
-@group
-(file-name-completion "file.c.~1~" "")
- @result{} t
-@end group
-
-@group
-(file-name-completion "file.c.~3" "")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defopt completion-ignored-extensions
-@code{file-name-completion} usually ignores file names that end in any
-string in this list. It does not ignore them when all the possible
-completions end in one of these suffixes. This variable has no effect
-on @code{file-name-all-completions}.@refill
-
-A typical value might look like this:
-
-@example
-@group
-completion-ignored-extensions
- @result{} (".o" ".elc" "~" ".dvi")
-@end group
-@end example
-
-If an element of @code{completion-ignored-extensions} ends in a slash
-@samp{/}, it signals a directory. The elements which do @emph{not} end
-in a slash will never match a directory; thus, the above value will not
-filter out a directory named @file{foo.elc}.
-@end defopt
-
-@node Standard File Names
-@subsection Standard File Names
-
- Most of the file names used in Lisp programs are entered by the user.
-But occasionally a Lisp program needs to specify a standard file name
-for a particular use---typically, to hold customization information
-about each user. For example, abbrev definitions are stored (by
-default) in the file @file{~/.abbrev_defs}; the @code{completion}
-package stores completions in the file @file{~/.completions}. These are
-two of the many standard file names used by parts of Emacs for certain
-purposes.
-
- Various operating systems have their own conventions for valid file
-names and for which file names to use for user profile data. A Lisp
-program which reads a file using a standard file name ought to use, on
-each type of system, a file name suitable for that system. The function
-@code{convert-standard-filename} makes this easy to do.
-
-@defun convert-standard-filename filename
-This function alters the file name @var{filename} to fit the conventions
-of the operating system in use, and returns the result as a new string.
-@end defun
-
- The recommended way to specify a standard file name in a Lisp program
-is to choose a name which fits the conventions of GNU and Unix systems,
-usually with a nondirectory part that starts with a period, and pass it
-to @code{convert-standard-filename} instead of using it directly. Here
-is an example from the @code{completion} package:
-
-@example
-(defvar save-completions-file-name
- (convert-standard-filename "~/.completions")
- "*The file name to save completions to.")
-@end example
-
- On GNU and Unix systems, and on some other systems as well,
-@code{convert-standard-filename} returns its argument unchanged. On
-some other systems, it alters the name to fit the system's conventions.
-
- For example, on MS-DOS the alterations made by this function include
-converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
-middle of the name to @samp{.} if there is no other @samp{.}, inserting
-a @samp{.} after eight characters if there is none, and truncating to
-three characters after the @samp{.}. (It makes other changes as well.)
-Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
-@file{.completions} becomes @file{_complet.ion}.
-
-@node Contents of Directories
-@section Contents of Directories
-@cindex directory-oriented functions
-@cindex file names in directory
-
- A directory is a kind of file that contains other files entered under
-various names. Directories are a feature of the file system.
-
- Emacs can list the names of the files in a directory as a Lisp list,
-or display the names in a buffer using the @code{ls} shell command. In
-the latter case, it can optionally display information about each file,
-depending on the options passed to the @code{ls} command.
-
-@defun directory-files directory &optional full-name match-regexp nosort
-This function returns a list of the names of the files in the directory
-@var{directory}. By default, the list is in alphabetical order.
-
-If @var{full-name} is non-@code{nil}, the function returns the files'
-absolute file names. Otherwise, it returns the names relative to
-the specified directory.
-
-If @var{match-regexp} is non-@code{nil}, this function returns only
-those file names that contain a match for that regular expression---the
-other file names are excluded from the list. On case-insensitive
-filesystems, the regular expression matching is case-insensitive.
-
-@c Emacs 19 feature
-If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
-the list, so you get the file names in no particular order. Use this if
-you want the utmost possible speed and don't care what order the files
-are processed in. If the order of processing is visible to the user,
-then the user will probably be happier if you do sort the names.
-
-@example
-@group
-(directory-files "~lewis")
- @result{} ("#foo#" "#foo.el#" "." ".."
- "dired-mods.el" "files.texi"
- "files.texi.~1~")
-@end group
-@end example
-
-An error is signaled if @var{directory} is not the name of a directory
-that can be read.
-@end defun
-
-@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
-This is similar to @code{directory-files} in deciding which files
-to report on and how to report their names. However, instead
-of returning a list of file names, it returns for each file a
-list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
-is what @code{file-attributes} would return for that file.
-The optional argument @var{id-format} has the same meaning as the
-corresponding argument to @code{file-attributes} (@pxref{Definition
-of file-attributes}).
-@end defun
-
-@defun file-name-all-versions file dirname
-This function returns a list of all versions of the file named
-@var{file} in directory @var{dirname}. It is only available on VMS.
-@end defun
-
-@defun file-expand-wildcards pattern &optional full
-This function expands the wildcard pattern @var{pattern}, returning
-a list of file names that match it.
-
-If @var{pattern} is written as an absolute file name,
-the values are absolute also.
-
-If @var{pattern} is written as a relative file name, it is interpreted
-relative to the current default directory. The file names returned are
-normally also relative to the current default directory. However, if
-@var{full} is non-@code{nil}, they are absolute.
-@end defun
-
-@defun insert-directory file switches &optional wildcard full-directory-p
-This function inserts (in the current buffer) a directory listing for
-directory @var{file}, formatted with @code{ls} according to
-@var{switches}. It leaves point after the inserted text.
-@var{switches} may be a string of options, or a list of strings
-representing individual options.
-
-The argument @var{file} may be either a directory name or a file
-specification including wildcard characters. If @var{wildcard} is
-non-@code{nil}, that means treat @var{file} as a file specification with
-wildcards.
-
-If @var{full-directory-p} is non-@code{nil}, that means the directory
-listing is expected to show the full contents of a directory. You
-should specify @code{t} when @var{file} is a directory and switches do
-not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
-describe a directory itself as a file, rather than showing its
-contents.)
-
-On most systems, this function works by running a directory listing
-program whose name is in the variable @code{insert-directory-program}.
-If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
-@code{shell-file-name}, to expand the wildcards.
-
-MS-DOS and MS-Windows systems usually lack the standard Unix program
-@code{ls}, so this function emulates the standard Unix program @code{ls}
-with Lisp code.
-
-As a technical detail, when @var{switches} contains the long
-@samp{--dired} option, @code{insert-directory} treats it specially,
-for the sake of dired. However, the normally equivalent short
-@samp{-D} option is just passed on to @code{insert-directory-program},
-as any other option.
-@end defun
-
-@defvar insert-directory-program
-This variable's value is the program to run to generate a directory listing
-for the function @code{insert-directory}. It is ignored on systems
-which generate the listing with Lisp code.
-@end defvar
-
-@node Create/Delete Dirs
-@section Creating and Deleting Directories
-@cindex creating and deleting directories
-@c Emacs 19 features
-
- Most Emacs Lisp file-manipulation functions get errors when used on
-files that are directories. For example, you cannot delete a directory
-with @code{delete-file}. These special functions exist to create and
-delete directories.
-
-@defun make-directory dirname &optional parents
-This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, as is always the case in an
-interactive call, that means to create the parent directories first,
-if they don't already exist.
-@end defun
-
-@defun delete-directory dirname
-This function deletes the directory named @var{dirname}. The function
-@code{delete-file} does not work for files that are directories; you
-must use @code{delete-directory} for them. If the directory contains
-any files, @code{delete-directory} signals an error.
-
-This function only follows symbolic links at the level of parent
-directories.
-@end defun
-
-@node Magic File Names
-@section Making Certain File Names ``Magic''
-@cindex magic file names
-
-@c Emacs 19 feature
- You can implement special handling for certain file names. This is
-called making those names @dfn{magic}. The principal use for this
-feature is in implementing remote file names (@pxref{Remote Files,,
-Remote Files, emacs, The GNU Emacs Manual}).
-
- To define a kind of magic file name, you must supply a regular
-expression to define the class of names (all those that match the
-regular expression), plus a handler that implements all the primitive
-Emacs file operations for file names that do match.
-
- The variable @code{file-name-handler-alist} holds a list of handlers,
-together with regular expressions that determine when to apply each
-handler. Each element has this form:
-
-@example
-(@var{regexp} . @var{handler})
-@end example
-
-@noindent
-All the Emacs primitives for file access and file name transformation
-check the given file name against @code{file-name-handler-alist}. If
-the file name matches @var{regexp}, the primitives handle that file by
-calling @var{handler}.
-
- The first argument given to @var{handler} is the name of the
-primitive, as a symbol; the remaining arguments are the arguments that
-were passed to that primitive. (The first of these arguments is most
-often the file name itself.) For example, if you do this:
-
-@example
-(file-exists-p @var{filename})
-@end example
-
-@noindent
-and @var{filename} has handler @var{handler}, then @var{handler} is
-called like this:
-
-@example
-(funcall @var{handler} 'file-exists-p @var{filename})
-@end example
-
- When a function takes two or more arguments that must be file names,
-it checks each of those names for a handler. For example, if you do
-this:
-
-@example
-(expand-file-name @var{filename} @var{dirname})
-@end example
-
-@noindent
-then it checks for a handler for @var{filename} and then for a handler
-for @var{dirname}. In either case, the @var{handler} is called like
-this:
-
-@example
-(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
-@end example
-
-@noindent
-The @var{handler} then needs to figure out whether to handle
-@var{filename} or @var{dirname}.
-
- If the specified file name matches more than one handler, the one
-whose match starts last in the file name gets precedence. This rule
-is chosen so that handlers for jobs such as uncompression are handled
-first, before handlers for jobs such as remote file access.
-
- Here are the operations that a magic file name handler gets to handle:
-
-@ifnottex
-@noindent
-@code{access-file}, @code{add-name-to-file},
-@code{byte-compiler-base-file-name},@*
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
-@code{diff-latest-backup-file},
-@code{directory-file-name},
-@code{directory-files},
-@code{directory-files-and-attributes},
-@code{dired-compress-file}, @code{dired-uncache},@*
-@code{expand-file-name},
-@code{file-accessible-directory-p},
-@code{file-attributes},
-@code{file-directory-p},
-@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory},
-@code{file-name-completion},
-@code{file-name-directory},
-@code{file-name-nondirectory},
-@code{file-name-sans-versions}, @code{file-newer-than-file-p},
-@code{file-ownership-preserved-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
-@code{find-backup-file-name},
-@code{find-file-noselect},@*
-@code{get-file-buffer},
-@code{insert-directory},
-@code{insert-file-contents},@*
-@code{load},
-@code{make-auto-save-file-name},
-@code{make-directory},
-@code{make-directory-internal},
-@code{make-symbolic-link},@*
-@code{process-file},
-@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
-@code{set-visited-file-modtime}, @code{shell-command},
-@code{start-file-process},
-@code{substitute-in-file-name},@*
-@code{unhandled-file-name-directory},
-@code{vc-registered},
-@code{verify-visited-file-modtime},@*
-@code{write-region}.
-@end ifnottex
-@iftex
-@noindent
-@flushleft
-@code{access-file}, @code{add-name-to-file},
-@code{byte-com@discretionary{}{}{}piler-base-file-name},
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
-@code{diff-latest-backup-file},
-@code{directory-file-name},
-@code{directory-files},
-@code{directory-files-and-at@discretionary{}{}{}tributes},
-@code{dired-compress-file}, @code{dired-uncache},
-@code{expand-file-name},
-@code{file-accessible-direc@discretionary{}{}{}tory-p},
-@code{file-attributes},
-@code{file-direct@discretionary{}{}{}ory-p},
-@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory},
-@code{file-name-completion},
-@code{file-name-directory},
-@code{file-name-nondirec@discretionary{}{}{}tory},
-@code{file-name-sans-versions}, @code{file-newer-than-file-p},
-@code{file-ownership-pre@discretionary{}{}{}served-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
-@code{find-backup-file-name},
-@code{find-file-noselect},
-@code{get-file-buffer},
-@code{insert-directory},
-@code{insert-file-contents},
-@code{load}, @code{make-direc@discretionary{}{}{}tory},
-@code{make-direc@discretionary{}{}{}tory-internal},
-@code{make-symbolic-link},
-@code{process-file},
-@code{rename-file}, @code{set-file-modes},
-@code{set-visited-file-modtime}, @code{shell-command},
-@code{start-file-process},
-@code{substitute-in-file-name},
-@code{unhandled-file-name-directory},
-@code{vc-regis@discretionary{}{}{}tered},
-@code{verify-visited-file-modtime},
-@code{write-region}.
-@end flushleft
-@end iftex
-
- Handlers for @code{insert-file-contents} typically need to clear the
-buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
-@var{visit} argument is non-@code{nil}. This also has the effect of
-unlocking the buffer if it is locked.
-
- The handler function must handle all of the above operations, and
-possibly others to be added in the future. It need not implement all
-these operations itself---when it has nothing special to do for a
-certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way.'' It should always reinvoke the primitive
-for an operation it does not recognize. Here's one way to do this:
-
-@smallexample
-(defun my-file-handler (operation &rest args)
- ;; @r{First check for the specific operations}
- ;; @r{that we have special handling for.}
- (cond ((eq operation 'insert-file-contents) @dots{})
- ((eq operation 'write-region) @dots{})
- @dots{}
- ;; @r{Handle any operation we don't know about.}
- (t (let ((inhibit-file-name-handlers
- (cons 'my-file-handler
- (and (eq inhibit-file-name-operation operation)
- inhibit-file-name-handlers)))
- (inhibit-file-name-operation operation))
- (apply operation args)))))
-@end smallexample
-
- When a handler function decides to call the ordinary Emacs primitive for
-the operation at hand, it needs to prevent the primitive from calling
-the same handler once again, thus leading to an infinite recursion. The
-example above shows how to do this, with the variables
-@code{inhibit-file-name-handlers} and
-@code{inhibit-file-name-operation}. Be careful to use them exactly as
-shown above; the details are crucial for proper behavior in the case of
-multiple handlers, and for operations that have two file names that may
-each have handlers.
-
-@kindex safe-magic (@r{property})
- Handlers that don't really do anything special for actual access to the
-file---such as the ones that implement completion of host names for
-remote file names---should have a non-@code{nil} @code{safe-magic}
-property. For instance, Emacs normally ``protects'' directory names
-it finds in @code{PATH} from becoming magic, if they look like magic
-file names, by prefixing them with @samp{/:}. But if the handler that
-would be used for them has a non-@code{nil} @code{safe-magic}
-property, the @samp{/:} is not added.
-
-@kindex operations (@r{property})
- A file name handler can have an @code{operations} property to
-declare which operations it handles in a nontrivial way. If this
-property has a non-@code{nil} value, it should be a list of
-operations; then only those operations will call the handler. This
-avoids inefficiency, but its main purpose is for autoloaded handler
-functions, so that they won't be loaded except when they have real
-work to do.
-
- Simply deferring all operations to the usual primitives does not
-work. For instance, if the file name handler applies to
-@code{file-exists-p}, then it must handle @code{load} itself, because
-the usual @code{load} code won't work properly in that case. However,
-if the handler uses the @code{operations} property to say it doesn't
-handle @code{file-exists-p}, then it need not handle @code{load}
-nontrivially.
-
-@defvar inhibit-file-name-handlers
-This variable holds a list of handlers whose use is presently inhibited
-for a certain operation.
-@end defvar
-
-@defvar inhibit-file-name-operation
-The operation for which certain handlers are presently inhibited.
-@end defvar
-
-@defun find-file-name-handler file operation
-This function returns the handler function for file name @var{file},
-or @code{nil} if there is none. The argument @var{operation} should
-be the operation to be performed on the file---the value you will pass
-to the handler as its first argument when you call it. If
-@var{operation} equals @code{inhibit-file-name-operation}, or if it is
-not found in the @code{operations} property of the handler, this
-function returns @code{nil}.
-@end defun
-
-@defun file-local-copy filename
-This function copies file @var{filename} to an ordinary non-magic file
-on the local machine, if it isn't on the local machine already. Magic
-file names should handle the @code{file-local-copy} operation if they
-refer to files on other machines. A magic file name that is used for
-other purposes than remote file access should not handle
-@code{file-local-copy}; then this function will treat the file as
-local.
-
-If @var{filename} is local, whether magic or not, this function does
-nothing and returns @code{nil}. Otherwise it returns the file name
-of the local copy file.
-@end defun
-
-@defun file-remote-p filename &optional identification connected
-This function tests whether @var{filename} is a remote file. If
-@var{filename} is local (not remote), the return value is @code{nil}.
-If @var{filename} is indeed remote, the return value is a string that
-identifies the remote system.
-
-This identifier string can include a host name and a user name, as
-well as characters designating the method used to access the remote
-system. For example, the remote identifier string for the filename
-@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
-
-If @code{file-remote-p} returns the same identifier for two different
-filenames, that means they are stored on the same file system and can
-be accessed locally with respect to each other. This means, for
-example, that it is possible to start a remote process accessing both
-files at the same time. Implementors of file handlers need to ensure
-this principle is valid.
-
-@var{identification} specifies which part of the identifier shall be
-returned as string. @var{identification} can be the symbol
-@code{method}, @code{user} or @code{host}; any other value is handled
-like @code{nil} and means to return the complete identifier string.
-In the example above, the remote @code{user} identifier string would
-be @code{root}.
-
-If @var{connected} is non-@code{nil}, this function returns @code{nil}
-even if @var{filename} is remote, if Emacs has no network connection
-to its host. This is useful when you want to avoid the delay of
-making connections when they don't exist.
-@end defun
-
-@defun unhandled-file-name-directory filename
-This function returns the name of a directory that is not magic. It
-uses the directory part of @var{filename} if that is not magic. For a
-magic file name, it invokes the file name handler, which therefore
-decides what value to return.
-
-This is useful for running a subprocess; every subprocess must have a
-non-magic directory to serve as its current directory, and this function
-is a good way to come up with one.
-@end defun
-
-@node Format Conversion
-@section File Format Conversion
-
-@cindex file format conversion
-@cindex encoding file formats
-@cindex decoding file formats
-@cindex text properties in files
-@cindex saving text properties
- Emacs performs several steps to convert the data in a buffer (text,
-text properties, and possibly other information) to and from a
-representation suitable for storing into a file. This section describes
-the fundamental functions that perform this @dfn{format conversion},
-namely @code{insert-file-contents} for reading a file into a buffer,
-and @code{write-region} for writing a buffer into a file.
-
-@menu
-* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}
-* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
-* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
-@end menu
-
-@node Format Conversion Overview
-@subsection Overview
-@noindent
-The function @code{insert-file-contents}:
-
-@itemize
-@item initially, inserts bytes from the file into the buffer;
-@item decodes bytes to characters as appropriate;
-@item processes formats as defined by entries in @code{format-alist}; and
-@item calls functions in @code{after-insert-file-functions}.
-@end itemize
-
-@noindent
-The function @code{write-region}:
-
-@itemize
-@item initially, calls functions in @code{write-region-annotate-functions};
-@item processes formats as defined by entries in @code{format-alist};
-@item encodes characters to bytes as appropriate; and
-@item modifies the file with the bytes.
-@end itemize
-
- This shows the symmetry of the lowest-level operations; reading and
-writing handle things in opposite order. The rest of this section
-describes the two facilities surrounding the three variables named
-above, as well as some related functions. @ref{Coding Systems}, for
-details on character encoding and decoding.
-
-@node Format Conversion Round-Trip
-@subsection Round-Trip Specification
-
- The most general of the two facilities is controlled by the variable
-@code{format-alist}, a list of @dfn{file format} specifications, which
-describe textual representations used in files for the data in an Emacs
-buffer. The descriptions for reading and writing are paired, which is
-why we call this ``round-trip'' specification
-(@pxref{Format Conversion Piecemeal}, for non-paired specification).
-
-@defvar format-alist
-This list contains one format definition for each defined file format.
-Each format definition is a list of this form:
-
-@example
-(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
-@end example
-@end defvar
-
-@cindex format definition
-@noindent
-Here is what the elements in a format definition mean:
-
-@table @var
-@item name
-The name of this format.
-
-@item doc-string
-A documentation string for the format.
-
-@item regexp
-A regular expression which is used to recognize files represented in
-this format.
-
-@item from-fn
-A shell command or function to decode data in this format (to convert
-file data into the usual Emacs data representation).
-
-A shell command is represented as a string; Emacs runs the command as a
-filter to perform the conversion.
-
-If @var{from-fn} is a function, it is called with two arguments, @var{begin}
-and @var{end}, which specify the part of the buffer it should convert.
-It should convert the text by editing it in place. Since this can
-change the length of the text, @var{from-fn} should return the modified
-end position.
-
-One responsibility of @var{from-fn} is to make sure that the beginning
-of the file no longer matches @var{regexp}. Otherwise it is likely to
-get called again.
-
-@item to-fn
-A shell command or function to encode data in this format---that is, to
-convert the usual Emacs data representation into this format.
-
-If @var{to-fn} is a string, it is a shell command; Emacs runs the
-command as a filter to perform the conversion.
-
-If @var{to-fn} is a function, it is called with three arguments:
-@var{begin} and @var{end}, which specify the part of the buffer it
-should convert, and @var{buffer}, which specifies which buffer. There
-are two ways it can do the conversion:
-
-@itemize @bullet
-@item
-By editing the buffer in place. In this case, @var{to-fn} should
-return the end-position of the range of text, as modified.
-
-@item
-By returning a list of annotations. This is a list of elements of the
-form @code{(@var{position} . @var{string})}, where @var{position} is an
-integer specifying the relative position in the text to be written, and
-@var{string} is the annotation to add there. The list must be sorted in
-order of position when @var{to-fn} returns it.
-
-When @code{write-region} actually writes the text from the buffer to the
-file, it intermixes the specified annotations at the corresponding
-positions. All this takes place without modifying the buffer.
-@end itemize
-
-@item modify
-A flag, @code{t} if the encoding function modifies the buffer, and
-@code{nil} if it works by returning a list of annotations.
-
-@item mode-fn
-A minor-mode function to call after visiting a file converted from this
-format. The function is called with one argument, the integer 1;
-that tells a minor-mode function to enable the mode.
-@end table
-
-The function @code{insert-file-contents} automatically recognizes file
-formats when it reads the specified file. It checks the text of the
-beginning of the file against the regular expressions of the format
-definitions, and if it finds a match, it calls the decoding function for
-that format. Then it checks all the known formats over again.
-It keeps checking them until none of them is applicable.
-
-Visiting a file, with @code{find-file-noselect} or the commands that use
-it, performs conversion likewise (because it calls
-@code{insert-file-contents}); it also calls the mode function for each
-format that it decodes. It stores a list of the format names in the
-buffer-local variable @code{buffer-file-format}.
-
-@defvar buffer-file-format
-This variable states the format of the visited file. More precisely,
-this is a list of the file format names that were decoded in the course
-of visiting the current buffer's file. It is always buffer-local in all
-buffers.
-@end defvar
-
-When @code{write-region} writes data into a file, it first calls the
-encoding functions for the formats listed in @code{buffer-file-format},
-in the order of appearance in the list.
-
-@deffn Command format-write-file file format &optional confirm
-This command writes the current buffer contents into the file
-@var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer. The argument @var{format} is a list
-of format names. Except for the @var{format} argument, this command
-is similar to @code{write-file}. In particular, @var{confirm} has the
-same meaning and interactive treatment as the corresponding argument
-to @code{write-file}. @xref{Definition of write-file}.
-@end deffn
-
-@deffn Command format-find-file file format
-This command finds the file @var{file}, converting it according to
-format @var{format}. It also makes @var{format} the default if the
-buffer is saved later.
-
-The argument @var{format} is a list of format names. If @var{format} is
-@code{nil}, no conversion takes place. Interactively, typing just
-@key{RET} for @var{format} specifies @code{nil}.
-@end deffn
-
-@deffn Command format-insert-file file format &optional beg end
-This command inserts the contents of file @var{file}, converting it
-according to format @var{format}. If @var{beg} and @var{end} are
-non-@code{nil}, they specify which part of the file to read, as in
-@code{insert-file-contents} (@pxref{Reading from Files}).
-
-The return value is like what @code{insert-file-contents} returns: a
-list of the absolute file name and the length of the data inserted
-(after conversion).
-
-The argument @var{format} is a list of format names. If @var{format} is
-@code{nil}, no conversion takes place. Interactively, typing just
-@key{RET} for @var{format} specifies @code{nil}.
-@end deffn
-
-@defvar buffer-auto-save-file-format
-This variable specifies the format to use for auto-saving. Its value is
-a list of format names, just like the value of
-@code{buffer-file-format}; however, it is used instead of
-@code{buffer-file-format} for writing auto-save files. If the value
-is @code{t}, the default, auto-saving uses the same format as a
-regular save in the same buffer. This variable is always buffer-local
-in all buffers.
-@end defvar
-
-@node Format Conversion Piecemeal
-@subsection Piecemeal Specification
-
- In contrast to the round-trip specification described in the previous
-subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
-@code{after-insert-file-functions} and @code{write-region-annotate-functions}
-to separately control the respective reading and writing conversions.
-
- Conversion starts with one representation and produces another
-representation. When there is only one conversion to do, there is no
-conflict about what to start with. However, when there are multiple
-conversions involved, conflict may arise when two conversions need to
-start with the same data.
-
- This situation is best understood in the context of converting text
-properties during @code{write-region}. For example, the character at
-position 42 in a buffer is @samp{X} with a text property @code{foo}. If
-the conversion for @code{foo} is done by inserting into the buffer, say,
-@samp{FOO:}, then that changes the character at position 42 from
-@samp{X} to @samp{F}. The next conversion will start with the wrong
-data straight away.
-
- To avoid conflict, cooperative conversions do not modify the buffer,
-but instead specify @dfn{annotations}, a list of elements of the form
-@code{(@var{position} . @var{string})}, sorted in order of increasing
-@var{position}.
-
- If there is more than one conversion, @code{write-region} merges their
-annotations destructively into one sorted list. Later, when the text
-from the buffer is actually written to the file, it intermixes the
-specified annotations at the corresponding positions. All this takes
-place without modifying the buffer.
-
-@c ??? What about ``overriding'' conversions like those allowed
-@c ??? for `write-region-annotate-functions', below? --ttn
-
- In contrast, when reading, the annotations intermixed with the text
-are handled immediately. @code{insert-file-contents} sets point to the
-beginning of some text to be converted, then calls the conversion
-functions with the length of that text. These functions should always
-return with point at the beginning of the inserted text. This approach
-makes sense for reading because annotations removed by the first
-converter can't be mistakenly processed by a later converter.
-
- Each conversion function should scan for the annotations it
-recognizes, remove the annotation, modify the buffer text (to set a text
-property, for example), and return the updated length of the text, as it
-stands after those changes. The value returned by one function becomes
-the argument to the next function.
-
-@defvar write-region-annotate-functions
-A list of functions for @code{write-region} to call. Each function in
-the list is called with two arguments: the start and end of the region
-to be written. These functions should not alter the contents of the
-buffer. Instead, they should return annotations.
-
-@c ??? Following adapted from comment in `build_annotations' (fileio.c).
-@c ??? Perhaps this is intended for internal use only?
-@c ??? Someone who understands this, please reword it. --ttn
-As a special case, if a function returns with a different buffer
-current, Emacs takes it to mean the current buffer contains altered text
-to be output, and discards all previous annotations because they should
-have been dealt with by this function.
-@end defvar
-
-@defvar after-insert-file-functions
-Each function in this list is called by @code{insert-file-contents}
-with one argument, the number of characters inserted, and with point
-at the beginning of the inserted text. Each function should leave
-point unchanged, and return the new character count describing the
-inserted text as modified by the function.
-@c ??? The docstring mentions a handler from `file-name-handler-alist'
-@c "intercepting" `insert-file-contents'. Hmmm. --ttn
-@end defvar
-
- We invite users to write Lisp programs to store and retrieve text
-properties in files, using these hooks, and thus to experiment with
-various data formats and find good ones. Eventually we hope users
-will produce good, general extensions we can install in Emacs.
-
- We suggest not trying to handle arbitrary Lisp objects as text property
-names or values---because a program that general is probably difficult
-to write, and slow. Instead, choose a set of possible data types that
-are reasonably flexible, and not too hard to encode.
-
-@ignore
- arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/frames
-@node Frames, Positions, Windows, Top
-@chapter Frames
-@cindex frame
-
- In Emacs editing, A @dfn{frame} is a screen object that contains one
-or more Emacs windows. It's the kind of object that is called a
-``window'' in the terminology of graphical environments; but we can't
-call it a ``window'' here, because Emacs uses that word in a different
-way.
-
- A frame initially contains a single main window and/or a minibuffer
-window; you can subdivide the main window vertically or horizontally
-into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp
-object that represents a frame on the screen.
-
-@cindex terminal frame
- When Emacs runs on a text-only terminal, it starts with one
-@dfn{terminal frame}. If you create additional ones, Emacs displays
-one and only one at any given time---on the terminal screen, of course.
-
-@cindex window frame
- When Emacs communicates directly with a supported window system, such
-as X, it does not have a terminal frame; instead, it starts with
-a single @dfn{window frame}, but you can create more, and Emacs can
-display several such frames at once as is usual for window systems.
-
-@defun framep object
-This predicate returns a non-@code{nil} value if @var{object} is a
-frame, and @code{nil} otherwise. For a frame, the value indicates which
-kind of display the frame uses:
-
-@table @code
-@item x
-The frame is displayed in an X window.
-@item t
-A terminal frame on a character display.
-@item mac
-The frame is displayed on a Macintosh.
-@item w32
-The frame is displayed on MS-Windows 9X/NT.
-@item pc
-The frame is displayed on an MS-DOS terminal.
-@end table
-@end defun
-
-@menu
-* 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 makes the others hide it.
-* 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 X clients.
-* 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.
-@end menu
-
- @xref{Display}, for information about the related topic of
-controlling Emacs redisplay.
-
-@node Creating Frames
-@section Creating Frames
-
-To create a new frame, call the function @code{make-frame}.
-
-@defun make-frame &optional alist
-This function creates and returns a new frame, displaying the current
-buffer. If you are using a supported window system, it makes a window
-frame; otherwise, it makes a terminal frame.
-
-The argument is an alist specifying frame parameters. Any parameters
-not mentioned in @var{alist} default according to the value of the
-variable @code{default-frame-alist}; parameters not specified even there
-default from the standard X resources or whatever is used instead on
-your system.
-
-The set of possible parameters depends in principle on what kind of
-window system Emacs uses to display its frames. @xref{Window Frame
-Parameters}, for documentation of individual parameters you can specify.
-
-This function itself does not make the new frame the selected frame.
-@xref{Input Focus}. The previously selected frame remains selected.
-However, the window system may select the new frame for its own reasons,
-for instance if the frame appears under the mouse pointer and your
-setup is for focus to follow the pointer.
-@end defun
-
-@defvar before-make-frame-hook
-A normal hook run by @code{make-frame} before it actually creates the
-frame.
-@end defvar
-
-@defvar after-make-frame-functions
-An abnormal hook run by @code{make-frame} after it creates the frame.
-Each function in @code{after-make-frame-functions} receives one argument, the
-frame just created.
-@end defvar
-
-@node Multiple Displays
-@section Multiple Displays
-@cindex multiple X displays
-@cindex displays, multiple
-
- A single Emacs can talk to more than one X display.
-Initially, Emacs uses just one display---the one chosen with the
-@code{DISPLAY} environment variable or with the @samp{--display} option
-(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
-another display, use the command @code{make-frame-on-display} or specify
-the @code{display} frame parameter when you create the frame.
-
- Emacs treats each X server as a separate terminal, giving each one its
-own selected frame and its own minibuffer windows. However, only one of
-those frames is ``@emph{the} selected frame'' at any given moment, see
-@ref{Input Focus}.
-
- A few Lisp variables are @dfn{terminal-local}; that is, they have a
-separate binding for each terminal. The binding in effect at any time
-is the one for the terminal that the currently selected frame belongs
-to. These variables include @code{default-minibuffer-frame},
-@code{defining-kbd-macro}, @code{last-kbd-macro}, and
-@code{system-key-alist}. They are always terminal-local, and can never
-be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
-
- A single X server can handle more than one screen. A display name
-@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
-part specifies the screen number for a given server. When you use two
-screens belonging to one server, Emacs knows by the similarity in their
-names that they share a single keyboard, and it treats them as a single
-terminal.
-
- Note that some graphical terminals can output to more than a one
-monitor (or other output device) at the same time. On these
-``multi-monitor'' setups, a single @var{display} value controls the
-output to all the physical monitors. In this situation, there is
-currently no platform-independent way for Emacs to distinguish between
-the different physical monitors.
-
-@deffn Command make-frame-on-display display &optional parameters
-This creates and returns a new frame on display @var{display}, taking
-the other frame parameters from @var{parameters}. Aside from the
-@var{display} argument, it is like @code{make-frame} (@pxref{Creating
-Frames}).
-@end deffn
-
-@defun x-display-list
-This returns a list that indicates which X displays Emacs has a
-connection to. The elements of the list are strings, and each one is
-a display name.
-@end defun
-
-@defun x-open-connection display &optional xrm-string must-succeed
-This function opens a connection to the X display @var{display}. It
-does not create a frame on that display, but it permits you to check
-that communication can be established with that display.
-
-The optional argument @var{xrm-string}, if not @code{nil}, is a
-string of resource names and values, in the same format used in the
-@file{.Xresources} file. The values you specify override the resource
-values recorded in the X server itself; they apply to all Emacs frames
-created on this display. Here's an example of what this string might
-look like:
-
-@example
-"*BorderWidth: 3\n*InternalBorder: 2\n"
-@end example
-
-@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
-
-If @var{must-succeed} is non-@code{nil}, failure to open the connection
-terminates Emacs. Otherwise, it is an ordinary Lisp error.
-@end defun
-
-@defun x-close-connection display
-This function closes the connection to display @var{display}. Before
-you can do this, you must first delete all the frames that were open on
-that display (@pxref{Deleting Frames}).
-@end defun
-
-@node Frame Parameters
-@section Frame Parameters
-@cindex frame parameters
-
- A frame has many parameters that control its appearance and behavior.
-Just what parameters a frame has depends on what display mechanism it
-uses.
-
- Frame parameters exist mostly for the sake of window systems. A
-terminal frame has a few parameters, mostly for compatibility's sake;
-only the @code{height}, @code{width}, @code{name}, @code{title},
-@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
-parameters do something special. If the terminal supports colors, the
-parameters @code{foreground-color}, @code{background-color},
-@code{background-mode} and @code{display-type} are also meaningful.
-
-@menu
-* 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.
-@end menu
-
-@node Parameter Access
-@subsection Access to Frame Parameters
-
-These functions let you read and change the parameter values of a
-frame.
-
-@defun frame-parameter frame parameter
-This function returns the value of the parameter @var{parameter} (a
-symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
-selected frame's parameter. If @var{frame} has no setting for
-@var{parameter}, this function returns @code{nil}.
-@end defun
-
-@defun frame-parameters &optional frame
-The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values. If @var{frame} is
-@code{nil} or omitted, this returns the selected frame's parameters
-@end defun
-
-@defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-elements of @var{alist}. Each element of @var{alist} has the form
-@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
-parameter. If you don't mention a parameter in @var{alist}, its value
-doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
-frame.
-@end defun
-
-@defun modify-all-frames-parameters alist
-This function alters the frame parameters of all existing frames
-according to @var{alist}, then modifies @code{default-frame-alist}
-(and, if necessary, @code{initial-frame-alist}) to apply the same
-parameter values to frames that will be created henceforth.
-@end defun
-
-@node Initial Parameters
-@subsection Initial Frame Parameters
-
-You can specify the parameters for the initial startup frame
-by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
-
-@defvar initial-frame-alist
-This variable's value is an alist of parameter values used when creating
-the initial window frame. You can set this variable to specify the
-appearance of the initial frame without altering subsequent frames.
-Each element has the form:
-
-@example
-(@var{parameter} . @var{value})
-@end example
-
-Emacs creates the initial frame before it reads your init
-file. After reading that file, Emacs checks @code{initial-frame-alist},
-and applies the parameter settings in the altered value to the already
-created initial frame.
-
-If these settings affect the frame geometry and appearance, you'll see
-the frame appear with the wrong ones and then change to the specified
-ones. If that bothers you, you can specify the same geometry and
-appearance with X resources; those do take effect before the frame is
-created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
-
-X resource settings typically apply to all frames. If you want to
-specify some X resources solely for the sake of the initial frame, and
-you don't want them to apply to subsequent frames, here's how to achieve
-this. Specify parameters in @code{default-frame-alist} to override the
-X resources for subsequent frames; then, to prevent these from affecting
-the initial frame, specify the same parameters in
-@code{initial-frame-alist} with values that match the X resources.
-@end defvar
-
-If these parameters specify a separate minibuffer-only frame with
-@code{(minibuffer . nil)}, and you have not created one, Emacs creates
-one for you.
-
-@defvar minibuffer-frame-alist
-This variable's value is an alist of parameter values used when creating
-an initial minibuffer-only frame---if such a frame is needed, according
-to the parameters for the main initial frame.
-@end defvar
-
-@defvar default-frame-alist
-This is an alist specifying default values of frame parameters for all
-Emacs frames---the first frame, and subsequent frames. When using the X
-Window System, you can get the same results by means of X resources
-in many cases.
-
-Setting this variable does not affect existing frames.
-@end defvar
-
-See also @code{special-display-frame-alist}. @xref{Definition of
-special-display-frame-alist}.
-
-If you use options that specify window appearance when you invoke Emacs,
-they take effect by adding elements to @code{default-frame-alist}. One
-exception is @samp{-geometry}, which adds the specified position to
-@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
-Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
-
-@node Window Frame Parameters
-@subsection Window Frame Parameters
-
- Just what parameters a frame has depends on what display mechanism
-it uses. This section describes the parameters that have special
-meanings on some or all kinds of terminals. Of these, @code{name},
-@code{title}, @code{height}, @code{width}, @code{buffer-list} and
-@code{buffer-predicate} provide meaningful information in terminal
-frames, and @code{tty-color-mode} is meaningful @emph{only} in
-terminal frames.
-
-@menu
-* 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.
-@end menu
-
-@node Basic Parameters
-@subsubsection Basic Parameters
-
- These frame parameters give the most basic information about the
-frame. @code{title} and @code{name} are meaningful on all terminals.
-
-@table @code
-@item display
-The display on which to open this frame. It should be a string of the
-form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@code{DISPLAY} environment variable.
-
-@item display-type
-This parameter describes the range of possible colors that can be used
-in this frame. Its value is @code{color}, @code{grayscale} or
-@code{mono}.
-
-@item title
-If a frame has a non-@code{nil} title, it appears in the window system's
-border for the frame, and also in the mode line of windows in that frame
-if @code{mode-line-frame-identification} uses @samp{%F}
-(@pxref{%-Constructs}). This is normally the case when Emacs is not
-using a window system, and can only display one frame at a time.
-@xref{Frame Titles}.
-
-@item name
-The name of the frame. The frame name serves as a default for the frame
-title, if the @code{title} parameter is unspecified or @code{nil}. If
-you don't specify a name, Emacs sets the frame name automatically
-(@pxref{Frame Titles}).
-
-If you specify the frame name explicitly when you create the frame, the
-name is also used (instead of the name of the Emacs executable) when
-looking up X resources for the frame.
-
-@item display-environment-variable
-The value of the @code{DISPLAY} environment variable for the frame. It
-is passed to child processes.
-
-@item term-environment-variable
-The value of the @code{TERM} environment variable for the frame. It
-is passed to child processes.
-@end table
-
-@node Position Parameters
-@subsubsection Position Parameters
-
- Position parameters' values are normally measured in pixels, but on
-text-only terminals they count characters or lines instead.
-
-@table @code
-@item left
-The screen position of the left edge, in pixels, with respect to the
-left edge of the screen. The value may be a positive number @var{pos},
-or a list of the form @code{(+ @var{pos})} which permits specifying a
-negative @var{pos} value.
-
-A negative number @minus{}@var{pos}, or a list of the form @code{(-
-@var{pos})}, actually specifies the position of the right edge of the
-window with respect to the right edge of the screen. A positive value
-of @var{pos} counts toward the left. @strong{Reminder:} if the
-parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
-positive.
-
-Some window managers ignore program-specified positions. If you want to
-be sure the position you specify is not ignored, specify a
-non-@code{nil} value for the @code{user-position} parameter as well.
-
-@item top
-The screen position of the top edge, in pixels, with respect to the
-top edge of the screen. It works just like @code{left}, except vertically
-instead of horizontally.
-
-@item icon-left
-The screen position of the left edge @emph{of the frame's icon}, in
-pixels, counting from the left edge of the screen. This takes effect if
-and when the frame is iconified.
-
-If you specify a value for this parameter, then you must also specify
-a value for @code{icon-top} and vice versa. The window manager may
-ignore these two parameters.
-
-@item icon-top
-The screen position of the top edge @emph{of the frame's icon}, in
-pixels, counting from the top edge of the screen. This takes effect if
-and when the frame is iconified.
-
-@item user-position
-When you create a frame and specify its screen position with the
-@code{left} and @code{top} parameters, use this parameter to say whether
-the specified position was user-specified (explicitly requested in some
-way by a human user) or merely program-specified (chosen by a program).
-A non-@code{nil} value says the position was user-specified.
-
-Window managers generally heed user-specified positions, and some heed
-program-specified positions too. But many ignore program-specified
-positions, placing the window in a default fashion or letting the user
-place it with the mouse. Some window managers, including @code{twm},
-let the user specify whether to obey program-specified positions or
-ignore them.
-
-When you call @code{make-frame}, you should specify a non-@code{nil}
-value for this parameter if the values of the @code{left} and @code{top}
-parameters represent the user's stated preference; otherwise, use
-@code{nil}.
-@end table
-
-@node Size Parameters
-@subsubsection Size Parameters
-
- Size parameters' values are normally measured in pixels, but on
-text-only terminals they count characters or lines instead.
-
-@table @code
-@item height
-The height of the frame contents, in characters. (To get the height in
-pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
-
-@item width
-The width of the frame contents, in characters. (To get the height in
-pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
-
-@item user-size
-This does for the size parameters @code{height} and @code{width} what
-the @code{user-position} parameter (see above) does for the position
-parameters @code{top} and @code{left}.
-
-@item fullscreen
-Specify that width, height or both shall be set to the size of the screen.
-The value @code{fullwidth} specifies that width shall be the size of the
-screen. The value @code{fullheight} specifies that height shall be the
-size of the screen. The value @code{fullboth} specifies that both the
-width and the height shall be set to the size of the screen.
-@end table
-
-@node Layout Parameters
-@subsubsection Layout Parameters
-
- These frame parameters enable or disable various parts of the
-frame, or control their sizes.
-
-@table @code
-@item border-width
-The width in pixels of the frame's border.
-
-@item internal-border-width
-The distance in pixels between text (or fringe) and the frame's border.
-
-@item vertical-scroll-bars
-Whether the frame has scroll bars for vertical scrolling, and which side
-of the frame they should be on. The possible values are @code{left},
-@code{right}, and @code{nil} for no scroll bars.
-
-@ignore
-@item horizontal-scroll-bars
-Whether the frame has scroll bars for horizontal scrolling
-(non-@code{nil} means yes). Horizontal scroll bars are not currently
-implemented.
-@end ignore
-
-@item scroll-bar-width
-The width of vertical scroll bars, in pixels, or @code{nil} meaning to
-use the default width.
-
-@item left-fringe
-@itemx right-fringe
-The default width of the left and right fringes of windows in this
-frame (@pxref{Fringes}). If either of these is zero, that effectively
-removes the corresponding fringe. A value of @code{nil} stands for
-the standard fringe width, which is the width needed to display the
-fringe bitmaps.
-
-The combined fringe widths must add up to an integral number of
-columns, so the actual default fringe widths for the frame may be
-larger than the specified values. The extra width needed to reach an
-acceptable total is distributed evenly between the left and right
-fringe. However, you can force one fringe or the other to a precise
-width by specifying that width as a negative integer. If both widths are
-negative, only the left fringe gets the specified width.
-
-@item menu-bar-lines
-The number of lines to allocate at the top of the frame for a menu
-bar. The default is 1. A value of @code{nil} means don't display a
-menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
-menu bar line; they treat larger values as 1.)
-
-@item tool-bar-lines
-The number of lines to use for the tool bar. A value of @code{nil}
-means don't display a tool bar. (GTK allows at most one tool bar line;
-it treats larger values as 1.)
-
-@item line-spacing
-Additional space to leave below each text line, in pixels (a positive
-integer). @xref{Line Height}, for more information.
-@end table
-
-@node Buffer Parameters
-@subsubsection Buffer Parameters
-
- These frame parameters, meaningful on all kinds of terminals, deal
-with which buffers have been, or should, be displayed in the frame.
-
-@table @code
-@item minibuffer
-Whether this frame has its own minibuffer. The value @code{t} means
-yes, @code{nil} means no, @code{only} means this frame is just a
-minibuffer. If the value is a minibuffer window (in some other frame),
-the new frame uses that minibuffer.
-
-@item buffer-predicate
-The buffer-predicate function for this frame. The function
-@code{other-buffer} uses this predicate (from the selected frame) to
-decide which buffers it should consider, if the predicate is not
-@code{nil}. It calls the predicate with one argument, a buffer, once for
-each buffer; if the predicate returns a non-@code{nil} value, it
-considers that buffer.
-
-@item buffer-list
-A list of buffers that have been selected in this frame,
-ordered most-recently-selected first.
-
-@item unsplittable
-If non-@code{nil}, this frame's window is never split automatically.
-@end table
-
-@node Management Parameters
-@subsubsection Window Management Parameters
-@cindex window manager, and frame parameters
-
- These frame parameters, meaningful only on window system displays,
-interact with the window manager.
-
-@table @code
-@item visibility
-The state of visibility of the frame. There are three possibilities:
-@code{nil} for invisible, @code{t} for visible, and @code{icon} for
-iconified. @xref{Visibility of Frames}.
-
-@item auto-raise
-Whether selecting the frame raises it (non-@code{nil} means yes).
-
-@item auto-lower
-Whether deselecting the frame lowers it (non-@code{nil} means yes).
-
-@item icon-type
-The type of icon to use for this frame when it is iconified. If the
-value is a string, that specifies a file containing a bitmap to use.
-Any other non-@code{nil} value specifies the default bitmap icon (a
-picture of a gnu); @code{nil} specifies a text icon.
-
-@item icon-name
-The name to use in the icon for this frame, when and if the icon
-appears. If this is @code{nil}, the frame's title is used.
-
-@item window-id
-The number of the window-system window used by the frame
-to contain the actual Emacs windows.
-
-@item outer-window-id
-The number of the outermost window-system window used for the whole frame.
-
-@item wait-for-wm
-If non-@code{nil}, tell Xt to wait for the window manager to confirm
-geometry changes. Some window managers, including versions of Fvwm2
-and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
-prevent hanging with those window managers.
-
-@ignore
-@item parent-id
-@c ??? Not yet working.
-The X window number of the window that should be the parent of this one.
-Specifying this lets you create an Emacs window inside some other
-application's window. (It is not certain this will be implemented; try
-it and see if it works.)
-@end ignore
-@end table
-
-@node Cursor Parameters
-@subsubsection Cursor Parameters
-
- This frame parameter controls the way the cursor looks.
-
-@table @code
-@item cursor-type
-How to display the cursor. Legitimate values are:
-
-@table @code
-@item box
-Display a filled box. (This is the default.)
-@item hollow
-Display a hollow box.
-@item nil
-Don't display a cursor.
-@item bar
-Display a vertical bar between characters.
-@item (bar . @var{width})
-Display a vertical bar @var{width} pixels wide between characters.
-@item hbar
-Display a horizontal bar.
-@item (hbar . @var{height})
-Display a horizontal bar @var{height} pixels high.
-@end table
-@end table
-
-@vindex cursor-type
-The buffer-local variable @code{cursor-type} overrides the value of
-the @code{cursor-type} frame parameter, but if it is @code{t}, that
-means to use the cursor specified for the frame.
-
-@defvar blink-cursor-alist
-This variable specifies how to blink the cursor. Each element has the
-form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
-type equals @var{on-state} (comparing using @code{equal}), the
-corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off.'' Both @var{on-state} and @var{off-state}
-should be suitable values for the @code{cursor-type} frame parameter.
-
-There are various defaults for how to blink each type of cursor, if
-the type is not mentioned as an @var{on-state} here. Changes in this
-variable do not take effect immediately, because the variable is
-examined only when you specify the @code{cursor-type} parameter.
-@end defvar
-
-@node Color Parameters
-@subsubsection Color Parameters
-
- These frame parameters control the use of colors.
-
-@table @code
-@item background-mode
-This parameter is either @code{dark} or @code{light}, according
-to whether the background color is a light one or a dark one.
-
-@item tty-color-mode
-@cindex standard colors for character terminals
-This parameter overrides the terminal's color support as given by the
-system's terminal capabilities database in that this parameter's value
-specifies the color mode to use in terminal frames. The value can be
-either a symbol or a number. A number specifies the number of colors
-to use (and, indirectly, what commands to issue to produce each
-color). For example, @code{(tty-color-mode . 8)} specifies use of the
-ANSI escape sequences for 8 standard text colors. A value of -1 turns
-off color support.
-
-If the parameter's value is a symbol, it specifies a number through
-the value of @code{tty-color-mode-alist}, and the associated number is
-used instead.
-
-@item screen-gamma
-@cindex gamma correction
-If this is a number, Emacs performs ``gamma correction'' which adjusts
-the brightness of all colors. The value should be the screen gamma of
-your display, a floating point number.
-
-Usual PC monitors have a screen gamma of 2.2, so color values in
-Emacs, and in X windows generally, are calibrated to display properly
-on a monitor with that gamma value. If you specify 2.2 for
-@code{screen-gamma}, that means no correction is needed. Other values
-request correction, designed to make the corrected colors appear on
-your screen the way they would have appeared without correction on an
-ordinary monitor with a gamma value of 2.2.
-
-If your monitor displays colors too light, you should specify a
-@code{screen-gamma} value smaller than 2.2. This requests correction
-that makes colors darker. A screen gamma value of 1.5 may give good
-results for LCD color displays.
-@end table
-
-These frame parameters are semi-obsolete in that they are automatically
-equivalent to particular face attributes of particular faces.
-@xref{Standard Faces,,, emacs, The Emacs Manual}.
-
-@table @code
-@item font
-The name of the font for displaying text in the frame. This is a
-string, either a valid font name for your system or the name of an Emacs
-fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
-attribute of the @code{default} face.
-
-@item foreground-color
-The color to use for the image of a character. It is equivalent to
-the @code{:foreground} attribute of the @code{default} face.
-
-@item background-color
-The color to use for the background of characters. It is equivalent to
-the @code{:background} attribute of the @code{default} face.
-
-@item mouse-color
-The color for the mouse pointer. It is equivalent to the @code{:background}
-attribute of the @code{mouse} face.
-
-@item cursor-color
-The color for the cursor that shows point. It is equivalent to the
-@code{:background} attribute of the @code{cursor} face.
-
-@item border-color
-The color for the border of the frame. It is equivalent to the
-@code{:background} attribute of the @code{border} face.
-
-@item scroll-bar-foreground
-If non-@code{nil}, the color for the foreground of scroll bars. It is
-equivalent to the @code{:foreground} attribute of the
-@code{scroll-bar} face.
-
-@item scroll-bar-background
-If non-@code{nil}, the color for the background of scroll bars. It is
-equivalent to the @code{:background} attribute of the
-@code{scroll-bar} face.
-@end table
-
-@node Size and Position
-@subsection Frame Size And Position
-@cindex size of frame
-@cindex screen size
-@cindex frame size
-@cindex resize frame
-
- You can read or change the size and position of a frame using the
-frame parameters @code{left}, @code{top}, @code{height}, and
-@code{width}. Whatever geometry parameters you don't specify are chosen
-by the window manager in its usual fashion.
-
- Here are some special features for working with sizes and positions.
-(For the precise meaning of ``selected frame'' used by these functions,
-see @ref{Input Focus}.)
-
-@defun set-frame-position frame left top
-This function sets the position of the top left corner of @var{frame} to
-@var{left} and @var{top}. These arguments are measured in pixels, and
-normally count from the top left corner of the screen.
-
-Negative parameter values position the bottom edge of the window up from
-the bottom edge of the screen, or the right window edge to the left of
-the right edge of the screen. It would probably be better if the values
-were always counted from the left and top, so that negative arguments
-would position the frame partly off the top or left edge of the screen,
-but it seems inadvisable to change that now.
-@end defun
-
-@defun frame-height &optional frame
-@defunx frame-width &optional frame
-These functions return the height and width of @var{frame}, measured in
-lines and columns. If you don't supply @var{frame}, they use the
-selected frame.
-@end defun
-
-@defun screen-height
-@defunx screen-width
-These functions are old aliases for @code{frame-height} and
-@code{frame-width}. When you are using a non-window terminal, the size
-of the frame is normally the same as the size of the terminal screen.
-@end defun
-
-@defun frame-pixel-height &optional frame
-@defunx frame-pixel-width &optional frame
-These functions return the height and width of @var{frame}, measured in
-pixels. If you don't supply @var{frame}, they use the selected frame.
-@end defun
-
-@defun frame-char-height &optional frame
-@defunx frame-char-width &optional frame
-These functions return the height and width of a character in
-@var{frame}, measured in pixels. The values depend on the choice of
-font. If you don't supply @var{frame}, these functions use the selected
-frame.
-@end defun
-
-@defun set-frame-size frame cols rows
-This function sets the size of @var{frame}, measured in characters;
-@var{cols} and @var{rows} specify the new width and height.
-
-To set the size based on values measured in pixels, use
-@code{frame-char-height} and @code{frame-char-width} to convert
-them to units of characters.
-@end defun
-
-@defun set-frame-height frame lines &optional pretend
-This function resizes @var{frame} to a height of @var{lines} lines. The
-sizes of existing windows in @var{frame} are altered proportionally to
-fit.
-
-If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
-lines of output in @var{frame}, but does not change its value for the
-actual height of the frame. This is only useful for a terminal frame.
-Using a smaller height than the terminal actually implements may be
-useful to reproduce behavior observed on a smaller screen, or if the
-terminal malfunctions when using its whole screen. Setting the frame
-height ``for real'' does not always work, because knowing the correct
-actual size may be necessary for correct cursor positioning on a
-terminal frame.
-@end defun
-
-@defun set-frame-width frame width &optional pretend
-This function sets the width of @var{frame}, measured in characters.
-The argument @var{pretend} has the same meaning as in
-@code{set-frame-height}.
-@end defun
-
-@findex set-screen-height
-@findex set-screen-width
- The older functions @code{set-screen-height} and
-@code{set-screen-width} were used to specify the height and width of the
-screen, in Emacs versions that did not support multiple frames. They
-are semi-obsolete, but still work; they apply to the selected frame.
-
-@node Geometry
-@subsection Geometry
-
- Here's how to examine the data in an X-style window geometry
-specification:
-
-@defun x-parse-geometry geom
-@cindex geometry specification
-The function @code{x-parse-geometry} converts a standard X window
-geometry string to an alist that you can use as part of the argument to
-@code{make-frame}.
-
-The alist describes which parameters were specified in @var{geom}, and
-gives the values specified for them. Each element looks like
-@code{(@var{parameter} . @var{value})}. The possible @var{parameter}
-values are @code{left}, @code{top}, @code{width}, and @code{height}.
-
-For the size parameters, the value must be an integer. The position
-parameter names @code{left} and @code{top} are not totally accurate,
-because some values indicate the position of the right or bottom edges
-instead. These are the @var{value} possibilities for the position
-parameters:
-
-@table @asis
-@item an integer
-A positive integer relates the left edge or top edge of the window to
-the left or top edge of the screen. A negative integer relates the
-right or bottom edge of the window to the right or bottom edge of the
-screen.
-
-@item @code{(+ @var{position})}
-This specifies the position of the left or top edge of the window
-relative to the left or top edge of the screen. The integer
-@var{position} may be positive or negative; a negative value specifies a
-position outside the screen.
-
-@item @code{(- @var{position})}
-This specifies the position of the right or bottom edge of the window
-relative to the right or bottom edge of the screen. The integer
-@var{position} may be positive or negative; a negative value specifies a
-position outside the screen.
-@end table
-
-Here is an example:
-
-@example
-(x-parse-geometry "35x70+0-0")
- @result{} ((height . 70) (width . 35)
- (top - 0) (left . 0))
-@end example
-@end defun
-
-@node Frame Titles
-@section Frame Titles
-@cindex frame title
-
- Every frame has a @code{name} parameter; this serves as the default
-for the frame title which window systems typically display at the top of
-the frame. You can specify a name explicitly by setting the @code{name}
-frame property.
-
- Normally you don't specify the name explicitly, and Emacs computes the
-frame name automatically based on a template stored in the variable
-@code{frame-title-format}. Emacs recomputes the name each time the
-frame is redisplayed.
-
-@defvar frame-title-format
-This variable specifies how to compute a name for a frame when you have
-not explicitly specified one. The variable's value is actually a mode
-line construct, just like @code{mode-line-format}, except that the
-@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
-Data}.
-@end defvar
-
-@defvar icon-title-format
-This variable specifies how to compute the name for an iconified frame,
-when you have not explicitly specified the frame title. This title
-appears in the icon itself.
-@end defvar
-
-@defvar multiple-frames
-This variable is set automatically by Emacs. Its value is @code{t} when
-there are two or more frames (not counting minibuffer-only frames or
-invisible frames). The default value of @code{frame-title-format} uses
-@code{multiple-frames} so as to put the buffer name in the frame title
-only when there is more than one frame.
-
-The value of this variable is not guaranteed to be accurate except
-while processing @code{frame-title-format} or
-@code{icon-title-format}.
-@end defvar
-
-@node Deleting Frames
-@section Deleting Frames
-@cindex deleting frames
-
-Frames remain potentially visible until you explicitly @dfn{delete}
-them. A deleted frame cannot appear on the screen, but continues to
-exist as a Lisp object until there are no references to it.
-
-@deffn Command delete-frame &optional frame force
-@vindex delete-frame-functions
-This function deletes the frame @var{frame}. Unless @var{frame} is a
-tooltip, it first runs the hook @code{delete-frame-functions} (each
-function gets one argument, @var{frame}). By default, @var{frame} is
-the selected frame.
-
-A frame cannot be deleted if its minibuffer is used by other frames.
-Normally, you cannot delete a frame if all other frames are invisible,
-but if the @var{force} is non-@code{nil}, then you are allowed to do so.
-@end deffn
-
-@defun frame-live-p frame
-The function @code{frame-live-p} returns non-@code{nil} if the frame
-@var{frame} has not been deleted. The possible non-@code{nil} return
-values are like those of @code{framep}. @xref{Frames}.
-@end defun
-
- Some window managers provide a command to delete a window. These work
-by sending a special message to the program that operates the window.
-When Emacs gets one of these commands, it generates a
-@code{delete-frame} event, whose normal definition is a command that
-calls the function @code{delete-frame}. @xref{Misc Events}.
-
-@node Finding All Frames
-@section Finding All Frames
-@cindex frames, scanning all
-
-@defun frame-list
-The function @code{frame-list} returns a list of all the frames that
-have not been deleted. It is analogous to @code{buffer-list} for
-buffers, and includes frames on all terminals. The list that you get is
-newly created, so modifying the list doesn't have any effect on the
-internals of Emacs.
-@end defun
-
-@defun visible-frame-list
-This function returns a list of just the currently visible frames.
-@xref{Visibility of Frames}. (Terminal frames always count as
-``visible,'' even though only the selected one is actually displayed.)
-@end defun
-
-@defun next-frame &optional frame minibuf
-The function @code{next-frame} lets you cycle conveniently through all
-the frames on the current display from an arbitrary starting point. It
-returns the ``next'' frame after @var{frame} in the cycle. If
-@var{frame} is omitted or @code{nil}, it defaults to the selected frame
-(@pxref{Input Focus}).
-
-The second argument, @var{minibuf}, says which frames to consider:
-
-@table @asis
-@item @code{nil}
-Exclude minibuffer-only frames.
-@item @code{visible}
-Consider all visible frames.
-@item 0
-Consider all visible or iconified frames.
-@item a window
-Consider only the frames using that particular window as their
-minibuffer.
-@item anything else
-Consider all frames.
-@end table
-@end defun
-
-@defun previous-frame &optional frame minibuf
-Like @code{next-frame}, but cycles through all frames in the opposite
-direction.
-@end defun
-
- See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
-Window Ordering}.
-
-@node Frames and Windows
-@section Frames and Windows
-
- Each window is part of one and only one frame; you can get the frame
-with @code{window-frame}.
-
-@defun window-frame window
-This function returns the frame that @var{window} is on.
-@end defun
-
- All the non-minibuffer windows in a frame are arranged in a cyclic
-order. The order runs from the frame's top window, which is at the
-upper left corner, down and to the right, until it reaches the window at
-the lower right corner (always the minibuffer window, if the frame has
-one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
-
-@defun frame-first-window &optional frame
-This returns the topmost, leftmost window of frame @var{frame}.
-If omitted or @code{nil}, @var{frame} defaults to the selected frame.
-@end defun
-
-At any time, exactly one window on any frame is @dfn{selected within the
-frame}. The significance of this designation is that selecting the
-frame also selects this window. You can get the frame's current
-selected window with @code{frame-selected-window}.
-
-@defun frame-selected-window &optional frame
-This function returns the window on @var{frame} that is selected
-within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
-the selected frame.
-@end defun
-
-@defun set-frame-selected-window frame window
-This sets the selected window of frame @var{frame} to @var{window}.
-If @var{frame} is @code{nil}, it operates on the selected frame. If
-@var{frame} is the selected frame, this makes @var{window} the
-selected window. This function returns @var{window}.
-@end defun
-
- Conversely, selecting a window for Emacs with @code{select-window} also
-makes that window selected within its frame. @xref{Selecting Windows}.
-
- Another function that (usually) returns one of the windows in a given
-frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
-
-@node Minibuffers and Frames
-@section Minibuffers and Frames
-
-Normally, each frame has its own minibuffer window at the bottom, which
-is used whenever that frame is selected. If the frame has a minibuffer,
-you can get it with @code{minibuffer-window} (@pxref{Definition of
-minibuffer-window}).
-
-However, you can also create a frame with no minibuffer. Such a frame
-must use the minibuffer window of some other frame. When you create the
-frame, you can specify explicitly the minibuffer window to use (in some
-other frame). If you don't, then the minibuffer is found in the frame
-which is the value of the variable @code{default-minibuffer-frame}. Its
-value should be a frame that does have a minibuffer.
-
-If you use a minibuffer-only frame, you might want that frame to raise
-when you enter the minibuffer. If so, set the variable
-@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
-
-@defvar default-minibuffer-frame
-This variable specifies the frame to use for the minibuffer window, by
-default. It does not affect existing frames. It is always local to
-the current terminal and cannot be buffer-local. @xref{Multiple
-Displays}.
-@end defvar
-
-@node Input Focus
-@section Input Focus
-@cindex input focus
-@c @cindex selected frame Duplicates selected-frame
-
-At any time, one frame in Emacs is the @dfn{selected frame}. The selected
-window always resides on the selected frame.
-
-When Emacs displays its frames on several terminals (@pxref{Multiple
-Displays}), each terminal has its own selected frame. But only one of
-these is ``@emph{the} selected frame'': it's the frame that belongs to
-the terminal from which the most recent input came. That is, when Emacs
-runs a command that came from a certain terminal, the selected frame is
-the one of that terminal. Since Emacs runs only a single command at any
-given time, it needs to consider only one selected frame at a time; this
-frame is what we call @dfn{the selected frame} in this manual. The
-display on which the selected frame is displayed is the @dfn{selected
-frame's display}.
-
-@defun selected-frame
-This function returns the selected frame.
-@end defun
-
-Some window systems and window managers direct keyboard input to the
-window object that the mouse is in; others require explicit clicks or
-commands to @dfn{shift the focus} to various window objects. Either
-way, Emacs automatically keeps track of which frame has the focus. To
-switch to a different frame from a Lisp function, call
-@code{select-frame-set-input-focus}.
-
-Lisp programs can also switch frames ``temporarily'' by calling the
-function @code{select-frame}. This does not alter the window system's
-concept of focus; rather, it escapes from the window manager's control
-until that control is somehow reasserted.
-
-When using a text-only terminal, only one frame can be displayed at a
-time on the terminal, so after a call to @code{select-frame}, the next
-redisplay actually displays the newly selected frame. This frame
-remains selected until a subsequent call to @code{select-frame} or
-@code{select-frame-set-input-focus}. Each terminal frame has a number
-which appears in the mode line before the buffer name (@pxref{Mode
-Line Variables}).
-
-@defun select-frame-set-input-focus frame
-This function makes @var{frame} the selected frame, raises it (should
-it happen to be obscured by other frames) and tries to give it the X
-server's focus. On a text-only terminal, the next redisplay displays
-the new frame on the entire terminal screen. The return value of this
-function is not significant.
-@end defun
-
-@c ??? This is not yet implemented properly.
-@defun select-frame frame
-This function selects frame @var{frame}, temporarily disregarding the
-focus of the X server if any. The selection of @var{frame} lasts until
-the next time the user does something to select a different frame, or
-until the next time this function is called. (If you are using a
-window system, the previously selected frame may be restored as the
-selected frame after return to the command loop, because it still may
-have the window system's input focus.) The specified @var{frame}
-becomes the selected frame, as explained above, and the terminal that
-@var{frame} is on becomes the selected terminal. This function
-returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
-
-In general, you should never use @code{select-frame} in a way that could
-switch to a different terminal without switching back when you're done.
-@end defun
-
-Emacs cooperates with the window system by arranging to select frames as
-the server and window manager request. It does so by generating a
-special kind of input event, called a @dfn{focus} event, when
-appropriate. The command loop handles a focus event by calling
-@code{handle-switch-frame}. @xref{Focus Events}.
-
-@deffn Command handle-switch-frame frame
-This function handles a focus event by selecting frame @var{frame}.
-
-Focus events normally do their job by invoking this command.
-Don't call it for any other reason.
-@end deffn
-
-@defun redirect-frame-focus frame &optional focus-frame
-This function redirects focus from @var{frame} to @var{focus-frame}.
-This means that @var{focus-frame} will receive subsequent keystrokes and
-events intended for @var{frame}. After such an event, the value of
-@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
-events specifying @var{frame} will instead select @var{focus-frame}.
-
-If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
-redirection for @var{frame}, which therefore once again receives its own
-events.
-
-One use of focus redirection is for frames that don't have minibuffers.
-These frames use minibuffers on other frames. Activating a minibuffer
-on another frame redirects focus to that frame. This puts the focus on
-the minibuffer's frame, where it belongs, even though the mouse remains
-in the frame that activated the minibuffer.
-
-Selecting a frame can also change focus redirections. Selecting frame
-@code{bar}, when @code{foo} had been selected, changes any redirections
-pointing to @code{foo} so that they point to @code{bar} instead. This
-allows focus redirection to work properly when the user switches from
-one frame to another using @code{select-window}.
-
-This means that a frame whose focus is redirected to itself is treated
-differently from a frame whose focus is not redirected.
-@code{select-frame} affects the former but not the latter.
-
-The redirection lasts until @code{redirect-frame-focus} is called to
-change it.
-@end defun
-
-@defopt focus-follows-mouse
-This option is how you inform Emacs whether the window manager transfers
-focus when the user moves the mouse. Non-@code{nil} says that it does.
-When this is so, the command @code{other-frame} moves the mouse to a
-position consistent with the new selected frame. (This option has no
-effect on MS-Windows, where the mouse pointer is always automatically
-moved by the OS to the selected frame.)
-@end defopt
-
-@node Visibility of Frames
-@section Visibility of Frames
-@cindex visible frame
-@cindex invisible frame
-@cindex iconified frame
-@cindex frame visibility
-
-A window frame may be @dfn{visible}, @dfn{invisible}, or
-@dfn{iconified}. If it is visible, you can see its contents, unless
-other windows cover it. If it is iconified, the frame's contents do
-not appear on the screen, but an icon does. If the frame is
-invisible, it doesn't show on the screen, not even as an icon.
-
-Visibility is meaningless for terminal frames, since only the selected
-one is actually displayed in any case.
-
-@deffn Command make-frame-visible &optional frame
-This function makes frame @var{frame} visible. If you omit
-@var{frame}, it makes the selected frame visible. This does not raise
-the frame, but you can do that with @code{raise-frame} if you wish
-(@pxref{Raising and Lowering}).
-@end deffn
-
-@deffn Command make-frame-invisible &optional frame force
-This function makes frame @var{frame} invisible. If you omit
-@var{frame}, it makes the selected frame invisible.
-
-Unless @var{force} is non-@code{nil}, this function refuses to make
-@var{frame} invisible if all other frames are invisible..
-@end deffn
-
-@deffn Command iconify-frame &optional frame
-This function iconifies frame @var{frame}. If you omit @var{frame}, it
-iconifies the selected frame.
-@end deffn
-
-@defun frame-visible-p frame
-This returns the visibility status of frame @var{frame}. The value is
-@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
-@code{icon} if it is iconified.
-
-On a text-only terminal, all frames are considered visible, whether
-they are currently being displayed or not, and this function returns
-@code{t} for all frames.
-@end defun
-
- The visibility status of a frame is also available as a frame
-parameter. You can read or change it as such. @xref{Management
-Parameters}.
-
- The user can iconify and deiconify frames with the window manager.
-This happens below the level at which Emacs can exert any control, but
-Emacs does provide events that you can use to keep track of such
-changes. @xref{Misc Events}.
-
-@node Raising and Lowering
-@section Raising and Lowering Frames
-
- Most window systems use a desktop metaphor. Part of this metaphor is
-the idea that windows are stacked in a notional third dimension
-perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest.'' Where two windows overlap, the one higher up covers
-the one underneath. Even a window at the bottom of the stack can be
-seen if no other window overlaps it.
-
-@c @cindex raising a frame redundant with raise-frame
-@cindex lowering a frame
- A window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently. @dfn{Raising} a window means moving
-it ``up,'' to the top of the stack. @dfn{Lowering} a window means
-moving it to the bottom of the stack. This motion is in the notional
-third dimension only, and does not change the position of the window
-on the screen.
-
- You can raise and lower Emacs frame Windows with these functions:
-
-@deffn Command raise-frame &optional frame
-This function raises frame @var{frame} (default, the selected frame).
-If @var{frame} is invisible or iconified, this makes it visible.
-@end deffn
-
-@deffn Command lower-frame &optional frame
-This function lowers frame @var{frame} (default, the selected frame).
-@end deffn
-
-@defopt minibuffer-auto-raise
-If this is non-@code{nil}, activation of the minibuffer raises the frame
-that the minibuffer window is in.
-@end defopt
-
-You can also enable auto-raise (raising automatically when a frame is
-selected) or auto-lower (lowering automatically when it is deselected)
-for any frame using frame parameters. @xref{Management Parameters}.
-
-@node Frame Configurations
-@section Frame Configurations
-@cindex frame configuration
-
- A @dfn{frame configuration} records the current arrangement of frames,
-all their properties, and the window configuration of each one.
-(@xref{Window Configurations}.)
-
-@defun current-frame-configuration
-This function returns a frame configuration list that describes
-the current arrangement of frames and their contents.
-@end defun
-
-@defun set-frame-configuration configuration &optional nodelete
-This function restores the state of frames described in
-@var{configuration}. However, this function does not restore deleted
-frames.
-
-Ordinarily, this function deletes all existing frames not listed in
-@var{configuration}. But if @var{nodelete} is non-@code{nil}, the
-unwanted frames are iconified instead.
-@end defun
-
-@node Mouse Tracking
-@section Mouse Tracking
-@cindex mouse tracking
-@c @cindex tracking the mouse Duplicates track-mouse
-
- Sometimes it is useful to @dfn{track} the mouse, which means to display
-something to indicate where the mouse is and move the indicator as the
-mouse moves. For efficient mouse tracking, you need a way to wait until
-the mouse actually moves.
-
- The convenient way to track the mouse is to ask for events to represent
-mouse motion. Then you can wait for motion by waiting for an event. In
-addition, you can easily handle any other sorts of events that may
-occur. That is useful, because normally you don't want to track the
-mouse forever---only until some other event, such as the release of a
-button.
-
-@defspec track-mouse body@dots{}
-This special form executes @var{body}, with generation of mouse motion
-events enabled. Typically @var{body} would use @code{read-event} to
-read the motion events and modify the display accordingly. @xref{Motion
-Events}, for the format of mouse motion events.
-
-The value of @code{track-mouse} is that of the last form in @var{body}.
-You should design @var{body} to return when it sees the up-event that
-indicates the release of the button, or whatever kind of event means
-it is time to stop tracking.
-@end defspec
-
-The usual purpose of tracking mouse motion is to indicate on the screen
-the consequences of pushing or releasing a button at the current
-position.
-
-In many cases, you can avoid the need to track the mouse by using
-the @code{mouse-face} text property (@pxref{Special Properties}).
-That works at a much lower level and runs more smoothly than
-Lisp-level mouse tracking.
-
-@ignore
-@c These are not implemented yet.
-
-These functions change the screen appearance instantaneously. The
-effect is transient, only until the next ordinary Emacs redisplay. That
-is OK for mouse tracking, since it doesn't make sense for mouse tracking
-to change the text, and the body of @code{track-mouse} normally reads
-the events itself and does not do redisplay.
-
-@defun x-contour-region window beg end
-This function draws lines to make a box around the text from @var{beg}
-to @var{end}, in window @var{window}.
-@end defun
-
-@defun x-uncontour-region window beg end
-This function erases the lines that would make a box around the text
-from @var{beg} to @var{end}, in window @var{window}. Use it to remove
-a contour that you previously made by calling @code{x-contour-region}.
-@end defun
-
-@defun x-draw-rectangle frame left top right bottom
-This function draws a hollow rectangle on frame @var{frame} with the
-specified edge coordinates, all measured in pixels from the inside top
-left corner. It uses the cursor color, the one used for indicating the
-location of point.
-@end defun
-
-@defun x-erase-rectangle frame left top right bottom
-This function erases a hollow rectangle on frame @var{frame} with the
-specified edge coordinates, all measured in pixels from the inside top
-left corner. Erasure means redrawing the text and background that
-normally belong in the specified rectangle.
-@end defun
-@end ignore
-
-@node Mouse Position
-@section Mouse Position
-@cindex mouse position
-@cindex position of mouse
-
- The functions @code{mouse-position} and @code{set-mouse-position}
-give access to the current position of the mouse.
-
-@defun mouse-position
-This function returns a description of the position of the mouse. The
-value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x}
-and @var{y} are integers giving the position in characters relative to
-the top left corner of the inside of @var{frame}.
-@end defun
-
-@defvar mouse-position-function
-If non-@code{nil}, the value of this variable is a function for
-@code{mouse-position} to call. @code{mouse-position} calls this
-function just before returning, with its normal return value as the
-sole argument, and it returns whatever this function returns to it.
-
-This abnormal hook exists for the benefit of packages like
-@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
-@end defvar
-
-@defun set-mouse-position frame x y
-This function @dfn{warps the mouse} to position @var{x}, @var{y} in
-frame @var{frame}. The arguments @var{x} and @var{y} are integers,
-giving the position in characters relative to the top left corner of the
-inside of @var{frame}. If @var{frame} is not visible, this function
-does nothing. The return value is not significant.
-@end defun
-
-@defun mouse-pixel-position
-This function is like @code{mouse-position} except that it returns
-coordinates in units of pixels rather than units of characters.
-@end defun
-
-@defun set-mouse-pixel-position frame x y
-This function warps the mouse like @code{set-mouse-position} except that
-@var{x} and @var{y} are in units of pixels rather than units of
-characters. These coordinates are not required to be within the frame.
-
-If @var{frame} is not visible, this function does nothing. The return
-value is not significant.
-@end defun
-
-@need 3000
-
-@node Pop-Up Menus
-@section Pop-Up Menus
-
- When using a window system, a Lisp program can pop up a menu so that
-the user can choose an alternative with the mouse.
-
-@defun x-popup-menu position menu
-This function displays a pop-up menu and returns an indication of
-what selection the user makes.
-
-The argument @var{position} specifies where on the screen to put the
-top left corner of the menu. It can be either a mouse button event
-(which says to put the menu where the user actuated the button) or a
-list of this form:
-
-@example
-((@var{xoffset} @var{yoffset}) @var{window})
-@end example
-
-@noindent
-where @var{xoffset} and @var{yoffset} are coordinates, measured in
-pixels, counting from the top left corner of @var{window}. @var{window}
-may be a window or a frame.
-
-If @var{position} is @code{t}, it means to use the current mouse
-position. If @var{position} is @code{nil}, it means to precompute the
-key binding equivalents for the keymaps specified in @var{menu},
-without actually displaying or popping up the menu.
-
-The argument @var{menu} says what to display in the menu. It can be a
-keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
-return value is the list of events corresponding to the user's choice.
-(This list has more than one element if the choice occurred in a
-submenu.) Note that @code{x-popup-menu} does not actually execute the
-command bound to that sequence of events.
-
-Alternatively, @var{menu} can have the following form:
-
-@example
-(@var{title} @var{pane1} @var{pane2}...)
-@end example
-
-@noindent
-where each pane is a list of form
-
-@example
-(@var{title} @var{item1} @var{item2}...)
-@end example
-
-Each item should normally be a cons cell @code{(@var{line} . @var{value})},
-where @var{line} is a string, and @var{value} is the value to return if
-that @var{line} is chosen. An item can also be a string; this makes a
-non-selectable line in the menu.
-
-If the user gets rid of the menu without making a valid choice, for
-instance by clicking the mouse away from a valid choice or by typing
-keyboard input, then this normally results in a quit and
-@code{x-popup-menu} does not return. But if @var{position} is a mouse
-button event (indicating that the user invoked the menu with the
-mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
-@end defun
-
- @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
-if you could do the job with a prefix key defined with a menu keymap.
-If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
-a} can see the individual items in that menu and provide help for them.
-If instead you implement the menu by defining a command that calls
-@code{x-popup-menu}, the help facilities cannot know what happens inside
-that command, so they cannot give any help for the menu's items.
-
- The menu bar mechanism, which lets you switch between submenus by
-moving the mouse, cannot look within the definition of a command to see
-that it calls @code{x-popup-menu}. Therefore, if you try to implement a
-submenu using @code{x-popup-menu}, it cannot work with the menu bar in
-an integrated fashion. This is why all menu bar submenus are
-implemented with menu keymaps within the parent menu, and never with
-@code{x-popup-menu}. @xref{Menu Bar}.
-
- If you want a menu bar submenu to have contents that vary, you should
-still use a menu keymap to implement it. To make the contents vary, add
-a hook function to @code{menu-bar-update-hook} to update the contents of
-the menu keymap as necessary.
-
-@node Dialog Boxes
-@section Dialog Boxes
-@cindex dialog boxes
-
- A dialog box is a variant of a pop-up menu---it looks a little
-different, it always appears in the center of a frame, and it has just
-one level and one or more buttons. The main use of dialog boxes is
-for asking questions that the user can answer with ``yes,'' ``no,''
-and a few other alternatives. With a single button, they can also
-force the user to acknowledge important information. The functions
-@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
-keyboard, when called from commands invoked by mouse clicks.
-
-@defun x-popup-dialog position contents &optional header
-This function displays a pop-up dialog box and returns an indication of
-what selection the user makes. The argument @var{contents} specifies
-the alternatives to offer; it has this format:
-
-@example
-(@var{title} (@var{string} . @var{value})@dots{})
-@end example
-
-@noindent
-which looks like the list that specifies a single pane for
-@code{x-popup-menu}.
-
-The return value is @var{value} from the chosen alternative.
-
-As for @code{x-popup-menu}, an element of the list may be just a
-string instead of a cons cell @code{(@var{string} . @var{value})}.
-That makes a box that cannot be selected.
-
-If @code{nil} appears in the list, it separates the left-hand items from
-the right-hand items; items that precede the @code{nil} appear on the
-left, and items that follow the @code{nil} appear on the right. If you
-don't include a @code{nil} in the list, then approximately half the
-items appear on each side.
-
-Dialog boxes always appear in the center of a frame; the argument
-@var{position} specifies which frame. The possible values are as in
-@code{x-popup-menu}, but the precise coordinates or the individual
-window don't matter; only the frame matters.
-
-If @var{header} is non-@code{nil}, the frame title for the box is
-@samp{Information}, otherwise it is @samp{Question}. The former is used
-for @code{message-box} (@pxref{message-box}).
-
-In some configurations, Emacs cannot display a real dialog box; so
-instead it displays the same items in a pop-up menu in the center of the
-frame.
-
-If the user gets rid of the dialog box without making a valid choice,
-for instance using the window manager, then this produces a quit and
-@code{x-popup-dialog} does not return.
-@end defun
-
-@node Pointer Shape
-@section Pointer Shape
-@cindex pointer shape
-@cindex mouse pointer shape
-
- You can specify the mouse pointer style for particular text or
-images using the @code{pointer} text property, and for images with the
-@code{:pointer} and @code{:map} image properties. The values you can
-use in these properties are @code{text} (or @code{nil}), @code{arrow},
-@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
-@code{hourglass}. @code{text} stands for the usual mouse pointer
-style used over text.
-
- Over void parts of the window (parts that do not correspond to any
-of the buffer contents), the mouse pointer usually uses the
-@code{arrow} style, but you can specify a different style (one of
-those above) by setting @code{void-text-area-pointer}.
-
-@defvar void-text-area-pointer
-This variable specifies the mouse pointer style for void text areas.
-These include the areas after the end of a line or below the last line
-in the buffer. The default is to use the @code{arrow} (non-text)
-pointer style.
-@end defvar
-
- You can specify what the @code{text} pointer style really looks like
-by setting the variable @code{x-pointer-shape}.
-
-@defvar x-pointer-shape
-This variable specifies the pointer shape to use ordinarily in the
-Emacs frame, for the @code{text} pointer style.
-@end defvar
-
-@defvar x-sensitive-text-pointer-shape
-This variable specifies the pointer shape to use when the mouse
-is over mouse-sensitive text.
-@end defvar
-
- These variables affect newly created frames. They do not normally
-affect existing frames; however, if you set the mouse color of a
-frame, that also installs the current value of those two variables.
-@xref{Color Parameters}.
-
- The values you can use, to specify either of these pointer shapes, are
-defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
-@key{RET} x-pointer @key{RET}} to see a list of them.
-
-@node Window System Selections
-@section Window System Selections
-@cindex selection (for window systems)
-
-The X server records a set of @dfn{selections} which permit transfer of
-data between application programs. The various selections are
-distinguished by @dfn{selection types}, represented in Emacs by
-symbols. X clients including Emacs can read or set the selection for
-any given type.
-
-@deffn Command x-set-selection type data
-This function sets a ``selection'' in the X server. It takes two
-arguments: a selection type @var{type}, and the value to assign to it,
-@var{data}. If @var{data} is @code{nil}, it means to clear out the
-selection. Otherwise, @var{data} may be a string, a symbol, an integer
-(or a cons of two integers or list of two integers), an overlay, or a
-cons of two markers pointing to the same buffer. An overlay or a pair
-of markers stands for text in the overlay or between the markers.
-
-The argument @var{data} may also be a vector of valid non-vector
-selection values.
-
-Each possible @var{type} has its own selection value, which changes
-independently. The usual values of @var{type} are @code{PRIMARY},
-@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
-names, in accord with X Window System conventions. If @var{type} is
-@code{nil}, that stands for @code{PRIMARY}.
-
-This function returns @var{data}.
-@end deffn
-
-@defun x-get-selection &optional type data-type
-This function accesses selections set up by Emacs or by other X
-clients. It takes two optional arguments, @var{type} and
-@var{data-type}. The default for @var{type}, the selection type, is
-@code{PRIMARY}.
-
-The @var{data-type} argument specifies the form of data conversion to
-use, to convert the raw data obtained from another X client into Lisp
-data. Meaningful values include @code{TEXT}, @code{STRING},
-@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
-@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
-@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
-@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
-@code{INTEGER}. (These are symbols with upper-case names in accord
-with X conventions.) The default for @var{data-type} is
-@code{STRING}.
-@end defun
-
-@cindex cut buffer
-The X server also has a set of eight numbered @dfn{cut buffers} which can
-store text or other data being moved between applications. Cut buffers
-are considered obsolete, but Emacs supports them for the sake of X
-clients that still use them. Cut buffers are numbered from 0 to 7.
-
-@defun x-get-cut-buffer &optional n
-This function returns the contents of cut buffer number @var{n}.
-If omitted @var{n} defaults to 0.
-@end defun
-
-@defun x-set-cut-buffer string &optional push
-@anchor{Definition of x-set-cut-buffer}
-This function stores @var{string} into the first cut buffer (cut buffer
-0). If @var{push} is @code{nil}, only the first cut buffer is changed.
-If @var{push} is non-@code{nil}, that says to move the values down
-through the series of cut buffers, much like the way successive kills in
-Emacs move down the kill ring. In other words, the previous value of
-the first cut buffer moves into the second cut buffer, and the second to
-the third, and so on through all eight cut buffers.
-@end defun
-
-@defvar selection-coding-system
-This variable specifies the coding system to use when reading and
-writing selections or the clipboard. @xref{Coding
-Systems}. The default is @code{compound-text-with-extensions}, which
-converts to the text representation that X11 normally uses.
-@end defvar
-
-@cindex clipboard support (for MS-Windows)
-When Emacs runs on MS-Windows, it does not implement X selections in
-general, but it does support the clipboard. @code{x-get-selection}
-and @code{x-set-selection} on MS-Windows support the text data type
-only; if the clipboard holds other types of data, Emacs treats the
-clipboard as empty.
-
-@cindex scrap support (for Mac OS)
-On Mac OS, selection-like data transfer between applications is
-performed through a mechanism called @dfn{scraps}. The clipboard is a
-particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap
-data are called @dfn{scrap flavor types}, which are identified by
-four-char codes such as @code{TEXT}. Emacs associates a selection with
-a scrap, and a selection type with a scrap flavor type via
-@code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
-
-@example
-(get 'CLIPBOARD 'mac-scrap-name)
- @result{} "com.apple.scrap.clipboard"
-(get 'com.apple.traditional-mac-plain-text 'mac-ostype)
- @result{} "TEXT"
-@end example
-
-Conventionally, selection types for scrap flavor types on Mac OS have
-the form of @acronym{UTI, Uniform Type Identifier} such as
-@code{com.apple.traditional-mac-plain-text},
-@code{public.utf16-plain-text}, and @code{public.file-url}.
-
-@defopt x-select-enable-clipboard
-If this is non-@code{nil}, the Emacs yank functions consult the
-clipboard before the primary selection, and the kill functions store in
-the clipboard as well as the primary selection. Otherwise they do not
-access the clipboard at all. The default is @code{nil} on most systems,
-but @code{t} on MS-Windows and Mac.
-@end defopt
-
-@node Drag and Drop
-@section Drag and Drop
-
-@vindex x-dnd-test-function
-@vindex x-dnd-known-types
- When a user drags something from another application over Emacs, that other
-application expects Emacs to tell it if Emacs can handle the data that is
-dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine
-what to reply. The default value is @code{x-dnd-default-test-function}
-which accepts drops if the type of the data to be dropped is present in
-@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or
-@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
-on some other criteria.
-
-@vindex x-dnd-types-alist
- If you want to change the way Emacs handles drop of different types
-or add a new type, customize @code{x-dnd-types-alist}. This requires
-detailed knowledge of what types other applications use for drag and
-drop.
-
-@vindex dnd-protocol-alist
- When an URL is dropped on Emacs it may be a file, but it may also be
-another URL type (ftp, http, etc.). Emacs first checks
-@code{dnd-protocol-alist} to determine what to do with the URL. If
-there is no match there and if @code{browse-url-browser-function} is
-an alist, Emacs looks for a match there. If no match is found the
-text for the URL is inserted. If you want to alter Emacs behavior,
-you can customize these variables.
-
-@node Color Names
-@section Color Names
-
-@cindex color names
-@cindex specify color
-@cindex numerical RGB color specification
- A color name is text (usually in a string) that specifies a color.
-Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
-are allowed; use @kbd{M-x list-colors-display} to see a list of
-defined names. You can also specify colors numerically in forms such
-as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
-@var{r} specifies the red level, @var{g} specifies the green level,
-and @var{b} specifies the blue level. You can use either one, two,
-three, or four hex digits for @var{r}; then you must use the same
-number of hex digits for all @var{g} and @var{b} as well, making
-either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
-X Window System for more details about numerical RGB specification of
-colors.)
-
- These functions provide a way to determine which color names are
-valid, and what they look like. In some cases, the value depends on the
-@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
-meaning of the term ``selected frame.''
-
-@defun color-defined-p color &optional frame
-This function reports whether a color name is meaningful. It returns
-@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
-which frame's display to ask about; if @var{frame} is omitted or
-@code{nil}, the selected frame is used.
-
-Note that this does not tell you whether the display you are using
-really supports that color. When using X, you can ask for any defined
-color on any kind of display, and you will get some result---typically,
-the closest it can do. To determine whether a frame can really display
-a certain color, use @code{color-supported-p} (see below).
-
-@findex x-color-defined-p
-This function used to be called @code{x-color-defined-p},
-and that name is still supported as an alias.
-@end defun
-
-@defun defined-colors &optional frame
-This function returns a list of the color names that are defined
-and supported on frame @var{frame} (default, the selected frame).
-If @var{frame} does not support colors, the value is @code{nil}.
-
-@findex x-defined-colors
-This function used to be called @code{x-defined-colors},
-and that name is still supported as an alias.
-@end defun
-
-@defun color-supported-p color &optional frame background-p
-This returns @code{t} if @var{frame} can really display the color
-@var{color} (or at least something close to it). If @var{frame} is
-omitted or @code{nil}, the question applies to the selected frame.
-
-Some terminals support a different set of colors for foreground and
-background. If @var{background-p} is non-@code{nil}, that means you are
-asking whether @var{color} can be used as a background; otherwise you
-are asking whether it can be used as a foreground.
-
-The argument @var{color} must be a valid color name.
-@end defun
-
-@defun color-gray-p color &optional frame
-This returns @code{t} if @var{color} is a shade of gray, as defined on
-@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
-question applies to the selected frame. If @var{color} is not a valid
-color name, this function returns @code{nil}.
-@end defun
-
-@defun color-values color &optional frame
-@cindex rgb value
-This function returns a value that describes what @var{color} should
-ideally look like on @var{frame}. If @var{color} is defined, the
-value is a list of three integers, which give the amount of red, the
-amount of green, and the amount of blue. Each integer ranges in
-principle from 0 to 65535, but some displays may not use the full
-range. This three-element list is called the @dfn{rgb values} of the
-color.
-
-If @var{color} is not defined, the value is @code{nil}.
-
-@example
-(color-values "black")
- @result{} (0 0 0)
-(color-values "white")
- @result{} (65280 65280 65280)
-(color-values "red")
- @result{} (65280 0 0)
-(color-values "pink")
- @result{} (65280 49152 51968)
-(color-values "hungry")
- @result{} nil
-@end example
-
-The color values are returned for @var{frame}'s display. If
-@var{frame} is omitted or @code{nil}, the information is returned for
-the selected frame's display. If the frame cannot display colors, the
-value is @code{nil}.
-
-@findex x-color-values
-This function used to be called @code{x-color-values},
-and that name is still supported as an alias.
-@end defun
-
-@node Text Terminal Colors
-@section Text Terminal Colors
-@cindex colors on text-only terminals
-
- Text-only terminals usually support only a small number of colors,
-and the computer uses small integers to select colors on the terminal.
-This means that the computer cannot reliably tell what the selected
-color looks like; instead, you have to inform your application which
-small integers correspond to which colors. However, Emacs does know
-the standard set of colors and will try to use them automatically.
-
- The functions described in this section control how terminal colors
-are used by Emacs.
-
- Several of these functions use or return @dfn{rgb values}, described
-in @ref{Color Names}.
-
- These functions accept a display (either a frame or the name of a
-terminal) as an optional argument. We hope in the future to make Emacs
-support more than one text-only terminal at one time; then this argument
-will specify which terminal to operate on (the default being the
-selected frame's terminal; @pxref{Input Focus}). At present, though,
-the @var{frame} argument has no effect.
-
-@defun tty-color-define name number &optional rgb frame
-This function associates the color name @var{name} with
-color number @var{number} on the terminal.
-
-The optional argument @var{rgb}, if specified, is an rgb value, a list
-of three numbers that specify what the color actually looks like.
-If you do not specify @var{rgb}, then this color cannot be used by
-@code{tty-color-approximate} to approximate other colors, because
-Emacs will not know what it looks like.
-@end defun
-
-@defun tty-color-clear &optional frame
-This function clears the table of defined colors for a text-only terminal.
-@end defun
-
-@defun tty-color-alist &optional frame
-This function returns an alist recording the known colors supported by a
-text-only terminal.
-
-Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
-or @code{(@var{name} @var{number})}. Here, @var{name} is the color
-name, @var{number} is the number used to specify it to the terminal.
-If present, @var{rgb} is a list of three color values (for red, green,
-and blue) that says what the color actually looks like.
-@end defun
-
-@defun tty-color-approximate rgb &optional frame
-This function finds the closest color, among the known colors
-supported for @var{display}, to that described by the rgb value
-@var{rgb} (a list of color values). The return value is an element of
-@code{tty-color-alist}.
-@end defun
-
-@defun tty-color-translate color &optional frame
-This function finds the closest color to @var{color} among the known
-colors supported for @var{display} and returns its index (an integer).
-If the name @var{color} is not defined, the value is @code{nil}.
-@end defun
-
-@node Resources
-@section X Resources
-
-@defun x-get-resource attribute class &optional component subclass
-The function @code{x-get-resource} retrieves a resource value from the X
-Window defaults database.
-
-Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
-This function searches using a key of the form
-@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
-under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
-the class.
-
-The optional arguments @var{component} and @var{subclass} add to the key
-and the class, respectively. You must specify both of them or neither.
-If you specify them, the key is
-@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
-@samp{Emacs.@var{class}.@var{subclass}}.
-@end defun
-
-@defvar x-resource-class
-This variable specifies the application name that @code{x-get-resource}
-should look up. The default value is @code{"Emacs"}. You can examine X
-resources for application names other than ``Emacs'' by binding this
-variable to some other string, around a call to @code{x-get-resource}.
-@end defvar
-
-@defvar x-resource-name
-This variable specifies the instance name that @code{x-get-resource}
-should look up. The default value is the name Emacs was invoked with,
-or the value specified with the @samp{-name} or @samp{-rn} switches.
-@end defvar
-
-To illustrate some of the above, suppose that you have the line:
-
-@example
-xterm.vt100.background: yellow
-@end example
-
-@noindent
-in your X resources file (whose name is usually @file{~/.Xdefaults}
-or @file{~/.Xresources}). Then:
-
-@example
-@group
-(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
- (x-get-resource "vt100.background" "VT100.Background"))
- @result{} "yellow"
-@end group
-@group
-(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
- (x-get-resource "background" "VT100" "vt100" "Background"))
- @result{} "yellow"
-@end group
-@end example
-
- @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
-
-@node Display Feature Testing
-@section Display Feature Testing
-@cindex display feature testing
-
- The functions in this section describe the basic capabilities of a
-particular display. Lisp programs can use them to adapt their behavior
-to what the display can do. For example, a program that ordinarily uses
-a popup menu could use the minibuffer if popup menus are not supported.
-
- The optional argument @var{display} in these functions specifies which
-display to ask the question about. It can be a display name, a frame
-(which designates the display that frame is on), or @code{nil} (which
-refers to the selected frame's display, @pxref{Input Focus}).
-
- @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
-obtain information about displays.
-
-@defun display-popup-menus-p &optional display
-This function returns @code{t} if popup menus are supported on
-@var{display}, @code{nil} if not. Support for popup menus requires that
-the mouse be available, since the user cannot choose menu items without
-a mouse.
-@end defun
-
-@defun display-graphic-p &optional display
-This function returns @code{t} if @var{display} is a graphic display
-capable of displaying several frames and several different fonts at
-once. This is true for displays that use a window system such as X, and
-false for text-only terminals.
-@end defun
-
-@defun display-mouse-p &optional display
-@cindex mouse, availability
-This function returns @code{t} if @var{display} has a mouse available,
-@code{nil} if not.
-@end defun
-
-@defun display-color-p &optional display
-@findex x-display-color-p
-This function returns @code{t} if the screen is a color screen.
-It used to be called @code{x-display-color-p}, and that name
-is still supported as an alias.
-@end defun
-
-@defun display-grayscale-p &optional display
-This function returns @code{t} if the screen can display shades of gray.
-(All color displays can do this.)
-@end defun
-
-@defun display-supports-face-attributes-p attributes &optional display
-@anchor{Display Face Attribute Testing}
-This function returns non-@code{nil} if all the face attributes in
-@var{attributes} are supported (@pxref{Face Attributes}).
-
-The definition of `supported' is somewhat heuristic, but basically
-means that a face containing all the attributes in @var{attributes},
-when merged with the default face for display, can be represented in a
-way that's
-
-@enumerate
-@item
-different in appearance than the default face, and
-
-@item
-`close in spirit' to what the attributes specify, if not exact.
-@end enumerate
-
-Point (2) implies that a @code{:weight black} attribute will be
-satisfied by any display that can display bold, as will
-@code{:foreground "yellow"} as long as some yellowish color can be
-displayed, but @code{:slant italic} will @emph{not} be satisfied by
-the tty display code's automatic substitution of a `dim' face for
-italic.
-@end defun
-
-@defun display-selections-p &optional display
-This function returns @code{t} if @var{display} supports selections.
-Windowed displays normally support selections, but they may also be
-supported in some other cases.
-@end defun
-
-@defun display-images-p &optional display
-This function returns @code{t} if @var{display} can display images.
-Windowed displays ought in principle to handle images, but some
-systems lack the support for that. On a display that does not support
-images, Emacs cannot display a tool bar.
-@end defun
-
-@defun display-screens &optional display
-This function returns the number of screens associated with the display.
-@end defun
-
-@defun display-pixel-height &optional display
-This function returns the height of the screen in pixels.
-On a character terminal, it gives the height in characters.
-
-For graphical terminals, note that on ``multi-monitor'' setups this
-refers to the pixel width for all physical monitors associated with
-@var{display}. @xref{Multiple Displays}.
-@end defun
-
-@defun display-pixel-width &optional display
-This function returns the width of the screen in pixels.
-On a character terminal, it gives the width in characters.
-
-For graphical terminals, note that on ``multi-monitor'' setups this
-refers to the pixel width for all physical monitors associated with
-@var{display}. @xref{Multiple Displays}.
-@end defun
-
-@defun display-mm-height &optional display
-This function returns the height of the screen in millimeters,
-or @code{nil} if Emacs cannot get that information.
-@end defun
-
-@defun display-mm-width &optional display
-This function returns the width of the screen in millimeters,
-or @code{nil} if Emacs cannot get that information.
-@end defun
-
-@defvar display-mm-dimensions-alist
-This variable allows the user to specify the dimensions of graphical
-displays returned by @code{display-mm-height} and
-@code{display-mm-width} in case the system provides incorrect values.
-@end defvar
-
-@defun display-backing-store &optional display
-This function returns the backing store capability of the display.
-Backing store means recording the pixels of windows (and parts of
-windows) that are not exposed, so that when exposed they can be
-displayed very quickly.
-
-Values can be the symbols @code{always}, @code{when-mapped}, or
-@code{not-useful}. The function can also return @code{nil}
-when the question is inapplicable to a certain kind of display.
-@end defun
-
-@defun display-save-under &optional display
-This function returns non-@code{nil} if the display supports the
-SaveUnder feature. That feature is used by pop-up windows
-to save the pixels they obscure, so that they can pop down
-quickly.
-@end defun
-
-@defun display-planes &optional display
-This function returns the number of planes the display supports.
-This is typically the number of bits per pixel.
-For a tty display, it is log to base two of the number of colors supported.
-@end defun
-
-@defun display-visual-class &optional display
-This function returns the visual class for the screen. The value is one
-of the symbols @code{static-gray}, @code{gray-scale},
-@code{static-color}, @code{pseudo-color}, @code{true-color}, and
-@code{direct-color}.
-@end defun
-
-@defun display-color-cells &optional display
-This function returns the number of color cells the screen supports.
-@end defun
-
- These functions obtain additional information specifically
-about X displays.
-
-@defun x-server-version &optional display
-This function returns the list of version numbers of the X server
-running the display. The value is a list of three integers: the major
-and minor version numbers of the X protocol, and the
-distributor-specific release number of the X server software itself.
-@end defun
-
-@defun x-server-vendor &optional display
-This function returns the ``vendor'' that provided the X server
-software (as a string). Really this means whoever distributes the X
-server.
-
-When the developers of X labelled software distributors as
-``vendors,'' they showed their false assumption that no system could
-ever be developed and distributed noncommercially.
-@end defun
-
-@ignore
-@defvar x-no-window-manager
-This variable's value is @code{t} if no X window manager is in use.
-@end defvar
-@end ignore
-
-@ignore
-@item
-The functions @code{x-pixel-width} and @code{x-pixel-height} return the
-width and height of an X Window frame, measured in pixels.
-@end ignore
-
-@ignore
- arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@comment %**start of header
-@setfilename front1.info
-@settitle GNU Emacs Lisp Reference Manual
-@smallbook
-@comment %**end of header
-
-@titlepage
-.
-@sp 2
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19.29
-@center for Unix Users
-@center Edition 2.4, June 1995
-@sp 2
-@center @titlefont{Volume 1}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-@page
-.
-@sp 5
-@center @titlefont{The}
-@sp 1
-@center @titlefont{GNU}
-@sp 1
-@center @titlefont{Emacs Lisp}
-@sp 1
-@center @titlefont{Reference}
-@sp 1
-@center @titlefont{Manual}
-@sp 2
-@center GNU Emacs Version 19.29
-@center for Unix Users
-@center Edition 2.4, June 1995
-@sp 2
-@center @titlefont{Volume 2}
-@sp 2
-@center by Bil Lewis, Dan LaLiberte,
-@center and the GNU Manual Group
-
-@end titlepage
-@bye
-
-@ignore
- arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/functions
-@node Functions, Macros, Variables, Top
-@chapter Functions
-
- A Lisp program is composed mainly of Lisp functions. This chapter
-explains what functions are, how they accept arguments, and how to
-define them.
-
-@menu
-* 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.
-@end menu
-
-@node What Is a Function
-@section What Is a Function?
-
- In a general sense, a function is a rule for carrying on a computation
-given several values called @dfn{arguments}. The result of the
-computation is called the value of the function. The computation can
-also have side effects: lasting changes in the values of variables or
-the contents of data structures.
-
- Here are important terms for functions in Emacs Lisp and for other
-function-like objects.
-
-@table @dfn
-@item function
-@cindex function
-In Emacs Lisp, a @dfn{function} is anything that can be applied to
-arguments in a Lisp program. In some cases, we use it more
-specifically to mean a function written in Lisp. Special forms and
-macros are not functions.
-
-@item primitive
-@cindex primitive
-@cindex subr
-@cindex built-in function
-A @dfn{primitive} is a function callable from Lisp that is written in C,
-such as @code{car} or @code{append}. These functions are also called
-@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also
-considered primitives.)
-
-Usually the reason we implement a function as a primitive is either
-because it is fundamental, because it provides a low-level interface
-to operating system services, or because it needs to run fast.
-Primitives can be modified or added only by changing the C sources and
-recompiling the editor. See @ref{Writing Emacs Primitives}.
-
-@item lambda expression
-A @dfn{lambda expression} is a function written in Lisp.
-These are described in the following section.
-@ifnottex
-@xref{Lambda Expressions}.
-@end ifnottex
-
-@item special form
-A @dfn{special form} is a primitive that is like a function but does not
-evaluate all of its arguments in the usual way. It may evaluate only
-some of the arguments, or may evaluate them in an unusual order, or
-several times. Many special forms are described in @ref{Control
-Structures}.
-
-@item macro
-@cindex macro
-A @dfn{macro} is a construct defined in Lisp by the programmer. It
-differs from a function in that it translates a Lisp expression that you
-write into an equivalent expression to be evaluated instead of the
-original expression. Macros enable Lisp programmers to do the sorts of
-things that special forms can do. @xref{Macros}, for how to define and
-use macros.
-
-@item command
-@cindex command
-A @dfn{command} is an object that @code{command-execute} can invoke; it
-is a possible definition for a key sequence. Some functions are
-commands; a function written in Lisp is a command if it contains an
-interactive declaration (@pxref{Defining Commands}). Such a function
-can be called from Lisp expressions like other functions; in this case,
-the fact that the function is a command makes no difference.
-
-Keyboard macros (strings and vectors) are commands also, even though
-they are not functions. A symbol is a command if its function
-definition is a command; such symbols can be invoked with @kbd{M-x}.
-The symbol is a function as well if the definition is a function.
-@xref{Interactive Call}.
-
-@item keystroke command
-@cindex keystroke command
-A @dfn{keystroke command} is a command that is bound to a key sequence
-(typically one to three keystrokes). The distinction is made here
-merely to avoid confusion with the meaning of ``command'' in non-Emacs
-editors; for Lisp programs, the distinction is normally unimportant.
-
-@item byte-code function
-A @dfn{byte-code function} is a function that has been compiled by the
-byte compiler. @xref{Byte-Code Type}.
-@end table
-
-@defun functionp object
-This function returns @code{t} if @var{object} is any kind of
-function, or a special form, or, recursively, a symbol whose function
-definition is a function or special form. (This does not include
-macros.)
-@end defun
-
-Unlike @code{functionp}, the next three functions do @emph{not}
-treat a symbol as its function definition.
-
-@defun subrp object
-This function returns @code{t} if @var{object} is a built-in function
-(i.e., a Lisp primitive).
-
-@example
-@group
-(subrp 'message) ; @r{@code{message} is a symbol,}
- @result{} nil ; @r{not a subr object.}
-@end group
-@group
-(subrp (symbol-function 'message))
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun byte-code-function-p object
-This function returns @code{t} if @var{object} is a byte-code
-function. For example:
-
-@example
-@group
-(byte-code-function-p (symbol-function 'next-line))
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun subr-arity subr
-This function provides information about the argument list of a
-primitive, @var{subr}. The returned value is a pair
-@code{(@var{min} . @var{max})}. @var{min} is the minimum number of
-args. @var{max} is the maximum number or the symbol @code{many}, for a
-function with @code{&rest} arguments, or the symbol @code{unevalled} if
-@var{subr} is a special form.
-@end defun
-
-@node Lambda Expressions
-@section Lambda Expressions
-@cindex lambda expression
-
- A function written in Lisp is a list that looks like this:
-
-@example
-(lambda (@var{arg-variables}@dots{})
- @r{[}@var{documentation-string}@r{]}
- @r{[}@var{interactive-declaration}@r{]}
- @var{body-forms}@dots{})
-@end example
-
-@noindent
-Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
-actually is valid as an expression---it evaluates to itself. In some
-other Lisp dialects, a lambda expression is not a valid expression at
-all. In either case, its main use is not to be evaluated as an
-expression, but to be called as a function.
-
-@menu
-* 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.
-@end menu
-
-@node Lambda Components
-@subsection Components of a Lambda Expression
-
-@ifnottex
-
- A function written in Lisp (a ``lambda expression'') is a list that
-looks like this:
-
-@example
-(lambda (@var{arg-variables}@dots{})
- [@var{documentation-string}]
- [@var{interactive-declaration}]
- @var{body-forms}@dots{})
-@end example
-@end ifnottex
-
-@cindex lambda list
- The first element of a lambda expression is always the symbol
-@code{lambda}. This indicates that the list represents a function. The
-reason functions are defined to start with @code{lambda} is so that
-other lists, intended for other uses, will not accidentally be valid as
-functions.
-
- The second element is a list of symbols---the argument variable names.
-This is called the @dfn{lambda list}. When a Lisp function is called,
-the argument values are matched up against the variables in the lambda
-list, which are given local bindings with the values provided.
-@xref{Local Variables}.
-
- The documentation string is a Lisp string object placed within the
-function definition to describe the function for the Emacs help
-facilities. @xref{Function Documentation}.
-
- The interactive declaration is a list of the form @code{(interactive
-@var{code-string})}. This declares how to provide arguments if the
-function is used interactively. Functions with this declaration are called
-@dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
-Functions not intended to be called in this way should not have interactive
-declarations. @xref{Defining Commands}, for how to write an interactive
-declaration.
-
-@cindex body of function
- The rest of the elements are the @dfn{body} of the function: the Lisp
-code to do the work of the function (or, as a Lisp programmer would say,
-``a list of Lisp forms to evaluate''). The value returned by the
-function is the value returned by the last element of the body.
-
-@node Simple Lambda
-@subsection A Simple Lambda-Expression Example
-
- Consider for example the following function:
-
-@example
-(lambda (a b c) (+ a b c))
-@end example
-
-@noindent
-We can call this function by writing it as the @sc{car} of an
-expression, like this:
-
-@example
-@group
-((lambda (a b c) (+ a b c))
- 1 2 3)
-@end group
-@end example
-
-@noindent
-This call evaluates the body of the lambda expression with the variable
-@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
-Evaluation of the body adds these three numbers, producing the result 6;
-therefore, this call to the function returns the value 6.
-
- Note that the arguments can be the results of other function calls, as in
-this example:
-
-@example
-@group
-((lambda (a b c) (+ a b c))
- 1 (* 2 3) (- 5 4))
-@end group
-@end example
-
-@noindent
-This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
-4)} from left to right. Then it applies the lambda expression to the
-argument values 1, 6 and 1 to produce the value 8.
-
- It is not often useful to write a lambda expression as the @sc{car} of
-a form in this way. You can get the same result, of making local
-variables and giving them values, using the special form @code{let}
-(@pxref{Local Variables}). And @code{let} is clearer and easier to use.
-In practice, lambda expressions are either stored as the function
-definitions of symbols, to produce named functions, or passed as
-arguments to other functions (@pxref{Anonymous Functions}).
-
- However, calls to explicit lambda expressions were very useful in the
-old days of Lisp, before the special form @code{let} was invented. At
-that time, they were the only way to bind and initialize local
-variables.
-
-@node Argument List
-@subsection Other Features of Argument Lists
-@kindex wrong-number-of-arguments
-@cindex argument binding
-@cindex binding arguments
-@cindex argument lists, features
-
- Our simple sample function, @code{(lambda (a b c) (+ a b c))},
-specifies three argument variables, so it must be called with three
-arguments: if you try to call it with only two arguments or four
-arguments, you get a @code{wrong-number-of-arguments} error.
-
- It is often convenient to write a function that allows certain
-arguments to be omitted. For example, the function @code{substring}
-accepts three arguments---a string, the start index and the end
-index---but the third argument defaults to the @var{length} of the
-string if you omit it. It is also convenient for certain functions to
-accept an indefinite number of arguments, as the functions @code{list}
-and @code{+} do.
-
-@cindex optional arguments
-@cindex rest arguments
-@kindex &optional
-@kindex &rest
- To specify optional arguments that may be omitted when a function
-is called, simply include the keyword @code{&optional} before the optional
-arguments. To specify a list of zero or more extra arguments, include the
-keyword @code{&rest} before one final argument.
-
- Thus, the complete syntax for an argument list is as follows:
-
-@example
-@group
-(@var{required-vars}@dots{}
- @r{[}&optional @var{optional-vars}@dots{}@r{]}
- @r{[}&rest @var{rest-var}@r{]})
-@end group
-@end example
-
-@noindent
-The square brackets indicate that the @code{&optional} and @code{&rest}
-clauses, and the variables that follow them, are optional.
-
- A call to the function requires one actual argument for each of the
-@var{required-vars}. There may be actual arguments for zero or more of
-the @var{optional-vars}, and there cannot be any actual arguments beyond
-that unless the lambda list uses @code{&rest}. In that case, there may
-be any number of extra actual arguments.
-
- If actual arguments for the optional and rest variables are omitted,
-then they always default to @code{nil}. There is no way for the
-function to distinguish between an explicit argument of @code{nil} and
-an omitted argument. However, the body of the function is free to
-consider @code{nil} an abbreviation for some other meaningful value.
-This is what @code{substring} does; @code{nil} as the third argument to
-@code{substring} means to use the length of the string supplied.
-
-@cindex CL note---default optional arg
-@quotation
-@b{Common Lisp note:} Common Lisp allows the function to specify what
-default value to use when an optional argument is omitted; Emacs Lisp
-always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
-variables that tell you whether an argument was explicitly passed.
-@end quotation
-
- For example, an argument list that looks like this:
-
-@example
-(a b &optional c d &rest e)
-@end example
-
-@noindent
-binds @code{a} and @code{b} to the first two actual arguments, which are
-required. If one or two more arguments are provided, @code{c} and
-@code{d} are bound to them respectively; any arguments after the first
-four are collected into a list and @code{e} is bound to that list. If
-there are only two arguments, @code{c} is @code{nil}; if two or three
-arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
-is @code{nil}.
-
- There is no way to have required arguments following optional
-ones---it would not make sense. To see why this must be so, suppose
-that @code{c} in the example were optional and @code{d} were required.
-Suppose three actual arguments are given; which variable would the
-third argument be for? Would it be used for the @var{c}, or for
-@var{d}? One can argue for both possibilities. Similarly, it makes
-no sense to have any more arguments (either required or optional)
-after a @code{&rest} argument.
-
- Here are some examples of argument lists and proper calls:
-
-@smallexample
-((lambda (n) (1+ n)) ; @r{One required:}
- 1) ; @r{requires exactly one argument.}
- @result{} 2
-((lambda (n &optional n1) ; @r{One required and one optional:}
- (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
- 1 2)
- @result{} 3
-((lambda (n &rest ns) ; @r{One required and one rest:}
- (+ n (apply '+ ns))) ; @r{1 or more arguments.}
- 1 2 3 4 5)
- @result{} 15
-@end smallexample
-
-@node Function Documentation
-@subsection Documentation Strings of Functions
-@cindex documentation of function
-
- A lambda expression may optionally have a @dfn{documentation string} just
-after the lambda list. This string does not affect execution of the
-function; it is a kind of comment, but a systematized comment which
-actually appears inside the Lisp world and can be used by the Emacs help
-facilities. @xref{Documentation}, for how the @var{documentation-string} is
-accessed.
-
- It is a good idea to provide documentation strings for all the
-functions in your program, even those that are called only from within
-your program. Documentation strings are like comments, except that they
-are easier to access.
-
- The first line of the documentation string should stand on its own,
-because @code{apropos} displays just this first line. It should consist
-of one or two complete sentences that summarize the function's purpose.
-
- The start of the documentation string is usually indented in the
-source file, but since these spaces come before the starting
-double-quote, they are not part of the string. Some people make a
-practice of indenting any additional lines of the string so that the
-text lines up in the program source. @emph{That is a mistake.} The
-indentation of the following lines is inside the string; what looks
-nice in the source code will look ugly when displayed by the help
-commands.
-
- You may wonder how the documentation string could be optional, since
-there are required components of the function that follow it (the body).
-Since evaluation of a string returns that string, without any side effects,
-it has no effect if it is not the last form in the body. Thus, in
-practice, there is no confusion between the first form of the body and the
-documentation string; if the only body form is a string then it serves both
-as the return value and as the documentation.
-
- The last line of the documentation string can specify calling
-conventions different from the actual function arguments. Write
-text like this:
-
-@example
-\(fn @var{arglist})
-@end example
-
-@noindent
-following a blank line, at the beginning of the line, with no newline
-following it inside the documentation string. (The @samp{\} is used
-to avoid confusing the Emacs motion commands.) The calling convention
-specified in this way appears in help messages in place of the one
-derived from the actual arguments of the function.
-
- This feature is particularly useful for macro definitions, since the
-arguments written in a macro definition often do not correspond to the
-way users think of the parts of the macro call.
-
-@node Function Names
-@section Naming a Function
-@cindex function definition
-@cindex named function
-@cindex function name
-
- In most computer languages, every function has a name; the idea of a
-function without a name is nonsensical. In Lisp, a function in the
-strictest sense has no name. It is simply a list whose first element is
-@code{lambda}, a byte-code function object, or a primitive subr-object.
-
- However, a symbol can serve as the name of a function. This happens
-when you put the function in the symbol's @dfn{function cell}
-(@pxref{Symbol Components}). Then the symbol itself becomes a valid,
-callable function, equivalent to the list or subr-object that its
-function cell refers to. The contents of the function cell are also
-called the symbol's @dfn{function definition}. The procedure of using a
-symbol's function definition in place of the symbol is called
-@dfn{symbol function indirection}; see @ref{Function Indirection}.
-
- In practice, nearly all functions are given names in this way and
-referred to through their names. For example, the symbol @code{car} works
-as a function and does what it does because the primitive subr-object
-@code{#<subr car>} is stored in its function cell.
-
- We give functions names because it is convenient to refer to them by
-their names in Lisp expressions. For primitive subr-objects such as
-@code{#<subr car>}, names are the only way you can refer to them: there
-is no read syntax for such objects. For functions written in Lisp, the
-name is more convenient to use in a call than an explicit lambda
-expression. Also, a function with a name can refer to itself---it can
-be recursive. Writing the function's name in its own definition is much
-more convenient than making the function definition point to itself
-(something that is not impossible but that has various disadvantages in
-practice).
-
- We often identify functions with the symbols used to name them. For
-example, we often speak of ``the function @code{car},'' not
-distinguishing between the symbol @code{car} and the primitive
-subr-object that is its function definition. For most purposes, the
-distinction is not important.
-
- Even so, keep in mind that a function need not have a unique name. While
-a given function object @emph{usually} appears in the function cell of only
-one symbol, this is just a matter of convenience. It is easy to store
-it in several symbols using @code{fset}; then each of the symbols is
-equally well a name for the same function.
-
- A symbol used as a function name may also be used as a variable; these
-two uses of a symbol are independent and do not conflict. (Some Lisp
-dialects, such as Scheme, do not distinguish between a symbol's value
-and its function definition; a symbol's value as a variable is also its
-function definition.) If you have not given a symbol a function
-definition, you cannot use it as a function; whether the symbol has a
-value as a variable makes no difference to this.
-
-@node Defining Functions
-@section Defining Functions
-@cindex defining a function
-
- We usually give a name to a function when it is first created. This
-is called @dfn{defining a function}, and it is done with the
-@code{defun} special form.
-
-@defspec defun name argument-list body-forms
-@code{defun} is the usual way to define new Lisp functions. It
-defines the symbol @var{name} as a function that looks like this:
-
-@example
-(lambda @var{argument-list} . @var{body-forms})
-@end example
-
-@code{defun} stores this lambda expression in the function cell of
-@var{name}. It returns the value @var{name}, but usually we ignore this
-value.
-
-As described previously, @var{argument-list} is a list of argument
-names and may include the keywords @code{&optional} and @code{&rest}
-(@pxref{Lambda Expressions}). Also, the first two of the
-@var{body-forms} may be a documentation string and an interactive
-declaration.
-
-There is no conflict if the same symbol @var{name} is also used as a
-variable, since the symbol's value cell is independent of the function
-cell. @xref{Symbol Components}.
-
-Here are some examples:
-
-@example
-@group
-(defun foo () 5)
- @result{} foo
-@end group
-@group
-(foo)
- @result{} 5
-@end group
-
-@group
-(defun bar (a &optional b &rest c)
- (list a b c))
- @result{} bar
-@end group
-@group
-(bar 1 2 3 4 5)
- @result{} (1 2 (3 4 5))
-@end group
-@group
-(bar 1)
- @result{} (1 nil nil)
-@end group
-@group
-(bar)
-@error{} Wrong number of arguments.
-@end group
-
-@group
-(defun capitalize-backwards ()
- "Upcase the last letter of a word."
- (interactive)
- (backward-word 1)
- (forward-word 1)
- (backward-char 1)
- (capitalize-word 1))
- @result{} capitalize-backwards
-@end group
-@end example
-
-Be careful not to redefine existing functions unintentionally.
-@code{defun} redefines even primitive functions such as @code{car}
-without any hesitation or notification. Redefining a function already
-defined is often done deliberately, and there is no way to distinguish
-deliberate redefinition from unintentional redefinition.
-@end defspec
-
-@cindex function aliases
-@defun defalias name definition &optional docstring
-@anchor{Definition of defalias}
-This special form defines the symbol @var{name} as a function, with
-definition @var{definition} (which can be any valid Lisp function).
-It returns @var{definition}.
-
-If @var{docstring} is non-@code{nil}, it becomes the function
-documentation of @var{name}. Otherwise, any documentation provided by
-@var{definition} is used.
-
-The proper place to use @code{defalias} is where a specific function
-name is being defined---especially where that name appears explicitly in
-the source file being loaded. This is because @code{defalias} records
-which file defined the function, just like @code{defun}
-(@pxref{Unloading}).
-
-By contrast, in programs that manipulate function definitions for other
-purposes, it is better to use @code{fset}, which does not keep such
-records. @xref{Function Cells}.
-@end defun
-
- You cannot create a new primitive function with @code{defun} or
-@code{defalias}, but you can use them to change the function definition of
-any symbol, even one such as @code{car} or @code{x-popup-menu} whose
-normal definition is a primitive. However, this is risky: for
-instance, it is next to impossible to redefine @code{car} without
-breaking Lisp completely. Redefining an obscure function such as
-@code{x-popup-menu} is less dangerous, but it still may not work as
-you expect. If there are calls to the primitive from C code, they
-call the primitive's C definition directly, so changing the symbol's
-definition will have no effect on them.
-
- See also @code{defsubst}, which defines a function like @code{defun}
-and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
-
-@node Calling Functions
-@section Calling Functions
-@cindex function invocation
-@cindex calling a function
-
- Defining functions is only half the battle. Functions don't do
-anything until you @dfn{call} them, i.e., tell them to run. Calling a
-function is also known as @dfn{invocation}.
-
- The most common way of invoking a function is by evaluating a list.
-For example, evaluating the list @code{(concat "a" "b")} calls the
-function @code{concat} with arguments @code{"a"} and @code{"b"}.
-@xref{Evaluation}, for a description of evaluation.
-
- When you write a list as an expression in your program, you specify
-which function to call, and how many arguments to give it, in the text
-of the program. Usually that's just what you want. Occasionally you
-need to compute at run time which function to call. To do that, use
-the function @code{funcall}. When you also need to determine at run
-time how many arguments to pass, use @code{apply}.
-
-@defun funcall function &rest arguments
-@code{funcall} calls @var{function} with @var{arguments}, and returns
-whatever @var{function} returns.
-
-Since @code{funcall} is a function, all of its arguments, including
-@var{function}, are evaluated before @code{funcall} is called. This
-means that you can use any expression to obtain the function to be
-called. It also means that @code{funcall} does not see the
-expressions you write for the @var{arguments}, only their values.
-These values are @emph{not} evaluated a second time in the act of
-calling @var{function}; the operation of @code{funcall} is like the
-normal procedure for calling a function, once its arguments have
-already been evaluated.
-
-The argument @var{function} must be either a Lisp function or a
-primitive function. Special forms and macros are not allowed, because
-they make sense only when given the ``unevaluated'' argument
-expressions. @code{funcall} cannot provide these because, as we saw
-above, it never knows them in the first place.
-
-@example
-@group
-(setq f 'list)
- @result{} list
-@end group
-@group
-(funcall f 'x 'y 'z)
- @result{} (x y z)
-@end group
-@group
-(funcall f 'x 'y '(z))
- @result{} (x y (z))
-@end group
-@group
-(funcall 'and t nil)
-@error{} Invalid function: #<subr and>
-@end group
-@end example
-
-Compare these examples with the examples of @code{apply}.
-@end defun
-
-@defun apply function &rest arguments
-@code{apply} calls @var{function} with @var{arguments}, just like
-@code{funcall} but with one difference: the last of @var{arguments} is a
-list of objects, which are passed to @var{function} as separate
-arguments, rather than a single list. We say that @code{apply}
-@dfn{spreads} this list so that each individual element becomes an
-argument.
-
-@code{apply} returns the result of calling @var{function}. As with
-@code{funcall}, @var{function} must either be a Lisp function or a
-primitive function; special forms and macros do not make sense in
-@code{apply}.
-
-@example
-@group
-(setq f 'list)
- @result{} list
-@end group
-@group
-(apply f 'x 'y 'z)
-@error{} Wrong type argument: listp, z
-@end group
-@group
-(apply '+ 1 2 '(3 4))
- @result{} 10
-@end group
-@group
-(apply '+ '(1 2 3 4))
- @result{} 10
-@end group
-
-@group
-(apply 'append '((a b c) nil (x y z) nil))
- @result{} (a b c x y z)
-@end group
-@end example
-
-For an interesting example of using @code{apply}, see @ref{Definition
-of mapcar}.
-@end defun
-
-@cindex functionals
- It is common for Lisp functions to accept functions as arguments or
-find them in data structures (especially in hook variables and property
-lists) and call them using @code{funcall} or @code{apply}. Functions
-that accept function arguments are often called @dfn{functionals}.
-
- Sometimes, when you call a functional, it is useful to supply a no-op
-function as the argument. Here are two different kinds of no-op
-function:
-
-@defun identity arg
-This function returns @var{arg} and has no side effects.
-@end defun
-
-@defun ignore &rest args
-This function ignores any arguments and returns @code{nil}.
-@end defun
-
-@node Mapping Functions
-@section Mapping Functions
-@cindex mapping functions
-
- A @dfn{mapping function} applies a given function (@emph{not} a
-special form or macro) to each element of a list or other collection.
-Emacs Lisp has several such functions; @code{mapcar} and
-@code{mapconcat}, which scan a list, are described here.
-@xref{Definition of mapatoms}, for the function @code{mapatoms} which
-maps over the symbols in an obarray. @xref{Definition of maphash},
-for the function @code{maphash} which maps over key/value associations
-in a hash table.
-
- These mapping functions do not allow char-tables because a char-table
-is a sparse array whose nominal range of indices is very large. To map
-over a char-table in a way that deals properly with its sparse nature,
-use the function @code{map-char-table} (@pxref{Char-Tables}).
-
-@defun mapcar function sequence
-@anchor{Definition of mapcar}
-@code{mapcar} applies @var{function} to each element of @var{sequence}
-in turn, and returns a list of the results.
-
-The argument @var{sequence} can be any kind of sequence except a
-char-table; that is, a list, a vector, a bool-vector, or a string. The
-result is always a list. The length of the result is the same as the
-length of @var{sequence}. For example:
-
-@smallexample
-@group
-(mapcar 'car '((a b) (c d) (e f)))
- @result{} (a c e)
-(mapcar '1+ [1 2 3])
- @result{} (2 3 4)
-(mapcar 'char-to-string "abc")
- @result{} ("a" "b" "c")
-@end group
-
-@group
-;; @r{Call each function in @code{my-hooks}.}
-(mapcar 'funcall my-hooks)
-@end group
-
-@group
-(defun mapcar* (function &rest args)
- "Apply FUNCTION to successive cars of all ARGS.
-Return the list of results."
- ;; @r{If no list is exhausted,}
- (if (not (memq nil args))
- ;; @r{apply function to @sc{car}s.}
- (cons (apply function (mapcar 'car args))
- (apply 'mapcar* function
- ;; @r{Recurse for rest of elements.}
- (mapcar 'cdr args)))))
-@end group
-
-@group
-(mapcar* 'cons '(a b c) '(1 2 3 4))
- @result{} ((a . 1) (b . 2) (c . 3))
-@end group
-@end smallexample
-@end defun
-
-@defun mapc function sequence
-@code{mapc} is like @code{mapcar} except that @var{function} is used for
-side-effects only---the values it returns are ignored, not collected
-into a list. @code{mapc} always returns @var{sequence}.
-@end defun
-
-@defun mapconcat function sequence separator
-@code{mapconcat} applies @var{function} to each element of
-@var{sequence}: the results, which must be strings, are concatenated.
-Between each pair of result strings, @code{mapconcat} inserts the string
-@var{separator}. Usually @var{separator} contains a space or comma or
-other suitable punctuation.
-
-The argument @var{function} must be a function that can take one
-argument and return a string. The argument @var{sequence} can be any
-kind of sequence except a char-table; that is, a list, a vector, a
-bool-vector, or a string.
-
-@smallexample
-@group
-(mapconcat 'symbol-name
- '(The cat in the hat)
- " ")
- @result{} "The cat in the hat"
-@end group
-
-@group
-(mapconcat (function (lambda (x) (format "%c" (1+ x))))
- "HAL-8000"
- "")
- @result{} "IBM.9111"
-@end group
-@end smallexample
-@end defun
-
-@node Anonymous Functions
-@section Anonymous Functions
-@cindex anonymous function
-
- In Lisp, a function is a list that starts with @code{lambda}, a
-byte-code function compiled from such a list, or alternatively a
-primitive subr-object; names are ``extra.'' Although usually functions
-are defined with @code{defun} and given names at the same time, it is
-occasionally more concise to use an explicit lambda expression---an
-anonymous function. Such a list is valid wherever a function name is.
-
- Any method of creating such a list makes a valid function. Even this:
-
-@smallexample
-@group
-(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
-@result{} (lambda (x) (+ 12 x))
-@end group
-@end smallexample
-
-@noindent
-This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
-makes it the value (@emph{not} the function definition!) of
-@code{silly}.
-
- Here is how we might call this function:
-
-@example
-@group
-(funcall silly 1)
-@result{} 13
-@end group
-@end example
-
-@noindent
-(It does @emph{not} work to write @code{(silly 1)}, because this function
-is not the @emph{function definition} of @code{silly}. We have not given
-@code{silly} any function definition, just a value as a variable.)
-
- Most of the time, anonymous functions are constants that appear in
-your program. For example, you might want to pass one as an argument to
-the function @code{mapcar}, which applies any given function to each
-element of a list.
-
- Here we define a function @code{change-property} which
-uses a function as its third argument:
-
-@example
-@group
-(defun change-property (symbol prop function)
- (let ((value (get symbol prop)))
- (put symbol prop (funcall function value))))
-@end group
-@end example
-
-@noindent
-Here we define a function that uses @code{change-property},
-passing it a function to double a number:
-
-@example
-@group
-(defun double-property (symbol prop)
- (change-property symbol prop '(lambda (x) (* 2 x))))
-@end group
-@end example
-
-@noindent
-In such cases, we usually use the special form @code{function} instead
-of simple quotation to quote the anonymous function, like this:
-
-@example
-@group
-(defun double-property (symbol prop)
- (change-property symbol prop
- (function (lambda (x) (* 2 x)))))
-@end group
-@end example
-
-Using @code{function} instead of @code{quote} makes a difference if you
-compile the function @code{double-property}. For example, if you
-compile the second definition of @code{double-property}, the anonymous
-function is compiled as well. By contrast, if you compile the first
-definition which uses ordinary @code{quote}, the argument passed to
-@code{change-property} is the precise list shown:
-
-@example
-(lambda (x) (* x 2))
-@end example
-
-@noindent
-The Lisp compiler cannot assume this list is a function, even though it
-looks like one, since it does not know what @code{change-property} will
-do with the list. Perhaps it will check whether the @sc{car} of the third
-element is the symbol @code{*}! Using @code{function} tells the
-compiler it is safe to go ahead and compile the constant function.
-
- Nowadays it is possible to omit @code{function} entirely, like this:
-
-@example
-@group
-(defun double-property (symbol prop)
- (change-property symbol prop (lambda (x) (* 2 x))))
-@end group
-@end example
-
-@noindent
-This is because @code{lambda} itself implies @code{function}.
-
- We sometimes write @code{function} instead of @code{quote} when
-quoting the name of a function, but this usage is just a sort of
-comment:
-
-@example
-(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
-@end example
-
-@cindex @samp{#'} syntax
- The read syntax @code{#'} is a short-hand for using @code{function}.
-For example,
-
-@example
-#'(lambda (x) (* x x))
-@end example
-
-@noindent
-is equivalent to
-
-@example
-(function (lambda (x) (* x x)))
-@end example
-
-@defspec function function-object
-@cindex function quoting
-This special form returns @var{function-object} without evaluating it.
-In this, it is equivalent to @code{quote}. However, it serves as a
-note to the Emacs Lisp compiler that @var{function-object} is intended
-to be used only as a function, and therefore can safely be compiled.
-Contrast this with @code{quote}, in @ref{Quoting}.
-@end defspec
-
- @xref{describe-symbols example}, for a realistic example using
-@code{function} and an anonymous function.
-
-@node Function Cells
-@section Accessing Function Cell Contents
-
- The @dfn{function definition} of a symbol is the object stored in the
-function cell of the symbol. The functions described here access, test,
-and set the function cell of symbols.
-
- See also the function @code{indirect-function}. @xref{Definition of
-indirect-function}.
-
-@defun symbol-function symbol
-@kindex void-function
-This returns the object in the function cell of @var{symbol}. If the
-symbol's function cell is void, a @code{void-function} error is
-signaled.
-
-This function does not check that the returned object is a legitimate
-function.
-
-@example
-@group
-(defun bar (n) (+ n 2))
- @result{} bar
-@end group
-@group
-(symbol-function 'bar)
- @result{} (lambda (n) (+ n 2))
-@end group
-@group
-(fset 'baz 'bar)
- @result{} bar
-@end group
-@group
-(symbol-function 'baz)
- @result{} bar
-@end group
-@end example
-@end defun
-
-@cindex void function cell
- If you have never given a symbol any function definition, we say that
-that symbol's function cell is @dfn{void}. In other words, the function
-cell does not have any Lisp object in it. If you try to call such a symbol
-as a function, it signals a @code{void-function} error.
-
- Note that void is not the same as @code{nil} or the symbol
-@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
-and can be stored into a function cell just as any other object can be
-(and they can be valid functions if you define them in turn with
-@code{defun}). A void function cell contains no object whatsoever.
-
- You can test the voidness of a symbol's function definition with
-@code{fboundp}. After you have given a symbol a function definition, you
-can make it void once more using @code{fmakunbound}.
-
-@defun fboundp symbol
-This function returns @code{t} if the symbol has an object in its
-function cell, @code{nil} otherwise. It does not check that the object
-is a legitimate function.
-@end defun
-
-@defun fmakunbound symbol
-This function makes @var{symbol}'s function cell void, so that a
-subsequent attempt to access this cell will cause a
-@code{void-function} error. It returns @var{symbol}. (See also
-@code{makunbound}, in @ref{Void Variables}.)
-
-@example
-@group
-(defun foo (x) x)
- @result{} foo
-@end group
-@group
-(foo 1)
- @result{}1
-@end group
-@group
-(fmakunbound 'foo)
- @result{} foo
-@end group
-@group
-(foo 1)
-@error{} Symbol's function definition is void: foo
-@end group
-@end example
-@end defun
-
-@defun fset symbol definition
-This function stores @var{definition} in the function cell of
-@var{symbol}. The result is @var{definition}. Normally
-@var{definition} should be a function or the name of a function, but
-this is not checked. The argument @var{symbol} is an ordinary evaluated
-argument.
-
-There are three normal uses of this function:
-
-@itemize @bullet
-@item
-Copying one symbol's function definition to another---in other words,
-making an alternate name for a function. (If you think of this as the
-definition of the new name, you should use @code{defalias} instead of
-@code{fset}; see @ref{Definition of defalias}.)
-
-@item
-Giving a symbol a function definition that is not a list and therefore
-cannot be made with @code{defun}. For example, you can use @code{fset}
-to give a symbol @code{s1} a function definition which is another symbol
-@code{s2}; then @code{s1} serves as an alias for whatever definition
-@code{s2} presently has. (Once again use @code{defalias} instead of
-@code{fset} if you think of this as the definition of @code{s1}.)
-
-@item
-In constructs for defining or altering functions. If @code{defun}
-were not a primitive, it could be written in Lisp (as a macro) using
-@code{fset}.
-@end itemize
-
-Here are examples of these uses:
-
-@example
-@group
-;; @r{Save @code{foo}'s definition in @code{old-foo}.}
-(fset 'old-foo (symbol-function 'foo))
-@end group
-
-@group
-;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
-;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
-(fset 'xfirst 'car)
- @result{} car
-@end group
-@group
-(xfirst '(1 2 3))
- @result{} 1
-@end group
-@group
-(symbol-function 'xfirst)
- @result{} car
-@end group
-@group
-(symbol-function (symbol-function 'xfirst))
- @result{} #<subr car>
-@end group
-
-@group
-;; @r{Define a named keyboard macro.}
-(fset 'kill-two-lines "\^u2\^k")
- @result{} "\^u2\^k"
-@end group
-
-@group
-;; @r{Here is a function that alters other functions.}
-(defun copy-function-definition (new old)
- "Define NEW with the same function definition as OLD."
- (fset new (symbol-function old)))
-@end group
-@end example
-@end defun
-
- @code{fset} is sometimes used to save the old definition of a
-function before redefining it. That permits the new definition to
-invoke the old definition. But it is unmodular and unclean for a Lisp
-file to redefine a function defined elsewhere. If you want to modify
-a function defined by another package, it is cleaner to use
-@code{defadvice} (@pxref{Advising Functions}).
-
-@node Obsolete Functions
-@section Declaring Functions Obsolete
-
-You can use @code{make-obsolete} to declare a function obsolete. This
-indicates that the function may be removed at some stage in the future.
-
-@defun make-obsolete obsolete-name current-name &optional when
-This function makes the byte compiler warn that the function
-@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
-warning message says to use @var{current-name} instead of
-@var{obsolete-name}. @var{current-name} does not need to be an alias for
-@var{obsolete-name}; it can be a different function with similar
-functionality. If @var{current-name} is a string, it is the warning
-message.
-
-If provided, @var{when} should be a string indicating when the function
-was first made obsolete---for example, a date or a release number.
-@end defun
-
-You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}.
-
-@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
-This macro marks the function @var{obsolete-name} obsolete and also
-defines it as an alias for the function @var{current-name}. It is
-equivalent to the following:
-
-@example
-(defalias @var{obsolete-name} @var{current-name} @var{docstring})
-(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
-@end example
-@end defmac
-
-@node Inline Functions
-@section Inline Functions
-@cindex inline functions
-
-@findex defsubst
-You can define an @dfn{inline function} by using @code{defsubst} instead
-of @code{defun}. An inline function works just like an ordinary
-function except for one thing: when you compile a call to the function,
-the function's definition is open-coded into the caller.
-
-Making a function inline makes explicit calls run faster. But it also
-has disadvantages. For one thing, it reduces flexibility; if you
-change the definition of the function, calls already inlined still use
-the old definition until you recompile them.
-
-Another disadvantage is that making a large function inline can increase
-the size of compiled code both in files and in memory. Since the speed
-advantage of inline functions is greatest for small functions, you
-generally should not make large functions inline.
-
-Also, inline functions do not behave well with respect to debugging,
-tracing, and advising (@pxref{Advising Functions}). Since ease of
-debugging and the flexibility of redefining functions are important
-features of Emacs, you should not make a function inline, even if it's
-small, unless its speed is really crucial, and you've timed the code
-to verify that using @code{defun} actually has performance problems.
-
-It's possible to define a macro to expand into the same code that an
-inline function would execute. (@xref{Macros}.) But the macro would be
-limited to direct use in expressions---a macro cannot be called with
-@code{apply}, @code{mapcar} and so on. Also, it takes some work to
-convert an ordinary function into a macro. To convert it into an inline
-function is very easy; simply replace @code{defun} with @code{defsubst}.
-Since each argument of an inline function is evaluated exactly once, you
-needn't worry about how many times the body uses the arguments, as you
-do for macros. (@xref{Argument Evaluation}.)
-
-Inline functions can be used and open-coded later on in the same file,
-following the definition, just like macros.
-
-@node Function Safety
-@section Determining whether a Function is Safe to Call
-@cindex function safety
-@cindex safety of functions
-
-Some major modes such as SES call functions that are stored in user
-files. (@inforef{Top, ,ses}, for more information on SES.) User
-files sometimes have poor pedigrees---you can get a spreadsheet from
-someone you've just met, or you can get one through email from someone
-you've never met. So it is risky to call a function whose source code
-is stored in a user file until you have determined that it is safe.
-
-@defun unsafep form &optional unsafep-vars
-Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
-returns a list that describes why it might be unsafe. The argument
-@var{unsafep-vars} is a list of symbols known to have temporary
-bindings at this point; it is mainly used for internal recursive
-calls. The current buffer is an implicit argument, which provides a
-list of buffer-local bindings.
-@end defun
-
-Being quick and simple, @code{unsafep} does a very light analysis and
-rejects many Lisp expressions that are actually safe. There are no
-known cases where @code{unsafep} returns @code{nil} for an unsafe
-expression. However, a ``safe'' Lisp expression can return a string
-with a @code{display} property, containing an associated Lisp
-expression to be executed after the string is inserted into a buffer.
-This associated expression can be a virus. In order to be safe, you
-must delete properties from all strings calculated by user code before
-inserting them into buffers.
-
-@ignore
-What is a safe Lisp expression? Basically, it's an expression that
-calls only built-in functions with no side effects (or only innocuous
-ones). Innocuous side effects include displaying messages and
-altering non-risky buffer-local variables (but not global variables).
-
-@table @dfn
-@item Safe expression
-@itemize
-@item
-An atom or quoted thing.
-@item
-A call to a safe function (see below), if all its arguments are
-safe expressions.
-@item
-One of the special forms @code{and}, @code{catch}, @code{cond},
-@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
-@code{while}, and @code{unwind-protect}], if all its arguments are
-safe.
-@item
-A form that creates temporary bindings (@code{condition-case},
-@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
-@code{let*}), if all args are safe and the symbols to be bound are not
-explicitly risky (see @pxref{File Local Variables}).
-@item
-An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
-@code{pop}, if all args are safe and the symbols to be assigned are
-not explicitly risky and they already have temporary or buffer-local
-bindings.
-@item
-One of [apply, mapc, mapcar, mapconcat] if the first argument is a
-safe explicit lambda and the other args are safe expressions.
-@end itemize
-
-@item Safe function
-@itemize
-@item
-A lambda containing safe expressions.
-@item
-A symbol on the list @code{safe-functions}, so the user says it's safe.
-@item
-A symbol with a non-@code{nil} @code{side-effect-free} property.
-@item
-A symbol with a non-@code{nil} @code{safe-function} property. Value t
-indicates a function that is safe but has innocuous side effects.
-Other values will someday indicate functions with classes of side
-effects that are not always safe.
-@end itemize
-
-The @code{side-effect-free} and @code{safe-function} properties are
-provided for built-in functions and for low-level functions and macros
-defined in @file{subr.el}. You can assign these properties for the
-functions you write.
-@end table
-@end ignore
-
-@node Related Topics
-@section Other Topics Related to Functions
-
- Here is a table of several functions that do things related to
-function calling and function definitions. They are documented
-elsewhere, but we provide cross references here.
-
-@table @code
-@item apply
-See @ref{Calling Functions}.
-
-@item autoload
-See @ref{Autoload}.
-
-@item call-interactively
-See @ref{Interactive Call}.
-
-@item commandp
-See @ref{Interactive Call}.
-
-@item documentation
-See @ref{Accessing Documentation}.
-
-@item eval
-See @ref{Eval}.
-
-@item funcall
-See @ref{Calling Functions}.
-
-@item function
-See @ref{Anonymous Functions}.
-
-@item ignore
-See @ref{Calling Functions}.
-
-@item indirect-function
-See @ref{Function Indirection}.
-
-@item interactive
-See @ref{Using Interactive}.
-
-@item interactive-p
-See @ref{Interactive Call}.
-
-@item mapatoms
-See @ref{Creating Symbols}.
-
-@item mapcar
-See @ref{Mapping Functions}.
-
-@item map-char-table
-See @ref{Char-Tables}.
-
-@item mapconcat
-See @ref{Mapping Functions}.
-
-@item undefined
-See @ref{Functions for Key Lookup}.
-@end table
-
-@ignore
- arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@setfilename ../info/gpl
-
-@node GPL, Tips, GNU Free Documentation License, Top
-@comment node-name, next, previous, up
-@appendix GNU General Public License
-@c The GNU General Public License.
-@center Version 3, 29 June 2007
-
-@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
-
-@display
-Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-@end display
-
-@heading Preamble
-
-The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
-
-The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works. By contrast,
-the GNU General Public License is intended to guarantee your freedom
-to share and change all versions of a program---to make sure it remains
-free software for all its users. We, the Free Software Foundation,
-use the GNU General Public License for most of our software; it
-applies also to any other work released this way by its authors. You
-can apply it to your programs, too.
-
-When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights. Therefore, you
-have certain responsibilities if you distribute copies of the
-software, or if you modify it: responsibilities to respect the freedom
-of others.
-
-For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received. You must make sure that they, too,
-receive or can get the source code. And you must show them these
-terms so they know their rights.
-
-Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
-For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software. For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the
-manufacturer can do so. This is fundamentally incompatible with the
-aim of protecting users' freedom to change the software. The
-systematic pattern of such abuse occurs in the area of products for
-individuals to use, which is precisely where it is most unacceptable.
-Therefore, we have designed this version of the GPL to prohibit the
-practice for those products. If such problems arise substantially in
-other domains, we stand ready to extend this provision to those
-domains in future versions of the GPL, as needed to protect the
-freedom of users.
-
-Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish
-to avoid the special danger that patents applied to a free program
-could make it effectively proprietary. To prevent this, the GPL
-assures that patents cannot be used to render the program non-free.
-
-The precise terms and conditions for copying, distribution and
-modification follow.
-
-@heading TERMS AND CONDITIONS
-
-@enumerate 0
-@item Definitions.
-
-``This License'' refers to version 3 of the GNU General Public License.
-
-``Copyright'' also means copyright-like laws that apply to other kinds
-of works, such as semiconductor masks.
-
-``The Program'' refers to any copyrightable work licensed under this
-License. Each licensee is addressed as ``you''. ``Licensees'' and
-``recipients'' may be individuals or organizations.
-
-To ``modify'' a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of
-an exact copy. The resulting work is called a ``modified version'' of
-the earlier work or a work ``based on'' the earlier work.
-
-A ``covered work'' means either the unmodified Program or a work based
-on the Program.
-
-To ``propagate'' a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy. Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-To ``convey'' a work means any kind of propagation that enables other
-parties to make or receive copies. Mere interaction with a user
-through a computer network, with no transfer of a copy, is not
-conveying.
-
-An interactive user interface displays ``Appropriate Legal Notices'' to
-the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License. If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-@item Source Code.
-
-The ``source code'' for a work means the preferred form of the work for
-making modifications to it. ``Object code'' means any non-source form
-of a work.
-
-A ``Standard Interface'' means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-The ``System Libraries'' of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form. A
-``Major Component'', in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-The ``Corresponding Source'' for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities. However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work. For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-The Corresponding Source need not include anything that users can
-regenerate automatically from other parts of the Corresponding Source.
-
-The Corresponding Source for a work in source code form is that same
-work.
-
-@item Basic Permissions.
-
-All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met. This License explicitly affirms your unlimited
-permission to run the unmodified Program. The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work. This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-You may make, run and propagate covered works that you do not convey,
-without conditions so long as your license otherwise remains in force.
-You may convey covered works to others for the sole purpose of having
-them make modifications exclusively for you, or provide you with
-facilities for running those works, provided that you comply with the
-terms of this License in conveying all material for which you do not
-control copyright. Those thus making or running the covered works for
-you must do so exclusively on your behalf, under your direction and
-control, on terms that prohibit them from making any copies of your
-copyrighted material outside their relationship with you.
-
-Conveying under any other circumstances is permitted solely under the
-conditions stated below. Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-@item Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such
-circumvention is effected by exercising rights under this License with
-respect to the covered work, and you disclaim any intention to limit
-operation or modification of the work as a means of enforcing, against
-the work's users, your or third parties' legal rights to forbid
-circumvention of technological measures.
-
-@item Conveying Verbatim Copies.
-
-You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-@item Conveying Modified Source Versions.
-
-You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these
-conditions:
-
-@enumerate a
-@item
-The work must carry prominent notices stating that you modified it,
-and giving a relevant date.
-
-@item
-The work must carry prominent notices stating that it is released
-under this License and any conditions added under section 7. This
-requirement modifies the requirement in section 4 to ``keep intact all
-notices''.
-
-@item
-You must license the entire work, as a whole, under this License to
-anyone who comes into possession of a copy. This License will
-therefore apply, along with any applicable section 7 additional terms,
-to the whole of the work, and all its parts, regardless of how they
-are packaged. This License gives no permission to license the work in
-any other way, but it does not invalidate such permission if you have
-separately received it.
-
-@item
-If the work has interactive user interfaces, each must display
-Appropriate Legal Notices; however, if the Program has interactive
-interfaces that do not display Appropriate Legal Notices, your work
-need not make them do so.
-@end enumerate
-
-A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-``aggregate'' if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit. Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-@item Conveying Non-Source Forms.
-
-You may convey a covered work in object code form under the terms of
-sections 4 and 5, provided that you also convey the machine-readable
-Corresponding Source under the terms of this License, in one of these
-ways:
-
-@enumerate a
-@item
-Convey the object code in, or embodied in, a physical product
-(including a physical distribution medium), accompanied by the
-Corresponding Source fixed on a durable physical medium customarily
-used for software interchange.
-
-@item
-Convey the object code in, or embodied in, a physical product
-(including a physical distribution medium), accompanied by a written
-offer, valid for at least three years and valid for as long as you
-offer spare parts or customer support for that product model, to give
-anyone who possesses the object code either (1) a copy of the
-Corresponding Source for all the software in the product that is
-covered by this License, on a durable physical medium customarily used
-for software interchange, for a price no more than your reasonable
-cost of physically performing this conveying of source, or (2) access
-to copy the Corresponding Source from a network server at no charge.
-
-@item
-Convey individual copies of the object code with a copy of the written
-offer to provide the Corresponding Source. This alternative is
-allowed only occasionally and noncommercially, and only if you
-received the object code with such an offer, in accord with subsection
-6b.
-
-@item
-Convey the object code by offering access from a designated place
-(gratis or for a charge), and offer equivalent access to the
-Corresponding Source in the same way through the same place at no
-further charge. You need not require recipients to copy the
-Corresponding Source along with the object code. If the place to copy
-the object code is a network server, the Corresponding Source may be
-on a different server (operated by you or a third party) that supports
-equivalent copying facilities, provided you maintain clear directions
-next to the object code saying where to find the Corresponding Source.
-Regardless of what server hosts the Corresponding Source, you remain
-obligated to ensure that it is available for as long as needed to
-satisfy these requirements.
-
-@item
-Convey the object code using peer-to-peer transmission, provided you
-inform other peers where the object code and Corresponding Source of
-the work are being offered to the general public at no charge under
-subsection 6d.
-
-@end enumerate
-
-A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-A ``User Product'' is either (1) a ``consumer product'', which means any
-tangible personal property which is normally used for personal,
-family, or household purposes, or (2) anything designed or sold for
-incorporation into a dwelling. In determining whether a product is a
-consumer product, doubtful cases shall be resolved in favor of
-coverage. For a particular product received by a particular user,
-``normally used'' refers to a typical or common use of that class of
-product, regardless of the status of the particular user or of the way
-in which the particular user actually uses, or expects or is expected
-to use, the product. A product is a consumer product regardless of
-whether the product has substantial commercial, industrial or
-non-consumer uses, unless such uses represent the only significant
-mode of use of the product.
-
-``Installation Information'' for a User Product means any methods,
-procedures, authorization keys, or other information required to
-install and execute modified versions of a covered work in that User
-Product from a modified version of its Corresponding Source. The
-information must suffice to ensure that the continued functioning of
-the modified object code is in no case prevented or interfered with
-solely because modification has been made.
-
-If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information. But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or
-updates for a work that has been modified or installed by the
-recipient, or for the User Product in which it has been modified or
-installed. Access to a network may be denied when the modification
-itself materially and adversely affects the operation of the network
-or violates the rules and protocols for communication across the
-network.
-
-Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-@item Additional Terms.
-
-``Additional permissions'' are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law. If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it. (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.) You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders
-of that material) supplement the terms of this License with terms:
-
-@enumerate a
-@item
-Disclaiming warranty or limiting liability differently from the terms
-of sections 15 and 16 of this License; or
-
-@item
-Requiring preservation of specified reasonable legal notices or author
-attributions in that material or in the Appropriate Legal Notices
-displayed by works containing it; or
-
-@item
-Prohibiting misrepresentation of the origin of that material, or
-requiring that modified versions of such material be marked in
-reasonable ways as different from the original version; or
-
-@item
-Limiting the use for publicity purposes of names of licensors or
-authors of the material; or
-
-@item
-Declining to grant rights under trademark law for use of some trade
-names, trademarks, or service marks; or
-
-@item
-Requiring indemnification of licensors and authors of that material by
-anyone who conveys the material (or modified versions of it) with
-contractual assumptions of liability to the recipient, for any
-liability that these contractual assumptions directly impose on those
-licensors and authors.
-@end enumerate
-
-All other non-permissive additional terms are considered ``further
-restrictions'' within the meaning of section 10. If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term. If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions; the
-above requirements apply either way.
-
-@item Termination.
-
-You may not propagate or modify a covered work except as expressly
-provided under this License. Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License. If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-@item Acceptance Not Required for Having Copies.
-
-You are not required to accept this License in order to receive or run
-a copy of the Program. Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance. However,
-nothing other than this License grants you permission to propagate or
-modify any covered work. These actions infringe copyright if you do
-not accept this License. Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-@item Automatic Licensing of Downstream Recipients.
-
-Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License. You are not responsible
-for enforcing compliance by third parties with this License.
-
-An ``entity transaction'' is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations. If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License. For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-@item Patents.
-
-A ``contributor'' is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based. The
-work thus licensed is called the contributor's ``contributor version''.
-
-A contributor's ``essential patent claims'' are all patent claims owned
-or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version. For
-purposes of this definition, ``control'' includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-In the following three paragraphs, a ``patent license'' is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement). To ``grant'' such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients. ``Knowingly relying'' means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-A patent license is ``discriminatory'' if it does not include within the
-scope of its coverage, prohibits the exercise of, or is conditioned on
-the non-exercise of one or more of the rights that are specifically
-granted under this License. You may not convey a covered work if you
-are a party to an arrangement with a third party that is in the
-business of distributing software, under which you make payment to the
-third party based on the extent of your activity of conveying the
-work, and under which the third party grants, to any of the parties
-who would receive the covered work from you, a discriminatory patent
-license (a) in connection with copies of the covered work conveyed by
-you (or copies made from those copies), or (b) primarily for and in
-connection with specific products or compilations that contain the
-covered work, unless you entered into that arrangement, or that patent
-license was granted, prior to 28 March 2007.
-
-Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-@item No Surrender of Others' Freedom.
-
-If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot convey
-a covered work so as to satisfy simultaneously your obligations under
-this License and any other pertinent obligations, then as a
-consequence you may not convey it at all. For example, if you agree
-to terms that obligate you to collect a royalty for further conveying
-from those to whom you convey the Program, the only way you could
-satisfy both those terms and this License would be to refrain entirely
-from conveying the Program.
-
-@item Use with the GNU Affero General Public License.
-
-Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
-combined work, and to convey the resulting work. The terms of this
-License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
-
-@item Revised Versions of this License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Program
-specifies that a certain numbered version of the GNU General Public
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that numbered version or
-of any later version published by the Free Software Foundation. If
-the Program does not specify a version number of the GNU General
-Public License, you may choose any version ever published by the Free
-Software Foundation.
-
-If the Program specifies that a proxy can decide which future versions
-of the GNU General Public License can be used, that proxy's public
-statement of acceptance of a version permanently authorizes you to
-choose that version for the Program.
-
-Later license versions may give you additional or different
-permissions. However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-@item Disclaimer of Warranty.
-
-THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
-WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
-DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
-CORRECTION.
-
-@item Limitation of Liability.
-
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
-CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
-ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
-NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
-LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
-TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
-PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-@item Interpretation of Sections 15 and 16.
-
-If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-@end enumerate
-
-@heading END OF TERMS AND CONDITIONS
-
-@heading How to Apply These Terms to Your New Programs
-
-If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these
-terms.
-
-To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the ``copyright'' line and a pointer to where the full notice is found.
-
-@smallexample
-@var{one line to give the program's name and a brief idea of what it does.}
-Copyright (C) @var{year} @var{name of author}
-
-This program 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 of the License, or (at
-your option) any later version.
-
-This program 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 this program. If not, see @url{http://www.gnu.org/licenses/}.
-@end smallexample
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-@smallexample
-@var{program} Copyright (C) @var{year} @var{name of author}
-This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
-This is free software, and you are welcome to redistribute it
-under certain conditions; type @samp{show c} for details.
-@end smallexample
-
-The hypothetical commands @samp{show w} and @samp{show c} should show
-the appropriate parts of the General Public License. Of course, your
-program's commands might be different; for a GUI interface, you would
-use an ``about box''.
-
-You should also get your employer (if you work as a programmer) or school,
-if any, to sign a ``copyright disclaimer'' for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-@url{http://www.gnu.org/licenses/}.
-
-The GNU General Public License does not permit incorporating your
-program into proprietary programs. If your program is a subroutine
-library, you may consider it more useful to permit linking proprietary
-applications with the library. If this is what you want to do, use
-the GNU Lesser General Public License instead of this License. But
-first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
-
-@ignore
- arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005,
-@c 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/hash
-@node Hash Tables, Symbols, Sequences Arrays Vectors, Top
-@chapter Hash Tables
-@cindex hash tables
-@cindex lookup tables
-
- A hash table is a very fast kind of lookup table, somewhat like an
-alist (@pxref{Association Lists}) in that it maps keys to
-corresponding values. It differs from an alist in these ways:
-
-@itemize @bullet
-@item
-Lookup in a hash table is extremely fast for large tables---in fact, the
-time required is essentially @emph{independent} of how many elements are
-stored in the table. For smaller tables (a few tens of elements)
-alists may still be faster because hash tables have a more-or-less
-constant overhead.
-
-@item
-The correspondences in a hash table are in no particular order.
-
-@item
-There is no way to share structure between two hash tables,
-the way two alists can share a common tail.
-@end itemize
-
- Emacs Lisp provides a general-purpose hash table data type, along
-with a series of functions for operating on them. Hash tables have no
-read syntax, and print in hash notation, like this:
-
-@example
-(make-hash-table)
- @result{} #<hash-table 'eql nil 0/65 0x83af980>
-@end example
-
-@noindent
-(The term ``hash notation'' refers to the initial @samp{#}
-character---@pxref{Printed Representation}---and has nothing to do with
-the term ``hash table.'')
-
- Obarrays are also a kind of hash table, but they are a different type
-of object and are used only for recording interned symbols
-(@pxref{Creating Symbols}).
-
-@menu
-* 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.
-@end menu
-
-@node Creating Hash
-@section Creating Hash Tables
-@cindex creating hash tables
-
- The principal function for creating a hash table is
-@code{make-hash-table}.
-
-@defun make-hash-table &rest keyword-args
-This function creates a new hash table according to the specified
-arguments. The arguments should consist of alternating keywords
-(particular symbols recognized specially) and values corresponding to
-them.
-
-Several keywords make sense in @code{make-hash-table}, but the only two
-that you really need to know about are @code{:test} and @code{:weakness}.
-
-@table @code
-@item :test @var{test}
-This specifies the method of key lookup for this hash table. The
-default is @code{eql}; @code{eq} and @code{equal} are other
-alternatives:
-
-@table @code
-@item eql
-Keys which are numbers are ``the same'' if they are @code{equal}, that
-is, if they are equal in value and either both are integers or both
-are floating point numbers; otherwise, two distinct objects are never
-``the same.''
-
-@item eq
-Any two distinct Lisp objects are ``different'' as keys.
-
-@item equal
-Two Lisp objects are ``the same,'' as keys, if they are equal
-according to @code{equal}.
-@end table
-
-You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to
-define additional possibilities for @var{test}.
-
-@item :weakness @var{weak}
-The weakness of a hash table specifies whether the presence of a key or
-value in the hash table preserves it from garbage collection.
-
-The value, @var{weak}, must be one of @code{nil}, @code{key},
-@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
-which is an alias for @code{key-and-value}. If @var{weak} is @code{key}
-then the hash table does not prevent its keys from being collected as
-garbage (if they are not referenced anywhere else); if a particular key
-does get collected, the corresponding association is removed from the
-hash table.
-
-If @var{weak} is @code{value}, then the hash table does not prevent
-values from being collected as garbage (if they are not referenced
-anywhere else); if a particular value does get collected, the
-corresponding association is removed from the hash table.
-
-If @var{weak} is @code{key-and-value} or @code{t}, both the key and
-the value must be live in order to preserve the association. Thus,
-the hash table does not protect either keys or values from garbage
-collection; if either one is collected as garbage, that removes the
-association.
-
-If @var{weak} is @code{key-or-value}, either the key or
-the value can preserve the association. Thus, associations are
-removed from the hash table when both their key and value would be
-collected as garbage (if not for references from weak hash tables).
-
-The default for @var{weak} is @code{nil}, so that all keys and values
-referenced in the hash table are preserved from garbage collection.
-
-@item :size @var{size}
-This specifies a hint for how many associations you plan to store in the
-hash table. If you know the approximate number, you can make things a
-little more efficient by specifying it this way. If you specify too
-small a size, the hash table will grow automatically when necessary, but
-doing that takes some extra time.
-
-The default size is 65.
-
-@item :rehash-size @var{rehash-size}
-When you add an association to a hash table and the table is ``full,''
-it grows automatically. This value specifies how to make the hash table
-larger, at that time.
-
-If @var{rehash-size} is an integer, it should be positive, and the hash
-table grows by adding that much to the nominal size. If
-@var{rehash-size} is a floating point number, it had better be greater
-than 1, and the hash table grows by multiplying the old size by that
-number.
-
-The default value is 1.5.
-
-@item :rehash-threshold @var{threshold}
-This specifies the criterion for when the hash table is ``full'' (so
-it should be made larger). The value, @var{threshold}, should be a
-positive floating point number, no greater than 1. The hash table is
-``full'' whenever the actual number of entries exceeds this fraction
-of the nominal size. The default for @var{threshold} is 0.8.
-@end table
-@end defun
-
-@defun makehash &optional test
-This is equivalent to @code{make-hash-table}, but with a different style
-argument list. The argument @var{test} specifies the method
-of key lookup.
-
-This function is obsolete. Use @code{make-hash-table} instead.
-@end defun
-
-@node Hash Access
-@section Hash Table Access
-
- This section describes the functions for accessing and storing
-associations in a hash table. In general, any Lisp object can be used
-as a hash key, unless the comparison method imposes limits. Any Lisp
-object can also be used as the value.
-
-@defun gethash key table &optional default
-This function looks up @var{key} in @var{table}, and returns its
-associated @var{value}---or @var{default}, if @var{key} has no
-association in @var{table}.
-@end defun
-
-@defun puthash key value table
-This function enters an association for @var{key} in @var{table}, with
-value @var{value}. If @var{key} already has an association in
-@var{table}, @var{value} replaces the old associated value.
-@end defun
-
-@defun remhash key table
-This function removes the association for @var{key} from @var{table}, if
-there is one. If @var{key} has no association, @code{remhash} does
-nothing.
-
-@b{Common Lisp note:} In Common Lisp, @code{remhash} returns
-non-@code{nil} if it actually removed an association and @code{nil}
-otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}.
-@end defun
-
-@defun clrhash table
-This function removes all the associations from hash table @var{table},
-so that it becomes empty. This is also called @dfn{clearing} the hash
-table.
-
-@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
-@var{table}. In Emacs Lisp, it returns @code{nil}.
-@end defun
-
-@defun maphash function table
-@anchor{Definition of maphash}
-This function calls @var{function} once for each of the associations in
-@var{table}. The function @var{function} should accept two
-arguments---a @var{key} listed in @var{table}, and its associated
-@var{value}. @code{maphash} returns @code{nil}.
-@end defun
-
-@node Defining Hash
-@section Defining Hash Comparisons
-@cindex hash code
-@cindex define hash comparisons
-
- You can define new methods of key lookup by means of
-@code{define-hash-table-test}. In order to use this feature, you need
-to understand how hash tables work, and what a @dfn{hash code} means.
-
- You can think of a hash table conceptually as a large array of many
-slots, each capable of holding one association. To look up a key,
-@code{gethash} first computes an integer, the hash code, from the key.
-It reduces this integer modulo the length of the array, to produce an
-index in the array. Then it looks in that slot, and if necessary in
-other nearby slots, to see if it has found the key being sought.
-
- Thus, to define a new method of key lookup, you need to specify both a
-function to compute the hash code from a key, and a function to compare
-two keys directly.
-
-@defun define-hash-table-test name test-fn hash-fn
-This function defines a new hash table test, named @var{name}.
-
-After defining @var{name} in this way, you can use it as the @var{test}
-argument in @code{make-hash-table}. When you do that, the hash table
-will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
-a ``hash code'' from a key value.
-
-The function @var{test-fn} should accept two arguments, two keys, and
-return non-@code{nil} if they are considered ``the same.''
-
-The function @var{hash-fn} should accept one argument, a key, and return
-an integer that is the ``hash code'' of that key. For good results, the
-function should use the whole range of integer values for hash codes,
-including negative integers.
-
-The specified functions are stored in the property list of @var{name}
-under the property @code{hash-table-test}; the property value's form is
-@code{(@var{test-fn} @var{hash-fn})}.
-@end defun
-
-@defun sxhash obj
-This function returns a hash code for Lisp object @var{obj}.
-This is an integer which reflects the contents of @var{obj}
-and the other Lisp objects it points to.
-
-If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
-@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
-
-If the two objects are not equal, the values returned by @code{sxhash}
-are usually different, but not always; once in a rare while, by luck,
-you will encounter two distinct-looking objects that give the same
-result from @code{sxhash}.
-@end defun
-
- This example creates a hash table whose keys are strings that are
-compared case-insensitively.
-
-@example
-(defun case-fold-string= (a b)
- (compare-strings a nil nil b nil nil t))
-(defun case-fold-string-hash (a)
- (sxhash (upcase a)))
-
-(define-hash-table-test 'case-fold
- 'case-fold-string= 'case-fold-string-hash)
-
-(make-hash-table :test 'case-fold)
-@end example
-
- Here is how you could define a hash table test equivalent to the
-predefined test value @code{equal}. The keys can be any Lisp object,
-and equal-looking objects are considered the same key.
-
-@example
-(define-hash-table-test 'contents-hash 'equal 'sxhash)
-
-(make-hash-table :test 'contents-hash)
-@end example
-
-@node Other Hash
-@section Other Hash Table Functions
-
- Here are some other functions for working with hash tables.
-
-@defun hash-table-p table
-This returns non-@code{nil} if @var{table} is a hash table object.
-@end defun
-
-@defun copy-hash-table table
-This function creates and returns a copy of @var{table}. Only the table
-itself is copied---the keys and values are shared.
-@end defun
-
-@defun hash-table-count table
-This function returns the actual number of entries in @var{table}.
-@end defun
-
-@defun hash-table-test table
-This returns the @var{test} value that was given when @var{table} was
-created, to specify how to hash and compare keys. See
-@code{make-hash-table} (@pxref{Creating Hash}).
-@end defun
-
-@defun hash-table-weakness table
-This function returns the @var{weak} value that was specified for hash
-table @var{table}.
-@end defun
-
-@defun hash-table-rehash-size table
-This returns the rehash size of @var{table}.
-@end defun
-
-@defun hash-table-rehash-threshold table
-This returns the rehash threshold of @var{table}.
-@end defun
-
-@defun hash-table-size table
-This returns the current nominal size of @var{table}.
-@end defun
-
-@ignore
- arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/help
-@node Documentation, Files, Modes, Top
-@chapter Documentation
-@cindex documentation strings
-
- GNU Emacs Lisp has convenient on-line help facilities, most of which
-derive their information from the documentation strings associated with
-functions and variables. This chapter describes how to write good
-documentation strings for your Lisp programs, as well as how to write
-programs to access documentation.
-
- Note that the documentation strings for Emacs are not the same thing
-as the Emacs manual. Manuals have their own source files, written in
-the Texinfo language; documentation strings are specified in the
-definitions of the functions and variables they apply to. A collection
-of documentation strings is not sufficient as a manual because a good
-manual is not organized in that fashion; it is organized in terms of
-topics of discussion.
-
- For commands to display documentation strings, see @ref{Help, ,
-Help, emacs, The GNU Emacs Manual}. For the conventions for writing
-documentation strings, see @ref{Documentation Tips}.
-
-@menu
-* 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.
-@end menu
-
-@node Documentation Basics
-@comment node-name, next, previous, up
-@section Documentation Basics
-@cindex documentation conventions
-@cindex writing a documentation string
-@cindex string, writing a doc string
-
- A documentation string is written using the Lisp syntax for strings,
-with double-quote characters surrounding the text of the string. This
-is because it really is a Lisp string object. The string serves as
-documentation when it is written in the proper place in the definition
-of a function or variable. In a function definition, the documentation
-string follows the argument list. In a variable definition, the
-documentation string follows the initial value of the variable.
-
- When you write a documentation string, make the first line a
-complete sentence (or two complete sentences) since some commands,
-such as @code{apropos}, show only the first line of a multi-line
-documentation string. Also, you should not indent the second line of
-a documentation string, if it has one, because that looks odd when you
-use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
-(@code{describe-variable}) to view the documentation string. There
-are many other conventions for doc strings; see @ref{Documentation
-Tips}.
-
- Documentation strings can contain several special substrings, which
-stand for key bindings to be looked up in the current keymaps when the
-documentation is displayed. This allows documentation strings to refer
-to the keys for related commands and be accurate even when a user
-rearranges the key bindings. (@xref{Keys in Documentation}.)
-
-@vindex emacs-lisp-docstring-fill-column
- Emacs Lisp mode fills documentation strings to the width
-specified by @code{emacs-lisp-docstring-fill-column}.
-
- In Emacs Lisp, a documentation string is accessible through the
-function or variable that it describes:
-
-@itemize @bullet
-@item
-@kindex function-documentation
-The documentation for a function is usually stored in the function
-definition itself (@pxref{Lambda Expressions}). The function
-@code{documentation} knows how to extract it. You can also put
-function documentation in the @code{function-documentation} property
-of the function name. That is useful with definitions such as
-keyboard macros that can't hold a documentation string.
-
-@item
-@kindex variable-documentation
-The documentation for a variable is stored in the variable's property
-list under the property name @code{variable-documentation}. The
-function @code{documentation-property} knows how to retrieve it.
-@end itemize
-
-@cindex @file{DOC-@var{version}} (documentation) file
-To save space, the documentation for preloaded functions and variables
-(including primitive functions and autoloaded functions) is stored in
-the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
-documentation strings for functions and variables loaded during the
-Emacs session from byte-compiled files are stored in those files
-(@pxref{Docs and Compilation}).
-
-The data structure inside Emacs has an integer offset into the file, or
-a list containing a file name and an integer, in place of the
-documentation string. The functions @code{documentation} and
-@code{documentation-property} use that information to fetch the
-documentation string from the appropriate file; this is transparent to
-the user.
-
-@c Wordy to prevent overfull hbox. --rjc 15mar92
- The @file{emacs/lib-src} directory contains two utilities that you can
-use to print nice-looking hardcopy for the file
-@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
-@file{digest-doc}.
-
-@node Accessing Documentation
-@section Access to Documentation Strings
-
-@defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded in
-@var{symbol}'s property list under property @var{property}. It
-retrieves the text from a file if the value calls for that. If the
-property value isn't @code{nil}, isn't a string, and doesn't refer to
-text in a file, then it is evaluated to obtain a string.
-
-The last thing this function does is pass the string through
-@code{substitute-command-keys} to substitute actual key bindings,
-unless @var{verbatim} is non-@code{nil}.
-
-@smallexample
-@group
-(documentation-property 'command-line-processed
- 'variable-documentation)
- @result{} "Non-nil once command line has been processed"
-@end group
-@group
-(symbol-plist 'command-line-processed)
- @result{} (variable-documentation 188902)
-@end group
-@group
-(documentation-property 'emacs 'group-documentation)
- @result{} "Customization of the One True Editor."
-@end group
-@end smallexample
-@end defun
-
-@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}.
-@code{documentation} handles macros, named keyboard macros, and
-special forms, as well as ordinary functions.
-
-If @var{function} is a symbol, this function first looks for the
-@code{function-documentation} property of that symbol; if that has a
-non-@code{nil} value, the documentation comes from that value (if the
-value is not a string, it is evaluated). If @var{function} is not a
-symbol, or if it has no @code{function-documentation} property, then
-@code{documentation} extracts the documentation string from the actual
-function definition, reading it from a file if called for.
-
-Finally, unless @var{verbatim} is non-@code{nil}, it calls
-@code{substitute-command-keys} so as to return a value containing the
-actual (current) key bindings.
-
-The function @code{documentation} signals a @code{void-function} error
-if @var{function} has no function definition. However, it is OK if
-the function definition has no documentation string. In that case,
-@code{documentation} returns @code{nil}.
-@end defun
-
-@defun face-documentation face
-This function returns the documentation string of @var{face} as a
-face.
-@end defun
-
-@c Wordy to prevent overfull hboxes. --rjc 15mar92
-Here is an example of using the two functions, @code{documentation} and
-@code{documentation-property}, to display the documentation strings for
-several symbols in a @samp{*Help*} buffer.
-
-@anchor{describe-symbols example}
-@smallexample
-@group
-(defun describe-symbols (pattern)
- "Describe the Emacs Lisp symbols matching PATTERN.
-All symbols that have PATTERN in their name are described
-in the `*Help*' buffer."
- (interactive "sDescribe symbols matching: ")
- (let ((describe-func
- (function
- (lambda (s)
-@end group
-@group
- ;; @r{Print description of symbol.}
- (if (fboundp s) ; @r{It is a function.}
- (princ
- (format "%s\t%s\n%s\n\n" s
- (if (commandp s)
- (let ((keys (where-is-internal s)))
- (if keys
- (concat
- "Keys: "
- (mapconcat 'key-description
- keys " "))
- "Keys: none"))
- "Function")
-@end group
-@group
- (or (documentation s)
- "not documented"))))
-
- (if (boundp s) ; @r{It is a variable.}
-@end group
-@group
- (princ
- (format "%s\t%s\n%s\n\n" s
- (if (user-variable-p s)
- "Option " "Variable")
-@end group
-@group
- (or (documentation-property
- s 'variable-documentation)
- "not documented")))))))
- sym-list)
-@end group
-
-@group
- ;; @r{Build a list of symbols that match pattern.}
- (mapatoms (function
- (lambda (sym)
- (if (string-match pattern (symbol-name sym))
- (setq sym-list (cons sym sym-list))))))
-@end group
-
-@group
- ;; @r{Display the data.}
- (with-output-to-temp-buffer "*Help*"
- (mapcar describe-func (sort sym-list 'string<))
- (print-help-return-message))))
-@end group
-@end smallexample
-
- The @code{describe-symbols} function works like @code{apropos},
-but provides more information.
-
-@smallexample
-@group
-(describe-symbols "goal")
-
----------- Buffer: *Help* ----------
-goal-column Option
-*Semipermanent goal column for vertical motion, as set by @dots{}
-@end group
-@c Do not blithely break or fill these lines.
-@c That makes them incorrect.
-
-@group
-set-goal-column Keys: C-x C-n
-Set the current horizontal position as a goal for C-n and C-p.
-@end group
-@c DO NOT put a blank line here! That is factually inaccurate!
-@group
-Those commands will move to this position in the line moved to
-rather than trying to keep the same horizontal position.
-With a non-nil argument, clears out the goal column
-so that C-n and C-p resume vertical motion.
-The goal column is stored in the variable `goal-column'.
-@end group
-
-@group
-temporary-goal-column Variable
-Current goal column for vertical motion.
-It is the column where point was
-at the start of current run of vertical motion commands.
-When the `track-eol' feature is doing its job, the value is 9999.
----------- Buffer: *Help* ----------
-@end group
-@end smallexample
-
-The asterisk @samp{*} as the first character of a variable's doc string,
-as shown above for the @code{goal-column} variable, means that it is a
-user option; see the description of @code{defvar} in @ref{Defining
-Variables}.
-
-@defun Snarf-documentation filename
-@anchor{Definition of Snarf-documentation}
-This function is used only during Emacs initialization, just before
-the runnable Emacs is dumped. It finds the file offsets of the
-documentation strings stored in the file @var{filename}, and records
-them in the in-core function definitions and variable property lists in
-place of the actual strings. @xref{Building Emacs}.
-
-Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
-When the dumped Emacs is later executed, the same file will be looked
-for in the directory @code{doc-directory}. Usually @var{filename} is
-@code{"DOC-@var{version}"}.
-@end defun
-
-@c Emacs 19 feature
-@defvar doc-directory
-This variable holds the name of the directory which should contain the
-file @code{"DOC-@var{version}"} that contains documentation strings for
-built-in and preloaded functions and variables.
-
-In most cases, this is the same as @code{data-directory}. They may be
-different when you run Emacs from the directory where you built it,
-without actually installing it. @xref{Definition of data-directory}.
-
-In older Emacs versions, @code{exec-directory} was used for this.
-@end defvar
-
-@node Keys in Documentation
-@section Substituting Key Bindings in Documentation
-@cindex documentation, keys in
-@cindex keys in documentation strings
-@cindex substituting keys in documentation
-
- When documentation strings refer to key sequences, they should use the
-current, actual key bindings. They can do so using certain special text
-sequences described below. Accessing documentation strings in the usual
-way substitutes current key binding information for these special
-sequences. This works by calling @code{substitute-command-keys}. You
-can also call that function yourself.
-
- Here is a list of the special sequences and what they mean:
-
-@table @code
-@item \[@var{command}]
-stands for a key sequence that will invoke @var{command}, or @samp{M-x
-@var{command}} if @var{command} has no key bindings.
-
-@item \@{@var{mapvar}@}
-stands for a summary of the keymap which is the value of the variable
-@var{mapvar}. The summary is made using @code{describe-bindings}.
-
-@item \<@var{mapvar}>
-stands for no text itself. It is used only for a side effect: it
-specifies @var{mapvar}'s value as the keymap for any following
-@samp{\[@var{command}]} sequences in this documentation string.
-
-@item \=
-quotes the following character and is discarded; thus, @samp{\=\[} puts
-@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
-output.
-@end table
-
-@strong{Please note:} Each @samp{\} must be doubled when written in a
-string in Emacs Lisp.
-
-@defun substitute-command-keys string
-This function scans @var{string} for the above special sequences and
-replaces them by what they stand for, returning the result as a string.
-This permits display of documentation that refers accurately to the
-user's own customized key bindings.
-@end defun
-
- Here are examples of the special sequences:
-
-@smallexample
-@group
-(substitute-command-keys
- "To abort recursive edit, type: \\[abort-recursive-edit]")
-@result{} "To abort recursive edit, type: C-]"
-@end group
-
-@group
-(substitute-command-keys
- "The keys that are defined for the minibuffer here are:
- \\@{minibuffer-local-must-match-map@}")
-@result{} "The keys that are defined for the minibuffer here are:
-@end group
-
-? minibuffer-completion-help
-SPC minibuffer-complete-word
-TAB minibuffer-complete
-C-j minibuffer-complete-and-exit
-RET minibuffer-complete-and-exit
-C-g abort-recursive-edit
-"
-
-@group
-(substitute-command-keys
- "To abort a recursive edit from the minibuffer, type\
-\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
-@result{} "To abort a recursive edit from the minibuffer, type C-g."
-@end group
-@end smallexample
-
- There are other special conventions for the text in documentation
-strings---for instance, you can refer to functions, variables, and
-sections of this manual. @xref{Documentation Tips}, for details.
-
-@node Describing Characters
-@section Describing Characters for Help Messages
-@cindex describe characters and events
-
- These functions convert events, key sequences, or characters to
-textual descriptions. These descriptions are useful for including
-arbitrary text characters or key sequences in messages, because they
-convert non-printing and whitespace characters to sequences of printing
-characters. The description of a non-whitespace printing character is
-the character itself.
-
-@defun key-description sequence &optional prefix
-@cindex Emacs event standard notation
-This function returns a string containing the Emacs standard notation
-for the input events in @var{sequence}. If @var{prefix} is
-non-@code{nil}, it is a sequence of input events leading up to
-@var{sequence} and is included in the return value. Both arguments
-may be strings, vectors or lists. @xref{Input Events}, for more
-information about valid events.
-
-@smallexample
-@group
-(key-description [?\M-3 delete])
- @result{} "M-3 <delete>"
-@end group
-@group
-(key-description [delete] "\M-3")
- @result{} "M-3 <delete>"
-@end group
-@end smallexample
-
- See also the examples for @code{single-key-description}, below.
-@end defun
-
-@defun single-key-description event &optional no-angles
-@cindex event printing
-@cindex character printing
-@cindex control character printing
-@cindex meta character printing
-This function returns a string describing @var{event} in the standard
-Emacs notation for keyboard input. A normal printing character
-appears as itself, but a control character turns into a string
-starting with @samp{C-}, a meta character turns into a string starting
-with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
-@samp{TAB}, etc. A function key symbol appears inside angle brackets
-@samp{<@dots{}>}. An event that is a list appears as the name of the
-symbol in the @sc{car} of the list, inside angle brackets.
-
-If the optional argument @var{no-angles} is non-@code{nil}, the angle
-brackets around function keys and event symbols are omitted; this is
-for compatibility with old versions of Emacs which didn't use the
-brackets.
-
-@smallexample
-@group
-(single-key-description ?\C-x)
- @result{} "C-x"
-@end group
-@group
-(key-description "\C-x \M-y \n \t \r \f123")
- @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
-@end group
-@group
-(single-key-description 'delete)
- @result{} "<delete>"
-@end group
-@group
-(single-key-description 'C-mouse-1)
- @result{} "<C-mouse-1>"
-@end group
-@group
-(single-key-description 'C-mouse-1 t)
- @result{} "C-mouse-1"
-@end group
-@end smallexample
-@end defun
-
-@defun text-char-description character
-This function returns a string describing @var{character} in the
-standard Emacs notation for characters that appear in text---like
-@code{single-key-description}, except that control characters are
-represented with a leading caret (which is how control characters in
-Emacs buffers are usually displayed). Another difference is that
-@code{text-char-description} recognizes the 2**7 bit as the Meta
-character, whereas @code{single-key-description} uses the 2**27 bit
-for Meta.
-
-@smallexample
-@group
-(text-char-description ?\C-c)
- @result{} "^C"
-@end group
-@group
-(text-char-description ?\M-m)
- @result{} "\xed"
-@end group
-@group
-(text-char-description ?\C-\M-m)
- @result{} "\x8d"
-@end group
-@group
-(text-char-description (+ 128 ?m))
- @result{} "M-m"
-@end group
-@group
-(text-char-description (+ 128 ?\C-m))
- @result{} "M-^M"
-@end group
-@end smallexample
-@end defun
-
-@defun read-kbd-macro string &optional need-vector
-This function is used mainly for operating on keyboard macros, but it
-can also be used as a rough inverse for @code{key-description}. You
-call it with a string containing key descriptions, separated by spaces;
-it returns a string or vector containing the corresponding events.
-(This may or may not be a single valid key sequence, depending on what
-events you use; @pxref{Key Sequences}.) If @var{need-vector} is
-non-@code{nil}, the return value is always a vector.
-@end defun
-
-@node Help Functions
-@section Help Functions
-
- Emacs provides a variety of on-line help functions, all accessible to
-the user as subcommands of the prefix @kbd{C-h}. For more information
-about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
-we describe some program-level interfaces to the same information.
-
-@deffn Command apropos pattern &optional do-all
-This function finds all ``meaningful'' symbols whose names contain a
-match for the apropos pattern @var{pattern}. An apropos pattern is
-either a word to match, a space-separated list of words of which at
-least two must match, or a regular expression (if any special regular
-expression characters occur). A symbol is ``meaningful'' if it has a
-definition as a function, variable, or face, or has properties.
-
-The function returns a list of elements that look like this:
-
-@example
-(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
- @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
-@end example
-
-Here, @var{score} is an integer measure of how important the symbol
-seems to be as a match, and the remaining elements are documentation
-strings for @var{symbol}'s various roles (or @code{nil}).
-
-It also displays the symbols in a buffer named @samp{*Apropos*}, each
-with a one-line description taken from the beginning of its
-documentation string.
-
-@c Emacs 19 feature
-If @var{do-all} is non-@code{nil}, or if the user option
-@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
-shows key bindings for the functions that are found; it also shows
-@emph{all} interned symbols, not just meaningful ones (and it lists
-them in the return value as well).
-@end deffn
-
-@defvar help-map
-The value of this variable is a local keymap for characters following the
-Help key, @kbd{C-h}.
-@end defvar
-
-@deffn {Prefix Command} help-command
-This symbol is not a function; its function definition cell holds the
-keymap known as @code{help-map}. It is defined in @file{help.el} as
-follows:
-
-@smallexample
-@group
-(define-key global-map (char-to-string help-char) 'help-command)
-(fset 'help-command help-map)
-@end group
-@end smallexample
-@end deffn
-
-@defun print-help-return-message &optional function
-This function builds a string that explains how to restore the previous
-state of the windows after a help command. After building the message,
-it applies @var{function} to it if @var{function} is non-@code{nil}.
-Otherwise it calls @code{message} to display it in the echo area.
-
-This function expects to be called inside a
-@code{with-output-to-temp-buffer} special form, and expects
-@code{standard-output} to have the value bound by that special form.
-For an example of its use, see the long example in @ref{Accessing
-Documentation}.
-@end defun
-
-@defvar help-char
-The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help. By default, its value is 8, which
-stands for @kbd{C-h}. When Emacs reads this character, if
-@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
-expression, and displays the result in a window if it is a string.
-
-Usually the value of @code{help-form} is @code{nil}. Then the
-help character has no special meaning at the level of command input, and
-it becomes part of a key sequence in the normal way. The standard key
-binding of @kbd{C-h} is a prefix key for several general-purpose help
-features.
-
-The help character is special after prefix keys, too. If it has no
-binding as a subcommand of the prefix key, it runs
-@code{describe-prefix-bindings}, which displays a list of all the
-subcommands of the prefix key.
-@end defvar
-
-@defvar help-event-list
-The value of this variable is a list of event types that serve as
-alternative ``help characters.'' These events are handled just like the
-event specified by @code{help-char}.
-@end defvar
-
-@defvar help-form
-If this variable is non-@code{nil}, its value is a form to evaluate
-whenever the character @code{help-char} is read. If evaluating the form
-produces a string, that string is displayed.
-
-A command that calls @code{read-event} or @code{read-char} probably
-should bind @code{help-form} to a non-@code{nil} expression while it
-does input. (The time when you should not do this is when @kbd{C-h} has
-some other meaning.) Evaluating this expression should result in a
-string that explains what the input is for and how to enter it properly.
-
-Entry to the minibuffer binds this variable to the value of
-@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
-@end defvar
-
-@defvar prefix-help-command
-This variable holds a function to print help for a prefix key. The
-function is called when the user types a prefix key followed by the help
-character, and the help character has no binding after that prefix. The
-variable's default value is @code{describe-prefix-bindings}.
-@end defvar
-
-@defun describe-prefix-bindings
-This function calls @code{describe-bindings} to display a list of all
-the subcommands of the prefix key of the most recent key sequence. The
-prefix described consists of all but the last event of that key
-sequence. (The last event is, presumably, the help character.)
-@end defun
-
- The following two functions are meant for modes that want to provide
-help without relinquishing control, such as the ``electric'' modes.
-Their names begin with @samp{Helper} to distinguish them from the
-ordinary help functions.
-
-@deffn Command Helper-describe-bindings
-This command pops up a window displaying a help buffer containing a
-listing of all of the key bindings from both the local and global keymaps.
-It works by calling @code{describe-bindings}.
-@end deffn
-
-@deffn Command Helper-help
-This command provides help for the current mode. It prompts the user
-in the minibuffer with the message @samp{Help (Type ? for further
-options)}, and then provides assistance in finding out what the key
-bindings are, and what the mode is intended for. It returns @code{nil}.
-
-This can be customized by changing the map @code{Helper-help-map}.
-@end deffn
-
-@c Emacs 19 feature
-@defvar data-directory
-@anchor{Definition of data-directory}
-This variable holds the name of the directory in which Emacs finds
-certain documentation and text files that come with Emacs. In older
-Emacs versions, @code{exec-directory} was used for this.
-@end defvar
-
-@c Emacs 19 feature
-@defmac make-help-screen fname help-line help-text help-map
-This macro defines a help command named @var{fname} that acts like a
-prefix key that shows a list of the subcommands it offers.
-
-When invoked, @var{fname} displays @var{help-text} in a window, then
-reads and executes a key sequence according to @var{help-map}. The
-string @var{help-text} should describe the bindings available in
-@var{help-map}.
-
-The command @var{fname} is defined to handle a few events itself, by
-scrolling the display of @var{help-text}. When @var{fname} reads one of
-those special events, it does the scrolling and then reads another
-event. When it reads an event that is not one of those few, and which
-has a binding in @var{help-map}, it executes that key's binding and
-then returns.
-
-The argument @var{help-line} should be a single-line summary of the
-alternatives in @var{help-map}. In the current version of Emacs, this
-argument is used only if you set the option @code{three-step-help} to
-@code{t}.
-
-This macro is used in the command @code{help-for-help} which is the
-binding of @kbd{C-h C-h}.
-@end defmac
-
-@defopt three-step-help
-If this variable is non-@code{nil}, commands defined with
-@code{make-help-screen} display their @var{help-line} strings in the
-echo area at first, and display the longer @var{help-text} strings only
-if the user types the help character again.
-@end defopt
-
-@ignore
- arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/hooks
-@node Standard Hooks, Index, Standard Keymaps, Top
-@appendix Standard Hooks
-@cindex standard hooks
-@cindex hook variables, list of
-
-The following is a list of hook variables that let you provide
-functions to be called from within Emacs on suitable occasions.
-
-Most of these variables have names ending with @samp{-hook}. They are
-@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such
-a hook is a list of functions; the functions are called with no
-arguments and their values are completely ignored. The recommended way
-to put a new function on such a hook is to call @code{add-hook}.
-@xref{Hooks}, for more information about using hooks.
-
-Every major mode defines a mode hook named
-@samp{@var{modename}-mode-hook}. The major mode command runs this
-normal hook with @code{run-mode-hooks} as the very last thing it does.
-@xref{Mode Hooks}. Most minor modes have mode hooks too. Mode hooks
-are omitted in the list below.
-
-The variables whose names end in @samp{-hooks} or @samp{-functions} are
-usually @dfn{abnormal hooks}; their values are lists of functions, but
-these functions are called in a special way (they are passed arguments,
-or their values are used). The variables whose names end in
-@samp{-function} have single functions as their values.
-
-@c We need to xref to where each hook is documented or else document
-@c it here.
-
-@table @code
-@item activate-mark-hook
-@xref{The Mark}.
-
-@item after-change-functions
-@xref{Change Hooks}.
-
-@item after-change-major-mode-hook
-@xref{Mode Hooks}.
-
-@item after-init-hook
-@xref{Init File}.
-
-@item after-insert-file-functions
-@xref{Format Conversion}.
-
-@item after-make-frame-functions
-@xref{Creating Frames}.
-
-@item after-revert-hook
-@xref{Reverting}.
-
-@item after-save-hook
-@xref{Saving Buffers}.
-
-@item auto-fill-function
-@xref{Auto Filling}.
-
-@item auto-save-hook
-@xref{Auto-Saving}.
-
-@item before-change-functions
-@xref{Change Hooks}.
-
-@item before-init-hook
-@xref{Init File}.
-
-@item before-make-frame-hook
-@xref{Creating Frames}.
-
-@item before-revert-hook
-@xref{Reverting}.
-
-@item before-save-hook
-@xref{Saving Buffers}.
-
-@item blink-paren-function
-@xref{Blinking}.
-
-@item buffer-access-fontify-functions
-@xref{Lazy Properties}.
-
-@item calendar-load-hook
-@iftex
-@inforef{Calendar Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing,,, emacs}.
-@end ifnottex
-
-
-@item change-major-mode-hook
-@xref{Creating Buffer-Local}.
-
-@item command-line-functions
-@xref{Command-Line Arguments}.
-
-@item comment-indent-function
-@xref{Options for Comments,, Options Controlling Comments, emacs, the
-GNU Emacs Manual}.
-
-@item compilation-finish-functions
-Functions to call when a compilation process finishes.
-
-@item custom-define-hook
-Hook called after defining each customize option.
-
-@item deactivate-mark-hook
-@xref{The Mark}.
-
-@item desktop-after-read-hook
-Normal hook run after a successful @code{desktop-read}. May be used
-to show a buffer list. @xref{Saving Emacs Sessions,, Saving Emacs
-Sessions, emacs, the GNU Emacs Manual}.
-
-@item desktop-no-desktop-file-hook
-Normal hook run when @code{desktop-read} can't find a desktop file.
-May be used to show a dired buffer. @xref{Saving Emacs Sessions,,
-Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
-
-@item desktop-save-hook
-Normal hook run before the desktop is saved in a desktop file. This
-is useful for truncating history lists, for example. @xref{Saving
-Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
-
-@item diary-display-hook
-@iftex
-@inforef{Fancy Diary Display,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Fancy Diary Display,,, emacs}.
-@end ifnottex
-
-@item diary-hook
-List of functions called after the display of the diary. Can be used
-for appointment notification.
-
-@item disabled-command-function
-@xref{Disabling Commands}.
-
-@item echo-area-clear-hook
-@xref{Echo Area Customization}.
-
-@item emacs-startup-hook
-@xref{Init File}.
-
-@item find-file-hook
-@xref{Visiting Functions}.
-
-@item find-file-not-found-functions
-@xref{Visiting Functions}.
-
-@item first-change-hook
-@xref{Change Hooks}.
-
-@item font-lock-beginning-of-syntax-function
-@xref{Syntactic Font Lock}.
-
-@item font-lock-fontify-buffer-function
-@xref{Other Font Lock Variables}.
-
-@item font-lock-fontify-region-function
-@xref{Other Font Lock Variables}.
-
-@item font-lock-mark-block-function
-@xref{Other Font Lock Variables}.
-
-@item font-lock-syntactic-face-function
-@xref{Syntactic Font Lock}.
-
-@item font-lock-unfontify-buffer-function
-@xref{Other Font Lock Variables}.
-
-@item font-lock-unfontify-region-function
-@xref{Other Font Lock Variables}.
-
-@item initial-calendar-window-hook
-@iftex
-@inforef{Calendar Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing,,, emacs}.
-@end ifnottex
-
-@item kbd-macro-termination-hook
-@xref{Keyboard Macros}.
-
-@item kill-buffer-hook
-@xref{Killing Buffers}.
-
-@item kill-buffer-query-functions
-@xref{Killing Buffers}.
-
-@item kill-emacs-hook
-@xref{Killing Emacs}.
-
-@item kill-emacs-query-functions
-@xref{Killing Emacs}.
-
-@item lisp-indent-function
-
-@item list-diary-entries-hook
-@iftex
-@inforef{Fancy Diary Display,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Fancy Diary Display,,, emacs}.
-@end ifnottex
-
-@item mail-setup-hook
-@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs
-Manual}.
-
-@item mark-diary-entries-hook
-@iftex
-@inforef{Fancy Diary Display,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Fancy Diary Display,,, emacs}.
-@end ifnottex
-
-@item menu-bar-update-hook
-@xref{Menu Bar}.
-
-@item minibuffer-setup-hook
-@xref{Minibuffer Misc}.
-
-@item minibuffer-exit-hook
-@xref{Minibuffer Misc}.
-
-@item mouse-position-function
-@xref{Mouse Position}.
-
-@item nongregorian-diary-listing-hook
-@iftex
-@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Hebrew/Islamic Entries,,, emacs}.
-@end ifnottex
-
-@item nongregorian-diary-marking-hook
-@iftex
-@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Hebrew/Islamic Entries,,, emacs}.
-@end ifnottex
-
-@item occur-hook
-
-@item post-command-hook
-@xref{Command Overview}.
-
-@item pre-abbrev-expand-hook
-@xref{Abbrev Expansion}.
-
-@item pre-command-hook
-@xref{Command Overview}.
-
-@item print-diary-entries-hook
-@iftex
-@inforef{Diary Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Diary Customizing,,, emacs}.
-@end ifnottex
-
-@item redisplay-end-trigger-functions
-@xref{Window Hooks}.
-
-@item scheme-indent-function
-
-@item suspend-hook
-@xref{Suspending Emacs}.
-
-@item suspend-resume-hook
-@xref{Suspending Emacs}.
-
-@item temp-buffer-setup-hook
-@xref{Temporary Displays}.
-
-@item temp-buffer-show-function
-@xref{Temporary Displays}.
-
-@item temp-buffer-show-hook
-@xref{Temporary Displays}.
-
-@item term-setup-hook
-@xref{Terminal-Specific}.
-
-@item today-visible-calendar-hook
-@iftex
-@inforef{Calendar Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing,,, emacs}.
-@end ifnottex
-
-@item today-invisible-calendar-hook
-@iftex
-@inforef{Calendar Customizing,, emacs-xtra}.
-@end iftex
-@ifnottex
-@xref{Calendar Customizing,,, emacs}.
-@end ifnottex
-
-@item window-configuration-change-hook
-@xref{Window Hooks}.
-
-@item window-scroll-functions
-@xref{Window Hooks}.
-
-@item window-setup-hook
-@xref{Window Systems}.
-
-@item window-size-change-functions
-@xref{Window Hooks}.
-
-@item write-contents-functions
-@xref{Saving Buffers}.
-
-@item write-file-functions
-@xref{Saving Buffers}.
-
-@item write-region-annotate-functions
-@xref{Format Conversion}.
-@end table
-
-@ignore
- arch-tag: 55fd0296-d906-4551-b300-979d3846aa88
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@setfilename ../info/index
-
-@c Indexing guidelines
-
-@c I assume that all indexes will be combined.
-@c Therefore, if a generated findex and permutations
-@c cover the ways an index user would look up the entry,
-@c then no cindex is added.
-@c Concept index (cindex) entries will also be permuted. Therefore, they
-@c have no commas and few irrelevant connectives in them.
-
-@c I tried to include words in a cindex that give the context of the entry,
-@c particularly if there is more than one entry for the same concept.
-@c For example, "nil in keymap"
-@c Similarly for explicit findex and vindex entries, e.g. "print example".
-
-@c Error codes are given cindex entries, e.g. "end-of-file error".
-
-@c pindex is used for .el files and Unix programs
-
-@node Index, , Standard Hooks, Top
-@unnumbered Index
-
-@c Print the indices
-
-@printindex fn
-
-
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/internals
-@node GNU Emacs Internals, Standard Errors, Tips, Top
-@comment node-name, next, previous, up
-@appendix GNU Emacs Internals
-
-This chapter describes how the runnable Emacs executable is dumped with
-the preloaded Lisp libraries in it, how storage is allocated, and some
-internal aspects of GNU Emacs that may be of interest to C programmers.
-
-@menu
-* 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.
-@end menu
-
-@node Building Emacs
-@appendixsec Building Emacs
-@cindex building Emacs
-@pindex temacs
-
- This section explains the steps involved in building the Emacs
-executable. You don't have to know this material to build and install
-Emacs, since the makefiles do all these things automatically. This
-information is pertinent to Emacs maintenance.
-
- Compilation of the C source files in the @file{src} directory
-produces an executable file called @file{temacs}, also called a
-@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O
-routines, but not the editing commands.
-
-@cindex @file{loadup.el}
- The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
-the real runnable Emacs executable. These arguments direct
-@file{temacs} to evaluate the Lisp files specified in the file
-@file{loadup.el}. These files set up the normal Emacs editing
-environment, resulting in an Emacs that is still impure but no longer
-bare.
-
-@cindex dumping Emacs
- It takes a substantial time to load the standard Lisp files. Luckily,
-you don't have to do this each time you run Emacs; @file{temacs} can
-dump out an executable program called @file{emacs} that has these files
-preloaded. @file{emacs} starts more quickly because it does not need to
-load the files. This is the Emacs executable that is normally
-installed.
-
- To create @file{emacs}, use the command @samp{temacs -batch -l loadup
-dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
-from trying to initialize any of its data on the terminal; this ensures
-that the tables of terminal information are empty in the dumped Emacs.
-The argument @samp{dump} tells @file{loadup.el} to dump a new executable
-named @file{emacs}.
-
- Some operating systems don't support dumping. On those systems, you
-must start Emacs with the @samp{temacs -l loadup} command each time you
-use it. This takes a substantial time, but since you need to start
-Emacs once a day at most---or once a week if you never log out---the
-extra time is not too severe a problem.
-
-@cindex @file{site-load.el}
-
- You can specify additional files to preload by writing a library named
-@file{site-load.el} that loads them. You may need to add a definition
-
-@example
-#define SITELOAD_PURESIZE_EXTRA @var{n}
-@end example
-
-@noindent
-to make @var{n} added bytes of pure space to hold the additional files.
-(Try adding increments of 20000 until it is big enough.) However, the
-advantage of preloading additional files decreases as machines get
-faster. On modern machines, it is usually not advisable.
-
- After @file{loadup.el} reads @file{site-load.el}, it finds the
-documentation strings for primitive and preloaded functions (and
-variables) in the file @file{etc/DOC} where they are stored, by
-calling @code{Snarf-documentation} (@pxref{Definition of
-Snarf-documentation,, Accessing Documentation}).
-
-@cindex @file{site-init.el}
-@cindex preloading additional functions and variables
- You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named @file{site-init.el}. This file is
-executed after the documentation strings are found.
-
- If you want to preload function or variable definitions, there are
-three ways you can do this and make their documentation strings
-accessible when you subsequently run Emacs:
-
-@itemize @bullet
-@item
-Arrange to scan these files when producing the @file{etc/DOC} file,
-and load them with @file{site-load.el}.
-
-@item
-Load the files with @file{site-init.el}, then copy the files into the
-installation directory for Lisp files when you install Emacs.
-
-@item
-Specify a non-@code{nil} value for
-@code{byte-compile-dynamic-docstrings} as a local variable in each of these
-files, and load them with either @file{site-load.el} or
-@file{site-init.el}. (This method has the drawback that the
-documentation strings take up space in Emacs all the time.)
-@end itemize
-
- It is not advisable to put anything in @file{site-load.el} or
-@file{site-init.el} that would alter any of the features that users
-expect in an ordinary unmodified Emacs. If you feel you must override
-normal features for your site, do it with @file{default.el}, so that
-users can override your changes if they wish. @xref{Startup Summary}.
-
- In a package that can be preloaded, it is sometimes useful to
-specify a computation to be done when Emacs subsequently starts up.
-For this, use @code{eval-at-startup}:
-
-@defmac eval-at-startup body@dots{}
-This evaluates the @var{body} forms, either immediately if running in
-an Emacs that has already started up, or later when Emacs does start
-up. Since the value of the @var{body} forms is not necessarily
-available when the @code{eval-at-startup} form is run, that form
-always returns @code{nil}.
-@end defmac
-
-@defun dump-emacs to-file from-file
-@cindex unexec
-This function dumps the current state of Emacs into an executable file
-@var{to-file}. It takes symbols from @var{from-file} (this is normally
-the executable file @file{temacs}).
-
-If you want to use this function in an Emacs that was already dumped,
-you must run Emacs with @samp{-batch}.
-@end defun
-
-@node Pure Storage
-@appendixsec Pure Storage
-@cindex pure storage
-
- Emacs Lisp uses two kinds of storage for user-created Lisp objects:
-@dfn{normal storage} and @dfn{pure storage}. Normal storage is where
-all the new data created during an Emacs session are kept; see the
-following section for information on normal storage. Pure storage is
-used for certain data in the preloaded standard Lisp files---data that
-should never change during actual use of Emacs.
-
- Pure storage is allocated only while @file{temacs} is loading the
-standard preloaded Lisp libraries. In the file @file{emacs}, it is
-marked as read-only (on operating systems that permit this), so that
-the memory space can be shared by all the Emacs jobs running on the
-machine at once. Pure storage is not expandable; a fixed amount is
-allocated when Emacs is compiled, and if that is not sufficient for
-the preloaded libraries, @file{temacs} allocates dynamic memory for
-the part that didn't fit. If that happens, you should increase the
-compilation parameter @code{PURESIZE} in the file
-@file{src/puresize.h} and rebuild Emacs, even though the resulting
-image will work: garbage collection is disabled in this situation,
-causing a memory leak. Such an overflow normally won't happen unless you
-try to preload additional libraries or add features to the standard
-ones. Emacs will display a warning about the overflow when it
-starts.
-
-@defun purecopy object
-This function makes a copy in pure storage of @var{object}, and returns
-it. It copies a string by simply making a new string with the same
-characters, but without text properties, in pure storage. It
-recursively copies the contents of vectors and cons cells. It does
-not make copies of other objects such as symbols, but just returns
-them unchanged. It signals an error if asked to copy markers.
-
-This function is a no-op except while Emacs is being built and dumped;
-it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
-a few packages call it just in case you decide to preload them.
-@end defun
-
-@defvar pure-bytes-used
-The value of this variable is the number of bytes of pure storage
-allocated so far. Typically, in a dumped Emacs, this number is very
-close to the total amount of pure storage available---if it were not,
-we would preallocate less.
-@end defvar
-
-@defvar purify-flag
-This variable determines whether @code{defun} should make a copy of the
-function definition in pure storage. If it is non-@code{nil}, then the
-function definition is copied into pure storage.
-
-This flag is @code{t} while loading all of the basic functions for
-building Emacs initially (allowing those functions to be sharable and
-non-collectible). Dumping Emacs as an executable always writes
-@code{nil} in this variable, regardless of the value it actually has
-before and after dumping.
-
-You should not change this flag in a running Emacs.
-@end defvar
-
-@node Garbage Collection
-@appendixsec Garbage Collection
-@cindex garbage collection
-
-@cindex memory allocation
- When a program creates a list or the user defines a new function (such
-as by loading a library), that data is placed in normal storage. If
-normal storage runs low, then Emacs asks the operating system to
-allocate more memory in blocks of 1k bytes. Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory. (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes.)
-
- It is quite common to use some storage for a while, then release it by
-(for example) killing a buffer or deleting the last pointer to an
-object. Emacs provides a @dfn{garbage collector} to reclaim this
-abandoned storage. (This name is traditional, but ``garbage recycler''
-might be a more intuitive metaphor for this facility.)
-
- The garbage collector operates by finding and marking all Lisp objects
-that are still accessible to Lisp programs. To begin with, it assumes
-all the symbols, their values and associated function definitions, and
-any data presently on the stack, are accessible. Any objects that can
-be reached indirectly through other accessible objects are also
-accessible.
-
- When marking is finished, all objects still unmarked are garbage. No
-matter what the Lisp program or the user does, it is impossible to refer
-to them, since there is no longer a way to reach them. Their space
-might as well be reused, since no one will miss them. The second
-(``sweep'') phase of the garbage collector arranges to reuse them.
-
-@c ??? Maybe add something describing weak hash tables here?
-
-@cindex free list
- The sweep phase puts unused cons cells onto a @dfn{free list}
-for future allocation; likewise for symbols and markers. It compacts
-the accessible strings so they occupy fewer 8k blocks; then it frees the
-other 8k blocks. Vectors, buffers, windows, and other large objects are
-individually allocated and freed using @code{malloc} and @code{free}.
-
-@cindex CL note---allocate more storage
-@quotation
-@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
-call the garbage collector when the free list is empty. Instead, it
-simply requests the operating system to allocate more storage, and
-processing continues until @code{gc-cons-threshold} bytes have been
-used.
-
-This means that you can make sure that the garbage collector will not
-run during a certain portion of a Lisp program by calling the garbage
-collector explicitly just before it (provided that portion of the
-program does not use so much space as to force a second garbage
-collection).
-@end quotation
-
-@deffn Command garbage-collect
-This command runs a garbage collection, and returns information on
-the amount of space in use. (Garbage collection can also occur
-spontaneously if you use more than @code{gc-cons-threshold} bytes of
-Lisp data since the previous garbage collection.)
-
-@code{garbage-collect} returns a list containing the following
-information:
-
-@example
-@group
-((@var{used-conses} . @var{free-conses})
- (@var{used-syms} . @var{free-syms})
-@end group
- (@var{used-miscs} . @var{free-miscs})
- @var{used-string-chars}
- @var{used-vector-slots}
- (@var{used-floats} . @var{free-floats})
- (@var{used-intervals} . @var{free-intervals})
- (@var{used-strings} . @var{free-strings}))
-@end example
-
-Here is an example:
-
-@example
-@group
-(garbage-collect)
- @result{} ((106886 . 13184) (9769 . 0)
- (7731 . 4651) 347543 121628
- (31 . 94) (1273 . 168)
- (25474 . 3569))
-@end group
-@end example
-
-Here is a table explaining each element:
-
-@table @var
-@item used-conses
-The number of cons cells in use.
-
-@item free-conses
-The number of cons cells for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-syms
-The number of symbols in use.
-
-@item free-syms
-The number of symbols for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-miscs
-The number of miscellaneous objects in use. These include markers and
-overlays, plus certain objects not visible to users.
-
-@item free-miscs
-The number of miscellaneous objects for which space has been obtained
-from the operating system, but that are not currently being used.
-
-@item used-string-chars
-The total size of all strings, in characters.
-
-@item used-vector-slots
-The total number of elements of existing vectors.
-
-@item used-floats
-@c Emacs 19 feature
-The number of floats in use.
-
-@item free-floats
-@c Emacs 19 feature
-The number of floats for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-intervals
-The number of intervals in use. Intervals are an internal
-data structure used for representing text properties.
-
-@item free-intervals
-The number of intervals for which space has been obtained
-from the operating system, but that are not currently being used.
-
-@item used-strings
-The number of strings in use.
-
-@item free-strings
-The number of string headers for which the space was obtained from the
-operating system, but which are currently not in use. (A string
-object consists of a header and the storage for the string text
-itself; the latter is only allocated when the string is created.)
-@end table
-
-If there was overflow in pure space (see the previous section),
-@code{garbage-collect} returns @code{nil}, because a real garbage
-collection can not be done in this situation.
-@end deffn
-
-@defopt garbage-collection-messages
-If this variable is non-@code{nil}, Emacs displays a message at the
-beginning and end of garbage collection. The default value is
-@code{nil}, meaning there are no such messages.
-@end defopt
-
-@defvar post-gc-hook
-This is a normal hook that is run at the end of garbage collection.
-Garbage collection is inhibited while the hook functions run, so be
-careful writing them.
-@end defvar
-
-@defopt gc-cons-threshold
-The value of this variable is the number of bytes of storage that must
-be allocated for Lisp objects after one garbage collection in order to
-trigger another garbage collection. A cons cell counts as eight bytes,
-a string as one byte per character plus a few bytes of overhead, and so
-on; space allocated to the contents of buffers does not count. Note
-that the subsequent garbage collection does not happen immediately when
-the threshold is exhausted, but only the next time the Lisp evaluator is
-called.
-
-The initial threshold value is 400,000. If you specify a larger
-value, garbage collection will happen less often. This reduces the
-amount of time spent garbage collecting, but increases total memory use.
-You may want to do this when running a program that creates lots of
-Lisp data.
-
-You can make collections more frequent by specifying a smaller value,
-down to 10,000. A value less than 10,000 will remain in effect only
-until the subsequent garbage collection, at which time
-@code{garbage-collect} will set the threshold back to 10,000.
-@end defopt
-
-@defopt gc-cons-percentage
-The value of this variable specifies the amount of consing before a
-garbage collection occurs, as a fraction of the current heap size.
-This criterion and @code{gc-cons-threshold} apply in parallel, and
-garbage collection occurs only when both criteria are satisfied.
-
-As the heap size increases, the time to perform a garbage collection
-increases. Thus, it can be desirable to do them less frequently in
-proportion.
-@end defopt
-
- The value returned by @code{garbage-collect} describes the amount of
-memory used by Lisp data, broken down by data type. By contrast, the
-function @code{memory-limit} provides information on the total amount of
-memory Emacs is currently using.
-
-@c Emacs 19 feature
-@defun memory-limit
-This function returns the address of the last byte Emacs has allocated,
-divided by 1024. We divide the value by 1024 to make sure it fits in a
-Lisp integer.
-
-You can use this to get a general idea of how your actions affect the
-memory usage.
-@end defun
-
-@defvar memory-full
-This variable is @code{t} if Emacs is close to out of memory for Lisp
-objects, and @code{nil} otherwise.
-@end defvar
-
-@defun memory-use-counts
-This returns a list of numbers that count the number of objects
-created in this Emacs session. Each of these counters increments for
-a certain kind of object. See the documentation string for details.
-@end defun
-
-@defvar gcs-done
-This variable contains the total number of garbage collections
-done so far in this Emacs session.
-@end defvar
-
-@defvar gc-elapsed
-This variable contains the total number of seconds of elapsed time
-during garbage collection so far in this Emacs session, as a floating
-point number.
-@end defvar
-
-@node Memory Usage
-@section Memory Usage
-@cindex memory usage
-
- These functions and variables give information about the total amount
-of memory allocation that Emacs has done, broken down by data type.
-Note the difference between these and the values returned by
-@code{(garbage-collect)}; those count objects that currently exist, but
-these count the number or size of all allocations, including those for
-objects that have since been freed.
-
-@defvar cons-cells-consed
-The total number of cons cells that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar floats-consed
-The total number of floats that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar vector-cells-consed
-The total number of vector cells that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar symbols-consed
-The total number of symbols that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar string-chars-consed
-The total number of string characters that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar misc-objects-consed
-The total number of miscellaneous objects that have been allocated so
-far in this Emacs session. These include markers and overlays, plus
-certain objects not visible to users.
-@end defvar
-
-@defvar intervals-consed
-The total number of intervals that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar strings-consed
-The total number of strings that have been allocated so far in this
-Emacs session.
-@end defvar
-
-@node Writing Emacs Primitives
-@appendixsec Writing Emacs Primitives
-@cindex primitive function internals
-@cindex writing Emacs primitives
-
- Lisp primitives are Lisp functions implemented in C. The details of
-interfacing the C function so that Lisp can call it are handled by a few
-C macros. The only way to really understand how to write new C code is
-to read the source, but we can explain some things here.
-
- An example of a special form is the definition of @code{or}, from
-@file{eval.c}. (An ordinary function would have the same general
-appearance.)
-
-@cindex garbage collection protection
-@smallexample
-@group
-DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
- doc: /* Eval args until one of them yields non-nil, then return that
-value. The remaining args are not evalled at all.
-If all args return nil, return nil.
-@end group
-@group
-usage: (or CONDITIONS ...) */)
- (args)
- Lisp_Object args;
-@{
- register Lisp_Object val = Qnil;
- struct gcpro gcpro1;
-@end group
-
-@group
- GCPRO1 (args);
-@end group
-
-@group
- while (CONSP (args))
- @{
- val = Feval (XCAR (args));
- if (!NILP (val))
- break;
- args = XCDR (args);
- @}
-@end group
-
-@group
- UNGCPRO;
- return val;
-@}
-@end group
-@end smallexample
-
-@cindex @code{DEFUN}, C macro to define Lisp primitives
- Let's start with a precise explanation of the arguments to the
-@code{DEFUN} macro. Here is a template for them:
-
-@example
-DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
-@end example
-
-@table @var
-@item lname
-This is the name of the Lisp symbol to define as the function name; in
-the example above, it is @code{or}.
-
-@item fname
-This is the C function name for this function. This is
-the name that is used in C code for calling the function. The name is,
-by convention, @samp{F} prepended to the Lisp name, with all dashes
-(@samp{-}) in the Lisp name changed to underscores. Thus, to call this
-function from C code, call @code{For}. Remember that the arguments must
-be of type @code{Lisp_Object}; various macros and functions for creating
-values of type @code{Lisp_Object} are declared in the file
-@file{lisp.h}.
-
-@item sname
-This is a C variable name to use for a structure that holds the data for
-the subr object that represents the function in Lisp. This structure
-conveys the Lisp symbol name to the initialization routine that will
-create the symbol and store the subr object as its definition. By
-convention, this name is always @var{fname} with @samp{F} replaced with
-@samp{S}.
-
-@item min
-This is the minimum number of arguments that the function requires. The
-function @code{or} allows a minimum of zero arguments.
-
-@item max
-This is the maximum number of arguments that the function accepts, if
-there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
-indicating a special form that receives unevaluated arguments, or
-@code{MANY}, indicating an unlimited number of evaluated arguments (the
-equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are
-macros. If @var{max} is a number, it may not be less than @var{min} and
-it may not be greater than eight.
-
-@item interactive
-This is an interactive specification, a string such as might be used as
-the argument of @code{interactive} in a Lisp function. In the case of
-@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
-called interactively. A value of @code{""} indicates a function that
-should receive no arguments when called interactively.
-
-@item doc
-This is the documentation string. It uses C comment syntax rather
-than C string syntax because comment syntax requires nothing special
-to include multiple lines. The @samp{doc:} identifies the comment
-that follows as the documentation string. The @samp{/*} and @samp{*/}
-delimiters that begin and end the comment are not part of the
-documentation string.
-
-If the last line of the documentation string begins with the keyword
-@samp{usage:}, the rest of the line is treated as the argument list
-for documentation purposes. This way, you can use different argument
-names in the documentation string from the ones used in the C code.
-@samp{usage:} is required if the function has an unlimited number of
-arguments.
-
-All the usual rules for documentation strings in Lisp code
-(@pxref{Documentation Tips}) apply to C code documentation strings
-too.
-@end table
-
- After the call to the @code{DEFUN} macro, you must write the argument
-name list that every C function must have, followed by ordinary C
-declarations for the arguments. For a function with a fixed maximum
-number of arguments, declare a C argument for each Lisp argument, and
-give them all type @code{Lisp_Object}. When a Lisp function has no
-upper limit on the number of arguments, its implementation in C actually
-receives exactly two arguments: the first is the number of Lisp
-arguments, and the second is the address of a block containing their
-values. They have types @code{int} and @w{@code{Lisp_Object *}}.
-
-@cindex @code{GCPRO} and @code{UNGCPRO}
-@cindex protect C variables from garbage collection
- Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to
-``protect'' a variable from garbage collection---to inform the garbage
-collector that it must look in that variable and regard its contents
-as an accessible object. GC protection is necessary whenever you call
-@code{Feval} or anything that can directly or indirectly call
-@code{Feval}. At such a time, any Lisp object that this function may
-refer to again must be protected somehow.
-
- It suffices to ensure that at least one pointer to each object is
-GC-protected; that way, the object cannot be recycled, so all pointers
-to it remain valid. Thus, a particular local variable can do without
-protection if it is certain that the object it points to will be
-preserved by some other pointer (such as another local variable which
-has a @code{GCPRO})@footnote{Formerly, strings were a special
-exception; in older Emacs versions, every local variable that might
-point to a string needed a @code{GCPRO}.}. Otherwise, the local
-variable needs a @code{GCPRO}.
-
- The macro @code{GCPRO1} protects just one local variable. If you
-want to protect two variables, use @code{GCPRO2} instead; repeating
-@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4},
-@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros
-implicitly use local variables such as @code{gcpro1}; you must declare
-these explicitly, with type @code{struct gcpro}. Thus, if you use
-@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
-Alas, we can't explain all the tricky details here.
-
- @code{UNGCPRO} cancels the protection of the variables that are
-protected in the current function. It is necessary to do this
-explicitly.
-
- Built-in functions that take a variable number of arguments actually
-accept two arguments at the C level: the number of Lisp arguments, and
-a @code{Lisp_Object *} pointer to a C vector containing those Lisp
-arguments. This C vector may be part of a Lisp vector, but it need
-not be. The responsibility for using @code{GCPRO} to protect the Lisp
-arguments from GC if necessary rests with the caller in this case,
-since the caller allocated or found the storage for them.
-
- You must not use C initializers for static or global variables unless
-the variables are never written once Emacs is dumped. These variables
-with initializers are allocated in an area of memory that becomes
-read-only (on certain operating systems) as a result of dumping Emacs.
-@xref{Pure Storage}.
-
- Do not use static variables within functions---place all static
-variables at top level in the file. This is necessary because Emacs on
-some operating systems defines the keyword @code{static} as a null
-macro. (This definition is used because those systems put all variables
-declared static in a place that becomes read-only after dumping, whether
-they have initializers or not.)
-
-@cindex @code{defsubr}, Lisp symbol for a primitive
- Defining the C function is not enough to make a Lisp primitive
-available; you must also create the Lisp symbol for the primitive and
-store a suitable subr object in its function cell. The code looks like
-this:
-
-@example
-defsubr (&@var{subr-structure-name});
-@end example
-
-@noindent
-Here @var{subr-structure-name} is the name you used as the third
-argument to @code{DEFUN}.
-
- If you add a new primitive to a file that already has Lisp primitives
-defined in it, find the function (near the end of the file) named
-@code{syms_of_@var{something}}, and add the call to @code{defsubr}
-there. If the file doesn't have this function, or if you create a new
-file, add to it a @code{syms_of_@var{filename}} (e.g.,
-@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all
-of these functions are called, and add a call to
-@code{syms_of_@var{filename}} there.
-
-@anchor{Defining Lisp variables in C}
-@vindex byte-boolean-vars
-@cindex defining Lisp variables in C
-@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}
- The function @code{syms_of_@var{filename}} is also the place to define
-any C variables that are to be visible as Lisp variables.
-@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
-in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
-visible in Lisp with a value that is always an integer.
-@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
-with a value that is either @code{t} or @code{nil}. Note that variables
-defined with @code{DEFVAR_BOOL} are automatically added to the list
-@code{byte-boolean-vars} used by the byte compiler.
-
-@cindex @code{staticpro}, protection from GC
- If you define a file-scope C variable of type @code{Lisp_Object},
-you must protect it from garbage-collection by calling @code{staticpro}
-in @code{syms_of_@var{filename}}, like this:
-
-@example
-staticpro (&@var{variable});
-@end example
-
- Here is another example function, with more complicated arguments.
-This comes from the code in @file{window.c}, and it demonstrates the use
-of macros and functions to manipulate Lisp objects.
-
-@smallexample
-@group
-DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
- Scoordinates_in_window_p, 2, 2,
- "xSpecify coordinate pair: \nXExpression which evals to window: ",
- "Return non-nil if COORDINATES is in WINDOW.\n\
-COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
-...
-@end group
-@group
-If they are on the border between WINDOW and its right sibling,\n\
- `vertical-line' is returned.")
- (coordinates, window)
- register Lisp_Object coordinates, window;
-@{
- int x, y;
-@end group
-
-@group
- CHECK_LIVE_WINDOW (window, 0);
- CHECK_CONS (coordinates, 1);
- x = XINT (Fcar (coordinates));
- y = XINT (Fcdr (coordinates));
-@end group
-
-@group
- switch (coordinates_in_window (XWINDOW (window), &x, &y))
- @{
- case 0: /* NOT in window at all. */
- return Qnil;
-@end group
-
-@group
- case 1: /* In text part of window. */
- return Fcons (make_number (x), make_number (y));
-@end group
-
-@group
- case 2: /* In mode line of window. */
- return Qmode_line;
-@end group
-
-@group
- case 3: /* On right border of window. */
- return Qvertical_line;
-@end group
-
-@group
- default:
- abort ();
- @}
-@}
-@end group
-@end smallexample
-
- Note that C code cannot call functions by name unless they are defined
-in C. The way to call a function written in Lisp is to use
-@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
-the Lisp function @code{funcall} accepts an unlimited number of
-arguments, in C it takes two: the number of Lisp-level arguments, and a
-one-dimensional array containing their values. The first Lisp-level
-argument is the Lisp function to call, and the rest are the arguments to
-pass to it. Since @code{Ffuncall} can call the evaluator, you must
-protect pointers from garbage collection around the call to
-@code{Ffuncall}.
-
- The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
-provide handy ways to call a Lisp function conveniently with a fixed
-number of arguments. They work by calling @code{Ffuncall}.
-
- @file{eval.c} is a very good file to look through for examples;
-@file{lisp.h} contains the definitions for some important macros and
-functions.
-
- If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
-@code{side-effect-and-error-free-fns} so that the compiler optimizer
-knows about it.
-
-@node Object Internals
-@appendixsec Object Internals
-@cindex object internals
-
- GNU Emacs Lisp manipulates many different types of data. The actual
-data are stored in a heap and the only access that programs have to it
-is through pointers. Pointers are thirty-two bits wide in most
-implementations. Depending on the operating system and type of machine
-for which you compile Emacs, twenty-nine bits are used to address the
-object, and the remaining three bits are used for the tag that
-identifies the object's type.
-
- Because Lisp objects are represented as tagged pointers, it is always
-possible to determine the Lisp data type of any object. The C data type
-@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary
-variables have type @code{Lisp_Object}, which means they can hold any
-type of Lisp value; you can determine the actual data type only at run
-time. The same is true for function arguments; if you want a function
-to accept only a certain type of argument, you must check the type
-explicitly using a suitable predicate (@pxref{Type Predicates}).
-@cindex type checking internals
-
-@menu
-* Buffer Internals:: Components of a buffer structure.
-* Window Internals:: Components of a window structure.
-* Process Internals:: Components of a process structure.
-@end menu
-
-@node Buffer Internals
-@appendixsubsec Buffer Internals
-@cindex internals, of buffer
-@cindex buffer internals
-
- Buffers contain fields not directly accessible by the Lisp programmer.
-We describe them here, naming them by the names used in the C code.
-Many are accessible indirectly in Lisp programs via Lisp primitives.
-
-Two structures are used to represent buffers in C. The
-@code{buffer_text} structure contains fields describing the text of a
-buffer; the @code{buffer} structure holds other fields. In the case
-of indirect buffers, two or more @code{buffer} structures reference
-the same @code{buffer_text} structure.
-
-Here is a list of the @code{struct buffer_text} fields:
-
-@table @code
-@item beg
-This field contains the actual address of the buffer contents.
-
-@item gpt
-This holds the character position of the gap in the buffer.
-@xref{Buffer Gap}.
-
-@item z
-This field contains the character position of the end of the buffer
-text.
-
-@item gpt_byte
-Contains the byte position of the gap.
-
-@item z_byte
-Holds the byte position of the end of the buffer text.
-
-@item gap_size
-Contains the size of buffer's gap. @xref{Buffer Gap}.
-
-@item modiff
-This field counts buffer-modification events for this buffer. It is
-incremented for each such event, and never otherwise changed.
-
-@item save_modiff
-Contains the previous value of @code{modiff}, as of the last time a
-buffer was visited or saved in a file.
-
-@item overlay_modiff
-Counts modifications to overlays analogous to @code{modiff}.
-
-@item beg_unchanged
-Holds the number of characters at the start of the text that are known
-to be unchanged since the last redisplay that finished.
-
-@item end_unchanged
-Holds the number of characters at the end of the text that are known to
-be unchanged since the last redisplay that finished.
-
-@item unchanged_modified
-Contains the value of @code{modiff} at the time of the last redisplay
-that finished. If this value matches @code{modiff},
-@code{beg_unchanged} and @code{end_unchanged} contain no useful
-information.
-
-@item overlay_unchanged_modified
-Contains the value of @code{overlay_modiff} at the time of the last
-redisplay that finished. If this value matches @code{overlay_modiff},
-@code{beg_unchanged} and @code{end_unchanged} contain no useful
-information.
-
-@item markers
-The markers that refer to this buffer. This is actually a single
-marker, and successive elements in its marker @code{chain} are the other
-markers referring to this buffer text.
-
-@item intervals
-Contains the interval tree which records the text properties of this
-buffer.
-@end table
-
-The fields of @code{struct buffer} are:
-
-@table @code
-@item next
-Points to the next buffer, in the chain of all buffers including killed
-buffers. This chain is used only for garbage collection, in order to
-collect killed buffers properly. Note that vectors, and most kinds of
-objects allocated as vectors, are all on one chain, but buffers are on a
-separate chain of their own.
-
-@item own_text
-This is a @code{struct buffer_text} structure. In an ordinary buffer,
-it holds the buffer contents. In indirect buffers, this field is not
-used.
-
-@item text
-This points to the @code{buffer_text} structure that is used for this
-buffer. In an ordinary buffer, this is the @code{own_text} field above.
-In an indirect buffer, this is the @code{own_text} field of the base
-buffer.
-
-@item pt
-Contains the character position of point in a buffer.
-
-@item pt_byte
-Contains the byte position of point in a buffer.
-
-@item begv
-This field contains the character position of the beginning of the
-accessible range of text in the buffer.
-
-@item begv_byte
-This field contains the byte position of the beginning of the
-accessible range of text in the buffer.
-
-@item zv
-This field contains the character position of the end of the
-accessible range of text in the buffer.
-
-@item zv_byte
-This field contains the byte position of the end of the
-accessible range of text in the buffer.
-
-@item base_buffer
-In an indirect buffer, this points to the base buffer. In an ordinary
-buffer, it is null.
-
-@item local_var_flags
-This field contains flags indicating that certain variables are local in
-this buffer. Such variables are declared in the C code using
-@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in
-fields in the buffer structure itself. (Some of these fields are
-described in this table.)
-
-@item modtime
-This field contains the modification time of the visited file. It is
-set when the file is written or read. Before writing the buffer into a
-file, this field is compared to the modification time of the file to see
-if the file has changed on disk. @xref{Buffer Modification}.
-
-@item auto_save_modified
-This field contains the time when the buffer was last auto-saved.
-
-@item auto_save_failure_time
-The time at which we detected a failure to auto-save, or -1 if we didn't
-have a failure.
-
-@item last_window_start
-This field contains the @code{window-start} position in the buffer as of
-the last time the buffer was displayed in a window.
-
-@item clip_changed
-This flag is set when narrowing changes in a buffer.
-
-@item prevent_redisplay_optimizations_p
-this flag indicates that redisplay optimizations should not be used
-to display this buffer.
-
-@item undo_list
-This field points to the buffer's undo list. @xref{Undo}.
-
-@item name
-The buffer name is a string that names the buffer. It is guaranteed to
-be unique. @xref{Buffer Names}.
-
-@item filename
-The name of the file visited in this buffer, or @code{nil}.
-
-@item directory
-The directory for expanding relative file names.
-
-@item save_length
-Length of the file this buffer is visiting, when last read or saved.
-This and other fields concerned with saving are not kept in the
-@code{buffer_text} structure because indirect buffers are never saved.
-
-@item auto_save_file_name
-File name used for auto-saving this buffer. This is not in the
-@code{buffer_text} because it's not used in indirect buffers at all.
-
-@item read_only
-Non-@code{nil} means this buffer is read-only.
-
-@item mark
-This field contains the mark for the buffer. The mark is a marker,
-hence it is also included on the list @code{markers}. @xref{The Mark}.
-
-@item local_var_alist
-This field contains the association list describing the buffer-local
-variable bindings of this buffer, not including the built-in
-buffer-local bindings that have special slots in the buffer object.
-(Those slots are omitted from this table.) @xref{Buffer-Local
-Variables}.
-
-@item major_mode
-Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}.
-
-@item mode_name
-Pretty name of major mode, e.g., @code{"Lisp"}.
-
-@item mode_line_format
-Mode line element that controls the format of the mode line. If this
-is @code{nil}, no mode line will be displayed.
-
-@item header_line_format
-This field is analogous to @code{mode_line_format} for the mode
-line displayed at the top of windows.
-
-@item keymap
-This field holds the buffer's local keymap. @xref{Keymaps}.
-
-@item abbrev_table
-This buffer's local abbrevs.
-
-@item syntax_table
-This field contains the syntax table for the buffer. @xref{Syntax Tables}.
-
-@item category_table
-This field contains the category table for the buffer.
-
-@item case_fold_search
-The value of @code{case-fold-search} in this buffer.
-
-@item tab_width
-The value of @code{tab-width} in this buffer.
-
-@item fill_column
-The value of @code{fill-column} in this buffer.
-
-@item left_margin
-The value of @code{left-margin} in this buffer.
-
-@item auto_fill_function
-The value of @code{auto-fill-function} in this buffer.
-
-@item downcase_table
-This field contains the conversion table for converting text to lower case.
-@xref{Case Tables}.
-
-@item upcase_table
-This field contains the conversion table for converting text to upper case.
-@xref{Case Tables}.
-
-@item case_canon_table
-This field contains the conversion table for canonicalizing text for
-case-folding search. @xref{Case Tables}.
-
-@item case_eqv_table
-This field contains the equivalence table for case-folding search.
-@xref{Case Tables}.
-
-@item truncate_lines
-The value of @code{truncate-lines} in this buffer.
-
-@item ctl_arrow
-The value of @code{ctl-arrow} in this buffer.
-
-@item selective_display
-The value of @code{selective-display} in this buffer.
-
-@item selective_display_ellipsis
-The value of @code{selective-display-ellipsis} in this buffer.
-
-@item minor_modes
-An alist of the minor modes of this buffer.
-
-@item overwrite_mode
-The value of @code{overwrite_mode} in this buffer.
-
-@item abbrev_mode
-The value of @code{abbrev-mode} in this buffer.
-
-@item display_table
-This field contains the buffer's display table, or @code{nil} if it doesn't
-have one. @xref{Display Tables}.
-
-@item save_modified
-This field contains the time when the buffer was last saved, as an integer.
-@xref{Buffer Modification}.
-
-@item mark_active
-This field is non-@code{nil} if the buffer's mark is active.
-
-@item overlays_before
-This field holds a list of the overlays in this buffer that end at or
-before the current overlay center position. They are sorted in order of
-decreasing end position.
-
-@item overlays_after
-This field holds a list of the overlays in this buffer that end after
-the current overlay center position. They are sorted in order of
-increasing beginning position.
-
-@item overlay_center
-This field holds the current overlay center position. @xref{Overlays}.
-
-@item enable_multibyte_characters
-This field holds the buffer's local value of
-@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
-
-@item buffer_file_coding_system
-The value of @code{buffer-file-coding-system} in this buffer.
-
-@item file_format
-The value of @code{buffer-file-format} in this buffer.
-
-@item auto_save_file_format
-The value of @code{buffer-auto-save-file-format} in this buffer.
-
-@item pt_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records point for this buffer when the
-buffer is not current.
-
-@item begv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{begv} for this buffer
-when the buffer is not current.
-
-@item zv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{zv} for this buffer when
-the buffer is not current.
-
-@item file_truename
-The truename of the visited file, or @code{nil}.
-
-@item invisibility_spec
-The value of @code{buffer-invisibility-spec} in this buffer.
-
-@item last_selected_window
-This is the last window that was selected with this buffer in it, or @code{nil}
-if that window no longer displays this buffer.
-
-@item display_count
-This field is incremented each time the buffer is displayed in a window.
-
-@item left_margin_width
-The value of @code{left-margin-width} in this buffer.
-
-@item right_margin_width
-The value of @code{right-margin-width} in this buffer.
-
-@item indicate_empty_lines
-Non-@code{nil} means indicate empty lines (lines with no text) with a
-small bitmap in the fringe, when using a window system that can do it.
-
-@item display_time
-This holds a time stamp that is updated each time this buffer is
-displayed in a window.
-
-@item scroll_up_aggressively
-The value of @code{scroll-up-aggressively} in this buffer.
-
-@item scroll_down_aggressively
-The value of @code{scroll-down-aggressively} in this buffer.
-@end table
-
-@node Window Internals
-@appendixsubsec Window Internals
-@cindex internals, of window
-@cindex window internals
-
- Windows have the following accessible fields:
-
-@table @code
-@item frame
-The frame that this window is on.
-
-@item mini_p
-Non-@code{nil} if this window is a minibuffer window.
-
-@item parent
-Internally, Emacs arranges windows in a tree; each group of siblings has
-a parent window whose area includes all the siblings. This field points
-to a window's parent.
-
-Parent windows do not display buffers, and play little role in display
-except to shape their child windows. Emacs Lisp programs usually have
-no access to the parent windows; they operate on the windows at the
-leaves of the tree, which actually display buffers.
-
-The following four fields also describe the window tree structure.
-
-@item hchild
-In a window subdivided horizontally by child windows, the leftmost child.
-Otherwise, @code{nil}.
-
-@item vchild
-In a window subdivided vertically by child windows, the topmost child.
-Otherwise, @code{nil}.
-
-@item next
-The next sibling of this window. It is @code{nil} in a window that is
-the rightmost or bottommost of a group of siblings.
-
-@item prev
-The previous sibling of this window. It is @code{nil} in a window that
-is the leftmost or topmost of a group of siblings.
-
-@item left
-This is the left-hand edge of the window, measured in columns. (The
-leftmost column on the screen is @w{column 0}.)
-
-@item top
-This is the top edge of the window, measured in lines. (The top line on
-the screen is @w{line 0}.)
-
-@item height
-The height of the window, measured in lines.
-
-@item width
-The width of the window, measured in columns. This width includes the
-scroll bar and fringes, and/or the separator line on the right of the
-window (if any).
-
-@item buffer
-The buffer that the window is displaying. This may change often during
-the life of the window.
-
-@item start
-The position in the buffer that is the first character to be displayed
-in the window.
-
-@item pointm
-@cindex window point internals
-This is the value of point in the current buffer when this window is
-selected; when it is not selected, it retains its previous value.
-
-@item force_start
-If this flag is non-@code{nil}, it says that the window has been
-scrolled explicitly by the Lisp program. This affects what the next
-redisplay does if point is off the screen: instead of scrolling the
-window to show the text around point, it moves point to a location that
-is on the screen.
-
-@item frozen_window_start_p
-This field is set temporarily to 1 to indicate to redisplay that
-@code{start} of this window should not be changed, even if point
-gets invisible.
-
-@item start_at_line_beg
-Non-@code{nil} means current value of @code{start} was the beginning of a line
-when it was chosen.
-
-@item too_small_ok
-Non-@code{nil} means don't delete this window for becoming ``too small.''
-
-@item height_fixed_p
-This field is temporarily set to 1 to fix the height of the selected
-window when the echo area is resized.
-
-@item use_time
-This is the last time that the window was selected. The function
-@code{get-lru-window} uses this field.
-
-@item sequence_number
-A unique number assigned to this window when it was created.
-
-@item last_modified
-The @code{modiff} field of the window's buffer, as of the last time
-a redisplay completed in this window.
-
-@item last_overlay_modified
-The @code{overlay_modiff} field of the window's buffer, as of the last
-time a redisplay completed in this window.
-
-@item last_point
-The buffer's value of point, as of the last time a redisplay completed
-in this window.
-
-@item last_had_star
-A non-@code{nil} value means the window's buffer was ``modified'' when the
-window was last updated.
-
-@item vertical_scroll_bar
-This window's vertical scroll bar.
-
-@item left_margin_width
-The width of the left margin in this window, or @code{nil} not to
-specify it (in which case the buffer's value of @code{left-margin-width}
-is used.
-
-@item right_margin_width
-Likewise for the right margin.
-
-@ignore
-@item last_mark_x
-@item last_mark_y
-???Not used.
-@end ignore
-
-@item window_end_pos
-This is computed as @code{z} minus the buffer position of the last glyph
-in the current matrix of the window. The value is only valid if
-@code{window_end_valid} is not @code{nil}.
-
-@item window_end_bytepos
-The byte position corresponding to @code{window_end_pos}.
-
-@item window_end_vpos
-The window-relative vertical position of the line containing
-@code{window_end_pos}.
-
-@item window_end_valid
-This field is set to a non-@code{nil} value if @code{window_end_pos} is truly
-valid. This is @code{nil} if nontrivial redisplay is preempted since in that
-case the display that @code{window_end_pos} was computed for did not get
-onto the screen.
-
-@item redisplay_end_trigger
-If redisplay in this window goes beyond this buffer position, it runs
-the @code{redisplay-end-trigger-hook}.
-
-@ignore
-@item orig_height
-@item orig_top
-??? Are temporary storage areas.
-@end ignore
-
-@item cursor
-A structure describing where the cursor is in this window.
-
-@item last_cursor
-The value of @code{cursor} as of the last redisplay that finished.
-
-@item phys_cursor
-A structure describing where the cursor of this window physically is.
-
-@item phys_cursor_type
-The type of cursor that was last displayed on this window.
-
-@item phys_cursor_on_p
-This field is non-zero if the cursor is physically on.
-
-@item cursor_off_p
-Non-zero means the cursor in this window is logically on.
-
-@item last_cursor_off_p
-This field contains the value of @code{cursor_off_p} as of the time of
-the last redisplay.
-
-@item must_be_updated_p
-This is set to 1 during redisplay when this window must be updated.
-
-@item hscroll
-This is the number of columns that the display in the window is scrolled
-horizontally to the left. Normally, this is 0.
-
-@item vscroll
-Vertical scroll amount, in pixels. Normally, this is 0.
-
-@item dedicated
-Non-@code{nil} if this window is dedicated to its buffer.
-
-@item display_table
-The window's display table, or @code{nil} if none is specified for it.
-
-@item update_mode_line
-Non-@code{nil} means this window's mode line needs to be updated.
-
-@item base_line_number
-The line number of a certain position in the buffer, or @code{nil}.
-This is used for displaying the line number of point in the mode line.
-
-@item base_line_pos
-The position in the buffer for which the line number is known, or
-@code{nil} meaning none is known.
-
-@item region_showing
-If the region (or part of it) is highlighted in this window, this field
-holds the mark position that made one end of that region. Otherwise,
-this field is @code{nil}.
-
-@item column_number_displayed
-The column number currently displayed in this window's mode line, or @code{nil}
-if column numbers are not being displayed.
-
-@item current_matrix
-A glyph matrix describing the current display of this window.
-
-@item desired_matrix
-A glyph matrix describing the desired display of this window.
-@end table
-
-@node Process Internals
-@appendixsubsec Process Internals
-@cindex internals, of process
-@cindex process internals
-
- The fields of a process are:
-
-@table @code
-@item name
-A string, the name of the process.
-
-@item command
-A list containing the command arguments that were used to start this
-process.
-
-@item filter
-A function used to accept output from the process instead of a buffer,
-or @code{nil}.
-
-@item sentinel
-A function called whenever the process receives a signal, or @code{nil}.
-
-@item buffer
-The associated buffer of the process.
-
-@item pid
-An integer, the operating system's process @acronym{ID}.
-
-@item childp
-A flag, non-@code{nil} if this is really a child process.
-It is @code{nil} for a network connection.
-
-@item mark
-A marker indicating the position of the end of the last output from this
-process inserted into the buffer. This is often but not always the end
-of the buffer.
-
-@item kill_without_query
-If this is non-@code{nil}, killing Emacs while this process is still
-running does not ask for confirmation about killing the process.
-
-@item raw_status_low
-@itemx raw_status_high
-These two fields record 16 bits each of the process status returned by
-the @code{wait} system call.
-
-@item status
-The process status, as @code{process-status} should return it.
-
-@item tick
-@itemx update_tick
-If these two fields are not equal, a change in the status of the process
-needs to be reported, either by running the sentinel or by inserting a
-message in the process buffer.
-
-@item pty_flag
-Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
-@code{nil} if it uses a pipe.
-
-@item infd
-The file descriptor for input from the process.
-
-@item outfd
-The file descriptor for output to the process.
-
-@item subtty
-The file descriptor for the terminal that the subprocess is using. (On
-some systems, there is no need to record this, so the value is
-@code{nil}.)
-
-@item tty_name
-The name of the terminal that the subprocess is using,
-or @code{nil} if it is using pipes.
-
-@item decode_coding_system
-Coding-system for decoding the input from this process.
-
-@item decoding_buf
-A working buffer for decoding.
-
-@item decoding_carryover
-Size of carryover in decoding.
-
-@item encode_coding_system
-Coding-system for encoding the output to this process.
-
-@item encoding_buf
-A working buffer for encoding.
-
-@item encoding_carryover
-Size of carryover in encoding.
-
-@item inherit_coding_system_flag
-Flag to set @code{coding-system} of the process buffer from the
-coding system used to decode process output.
-@end table
-
-@ignore
- arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/intro
-
-@node Introduction, Lisp Data Types, Top, Top
-@comment node-name, next, previous, up
-@chapter Introduction
-
- Most of the GNU Emacs text editor is written in the programming
-language called Emacs Lisp. You can write new code in Emacs Lisp and
-install it as an extension to the editor. However, Emacs Lisp is more
-than a mere ``extension language''; it is a full computer programming
-language in its own right. You can use it as you would any other
-programming language.
-
- Because Emacs Lisp is designed for use in an editor, it has special
-features for scanning and parsing text as well as features for handling
-files, buffers, displays, subprocesses, and so on. Emacs Lisp is
-closely integrated with the editing facilities; thus, editing commands
-are functions that can also conveniently be called from Lisp programs,
-and parameters for customization are ordinary Lisp variables.
-
- This manual attempts to be a full description of Emacs Lisp. For a
-beginner's introduction to Emacs Lisp, see @cite{An Introduction to
-Emacs Lisp Programming}, by Bob Chassell, also published by the Free
-Software Foundation. This manual presumes considerable familiarity with
-the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
-basic information.
-
- Generally speaking, the earlier chapters describe features of Emacs
-Lisp that have counterparts in many programming languages, and later
-chapters describe features that are peculiar to Emacs Lisp or relate
-specifically to editing.
-
- This is edition @value{VERSION} of the GNU Emacs Lisp Reference
-Manual, corresponding to Emacs version @value{EMACSVER}.
-
-@menu
-* 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.
-@end menu
-
-@node Caveats
-@section Caveats
-@cindex bugs in this manual
-
- This manual has gone through numerous drafts. It is nearly complete
-but not flawless. There are a few topics that are not covered, either
-because we consider them secondary (such as most of the individual
-modes) or because they are yet to be written. Because we are not able
-to deal with them completely, we have left out several parts
-intentionally. This includes most information about usage on VMS.
-
- The manual should be fully correct in what it does cover, and it is
-therefore open to criticism on anything it says---from specific examples
-and descriptive text, to the ordering of chapters and sections. If
-something is confusing, or you find that you have to look at the sources
-or experiment to learn something not covered in the manual, then perhaps
-the manual should be fixed. Please let us know.
-
-@iftex
- As you use this manual, we ask that you mark pages with corrections so
-you can later look them up and send them to us. If you think of a simple,
-real-life example for a function or group of functions, please make an
-effort to write it up and send it in. Please reference any comments to
-the chapter name, section name, and function name, as appropriate, since
-page numbers and chapter and section numbers will change and we may have
-trouble finding the text you are talking about. Also state the number
-of the edition you are criticizing.
-@end iftex
-@ifnottex
-
-As you use this manual, we ask that you send corrections as soon as you
-find them. If you think of a simple, real life example for a function
-or group of functions, please make an effort to write it up and send it
-in. Please reference any comments to the node name and function or
-variable name, as appropriate. Also state the number of the edition
-you are criticizing.
-@end ifnottex
-
-@cindex bugs
-@cindex suggestions
-Please mail comments and corrections to
-
-@example
-bug-lisp-manual@@gnu.org
-@end example
-
-@noindent
-We let mail to this list accumulate unread until someone decides to
-apply the corrections. Months, and sometimes years, go by between
-updates. So please attach no significance to the lack of a reply---your
-mail @emph{will} be acted on in due time. If you want to contact the
-Emacs maintainers more quickly, send mail to
-@code{bug-gnu-emacs@@gnu.org}.
-
-@node Lisp History
-@section Lisp History
-@cindex Lisp history
-
- Lisp (LISt Processing language) was first developed in the late 1950s
-at the Massachusetts Institute of Technology for research in artificial
-intelligence. The great power of the Lisp language makes it ideal
-for other purposes as well, such as writing editing commands.
-
-@cindex Maclisp
-@cindex Common Lisp
- Dozens of Lisp implementations have been built over the years, each
-with its own idiosyncrasies. Many of them were inspired by Maclisp,
-which was written in the 1960s at MIT's Project MAC. Eventually the
-implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp. In the meantime, Gerry
-Sussman and Guy Steele at MIT developed a simplified but very powerful
-dialect of Lisp, called Scheme.
-
- GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
-Lisp. If you know Common Lisp, you will notice many similarities.
-However, many features of Common Lisp have been omitted or
-simplified in order to reduce the memory requirements of GNU Emacs.
-Sometimes the simplifications are so drastic that a Common Lisp user
-might be very confused. We will occasionally point out how GNU Emacs
-Lisp differs from Common Lisp. If you don't know Common Lisp, don't
-worry about it; this manual is self-contained.
-
-@pindex cl
- A certain amount of Common Lisp emulation is available via the
-@file{cl} library. @inforef{Top, Overview, cl}.
-
- Emacs Lisp is not at all influenced by Scheme; but the GNU project has
-an implementation of Scheme, called Guile. We use Guile in all new GNU
-software that calls for extensibility.
-
-@node Conventions
-@section Conventions
-
-This section explains the notational conventions that are used in this
-manual. You may want to skip this section and refer back to it later.
-
-@menu
-* 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 when examples print text.
-* 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.
-@end menu
-
-@node Some Terms
-@subsection Some Terms
-
- Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
-printer'' refer to those routines in Lisp that convert textual
-representations of Lisp objects into actual Lisp objects, and vice
-versa. @xref{Printed Representation}, for more details. You, the
-person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you.'' ``The user'' is the person who uses Lisp
-programs, including those you write.
-
-@cindex fonts in this manual
- Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
-Names that represent metasyntactic variables, or arguments to a function
-being described, are formatted like this: @var{first-number}.
-
-@node nil and t
-@subsection @code{nil} and @code{t}
-@cindex truth value
-@cindex boolean
-
-@cindex @code{nil}
-@cindex false
- In Lisp, the symbol @code{nil} has three separate meanings: it
-is a symbol with the name @samp{nil}; it is the logical truth value
-@var{false}; and it is the empty list---the list of zero elements.
-When used as a variable, @code{nil} always has the value @code{nil}.
-
- As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are
-identical: they stand for the same object, the symbol @code{nil}. The
-different ways of writing the symbol are intended entirely for human
-readers. After the Lisp reader has read either @samp{()} or @samp{nil},
-there is no way to determine which representation was actually written
-by the programmer.
-
- In this manual, we write @code{()} when we wish to emphasize that it
-means the empty list, and we write @code{nil} when we wish to emphasize
-that it means the truth value @var{false}. That is a good convention to use
-in Lisp programs also.
-
-@example
-(cons 'foo ()) ; @r{Emphasize the empty list}
-(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}}
-@end example
-
-@cindex @code{t}
-@cindex true
- In contexts where a truth value is expected, any non-@code{nil} value
-is considered to be @var{true}. However, @code{t} is the preferred way
-to represent the truth value @var{true}. When you need to choose a
-value which represents @var{true}, and there is no other basis for
-choosing, use @code{t}. The symbol @code{t} always has the value
-@code{t}.
-
- In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
-evaluate to themselves. This is so that you do not need to quote them
-to use them as constants in a program. An attempt to change their
-values results in a @code{setting-constant} error. @xref{Constant
-Variables}.
-
-@defun booleanp object
-Return non-nil if @var{object} is one of the two canonical boolean
-values: @code{t} or @code{nil}.
-@end defun
-
-@node Evaluation Notation
-@subsection Evaluation Notation
-@cindex evaluation notation
-@cindex documentation notation
-@cindex notation
-
- A Lisp expression that you can evaluate is called a @dfn{form}.
-Evaluating a form always produces a result, which is a Lisp object. In
-the examples in this manual, this is indicated with @samp{@result{}}:
-
-@example
-(car '(1 2))
- @result{} 1
-@end example
-
-@noindent
-You can read this as ``@code{(car '(1 2))} evaluates to 1.''
-
- When a form is a macro call, it expands into a new form for Lisp to
-evaluate. We show the result of the expansion with
-@samp{@expansion{}}. We may or may not show the result of the
-evaluation of the expanded form.
-
-@example
-(third '(a b c))
- @expansion{} (car (cdr (cdr '(a b c))))
- @result{} c
-@end example
-
- Sometimes to help describe one form we show another form that
-produces identical results. The exact equivalence of two forms is
-indicated with @samp{@equiv{}}.
-
-@example
-(make-sparse-keymap) @equiv{} (list 'keymap)
-@end example
-
-@node Printing Notation
-@subsection Printing Notation
-@cindex printing notation
-
- Many of the examples in this manual print text when they are
-evaluated. If you execute example code in a Lisp Interaction buffer
-(such as the buffer @samp{*scratch*}), the printed text is inserted into
-the buffer. If you execute the example by other means (such as by
-evaluating the function @code{eval-region}), the printed text is
-displayed in the echo area.
-
- Examples in this manual indicate printed text with @samp{@print{}},
-irrespective of where that text goes. The value returned by
-evaluating the form (here @code{bar}) follows on a separate line with
-@samp{@result{}}.
-
-@example
-@group
-(progn (prin1 'foo) (princ "\n") (prin1 'bar))
- @print{} foo
- @print{} bar
- @result{} bar
-@end group
-@end example
-
-@node Error Messages
-@subsection Error Messages
-@cindex error message notation
-
- Some examples signal errors. This normally displays an error message
-in the echo area. We show the error message on a line starting with
-@samp{@error{}}. Note that @samp{@error{}} itself does not appear in
-the echo area.
-
-@example
-(+ 23 'x)
-@error{} Wrong type argument: number-or-marker-p, x
-@end example
-
-@node Buffer Text Notation
-@subsection Buffer Text Notation
-@cindex buffer text notation
-
- Some examples describe modifications to the contents of a buffer, by
-showing the ``before'' and ``after'' versions of the text. These
-examples show the contents of the buffer in question between two lines
-of dashes containing the buffer name. In addition, @samp{@point{}}
-indicates the location of point. (The symbol for point, of course, is
-not part of the text in the buffer; it indicates the place
-@emph{between} two characters where point is currently located.)
-
-@example
----------- Buffer: foo ----------
-This is the @point{}contents of foo.
----------- Buffer: foo ----------
-
-(insert "changed ")
- @result{} nil
----------- Buffer: foo ----------
-This is the changed @point{}contents of foo.
----------- Buffer: foo ----------
-@end example
-
-@node Format of Descriptions
-@subsection Format of Descriptions
-@cindex description format
-
- Functions, variables, macros, commands, user options, and special
-forms are described in this manual in a uniform format. The first
-line of a description contains the name of the item followed by its
-arguments, if any.
-@ifnottex
-The category---function, variable, or whatever---appears at the
-beginning of the line.
-@end ifnottex
-@iftex
-The category---function, variable, or whatever---is printed next to the
-right margin.
-@end iftex
-The description follows on succeeding lines, sometimes with examples.
-
-@menu
-* 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}.
-@end menu
-
-@node A Sample Function Description
-@subsubsection A Sample Function Description
-@cindex function descriptions
-@cindex command descriptions
-@cindex macro descriptions
-@cindex special form descriptions
-
- In a function description, the name of the function being described
-appears first. It is followed on the same line by a list of argument
-names. These names are also used in the body of the description, to
-stand for the values of the arguments.
-
- The appearance of the keyword @code{&optional} in the argument list
-indicates that the subsequent arguments may be omitted (omitted
-arguments default to @code{nil}). Do not write @code{&optional} when
-you call the function.
-
- The keyword @code{&rest} (which must be followed by a single
-argument name) indicates that any number of arguments can follow. The
-single argument name following @code{&rest} will receive, as its
-value, a list of all the remaining arguments passed to the function.
-Do not write @code{&rest} when you call the function.
-
- Here is a description of an imaginary function @code{foo}:
-
-@defun foo integer1 &optional integer2 &rest integers
-The function @code{foo} subtracts @var{integer1} from @var{integer2},
-then adds all the rest of the arguments to the result. If @var{integer2}
-is not supplied, then the number 19 is used by default.
-
-@example
-(foo 1 5 3 9)
- @result{} 16
-(foo 5)
- @result{} 14
-@end example
-
-@need 1500
-More generally,
-
-@example
-(foo @var{w} @var{x} @var{y}@dots{})
-@equiv{}
-(+ (- @var{x} @var{w}) @var{y}@dots{})
-@end example
-@end defun
-
- Any argument whose name contains the name of a type (e.g.,
-@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
-type. A plural of a type (such as @var{buffers}) often means a list of
-objects of that type. Arguments named @var{object} may be of any type.
-(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments
-with other sorts of names (e.g., @var{new-file}) are discussed
-specifically in the description of the function. In some sections,
-features common to the arguments of several functions are described at
-the beginning.
-
- @xref{Lambda Expressions}, for a more complete description of optional
-and rest arguments.
-
- Command, macro, and special form descriptions have the same format,
-but the word `Function' is replaced by `Command', `Macro', or `Special
-Form', respectively. Commands are simply functions that may be called
-interactively; macros process their arguments differently from functions
-(the arguments are not evaluated), but are presented the same way.
-
- Special form descriptions use a more complex notation to specify
-optional and repeated arguments because they can break the argument
-list down into separate arguments in more complicated ways.
-@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
-optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
-arguments. Parentheses are used when several arguments are grouped into
-additional levels of list structure. Here is an example:
-
-@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
-This imaginary special form implements a loop that executes the
-@var{body} forms and then increments the variable @var{var} on each
-iteration. On the first iteration, the variable has the value
-@var{from}; on subsequent iterations, it is incremented by one (or by
-@var{inc} if that is given). The loop exits before executing @var{body}
-if @var{var} equals @var{to}. Here is an example:
-
-@example
-(count-loop (i 0 10)
- (prin1 i) (princ " ")
- (prin1 (aref vector i))
- (terpri))
-@end example
-
-If @var{from} and @var{to} are omitted, @var{var} is bound to
-@code{nil} before the loop begins, and the loop exits if @var{var} is
-non-@code{nil} at the beginning of an iteration. Here is an example:
-
-@example
-(count-loop (done)
- (if (pending)
- (fixit)
- (setq done t)))
-@end example
-
-In this special form, the arguments @var{from} and @var{to} are
-optional, but must both be present or both absent. If they are present,
-@var{inc} may optionally be specified as well. These arguments are
-grouped with the argument @var{var} into a list, to distinguish them
-from @var{body}, which includes all remaining elements of the form.
-@end defspec
-
-@node A Sample Variable Description
-@subsubsection A Sample Variable Description
-@cindex variable descriptions
-@cindex option descriptions
-
- A @dfn{variable} is a name that can hold a value. Although nearly
-all variables can be set by the user, certain variables exist
-specifically so that users can change them; these are called @dfn{user
-options}. Ordinary variables and user options are described using a
-format like that for functions except that there are no arguments.
-
- Here is a description of the imaginary @code{electric-future-map}
-variable.@refill
-
-@defvar electric-future-map
-The value of this variable is a full keymap used by Electric Command
-Future mode. The functions in this map allow you to edit commands you
-have not yet thought about executing.
-@end defvar
-
- User option descriptions have the same format, but `Variable' is
-replaced by `User Option'.
-
-@node Version Info
-@section Version Information
-
- These facilities provide information about which version of Emacs is
-in use.
-
-@deffn Command emacs-version &optional here
-This function returns a string describing the version of Emacs that is
-running. It is useful to include this string in bug reports.
-
-@smallexample
-@group
-(emacs-version)
- @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
- of Sat Feb 14 1998 on psilocin.gnu.org"
-@end group
-@end smallexample
-
-If @var{here} is non-@code{nil}, it inserts the text in the buffer
-before point, and returns @code{nil}. Called interactively, the
-function prints the same information in the echo area, but giving a
-prefix argument makes @var{here} non-@code{nil}.
-@end deffn
-
-@defvar emacs-build-time
-The value of this variable indicates the time at which Emacs was built
-at the local site. It is a list of three integers, like the value
-of @code{current-time} (@pxref{Time of Day}).
-
-@example
-@group
-emacs-build-time
- @result{} (13623 62065 344633)
-@end group
-@end example
-@end defvar
-
-@defvar emacs-version
-The value of this variable is the version of Emacs being run. It is a
-string such as @code{"20.3.1"}. The last number in this string is not
-really part of the Emacs release version number; it is incremented each
-time you build Emacs in any given directory. A value with four numeric
-components, such as @code{"20.3.9.1"}, indicates an unreleased test
-version.
-@end defvar
-
- The following two variables have existed since Emacs version 19.23:
-
-@defvar emacs-major-version
-The major version number of Emacs, as an integer. For Emacs version
-20.3, the value is 20.
-@end defvar
-
-@defvar emacs-minor-version
-The minor version number of Emacs, as an integer. For Emacs version
-20.3, the value is 3.
-@end defvar
-
-@node Acknowledgements
-@section Acknowledgements
-
- This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
-Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU
-manual group, in an effort extending over several years.
-Robert@tie{}J. Chassell helped to review and edit the manual, with the
-support of the Defense Advanced Research Projects Agency, ARPA Order
-6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic,
-Inc.
-
- Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom,
-Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence
-R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly
-Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea,
-Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki
-Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe
-Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland
-McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson,
-Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul
-Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
-Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
-Dale Worley, Rusty Wright, and David D. Zuhn.
-
-@ignore
- arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 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/keymaps
-@node Keymaps, Modes, Command Loop, Top
-@chapter Keymaps
-@cindex keymap
-
- The command bindings of input events are recorded in data structures
-called @dfn{keymaps}. Each entry in a keymap associates (or
-@dfn{binds}) an individual event type, either to another keymap or to
-a command. When an event type is bound to a keymap, that keymap is
-used to look up the next input event; this continues until a command
-is found. The whole process is called @dfn{key lookup}.
-
-@menu
-* 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:: Finding a key's binding in one keymap.
-* 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:: Defining a menu as a keymap.
-@end menu
-
-@node Key Sequences
-@section Key Sequences
-@cindex key
-@cindex keystroke
-@cindex key sequence
-
- A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
-or more input events that form a unit. Input events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
-The Emacs Lisp representation for a key sequence is a string or
-vector. Unless otherwise stated, any Emacs Lisp function that accepts
-a key sequence as an argument can handle both representations.
-
- In the string representation, alphanumeric characters ordinarily
-stand for themselves; for example, @code{"a"} represents @kbd{a}
-and @code{"2"} represents @kbd{2}. Control character events are
-prefixed by the substring @code{"\C-"}, and meta characters by
-@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
-In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
-are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
-@code{"\d"} respectively. The string representation of a complete key
-sequence is the concatenation of the string representations of the
-constituent events; thus, @code{"\C-xl"} represents the key sequence
-@kbd{C-x l}.
-
- Key sequences containing function keys, mouse button events, or
-non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
-represented as strings; they have to be represented as vectors.
-
- In the vector representation, each element of the vector represents
-an input event, in its Lisp form. @xref{Input Events}. For example,
-the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
-
- For examples of key sequences written in string and vector
-representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
-
-@defmac kbd keyseq-text
-This macro converts the text @var{keyseq-text} (a string constant)
-into a key sequence (a string or vector constant). The contents of
-@var{keyseq-text} should describe the key sequence using almost the same
-syntax used in this manual. More precisely, it uses the same syntax
-that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
-Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
-function key names with @samp{<@dots{}>}.
-
-@example
-(kbd "C-x") @result{} "\C-x"
-(kbd "C-x C-f") @result{} "\C-x\C-f"
-(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
-(kbd "X") @result{} "X"
-(kbd "RET") @result{} "\^M"
-(kbd "C-c SPC") @result{} "\C-c@ "
-(kbd "<f1> SPC") @result{} [f1 32]
-(kbd "C-M-<down>") @result{} [C-M-down]
-@end example
-
-This macro is not meant for use with arguments that vary---only
-with string constants.
-@end defmac
-
-@node Keymap Basics
-@section Keymap Basics
-@cindex key binding
-@cindex binding of a key
-@cindex complete key
-@cindex undefined key
-
- A keymap is a Lisp data structure that specifies @dfn{key bindings}
-for various key sequences.
-
- A single keymap directly specifies definitions for individual
-events. When a key sequence consists of a single event, its binding
-in a keymap is the keymap's definition for that event. The binding of
-a longer key sequence is found by an iterative process: first find the
-definition of the first event (which must itself be a keymap); then
-find the second event's definition in that keymap, and so on until all
-the events in the key sequence have been processed.
-
- If the binding of a key sequence is a keymap, we call the key sequence
-a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
-no more events can be added to it). If the binding is @code{nil},
-we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
-@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
-@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
-keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more
-details.
-
- The rule for finding the binding of a key sequence assumes that the
-intermediate bindings (found for the events before the last) are all
-keymaps; if this is not so, the sequence of events does not form a
-unit---it is not really one key sequence. In other words, removing one
-or more events from the end of any valid key sequence must always yield
-a prefix key. For example, @kbd{C-f C-n} is not a key sequence;
-@kbd{C-f} is not a prefix key, so a longer sequence starting with
-@kbd{C-f} cannot be a key sequence.
-
- The set of possible multi-event key sequences depends on the bindings
-for prefix keys; therefore, it can be different for different keymaps,
-and can change when bindings are changed. However, a one-event sequence
-is always a key sequence, because it does not depend on any prefix keys
-for its well-formedness.
-
- At any time, several primary keymaps are @dfn{active}---that is, in
-use for finding key bindings. These are the @dfn{global map}, which is
-shared by all buffers; the @dfn{local keymap}, which is usually
-associated with a specific major mode; and zero or more @dfn{minor mode
-keymaps}, which belong to currently enabled minor modes. (Not all minor
-modes have keymaps.) The local keymap bindings shadow (i.e., take
-precedence over) the corresponding global bindings. The minor mode
-keymaps shadow both local and global keymaps. @xref{Active Keymaps},
-for details.
-
-@node Format of Keymaps
-@section Format of Keymaps
-@cindex format of keymaps
-@cindex keymap format
-@cindex full keymap
-@cindex sparse keymap
-
- Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The
-remaining elements of the list define the key bindings of the keymap.
-A symbol whose function definition is a keymap is also a keymap. Use
-the function @code{keymapp} (see below) to test whether an object is a
-keymap.
-
- Several kinds of elements may appear in a keymap, after the symbol
-@code{keymap} that begins it:
-
-@table @code
-@item (@var{type} .@: @var{binding})
-This specifies one binding, for events of type @var{type}. Each
-ordinary binding applies to events of a particular @dfn{event type},
-which is always a character or a symbol. @xref{Classifying Events}.
-In this kind of binding, @var{binding} is a command.
-
-@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
-This specifies a binding which is also a simple menu item that
-displays as @var{item-name} in the menu. @var{cache}, if present,
-caches certain information for display in the menu. @xref{Simple Menu
-Items}.
-
-@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
-This is a simple menu item with help string @var{help-string}.
-
-@item (@var{type} menu-item .@: @var{details})
-This specifies a binding which is also an extended menu item. This
-allows use of other features. @xref{Extended Menu Items}.
-
-@item (t .@: @var{binding})
-@cindex default key binding
-This specifies a @dfn{default key binding}; any event not bound by other
-elements of the keymap is given @var{binding} as its binding. Default
-bindings allow a keymap to bind all possible event types without having
-to enumerate all of them. A keymap that has a default binding
-completely masks any lower-precedence keymap, except for events
-explicitly bound to @code{nil} (see below).
-
-@item @var{char-table}
-If an element of a keymap is a char-table, it counts as holding
-bindings for all character events with no modifier bits
-(@pxref{modifier bits}): element @var{n} is the binding for the
-character with code @var{n}. This is a compact way to record lots of
-bindings. A keymap with such a char-table is called a @dfn{full
-keymap}. Other keymaps are called @dfn{sparse keymaps}.
-
-@item @var{string}
-@cindex keymap prompt string
-@cindex overall prompt string
-@cindex prompt string of keymap
-Aside from elements that specify bindings for keys, a keymap can also
-have a string as an element. This is called the @dfn{overall prompt
-string} and makes it possible to use the keymap as a menu.
-@xref{Defining Menus}.
-@end table
-
-When the binding is @code{nil}, it doesn't constitute a definition
-but it does take precedence over a default binding or a binding in the
-parent keymap. On the other hand, a binding of @code{nil} does
-@emph{not} override lower-precedence keymaps; thus, if the local map
-gives a binding of @code{nil}, Emacs uses the binding from the
-global map.
-
-@cindex meta characters lookup
- Keymaps do not directly record bindings for the meta characters.
-Instead, meta characters are regarded for purposes of key lookup as
-sequences of two characters, the first of which is @key{ESC} (or
-whatever is currently the value of @code{meta-prefix-char}). Thus, the
-key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
-global binding is found at the slot for @kbd{a} in @code{esc-map}
-(@pxref{Prefix Keys}).
-
- This conversion applies only to characters, not to function keys or
-other input events; thus, @kbd{M-@key{end}} has nothing to do with
-@kbd{@key{ESC} @key{end}}.
-
- Here as an example is the local keymap for Lisp mode, a sparse
-keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
-C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
-
-@example
-@group
-lisp-mode-map
-@result{}
-@end group
-@group
-(keymap
- (3 keymap
- ;; @kbd{C-c C-z}
- (26 . run-lisp))
-@end group
-@group
- (27 keymap
- ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)
- keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
-@end group
-@group
- ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
- keymap
- ;; @key{DEL}
- (127 . backward-delete-char-untabify)
-@end group
-@group
- (27 keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
- (9 . lisp-indent-line))
-@end group
-@end example
-
-@defun keymapp object
-This function returns @code{t} if @var{object} is a keymap, @code{nil}
-otherwise. More precisely, this function tests for a list whose
-@sc{car} is @code{keymap}, or for a symbol whose function definition
-satisfies @code{keymapp}.
-
-@example
-@group
-(keymapp '(keymap))
- @result{} t
-@end group
-@group
-(fset 'foo '(keymap))
-(keymapp 'foo)
- @result{} t
-@end group
-@group
-(keymapp (current-global-map))
- @result{} t
-@end group
-@end example
-@end defun
-
-@node Creating Keymaps
-@section Creating Keymaps
-@cindex creating keymaps
-
- Here we describe the functions for creating keymaps.
-
-@defun make-sparse-keymap &optional prompt
-This function creates and returns a new sparse keymap with no entries.
-(A sparse keymap is the kind of keymap you usually want.) The new
-keymap does not contain a char-table, unlike @code{make-keymap}, and
-does not bind any events.
-
-@example
-@group
-(make-sparse-keymap)
- @result{} (keymap)
-@end group
-@end example
-
-If you specify @var{prompt}, that becomes the overall prompt string
-for the keymap. You should specify this only for menu keymaps
-(@pxref{Defining Menus}). A keymap with an overall prompt string will
-always present a mouse menu or a keyboard menu if it is active for
-looking up the next input event. Don't specify an overall prompt string
-for the main map of a major or minor mode, because that would cause
-the command loop to present a keyboard menu every time.
-@end defun
-
-@defun make-keymap &optional prompt
-This function creates and returns a new full keymap. That keymap
-contains a char-table (@pxref{Char-Tables}) with slots for all
-characters without modifiers. The new keymap initially binds all
-these characters to @code{nil}, and does not bind any other kind of
-event. The argument @var{prompt} specifies a
-prompt string, as in @code{make-sparse-keymap}.
-
-@example
-@group
-(make-keymap)
- @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
-@end group
-@end example
-
-A full keymap is more efficient than a sparse keymap when it holds
-lots of bindings; for just a few, the sparse keymap is better.
-@end defun
-
-@defun copy-keymap keymap
-This function returns a copy of @var{keymap}. Any keymaps that
-appear directly as bindings in @var{keymap} are also copied recursively,
-and so on to any number of levels. However, recursive copying does not
-take place when the definition of a character is a symbol whose function
-definition is a keymap; the same symbol appears in the new copy.
-@c Emacs 19 feature
-
-@example
-@group
-(setq map (copy-keymap (current-local-map)))
-@result{} (keymap
-@end group
-@group
- ;; @r{(This implements meta characters.)}
- (27 keymap
- (83 . center-paragraph)
- (115 . center-line))
- (9 . tab-to-tab-stop))
-@end group
-
-@group
-(eq map (current-local-map))
- @result{} nil
-@end group
-@group
-(equal map (current-local-map))
- @result{} t
-@end group
-@end example
-@end defun
-
-@node Inheritance and Keymaps
-@section Inheritance and Keymaps
-@cindex keymap inheritance
-@cindex inheriting a keymap's bindings
-
- A keymap can inherit the bindings of another keymap, which we call the
-@dfn{parent keymap}. Such a keymap looks like this:
-
-@example
-(keymap @var{elements}@dots{} . @var{parent-keymap})
-@end example
-
-@noindent
-The effect is that this keymap inherits all the bindings of
-@var{parent-keymap}, whatever they may be at the time a key is looked up,
-but can add to them or override them with @var{elements}.
-
-If you change the bindings in @var{parent-keymap} using
-@code{define-key} or other key-binding functions, these changed
-bindings are visible in the inheriting keymap, unless shadowed by the
-bindings made by @var{elements}. The converse is not true: if you use
-@code{define-key} to change bindings in the inheriting keymap, these
-changes are recorded in @var{elements}, but have no effect on
-@var{parent-keymap}.
-
-The proper way to construct a keymap with a parent is to use
-@code{set-keymap-parent}; if you have code that directly constructs a
-keymap with a parent, please convert the program to use
-@code{set-keymap-parent} instead.
-
-@defun keymap-parent keymap
-This returns the parent keymap of @var{keymap}. If @var{keymap}
-has no parent, @code{keymap-parent} returns @code{nil}.
-@end defun
-
-@defun set-keymap-parent keymap parent
-This sets the parent keymap of @var{keymap} to @var{parent}, and returns
-@var{parent}. If @var{parent} is @code{nil}, this function gives
-@var{keymap} no parent at all.
-
-If @var{keymap} has submaps (bindings for prefix keys), they too receive
-new parent keymaps that reflect what @var{parent} specifies for those
-prefix keys.
-@end defun
-
- Here is an example showing how to make a keymap that inherits
-from @code{text-mode-map}:
-
-@example
-(let ((map (make-sparse-keymap)))
- (set-keymap-parent map text-mode-map)
- map)
-@end example
-
- A non-sparse keymap can have a parent too, but this is not very
-useful. A non-sparse keymap always specifies something as the binding
-for every numeric character code without modifier bits, even if it is
-@code{nil}, so these character's bindings are never inherited from
-the parent keymap.
-
-@node Prefix Keys
-@section Prefix Keys
-@cindex prefix key
-
- A @dfn{prefix key} is a key sequence whose binding is a keymap. The
-keymap defines what to do with key sequences that extend the prefix key.
-For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
-also stored in the variable @code{ctl-x-map}. This keymap defines
-bindings for key sequences starting with @kbd{C-x}.
-
- Some of the standard Emacs prefix keys use keymaps that are
-also found in Lisp variables:
-
-@itemize @bullet
-@item
-@vindex esc-map
-@findex ESC-prefix
-@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus,
-the global definitions of all meta characters are actually found here.
-This map is also the function definition of @code{ESC-prefix}.
-
-@item
-@cindex @kbd{C-h}
-@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
-
-@item
-@cindex @kbd{C-c}
-@vindex mode-specific-map
-@code{mode-specific-map} is the global keymap for the prefix key
-@kbd{C-c}. This map is actually global, not mode-specific, but its name
-provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
-(@code{display-bindings}), since the main use of this prefix key is for
-mode-specific bindings.
-
-@item
-@cindex @kbd{C-x}
-@vindex ctl-x-map
-@findex Control-X-prefix
-@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
-This map is found via the function cell of the symbol
-@code{Control-X-prefix}.
-
-@item
-@cindex @kbd{C-x @key{RET}}
-@vindex mule-keymap
-@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
-prefix key.
-
-@item
-@cindex @kbd{C-x 4}
-@vindex ctl-x-4-map
-@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
-key.
-
-@c Emacs 19 feature
-@item
-@cindex @kbd{C-x 5}
-@vindex ctl-x-5-map
-@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
-key.
-
-@c Emacs 19 feature
-@item
-@cindex @kbd{C-x 6}
-@vindex 2C-mode-map
-@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
-key.
-
-@item
-@cindex @kbd{C-x v}
-@vindex vc-prefix-map
-@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
-key.
-
-@item
-@cindex @kbd{M-o}
-@vindex facemenu-keymap
-@code{facemenu-keymap} is the global keymap used for the @kbd{M-o}
-prefix key.
-
-@c Emacs 19 feature
-@item
-The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
-@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps
-that have no special names.
-@end itemize
-
- The keymap binding of a prefix key is used for looking up the event
-that follows the prefix key. (It may instead be a symbol whose function
-definition is a keymap. The effect is the same, but the symbol serves
-as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the
-symbol @code{Control-X-prefix}, whose function cell holds the keymap
-for @kbd{C-x} commands. (The same keymap is also the value of
-@code{ctl-x-map}.)
-
- Prefix key definitions can appear in any active keymap. The
-definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
-keys appear in the global map, so these prefix keys are always
-available. Major and minor modes can redefine a key as a prefix by
-putting a prefix key definition for it in the local map or the minor
-mode's map. @xref{Active Keymaps}.
-
- If a key is defined as a prefix in more than one active map, then its
-various definitions are in effect merged: the commands defined in the
-minor mode keymaps come first, followed by those in the local map's
-prefix definition, and then by those from the global map.
-
- In the following example, we make @kbd{C-p} a prefix key in the local
-keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
-the binding for @kbd{C-p C-f} is the function @code{find-file}, just
-like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
-active keymap.
-
-@example
-@group
-(use-local-map (make-sparse-keymap))
- @result{} nil
-@end group
-@group
-(local-set-key "\C-p" ctl-x-map)
- @result{} nil
-@end group
-@group
-(key-binding "\C-p\C-f")
- @result{} find-file
-@end group
-
-@group
-(key-binding "\C-p6")
- @result{} nil
-@end group
-@end example
-
-@defun define-prefix-command symbol &optional mapvar prompt
-@cindex prefix command
-@anchor{Definition of define-prefix-command}
-This function prepares @var{symbol} for use as a prefix key's binding:
-it creates a sparse keymap and stores it as @var{symbol}'s function
-definition. Subsequently binding a key sequence to @var{symbol} will
-make that key sequence into a prefix key. The return value is @code{symbol}.
-
-This function also sets @var{symbol} as a variable, with the keymap as
-its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
-as a variable instead.
-
-If @var{prompt} is non-@code{nil}, that becomes the overall prompt
-string for the keymap. The prompt string should be given for menu keymaps
-(@pxref{Defining Menus}).
-@end defun
-
-@node Active Keymaps
-@section Active Keymaps
-@cindex active keymap
-@cindex global keymap
-@cindex local keymap
-
- Emacs normally contains many keymaps; at any given time, just a few
-of them are @dfn{active}, meaning that they participate in the
-interpretation of user input. All the active keymaps are used
-together to determine what command to execute when a key is entered.
-
- Normally the active keymaps are the @code{keymap} property keymap,
-the keymaps of any enabled minor modes, the current buffer's local
-keymap, and the global keymap, in that order. Emacs searches for each
-input key sequence in all these keymaps. @xref{Searching Keymaps},
-for more details of this procedure.
-
- When the key sequence starts with a mouse event (optionally preceded
-by a symbolic prefix), the active keymaps are determined based on the
-position in that event. If the event happened on a string embedded
-with a @code{display}, @code{before-string}, or @code{after-string}
-property (@pxref{Special Properties}), the non-@code{nil} map
-properties of the string override those of the buffer.
-
- The @dfn{global keymap} holds the bindings of keys that are defined
-regardless of the current buffer, such as @kbd{C-f}. The variable
-@code{global-map} holds this keymap, which is always active.
-
- Each buffer may have another keymap, its @dfn{local keymap}, which
-may contain new or overriding definitions for keys. The current
-buffer's local keymap is always active except when
-@code{overriding-local-map} overrides it. The @code{local-map} text
-or overlay property can specify an alternative local keymap for certain
-parts of the buffer; see @ref{Special Properties}.
-
- Each minor mode can have a keymap; if it does, the keymap is active
-when the minor mode is enabled. Modes for emulation can specify
-additional active keymaps through the variable
-@code{emulation-mode-map-alists}.
-
- The highest precedence normal keymap comes from the @code{keymap}
-text or overlay property. If that is non-@code{nil}, it is the first
-keymap to be processed, in normal circumstances.
-
- However, there are also special ways for programs to substitute
-other keymaps for some of those. The variable
-@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
-that replaces all the usual active keymaps except the global keymap.
-Another way to do this is with @code{overriding-terminal-local-map};
-it operates on a per-terminal basis. These variables are documented
-below.
-
-@cindex major mode keymap
- Since every buffer that uses the same major mode normally uses the
-same local keymap, you can think of the keymap as local to the mode. A
-change to the local keymap of a buffer (using @code{local-set-key}, for
-example) is seen also in the other buffers that share that keymap.
-
- The local keymaps that are used for Lisp mode and some other major
-modes exist even if they have not yet been used. These local keymaps are
-the values of variables such as @code{lisp-mode-map}. For most major
-modes, which are less frequently used, the local keymap is constructed
-only when the mode is used for the first time in a session.
-
- The minibuffer has local keymaps, too; they contain various completion
-and exit commands. @xref{Intro to Minibuffers}.
-
- Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}. @xref{Translation Keymaps}.
-
- @xref{Standard Keymaps}, for a list of standard keymaps.
-
-@defun current-active-maps &optional olp position
-This returns the list of active keymaps that would be used by the
-command loop in the current circumstances to look up a key sequence.
-Normally it ignores @code{overriding-local-map} and
-@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil}
-then it pays attention to them. @var{position} can optionally be either
-an event position as returned by @code{event-start} or a buffer
-position, and may change the keymaps as described for
-@code{key-binding}.
-@end defun
-
-@defun key-binding key &optional accept-defaults no-remap position
-This function returns the binding for @var{key} according to the
-current active keymaps. The result is @code{nil} if @var{key} is
-undefined in the keymaps.
-
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}).
-
-When commands are remapped (@pxref{Remapping Commands}),
-@code{key-binding} normally processes command remappings so as to
-returns the remapped command that will actually be executed. However,
-if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
-remappings and returns the binding directly specified for @var{key}.
-
-If @var{key} starts with a mouse event (perhaps following a prefix
-event), the maps to be consulted are determined based on the event's
-position. Otherwise, they are determined based on the value of point.
-However, you can override either of them by specifying @var{position}.
-If @var{position} is non-@code{nil}, it should be either a buffer
-position or an event position like the value of @code{event-start}.
-Then the maps consulted are determined based on @var{position}.
-
-An error is signaled if @var{key} is not a string or a vector.
-
-@example
-@group
-(key-binding "\C-x\C-f")
- @result{} find-file
-@end group
-@end example
-@end defun
-
-@node Searching Keymaps
-@section Searching the Active Keymaps
-@cindex searching active keymaps for keys
-
- After translation of event subsequences (@pxref{Translation
-Keymaps}) Emacs looks for them in the active keymaps. Here is a
-pseudo-Lisp description of the order and conditions for searching
-them:
-
-@lisp
-(or (if overriding-terminal-local-map
- (@var{find-in} overriding-terminal-local-map)
- (if overriding-local-map
- (@var{find-in} overriding-local-map)
- (or (@var{find-in} (get-char-property (point) 'keymap))
- (@var{find-in-any} emulation-mode-map-alists)
- (@var{find-in-any} minor-mode-overriding-map-alist)
- (@var{find-in-any} minor-mode-map-alist)
- (if (get-text-property (point) 'local-map)
- (@var{find-in} (get-char-property (point) 'local-map))
- (@var{find-in} (current-local-map))))))
- (@var{find-in} (current-global-map)))
-@end lisp
-
-@noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.) If the key sequence starts with a mouse event,
-or a symbolic prefix event followed by a mouse event, that event's
-position is used instead of point and the current buffer. Mouse
-events on an embedded string use non-@code{nil} text properties from
-that string instead of the buffer.
-
-@enumerate
-@item
-The function finally found may be remapped
-(@pxref{Remapping Commands}).
-
-@item
-Characters that are bound to @code{self-insert-command} are translated
-according to @code{translation-table-for-input} before insertion.
-
-@item
-@code{current-active-maps} returns a list of the
-currently active keymaps at point.
-
-@item
-When a match is found (@pxref{Key Lookup}), if the binding in the
-keymap is a function, the search is over. However if the keymap entry
-is a symbol with a value or a string, Emacs replaces the input key
-sequences with the variable's value or the string, and restarts the
-search of the active keymaps.
-@end enumerate
-
-@node Controlling Active Maps
-@section Controlling the Active Keymaps
-
-@defvar global-map
-This variable contains the default global keymap that maps Emacs
-keyboard input to commands. The global keymap is normally this
-keymap. The default global keymap is a full keymap that binds
-@code{self-insert-command} to all of the printing characters.
-
-It is normal practice to change the bindings in the global keymap, but you
-should not assign this variable any value other than the keymap it starts
-out with.
-@end defvar
-
-@defun current-global-map
-This function returns the current global keymap. This is the
-same as the value of @code{global-map} unless you change one or the
-other.
-
-@example
-@group
-(current-global-map)
-@result{} (keymap [set-mark-command beginning-of-line @dots{}
- delete-backward-char])
-@end group
-@end example
-@end defun
-
-@defun current-local-map
-This function returns the current buffer's local keymap, or @code{nil}
-if it has none. In the following example, the keymap for the
-@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
-keymap.
-
-@example
-@group
-(current-local-map)
-@result{} (keymap
- (10 . eval-print-last-sexp)
- (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
-@end group
-@group
- (27 keymap
- (24 . eval-defun)
- (17 . indent-sexp)))
-@end group
-@end example
-@end defun
-
-@defun current-minor-mode-maps
-This function returns a list of the keymaps of currently enabled minor modes.
-@end defun
-
-@defun use-global-map keymap
-This function makes @var{keymap} the new current global keymap. It
-returns @code{nil}.
-
-It is very unusual to change the global keymap.
-@end defun
-
-@defun use-local-map keymap
-This function makes @var{keymap} the new local keymap of the current
-buffer. If @var{keymap} is @code{nil}, then the buffer has no local
-keymap. @code{use-local-map} returns @code{nil}. Most major mode
-commands use this function.
-@end defun
-
-@c Emacs 19 feature
-@defvar minor-mode-map-alist
-@anchor{Definition of minor-mode-map-alist}
-This variable is an alist describing keymaps that may or may not be
-active according to the values of certain variables. Its elements look
-like this:
-
-@example
-(@var{variable} . @var{keymap})
-@end example
-
-The keymap @var{keymap} is active whenever @var{variable} has a
-non-@code{nil} value. Typically @var{variable} is the variable that
-enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose
-function definition is a keymap.
-
-When more than one minor mode keymap is active, the earlier one in
-@code{minor-mode-map-alist} takes priority. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-
-See @ref{Keymaps and Minor Modes}, for more information about minor
-modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key
-Lookup}).
-@end defvar
-
-@defvar minor-mode-overriding-map-alist
-This variable allows major modes to override the key bindings for
-particular minor modes. The elements of this alist look like the
-elements of @code{minor-mode-map-alist}: @code{(@var{variable}
-. @var{keymap})}.
-
-If a variable appears as an element of
-@code{minor-mode-overriding-map-alist}, the map specified by that
-element totally replaces any map specified for the same variable in
-@code{minor-mode-map-alist}.
-
-@code{minor-mode-overriding-map-alist} is automatically buffer-local in
-all buffers.
-@end defvar
-
-@defvar overriding-local-map
-If non-@code{nil}, this variable holds a keymap to use instead of the
-buffer's local keymap, any text property or overlay keymaps, and any
-minor mode keymaps. This keymap, if specified, overrides all other
-maps that would have been active, except for the current global map.
-@end defvar
-
-@defvar overriding-terminal-local-map
-If non-@code{nil}, this variable holds a keymap to use instead of
-@code{overriding-local-map}, the buffer's local keymap, text property
-or overlay keymaps, and all the minor mode keymaps.
-
-This variable is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}. It is used to implement
-incremental search mode.
-@end defvar
-
-@defvar overriding-local-map-menu-flag
-If this variable is non-@code{nil}, the value of
-@code{overriding-local-map} or @code{overriding-terminal-local-map} can
-affect the display of the menu bar. The default value is @code{nil}, so
-those map variables have no effect on the menu bar.
-
-Note that these two map variables do affect the execution of key
-sequences entered using the menu bar, even if they do not affect the
-menu bar display. So if a menu bar key sequence comes in, you should
-clear the variables before looking up and executing that key sequence.
-Modes that use the variables would typically do this anyway; normally
-they respond to events that they do not handle by ``unreading'' them and
-exiting.
-@end defvar
-
-@defvar special-event-map
-This variable holds a keymap for special events. If an event type has a
-binding in this keymap, then it is special, and the binding for the
-event is run directly by @code{read-event}. @xref{Special Events}.
-@end defvar
-
-@defvar emulation-mode-map-alists
-This variable holds a list of keymap alists to use for emulations
-modes. It is intended for modes or packages using multiple minor-mode
-keymaps. Each element is a keymap alist which has the same format and
-meaning as @code{minor-mode-map-alist}, or a symbol with a variable
-binding which is such an alist. The ``active'' keymaps in each alist
-are used before @code{minor-mode-map-alist} and
-@code{minor-mode-overriding-map-alist}.
-@end defvar
-
-@node Key Lookup
-@section Key Lookup
-@cindex key lookup
-@cindex keymap entry
-
- @dfn{Key lookup} is the process of finding the binding of a key
-sequence from a given keymap. The execution or use of the binding is
-not part of key lookup.
-
- Key lookup uses just the event type of each event in the key sequence;
-the rest of the event is ignored. In fact, a key sequence used for key
-lookup may designate a mouse event with just its types (a symbol)
-instead of the entire event (a list). @xref{Input Events}. Such
-a ``key sequence'' is insufficient for @code{command-execute} to run,
-but it is sufficient for looking up or rebinding a key.
-
- When the key sequence consists of multiple events, key lookup
-processes the events sequentially: the binding of the first event is
-found, and must be a keymap; then the second event's binding is found in
-that keymap, and so on until all the events in the key sequence are used
-up. (The binding thus found for the last event may or may not be a
-keymap.) Thus, the process of key lookup is defined in terms of a
-simpler process for looking up a single event in a keymap. How that is
-done depends on the type of object associated with the event in that
-keymap.
-
- Let's use the term @dfn{keymap entry} to describe the value found by
-looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in a keymap element for a menu item, because
-@code{lookup-key} and other key lookup functions don't include them in
-the returned value.) While any Lisp object may be stored in a keymap
-as a keymap entry, not all make sense for key lookup. Here is a table
-of the meaningful types of keymap entries:
-
-@table @asis
-@item @code{nil}
-@cindex @code{nil} in keymap
-@code{nil} means that the events used so far in the lookup form an
-undefined key. When a keymap fails to mention an event type at all, and
-has no default binding, that is equivalent to a binding of @code{nil}
-for that event type.
-
-@item @var{command}
-@cindex command in keymap
-The events used so far in the lookup form a complete key,
-and @var{command} is its binding. @xref{What Is a Function}.
-
-@item @var{array}
-@cindex string in keymap
-The array (either a string or a vector) is a keyboard macro. The events
-used so far in the lookup form a complete key, and the array is its
-binding. See @ref{Keyboard Macros}, for more information.
-
-@item @var{keymap}
-@cindex keymap in keymap
-The events used so far in the lookup form a prefix key. The next
-event of the key sequence is looked up in @var{keymap}.
-
-@item @var{list}
-@cindex list in keymap
-The meaning of a list depends on what it contains:
-
-@itemize @bullet
-@item
-If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
-is a keymap, and is treated as a keymap (see above).
-
-@item
-@cindex @code{lambda} in keymap
-If the @sc{car} of @var{list} is @code{lambda}, then the list is a
-lambda expression. This is presumed to be a function, and is treated
-as such (see above). In order to execute properly as a key binding,
-this function must be a command---it must have an @code{interactive}
-specification. @xref{Defining Commands}.
-
-@item
-If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
-type, then this is an @dfn{indirect entry}:
-
-@example
-(@var{othermap} . @var{othertype})
-@end example
-
-When key lookup encounters an indirect entry, it looks up instead the
-binding of @var{othertype} in @var{othermap} and uses that.
-
-This feature permits you to define one key as an alias for another key.
-For example, an entry whose @sc{car} is the keymap called @code{esc-map}
-and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
-@end itemize
-
-@item @var{symbol}
-@cindex symbol in keymap
-The function definition of @var{symbol} is used in place of
-@var{symbol}. If that too is a symbol, then this process is repeated,
-any number of times. Ultimately this should lead to an object that is
-a keymap, a command, or a keyboard macro. A list is allowed if it is a
-keymap or a command, but indirect entries are not understood when found
-via symbols.
-
-Note that keymaps and keyboard macros (strings and vectors) are not
-valid functions, so a symbol with a keymap, string, or vector as its
-function definition is invalid as a function. It is, however, valid as
-a key binding. If the definition is a keyboard macro, then the symbol
-is also valid as an argument to @code{command-execute}
-(@pxref{Interactive Call}).
-
-@cindex @code{undefined} in keymap
-The symbol @code{undefined} is worth special mention: it means to treat
-the key as undefined. Strictly speaking, the key is defined, and its
-binding is the command @code{undefined}; but that command does the same
-thing that is done automatically for an undefined key: it rings the bell
-(by calling @code{ding}) but does not signal an error.
-
-@cindex preventing prefix key
-@code{undefined} is used in local keymaps to override a global key
-binding and make the key ``undefined'' locally. A local binding of
-@code{nil} would fail to do this because it would not override the
-global binding.
-
-@item @var{anything else}
-If any other type of object is found, the events used so far in the
-lookup form a complete key, and the object is its binding, but the
-binding is not executable as a command.
-@end table
-
- In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol that leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap. This map is the normal value
-of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
-@kbd{C-x}.
-
-@example
-@group
-(keymap (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
- (27 keymap (17 . indent-sexp) (24 . eval-defun)))
-@end group
-@end example
-
-@node Functions for Key Lookup
-@section Functions for Key Lookup
-
- Here are the functions and variables pertaining to key lookup.
-
-@defun lookup-key keymap key &optional accept-defaults
-This function returns the definition of @var{key} in @var{keymap}. All
-the other functions described in this chapter that look up keys use
-@code{lookup-key}. Here are examples:
-
-@example
-@group
-(lookup-key (current-global-map) "\C-x\C-f")
- @result{} find-file
-@end group
-@group
-(lookup-key (current-global-map) (kbd "C-x C-f"))
- @result{} find-file
-@end group
-@group
-(lookup-key (current-global-map) "\C-x\C-f12345")
- @result{} 2
-@end group
-@end example
-
-If the string or vector @var{key} is not a valid key sequence according
-to the prefix keys specified in @var{keymap}, it must be ``too long''
-and have extra events at the end that do not fit into a single key
-sequence. Then the value is a number, the number of events at the front
-of @var{key} that compose a complete key.
-
-@c Emacs 19 feature
-If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
-considers default bindings as well as bindings for the specific events
-in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
-the specific sequence @var{key}, ignoring default bindings except when
-you explicitly ask about them. (To do this, supply @code{t} as an
-element of @var{key}; see @ref{Format of Keymaps}.)
-
-If @var{key} contains a meta character (not a function key), that
-character is implicitly replaced by a two-character sequence: the value
-of @code{meta-prefix-char}, followed by the corresponding non-meta
-character. Thus, the first example below is handled by conversion into
-the second example.
-
-@example
-@group
-(lookup-key (current-global-map) "\M-f")
- @result{} forward-word
-@end group
-@group
-(lookup-key (current-global-map) "\ef")
- @result{} forward-word
-@end group
-@end example
-
-Unlike @code{read-key-sequence}, this function does not modify the
-specified events in ways that discard information (@pxref{Key Sequence
-Input}). In particular, it does not convert letters to lower case and
-it does not change drag events to clicks.
-@end defun
-
-@deffn Command undefined
-Used in keymaps to undefine keys. It calls @code{ding}, but does
-not cause an error.
-@end deffn
-
-@defun local-key-binding key &optional accept-defaults
-This function returns the binding for @var{key} in the current
-local keymap, or @code{nil} if it is undefined there.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
-@end defun
-
-@defun global-key-binding key &optional accept-defaults
-This function returns the binding for command @var{key} in the
-current global keymap, or @code{nil} if it is undefined there.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
-@end defun
-
-@c Emacs 19 feature
-@defun minor-mode-key-binding key &optional accept-defaults
-This function returns a list of all the active minor mode bindings of
-@var{key}. More precisely, it returns an alist of pairs
-@code{(@var{modename} . @var{binding})}, where @var{modename} is the
-variable that enables the minor mode, and @var{binding} is @var{key}'s
-binding in that mode. If @var{key} has no minor-mode bindings, the
-value is @code{nil}.
-
-If the first binding found is not a prefix definition (a keymap or a
-symbol defined as a keymap), all subsequent bindings from other minor
-modes are omitted, since they would be completely shadowed. Similarly,
-the list omits non-prefix bindings that follow prefix bindings.
-
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-@end defun
-
-@defvar meta-prefix-char
-@cindex @key{ESC}
-This variable is the meta-prefix character code. It is used for
-translating a meta character to a two-character sequence so it can be
-looked up in a keymap. For useful results, the value should be a
-prefix event (@pxref{Prefix Keys}). The default value is 27, which is
-the @acronym{ASCII} code for @key{ESC}.
-
-As long as the value of @code{meta-prefix-char} remains 27, key lookup
-translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
-as the @code{backward-word} command. However, if you were to set
-@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
-translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
-@code{switch-to-buffer} command. (Don't actually do this!) Here is an
-illustration of what would happen:
-
-@smallexample
-@group
-meta-prefix-char ; @r{The default value.}
- @result{} 27
-@end group
-@group
-(key-binding "\M-b")
- @result{} backward-word
-@end group
-@group
-?\C-x ; @r{The print representation}
- @result{} 24 ; @r{of a character.}
-@end group
-@group
-(setq meta-prefix-char 24)
- @result{} 24
-@end group
-@group
-(key-binding "\M-b")
- @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
- ; @r{like typing @kbd{C-x b}.}
-
-(setq meta-prefix-char 27) ; @r{Avoid confusion!}
- @result{} 27 ; @r{Restore the default value!}
-@end group
-@end smallexample
-
-This translation of one event into two happens only for characters, not
-for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function
-key, is not converted into @kbd{@key{ESC} @key{F1}}.
-@end defvar
-
-@node Changing Key Bindings
-@section Changing Key Bindings
-@cindex changing key bindings
-@cindex rebinding
-
- The way to rebind a key is to change its entry in a keymap. If you
-change a binding in the global keymap, the change is effective in all
-buffers (though it has no direct effect in buffers that shadow the
-global binding with a local one). If you change the current buffer's
-local map, that usually affects all buffers using the same major mode.
-The @code{global-set-key} and @code{local-set-key} functions are
-convenient interfaces for these operations (@pxref{Key Binding
-Commands}). You can also use @code{define-key}, a more general
-function; then you must specify explicitly the map to change.
-
- When choosing the key sequences for Lisp programs to rebind, please
-follow the Emacs conventions for use of various keys (@pxref{Key
-Binding Conventions}).
-
-@cindex meta character key constants
-@cindex control character key constants
- In writing the key sequence to rebind, it is good to use the special
-escape sequences for control and meta characters (@pxref{String Type}).
-The syntax @samp{\C-} means that the following character is a control
-character and @samp{\M-} means that the following character is a meta
-character. Thus, the string @code{"\M-x"} is read as containing a
-single @kbd{M-x}, @code{"\C-f"} is read as containing a single
-@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
-containing a single @kbd{C-M-x}. You can also use this escape syntax in
-vectors, as well as others that aren't allowed in strings; one example
-is @samp{[?\C-\H-x home]}. @xref{Character Type}.
-
- The key definition and lookup functions accept an alternate syntax for
-event types in a key sequence that is a vector: you can use a list
-containing modifier names plus one base event (a character or function
-key name). For example, @code{(control ?a)} is equivalent to
-@code{?\C-a} and @code{(hyper control left)} is equivalent to
-@code{C-H-left}. One advantage of such lists is that the precise
-numeric codes for the modifier bits don't appear in compiled files.
-
- The functions below signal an error if @var{keymap} is not a keymap,
-or if @var{key} is not a string or vector representing a key sequence.
-You can use event types (symbols) as shorthand for events that are
-lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
-way to specify the key sequence.
-
-@defun define-key keymap key binding
-This function sets the binding for @var{key} in @var{keymap}. (If
-@var{key} is more than one event long, the change is actually made
-in another keymap reached from @var{keymap}.) The argument
-@var{binding} can be any Lisp object, but only certain types are
-meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
-The value returned by @code{define-key} is @var{binding}.
-
-If @var{key} is @code{[t]}, this sets the default binding in
-@var{keymap}. When an event has no binding of its own, the Emacs
-command loop uses the keymap's default binding, if there is one.
-
-@cindex invalid prefix key error
-@cindex key sequence error
-Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
-or undefined; otherwise an error is signaled. If some prefix of
-@var{key} is undefined, then @code{define-key} defines it as a prefix
-key so that the rest of @var{key} can be defined as specified.
-
-If there was previously no binding for @var{key} in @var{keymap}, the
-new binding is added at the beginning of @var{keymap}. The order of
-bindings in a keymap makes no difference for keyboard input, but it
-does matter for menu keymaps (@pxref{Menu Keymaps}).
-@end defun
-
- This example creates a sparse keymap and makes a number of
-bindings in it:
-
-@smallexample
-@group
-(setq map (make-sparse-keymap))
- @result{} (keymap)
-@end group
-@group
-(define-key map "\C-f" 'forward-char)
- @result{} forward-char
-@end group
-@group
-map
- @result{} (keymap (6 . forward-char))
-@end group
-
-@group
-;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
-(define-key map (kbd "C-x f") 'forward-word)
- @result{} forward-word
-@end group
-@group
-map
-@result{} (keymap
- (24 keymap ; @kbd{C-x}
- (102 . forward-word)) ; @kbd{f}
- (6 . forward-char)) ; @kbd{C-f}
-@end group
-
-@group
-;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
-(define-key map (kbd "C-p") ctl-x-map)
-;; @code{ctl-x-map}
-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
-@end group
-
-@group
-;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
-(define-key map (kbd "C-p C-f") 'foo)
-@result{} 'foo
-@end group
-@group
-map
-@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
- (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
- (24 keymap
- (102 . forward-word))
- (6 . forward-char))
-@end group
-@end smallexample
-
-@noindent
-Note that storing a new binding for @kbd{C-p C-f} actually works by
-changing an entry in @code{ctl-x-map}, and this has the effect of
-changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
-default global map.
-
- The function @code{substitute-key-definition} scans a keymap for
-keys that have a certain binding and rebinds them with a different
-binding. Another feature which is cleaner and can often produce the
-same results to remap one command into another (@pxref{Remapping
-Commands}).
-
-@defun substitute-key-definition olddef newdef keymap &optional oldmap
-@cindex replace bindings
-This function replaces @var{olddef} with @var{newdef} for any keys in
-@var{keymap} that were bound to @var{olddef}. In other words,
-@var{olddef} is replaced with @var{newdef} wherever it appears. The
-function returns @code{nil}.
-
-For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
-standard bindings:
-
-@smallexample
-@group
-(substitute-key-definition
- 'find-file 'find-file-read-only (current-global-map))
-@end group
-@end smallexample
-
-@c Emacs 19 feature
-If @var{oldmap} is non-@code{nil}, that changes the behavior of
-@code{substitute-key-definition}: the bindings in @var{oldmap} determine
-which keys to rebind. The rebindings still happen in @var{keymap}, not
-in @var{oldmap}. Thus, you can change one map under the control of the
-bindings in another. For example,
-
-@smallexample
-(substitute-key-definition
- 'delete-backward-char 'my-funny-delete
- my-map global-map)
-@end smallexample
-
-@noindent
-puts the special deletion command in @code{my-map} for whichever keys
-are globally bound to the standard deletion command.
-
-Here is an example showing a keymap before and after substitution:
-
-@smallexample
-@group
-(setq map '(keymap
- (?1 . olddef-1)
- (?2 . olddef-2)
- (?3 . olddef-1)))
-@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
-@end group
-
-@group
-(substitute-key-definition 'olddef-1 'newdef map)
-@result{} nil
-@end group
-@group
-map
-@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
-@end group
-@end smallexample
-@end defun
-
-@defun suppress-keymap keymap &optional nodigits
-@cindex @code{self-insert-command} override
-This function changes the contents of the full keymap @var{keymap} by
-remapping @code{self-insert-command} to the command @code{undefined}
-(@pxref{Remapping Commands}). This has the effect of undefining all
-printing characters, thus making ordinary insertion of text impossible.
-@code{suppress-keymap} returns @code{nil}.
-
-If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
-digits to run @code{digit-argument}, and @kbd{-} to run
-@code{negative-argument}. Otherwise it makes them undefined like the
-rest of the printing characters.
-
-@cindex yank suppression
-@cindex @code{quoted-insert} suppression
-The @code{suppress-keymap} function does not make it impossible to
-modify a buffer, as it does not suppress commands such as @code{yank}
-and @code{quoted-insert}. To prevent any modification of a buffer, make
-it read-only (@pxref{Read Only Buffers}).
-
-Since this function modifies @var{keymap}, you would normally use it
-on a newly created keymap. Operating on an existing keymap
-that is used for some other purpose is likely to cause trouble; for
-example, suppressing @code{global-map} would make it impossible to use
-most of Emacs.
-
-Most often, @code{suppress-keymap} is used to initialize local
-keymaps of modes such as Rmail and Dired where insertion of text is not
-desirable and the buffer is read-only. Here is an example taken from
-the file @file{emacs/lisp/dired.el}, showing how the local keymap for
-Dired mode is set up:
-
-@smallexample
-@group
-(setq dired-mode-map (make-keymap))
-(suppress-keymap dired-mode-map)
-(define-key dired-mode-map "r" 'dired-rename-file)
-(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "v" 'dired-view-file)
-(define-key dired-mode-map "e" 'dired-find-file)
-(define-key dired-mode-map "f" 'dired-find-file)
-@dots{}
-@end group
-@end smallexample
-@end defun
-
-@node Remapping Commands
-@section Remapping Commands
-@cindex remapping commands
-
- A special kind of key binding, using a special ``key sequence''
-which includes a command name, has the effect of @dfn{remapping} that
-command into another. Here's how it works. You make a key binding
-for a key sequence that starts with the dummy event @code{remap},
-followed by the command name you want to remap. Specify the remapped
-definition as the definition in this binding. The remapped definition
-is usually a command name, but it can be any valid definition for
-a key binding.
-
- Here's an example. Suppose that My mode uses special commands
-@code{my-kill-line} and @code{my-kill-word}, which should be invoked
-instead of @code{kill-line} and @code{kill-word}. It can establish
-this by making these two command-remapping bindings in its keymap:
-
-@smallexample
-(define-key my-mode-map [remap kill-line] 'my-kill-line)
-(define-key my-mode-map [remap kill-word] 'my-kill-word)
-@end smallexample
-
-Whenever @code{my-mode-map} is an active keymap, if the user types
-@kbd{C-k}, Emacs will find the standard global binding of
-@code{kill-line} (assuming nobody has changed it). But
-@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
-so instead of running @code{kill-line}, Emacs runs
-@code{my-kill-line}.
-
-Remapping only works through a single level. In other words,
-
-@smallexample
-(define-key my-mode-map [remap kill-line] 'my-kill-line)
-(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
-@end smallexample
-
-@noindent
-does not have the effect of remapping @code{kill-line} into
-@code{my-other-kill-line}. If an ordinary key binding specifies
-@code{kill-line}, this keymap will remap it to @code{my-kill-line};
-if an ordinary binding specifies @code{my-kill-line}, this keymap will
-remap it to @code{my-other-kill-line}.
-
-@defun command-remapping command &optional position keymaps
-This function returns the remapping for @var{command} (a symbol),
-given the current active keymaps. If @var{command} is not remapped
-(which is the usual situation), or not a symbol, the function returns
-@code{nil}. @code{position} can optionally specify a buffer position
-or an event position to determine the keymaps to use, as in
-@code{key-binding}.
-
-If the optional argument @code{keymaps} is non-@code{nil}, it
-specifies a list of keymaps to search in. This argument is ignored if
-@code{position} is non-@code{nil}.
-@end defun
-
-@node Translation Keymaps
-@section Keymaps for Translating Sequences of Events
-@cindex keymaps for translating events
-
- This section describes keymaps that are used during reading a key
-sequence, to translate certain event sequences into others.
-@code{read-key-sequence} checks every subsequence of the key sequence
-being read, as it is read, against @code{function-key-map} and then
-against @code{key-translation-map}.
-
-@defvar function-key-map
-This variable holds a keymap that describes the character sequences sent
-by function keys on an ordinary character terminal. This keymap has the
-same structure as other keymaps, but is used differently: it specifies
-translations to make while reading key sequences, rather than bindings
-for key sequences.
-
-If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
-@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
-key sequence, it is replaced with the events in @var{v}.
-
-For example, VT100 terminals send @kbd{@key{ESC} O P} when the
-keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
-that sequence of events into the single event @code{pf1}. We accomplish
-this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
-@code{function-key-map}, when using a VT100.
-
-Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
-@key{ESC} O P}; later the function @code{read-key-sequence} translates
-this back into @kbd{C-c @key{PF1}}, which it returns as the vector
-@code{[?\C-c pf1]}.
-
-Entries in @code{function-key-map} are ignored if they conflict with
-bindings made in the minor mode, local, or global keymaps. The intent
-is that the character sequences that function keys send should not have
-command bindings in their own right---but if they do, the ordinary
-bindings take priority.
-
-The value of @code{function-key-map} is usually set up automatically
-according to the terminal's Terminfo or Termcap entry, but sometimes
-those need help from terminal-specific Lisp files. Emacs comes with
-terminal-specific files for many common terminals; their main purpose is
-to make entries in @code{function-key-map} beyond those that can be
-deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
-@end defvar
-
-@defvar key-translation-map
-This variable is another keymap used just like @code{function-key-map}
-to translate input events into other events. It differs from
-@code{function-key-map} in two ways:
-
-@itemize @bullet
-@item
-@code{key-translation-map} goes to work after @code{function-key-map} is
-finished; it receives the results of translation by
-@code{function-key-map}.
-
-@item
-Non-prefix bindings in @code{key-translation-map} override actual key
-bindings. For example, if @kbd{C-x f} has a non-prefix binding in
-@code{key-translation-map}, that translation takes effect even though
-@kbd{C-x f} also has a key binding in the global map.
-@end itemize
-
-Note however that actual key bindings can have an effect on
-@code{key-translation-map}, even though they are overridden by it.
-Indeed, actual key bindings override @code{function-key-map} and thus
-may alter the key sequence that @code{key-translation-map} receives.
-Clearly, it is better to avoid this type of situation.
-
-The intent of @code{key-translation-map} is for users to map one
-character set to another, including ordinary characters normally bound
-to @code{self-insert-command}.
-@end defvar
-
-@cindex key translation function
-You can use @code{function-key-map} or @code{key-translation-map} for
-more than simple aliases, by using a function, instead of a key
-sequence, as the ``translation'' of a key. Then this function is called
-to compute the translation of that key.
-
-The key translation function receives one argument, which is the prompt
-that was specified in @code{read-key-sequence}---or @code{nil} if the
-key sequence is being read by the editor command loop. In most cases
-you can ignore the prompt value.
-
-If the function reads input itself, it can have the effect of altering
-the event that follows. For example, here's how to define @kbd{C-c h}
-to turn the character that follows into a Hyper character:
-
-@example
-@group
-(defun hyperify (prompt)
- (let ((e (read-event)))
- (vector (if (numberp e)
- (logior (lsh 1 24) e)
- (if (memq 'hyper (event-modifiers e))
- e
- (add-event-modifier "H-" e))))))
-
-(defun add-event-modifier (string e)
- (let ((symbol (if (symbolp e) e (car e))))
- (setq symbol (intern (concat string
- (symbol-name symbol))))
-@end group
-@group
- (if (symbolp e)
- symbol
- (cons symbol (cdr e)))))
-
-(define-key function-key-map "\C-ch" 'hyperify)
-@end group
-@end example
-
- If you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done after the
-translations listed above. @xref{Terminal I/O Encoding}. However, in
-future Emacs versions, character set decoding may be done at an
-earlier stage.
-
-@node Key Binding Commands
-@section Commands for Binding Keys
-
- This section describes some convenient interactive interfaces for
-changing key bindings. They work by calling @code{define-key}.
-
- People often use @code{global-set-key} in their init files
-(@pxref{Init File}) for simple customization. For example,
-
-@smallexample
-(global-set-key (kbd "C-x C-\\") 'next-line)
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key [?\C-x ?\C-\\] 'next-line)
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key [(control ?x) (control ?\\)] 'next-line)
-@end smallexample
-
-@noindent
-redefines @kbd{C-x C-\} to move down a line.
-
-@smallexample
-(global-set-key [M-mouse-1] 'mouse-set-point)
-@end smallexample
-
-@noindent
-redefines the first (leftmost) mouse button, entered with the Meta key, to
-set point where you click.
-
-@cindex non-@acronym{ASCII} text in keybindings
- Be careful when using non-@acronym{ASCII} text characters in Lisp
-specifications of keys to bind. If these are read as multibyte text, as
-they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
-must type the keys as multibyte too. For instance, if you use this:
-
-@smallexample
-(global-set-key "@"o" 'my-function) ; bind o-umlaut
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key ?@"o 'my-function) ; bind o-umlaut
-@end smallexample
-
-@noindent
-and your language environment is multibyte Latin-1, these commands
-actually bind the multibyte character with code 2294, not the unibyte
-Latin-1 character with code 246 (@kbd{M-v}). In order to use this
-binding, you need to enter the multibyte Latin-1 character as keyboard
-input. One way to do this is by using an appropriate input method
-(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
-
- If you want to use a unibyte character in the key binding, you can
-construct the key sequence string using @code{multibyte-char-to-unibyte}
-or @code{string-make-unibyte} (@pxref{Converting Representations}).
-
-@deffn Command global-set-key key binding
-This function sets the binding of @var{key} in the current global map
-to @var{binding}.
-
-@smallexample
-@group
-(global-set-key @var{key} @var{binding})
-@equiv{}
-(define-key (current-global-map) @var{key} @var{binding})
-@end group
-@end smallexample
-@end deffn
-
-@deffn Command global-unset-key key
-@cindex unbinding keys
-This function removes the binding of @var{key} from the current
-global map.
-
-One use of this function is in preparation for defining a longer key
-that uses @var{key} as a prefix---which would not be allowed if
-@var{key} has a non-prefix binding. For example:
-
-@smallexample
-@group
-(global-unset-key "\C-l")
- @result{} nil
-@end group
-@group
-(global-set-key "\C-l\C-l" 'redraw-display)
- @result{} nil
-@end group
-@end smallexample
-
-This function is implemented simply using @code{define-key}:
-
-@smallexample
-@group
-(global-unset-key @var{key})
-@equiv{}
-(define-key (current-global-map) @var{key} nil)
-@end group
-@end smallexample
-@end deffn
-
-@deffn Command local-set-key key binding
-This function sets the binding of @var{key} in the current local
-keymap to @var{binding}.
-
-@smallexample
-@group
-(local-set-key @var{key} @var{binding})
-@equiv{}
-(define-key (current-local-map) @var{key} @var{binding})
-@end group
-@end smallexample
-@end deffn
-
-@deffn Command local-unset-key key
-This function removes the binding of @var{key} from the current
-local map.
-
-@smallexample
-@group
-(local-unset-key @var{key})
-@equiv{}
-(define-key (current-local-map) @var{key} nil)
-@end group
-@end smallexample
-@end deffn
-
-@node Scanning Keymaps
-@section Scanning Keymaps
-
- This section describes functions used to scan all the current keymaps
-for the sake of printing help information.
-
-@defun accessible-keymaps keymap &optional prefix
-This function returns a list of all the keymaps that can be reached (via
-zero or more prefix keys) from @var{keymap}. The value is an
-association list with elements of the form @code{(@var{key} .@:
-@var{map})}, where @var{key} is a prefix key whose definition in
-@var{keymap} is @var{map}.
-
-The elements of the alist are ordered so that the @var{key} increases
-in length. The first element is always @code{([] .@: @var{keymap})},
-because the specified keymap is accessible from itself with a prefix of
-no events.
-
-If @var{prefix} is given, it should be a prefix key sequence; then
-@code{accessible-keymaps} includes only the submaps whose prefixes start
-with @var{prefix}. These elements look just as they do in the value of
-@code{(accessible-keymaps)}; the only difference is that some elements
-are omitted.
-
-In the example below, the returned alist indicates that the key
-@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
-definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
-(115 .@: foo))}.
-
-@smallexample
-@group
-(accessible-keymaps (current-local-map))
-@result{}(([] keymap
- (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
- (83 . center-paragraph)
- (115 . center-line))
- (9 . tab-to-tab-stop))
-@end group
-
-@group
- ("^[" keymap
- (83 . center-paragraph)
- (115 . foo)))
-@end group
-@end smallexample
-
-In the following example, @kbd{C-h} is a prefix key that uses a sparse
-keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
-Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
-the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of
-several dummy events used as prefixes for mouse actions in special parts
-of a window.
-
-@smallexample
-@group
-(accessible-keymaps (current-global-map))
-@result{} (([] keymap [set-mark-command beginning-of-line @dots{}
- delete-backward-char])
-@end group
-@group
- ("^H" keymap (118 . describe-variable) @dots{}
- (8 . help-for-help))
-@end group
-@group
- ("^X" keymap [x-flush-mouse-queue @dots{}
- backward-kill-sentence])
-@end group
-@group
- ("^[" keymap [mark-sexp backward-sexp @dots{}
- backward-kill-word])
-@end group
- ("^X4" keymap (15 . display-buffer) @dots{})
-@group
- ([mode-line] keymap
- (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
-@end group
-@end smallexample
-
-@noindent
-These are not all the keymaps you would see in actuality.
-@end defun
-
-@defun map-keymap function keymap
-The function @code{map-keymap} calls @var{function} once
-for each binding in @var{keymap}. It passes two arguments,
-the event type and the value of the binding. If @var{keymap}
-has a parent, the parent's bindings are included as well.
-This works recursively: if the parent has itself a parent, then the
-grandparent's bindings are also included and so on.
-
-This function is the cleanest way to examine all the bindings
-in a keymap.
-@end defun
-
-@defun where-is-internal command &optional keymap firstonly noindirect no-remap
-This function is a subroutine used by the @code{where-is} command
-(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
-of all key sequences (of any length) that are bound to @var{command} in a
-set of keymaps.
-
-The argument @var{command} can be any object; it is compared with all
-keymap entries using @code{eq}.
-
-If @var{keymap} is @code{nil}, then the maps used are the current active
-keymaps, disregarding @code{overriding-local-map} (that is, pretending
-its value is @code{nil}). If @var{keymap} is a keymap, then the
-maps searched are @var{keymap} and the global keymap. If @var{keymap}
-is a list of keymaps, only those keymaps are searched.
-
-Usually it's best to use @code{overriding-local-map} as the expression
-for @var{keymap}. Then @code{where-is-internal} searches precisely the
-keymaps that are active. To search only the global map, pass
-@code{(keymap)} (an empty keymap) as @var{keymap}.
-
-If @var{firstonly} is @code{non-ascii}, then the value is a single
-vector representing the first key sequence found, rather than a list of
-all possible key sequences. If @var{firstonly} is @code{t}, then the
-value is the first key sequence, except that key sequences consisting
-entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
-characters) are preferred to all other key sequences and that the
-return value can never be a menu binding.
-
-If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
-follow indirect keymap bindings. This makes it possible to search for
-an indirect definition itself.
-
-When command remapping is in effect (@pxref{Remapping Commands}),
-@code{where-is-internal} figures out when a command will be run due to
-remapping and reports keys accordingly. It also returns @code{nil} if
-@var{command} won't really be run because it has been remapped to some
-other command. However, if @var{no-remap} is non-@code{nil}.
-@code{where-is-internal} ignores remappings.
-
-@smallexample
-@group
-(where-is-internal 'describe-function)
- @result{} ([8 102] [f1 102] [help 102]
- [menu-bar help-menu describe describe-function])
-@end group
-@end smallexample
-@end defun
-
-@deffn Command describe-bindings &optional prefix buffer-or-name
-This function creates a listing of all current key bindings, and
-displays it in a buffer named @samp{*Help*}. The text is grouped by
-modes---minor modes first, then the major mode, then global bindings.
-
-If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
-listing includes only keys that start with @var{prefix}.
-
-The listing describes meta characters as @key{ESC} followed by the
-corresponding non-meta character.
-
-When several characters with consecutive @acronym{ASCII} codes have the
-same definition, they are shown together, as
-@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
-know the @acronym{ASCII} codes to understand which characters this means.
-For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32,
-@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
-the normal printing characters, (e.g., letters, digits, punctuation,
-etc.@:); all these characters are bound to @code{self-insert-command}.
-
-If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
-buffer name. Then @code{describe-bindings} lists that buffer's bindings,
-instead of the current buffer's.
-@end deffn
-
-@node Menu Keymaps
-@section Menu Keymaps
-@cindex menu keymaps
-
-A keymap can operate as a menu as well as defining bindings for
-keyboard keys and mouse buttons. Menus are usually actuated with the
-mouse, but they can function with the keyboard also. If a menu keymap
-is active for the next input event, that activates the keyboard menu
-feature.
-
-@menu
-* 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.
-@end menu
-
-@node Defining Menus
-@subsection Defining Menus
-@cindex defining menus
-@cindex menu prompt string
-@cindex prompt string (of menu)
-
-A keymap acts as a menu if it has an @dfn{overall prompt string},
-which is a string that appears as an element of the keymap.
-(@xref{Format of Keymaps}.) The string should describe the purpose of
-the menu's commands. Emacs displays the overall prompt string as the
-menu title in some cases, depending on the toolkit (if any) used for
-displaying menus.@footnote{It is required for menus which do not use a
-toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the
-overall prompt string.
-
-The easiest way to construct a keymap with a prompt string is to
-specify the string as an argument when you call @code{make-keymap},
-@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
-@code{define-prefix-command} (@pxref{Definition of
-define-prefix-command}). If you do not want the keymap to operate as
-a menu, don't specify a prompt string for it.
-
-@defun keymap-prompt keymap
-This function returns the overall prompt string of @var{keymap},
-or @code{nil} if it has none.
-@end defun
-
-The menu's items are the bindings in the keymap. Each binding
-associates an event type to a definition, but the event types have no
-significance for the menu appearance. (Usually we use pseudo-events,
-symbols that the keyboard cannot generate, as the event types for menu
-item bindings.) The menu is generated entirely from the bindings that
-correspond in the keymap to these events.
-
-The order of items in the menu is the same as the order of bindings in
-the keymap. Since @code{define-key} puts new bindings at the front, you
-should define the menu items starting at the bottom of the menu and
-moving to the top, if you care about the order. When you add an item to
-an existing menu, you can specify its position in the menu using
-@code{define-key-after} (@pxref{Modifying Menus}).
-
-@menu
-* 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.
-@end menu
-
-@node Simple Menu Items
-@subsubsection Simple Menu Items
-
- The simpler (and original) way to define a menu item is to bind some
-event type (it doesn't matter what event type) to a binding like this:
-
-@example
-(@var{item-string} . @var{real-binding})
-@end example
-
-@noindent
-The @sc{car}, @var{item-string}, is the string to be displayed in the
-menu. It should be short---preferably one to three words. It should
-describe the action of the command it corresponds to. Note that it is
-not generally possible to display non-@acronym{ASCII} text in menus. It will
-work for keyboard menus and will work to a large extent when Emacs is
-built with the Gtk+ toolkit.@footnote{In this case, the text is first
-encoded using the @code{utf-8} coding system and then rendered by the
-toolkit as it sees fit.}
-
- You can also supply a second string, called the help string, as follows:
-
-@example
-(@var{item-string} @var{help} . @var{real-binding})
-@end example
-
-@noindent
-@var{help} specifies a ``help-echo'' string to display while the mouse
-is on that item in the same way as @code{help-echo} text properties
-(@pxref{Help display}).
-
- As far as @code{define-key} is concerned, @var{item-string} and
-@var{help-string} are part of the event's binding. However,
-@code{lookup-key} returns just @var{real-binding}, and only
-@var{real-binding} is used for executing the key.
-
- If @var{real-binding} is @code{nil}, then @var{item-string} appears in
-the menu but cannot be selected.
-
- If @var{real-binding} is a symbol and has a non-@code{nil}
-@code{menu-enable} property, that property is an expression that
-controls whether the menu item is enabled. Every time the keymap is
-used to display a menu, Emacs evaluates the expression, and it enables
-the menu item only if the expression's value is non-@code{nil}. When a
-menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
-cannot be selected.
-
- The menu bar does not recalculate which items are enabled every time you
-look at a menu. This is because the X toolkit requires the whole tree
-of menus in advance. To force recalculation of the menu bar, call
-@code{force-mode-line-update} (@pxref{Mode Line Format}).
-
- You've probably noticed that menu items show the equivalent keyboard key
-sequence (if any) to invoke the same command. To save time on
-recalculation, menu display caches this information in a sublist in the
-binding, like this:
-
-@c This line is not too long--rms.
-@example
-(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
-@end example
-
-@noindent
-Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't mention keyboard equivalents in
-the item strings themselves, since that is redundant.
-
-@node Extended Menu Items
-@subsubsection Extended Menu Items
-@kindex menu-item
-
- An extended-format menu item is a more flexible and also cleaner
-alternative to the simple format. You define an event type with a
-binding that's a list starting with the symbol @code{menu-item}.
-For a non-selectable string, the binding looks like this:
-
-@example
-(menu-item @var{item-name})
-@end example
-
-@noindent
-A string starting with two or more dashes specifies a separator line;
-see @ref{Menu Separators}.
-
- To define a real menu item which can be selected, the extended format
-binding looks like this:
-
-@example
-(menu-item @var{item-name} @var{real-binding}
- . @var{item-property-list})
-@end example
-
-@noindent
-Here, @var{item-name} is an expression which evaluates to the menu item
-string. Thus, the string need not be a constant. The third element,
-@var{real-binding}, is the command to execute. The tail of the list,
-@var{item-property-list}, has the form of a property list which contains
-other information.
-
- When an equivalent keyboard key binding is cached, the extended menu
-item binding looks like this:
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
- Here is a table of the properties that are supported:
-
-@table @code
-@item :enable @var{form}
-The result of evaluating @var{form} determines whether the item is
-enabled (non-@code{nil} means yes). If the item is not enabled,
-you can't really click on it.
-
-@item :visible @var{form}
-The result of evaluating @var{form} determines whether the item should
-actually appear in the menu (non-@code{nil} means yes). If the item
-does not appear, then the menu is displayed as if this item were
-not defined at all.
-
-@item :help @var{help}
-The value of this property, @var{help}, specifies a ``help-echo'' string
-to display while the mouse is on that item. This is displayed in the
-same way as @code{help-echo} text properties (@pxref{Help display}).
-Note that this must be a constant string, unlike the @code{help-echo}
-property for text and overlays.
-
-@item :button (@var{type} . @var{selected})
-This property provides a way to define radio buttons and toggle buttons.
-The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
-@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
-result of evaluating it says whether this button is currently selected.
-
-A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
-according to the value of @var{selected}. The command itself should
-toggle @var{selected}, setting it to @code{t} if it is @code{nil},
-and to @code{nil} if it is @code{t}. Here is how the menu item
-to toggle the @code{debug-on-error} flag is defined:
-
-@example
-(menu-item "Debug on Error" toggle-debug-on-error
- :button (:toggle
- . (and (boundp 'debug-on-error)
- debug-on-error)))
-@end example
-
-@noindent
-This works because @code{toggle-debug-on-error} is defined as a command
-which toggles the variable @code{debug-on-error}.
-
-@dfn{Radio buttons} are a group of menu items, in which at any time one
-and only one is ``selected.'' There should be a variable whose value
-says which one is selected at any time. The @var{selected} form for
-each radio button in the group should check whether the variable has the
-right value for selecting that button. Clicking on the button should
-set the variable so that the button you clicked on becomes selected.
-
-@item :key-sequence @var{key-sequence}
-This property specifies which key sequence is likely to be bound to the
-same command invoked by this menu item. If you specify the right key
-sequence, that makes preparing the menu for display run much faster.
-
-If you specify the wrong key sequence, it has no effect; before Emacs
-displays @var{key-sequence} in the menu, it verifies that
-@var{key-sequence} is really equivalent to this menu item.
-
-@item :key-sequence nil
-This property indicates that there is normally no key binding which is
-equivalent to this menu item. Using this property saves time in
-preparing the menu for display, because Emacs does not need to search
-the keymaps for a keyboard equivalent for this menu item.
-
-However, if the user has rebound this item's definition to a key
-sequence, Emacs ignores the @code{:keys} property and finds the keyboard
-equivalent anyway.
-
-@item :keys @var{string}
-This property specifies that @var{string} is the string to display
-as the keyboard equivalent for this menu item. You can use
-the @samp{\\[...]} documentation construct in @var{string}.
-
-@item :filter @var{filter-fn}
-This property provides a way to compute the menu item dynamically.
-The property value @var{filter-fn} should be a function of one argument;
-when it is called, its argument will be @var{real-binding}. The
-function should return the binding to use instead.
-
-Emacs can call this function at any time that it does redisplay or
-operates on menu data structures, so you should write it so it can
-safely be called at any time.
-@end table
-
-@node Menu Separators
-@subsubsection Menu Separators
-@cindex menu separators
-
- A menu separator is a kind of menu item that doesn't display any
-text---instead, it divides the menu into subparts with a horizontal line.
-A separator looks like this in the menu keymap:
-
-@example
-(menu-item @var{separator-type})
-@end example
-
-@noindent
-where @var{separator-type} is a string starting with two or more dashes.
-
- In the simplest case, @var{separator-type} consists of only dashes.
-That specifies the default kind of separator. (For compatibility,
-@code{""} and @code{-} also count as separators.)
-
- Certain other values of @var{separator-type} specify a different
-style of separator. Here is a table of them:
-
-@table @code
-@item "--no-line"
-@itemx "--space"
-An extra vertical space, with no actual line.
-
-@item "--single-line"
-A single line in the menu's foreground color.
-
-@item "--double-line"
-A double line in the menu's foreground color.
-
-@item "--single-dashed-line"
-A single dashed line in the menu's foreground color.
-
-@item "--double-dashed-line"
-A double dashed line in the menu's foreground color.
-
-@item "--shadow-etched-in"
-A single line with a 3D sunken appearance. This is the default,
-used separators consisting of dashes only.
-
-@item "--shadow-etched-out"
-A single line with a 3D raised appearance.
-
-@item "--shadow-etched-in-dash"
-A single dashed line with a 3D sunken appearance.
-
-@item "--shadow-etched-out-dash"
-A single dashed line with a 3D raised appearance.
-
-@item "--shadow-double-etched-in"
-Two lines with a 3D sunken appearance.
-
-@item "--shadow-double-etched-out"
-Two lines with a 3D raised appearance.
-
-@item "--shadow-double-etched-in-dash"
-Two dashed lines with a 3D sunken appearance.
-
-@item "--shadow-double-etched-out-dash"
-Two dashed lines with a 3D raised appearance.
-@end table
-
- You can also give these names in another style, adding a colon after
-the double-dash and replacing each single dash with capitalization of
-the following word. Thus, @code{"--:singleLine"}, is equivalent to
-@code{"--single-line"}.
-
- Some systems and display toolkits don't really handle all of these
-separator types. If you use a type that isn't supported, the menu
-displays a similar kind of separator that is supported.
-
-@node Alias Menu Items
-@subsubsection Alias Menu Items
-
- Sometimes it is useful to make menu items that use the ``same''
-command but with different enable conditions. The best way to do this
-in Emacs now is with extended menu items; before that feature existed,
-it could be done by defining alias commands and using them in menu
-items. Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
-
-@example
-(defalias 'make-read-only 'toggle-read-only)
-(put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
-(put 'make-writable 'menu-enable 'buffer-read-only)
-@end example
-
-When using aliases in menus, often it is useful to display the
-equivalent key bindings for the ``real'' command name, not the aliases
-(which typically don't have any key bindings except for the menu
-itself). To request this, give the alias symbol a non-@code{nil}
-@code{menu-alias} property. Thus,
-
-@example
-(put 'make-read-only 'menu-alias t)
-(put 'make-writable 'menu-alias t)
-@end example
-
-@noindent
-causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
-
-@node Mouse Menus
-@subsection Menus and the Mouse
-
- The usual way to make a menu keymap produce a menu is to make it the
-definition of a prefix key. (A Lisp program can explicitly pop up a
-menu and receive the user's choice---see @ref{Pop-Up Menus}.)
-
- If the prefix key ends with a mouse event, Emacs handles the menu keymap
-by popping up a visible menu, so that the user can select a choice with
-the mouse. When the user clicks on a menu item, the event generated is
-whatever character or symbol has the binding that brought about that
-menu item. (A menu item may generate a series of events if the menu has
-multiple levels or comes from the menu bar.)
-
- It's often best to use a button-down event to trigger the menu. Then
-the user can select a menu item by releasing the button.
-
- A single keymap can appear as multiple menu panes, if you explicitly
-arrange for this. The way to do this is to make a keymap for each pane,
-then create a binding for each of those maps in the main keymap of the
-menu. Give each of these bindings an item string that starts with
-@samp{@@}. The rest of the item string becomes the name of the pane.
-See the file @file{lisp/mouse.el} for an example of this. Any ordinary
-bindings with @samp{@@}-less item strings are grouped into one pane,
-which appears along with the other panes explicitly created for the
-submaps.
-
- X toolkit menus don't have panes; instead, they can have submenus.
-Every nested keymap becomes a submenu, whether the item string starts
-with @samp{@@} or not. In a toolkit version of Emacs, the only thing
-special about @samp{@@} at the beginning of an item string is that the
-@samp{@@} doesn't appear in the menu item.
-
- Multiple keymaps that define the same menu prefix key produce
-separate panes or separate submenus.
-
-@node Keyboard Menus
-@subsection Menus and the Keyboard
-
- When a prefix key ending with a keyboard event (a character or
-function key) has a definition that is a menu keymap, the keymap
-operates as a keyboard menu; the user specifies the next event by
-choosing a menu item with the keyboard.
-
- Emacs displays the keyboard menu with the map's overall prompt
-string, followed by the alternatives (the item strings of the map's
-bindings), in the echo area. If the bindings don't all fit at once,
-the user can type @key{SPC} to see the next line of alternatives.
-Successive uses of @key{SPC} eventually get to the end of the menu and
-then cycle around to the beginning. (The variable
-@code{menu-prompt-more-char} specifies which character is used for
-this; @key{SPC} is the default.)
-
- When the user has found the desired alternative from the menu, he or
-she should type the corresponding character---the one whose binding is
-that alternative.
-
-@ignore
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type. The best convention to use is to make
-the character the first letter of the item string---that is something
-users will understand without being told. We plan to change this; by
-the time you read this manual, keyboard menus may explicitly name the
-key for each alternative.
-@end ignore
-
- This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
-
-@defvar menu-prompt-more-char
-This variable specifies the character to use to ask to see
-the next line of a menu. Its initial value is 32, the code
-for @key{SPC}.
-@end defvar
-
-@node Menu Example
-@subsection Menu Example
-@cindex menu definition example
-
- Here is a complete example of defining a menu keymap. It is the
-definition of the @samp{Replace} submenu in the @samp{Edit} menu in
-the menu bar, and it uses the extended menu item format
-(@pxref{Extended Menu Items}). First we create the keymap, and give
-it a name:
-
-@smallexample
-(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
-@end smallexample
-
-@noindent
-Next we define the menu items:
-
-@smallexample
-(define-key menu-bar-replace-menu [tags-repl-continue]
- '(menu-item "Continue Replace" tags-loop-continue
- :help "Continue last tags replace operation"))
-(define-key menu-bar-replace-menu [tags-repl]
- '(menu-item "Replace in tagged files" tags-query-replace
- :help "Interactively replace a regexp in all tagged files"))
-(define-key menu-bar-replace-menu [separator-replace-tags]
- '(menu-item "--"))
-;; @r{@dots{}}
-@end smallexample
-
-@noindent
-Note the symbols which the bindings are ``made for''; these appear
-inside square brackets, in the key sequence being defined. In some
-cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys,'' but they are
-not real function keys on the keyboard. They do not affect the
-functioning of the menu itself, but they are ``echoed'' in the echo area
-when the user selects from the menu, and they appear in the output of
-@code{where-is} and @code{apropos}.
-
- The menu in this example is intended for use with the mouse. If a
-menu is intended for use with the keyboard, that is, if it is bound to
-a key sequence ending with a keyboard event, then the menu items
-should be bound to characters or ``real'' function keys, that can be
-typed with the keyboard.
-
- The binding whose definition is @code{("--")} is a separator line.
-Like a real menu item, the separator has a key symbol, in this case
-@code{separator-replace-tags}. If one menu has two separators, they
-must have two different key symbols.
-
- Here is how we make this menu appear as an item in the parent menu:
-
-@example
-(define-key menu-bar-edit-menu [replace]
- (list 'menu-item "Replace" menu-bar-replace-menu))
-@end example
-
-@noindent
-Note that this incorporates the submenu keymap, which is the value of
-the variable @code{menu-bar-replace-menu}, rather than the symbol
-@code{menu-bar-replace-menu} itself. Using that symbol in the parent
-menu item would be meaningless because @code{menu-bar-replace-menu} is
-not a command.
-
- If you wanted to attach the same replace menu to a mouse click, you
-can do it this way:
-
-@example
-(define-key global-map [C-S-down-mouse-1]
- menu-bar-replace-menu)
-@end example
-
-@node Menu Bar
-@subsection The Menu Bar
-@cindex menu bar
-
- Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of the
-frame. The items of the menu bar are the subcommands of the fake
-``function key'' @code{menu-bar}, as defined in the active keymaps.
-
- To add an item to the menu bar, invent a fake ``function key'' of your
-own (let's call it @var{key}), and make a binding for the key sequence
-@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
-so that pressing a button on the menu bar item leads to another menu.
-
- When more than one active keymap defines the same fake function key
-for the menu bar, the item appears just once. If the user clicks on
-that menu bar item, it brings up a single, combined menu containing
-all the subcommands of that item---the global subcommands, the local
-subcommands, and the minor mode subcommands.
-
- The variable @code{overriding-local-map} is normally ignored when
-determining the menu bar contents. That is, the menu bar is computed
-from the keymaps that would be active if @code{overriding-local-map}
-were @code{nil}. @xref{Active Keymaps}.
-
- In order for a frame to display a menu bar, its @code{menu-bar-lines}
-parameter must be greater than zero. Emacs uses just one line for the
-menu bar itself; if you specify more than one line, the other lines
-serve to separate the menu bar from the windows in the frame. We
-recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout
-Parameters}.
-
- Here's an example of setting up a menu bar item:
-
-@example
-@group
-(modify-frame-parameters (selected-frame)
- '((menu-bar-lines . 2)))
-@end group
-
-@group
-;; @r{Make a menu keymap (with a prompt string)}
-;; @r{and make it the menu bar item's definition.}
-(define-key global-map [menu-bar words]
- (cons "Words" (make-sparse-keymap "Words")))
-@end group
-
-@group
-;; @r{Define specific subcommands in this menu.}
-(define-key global-map
- [menu-bar words forward]
- '("Forward word" . forward-word))
-@end group
-@group
-(define-key global-map
- [menu-bar words backward]
- '("Backward word" . backward-word))
-@end group
-@end example
-
- A local keymap can cancel a menu bar item made by the global keymap by
-rebinding the same fake function key with @code{undefined} as the
-binding. For example, this is how Dired suppresses the @samp{Edit} menu
-bar item:
-
-@example
-(define-key dired-mode-map [menu-bar edit] 'undefined)
-@end example
-
-@noindent
-@code{edit} is the fake function key used by the global map for the
-@samp{Edit} menu bar item. The main reason to suppress a global
-menu bar item is to regain space for mode-specific items.
-
-@defvar menu-bar-final-items
-Normally the menu bar shows global items followed by items defined by the
-local maps.
-
-This variable holds a list of fake function keys for items to display at
-the end of the menu bar rather than in normal sequence. The default
-value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
-at the end of the menu bar, following local menu items.
-@end defvar
-
-@defvar menu-bar-update-hook
-This normal hook is run by redisplay to update the menu bar contents,
-before redisplaying the menu bar. You can use it to update submenus
-whose contents should vary. Since this hook is run frequently, we
-advise you to ensure that the functions it calls do not take much time
-in the usual case.
-@end defvar
-
-@node Tool Bar
-@subsection Tool bars
-@cindex tool bar
-
- A @dfn{tool bar} is a row of icons at the top of a frame, that execute
-commands when you click on them---in effect, a kind of graphical menu
-bar.
-
- The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
-controls how many lines' worth of height to reserve for the tool bar. A
-zero value suppresses the tool bar. If the value is nonzero, and
-@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
-contracts automatically as needed to hold the specified contents.
-
- If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, the user has to redraw the frame by entering
-@kbd{C-l}.
-
- The tool bar contents are controlled by a menu keymap attached to a
-fake ``function key'' called @code{tool-bar} (much like the way the menu
-bar is controlled). So you define a tool bar item using
-@code{define-key}, like this:
-
-@example
-(define-key global-map [tool-bar @var{key}] @var{item})
-@end example
-
-@noindent
-where @var{key} is a fake ``function key'' to distinguish this item from
-other items, and @var{item} is a menu item key binding (@pxref{Extended
-Menu Items}), which says how to display this item and how it behaves.
-
- The usual menu keymap item properties, @code{:visible},
-@code{:enable}, @code{:button}, and @code{:filter}, are useful in
-tool bar bindings and have their normal meanings. The @var{real-binding}
-in the item must be a command, not a keymap; in other words, it does not
-work to define a tool bar icon as a prefix key.
-
- The @code{:help} property specifies a ``help-echo'' string to display
-while the mouse is on that item. This is displayed in the same way as
-@code{help-echo} text properties (@pxref{Help display}).
-
- In addition, you should use the @code{:image} property;
-this is how you specify the image to display in the tool bar:
-
-@table @code
-@item :image @var{image}
-@var{images} is either a single image specification or a vector of four
-image specifications. If you use a vector of four,
-one of them is used, depending on circumstances:
-
-@table @asis
-@item item 0
-Used when the item is enabled and selected.
-@item item 1
-Used when the item is enabled and deselected.
-@item item 2
-Used when the item is disabled and selected.
-@item item 3
-Used when the item is disabled and deselected.
-@end table
-@end table
-
-If @var{image} is a single image specification, Emacs draws the tool bar
-button in disabled state by applying an edge-detection algorithm to the
-image.
-
-The default tool bar is defined so that items specific to editing do not
-appear for major modes whose command symbol has a @code{mode-class}
-property of @code{special} (@pxref{Major Mode Conventions}). Major
-modes may add items to the global bar by binding @code{[tool-bar
-@var{foo}]} in their local map. It makes sense for some major modes to
-replace the default tool bar items completely, since not many can be
-accommodated conveniently, and the default bindings make this easy by
-using an indirection through @code{tool-bar-map}.
-
-@defvar tool-bar-map
-By default, the global map binds @code{[tool-bar]} as follows:
-@example
-(global-set-key [tool-bar]
- '(menu-item "tool bar" ignore
- :filter (lambda (ignore) tool-bar-map)))
-@end example
-@noindent
-Thus the tool bar map is derived dynamically from the value of variable
-@code{tool-bar-map} and you should normally adjust the default (global)
-tool bar by changing that map. Major modes may replace the global bar
-completely by making @code{tool-bar-map} buffer-local and set to a
-keymap containing only the desired items. Info mode provides an
-example.
-@end defvar
-
-There are two convenience functions for defining tool bar items, as
-follows.
-
-@defun tool-bar-add-item icon def key &rest props
-This function adds an item to the tool bar by modifying
-@code{tool-bar-map}. The image to use is defined by @var{icon}, which
-is the base name of an XPM, XBM or PBM image file to be located by
-@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm},
-@file{exit.pbm} and @file{exit.xbm} would be searched for in that order
-on a color display. On a monochrome display, the search order is
-@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the
-command @var{def}, and @var{key} is the fake function key symbol in the
-prefix keymap. The remaining arguments @var{props} are additional
-property list elements to add to the menu item specification.
-
-To define items in some local map, bind @code{tool-bar-map} with
-@code{let} around calls of this function:
-@example
-(defvar foo-tool-bar-map
- (let ((tool-bar-map (make-sparse-keymap)))
- (tool-bar-add-item @dots{})
- @dots{}
- tool-bar-map))
-@end example
-@end defun
-
-@defun tool-bar-add-item-from-menu command icon &optional map &rest props
-This function is a convenience for defining tool bar items which are
-consistent with existing menu bar bindings. The binding of
-@var{command} is looked up in the menu bar in @var{map} (default
-@code{global-map}) and modified to add an image specification for
-@var{icon}, which is found in the same way as by
-@code{tool-bar-add-item}. The resulting binding is then placed in
-@code{tool-bar-map}, so use this function only for global tool bar
-items.
-
-@var{map} must contain an appropriate keymap bound to
-@code{[menu-bar]}. The remaining arguments @var{props} are additional
-property list elements to add to the menu item specification.
-@end defun
-
-@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
-This function is used for making non-global tool bar items. Use it
-like @code{tool-bar-add-item-from-menu} except that @var{in-map}
-specifies the local map to make the definition in. The argument
-@var{from-map} is like the @var{map} argument of
-@code{tool-bar-add-item-from-menu}.
-@end defun
-
-@defvar auto-resize-tool-bar
-If this variable is non-@code{nil}, the tool bar automatically resizes to
-show all defined tool bar items---but not larger than a quarter of the
-frame's height.
-
-If the value is @code{grow-only}, the tool bar expands automatically,
-but does not contract automatically. To contract the tool bar, the
-user has to redraw the frame by entering @kbd{C-l}.
-@end defvar
-
-@defvar auto-raise-tool-bar-buttons
-If this variable is non-@code{nil}, tool bar items display
-in raised form when the mouse moves over them.
-@end defvar
-
-@defvar tool-bar-button-margin
-This variable specifies an extra margin to add around tool bar items.
-The value is an integer, a number of pixels. The default is 4.
-@end defvar
-
-@defvar tool-bar-button-relief
-This variable specifies the shadow width for tool bar items.
-The value is an integer, a number of pixels. The default is 1.
-@end defvar
-
-@defvar tool-bar-border
-This variable specifies the height of the border drawn below the tool
-bar area. An integer value specifies height as a number of pixels.
-If the value is one of @code{internal-border-width} (the default) or
-@code{border-width}, the tool bar border height corresponds to the
-corresponding frame parameter.
-@end defvar
-
- You can define a special meaning for clicking on a tool bar item with
-the shift, control, meta, etc., modifiers. You do this by setting up
-additional items that relate to the original item through the fake
-function keys. Specifically, the additional items should use the
-modified versions of the same fake function key used to name the
-original item.
-
- Thus, if the original item was defined this way,
-
-@example
-(define-key global-map [tool-bar shell]
- '(menu-item "Shell" shell
- :image (image :type xpm :file "shell.xpm")))
-@end example
-
-@noindent
-then here is how you can define clicking on the same tool bar image with
-the shift modifier:
-
-@example
-(define-key global-map [tool-bar S-shell] 'some-command)
-@end example
-
-@xref{Function Keys}, for more information about how to add modifiers to
-function keys.
-
-@node Modifying Menus
-@subsection Modifying Menus
-
- When you insert a new item in an existing menu, you probably want to
-put it in a particular place among the menu's existing items. If you
-use @code{define-key} to add the item, it normally goes at the front of
-the menu. To put it elsewhere in the menu, use @code{define-key-after}:
-
-@defun define-key-after map key binding &optional after
-Define a binding in @var{map} for @var{key}, with value @var{binding},
-just like @code{define-key}, but position the binding in @var{map} after
-the binding for the event @var{after}. The argument @var{key} should be
-of length one---a vector or string with just one element. But
-@var{after} should be a single event type---a symbol or a character, not
-a sequence. The new binding goes after the binding for @var{after}. If
-@var{after} is @code{t} or is omitted, then the new binding goes last, at
-the end of the keymap. However, new bindings are added before any
-inherited keymap.
-
-Here is an example:
-
-@example
-(define-key-after my-menu [drink]
- '("Drink" . drink-command) 'eat)
-@end example
-
-@noindent
-makes a binding for the fake function key @key{DRINK} and puts it
-right after the binding for @key{EAT}.
-
-Here is how to insert an item called @samp{Work} in the @samp{Signals}
-menu of Shell mode, after the item @code{break}:
-
-@example
-(define-key-after
- (lookup-key shell-mode-map [menu-bar signals])
- [work] '("Work" . work-command) 'break)
-@end example
-@end defun
-
-@ignore
- arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
-@c Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@c
-@comment %**start of header
-@setfilename inner-covers.info
-@settitle Inner Covers
-@smallbook
-@comment %**end of header
-
-@headings off
-
-@w{ }
-@sp 4
-@tex
-\center {\secfonts \rm Lay-Flat Binding}
-@end tex
-@sp 2
-
-We have bound this manual using a new @dfn{lay-flat} binding
-technology. This type of binding allows you to open a soft cover book
-so that it ``lays flat'' on a table without creasing the binding.
-
-In order to make the book lay flat properly, you need to ``crack'' the
-binding. To do this, divide the book into two sections and bend it so
-that the front and back covers meet. Do not worry; the pages are
-sewn and glued to the binding, and will not fall out easily.
-The outer cardboard binding itself is designed so that it will not
-break or crease as an ordinary paperback binding will. Bend the book
-several times in this manner, dividing it in a different place each
-time and pressing the pages flat and open. With use, the binding will
-become flexible and the pages will lay flat without needing to be
-pushed or held down.
-
-@page
-
-
-@tex
-\center {\secfonts \rm Notes}
-@end tex
-
-@bye
-
-@ignore
- arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/lists
-@node Lists, Sequences Arrays Vectors, Strings and Characters, Top
-@chapter Lists
-@cindex lists
-@cindex element (of list)
-
- A @dfn{list} represents a sequence of zero or more elements (which may
-be any Lisp objects). The important difference between lists and
-vectors is that two or more lists can share part of their structure; in
-addition, you can insert or delete elements in a list without copying
-the whole list.
-
-@menu
-* 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.
-@end menu
-
-@node Cons Cells
-@section Lists and Cons Cells
-@cindex lists and cons cells
-
- Lists in Lisp are not a primitive data type; they are built up from
-@dfn{cons cells}. A cons cell is a data object that represents an
-ordered pair. That is, it has two slots, and each slot @dfn{holds}, or
-@dfn{refers to}, some Lisp object. One slot is known as the @sc{car},
-and the other is known as the @sc{cdr}. (These names are traditional;
-see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.''
-
- We say that ``the @sc{car} of this cons cell is'' whatever object
-its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
-
- A list is a series of cons cells ``chained together,'' so that each
-cell refers to the next one. There is one cons cell for each element of
-the list. By convention, the @sc{car}s of the cons cells hold the
-elements of the list, and the @sc{cdr}s are used to chain the list: the
-@sc{cdr} slot of each cons cell refers to the following cons cell. The
-@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between
-the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
-level of cons cells, the @sc{car} and @sc{cdr} slots have the same
-characteristics.
-
-@cindex true list
- Since @code{nil} is the conventional value to put in the @sc{cdr} of
-the last cons cell in the list, we call that case a @dfn{true list}.
-
- In Lisp, we consider the symbol @code{nil} a list as well as a
-symbol; it is the list with no elements. For convenience, the symbol
-@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
-as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a
-true list.
-
-@cindex dotted list
-@cindex circular list
- If the @sc{cdr} of a list's last cons cell is some other value,
-neither @code{nil} nor another cons cell, we call the structure a
-@dfn{dotted list}, since its printed representation would use
-@samp{.}. There is one other possibility: some cons cell's @sc{cdr}
-could point to one of the previous cons cells in the list. We call
-that structure a @dfn{circular list}.
-
- For some purposes, it does not matter whether a list is true,
-circular or dotted. If the program doesn't look far enough down the
-list to see the @sc{cdr} of the final cons cell, it won't care.
-However, some functions that operate on lists demand true lists and
-signal errors if given a dotted list. Most functions that try to find
-the end of a list enter infinite loops if given a circular list.
-
-@cindex list structure
- Because most cons cells are used as part of lists, the phrase
-@dfn{list structure} has come to mean any structure made out of cons
-cells.
-
- The @sc{cdr} of any nonempty true list @var{l} is a list containing all the
-elements of @var{l} except the first.
-
- @xref{Cons Cell Type}, for the read and print syntax of cons cells and
-lists, and for ``box and arrow'' illustrations of lists.
-
-@node List-related Predicates
-@section Predicates on Lists
-
- The following predicates test whether a Lisp object is an atom,
-whether it is a cons cell or is a list, or whether it is the
-distinguished object @code{nil}. (Many of these predicates can be
-defined in terms of the others, but they are used so often that it is
-worth having all of them.)
-
-@defun consp object
-This function returns @code{t} if @var{object} is a cons cell, @code{nil}
-otherwise. @code{nil} is not a cons cell, although it @emph{is} a list.
-@end defun
-
-@defun atom object
-This function returns @code{t} if @var{object} is an atom, @code{nil}
-otherwise. All objects except cons cells are atoms. The symbol
-@code{nil} is an atom and is also a list; it is the only Lisp object
-that is both.
-
-@example
-(atom @var{object}) @equiv{} (not (consp @var{object}))
-@end example
-@end defun
-
-@defun listp object
-This function returns @code{t} if @var{object} is a cons cell or
-@code{nil}. Otherwise, it returns @code{nil}.
-
-@example
-@group
-(listp '(1))
- @result{} t
-@end group
-@group
-(listp '())
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun nlistp object
-This function is the opposite of @code{listp}: it returns @code{t} if
-@var{object} is not a list. Otherwise, it returns @code{nil}.
-
-@example
-(listp @var{object}) @equiv{} (not (nlistp @var{object}))
-@end example
-@end defun
-
-@defun null object
-This function returns @code{t} if @var{object} is @code{nil}, and
-returns @code{nil} otherwise. This function is identical to @code{not},
-but as a matter of clarity we use @code{null} when @var{object} is
-considered a list and @code{not} when it is considered a truth value
-(see @code{not} in @ref{Combining Conditions}).
-
-@example
-@group
-(null '(1))
- @result{} nil
-@end group
-@group
-(null '())
- @result{} t
-@end group
-@end example
-@end defun
-
-
-@node List Elements
-@section Accessing Elements of Lists
-@cindex list elements
-
-@defun car cons-cell
-This function returns the value referred to by the first slot of the
-cons cell @var{cons-cell}. Expressed another way, this function
-returns the @sc{car} of @var{cons-cell}.
-
-As a special case, if @var{cons-cell} is @code{nil}, then @code{car}
-is defined to return @code{nil}; therefore, any list is a valid argument
-for @code{car}. An error is signaled if the argument is not a cons cell
-or @code{nil}.
-
-@example
-@group
-(car '(a b c))
- @result{} a
-@end group
-@group
-(car '())
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun cdr cons-cell
-This function returns the value referred to by the second slot of
-the cons cell @var{cons-cell}. Expressed another way, this function
-returns the @sc{cdr} of @var{cons-cell}.
-
-As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr}
-is defined to return @code{nil}; therefore, any list is a valid argument
-for @code{cdr}. An error is signaled if the argument is not a cons cell
-or @code{nil}.
-
-@example
-@group
-(cdr '(a b c))
- @result{} (b c)
-@end group
-@group
-(cdr '())
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun car-safe object
-This function lets you take the @sc{car} of a cons cell while avoiding
-errors for other data types. It returns the @sc{car} of @var{object} if
-@var{object} is a cons cell, @code{nil} otherwise. This is in contrast
-to @code{car}, which signals an error if @var{object} is not a list.
-
-@example
-@group
-(car-safe @var{object})
-@equiv{}
-(let ((x @var{object}))
- (if (consp x)
- (car x)
- nil))
-@end group
-@end example
-@end defun
-
-@defun cdr-safe object
-This function lets you take the @sc{cdr} of a cons cell while
-avoiding errors for other data types. It returns the @sc{cdr} of
-@var{object} if @var{object} is a cons cell, @code{nil} otherwise.
-This is in contrast to @code{cdr}, which signals an error if
-@var{object} is not a list.
-
-@example
-@group
-(cdr-safe @var{object})
-@equiv{}
-(let ((x @var{object}))
- (if (consp x)
- (cdr x)
- nil))
-@end group
-@end example
-@end defun
-
-@defmac pop listname
-This macro is a way of examining the @sc{car} of a list,
-and taking it off the list, all at once.
-
-It operates on the list which is stored in the symbol @var{listname}.
-It removes this element from the list by setting @var{listname}
-to the @sc{cdr} of its old value---but it also returns the @sc{car}
-of that list, which is the element being removed.
-
-@example
-x
- @result{} (a b c)
-(pop x)
- @result{} a
-x
- @result{} (b c)
-@end example
-@end defmac
-
-@defun nth n list
-@anchor{Definition of nth}
-This function returns the @var{n}th element of @var{list}. Elements
-are numbered starting with zero, so the @sc{car} of @var{list} is
-element number zero. If the length of @var{list} is @var{n} or less,
-the value is @code{nil}.
-
-If @var{n} is negative, @code{nth} returns the first element of
-@var{list}.
-
-@example
-@group
-(nth 2 '(1 2 3 4))
- @result{} 3
-@end group
-@group
-(nth 10 '(1 2 3 4))
- @result{} nil
-@end group
-@group
-(nth -3 '(1 2 3 4))
- @result{} 1
-
-(nth n x) @equiv{} (car (nthcdr n x))
-@end group
-@end example
-
-The function @code{elt} is similar, but applies to any kind of sequence.
-For historical reasons, it takes its arguments in the opposite order.
-@xref{Sequence Functions}.
-@end defun
-
-@defun nthcdr n list
-This function returns the @var{n}th @sc{cdr} of @var{list}. In other
-words, it skips past the first @var{n} links of @var{list} and returns
-what follows.
-
-If @var{n} is zero or negative, @code{nthcdr} returns all of
-@var{list}. If the length of @var{list} is @var{n} or less,
-@code{nthcdr} returns @code{nil}.
-
-@example
-@group
-(nthcdr 1 '(1 2 3 4))
- @result{} (2 3 4)
-@end group
-@group
-(nthcdr 10 '(1 2 3 4))
- @result{} nil
-@end group
-@group
-(nthcdr -3 '(1 2 3 4))
- @result{} (1 2 3 4)
-@end group
-@end example
-@end defun
-
-@defun last list &optional n
-This function returns the last link of @var{list}. The @code{car} of
-this link is the list's last element. If @var{list} is null,
-@code{nil} is returned. If @var{n} is non-@code{nil}, the
-@var{n}th-to-last link is returned instead, or the whole of @var{list}
-if @var{n} is bigger than @var{list}'s length.
-@end defun
-
-@defun safe-length list
-@anchor{Definition of safe-length}
-This function returns the length of @var{list}, with no risk of either
-an error or an infinite loop. It generally returns the number of
-distinct cons cells in the list. However, for circular lists,
-the value is just an upper bound; it is often too large.
-
-If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
-returns 0.
-@end defun
-
- The most common way to compute the length of a list, when you are not
-worried that it may be circular, is with @code{length}. @xref{Sequence
-Functions}.
-
-@defun caar cons-cell
-This is the same as @code{(car (car @var{cons-cell}))}.
-@end defun
-
-@defun cadr cons-cell
-This is the same as @code{(car (cdr @var{cons-cell}))}
-or @code{(nth 1 @var{cons-cell})}.
-@end defun
-
-@defun cdar cons-cell
-This is the same as @code{(cdr (car @var{cons-cell}))}.
-@end defun
-
-@defun cddr cons-cell
-This is the same as @code{(cdr (cdr @var{cons-cell}))}
-or @code{(nthcdr 2 @var{cons-cell})}.
-@end defun
-
-@defun butlast x &optional n
-This function returns the list @var{x} with the last element,
-or the last @var{n} elements, removed. If @var{n} is greater
-than zero it makes a copy of the list so as not to damage the
-original list. In general, @code{(append (butlast @var{x} @var{n})
-(last @var{x} @var{n}))} will return a list equal to @var{x}.
-@end defun
-
-@defun nbutlast x &optional n
-This is a version of @code{butlast} that works by destructively
-modifying the @code{cdr} of the appropriate element, rather than
-making a copy of the list.
-@end defun
-
-@node Building Lists
-@comment node-name, next, previous, up
-@section Building Cons Cells and Lists
-@cindex cons cells
-@cindex building lists
-
- Many functions build lists, as lists reside at the very heart of Lisp.
-@code{cons} is the fundamental list-building function; however, it is
-interesting to note that @code{list} is used more times in the source
-code for Emacs than @code{cons}.
-
-@defun cons object1 object2
-This function is the most basic function for building new list
-structure. It creates a new cons cell, making @var{object1} the
-@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new
-cons cell. The arguments @var{object1} and @var{object2} may be any
-Lisp objects, but most often @var{object2} is a list.
-
-@example
-@group
-(cons 1 '(2))
- @result{} (1 2)
-@end group
-@group
-(cons 1 '())
- @result{} (1)
-@end group
-@group
-(cons 1 2)
- @result{} (1 . 2)
-@end group
-@end example
-
-@cindex consing
-@code{cons} is often used to add a single element to the front of a
-list. This is called @dfn{consing the element onto the list}.
-@footnote{There is no strictly equivalent way to add an element to
-the end of a list. You can use @code{(append @var{listname} (list
-@var{newelt}))}, which creates a whole new list by copying @var{listname}
-and adding @var{newelt} to its end. Or you can use @code{(nconc
-@var{listname} (list @var{newelt}))}, which modifies @var{listname}
-by following all the @sc{cdr}s and then replacing the terminating
-@code{nil}. Compare this to adding an element to the beginning of a
-list with @code{cons}, which neither copies nor modifies the list.}
-For example:
-
-@example
-(setq list (cons newelt list))
-@end example
-
-Note that there is no conflict between the variable named @code{list}
-used in this example and the function named @code{list} described below;
-any symbol can serve both purposes.
-@end defun
-
-@defun list &rest objects
-This function creates a list with @var{objects} as its elements. The
-resulting list is always @code{nil}-terminated. If no @var{objects}
-are given, the empty list is returned.
-
-@example
-@group
-(list 1 2 3 4 5)
- @result{} (1 2 3 4 5)
-@end group
-@group
-(list 1 2 '(3 4 5) 'foo)
- @result{} (1 2 (3 4 5) foo)
-@end group
-@group
-(list)
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun make-list length object
-This function creates a list of @var{length} elements, in which each
-element is @var{object}. Compare @code{make-list} with
-@code{make-string} (@pxref{Creating Strings}).
-
-@example
-@group
-(make-list 3 'pigs)
- @result{} (pigs pigs pigs)
-@end group
-@group
-(make-list 0 'pigs)
- @result{} nil
-@end group
-@group
-(setq l (make-list 3 '(a b))
- @result{} ((a b) (a b) (a b))
-(eq (car l) (cadr l))
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun append &rest sequences
-@cindex copying lists
-This function returns a list containing all the elements of
-@var{sequences}. The @var{sequences} may be lists, vectors,
-bool-vectors, or strings, but the last one should usually be a list.
-All arguments except the last one are copied, so none of the arguments
-is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
-lists with no copying.)
-
-More generally, the final argument to @code{append} may be any Lisp
-object. The final argument is not copied or converted; it becomes the
-@sc{cdr} of the last cons cell in the new list. If the final argument
-is itself a list, then its elements become in effect elements of the
-result list. If the final element is not a list, the result is a
-dotted list since its final @sc{cdr} is not @code{nil} as required
-in a true list.
-
-In Emacs 20 and before, the @code{append} function also allowed
-integers as (non last) arguments. It converted them to strings of
-digits, making up the decimal print representation of the integer, and
-then used the strings instead of the original integers. This obsolete
-usage no longer works. The proper way to convert an integer to a
-decimal number in this way is with @code{format} (@pxref{Formatting
-Strings}) or @code{number-to-string} (@pxref{String Conversion}).
-@end defun
-
- Here is an example of using @code{append}:
-
-@example
-@group
-(setq trees '(pine oak))
- @result{} (pine oak)
-(setq more-trees (append '(maple birch) trees))
- @result{} (maple birch pine oak)
-@end group
-
-@group
-trees
- @result{} (pine oak)
-more-trees
- @result{} (maple birch pine oak)
-@end group
-@group
-(eq trees (cdr (cdr more-trees)))
- @result{} t
-@end group
-@end example
-
- You can see how @code{append} works by looking at a box diagram. The
-variable @code{trees} is set to the list @code{(pine oak)} and then the
-variable @code{more-trees} is set to the list @code{(maple birch pine
-oak)}. However, the variable @code{trees} continues to refer to the
-original list:
-
-@smallexample
-@group
-more-trees trees
-| |
-| --- --- --- --- -> --- --- --- ---
- --> | | |--> | | |--> | | |--> | | |--> nil
- --- --- --- --- --- --- --- ---
- | | | |
- | | | |
- --> maple -->birch --> pine --> oak
-@end group
-@end smallexample
-
- An empty sequence contributes nothing to the value returned by
-@code{append}. As a consequence of this, a final @code{nil} argument
-forces a copy of the previous argument:
-
-@example
-@group
-trees
- @result{} (pine oak)
-@end group
-@group
-(setq wood (append trees nil))
- @result{} (pine oak)
-@end group
-@group
-wood
- @result{} (pine oak)
-@end group
-@group
-(eq wood trees)
- @result{} nil
-@end group
-@end example
-
-@noindent
-This once was the usual way to copy a list, before the function
-@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
-
- Here we show the use of vectors and strings as arguments to @code{append}:
-
-@example
-@group
-(append [a b] "cd" nil)
- @result{} (a b 99 100)
-@end group
-@end example
-
- With the help of @code{apply} (@pxref{Calling Functions}), we can append
-all the lists in a list of lists:
-
-@example
-@group
-(apply 'append '((a b c) nil (x y z) nil))
- @result{} (a b c x y z)
-@end group
-@end example
-
- If no @var{sequences} are given, @code{nil} is returned:
-
-@example
-@group
-(append)
- @result{} nil
-@end group
-@end example
-
- Here are some examples where the final argument is not a list:
-
-@example
-(append '(x y) 'z)
- @result{} (x y . z)
-(append '(x y) [z])
- @result{} (x y . [z])
-@end example
-
-@noindent
-The second example shows that when the final argument is a sequence but
-not a list, the sequence's elements do not become elements of the
-resulting list. Instead, the sequence becomes the final @sc{cdr}, like
-any other non-list final argument.
-
-@defun reverse list
-This function creates a new list whose elements are the elements of
-@var{list}, but in reverse order. The original argument @var{list} is
-@emph{not} altered.
-
-@example
-@group
-(setq x '(1 2 3 4))
- @result{} (1 2 3 4)
-@end group
-@group
-(reverse x)
- @result{} (4 3 2 1)
-x
- @result{} (1 2 3 4)
-@end group
-@end example
-@end defun
-
-@defun copy-tree tree &optional vecp
-This function returns a copy of the tree @code{tree}. If @var{tree} is a
-cons cell, this makes a new cons cell with the same @sc{car} and
-@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
-same way.
-
-Normally, when @var{tree} is anything other than a cons cell,
-@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is
-non-@code{nil}, it copies vectors too (and operates recursively on
-their elements).
-@end defun
-
-@defun number-sequence from &optional to separation
-This returns a list of numbers starting with @var{from} and
-incrementing by @var{separation}, and ending at or just before
-@var{to}. @var{separation} can be positive or negative and defaults
-to 1. If @var{to} is @code{nil} or numerically equal to @var{from},
-the value is the one-element list @code{(@var{from})}. If @var{to} is
-less than @var{from} with a positive @var{separation}, or greater than
-@var{from} with a negative @var{separation}, the value is @code{nil}
-because those arguments specify an empty sequence.
-
-If @var{separation} is 0 and @var{to} is neither @code{nil} nor
-numerically equal to @var{from}, @code{number-sequence} signals an
-error, since those arguments specify an infinite sequence.
-
-All arguments can be integers or floating point numbers. However,
-floating point arguments can be tricky, because floating point
-arithmetic is inexact. For instance, depending on the machine, it may
-quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
-the one element list @code{(0.4)}, whereas
-@code{(number-sequence 0.4 0.8 0.2)} returns a list with three
-elements. The @var{n}th element of the list is computed by the exact
-formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if
-one wants to make sure that @var{to} is included in the list, one can
-pass an expression of this exact type for @var{to}. Alternatively,
-one can replace @var{to} with a slightly larger value (or a slightly
-more negative value if @var{separation} is negative).
-
-Some examples:
-
-@example
-(number-sequence 4 9)
- @result{} (4 5 6 7 8 9)
-(number-sequence 9 4 -1)
- @result{} (9 8 7 6 5 4)
-(number-sequence 9 4 -2)
- @result{} (9 7 5)
-(number-sequence 8)
- @result{} (8)
-(number-sequence 8 5)
- @result{} nil
-(number-sequence 5 8 -1)
- @result{} nil
-(number-sequence 1.5 6 2)
- @result{} (1.5 3.5 5.5)
-@end example
-@end defun
-
-@node List Variables
-@section Modifying List Variables
-
- These functions, and one macro, provide convenient ways
-to modify a list which is stored in a variable.
-
-@defmac push newelt listname
-This macro provides an alternative way to write
-@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
-
-@example
-(setq l '(a b))
- @result{} (a b)
-(push 'c l)
- @result{} (c a b)
-l
- @result{} (c a b)
-@end example
-@end defmac
-
- Two functions modify lists that are the values of variables.
-
-@defun add-to-list symbol element &optional append compare-fn
-This function sets the variable @var{symbol} by consing @var{element}
-onto the old value, if @var{element} is not already a member of that
-value. It returns the resulting list, whether updated or not. The
-value of @var{symbol} had better be a list already before the call.
-@code{add-to-list} uses @var{compare-fn} to compare @var{element}
-against existing list members; if @var{compare-fn} is @code{nil}, it
-uses @code{equal}.
-
-Normally, if @var{element} is added, it is added to the front of
-@var{symbol}, but if the optional argument @var{append} is
-non-@code{nil}, it is added at the end.
-
-The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
-is an ordinary function, like @code{set} and unlike @code{setq}. Quote
-the argument yourself if that is what you want.
-@end defun
-
-Here's a scenario showing how to use @code{add-to-list}:
-
-@example
-(setq foo '(a b))
- @result{} (a b)
-
-(add-to-list 'foo 'c) ;; @r{Add @code{c}.}
- @result{} (c a b)
-
-(add-to-list 'foo 'b) ;; @r{No effect.}
- @result{} (c a b)
-
-foo ;; @r{@code{foo} was changed.}
- @result{} (c a b)
-@end example
-
- An equivalent expression for @code{(add-to-list '@var{var}
-@var{value})} is this:
-
-@example
-(or (member @var{value} @var{var})
- (setq @var{var} (cons @var{value} @var{var})))
-@end example
-
-@defun add-to-ordered-list symbol element &optional order
-This function sets the variable @var{symbol} by inserting
-@var{element} into the old value, which must be a list, at the
-position specified by @var{order}. If @var{element} is already a
-member of the list, its position in the list is adjusted according
-to @var{order}. Membership is tested using @code{eq}.
-This function returns the resulting list, whether updated or not.
-
-The @var{order} is typically a number (integer or float), and the
-elements of the list are sorted in non-decreasing numerical order.
-
-@var{order} may also be omitted or @code{nil}. Then the numeric order
-of @var{element} stays unchanged if it already has one; otherwise,
-@var{element} has no numeric order. Elements without a numeric list
-order are placed at the end of the list, in no particular order.
-
-Any other value for @var{order} removes the numeric order of @var{element}
-if it already has one; otherwise, it is equivalent to @code{nil}.
-
-The argument @var{symbol} is not implicitly quoted;
-@code{add-to-ordered-list} is an ordinary function, like @code{set}
-and unlike @code{setq}. Quote the argument yourself if that is what
-you want.
-
-The ordering information is stored in a hash table on @var{symbol}'s
-@code{list-order} property.
-@end defun
-
-Here's a scenario showing how to use @code{add-to-ordered-list}:
-
-@example
-(setq foo '())
- @result{} nil
-
-(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.}
- @result{} (a)
-
-(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.}
- @result{} (a c)
-
-(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.}
- @result{} (a b c)
-
-(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.}
- @result{} (a c b)
-
-(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
- @result{} (a c b d)
-
-(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
- @result{} (a c b e d)
-
-foo ;; @r{@code{foo} was changed.}
- @result{} (a c b e d)
-@end example
-
-@node Modifying Lists
-@section Modifying Existing List Structure
-@cindex destructive list operations
-
- You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
-primitives @code{setcar} and @code{setcdr}. We call these ``destructive''
-operations because they change existing list structure.
-
-@cindex CL note---@code{rplaca} vs @code{setcar}
-@quotation
-@findex rplaca
-@findex rplacd
-@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
-@code{rplacd} to alter list structure; they change structure the same
-way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
-return the cons cell while @code{setcar} and @code{setcdr} return the
-new @sc{car} or @sc{cdr}.
-@end quotation
-
-@menu
-* 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.
-@end menu
-
-@node Setcar
-@subsection Altering List Elements with @code{setcar}
-
- Changing the @sc{car} of a cons cell is done with @code{setcar}. When
-used on a list, @code{setcar} replaces one element of a list with a
-different element.
-
-@defun setcar cons object
-This function stores @var{object} as the new @sc{car} of @var{cons},
-replacing its previous @sc{car}. In other words, it changes the
-@sc{car} slot of @var{cons} to refer to @var{object}. It returns the
-value @var{object}. For example:
-
-@example
-@group
-(setq x '(1 2))
- @result{} (1 2)
-@end group
-@group
-(setcar x 4)
- @result{} 4
-@end group
-@group
-x
- @result{} (4 2)
-@end group
-@end example
-@end defun
-
- When a cons cell is part of the shared structure of several lists,
-storing a new @sc{car} into the cons changes one element of each of
-these lists. Here is an example:
-
-@example
-@group
-;; @r{Create two lists that are partly shared.}
-(setq x1 '(a b c))
- @result{} (a b c)
-(setq x2 (cons 'z (cdr x1)))
- @result{} (z b c)
-@end group
-
-@group
-;; @r{Replace the @sc{car} of a shared link.}
-(setcar (cdr x1) 'foo)
- @result{} foo
-x1 ; @r{Both lists are changed.}
- @result{} (a foo c)
-x2
- @result{} (z foo c)
-@end group
-
-@group
-;; @r{Replace the @sc{car} of a link that is not shared.}
-(setcar x1 'baz)
- @result{} baz
-x1 ; @r{Only one list is changed.}
- @result{} (baz foo c)
-x2
- @result{} (z foo c)
-@end group
-@end example
-
- Here is a graphical depiction of the shared structure of the two lists
-in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
-changes them both:
-
-@example
-@group
- --- --- --- --- --- ---
-x1---> | | |----> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | --> | |
- | | | |
- --> a | --> b --> c
- |
- --- --- |
-x2--> | | |--
- --- ---
- |
- |
- --> z
-@end group
-@end example
-
- Here is an alternative form of box diagram, showing the same relationship:
-
-@example
-@group
-x1:
- -------------- -------------- --------------
-| car | cdr | | car | cdr | | car | cdr |
-| a | o------->| b | o------->| c | nil |
-| | | -->| | | | | |
- -------------- | -------------- --------------
- |
-x2: |
- -------------- |
-| car | cdr | |
-| z | o----
-| | |
- --------------
-@end group
-@end example
-
-@node Setcdr
-@subsection Altering the CDR of a List
-
- The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
-
-@defun setcdr cons object
-This function stores @var{object} as the new @sc{cdr} of @var{cons},
-replacing its previous @sc{cdr}. In other words, it changes the
-@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
-value @var{object}.
-@end defun
-
- Here is an example of replacing the @sc{cdr} of a list with a
-different list. All but the first element of the list are removed in
-favor of a different sequence of elements. The first element is
-unchanged, because it resides in the @sc{car} of the list, and is not
-reached via the @sc{cdr}.
-
-@example
-@group
-(setq x '(1 2 3))
- @result{} (1 2 3)
-@end group
-@group
-(setcdr x '(4))
- @result{} (4)
-@end group
-@group
-x
- @result{} (1 4)
-@end group
-@end example
-
- You can delete elements from the middle of a list by altering the
-@sc{cdr}s of the cons cells in the list. For example, here we delete
-the second element, @code{b}, from the list @code{(a b c)}, by changing
-the @sc{cdr} of the first cons cell:
-
-@example
-@group
-(setq x1 '(a b c))
- @result{} (a b c)
-(setcdr x1 (cdr (cdr x1)))
- @result{} (c)
-x1
- @result{} (a c)
-@end group
-@end example
-
- Here is the result in box notation:
-
-@smallexample
-@group
- --------------------
- | |
- -------------- | -------------- | --------------
-| car | cdr | | | car | cdr | -->| car | cdr |
-| a | o----- | b | o-------->| c | nil |
-| | | | | | | | |
- -------------- -------------- --------------
-@end group
-@end smallexample
-
-@noindent
-The second cons cell, which previously held the element @code{b}, still
-exists and its @sc{car} is still @code{b}, but it no longer forms part
-of this list.
-
- It is equally easy to insert a new element by changing @sc{cdr}s:
-
-@example
-@group
-(setq x1 '(a b c))
- @result{} (a b c)
-(setcdr x1 (cons 'd (cdr x1)))
- @result{} (d b c)
-x1
- @result{} (a d b c)
-@end group
-@end example
-
- Here is this result in box notation:
-
-@smallexample
-@group
- -------------- ------------- -------------
-| car | cdr | | car | cdr | | car | cdr |
-| a | o | -->| b | o------->| c | nil |
-| | | | | | | | | | |
- --------- | -- | ------------- -------------
- | |
- ----- --------
- | |
- | --------------- |
- | | car | cdr | |
- -->| d | o------
- | | |
- ---------------
-@end group
-@end smallexample
-
-@node Rearrangement
-@subsection Functions that Rearrange Lists
-@cindex rearrangement of lists
-@cindex modification of lists
-
- Here are some functions that rearrange lists ``destructively'' by
-modifying the @sc{cdr}s of their component cons cells. We call these
-functions ``destructive'' because they chew up the original lists passed
-to them as arguments, relinking their cons cells to form a new list that
-is the returned value.
-
-@ifnottex
- See @code{delq}, in @ref{Sets And Lists}, for another function
-that modifies cons cells.
-@end ifnottex
-@iftex
- The function @code{delq} in the following section is another example
-of destructive list manipulation.
-@end iftex
-
-@defun nconc &rest lists
-@cindex concatenating lists
-@cindex joining lists
-This function returns a list containing all the elements of @var{lists}.
-Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
-@emph{not} copied. Instead, the last @sc{cdr} of each of the
-@var{lists} is changed to refer to the following list. The last of the
-@var{lists} is not altered. For example:
-
-@example
-@group
-(setq x '(1 2 3))
- @result{} (1 2 3)
-@end group
-@group
-(nconc x '(4 5))
- @result{} (1 2 3 4 5)
-@end group
-@group
-x
- @result{} (1 2 3 4 5)
-@end group
-@end example
-
- Since the last argument of @code{nconc} is not itself modified, it is
-reasonable to use a constant list, such as @code{'(4 5)}, as in the
-above example. For the same reason, the last argument need not be a
-list:
-
-@example
-@group
-(setq x '(1 2 3))
- @result{} (1 2 3)
-@end group
-@group
-(nconc x 'z)
- @result{} (1 2 3 . z)
-@end group
-@group
-x
- @result{} (1 2 3 . z)
-@end group
-@end example
-
-However, the other arguments (all but the last) must be lists.
-
-A common pitfall is to use a quoted constant list as a non-last
-argument to @code{nconc}. If you do this, your program will change
-each time you run it! Here is what happens:
-
-@smallexample
-@group
-(defun add-foo (x) ; @r{We want this function to add}
- (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.}
-@end group
-
-@group
-(symbol-function 'add-foo)
- @result{} (lambda (x) (nconc (quote (foo)) x))
-@end group
-
-@group
-(setq xx (add-foo '(1 2))) ; @r{It seems to work.}
- @result{} (foo 1 2)
-@end group
-@group
-(setq xy (add-foo '(3 4))) ; @r{What happened?}
- @result{} (foo 1 2 3 4)
-@end group
-@group
-(eq xx xy)
- @result{} t
-@end group
-
-@group
-(symbol-function 'add-foo)
- @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
-@end group
-@end smallexample
-@end defun
-
-@defun nreverse list
-@cindex reversing a list
- This function reverses the order of the elements of @var{list}.
-Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
-the @sc{cdr}s in the cons cells forming the list. The cons cell that
-used to be the last one in @var{list} becomes the first cons cell of the
-value.
-
- For example:
-
-@example
-@group
-(setq x '(a b c))
- @result{} (a b c)
-@end group
-@group
-x
- @result{} (a b c)
-(nreverse x)
- @result{} (c b a)
-@end group
-@group
-;; @r{The cons cell that was first is now last.}
-x
- @result{} (a)
-@end group
-@end example
-
- To avoid confusion, we usually store the result of @code{nreverse}
-back in the same variable which held the original list:
-
-@example
-(setq x (nreverse x))
-@end example
-
- Here is the @code{nreverse} of our favorite example, @code{(a b c)},
-presented graphically:
-
-@smallexample
-@group
-@r{Original list head:} @r{Reversed list:}
- ------------- ------------- ------------
-| car | cdr | | car | cdr | | car | cdr |
-| a | nil |<-- | b | o |<-- | c | o |
-| | | | | | | | | | | | |
- ------------- | --------- | - | -------- | -
- | | | |
- ------------- ------------
-@end group
-@end smallexample
-@end defun
-
-@defun sort list predicate
-@cindex stable sort
-@cindex sorting lists
-This function sorts @var{list} stably, though destructively, and
-returns the sorted list. It compares elements using @var{predicate}. A
-stable sort is one in which elements with equal sort keys maintain their
-relative order before and after the sort. Stability is important when
-successive sorts are used to order elements according to different
-criteria.
-
-The argument @var{predicate} must be a function that accepts two
-arguments. It is called with two elements of @var{list}. To get an
-increasing order sort, the @var{predicate} should return non-@code{nil} if the
-first element is ``less than'' the second, or @code{nil} if not.
-
-The comparison function @var{predicate} must give reliable results for
-any given pair of arguments, at least within a single call to
-@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
-less than @var{b}, @var{b} must not be less than @var{a}. It must be
-@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
-is less than @var{c}, then @var{a} must be less than @var{c}. If you
-use a comparison function which does not meet these requirements, the
-result of @code{sort} is unpredictable.
-
-The destructive aspect of @code{sort} is that it rearranges the cons
-cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
-function would create new cons cells to store the elements in their
-sorted order. If you wish to make a sorted copy without destroying the
-original, copy it first with @code{copy-sequence} and then sort.
-
-Sorting does not change the @sc{car}s of the cons cells in @var{list};
-the cons cell that originally contained the element @code{a} in
-@var{list} still has @code{a} in its @sc{car} after sorting, but it now
-appears in a different position in the list due to the change of
-@sc{cdr}s. For example:
-
-@example
-@group
-(setq nums '(1 3 2 6 5 4 0))
- @result{} (1 3 2 6 5 4 0)
-@end group
-@group
-(sort nums '<)
- @result{} (0 1 2 3 4 5 6)
-@end group
-@group
-nums
- @result{} (1 2 3 4 5 6)
-@end group
-@end example
-
-@noindent
-@strong{Warning}: Note that the list in @code{nums} no longer contains
-0; this is the same cons cell that it was before, but it is no longer
-the first one in the list. Don't assume a variable that formerly held
-the argument now holds the entire sorted list! Instead, save the result
-of @code{sort} and use that. Most often we store the result back into
-the variable that held the original list:
-
-@example
-(setq nums (sort nums '<))
-@end example
-
-@xref{Sorting}, for more functions that perform sorting.
-See @code{documentation} in @ref{Accessing Documentation}, for a
-useful example of @code{sort}.
-@end defun
-
-@node Sets And Lists
-@section Using Lists as Sets
-@cindex lists as sets
-@cindex sets
-
- A list can represent an unordered mathematical set---simply consider a
-value an element of a set if it appears in the list, and ignore the
-order of the list. To form the union of two sets, use @code{append} (as
-long as you don't mind having duplicate elements). You can remove
-@code{equal} duplicates using @code{delete-dups}. Other useful
-functions for sets include @code{memq} and @code{delq}, and their
-@code{equal} versions, @code{member} and @code{delete}.
-
-@cindex CL note---lack @code{union}, @code{intersection}
-@quotation
-@b{Common Lisp note:} Common Lisp has functions @code{union} (which
-avoids duplicate elements) and @code{intersection} for set operations,
-but GNU Emacs Lisp does not have them. You can write them in Lisp if
-you wish.
-@end quotation
-
-@defun memq object list
-@cindex membership in a list
-This function tests to see whether @var{object} is a member of
-@var{list}. If it is, @code{memq} returns a list starting with the
-first occurrence of @var{object}. Otherwise, it returns @code{nil}.
-The letter @samp{q} in @code{memq} says that it uses @code{eq} to
-compare @var{object} against the elements of the list. For example:
-
-@example
-@group
-(memq 'b '(a b c b a))
- @result{} (b c b a)
-@end group
-@group
-(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun delq object list
-@cindex deleting list elements
-This function destructively removes all elements @code{eq} to
-@var{object} from @var{list}. The letter @samp{q} in @code{delq} says
-that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq} and @code{remq}.
-@end defun
-
-When @code{delq} deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
-
-@example
-@group
-(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
-@end group
-@end example
-
-When an element to be deleted appears in the middle of the list,
-removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
-
-@example
-@group
-(setq sample-list '(a b c (4)))
- @result{} (a b c (4))
-@end group
-@group
-(delq 'a sample-list)
- @result{} (b c (4))
-@end group
-@group
-sample-list
- @result{} (a b c (4))
-@end group
-@group
-(delq 'c sample-list)
- @result{} (a b (4))
-@end group
-@group
-sample-list
- @result{} (a b (4))
-@end group
-@end example
-
-Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
-splice out the third element, but @code{(delq 'a sample-list)} does not
-splice anything---it just returns a shorter list. Don't assume that a
-variable which formerly held the argument @var{list} now has fewer
-elements, or that it still holds the original list! Instead, save the
-result of @code{delq} and use that. Most often we store the result back
-into the variable that held the original list:
-
-@example
-(setq flowers (delq 'rose flowers))
-@end example
-
-In the following example, the @code{(4)} that @code{delq} attempts to match
-and the @code{(4)} in the @code{sample-list} are not @code{eq}:
-
-@example
-@group
-(delq '(4) sample-list)
- @result{} (a c (4))
-@end group
-
-If you want to delete elements that are @code{equal} to a given value,
-use @code{delete} (see below).
-@end example
-
-@defun remq object list
-This function returns a copy of @var{list}, with all elements removed
-which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq}
-says that it uses @code{eq} to compare @var{object} against the elements
-of @code{list}.
-
-@example
-@group
-(setq sample-list '(a b c a b c))
- @result{} (a b c a b c)
-@end group
-@group
-(remq 'a sample-list)
- @result{} (b c b c)
-@end group
-@group
-sample-list
- @result{} (a b c a b c)
-@end group
-@end example
-@end defun
-
-@defun memql object list
-The function @code{memql} tests to see whether @var{object} is a member
-of @var{list}, comparing members with @var{object} using @code{eql},
-so floating point elements are compared by value.
-If @var{object} is a member, @code{memql} returns a list starting with
-its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
-
-Compare this with @code{memq}:
-
-@example
-@group
-(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
- @result{} (1.2 1.3)
-@end group
-@group
-(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
- @result{} nil
-@end group
-@end example
-@end defun
-
-The following three functions are like @code{memq}, @code{delq} and
-@code{remq}, but use @code{equal} rather than @code{eq} to compare
-elements. @xref{Equality Predicates}.
-
-@defun member object list
-The function @code{member} tests to see whether @var{object} is a member
-of @var{list}, comparing members with @var{object} using @code{equal}.
-If @var{object} is a member, @code{member} returns a list starting with
-its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
-
-Compare this with @code{memq}:
-
-@example
-@group
-(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
- @result{} ((2))
-@end group
-@group
-(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
- @result{} nil
-@end group
-@group
-;; @r{Two strings with the same contents are @code{equal}.}
-(member "foo" '("foo" "bar"))
- @result{} ("foo" "bar")
-@end group
-@end example
-@end defun
-
-@defun delete object sequence
-If @code{sequence} is a list, this function destructively removes all
-elements @code{equal} to @var{object} from @var{sequence}. For lists,
-@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
-uses @code{equal} to compare elements with @var{object}, like
-@code{member}; when it finds an element that matches, it cuts the
-element out just as @code{delq} would.
-
-If @code{sequence} is a vector or string, @code{delete} returns a copy
-of @code{sequence} with all elements @code{equal} to @code{object}
-removed.
-
-For example:
-
-@example
-@group
-(setq l '((2) (1) (2)))
-(delete '(2) l)
- @result{} ((1))
-l
- @result{} ((2) (1))
-;; @r{If you want to change @code{l} reliably,}
-;; @r{write @code{(setq l (delete elt l))}.}
-@end group
-@group
-(setq l '((2) (1) (2)))
-(delete '(1) l)
- @result{} ((2) (2))
-l
- @result{} ((2) (2))
-;; @r{In this case, it makes no difference whether you set @code{l},}
-;; @r{but you should do so for the sake of the other case.}
-@end group
-@group
-(delete '(2) [(2) (1) (2)])
- @result{} [(1)]
-@end group
-@end example
-@end defun
-
-@defun remove object sequence
-This function is the non-destructive counterpart of @code{delete}. It
-returns a copy of @code{sequence}, a list, vector, or string, with
-elements @code{equal} to @code{object} removed. For example:
-
-@example
-@group
-(remove '(2) '((2) (1) (2)))
- @result{} ((1))
-@end group
-@group
-(remove '(2) [(2) (1) (2)])
- @result{} [(1)]
-@end group
-@end example
-@end defun
-
-@quotation
-@b{Common Lisp note:} The functions @code{member}, @code{delete} and
-@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
-Lisp. The Common Lisp versions do not use @code{equal} to compare
-elements.
-@end quotation
-
-@defun member-ignore-case object list
-This function is like @code{member}, except that @var{object} should
-be a string and that it ignores differences in letter-case and text
-representation: upper-case and lower-case letters are treated as
-equal, and unibyte strings are converted to multibyte prior to
-comparison.
-@end defun
-
-@defun delete-dups list
-This function destructively removes all @code{equal} duplicates from
-@var{list}, stores the result in @var{list} and returns it. Of
-several @code{equal} occurrences of an element in @var{list},
-@code{delete-dups} keeps the first one.
-@end defun
-
- See also the function @code{add-to-list}, in @ref{List Variables},
-for a way to add an element to a list stored in a variable and used as a
-set.
-
-@node Association Lists
-@section Association Lists
-@cindex association list
-@cindex alist
-
- An @dfn{association list}, or @dfn{alist} for short, records a mapping
-from keys to values. It is a list of cons cells called
-@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
-@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
-is not related to the term ``key sequence''; it means a value used to
-look up an item in a table. In this case, the table is the alist, and
-the alist associations are the items.}
-
- Here is an example of an alist. The key @code{pine} is associated with
-the value @code{cones}; the key @code{oak} is associated with
-@code{acorns}; and the key @code{maple} is associated with @code{seeds}.
-
-@example
-@group
-((pine . cones)
- (oak . acorns)
- (maple . seeds))
-@end group
-@end example
-
- Both the values and the keys in an alist may be any Lisp objects.
-For example, in the following alist, the symbol @code{a} is
-associated with the number @code{1}, and the string @code{"b"} is
-associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
-the alist element:
-
-@example
-((a . 1) ("b" 2 3))
-@end example
-
- Sometimes it is better to design an alist to store the associated
-value in the @sc{car} of the @sc{cdr} of the element. Here is an
-example of such an alist:
-
-@example
-((rose red) (lily white) (buttercup yellow))
-@end example
-
-@noindent
-Here we regard @code{red} as the value associated with @code{rose}. One
-advantage of this kind of alist is that you can store other related
-information---even a list of other items---in the @sc{cdr} of the
-@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
-below) to find the element containing a given value. When neither of
-these considerations is important, the choice is a matter of taste, as
-long as you are consistent about it for any given alist.
-
- The same alist shown above could be regarded as having the
-associated value in the @sc{cdr} of the element; the value associated
-with @code{rose} would be the list @code{(red)}.
-
- Association lists are often used to record information that you might
-otherwise keep on a stack, since new associations may be added easily to
-the front of the list. When searching an association list for an
-association with a given key, the first one found is returned, if there
-is more than one.
-
- In Emacs Lisp, it is @emph{not} an error if an element of an
-association list is not a cons cell. The alist search functions simply
-ignore such elements. Many other versions of Lisp signal errors in such
-cases.
-
- Note that property lists are similar to association lists in several
-respects. A property list behaves like an association list in which
-each key can occur only once. @xref{Property Lists}, for a comparison
-of property lists and association lists.
-
-@defun assoc key alist
-This function returns the first association for @var{key} in
-@var{alist}, comparing @var{key} against the alist elements using
-@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no
-association in @var{alist} has a @sc{car} @code{equal} to @var{key}.
-For example:
-
-@smallexample
-(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- @result{} ((pine . cones) (oak . acorns) (maple . seeds))
-(assoc 'oak trees)
- @result{} (oak . acorns)
-(cdr (assoc 'oak trees))
- @result{} acorns
-(assoc 'birch trees)
- @result{} nil
-@end smallexample
-
-Here is another example, in which the keys and values are not symbols:
-
-@smallexample
-(setq needles-per-cluster
- '((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine")))
-
-(cdr (assoc 3 needles-per-cluster))
- @result{} ("Pitch Pine")
-(cdr (assoc 2 needles-per-cluster))
- @result{} ("Austrian Pine" "Red Pine")
-@end smallexample
-@end defun
-
- The function @code{assoc-string} is much like @code{assoc} except
-that it ignores certain differences between strings. @xref{Text
-Comparison}.
-
-@defun rassoc value alist
-This function returns the first association with value @var{value} in
-@var{alist}. It returns @code{nil} if no association in @var{alist} has
-a @sc{cdr} @code{equal} to @var{value}.
-
-@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
-each @var{alist} association instead of the @sc{car}. You can think of
-this as ``reverse @code{assoc},'' finding the key for a given value.
-@end defun
-
-@defun assq key alist
-This function is like @code{assoc} in that it returns the first
-association for @var{key} in @var{alist}, but it makes the comparison
-using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil}
-if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}.
-This function is used more often than @code{assoc}, since @code{eq} is
-faster than @code{equal} and most alists use symbols as keys.
-@xref{Equality Predicates}.
-
-@smallexample
-(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
- @result{} ((pine . cones) (oak . acorns) (maple . seeds))
-(assq 'pine trees)
- @result{} (pine . cones)
-@end smallexample
-
-On the other hand, @code{assq} is not usually useful in alists where the
-keys may not be symbols:
-
-@smallexample
-(setq leaves
- '(("simple leaves" . oak)
- ("compound leaves" . horsechestnut)))
-
-(assq "simple leaves" leaves)
- @result{} nil
-(assoc "simple leaves" leaves)
- @result{} ("simple leaves" . oak)
-@end smallexample
-@end defun
-
-@defun rassq value alist
-This function returns the first association with value @var{value} in
-@var{alist}. It returns @code{nil} if no association in @var{alist} has
-a @sc{cdr} @code{eq} to @var{value}.
-
-@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
-each @var{alist} association instead of the @sc{car}. You can think of
-this as ``reverse @code{assq},'' finding the key for a given value.
-
-For example:
-
-@smallexample
-(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-
-(rassq 'acorns trees)
- @result{} (oak . acorns)
-(rassq 'spores trees)
- @result{} nil
-@end smallexample
-
-@code{rassq} cannot search for a value stored in the @sc{car}
-of the @sc{cdr} of an element:
-
-@smallexample
-(setq colors '((rose red) (lily white) (buttercup yellow)))
-
-(rassq 'white colors)
- @result{} nil
-@end smallexample
-
-In this case, the @sc{cdr} of the association @code{(lily white)} is not
-the symbol @code{white}, but rather the list @code{(white)}. This
-becomes clearer if the association is written in dotted pair notation:
-
-@smallexample
-(lily white) @equiv{} (lily . (white))
-@end smallexample
-@end defun
-
-@defun assoc-default key alist &optional test default
-This function searches @var{alist} for a match for @var{key}. For each
-element of @var{alist}, it compares the element (if it is an atom) or
-the element's @sc{car} (if it is a cons) against @var{key}, by calling
-@var{test} with two arguments: the element or its @sc{car}, and
-@var{key}. The arguments are passed in that order so that you can get
-useful results using @code{string-match} with an alist that contains
-regular expressions (@pxref{Regexp Search}). If @var{test} is omitted
-or @code{nil}, @code{equal} is used for comparison.
-
-If an alist element matches @var{key} by this criterion,
-then @code{assoc-default} returns a value based on this element.
-If the element is a cons, then the value is the element's @sc{cdr}.
-Otherwise, the return value is @var{default}.
-
-If no alist element matches @var{key}, @code{assoc-default} returns
-@code{nil}.
-@end defun
-
-@defun copy-alist alist
-@cindex copying alists
-This function returns a two-level deep copy of @var{alist}: it creates a
-new copy of each association, so that you can alter the associations of
-the new alist without changing the old one.
-
-@smallexample
-@group
-(setq needles-per-cluster
- '((2 . ("Austrian Pine" "Red Pine"))
- (3 . ("Pitch Pine"))
-@end group
- (5 . ("White Pine"))))
-@result{}
-((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
-
-(setq copy (copy-alist needles-per-cluster))
-@result{}
-((2 "Austrian Pine" "Red Pine")
- (3 "Pitch Pine")
- (5 "White Pine"))
-
-(eq needles-per-cluster copy)
- @result{} nil
-(equal needles-per-cluster copy)
- @result{} t
-(eq (car needles-per-cluster) (car copy))
- @result{} nil
-(cdr (car (cdr needles-per-cluster)))
- @result{} ("Pitch Pine")
-@group
-(eq (cdr (car (cdr needles-per-cluster)))
- (cdr (car (cdr copy))))
- @result{} t
-@end group
-@end smallexample
-
- This example shows how @code{copy-alist} makes it possible to change
-the associations of one copy without affecting the other:
-
-@smallexample
-@group
-(setcdr (assq 3 copy) '("Martian Vacuum Pine"))
-(cdr (assq 3 needles-per-cluster))
- @result{} ("Pitch Pine")
-@end group
-@end smallexample
-@end defun
-
-@defun assq-delete-all key alist
-This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}, much as if you used @code{delq} to delete
-each such element one by one. It returns the shortened alist, and
-often modifies the original list structure of @var{alist}. For
-correct results, use the return value of @code{assq-delete-all} rather
-than looking at the saved value of @var{alist}.
-
-@example
-(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
- @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
-(assq-delete-all 'foo alist)
- @result{} ((bar 2) (lose 4))
-alist
- @result{} ((foo 1) (bar 2) (lose 4))
-@end example
-@end defun
-
-@defun rassq-delete-all value alist
-This function deletes from @var{alist} all the elements whose @sc{cdr}
-is @code{eq} to @var{value}. It returns the shortened alist, and
-often modifies the original list structure of @var{alist}.
-@code{rassq-delete-all} is like @code{assq-delete-all} except that it
-compares the @sc{cdr} of each @var{alist} association instead of the
-@sc{car}.
-@end defun
-
-@node Rings
-@section Managing a Fixed-Size Ring of Objects
-
-@cindex ring data structure
- This section describes functions for operating on rings. A
-@dfn{ring} is a fixed-size data structure that supports insertion,
-deletion, rotation, and modulo-indexed reference and traversal.
-
-@defun make-ring size
-This returns a new ring capable of holding @var{size} objects.
-@var{size} should be an integer.
-@end defun
-
-@defun ring-p object
-This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
-@end defun
-
-@defun ring-size ring
-This returns the maximum capacity of the @var{ring}.
-@end defun
-
-@defun ring-length ring
-This returns the number of objects that @var{ring} currently contains.
-The value will never exceed that returned by @code{ring-size}.
-@end defun
-
-@defun ring-elements ring
-This returns a list of the objects in @var{ring}, in order, newest first.
-@end defun
-
-@defun ring-copy ring
-This returns a new ring which is a copy of @var{ring}.
-The new ring contains the same (@code{eq}) objects as @var{ring}.
-@end defun
-
-@defun ring-empty-p ring
-This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
-@end defun
-
- The newest element in the ring always has index 0. Higher indices
-correspond to older elements. Indices are computed modulo the ring
-length. Index @minus{}1 corresponds to the oldest element, @minus{}2
-to the next-oldest, and so forth.
-
-@defun ring-ref ring index
-This returns the object in @var{ring} found at index @var{index}.
-@var{index} may be negative or greater than the ring length. If
-@var{ring} is empty, @code{ring-ref} signals an error.
-@end defun
-
-@defun ring-insert ring object
-This inserts @var{object} into @var{ring}, making it the newest
-element, and returns @var{object}.
-
-If the ring is full, insertion removes the oldest element to
-make room for the new element.
-@end defun
-
-@defun ring-remove ring &optional index
-Remove an object from @var{ring}, and return that object. The
-argument @var{index} specifies which item to remove; if it is
-@code{nil}, that means to remove the oldest item. If @var{ring} is
-empty, @code{ring-remove} signals an error.
-@end defun
-
-@defun ring-insert-at-beginning ring object
-This inserts @var{object} into @var{ring}, treating it as the oldest
-element. The return value is not significant.
-
-If the ring is full, this function removes the newest element to make
-room for the inserted element.
-@end defun
-
-@cindex fifo data structure
- If you are careful not to exceed the ring size, you can
-use the ring as a first-in-first-out queue. For example:
-
-@lisp
-(let ((fifo (make-ring 5)))
- (mapc (lambda (obj) (ring-insert fifo obj))
- '(0 one "two"))
- (list (ring-remove fifo) t
- (ring-remove fifo) t
- (ring-remove fifo)))
- @result{} (0 t one t "two")
-@end lisp
-
-@ignore
- arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/loading
-@node Loading, Byte Compilation, Customization, Top
-@chapter Loading
-@cindex loading
-@cindex library
-@cindex Lisp library
-
- Loading a file of Lisp code means bringing its contents into the Lisp
-environment in the form of Lisp objects. Emacs finds and opens the
-file, reads the text, evaluates each form, and then closes the file.
-
- The load functions evaluate all the expressions in a file just
-as the @code{eval-buffer} function evaluates all the
-expressions in a buffer. The difference is that the load functions
-read and evaluate the text in the file as found on disk, not the text
-in an Emacs buffer.
-
-@cindex top-level form
- The loaded file must contain Lisp expressions, either as source code
-or as byte-compiled code. Each form in the file is called a
-@dfn{top-level form}. There is no special format for the forms in a
-loadable file; any form in a file may equally well be typed directly
-into a buffer and evaluated there. (Indeed, most code is tested this
-way.) Most often, the forms are function definitions and variable
-definitions.
-
- A file containing Lisp code is often called a @dfn{library}. Thus,
-the ``Rmail library'' is a file containing code for Rmail mode.
-Similarly, a ``Lisp library directory'' is a directory of files
-containing Lisp code.
-
-@menu
-* 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.
-@end menu
-
-@node How Programs Do Loading
-@section How Programs Do Loading
-
- Emacs Lisp has several interfaces for loading. For example,
-@code{autoload} creates a placeholder object for a function defined in a
-file; trying to call the autoloading function loads the file to get the
-function's real definition (@pxref{Autoload}). @code{require} loads a
-file if it isn't already loaded (@pxref{Named Features}). Ultimately,
-all these facilities call the @code{load} function to do the work.
-
-@defun load filename &optional missing-ok nomessage nosuffix must-suffix
-This function finds and opens a file of Lisp code, evaluates all the
-forms in it, and closes the file.
-
-To find the file, @code{load} first looks for a file named
-@file{@var{filename}.elc}, that is, for a file whose name is
-@var{filename} with the extension @samp{.elc} appended. If such a
-file exists, it is loaded. If there is no file by that name, then
-@code{load} looks for a file named @file{@var{filename}.el}. If that
-file exists, it is loaded. Finally, if neither of those names is
-found, @code{load} looks for a file named @var{filename} with nothing
-appended, and loads it if it exists. (The @code{load} function is not
-clever about looking at @var{filename}. In the perverse case of a
-file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
-indeed find it.)
-
-If Auto Compression mode is enabled, as it is by default, then if
-@code{load} can not find a file, it searches for a compressed version
-of the file before trying other file names. It decompresses and loads
-it if it exists. It looks for compressed versions by appending each
-of the suffixes in @code{jka-compr-load-suffixes} to the file name.
-The value of this variable must be a list of strings. Its standard
-value is @code{(".gz")}.
-
-If the optional argument @var{nosuffix} is non-@code{nil}, then
-@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
-this case, you must specify the precise file name you want, except
-that, if Auto Compression mode is enabled, @code{load} will still use
-@code{jka-compr-load-suffixes} to find compressed versions. By
-specifying the precise file name and using @code{t} for
-@var{nosuffix}, you can prevent perverse file names such as
-@file{foo.el.el} from being tried.
-
-If the optional argument @var{must-suffix} is non-@code{nil}, then
-@code{load} insists that the file name used must end in either
-@samp{.el} or @samp{.elc} (possibly extended with a compression
-suffix), unless it contains an explicit directory name.
-
-If @var{filename} is a relative file name, such as @file{foo} or
-@file{baz/foo.bar}, @code{load} searches for the file using the variable
-@code{load-path}. It appends @var{filename} to each of the directories
-listed in @code{load-path}, and loads the first file it finds whose name
-matches. The current default directory is tried only if it is specified
-in @code{load-path}, where @code{nil} stands for the default directory.
-@code{load} tries all three possible suffixes in the first directory in
-@code{load-path}, then all three suffixes in the second directory, and
-so on. @xref{Library Search}.
-
-If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
-means you should consider recompiling @file{foo.el}. @xref{Byte
-Compilation}.
-
-When loading a source file (not compiled), @code{load} performs
-character set translation just as Emacs would do when visiting the file.
-@xref{Coding Systems}.
-
-Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
-in the echo area during loading unless @var{nomessage} is
-non-@code{nil}.
-
-@cindex load errors
-Any unhandled errors while loading a file terminate loading. If the
-load was done for the sake of @code{autoload}, any function definitions
-made during the loading are undone.
-
-@kindex file-error
-If @code{load} can't find the file to load, then normally it signals the
-error @code{file-error} (with @samp{Cannot open load file
-@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
-@code{load} just returns @code{nil}.
-
-You can use the variable @code{load-read-function} to specify a function
-for @code{load} to use instead of @code{read} for reading expressions.
-See below.
-
-@code{load} returns @code{t} if the file loads successfully.
-@end defun
-
-@deffn Command load-file filename
-This command loads the file @var{filename}. If @var{filename} is a
-relative file name, then the current default directory is assumed.
-This command does not use @code{load-path}, and does not append
-suffixes. However, it does look for compressed versions (if Auto
-Compression Mode is enabled). Use this command if you wish to specify
-precisely the file name to load.
-@end deffn
-
-@deffn Command load-library library
-This command loads the library named @var{library}. It is equivalent to
-@code{load}, except in how it reads its argument interactively.
-@end deffn
-
-@defvar load-in-progress
-This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise.
-@end defvar
-
-@defvar load-read-function
-@anchor{Definition of load-read-function}
-@c do not allow page break at anchor; work around Texinfo deficiency.
-This variable specifies an alternate expression-reading function for
-@code{load} and @code{eval-region} to use instead of @code{read}.
-The function should accept one argument, just as @code{read} does.
-
-Normally, the variable's value is @code{nil}, which means those
-functions should use @code{read}.
-
-Instead of using this variable, it is cleaner to use another, newer
-feature: to pass the function as the @var{read-function} argument to
-@code{eval-region}. @xref{Definition of eval-region,, Eval}.
-@end defvar
-
- For information about how @code{load} is used in building Emacs, see
-@ref{Building Emacs}.
-
-@node Load Suffixes
-@section Load Suffixes
-We now describe some technical details about the exact suffixes that
-@code{load} tries.
-
-@defvar load-suffixes
-This is a list of suffixes indicating (compiled or source) Emacs Lisp
-files. It should not include the empty string. @code{load} uses
-these suffixes in order when it appends Lisp suffixes to the specified
-file name. The standard value is @code{(".elc" ".el")} which produces
-the behavior described in the previous section.
-@end defvar
-
-@defvar load-file-rep-suffixes
-This is a list of suffixes that indicate representations of the same
-file. This list should normally start with the empty string.
-When @code{load} searches for a file it appends the suffixes in this
-list, in order, to the file name, before searching for another file.
-
-Enabling Auto Compression mode appends the suffixes in
-@code{jka-compr-load-suffixes} to this list and disabling Auto
-Compression mode removes them again. The standard value of
-@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
-@code{("")}. Given that the standard value of
-@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
-of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
-is @code{("" ".gz")}.
-@end defvar
-
-@defun get-load-suffixes
-This function returns the list of all suffixes that @code{load} should
-try, in order, when its @var{must-suffix} argument is non-@code{nil}.
-This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
-into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
-and @code{load-file-rep-suffixes} all have their standard values, this
-function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
-Compression mode is enabled and @code{(".elc" ".el")} if Auto
-Compression mode is disabled.
-@end defun
-
-To summarize, @code{load} normally first tries the suffixes in the
-value of @code{(get-load-suffixes)} and then those in
-@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
-it skips the former group, and if @var{must-suffix} is non-@code{nil},
-it skips the latter group.
-
-@node Library Search
-@section Library Search
-@cindex library search
-@cindex find library
-
- When Emacs loads a Lisp library, it searches for the library
-in a list of directories specified by the variable @code{load-path}.
-
-@defopt load-path
-@cindex @code{EMACSLOADPATH} environment variable
-The value of this variable is a list of directories to search when
-loading files with @code{load}. Each element is a string (which must be
-a directory name) or @code{nil} (which stands for the current working
-directory).
-@end defopt
-
- The value of @code{load-path} is initialized from the environment
-variable @code{EMACSLOADPATH}, if that exists; otherwise its default
-value is specified in @file{emacs/src/epaths.h} when Emacs is built.
-Then the list is expanded by adding subdirectories of the directories
-in the list.
-
- The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
-@samp{:} (or @samp{;}, according to the operating system) separates
-directory names, and @samp{.} is used for the current default directory.
-Here is an example of how to set your @code{EMACSLOADPATH} variable from
-a @code{csh} @file{.login} file:
-
-@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
-@end smallexample
-
- Here is how to set it using @code{sh}:
-
-@smallexample
-export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
-@end smallexample
-
- Here is an example of code you can place in your init file (@pxref{Init
-File}) to add several directories to the front of your default
-@code{load-path}:
-
-@smallexample
-@group
-(setq load-path
- (append (list nil "/user/bil/emacs"
- "/usr/local/lisplib"
- "~/emacs")
- load-path))
-@end group
-@end smallexample
-
-@c Wordy to rid us of an overfull hbox. --rjc 15mar92
-@noindent
-In this example, the path searches the current working directory first,
-followed then by the @file{/user/bil/emacs} directory, the
-@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
-which are then followed by the standard directories for Lisp code.
-
- Dumping Emacs uses a special value of @code{load-path}. If the value of
-@code{load-path} at the end of dumping is unchanged (that is, still the
-same special value), the dumped Emacs switches to the ordinary
-@code{load-path} value when it starts up, as described above. But if
-@code{load-path} has any other value at the end of dumping, that value
-is used for execution of the dumped Emacs also.
-
- Therefore, if you want to change @code{load-path} temporarily for
-loading a few libraries in @file{site-init.el} or @file{site-load.el},
-you should bind @code{load-path} locally with @code{let} around the
-calls to @code{load}.
-
- The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, includes two special directories (and
-their subdirectories as well):
-
-@smallexample
-"/usr/local/share/emacs/@var{version}/site-lisp"
-@end smallexample
-
-@noindent
-and
-
-@smallexample
-"/usr/local/share/emacs/site-lisp"
-@end smallexample
-
-@noindent
-The first one is for locally installed packages for a particular Emacs
-version; the second is for locally installed packages meant for use with
-all installed Emacs versions.
-
- There are several reasons why a Lisp package that works well in one
-Emacs version can cause trouble in another. Sometimes packages need
-updating for incompatible changes in Emacs; sometimes they depend on
-undocumented internal Emacs data that can change without notice;
-sometimes a newer Emacs version incorporates a version of the package,
-and should be used only with that version.
-
- Emacs finds these directories' subdirectories and adds them to
-@code{load-path} when it starts up. Both immediate subdirectories and
-subdirectories multiple levels down are added to @code{load-path}.
-
- Not all subdirectories are included, though. Subdirectories whose
-names do not start with a letter or digit are excluded. Subdirectories
-named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
-contains a file named @file{.nosearch} is excluded. You can use these
-methods to prevent certain subdirectories of the @file{site-lisp}
-directories from being searched.
-
- If you run Emacs from the directory where it was built---that is, an
-executable that has not been formally installed---then @code{load-path}
-normally contains two additional directories. These are the @code{lisp}
-and @code{site-lisp} subdirectories of the main build directory. (Both
-are represented as absolute file names.)
-
-@deffn Command locate-library library &optional nosuffix path interactive-call
-This command finds the precise file name for library @var{library}. It
-searches for the library in the same way @code{load} does, and the
-argument @var{nosuffix} has the same meaning as in @code{load}: don't
-add suffixes @samp{.elc} or @samp{.el} to the specified name
-@var{library}.
-
-If the @var{path} is non-@code{nil}, that list of directories is used
-instead of @code{load-path}.
-
-When @code{locate-library} is called from a program, it returns the file
-name as a string. When the user runs @code{locate-library}
-interactively, the argument @var{interactive-call} is @code{t}, and this
-tells @code{locate-library} to display the file name in the echo area.
-@end deffn
-
-@node Loading Non-ASCII
-@section Loading Non-@acronym{ASCII} Characters
-
- When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
-characters, these can be represented within Emacs either as unibyte
-strings or as multibyte strings (@pxref{Text Representations}). Which
-representation is used depends on how the file is read into Emacs. If
-it is read with decoding into multibyte representation, the text of the
-Lisp program will be multibyte text, and its string constants will be
-multibyte strings. If a file containing Latin-1 characters (for
-example) is read without decoding, the text of the program will be
-unibyte text, and its string constants will be unibyte strings.
-@xref{Coding Systems}.
-
- To make the results more predictable, Emacs always performs decoding
-into the multibyte representation when loading Lisp files, even if it
-was started with the @samp{--unibyte} option. This means that string
-constants with non-@acronym{ASCII} characters translate into multibyte
-strings. The only exception is when a particular file specifies no
-decoding.
-
- The reason Emacs is designed this way is so that Lisp programs give
-predictable results, regardless of how Emacs was started. In addition,
-this enables programs that depend on using multibyte text to work even
-in a unibyte Emacs. Of course, such programs should be designed to
-notice whether the user prefers unibyte or multibyte text, by checking
-@code{default-enable-multibyte-characters}, and convert representations
-appropriately.
-
- In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
-multibyte strings should not be noticeable, since inserting them in
-unibyte buffers converts them to unibyte automatically. However, if
-this does make a difference, you can force a particular Lisp file to be
-interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
-comment on the file's first line. With that designator, the file will
-unconditionally be interpreted as unibyte, even in an ordinary
-multibyte Emacs session. This can matter when making keybindings to
-non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
-
-@node Autoload
-@section Autoload
-@cindex autoload
-
- The @dfn{autoload} facility allows you to make a function or macro
-known in Lisp, but put off loading the file that defines it. The first
-call to the function automatically reads the proper file to install the
-real definition and other associated code, then runs the real definition
-as if it had been loaded all along.
-
- There are two ways to set up an autoloaded function: by calling
-@code{autoload}, and by writing a special ``magic'' comment in the
-source before the real definition. @code{autoload} is the low-level
-primitive for autoloading; any Lisp program can call @code{autoload} at
-any time. Magic comments are the most convenient way to make a function
-autoload, for packages installed along with Emacs. These comments do
-nothing on their own, but they serve as a guide for the command
-@code{update-file-autoloads}, which constructs calls to @code{autoload}
-and arranges to execute them when Emacs is built.
-
-@defun autoload function filename &optional docstring interactive type
-This function defines the function (or macro) named @var{function} so as
-to load automatically from @var{filename}. The string @var{filename}
-specifies the file to load to get the real definition of @var{function}.
-
-If @var{filename} does not contain either a directory name, or the
-suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
-one of these suffixes, and it will not load from a file whose name is
-just @var{filename} with no added suffix. (The variable
-@code{load-suffixes} specifies the exact required suffixes.)
-
-The argument @var{docstring} is the documentation string for the
-function. Specifying the documentation string in the call to
-@code{autoload} makes it possible to look at the documentation without
-loading the function's real definition. Normally, this should be
-identical to the documentation string in the function definition
-itself. If it isn't, the function definition's documentation string
-takes effect when it is loaded.
-
-If @var{interactive} is non-@code{nil}, that says @var{function} can be
-called interactively. This lets completion in @kbd{M-x} work without
-loading @var{function}'s real definition. The complete interactive
-specification is not given here; it's not needed unless the user
-actually calls @var{function}, and when that happens, it's time to load
-the real definition.
-
-You can autoload macros and keymaps as well as ordinary functions.
-Specify @var{type} as @code{macro} if @var{function} is really a macro.
-Specify @var{type} as @code{keymap} if @var{function} is really a
-keymap. Various parts of Emacs need to know this information without
-loading the real definition.
-
-An autoloaded keymap loads automatically during key lookup when a prefix
-key's binding is the symbol @var{function}. Autoloading does not occur
-for other kinds of access to the keymap. In particular, it does not
-happen when a Lisp program gets the keymap from the value of a variable
-and calls @code{define-key}; not even if the variable name is the same
-symbol @var{function}.
-
-@cindex function cell in autoload
-If @var{function} already has a non-void function definition that is not
-an autoload object, @code{autoload} does nothing and returns @code{nil}.
-If the function cell of @var{function} is void, or is already an autoload
-object, then it is defined as an autoload object like this:
-
-@example
-(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
-@end example
-
-For example,
-
-@example
-@group
-(symbol-function 'run-prolog)
- @result{} (autoload "prolog" 169681 t nil)
-@end group
-@end example
-
-@noindent
-In this case, @code{"prolog"} is the name of the file to load, 169681
-refers to the documentation string in the
-@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
-@code{t} means the function is interactive, and @code{nil} that it is
-not a macro or a keymap.
-@end defun
-
-@cindex autoload errors
- The autoloaded file usually contains other definitions and may require
-or provide one or more features. If the file is not completely loaded
-(due to an error in the evaluation of its contents), any function
-definitions or @code{provide} calls that occurred during the load are
-undone. This is to ensure that the next attempt to call any function
-autoloading from this file will try again to load the file. If not for
-this, then some of the functions in the file might be defined by the
-aborted load, but fail to work properly for the lack of certain
-subroutines not loaded successfully because they come later in the file.
-
- If the autoloaded file fails to define the desired Lisp function or
-macro, then an error is signaled with data @code{"Autoloading failed to
-define function @var{function-name}"}.
-
-@findex update-file-autoloads
-@findex update-directory-autoloads
-@cindex magic autoload comment
-@cindex autoload cookie
-@anchor{autoload cookie}
- A magic autoload comment (often called an @dfn{autoload cookie})
-consists of @samp{;;;###autoload}, on a line by itself,
-just before the real definition of the function in its
-autoloadable source file. The command @kbd{M-x update-file-autoloads}
-writes a corresponding @code{autoload} call into @file{loaddefs.el}.
-Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
-@kbd{M-x update-directory-autoloads} is even more powerful; it updates
-autoloads for all files in the current directory.
-
- The same magic comment can copy any kind of form into
-@file{loaddefs.el}. If the form following the magic comment is not a
-function-defining form or a @code{defcustom} form, it is copied
-verbatim. ``Function-defining forms'' include @code{define-skeleton},
-@code{define-derived-mode}, @code{define-generic-mode} and
-@code{define-minor-mode} as well as @code{defun} and
-@code{defmacro}. To save space, a @code{defcustom} form is converted to
-a @code{defvar} in @file{loaddefs.el}, with some additional information
-if it uses @code{:require}.
-
- You can also use a magic comment to execute a form at build time
-@emph{without} executing it when the file itself is loaded. To do this,
-write the form @emph{on the same line} as the magic comment. Since it
-is in a comment, it does nothing when you load the source file; but
-@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
-it is executed while building Emacs.
-
- The following example shows how @code{doctor} is prepared for
-autoloading with a magic comment:
-
-@smallexample
-;;;###autoload
-(defun doctor ()
- "Switch to *doctor* buffer and start giving psychotherapy."
- (interactive)
- (switch-to-buffer "*doctor*")
- (doctor-mode))
-@end smallexample
-
-@noindent
-Here's what that produces in @file{loaddefs.el}:
-
-@smallexample
-(autoload (quote doctor) "doctor" "\
-Switch to *doctor* buffer and start giving psychotherapy.
-
-\(fn)" t nil)
-@end smallexample
-
-@noindent
-@cindex @code{fn} in function's documentation string
-The backslash and newline immediately following the double-quote are a
-convention used only in the preloaded uncompiled Lisp files such as
-@file{loaddefs.el}; they tell @code{make-docfile} to put the
-documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
-See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
-in the usage part of the documentation string is replaced with the
-function's name when the various help functions (@pxref{Help
-Functions}) display it.
-
- If you write a function definition with an unusual macro that is not
-one of the known and recognized function definition methods, use of an
-ordinary magic autoload comment would copy the whole definition into
-@code{loaddefs.el}. That is not desirable. You can put the desired
-@code{autoload} call into @code{loaddefs.el} instead by writing this:
-
-@smallexample
-;;;###autoload (autoload 'foo "myfile")
-(mydefunmacro foo
- ...)
-@end smallexample
-
-@node Repeated Loading
-@section Repeated Loading
-@cindex repeated loading
-
- You can load a given file more than once in an Emacs session. For
-example, after you have rewritten and reinstalled a function definition
-by editing it in a buffer, you may wish to return to the original
-version; you can do this by reloading the file it came from.
-
- When you load or reload files, bear in mind that the @code{load} and
-@code{load-library} functions automatically load a byte-compiled file
-rather than a non-compiled file of similar name. If you rewrite a file
-that you intend to save and reinstall, you need to byte-compile the new
-version; otherwise Emacs will load the older, byte-compiled file instead
-of your newer, non-compiled file! If that happens, the message
-displayed when loading the file includes, @samp{(compiled; note, source is
-newer)}, to remind you to recompile it.
-
- When writing the forms in a Lisp library file, keep in mind that the
-file might be loaded more than once. For example, think about whether
-each variable should be reinitialized when you reload the library;
-@code{defvar} does not change the value if the variable is already
-initialized. (@xref{Defining Variables}.)
-
- The simplest way to add an element to an alist is like this:
-
-@example
-(push '(leif-mode " Leif") minor-mode-alist)
-@end example
-
-@noindent
-But this would add multiple elements if the library is reloaded.
-To avoid the problem, write this:
-
-@example
-(or (assq 'leif-mode minor-mode-alist)
- (push '(leif-mode " Leif") minor-mode-alist))
-@end example
-
-@noindent
-or this:
-
-@example
-(add-to-list '(leif-mode " Leif") minor-mode-alist)
-@end example
-
- Occasionally you will want to test explicitly whether a library has
-already been loaded. Here's one way to test, in a library, whether it
-has been loaded before:
-
-@example
-(defvar foo-was-loaded nil)
-
-(unless foo-was-loaded
- @var{execute-first-time-only}
- (setq foo-was-loaded t))
-@end example
-
-@noindent
-If the library uses @code{provide} to provide a named feature, you can
-use @code{featurep} earlier in the file to test whether the
-@code{provide} call has been executed before.
-@ifnottex
-@xref{Named Features}.
-@end ifnottex
-
-@node Named Features
-@section Features
-@cindex features
-@cindex requiring features
-@cindex providing features
-
- @code{provide} and @code{require} are an alternative to
-@code{autoload} for loading files automatically. They work in terms of
-named @dfn{features}. Autoloading is triggered by calling a specific
-function, but a feature is loaded the first time another program asks
-for it by name.
-
- A feature name is a symbol that stands for a collection of functions,
-variables, etc. The file that defines them should @dfn{provide} the
-feature. Another program that uses them may ensure they are defined by
-@dfn{requiring} the feature. This loads the file of definitions if it
-hasn't been loaded already.
-
- To require the presence of a feature, call @code{require} with the
-feature name as argument. @code{require} looks in the global variable
-@code{features} to see whether the desired feature has been provided
-already. If not, it loads the feature from the appropriate file. This
-file should call @code{provide} at the top level to add the feature to
-@code{features}; if it fails to do so, @code{require} signals an error.
-@cindex load error with require
-
- For example, in @file{emacs/lisp/prolog.el},
-the definition for @code{run-prolog} includes the following code:
-
-@smallexample
-(defun run-prolog ()
- "Run an inferior Prolog process, with I/O via buffer *prolog*."
- (interactive)
- (require 'comint)
- (switch-to-buffer (make-comint "prolog" prolog-program-name))
- (inferior-prolog-mode))
-@end smallexample
-
-@noindent
-The expression @code{(require 'comint)} loads the file @file{comint.el}
-if it has not yet been loaded. This ensures that @code{make-comint} is
-defined. Features are normally named after the files that provide them,
-so that @code{require} need not be given the file name.
-
-The @file{comint.el} file contains the following top-level expression:
-
-@smallexample
-(provide 'comint)
-@end smallexample
-
-@noindent
-This adds @code{comint} to the global @code{features} list, so that
-@code{(require 'comint)} will henceforth know that nothing needs to be
-done.
-
-@cindex byte-compiling @code{require}
- When @code{require} is used at top level in a file, it takes effect
-when you byte-compile that file (@pxref{Byte Compilation}) as well as
-when you load it. This is in case the required package contains macros
-that the byte compiler must know about. It also avoids byte-compiler
-warnings for functions and variables defined in the file loaded with
-@code{require}.
-
- Although top-level calls to @code{require} are evaluated during
-byte compilation, @code{provide} calls are not. Therefore, you can
-ensure that a file of definitions is loaded before it is byte-compiled
-by including a @code{provide} followed by a @code{require} for the same
-feature, as in the following example.
-
-@smallexample
-@group
-(provide 'my-feature) ; @r{Ignored by byte compiler,}
- ; @r{evaluated by @code{load}.}
-(require 'my-feature) ; @r{Evaluated by byte compiler.}
-@end group
-@end smallexample
-
-@noindent
-The compiler ignores the @code{provide}, then processes the
-@code{require} by loading the file in question. Loading the file does
-execute the @code{provide} call, so the subsequent @code{require} call
-does nothing when the file is loaded.
-
-@defun provide feature &optional subfeatures
-This function announces that @var{feature} is now loaded, or being
-loaded, into the current Emacs session. This means that the facilities
-associated with @var{feature} are or will be available for other Lisp
-programs.
-
-The direct effect of calling @code{provide} is to add @var{feature} to
-the front of the list @code{features} if it is not already in the list.
-The argument @var{feature} must be a symbol. @code{provide} returns
-@var{feature}.
-
-If provided, @var{subfeatures} should be a list of symbols indicating
-a set of specific subfeatures provided by this version of
-@var{feature}. You can test the presence of a subfeature using
-@code{featurep}. The idea of subfeatures is that you use them when a
-package (which is one @var{feature}) is complex enough to make it
-useful to give names to various parts or functionalities of the
-package, which might or might not be loaded, or might or might not be
-present in a given version. @xref{Network Feature Testing}, for
-an example.
-
-@smallexample
-features
- @result{} (bar bish)
-
-(provide 'foo)
- @result{} foo
-features
- @result{} (foo bar bish)
-@end smallexample
-
-When a file is loaded to satisfy an autoload, and it stops due to an
-error in the evaluation of its contents, any function definitions or
-@code{provide} calls that occurred during the load are undone.
-@xref{Autoload}.
-@end defun
-
-@defun require feature &optional filename noerror
-This function checks whether @var{feature} is present in the current
-Emacs session (using @code{(featurep @var{feature})}; see below). The
-argument @var{feature} must be a symbol.
-
-If the feature is not present, then @code{require} loads @var{filename}
-with @code{load}. If @var{filename} is not supplied, then the name of
-the symbol @var{feature} is used as the base file name to load.
-However, in this case, @code{require} insists on finding @var{feature}
-with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
-a compression suffix); a file whose name is just @var{feature} won't
-be used. (The variable @code{load-suffixes} specifies the exact
-required Lisp suffixes.)
-
-If @var{noerror} is non-@code{nil}, that suppresses errors from actual
-loading of the file. In that case, @code{require} returns @code{nil}
-if loading the file fails. Normally, @code{require} returns
-@var{feature}.
-
-If loading the file succeeds but does not provide @var{feature},
-@code{require} signals an error, @samp{Required feature @var{feature}
-was not provided}.
-@end defun
-
-@defun featurep feature &optional subfeature
-This function returns @code{t} if @var{feature} has been provided in
-the current Emacs session (i.e.@:, if @var{feature} is a member of
-@code{features}.) If @var{subfeature} is non-@code{nil}, then the
-function returns @code{t} only if that subfeature is provided as well
-(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
-property of the @var{feature} symbol.)
-@end defun
-
-@defvar features
-The value of this variable is a list of symbols that are the features
-loaded in the current Emacs session. Each symbol was put in this list
-with a call to @code{provide}. The order of the elements in the
-@code{features} list is not significant.
-@end defvar
-
-@node Where Defined
-@section Which File Defined a Certain Symbol
-
-@defun symbol-file symbol &optional type
-This function returns the name of the file that defined @var{symbol}.
-If @var{type} is @code{nil}, then any kind of definition is
-acceptable. If @var{type} is @code{defun} or @code{defvar}, that
-specifies function definition only or variable definition only.
-
-The value is normally an absolute file name. It can also be
-@code{nil}, if the definition is not associated with any file.
-@end defun
-
- The basis for @code{symbol-file} is the data in the variable
-@code{load-history}.
-
-@defvar load-history
-This variable's value is an alist connecting library file names with the
-names of functions and variables they define, the features they provide,
-and the features they require.
-
-Each element is a list and describes one library. The @sc{car} of the
-list is the absolute file name of the library, as a string. The rest
-of the list elements have these forms:
-
-@table @code
-@item @var{var}
-The symbol @var{var} was defined as a variable.
-@item (defun . @var{fun})
-The function @var{fun} was defined.
-@item (t . @var{fun})
-The function @var{fun} was previously an autoload before this library
-redefined it as a function. The following element is always
-@code{(defun . @var{fun})}, which represents defining @var{fun} as a
-function.
-@item (autoload . @var{fun})
-The function @var{fun} was defined as an autoload.
-@item (require . @var{feature})
-The feature @var{feature} was required.
-@item (provide . @var{feature})
-The feature @var{feature} was provided.
-@end table
-
-The value of @code{load-history} may have one element whose @sc{car} is
-@code{nil}. This element describes definitions made with
-@code{eval-buffer} on a buffer that is not visiting a file.
-@end defvar
-
- The command @code{eval-region} updates @code{load-history}, but does so
-by adding the symbols defined to the element for the file being visited,
-rather than replacing that element. @xref{Eval}.
-
-@node Unloading
-@section Unloading
-@cindex unloading packages
-
-@c Emacs 19 feature
- You can discard the functions and variables loaded by a library to
-reclaim memory for other Lisp objects. To do this, use the function
-@code{unload-feature}:
-
-@deffn Command unload-feature feature &optional force
-This command unloads the library that provided feature @var{feature}.
-It undefines all functions, macros, and variables defined in that
-library with @code{defun}, @code{defalias}, @code{defsubst},
-@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
-It then restores any autoloads formerly associated with those symbols.
-(Loading saves these in the @code{autoload} property of the symbol.)
-
-@vindex unload-feature-special-hooks
-Before restoring the previous definitions, @code{unload-feature} runs
-@code{remove-hook} to remove functions in the library from certain
-hooks. These hooks include variables whose names end in @samp{hook}
-or @samp{-hooks}, plus those listed in
-@code{unload-feature-special-hooks}. This is to prevent Emacs from
-ceasing to function because important hooks refer to functions that
-are no longer defined.
-
-@vindex @var{feature}-unload-hook
-If these measures are not sufficient to prevent malfunction, a library
-can define an explicit unload hook. If @code{@var{feature}-unload-hook}
-is defined, it is run as a normal hook before restoring the previous
-definitions, @emph{instead of} the usual hook-removing actions. The
-unload hook ought to undo all the global state changes made by the
-library that might cease to work once the library is unloaded.
-@code{unload-feature} can cause problems with libraries that fail to do
-this, so it should be used with caution.
-
-Ordinarily, @code{unload-feature} refuses to unload a library on which
-other loaded libraries depend. (A library @var{a} depends on library
-@var{b} if @var{a} contains a @code{require} for @var{b}.) If the
-optional argument @var{force} is non-@code{nil}, dependencies are
-ignored and you can unload any library.
-@end deffn
-
- The @code{unload-feature} function is written in Lisp; its actions are
-based on the variable @code{load-history}.
-
-@defvar unload-feature-special-hooks
-This variable holds a list of hooks to be scanned before unloading a
-library, to remove functions defined in the library.
-@end defvar
-
-@node Hooks for Loading
-@section Hooks for Loading
-@cindex loading hooks
-@cindex hooks for loading
-
-You can ask for code to be executed if and when a particular library is
-loaded, by calling @code{eval-after-load}.
-
-@defun eval-after-load library form
-This function arranges to evaluate @var{form} at the end of loading
-the file @var{library}, each time @var{library} is loaded. If
-@var{library} is already loaded, it evaluates @var{form} right away.
-Don't forget to quote @var{form}!
-
-You don't need to give a directory or extension in the file name
-@var{library}---normally you just give a bare file name, like this:
-
-@example
-(eval-after-load "edebug" '(def-edebug-spec c-point t))
-@end example
-
-To restrict which files can trigger the evaluation, include a
-directory or an extension or both in @var{library}. Only a file whose
-absolute true name (i.e., the name with all symbolic links chased out)
-matches all the given name components will match. In the following
-example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
-@code{..../foo/bar} will trigger the evaluation, but not
-@file{my_inst.el}:
-
-@example
-(eval-after-load "foo/bar/my_inst.elc" @dots{})
-@end example
-
-@var{library} can also be a feature (i.e.@: a symbol), in which case
-@var{form} is evaluated when @code{(provide @var{library})} is called.
-
-An error in @var{form} does not undo the load, but does prevent
-execution of the rest of @var{form}.
-@end defun
-
-In general, well-designed Lisp programs should not use this feature.
-The clean and modular ways to interact with a Lisp library are (1)
-examine and set the library's variables (those which are meant for
-outside use), and (2) call the library's functions. If you wish to
-do (1), you can do it immediately---there is no need to wait for when
-the library is loaded. To do (2), you must load the library (preferably
-with @code{require}).
-
-But it is OK to use @code{eval-after-load} in your personal
-customizations if you don't feel they must meet the design standards for
-programs meant for wider use.
-
-@defvar after-load-alist
-This variable, an alist built by @code{eval-after-load}, holds the
-expressions to evaluate when particular libraries are loaded. Each
-element looks like this:
-
-@example
-(@var{regexp-or-feature} @var{forms}@dots{})
-@end example
-
-The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms. The forms are evaluated when
-the key matches the absolute true name of the file being
-@code{load}ed or the symbol being @code{provide}d.
-@end defvar
-
-@ignore
- arch-tag: df731f89-0900-4389-a436-9105241b6f7a
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/locals
-@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top
-@appendix Buffer-Local Variables
-@c The title "Standard Buffer-Local Variables" is too long for
-@c smallbook. --rjc 30mar92
-@cindex buffer-local variables, general-purpose
-@cindex standard buffer-local variables
-
- The table below lists the general-purpose Emacs variables that
-automatically become buffer-local in each buffer. Most become
-buffer-local only when set; a few of them are always local in every
-buffer. Many Lisp packages define such variables for their internal
-use, but we don't try to list them all here.
-
- Every buffer-specific minor mode defines a buffer-local variable
-named @samp{@var{modename}-mode}. @xref{Minor Mode Conventions}.
-Minor mode variables will not be listed here.
-
-@table @code
-@item auto-fill-function
-@xref{Auto Filling}.
-
-@item buffer-auto-save-file-format
-@xref{Format Conversion}.
-
-@item buffer-auto-save-file-name
-@xref{Auto-Saving}.
-
-@item buffer-backed-up
-@xref{Making Backups}.
-
-@item buffer-display-count
-@xref{Buffers and Windows}.
-
-@item buffer-display-table
-@xref{Active Display Table}.
-
-@item buffer-display-time
-@xref{Buffers and Windows}.
-
-@item buffer-file-coding-system
-@xref{Encoding and I/O}.
-
-@item buffer-file-format
-@xref{Format Conversion}.
-
-@item buffer-file-name
-@xref{Buffer File Name}.
-
-@item buffer-file-number
-@xref{Buffer File Name}.
-
-@item buffer-file-truename
-@xref{Buffer File Name}.
-
-@item buffer-file-type
-@xref{MS-DOS File Types}.
-
-@item buffer-invisibility-spec
-@xref{Invisible Text}.
-
-@item buffer-offer-save
-@xref{Killing Buffers}.
-
-@item buffer-save-without-query
-@xref{Killing Buffers}.
-
-@item buffer-read-only
-@xref{Read Only Buffers}.
-
-@item buffer-saved-size
-@xref{Auto-Saving}.
-
-@item buffer-undo-list
-@xref{Undo}.
-
-@item cache-long-line-scans
-@xref{Truncation}.
-
-@item case-fold-search
-@xref{Searching and Case}.
-
-@item ctl-arrow
-@xref{Usual Display}.
-
-@item cursor-type
-@xref{Cursor Parameters}.
-
-@item cursor-in-non-selected-windows
-@xref{Basic Windows}.
-
-@item comment-column
-@xref{Comments,,, emacs, The GNU Emacs Manual}.
-
-@item default-directory
-@xref{File Name Expansion}.
-
-@item defun-prompt-regexp
-@xref{List Motion}.
-
-@item desktop-save-buffer
-@xref{Desktop Save Mode}.
-
-@ignore
-@item direction-reversed
-Does not work yet.
-@end ignore
-
-@item enable-multibyte-characters
-@ref{Text Representations}.
-
-@item fill-column
-@xref{Margins}.
-
-@item fill-prefix
-@xref{Margins}.
-
-@item font-lock-defaults
-@xref{Font Lock Basics}.
-
-@item fringe-cursor-alist
-@xref{Fringe Cursors}.
-
-@item fringe-indicator-alist
-@xref{Fringe Indicators}.
-
-@item fringes-outside-margins
-@xref{Fringes}.
-
-@item goal-column
-@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
-
-@item header-line-format
-@xref{Header Lines}.
-
-@item indicate-buffer-boundaries
-@xref{Usual Display}.
-
-@item indicate-empty-lines
-@xref{Usual Display}.
-
-@item left-fringe-width
-@xref{Fringe Size/Pos}.
-
-@item left-margin
-@xref{Margins}.
-
-@item left-margin-width
-@xref{Display Margins}.
-
-@item line-spacing
-@xref{Line Height}.
-
-@item local-abbrev-table
-@xref{Standard Abbrev Tables}.
-
-@item major-mode
-@xref{Mode Help}.
-
-@item mark-active
-@xref{The Mark}.
-
-@item mark-ring
-@xref{The Mark}.
-
-@item mode-line-buffer-identification
-@xref{Mode Line Variables}.
-
-@item mode-line-format
-@xref{Mode Line Data}.
-
-@item mode-line-modified
-@xref{Mode Line Variables}.
-
-@item mode-line-process
-@xref{Mode Line Variables}.
-
-@item mode-name
-@xref{Mode Line Variables}.
-
-@item point-before-scroll
-Used for communication between mouse commands and scroll-bar commands.
-
-@item right-fringe-width
-@xref{Fringe Size/Pos}.
-
-@item right-margin-width
-@xref{Display Margins}.
-
-@item save-buffer-coding-system
-@xref{Encoding and I/O}.
-
-@item scroll-bar-width
-@xref{Scroll Bars}.
-
-@item scroll-down-aggressively
-@xref{Textual Scrolling}.
-
-@item scroll-up-aggressively
-@xref{Textual Scrolling}.
-
-@item selective-display
-@xref{Selective Display}.
-
-@item selective-display-ellipses
-@xref{Selective Display}.
-
-@item tab-width
-@xref{Usual Display}.
-
-@item truncate-lines
-@xref{Truncation}.
-
-@item vertical-scroll-bar
-@xref{Scroll Bars}.
-
-@item window-size-fixed
-@xref{Resizing Windows}.
-
-@item write-contents-functions
-@xref{Saving Buffers}.
-@end table
-
-
-@ignore
- arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/macros
-@node Macros, Customization, Functions, Top
-@chapter Macros
-@cindex macros
-
- @dfn{Macros} enable you to define new control constructs and other
-language features. A macro is defined much like a function, but instead
-of telling how to compute a value, it tells how to compute another Lisp
-expression which will in turn compute the value. We call this
-expression the @dfn{expansion} of the macro.
-
- Macros can do this because they operate on the unevaluated expressions
-for the arguments, not on the argument values as functions do. They can
-therefore construct an expansion containing these argument expressions
-or parts of them.
-
- If you are using a macro to do something an ordinary function could
-do, just for the sake of speed, consider using an inline function
-instead. @xref{Inline Functions}.
-
-@menu
-* 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.
-@end menu
-
-@node Simple Macro
-@section A Simple Example of a Macro
-
- Suppose we would like to define a Lisp construct to increment a
-variable value, much like the @code{++} operator in C. We would like to
-write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
-Here's a macro definition that does the job:
-
-@findex inc
-@example
-@group
-(defmacro inc (var)
- (list 'setq var (list '1+ var)))
-@end group
-@end example
-
- When this is called with @code{(inc x)}, the argument @var{var} is the
-symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
-be in a function. The body of the macro uses this to construct the
-expansion, which is @code{(setq x (1+ x))}. Once the macro definition
-returns this expansion, Lisp proceeds to evaluate it, thus incrementing
-@code{x}.
-
-@node Expansion
-@section Expansion of a Macro Call
-@cindex expansion of macros
-@cindex macro call
-
- A macro call looks just like a function call in that it is a list which
-starts with the name of the macro. The rest of the elements of the list
-are the arguments of the macro.
-
- Evaluation of the macro call begins like evaluation of a function call
-except for one crucial difference: the macro arguments are the actual
-expressions appearing in the macro call. They are not evaluated before
-they are given to the macro definition. By contrast, the arguments of a
-function are results of evaluating the elements of the function call
-list.
-
- Having obtained the arguments, Lisp invokes the macro definition just
-as a function is invoked. The argument variables of the macro are bound
-to the argument values from the macro call, or to a list of them in the
-case of a @code{&rest} argument. And the macro body executes and
-returns its value just as a function body does.
-
- The second crucial difference between macros and functions is that the
-value returned by the macro body is not the value of the macro call.
-Instead, it is an alternate expression for computing that value, also
-known as the @dfn{expansion} of the macro. The Lisp interpreter
-proceeds to evaluate the expansion as soon as it comes back from the
-macro.
-
- Since the expansion is evaluated in the normal manner, it may contain
-calls to other macros. It may even be a call to the same macro, though
-this is unusual.
-
- You can see the expansion of a given macro call by calling
-@code{macroexpand}.
-
-@defun macroexpand form &optional environment
-@cindex macro expansion
-This function expands @var{form}, if it is a macro call. If the result
-is another macro call, it is expanded in turn, until something which is
-not a macro call results. That is the value returned by
-@code{macroexpand}. If @var{form} is not a macro call to begin with, it
-is returned as given.
-
-Note that @code{macroexpand} does not look at the subexpressions of
-@var{form} (although some macro definitions may do so). Even if they
-are macro calls themselves, @code{macroexpand} does not expand them.
-
-The function @code{macroexpand} does not expand calls to inline functions.
-Normally there is no need for that, since a call to an inline function is
-no harder to understand than a call to an ordinary function.
-
-If @var{environment} is provided, it specifies an alist of macro
-definitions that shadow the currently defined macros. Byte compilation
-uses this feature.
-
-@smallexample
-@group
-(defmacro inc (var)
- (list 'setq var (list '1+ var)))
- @result{} inc
-@end group
-
-@group
-(macroexpand '(inc r))
- @result{} (setq r (1+ r))
-@end group
-
-@group
-(defmacro inc2 (var1 var2)
- (list 'progn (list 'inc var1) (list 'inc var2)))
- @result{} inc2
-@end group
-
-@group
-(macroexpand '(inc2 r s))
- @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
-@end group
-@end smallexample
-@end defun
-
-
-@defun macroexpand-all form &optional environment
-@code{macroexpand-all} expands macros like @code{macroexpand}, but
-will look for and expand all macros in @var{form}, not just at the
-top-level. If no macros are expanded, the return value is @code{eq}
-to @var{form}.
-
-Repeating the example used for @code{macroexpand} above with
-@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
-expand the embedded calls to @code{inc}:
-
-@smallexample
-(macroexpand-all '(inc2 r s))
- @result{} (progn (setq r (1+ r)) (setq s (1+ s)))
-@end smallexample
-
-@end defun
-
-@node Compiling Macros
-@section Macros and Byte Compilation
-@cindex byte-compiling macros
-
- You might ask why we take the trouble to compute an expansion for a
-macro and then evaluate the expansion. Why not have the macro body
-produce the desired results directly? The reason has to do with
-compilation.
-
- When a macro call appears in a Lisp program being compiled, the Lisp
-compiler calls the macro definition just as the interpreter would, and
-receives an expansion. But instead of evaluating this expansion, it
-compiles the expansion as if it had appeared directly in the program.
-As a result, the compiled code produces the value and side effects
-intended for the macro, but executes at full compiled speed. This would
-not work if the macro body computed the value and side effects
-itself---they would be computed at compile time, which is not useful.
-
- In order for compilation of macro calls to work, the macros must
-already be defined in Lisp when the calls to them are compiled. The
-compiler has a special feature to help you do this: if a file being
-compiled contains a @code{defmacro} form, the macro is defined
-temporarily for the rest of the compilation of that file. To make this
-feature work, you must put the @code{defmacro} in the same file where it
-is used, and before its first use.
-
- Byte-compiling a file executes any @code{require} calls at top-level
-in the file. This is in case the file needs the required packages for
-proper compilation. One way to ensure that necessary macro definitions
-are available during compilation is to require the files that define
-them (@pxref{Named Features}). To avoid loading the macro definition files
-when someone @emph{runs} the compiled program, write
-@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
-During Compile}).
-
-@node Defining Macros
-@section Defining Macros
-
- A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should
-be a function; expansion of the macro works by applying the function
-(with @code{apply}) to the list of unevaluated argument-expressions
-from the macro call.
-
- It is possible to use an anonymous Lisp macro just like an anonymous
-function, but this is never done, because it does not make sense to pass
-an anonymous macro to functionals such as @code{mapcar}. In practice,
-all Lisp macros have names, and they are usually defined with the
-special form @code{defmacro}.
-
-@defspec defmacro name argument-list body-forms@dots{}
-@code{defmacro} defines the symbol @var{name} as a macro that looks
-like this:
-
-@example
-(macro lambda @var{argument-list} . @var{body-forms})
-@end example
-
-(Note that the @sc{cdr} of this list is a function---a lambda expression.)
-This macro object is stored in the function cell of @var{name}. The
-value returned by evaluating the @code{defmacro} form is @var{name}, but
-usually we ignore this value.
-
-The shape and meaning of @var{argument-list} is the same as in a
-function, and the keywords @code{&rest} and @code{&optional} may be used
-(@pxref{Argument List}). Macros may have a documentation string, but
-any @code{interactive} declaration is ignored since macros cannot be
-called interactively.
-@end defspec
-
- The body of the macro definition can include a @code{declare} form,
-which can specify how @key{TAB} should indent macro calls, and how to
-step through them for Edebug.
-
-@defmac declare @var{specs}@dots{}
-@anchor{Definition of declare}
-A @code{declare} form is used in a macro definition to specify various
-additional information about it. Two kinds of specification are
-currently supported:
-
-@table @code
-@item (debug @var{edebug-form-spec})
-Specify how to step through macro calls for Edebug.
-@xref{Instrumenting Macro Calls}.
-
-@item (indent @var{indent-spec})
-Specify how to indent calls to this macro. @xref{Indenting Macros},
-for more details.
-@end table
-
-A @code{declare} form only has its special effect in the body of a
-@code{defmacro} form if it immediately follows the documentation
-string, if present, or the argument list otherwise. (Strictly
-speaking, @emph{several} @code{declare} forms can follow the
-documentation string or argument list, but since a @code{declare} form
-can have several @var{specs}, they can always be combined into a
-single form.) When used at other places in a @code{defmacro} form, or
-outside a @code{defmacro} form, @code{declare} just returns @code{nil}
-without evaluating any @var{specs}.
-@end defmac
-
- No macro absolutely needs a @code{declare} form, because that form
-has no effect on how the macro expands, on what the macro means in the
-program. It only affects secondary features: indentation and Edebug.
-
-@node Backquote
-@section Backquote
-@cindex backquote (list substitution)
-@cindex ` (list substitution)
-@findex `
-
- Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts. To make this easier, use the @samp{`}
-syntax (usually called @dfn{backquote}).
-
- Backquote allows you to quote a list, but selectively evaluate
-elements of that list. In the simplest case, it is identical to the
-special form @code{quote} (@pxref{Quoting}). For example, these
-two forms yield identical results:
-
-@example
-@group
-`(a list of (+ 2 3) elements)
- @result{} (a list of (+ 2 3) elements)
-@end group
-@group
-'(a list of (+ 2 3) elements)
- @result{} (a list of (+ 2 3) elements)
-@end group
-@end example
-
-@findex , @r{(with backquote)}
-The special marker @samp{,} inside of the argument to backquote
-indicates a value that isn't constant. Backquote evaluates the
-argument of @samp{,} and puts the value in the list structure:
-
-@example
-@group
-(list 'a 'list 'of (+ 2 3) 'elements)
- @result{} (a list of 5 elements)
-@end group
-@group
-`(a list of ,(+ 2 3) elements)
- @result{} (a list of 5 elements)
-@end group
-@end example
-
- Substitution with @samp{,} is allowed at deeper levels of the list
-structure also. For example:
-
-@example
-@group
-(defmacro t-becomes-nil (variable)
- `(if (eq ,variable t)
- (setq ,variable nil)))
-@end group
-
-@group
-(t-becomes-nil foo)
- @equiv{} (if (eq foo t) (setq foo nil))
-@end group
-@end example
-
-@findex ,@@ @r{(with backquote)}
-@cindex splicing (with backquote)
- You can also @dfn{splice} an evaluated value into the resulting list,
-using the special marker @samp{,@@}. The elements of the spliced list
-become elements at the same level as the other elements of the resulting
-list. The equivalent code without using @samp{`} is often unreadable.
-Here are some examples:
-
-@example
-@group
-(setq some-list '(2 3))
- @result{} (2 3)
-@end group
-@group
-(cons 1 (append some-list '(4) some-list))
- @result{} (1 2 3 4 2 3)
-@end group
-@group
-`(1 ,@@some-list 4 ,@@some-list)
- @result{} (1 2 3 4 2 3)
-@end group
-
-@group
-(setq list '(hack foo bar))
- @result{} (hack foo bar)
-@end group
-@group
-(cons 'use
- (cons 'the
- (cons 'words (append (cdr list) '(as elements)))))
- @result{} (use the words foo bar as elements)
-@end group
-@group
-`(use the words ,@@(cdr list) as elements)
- @result{} (use the words foo bar as elements)
-@end group
-@end example
-
-In old Emacs versions, before version 19.29, @samp{`} used a different
-syntax which required an extra level of parentheses around the entire
-backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution
-required an extra level of parentheses surrounding both the @samp{,} or
-@samp{,@@} and the following expression. The old syntax required
-whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
-following expression.
-
-This syntax is still accepted, for compatibility with old Emacs
-versions, but support for it will soon disappear.
-
-@node Problems with Macros
-@section Common Problems Using Macros
-
- The basic facts of macro expansion have counterintuitive consequences.
-This section describes some important consequences that can lead to
-trouble, and rules to follow to avoid trouble.
-
-@menu
-* 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.
-@end menu
-
-@node Wrong Time
-@subsection Wrong Time
-
- The most common problem in writing macros is doing some of the
-real work prematurely---while expanding the macro, rather than in the
-expansion itself. For instance, one real package had this macro
-definition:
-
-@example
-(defmacro my-set-buffer-multibyte (arg)
- (if (fboundp 'set-buffer-multibyte)
- (set-buffer-multibyte arg)))
-@end example
-
-With this erroneous macro definition, the program worked fine when
-interpreted but failed when compiled. This macro definition called
-@code{set-buffer-multibyte} during compilation, which was wrong, and
-then did nothing when the compiled package was run. The definition
-that the programmer really wanted was this:
-
-@example
-(defmacro my-set-buffer-multibyte (arg)
- (if (fboundp 'set-buffer-multibyte)
- `(set-buffer-multibyte ,arg)))
-@end example
-
-@noindent
-This macro expands, if appropriate, into a call to
-@code{set-buffer-multibyte} that will be executed when the compiled
-program is actually run.
-
-@node Argument Evaluation
-@subsection Evaluating Macro Arguments Repeatedly
-
- When defining a macro you must pay attention to the number of times
-the arguments will be evaluated when the expansion is executed. The
-following macro (used to facilitate iteration) illustrates the problem.
-This macro allows us to write a simple ``for'' loop such as one might
-find in Pascal.
-
-@findex for
-@smallexample
-@group
-(defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
-For example, (for i from 1 to 10 do (print i))."
- (list 'let (list (list var init))
- (cons 'while (cons (list '<= var final)
- (append body (list (list 'inc var)))))))
-@end group
-@result{} for
-
-@group
-(for i from 1 to 3 do
- (setq square (* i i))
- (princ (format "\n%d %d" i square)))
-@expansion{}
-@end group
-@group
-(let ((i 1))
- (while (<= i 3)
- (setq square (* i i))
- (princ (format "\n%d %d" i square))
- (inc i)))
-@end group
-@group
-
- @print{}1 1
- @print{}2 4
- @print{}3 9
-@result{} nil
-@end group
-@end smallexample
-
-@noindent
-The arguments @code{from}, @code{to}, and @code{do} in this macro are
-``syntactic sugar''; they are entirely ignored. The idea is that you
-will write noise words (such as @code{from}, @code{to}, and @code{do})
-in those positions in the macro call.
-
-Here's an equivalent definition simplified through use of backquote:
-
-@smallexample
-@group
-(defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
-For example, (for i from 1 to 10 do (print i))."
- `(let ((,var ,init))
- (while (<= ,var ,final)
- ,@@body
- (inc ,var))))
-@end group
-@end smallexample
-
-Both forms of this definition (with backquote and without) suffer from
-the defect that @var{final} is evaluated on every iteration. If
-@var{final} is a constant, this is not a problem. If it is a more
-complex form, say @code{(long-complex-calculation x)}, this can slow
-down the execution significantly. If @var{final} has side effects,
-executing it more than once is probably incorrect.
-
-@cindex macro argument evaluation
-A well-designed macro definition takes steps to avoid this problem by
-producing an expansion that evaluates the argument expressions exactly
-once unless repeated evaluation is part of the intended purpose of the
-macro. Here is a correct expansion for the @code{for} macro:
-
-@smallexample
-@group
-(let ((i 1)
- (max 3))
- (while (<= i max)
- (setq square (* i i))
- (princ (format "%d %d" i square))
- (inc i)))
-@end group
-@end smallexample
-
-Here is a macro definition that creates this expansion:
-
-@smallexample
-@group
-(defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
- `(let ((,var ,init)
- (max ,final))
- (while (<= ,var max)
- ,@@body
- (inc ,var))))
-@end group
-@end smallexample
-
- Unfortunately, this fix introduces another problem,
-described in the following section.
-
-@node Surprising Local Vars
-@subsection Local Variables in Macro Expansions
-
-@ifnottex
- In the previous section, the definition of @code{for} was fixed as
-follows to make the expansion evaluate the macro arguments the proper
-number of times:
-
-@smallexample
-@group
-(defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
-@end group
-@group
- `(let ((,var ,init)
- (max ,final))
- (while (<= ,var max)
- ,@@body
- (inc ,var))))
-@end group
-@end smallexample
-@end ifnottex
-
- The new definition of @code{for} has a new problem: it introduces a
-local variable named @code{max} which the user does not expect. This
-causes trouble in examples such as the following:
-
-@smallexample
-@group
-(let ((max 0))
- (for x from 0 to 10 do
- (let ((this (frob x)))
- (if (< max this)
- (setq max this)))))
-@end group
-@end smallexample
-
-@noindent
-The references to @code{max} inside the body of the @code{for}, which
-are supposed to refer to the user's binding of @code{max}, really access
-the binding made by @code{for}.
-
-The way to correct this is to use an uninterned symbol instead of
-@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be
-bound and referred to just like any other symbol, but since it is
-created by @code{for}, we know that it cannot already appear in the
-user's program. Since it is not interned, there is no way the user can
-put it into the program later. It will never appear anywhere except
-where put by @code{for}. Here is a definition of @code{for} that works
-this way:
-
-@smallexample
-@group
-(defmacro for (var from init to final do &rest body)
- "Execute a simple for loop: (for i from 1 to 10 do (print i))."
- (let ((tempvar (make-symbol "max")))
- `(let ((,var ,init)
- (,tempvar ,final))
- (while (<= ,var ,tempvar)
- ,@@body
- (inc ,var)))))
-@end group
-@end smallexample
-
-@noindent
-This creates an uninterned symbol named @code{max} and puts it in the
-expansion instead of the usual interned symbol @code{max} that appears
-in expressions ordinarily.
-
-@node Eval During Expansion
-@subsection Evaluating Macro Arguments in Expansion
-
- Another problem can happen if the macro definition itself
-evaluates any of the macro argument expressions, such as by calling
-@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the
-user's variables, you may have trouble if the user happens to use a
-variable with the same name as one of the macro arguments. Inside the
-macro body, the macro argument binding is the most local binding of this
-variable, so any references inside the form being evaluated do refer to
-it. Here is an example:
-
-@example
-@group
-(defmacro foo (a)
- (list 'setq (eval a) t))
- @result{} foo
-@end group
-@group
-(setq x 'b)
-(foo x) @expansion{} (setq b t)
- @result{} t ; @r{and @code{b} has been set.}
-;; @r{but}
-(setq a 'c)
-(foo a) @expansion{} (setq a t)
- @result{} t ; @r{but this set @code{a}, not @code{c}.}
-
-@end group
-@end example
-
- It makes a difference whether the user's variable is named @code{a} or
-@code{x}, because @code{a} conflicts with the macro argument variable
-@code{a}.
-
- Another problem with calling @code{eval} in a macro definition is that
-it probably won't do what you intend in a compiled program. The
-byte-compiler runs macro definitions while compiling the program, when
-the program's own computations (which you might have wished to access
-with @code{eval}) don't occur and its local variable bindings don't
-exist.
-
- To avoid these problems, @strong{don't evaluate an argument expression
-while computing the macro expansion}. Instead, substitute the
-expression into the macro expansion, so that its value will be computed
-as part of executing the expansion. This is how the other examples in
-this chapter work.
-
-@node Repeated Expansion
-@subsection How Many Times is the Macro Expanded?
-
- Occasionally problems result from the fact that a macro call is
-expanded each time it is evaluated in an interpreted function, but is
-expanded only once (during compilation) for a compiled function. If the
-macro definition has side effects, they will work differently depending
-on how many times the macro is expanded.
-
- Therefore, you should avoid side effects in computation of the
-macro expansion, unless you really know what you are doing.
-
- One special kind of side effect can't be avoided: constructing Lisp
-objects. Almost all macro expansions include constructed lists; that is
-the whole point of most macros. This is usually safe; there is just one
-case where you must be careful: when the object you construct is part of a
-quoted constant in the macro expansion.
-
- If the macro is expanded just once, in compilation, then the object is
-constructed just once, during compilation. But in interpreted
-execution, the macro is expanded each time the macro call runs, and this
-means a new object is constructed each time.
-
- In most clean Lisp code, this difference won't matter. It can matter
-only if you perform side-effects on the objects constructed by the macro
-definition. Thus, to avoid trouble, @strong{avoid side effects on
-objects constructed by macro definitions}. Here is an example of how
-such side effects can get you into trouble:
-
-@lisp
-@group
-(defmacro empty-object ()
- (list 'quote (cons nil nil)))
-@end group
-
-@group
-(defun initialize (condition)
- (let ((object (empty-object)))
- (if condition
- (setcar object condition))
- object))
-@end group
-@end lisp
-
-@noindent
-If @code{initialize} is interpreted, a new list @code{(nil)} is
-constructed each time @code{initialize} is called. Thus, no side effect
-survives between calls. If @code{initialize} is compiled, then the
-macro @code{empty-object} is expanded during compilation, producing a
-single ``constant'' @code{(nil)} that is reused and altered each time
-@code{initialize} is called.
-
-One way to avoid pathological cases like this is to think of
-@code{empty-object} as a funny kind of constant, not as a memory
-allocation construct. You wouldn't use @code{setcar} on a constant such
-as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
-either.
-
-@node Indenting Macros
-@section Indenting Macros
-
- You can use the @code{declare} form in the macro definition to
-specify how to @key{TAB} should indent indent calls to the macro. You
-write it like this:
-
-@example
-(declare (indent @var{indent-spec}))
-@end example
-
-@noindent
-Here are the possibilities for @var{indent-spec}:
-
-@table @asis
-@item @code{nil}
-This is the same as no property---use the standard indentation pattern.
-@item @code{defun}
-Handle this function like a @samp{def} construct: treat the second
-line as the start of a @dfn{body}.
-@item an integer, @var{number}
-The first @var{number} arguments of the function are
-@dfn{distinguished} arguments; the rest are considered the body
-of the expression. A line in the expression is indented according to
-whether the first argument on it is distinguished or not. If the
-argument is part of the body, the line is indented @code{lisp-body-indent}
-more columns than the open-parenthesis starting the containing
-expression. If the argument is distinguished and is either the first
-or second argument, it is indented @emph{twice} that many extra columns.
-If the argument is distinguished and not the first or second argument,
-the line uses the standard pattern.
-@item a symbol, @var{symbol}
-@var{symbol} should be a function name; that function is called to
-calculate the indentation of a line within this expression. The
-function receives two arguments:
-@table @asis
-@item @var{state}
-The value returned by @code{parse-partial-sexp} (a Lisp primitive for
-indentation and nesting computation) when it parses up to the
-beginning of this line.
-@item @var{pos}
-The position at which the line being indented begins.
-@end table
-@noindent
-It should return either a number, which is the number of columns of
-indentation for that line, or a list whose car is such a number. The
-difference between returning a number and returning a list is that a
-number says that all following lines at the same nesting level should
-be indented just like this one; a list says that following lines might
-call for different indentations. This makes a difference when the
-indentation is being computed by @kbd{C-M-q}; if the value is a
-number, @kbd{C-M-q} need not recalculate indentation for the following
-lines until the end of the list.
-@end table
-
-@ignore
- arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
-@end ignore
+++ /dev/null
-# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual.
-
-# Copyright (C) 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.
-
-# Standard configure variables.
-srcdir = .
-
-infodir = $(srcdir)/../info
-usermanualdir = $(srcdir)/../man
-
-# Redefine `TEX' if `tex' does not invoke plain TeX. For example:
-# TEX=platex
-TEX=tex
-INSTALL_INFO = install-info
-MAKEINFO = makeinfo --force
-
-# The environment variable and its value to add $(srcdir) to the path
-# searched for TeX input files.
-texinputdir = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C
-
-# The name of the manual:
-VERSION=2.9
-manual = elisp-manual-21-$(VERSION)
-
-# List of all the texinfo files in the manual:
-
-srcs = \
- $(srcdir)/abbrevs.texi \
- $(srcdir)/advice.texi \
- $(srcdir)/anti.texi \
- $(srcdir)/back.texi \
- $(srcdir)/backups.texi \
- $(srcdir)/buffers.texi \
- $(srcdir)/commands.texi \
- $(srcdir)/compile.texi \
- $(srcdir)/control.texi \
- $(srcdir)/customize.texi \
- $(srcdir)/debugging.texi \
- $(srcdir)/display.texi \
- $(srcdir)/edebug.texi \
- $(srcdir)/elisp.texi \
- $(srcdir)/errors.texi \
- $(srcdir)/eval.texi \
- $(srcdir)/files.texi \
- $(srcdir)/frames.texi \
- $(srcdir)/functions.texi \
- $(srcdir)/hash.texi \
- $(srcdir)/help.texi \
- $(srcdir)/hooks.texi \
- $(srcdir)/internals.texi \
- $(srcdir)/intro.texi \
- $(srcdir)/keymaps.texi \
- $(srcdir)/lists.texi \
- $(srcdir)/loading.texi \
- $(srcdir)/locals.texi \
- $(srcdir)/macros.texi \
- $(srcdir)/maps.texi \
- $(srcdir)/markers.texi \
- $(srcdir)/minibuf.texi \
- $(srcdir)/modes.texi \
- $(srcdir)/nonascii.texi \
- $(srcdir)/numbers.texi \
- $(srcdir)/objects.texi \
- $(srcdir)/os.texi \
- $(srcdir)/positions.texi \
- $(srcdir)/processes.texi \
- $(srcdir)/searching.texi \
- $(srcdir)/sequences.texi \
- $(srcdir)/streams.texi \
- $(srcdir)/strings.texi \
- $(srcdir)/symbols.texi \
- $(srcdir)/syntax.texi \
- $(srcdir)/text.texi \
- $(srcdir)/tips.texi \
- $(srcdir)/variables.texi \
- $(srcdir)/windows.texi \
- $(srcdir)/index.texi \
- $(srcdir)/gpl.texi \
- $(srcdir)/doclicense.texi
-
-
-.PHONY: clean
-
-# The info file is named `elisp'.
-
-info: $(infodir)/elisp
-
-$(infodir)/dir:
- $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp
-
-$(infodir)/elisp: $(srcs)
- $(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi
-
-elisp.dvi: $(srcs)
- $(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi
-
-clean:
- - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
- *.vr *.vrs *.pg *.pgs *.ky *.kys
- - $(DEL) make.out core
- - $(DEL) $(infodir)/elisp*
-
-distclean: clean
-
-maintainer-clean: distclean
- - $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/maps
-@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top
-@appendix Standard Keymaps
-@cindex standard keymaps
-
-The following symbols are used as the names for various keymaps.
-Some of these exist when Emacs is first started, others are
-loaded only when their respective mode is used. This is not
-an exhaustive list.
-
-Several keymaps are used in the minibuffer. @xref{Completion Commands}.
-
-Almost all of these maps are used as local maps. Indeed, of the modes
-that presently exist, only Vip mode and Terminal mode ever change the
-global keymap.
-
-@table @code
-@item apropos-mode-map
-@vindex apropos-mode-map
-A sparse keymap for @code{apropos} buffers.
-
-@item Buffer-menu-mode-map
-@vindex Buffer-menu-mode-map
-A full keymap used by Buffer Menu mode.
-
-@item c-mode-map
-@vindex c-mode-map
-A sparse keymap used by C mode.
-
-@item command-history-map
-@vindex command-history-map
-A full keymap used by Command History mode.
-
-@item ctl-x-4-map
-A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
-
-@item ctl-x-5-map
-A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
-
-@item ctl-x-map
-A full keymap for @kbd{C-x} commands.
-
-@item custom-mode-map
-A full keymap for Custom mode.
-
-@item debugger-mode-map
-@vindex debugger-mode-map
-A full keymap used by Debugger mode.
-
-@item dired-mode-map
-@vindex dired-mode-map
-A full keymap for @code{dired-mode} buffers.
-
-@item edit-abbrevs-map
-@vindex edit-abbrevs-map
-A sparse keymap used in @code{edit-abbrevs}.
-
-@item edit-tab-stops-map
-@vindex edit-tab-stops-map
-A sparse keymap used in @code{edit-tab-stops}.
-
-@item electric-buffer-menu-mode-map
-@vindex electric-buffer-menu-mode-map
-A full keymap used by Electric Buffer Menu mode.
-
-@item electric-history-map
-@vindex electric-history-map
-A full keymap used by Electric Command History mode.
-
-@item emacs-lisp-mode-map
-@vindex emacs-lisp-mode-map
-A sparse keymap used by Emacs Lisp mode.
-
-@item esc-map
-A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
-
-@item facemenu-menu
-@vindex facemenu-menu
-The sparse keymap that displays the Text Properties menu.
-
-@item facemenu-background-menu
-@vindex facemenu-background-menu
-The sparse keymap that displays the Background Color submenu of the Text
-Properties menu.
-
-@item facemenu-face-menu
-@vindex facemenu-face-menu
-The sparse keymap that displays the Face submenu of the Text Properties menu.
-
-@item facemenu-foreground-menu
-@vindex facemenu-foreground-menu
-The sparse keymap that displays the Foreground Color submenu of the Text
-Properties menu.
-
-@item facemenu-indentation-menu
-@vindex facemenu-indentation-menu
-The sparse keymap that displays the Indentation submenu of the Text
-Properties menu.
-
-@item facemenu-justification-menu
-@vindex facemenu-justification-menu
-The sparse keymap that displays the Justification submenu of the Text
-Properties menu.
-
-@item facemenu-special-menu
-@vindex facemenu-special-menu
-The sparse keymap that displays the Special Props submenu of the Text
-Properties menu.
-
-@item function-key-map
-The keymap for translating keypad and function keys.@*
-If there are none, then it contains an empty sparse keymap.
-@xref{Translation Keymaps}.
-
-@item fundamental-mode-map
-@vindex fundamental-mode-map
-The sparse keymap for Fundamental mode.@*
-It is empty and should not be changed.
-
-@item global-map
-The full keymap containing default global key bindings.@*
-Modes should not modify the Global map.
-
-@item grep-mode-map
-@vindex grep-mode-map
-The keymap for @code{grep-mode} buffers.
-
-@item help-map
-The sparse keymap for the keys that follow the help character @kbd{C-h}.
-
-@item help-mode-map
-@vindex help-mode-map
-The sparse keymap for Help mode.
-
-@item Helper-help-map
-@vindex Helper-help-map
-A full keymap used by the help utility package.@*
-It has the same keymap in its value cell and in its function
-cell.
-
-@item Info-edit-map
-@vindex Info-edit-map
-A sparse keymap used by the @kbd{e} command of Info.
-
-@item Info-mode-map
-@vindex Info-mode-map
-A sparse keymap containing Info commands.
-
-@item isearch-mode-map
-@vindex isearch-mode-map
-A keymap that defines the characters you can type within incremental
-search.
-
-@item key-translation-map
-A keymap for translating keys. This one overrides ordinary key
-bindings, unlike @code{function-key-map}. @xref{Translation Keymaps}.
-
-@item kmacro-map
-@vindex kmacro-map
-A sparse keymap for keys that follows the @kbd{C-x C-k} prefix
-search.
-
-@item lisp-interaction-mode-map
-@vindex lisp-interaction-mode-map
-A sparse keymap used by Lisp Interaction mode.
-
-@item lisp-mode-map
-@vindex lisp-mode-map
-A sparse keymap used by Lisp mode.
-
-@item menu-bar-edit-menu
-@vindex menu-bar-edit-menu
-The keymap which displays the Edit menu in the menu bar.
-
-@item menu-bar-files-menu
-@vindex menu-bar-files-menu
-The keymap which displays the Files menu in the menu bar.
-
-@item menu-bar-help-menu
-@vindex menu-bar-help-menu
-The keymap which displays the Help menu in the menu bar.
-
-@item menu-bar-mule-menu
-@vindex menu-bar-mule-menu
-The keymap which displays the Mule menu in the menu bar.
-
-@item menu-bar-search-menu
-@vindex menu-bar-search-menu
-The keymap which displays the Search menu in the menu bar.
-
-@item menu-bar-tools-menu
-@vindex menu-bar-tools-menu
-The keymap which displays the Tools menu in the menu bar.
-
-@item mode-specific-map
-The keymap for characters following @kbd{C-c}. Note, this is in the
-global map. This map is not actually mode specific: its name was chosen
-to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
-where it describes the main use of the @kbd{C-c} prefix key.
-
-@item occur-mode-map
-@vindex occur-mode-map
-A sparse keymap used by Occur mode.
-
-@item query-replace-map
-A sparse keymap used for responses in @code{query-replace} and related
-commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions
-that use this map do not support prefix keys; they look up one event at a
-time.
-
-@item text-mode-map
-@vindex text-mode-map
-A sparse keymap used by Text mode.
-
-@item tool-bar-map
-The keymap defining the contents of the tool bar.
-
-@item view-mode-map
-@vindex view-mode-map
-A full keymap used by View mode.
-@end table
-
-@ignore
- arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/markers
-@node Markers, Text, Positions, Top
-@chapter Markers
-@cindex markers
-
- A @dfn{marker} is a Lisp object used to specify a position in a buffer
-relative to the surrounding text. A marker changes its offset from the
-beginning of the buffer automatically whenever text is inserted or
-deleted, so that it stays with the two characters on either side of it.
-
-@menu
-* 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".
-@end menu
-
-@node Overview of Markers
-@section Overview of Markers
-
- A marker specifies a buffer and a position in that buffer. The
-marker can be used to represent a position in the functions that
-require one, just as an integer could be used. In that case, the
-marker's buffer is normally ignored. Of course, a marker used in this
-way usually points to a position in the buffer that the function
-operates on, but that is entirely the programmer's responsibility.
-@xref{Positions}, for a complete description of positions.
-
- A marker has three attributes: the marker position, the marker
-buffer, and the insertion type. The marker position is an integer
-that is equivalent (at a given time) to the marker as a position in
-that buffer. But the marker's position value can change often during
-the life of the marker. Insertion and deletion of text in the buffer
-relocate the marker. The idea is that a marker positioned between two
-characters remains between those two characters despite insertion and
-deletion elsewhere in the buffer. Relocation changes the integer
-equivalent of the marker.
-
-@cindex marker relocation
- Deleting text around a marker's position leaves the marker between the
-characters immediately before and after the deleted text. Inserting
-text at the position of a marker normally leaves the marker either in
-front of or after the new text, depending on the marker's @dfn{insertion
-type} (@pxref{Marker Insertion Types})---unless the insertion is done
-with @code{insert-before-markers} (@pxref{Insertion}).
-
-@cindex marker garbage collection
- Insertion and deletion in a buffer must check all the markers and
-relocate them if necessary. This slows processing in a buffer with a
-large number of markers. For this reason, it is a good idea to make a
-marker point nowhere if you are sure you don't need it any more.
-Unreferenced markers are garbage collected eventually, but until then
-will continue to use time if they do point somewhere.
-
-@cindex markers as numbers
- Because it is common to perform arithmetic operations on a marker
-position, most of the arithmetic operations (including @code{+} and
-@code{-}) accept markers as arguments. In such cases, the marker
-stands for its current position.
-
-Here are examples of creating markers, setting markers, and moving point
-to markers:
-
-@example
-@group
-;; @r{Make a new marker that initially does not point anywhere:}
-(setq m1 (make-marker))
- @result{} #<marker in no buffer>
-@end group
-
-@group
-;; @r{Set @code{m1} to point between the 99th and 100th characters}
-;; @r{in the current buffer:}
-(set-marker m1 100)
- @result{} #<marker at 100 in markers.texi>
-@end group
-
-@group
-;; @r{Now insert one character at the beginning of the buffer:}
-(goto-char (point-min))
- @result{} 1
-(insert "Q")
- @result{} nil
-@end group
-
-@group
-;; @r{@code{m1} is updated appropriately.}
-m1
- @result{} #<marker at 101 in markers.texi>
-@end group
-
-@group
-;; @r{Two markers that point to the same position}
-;; @r{are not @code{eq}, but they are @code{equal}.}
-(setq m2 (copy-marker m1))
- @result{} #<marker at 101 in markers.texi>
-(eq m1 m2)
- @result{} nil
-(equal m1 m2)
- @result{} t
-@end group
-
-@group
-;; @r{When you are finished using a marker, make it point nowhere.}
-(set-marker m1 nil)
- @result{} #<marker in no buffer>
-@end group
-@end example
-
-@node Predicates on Markers
-@section Predicates on Markers
-
- You can test an object to see whether it is a marker, or whether it is
-either an integer or a marker. The latter test is useful in connection
-with the arithmetic functions that work with both markers and integers.
-
-@defun markerp object
-This function returns @code{t} if @var{object} is a marker, @code{nil}
-otherwise. Note that integers are not markers, even though many
-functions will accept either a marker or an integer.
-@end defun
-
-@defun integer-or-marker-p object
-This function returns @code{t} if @var{object} is an integer or a marker,
-@code{nil} otherwise.
-@end defun
-
-@defun number-or-marker-p object
-This function returns @code{t} if @var{object} is a number (either
-integer or floating point) or a marker, @code{nil} otherwise.
-@end defun
-
-@node Creating Markers
-@section Functions that Create Markers
-
- When you create a new marker, you can make it point nowhere, or point
-to the present position of point, or to the beginning or end of the
-accessible portion of the buffer, or to the same place as another given
-marker.
-
-The next four functions all return markers with insertion type
-@code{nil}. @xref{Marker Insertion Types}.
-
-@defun make-marker
-This function returns a newly created marker that does not point
-anywhere.
-
-@example
-@group
-(make-marker)
- @result{} #<marker in no buffer>
-@end group
-@end example
-@end defun
-
-@defun point-marker
-This function returns a new marker that points to the present position
-of point in the current buffer. @xref{Point}. For an example, see
-@code{copy-marker}, below.
-@end defun
-
-@defun point-min-marker
-This function returns a new marker that points to the beginning of the
-accessible portion of the buffer. This will be the beginning of the
-buffer unless narrowing is in effect. @xref{Narrowing}.
-@end defun
-
-@defun point-max-marker
-This function returns a new marker that points to the end of the
-accessible portion of the buffer. This will be the end of the buffer
-unless narrowing is in effect. @xref{Narrowing}.
-
-Here are examples of this function and @code{point-min-marker}, shown in
-a buffer containing a version of the source file for the text of this
-chapter.
-
-@example
-@group
-(point-min-marker)
- @result{} #<marker at 1 in markers.texi>
-(point-max-marker)
- @result{} #<marker at 15573 in markers.texi>
-@end group
-
-@group
-(narrow-to-region 100 200)
- @result{} nil
-@end group
-@group
-(point-min-marker)
- @result{} #<marker at 100 in markers.texi>
-@end group
-@group
-(point-max-marker)
- @result{} #<marker at 200 in markers.texi>
-@end group
-@end example
-@end defun
-
-@defun copy-marker marker-or-integer &optional insertion-type
-If passed a marker as its argument, @code{copy-marker} returns a
-new marker that points to the same place and the same buffer as does
-@var{marker-or-integer}. If passed an integer as its argument,
-@code{copy-marker} returns a new marker that points to position
-@var{marker-or-integer} in the current buffer.
-
-The new marker's insertion type is specified by the argument
-@var{insertion-type}. @xref{Marker Insertion Types}.
-
-If passed an integer argument less than 1, @code{copy-marker} returns a
-new marker that points to the beginning of the current buffer. If
-passed an integer argument greater than the length of the buffer,
-@code{copy-marker} returns a new marker that points to the end of the
-buffer.
-
-@example
-@group
-(copy-marker 0)
- @result{} #<marker at 1 in markers.texi>
-@end group
-
-@group
-(copy-marker 20000)
- @result{} #<marker at 7572 in markers.texi>
-@end group
-@end example
-
-An error is signaled if @var{marker} is neither a marker nor an
-integer.
-@end defun
-
- Two distinct markers are considered @code{equal} (even though not
-@code{eq}) to each other if they have the same position and buffer, or
-if they both point nowhere.
-
-@example
-@group
-(setq p (point-marker))
- @result{} #<marker at 2139 in markers.texi>
-@end group
-
-@group
-(setq q (copy-marker p))
- @result{} #<marker at 2139 in markers.texi>
-@end group
-
-@group
-(eq p q)
- @result{} nil
-@end group
-
-@group
-(equal p q)
- @result{} t
-@end group
-@end example
-
-@node Information from Markers
-@section Information from Markers
-
- This section describes the functions for accessing the components of a
-marker object.
-
-@defun marker-position marker
-This function returns the position that @var{marker} points to, or
-@code{nil} if it points nowhere.
-@end defun
-
-@defun marker-buffer marker
-This function returns the buffer that @var{marker} points into, or
-@code{nil} if it points nowhere.
-
-@example
-@group
-(setq m (make-marker))
- @result{} #<marker in no buffer>
-@end group
-@group
-(marker-position m)
- @result{} nil
-@end group
-@group
-(marker-buffer m)
- @result{} nil
-@end group
-
-@group
-(set-marker m 3770 (current-buffer))
- @result{} #<marker at 3770 in markers.texi>
-@end group
-@group
-(marker-buffer m)
- @result{} #<buffer markers.texi>
-@end group
-@group
-(marker-position m)
- @result{} 3770
-@end group
-@end example
-@end defun
-
-@defun buffer-has-markers-at position
-This function returns @code{t} if one or more markers
-point at position @var{position} in the current buffer.
-@end defun
-
-@node Marker Insertion Types
-@section Marker Insertion Types
-
-@cindex insertion type of a marker
- When you insert text directly at the place where a marker points,
-there are two possible ways to relocate that marker: it can point before
-the inserted text, or point after it. You can specify which one a given
-marker should do by setting its @dfn{insertion type}. Note that use of
-@code{insert-before-markers} ignores markers' insertion types, always
-relocating a marker to point after the inserted text.
-
-@defun set-marker-insertion-type marker type
-This function sets the insertion type of marker @var{marker} to
-@var{type}. If @var{type} is @code{t}, @var{marker} will advance when
-text is inserted at its position. If @var{type} is @code{nil},
-@var{marker} does not advance when text is inserted there.
-@end defun
-
-@defun marker-insertion-type marker
-This function reports the current insertion type of @var{marker}.
-@end defun
-
-Most functions that create markers, without an argument allowing to
-specify the insertion type, create them with insertion type
-@code{nil}. Also, the mark has, by default, insertion type
-@code{nil}.
-
-@node Moving Markers
-@section Moving Marker Positions
-
- This section describes how to change the position of an existing
-marker. When you do this, be sure you know whether the marker is used
-outside of your program, and, if so, what effects will result from
-moving it---otherwise, confusing things may happen in other parts of
-Emacs.
-
-@defun set-marker marker position &optional buffer
-This function moves @var{marker} to @var{position}
-in @var{buffer}. If @var{buffer} is not provided, it defaults to
-the current buffer.
-
-If @var{position} is less than 1, @code{set-marker} moves @var{marker}
-to the beginning of the buffer. If @var{position} is greater than the
-size of the buffer, @code{set-marker} moves marker to the end of the
-buffer. If @var{position} is @code{nil} or a marker that points
-nowhere, then @var{marker} is set to point nowhere.
-
-The value returned is @var{marker}.
-
-@example
-@group
-(setq m (point-marker))
- @result{} #<marker at 4714 in markers.texi>
-@end group
-@group
-(set-marker m 55)
- @result{} #<marker at 55 in markers.texi>
-@end group
-@group
-(setq b (get-buffer "foo"))
- @result{} #<buffer foo>
-@end group
-@group
-(set-marker m 0 b)
- @result{} #<marker at 1 in foo>
-@end group
-@end example
-@end defun
-
-@defun move-marker marker position &optional buffer
-This is another name for @code{set-marker}.
-@end defun
-
-@node The Mark
-@section The Mark
-@cindex mark, the
-@cindex mark ring
-
- One special marker in each buffer is designated @dfn{the mark}. It
-specifies a position to bound a range of text for commands such as
-@code{kill-region} and @code{indent-rigidly}. Lisp programs should
-set the mark only to values that have a potential use to the user, and
-never for their own internal purposes. For example, the
-@code{replace-regexp} command sets the mark to the value of point
-before doing any replacements, because this enables the user to move
-back there conveniently after the replace is finished.
-
- Many commands are designed to operate on the text between point and
-the mark when called interactively. If you are writing such a
-command, don't examine the mark directly; instead, use
-@code{interactive} with the @samp{r} specification. This provides the
-values of point and the mark as arguments to the command in an
-interactive call, but permits other Lisp programs to specify arguments
-explicitly. @xref{Interactive Codes}.
-
- Each buffer has a marker which represents the value of the mark in
-that buffer, independent of any other buffer. When a buffer is newly
-created, this marker exists but does not point anywhere. That means
-the mark ``doesn't exist'' in that buffer as yet.
-
- Once the mark ``exists'' in a buffer, it normally never ceases to
-exist. However, it may become @dfn{inactive}, if Transient Mark mode is
-enabled. The variable @code{mark-active}, which is always buffer-local
-in all buffers, indicates whether the mark is active: non-@code{nil}
-means yes. A command can request deactivation of the mark upon return
-to the editor command loop by setting @code{deactivate-mark} to a
-non-@code{nil} value (but this causes deactivation only if Transient
-Mark mode is enabled).
-
- The main motivation for using Transient Mark mode is that this mode
-also enables highlighting of the region when the mark is active.
-@xref{Display}.
-
- In addition to the mark, each buffer has a @dfn{mark ring} which is a
-list of markers containing previous values of the mark. When editing
-commands change the mark, they should normally save the old value of the
-mark on the mark ring. The variable @code{mark-ring-max} specifies the
-maximum number of entries in the mark ring; once the list becomes this
-long, adding a new element deletes the last element.
-
- There is also a separate global mark ring, but that is used only in a
-few particular user-level commands, and is not relevant to Lisp
-programming. So we do not describe it here.
-
-@defun mark &optional force
-@cindex current buffer mark
-This function returns the current buffer's mark position as an integer,
-or @code{nil} if no mark has ever been set in this buffer.
-
-If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
-@code{nil}, @code{mark} signals an error if the mark is inactive.
-However, if @var{force} is non-@code{nil}, then @code{mark} disregards
-inactivity of the mark, and returns the mark position anyway (or
-@code{nil}).
-@end defun
-
-@defun mark-marker
-This function returns the marker that represents the current buffer's
-mark. It is not a copy, it is the marker used internally. Therefore,
-changing this marker's position will directly affect the buffer's
-mark. Don't do that unless that is the effect you want.
-
-@example
-@group
-(setq m (mark-marker))
- @result{} #<marker at 3420 in markers.texi>
-@end group
-@group
-(set-marker m 100)
- @result{} #<marker at 100 in markers.texi>
-@end group
-@group
-(mark-marker)
- @result{} #<marker at 100 in markers.texi>
-@end group
-@end example
-
-Like any marker, this marker can be set to point at any buffer you
-like. If you make it point at any buffer other than the one of which
-it is the mark, it will yield perfectly consistent, but rather odd,
-results. We recommend that you not do it!
-@end defun
-
-@ignore
-@deffn Command set-mark-command jump
-If @var{jump} is @code{nil}, this command sets the mark to the value
-of point and pushes the previous value of the mark on the mark ring. The
-message @samp{Mark set} is also displayed in the echo area.
-
-If @var{jump} is not @code{nil}, this command sets point to the value
-of the mark, and sets the mark to the previous saved mark value, which
-is popped off the mark ring.
-
-This function is @emph{only} intended for interactive use.
-@end deffn
-@end ignore
-
-@defun set-mark position
-This function sets the mark to @var{position}, and activates the mark.
-The old value of the mark is @emph{not} pushed onto the mark ring.
-
-@strong{Please note:} Use this function only if you want the user to
-see that the mark has moved, and you want the previous mark position to
-be lost. Normally, when a new mark is set, the old one should go on the
-@code{mark-ring}. For this reason, most applications should use
-@code{push-mark} and @code{pop-mark}, not @code{set-mark}.
-
-Novice Emacs Lisp programmers often try to use the mark for the wrong
-purposes. The mark saves a location for the user's convenience. An
-editing command should not alter the mark unless altering the mark is
-part of the user-level functionality of the command. (And, in that
-case, this effect should be documented.) To remember a location for
-internal use in the Lisp program, store it in a Lisp variable. For
-example:
-
-@example
-@group
-(let ((beg (point)))
- (forward-line 1)
- (delete-region beg (point))).
-@end group
-@end example
-@end defun
-
-@c for interactive use only
-@ignore
-@deffn Command exchange-point-and-mark
-This function exchanges the positions of point and the mark.
-It is intended for interactive use.
-@end deffn
-@end ignore
-
-@defun push-mark &optional position nomsg activate
-This function sets the current buffer's mark to @var{position}, and
-pushes a copy of the previous mark onto @code{mark-ring}. If
-@var{position} is @code{nil}, then the value of point is used.
-@code{push-mark} returns @code{nil}.
-
-The function @code{push-mark} normally @emph{does not} activate the
-mark. To do that, specify @code{t} for the argument @var{activate}.
-
-A @samp{Mark set} message is displayed unless @var{nomsg} is
-non-@code{nil}.
-@end defun
-
-@defun pop-mark
-This function pops off the top element of @code{mark-ring} and makes
-that mark become the buffer's actual mark. This does not move point in
-the buffer, and it does nothing if @code{mark-ring} is empty. It
-deactivates the mark.
-
-The return value is not meaningful.
-@end defun
-
-@defopt transient-mark-mode
-@c @cindex Transient Mark mode Redundant
-This variable if non-@code{nil} enables Transient Mark mode, in which
-every buffer-modifying primitive sets @code{deactivate-mark}. The
-consequence of this is that commands that modify the buffer normally
-make the mark inactive.
-
-Lisp programs can set @code{transient-mark-mode} to @code{only} to
-enable Transient Mark mode for the following command only. During
-that following command, the value of @code{transient-mark-mode} is
-@code{identity}. If it is still @code{identity} at the end of the
-command, it changes to @code{nil}.
-@end defopt
-
-@defopt mark-even-if-inactive
-If this is non-@code{nil}, Lisp programs and the Emacs user can use the
-mark even when it is inactive. This option affects the behavior of
-Transient Mark mode. When the option is non-@code{nil}, deactivation of
-the mark turns off region highlighting, but commands that use the mark
-behave as if the mark were still active.
-@end defopt
-
-@defvar deactivate-mark
-If an editor command sets this variable non-@code{nil}, then the editor
-command loop deactivates the mark after the command returns (if
-Transient Mark mode is enabled). All the primitives that change the
-buffer set @code{deactivate-mark}, to deactivate the mark when the
-command is finished.
-
-To write Lisp code that modifies the buffer without causing
-deactivation of the mark at the end of the command, bind
-@code{deactivate-mark} to @code{nil} around the code that does the
-modification. For example:
-
-@example
-(let (deactivate-mark)
- (insert " "))
-@end example
-@end defvar
-
-@defun deactivate-mark
-This function deactivates the mark, if Transient Mark mode is enabled.
-Otherwise it does nothing.
-@end defun
-
-@defvar mark-active
-The mark is active when this variable is non-@code{nil}. This variable
-is always buffer-local in each buffer.
-@end defvar
-
-@defvar activate-mark-hook
-@defvarx deactivate-mark-hook
-These normal hooks are run, respectively, when the mark becomes active
-and when it becomes inactive. The hook @code{activate-mark-hook} is
-also run at the end of a command if the mark is active and it is
-possible that the region may have changed.
-@end defvar
-
-@defvar mark-ring
-The value of this buffer-local variable is the list of saved former
-marks of the current buffer, most recent first.
-
-@example
-@group
-mark-ring
-@result{} (#<marker at 11050 in markers.texi>
- #<marker at 10832 in markers.texi>
- @dots{})
-@end group
-@end example
-@end defvar
-
-@defopt mark-ring-max
-The value of this variable is the maximum size of @code{mark-ring}. If
-more marks than this are pushed onto the @code{mark-ring},
-@code{push-mark} discards an old mark when it adds a new one.
-@end defopt
-
-@node The Region
-@section The Region
-@cindex region (between point and mark)
-
- The text between point and the mark is known as @dfn{the region}.
-Various functions operate on text delimited by point and the mark, but
-only those functions specifically related to the region itself are
-described here.
-
-The next two functions signal an error if the mark does not point
-anywhere. If Transient Mark mode is enabled and
-@code{mark-even-if-inactive} is @code{nil}, they also signal an error
-if the mark is inactive.
-
-@defun region-beginning
-This function returns the position of the beginning of the region (as
-an integer). This is the position of either point or the mark,
-whichever is smaller.
-@end defun
-
-@defun region-end
-This function returns the position of the end of the region (as an
-integer). This is the position of either point or the mark, whichever is
-larger.
-@end defun
-
- Few programs need to use the @code{region-beginning} and
-@code{region-end} functions. A command designed to operate on a region
-should normally use @code{interactive} with the @samp{r} specification
-to find the beginning and end of the region. This lets other Lisp
-programs specify the bounds explicitly as arguments. (@xref{Interactive
-Codes}.)
-
-@ignore
- arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
-@end ignore
+++ /dev/null
-@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/minibuf
-@node Minibuffers, Command Loop, Read and Print, Top
-@chapter Minibuffers
-@cindex arguments, reading
-@cindex complex arguments
-@cindex minibuffer
-
- A @dfn{minibuffer} is a special buffer that Emacs commands use to
-read arguments more complicated than the single numeric prefix
-argument. These arguments include file names, buffer names, and
-command names (as in @kbd{M-x}). The minibuffer is displayed on the
-bottom line of the frame, in the same place as the echo area
-(@pxref{The Echo Area}), but only while it is in use for reading an
-argument.
-
-@menu
-* 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.
-@end menu
-
-@node Intro to Minibuffers
-@section Introduction to Minibuffers
-
- In most ways, a minibuffer is a normal Emacs buffer. Most operations
-@emph{within} a buffer, such as editing commands, work normally in a
-minibuffer. However, many operations for managing buffers do not apply
-to minibuffers. The name of a minibuffer always has the form @w{@samp{
-*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are
-displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame. (Sometimes frames have
-no minibuffer window, and sometimes a special kind of frame contains
-nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
-
- The text in the minibuffer always starts with the @dfn{prompt string},
-the text that was specified by the program that is using the minibuffer
-to tell the user what sort of input to type. This text is marked
-read-only so you won't accidentally delete or change it. It is also
-marked as a field (@pxref{Fields}), so that certain motion functions,
-including @code{beginning-of-line}, @code{forward-word},
-@code{forward-sentence}, and @code{forward-paragraph}, stop at the
-boundary between the prompt and the actual text. (In older Emacs
-versions, the prompt was displayed using a special mechanism and was not
-part of the buffer contents.)
-
- The minibuffer's window is normally a single line; it grows
-automatically if necessary if the contents require more space. You can
-explicitly resize it temporarily with the window sizing commands; it
-reverts to its normal size when the minibuffer is exited. You can
-resize it permanently by using the window sizing commands in the frame's
-other window, when the minibuffer is not active. If the frame contains
-just a minibuffer, you can change the minibuffer's size by changing the
-frame's size.
-
- Use of the minibuffer reads input events, and that alters the values
-of variables such as @code{this-command} and @code{last-command}
-(@pxref{Command Loop Info}). Your program should bind them around the
-code that uses the minibuffer, if you do not want that to change them.
-
- If a command uses a minibuffer while there is an active minibuffer,
-this is called a @dfn{recursive minibuffer}. The first minibuffer is
-named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
-incrementing the number at the end of the name. (The names begin with a
-space so that they won't show up in normal buffer lists.) Of several
-recursive minibuffers, the innermost (or most recently entered) is the
-active minibuffer. We usually call this ``the'' minibuffer. You can
-permit or forbid recursive minibuffers by setting the variable
-@code{enable-recursive-minibuffers} or by putting properties of that
-name on command symbols (@pxref{Recursive Mini}).
-
- Like other buffers, a minibuffer uses a local keymap
-(@pxref{Keymaps}) to specify special key bindings. The function that
-invokes the minibuffer also sets up its local map according to the job
-to be done. @xref{Text from Minibuffer}, for the non-completion
-minibuffer local maps. @xref{Completion Commands}, for the minibuffer
-local maps for completion.
-
- When Emacs is running in batch mode, any request to read from the
-minibuffer actually reads a line from the standard input descriptor that
-was supplied when Emacs was started.
-
-@node Text from Minibuffer
-@section Reading Text Strings with the Minibuffer
-
- Most often, the minibuffer is used to read text as a string. It can
-also be used to read a Lisp object in textual form. The most basic
-primitive for minibuffer input is @code{read-from-minibuffer}; it can do
-either one. There are also specialized commands for reading
-commands, variables, file names, etc. (@pxref{Completion}).
-
- In most cases, you should not call minibuffer input functions in the
-middle of a Lisp function. Instead, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive}
-specification. @xref{Defining Commands}.
-
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
-This function is the most general way to get input through the
-minibuffer. By default, it accepts arbitrary text and returns it as a
-string; however, if @var{read} is non-@code{nil}, then it uses
-@code{read} to convert the text into a Lisp object (@pxref{Input
-Functions}).
-
-The first thing this function does is to activate a minibuffer and
-display it with @var{prompt-string} as the prompt. This value must be a
-string. Then the user can edit text in the minibuffer.
-
-When the user types a command to exit the minibuffer,
-@code{read-from-minibuffer} constructs the return value from the text in
-the minibuffer. Normally it returns a string containing that text.
-However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
-reads the text and returns the resulting Lisp object, unevaluated.
-(@xref{Input Functions}, for information about reading.)
-
-The argument @var{default} specifies a default value to make available
-through the history commands. It should be a string, or @code{nil}.
-If non-@code{nil}, the user can access it using
-@code{next-history-element}, usually bound in the minibuffer to
-@kbd{M-n}. If @var{read} is non-@code{nil}, then @var{default} is
-also used as the input to @code{read}, if the user enters empty input.
-(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty
-input results in an @code{end-of-file} error.) However, in the usual
-case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
-ignores @var{default} when the user enters empty input and returns an
-empty string, @code{""}. In this respect, it is different from all
-the other minibuffer input functions in this chapter.
-
-If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
-use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
-value of @code{minibuffer-local-map} is used as the keymap. Specifying
-a keymap is the most important way to customize the minibuffer for
-various applications such as completion.
-
-The argument @var{hist} specifies which history list variable to use
-for saving the input and for history commands used in the minibuffer.
-It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
-
-If the variable @code{minibuffer-allow-text-properties} is
-non-@code{nil}, then the string which is returned includes whatever text
-properties were present in the minibuffer. Otherwise all the text
-properties are stripped when the value is returned.
-
-If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method (@pxref{Input Methods}) and
-the setting of @code{enable-multibyte-characters} (@pxref{Text
-Representations}) from whichever buffer was current before entering the
-minibuffer.
-
-Use of @var{initial-contents} is mostly deprecated; we recommend using
-a non-@code{nil} value only in conjunction with specifying a cons cell
-for @var{hist}. @xref{Initial Input}.
-@end defun
-
-@defun read-string prompt &optional initial history default inherit-input-method
-This function reads a string from the minibuffer and returns it. The
-arguments @var{prompt}, @var{initial}, @var{history} and
-@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
-The keymap used is @code{minibuffer-local-map}.
-
-The optional argument @var{default} is used as in
-@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
-specifies a default value to return if the user enters null input. As
-in @code{read-from-minibuffer} it should be a string, or @code{nil},
-which is equivalent to an empty string.
-
-This function is a simplified interface to the
-@code{read-from-minibuffer} function:
-
-@smallexample
-@group
-(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
-@equiv{}
-(let ((value
- (read-from-minibuffer @var{prompt} @var{initial} nil nil
- @var{history} @var{default} @var{inherit})))
- (if (and (equal value "") @var{default})
- @var{default}
- value))
-@end group
-@end smallexample
-@end defun
-
-@defvar minibuffer-allow-text-properties
-If this variable is @code{nil}, then @code{read-from-minibuffer} strips
-all text properties from the minibuffer input before returning it.
-This variable also affects @code{read-string}. However,
-@code{read-no-blanks-input} (see below), as well as
-@code{read-minibuffer} and related functions (@pxref{Object from
-Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
-functions that do minibuffer input with completion, discard text
-properties unconditionally, regardless of the value of this variable.
-@end defvar
-
-@defvar minibuffer-local-map
-This
-@anchor{Definition of minibuffer-local-map}
-@c avoid page break at anchor; work around Texinfo deficiency
-is the default local keymap for reading from the minibuffer. By
-default, it makes the following bindings:
-
-@table @asis
-@item @kbd{C-j}
-@code{exit-minibuffer}
-
-@item @key{RET}
-@code{exit-minibuffer}
-
-@item @kbd{C-g}
-@code{abort-recursive-edit}
-
-@item @kbd{M-n}
-@itemx @key{DOWN}
-@code{next-history-element}
-
-@item @kbd{M-p}
-@itemx @key{UP}
-@code{previous-history-element}
-
-@item @kbd{M-s}
-@code{next-matching-history-element}
-
-@item @kbd{M-r}
-@code{previous-matching-history-element}
-@end table
-@end defvar
-
-@c In version 18, initial is required
-@c Emacs 19 feature
-@defun read-no-blanks-input prompt &optional initial inherit-input-method
-This function reads a string from the minibuffer, but does not allow
-whitespace characters as part of the input: instead, those characters
-terminate the input. The arguments @var{prompt}, @var{initial}, and
-@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
-
-This is a simplified interface to the @code{read-from-minibuffer}
-function, and passes the value of the @code{minibuffer-local-ns-map}
-keymap as the @var{keymap} argument for that function. Since the keymap
-@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
-possible to put a space into the string, by quoting it.
-
-This function discards text properties, regardless of the value of
-@code{minibuffer-allow-text-properties}.
-
-@smallexample
-@group
-(read-no-blanks-input @var{prompt} @var{initial})
-@equiv{}
-(let (minibuffer-allow-text-properties)
- (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
-@end group
-@end smallexample
-@end defun
-
-@defvar minibuffer-local-ns-map
-This built-in variable is the keymap used as the minibuffer local keymap
-in the function @code{read-no-blanks-input}. By default, it makes the
-following bindings, in addition to those of @code{minibuffer-local-map}:
-
-@table @asis
-@item @key{SPC}
-@cindex @key{SPC} in minibuffer
-@code{exit-minibuffer}
-
-@item @key{TAB}
-@cindex @key{TAB} in minibuffer
-@code{exit-minibuffer}
-
-@item @kbd{?}
-@cindex @kbd{?} in minibuffer
-@code{self-insert-and-exit}
-@end table
-@end defvar
-
-@node Object from Minibuffer
-@section Reading Lisp Objects with the Minibuffer
-
- This section describes functions for reading Lisp objects with the
-minibuffer.
-
-@defun read-minibuffer prompt &optional initial
-This function reads a Lisp object using the minibuffer, and returns it
-without evaluating it. The arguments @var{prompt} and @var{initial} are
-used as in @code{read-from-minibuffer}.
-
-This is a simplified interface to the
-@code{read-from-minibuffer} function:
-
-@smallexample
-@group
-(read-minibuffer @var{prompt} @var{initial})
-@equiv{}
-(let (minibuffer-allow-text-properties)
- (read-from-minibuffer @var{prompt} @var{initial} nil t))
-@end group
-@end smallexample
-
-Here is an example in which we supply the string @code{"(testing)"} as
-initial input:
-
-@smallexample
-@group
-(read-minibuffer
- "Enter an expression: " (format "%s" '(testing)))
-
-;; @r{Here is how the minibuffer is displayed:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Enter an expression: (testing)@point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end smallexample
-
-@noindent
-The user can type @key{RET} immediately to use the initial input as a
-default, or can edit the input.
-@end defun
-
-@defun eval-minibuffer prompt &optional initial
-This function reads a Lisp expression using the minibuffer, evaluates
-it, then returns the result. The arguments @var{prompt} and
-@var{initial} are used as in @code{read-from-minibuffer}.
-
-This function simply evaluates the result of a call to
-@code{read-minibuffer}:
-
-@smallexample
-@group
-(eval-minibuffer @var{prompt} @var{initial})
-@equiv{}
-(eval (read-minibuffer @var{prompt} @var{initial}))
-@end group
-@end smallexample
-@end defun
-
-@defun edit-and-eval-command prompt form
-This function reads a Lisp expression in the minibuffer, and then
-evaluates it. The difference between this command and
-@code{eval-minibuffer} is that here the initial @var{form} is not
-optional and it is treated as a Lisp object to be converted to printed
-representation rather than as a string of text. It is printed with
-@code{prin1}, so if it is a string, double-quote characters (@samp{"})
-appear in the initial text. @xref{Output Functions}.
-
-The first thing @code{edit-and-eval-command} does is to activate the
-minibuffer with @var{prompt} as the prompt. Then it inserts the printed
-representation of @var{form} in the minibuffer, and lets the user edit it.
-When the user exits the minibuffer, the edited text is read with
-@code{read} and then evaluated. The resulting value becomes the value
-of @code{edit-and-eval-command}.
-
-In the following example, we offer the user an expression with initial
-text which is a valid form already:
-
-@smallexample
-@group
-(edit-and-eval-command "Please edit: " '(forward-word 1))
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following appears in the minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Please edit: (forward-word 1)@point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end smallexample
-
-@noindent
-Typing @key{RET} right away would exit the minibuffer and evaluate the
-expression, thus moving point forward one word.
-@code{edit-and-eval-command} returns @code{nil} in this example.
-@end defun
-
-@node Minibuffer History
-@section Minibuffer History
-@cindex minibuffer history
-@cindex history list
-
- A @dfn{minibuffer history list} records previous minibuffer inputs so
-the user can reuse them conveniently. A history list is actually a
-symbol, not a list; it is a variable whose value is a list of strings
-(previous inputs), most recent first.
-
- There are many separate history lists, used for different kinds of
-inputs. It's the Lisp programmer's job to specify the right history
-list for each use of the minibuffer.
-
- You specify the history list with the optional @var{hist} argument
-to either @code{read-from-minibuffer} or @code{completing-read}. Here
-are the possible values for it:
-
-@table @asis
-@item @var{variable}
-Use @var{variable} (a symbol) as the history list.
-
-@item (@var{variable} . @var{startpos})
-Use @var{variable} (a symbol) as the history list, and assume that the
-initial history position is @var{startpos} (a nonnegative integer).
-
-Specifying 0 for @var{startpos} is equivalent to just specifying the
-symbol @var{variable}. @code{previous-history-element} will display
-the most recent element of the history list in the minibuffer. If you
-specify a positive @var{startpos}, the minibuffer history functions
-behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
-history element currently shown in the minibuffer.
-
-For consistency, you should also specify that element of the history
-as the initial minibuffer contents, using the @var{initial} argument
-to the minibuffer input function (@pxref{Initial Input}).
-@end table
-
- If you don't specify @var{hist}, then the default history list
-@code{minibuffer-history} is used. For other standard history lists,
-see below. You can also create your own history list variable; just
-initialize it to @code{nil} before the first use.
-
- Both @code{read-from-minibuffer} and @code{completing-read} add new
-elements to the history list automatically, and provide commands to
-allow the user to reuse items on the list. The only thing your program
-needs to do to use a history list is to initialize it and to pass its
-name to the input functions when you wish. But it is safe to modify the
-list by hand when the minibuffer input functions are not using it.
-
- Emacs functions that add a new element to a history list can also
-delete old elements if the list gets too long. The variable
-@code{history-length} specifies the maximum length for most history
-lists. To specify a different maximum length for a particular history
-list, put the length in the @code{history-length} property of the
-history list symbol. The variable @code{history-delete-duplicates}
-specifies whether to delete duplicates in history.
-
-@defun add-to-history history-var newelt &optional maxelt keep-all
-This function adds a new element @var{newelt}, if it isn't the empty
-string, to the history list stored in the variable @var{history-var},
-and returns the updated history list. It limits the list length to
-the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
-(described below). The possible values of @var{maxelt} have the same
-meaning as the values of @code{history-length}.
-
-Normally, @code{add-to-history} removes duplicate members from the
-history list if @code{history-delete-duplicates} is non-@code{nil}.
-However, if @var{keep-all} is non-@code{nil}, that says not to remove
-duplicates, and to add @var{newelt} to the list even if it is empty.
-@end defun
-
-@defvar history-add-new-input
-If the value of this variable is @code{nil}, standard functions that
-read from the minibuffer don't add new elements to the history list.
-This lets Lisp programs explicitly manage input history by using
-@code{add-to-history}. By default, @code{history-add-new-input} is
-set to a non-@code{nil} value.
-@end defvar
-
-@defvar history-length
-The value of this variable specifies the maximum length for all
-history lists that don't specify their own maximum lengths. If the
-value is @code{t}, that means there no maximum (don't delete old
-elements). The value of @code{history-length} property of the history
-list variable's symbol, if set, overrides this variable for that
-particular history list.
-@end defvar
-
-@defvar history-delete-duplicates
-If the value of this variable is @code{t}, that means when adding a
-new history element, all previous identical elements are deleted.
-@end defvar
-
- Here are some of the standard minibuffer history list variables:
-
-@defvar minibuffer-history
-The default history list for minibuffer history input.
-@end defvar
-
-@defvar query-replace-history
-A history list for arguments to @code{query-replace} (and similar
-arguments to other commands).
-@end defvar
-
-@defvar file-name-history
-A history list for file-name arguments.
-@end defvar
-
-@defvar buffer-name-history
-A history list for buffer-name arguments.
-@end defvar
-
-@defvar regexp-history
-A history list for regular expression arguments.
-@end defvar
-
-@defvar extended-command-history
-A history list for arguments that are names of extended commands.
-@end defvar
-
-@defvar shell-command-history
-A history list for arguments that are shell commands.
-@end defvar
-
-@defvar read-expression-history
-A history list for arguments that are Lisp expressions to evaluate.
-@end defvar
-
-@node Initial Input
-@section Initial Input
-
-Several of the functions for minibuffer input have an argument called
-@var{initial} or @var{initial-contents}. This is a mostly-deprecated
-feature for specifying that the minibuffer should start out with
-certain text, instead of empty as usual.
-
-If @var{initial} is a string, the minibuffer starts out containing the
-text of the string, with point at the end, when the user starts to
-edit the text. If the user simply types @key{RET} to exit the
-minibuffer, it will use the initial input string to determine the
-value to return.
-
-@strong{We discourage use of a non-@code{nil} value for
-@var{initial}}, because initial input is an intrusive interface.
-History lists and default values provide a much more convenient method
-to offer useful default inputs to the user.
-
-There is just one situation where you should specify a string for an
-@var{initial} argument. This is when you specify a cons cell for the
-@var{hist} or @var{history} argument. @xref{Minibuffer History}.
-
-@var{initial} can also be a cons cell of the form @code{(@var{string}
-. @var{position})}. This means to insert @var{string} in the
-minibuffer but put point at @var{position} within the string's text.
-
-As a historical accident, @var{position} was implemented
-inconsistently in different functions. In @code{completing-read},
-@var{position}'s value is interpreted as origin-zero; that is, a value
-of 0 means the beginning of the string, 1 means after the first
-character, etc. In @code{read-minibuffer}, and the other
-non-completion minibuffer input functions that support this argument,
-1 means the beginning of the string 2 means after the first character,
-etc.
-
-Use of a cons cell as the value for @var{initial} arguments is
-deprecated in user code.
-
-@node Completion
-@section Completion
-@cindex completion
-
- @dfn{Completion} is a feature that fills in the rest of a name
-starting from an abbreviation for it. Completion works by comparing the
-user's input against a list of valid names and determining how much of
-the name is determined uniquely by what the user has typed. For
-example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
-type the first few letters of the name of the buffer to which you wish
-to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
-extends the name as far as it can.
-
- Standard Emacs commands offer completion for names of symbols, files,
-buffers, and processes; with the functions in this section, you can
-implement completion for other kinds of names.
-
- The @code{try-completion} function is the basic primitive for
-completion: it returns the longest determined completion of a given
-initial string, with a given set of strings to match against.
-
- The function @code{completing-read} provides a higher-level interface
-for completion. A call to @code{completing-read} specifies how to
-determine the list of valid names. The function then activates the
-minibuffer with a local keymap that binds a few keys to commands useful
-for completion. Other functions provide convenient simple interfaces
-for reading certain kinds of names with completion.
-
-@menu
-* 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:: Writing your own completion-function.
-@end menu
-
-@node Basic Completion
-@subsection Basic Completion Functions
-
- The completion functions @code{try-completion},
-@code{all-completions} and @code{test-completion} have nothing in
-themselves to do with minibuffers. We describe them in this chapter
-so as to keep them near the higher-level completion features that do
-use the minibuffer.
-
- If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a non-@code{nil}
-@code{risky-local-variable} property.
-
-@defun try-completion string collection &optional predicate
-This function returns the longest common substring of all possible
-completions of @var{string} in @var{collection}. The value of
-@var{collection} must be a list of strings or symbols, an alist, an
-obarray, a hash table, or a function that implements a virtual set of
-strings (see below).
-
-Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}; if the beginning of the
-permissible completion equals @var{string}, it matches. If no permissible
-completions match, @code{try-completion} returns @code{nil}. If only
-one permissible completion matches, and the match is exact, then
-@code{try-completion} returns @code{t}. Otherwise, the value is the
-longest initial sequence common to all the permissible completions that
-match.
-
-If @var{collection} is an alist (@pxref{Association Lists}), the
-permissible completions are the elements of the alist that are either
-strings, symbols, or conses whose @sc{car} is a string or symbol.
-Symbols are converted to strings using @code{symbol-name}. Other
-elements of the alist are ignored. (Remember that in Emacs Lisp, the
-elements of alists do not @emph{have} to be conses.) In particular, a
-list of strings or symbols is allowed, even though we usually do not
-think of such lists as alists.
-
-@cindex obarray in completion
-If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
-of all symbols in the obarray form the set of permissible completions. The
-global variable @code{obarray} holds an obarray containing the names of
-all interned Lisp symbols.
-
-Note that the only valid way to make a new obarray is to create it
-empty and then add symbols to it one by one using @code{intern}.
-Also, you cannot intern a given symbol in more than one obarray.
-
-If @var{collection} is a hash table, then the keys that are strings
-are the possible completions. Other keys are ignored.
-
-You can also use a symbol that is a function as @var{collection}. Then
-the function is solely responsible for performing completion;
-@code{try-completion} returns whatever this function returns. The
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil}. (The reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case.) @xref{Programmed Completion}.
-
-If the argument @var{predicate} is non-@code{nil}, then it must be a
-function of one argument, unless @var{collection} is a hash table, in
-which case it should be a function of two arguments. It is used to
-test each possible match, and the match is accepted only if
-@var{predicate} returns non-@code{nil}. The argument given to
-@var{predicate} is either a string or a cons cell (the @sc{car} of
-which is a string) from the alist, or a symbol (@emph{not} a symbol
-name) from the obarray. If @var{collection} is a hash table,
-@var{predicate} is called with two arguments, the string key and the
-associated value.
-
-In addition, to be acceptable, a completion must also match all the
-regular expressions in @code{completion-regexp-list}. (Unless
-@var{collection} is a function, in which case that function has to
-handle @code{completion-regexp-list} itself.)
-
-In the first of the following examples, the string @samp{foo} is
-matched by three of the alist @sc{car}s. All of the matches begin with
-the characters @samp{fooba}, so that is the result. In the second
-example, there is only one possible match, and it is exact, so the value
-is @code{t}.
-
-@smallexample
-@group
-(try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
- @result{} "fooba"
-@end group
-
-@group
-(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
- @result{} t
-@end group
-@end smallexample
-
-In the following example, numerous symbols begin with the characters
-@samp{forw}, and all of them begin with the word @samp{forward}. In
-most of the symbols, this is followed with a @samp{-}, but not in all,
-so no more than @samp{forward} can be completed.
-
-@smallexample
-@group
-(try-completion "forw" obarray)
- @result{} "forward"
-@end group
-@end smallexample
-
-Finally, in the following example, only two of the three possible
-matches pass the predicate @code{test} (the string @samp{foobaz} is
-too short). Both of those begin with the string @samp{foobar}.
-
-@smallexample
-@group
-(defun test (s)
- (> (length (car s)) 6))
- @result{} test
-@end group
-@group
-(try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
- @result{} "foobar"
-@end group
-@end smallexample
-@end defun
-
-@defun all-completions string collection &optional predicate nospace
-This function returns a list of all possible completions of
-@var{string}. The arguments to this function (aside from
-@var{nospace}) are the same as those of @code{try-completion}. Also,
-this function uses @code{completion-regexp-list} in the same way that
-@code{try-completion} does. The optional argument @var{nospace} only
-matters if @var{string} is the empty string. In that case, if
-@var{nospace} is non-@code{nil}, completions that start with a space
-are ignored.
-
-If @var{collection} is a function, it is called with three arguments:
-@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
-returns whatever the function returns. @xref{Programmed Completion}.
-
-Here is an example, using the function @code{test} shown in the
-example for @code{try-completion}:
-
-@smallexample
-@group
-(defun test (s)
- (> (length (car s)) 6))
- @result{} test
-@end group
-
-@group
-(all-completions
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
- @result{} ("foobar1" "foobar2")
-@end group
-@end smallexample
-@end defun
-
-@defun test-completion string collection &optional predicate
-@anchor{Definition of test-completion}
-This function returns non-@code{nil} if @var{string} is a valid
-completion possibility specified by @var{collection} and
-@var{predicate}. The arguments are the same as in
-@code{try-completion}. For instance, if @var{collection} is a list of
-strings, this is true if @var{string} appears in the list and
-@var{predicate} is satisfied.
-
-This function uses @code{completion-regexp-list} in the same
-way that @code{try-completion} does.
-
-If @var{predicate} is non-@code{nil} and if @var{collection} contains
-several strings that are equal to each other, as determined by
-@code{compare-strings} according to @code{completion-ignore-case},
-then @var{predicate} should accept either all or none of them.
-Otherwise, the return value of @code{test-completion} is essentially
-unpredictable.
-
-If @var{collection} is a function, it is called with three arguments,
-the values @var{string}, @var{predicate} and @code{lambda}; whatever
-it returns, @code{test-completion} returns in turn.
-@end defun
-
-@defvar completion-ignore-case
-If the value of this variable is non-@code{nil}, Emacs does not
-consider case significant in completion.
-@end defvar
-
-@defvar completion-regexp-list
-This is a list of regular expressions. The completion functions only
-consider a completion acceptable if it matches all regular expressions
-in this list, with @code{case-fold-search} (@pxref{Searching and Case})
-bound to the value of @code{completion-ignore-case}.
-@end defvar
-
-@defmac lazy-completion-table var fun
-This macro provides a way to initialize the variable @var{var} as a
-collection for completion in a lazy way, not computing its actual
-contents until they are first needed. You use this macro to produce a
-value that you store in @var{var}. The actual computation of the
-proper value is done the first time you do completion using @var{var}.
-It is done by calling @var{fun} with no arguments. The
-value @var{fun} returns becomes the permanent value of @var{var}.
-
-Here is an example of use:
-
-@smallexample
-(defvar foo (lazy-completion-table foo make-my-alist))
-@end smallexample
-@end defmac
-
-@node Minibuffer Completion
-@subsection Completion and the Minibuffer
-@cindex minibuffer completion
-@cindex reading from minibuffer with completion
-
- This section describes the basic interface for reading from the
-minibuffer with completion.
-
-@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
-This function reads a string in the minibuffer, assisting the user by
-providing completion. It activates the minibuffer with prompt
-@var{prompt}, which must be a string.
-
-The actual completion is done by passing @var{collection} and
-@var{predicate} to the function @code{try-completion}. This happens
-in certain commands bound in the local keymaps used for completion.
-Some of these commands also call @code{test-completion}. Thus, if
-@var{predicate} is non-@code{nil}, it should be compatible with
-@var{collection} and @code{completion-ignore-case}. @xref{Definition
-of test-completion}.
-
-If @var{require-match} is @code{nil}, the exit commands work regardless
-of the input in the minibuffer. If @var{require-match} is @code{t}, the
-usual minibuffer exit commands won't exit unless the input completes to
-an element of @var{collection}. If @var{require-match} is neither
-@code{nil} nor @code{t}, then the exit commands won't exit unless the
-input already in the buffer matches an element of @var{collection}.
-
-However, empty input is always permitted, regardless of the value of
-@var{require-match}; in that case, @code{completing-read} returns
-@var{default}, or @code{""}, if @var{default} is @code{nil}. The
-value of @var{default} (if non-@code{nil}) is also available to the
-user through the history commands.
-
-The function @code{completing-read} uses
-@code{minibuffer-local-completion-map} as the keymap if
-@var{require-match} is @code{nil}, and uses
-@code{minibuffer-local-must-match-map} if @var{require-match} is
-non-@code{nil}. @xref{Completion Commands}.
-
-The argument @var{hist} specifies which history list variable to use for
-saving the input and for minibuffer history commands. It defaults to
-@code{minibuffer-history}. @xref{Minibuffer History}.
-
-The argument @var{initial} is mostly deprecated; we recommend using a
-non-@code{nil} value only in conjunction with specifying a cons cell
-for @var{hist}. @xref{Initial Input}. For default input, use
-@var{default} instead.
-
-If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method (@pxref{Input
-Methods}) and the setting of @code{enable-multibyte-characters}
-(@pxref{Text Representations}) from whichever buffer was current before
-entering the minibuffer.
-
-If the built-in variable @code{completion-ignore-case} is
-non-@code{nil}, completion ignores case when comparing the input
-against the possible matches. @xref{Basic Completion}. In this mode
-of operation, @var{predicate} must also ignore case, or you will get
-surprising results.
-
-Here's an example of using @code{completing-read}:
-
-@smallexample
-@group
-(completing-read
- "Complete a foo: "
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- nil t "fo")
-@end group
-
-@group
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following appears in the minibuffer:}
-
----------- Buffer: Minibuffer ----------
-Complete a foo: fo@point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end smallexample
-
-@noindent
-If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
-@code{completing-read} returns @code{barfoo}.
-
-The @code{completing-read} function binds variables to pass
-information to the commands that actually do completion.
-They are described in the following section.
-@end defun
-
-@node Completion Commands
-@subsection Minibuffer Commands that Do Completion
-
- This section describes the keymaps, commands and user options used
-in the minibuffer to do completion. The description refers to the
-situation when Partial Completion mode is disabled (as it is by
-default). When enabled, this minor mode uses its own alternatives to
-some of the commands described below. @xref{Completion Options,,,
-emacs, The GNU Emacs Manual}, for a short description of Partial
-Completion mode.
-
-@defvar minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer. This is the global variable that contains what
-@code{completing-read} passes to @code{try-completion}. It is used by
-minibuffer completion commands such as @code{minibuffer-complete-word}.
-@end defvar
-
-@defvar minibuffer-completion-predicate
-This variable's value is the predicate that @code{completing-read}
-passes to @code{try-completion}. The variable is also used by the other
-minibuffer completion functions.
-@end defvar
-
-@defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, Emacs asks for
-confirmation of a completion before exiting the minibuffer.
-@code{completing-read} binds this variable, and the function
-@code{minibuffer-complete-and-exit} checks the value before exiting.
-@end defvar
-
-@deffn Command minibuffer-complete-word
-This function completes the minibuffer contents by at most a single
-word. Even if the minibuffer contents have only one completion,
-@code{minibuffer-complete-word} does not add any characters beyond the
-first character that is not a word constituent. @xref{Syntax Tables}.
-@end deffn
-
-@deffn Command minibuffer-complete
-This function completes the minibuffer contents as far as possible.
-@end deffn
-
-@deffn Command minibuffer-complete-and-exit
-This function completes the minibuffer contents, and exits if
-confirmation is not required, i.e., if
-@code{minibuffer-completion-confirm} is @code{nil}. If confirmation
-@emph{is} required, it is given by repeating this command
-immediately---the command is programmed to work without confirmation
-when run twice in succession.
-@end deffn
-
-@deffn Command minibuffer-completion-help
-This function creates a list of the possible completions of the
-current minibuffer contents. It works by calling @code{all-completions}
-using the value of the variable @code{minibuffer-completion-table} as
-the @var{collection} argument, and the value of
-@code{minibuffer-completion-predicate} as the @var{predicate} argument.
-The list of completions is displayed as text in a buffer named
-@samp{*Completions*}.
-@end deffn
-
-@defun display-completion-list completions &optional common-substring
-This function displays @var{completions} to the stream in
-@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
-information about streams.) The argument @var{completions} is normally
-a list of completions just returned by @code{all-completions}, but it
-does not have to be. Each element may be a symbol or a string, either
-of which is simply printed. It can also be a list of two strings,
-which is printed as if the strings were concatenated. The first of
-the two strings is the actual completion, the second string serves as
-annotation.
-
-The argument @var{common-substring} is the prefix that is common to
-all the completions. With normal Emacs completion, it is usually the
-same as the string that was completed. @code{display-completion-list}
-uses this to highlight text in the completion list for better visual
-feedback. This is not needed in the minibuffer; for minibuffer
-completion, you can pass @code{nil}.
-
-This function is called by @code{minibuffer-completion-help}. The
-most common way to use it is together with
-@code{with-output-to-temp-buffer}, like this:
-
-@example
-(with-output-to-temp-buffer "*Completions*"
- (display-completion-list
- (all-completions (buffer-string) my-alist)
- (buffer-string)))
-@end example
-@end defun
-
-@defopt completion-auto-help
-If this variable is non-@code{nil}, the completion commands
-automatically display a list of possible completions whenever nothing
-can be completed because the next character is not uniquely determined.
-@end defopt
-
-@defvar minibuffer-local-completion-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is not required. By default, this
-keymap makes the following bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Definition of minibuffer-local-map}).
-@end defvar
-
-@defvar minibuffer-local-must-match-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is required. Therefore, no keys
-are bound to @code{exit-minibuffer}, the command that exits the
-minibuffer unconditionally. By default, this keymap makes the following
-bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
-@item @kbd{C-j}
-@code{minibuffer-complete-and-exit}
-
-@item @key{RET}
-@code{minibuffer-complete-and-exit}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}.
-@end defvar
-
-@defvar minibuffer-local-filename-completion-map
-This is like @code{minibuffer-local-completion-map}
-except that it does not bind @key{SPC}. This keymap is used by the
-function @code{read-file-name}.
-@end defvar
-
-@defvar minibuffer-local-must-match-filename-map
-This is like @code{minibuffer-local-must-match-map}
-except that it does not bind @key{SPC}. This keymap is used by the
-function @code{read-file-name}.
-@end defvar
-
-@node High-Level Completion
-@subsection High-Level Completion Functions
-
- This section describes the higher-level convenient functions for
-reading certain sorts of names with completion.
-
- In most cases, you should not call these functions in the middle of a
-Lisp function. When possible, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive}
-specification. @xref{Defining Commands}.
-
-@defun read-buffer prompt &optional default existing
-This function reads the name of a buffer and returns it as a string.
-The argument @var{default} is the default name to use, the value to
-return if the user exits with an empty minibuffer. If non-@code{nil},
-it should be a string or a buffer. It is mentioned in the prompt, but
-is not inserted in the minibuffer as initial input.
-
-The argument @var{prompt} should be a string ending with a colon and a
-space. If @var{default} is non-@code{nil}, the function inserts it in
-@var{prompt} before the colon to follow the convention for reading from
-the minibuffer with a default value (@pxref{Programming Tips}).
-
-If @var{existing} is non-@code{nil}, then the name specified must be
-that of an existing buffer. The usual commands to exit the minibuffer
-do not exit if the text is not valid, and @key{RET} does completion to
-attempt to find a valid name. If @var{existing} is neither @code{nil}
-nor @code{t}, confirmation is required after completion. (However,
-@var{default} is not checked for validity; it is returned, whatever it
-is, if the user exits with the minibuffer empty.)
-
-In the following example, the user enters @samp{minibuffer.t}, and
-then types @key{RET}. The argument @var{existing} is @code{t}, and the
-only buffer name starting with the given input is
-@samp{minibuffer.texi}, so that name is the value.
-
-@example
-(read-buffer "Buffer name: " "foo" t)
-@group
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
-;; @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Buffer name (default foo): @point{}
----------- Buffer: Minibuffer ----------
-@end group
-
-@group
-;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
- @result{} "minibuffer.texi"
-@end group
-@end example
-@end defun
-
-@defvar read-buffer-function
-This variable specifies how to read buffer names. For example, if you
-set this variable to @code{iswitchb-read-buffer}, all Emacs commands
-that call @code{read-buffer} to read a buffer name will actually use the
-@code{iswitchb} package to read it.
-@end defvar
-
-@defun read-command prompt &optional default
-This function reads the name of a command and returns it as a Lisp
-symbol. The argument @var{prompt} is used as in
-@code{read-from-minibuffer}. Recall that a command is anything for
-which @code{commandp} returns @code{t}, and a command name is a symbol
-for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
-
-The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string; if it is a string,
-@code{read-command} interns it before returning it. If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{(intern "")}, that is, a
-symbol whose name is an empty string.
-
-@example
-(read-command "Command name? ")
-
-@group
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Command name?
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-If the user types @kbd{forward-c @key{RET}}, then this function returns
-@code{forward-char}.
-
-The @code{read-command} function is a simplified interface to
-@code{completing-read}. It uses the variable @code{obarray} so as to
-complete in the set of extant Lisp symbols, and it uses the
-@code{commandp} predicate so as to accept only command names:
-
-@cindex @code{commandp} example
-@example
-@group
-(read-command @var{prompt})
-@equiv{}
-(intern (completing-read @var{prompt} obarray
- 'commandp t nil))
-@end group
-@end example
-@end defun
-
-@defun read-variable prompt &optional default
-@anchor{Definition of read-variable}
-This function reads the name of a user variable and returns it as a
-symbol.
-
-The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string; if it is a string,
-@code{read-variable} interns it before returning it. If @var{default}
-is @code{nil}, that means no default has been specified; then if the
-user enters null input, the return value is @code{(intern "")}.
-
-@example
-@group
-(read-variable "Variable name? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
-;; @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Variable name? @point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
-returns @code{fill-prefix}.
-
-In general, @code{read-variable} is similar to @code{read-command},
-but uses the predicate @code{user-variable-p} instead of
-@code{commandp}:
-
-@cindex @code{user-variable-p} example
-@example
-@group
-(read-variable @var{prompt})
-@equiv{}
-(intern
- (completing-read @var{prompt} obarray
- 'user-variable-p t nil))
-@end group
-@end example
-@end defun
-
- See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
-and @code{read-input-method-name}, in @ref{Input Methods}.
-
-@node Reading File Names
-@subsection Reading File Names
-@cindex read file names
-@cindex prompt for file name
-
- Here is another high-level completion function, designed for reading a
-file name. It provides special features including automatic insertion
-of the default directory.
-
-@defun read-file-name prompt &optional directory default existing initial predicate
-This function reads a file name in the minibuffer, prompting with
-@var{prompt} and providing completion.
-
-If @var{existing} is non-@code{nil}, then the user must specify the name
-of an existing file; @key{RET} performs completion to make the name
-valid if possible, and then refuses to exit if it is not valid. If the
-value of @var{existing} is neither @code{nil} nor @code{t}, then
-@key{RET} also requires confirmation after completion. If
-@var{existing} is @code{nil}, then the name of a nonexistent file is
-acceptable.
-
-@code{read-file-name} uses
-@code{minibuffer-local-filename-completion-map} as the keymap if
-@var{existing} is @code{nil}, and uses
-@code{minibuffer-local-must-match-filename-map} if @var{existing} is
-non-@code{nil}. @xref{Completion Commands}.
-
-The argument @var{directory} specifies the directory to use for
-completion of relative file names. It should be an absolute directory
-name. If @code{insert-default-directory} is non-@code{nil},
-@var{directory} is also inserted in the minibuffer as initial input.
-It defaults to the current buffer's value of @code{default-directory}.
-
-@c Emacs 19 feature
-If you specify @var{initial}, that is an initial file name to insert
-in the buffer (after @var{directory}, if that is inserted). In this
-case, point goes at the beginning of @var{initial}. The default for
-@var{initial} is @code{nil}---don't insert any file name. To see what
-@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please
-note:} we recommend using @var{default} rather than @var{initial} in
-most cases.
-
-If @var{default} is non-@code{nil}, then the function returns
-@var{default} if the user exits the minibuffer with the same non-empty
-contents that @code{read-file-name} inserted initially. The initial
-minibuffer contents are always non-empty if
-@code{insert-default-directory} is non-@code{nil}, as it is by
-default. @var{default} is not checked for validity, regardless of the
-value of @var{existing}. However, if @var{existing} is
-non-@code{nil}, the initial minibuffer contents should be a valid file
-(or directory) name. Otherwise @code{read-file-name} attempts
-completion if the user exits without any editing, and does not return
-@var{default}. @var{default} is also available through the history
-commands.
-
-If @var{default} is @code{nil}, @code{read-file-name} tries to find a
-substitute default to use in its place, which it treats in exactly the
-same way as if it had been specified explicitly. If @var{default} is
-@code{nil}, but @var{initial} is non-@code{nil}, then the default is
-the absolute file name obtained from @var{directory} and
-@var{initial}. If both @var{default} and @var{initial} are @code{nil}
-and the buffer is visiting a file, @code{read-file-name} uses the
-absolute file name of that file as default. If the buffer is not
-visiting a file, then there is no default. In that case, if the user
-types @key{RET} without any editing, @code{read-file-name} simply
-returns the pre-inserted contents of the minibuffer.
-
-If the user types @key{RET} in an empty minibuffer, this function
-returns an empty string, regardless of the value of @var{existing}.
-This is, for instance, how the user can make the current buffer visit
-no file using @code{M-x set-visited-file-name}.
-
-If @var{predicate} is non-@code{nil}, it specifies a function of one
-argument that decides which file names are acceptable completion
-possibilities. A file name is an acceptable value if @var{predicate}
-returns non-@code{nil} for it.
-
-@code{read-file-name} does not automatically expand file names. You
-must call @code{expand-file-name} yourself if an absolute file name is
-required.
-
-Here is an example:
-
-@example
-@group
-(read-file-name "The file is ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following appears in the minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-The file is /gp/gnu/elisp/@point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-Typing @kbd{manual @key{TAB}} results in the following:
-
-@example
-@group
----------- Buffer: Minibuffer ----------
-The file is /gp/gnu/elisp/manual.texi@point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@c Wordy to avoid overfull hbox in smallbook mode.
-@noindent
-If the user types @key{RET}, @code{read-file-name} returns the file name
-as the string @code{"/gp/gnu/elisp/manual.texi"}.
-@end defun
-
-@defvar read-file-name-function
-If non-@code{nil}, this should be a function that accepts the same
-arguments as @code{read-file-name}. When @code{read-file-name} is
-called, it calls this function with the supplied arguments instead of
-doing its usual work.
-@end defvar
-
-@defvar read-file-name-completion-ignore-case
-If this variable is non-@code{nil}, @code{read-file-name} ignores case
-when performing completion.
-@end defvar
-
-@defun read-directory-name prompt &optional directory default existing initial
-This function is like @code{read-file-name} but allows only directory
-names as completion possibilities.
-
-If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
-@code{read-directory-name} constructs a substitute default by
-combining @var{directory} (or the current buffer's default directory
-if @var{directory} is @code{nil}) and @var{initial}. If both
-@var{default} and @var{initial} are @code{nil}, this function uses
-@var{directory} as substitute default, or the current buffer's default
-directory if @var{directory} is @code{nil}.
-@end defun
-
-@defopt insert-default-directory
-This variable is used by @code{read-file-name}, and thus, indirectly,
-by most commands reading file names. (This includes all commands that
-use the code letters @samp{f} or @samp{F} in their interactive form.
-@xref{Interactive Codes,, Code Characters for interactive}.) Its
-value controls whether @code{read-file-name} starts by placing the
-name of the default directory in the minibuffer, plus the initial file
-name if any. If the value of this variable is @code{nil}, then
-@code{read-file-name} does not place any initial input in the
-minibuffer (unless you specify initial input with the @var{initial}
-argument). In that case, the default directory is still used for
-completion of relative file names, but is not displayed.
-
-If this variable is @code{nil} and the initial minibuffer contents are
-empty, the user may have to explicitly fetch the next history element
-to access a default value. If the variable is non-@code{nil}, the
-initial minibuffer contents are always non-empty and the user can
-always request a default value by immediately typing @key{RET} in an
-unedited minibuffer. (See above.)
-
-For example:
-
-@example
-@group
-;; @r{Here the minibuffer starts out with the default directory.}
-(let ((insert-default-directory t))
- (read-file-name "The file is "))
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-The file is ~lewis/manual/@point{}
----------- Buffer: Minibuffer ----------
-@end group
-
-@group
-;; @r{Here the minibuffer is empty and only the prompt}
-;; @r{appears on its line.}
-(let ((insert-default-directory nil))
- (read-file-name "The file is "))
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-The file is @point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-@end defopt
-
-@node Programmed Completion
-@subsection Programmed Completion
-@cindex programmed completion
-
- Sometimes it is not possible to create an alist or an obarray
-containing all the intended possible completions. In such a case, you
-can supply your own function to compute the completion of a given string.
-This is called @dfn{programmed completion}.
-
- To use this feature, pass a symbol with a function definition as the
-@var{collection} argument to @code{completing-read}. The function
-@code{completing-read} arranges to pass your completion function along
-to @code{try-completion} and @code{all-completions}, which will then let
-your function do all the work.
-
- The completion function should accept three arguments:
-
-@itemize @bullet
-@item
-The string to be completed.
-
-@item
-The predicate function to filter possible matches, or @code{nil} if
-none. Your function should call the predicate for each possible match,
-and ignore the possible match if the predicate returns @code{nil}.
-
-@item
-A flag specifying the type of operation.
-@end itemize
-
- There are three flag values for three operations:
-
-@itemize @bullet
-@item
-@code{nil} specifies @code{try-completion}. The completion function
-should return the completion of the specified string, or @code{t} if the
-string is a unique and exact match already, or @code{nil} if the string
-matches no possibility.
-
-If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function should return the string, not
-@code{t}.
-
-@item
-@code{t} specifies @code{all-completions}. The completion function
-should return a list of all possible completions of the specified
-string.
-
-@item
-@code{lambda} specifies @code{test-completion}. The completion
-function should return @code{t} if the specified string is an exact
-match for some possibility; @code{nil} otherwise.
-@end itemize
-
- It would be consistent and clean for completion functions to allow
-lambda expressions (lists that are functions) as well as function
-symbols as @var{collection}, but this is impossible. Lists as
-completion tables already have other meanings, and it would be
-unreliable to treat one differently just because it is also a possible
-function. So you must arrange for any function you wish to use for
-completion to be encapsulated in a symbol.
-
- Emacs uses programmed completion when completing file names.
-@xref{File Name Completion}.
-
-@defmac dynamic-completion-table function
-This macro is a convenient way to write a function that can act as
-programmed completion function. The argument @var{function} should be
-a function that takes one argument, a string, and returns an alist of
-possible completions of it. You can think of
-@code{dynamic-completion-table} as a transducer between that interface
-and the interface for programmed completion functions.
-@end defmac
-
-@node Yes-or-No Queries
-@section Yes-or-No Queries
-@cindex asking the user questions
-@cindex querying the user
-@cindex yes-or-no questions
-
- This section describes functions used to ask the user a yes-or-no
-question. The function @code{y-or-n-p} can be answered with a single
-character; it is useful for questions where an inadvertent wrong answer
-will not have serious consequences. @code{yes-or-no-p} is suitable for
-more momentous questions, since it requires three or four characters to
-answer.
-
- If either of these functions 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 ask the question. Otherwise, it
-uses keyboard input. You can force use of the mouse or use of keyboard
-input by binding @code{last-nonmenu-event} to a suitable value around
-the call.
-
- Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
-@code{y-or-n-p} does not; but it seems best to describe them together.
-
-@defun y-or-n-p prompt
-This function asks the user a question, expecting input in the echo
-area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
-user types @kbd{n}. This function also accepts @key{SPC} to mean yes
-and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like
-@kbd{C-g}, because the question might look like a minibuffer and for
-that reason the user might try to use @kbd{C-]} to get out. The answer
-is a single character, with no @key{RET} needed to terminate it. Upper
-and lower case are equivalent.
-
-``Asking the question'' means printing @var{prompt} in the echo area,
-followed by the string @w{@samp{(y or n) }}. If the input is not one of
-the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
-@kbd{@key{DEL}}, or something that quits), the function responds
-@samp{Please answer y or n.}, and repeats the request.
-
-This function does not actually use the minibuffer, since it does not
-allow editing of the answer. It actually uses the echo area (@pxref{The
-Echo Area}), which uses the same screen space as the minibuffer. The
-cursor moves to the echo area while the question is being asked.
-
-The answers and their meanings, even @samp{y} and @samp{n}, are not
-hardwired. The keymap @code{query-replace-map} specifies them.
-@xref{Search and Replace}.
-
-In the following example, the user first types @kbd{q}, which is
-invalid. At the next prompt the user types @kbd{y}.
-
-@smallexample
-@group
-(y-or-n-p "Do you need a lift? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears in the echo area:}
-@end group
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{If the user then types @kbd{q}, the following appears:}
-
-@group
----------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{When the user types a valid answer,}
-;; @r{it is displayed after the question:}
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n) y
----------- Echo area ----------
-@end group
-@end smallexample
-
-@noindent
-We show successive lines of echo area messages, but only one actually
-appears on the screen at a time.
-@end defun
-
-@defun y-or-n-p-with-timeout prompt seconds default-value
-Like @code{y-or-n-p}, except that if the user fails to answer within
-@var{seconds} seconds, this function stops waiting and returns
-@var{default-value}. It works by setting up a timer; see @ref{Timers}.
-The argument @var{seconds} may be an integer or a floating point number.
-@end defun
-
-@defun yes-or-no-p prompt
-This function asks the user a question, expecting input in the
-minibuffer. It returns @code{t} if the user enters @samp{yes},
-@code{nil} if the user types @samp{no}. The user must type @key{RET} to
-finalize the response. Upper and lower case are equivalent.
-
-@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
-followed by @w{@samp{(yes or no) }}. The user must type one of the
-expected responses; otherwise, the function responds @samp{Please answer
-yes or no.}, waits about two seconds and repeats the request.
-
-@code{yes-or-no-p} requires more work from the user than
-@code{y-or-n-p} and is appropriate for more crucial decisions.
-
-Here is an example:
-
-@smallexample
-@group
-(yes-or-no-p "Do you really want to remove everything? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
-;; @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: minibuffer ----------
-Do you really want to remove everything? (yes or no)
----------- Buffer: minibuffer ----------
-@end group
-@end smallexample
-
-@noindent
-If the user first types @kbd{y @key{RET}}, which is invalid because this
-function demands the entire word @samp{yes}, it responds by displaying
-these prompts, with a brief pause between them:
-
-@smallexample
-@group
----------- Buffer: minibuffer ----------
-Please answer yes or no.
-Do you really want to remove everything? (yes or no)
----------- Buffer: minibuffer ----------
-@end group
-@end smallexample
-@end defun
-
-@node Multiple Queries
-@section Asking Multiple Y-or-N Questions
-
- When you have a series of similar questions to ask, such as ``Do you
-want to save this buffer'' for each buffer in turn, you should use
-@code{map-y-or-n-p} to ask the collection of questions, rather than
-asking each question individually. This gives the user certain
-convenient facilities such as the ability to answer the whole series at
-once.
-
-@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
-This function asks the user a series of questions, reading a
-single-character answer in the echo area for each one.
-
-The value of @var{list} specifies the objects to ask questions about.
-It should be either a list of objects or a generator function. If it is
-a function, it should expect no arguments, and should return either the
-next object to ask about, or @code{nil} meaning stop asking questions.
-
-The argument @var{prompter} specifies how to ask each question. If
-@var{prompter} is a string, the question text is computed like this:
-
-@example
-(format @var{prompter} @var{object})
-@end example
-
-@noindent
-where @var{object} is the next object to ask about (as obtained from
-@var{list}).
-
-If not a string, @var{prompter} should be a function of one argument
-(the next object to ask about) and should return the question text. If
-the value is a string, that is the question to ask the user. The
-function can also return @code{t} meaning do act on this object (and
-don't ask the user), or @code{nil} meaning ignore this object (and don't
-ask the user).
-
-The argument @var{actor} says how to act on the answers that the user
-gives. It should be a function of one argument, and it is called with
-each object that the user says yes for. Its argument is always an
-object obtained from @var{list}.
-
-If the argument @var{help} is given, it should be a list of this form:
-
-@example
-(@var{singular} @var{plural} @var{action})
-@end example
-
-@noindent
-where @var{singular} is a string containing a singular noun that
-describes the objects conceptually being acted on, @var{plural} is the
-corresponding plural noun, and @var{action} is a transitive verb
-describing what @var{actor} does.
-
-If you don't specify @var{help}, the default is @code{("object"
-"objects" "act on")}.
-
-Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
-@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
-that object; @kbd{!} to act on all following objects; @key{ESC} or
-@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
-the current object and then exit; or @kbd{C-h} to get help. These are
-the same answers that @code{query-replace} accepts. The keymap
-@code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
-as well as for @code{query-replace}; see @ref{Search and Replace}.
-
-You can use @var{action-alist} to specify additional possible answers
-and what they mean. It is an alist of elements of the form
-@code{(@var{char} @var{function} @var{help})}, each of which defines one
-additional answer. In this element, @var{char} is a character (the
-answer); @var{function} is a function of one argument (an object from
-@var{list}); @var{help} is a string.
-
-When the user responds with @var{char}, @code{map-y-or-n-p} calls
-@var{function}. If it returns non-@code{nil}, the object is considered
-``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
-@var{list}. If it returns @code{nil}, the prompt is repeated for the
-same object.
-
-Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
-prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
-does not do that.
-
-If @code{map-y-or-n-p} 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 ask the question. In this case, it does not use
-keyboard input or the echo area. You can force use of the mouse or use
-of keyboard input by binding @code{last-nonmenu-event} to a suitable
-value around the call.
-
-The return value of @code{map-y-or-n-p} is the number of objects acted on.
-@end defun
-
-@node Reading a Password
-@section Reading a Password
-@cindex passwords, reading
-
- To read a password to pass to another program, you can use the
-function @code{read-passwd}.
-
-@defun read-passwd prompt &optional confirm default
-This function reads a password, prompting with @var{prompt}. It does
-not echo the password as the user types it; instead, it echoes @samp{.}
-for each character in the password.
-
-The optional argument @var{confirm}, if non-@code{nil}, says to read the
-password twice and insist it must be the same both times. If it isn't
-the same, the user has to type it over and over until the last two
-times match.
-
-The optional argument @var{default} specifies the default password to
-return if the user enters empty input. If @var{default} is @code{nil},
-then @code{read-passwd} returns the null string in that case.
-@end defun
-
-@node Minibuffer Commands
-@section Minibuffer Commands
-
- This section describes some commands meant for use in the
-minibuffer.
-
-@deffn Command exit-minibuffer
-This command exits the active minibuffer. It is normally bound to
-keys in minibuffer local keymaps.
-@end deffn
-
-@deffn Command self-insert-and-exit
-This command exits the active minibuffer after inserting the last
-character typed on the keyboard (found in @code{last-command-char};
-@pxref{Command Loop Info}).
-@end deffn
-
-@deffn Command previous-history-element n
-This command replaces the minibuffer contents with the value of the
-@var{n}th previous (older) history element.
-@end deffn
-
-@deffn Command next-history-element n
-This command replaces the minibuffer contents with the value of the
-@var{n}th more recent history element.
-@end deffn
-
-@deffn Command previous-matching-history-element pattern n
-This command replaces the minibuffer contents with the value of the
-@var{n}th previous (older) history element that matches @var{pattern} (a
-regular expression).
-@end deffn
-
-@deffn Command next-matching-history-element pattern n
-This command replaces the minibuffer contents with the value of the
-@var{n}th next (newer) history element that matches @var{pattern} (a
-regular expression).
-@end deffn
-
-@node Minibuffer Windows
-@section Minibuffer Windows
-@cindex minibuffer windows
-
- These functions access and select minibuffer windows
-and test whether they are active.
-
-@defun active-minibuffer-window
-This function returns the currently active minibuffer window, or
-@code{nil} if none is currently active.
-@end defun
-
-@defun minibuffer-window &optional frame
-@anchor{Definition of minibuffer-window}
-This function returns the minibuffer window used for frame @var{frame}.
-If @var{frame} is @code{nil}, that stands for the current frame. Note
-that the minibuffer window used by a frame need not be part of that
-frame---a frame that has no minibuffer of its own necessarily uses some
-other frame's minibuffer window.
-@end defun
-
-@defun set-minibuffer-window window
-This function specifies @var{window} as the minibuffer window to use.
-This affects where the minibuffer is displayed if you put text in it
-without invoking the usual minibuffer commands. It has no effect on
-the usual minibuffer input functions because they all start by
-choosing the minibuffer window according to the current frame.
-@end defun
-
-@c Emacs 19 feature
-@defun window-minibuffer-p &optional window
-This function returns non-@code{nil} if @var{window} is a minibuffer
-window.
-@var{window} defaults to the selected window.
-@end defun
-
-It is not correct to determine whether a given window is a minibuffer by
-comparing it with the result of @code{(minibuffer-window)}, because
-there can be more than one minibuffer window if there is more than one
-frame.
-
-@defun minibuffer-window-active-p window
-This function returns non-@code{nil} if @var{window}, assumed to be
-a minibuffer window, is currently active.
-@end defun
-
-@node Minibuffer Contents
-@section Minibuffer Contents
-
- These functions access the minibuffer prompt and contents.
-
-@defun minibuffer-prompt
-This function returns the prompt string of the currently active
-minibuffer. If no minibuffer is active, it returns @code{nil}.
-@end defun
-
-@defun minibuffer-prompt-end
-This function returns the current
-position of the end of the minibuffer prompt, if a minibuffer is
-current. Otherwise, it returns the minimum valid buffer position.
-@end defun
-
-@defun minibuffer-prompt-width
-This function returns the current display-width of the minibuffer
-prompt, if a minibuffer is current. Otherwise, it returns zero.
-@end defun
-
-@defun minibuffer-contents
-This function returns the editable
-contents of the minibuffer (that is, everything except the prompt) as
-a string, if a minibuffer is current. Otherwise, it returns the
-entire contents of the current buffer.
-@end defun
-
-@defun minibuffer-contents-no-properties
-This is like @code{minibuffer-contents}, except that it does not copy text
-properties, just the characters themselves. @xref{Text Properties}.
-@end defun
-
-@defun minibuffer-completion-contents
-This is like @code{minibuffer-contents}, except that it returns only
-the contents before point. That is the part that completion commands
-operate on. @xref{Minibuffer Completion}.
-@end defun
-
-@defun delete-minibuffer-contents
-This function erases the editable contents of the minibuffer (that is,
-everything except the prompt), if a minibuffer is current. Otherwise,
-it erases the entire current buffer.
-@end defun
-
-@node Recursive Mini
-@section Recursive Minibuffers
-@cindex recursive minibuffers
-
- These functions and variables deal with recursive minibuffers
-(@pxref{Recursive Editing}):
-
-@defun minibuffer-depth
-This function returns the current depth of activations of the
-minibuffer, a nonnegative integer. If no minibuffers are active, it
-returns zero.
-@end defun
-
-@defopt enable-recursive-minibuffers
-If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while the minibuffer window
-is active. Such invocation produces a recursive editing level for a new
-minibuffer. The outer-level minibuffer is invisible while you are
-editing the inner one.
-
-If this variable is @code{nil}, you cannot invoke minibuffer
-commands when the minibuffer window is active, not even if you switch to
-another window to do it.
-@end defopt
-
-@c Emacs 19 feature
-If a command name has a property @code{enable-recursive-minibuffers}
-that is non-@code{nil}, then the command can use the minibuffer to read
-arguments even if it is invoked from the minibuffer. A command can
-also achieve this by binding @code{enable-recursive-minibuffers}
-to @code{t} in the interactive declaration (@pxref{Using Interactive}).
-The minibuffer command @code{next-matching-history-element} (normally
-@kbd{M-s} in the minibuffer) does the latter.
-
-@node Minibuffer Misc
-@section Minibuffer Miscellany
-
-@defun minibufferp &optional buffer-or-name
-This function returns non-@code{nil} if @var{buffer-or-name} is a
-minibuffer. If @var{buffer-or-name} is omitted, it tests the current
-buffer.
-@end defun
-
-@defvar minibuffer-setup-hook
-This is a normal hook that is run whenever the minibuffer is entered.
-@xref{Hooks}.
-@end defvar
-
-@defvar minibuffer-exit-hook
-This is a normal hook that is run whenever the minibuffer is exited.
-@xref{Hooks}.
-@end defvar
-
-@defvar minibuffer-help-form
-@anchor{Definition of minibuffer-help-form}
-The current value of this variable is used to rebind @code{help-form}
-locally inside the minibuffer (@pxref{Help Functions}).
-@end defvar
-
-@defvar minibuffer-scroll-window
-@anchor{Definition of minibuffer-scroll-window}
-If the value of this variable is non-@code{nil}, it should be a window
-object. When the function @code{scroll-other-window} is called in the
-minibuffer, it scrolls this window.
-@end defvar
-
-@defun minibuffer-selected-window
-This function returns the window which was selected when the
-minibuffer was entered. If selected window is not a minibuffer
-window, it returns @code{nil}.
-@end defun
-
-@defopt max-mini-window-height
-This variable specifies the maximum height for resizing minibuffer
-windows. If a float, it specifies a fraction of the height of the
-frame. If an integer, it specifies a number of lines.
-@end defopt
-
-@defun minibuffer-message string
-This function displays @var{string} temporarily at the end of the
-minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.
-@end defun
-
-@ignore
- arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
-@end ignore
+++ /dev/null
-#! /bin/sh
-# mkinstalldirs --- make directory hierarchy
-# Author: Noah Friedman <friedman@prep.ai.mit.edu>
-# Created: 1993-05-16
-# Public domain
-
-errstatus=0
-
-for file
-do
- set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'`
- shift
-
- pathcomp=
- for d
- do
- pathcomp="$pathcomp$d"
- case "$pathcomp" in
- -* ) pathcomp=./$pathcomp ;;
- esac
-
- if test ! -d "$pathcomp"; then
- echo "mkdir $pathcomp" 1>&2
-
- mkdir "$pathcomp" || lasterr=$?
-
- if test ! -d "$pathcomp"; then
- errstatus=$lasterr
- fi
- fi
-
- pathcomp="$pathcomp/"
- done
-done
-
-exit $errstatus
-
-# mkinstalldirs ends here
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/modes
-@node Modes, Documentation, Keymaps, Top
-@chapter Major and Minor Modes
-@cindex mode
-
- A @dfn{mode} is a set of definitions that customize Emacs and can be
-turned on and off while you edit. There are two varieties of modes:
-@dfn{major modes}, which are mutually exclusive and used for editing
-particular kinds of text, and @dfn{minor modes}, which provide features
-that users can enable individually.
-
- This chapter describes how to write both major and minor modes, how to
-indicate them in the mode line, and how they run hooks supplied by the
-user. For related topics such as keymaps and syntax tables, see
-@ref{Keymaps}, and @ref{Syntax Tables}.
-
-@menu
-* 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.
-@end menu
-
-@node Hooks
-@section Hooks
-@cindex hooks
-
- A @dfn{hook} is a variable where you can store a function or functions
-to be called on a particular occasion by an existing program. Emacs
-provides hooks for the sake of customization. Most often, hooks are set
-up in the init file (@pxref{Init File}), but Lisp programs can set them also.
-@xref{Standard Hooks}, for a list of standard hook variables.
-
-@cindex normal hook
- Most of the hooks in Emacs are @dfn{normal hooks}. These variables
-contain lists of functions to be called with no arguments. By
-convention, whenever the hook name ends in @samp{-hook}, that tells
-you it is normal. We try to make all hooks normal, as much as
-possible, so that you can use them in a uniform way.
-
- Every major mode function is supposed to run a normal hook called
-the @dfn{mode hook} as the one of the last steps of initialization.
-This makes it easy for a user to customize the behavior of the mode,
-by overriding the buffer-local variable assignments already made by
-the mode. Most minor mode functions also run a mode hook at the end.
-But hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
-
- The recommended way to add a hook function to a normal hook is by
-calling @code{add-hook} (see below). The hook functions may be any of
-the valid kinds of functions that @code{funcall} accepts (@pxref{What
-Is a Function}). Most normal hook variables are initially void;
-@code{add-hook} knows how to deal with this. You can add hooks either
-globally or buffer-locally with @code{add-hook}.
-
-@cindex abnormal hook
- If the hook variable's name does not end with @samp{-hook}, that
-indicates it is probably an @dfn{abnormal hook}. That means the hook
-functions are called with arguments, or their return values are used
-in some way. The hook's documentation says how the functions are
-called. You can use @code{add-hook} to add a function to an abnormal
-hook, but you must write the function to follow the hook's calling
-convention.
-
- By convention, abnormal hook names end in @samp{-functions} or
-@samp{-hooks}. If the variable's name ends in @samp{-function}, then
-its value is just a single function, not a list of functions.
-
- Here's an example that uses a mode hook to turn on Auto Fill mode when
-in Lisp Interaction mode:
-
-@example
-(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
-@end example
-
- At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks.
-
-@defun run-hooks &rest hookvars
-This function takes one or more normal hook variable names as
-arguments, and runs each hook in turn. Each argument should be a
-symbol that is a normal hook variable. These arguments are processed
-in the order specified.
-
-If a hook variable has a non-@code{nil} value, that value should be a
-list of functions. @code{run-hooks} calls all the functions, one by
-one, with no arguments.
-
-The hook variable's value can also be a single function---either a
-lambda expression or a symbol with a function definition---which
-@code{run-hooks} calls. But this usage is obsolete.
-@end defun
-
-@defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook and always call all
-of the hook functions. It calls each of the hook functions one by
-one, passing each of them the arguments @var{args}.
-@end defun
-
-@defun run-hook-with-args-until-failure hook &rest args
-This function is the way to run an abnormal hook until one of the hook
-functions fails. It calls each of the hook functions, passing each of
-them the arguments @var{args}, until some hook function returns
-@code{nil}. It then stops and returns @code{nil}. If none of the
-hook functions return @code{nil}, it returns a non-@code{nil} value.
-@end defun
-
-@defun run-hook-with-args-until-success hook &rest args
-This function is the way to run an abnormal hook until a hook function
-succeeds. It calls each of the hook functions, passing each of them
-the arguments @var{args}, until some hook function returns
-non-@code{nil}. Then it stops, and returns whatever was returned by
-the last hook function that was called. If all hook functions return
-@code{nil}, it returns @code{nil} as well.
-@end defun
-
-@defun add-hook hook function &optional append local
-This function is the handy way to add function @var{function} to hook
-variable @var{hook}. You can use it for abnormal hooks as well as for
-normal hooks. @var{function} can be any Lisp function that can accept
-the proper number of arguments for @var{hook}. For example,
-
-@example
-(add-hook 'text-mode-hook 'my-text-hook-function)
-@end example
-
-@noindent
-adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
-
-If @var{function} is already present in @var{hook} (comparing using
-@code{equal}), then @code{add-hook} does not add it a second time.
-
-It is best to design your hook functions so that the order in which they
-are executed does not matter. Any dependence on the order is ``asking
-for trouble.'' However, the order is predictable: normally,
-@var{function} goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call). If the optional
-argument @var{append} is non-@code{nil}, the new hook function goes at
-the end of the hook list and will be executed last.
-
-@code{add-hook} can handle the cases where @var{hook} is void or its
-value is a single function; it sets or changes the value to a list of
-functions.
-
-If @var{local} is non-@code{nil}, that says to add @var{function} to
-the buffer-local hook list instead of to the global hook list. If
-needed, this makes the hook buffer-local and adds @code{t} to the
-buffer-local value. The latter acts as a flag to run the hook
-functions in the default value as well as in the local value.
-@end defun
-
-@defun remove-hook hook function &optional local
-This function removes @var{function} from the hook variable
-@var{hook}. It compares @var{function} with elements of @var{hook}
-using @code{equal}, so it works for both symbols and lambda
-expressions.
-
-If @var{local} is non-@code{nil}, that says to remove @var{function}
-from the buffer-local hook list instead of from the global hook list.
-@end defun
-
-@node Major Modes
-@section Major Modes
-@cindex major mode
-
- Major modes specialize Emacs for editing particular kinds of text.
-Each buffer has only one major mode at a time. For each major mode
-there is a function to switch to that mode in the current buffer; its
-name should end in @samp{-mode}. These functions work by setting
-buffer-local variable bindings and other data associated with the
-buffer, such as a local keymap. The effect lasts until you switch
-to another major mode in the same buffer.
-
-@menu
-* Major Mode Basics::
-* Major Mode Conventions:: Coding conventions for keymaps, etc.
-* 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.
-* Example Major Modes:: Text mode and Lisp modes.
-@end menu
-
-@node Major Mode Basics
-@subsection Major Mode Basics
-@cindex Fundamental mode
-
- The least specialized major mode is called @dfn{Fundamental mode}.
-This mode has no mode-specific definitions or variable settings, so each
-Emacs command behaves in its default manner, and each option is in its
-default state. All other major modes redefine various keys and options.
-For example, Lisp Interaction mode provides special key bindings for
-@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
-(@code{lisp-indent-line}), and other keys.
-
- When you need to write several editing commands to help you perform a
-specialized editing task, creating a new major mode is usually a good
-idea. In practice, writing a major mode is easy (in contrast to
-writing a minor mode, which is often difficult).
-
- If the new mode is similar to an old one, it is often unwise to
-modify the old one to serve two purposes, since it may become harder
-to use and maintain. Instead, copy and rename an existing major mode
-definition and alter the copy---or use @code{define-derived-mode} to
-define a @dfn{derived mode} (@pxref{Derived Modes}). For example,
-Rmail Edit mode is a major mode that is very similar to Text mode
-except that it provides two additional commands. Its definition is
-distinct from that of Text mode, but uses that of Text mode.
-
- Even if the new mode is not an obvious derivative of any other mode,
-it is convenient to use @code{define-derived-mode} with a @code{nil}
-parent argument, since it automatically enforces the most important
-coding conventions for you.
-
- For a very simple programming language major mode that handles
-comments and fontification, you can use @code{define-generic-mode}.
-@xref{Generic Modes}.
-
- Rmail Edit mode offers an example of changing the major mode
-temporarily for a buffer, so it can be edited in a different way (with
-ordinary Emacs commands rather than Rmail commands). In such cases, the
-temporary major mode usually provides a command to switch back to the
-buffer's usual mode (Rmail mode, in this case). You might be tempted to
-present the temporary redefinitions inside a recursive edit and restore
-the usual ones when the user exits; but this is a bad idea because it
-constrains the user's options when it is done in more than one buffer:
-recursive edits must be exited most-recently-entered first. Using an
-alternative major mode avoids this limitation. @xref{Recursive
-Editing}.
-
- The standard GNU Emacs Lisp library directory tree contains the code
-for several major modes, in files such as @file{text-mode.el},
-@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
-@file{rmail.el}. They are found in various subdirectories of the
-@file{lisp} directory. You can study these libraries to see how modes
-are written. Text mode is perhaps the simplest major mode aside from
-Fundamental mode. Rmail mode is a complicated and specialized mode.
-
-@node Major Mode Conventions
-@subsection Major Mode Conventions
-@cindex major mode conventions
-@cindex conventions for writing major modes
-
- The code for existing major modes follows various coding conventions,
-including conventions for local keymap and syntax table initialization,
-global names, and hooks. Please follow these conventions when you
-define a new major mode. (Fundamental mode is an exception to many
-of these conventions, because its definition is to present the global
-state of Emacs.)
-
- This list of conventions is only partial, because each major mode
-should aim for consistency in general with other Emacs major modes.
-This makes Emacs as a whole more coherent. It is impossible to list
-here all the possible points where this issue might come up; if the
-Emacs developers point out an area where your major mode deviates from
-the usual conventions, please make it compatible.
-
-@itemize @bullet
-@item
-Define a command whose name ends in @samp{-mode}, with no arguments,
-that switches to the new mode in the current buffer. This command
-should set up the keymap, syntax table, and buffer-local variables in an
-existing buffer, without changing the buffer's contents.
-
-@item
-Write a documentation string for this command that describes the
-special commands available in this mode. @kbd{C-h m}
-(@code{describe-mode}) in your mode will display this string.
-
-The documentation string may include the special documentation
-substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
-@samp{\<@var{keymap}>}, which enable the documentation to adapt
-automatically to the user's own key bindings. @xref{Keys in
-Documentation}.
-
-@item
-The major mode command should start by calling
-@code{kill-all-local-variables}. This runs the normal hook
-@code{change-major-mode-hook}, then gets rid of the buffer-local
-variables of the major mode previously in effect. @xref{Creating
-Buffer-Local}.
-
-@item
-The major mode command should set the variable @code{major-mode} to the
-major mode command symbol. This is how @code{describe-mode} discovers
-which documentation to print.
-
-@item
-The major mode command should set the variable @code{mode-name} to the
-``pretty'' name of the mode, as a string. This string appears in the
-mode line.
-
-@item
-@cindex functions in modes
-Since all global names are in the same name space, all the global
-variables, constants, and functions that are part of the mode should
-have names that start with the major mode name (or with an abbreviation
-of it if the name is long). @xref{Coding Conventions}.
-
-@item
-In a major mode for editing some kind of structured text, such as a
-programming language, indentation of text according to structure is
-probably useful. So the mode should set @code{indent-line-function}
-to a suitable function, and probably customize other variables
-for indentation.
-
-@item
-@cindex keymaps in modes
-The major mode should usually have its own keymap, which is used as the
-local keymap in all buffers in that mode. The major mode command should
-call @code{use-local-map} to install this local map. @xref{Active
-Keymaps}, for more information.
-
-This keymap should be stored permanently in a global variable named
-@code{@var{modename}-mode-map}. Normally the library that defines the
-mode sets this variable.
-
-@xref{Tips for Defining}, for advice about how to write the code to set
-up the mode's keymap variable.
-
-@item
-The key sequences bound in a major mode keymap should usually start with
-@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
-@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
-characters are reserved for minor modes, and ordinary letters are
-reserved for users.
-
-A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
-@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
-be some kind of ``moving forward and backward,'' but this does not
-necessarily mean cursor motion.
-
-It is legitimate for a major mode to rebind a standard key sequence if
-it provides a command that does ``the same job'' in a way better
-suited to the text this mode is used for. For example, a major mode
-for editing a programming language might redefine @kbd{C-M-a} to
-``move to the beginning of a function'' in a way that works better for
-that language.
-
-It is also legitimate for a major mode to rebind a standard key
-sequence whose standard meaning is rarely useful in that mode. For
-instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
-rarely of any use in the minibuffer. Major modes such as Dired or
-Rmail that do not allow self-insertion of text can reasonably redefine
-letters and other printing characters as special commands.
-
-@item
-Major modes modes for editing text should not define @key{RET} to do
-anything other than insert a newline. However, it is ok for
-specialized modes for text that users don't directly edit, such as
-Dired and Info modes, to redefine @key{RET} to do something entirely
-different.
-
-@item
-Major modes should not alter options that are primarily a matter of user
-preference, such as whether Auto-Fill mode is enabled. Leave this to
-each user to decide. However, a major mode should customize other
-variables so that Auto-Fill mode will work usefully @emph{if} the user
-decides to use it.
-
-@item
-@cindex syntax tables in modes
-The mode may have its own syntax table or may share one with other
-related modes. If it has its own syntax table, it should store this in
-a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
-Tables}.
-
-@item
-If the mode handles a language that has a syntax for comments, it should
-set the variables that define the comment syntax. @xref{Options for
-Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
-
-@item
-@cindex abbrev tables in modes
-The mode may have its own abbrev table or may share one with other
-related modes. If it has its own abbrev table, it should store this
-in a variable named @code{@var{modename}-mode-abbrev-table}. If the
-major mode command defines any abbrevs itself, it should pass @code{t}
-for the @var{system-flag} argument to @code{define-abbrev}.
-@xref{Defining Abbrevs}.
-
-@item
-The mode should specify how to do highlighting for Font Lock mode, by
-setting up a buffer-local value for the variable
-@code{font-lock-defaults} (@pxref{Font Lock Mode}).
-
-@item
-The mode should specify how Imenu should find the definitions or
-sections of a buffer, by setting up a buffer-local value for the
-variable @code{imenu-generic-expression}, for the two variables
-@code{imenu-prev-index-position-function} and
-@code{imenu-extract-index-name-function}, or for the variable
-@code{imenu-create-index-function} (@pxref{Imenu}).
-
-@item
-The mode can specify a local value for
-@code{eldoc-documentation-function} to tell ElDoc mode how to handle
-this mode.
-
-@item
-Use @code{defvar} or @code{defcustom} to set mode-related variables, so
-that they are not reinitialized if they already have a value. (Such
-reinitialization could discard customizations made by the user.)
-
-@item
-@cindex buffer-local variables in modes
-To make a buffer-local binding for an Emacs customization variable, use
-@code{make-local-variable} in the major mode command, not
-@code{make-variable-buffer-local}. The latter function would make the
-variable local to every buffer in which it is subsequently set, which
-would affect buffers that do not use this mode. It is undesirable for a
-mode to have such global effects. @xref{Buffer-Local Variables}.
-
-With rare exceptions, the only reasonable way to use
-@code{make-variable-buffer-local} in a Lisp package is for a variable
-which is used only within that package. Using it on a variable used by
-other packages would interfere with them.
-
-@item
-@cindex mode hook
-@cindex major mode hook
-Each major mode should have a normal @dfn{mode hook} named
-@code{@var{modename}-mode-hook}. The very last thing the major mode command
-should do is to call @code{run-mode-hooks}. This runs the mode hook,
-and then runs the normal hook @code{after-change-major-mode-hook}.
-@xref{Mode Hooks}.
-
-@item
-The major mode command may start by calling some other major mode
-command (called the @dfn{parent mode}) and then alter some of its
-settings. A mode that does this is called a @dfn{derived mode}. The
-recommended way to define one is to use @code{define-derived-mode},
-but this is not required. Such a mode should call the parent mode
-command inside a @code{delay-mode-hooks} form. (Using
-@code{define-derived-mode} does this automatically.) @xref{Derived
-Modes}, and @ref{Mode Hooks}.
-
-@item
-If something special should be done if the user switches a buffer from
-this mode to any other major mode, this mode can set up a buffer-local
-value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
-
-@item
-If this mode is appropriate only for specially-prepared text, then the
-major mode command symbol should have a property named @code{mode-class}
-with value @code{special}, put on as follows:
-
-@kindex mode-class @r{(property)}
-@cindex @code{special}
-@example
-(put 'funny-mode 'mode-class 'special)
-@end example
-
-@noindent
-This tells Emacs that new buffers created while the current buffer is
-in Funny mode should not inherit Funny mode, in case
-@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
-and Buffer List use this feature.
-
-@item
-If you want to make the new mode the default for files with certain
-recognizable names, add an element to @code{auto-mode-alist} to select
-the mode for those file names (@pxref{Auto Major Mode}). If you
-define the mode command to autoload, you should add this element in
-the same file that calls @code{autoload}. If you use an autoload
-cookie for the mode command, you can also use an autoload cookie for
-the form that adds the element (@pxref{autoload cookie}). If you do
-not autoload the mode command, it is sufficient to add the element in
-the file that contains the mode definition.
-
-@item
-In the comments that document the file, you should provide a sample
-@code{autoload} form and an example of how to add to
-@code{auto-mode-alist}, that users can include in their init files
-(@pxref{Init File}).
-
-@item
-@cindex mode loading
-The top-level forms in the file defining the mode should be written so
-that they may be evaluated more than once without adverse consequences.
-Even if you never load the file more than once, someone else will.
-@end itemize
-
-@node Auto Major Mode
-@subsection How Emacs Chooses a Major Mode
-@cindex major mode, automatic selection
-
- Based on information in the file name or in the file itself, Emacs
-automatically selects a major mode for the new buffer when a file is
-visited. It also processes local variables specified in the file text.
-
-@deffn Command fundamental-mode
- Fundamental mode is a major mode that is not specialized for anything
-in particular. Other major modes are defined in effect by comparison
-with this one---their definitions say what to change, starting from
-Fundamental mode. The @code{fundamental-mode} function does @emph{not}
-run any mode hooks; you're not supposed to customize it. (If you want Emacs
-to behave differently in Fundamental mode, change the @emph{global}
-state of Emacs.)
-@end deffn
-
-@deffn Command normal-mode &optional find-file
-This function establishes the proper major mode and buffer-local variable
-bindings for the current buffer. First it calls @code{set-auto-mode}
-(see below), then it runs @code{hack-local-variables} to parse, and
-bind or evaluate as appropriate, the file's local variables
-(@pxref{File Local Variables}).
-
-If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
-@code{normal-mode} assumes that the @code{find-file} function is calling
-it. In this case, it may process local variables in the @samp{-*-}
-line or at the end of the file. The variable
-@code{enable-local-variables} controls whether to do so. @xref{File
-Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
-for the syntax of the local variables section of a file.
-
-If you run @code{normal-mode} interactively, the argument
-@var{find-file} is normally @code{nil}. In this case,
-@code{normal-mode} unconditionally processes any file local variables.
-
-If @code{normal-mode} processes the local variables list and this list
-specifies a major mode, that mode overrides any mode chosen by
-@code{set-auto-mode}. If neither @code{set-auto-mode} nor
-@code{hack-local-variables} specify a major mode, the buffer stays in
-the major mode determined by @code{default-major-mode} (see below).
-
-@cindex file mode specification error
-@code{normal-mode} uses @code{condition-case} around the call to the
-major mode function, so errors are caught and reported as a @samp{File
-mode specification error}, followed by the original error message.
-@end deffn
-
-@defun set-auto-mode &optional keep-mode-if-same
-@cindex visited file mode
- This function selects the major mode that is appropriate for the
-current buffer. It bases its decision (in order of precedence) on
-the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
-@code{interpreter-mode-alist}), on the text at the beginning of the
-buffer (using @code{magic-mode-alist}), and finally on the visited
-file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
-Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
-function does not look for the @samp{mode:} local variable near the
-end of a file; the @code{hack-local-variables} function does that.
-If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
-does not check the @w{@samp{-*-}} line for a mode tag either.
-
-If @var{keep-mode-if-same} is non-@code{nil}, this function does not
-call the mode command if the buffer is already in the proper major
-mode. For instance, @code{set-visited-file-name} sets this to
-@code{t} to avoid killing buffer local variables that the user may
-have set.
-@end defun
-
-@defopt default-major-mode
-This variable holds the default major mode for new buffers. The
-standard value is @code{fundamental-mode}.
-
-If the value of @code{default-major-mode} is @code{nil}, Emacs uses
-the (previously) current buffer's major mode as the default major mode
-of a new buffer. However, if that major mode symbol has a @code{mode-class}
-property with value @code{special}, then it is not used for new buffers;
-Fundamental mode is used instead. The modes that have this property are
-those such as Dired and Rmail that are useful only with text that has
-been specially prepared.
-@end defopt
-
-@defun set-buffer-major-mode buffer
-This function sets the major mode of @var{buffer} to the value of
-@code{default-major-mode}; if that variable is @code{nil}, it uses the
-current buffer's major mode (if that is suitable). As an exception,
-if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
-@code{initial-major-mode}.
-
-The low-level primitives for creating buffers do not use this function,
-but medium-level commands such as @code{switch-to-buffer} and
-@code{find-file-noselect} use it whenever they create buffers.
-@end defun
-
-@defopt initial-major-mode
-@cindex @samp{*scratch*}
-The value of this variable determines the major mode of the initial
-@samp{*scratch*} buffer. The value should be a symbol that is a major
-mode command. The default value is @code{lisp-interaction-mode}.
-@end defopt
-
-@defvar interpreter-mode-alist
-This variable specifies major modes to use for scripts that specify a
-command interpreter in a @samp{#!} line. Its value is an alist with
-elements of the form @code{(@var{interpreter} . @var{mode})}; for
-example, @code{("perl" . perl-mode)} is one element present by
-default. The element says to use mode @var{mode} if the file
-specifies an interpreter which matches @var{interpreter}.
-@end defvar
-
-@defvar magic-mode-alist
-This variable's value is an alist with elements of the form
-@code{(@var{regexp} . @var{function})}, where @var{regexp} is a
-regular expression and @var{function} is a function or @code{nil}.
-After visiting a file, @code{set-auto-mode} calls @var{function} if
-the text at the beginning of the buffer matches @var{regexp} and
-@var{function} is non-@code{nil}; if @var{function} is @code{nil},
-@code{auto-mode-alist} gets to decide the mode.
-@end defvar
-
-@defvar magic-fallback-mode-alist
-This works like @code{magic-mode-alist}, except that it is handled
-only if @code{auto-mode-alist} does not specify a mode for this file.
-@end defvar
-
-@defvar auto-mode-alist
-This variable contains an association list of file name patterns
-(regular expressions) and corresponding major mode commands. Usually,
-the file name patterns test for suffixes, such as @samp{.el} and
-@samp{.c}, but this need not be the case. An ordinary element of the
-alist looks like @code{(@var{regexp} . @var{mode-function})}.
-
-For example,
-
-@smallexample
-@group
-(("\\`/tmp/fol/" . text-mode)
- ("\\.texinfo\\'" . texinfo-mode)
- ("\\.texi\\'" . texinfo-mode)
-@end group
-@group
- ("\\.el\\'" . emacs-lisp-mode)
- ("\\.c\\'" . c-mode)
- ("\\.h\\'" . c-mode)
- @dots{})
-@end group
-@end smallexample
-
-When you visit a file whose expanded file name (@pxref{File Name
-Expansion}), with version numbers and backup suffixes removed using
-@code{file-name-sans-versions} (@pxref{File Name Components}), matches
-a @var{regexp}, @code{set-auto-mode} calls the corresponding
-@var{mode-function}. This feature enables Emacs to select the proper
-major mode for most files.
-
-If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
-@var{function} t)}, then after calling @var{function}, Emacs searches
-@code{auto-mode-alist} again for a match against the portion of the file
-name that did not match before. This feature is useful for
-uncompression packages: an entry of the form @code{("\\.gz\\'"
-@var{function} t)} can uncompress the file and then put the uncompressed
-file in the proper mode according to the name sans @samp{.gz}.
-
-Here is an example of how to prepend several pattern pairs to
-@code{auto-mode-alist}. (You might use this sort of expression in your
-init file.)
-
-@smallexample
-@group
-(setq auto-mode-alist
- (append
- ;; @r{File name (within directory) starts with a dot.}
- '(("/\\.[^/]*\\'" . fundamental-mode)
- ;; @r{File name has no dot.}
- ("[^\\./]*\\'" . fundamental-mode)
- ;; @r{File name ends in @samp{.C}.}
- ("\\.C\\'" . c++-mode))
- auto-mode-alist))
-@end group
-@end smallexample
-@end defvar
-
-@node Mode Help
-@subsection Getting Help about a Major Mode
-@cindex mode help
-@cindex help for major mode
-@cindex documentation for major mode
-
- The @code{describe-mode} function is used to provide information
-about major modes. It is normally called with @kbd{C-h m}. The
-@code{describe-mode} function uses the value of @code{major-mode},
-which is why every major mode function needs to set the
-@code{major-mode} variable.
-
-@deffn Command describe-mode
-This function displays the documentation of the current major mode.
-
-The @code{describe-mode} function calls the @code{documentation}
-function using the value of @code{major-mode} as an argument. Thus, it
-displays the documentation string of the major mode function.
-(@xref{Accessing Documentation}.)
-@end deffn
-
-@defvar major-mode
-This buffer-local variable holds the symbol for the current buffer's
-major mode. This symbol should have a function definition that is the
-command to switch to that major mode. The @code{describe-mode}
-function uses the documentation string of the function as the
-documentation of the major mode.
-@end defvar
-
-@node Derived Modes
-@subsection Defining Derived Modes
-@cindex derived mode
-
- It's often useful to define a new major mode in terms of an existing
-one. An easy way to do this is to use @code{define-derived-mode}.
-
-@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
-This construct defines @var{variant} as a major mode command, using
-@var{name} as the string form of the mode name. @var{variant} and
-@var{parent} should be unquoted symbols.
-
-The new command @var{variant} is defined to call the function
-@var{parent}, then override certain aspects of that parent mode:
-
-@itemize @bullet
-@item
-The new mode has its own sparse keymap, named
-@code{@var{variant}-map}. @code{define-derived-mode}
-makes the parent mode's keymap the parent of the new map, unless
-@code{@var{variant}-map} is already set and already has a parent.
-
-@item
-The new mode has its own syntax table, kept in the variable
-@code{@var{variant}-syntax-table}, unless you override this using the
-@code{:syntax-table} keyword (see below). @code{define-derived-mode}
-makes the parent mode's syntax-table the parent of
-@code{@var{variant}-syntax-table}, unless the latter is already set
-and already has a parent different from the standard syntax table.
-
-@item
-The new mode has its own abbrev table, kept in the variable
-@code{@var{variant}-abbrev-table}, unless you override this using the
-@code{:abbrev-table} keyword (see below).
-
-@item
-The new mode has its own mode hook, @code{@var{variant}-hook}. It
-runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
-@end itemize
-
-In addition, you can specify how to override other aspects of
-@var{parent} with @var{body}. The command @var{variant}
-evaluates the forms in @var{body} after setting up all its usual
-overrides, just before running the mode hooks.
-
-You can also specify @code{nil} for @var{parent}. This gives the new
-mode no parent. Then @code{define-derived-mode} behaves as described
-above, but, of course, omits all actions connected with @var{parent}.
-
-The argument @var{docstring} specifies the documentation string for
-the new mode. @code{define-derived-mode} adds some general
-information about the mode's hook, followed by the mode's keymap, at
-the end of this docstring. If you omit @var{docstring},
-@code{define-derived-mode} generates a documentation string.
-
-The @var{keyword-args} are pairs of keywords and values. The values
-are evaluated. The following keywords are currently supported:
-
-@table @code
-@item :syntax-table
-You can use this to explicitly specify a syntax table for the new
-mode. If you specify a @code{nil} value, the new mode uses the same
-syntax table as @var{parent}, or the standard syntax table if
-@var{parent} is @code{nil}. (Note that this does @emph{not} follow
-the convention used for non-keyword arguments that a @code{nil} value
-is equivalent with not specifying the argument.)
-
-@item :abbrev-table
-You can use this to explicitly specify an abbrev table for the new
-mode. If you specify a @code{nil} value, the new mode uses the same
-abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
-if @var{parent} is @code{nil}. (Again, a @code{nil} value is
-@emph{not} equivalent to not specifying this keyword.)
-
-@item :group
-If this is specified, the value should be the customization group for
-this mode. (Not all major modes have one.) Only the (still
-experimental and unadvertised) command @code{customize-mode} currently
-uses this. @code{define-derived-mode} does @emph{not} automatically
-define the specified customization group.
-@end table
-
-Here is a hypothetical example:
-
-@example
-(define-derived-mode hypertext-mode
- text-mode "Hypertext"
- "Major mode for hypertext.
-\\@{hypertext-mode-map@}"
- (setq case-fold-search nil))
-
-(define-key hypertext-mode-map
- [down-mouse-3] 'do-hyper-link)
-@end example
-
-Do not write an @code{interactive} spec in the definition;
-@code{define-derived-mode} does that automatically.
-@end defmac
-
-@node Generic Modes
-@subsection Generic Modes
-@cindex generic mode
-
- @dfn{Generic modes} are simple major modes with basic support for
-comment syntax and Font Lock mode. To define a generic mode, use the
-macro @code{define-generic-mode}. See the file @file{generic-x.el}
-for some examples of the use of @code{define-generic-mode}.
-
-@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
-This macro defines a generic mode command named @var{mode} (a symbol,
-not quoted). The optional argument @var{docstring} is the
-documentation for the mode command. If you do not supply it,
-@code{define-generic-mode} generates one by default.
-
-The argument @var{comment-list} is a list in which each element is
-either a character, a string of one or two characters, or a cons cell.
-A character or a string is set up in the mode's syntax table as a
-``comment starter.'' If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
-(Use @code{nil} for the latter if you want comments to end at the end
-of the line.) Note that the syntax table mechanism has limitations
-about what comment starters and enders are actually possible.
-@xref{Syntax Tables}.
-
-The argument @var{keyword-list} is a list of keywords to highlight
-with @code{font-lock-keyword-face}. Each keyword should be a string.
-Meanwhile, @var{font-lock-list} is a list of additional expressions to
-highlight. Each element of this list should have the same form as an
-element of @code{font-lock-keywords}. @xref{Search-based
-Fontification}.
-
-The argument @var{auto-mode-list} is a list of regular expressions to
-add to the variable @code{auto-mode-alist}. They are added by the execution
-of the @code{define-generic-mode} form, not by expanding the macro call.
-
-Finally, @var{function-list} is a list of functions for the mode
-command to call for additional setup. It calls these functions just
-before it runs the mode hook variable @code{@var{mode}-hook}.
-@end defmac
-
-@node Mode Hooks
-@subsection Mode Hooks
-
- Every major mode function should finish by running its mode hook and
-the mode-independent normal hook @code{after-change-major-mode-hook}.
-It does this by calling @code{run-mode-hooks}. If the major mode is a
-derived mode, that is if it calls another major mode (the parent mode)
-in its body, it should do this inside @code{delay-mode-hooks} so that
-the parent won't run these hooks itself. Instead, the derived mode's
-call to @code{run-mode-hooks} runs the parent's mode hook too.
-@xref{Major Mode Conventions}.
-
- Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
-When user-implemented major modes have not been updated to use it,
-they won't entirely follow these conventions: they may run the
-parent's mode hook too early, or fail to run
-@code{after-change-major-mode-hook}. If you encounter such a major
-mode, please correct it to follow these conventions.
-
- When you defined a major mode using @code{define-derived-mode}, it
-automatically makes sure these conventions are followed. If you
-define a major mode ``by hand,'' not using @code{define-derived-mode},
-use the following functions to handle these conventions automatically.
-
-@defun run-mode-hooks &rest hookvars
-Major modes should run their mode hook using this function. It is
-similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
-@code{after-change-major-mode-hook}.
-
-When this function is called during the execution of a
-@code{delay-mode-hooks} form, it does not run the hooks immediately.
-Instead, it arranges for the next call to @code{run-mode-hooks} to run
-them.
-@end defun
-
-@defmac delay-mode-hooks body@dots{}
-When one major mode command calls another, it should do so inside of
-@code{delay-mode-hooks}.
-
-This macro executes @var{body}, but tells all @code{run-mode-hooks}
-calls during the execution of @var{body} to delay running their hooks.
-The hooks will actually run during the next call to
-@code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
-construct.
-@end defmac
-
-@defvar after-change-major-mode-hook
-This is a normal hook run by @code{run-mode-hooks}. It is run at the
-very end of every properly-written major mode function.
-@end defvar
-
-@node Example Major Modes
-@subsection Major Mode Examples
-
- Text mode is perhaps the simplest mode besides Fundamental mode.
-Here are excerpts from @file{text-mode.el} that illustrate many of
-the conventions listed above:
-
-@smallexample
-@group
-;; @r{Create the syntax table for this mode.}
-(defvar text-mode-syntax-table
- (let ((st (make-syntax-table)))
- (modify-syntax-entry ?\" ". " st)
- (modify-syntax-entry ?\\ ". " st)
- ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
- (modify-syntax-entry ?' "w p" st)
- st)
- "Syntax table used while in `text-mode'.")
-@end group
-
-;; @r{Create the keymap for this mode.}
-@group
-(defvar text-mode-map
- (let ((map (make-sparse-keymap)))
- (define-key map "\e\t" 'ispell-complete-word)
- (define-key map "\es" 'center-line)
- (define-key map "\eS" 'center-paragraph)
- map)
- "Keymap for `text-mode'.
-Many other modes, such as Mail mode, Outline mode
-and Indented Text mode, inherit all the commands
-defined in this map.")
-@end group
-@end smallexample
-
- Here is how the actual mode command is defined now:
-
-@smallexample
-@group
-(define-derived-mode text-mode nil "Text"
- "Major mode for editing text written for humans to read.
-In this mode, paragraphs are delimited only by blank or white lines.
-You can thus get the full benefit of adaptive filling
- (see the variable `adaptive-fill-mode').
-\\@{text-mode-map@}
-Turning on Text mode runs the normal hook `text-mode-hook'."
-@end group
-@group
- (make-local-variable 'text-mode-variant)
- (setq text-mode-variant t)
- ;; @r{These two lines are a feature added recently.}
- (set (make-local-variable 'require-final-newline)
- mode-require-final-newline)
- (set (make-local-variable 'indent-line-function) 'indent-relative))
-@end group
-@end smallexample
-
-@noindent
-(The last line is redundant nowadays, since @code{indent-relative} is
-the default value, and we'll delete it in a future version.)
-
- Here is how it was defined formerly, before
-@code{define-derived-mode} existed:
-
-@smallexample
-@group
-;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
-(defvar text-mode-abbrev-table nil
- "Abbrev table used while in text mode.")
-(define-abbrev-table 'text-mode-abbrev-table ())
-@end group
-
-@group
-(defun text-mode ()
- "Major mode for editing text intended for humans to read...
- Special commands: \\@{text-mode-map@}
-@end group
-@group
-Turning on text-mode runs the hook `text-mode-hook'."
- (interactive)
- (kill-all-local-variables)
- (use-local-map text-mode-map)
-@end group
-@group
- (setq local-abbrev-table text-mode-abbrev-table)
- (set-syntax-table text-mode-syntax-table)
-@end group
-@group
- ;; @r{These four lines are absent from the current version}
- ;; @r{not because this is done some other way, but rather}
- ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
- (make-local-variable 'paragraph-start)
- (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
- (make-local-variable 'paragraph-separate)
- (setq paragraph-separate paragraph-start)
- (make-local-variable 'indent-line-function)
- (setq indent-line-function 'indent-relative-maybe)
-@end group
-@group
- (setq mode-name "Text")
- (setq major-mode 'text-mode)
- (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
- ; @r{customize the mode with a hook.}
-@end group
-@end smallexample
-
-@cindex @file{lisp-mode.el}
- The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
-Interaction mode) have more features than Text mode and the code is
-correspondingly more complicated. Here are excerpts from
-@file{lisp-mode.el} that illustrate how these modes are written.
-
-@cindex syntax table example
-@smallexample
-@group
-;; @r{Create mode-specific table variables.}
-(defvar lisp-mode-syntax-table nil "")
-(defvar lisp-mode-abbrev-table nil "")
-@end group
-
-@group
-(defvar emacs-lisp-mode-syntax-table
- (let ((table (make-syntax-table)))
- (let ((i 0))
-@end group
-
-@group
- ;; @r{Set syntax of chars up to @samp{0} to say they are}
- ;; @r{part of symbol names but not words.}
- ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
- (while (< i ?0)
- (modify-syntax-entry i "_ " table)
- (setq i (1+ i)))
- ;; @r{@dots{} similar code follows for other character ranges.}
-@end group
-@group
- ;; @r{Then set the syntax codes for characters that are special in Lisp.}
- (modify-syntax-entry ? " " table)
- (modify-syntax-entry ?\t " " table)
- (modify-syntax-entry ?\f " " table)
- (modify-syntax-entry ?\n "> " table)
-@end group
-@group
- ;; @r{Give CR the same syntax as newline, for selective-display.}
- (modify-syntax-entry ?\^m "> " table)
- (modify-syntax-entry ?\; "< " table)
- (modify-syntax-entry ?` "' " table)
- (modify-syntax-entry ?' "' " table)
- (modify-syntax-entry ?, "' " table)
-@end group
-@group
- ;; @r{@dots{}likewise for many other characters@dots{}}
- (modify-syntax-entry ?\( "() " table)
- (modify-syntax-entry ?\) ")( " table)
- (modify-syntax-entry ?\[ "(] " table)
- (modify-syntax-entry ?\] ")[ " table))
- table))
-@end group
-@group
-;; @r{Create an abbrev table for lisp-mode.}
-(define-abbrev-table 'lisp-mode-abbrev-table ())
-@end group
-@end smallexample
-
- The three modes for Lisp share much of their code. For instance,
-each calls the following function to set various variables:
-
-@smallexample
-@group
-(defun lisp-mode-variables (lisp-syntax)
- (when lisp-syntax
- (set-syntax-table lisp-mode-syntax-table))
- (setq local-abbrev-table lisp-mode-abbrev-table)
- @dots{}
-@end group
-@end smallexample
-
- In Lisp and most programming languages, we want the paragraph
-commands to treat only blank lines as paragraph separators. And the
-modes should understand the Lisp conventions for comments. The rest of
-@code{lisp-mode-variables} sets this up:
-
-@smallexample
-@group
- (make-local-variable 'paragraph-start)
- (setq paragraph-start (concat page-delimiter "\\|$" ))
- (make-local-variable 'paragraph-separate)
- (setq paragraph-separate paragraph-start)
- @dots{}
-@end group
-@group
- (make-local-variable 'comment-indent-function)
- (setq comment-indent-function 'lisp-comment-indent))
- @dots{}
-@end group
-@end smallexample
-
- Each of the different Lisp modes has a slightly different keymap. For
-example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
-Lisp modes do not. However, all Lisp modes have some commands in
-common. The following code sets up the common commands:
-
-@smallexample
-@group
-(defvar shared-lisp-mode-map ()
- "Keymap for commands shared by all sorts of Lisp modes.")
-
-;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
-(if shared-lisp-mode-map
- ()
- (setq shared-lisp-mode-map (make-sparse-keymap))
- (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
- (define-key shared-lisp-mode-map "\177"
- 'backward-delete-char-untabify))
-@end group
-@end smallexample
-
-@noindent
-And here is the code to set up the keymap for Lisp mode:
-
-@smallexample
-@group
-(defvar lisp-mode-map ()
- "Keymap for ordinary Lisp mode...")
-
-(if lisp-mode-map
- ()
- (setq lisp-mode-map (make-sparse-keymap))
- (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
- (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
- (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
-@end group
-@end smallexample
-
- Finally, here is the complete major mode function definition for
-Lisp mode.
-
-@smallexample
-@group
-(defun lisp-mode ()
- "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
-Commands:
-Delete converts tabs to spaces as it moves back.
-Blank lines separate paragraphs. Semicolons start comments.
-\\@{lisp-mode-map@}
-Note that `run-lisp' may be used either to start an inferior Lisp job
-or to switch back to an existing one.
-@end group
-
-@group
-Entry to this mode calls the value of `lisp-mode-hook'
-if that value is non-nil."
- (interactive)
- (kill-all-local-variables)
-@end group
-@group
- (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
- (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
- ; @r{finds out what to describe.}
- (setq mode-name "Lisp") ; @r{This goes into the mode line.}
- (lisp-mode-variables t) ; @r{This defines various variables.}
- (make-local-variable 'comment-start-skip)
- (setq comment-start-skip
- "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
- (make-local-variable 'font-lock-keywords-case-fold-search)
- (setq font-lock-keywords-case-fold-search t)
-@end group
-@group
- (setq imenu-case-fold-search t)
- (set-syntax-table lisp-mode-syntax-table)
- (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
- ; @r{hook to customize the mode.}
-@end group
-@end smallexample
-
-@node Minor Modes
-@section Minor Modes
-@cindex minor mode
-
- A @dfn{minor mode} provides features that users may enable or disable
-independently of the choice of major mode. Minor modes can be enabled
-individually or in combination. Minor modes would be better named
-``generally available, optional feature modes,'' except that such a name
-would be unwieldy.
-
- A minor mode is not usually meant as a variation of a single major mode.
-Usually they are general and can apply to many major modes. For
-example, Auto Fill mode works with any major mode that permits text
-insertion. To be general, a minor mode must be effectively independent
-of the things major modes do.
-
- A minor mode is often much more difficult to implement than a major
-mode. One reason is that you should be able to activate and deactivate
-minor modes in any order. A minor mode should be able to have its
-desired effect regardless of the major mode and regardless of the other
-minor modes in effect.
-
- Often the biggest problem in implementing a minor mode is finding a
-way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier than it used to be.
-
-@defvar minor-mode-list
-The value of this variable is a list of all minor mode commands.
-@end defvar
-
-@menu
-* 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.
-@end menu
-
-@node Minor Mode Conventions
-@subsection Conventions for Writing Minor Modes
-@cindex minor mode conventions
-@cindex conventions for writing minor modes
-
- There are conventions for writing minor modes just as there are for
-major modes. Several of the major mode conventions apply to minor
-modes as well: those regarding the name of the mode initialization
-function, the names of global symbols, the use of a hook at the end of
-the initialization function, and the use of keymaps and other tables.
-
- In addition, there are several conventions that are specific to
-minor modes. (The easiest way to follow all the conventions is to use
-the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
-
-@itemize @bullet
-@item
-@cindex mode variable
-Make a variable whose name ends in @samp{-mode} to control the minor
-mode. We call this the @dfn{mode variable}. The minor mode command
-should set this variable (@code{nil} to disable; anything else to
-enable).
-
-If possible, implement the mode so that setting the variable
-automatically enables or disables the mode. Then the minor mode command
-does not need to do anything except set the variable.
-
-This variable is used in conjunction with the @code{minor-mode-alist} to
-display the minor mode name in the mode line. It can also enable
-or disable a minor mode keymap. Individual commands or hooks can also
-check the variable's value.
-
-If you want the minor mode to be enabled separately in each buffer,
-make the variable buffer-local.
-
-@item
-Define a command whose name is the same as the mode variable.
-Its job is to enable and disable the mode by setting the variable.
-
-The command should accept one optional argument. If the argument is
-@code{nil}, it should toggle the mode (turn it on if it is off, and
-off if it is on). It should turn the mode on if the argument is a
-positive integer, the symbol @code{t}, or a list whose @sc{car} is one
-of those. It should turn the mode off if the argument is a negative
-integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
-negative integer or zero. The meaning of other arguments is not
-specified.
-
-Here is an example taken from the definition of @code{transient-mark-mode}.
-It shows the use of @code{transient-mark-mode} as a variable that enables or
-disables the mode's behavior, and also shows the proper way to toggle,
-enable or disable the minor mode based on the raw prefix argument value.
-
-@smallexample
-@group
-(setq transient-mark-mode
- (if (null arg) (not transient-mark-mode)
- (> (prefix-numeric-value arg) 0)))
-@end group
-@end smallexample
-
-@item
-Add an element to @code{minor-mode-alist} for each minor mode
-(@pxref{Definition of minor-mode-alist}), if you want to indicate the
-minor mode in the mode line. This element should be a list of the
-following form:
-
-@smallexample
-(@var{mode-variable} @var{string})
-@end smallexample
-
-Here @var{mode-variable} is the variable that controls enabling of the
-minor mode, and @var{string} is a short string, starting with a space,
-to represent the mode in the mode line. These strings must be short so
-that there is room for several of them at once.
-
-When you add an element to @code{minor-mode-alist}, use @code{assq} to
-check for an existing element, to avoid duplication. For example:
-
-@smallexample
-@group
-(unless (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
-@end group
-@end smallexample
-
-@noindent
-or like this, using @code{add-to-list} (@pxref{List Variables}):
-
-@smallexample
-@group
-(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
-@end group
-@end smallexample
-@end itemize
-
- Global minor modes distributed with Emacs should if possible support
-enabling and disabling via Custom (@pxref{Customization}). To do this,
-the first step is to define the mode variable with @code{defcustom}, and
-specify @code{:type boolean}.
-
- If just setting the variable is not sufficient to enable the mode, you
-should also specify a @code{:set} method which enables the mode by
-invoking the mode command. Note in the variable's documentation string that
-setting the variable other than via Custom may not take effect.
-
- Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
-and specify a @code{:require} so that customizing the variable will load
-the library that defines the mode. This will copy suitable definitions
-into @file{loaddefs.el} so that users can use @code{customize-option} to
-enable the mode. For example:
-
-@smallexample
-@group
-
-;;;###autoload
-(defcustom msb-mode nil
- "Toggle msb-mode.
-Setting this variable directly does not take effect;
-use either \\[customize] or the function `msb-mode'."
- :set 'custom-set-minor-mode
- :initialize 'custom-initialize-default
- :version "20.4"
- :type 'boolean
- :group 'msb
- :require 'msb)
-@end group
-@end smallexample
-
-@node Keymaps and Minor Modes
-@subsection Keymaps and Minor Modes
-
- Each minor mode can have its own keymap, which is active when the mode
-is enabled. To set up a keymap for a minor mode, add an element to the
-alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
-
-@cindex @code{self-insert-command}, minor modes
- One use of minor mode keymaps is to modify the behavior of certain
-self-inserting characters so that they do something else as well as
-self-insert. In general, this is the only way to do that, since the
-facilities for customizing @code{self-insert-command} are limited to
-special cases (designed for abbrevs and Auto Fill mode). (Do not try
-substituting your own definition of @code{self-insert-command} for the
-standard one. The editor command loop handles this function specially.)
-
-The key sequences bound in a minor mode should consist of @kbd{C-c}
-followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other
-punctuation characters are reserved for major modes.)
-
-@node Defining Minor Modes
-@subsection Defining Minor Modes
-
- The macro @code{define-minor-mode} offers a convenient way of
-implementing a mode in one self-contained definition.
-
-@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
-This macro defines a new minor mode whose name is @var{mode} (a
-symbol). It defines a command named @var{mode} to toggle the minor
-mode, with @var{doc} as its documentation string. It also defines a
-variable named @var{mode}, which is set to @code{t} or @code{nil} by
-enabling or disabling the mode. The variable is initialized to
-@var{init-value}. Except in unusual circumstances (see below), this
-value must be @code{nil}.
-
-The string @var{lighter} says what to display in the mode line
-when the mode is enabled; if it is @code{nil}, the mode is not displayed
-in the mode line.
-
-The optional argument @var{keymap} specifies the keymap for the minor mode.
-It can be a variable name, whose value is the keymap, or it can be an alist
-specifying bindings in this form:
-
-@example
-(@var{key-sequence} . @var{definition})
-@end example
-
-The above three arguments @var{init-value}, @var{lighter}, and
-@var{keymap} can be (partially) omitted when @var{keyword-args} are
-used. The @var{keyword-args} consist of keywords followed by
-corresponding values. A few keywords have special meanings:
-
-@table @code
-@item :group @var{group}
-Custom group name to use in all generated @code{defcustom} forms.
-Defaults to @var{mode} without the possible trailing @samp{-mode}.
-@strong{Warning:} don't use this default group name unless you have
-written a @code{defgroup} to define that group properly. @xref{Group
-Definitions}.
-
-@item :global @var{global}
-If non-@code{nil}, this specifies that the minor mode should be global
-rather than buffer-local. It defaults to @code{nil}.
-
-One of the effects of making a minor mode global is that the
-@var{mode} variable becomes a customization variable. Toggling it
-through the Custom interface turns the mode on and off, and its value
-can be saved for future Emacs sessions (@pxref{Saving
-Customizations,,, emacs, The GNU Emacs Manual}. For the saved
-variable to work, you should ensure that the @code{define-minor-mode}
-form is evaluated each time Emacs starts; for packages that are not
-part of Emacs, the easiest way to do this is to specify a
-@code{:require} keyword.
-
-@item :init-value @var{init-value}
-This is equivalent to specifying @var{init-value} positionally.
-
-@item :lighter @var{lighter}
-This is equivalent to specifying @var{lighter} positionally.
-
-@item :keymap @var{keymap}
-This is equivalent to specifying @var{keymap} positionally.
-@end table
-
-Any other keyword arguments are passed directly to the
-@code{defcustom} generated for the variable @var{mode}.
-
-The command named @var{mode} first performs the standard actions such
-as setting the variable named @var{mode} and then executes the
-@var{body} forms, if any. It finishes by running the mode hook
-variable @code{@var{mode}-hook}.
-@end defmac
-
- The initial value must be @code{nil} except in cases where (1) the
-mode is preloaded in Emacs, or (2) it is painless for loading to
-enable the mode even though the user did not request it. For
-instance, if the mode has no effect unless something else is enabled,
-and will always be loaded by that time, enabling it by default is
-harmless. But these are unusual circumstances. Normally, the
-initial value must be @code{nil}.
-
-@findex easy-mmode-define-minor-mode
- The name @code{easy-mmode-define-minor-mode} is an alias
-for this macro.
-
- Here is an example of using @code{define-minor-mode}:
-
-@smallexample
-(define-minor-mode hungry-mode
- "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
-
-When Hungry mode is enabled, the control delete key
-gobbles all preceding whitespace except the last.
-See the command \\[hungry-electric-delete]."
- ;; The initial value.
- nil
- ;; The indicator for the mode line.
- " Hungry"
- ;; The minor mode bindings.
- '(("\C-\^?" . hungry-electric-delete))
- :group 'hunger)
-@end smallexample
-
-@noindent
-This defines a minor mode named ``Hungry mode,'' a command named
-@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
-which indicates whether the mode is enabled, and a variable named
-@code{hungry-mode-map} which holds the keymap that is active when the
-mode is enabled. It initializes the keymap with a key binding for
-@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
-custom group @code{hunger}. There are no @var{body} forms---many
-minor modes don't need any.
-
- Here's an equivalent way to write it:
-
-@smallexample
-(define-minor-mode hungry-mode
- "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
-
-When Hungry mode is enabled, the control delete key
-gobbles all preceding whitespace except the last.
-See the command \\[hungry-electric-delete]."
- ;; The initial value.
- :init-value nil
- ;; The indicator for the mode line.
- :lighter " Hungry"
- ;; The minor mode bindings.
- :keymap
- '(("\C-\^?" . hungry-electric-delete)
- ("\C-\M-\^?"
- . (lambda ()
- (interactive)
- (hungry-electric-delete t))))
- :group 'hunger)
-@end smallexample
-
-@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
-This defines a global toggle named @var{global-mode} whose meaning is
-to enable or disable the buffer-local minor mode @var{mode} in all
-buffers. To turn on the minor mode in a buffer, it uses the function
-@var{turn-on}; to turn off the minor mode, it calls @code{mode} with
-@minus{}1 as argument.
-
-Globally enabling the mode also affects buffers subsequently created
-by visiting files, and buffers that use a major mode other than
-Fundamental mode; but it does not detect the creation of a new buffer
-in Fundamental mode.
-
-This defines the customization option @var{global-mode} (@pxref{Customization}),
-which can be toggled in the Custom interface to turn the minor mode on
-and off. As with @code{define-minor-mode}, you should ensure that the
-@code{define-globalized-minor-mode} form is evaluated each time Emacs
-starts, for example by providing a @code{:require} keyword.
-
-Use @code{:group @var{group}} in @var{keyword-args} to specify the
-custom group for the mode variable of the global minor mode.
-@end defmac
-
-@node Mode Line Format
-@section Mode-Line Format
-@cindex mode line
-
- Each Emacs window (aside from minibuffer windows) typically has a mode
-line at the bottom, which displays status information about the buffer
-displayed in the window. The mode line contains information about the
-buffer, such as its name, associated file, depth of recursive editing,
-and major and minor modes. A window can also have a @dfn{header
-line}, which is much like the mode line but appears at the top of the
-window.
-
- This section describes how to control the contents of the mode line
-and header line. We include it in this chapter because much of the
-information displayed in the mode line relates to the enabled major and
-minor modes.
-
-@menu
-* Base: Mode Line Basics. Basic ideas of mode line control.
-* Data: Mode Line Data. The data structure that controls the mode line.
-* Top: Mode Line Top. The top level variable, mode-line-format.
-* 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.
-@end menu
-
-@node Mode Line Basics
-@subsection Mode Line Basics
-
- @code{mode-line-format} is a buffer-local variable that holds a
-@dfn{mode line construct}, a kind of template, which controls what is
-displayed on the mode line of the current buffer. The value of
-@code{header-line-format} specifies the buffer's header line in the
-same way. All windows for the same buffer use the same
-@code{mode-line-format} and @code{header-line-format}.
-
- For efficiency, Emacs does not continuously recompute the mode
-line and header line of a window. It does so when circumstances
-appear to call for it---for instance, if you change the window
-configuration, switch buffers, narrow or widen the buffer, scroll, or
-change the buffer's modification status. If you modify any of the
-variables referenced by @code{mode-line-format} (@pxref{Mode Line
-Variables}), or any other variables and data structures that affect
-how text is displayed (@pxref{Display}), you may want to force an
-update of the mode line so as to display the new information or
-display it in the new way.
-
-@defun force-mode-line-update &optional all
-Force redisplay of the current buffer's mode line and header line.
-The next redisplay will update the mode line and header line based on
-the latest values of all relevant variables. With optional
-non-@code{nil} @var{all}, force redisplay of all mode lines and header
-lines.
-
-This function also forces recomputation of the menu bar menus
-and the frame title.
-@end defun
-
- The selected window's mode line is usually displayed in a different
-color using the face @code{mode-line}. Other windows' mode lines
-appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
-
-@node Mode Line Data
-@subsection The Data Structure of the Mode Line
-@cindex mode-line construct
-
- The mode-line contents are controlled by a data structure called a
-@dfn{mode-line construct}, made up of lists, strings, symbols, and
-numbers kept in buffer-local variables. Each data type has a specific
-meaning for the mode-line appearance, as described below. The same
-data structure is used for constructing frame titles (@pxref{Frame
-Titles}) and header lines (@pxref{Header Lines}).
-
- A mode-line construct may be as simple as a fixed string of text,
-but it usually specifies how to combine fixed strings with variables'
-values to construct the text. Many of these variables are themselves
-defined to have mode-line constructs as their values.
-
- Here are the meanings of various data types as mode-line constructs:
-
-@table @code
-@cindex percent symbol in mode line
-@item @var{string}
-A string as a mode-line construct appears verbatim except for
-@dfn{@code{%}-constructs} in it. These stand for substitution of
-other data; see @ref{%-Constructs}.
-
-If parts of the string have @code{face} properties, they control
-display of the text just as they would text in the buffer. Any
-characters which have no @code{face} properties are displayed, by
-default, in the face @code{mode-line} or @code{mode-line-inactive}
-(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
-@code{help-echo} and @code{local-map} properties in @var{string} have
-special meanings. @xref{Properties in Mode}.
-
-@item @var{symbol}
-A symbol as a mode-line construct stands for its value. The value of
-@var{symbol} is used as a mode-line construct, in place of @var{symbol}.
-However, the symbols @code{t} and @code{nil} are ignored, as is any
-symbol whose value is void.
-
-There is one exception: if the value of @var{symbol} is a string, it is
-displayed verbatim: the @code{%}-constructs are not recognized.
-
-Unless @var{symbol} is marked as ``risky'' (i.e., it has a
-non-@code{nil} @code{risky-local-variable} property), all text
-properties specified in @var{symbol}'s value are ignored. This
-includes the text properties of strings in @var{symbol}'s value, as
-well as all @code{:eval} and @code{:propertize} forms in it. (The
-reason for this is security: non-risky variables could be set
-automatically from file variables without prompting the user.)
-
-@item (@var{string} @var{rest}@dots{})
-@itemx (@var{list} @var{rest}@dots{})
-A list whose first element is a string or list means to process all the
-elements recursively and concatenate the results. This is the most
-common form of mode-line construct.
-
-@item (:eval @var{form})
-A list whose first element is the symbol @code{:eval} says to evaluate
-@var{form}, and use the result as a string to display. Make sure this
-evaluation cannot load any files, as doing so could cause infinite
-recursion.
-
-@item (:propertize @var{elt} @var{props}@dots{})
-A list whose first element is the symbol @code{:propertize} says to
-process the mode-line construct @var{elt} recursively, then add the text
-properties specified by @var{props} to the result. The argument
-@var{props} should consist of zero or more pairs @var{text-property}
-@var{value}. (This feature is new as of Emacs 22.1.)
-
-@item (@var{symbol} @var{then} @var{else})
-A list whose first element is a symbol that is not a keyword specifies
-a conditional. Its meaning depends on the value of @var{symbol}. If
-@var{symbol} has a non-@code{nil} value, the second element,
-@var{then}, is processed recursively as a mode-line element.
-Otherwise, the third element, @var{else}, is processed recursively.
-You may omit @var{else}; then the mode-line element displays nothing
-if the value of @var{symbol} is @code{nil} or void.
-
-@item (@var{width} @var{rest}@dots{})
-A list whose first element is an integer specifies truncation or
-padding of the results of @var{rest}. The remaining elements
-@var{rest} are processed recursively as mode-line constructs and
-concatenated together. When @var{width} is positive, the result is
-space filled on the right if its width is less than @var{width}. When
-@var{width} is negative, the result is truncated on the right to
-@minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
-
-For example, the usual way to show what percentage of a buffer is above
-the top of the window is to use a list like this: @code{(-3 "%p")}.
-@end table
-
-@node Mode Line Top
-@subsection The Top Level of Mode Line Control
-
- The variable in overall control of the mode line is
-@code{mode-line-format}.
-
-@defvar mode-line-format
-The value of this variable is a mode-line construct that controls the
-contents of the mode-line. It is always buffer-local in all buffers.
-
-If you set this variable to @code{nil} in a buffer, that buffer does
-not have a mode line. (A window that is just one line tall never
-displays a mode line.)
-@end defvar
-
- The default value of @code{mode-line-format} is designed to use the
-values of other variables such as @code{mode-line-position} and
-@code{mode-line-modes} (which in turn incorporates the values of the
-variables @code{mode-name} and @code{minor-mode-alist}). Very few
-modes need to alter @code{mode-line-format} itself. For most
-purposes, it is sufficient to alter some of the variables that
-@code{mode-line-format} either directly or indirectly refers to.
-
- If you do alter @code{mode-line-format} itself, the new value should
-use the same variables that appear in the default value (@pxref{Mode
-Line Variables}), rather than duplicating their contents or displaying
-the information in another fashion. This way, customizations made by
-the user or by Lisp programs (such as @code{display-time} and major
-modes) via changes to those variables remain effective.
-
- Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode}, since it contains the host name and default
-directory.
-
-@example
-@group
-(setq mode-line-format
- (list "-"
- 'mode-line-mule-info
- 'mode-line-modified
- 'mode-line-frame-identification
- "%b--"
-@end group
-@group
- ;; @r{Note that this is evaluated while making the list.}
- ;; @r{It makes a mode-line construct which is just a string.}
- (getenv "HOST")
-@end group
- ":"
- 'default-directory
- " "
- 'global-mode-string
- " %[("
- '(:eval (mode-line-mode-name))
- 'mode-line-process
- 'minor-mode-alist
- "%n"
- ")%]--"
-@group
- '(which-func-mode ("" which-func-format "--"))
- '(line-number-mode "L%l--")
- '(column-number-mode "C%c--")
- '(-3 "%p")
- "-%-"))
-@end group
-@end example
-
-@noindent
-(The variables @code{line-number-mode}, @code{column-number-mode}
-and @code{which-func-mode} enable particular minor modes; as usual,
-these variable names are also the minor mode command names.)
-
-@node Mode Line Variables
-@subsection Variables Used in the Mode Line
-
- This section describes variables incorporated by the standard value
-of @code{mode-line-format} into the text of the mode line. There is
-nothing inherently special about these variables; any other variables
-could have the same effects on the mode line if
-@code{mode-line-format}'s value were changed to use them. However,
-various parts of Emacs set these variables on the understanding that
-they will control parts of the mode line; therefore, practically
-speaking, it is essential for the mode line to use them.
-
-@defvar mode-line-mule-info
-This variable holds the value of the mode-line construct that displays
-information about the language environment, buffer coding system, and
-current input method. @xref{Non-ASCII Characters}.
-@end defvar
-
-@defvar mode-line-modified
-This variable holds the value of the mode-line construct that displays
-whether the current buffer is modified.
-
-The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
-This means that the mode line displays @samp{**} if the buffer is
-modified, @samp{--} if the buffer is not modified, @samp{%%} if the
-buffer is read only, and @samp{%*} if the buffer is read only and
-modified.
-
-Changing this variable does not force an update of the mode line.
-@end defvar
-
-@defvar mode-line-frame-identification
-This variable identifies the current frame. The default value is
-@code{" "} if you are using a window system which can show multiple
-frames, or @code{"-%F "} on an ordinary terminal which shows only one
-frame at a time.
-@end defvar
-
-@defvar mode-line-buffer-identification
-This variable identifies the buffer being displayed in the window. Its
-default value is @code{("%12b")}, which displays the buffer name, padded
-with spaces to at least 12 columns.
-@end defvar
-
-@defvar mode-line-position
-This variable indicates the position in the buffer. Here is a
-simplified version of its default value. The actual default value
-also specifies addition of the @code{help-echo} text property.
-
-@example
-@group
-((-3 "%p")
- (size-indication-mode (8 " of %I"))
-@end group
-@group
- (line-number-mode
- ((column-number-mode
- (10 " (%l,%c)")
- (6 " L%l")))
- ((column-number-mode
- (5 " C%c")))))
-@end group
-@end example
-
-This means that @code{mode-line-position} displays at least the buffer
-percentage and possibly the buffer size, the line number and the column
-number.
-@end defvar
-
-@defvar vc-mode
-The variable @code{vc-mode}, buffer-local in each buffer, records
-whether the buffer's visited file is maintained with version control,
-and, if so, which kind. Its value is a string that appears in the mode
-line, or @code{nil} for no version control.
-@end defvar
-
-@defvar mode-line-modes
-This variable displays the buffer's major and minor modes. Here is a
-simplified version of its default value. The real default value also
-specifies addition of text properties.
-
-@example
-@group
-("%[(" mode-name
- mode-line-process minor-mode-alist
- "%n" ")%]--")
-@end group
-@end example
-
-So @code{mode-line-modes} normally also displays the recursive editing
-level, information on the process status and whether narrowing is in
-effect.
-@end defvar
-
- The following three variables are used in @code{mode-line-modes}:
-
-@defvar mode-name
-This buffer-local variable holds the ``pretty'' name of the current
-buffer's major mode. Each major mode should set this variable so that the
-mode name will appear in the mode line.
-@end defvar
-
-@defvar mode-line-process
-This buffer-local variable contains the mode-line information on process
-status in modes used for communicating with subprocesses. It is
-displayed immediately following the major mode name, with no intervening
-space. For example, its value in the @samp{*shell*} buffer is
-@code{(":%s")}, which allows the shell to display its status along
-with the major mode as: @samp{(Shell:run)}. Normally this variable
-is @code{nil}.
-@end defvar
-
-@defvar minor-mode-alist
-@anchor{Definition of minor-mode-alist}
-This variable holds an association list whose elements specify how the
-mode line should indicate that a minor mode is active. Each element of
-the @code{minor-mode-alist} should be a two-element list:
-
-@example
-(@var{minor-mode-variable} @var{mode-line-string})
-@end example
-
-More generally, @var{mode-line-string} can be any mode-line spec. It
-appears in the mode line when the value of @var{minor-mode-variable}
-is non-@code{nil}, and not otherwise. These strings should begin with
-spaces so that they don't run together. Conventionally, the
-@var{minor-mode-variable} for a specific mode is set to a
-non-@code{nil} value when that minor mode is activated.
-
-@code{minor-mode-alist} itself is not buffer-local. Each variable
-mentioned in the alist should be buffer-local if its minor mode can be
-enabled separately in each buffer.
-@end defvar
-
-@defvar global-mode-string
-This variable holds a mode-line spec that, by default, appears in the
-mode line just after the @code{which-func-mode} minor mode if set,
-else after @code{mode-line-modes}. The command @code{display-time}
-sets @code{global-mode-string} to refer to the variable
-@code{display-time-string}, which holds a string containing the time
-and load information.
-
-The @samp{%M} construct substitutes the value of
-@code{global-mode-string}, but that is obsolete, since the variable is
-included in the mode line from @code{mode-line-format}.
-@end defvar
-
- The variable @code{default-mode-line-format} is where
-@code{mode-line-format} usually gets its value:
-
-@defvar default-mode-line-format
-This variable holds the default @code{mode-line-format} for buffers
-that do not override it. This is the same as @code{(default-value
-'mode-line-format)}.
-
-Here is a simplified version of the default value of
-@code{default-mode-line-format}. The real default value also
-specifies addition of text properties.
-
-@example
-@group
-("-"
- mode-line-mule-info
- mode-line-modified
- mode-line-frame-identification
- mode-line-buffer-identification
-@end group
- " "
- mode-line-position
- (vc-mode vc-mode)
- " "
-@group
- mode-line-modes
- (which-func-mode ("" which-func-format "--"))
- (global-mode-string ("--" global-mode-string))
- "-%-")
-@end group
-@end example
-@end defvar
-
-@node %-Constructs
-@subsection @code{%}-Constructs in the Mode Line
-
- Strings used as mode-line constructs can use certain
-@code{%}-constructs to substitute various kinds of data. Here is a
-list of the defined @code{%}-constructs, and what they mean. In any
-construct except @samp{%%}, you can add a decimal integer after the
-@samp{%} to specify a minimum field width. If the width is less, the
-field is padded with spaces to the right.
-
-@table @code
-@item %b
-The current buffer name, obtained with the @code{buffer-name} function.
-@xref{Buffer Names}.
-
-@item %c
-The current column number of point.
-
-@item %e
-When Emacs is nearly out of memory for Lisp objects, a brief message
-saying so. Otherwise, this is empty.
-
-@item %f
-The visited file name, obtained with the @code{buffer-file-name}
-function. @xref{Buffer File Name}.
-
-@item %F
-The title (only on a window system) or the name of the selected frame.
-@xref{Basic Parameters}.
-
-@item %i
-The size of the accessible part of the current buffer; basically
-@code{(- (point-max) (point-min))}.
-
-@item %I
-Like @samp{%i}, but the size is printed in a more readable way by using
-@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
-abbreviate.
-
-@item %l
-The current line number of point, counting within the accessible portion
-of the buffer.
-
-@item %n
-@samp{Narrow} when narrowing is in effect; nothing otherwise (see
-@code{narrow-to-region} in @ref{Narrowing}).
-
-@item %p
-The percentage of the buffer text above the @strong{top} of window, or
-@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
-mode-line specification truncates this to three characters.
-
-@item %P
-The percentage of the buffer text that is above the @strong{bottom} of
-the window (which includes the text visible in the window, as well as
-the text above the top), plus @samp{Top} if the top of the buffer is
-visible on screen; or @samp{Bottom} or @samp{All}.
-
-@item %s
-The status of the subprocess belonging to the current buffer, obtained with
-@code{process-status}. @xref{Process Information}.
-
-@item %t
-Whether the visited file is a text file or a binary file. This is a
-meaningful distinction only on certain operating systems (@pxref{MS-DOS
-File Types}).
-
-@item %z
-The mnemonics of keyboard, terminal, and buffer coding systems.
-
-@item %Z
-Like @samp{%z}, but including the end-of-line format.
-
-@item %*
-@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
-@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
-@samp{-} otherwise. @xref{Buffer Modification}.
-
-@item %+
-@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
-@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
-@samp{-} otherwise. This differs from @samp{%*} only for a modified
-read-only buffer. @xref{Buffer Modification}.
-
-@item %&
-@samp{*} if the buffer is modified, and @samp{-} otherwise.
-
-@item %[
-An indication of the depth of recursive editing levels (not counting
-minibuffer levels): one @samp{[} for each editing level.
-@xref{Recursive Editing}.
-
-@item %]
-One @samp{]} for each recursive editing level (not counting minibuffer
-levels).
-
-@item %-
-Dashes sufficient to fill the remainder of the mode line.
-
-@item %%
-The character @samp{%}---this is how to include a literal @samp{%} in a
-string in which @code{%}-constructs are allowed.
-@end table
-
-The following two @code{%}-constructs are still supported, but they are
-obsolete, since you can get the same results with the variables
-@code{mode-name} and @code{global-mode-string}.
-
-@table @code
-@item %m
-The value of @code{mode-name}.
-
-@item %M
-The value of @code{global-mode-string}.
-@end table
-
-@node Properties in Mode
-@subsection Properties in the Mode Line
-@cindex text properties in the mode line
-
- Certain text properties are meaningful in the
-mode line. The @code{face} property affects the appearance of text; the
-@code{help-echo} property associates help strings with the text, and
-@code{local-map} can make the text mouse-sensitive.
-
- There are four ways to specify text properties for text in the mode
-line:
-
-@enumerate
-@item
-Put a string with a text property directly into the mode-line data
-structure.
-
-@item
-Put a text property on a mode-line %-construct such as @samp{%12b}; then
-the expansion of the %-construct will have that same text property.
-
-@item
-Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
-give @var{elt} a text property specified by @var{props}.
-
-@item
-Use a list containing @code{:eval @var{form}} in the mode-line data
-structure, and make @var{form} evaluate to a string that has a text
-property.
-@end enumerate
-
- You can use the @code{local-map} property to specify a keymap. This
-keymap only takes real effect for mouse clicks; binding character keys
-and function keys to it has no effect, since it is impossible to move
-point into the mode line.
-
- When the mode line refers to a variable which does not have a
-non-@code{nil} @code{risky-local-variable} property, any text
-properties given or specified within that variable's values are
-ignored. This is because such properties could otherwise specify
-functions to be called, and those functions could come from file
-local variables.
-
-@node Header Lines
-@subsection Window Header Lines
-@cindex header line (of a window)
-@cindex window header line
-
- A window can have a @dfn{header line} at the
-top, just as it can have a mode line at the bottom. The header line
-feature works just like the mode-line feature, except that it's
-controlled by different variables.
-
-@defvar header-line-format
-This variable, local in every buffer, specifies how to display the
-header line, for windows displaying the buffer. The format of the value
-is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
-@end defvar
-
-@defvar default-header-line-format
-This variable holds the default @code{header-line-format} for buffers
-that do not override it. This is the same as @code{(default-value
-'header-line-format)}.
-
-It is normally @code{nil}, so that ordinary buffers have no header line.
-@end defvar
-
- A window that is just one line tall never displays a header line. A
-window that is two lines tall cannot display both a mode line and a
-header line at once; if it has a mode line, then it does not display a
-header line.
-
-@node Emulating Mode Line
-@subsection Emulating Mode-Line Formatting
-
- You can use the function @code{format-mode-line} to compute
-the text that would appear in a mode line or header line
-based on a certain mode-line specification.
-
-@defun format-mode-line format &optional face window buffer
-This function formats a line of text according to @var{format} as if
-it were generating the mode line for @var{window}, but instead of
-displaying the text in the mode line or the header line, it returns
-the text as a string. The argument @var{window} defaults to the
-selected window. If @var{buffer} is non-@code{nil}, all the
-information used is taken from @var{buffer}; by default, it comes from
-@var{window}'s buffer.
-
-The value string normally has text properties that correspond to the
-faces, keymaps, etc., that the mode line would have. And any character
-for which no @code{face} property is specified gets a default
-value which is usually @var{face}. (If @var{face} is @code{t},
-that stands for either @code{mode-line} if @var{window} is selected,
-otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
-omitted, that stands for no face property.)
-
-However, if @var{face} is an integer, the value has no text properties.
-
-For example, @code{(format-mode-line header-line-format)} returns the
-text that would appear in the selected window's header line (@code{""}
-if it has no header line). @code{(format-mode-line header-line-format
-'header-line)} returns the same text, with each character
-carrying the face that it will have in the header line itself.
-@end defun
-
-@node Imenu
-@section Imenu
-
-@cindex Imenu
- @dfn{Imenu} is a feature that lets users select a definition or
-section in the buffer, from a menu which lists all of them, to go
-directly to that location in the buffer. Imenu works by constructing
-a buffer index which lists the names and buffer positions of the
-definitions, or other named portions of the buffer; then the user can
-choose one of them and move point to it. Major modes can add a menu
-bar item to use Imenu using @code{imenu-add-to-menubar}.
-
-@defun imenu-add-to-menubar name
-This function defines a local menu bar item named @var{name}
-to run Imenu.
-@end defun
-
- The user-level commands for using Imenu are described in the Emacs
-Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
-explains how to customize Imenu's method of finding definitions or
-buffer portions for a particular major mode.
-
- The usual and simplest way is to set the variable
-@code{imenu-generic-expression}:
-
-@defvar imenu-generic-expression
-This variable, if non-@code{nil}, is a list that specifies regular
-expressions for finding definitions for Imenu. Simple elements of
-@code{imenu-generic-expression} look like this:
-
-@example
-(@var{menu-title} @var{regexp} @var{index})
-@end example
-
-Here, if @var{menu-title} is non-@code{nil}, it says that the matches
-for this element should go in a submenu of the buffer index;
-@var{menu-title} itself specifies the name for the submenu. If
-@var{menu-title} is @code{nil}, the matches for this element go directly
-in the top level of the buffer index.
-
-The second item in the list, @var{regexp}, is a regular expression
-(@pxref{Regular Expressions}); anything in the buffer that it matches
-is considered a definition, something to mention in the buffer index.
-The third item, @var{index}, is a non-negative integer that indicates
-which subexpression in @var{regexp} matches the definition's name.
-
-An element can also look like this:
-
-@example
-(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
-@end example
-
-Each match for this element creates an index item, and when the index
-item is selected by the user, it calls @var{function} with arguments
-consisting of the item name, the buffer position, and @var{arguments}.
-
-For Emacs Lisp mode, @code{imenu-generic-expression} could look like
-this:
-
-@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
-@example
-@group
-((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
-\\s-+\\([-A-Za-z0-9+]+\\)" 2)
-@end group
-@group
- ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
-\\s-+\\([-A-Za-z0-9+]+\\)" 2)
-@end group
-@group
- ("*Types*"
- "^\\s-*\
-(def\\(type\\|struct\\|class\\|ine-condition\\)\
-\\s-+\\([-A-Za-z0-9+]+\\)" 2))
-@end group
-@end example
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
-@defvar imenu-case-fold-search
-This variable controls whether matching against the regular
-expressions in the value of @code{imenu-generic-expression} is
-case-sensitive: @code{t}, the default, means matching should ignore
-case.
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
-@defvar imenu-syntax-alist
-This variable is an alist of syntax table modifiers to use while
-processing @code{imenu-generic-expression}, to override the syntax table
-of the current buffer. Each element should have this form:
-
-@example
-(@var{characters} . @var{syntax-description})
-@end example
-
-The @sc{car}, @var{characters}, can be either a character or a string.
-The element says to give that character or characters the syntax
-specified by @var{syntax-description}, which is passed to
-@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
-
-This feature is typically used to give word syntax to characters which
-normally have symbol syntax, and thus to simplify
-@code{imenu-generic-expression} and speed up matching.
-For example, Fortran mode uses it this way:
-
-@example
-(setq imenu-syntax-alist '(("_$" . "w")))
-@end example
-
-The @code{imenu-generic-expression} regular expressions can then use
-@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
-technique may be inconvenient when the mode needs to limit the initial
-character of a name to a smaller set of characters than are allowed in
-the rest of a name.
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
- Another way to customize Imenu for a major mode is to set the
-variables @code{imenu-prev-index-position-function} and
-@code{imenu-extract-index-name-function}:
-
-@defvar imenu-prev-index-position-function
-If this variable is non-@code{nil}, its value should be a function that
-finds the next ``definition'' to put in the buffer index, scanning
-backward in the buffer from point. It should return @code{nil} if it
-doesn't find another ``definition'' before point. Otherwise it should
-leave point at the place it finds a ``definition'' and return any
-non-@code{nil} value.
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
-@defvar imenu-extract-index-name-function
-If this variable is non-@code{nil}, its value should be a function to
-return the name for a definition, assuming point is in that definition
-as the @code{imenu-prev-index-position-function} function would leave
-it.
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
- The last way to customize Imenu for a major mode is to set the
-variable @code{imenu-create-index-function}:
-
-@defvar imenu-create-index-function
-This variable specifies the function to use for creating a buffer
-index. The function should take no arguments, and return an index
-alist for the current buffer. It is called within
-@code{save-excursion}, so where it leaves point makes no difference.
-
-The index alist can have three types of elements. Simple elements
-look like this:
-
-@example
-(@var{index-name} . @var{index-position})
-@end example
-
-Selecting a simple element has the effect of moving to position
-@var{index-position} in the buffer. Special elements look like this:
-
-@example
-(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
-@end example
-
-Selecting a special element performs:
-
-@example
-(funcall @var{function}
- @var{index-name} @var{index-position} @var{arguments}@dots{})
-@end example
-
-A nested sub-alist element looks like this:
-
-@example
-(@var{menu-title} @var{sub-alist})
-@end example
-
-It creates the submenu @var{menu-title} specified by @var{sub-alist}.
-
-The default value of @code{imenu-create-index-function} is
-@code{imenu-default-create-index-function}. This function calls the
-value of @code{imenu-prev-index-position-function} and the value of
-@code{imenu-extract-index-name-function} to produce the index alist.
-However, if either of these two variables is @code{nil}, the default
-function uses @code{imenu-generic-expression} instead.
-
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
-
-@node Font Lock Mode
-@section Font Lock Mode
-@cindex Font Lock mode
-
- @dfn{Font Lock mode} is a feature that automatically attaches
-@code{face} properties to certain parts of the buffer based on their
-syntactic role. How it parses the buffer depends on the major mode;
-most major modes define syntactic criteria for which faces to use in
-which contexts. This section explains how to customize Font Lock for a
-particular major mode.
-
- Font Lock mode finds text to highlight in two ways: through
-syntactic parsing based on the syntax table, and through searching
-(usually for regular expressions). Syntactic fontification happens
-first; it finds comments and string constants and highlights them.
-Search-based fontification happens second.
-
-@menu
-* 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.
-@end menu
-
-@node Font Lock Basics
-@subsection Font Lock Basics
-
- There are several variables that control how Font Lock mode highlights
-text. But major modes should not set any of these variables directly.
-Instead, they should set @code{font-lock-defaults} as a buffer-local
-variable. The value assigned to this variable is used, if and when Font
-Lock mode is enabled, to set all the other variables.
-
-@defvar font-lock-defaults
-This variable is set by major modes, as a buffer-local variable, to
-specify how to fontify text in that mode. It automatically becomes
-buffer-local when you set it. If its value is @code{nil}, Font-Lock
-mode does no highlighting, and you can use the @samp{Faces} menu
-(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to
-assign faces explicitly to text in the buffer.
-
-If non-@code{nil}, the value should look like this:
-
-@example
-(@var{keywords} [@var{keywords-only} [@var{case-fold}
- [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
-@end example
-
-The first element, @var{keywords}, indirectly specifies the value of
-@code{font-lock-keywords} which directs search-based fontification.
-It can be a symbol, a variable or a function whose value is the list
-to use for @code{font-lock-keywords}. It can also be a list of
-several such symbols, one for each possible level of fontification.
-The first symbol specifies how to do level 1 fontification, the second
-symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
-
-The second element, @var{keywords-only}, specifies the value of the
-variable @code{font-lock-keywords-only}. If this is omitted or
-@code{nil}, syntactic fontification (of strings and comments) is also
-performed. If this is non-@code{nil}, such fontification is not
-performed. @xref{Syntactic Font Lock}.
-
-The third element, @var{case-fold}, specifies the value of
-@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
-Font Lock mode ignores case when searching as directed by
-@code{font-lock-keywords}.
-
-If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
-should be a list of cons cells of the form @code{(@var{char-or-string}
-. @var{string})}. These are used to set up a syntax table for
-syntactic fontification (@pxref{Syntax Table Functions}). The
-resulting syntax table is stored in @code{font-lock-syntax-table}.
-
-The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}. We recommend setting
-this variable to @code{nil} and using @code{syntax-begin-function}
-instead.
-
-All the remaining elements (if any) are collectively called
-@var{other-vars}. Each of these elements should have the form
-@code{(@var{variable} . @var{value})}---which means, make
-@var{variable} buffer-local and then set it to @var{value}. You can
-use these @var{other-vars} to set other variables that affect
-fontification, aside from those you can control with the first five
-elements. @xref{Other Font Lock Variables}.
-@end defvar
-
- If your mode fontifies text explicitly by adding
-@code{font-lock-face} properties, it can specify @code{(nil t)} for
-@code{font-lock-defaults} to turn off all automatic fontification.
-However, this is not required; it is possible to fontify some things
-using @code{font-lock-face} properties and set up automatic
-fontification for other parts of the text.
-
-@node Search-based Fontification
-@subsection Search-based Fontification
-
- The most important variable for customizing Font Lock mode is
-@code{font-lock-keywords}. It specifies the search criteria for
-search-based fontification. You should specify the value of this
-variable with @var{keywords} in @code{font-lock-defaults}.
-
-@defvar font-lock-keywords
-This variable's value is a list of the keywords to highlight. Be
-careful when composing regular expressions for this list; a poorly
-written pattern can dramatically slow things down!
-@end defvar
-
- Each element of @code{font-lock-keywords} specifies how to find
-certain cases of text, and how to highlight those cases. Font Lock mode
-processes the elements of @code{font-lock-keywords} one by one, and for
-each element, it finds and handles all matches. Ordinarily, once
-part of the text has been fontified already, this cannot be overridden
-by a subsequent match in the same text; but you can specify different
-behavior using the @var{override} element of a @var{subexp-highlighter}.
-
- Each element of @code{font-lock-keywords} should have one of these
-forms:
-
-@table @code
-@item @var{regexp}
-Highlight all matches for @var{regexp} using
-@code{font-lock-keyword-face}. For example,
-
-@example
-;; @r{Highlight occurrences of the word @samp{foo}}
-;; @r{using @code{font-lock-keyword-face}.}
-"\\<foo\\>"
-@end example
-
-The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
-for calculating optimal regular expressions to match a number of
-different keywords.
-
-@item @var{function}
-Find text by calling @var{function}, and highlight the matches
-it finds using @code{font-lock-keyword-face}.
-
-When @var{function} is called, it receives one argument, the limit of
-the search; it should begin searching at point, and not search beyond the
-limit. It should return non-@code{nil} if it succeeds, and set the
-match data to describe the match that was found. Returning @code{nil}
-indicates failure of the search.
-
-Fontification will call @var{function} repeatedly with the same limit,
-and with point where the previous invocation left it, until
-@var{function} fails. On failure, @var{function} need not reset point
-in any particular way.
-
-@item (@var{matcher} . @var{subexp})
-In this kind of element, @var{matcher} is either a regular
-expression or a function, as described above. The @sc{cdr},
-@var{subexp}, specifies which subexpression of @var{matcher} should be
-highlighted (instead of the entire text that @var{matcher} matched).
-
-@example
-;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
-;; @r{using @code{font-lock-keyword-face}.}
-("fu\\(bar\\)" . 1)
-@end example
-
-If you use @code{regexp-opt} to produce the regular expression
-@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
-Functions}) to calculate the value for @var{subexp}.
-
-@item (@var{matcher} . @var{facespec})
-In this kind of element, @var{facespec} is an expression whose value
-specifies the face to use for highlighting. In the simplest case,
-@var{facespec} is a Lisp variable (a symbol) whose value is a face
-name.
-
-@example
-;; @r{Highlight occurrences of @samp{fubar},}
-;; @r{using the face which is the value of @code{fubar-face}.}
-("fubar" . fubar-face)
-@end example
-
-However, @var{facespec} can also evaluate to a list of this form:
-
-@example
-(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
-@end example
-
-@noindent
-to specify the face @var{face} and various additional text properties
-to put on the text that matches. If you do this, be sure to add the
-other text property names that you set in this way to the value of
-@code{font-lock-extra-managed-props} so that the properties will also
-be cleared out when they are no longer appropriate. Alternatively,
-you can set the variable @code{font-lock-unfontify-region-function} to
-a function that clears these properties. @xref{Other Font Lock
-Variables}.
-
-@item (@var{matcher} . @var{subexp-highlighter})
-In this kind of element, @var{subexp-highlighter} is a list
-which specifies how to highlight matches found by @var{matcher}.
-It has the form:
-
-@example
-(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
-@end example
-
-The @sc{car}, @var{subexp}, is an integer specifying which subexpression
-of the match to fontify (0 means the entire matching text). The second
-subelement, @var{facespec}, is an expression whose value specifies the
-face, as described above.
-
-The last two values in @var{subexp-highlighter}, @var{override} and
-@var{laxmatch}, are optional flags. If @var{override} is @code{t},
-this element can override existing fontification made by previous
-elements of @code{font-lock-keywords}. If it is @code{keep}, then
-each character is fontified if it has not been fontified already by
-some other element. If it is @code{prepend}, the face specified by
-@var{facespec} is added to the beginning of the @code{font-lock-face}
-property. If it is @code{append}, the face is added to the end of the
-@code{font-lock-face} property.
-
-If @var{laxmatch} is non-@code{nil}, it means there should be no error
-if there is no subexpression numbered @var{subexp} in @var{matcher}.
-Obviously, fontification of the subexpression numbered @var{subexp} will
-not occur. However, fontification of other subexpressions (and other
-regexps) will continue. If @var{laxmatch} is @code{nil}, and the
-specified subexpression is missing, then an error is signaled which
-terminates search-based fontification.
-
-Here are some examples of elements of this kind, and what they do:
-
-@smallexample
-;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
-;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
-;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
-("foo\\|bar" 0 foo-bar-face t)
-
-;; @r{Highlight the first subexpression within each occurrence}
-;; @r{that the function @code{fubar-match} finds,}
-;; @r{using the face which is the value of @code{fubar-face}.}
-(fubar-match 1 fubar-face)
-@end smallexample
-
-@item (@var{matcher} . @var{anchored-highlighter})
-In this kind of element, @var{anchored-highlighter} specifies how to
-highlight text that follows a match found by @var{matcher}. So a
-match found by @var{matcher} acts as the anchor for further searches
-specified by @var{anchored-highlighter}. @var{anchored-highlighter}
-is a list of the following form:
-
-@example
-(@var{anchored-matcher} @var{pre-form} @var{post-form}
- @var{subexp-highlighters}@dots{})
-@end example
-
-Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
-expression or a function. After a match of @var{matcher} is found,
-point is at the end of the match. Now, Font Lock evaluates the form
-@var{pre-form}. Then it searches for matches of
-@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
-these. A @var{subexp-highlighter} is as described above. Finally,
-Font Lock evaluates @var{post-form}.
-
-The forms @var{pre-form} and @var{post-form} can be used to initialize
-before, and cleanup after, @var{anchored-matcher} is used. Typically,
-@var{pre-form} is used to move point to some position relative to the
-match of @var{matcher}, before starting with @var{anchored-matcher}.
-@var{post-form} might be used to move back, before resuming with
-@var{matcher}.
-
-After Font Lock evaluates @var{pre-form}, it does not search for
-@var{anchored-matcher} beyond the end of the line. However, if
-@var{pre-form} returns a buffer position that is greater than the
-position of point after @var{pre-form} is evaluated, then the position
-returned by @var{pre-form} is used as the limit of the search instead.
-It is generally a bad idea to return a position greater than the end
-of the line; in other words, the @var{anchored-matcher} search should
-not span lines.
-
-For example,
-
-@smallexample
-;; @r{Highlight occurrences of the word @samp{item} following}
-;; @r{an occurrence of the word @samp{anchor} (on the same line)}
-;; @r{in the value of @code{item-face}.}
-("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
-@end smallexample
-
-Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
-searching for @samp{item} starts at the end of the match of
-@samp{anchor}, and searching for subsequent instances of @samp{anchor}
-resumes from where searching for @samp{item} concluded.
-
-@item (@var{matcher} @var{highlighters}@dots{})
-This sort of element specifies several @var{highlighter} lists for a
-single @var{matcher}. A @var{highlighter} list can be of the type
-@var{subexp-highlighter} or @var{anchored-highlighter} as described
-above.
-
-For example,
-
-@smallexample
-;; @r{Highlight occurrences of the word @samp{anchor} in the value}
-;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
-;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
-("\\<anchor\\>" (0 anchor-face)
- ("\\<item\\>" nil nil (0 item-face)))
-@end smallexample
-
-@item (eval . @var{form})
-Here @var{form} is an expression to be evaluated the first time
-this value of @code{font-lock-keywords} is used in a buffer.
-Its value should have one of the forms described in this table.
-@end table
-
-@strong{Warning:} Do not design an element of @code{font-lock-keywords}
-to match text which spans lines; this does not work reliably.
-For details, see @xref{Multiline Font Lock}.
-
-You can use @var{case-fold} in @code{font-lock-defaults} to specify
-the value of @code{font-lock-keywords-case-fold-search} which says
-whether search-based fontification should be case-insensitive.
-
-@defvar font-lock-keywords-case-fold-search
-Non-@code{nil} means that regular expression matching for the sake of
-@code{font-lock-keywords} should be case-insensitive.
-@end defvar
-
-@node Customizing Keywords
-@subsection Customizing Search-Based Fontification
-
- You can use @code{font-lock-add-keywords} to add additional
-search-based fontification rules to a major mode, and
-@code{font-lock-remove-keywords} to removes rules.
-
-@defun font-lock-add-keywords mode keywords &optional how
-This function adds highlighting @var{keywords}, for the current buffer
-or for major mode @var{mode}. The argument @var{keywords} should be a
-list with the same format as the variable @code{font-lock-keywords}.
-
-If @var{mode} is a symbol which is a major mode command name, such as
-@code{c-mode}, the effect is that enabling Font Lock mode in
-@var{mode} will add @var{keywords} to @code{font-lock-keywords}.
-Calling with a non-@code{nil} value of @var{mode} is correct only in
-your @file{~/.emacs} file.
-
-If @var{mode} is @code{nil}, this function adds @var{keywords} to
-@code{font-lock-keywords} in the current buffer. This way of calling
-@code{font-lock-add-keywords} is usually used in mode hook functions.
-
-By default, @var{keywords} are added at the beginning of
-@code{font-lock-keywords}. If the optional argument @var{how} is
-@code{set}, they are used to replace the value of
-@code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
-value, they are added at the end of @code{font-lock-keywords}.
-
-Some modes provide specialized support you can use in additional
-highlighting patterns. See the variables
-@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
-and @code{java-font-lock-extra-types}, for example.
-
-@strong{Warning:} major mode functions must not call
-@code{font-lock-add-keywords} under any circumstances, either directly
-or indirectly, except through their mode hooks. (Doing so would lead
-to incorrect behavior for some minor modes.) They should set up their
-rules for search-based fontification by setting
-@code{font-lock-keywords}.
-@end defun
-
-@defun font-lock-remove-keywords mode keywords
-This function removes @var{keywords} from @code{font-lock-keywords}
-for the current buffer or for major mode @var{mode}. As in
-@code{font-lock-add-keywords}, @var{mode} should be a major mode
-command name or @code{nil}. All the caveats and requirements for
-@code{font-lock-add-keywords} apply here too.
-@end defun
-
- For example, this code
-
-@smallexample
-(font-lock-add-keywords 'c-mode
- '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
- ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
-@end smallexample
-
-@noindent
-adds two fontification patterns for C mode: one to fontify the word
-@samp{FIXME}, even in comments, and another to fontify the words
-@samp{and}, @samp{or} and @samp{not} as keywords.
-
-@noindent
-That example affects only C mode proper. To add the same patterns to
-C mode @emph{and} all modes derived from it, do this instead:
-
-@smallexample
-(add-hook 'c-mode-hook
- (lambda ()
- (font-lock-add-keywords nil
- '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
- ("\\<\\(and\\|or\\|not\\)\\>" .
- font-lock-keyword-face)))))
-@end smallexample
-
-@node Other Font Lock Variables
-@subsection Other Font Lock Variables
-
- This section describes additional variables that a major mode can
-set by means of @var{other-vars} in @code{font-lock-defaults}
-(@pxref{Font Lock Basics}).
-
-@defvar font-lock-mark-block-function
-If this variable is non-@code{nil}, it should be a function that is
-called with no arguments, to choose an enclosing range of text for
-refontification for the command @kbd{M-o M-o}
-(@code{font-lock-fontify-block}).
-
-The function should report its choice by placing the region around it.
-A good choice is a range of text large enough to give proper results,
-but not too large so that refontification becomes slow. Typical values
-are @code{mark-defun} for programming modes or @code{mark-paragraph} for
-textual modes.
-@end defvar
-
-@defvar font-lock-extra-managed-props
-This variable specifies additional properties (other than
-@code{font-lock-face}) that are being managed by Font Lock mode. It
-is used by @code{font-lock-default-unfontify-region}, which normally
-only manages the @code{font-lock-face} property. If you want Font
-Lock to manage other properties as well, you must specify them in a
-@var{facespec} in @code{font-lock-keywords} as well as add them to
-this list. @xref{Search-based Fontification}.
-@end defvar
-
-@defvar font-lock-fontify-buffer-function
-Function to use for fontifying the buffer. The default value is
-@code{font-lock-default-fontify-buffer}.
-@end defvar
-
-@defvar font-lock-unfontify-buffer-function
-Function to use for unfontifying the buffer. This is used when
-turning off Font Lock mode. The default value is
-@code{font-lock-default-unfontify-buffer}.
-@end defvar
-
-@defvar font-lock-fontify-region-function
-Function to use for fontifying a region. It should take two
-arguments, the beginning and end of the region, and an optional third
-argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
-function should print status messages. The default value is
-@code{font-lock-default-fontify-region}.
-@end defvar
-
-@defvar font-lock-unfontify-region-function
-Function to use for unfontifying a region. It should take two
-arguments, the beginning and end of the region. The default value is
-@code{font-lock-default-unfontify-region}.
-@end defvar
-
-@ignore
-@defvar font-lock-inhibit-thing-lock
-List of Font Lock mode related modes that should not be turned on.
-Currently, valid mode names are @code{fast-lock-mode},
-@code{jit-lock-mode} and @code{lazy-lock-mode}.
-@end defvar
-@end ignore
-
-@node Levels of Font Lock
-@subsection Levels of Font Lock
-
- Many major modes offer three different levels of fontification. You
-can define multiple levels by using a list of symbols for @var{keywords}
-in @code{font-lock-defaults}. Each symbol specifies one level of
-fontification; it is up to the user to choose one of these levels. The
-chosen level's symbol value is used to initialize
-@code{font-lock-keywords}.
-
- Here are the conventions for how to define the levels of
-fontification:
-
-@itemize @bullet
-@item
-Level 1: highlight function declarations, file directives (such as include or
-import directives), strings and comments. The idea is speed, so only
-the most important and top-level components are fontified.
-
-@item
-Level 2: in addition to level 1, highlight all language keywords,
-including type names that act like keywords, as well as named constant
-values. The idea is that all keywords (either syntactic or semantic)
-should be fontified appropriately.
-
-@item
-Level 3: in addition to level 2, highlight the symbols being defined in
-function and variable declarations, and all builtin function names,
-wherever they appear.
-@end itemize
-
-@node Precalculated Fontification
-@subsection Precalculated Fontification
-
- In addition to using @code{font-lock-defaults} for search-based
-fontification, you may use the special character property
-@code{font-lock-face} (@pxref{Special Properties}). This property
-acts just like the explicit @code{face} property, but its activation
-is toggled when the user calls @kbd{M-x font-lock-mode}. Using
-@code{font-lock-face} is especially convenient for special modes
-which construct their text programmatically, such as
-@code{list-buffers} and @code{occur}.
-
-If your mode does not use any of the other machinery of Font Lock
-(i.e. it only uses the @code{font-lock-face} property), it should not
-set the variable @code{font-lock-defaults}.
-
-@node Faces for Font Lock
-@subsection Faces for Font Lock
-@cindex faces for font lock
-@cindex font lock faces
-
- You can make Font Lock mode use any face, but several faces are
-defined specifically for Font Lock mode. Each of these symbols is both
-a face name, and a variable whose default value is the symbol itself.
-Thus, the default value of @code{font-lock-comment-face} is
-@code{font-lock-comment-face}. This means you can write
-@code{font-lock-comment-face} in a context such as
-@code{font-lock-keywords} where a face-name-valued expression is used.
-
-@table @code
-@item font-lock-comment-face
-@vindex font-lock-comment-face
-Used (typically) for comments.
-
-@item font-lock-comment-delimiter-face
-@vindex font-lock-comment-delimiter-face
-Used (typically) for comments delimiters.
-
-@item font-lock-doc-face
-@vindex font-lock-doc-face
-Used (typically) for documentation strings in the code.
-
-@item font-lock-string-face
-@vindex font-lock-string-face
-Used (typically) for string constants.
-
-@item font-lock-keyword-face
-@vindex font-lock-keyword-face
-Used (typically) for keywords---names that have special syntactic
-significance, like @code{for} and @code{if} in C.
-
-@item font-lock-builtin-face
-@vindex font-lock-builtin-face
-Used (typically) for built-in function names.
-
-@item font-lock-function-name-face
-@vindex font-lock-function-name-face
-Used (typically) for the name of a function being defined or declared,
-in a function definition or declaration.
-
-@item font-lock-variable-name-face
-@vindex font-lock-variable-name-face
-Used (typically) for the name of a variable being defined or declared,
-in a variable definition or declaration.
-
-@item font-lock-type-face
-@vindex font-lock-type-face
-Used (typically) for names of user-defined data types,
-where they are defined and where they are used.
-
-@item font-lock-constant-face
-@vindex font-lock-constant-face
-Used (typically) for constant names.
-
-@item font-lock-preprocessor-face
-@vindex font-lock-preprocessor-face
-Used (typically) for preprocessor commands.
-
-@item font-lock-negation-char-face
-@vindex font-lock-negation-char-face
-Used (typically) for easily-overlooked negation characters.
-
-@item font-lock-warning-face
-@vindex font-lock-warning-face
-Used (typically) for constructs that are peculiar, or that greatly
-change the meaning of other text. For example, this is used for
-@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
-directives in C.
-@end table
-
-@node Syntactic Font Lock
-@subsection Syntactic Font Lock
-@cindex syntactic font lock
-
-Syntactic fontification uses the syntax table to find comments and
-string constants (@pxref{Syntax Tables}). It highlights them using
-@code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}), or whatever
-@code{font-lock-syntactic-face-function} chooses. There are several
-variables that affect syntactic fontification; you should set them by
-means of @code{font-lock-defaults} (@pxref{Font Lock Basics}).
-
-@defvar font-lock-keywords-only
-Non-@code{nil} means Font Lock should not do syntactic fontification;
-it should only fontify based on @code{font-lock-keywords}. The normal
-way for a mode to set this variable to @code{t} is with
-@var{keywords-only} in @code{font-lock-defaults}.
-@end defvar
-
-@defvar font-lock-syntax-table
-This variable holds the syntax table to use for fontification of
-comments and strings. Specify it using @var{syntax-alist} in
-@code{font-lock-defaults}. If this is @code{nil}, fontification uses
-the buffer's syntax table.
-@end defvar
-
-@defvar font-lock-beginning-of-syntax-function
-If this variable is non-@code{nil}, it should be a function to move
-point back to a position that is syntactically at ``top level'' and
-outside of strings or comments. Font Lock uses this when necessary
-to get the right results for syntactic fontification.
-
-This function is called with no arguments. It should leave point at
-the beginning of any enclosing syntactic block. Typical values are
-@code{beginning-of-line} (used when the start of the line is known to
-be outside a syntactic block), or @code{beginning-of-defun} for
-programming modes, or @code{backward-paragraph} for textual modes.
-
-If the value is @code{nil}, Font Lock uses
-@code{syntax-begin-function} to move back outside of any comment,
-string, or sexp. This variable is semi-obsolete; we recommend setting
-@code{syntax-begin-function} instead.
-
-Specify this variable using @var{syntax-begin} in
-@code{font-lock-defaults}.
-@end defvar
-
-@defvar font-lock-syntactic-face-function
-A function to determine which face to use for a given syntactic
-element (a string or a comment). The function is called with one
-argument, the parse state at point returned by
-@code{parse-partial-sexp}, and should return a face. The default
-value returns @code{font-lock-comment-face} for comments and
-@code{font-lock-string-face} for strings.
-
-This can be used to highlighting different kinds of strings or
-comments differently. It is also sometimes abused together with
-@code{font-lock-syntactic-keywords} to highlight constructs that span
-multiple lines, but this is too esoteric to document here.
-
-Specify this variable using @var{other-vars} in
-@code{font-lock-defaults}.
-@end defvar
-
-@node Setting Syntax Properties
-@subsection Setting Syntax Properties
-
- Font Lock mode can be used to update @code{syntax-table} properties
-automatically (@pxref{Syntax Properties}). This is useful in
-languages for which a single syntax table by itself is not sufficient.
-
-@defvar font-lock-syntactic-keywords
-This variable enables and controls updating @code{syntax-table}
-properties by Font Lock. Its value should be a list of elements of
-this form:
-
-@example
-(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
-@end example
-
-The parts of this element have the same meanings as in the corresponding
-sort of element of @code{font-lock-keywords},
-
-@example
-(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
-@end example
-
-However, instead of specifying the value @var{facespec} to use for the
-@code{face} property, it specifies the value @var{syntax} to use for
-the @code{syntax-table} property. Here, @var{syntax} can be a string
-(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
-(as returned by @code{string-to-syntax}), or an expression whose value
-is one of those two types. @var{override} cannot be @code{prepend} or
-@code{append}.
-
-For example, an element of the form:
-
-@example
-("\\$\\(#\\)" 1 ".")
-@end example
-
-highlights syntactically a hash character when following a dollar
-character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
-Assuming that the buffer syntax table specifies hash characters to
-have comment start syntax, the element will only highlight hash
-characters that do not follow dollar characters as comments
-syntactically.
-
-An element of the form:
-
-@example
- ("\\('\\).\\('\\)"
- (1 "\"")
- (2 "\""))
-@end example
-
-highlights syntactically both single quotes which surround a single
-character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
-Assuming that the buffer syntax table does not specify single quotes
-to have quote syntax, the element will only highlight single quotes of
-the form @samp{'@var{c}'} as strings syntactically. Other forms, such
-as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
-strings.
-
-Major modes normally set this variable with @var{other-vars} in
-@code{font-lock-defaults}.
-@end defvar
-
-@node Multiline Font Lock
-@subsection Multiline Font Lock Constructs
-@cindex multiline font lock
-
- Normally, elements of @code{font-lock-keywords} should not match
-across multiple lines; that doesn't work reliably, because Font Lock
-usually scans just part of the buffer, and it can miss a multi-line
-construct that crosses the line boundary where the scan starts. (The
-scan normally starts at the beginning of a line.)
-
- Making elements that match multiline constructs work properly has
-two aspects: correct @emph{identification} and correct
-@emph{rehighlighting}. The first means that Font Lock finds all
-multiline constructs. The second means that Font Lock will correctly
-rehighlight all the relevant text when a multiline construct is
-changed---for example, if some of the text that was previously part of
-a multiline construct ceases to be part of it. The two aspects are
-closely related, and often getting one of them to work will appear to
-make the other also work. However, for reliable results you must
-attend explicitly to both aspects.
-
- There are three ways to ensure correct identification of multiline
-constructs:
-
-@itemize
-@item
-Add a function to @code{font-lock-extend-region-functions} that does
-the @emph{identification} and extends the scan so that the scanned
-text never starts or ends in the middle of a multiline construct.
-@item
-Use the @code{font-lock-fontify-region-function} hook similarly to
-extend the scan so that the scanned text never starts or ends in the
-middle of a multiline construct.
-@item
-Somehow identify the multiline construct right when it gets inserted
-into the buffer (or at any point after that but before font-lock
-tries to highlight it), and mark it with a @code{font-lock-multiline}
-which will instruct font-lock not to start or end the scan in the
-middle of the construct.
-@end itemize
-
- There are three ways to do rehighlighting of multiline constructs:
-
-@itemize
-@item
-Place a @code{font-lock-multiline} property on the construct. This
-will rehighlight the whole construct if any part of it is changed. In
-some cases you can do this automatically by setting the
-@code{font-lock-multiline} variable, which see.
-@item
-Make sure @code{jit-lock-contextually} is set and rely on it doing its
-job. This will only rehighlight the part of the construct that
-follows the actual change, and will do it after a short delay.
-This only works if the highlighting of the various parts of your
-multiline construct never depends on text in subsequent lines.
-Since @code{jit-lock-contextually} is activated by default, this can
-be an attractive solution.
-@item
-Place a @code{jit-lock-defer-multiline} property on the construct.
-This works only if @code{jit-lock-contextually} is used, and with the
-same delay before rehighlighting, but like @code{font-lock-multiline},
-it also handles the case where highlighting depends on
-subsequent lines.
-@end itemize
-
-@menu
-* Font Lock Multiline:: Marking multiline chunks with a text property
-* Region to Fontify:: Controlling which region gets refontified
- after a buffer change.
-@end menu
-
-@node Font Lock Multiline
-@subsubsection Font Lock Multiline
-
- One way to ensure reliable rehighlighting of multiline Font Lock
-constructs is to put on them the text property @code{font-lock-multiline}.
-It should be present and non-@code{nil} for text that is part of a
-multiline construct.
-
- When Font Lock is about to highlight a range of text, it first
-extends the boundaries of the range as necessary so that they do not
-fall within text marked with the @code{font-lock-multiline} property.
-Then it removes any @code{font-lock-multiline} properties from the
-range, and highlights it. The highlighting specification (mostly
-@code{font-lock-keywords}) must reinstall this property each time,
-whenever it is appropriate.
-
- @strong{Warning:} don't use the @code{font-lock-multiline} property
-on large ranges of text, because that will make rehighlighting slow.
-
-@defvar font-lock-multiline
-If the @code{font-lock-multiline} variable is set to @code{t}, Font
-Lock will try to add the @code{font-lock-multiline} property
-automatically on multiline constructs. This is not a universal
-solution, however, since it slows down Font Lock somewhat. It can
-miss some multiline constructs, or make the property larger or smaller
-than necessary.
-
-For elements whose @var{matcher} is a function, the function should
-ensure that submatch 0 covers the whole relevant multiline construct,
-even if only a small subpart will be highlighted. It is often just as
-easy to add the @code{font-lock-multiline} property by hand.
-@end defvar
-
- The @code{font-lock-multiline} property is meant to ensure proper
-refontification; it does not automatically identify new multiline
-constructs. Identifying the requires that Font-Lock operate on large
-enough chunks at a time. This will happen by accident on many cases,
-which may give the impression that multiline constructs magically work.
-If you set the @code{font-lock-multiline} variable non-@code{nil},
-this impression will be even stronger, since the highlighting of those
-constructs which are found will be properly updated from then on.
-But that does not work reliably.
-
- To find multiline constructs reliably, you must either manually
-place the @code{font-lock-multiline} property on the text before
-Font-Lock looks at it, or use
-@code{font-lock-fontify-region-function}.
-
-@node Region to Fontify
-@subsubsection Region to Fontify after a Buffer Change
-
- When a buffer is changed, the region that Font Lock refontifies is
-by default the smallest sequence of whole lines that spans the change.
-While this works well most of the time, sometimes it doesn't---for
-example, when a change alters the syntactic meaning of text on an
-earlier line.
-
- You can enlarge (or even reduce) the region to fontify by setting
-one the following variables:
-
-@defvar font-lock-extend-after-change-region-function
-This buffer-local variable is either @code{nil} or a function for
-Font-Lock to call to determine the region to scan and fontify.
-
-The function is given three parameters, the standard @var{beg},
-@var{end}, and @var{old-len} from after-change-functions
-(@pxref{Change Hooks}). It should return either a cons of the
-beginning and end buffer positions (in that order) of the region to
-fontify, or @code{nil} (which means choose the region in the standard
-way). This function needs to preserve point, the match-data, and the
-current restriction. The region it returns may start or end in the
-middle of a line.
-
-Since this function is called after every buffer change, it should be
-reasonably fast.
-@end defvar
-
-@node Desktop Save Mode
-@section Desktop Save Mode
-@cindex desktop save mode
-
-@dfn{Desktop Save Mode} is a feature to save the state of Emacs from
-one session to another. The user-level commands for using Desktop
-Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
-Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
-a file, don't have to do anything to use this feature.
-
-For buffers not visiting a file to have their state saved, the major
-mode must bind the buffer local variable @code{desktop-save-buffer} to
-a non-@code{nil} value.
-
-@defvar desktop-save-buffer
-If this buffer-local variable is non-@code{nil}, the buffer will have
-its state saved in the desktop file at desktop save. If the value is
-a function, it is called at desktop save with argument
-@var{desktop-dirname}, and its value is saved in the desktop file along
-with the state of the buffer for which it was called. When file names
-are returned as part of the auxiliary information, they should be
-formatted using the call
-
-@example
-(desktop-file-name @var{file-name} @var{desktop-dirname})
-@end example
-
-@end defvar
-
-For buffers not visiting a file to be restored, the major mode must
-define a function to do the job, and that function must be listed in
-the alist @code{desktop-buffer-mode-handlers}.
-
-@defvar desktop-buffer-mode-handlers
-Alist with elements
-
-@example
-(@var{major-mode} . @var{restore-buffer-function})
-@end example
-
-The function @var{restore-buffer-function} will be called with
-argument list
-
-@example
-(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
-@end example
-
-and it should return the restored buffer.
-Here @var{desktop-buffer-misc} is the value returned by the function
-optionally bound to @code{desktop-save-buffer}.
-@end defvar
-
-@ignore
- arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
-@end ignore
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/characters
-@node Non-ASCII Characters, Searching and Matching, Text, Top
-@chapter Non-@acronym{ASCII} Characters
-@cindex multibyte characters
-@cindex characters, multi-byte
-@cindex non-@acronym{ASCII} characters
-
- This chapter covers the special issues relating to non-@acronym{ASCII}
-characters and how they are stored in strings and buffers.
-
-@menu
-* 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.
-@end menu
-
-@node Text Representations
-@section Text Representations
-@cindex text representations
-
- Emacs has two @dfn{text representations}---two ways to represent text
-in a string or buffer. These are called @dfn{unibyte} and
-@dfn{multibyte}. Each string, and each buffer, uses one of these two
-representations. For most purposes, you can ignore the issue of
-representations, because Emacs converts text between them as
-appropriate. Occasionally in Lisp programming you will need to pay
-attention to the difference.
-
-@cindex unibyte text
- In unibyte representation, each character occupies one byte and
-therefore the possible character codes range from 0 to 255. Codes 0
-through 127 are @acronym{ASCII} characters; the codes from 128 through 255
-are used for one non-@acronym{ASCII} character set (you can choose which
-character set by setting the variable @code{nonascii-insert-offset}).
-
-@cindex leading code
-@cindex multibyte text
-@cindex trailing codes
- In multibyte representation, a character may occupy more than one
-byte, and as a result, the full range of Emacs character codes can be
-stored. The first byte of a multibyte character is always in the range
-128 through 159 (octal 0200 through 0237). These values are called
-@dfn{leading codes}. The second and subsequent bytes of a multibyte
-character are always in the range 160 through 255 (octal 0240 through
-0377); these values are @dfn{trailing codes}.
-
- Some sequences of bytes are not valid in multibyte text: for example,
-a single isolated byte in the range 128 through 159 is not allowed. But
-character codes 128 through 159 can appear in multibyte text,
-represented as two-byte sequences. All the character codes 128 through
-255 are possible (though slightly abnormal) in multibyte text; they
-appear in multibyte buffers and strings when you do explicit encoding
-and decoding (@pxref{Explicit Encoding}).
-
- In a buffer, the buffer-local value of the variable
-@code{enable-multibyte-characters} specifies the representation used.
-The representation for a string is determined and recorded in the string
-when the string is constructed.
-
-@defvar enable-multibyte-characters
-This variable specifies the current buffer's text representation.
-If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
-it contains unibyte text.
-
-You cannot set this variable directly; instead, use the function
-@code{set-buffer-multibyte} to change a buffer's representation.
-@end defvar
-
-@defvar default-enable-multibyte-characters
-This variable's value is entirely equivalent to @code{(default-value
-'enable-multibyte-characters)}, and setting this variable changes that
-default value. Setting the local binding of
-@code{enable-multibyte-characters} in a specific buffer is not allowed,
-but changing the default value is supported, and it is a reasonable
-thing to do, because it has no effect on existing buffers.
-
-The @samp{--unibyte} command line option does its job by setting the
-default value to @code{nil} early in startup.
-@end defvar
-
-@defun position-bytes position
-Return the byte-position corresponding to buffer position
-@var{position} in the current buffer. This is 1 at the start of the
-buffer, and counts upward in bytes. If @var{position} is out of
-range, the value is @code{nil}.
-@end defun
-
-@defun byte-to-position byte-position
-Return the buffer position corresponding to byte-position
-@var{byte-position} in the current buffer. If @var{byte-position} is
-out of range, the value is @code{nil}.
-@end defun
-
-@defun multibyte-string-p string
-Return @code{t} if @var{string} is a multibyte string.
-@end defun
-
-@defun string-bytes string
-@cindex string, number of bytes
-This function returns the number of bytes in @var{string}.
-If @var{string} is a multibyte string, this can be greater than
-@code{(length @var{string})}.
-@end defun
-
-@node Converting Representations
-@section Converting Text Representations
-
- Emacs can convert unibyte text to multibyte; it can also convert
-multibyte text to unibyte, though this conversion loses information. In
-general these conversions happen when inserting text into a buffer, or
-when putting text from several strings together in one string. You can
-also explicitly convert a string's contents to either representation.
-
- Emacs chooses the representation for a string based on the text that
-it is constructed from. The general rule is to convert unibyte text to
-multibyte text when combining it with other multibyte text, because the
-multibyte representation is more general and can hold whatever
-characters the unibyte text has.
-
- When inserting text into a buffer, Emacs converts the text to the
-buffer's representation, as specified by
-@code{enable-multibyte-characters} in that buffer. In particular, when
-you insert multibyte text into a unibyte buffer, Emacs converts the text
-to unibyte, even though this conversion cannot in general preserve all
-the characters that might be in the multibyte text. The other natural
-alternative, to convert the buffer contents to multibyte, is not
-acceptable because the buffer's representation is a choice made by the
-user that cannot be overridden automatically.
-
- Converting unibyte text to multibyte text leaves @acronym{ASCII} characters
-unchanged, and likewise character codes 128 through 159. It converts
-the non-@acronym{ASCII} codes 160 through 255 by adding the value
-@code{nonascii-insert-offset} to each character code. By setting this
-variable, you specify which character set the unibyte characters
-correspond to (@pxref{Character Sets}). For example, if
-@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
-'latin-iso8859-1) 128)}, then the unibyte non-@acronym{ASCII} characters
-correspond to Latin 1. If it is 2688, which is @code{(- (make-char
-'greek-iso8859-7) 128)}, then they correspond to Greek letters.
-
- Converting multibyte text to unibyte is simpler: it discards all but
-the low 8 bits of each character code. If @code{nonascii-insert-offset}
-has a reasonable value, corresponding to the beginning of some character
-set, this conversion is the inverse of the other: converting unibyte
-text to multibyte and back to unibyte reproduces the original unibyte
-text.
-
-@defvar nonascii-insert-offset
-This variable specifies the amount to add to a non-@acronym{ASCII} character
-when converting unibyte text to multibyte. It also applies when
-@code{self-insert-command} inserts a character in the unibyte
-non-@acronym{ASCII} range, 128 through 255. However, the functions
-@code{insert} and @code{insert-char} do not perform this conversion.
-
-The right value to use to select character set @var{cs} is @code{(-
-(make-char @var{cs}) 128)}. If the value of
-@code{nonascii-insert-offset} is zero, then conversion actually uses the
-value for the Latin 1 character set, rather than zero.
-@end defvar
-
-@defvar nonascii-translation-table
-This variable provides a more general alternative to
-@code{nonascii-insert-offset}. You can use it to specify independently
-how to translate each code in the range of 128 through 255 into a
-multibyte character. The value should be a char-table, or @code{nil}.
-If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
-@end defvar
-
-The next three functions either return the argument @var{string}, or a
-newly created string with no text properties.
-
-@defun string-make-unibyte string
-This function converts the text of @var{string} to unibyte
-representation, if it isn't already, and returns the result. If
-@var{string} is a unibyte string, it is returned unchanged. Multibyte
-character codes are converted to unibyte according to
-@code{nonascii-translation-table} or, if that is @code{nil}, using
-@code{nonascii-insert-offset}. If the lookup in the translation table
-fails, this function takes just the low 8 bits of each character.
-@end defun
-
-@defun string-make-multibyte string
-This function converts the text of @var{string} to multibyte
-representation, if it isn't already, and returns the result. If
-@var{string} is a multibyte string or consists entirely of
-@acronym{ASCII} characters, it is returned unchanged. In particular,
-if @var{string} is unibyte and entirely @acronym{ASCII}, the returned
-string is unibyte. (When the characters are all @acronym{ASCII},
-Emacs primitives will treat the string the same way whether it is
-unibyte or multibyte.) If @var{string} is unibyte and contains
-non-@acronym{ASCII} characters, the function
-@code{unibyte-char-to-multibyte} is used to convert each unibyte
-character to a multibyte character.
-@end defun
-
-@defun string-to-multibyte string
-This function returns a multibyte string containing the same sequence
-of character codes as @var{string}. Unlike
-@code{string-make-multibyte}, this function unconditionally returns a
-multibyte string. If @var{string} is a multibyte string, it is
-returned unchanged.
-@end defun
-
-@defun multibyte-char-to-unibyte char
-This convert the multibyte character @var{char} to a unibyte
-character, based on @code{nonascii-translation-table} and
-@code{nonascii-insert-offset}.
-@end defun
-
-@defun unibyte-char-to-multibyte char
-This convert the unibyte character @var{char} to a multibyte
-character, based on @code{nonascii-translation-table} and
-@code{nonascii-insert-offset}.
-@end defun
-
-@node Selecting a Representation
-@section Selecting a Representation
-
- Sometimes it is useful to examine an existing buffer or string as
-multibyte when it was unibyte, or vice versa.
-
-@defun set-buffer-multibyte multibyte
-Set the representation type of the current buffer. If @var{multibyte}
-is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte}
-is @code{nil}, the buffer becomes unibyte.
-
-This function leaves the buffer contents unchanged when viewed as a
-sequence of bytes. As a consequence, it can change the contents viewed
-as characters; a sequence of two bytes which is treated as one character
-in multibyte representation will count as two characters in unibyte
-representation. Character codes 128 through 159 are an exception. They
-are represented by one byte in a unibyte buffer, but when the buffer is
-set to multibyte, they are converted to two-byte sequences, and vice
-versa.
-
-This function sets @code{enable-multibyte-characters} to record which
-representation is in use. It also adjusts various data in the buffer
-(including overlays, text properties and markers) so that they cover the
-same text as they did before.
-
-You cannot use @code{set-buffer-multibyte} on an indirect buffer,
-because indirect buffers always inherit the representation of the
-base buffer.
-@end defun
-
-@defun string-as-unibyte string
-This function returns a string with the same bytes as @var{string} but
-treating each byte as a character. This means that the value may have
-more characters than @var{string} has.
-
-If @var{string} is already a unibyte string, then the value is
-@var{string} itself. Otherwise it is a newly created string, with no
-text properties. If @var{string} is multibyte, any characters it
-contains of charset @code{eight-bit-control} or @code{eight-bit-graphic}
-are converted to the corresponding single byte.
-@end defun
-
-@defun string-as-multibyte string
-This function returns a string with the same bytes as @var{string} but
-treating each multibyte sequence as one character. This means that the
-value may have fewer characters than @var{string} has.
-
-If @var{string} is already a multibyte string, then the value is
-@var{string} itself. Otherwise it is a newly created string, with no
-text properties. If @var{string} is unibyte and contains any individual
-8-bit bytes (i.e.@: not part of a multibyte form), they are converted to
-the corresponding multibyte character of charset @code{eight-bit-control}
-or @code{eight-bit-graphic}.
-@end defun
-
-@node Character Codes
-@section Character Codes
-@cindex character codes
-
- The unibyte and multibyte text representations use different character
-codes. The valid character codes for unibyte representation range from
-0 to 255---the values that can fit in one byte. The valid character
-codes for multibyte representation range from 0 to 524287, but not all
-values in that range are valid. The values 128 through 255 are not
-entirely proper in multibyte text, but they can occur if you do explicit
-encoding and decoding (@pxref{Explicit Encoding}). Some other character
-codes cannot occur at all in multibyte text. Only the @acronym{ASCII} codes
-0 through 127 are completely legitimate in both representations.
-
-@defun char-valid-p charcode &optional genericp
-This returns @code{t} if @var{charcode} is valid (either for unibyte
-text or for multibyte text).
-
-@example
-(char-valid-p 65)
- @result{} t
-(char-valid-p 256)
- @result{} nil
-(char-valid-p 2248)
- @result{} t
-@end example
-
-If the optional argument @var{genericp} is non-@code{nil}, this
-function also returns @code{t} if @var{charcode} is a generic
-character (@pxref{Splitting Characters}).
-@end defun
-
-@node Character Sets
-@section Character Sets
-@cindex character sets
-
- Emacs classifies characters into various @dfn{character sets}, each of
-which has a name which is a symbol. Each character belongs to one and
-only one character set.
-
- In general, there is one character set for each distinct script. For
-example, @code{latin-iso8859-1} is one character set,
-@code{greek-iso8859-7} is another, and @code{ascii} is another. An
-Emacs character set can hold at most 9025 characters; therefore, in some
-cases, characters that would logically be grouped together are split
-into several character sets. For example, one set of Chinese
-characters, generally known as Big 5, is divided into two Emacs
-character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
-
- @acronym{ASCII} characters are in character set @code{ascii}. The
-non-@acronym{ASCII} characters 128 through 159 are in character set
-@code{eight-bit-control}, and codes 160 through 255 are in character set
-@code{eight-bit-graphic}.
-
-@defun charsetp object
-Returns @code{t} if @var{object} is a symbol that names a character set,
-@code{nil} otherwise.
-@end defun
-
-@defvar charset-list
-The value is a list of all defined character set names.
-@end defvar
-
-@defun charset-list
-This function returns the value of @code{charset-list}. It is only
-provided for backward compatibility.
-@end defun
-
-@defun char-charset character
-This function returns the name of the character set that @var{character}
-belongs to, or the symbol @code{unknown} if @var{character} is not a
-valid character.
-@end defun
-
-@defun charset-plist charset
-This function returns the charset property list of the character set
-@var{charset}. Although @var{charset} is a symbol, this is not the same
-as the property list of that symbol. Charset properties are used for
-special purposes within Emacs.
-@end defun
-
-@deffn Command list-charset-chars charset
-This command displays a list of characters in the character set
-@var{charset}.
-@end deffn
-
-@node Chars and Bytes
-@section Characters and Bytes
-@cindex bytes and characters
-
-@cindex introduction sequence (of character)
-@cindex dimension (of character set)
- In multibyte representation, each character occupies one or more
-bytes. Each character set has an @dfn{introduction sequence}, which is
-normally one or two bytes long. (Exception: the @code{ascii} character
-set and the @code{eight-bit-graphic} character set have a zero-length
-introduction sequence.) The introduction sequence is the beginning of
-the byte sequence for any character in the character set. The rest of
-the character's bytes distinguish it from the other characters in the
-same character set. Depending on the character set, there are either
-one or two distinguishing bytes; the number of such bytes is called the
-@dfn{dimension} of the character set.
-
-@defun charset-dimension charset
-This function returns the dimension of @var{charset}; at present, the
-dimension is always 1 or 2.
-@end defun
-
-@defun charset-bytes charset
-This function returns the number of bytes used to represent a character
-in character set @var{charset}.
-@end defun
-
- This is the simplest way to determine the byte length of a character
-set's introduction sequence:
-
-@example
-(- (charset-bytes @var{charset})
- (charset-dimension @var{charset}))
-@end example
-
-@node Splitting Characters
-@section Splitting Characters
-@cindex character as bytes
-
- The functions in this section convert between characters and the byte
-values used to represent them. For most purposes, there is no need to
-be concerned with the sequence of bytes used to represent a character,
-because Emacs translates automatically when necessary.
-
-@defun split-char character
-Return a list containing the name of the character set of
-@var{character}, followed by one or two byte values (integers) which
-identify @var{character} within that character set. The number of byte
-values is the character set's dimension.
-
-If @var{character} is invalid as a character code, @code{split-char}
-returns a list consisting of the symbol @code{unknown} and @var{character}.
-
-@example
-(split-char 2248)
- @result{} (latin-iso8859-1 72)
-(split-char 65)
- @result{} (ascii 65)
-(split-char 128)
- @result{} (eight-bit-control 128)
-@end example
-@end defun
-
-@cindex generate characters in charsets
-@defun make-char charset &optional code1 code2
-This function returns the character in character set @var{charset} whose
-position codes are @var{code1} and @var{code2}. This is roughly the
-inverse of @code{split-char}. Normally, you should specify either one
-or both of @var{code1} and @var{code2} according to the dimension of
-@var{charset}. For example,
-
-@example
-(make-char 'latin-iso8859-1 72)
- @result{} 2248
-@end example
-
-Actually, the eighth bit of both @var{code1} and @var{code2} is zeroed
-before they are used to index @var{charset}. Thus you may use, for
-instance, an ISO 8859 character code rather than subtracting 128, as
-is necessary to index the corresponding Emacs charset.
-@end defun
-
-@cindex generic characters
- If you call @code{make-char} with no @var{byte-values}, the result is
-a @dfn{generic character} which stands for @var{charset}. A generic
-character is an integer, but it is @emph{not} valid for insertion in the
-buffer as a character. It can be used in @code{char-table-range} to
-refer to the whole character set (@pxref{Char-Tables}).
-@code{char-valid-p} returns @code{nil} for generic characters.
-For example:
-
-@example
-(make-char 'latin-iso8859-1)
- @result{} 2176
-(char-valid-p 2176)
- @result{} nil
-(char-valid-p 2176 t)
- @result{} t
-(split-char 2176)
- @result{} (latin-iso8859-1 0)
-@end example
-
-The character sets @code{ascii}, @code{eight-bit-control}, and
-@code{eight-bit-graphic} don't have corresponding generic characters. If
-@var{charset} is one of them and you don't supply @var{code1},
-@code{make-char} returns the character code corresponding to the
-smallest code in @var{charset}.
-
-@node Scanning Charsets
-@section Scanning for Character Sets
-
- Sometimes it is useful to find out which character sets appear in a
-part of a buffer or a string. One use for this is in determining which
-coding systems (@pxref{Coding Systems}) are capable of representing all
-of the text in question.
-
-@defun charset-after &optional pos
-This function return the charset of a character in the current buffer
-at position @var{pos}. If @var{pos} is omitted or @code{nil}, it
-defaults to the current value of point. If @var{pos} is out of range,
-the value is @code{nil}.
-@end defun
-
-@defun find-charset-region beg end &optional translation
-This function returns a list of the character sets that appear in the
-current buffer between positions @var{beg} and @var{end}.
-
-The optional argument @var{translation} specifies a translation table to
-be used in scanning the text (@pxref{Translation of Characters}). If it
-is non-@code{nil}, then each character in the region is translated
-through this table, and the value returned describes the translated
-characters instead of the characters actually in the buffer.
-@end defun
-
-@defun find-charset-string string &optional translation
-This function returns a list of the character sets that appear in the
-string @var{string}. It is just like @code{find-charset-region}, except
-that it applies to the contents of @var{string} instead of part of the
-current buffer.
-@end defun
-
-@node Translation of Characters
-@section Translation of Characters
-@cindex character translation tables
-@cindex translation tables
-
- A @dfn{translation table} is a char-table that specifies a mapping
-of characters into characters. These tables are used in encoding and
-decoding, and for other purposes. Some coding systems specify their
-own particular translation tables; there are also default translation
-tables which apply to all other coding systems.
-
- For instance, the coding-system @code{utf-8} has a translation table
-that maps characters of various charsets (e.g.,
-@code{latin-iso8859-@var{x}}) into Unicode character sets. This way,
-it can encode Latin-2 characters into UTF-8. Meanwhile,
-@code{unify-8859-on-decoding-mode} operates by specifying
-@code{standard-translation-table-for-decode} to translate
-Latin-@var{x} characters into corresponding Unicode characters.
-
-@defun make-translation-table &rest translations
-This function returns a translation table based on the argument
-@var{translations}. Each element of @var{translations} should be a
-list of elements of the form @code{(@var{from} . @var{to})}; this says
-to translate the character @var{from} into @var{to}.
-
-The arguments and the forms in each argument are processed in order,
-and if a previous form already translates @var{to} to some other
-character, say @var{to-alt}, @var{from} is also translated to
-@var{to-alt}.
-
-You can also map one whole character set into another character set with
-the same dimension. To do this, you specify a generic character (which
-designates a character set) for @var{from} (@pxref{Splitting Characters}).
-In this case, if @var{to} is also a generic character, its character
-set should have the same dimension as @var{from}'s. Then the
-translation table translates each character of @var{from}'s character
-set into the corresponding character of @var{to}'s character set. If
-@var{from} is a generic character and @var{to} is an ordinary
-character, then the translation table translates every character of
-@var{from}'s character set into @var{to}.
-@end defun
-
- In decoding, the translation table's translations are applied to the
-characters that result from ordinary decoding. If a coding system has
-property @code{translation-table-for-decode}, that specifies the
-translation table to use. (This is a property of the coding system,
-as returned by @code{coding-system-get}, not a property of the symbol
-that is the coding system's name. @xref{Coding System Basics,, Basic
-Concepts of Coding Systems}.) Otherwise, if
-@code{standard-translation-table-for-decode} is non-@code{nil},
-decoding uses that table.
-
- In encoding, the translation table's translations are applied to the
-characters in the buffer, and the result of translation is actually
-encoded. If a coding system has property
-@code{translation-table-for-encode}, that specifies the translation
-table to use. Otherwise the variable
-@code{standard-translation-table-for-encode} specifies the translation
-table.
-
-@defvar standard-translation-table-for-decode
-This is the default translation table for decoding, for
-coding systems that don't specify any other translation table.
-@end defvar
-
-@defvar standard-translation-table-for-encode
-This is the default translation table for encoding, for
-coding systems that don't specify any other translation table.
-@end defvar
-
-@defvar translation-table-for-input
-Self-inserting characters are translated through this translation
-table before they are inserted. Search commands also translate their
-input through this table, so they can compare more reliably with
-what's in the buffer.
-
-@code{set-buffer-file-coding-system} sets this variable so that your
-keyboard input gets translated into the character sets that the buffer
-is likely to contain. This variable automatically becomes
-buffer-local when set.
-@end defvar
-
-@node Coding Systems
-@section Coding Systems
-
-@cindex coding system
- When Emacs reads or writes a file, and when Emacs sends text to a
-subprocess or receives text from a subprocess, it normally performs
-character code conversion and end-of-line conversion as specified
-by a particular @dfn{coding system}.
-
- How to define a coding system is an arcane matter, and is not
-documented here.
-
-@menu
-* 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.
-@end menu
-
-@node Coding System Basics
-@subsection Basic Concepts of Coding Systems
-
-@cindex character code conversion
- @dfn{Character code conversion} involves conversion between the encoding
-used inside Emacs and some other encoding. Emacs supports many
-different encodings, in that it can convert to and from them. For
-example, it can convert text to or from encodings such as Latin 1, Latin
-2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022. In some
-cases, Emacs supports several alternative encodings for the same
-characters; for example, there are three coding systems for the Cyrillic
-(Russian) alphabet: ISO, Alternativnyj, and KOI8.
-
- Most coding systems specify a particular character code for
-conversion, but some of them leave the choice unspecified---to be chosen
-heuristically for each file, based on the data.
-
- In general, a coding system doesn't guarantee roundtrip identity:
-decoding a byte sequence using coding system, then encoding the
-resulting text in the same coding system, can produce a different byte
-sequence. However, the following coding systems do guarantee that the
-byte sequence will be the same as what you originally decoded:
-
-@quotation
-chinese-big5 chinese-iso-8bit cyrillic-iso-8bit emacs-mule
-greek-iso-8bit hebrew-iso-8bit iso-latin-1 iso-latin-2 iso-latin-3
-iso-latin-4 iso-latin-5 iso-latin-8 iso-latin-9 iso-safe
-japanese-iso-8bit japanese-shift-jis korean-iso-8bit raw-text
-@end quotation
-
- Encoding buffer text and then decoding the result can also fail to
-reproduce the original text. For instance, if you encode Latin-2
-characters with @code{utf-8} and decode the result using the same
-coding system, you'll get Unicode characters (of charset
-@code{mule-unicode-0100-24ff}). If you encode Unicode characters with
-@code{iso-latin-2} and decode the result with the same coding system,
-you'll get Latin-2 characters.
-
-@cindex EOL conversion
-@cindex end-of-line conversion
-@cindex line end conversion
- @dfn{End of line conversion} handles three different conventions used
-on various systems for representing end of line in files. The Unix
-convention is to use the linefeed character (also called newline). The
-DOS convention is to use a carriage-return and a linefeed at the end of
-a line. The Mac convention is to use just carriage-return.
-
-@cindex base coding system
-@cindex variant coding system
- @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
-conversion unspecified, to be chosen based on the data. @dfn{Variant
-coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
-@code{latin-1-mac} specify the end-of-line conversion explicitly as
-well. Most base coding systems have three corresponding variants whose
-names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
-
- The coding system @code{raw-text} is special in that it prevents
-character code conversion, and causes the buffer visited with that
-coding system to be a unibyte buffer. It does not specify the
-end-of-line conversion, allowing that to be determined as usual by the
-data, and has the usual three variants which specify the end-of-line
-conversion. @code{no-conversion} is equivalent to @code{raw-text-unix}:
-it specifies no conversion of either character codes or end-of-line.
-
- The coding system @code{emacs-mule} specifies that the data is
-represented in the internal Emacs encoding. This is like
-@code{raw-text} in that no code conversion happens, but different in
-that the result is multibyte data.
-
-@defun coding-system-get coding-system property
-This function returns the specified property of the coding system
-@var{coding-system}. Most coding system properties exist for internal
-purposes, but one that you might find useful is @code{mime-charset}.
-That property's value is the name used in MIME for the character coding
-which this coding system can read and write. Examples:
-
-@example
-(coding-system-get 'iso-latin-1 'mime-charset)
- @result{} iso-8859-1
-(coding-system-get 'iso-2022-cn 'mime-charset)
- @result{} iso-2022-cn
-(coding-system-get 'cyrillic-koi8 'mime-charset)
- @result{} koi8-r
-@end example
-
-The value of the @code{mime-charset} property is also defined
-as an alias for the coding system.
-@end defun
-
-@node Encoding and I/O
-@subsection Encoding and I/O
-
- The principal purpose of coding systems is for use in reading and
-writing files. The function @code{insert-file-contents} uses
-a coding system for decoding the file data, and @code{write-region}
-uses one to encode the buffer contents.
-
- You can specify the coding system to use either explicitly
-(@pxref{Specifying Coding Systems}), or implicitly using a default
-mechanism (@pxref{Default Coding Systems}). But these methods may not
-completely specify what to do. For example, they may choose a coding
-system such as @code{undefined} which leaves the character code
-conversion to be determined from the data. In these cases, the I/O
-operation finishes the job of choosing a coding system. Very often
-you will want to find out afterwards which coding system was chosen.
-
-@defvar buffer-file-coding-system
-This buffer-local variable records the coding system that was used to visit
-the current buffer. It is used for saving the buffer, and for writing part
-of the buffer with @code{write-region}. If the text to be written
-cannot be safely encoded using the coding system specified by this
-variable, these operations select an alternative encoding by calling
-the function @code{select-safe-coding-system} (@pxref{User-Chosen
-Coding Systems}). If selecting a different encoding requires to ask
-the user to specify a coding system, @code{buffer-file-coding-system}
-is updated to the newly selected coding system.
-
-@code{buffer-file-coding-system} does @emph{not} affect sending text
-to a subprocess.
-@end defvar
-
-@defvar save-buffer-coding-system
-This variable specifies the coding system for saving the buffer (by
-overriding @code{buffer-file-coding-system}). Note that it is not used
-for @code{write-region}.
-
-When a command to save the buffer starts out to use
-@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}),
-and that coding system cannot handle
-the actual text in the buffer, the command asks the user to choose
-another coding system (by calling @code{select-safe-coding-system}).
-After that happens, the command also updates
-@code{buffer-file-coding-system} to represent the coding system that
-the user specified.
-@end defvar
-
-@defvar last-coding-system-used
-I/O operations for files and subprocesses set this variable to the
-coding system name that was used. The explicit encoding and decoding
-functions (@pxref{Explicit Encoding}) set it too.
-
-@strong{Warning:} Since receiving subprocess output sets this variable,
-it can change whenever Emacs waits; therefore, you should copy the
-value shortly after the function call that stores the value you are
-interested in.
-@end defvar
-
- The variable @code{selection-coding-system} specifies how to encode
-selections for the window system. @xref{Window System Selections}.
-
-@defvar file-name-coding-system
-The variable @code{file-name-coding-system} specifies the coding
-system to use for encoding file names. Emacs encodes file names using
-that coding system for all file operations. If
-@code{file-name-coding-system} is @code{nil}, Emacs uses a default
-coding system determined by the selected language environment. In the
-default language environment, any non-@acronym{ASCII} characters in
-file names are not encoded specially; they appear in the file system
-using the internal Emacs representation.
-@end defvar
-
- @strong{Warning:} if you change @code{file-name-coding-system} (or
-the language environment) in the middle of an Emacs session, problems
-can result if you have already visited files whose names were encoded
-using the earlier coding system and are handled differently under the
-new coding system. If you try to save one of these buffers under the
-visited file name, saving may use the wrong file name, or it may get
-an error. If such a problem happens, use @kbd{C-x C-w} to specify a
-new file name for that buffer.
-
-@node Lisp and Coding Systems
-@subsection Coding Systems in Lisp
-
- Here are the Lisp facilities for working with coding systems:
-
-@defun coding-system-list &optional base-only
-This function returns a list of all coding system names (symbols). If
-@var{base-only} is non-@code{nil}, the value includes only the
-base coding systems. Otherwise, it includes alias and variant coding
-systems as well.
-@end defun
-
-@defun coding-system-p object
-This function returns @code{t} if @var{object} is a coding system
-name or @code{nil}.
-@end defun
-
-@defun check-coding-system coding-system
-This function checks the validity of @var{coding-system}.
-If that is valid, it returns @var{coding-system}.
-Otherwise it signals an error with condition @code{coding-system-error}.
-@end defun
-
-@defun coding-system-eol-type coding-system
-This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
-conversion used by @var{coding-system}. If @var{coding-system}
-specifies a certain eol conversion, the return value is an integer 0,
-1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
-respectively. If @var{coding-system} doesn't specify eol conversion
-explicitly, the return value is a vector of coding systems, each one
-with one of the possible eol conversion types, like this:
-
-@lisp
-(coding-system-eol-type 'latin-1)
- @result{} [latin-1-unix latin-1-dos latin-1-mac]
-@end lisp
-
-@noindent
-If this function returns a vector, Emacs will decide, as part of the
-text encoding or decoding process, what eol conversion to use. For
-decoding, the end-of-line format of the text is auto-detected, and the
-eol conversion is set to match it (e.g., DOS-style CRLF format will
-imply @code{dos} eol conversion). For encoding, the eol conversion is
-taken from the appropriate default coding system (e.g.,
-@code{default-buffer-file-coding-system} for
-@code{buffer-file-coding-system}), or from the default eol conversion
-appropriate for the underlying platform.
-@end defun
-
-@defun coding-system-change-eol-conversion coding-system eol-type
-This function returns a coding system which is like @var{coding-system}
-except for its eol conversion, which is specified by @code{eol-type}.
-@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
-@code{nil}. If it is @code{nil}, the returned coding system determines
-the end-of-line conversion from the data.
-
-@var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
-@code{dos} and @code{mac}, respectively.
-@end defun
-
-@defun coding-system-change-text-conversion eol-coding text-coding
-This function returns a coding system which uses the end-of-line
-conversion of @var{eol-coding}, and the text conversion of
-@var{text-coding}. If @var{text-coding} is @code{nil}, it returns
-@code{undecided}, or one of its variants according to @var{eol-coding}.
-@end defun
-
-@defun find-coding-systems-region from to
-This function returns a list of coding systems that could be used to
-encode a text between @var{from} and @var{to}. All coding systems in
-the list can safely encode any multibyte characters in that portion of
-the text.
-
-If the text contains no multibyte characters, the function returns the
-list @code{(undecided)}.
-@end defun
-
-@defun find-coding-systems-string string
-This function returns a list of coding systems that could be used to
-encode the text of @var{string}. All coding systems in the list can
-safely encode any multibyte characters in @var{string}. If the text
-contains no multibyte characters, this returns the list
-@code{(undecided)}.
-@end defun
-
-@defun find-coding-systems-for-charsets charsets
-This function returns a list of coding systems that could be used to
-encode all the character sets in the list @var{charsets}.
-@end defun
-
-@defun detect-coding-region start end &optional highest
-This function chooses a plausible coding system for decoding the text
-from @var{start} to @var{end}. This text should be a byte sequence
-(@pxref{Explicit Encoding}).
-
-Normally this function returns a list of coding systems that could
-handle decoding the text that was scanned. They are listed in order of
-decreasing priority. But if @var{highest} is non-@code{nil}, then the
-return value is just one coding system, the one that is highest in
-priority.
-
-If the region contains only @acronym{ASCII} characters except for such
-ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
-@code{undecided} or @code{(undecided)}, or a variant specifying
-end-of-line conversion, if that can be deduced from the text.
-@end defun
-
-@defun detect-coding-string string &optional highest
-This function is like @code{detect-coding-region} except that it
-operates on the contents of @var{string} instead of bytes in the buffer.
-@end defun
-
- @xref{Coding systems for a subprocess,, Process Information}, in
-particular the description of the functions
-@code{process-coding-system} and @code{set-process-coding-system}, for
-how to examine or set the coding systems used for I/O to a subprocess.
-
-@node User-Chosen Coding Systems
-@subsection User-Chosen Coding Systems
-
-@cindex select safe coding system
-@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
-This function selects a coding system for encoding specified text,
-asking the user to choose if necessary. Normally the specified text
-is the text in the current buffer between @var{from} and @var{to}. If
-@var{from} is a string, the string specifies the text to encode, and
-@var{to} is ignored.
-
-If @var{default-coding-system} is non-@code{nil}, that is the first
-coding system to try; if that can handle the text,
-@code{select-safe-coding-system} returns that coding system. It can
-also be a list of coding systems; then the function tries each of them
-one by one. After trying all of them, it next tries the current
-buffer's value of @code{buffer-file-coding-system} (if it is not
-@code{undecided}), then the value of
-@code{default-buffer-file-coding-system} and finally the user's most
-preferred coding system, which the user can set using the command
-@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
-Coding Systems, emacs, The GNU Emacs Manual}).
-
-If one of those coding systems can safely encode all the specified
-text, @code{select-safe-coding-system} chooses it and returns it.
-Otherwise, it asks the user to choose from a list of coding systems
-which can encode all the text, and returns the user's choice.
-
-@var{default-coding-system} can also be a list whose first element is
-t and whose other elements are coding systems. Then, if no coding
-system in the list can handle the text, @code{select-safe-coding-system}
-queries the user immediately, without trying any of the three
-alternatives described above.
-
-The optional argument @var{accept-default-p}, if non-@code{nil},
-should be a function to determine whether a coding system selected
-without user interaction is acceptable. @code{select-safe-coding-system}
-calls this function with one argument, the base coding system of the
-selected coding system. If @var{accept-default-p} returns @code{nil},
-@code{select-safe-coding-system} rejects the silently selected coding
-system, and asks the user to select a coding system from a list of
-possible candidates.
-
-@vindex select-safe-coding-system-accept-default-p
-If the variable @code{select-safe-coding-system-accept-default-p} is
-non-@code{nil}, its value overrides the value of
-@var{accept-default-p}.
-
-As a final step, before returning the chosen coding system,
-@code{select-safe-coding-system} checks whether that coding system is
-consistent with what would be selected if the contents of the region
-were read from a file. (If not, this could lead to data corruption in
-a file subsequently re-visited and edited.) Normally,
-@code{select-safe-coding-system} uses @code{buffer-file-name} as the
-file for this purpose, but if @var{file} is non-@code{nil}, it uses
-that file instead (this can be relevant for @code{write-region} and
-similar functions). If it detects an apparent inconsistency,
-@code{select-safe-coding-system} queries the user before selecting the
-coding system.
-@end defun
-
- Here are two functions you can use to let the user specify a coding
-system, with completion. @xref{Completion}.
-
-@defun read-coding-system prompt &optional default
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt}, and returns the coding system name as a symbol. If
-the user enters null input, @var{default} specifies which coding system
-to return. It should be a symbol or a string.
-@end defun
-
-@defun read-non-nil-coding-system prompt
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt}, and returns the coding system name as a symbol. If
-the user tries to enter null input, it asks the user to try again.
-@xref{Coding Systems}.
-@end defun
-
-@node Default Coding Systems
-@subsection Default Coding Systems
-
- This section describes variables that specify the default coding
-system for certain files or when running certain subprograms, and the
-function that I/O operations use to access them.
-
- The idea of these variables is that you set them once and for all to the
-defaults you want, and then do not change them again. To specify a
-particular coding system for a particular operation in a Lisp program,
-don't change these variables; instead, override them using
-@code{coding-system-for-read} and @code{coding-system-for-write}
-(@pxref{Specifying Coding Systems}).
-
-@defvar auto-coding-regexp-alist
-This variable is an alist of text patterns and corresponding coding
-systems. Each element has the form @code{(@var{regexp}
-. @var{coding-system})}; a file whose first few kilobytes match
-@var{regexp} is decoded with @var{coding-system} when its contents are
-read into a buffer. The settings in this alist take priority over
-@code{coding:} tags in the files and the contents of
-@code{file-coding-system-alist} (see below). The default value is set
-so that Emacs automatically recognizes mail files in Babyl format and
-reads them with no code conversions.
-@end defvar
-
-@defvar file-coding-system-alist
-This variable is an alist that specifies the coding systems to use for
-reading and writing particular files. Each element has the form
-@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
-expression that matches certain file names. The element applies to file
-names that match @var{pattern}.
-
-The @sc{cdr} of the element, @var{coding}, should be either a coding
-system, a cons cell containing two coding systems, or a function name (a
-symbol with a function definition). If @var{coding} is a coding system,
-that coding system is used for both reading the file and writing it. If
-@var{coding} is a cons cell containing two coding systems, its @sc{car}
-specifies the coding system for decoding, and its @sc{cdr} specifies the
-coding system for encoding.
-
-If @var{coding} is a function name, the function should take one
-argument, a list of all arguments passed to
-@code{find-operation-coding-system}. It must return a coding system
-or a cons cell containing two coding systems. This value has the same
-meaning as described above.
-
-If @var{coding} (or what returned by the above function) is
-@code{undecided}, the normal code-detection is performed.
-@end defvar
-
-@defvar process-coding-system-alist
-This variable is an alist specifying which coding systems to use for a
-subprocess, depending on which program is running in the subprocess. It
-works like @code{file-coding-system-alist}, except that @var{pattern} is
-matched against the program name used to start the subprocess. The coding
-system or systems specified in this alist are used to initialize the
-coding systems used for I/O to the subprocess, but you can specify
-other coding systems later using @code{set-process-coding-system}.
-@end defvar
-
- @strong{Warning:} Coding systems such as @code{undecided}, which
-determine the coding system from the data, do not work entirely reliably
-with asynchronous subprocess output. This is because Emacs handles
-asynchronous subprocess output in batches, as it arrives. If the coding
-system leaves the character code conversion unspecified, or leaves the
-end-of-line conversion unspecified, Emacs must try to detect the proper
-conversion from one batch at a time, and this does not always work.
-
- Therefore, with an asynchronous subprocess, if at all possible, use a
-coding system which determines both the character code conversion and
-the end of line conversion---that is, one like @code{latin-1-unix},
-rather than @code{undecided} or @code{latin-1}.
-
-@defvar network-coding-system-alist
-This variable is an alist that specifies the coding system to use for
-network streams. It works much like @code{file-coding-system-alist},
-with the difference that the @var{pattern} in an element may be either a
-port number or a regular expression. If it is a regular expression, it
-is matched against the network service name used to open the network
-stream.
-@end defvar
-
-@defvar default-process-coding-system
-This variable specifies the coding systems to use for subprocess (and
-network stream) input and output, when nothing else specifies what to
-do.
-
-The value should be a cons cell of the form @code{(@var{input-coding}
-. @var{output-coding})}. Here @var{input-coding} applies to input from
-the subprocess, and @var{output-coding} applies to output to it.
-@end defvar
-
-@defvar auto-coding-functions
-This variable holds a list of functions that try to determine a
-coding system for a file based on its undecoded contents.
-
-Each function in this list should be written to look at text in the
-current buffer, but should not modify it in any way. The buffer will
-contain undecoded text of parts of the file. Each function should
-take one argument, @var{size}, which tells it how many characters to
-look at, starting from point. If the function succeeds in determining
-a coding system for the file, it should return that coding system.
-Otherwise, it should return @code{nil}.
-
-If a file has a @samp{coding:} tag, that takes precedence, so these
-functions won't be called.
-@end defvar
-
-@defun find-operation-coding-system operation &rest arguments
-This function returns the coding system to use (by default) for
-performing @var{operation} with @var{arguments}. The value has this
-form:
-
-@example
-(@var{decoding-system} . @var{encoding-system})
-@end example
-
-The first element, @var{decoding-system}, is the coding system to use
-for decoding (in case @var{operation} does decoding), and
-@var{encoding-system} is the coding system for encoding (in case
-@var{operation} does encoding).
-
-The argument @var{operation} is a symbol, one of @code{write-region},
-@code{start-process}, @code{call-process}, @code{call-process-region},
-@code{insert-file-contents}, or @code{open-network-stream}. These are
-the names of the Emacs I/O primitives that can do character code and
-eol conversion.
-
-The remaining arguments should be the same arguments that might be given
-to the corresponding I/O primitive. Depending on the primitive, one
-of those arguments is selected as the @dfn{target}. For example, if
-@var{operation} does file I/O, whichever argument specifies the file
-name is the target. For subprocess primitives, the process name is the
-target. For @code{open-network-stream}, the target is the service name
-or port number.
-
-Depending on @var{operation}, this function looks up the target in
-@code{file-coding-system-alist}, @code{process-coding-system-alist},
-or @code{network-coding-system-alist}. If the target is found in the
-alist, @code{find-operation-coding-system} returns its association in
-the alist; otherwise it returns @code{nil}.
-
-If @var{operation} is @code{insert-file-contents}, the argument
-corresponding to the target may be a cons cell of the form
-@code{(@var{filename} . @var{buffer})}). In that case, @var{filename}
-is a file name to look up in @code{file-coding-system-alist}, and
-@var{buffer} is a buffer that contains the file's contents (not yet
-decoded). If @code{file-coding-system-alist} specifies a function to
-call for this file, and that function needs to examine the file's
-contents (as it usually does), it should examine the contents of
-@var{buffer} instead of reading the file.
-@end defun
-
-@node Specifying Coding Systems
-@subsection Specifying a Coding System for One Operation
-
- You can specify the coding system for a specific operation by binding
-the variables @code{coding-system-for-read} and/or
-@code{coding-system-for-write}.
-
-@defvar coding-system-for-read
-If this variable is non-@code{nil}, it specifies the coding system to
-use for reading a file, or for input from a synchronous subprocess.
-
-It also applies to any asynchronous subprocess or network stream, but in
-a different way: the value of @code{coding-system-for-read} when you
-start the subprocess or open the network stream specifies the input
-decoding method for that subprocess or network stream. It remains in
-use for that subprocess or network stream unless and until overridden.
-
-The right way to use this variable is to bind it with @code{let} for a
-specific I/O operation. Its global value is normally @code{nil}, and
-you should not globally set it to any other value. Here is an example
-of the right way to use the variable:
-
-@example
-;; @r{Read the file with no character code conversion.}
-;; @r{Assume @acronym{crlf} represents end-of-line.}
-(let ((coding-system-for-read 'emacs-mule-dos))
- (insert-file-contents filename))
-@end example
-
-When its value is non-@code{nil}, this variable takes precedence over
-all other methods of specifying a coding system to use for input,
-including @code{file-coding-system-alist},
-@code{process-coding-system-alist} and
-@code{network-coding-system-alist}.
-@end defvar
-
-@defvar coding-system-for-write
-This works much like @code{coding-system-for-read}, except that it
-applies to output rather than input. It affects writing to files,
-as well as sending output to subprocesses and net connections.
-
-When a single operation does both input and output, as do
-@code{call-process-region} and @code{start-process}, both
-@code{coding-system-for-read} and @code{coding-system-for-write}
-affect it.
-@end defvar
-
-@defvar inhibit-eol-conversion
-When this variable is non-@code{nil}, no end-of-line conversion is done,
-no matter which coding system is specified. This applies to all the
-Emacs I/O and subprocess primitives, and to the explicit encoding and
-decoding functions (@pxref{Explicit Encoding}).
-@end defvar
-
-@node Explicit Encoding
-@subsection Explicit Encoding and Decoding
-@cindex encoding in coding systems
-@cindex decoding in coding systems
-
- All the operations that transfer text in and out of Emacs have the
-ability to use a coding system to encode or decode the text.
-You can also explicitly encode and decode text using the functions
-in this section.
-
- The result of encoding, and the input to decoding, are not ordinary
-text. They logically consist of a series of byte values; that is, a
-series of characters whose codes are in the range 0 through 255. In a
-multibyte buffer or string, character codes 128 through 159 are
-represented by multibyte sequences, but this is invisible to Lisp
-programs.
-
- The usual way to read a file into a buffer as a sequence of bytes, so
-you can decode the contents explicitly, is with
-@code{insert-file-contents-literally} (@pxref{Reading from Files});
-alternatively, specify a non-@code{nil} @var{rawfile} argument when
-visiting a file with @code{find-file-noselect}. These methods result in
-a unibyte buffer.
-
- The usual way to use the byte sequence that results from explicitly
-encoding text is to copy it to a file or process---for example, to write
-it with @code{write-region} (@pxref{Writing to Files}), and suppress
-encoding by binding @code{coding-system-for-write} to
-@code{no-conversion}.
-
- Here are the functions to perform explicit encoding or decoding. The
-encoding functions produce sequences of bytes; the decoding functions
-are meant to operate on sequences of bytes. All of these functions
-discard text properties.
-
-@deffn Command encode-coding-region start end coding-system
-This command encodes the text from @var{start} to @var{end} according
-to coding system @var{coding-system}. The encoded text replaces the
-original text in the buffer. The result of encoding is logically a
-sequence of bytes, but the buffer remains multibyte if it was multibyte
-before.
-
-This command returns the length of the encoded text.
-@end deffn
-
-@defun encode-coding-string string coding-system &optional nocopy
-This function encodes the text in @var{string} according to coding
-system @var{coding-system}. It returns a new string containing the
-encoded text, except when @var{nocopy} is non-@code{nil}, in which
-case the function may return @var{string} itself if the encoding
-operation is trivial. The result of encoding is a unibyte string.
-@end defun
-
-@deffn Command decode-coding-region start end coding-system
-This command decodes the text from @var{start} to @var{end} according
-to coding system @var{coding-system}. The decoded text replaces the
-original text in the buffer. To make explicit decoding useful, the text
-before decoding ought to be a sequence of byte values, but both
-multibyte and unibyte buffers are acceptable.
-
-This command returns the length of the decoded text.
-@end deffn
-
-@defun decode-coding-string string coding-system &optional nocopy
-This function decodes the text in @var{string} according to coding
-system @var{coding-system}. It returns a new string containing the
-decoded text, except when @var{nocopy} is non-@code{nil}, in which
-case the function may return @var{string} itself if the decoding
-operation is trivial. To make explicit decoding useful, the contents
-of @var{string} ought to be a sequence of byte values, but a multibyte
-string is acceptable.
-@end defun
-
-@defun decode-coding-inserted-region from to filename &optional visit beg end replace
-This function decodes the text from @var{from} to @var{to} as if
-it were being read from file @var{filename} using @code{insert-file-contents}
-using the rest of the arguments provided.
-
-The normal way to use this function is after reading text from a file
-without decoding, if you decide you would rather have decoded it.
-Instead of deleting the text and reading it again, this time with
-decoding, you can call this function.
-@end defun
-
-@node Terminal I/O Encoding
-@subsection Terminal I/O Encoding
-
- Emacs can decode keyboard input using a coding system, and encode
-terminal output. This is useful for terminals that transmit or display
-text using a particular encoding such as Latin-1. Emacs does not set
-@code{last-coding-system-used} for encoding or decoding for the
-terminal.
-
-@defun keyboard-coding-system
-This function returns the coding system that is in use for decoding
-keyboard input---or @code{nil} if no coding system is to be used.
-@end defun
-
-@deffn Command set-keyboard-coding-system coding-system
-This command specifies @var{coding-system} as the coding system to
-use for decoding keyboard input. If @var{coding-system} is @code{nil},
-that means do not decode keyboard input.
-@end deffn
-
-@defun terminal-coding-system
-This function returns the coding system that is in use for encoding
-terminal output---or @code{nil} for no encoding.
-@end defun
-
-@deffn Command set-terminal-coding-system coding-system
-This command specifies @var{coding-system} as the coding system to use
-for encoding terminal output. If @var{coding-system} is @code{nil},
-that means do not encode terminal output.
-@end deffn
-
-@node MS-DOS File Types
-@subsection MS-DOS File Types
-@cindex DOS file types
-@cindex MS-DOS file types
-@cindex Windows file types
-@cindex file types on MS-DOS and Windows
-@cindex text files and binary files
-@cindex binary files and text files
-
- On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
-end-of-line conversion for a file by looking at the file's name. This
-feature classifies files as @dfn{text files} and @dfn{binary files}. By
-``binary file'' we mean a file of literal byte values that are not
-necessarily meant to be characters; Emacs does no end-of-line conversion
-and no character code conversion for them. On the other hand, the bytes
-in a text file are intended to represent characters; when you create a
-new file whose name implies that it is a text file, Emacs uses DOS
-end-of-line conversion.
-
-@defvar buffer-file-type
-This variable, automatically buffer-local in each buffer, records the
-file type of the buffer's visited file. When a buffer does not specify
-a coding system with @code{buffer-file-coding-system}, this variable is
-used to determine which coding system to use when writing the contents
-of the buffer. It should be @code{nil} for text, @code{t} for binary.
-If it is @code{t}, the coding system is @code{no-conversion}.
-Otherwise, @code{undecided-dos} is used.
-
-Normally this variable is set by visiting a file; it is set to
-@code{nil} if the file was visited without any actual conversion.
-@end defvar
-
-@defopt file-name-buffer-file-type-alist
-This variable holds an alist for recognizing text and binary files.
-Each element has the form (@var{regexp} . @var{type}), where
-@var{regexp} is matched against the file name, and @var{type} may be
-@code{nil} for text, @code{t} for binary, or a function to call to
-compute which. If it is a function, then it is called with a single
-argument (the file name) and should return @code{t} or @code{nil}.
-
-When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
-which coding system to use when reading a file. For a text file,
-@code{undecided-dos} is used. For a binary file, @code{no-conversion}
-is used.
-
-If no element in this alist matches a given file name, then
-@code{default-buffer-file-type} says how to treat the file.
-@end defopt
-
-@defopt default-buffer-file-type
-This variable says how to handle files for which
-@code{file-name-buffer-file-type-alist} says nothing about the type.
-
-If this variable is non-@code{nil}, then these files are treated as
-binary: the coding system @code{no-conversion} is used. Otherwise,
-nothing special is done for them---the coding system is deduced solely
-from the file contents, in the usual Emacs fashion.
-@end defopt
-
-@node Input Methods
-@section Input Methods
-@cindex input methods
-
- @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
-characters from the keyboard. Unlike coding systems, which translate
-non-@acronym{ASCII} characters to and from encodings meant to be read by
-programs, input methods provide human-friendly commands. (@xref{Input
-Methods,,, emacs, The GNU Emacs Manual}, for information on how users
-use input methods to enter text.) How to define input methods is not
-yet documented in this manual, but here we describe how to use them.
-
- Each input method has a name, which is currently a string;
-in the future, symbols may also be usable as input method names.
-
-@defvar current-input-method
-This variable holds the name of the input method now active in the
-current buffer. (It automatically becomes local in each buffer when set
-in any fashion.) It is @code{nil} if no input method is active in the
-buffer now.
-@end defvar
-
-@defopt default-input-method
-This variable holds the default input method for commands that choose an
-input method. Unlike @code{current-input-method}, this variable is
-normally global.
-@end defopt
-
-@deffn Command set-input-method input-method
-This command activates input method @var{input-method} for the current
-buffer. It also sets @code{default-input-method} to @var{input-method}.
-If @var{input-method} is @code{nil}, this command deactivates any input
-method for the current buffer.
-@end deffn
-
-@defun read-input-method-name prompt &optional default inhibit-null
-This function reads an input method name with the minibuffer, prompting
-with @var{prompt}. If @var{default} is non-@code{nil}, that is returned
-by default, if the user enters empty input. However, if
-@var{inhibit-null} is non-@code{nil}, empty input signals an error.
-
-The returned value is a string.
-@end defun
-
-@defvar input-method-alist
-This variable defines all the supported input methods.
-Each element defines one input method, and should have the form:
-
-@example
-(@var{input-method} @var{language-env} @var{activate-func}
- @var{title} @var{description} @var{args}...)
-@end example
-
-Here @var{input-method} is the input method name, a string;
-@var{language-env} is another string, the name of the language
-environment this input method is recommended for. (That serves only for
-documentation purposes.)
-
-@var{activate-func} is a function to call to activate this method. The
-@var{args}, if any, are passed as arguments to @var{activate-func}. All
-told, the arguments to @var{activate-func} are @var{input-method} and
-the @var{args}.
-
-@var{title} is a string to display in the mode line while this method is
-active. @var{description} is a string describing this method and what
-it is good for.
-@end defvar
-
- The fundamental interface to input methods is through the
-variable @code{input-method-function}. @xref{Reading One Event},
-and @ref{Invoking the Input Method}.
-
-@node Locales
-@section Locales
-@cindex locale
-
- POSIX defines a concept of ``locales'' which control which language
-to use in language-related features. These Emacs variables control
-how Emacs interacts with these features.
-
-@defvar locale-coding-system
-@cindex keyboard input decoding on X
-This variable specifies the coding system to use for decoding system
-error messages and---on X Window system only---keyboard input, for
-encoding the format argument to @code{format-time-string}, and for
-decoding the return value of @code{format-time-string}.
-@end defvar
-
-@defvar system-messages-locale
-This variable specifies the locale to use for generating system error
-messages. Changing the locale can cause messages to come out in a
-different language or in a different orthography. If the variable is
-@code{nil}, the locale is specified by environment variables in the
-usual POSIX fashion.
-@end defvar
-
-@defvar system-time-locale
-This variable specifies the locale to use for formatting time values.
-Changing the locale can cause messages to appear according to the
-conventions of a different language. If the variable is @code{nil}, the
-locale is specified by environment variables in the usual POSIX fashion.
-@end defvar
-
-@defun locale-info item
-This function returns locale data @var{item} for the current POSIX
-locale, if available. @var{item} should be one of these symbols:
-
-@table @code
-@item codeset
-Return the character set as a string (locale item @code{CODESET}).
-
-@item days
-Return a 7-element vector of day names (locale items
-@code{DAY_1} through @code{DAY_7});
-
-@item months
-Return a 12-element vector of month names (locale items @code{MON_1}
-through @code{MON_12}).
-
-@item paper
-Return a list @code{(@var{width} @var{height})} for the default paper
-size measured in millimeters (locale items @code{PAPER_WIDTH} and
-@code{PAPER_HEIGHT}).
-@end table
-
-If the system can't provide the requested information, or if
-@var{item} is not one of those symbols, the value is @code{nil}. All
-strings in the return value are decoded using
-@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual},
-for more information about locales and locale items.
-@end defun
-
-@ignore
- arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/numbers
-@node Numbers, Strings and Characters, Lisp Data Types, Top
-@chapter Numbers
-@cindex integers
-@cindex numbers
-
- GNU Emacs supports two numeric data types: @dfn{integers} and
-@dfn{floating point numbers}. Integers are whole numbers such as
-@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
-numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
-2.71828. They can also be expressed in exponential notation: 1.5e2
-equals 150; in this example, @samp{e2} stands for ten to the second
-power, and that is multiplied by 1.5. Floating point values are not
-exact; they have a fixed, limited amount of precision.
-
-@menu
-* 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.
-@end menu
-
-@node Integer Basics
-@comment node-name, next, previous, up
-@section Integer Basics
-
- The range of values for an integer depends on the machine. The
-minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
-@ifnottex
--2**28
-@end ifnottex
-@tex
-@math{-2^{28}}
-@end tex
-to
-@ifnottex
-2**28 - 1),
-@end ifnottex
-@tex
-@math{2^{28}-1}),
-@end tex
-but some machines may provide a wider range. Many examples in this
-chapter assume an integer has 29 bits.
-@cindex overflow
-
- The Lisp reader reads an integer as a sequence of digits with optional
-initial sign and optional final period.
-
-@example
- 1 ; @r{The integer 1.}
- 1. ; @r{The integer 1.}
-+1 ; @r{Also the integer 1.}
--1 ; @r{The integer @minus{}1.}
- 536870913 ; @r{Also the integer 1, due to overflow.}
- 0 ; @r{The integer 0.}
--0 ; @r{The integer 0.}
-@end example
-
-@cindex integers in specific radix
-@cindex radix for reading an integer
-@cindex base for reading an integer
-@cindex hex numbers
-@cindex octal numbers
-@cindex reading numbers in hex, octal, and binary
- The syntax for integers in bases other than 10 uses @samp{#}
-followed by a letter that specifies the radix: @samp{b} for binary,
-@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
-specify radix @var{radix}. Case is not significant for the letter
-that specifies the radix. Thus, @samp{#b@var{integer}} reads
-@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
-@var{integer} in radix @var{radix}. Allowed values of @var{radix} run
-from 2 to 36. For example:
-
-@example
-#b101100 @result{} 44
-#o54 @result{} 44
-#x2c @result{} 44
-#24r1k @result{} 44
-@end example
-
- To understand how various functions work on integers, especially the
-bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
-view the numbers in their binary form.
-
- In 29-bit binary, the decimal integer 5 looks like this:
-
-@example
-0 0000 0000 0000 0000 0000 0000 0101
-@end example
-
-@noindent
-(We have inserted spaces between groups of 4 bits, and two spaces
-between groups of 8 bits, to make the binary integer easier to read.)
-
- The integer @minus{}1 looks like this:
-
-@example
-1 1111 1111 1111 1111 1111 1111 1111
-@end example
-
-@noindent
-@cindex two's complement
-@minus{}1 is represented as 29 ones. (This is called @dfn{two's
-complement} notation.)
-
- The negative integer, @minus{}5, is creating by subtracting 4 from
-@minus{}1. In binary, the decimal integer 4 is 100. Consequently,
-@minus{}5 looks like this:
-
-@example
-1 1111 1111 1111 1111 1111 1111 1011
-@end example
-
- In this implementation, the largest 29-bit binary integer value is
-268,435,455 in decimal. In binary, it looks like this:
-
-@example
-0 1111 1111 1111 1111 1111 1111 1111
-@end example
-
- Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 268,435,455, the value is the
-negative integer @minus{}268,435,456:
-
-@example
-(+ 1 268435455)
- @result{} -268435456
- @result{} 1 0000 0000 0000 0000 0000 0000 0000
-@end example
-
- Many of the functions described in this chapter accept markers for
-arguments in place of numbers. (@xref{Markers}.) Since the actual
-arguments to such functions may be either numbers or markers, we often
-give these arguments the name @var{number-or-marker}. When the argument
-value is a marker, its position value is used and its buffer is ignored.
-
-@defvar most-positive-fixnum
-The value of this variable is the largest integer that Emacs Lisp
-can handle.
-@end defvar
-
-@defvar most-negative-fixnum
-The value of this variable is the smallest integer that Emacs Lisp can
-handle. It is negative.
-@end defvar
-
-@node Float Basics
-@section Floating Point Basics
-
- Floating point numbers are useful for representing numbers that are
-not integral. The precise range of floating point numbers is
-machine-specific; it is the same as the range of the C data type
-@code{double} on the machine you are using.
-
- The read-syntax for floating point numbers requires either a decimal
-point (with at least one digit following), an exponent, or both. For
-example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
-@samp{.15e4} are five ways of writing a floating point number whose
-value is 1500. They are all equivalent. You can also use a minus sign
-to write negative floating point numbers, as in @samp{-1.0}.
-
-@cindex @acronym{IEEE} floating point
-@cindex positive infinity
-@cindex negative infinity
-@cindex infinity
-@cindex NaN
- Most modern computers support the @acronym{IEEE} floating point standard,
-which provides for positive infinity and negative infinity as floating point
-values. It also provides for a class of values called NaN or
-``not-a-number''; numerical functions return such values in cases where
-there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
-NaN. For practical purposes, there's no significant difference between
-different NaN values in Emacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so Emacs Lisp
-doesn't try to distinguish them (but it does report the sign, if you
-print it). Here are the read syntaxes for these special floating
-point values:
-
-@table @asis
-@item positive infinity
-@samp{1.0e+INF}
-@item negative infinity
-@samp{-1.0e+INF}
-@item Not-a-number
-@samp{0.0e+NaN} or @samp{-0.0e+NaN}.
-@end table
-
- To test whether a floating point value is a NaN, compare it with
-itself using @code{=}. That returns @code{nil} for a NaN, and
-@code{t} for any other floating point value.
-
- The value @code{-0.0} is distinguishable from ordinary zero in
-@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
-@code{=} consider them equal values.
-
- You can use @code{logb} to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
-
-@defun logb number
-This function returns the binary exponent of @var{number}. More
-precisely, the value is the logarithm of @var{number} base 2, rounded
-down to an integer.
-
-@example
-(logb 10)
- @result{} 3
-(logb 10.0e20)
- @result{} 69
-@end example
-@end defun
-
-@node Predicates on Numbers
-@section Type Predicates for Numbers
-@cindex predicates for numbers
-
- The functions in this section test for numbers, or for a specific
-type of number. The functions @code{integerp} and @code{floatp} can
-take any type of Lisp object as argument (they would not be of much
-use otherwise), but the @code{zerop} predicate requires a number as
-its argument. See also @code{integer-or-marker-p} and
-@code{number-or-marker-p}, in @ref{Predicates on Markers}.
-
-@defun floatp object
-This predicate tests whether its argument is a floating point
-number and returns @code{t} if so, @code{nil} otherwise.
-
-@code{floatp} does not exist in Emacs versions 18 and earlier.
-@end defun
-
-@defun integerp object
-This predicate tests whether its argument is an integer, and returns
-@code{t} if so, @code{nil} otherwise.
-@end defun
-
-@defun numberp object
-This predicate tests whether its argument is a number (either integer or
-floating point), and returns @code{t} if so, @code{nil} otherwise.
-@end defun
-
-@defun wholenump object
-@cindex natural numbers
-The @code{wholenump} predicate (whose name comes from the phrase
-``whole-number-p'') tests to see whether its argument is a nonnegative
-integer, and returns @code{t} if so, @code{nil} otherwise. 0 is
-considered non-negative.
-
-@findex natnump
-@code{natnump} is an obsolete synonym for @code{wholenump}.
-@end defun
-
-@defun zerop number
-This predicate tests whether its argument is zero, and returns @code{t}
-if so, @code{nil} otherwise. The argument must be a number.
-
-@code{(zerop x)} is equivalent to @code{(= x 0)}.
-@end defun
-
-@node Comparison of Numbers
-@section Comparison of Numbers
-@cindex number comparison
-@cindex comparing numbers
-
- To test numbers for numerical equality, you should normally use
-@code{=}, not @code{eq}. There can be many distinct floating point
-number objects with the same numeric value. If you use @code{eq} to
-compare them, then you test whether two values are the same
-@emph{object}. By contrast, @code{=} compares only the numeric values
-of the objects.
-
- At present, each integer value has a unique Lisp object in Emacs Lisp.
-Therefore, @code{eq} is equivalent to @code{=} where integers are
-concerned. It is sometimes convenient to use @code{eq} for comparing an
-unknown value with an integer, because @code{eq} does not report an
-error if the unknown value is not a number---it accepts arguments of any
-type. By contrast, @code{=} signals an error if the arguments are not
-numbers or markers. However, it is a good idea to use @code{=} if you
-can, even for comparing integers, just in case we change the
-representation of integers in a future Emacs version.
-
- Sometimes it is useful to compare numbers with @code{equal}; it
-treats two numbers as equal if they have the same data type (both
-integers, or both floating point) and the same value. By contrast,
-@code{=} can treat an integer and a floating point number as equal.
-@xref{Equality Predicates}.
-
- There is another wrinkle: because floating point arithmetic is not
-exact, it is often a bad idea to check for equality of two floating
-point values. Usually it is better to test for approximate equality.
-Here's a function to do this:
-
-@example
-(defvar fuzz-factor 1.0e-6)
-(defun approx-equal (x y)
- (or (and (= x 0) (= y 0))
- (< (/ (abs (- x y))
- (max (abs x) (abs y)))
- fuzz-factor)))
-@end example
-
-@cindex CL note---integers vrs @code{eq}
-@quotation
-@b{Common Lisp note:} Comparing numbers in Common Lisp always requires
-@code{=} because Common Lisp implements multi-word integers, and two
-distinct integer objects can have the same numeric value. Emacs Lisp
-can have just one integer object for any given value because it has a
-limited range of integer values.
-@end quotation
-
-@defun = number-or-marker1 number-or-marker2
-This function tests whether its arguments are numerically equal, and
-returns @code{t} if so, @code{nil} otherwise.
-@end defun
-
-@defun eql value1 value2
-This function acts like @code{eq} except when both arguments are
-numbers. It compares numbers by type and numeric value, so that
-@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
-@code{(eql 1 1)} both return @code{t}.
-@end defun
-
-@defun /= number-or-marker1 number-or-marker2
-This function tests whether its arguments are numerically equal, and
-returns @code{t} if they are not, and @code{nil} if they are.
-@end defun
-
-@defun < number-or-marker1 number-or-marker2
-This function tests whether its first argument is strictly less than
-its second argument. It returns @code{t} if so, @code{nil} otherwise.
-@end defun
-
-@defun <= number-or-marker1 number-or-marker2
-This function tests whether its first argument is less than or equal
-to its second argument. It returns @code{t} if so, @code{nil}
-otherwise.
-@end defun
-
-@defun > number-or-marker1 number-or-marker2
-This function tests whether its first argument is strictly greater
-than its second argument. It returns @code{t} if so, @code{nil}
-otherwise.
-@end defun
-
-@defun >= number-or-marker1 number-or-marker2
-This function tests whether its first argument is greater than or
-equal to its second argument. It returns @code{t} if so, @code{nil}
-otherwise.
-@end defun
-
-@defun max number-or-marker &rest numbers-or-markers
-This function returns the largest of its arguments.
-If any of the arguments is floating-point, the value is returned
-as floating point, even if it was given as an integer.
-
-@example
-(max 20)
- @result{} 20
-(max 1 2.5)
- @result{} 2.5
-(max 1 3 2.5)
- @result{} 3.0
-@end example
-@end defun
-
-@defun min number-or-marker &rest numbers-or-markers
-This function returns the smallest of its arguments.
-If any of the arguments is floating-point, the value is returned
-as floating point, even if it was given as an integer.
-
-@example
-(min -4 1)
- @result{} -4
-@end example
-@end defun
-
-@defun abs number
-This function returns the absolute value of @var{number}.
-@end defun
-
-@node Numeric Conversions
-@section Numeric Conversions
-@cindex rounding in conversions
-@cindex number conversions
-@cindex converting numbers
-
-To convert an integer to floating point, use the function @code{float}.
-
-@defun float number
-This returns @var{number} converted to floating point.
-If @var{number} is already a floating point number, @code{float} returns
-it unchanged.
-@end defun
-
-There are four functions to convert floating point numbers to integers;
-they differ in how they round. All accept an argument @var{number}
-and an optional argument @var{divisor}. Both arguments may be
-integers or floating point numbers. @var{divisor} may also be
-@code{nil}. If @var{divisor} is @code{nil} or omitted, these
-functions convert @var{number} to an integer, or return it unchanged
-if it already is an integer. If @var{divisor} is non-@code{nil}, they
-divide @var{number} by @var{divisor} and convert the result to an
-integer. An @code{arith-error} results if @var{divisor} is 0.
-
-@defun truncate number &optional divisor
-This returns @var{number}, converted to an integer by rounding towards
-zero.
-
-@example
-(truncate 1.2)
- @result{} 1
-(truncate 1.7)
- @result{} 1
-(truncate -1.2)
- @result{} -1
-(truncate -1.7)
- @result{} -1
-@end example
-@end defun
-
-@defun floor number &optional divisor
-This returns @var{number}, converted to an integer by rounding downward
-(towards negative infinity).
-
-If @var{divisor} is specified, this uses the kind of division
-operation that corresponds to @code{mod}, rounding downward.
-
-@example
-(floor 1.2)
- @result{} 1
-(floor 1.7)
- @result{} 1
-(floor -1.2)
- @result{} -2
-(floor -1.7)
- @result{} -2
-(floor 5.99 3)
- @result{} 1
-@end example
-@end defun
-
-@defun ceiling number &optional divisor
-This returns @var{number}, converted to an integer by rounding upward
-(towards positive infinity).
-
-@example
-(ceiling 1.2)
- @result{} 2
-(ceiling 1.7)
- @result{} 2
-(ceiling -1.2)
- @result{} -1
-(ceiling -1.7)
- @result{} -1
-@end example
-@end defun
-
-@defun round number &optional divisor
-This returns @var{number}, converted to an integer by rounding towards the
-nearest integer. Rounding a value equidistant between two integers
-may choose the integer closer to zero, or it may prefer an even integer,
-depending on your machine.
-
-@example
-(round 1.2)
- @result{} 1
-(round 1.7)
- @result{} 2
-(round -1.2)
- @result{} -1
-(round -1.7)
- @result{} -2
-@end example
-@end defun
-
-@node Arithmetic Operations
-@section Arithmetic Operations
-@cindex arithmetic operations
-
- Emacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division. Remainder and modulus
-functions supplement the division functions. The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
-
- All of these functions except @code{%} return a floating point value
-if any argument is floating.
-
- It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
-@minus{}268435456, depending on your hardware.
-
-@defun 1+ number-or-marker
-This function returns @var{number-or-marker} plus 1.
-For example,
-
-@example
-(setq foo 4)
- @result{} 4
-(1+ foo)
- @result{} 5
-@end example
-
-This function is not analogous to the C operator @code{++}---it does not
-increment a variable. It just computes a sum. Thus, if we continue,
-
-@example
-foo
- @result{} 4
-@end example
-
-If you want to increment the variable, you must use @code{setq},
-like this:
-
-@example
-(setq foo (1+ foo))
- @result{} 5
-@end example
-@end defun
-
-@defun 1- number-or-marker
-This function returns @var{number-or-marker} minus 1.
-@end defun
-
-@defun + &rest numbers-or-markers
-This function adds its arguments together. When given no arguments,
-@code{+} returns 0.
-
-@example
-(+)
- @result{} 0
-(+ 1)
- @result{} 1
-(+ 1 2 3 4)
- @result{} 10
-@end example
-@end defun
-
-@defun - &optional number-or-marker &rest more-numbers-or-markers
-The @code{-} function serves two purposes: negation and subtraction.
-When @code{-} has a single argument, the value is the negative of the
-argument. When there are multiple arguments, @code{-} subtracts each of
-the @var{more-numbers-or-markers} from @var{number-or-marker},
-cumulatively. If there are no arguments, the result is 0.
-
-@example
-(- 10 1 2 3 4)
- @result{} 0
-(- 10)
- @result{} -10
-(-)
- @result{} 0
-@end example
-@end defun
-
-@defun * &rest numbers-or-markers
-This function multiplies its arguments together, and returns the
-product. When given no arguments, @code{*} returns 1.
-
-@example
-(*)
- @result{} 1
-(* 1)
- @result{} 1
-(* 1 2 3 4)
- @result{} 24
-@end example
-@end defun
-
-@defun / dividend divisor &rest divisors
-This function divides @var{dividend} by @var{divisor} and returns the
-quotient. If there are additional arguments @var{divisors}, then it
-divides @var{dividend} by each divisor in turn. Each argument may be a
-number or a marker.
-
-If all the arguments are integers, then the result is an integer too.
-This means the result has to be rounded. On most machines, the result
-is rounded towards zero after each division, but some machines may round
-differently with negative arguments. This is because the Lisp function
-@code{/} is implemented using the C division operator, which also
-permits machine-dependent rounding. As a practical matter, all known
-machines round in the standard fashion.
-
-@cindex @code{arith-error} in division
-If you divide an integer by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.) Floating point division by zero returns either
-infinity or a NaN if your machine supports @acronym{IEEE} floating point;
-otherwise, it signals an @code{arith-error} error.
-
-@example
-@group
-(/ 6 2)
- @result{} 3
-@end group
-(/ 5 2)
- @result{} 2
-(/ 5.0 2)
- @result{} 2.5
-(/ 5 2.0)
- @result{} 2.5
-(/ 5.0 2.0)
- @result{} 2.5
-(/ 25 3 2)
- @result{} 4
-@group
-(/ -17 6)
- @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
-@end group
-@end example
-@end defun
-
-@defun % dividend divisor
-@cindex remainder
-This function returns the integer remainder after division of @var{dividend}
-by @var{divisor}. The arguments must be integers or markers.
-
-For negative arguments, the remainder is in principle machine-dependent
-since the quotient is; but in practice, all known machines behave alike.
-
-An @code{arith-error} results if @var{divisor} is 0.
-
-@example
-(% 9 4)
- @result{} 1
-(% -9 4)
- @result{} -1
-(% 9 -4)
- @result{} 1
-(% -9 -4)
- @result{} -1
-@end example
-
-For any two integers @var{dividend} and @var{divisor},
-
-@example
-@group
-(+ (% @var{dividend} @var{divisor})
- (* (/ @var{dividend} @var{divisor}) @var{divisor}))
-@end group
-@end example
-
-@noindent
-always equals @var{dividend}.
-@end defun
-
-@defun mod dividend divisor
-@cindex modulus
-This function returns the value of @var{dividend} modulo @var{divisor};
-in other words, the remainder after division of @var{dividend}
-by @var{divisor}, but with the same sign as @var{divisor}.
-The arguments must be numbers or markers.
-
-Unlike @code{%}, @code{mod} returns a well-defined result for negative
-arguments. It also permits floating point arguments; it rounds the
-quotient downward (towards minus infinity) to an integer, and uses that
-quotient to compute the remainder.
-
-An @code{arith-error} results if @var{divisor} is 0.
-
-@example
-@group
-(mod 9 4)
- @result{} 1
-@end group
-@group
-(mod -9 4)
- @result{} 3
-@end group
-@group
-(mod 9 -4)
- @result{} -3
-@end group
-@group
-(mod -9 -4)
- @result{} -1
-@end group
-@group
-(mod 5.5 2.5)
- @result{} .5
-@end group
-@end example
-
-For any two numbers @var{dividend} and @var{divisor},
-
-@example
-@group
-(+ (mod @var{dividend} @var{divisor})
- (* (floor @var{dividend} @var{divisor}) @var{divisor}))
-@end group
-@end example
-
-@noindent
-always equals @var{dividend}, subject to rounding error if either
-argument is floating point. For @code{floor}, see @ref{Numeric
-Conversions}.
-@end defun
-
-@node Rounding Operations
-@section Rounding Operations
-@cindex rounding without conversion
-
-The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
-@code{ftruncate} take a floating point argument and return a floating
-point result whose value is a nearby integer. @code{ffloor} returns the
-nearest integer below; @code{fceiling}, the nearest integer above;
-@code{ftruncate}, the nearest integer in the direction towards zero;
-@code{fround}, the nearest integer.
-
-@defun ffloor float
-This function rounds @var{float} to the next lower integral value, and
-returns that value as a floating point number.
-@end defun
-
-@defun fceiling float
-This function rounds @var{float} to the next higher integral value, and
-returns that value as a floating point number.
-@end defun
-
-@defun ftruncate float
-This function rounds @var{float} towards zero to an integral value, and
-returns that value as a floating point number.
-@end defun
-
-@defun fround float
-This function rounds @var{float} to the nearest integral value,
-and returns that value as a floating point number.
-@end defun
-
-@node Bitwise Operations
-@section Bitwise Operations on Integers
-@cindex bitwise arithmetic
-@cindex logical arithmetic
-
- In a computer, an integer is represented as a binary number, a
-sequence of @dfn{bits} (digits which are either zero or one). A bitwise
-operation acts on the individual bits of such a sequence. For example,
-@dfn{shifting} moves the whole sequence left or right one or more places,
-reproducing the same pattern ``moved over.''
-
- The bitwise operations in Emacs Lisp apply only to integers.
-
-@defun lsh integer1 count
-@cindex logical shift
-@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
-bits in @var{integer1} to the left @var{count} places, or to the right
-if @var{count} is negative, bringing zeros into the vacated bits. If
-@var{count} is negative, @code{lsh} shifts zeros into the leftmost
-(most-significant) bit, producing a positive result even if
-@var{integer1} is negative. Contrast this with @code{ash}, below.
-
-Here are two examples of @code{lsh}, shifting a pattern of bits one
-place to the left. We show only the low-order eight bits of the binary
-pattern; the rest are all zero.
-
-@example
-@group
-(lsh 5 1)
- @result{} 10
-;; @r{Decimal 5 becomes decimal 10.}
-00000101 @result{} 00001010
-
-(lsh 7 1)
- @result{} 14
-;; @r{Decimal 7 becomes decimal 14.}
-00000111 @result{} 00001110
-@end group
-@end example
-
-@noindent
-As the examples illustrate, shifting the pattern of bits one place to
-the left produces a number that is twice the value of the previous
-number.
-
-Shifting a pattern of bits two places to the left produces results
-like this (with 8-bit binary numbers):
-
-@example
-@group
-(lsh 3 2)
- @result{} 12
-;; @r{Decimal 3 becomes decimal 12.}
-00000011 @result{} 00001100
-@end group
-@end example
-
-On the other hand, shifting one place to the right looks like this:
-
-@example
-@group
-(lsh 6 -1)
- @result{} 3
-;; @r{Decimal 6 becomes decimal 3.}
-00000110 @result{} 00000011
-@end group
-
-@group
-(lsh 5 -1)
- @result{} 2
-;; @r{Decimal 5 becomes decimal 2.}
-00000101 @result{} 00000010
-@end group
-@end example
-
-@noindent
-As the example illustrates, shifting one place to the right divides the
-value of a positive integer by two, rounding downward.
-
-The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
-not check for overflow, so shifting left can discard significant bits
-and change the sign of the number. For example, left shifting
-268,435,455 produces @minus{}2 on a 29-bit machine:
-
-@example
-(lsh 268435455 1) ; @r{left shift}
- @result{} -2
-@end example
-
-In binary, in the 29-bit implementation, the argument looks like this:
-
-@example
-@group
-;; @r{Decimal 268,435,455}
-0 1111 1111 1111 1111 1111 1111 1111
-@end group
-@end example
-
-@noindent
-which becomes the following when left shifted:
-
-@example
-@group
-;; @r{Decimal @minus{}2}
-1 1111 1111 1111 1111 1111 1111 1110
-@end group
-@end example
-@end defun
-
-@defun ash integer1 count
-@cindex arithmetic shift
-@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
-to the left @var{count} places, or to the right if @var{count}
-is negative.
-
-@code{ash} gives the same results as @code{lsh} except when
-@var{integer1} and @var{count} are both negative. In that case,
-@code{ash} puts ones in the empty bit positions on the left, while
-@code{lsh} puts zeros in those bit positions.
-
-Thus, with @code{ash}, shifting the pattern of bits one place to the right
-looks like this:
-
-@example
-@group
-(ash -6 -1) @result{} -3
-;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
-1 1111 1111 1111 1111 1111 1111 1010
- @result{}
-1 1111 1111 1111 1111 1111 1111 1101
-@end group
-@end example
-
-In contrast, shifting the pattern of bits one place to the right with
-@code{lsh} looks like this:
-
-@example
-@group
-(lsh -6 -1) @result{} 268435453
-;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
-1 1111 1111 1111 1111 1111 1111 1010
- @result{}
-0 1111 1111 1111 1111 1111 1111 1101
-@end group
-@end example
-
-Here are other examples:
-
-@c !!! Check if lined up in smallbook format! XDVI shows problem
-@c with smallbook but not with regular book! --rjc 16mar92
-@smallexample
-@group
- ; @r{ 29-bit binary values}
-
-(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100}
-@end group
-@group
-(ash 5 2)
- @result{} 20
-(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
- @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100}
-(ash -5 2)
- @result{} -20
-@end group
-@group
-(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001}
-@end group
-@group
-(ash 5 -2)
- @result{} 1
-@end group
-@group
-(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
- @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110}
-@end group
-@group
-(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
- @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110}
-@end group
-@end smallexample
-@end defun
-
-@defun logand &rest ints-or-markers
-This function returns the ``logical and'' of the arguments: the
-@var{n}th bit is set in the result if, and only if, the @var{n}th bit is
-set in all the arguments. (``Set'' means that the value of the bit is 1
-rather than 0.)
-
-For example, using 4-bit binary numbers, the ``logical and'' of 13 and
-12 is 12: 1101 combined with 1100 produces 1100.
-In both the binary numbers, the leftmost two bits are set (i.e., they
-are 1's), so the leftmost two bits of the returned value are set.
-However, for the rightmost two bits, each is zero in at least one of
-the arguments, so the rightmost two bits of the returned value are 0's.
-
-@noindent
-Therefore,
-
-@example
-@group
-(logand 13 12)
- @result{} 12
-@end group
-@end example
-
-If @code{logand} is not passed any argument, it returns a value of
-@minus{}1. This number is an identity element for @code{logand}
-because its binary representation consists entirely of ones. If
-@code{logand} is passed just one argument, it returns that argument.
-
-@smallexample
-@group
- ; @r{ 29-bit binary values}
-
-(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
- ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
- @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
-@end group
-
-@group
-(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
- ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
- ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
- @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
-@end group
-
-@group
-(logand)
- @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
-@end group
-@end smallexample
-@end defun
-
-@defun logior &rest ints-or-markers
-This function returns the ``inclusive or'' of its arguments: the @var{n}th bit
-is set in the result if, and only if, the @var{n}th bit is set in at least
-one of the arguments. If there are no arguments, the result is zero,
-which is an identity element for this operation. If @code{logior} is
-passed just one argument, it returns that argument.
-
-@smallexample
-@group
- ; @r{ 29-bit binary values}
-
-(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
-@end group
-
-@group
-(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
- @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111}
-@end group
-@end smallexample
-@end defun
-
-@defun logxor &rest ints-or-markers
-This function returns the ``exclusive or'' of its arguments: the
-@var{n}th bit is set in the result if, and only if, the @var{n}th bit is
-set in an odd number of the arguments. If there are no arguments, the
-result is 0, which is an identity element for this operation. If
-@code{logxor} is passed just one argument, it returns that argument.
-
-@smallexample
-@group
- ; @r{ 29-bit binary values}
-
-(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001}
-@end group
-
-@group
-(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
- ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
- @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
-@end group
-@end smallexample
-@end defun
-
-@defun lognot integer
-This function returns the logical complement of its argument: the @var{n}th
-bit is one in the result if, and only if, the @var{n}th bit is zero in
-@var{integer}, and vice-versa.
-
-@example
-(lognot 5)
- @result{} -6
-;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
-;; @r{becomes}
-;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010}
-@end example
-@end defun
-
-@node Math Functions
-@section Standard Mathematical Functions
-@cindex transcendental functions
-@cindex mathematical functions
-@cindex floating-point functions
-
- These mathematical functions allow integers as well as floating point
-numbers as arguments.
-
-@defun sin arg
-@defunx cos arg
-@defunx tan arg
-These are the ordinary trigonometric functions, with argument measured
-in radians.
-@end defun
-
-@defun asin arg
-The value of @code{(asin @var{arg})} is a number between
-@ifnottex
-@minus{}pi/2
-@end ifnottex
-@tex
-@math{-\pi/2}
-@end tex
-and
-@ifnottex
-pi/2
-@end ifnottex
-@tex
-@math{\pi/2}
-@end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
-range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
-@end defun
-
-@defun acos arg
-The value of @code{(acos @var{arg})} is a number between 0 and
-@ifnottex
-pi
-@end ifnottex
-@tex
-@math{\pi}
-@end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
-of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
-@end defun
-
-@defun atan y &optional x
-The value of @code{(atan @var{y})} is a number between
-@ifnottex
-@minus{}pi/2
-@end ifnottex
-@tex
-@math{-\pi/2}
-@end tex
-and
-@ifnottex
-pi/2
-@end ifnottex
-@tex
-@math{\pi/2}
-@end tex
-(exclusive) whose tangent is @var{y}. If the optional second
-argument @var{x} is given, the value of @code{(atan y x)} is the
-angle in radians between the vector @code{[@var{x}, @var{y}]} and the
-@code{X} axis.
-@end defun
-
-@defun exp arg
-This is the exponential function; it returns
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-to the power @var{arg}.
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-is a fundamental mathematical constant also called the base of natural
-logarithms.
-@end defun
-
-@defun log arg &optional base
-This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-is used. If @var{arg} is negative, it signals a @code{domain-error}
-error.
-@end defun
-
-@ignore
-@defun expm1 arg
-This function returns @code{(1- (exp @var{arg}))}, but it is more
-accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
-is close to 1.
-@end defun
-
-@defun log1p arg
-This function returns @code{(log (1+ @var{arg}))}, but it is more
-accurate than that when @var{arg} is so small that adding 1 to it would
-lose accuracy.
-@end defun
-@end ignore
-
-@defun log10 arg
-This function returns the logarithm of @var{arg}, with base 10. If
-@var{arg} is negative, it signals a @code{domain-error} error.
-@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
-approximately.
-@end defun
-
-@defun expt x y
-This function returns @var{x} raised to power @var{y}. If both
-arguments are integers and @var{y} is positive, the result is an
-integer; in this case, overflow causes truncation, so watch out.
-@end defun
-
-@defun sqrt arg
-This returns the square root of @var{arg}. If @var{arg} is negative,
-it signals a @code{domain-error} error.
-@end defun
-
-@node Random Numbers
-@section Random Numbers
-@cindex random numbers
-
-A deterministic computer program cannot generate true random numbers.
-For most purposes, @dfn{pseudo-random numbers} suffice. A series of
-pseudo-random numbers is generated in a deterministic fashion. The
-numbers are not truly random, but they have certain properties that
-mimic a random series. For example, all possible values occur equally
-often in a pseudo-random series.
-
-In Emacs, pseudo-random numbers are generated from a ``seed'' number.
-Starting from any given seed, the @code{random} function always
-generates the same sequence of numbers. Emacs always starts with the
-same seed value, so the sequence of values of @code{random} is actually
-the same in each Emacs run! For example, in one operating system, the
-first call to @code{(random)} after you start Emacs always returns
-@minus{}1457731, and the second one always returns @minus{}7692030. This
-repeatability is helpful for debugging.
-
-If you want random numbers that don't always come out the same, execute
-@code{(random t)}. This chooses a new seed based on the current time of
-day and on Emacs's process @acronym{ID} number.
-
-@defun random &optional limit
-This function returns a pseudo-random integer. Repeated calls return a
-series of pseudo-random integers.
-
-If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit}.
-
-If @var{limit} is @code{t}, it means to choose a new seed based on the
-current time of day and on Emacs's process @acronym{ID} number.
-@c "Emacs'" is incorrect usage!
-
-On some machines, any integer representable in Lisp may be the result
-of @code{random}. On other machines, the result can never be larger
-than a certain maximum or less than a certain (negative) minimum.
-@end defun
-
-@ignore
- arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/objects
-@node Lisp Data Types, Numbers, Introduction, Top
-@chapter Lisp Data Types
-@cindex object
-@cindex Lisp object
-@cindex type
-@cindex data type
-
- A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
-programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
-possible objects.
-
- Every object belongs to at least one type. Objects of the same type
-have similar structures and may usually be used in the same contexts.
-Types can overlap, and objects can belong to two or more types.
-Consequently, we can ask whether an object belongs to a particular type,
-but not for ``the'' type of an object.
-
-@cindex primitive type
- A few fundamental object types are built into Emacs. These, from
-which all other types are constructed, are called @dfn{primitive types}.
-Each object belongs to one and only one primitive type. These types
-include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
-@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
-@dfn{byte-code function}, plus several special types, such as
-@dfn{buffer}, that are related to editing. (@xref{Editing Types}.)
-
- Each primitive type has a corresponding Lisp function that checks
-whether an object is a member of that type.
-
- Note that Lisp is unlike many other languages in that Lisp objects are
-@dfn{self-typing}: the primitive type of the object is implicit in the
-object itself. For example, if an object is a vector, nothing can treat
-it as a number; Lisp knows it is a vector, not a number.
-
- In most languages, the programmer must declare the data type of each
-variable, and the type is known by the compiler but not represented in
-the data. Such type declarations do not exist in Emacs Lisp. A Lisp
-variable can have any type of value, and it remembers whatever value
-you store in it, type and all. (Actually, a small number of Emacs
-Lisp variables can only take on values of a certain type.
-@xref{Variables with Restricted Values}.)
-
- This chapter describes the purpose, printed representation, and read
-syntax of each of the standard types in GNU Emacs Lisp. Details on how
-to use these types can be found in later chapters.
-
-@menu
-* 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.
-@end menu
-
-@node Printed Representation
-@comment node-name, next, previous, up
-@section Printed Representation and Read Syntax
-@cindex printed representation
-@cindex read syntax
-
- The @dfn{printed representation} of an object is the format of the
-output generated by the Lisp printer (the function @code{prin1}) for
-that object. Every data type has a unique printed representation.
-The @dfn{read syntax} of an object is the format of the input accepted
-by the Lisp reader (the function @code{read}) for that object. This
-is not necessarily unique; many kinds of object have more than one
-syntax. @xref{Read and Print}.
-
-@cindex hash notation
- In most cases, an object's printed representation is also a read
-syntax for the object. However, some types have no read syntax, since
-it does not make sense to enter objects of these types as constants in
-a Lisp program. These objects are printed in @dfn{hash notation},
-which consists of the characters @samp{#<}, a descriptive string
-(typically the type name followed by the name of the object), and a
-closing @samp{>}. For example:
-
-@example
-(current-buffer)
- @result{} #<buffer objects.texi>
-@end example
-
-@noindent
-Hash notation cannot be read at all, so the Lisp reader signals the
-error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
-@kindex invalid-read-syntax
-
- In other languages, an expression is text; it has no other form. In
-Lisp, an expression is primarily a Lisp object and only secondarily the
-text that is the object's read syntax. Often there is no need to
-emphasize this distinction, but you must keep it in the back of your
-mind, or you will occasionally be very confused.
-
- When you evaluate an expression interactively, the Lisp interpreter
-first reads the textual representation of it, producing a Lisp object,
-and then evaluates that object (@pxref{Evaluation}). However,
-evaluation and reading are separate activities. Reading returns the
-Lisp object represented by the text that is read; the object may or may
-not be evaluated later. @xref{Input Functions}, for a description of
-@code{read}, the basic function for reading objects.
-
-@node Comments
-@comment node-name, next, previous, up
-@section Comments
-@cindex comments
-@cindex @samp{;} in comment
-
- A @dfn{comment} is text that is written in a program only for the sake
-of humans that read the program, and that has no effect on the meaning
-of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
-is not within a string or character constant. The comment continues to
-the end of line. The Lisp reader discards comments; they do not become
-part of the Lisp objects which represent the program within the Lisp
-system.
-
- The @samp{#@@@var{count}} construct, which skips the next @var{count}
-characters, is useful for program-generated comments containing binary
-data. The Emacs Lisp byte compiler uses this in its output files
-(@pxref{Byte Compilation}). It isn't meant for source files, however.
-
- @xref{Comment Tips}, for conventions for formatting comments.
-
-@node Programming Types
-@section Programming Types
-@cindex programming types
-
- There are two general categories of types in Emacs Lisp: those having
-to do with Lisp programming, and those having to do with editing. The
-former exist in many Lisp implementations, in one form or another. The
-latter are unique to Emacs Lisp.
-
-@menu
-* 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, or property list, and has a unique identity.
-* 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.
-@end menu
-
-@node Integer Type
-@subsection Integer Type
-
- The range of values for integers in Emacs Lisp is @minus{}268435456 to
-268435455 (29 bits; i.e.,
-@ifnottex
--2**28
-@end ifnottex
-@tex
-@math{-2^{28}}
-@end tex
-to
-@ifnottex
-2**28 - 1)
-@end ifnottex
-@tex
-@math{2^{28}-1})
-@end tex
-on most machines. (Some machines may provide a wider range.) It is
-important to note that the Emacs Lisp arithmetic functions do not check
-for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most
-machines.
-
- The read syntax for integers is a sequence of (base ten) digits with an
-optional sign at the beginning and an optional period at the end. The
-printed representation produced by the Lisp interpreter never has a
-leading @samp{+} or a final @samp{.}.
-
-@example
-@group
--1 ; @r{The integer -1.}
-1 ; @r{The integer 1.}
-1. ; @r{Also the integer 1.}
-+1 ; @r{Also the integer 1.}
-536870913 ; @r{Also the integer 1 on a 29-bit implementation.}
-@end group
-@end example
-
- @xref{Numbers}, for more information.
-
-@node Floating Point Type
-@subsection Floating Point Type
-
- Floating point numbers are the computer equivalent of scientific
-notation; you can think of a floating point number as a fraction
-together with a power of ten. The precise number of significant
-figures and the range of possible exponents is machine-specific; Emacs
-uses the C data type @code{double} to store the value, and internally
-this records a power of 2 rather than a power of 10.
-
- The printed representation for floating point numbers requires either
-a decimal point (with at least one digit following), an exponent, or
-both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
-@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
-number whose value is 1500. They are all equivalent.
-
- @xref{Numbers}, for more information.
-
-@node Character Type
-@subsection Character Type
-@cindex @acronym{ASCII} character codes
-
- A @dfn{character} in Emacs Lisp is nothing more than an integer. In
-other words, characters are represented by their character codes. For
-example, the character @kbd{A} is represented as the @w{integer 65}.
-
- Individual characters are used occasionally in programs, but it is
-more common to work with @emph{strings}, which are sequences composed
-of characters. @xref{String Type}.
-
- Characters in strings, buffers, and files are currently limited to
-the range of 0 to 524287---nineteen bits. But not all values in that
-range are valid character codes. Codes 0 through 127 are
-@acronym{ASCII} codes; the rest are non-@acronym{ASCII}
-(@pxref{Non-ASCII Characters}). Characters that represent keyboard
-input have a much wider range, to encode modifier keys such as
-Control, Meta and Shift.
-
- There are special functions for producing a human-readable textual
-description of a character for the sake of messages. @xref{Describing
-Characters}.
-
-@menu
-* Basic Char Syntax::
-* General Escape Syntax::
-* Ctl-Char Syntax::
-* Meta-Char Syntax::
-* Other Char Bits::
-@end menu
-
-@node Basic Char Syntax
-@subsubsection Basic Char Syntax
-@cindex read syntax for characters
-@cindex printed representation for characters
-@cindex syntax for characters
-@cindex @samp{?} in character constant
-@cindex question mark in character constant
-
- Since characters are really integers, the printed representation of
-a character is a decimal number. This is also a possible read syntax
-for a character, but writing characters that way in Lisp programs is
-not clear programming. You should @emph{always} use the special read
-syntax formats that Emacs Lisp provides for characters. These syntax
-formats start with a question mark.
-
- The usual read syntax for alphanumeric characters is a question mark
-followed by the character; thus, @samp{?A} for the character
-@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
-character @kbd{a}.
-
- For example:
-
-@example
-?Q @result{} 81 ?q @result{} 113
-@end example
-
- You can use the same syntax for punctuation characters, but it is
-often a good idea to add a @samp{\} so that the Emacs commands for
-editing Lisp code don't get confused. For example, @samp{?\(} is the
-way to write the open-paren character. If the character is @samp{\},
-you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
-
-@cindex whitespace
-@cindex bell character
-@cindex @samp{\a}
-@cindex backspace
-@cindex @samp{\b}
-@cindex tab (ASCII character)
-@cindex @samp{\t}
-@cindex vertical tab
-@cindex @samp{\v}
-@cindex formfeed
-@cindex @samp{\f}
-@cindex newline
-@cindex @samp{\n}
-@cindex return (ASCII character)
-@cindex @samp{\r}
-@cindex escape (ASCII character)
-@cindex @samp{\e}
-@cindex space (ASCII character)
-@cindex @samp{\s}
- You can express the characters control-g, backspace, tab, newline,
-vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
-@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
-@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
-(@samp{?\s} followed by a dash has a different meaning---it applies
-the ``super'' modifier to the following character.) Thus,
-
-@example
-?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
-?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
-?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
-?\n @result{} 10 ; @r{newline, @kbd{C-j}}
-?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
-?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
-?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
-?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
-?\s @result{} 32 ; @r{space character, @key{SPC}}
-?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
-?\d @result{} 127 ; @r{delete character, @key{DEL}}
-@end example
-
-@cindex escape sequence
- These sequences which start with backslash are also known as
-@dfn{escape sequences}, because backslash plays the role of an
-``escape character''; this terminology has nothing to do with the
-character @key{ESC}. @samp{\s} is meant for use in character
-constants; in string constants, just write the space.
-
- A backslash is allowed, and harmless, preceding any character without
-a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
-There is no reason to add a backslash before most characters. However,
-you should add a backslash before any of the characters
-@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
-Lisp code. You can also add a backslash before whitespace characters such as
-space, tab, newline and formfeed. However, it is cleaner to use one of
-the easily readable escape sequences, such as @samp{\t} or @samp{\s},
-instead of an actual whitespace character such as a tab or a space.
-(If you do write backslash followed by a space, you should write
-an extra space after the character constant to separate it from the
-following text.)
-
-@node General Escape Syntax
-@subsubsection General Escape Syntax
-
- In addition to the specific excape sequences for special important
-control characters, Emacs provides general categories of escape syntax
-that you can use to specify non-ASCII text characters.
-
-@cindex unicode character escape
- For instance, you can specify characters by their Unicode values.
-@code{?\u@var{nnnn}} represents a character that maps to the Unicode
-code point @samp{U+@var{nnnn}}. There is a slightly different syntax
-for specifying characters with code points above @code{#xFFFF};
-@code{\U00@var{nnnnnn}} represents the character whose Unicode code
-point is @samp{U+@var{nnnnnn}}, if such a character is supported by
-Emacs. If the corresponding character is not supported, Emacs signals
-an error.
-
- This peculiar and inconvenient syntax was adopted for compatibility
-with other programming languages. Unlike some other languages, Emacs
-Lisp supports this syntax in only character literals and strings.
-
-@cindex @samp{\} in character constant
-@cindex backslash in character constant
-@cindex octal character code
- The most general read syntax for a character represents the
-character code in either octal or hex. To use octal, write a question
-mark followed by a backslash and the octal character code (up to three
-octal digits); thus, @samp{?\101} for the character @kbd{A},
-@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
-character @kbd{C-b}. Although this syntax can represent any
-@acronym{ASCII} character, it is preferred only when the precise octal
-value is more important than the @acronym{ASCII} representation.
-
-@example
-@group
-?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
-?\101 @result{} 65 ?A @result{} 65
-@end group
-@end example
-
- To use hex, write a question mark followed by a backslash, @samp{x},
-and the hexadecimal character code. You can use any number of hex
-digits, so you can represent any character code in this way.
-Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
-character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
-@iftex
-@samp{@`a}.
-@end iftex
-@ifnottex
-@samp{a} with grave accent.
-@end ifnottex
-
-@node Ctl-Char Syntax
-@subsubsection Control-Character Syntax
-
-@cindex control characters
- Control characters can be represented using yet another read syntax.
-This consists of a question mark followed by a backslash, caret, and the
-corresponding non-control character, in either upper or lower case. For
-example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
-character @kbd{C-i}, the character whose value is 9.
-
- Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
-equivalent to @samp{?\^I} and to @samp{?\^i}:
-
-@example
-?\^I @result{} 9 ?\C-I @result{} 9
-@end example
-
- In strings and buffers, the only control characters allowed are those
-that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
-any character into a control character with @samp{C-}. The character
-codes for these non-@acronym{ASCII} control characters include the
-@tex
-@math{2^{26}}
-@end tex
-@ifnottex
-2**26
-@end ifnottex
-bit as well as the code for the corresponding non-control
-character. Ordinary terminals have no way of generating non-@acronym{ASCII}
-control characters, but you can generate them straightforwardly using X
-and other window systems.
-
- For historical reasons, Emacs treats the @key{DEL} character as
-the control equivalent of @kbd{?}:
-
-@example
-?\^? @result{} 127 ?\C-? @result{} 127
-@end example
-
-@noindent
-As a result, it is currently not possible to represent the character
-@kbd{Control-?}, which is a meaningful input character under X, using
-@samp{\C-}. It is not easy to change this, as various Lisp files refer
-to @key{DEL} in this way.
-
- For representing control characters to be found in files or strings,
-we recommend the @samp{^} syntax; for control characters in keyboard
-input, we prefer the @samp{C-} syntax. Which one you use does not
-affect the meaning of the program, but may guide the understanding of
-people who read it.
-
-@node Meta-Char Syntax
-@subsubsection Meta-Character Syntax
-
-@cindex meta characters
- A @dfn{meta character} is a character typed with the @key{META}
-modifier key. The integer that represents such a character has the
-@tex
-@math{2^{27}}
-@end tex
-@ifnottex
-2**27
-@end ifnottex
-bit set. We use high bits for this and other modifiers to make
-possible a wide range of basic character codes.
-
- In a string, the
-@tex
-@math{2^{7}}
-@end tex
-@ifnottex
-2**7
-@end ifnottex
-bit attached to an @acronym{ASCII} character indicates a meta
-character; thus, the meta characters that can fit in a string have
-codes in the range from 128 to 255, and are the meta versions of the
-ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older,
-this convention was used for characters outside of strings as well.)
-
- The read syntax for meta characters uses @samp{\M-}. For example,
-@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
-octal character codes (see below), with @samp{\C-}, or with any other
-syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
-or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
-@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
-
-@node Other Char Bits
-@subsubsection Other Character Modifier Bits
-
- The case of a graphic character is indicated by its character code;
-for example, @acronym{ASCII} distinguishes between the characters @samp{a}
-and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
-character is upper case or lower case. Emacs uses the
-@tex
-@math{2^{25}}
-@end tex
-@ifnottex
-2**25
-@end ifnottex
-bit to indicate that the shift key was used in typing a control
-character. This distinction is possible only when you use X terminals
-or other special terminals; ordinary terminals do not report the
-distinction to the computer in any way. The Lisp syntax for
-the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
-represents the shifted-control-o character.
-
-@cindex hyper characters
-@cindex super characters
-@cindex alt characters
- The X Window System defines three other
-@anchor{modifier bits}modifier bits that can be set
-in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
-for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
-significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
-@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
-represents the space character.)
-@tex
-Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
-for super and @math{2^{24}} for hyper.
-@end tex
-@ifnottex
-Numerically, the
-bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
-@end ifnottex
-
-@node Symbol Type
-@subsection Symbol Type
-
- A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
-symbol name serves as the printed representation of the symbol. In
-ordinary Lisp use, with one single obarray (@pxref{Creating Symbols},
-a symbol's name is unique---no two symbols have the same name.
-
- A symbol can serve as a variable, as a function name, or to hold a
-property list. Or it may serve only to be distinct from all other Lisp
-objects, so that its presence in a data structure may be recognized
-reliably. In a given context, usually only one of these uses is
-intended. But you can use one symbol in all of these ways,
-independently.
-
- A symbol whose name starts with a colon (@samp{:}) is called a
-@dfn{keyword symbol}. These symbols automatically act as constants, and
-are normally used only by comparing an unknown symbol with a few
-specific alternatives.
-
-@cindex @samp{\} in symbols
-@cindex backslash in symbols
- A symbol name can contain any characters whatever. Most symbol names
-are written with letters, digits, and the punctuation characters
-@samp{-+=*/}. Such names require no special punctuation; the characters
-of the name suffice as long as the name does not look like a number.
-(If it does, write a @samp{\} at the beginning of the name to force
-interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
-less often used but also require no special punctuation. Any other
-characters may be included in a symbol's name by escaping them with a
-backslash. In contrast to its use in strings, however, a backslash in
-the name of a symbol simply quotes the single character that follows the
-backslash. For example, in a string, @samp{\t} represents a tab
-character; in the name of a symbol, however, @samp{\t} merely quotes the
-letter @samp{t}. To have a symbol with a tab character in its name, you
-must actually use a tab (preceded with a backslash). But it's rare to
-do such a thing.
-
-@cindex CL note---case of letters
-@quotation
-@b{Common Lisp note:} In Common Lisp, lower case letters are always
-``folded'' to upper case, unless they are explicitly escaped. In Emacs
-Lisp, upper case and lower case letters are distinct.
-@end quotation
-
- Here are several examples of symbol names. Note that the @samp{+} in
-the fifth example is escaped to prevent it from being read as a number.
-This is not necessary in the fourth example because the rest of the name
-makes it invalid as a number.
-
-@example
-@group
-foo ; @r{A symbol named @samp{foo}.}
-FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
-char-to-string ; @r{A symbol named @samp{char-to-string}.}
-@end group
-@group
-1+ ; @r{A symbol named @samp{1+}}
- ; @r{(not @samp{+1}, which is an integer).}
-@end group
-@group
-\+1 ; @r{A symbol named @samp{+1}}
- ; @r{(not a very readable name).}
-@end group
-@group
-\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
-@c the @'s in this next line use up three characters, hence the
-@c apparent misalignment of the comment.
-+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
- ; @r{These characters need not be escaped.}
-@end group
-@end example
-
-@ifinfo
-@c This uses ``colon'' instead of a literal `:' because Info cannot
-@c cope with a `:' in a menu
-@cindex @samp{#@var{colon}} read syntax
-@end ifinfo
-@ifnotinfo
-@cindex @samp{#:} read syntax
-@end ifnotinfo
- Normally the Lisp reader interns all symbols (@pxref{Creating
-Symbols}). To prevent interning, you can write @samp{#:} before the
-name of the symbol.
-
-@node Sequence Type
-@subsection Sequence Types
-
- A @dfn{sequence} is a Lisp object that represents an ordered set of
-elements. There are two kinds of sequence in Emacs Lisp, lists and
-arrays. Thus, an object of type list or of type array is also
-considered a sequence.
-
- Arrays are further subdivided into strings, vectors, char-tables and
-bool-vectors. Vectors can hold elements of any type, but string
-elements must be characters, and bool-vector elements must be @code{t}
-or @code{nil}. Char-tables are like vectors except that they are
-indexed by any valid character code. The characters in a string can
-have text properties like characters in a buffer (@pxref{Text
-Properties}), but vectors do not support text properties, even when
-their elements happen to be characters.
-
- Lists, strings and the other array types are different, but they have
-important similarities. For example, all have a length @var{l}, and all
-have elements which can be indexed from zero to @var{l} minus one.
-Several functions, called sequence functions, accept any kind of
-sequence. For example, the function @code{elt} can be used to extract
-an element of a sequence, given its index. @xref{Sequences Arrays
-Vectors}.
-
- It is generally impossible to read the same sequence twice, since
-sequences are always created anew upon reading. If you read the read
-syntax for a sequence twice, you get two sequences with equal contents.
-There is one exception: the empty list @code{()} always stands for the
-same object, @code{nil}.
-
-@node Cons Cell Type
-@subsection Cons Cell and List Types
-@cindex address field of register
-@cindex decrement field of register
-@cindex pointers
-
- A @dfn{cons cell} is an object that consists of two slots, called the
-@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
-@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
-this cons cell is'' whatever object its @sc{car} slot currently holds,
-and likewise for the @sc{cdr}.
-
-@quotation
-A note to C programmers: in Lisp, we do not distinguish between
-``holding'' a value and ``pointing to'' the value, because pointers in
-Lisp are implicit.
-@end quotation
-
- A @dfn{list} is a series of cons cells, linked together so that the
-@sc{cdr} slot of each cons cell holds either the next cons cell or the
-empty list. The empty list is actually the symbol @code{nil}.
-@xref{Lists}, for functions that work on lists. Because most cons
-cells are used as part of lists, the phrase @dfn{list structure} has
-come to refer to any structure made out of cons cells.
-
-@cindex atoms
- Because cons cells are so central to Lisp, we also have a word for
-``an object which is not a cons cell.'' These objects are called
-@dfn{atoms}.
-
-@cindex parenthesis
-@cindex @samp{(@dots{})} in lists
- The read syntax and printed representation for lists are identical, and
-consist of a left parenthesis, an arbitrary number of elements, and a
-right parenthesis. Here are examples of lists:
-
-@example
-(A 2 "A") ; @r{A list of three elements.}
-() ; @r{A list of no elements (the empty list).}
-nil ; @r{A list of no elements (the empty list).}
-("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
-(A ()) ; @r{A list of two elements: @code{A} and the empty list.}
-(A nil) ; @r{Equivalent to the previous.}
-((A B C)) ; @r{A list of one element}
- ; @r{(which is a list of three elements).}
-@end example
-
- Upon reading, each object inside the parentheses becomes an element
-of the list. That is, a cons cell is made for each element. The
-@sc{car} slot of the cons cell holds the element, and its @sc{cdr}
-slot refers to the next cons cell of the list, which holds the next
-element in the list. The @sc{cdr} slot of the last cons cell is set to
-hold @code{nil}.
-
- The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
-original Lisp implementation ran on an @w{IBM 704} computer which
-divided words into two parts, called the ``address'' part and the
-``decrement''; @sc{car} was an instruction to extract the contents of
-the address part of a register, and @sc{cdr} an instruction to extract
-the contents of the decrement. By contrast, ``cons cells'' are named
-for the function @code{cons} that creates them, which in turn was named
-for its purpose, the construction of cells.
-
-@menu
-* Box Diagrams:: Drawing pictures of lists.
-* Dotted Pair Notation:: A general syntax for cons cells.
-* Association List Type:: A specially constructed list.
-@end menu
-
-@node Box Diagrams
-@subsubsection Drawing Lists as Box Diagrams
-@cindex box diagrams, for lists
-@cindex diagrams, boxed, for lists
-
- A list can be illustrated by a diagram in which the cons cells are
-shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
-such an illustration; unlike the textual notation, which can be
-understood by both humans and computers, the box illustrations can be
-understood only by humans.) This picture represents the three-element
-list @code{(rose violet buttercup)}:
-
-@example
-@group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- --> rose --> violet --> buttercup
-@end group
-@end example
-
- In this diagram, each box represents a slot that can hold or refer to
-any Lisp object. Each pair of boxes represents a cons cell. Each arrow
-represents a reference to a Lisp object, either an atom or another cons
-cell.
-
- In this example, the first box, which holds the @sc{car} of the first
-cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
-box, holding the @sc{cdr} of the first cons cell, refers to the next
-pair of boxes, the second cons cell. The @sc{car} of the second cons
-cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
-@sc{cdr} of the third (and last) cons cell is @code{nil}.
-
- Here is another diagram of the same list, @code{(rose violet
-buttercup)}, sketched in a different manner:
-
-@smallexample
-@group
- --------------- ---------------- -------------------
-| car | cdr | | car | cdr | | car | cdr |
-| rose | o-------->| violet | o-------->| buttercup | nil |
-| | | | | | | | |
- --------------- ---------------- -------------------
-@end group
-@end smallexample
-
-@cindex @code{nil} as a list
-@cindex empty list
- A list with no elements in it is the @dfn{empty list}; it is identical
-to the symbol @code{nil}. In other words, @code{nil} is both a symbol
-and a list.
-
- Here is the list @code{(A ())}, or equivalently @code{(A nil)},
-depicted with boxes and arrows:
-
-@example
-@group
- --- --- --- ---
- | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> A --> nil
-@end group
-@end example
-
- Here is a more complex illustration, showing the three-element list,
-@code{((pine needles) oak maple)}, the first element of which is a
-two-element list:
-
-@example
-@group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- | --> oak --> maple
- |
- | --- --- --- ---
- --> | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> pine --> needles
-@end group
-@end example
-
- The same list represented in the second box notation looks like this:
-
-@example
-@group
- -------------- -------------- --------------
-| car | cdr | | car | cdr | | car | cdr |
-| o | o------->| oak | o------->| maple | nil |
-| | | | | | | | | |
- -- | --------- -------------- --------------
- |
- |
- | -------------- ----------------
- | | car | cdr | | car | cdr |
- ------>| pine | o------->| needles | nil |
- | | | | | |
- -------------- ----------------
-@end group
-@end example
-
-@node Dotted Pair Notation
-@subsubsection Dotted Pair Notation
-@cindex dotted pair notation
-@cindex @samp{.} in lists
-
- @dfn{Dotted pair notation} is a general syntax for cons cells that
-represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
-@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
-the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted
-pair notation is more general than list syntax because the @sc{cdr}
-does not have to be a list. However, it is more cumbersome in cases
-where list syntax would work. In dotted pair notation, the list
-@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
-@code{nil}-terminated lists, you can use either notation, but list
-notation is usually clearer and more convenient. When printing a
-list, the dotted pair notation is only used if the @sc{cdr} of a cons
-cell is not a list.
-
- Here's an example using boxes to illustrate dotted pair notation.
-This example shows the pair @code{(rose . violet)}:
-
-@example
-@group
- --- ---
- | | |--> violet
- --- ---
- |
- |
- --> rose
-@end group
-@end example
-
- You can combine dotted pair notation with list notation to represent
-conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
-You write a dot after the last element of the list, followed by the
-@sc{cdr} of the final cons cell. For example, @code{(rose violet
-. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
-The object looks like this:
-
-@example
-@group
- --- --- --- ---
- | | |--> | | |--> buttercup
- --- --- --- ---
- | |
- | |
- --> rose --> violet
-@end group
-@end example
-
- The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
-there is nothing that it could mean. If anything, it would say to put
-@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
-used for @code{violet}.
-
- The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
-and looks like this:
-
-@example
-@group
- --- --- --- ---
- | | |--> | | |--> nil
- --- --- --- ---
- | |
- | |
- --> rose --> violet
-@end group
-@end example
-
- Similarly, the three-element list @code{(rose violet buttercup)}
-is equivalent to @code{(rose . (violet . (buttercup)))}.
-@ifnottex
-It looks like this:
-
-@example
-@group
- --- --- --- --- --- ---
- | | |--> | | |--> | | |--> nil
- --- --- --- --- --- ---
- | | |
- | | |
- --> rose --> violet --> buttercup
-@end group
-@end example
-@end ifnottex
-
-@node Association List Type
-@comment node-name, next, previous, up
-@subsubsection Association List Type
-
- An @dfn{association list} or @dfn{alist} is a specially-constructed
-list whose elements are cons cells. In each element, the @sc{car} is
-considered a @dfn{key}, and the @sc{cdr} is considered an
-@dfn{associated value}. (In some cases, the associated value is stored
-in the @sc{car} of the @sc{cdr}.) Association lists are often used as
-stacks, since it is easy to add or remove associations at the front of
-the list.
-
- For example,
-
-@example
-(setq alist-of-colors
- '((rose . red) (lily . white) (buttercup . yellow)))
-@end example
-
-@noindent
-sets the variable @code{alist-of-colors} to an alist of three elements. In the
-first element, @code{rose} is the key and @code{red} is the value.
-
- @xref{Association Lists}, for a further explanation of alists and for
-functions that work on alists. @xref{Hash Tables}, for another kind of
-lookup table, which is much faster for handling a large number of keys.
-
-@node Array Type
-@subsection Array Type
-
- An @dfn{array} is composed of an arbitrary number of slots for
-holding or referring to other Lisp objects, arranged in a contiguous block of
-memory. Accessing any element of an array takes approximately the same
-amount of time. In contrast, accessing an element of a list requires
-time proportional to the position of the element in the list. (Elements
-at the end of a list take longer to access than elements at the
-beginning of a list.)
-
- Emacs defines four types of array: strings, vectors, bool-vectors, and
-char-tables.
-
- A string is an array of characters and a vector is an array of
-arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
-These kinds of array may have any length up to the largest integer.
-Char-tables are sparse arrays indexed by any valid character code; they
-can hold arbitrary objects.
-
- The first element of an array has index zero, the second element has
-index 1, and so on. This is called @dfn{zero-origin} indexing. For
-example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
-largest possible index value is one less than the length of the array.
-Once an array is created, its length is fixed.
-
- All Emacs Lisp arrays are one-dimensional. (Most other programming
-languages support multidimensional arrays, but they are not essential;
-you can get the same effect with nested one-dimensional arrays.) Each
-type of array has its own read syntax; see the following sections for
-details.
-
- The array type is a subset of the sequence type, and contains the
-string type, the vector type, the bool-vector type, and the char-table
-type.
-
-@node String Type
-@subsection String Type
-
- A @dfn{string} is an array of characters. Strings are used for many
-purposes in Emacs, as can be expected in a text editor; for example, as
-the names of Lisp symbols, as messages for the user, and to represent
-text extracted from buffers. Strings in Lisp are constants: evaluation
-of a string returns the same string.
-
- @xref{Strings and Characters}, for functions that operate on strings.
-
-@menu
-* Syntax for Strings::
-* Non-ASCII in Strings::
-* Nonprinting Characters::
-* Text Props and Strings::
-@end menu
-
-@node Syntax for Strings
-@subsubsection Syntax for Strings
-
-@cindex @samp{"} in strings
-@cindex double-quote in strings
-@cindex @samp{\} in strings
-@cindex backslash in strings
- The read syntax for strings is a double-quote, an arbitrary number of
-characters, and another double-quote, @code{"like this"}. To include a
-double-quote in a string, precede it with a backslash; thus, @code{"\""}
-is a string containing just a single double-quote character. Likewise,
-you can include a backslash by preceding it with another backslash, like
-this: @code{"this \\ is a single embedded backslash"}.
-
-@cindex newline in strings
- The newline character is not special in the read syntax for strings;
-if you write a new line between the double-quotes, it becomes a
-character in the string. But an escaped newline---one that is preceded
-by @samp{\}---does not become part of the string; i.e., the Lisp reader
-ignores an escaped newline while reading a string. An escaped space
-@w{@samp{\ }} is likewise ignored.
-
-@example
-"It is useful to include newlines
-in documentation strings,
-but the newline is \
-ignored if escaped."
- @result{} "It is useful to include newlines
-in documentation strings,
-but the newline is ignored if escaped."
-@end example
-
-@node Non-ASCII in Strings
-@subsubsection Non-@acronym{ASCII} Characters in Strings
-
- You can include a non-@acronym{ASCII} international character in a string
-constant by writing it literally. There are two text representations
-for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
-and multibyte. If the string constant is read from a multibyte source,
-such as a multibyte buffer or string, or a file that would be visited as
-multibyte, then the character is read as a multibyte character, and that
-makes the string multibyte. If the string constant is read from a
-unibyte source, then the character is read as unibyte and that makes the
-string unibyte.
-
- You can also represent a multibyte non-@acronym{ASCII} character with its
-character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
-digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
-greater than 256.) Any character which is not a valid hex digit
-terminates this construct. If the next character in the string could be
-interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
-terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
-one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
-constant is just like backslash-newline; it does not contribute any
-character to the string, but it does terminate the preceding hex escape.
-
- You can represent a unibyte non-@acronym{ASCII} character with its
-character code, which must be in the range from 128 (0200 octal) to
-255 (0377 octal). If you write all such character codes in octal and
-the string contains no other characters forcing it to be multibyte,
-this produces a unibyte string. However, using any hex escape in a
-string (even for an @acronym{ASCII} character) forces the string to be
-multibyte.
-
- You can also specify characters in a string by their numeric values
-in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
-
- @xref{Text Representations}, for more information about the two
-text representations.
-
-@node Nonprinting Characters
-@subsubsection Nonprinting Characters in Strings
-
- You can use the same backslash escape-sequences in a string constant
-as in character literals (but do not use the question mark that begins a
-character constant). For example, you can write a string containing the
-nonprinting characters tab and @kbd{C-a}, with commas and spaces between
-them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
-description of the read syntax for characters.
-
- However, not all of the characters you can write with backslash
-escape-sequences are valid in strings. The only control characters that
-a string can hold are the @acronym{ASCII} control characters. Strings do not
-distinguish case in @acronym{ASCII} control characters.
-
- Properly speaking, strings cannot hold meta characters; but when a
-string is to be used as a key sequence, there is a special convention
-that provides a way to represent meta versions of @acronym{ASCII}
-characters in a string. If you use the @samp{\M-} syntax to indicate
-a meta character in a string constant, this sets the
-@tex
-@math{2^{7}}
-@end tex
-@ifnottex
-2**7
-@end ifnottex
-bit of the character in the string. If the string is used in
-@code{define-key} or @code{lookup-key}, this numeric code is translated
-into the equivalent meta character. @xref{Character Type}.
-
- Strings cannot hold characters that have the hyper, super, or alt
-modifiers.
-
-@node Text Props and Strings
-@subsubsection Text Properties in Strings
-
- A string can hold properties for the characters it contains, in
-addition to the characters themselves. This enables programs that copy
-text between strings and buffers to copy the text's properties with no
-special effort. @xref{Text Properties}, for an explanation of what text
-properties mean. Strings with text properties use a special read and
-print syntax:
-
-@example
-#("@var{characters}" @var{property-data}...)
-@end example
-
-@noindent
-where @var{property-data} consists of zero or more elements, in groups
-of three as follows:
-
-@example
-@var{beg} @var{end} @var{plist}
-@end example
-
-@noindent
-The elements @var{beg} and @var{end} are integers, and together specify
-a range of indices in the string; @var{plist} is the property list for
-that range. For example,
-
-@example
-#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
-@end example
-
-@noindent
-represents a string whose textual contents are @samp{foo bar}, in which
-the first three characters have a @code{face} property with value
-@code{bold}, and the last three have a @code{face} property with value
-@code{italic}. (The fourth character has no text properties, so its
-property list is @code{nil}. It is not actually necessary to mention
-ranges with @code{nil} as the property list, since any characters not
-mentioned in any range will default to having no properties.)
-
-@node Vector Type
-@subsection Vector Type
-
- A @dfn{vector} is a one-dimensional array of elements of any type. It
-takes a constant amount of time to access any element of a vector. (In
-a list, the access time of an element is proportional to the distance of
-the element from the beginning of the list.)
-
- The printed representation of a vector consists of a left square
-bracket, the elements, and a right square bracket. This is also the
-read syntax. Like numbers and strings, vectors are considered constants
-for evaluation.
-
-@example
-[1 "two" (three)] ; @r{A vector of three elements.}
- @result{} [1 "two" (three)]
-@end example
-
- @xref{Vectors}, for functions that work with vectors.
-
-@node Char-Table Type
-@subsection Char-Table Type
-
- A @dfn{char-table} is a one-dimensional array of elements of any type,
-indexed by character codes. Char-tables have certain extra features to
-make them more useful for many jobs that involve assigning information
-to character codes---for example, a char-table can have a parent to
-inherit from, a default value, and a small number of extra slots to use for
-special purposes. A char-table can also specify a single value for
-a whole character set.
-
- The printed representation of a char-table is like a vector
-except that there is an extra @samp{#^} at the beginning.
-
- @xref{Char-Tables}, for special functions to operate on char-tables.
-Uses of char-tables include:
-
-@itemize @bullet
-@item
-Case tables (@pxref{Case Tables}).
-
-@item
-Character category tables (@pxref{Categories}).
-
-@item
-Display tables (@pxref{Display Tables}).
-
-@item
-Syntax tables (@pxref{Syntax Tables}).
-@end itemize
-
-@node Bool-Vector Type
-@subsection Bool-Vector Type
-
- A @dfn{bool-vector} is a one-dimensional array of elements that
-must be @code{t} or @code{nil}.
-
- The printed representation of a bool-vector is like a string, except
-that it begins with @samp{#&} followed by the length. The string
-constant that follows actually specifies the contents of the bool-vector
-as a bitmap---each ``character'' in the string contains 8 bits, which
-specify the next 8 elements of the bool-vector (1 stands for @code{t},
-and 0 for @code{nil}). The least significant bits of the character
-correspond to the lowest indices in the bool-vector.
-
-@example
-(make-bool-vector 3 t)
- @result{} #&3"^G"
-(make-bool-vector 3 nil)
- @result{} #&3"^@@"
-@end example
-
-@noindent
-These results make sense, because the binary code for @samp{C-g} is
-111 and @samp{C-@@} is the character with code 0.
-
- If the length is not a multiple of 8, the printed representation
-shows extra elements, but these extras really make no difference. For
-instance, in the next example, the two bool-vectors are equal, because
-only the first 3 bits are used:
-
-@example
-(equal #&3"\377" #&3"\007")
- @result{} t
-@end example
-
-@node Hash Table Type
-@subsection Hash Table Type
-
- A hash table is a very fast kind of lookup table, somewhat like an
-alist in that it maps keys to corresponding values, but much faster.
-Hash tables have no read syntax, and print using hash notation.
-@xref{Hash Tables}, for functions that operate on hash tables.
-
-@example
-(make-hash-table)
- @result{} #<hash-table 'eql nil 0/65 0x83af980>
-@end example
-
-@node Function Type
-@subsection Function Type
-
- Lisp functions are executable code, just like functions in other
-programming languages. In Lisp, unlike most languages, functions are
-also Lisp objects. A non-compiled function in Lisp is a lambda
-expression: that is, a list whose first element is the symbol
-@code{lambda} (@pxref{Lambda Expressions}).
-
- In most programming languages, it is impossible to have a function
-without a name. In Lisp, a function has no intrinsic name. A lambda
-expression can be called as a function even though it has no name; to
-emphasize this, we also call it an @dfn{anonymous function}
-(@pxref{Anonymous Functions}). A named function in Lisp is just a
-symbol with a valid function in its function cell (@pxref{Defining
-Functions}).
-
- Most of the time, functions are called when their names are written in
-Lisp expressions in Lisp programs. However, you can construct or obtain
-a function object at run time and then call it with the primitive
-functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
-
-@node Macro Type
-@subsection Macro Type
-
- A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
-language. It is represented as an object much like a function, but with
-different argument-passing semantics. A Lisp macro has the form of a
-list whose first element is the symbol @code{macro} and whose @sc{cdr}
-is a Lisp function object, including the @code{lambda} symbol.
-
- Lisp macro objects are usually defined with the built-in
-@code{defmacro} function, but any list that begins with @code{macro} is
-a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
-of how to write a macro.
-
- @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
-Macros}) are entirely different things. When we use the word ``macro''
-without qualification, we mean a Lisp macro, not a keyboard macro.
-
-@node Primitive Function Type
-@subsection Primitive Function Type
-@cindex special forms
-
- A @dfn{primitive function} is a function callable from Lisp but
-written in the C programming language. Primitive functions are also
-called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
-derived from ``subroutine.'') Most primitive functions evaluate all
-their arguments when they are called. A primitive function that does
-not evaluate all its arguments is called a @dfn{special form}
-(@pxref{Special Forms}).@refill
-
- It does not matter to the caller of a function whether the function is
-primitive. However, this does matter if you try to redefine a primitive
-with a function written in Lisp. The reason is that the primitive
-function may be called directly from C code. Calls to the redefined
-function from Lisp will use the new definition, but calls from C code
-may still use the built-in definition. Therefore, @strong{we discourage
-redefinition of primitive functions}.
-
- The term @dfn{function} refers to all Emacs functions, whether written
-in Lisp or C. @xref{Function Type}, for information about the
-functions written in Lisp.
-
- Primitive functions have no read syntax and print in hash notation
-with the name of the subroutine.
-
-@example
-@group
-(symbol-function 'car) ; @r{Access the function cell}
- ; @r{of the symbol.}
- @result{} #<subr car>
-(subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
- @result{} t ; @r{Yes.}
-@end group
-@end example
-
-@node Byte-Code Type
-@subsection Byte-Code Function Type
-
-The byte compiler produces @dfn{byte-code function objects}.
-Internally, a byte-code function object is much like a vector; however,
-the evaluator handles this data type specially when it appears as a
-function to be called. @xref{Byte Compilation}, for information about
-the byte compiler.
-
-The printed representation and read syntax for a byte-code function
-object is like that for a vector, with an additional @samp{#} before the
-opening @samp{[}.
-
-@node Autoload Type
-@subsection Autoload Type
-
- An @dfn{autoload object} is a list whose first element is the symbol
-@code{autoload}. It is stored as the function definition of a symbol,
-where it serves as a placeholder for the real definition. The autoload
-object says that the real definition is found in a file of Lisp code
-that should be loaded when necessary. It contains the name of the file,
-plus some other information about the real definition.
-
- After the file has been loaded, the symbol should have a new function
-definition that is not an autoload object. The new definition is then
-called as if it had been there to begin with. From the user's point of
-view, the function call works as expected, using the function definition
-in the loaded file.
-
- An autoload object is usually created with the function
-@code{autoload}, which stores the object in the function cell of a
-symbol. @xref{Autoload}, for more details.
-
-@node Editing Types
-@section Editing Types
-@cindex editing types
-
- The types in the previous section are used for general programming
-purposes, and most of them are common to most Lisp dialects. Emacs Lisp
-provides several additional data types for purposes connected with
-editing.
-
-@menu
-* Buffer Type:: The basic object of editing.
-* Marker Type:: A position in a buffer.
-* Window Type:: Buffers are displayed in windows.
-* 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.
-@end menu
-
-@node Buffer Type
-@subsection Buffer Type
-
- A @dfn{buffer} is an object that holds text that can be edited
-(@pxref{Buffers}). Most buffers hold the contents of a disk file
-(@pxref{Files}) so they can be edited, but some are used for other
-purposes. Most buffers are also meant to be seen by the user, and
-therefore displayed, at some time, in a window (@pxref{Windows}). But a
-buffer need not be displayed in any window.
-
- The contents of a buffer are much like a string, but buffers are not
-used like strings in Emacs Lisp, and the available operations are
-different. For example, you can insert text efficiently into an
-existing buffer, altering the buffer's contents, whereas ``inserting''
-text into a string requires concatenating substrings, and the result is
-an entirely new string object.
-
- Each buffer has a designated position called @dfn{point}
-(@pxref{Positions}). At any time, one buffer is the @dfn{current
-buffer}. Most editing commands act on the contents of the current
-buffer in the neighborhood of point. Many of the standard Emacs
-functions manipulate or test the characters in the current buffer; a
-whole chapter in this manual is devoted to describing these functions
-(@pxref{Text}).
-
- Several other data structures are associated with each buffer:
-
-@itemize @bullet
-@item
-a local syntax table (@pxref{Syntax Tables});
-
-@item
-a local keymap (@pxref{Keymaps}); and,
-
-@item
-a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
-
-@item
-overlays (@pxref{Overlays}).
-
-@item
-text properties for the text in the buffer (@pxref{Text Properties}).
-@end itemize
-
-@noindent
-The local keymap and variable list contain entries that individually
-override global bindings or values. These are used to customize the
-behavior of programs in different buffers, without actually changing the
-programs.
-
- A buffer may be @dfn{indirect}, which means it shares the text
-of another buffer, but presents it differently. @xref{Indirect Buffers}.
-
- Buffers have no read syntax. They print in hash notation, showing the
-buffer name.
-
-@example
-@group
-(current-buffer)
- @result{} #<buffer objects.texi>
-@end group
-@end example
-
-@node Marker Type
-@subsection Marker Type
-
- A @dfn{marker} denotes a position in a specific buffer. Markers
-therefore have two components: one for the buffer, and one for the
-position. Changes in the buffer's text automatically relocate the
-position value as necessary to ensure that the marker always points
-between the same two characters in the buffer.
-
- Markers have no read syntax. They print in hash notation, giving the
-current character position and the name of the buffer.
-
-@example
-@group
-(point-marker)
- @result{} #<marker at 10779 in objects.texi>
-@end group
-@end example
-
-@xref{Markers}, for information on how to test, create, copy, and move
-markers.
-
-@node Window Type
-@subsection Window Type
-
- A @dfn{window} describes the portion of the terminal screen that Emacs
-uses to display a buffer. Every window has one associated buffer, whose
-contents appear in the window. By contrast, a given buffer may appear
-in one window, no window, or several windows.
-
- Though many windows may exist simultaneously, at any time one window
-is designated the @dfn{selected window}. This is the window where the
-cursor is (usually) displayed when Emacs is ready for a command. The
-selected window usually displays the current buffer, but this is not
-necessarily the case.
-
- Windows are grouped on the screen into frames; each window belongs to
-one and only one frame. @xref{Frame Type}.
-
- Windows have no read syntax. They print in hash notation, giving the
-window number and the name of the buffer being displayed. The window
-numbers exist to identify windows uniquely, since the buffer displayed
-in any given window can change frequently.
-
-@example
-@group
-(selected-window)
- @result{} #<window 1 on objects.texi>
-@end group
-@end example
-
- @xref{Windows}, for a description of the functions that work on windows.
-
-@node Frame Type
-@subsection Frame Type
-
- A @dfn{frame} is a screen area that contains one or more Emacs
-windows; we also use the term ``frame'' to refer to the Lisp object
-that Emacs uses to refer to the screen area.
-
- Frames have no read syntax. They print in hash notation, giving the
-frame's title, plus its address in core (useful to identify the frame
-uniquely).
-
-@example
-@group
-(selected-frame)
- @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
-@end group
-@end example
-
- @xref{Frames}, for a description of the functions that work on frames.
-
-@node Window Configuration Type
-@subsection Window Configuration Type
-@cindex window layout in a frame
-
- A @dfn{window configuration} stores information about the positions,
-sizes, and contents of the windows in a frame, so you can recreate the
-same arrangement of windows later.
-
- Window configurations do not have a read syntax; their print syntax
-looks like @samp{#<window-configuration>}. @xref{Window
-Configurations}, for a description of several functions related to
-window configurations.
-
-@node Frame Configuration Type
-@subsection Frame Configuration Type
-@cindex screen layout
-@cindex window layout, all frames
-
- A @dfn{frame configuration} stores information about the positions,
-sizes, and contents of the windows in all frames. It is actually
-a list whose @sc{car} is @code{frame-configuration} and whose
-@sc{cdr} is an alist. Each alist element describes one frame,
-which appears as the @sc{car} of that element.
-
- @xref{Frame Configurations}, for a description of several functions
-related to frame configurations.
-
-@node Process Type
-@subsection Process Type
-
- The word @dfn{process} usually means a running program. Emacs itself
-runs in a process of this sort. However, in Emacs Lisp, a process is a
-Lisp object that designates a subprocess created by the Emacs process.
-Programs such as shells, GDB, ftp, and compilers, running in
-subprocesses of Emacs, extend the capabilities of Emacs.
-
- An Emacs subprocess takes textual input from Emacs and returns textual
-output to Emacs for further manipulation. Emacs can also send signals
-to the subprocess.
-
- Process objects have no read syntax. They print in hash notation,
-giving the name of the process:
-
-@example
-@group
-(process-list)
- @result{} (#<process shell>)
-@end group
-@end example
-
-@xref{Processes}, for information about functions that create, delete,
-return information about, send input or signals to, and receive output
-from processes.
-
-@node Stream Type
-@subsection Stream Type
-
- A @dfn{stream} is an object that can be used as a source or sink for
-characters---either to supply characters for input or to accept them as
-output. Many different types can be used this way: markers, buffers,
-strings, and functions. Most often, input streams (character sources)
-obtain characters from the keyboard, a buffer, or a file, and output
-streams (character sinks) send characters to a buffer, such as a
-@file{*Help*} buffer, or to the echo area.
-
- The object @code{nil}, in addition to its other meanings, may be used
-as a stream. It stands for the value of the variable
-@code{standard-input} or @code{standard-output}. Also, the object
-@code{t} as a stream specifies input using the minibuffer
-(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
-Area}).
-
- Streams have no special printed representation or read syntax, and
-print as whatever primitive type they are.
-
- @xref{Read and Print}, for a description of functions
-related to streams, including parsing and printing functions.
-
-@node Keymap Type
-@subsection Keymap Type
-
- A @dfn{keymap} maps keys typed by the user to commands. This mapping
-controls how the user's command input is executed. A keymap is actually
-a list whose @sc{car} is the symbol @code{keymap}.
-
- @xref{Keymaps}, for information about creating keymaps, handling prefix
-keys, local as well as global keymaps, and changing key bindings.
-
-@node Overlay Type
-@subsection Overlay Type
-
- An @dfn{overlay} specifies properties that apply to a part of a
-buffer. Each overlay applies to a specified range of the buffer, and
-contains a property list (a list whose elements are alternating property
-names and values). Overlay properties are used to present parts of the
-buffer temporarily in a different display style. Overlays have no read
-syntax, and print in hash notation, giving the buffer name and range of
-positions.
-
- @xref{Overlays}, for how to create and use overlays.
-
-@node Circular Objects
-@section Read Syntax for Circular Objects
-@cindex circular structure, read syntax
-@cindex shared structure, read syntax
-@cindex @samp{#@var{n}=} read syntax
-@cindex @samp{#@var{n}#} read syntax
-
- To represent shared or circular structures within a complex of Lisp
-objects, you can use the reader constructs @samp{#@var{n}=} and
-@samp{#@var{n}#}.
-
- Use @code{#@var{n}=} before an object to label it for later reference;
-subsequently, you can use @code{#@var{n}#} to refer the same object in
-another place. Here, @var{n} is some integer. For example, here is how
-to make a list in which the first element recurs as the third element:
-
-@example
-(#1=(a) b #1#)
-@end example
-
-@noindent
-This differs from ordinary syntax such as this
-
-@example
-((a) b (a))
-@end example
-
-@noindent
-which would result in a list whose first and third elements
-look alike but are not the same Lisp object. This shows the difference:
-
-@example
-(prog1 nil
- (setq x '(#1=(a) b #1#)))
-(eq (nth 0 x) (nth 2 x))
- @result{} t
-(setq x '((a) b (a)))
-(eq (nth 0 x) (nth 2 x))
- @result{} nil
-@end example
-
- You can also use the same syntax to make a circular structure, which
-appears as an ``element'' within itself. Here is an example:
-
-@example
-#1=(a #1#)
-@end example
-
-@noindent
-This makes a list whose second element is the list itself.
-Here's how you can see that it really works:
-
-@example
-(prog1 nil
- (setq x '#1=(a #1#)))
-(eq x (cadr x))
- @result{} t
-@end example
-
- The Lisp printer can produce this syntax to record circular and shared
-structure in a Lisp object, if you bind the variable @code{print-circle}
-to a non-@code{nil} value. @xref{Output Variables}.
-
-@node Type Predicates
-@section Type Predicates
-@cindex type checking
-@kindex wrong-type-argument
-
- The Emacs Lisp interpreter itself does not perform type checking on
-the actual arguments passed to functions when they are called. It could
-not do so, since function arguments in Lisp do not have declared data
-types, as they do in other programming languages. It is therefore up to
-the individual function to test whether each actual argument belongs to
-a type that the function can use.
-
- All built-in functions do check the types of their actual arguments
-when appropriate, and signal a @code{wrong-type-argument} error if an
-argument is of the wrong type. For example, here is what happens if you
-pass an argument to @code{+} that it cannot handle:
-
-@example
-@group
-(+ 2 'a)
- @error{} Wrong type argument: number-or-marker-p, a
-@end group
-@end example
-
-@cindex type predicates
-@cindex testing types
- If you want your program to handle different types differently, you
-must do explicit type checking. The most common way to check the type
-of an object is to call a @dfn{type predicate} function. Emacs has a
-type predicate for each type, as well as some predicates for
-combinations of types.
-
- A type predicate function takes one argument; it returns @code{t} if
-the argument belongs to the appropriate type, and @code{nil} otherwise.
-Following a general Lisp convention for predicate functions, most type
-predicates' names end with @samp{p}.
-
- Here is an example which uses the predicates @code{listp} to check for
-a list and @code{symbolp} to check for a symbol.
-
-@example
-(defun add-on (x)
- (cond ((symbolp x)
- ;; If X is a symbol, put it on LIST.
- (setq list (cons x list)))
- ((listp x)
- ;; If X is a list, add its elements to LIST.
- (setq list (append x list)))
- (t
- ;; We handle only symbols and lists.
- (error "Invalid argument %s in add-on" x))))
-@end example
-
- Here is a table of predefined type predicates, in alphabetical order,
-with references to further information.
-
-@table @code
-@item atom
-@xref{List-related Predicates, atom}.
-
-@item arrayp
-@xref{Array Functions, arrayp}.
-
-@item bool-vector-p
-@xref{Bool-Vectors, bool-vector-p}.
-
-@item bufferp
-@xref{Buffer Basics, bufferp}.
-
-@item byte-code-function-p
-@xref{Byte-Code Type, byte-code-function-p}.
-
-@item case-table-p
-@xref{Case Tables, case-table-p}.
-
-@item char-or-string-p
-@xref{Predicates for Strings, char-or-string-p}.
-
-@item char-table-p
-@xref{Char-Tables, char-table-p}.
-
-@item commandp
-@xref{Interactive Call, commandp}.
-
-@item consp
-@xref{List-related Predicates, consp}.
-
-@item display-table-p
-@xref{Display Tables, display-table-p}.
-
-@item floatp
-@xref{Predicates on Numbers, floatp}.
-
-@item frame-configuration-p
-@xref{Frame Configurations, frame-configuration-p}.
-
-@item frame-live-p
-@xref{Deleting Frames, frame-live-p}.
-
-@item framep
-@xref{Frames, framep}.
-
-@item functionp
-@xref{Functions, functionp}.
-
-@item hash-table-p
-@xref{Other Hash, hash-table-p}.
-
-@item integer-or-marker-p
-@xref{Predicates on Markers, integer-or-marker-p}.
-
-@item integerp
-@xref{Predicates on Numbers, integerp}.
-
-@item keymapp
-@xref{Creating Keymaps, keymapp}.
-
-@item keywordp
-@xref{Constant Variables}.
-
-@item listp
-@xref{List-related Predicates, listp}.
-
-@item markerp
-@xref{Predicates on Markers, markerp}.
-
-@item wholenump
-@xref{Predicates on Numbers, wholenump}.
-
-@item nlistp
-@xref{List-related Predicates, nlistp}.
-
-@item numberp
-@xref{Predicates on Numbers, numberp}.
-
-@item number-or-marker-p
-@xref{Predicates on Markers, number-or-marker-p}.
-
-@item overlayp
-@xref{Overlays, overlayp}.
-
-@item processp
-@xref{Processes, processp}.
-
-@item sequencep
-@xref{Sequence Functions, sequencep}.
-
-@item stringp
-@xref{Predicates for Strings, stringp}.
-
-@item subrp
-@xref{Function Cells, subrp}.
-
-@item symbolp
-@xref{Symbols, symbolp}.
-
-@item syntax-table-p
-@xref{Syntax Tables, syntax-table-p}.
-
-@item user-variable-p
-@xref{Defining Variables, user-variable-p}.
-
-@item vectorp
-@xref{Vectors, vectorp}.
-
-@item window-configuration-p
-@xref{Window Configurations, window-configuration-p}.
-
-@item window-live-p
-@xref{Deleting Windows, window-live-p}.
-
-@item windowp
-@xref{Basic Windows, windowp}.
-
-@item booleanp
-@xref{nil and t, booleanp}.
-
-@item string-or-null-p
-@xref{Predicates for Strings, string-or-null-p}.
-@end table
-
- The most general way to check the type of an object is to call the
-function @code{type-of}. Recall that each object belongs to one and
-only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
-Data Types}). But @code{type-of} knows nothing about non-primitive
-types. In most cases, it is more convenient to use type predicates than
-@code{type-of}.
-
-@defun type-of object
-This function returns a symbol naming the primitive type of
-@var{object}. The value is one of the symbols @code{symbol},
-@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
-@code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
-@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
-@code{buffer}, @code{frame}, @code{process}, or
-@code{window-configuration}.
-
-@example
-(type-of 1)
- @result{} integer
-@group
-(type-of 'nil)
- @result{} symbol
-(type-of '()) ; @r{@code{()} is @code{nil}.}
- @result{} symbol
-(type-of '(x))
- @result{} cons
-@end group
-@end example
-@end defun
-
-@node Equality Predicates
-@section Equality Predicates
-@cindex equality
-
- Here we describe two functions that test for equality between any two
-objects. Other functions test equality between objects of specific
-types, e.g., strings. For these predicates, see the appropriate chapter
-describing the data type.
-
-@defun eq object1 object2
-This function returns @code{t} if @var{object1} and @var{object2} are
-the same object, @code{nil} otherwise.
-
-@code{eq} returns @code{t} if @var{object1} and @var{object2} are
-integers with the same value. Also, since symbol names are normally
-unique, if the arguments are symbols with the same name, they are
-@code{eq}. For other types (e.g., lists, vectors, strings), two
-arguments with the same contents or elements are not necessarily
-@code{eq} to each other: they are @code{eq} only if they are the same
-object, meaning that a change in the contents of one will be reflected
-by the same change in the contents of the other.
-
-@example
-@group
-(eq 'foo 'foo)
- @result{} t
-@end group
-
-@group
-(eq 456 456)
- @result{} t
-@end group
-
-@group
-(eq "asdf" "asdf")
- @result{} nil
-@end group
-
-@group
-(eq '(1 (2 (3))) '(1 (2 (3))))
- @result{} nil
-@end group
-
-@group
-(setq foo '(1 (2 (3))))
- @result{} (1 (2 (3)))
-(eq foo foo)
- @result{} t
-(eq foo '(1 (2 (3))))
- @result{} nil
-@end group
-
-@group
-(eq [(1 2) 3] [(1 2) 3])
- @result{} nil
-@end group
-
-@group
-(eq (point-marker) (point-marker))
- @result{} nil
-@end group
-@end example
-
-The @code{make-symbol} function returns an uninterned symbol, distinct
-from the symbol that is used if you write the name in a Lisp expression.
-Distinct symbols with the same name are not @code{eq}. @xref{Creating
-Symbols}.
-
-@example
-@group
-(eq (make-symbol "foo") 'foo)
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun equal object1 object2
-This function returns @code{t} if @var{object1} and @var{object2} have
-equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
-arguments are the same object, @code{equal} looks inside nonidentical
-arguments to see if their elements or contents are the same. So, if two
-objects are @code{eq}, they are @code{equal}, but the converse is not
-always true.
-
-@example
-@group
-(equal 'foo 'foo)
- @result{} t
-@end group
-
-@group
-(equal 456 456)
- @result{} t
-@end group
-
-@group
-(equal "asdf" "asdf")
- @result{} t
-@end group
-@group
-(eq "asdf" "asdf")
- @result{} nil
-@end group
-
-@group
-(equal '(1 (2 (3))) '(1 (2 (3))))
- @result{} t
-@end group
-@group
-(eq '(1 (2 (3))) '(1 (2 (3))))
- @result{} nil
-@end group
-
-@group
-(equal [(1 2) 3] [(1 2) 3])
- @result{} t
-@end group
-@group
-(eq [(1 2) 3] [(1 2) 3])
- @result{} nil
-@end group
-
-@group
-(equal (point-marker) (point-marker))
- @result{} t
-@end group
-
-@group
-(eq (point-marker) (point-marker))
- @result{} nil
-@end group
-@end example
-
-Comparison of strings is case-sensitive, but does not take account of
-text properties---it compares only the characters in the strings. For
-technical reasons, a unibyte string and a multibyte string are
-@code{equal} if and only if they contain the same sequence of
-character codes and all these codes are either in the range 0 through
-127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
-(@pxref{Text Representations}).
-
-@example
-@group
-(equal "asdf" "ASDF")
- @result{} nil
-@end group
-@end example
-
-However, two distinct buffers are never considered @code{equal}, even if
-their textual contents are the same.
-@end defun
-
- The test for equality is implemented recursively; for example, given
-two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
-returns @code{t} if and only if both the expressions below return
-@code{t}:
-
-@example
-(equal (car @var{x}) (car @var{y}))
-(equal (cdr @var{x}) (cdr @var{y}))
-@end example
-
-Because of this recursive method, circular lists may therefore cause
-infinite recursion (leading to an error).
-
-@ignore
- arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/os
-@node System Interface, Antinews, Display, Top
-@chapter Operating System Interface
-
- This chapter is about starting and getting out of Emacs, access to
-values in the operating system environment, and terminal input, output,
-and flow control.
-
- @xref{Building Emacs}, for related information. See also
-@ref{Display}, for additional operating system status information
-pertaining to the terminal and the screen.
-
-@menu
-* Starting Up:: Customizing Emacs startup 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 calendrical data, and 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.
-@end menu
-
-@node Starting Up
-@section Starting Up Emacs
-
- This section describes what Emacs does when it is started, and how you
-can customize these actions.
-
-@menu
-* Startup Summary:: Sequence of actions Emacs performs at startup.
-* 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.
-@end menu
-
-@node Startup Summary
-@subsection Summary: Sequence of Actions at Startup
-@cindex initialization of Emacs
-@cindex startup of Emacs
-@cindex @file{startup.el}
-
- The order of operations performed (in @file{startup.el}) by Emacs when
-it is started up is as follows:
-
-@enumerate
-@item
-It adds subdirectories to @code{load-path}, by running the file named
-@file{subdirs.el} in each directory in the list. Normally this file
-adds the directory's subdirectories to the list, and these will be
-scanned in their turn. The files @file{subdirs.el} are normally
-generated automatically by Emacs installation.
-
-@item
-It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
-
-@item
-It loads the initialization library for the window system, if you are
-using a window system. This library's name is
-@file{term/@var{windowsystem}-win.el}.
-
-@item
-It processes the initial options. (Some of them are handled
-even earlier than this.)
-
-@item
-It initializes the window frame and faces, if appropriate.
-
-@item
-It runs the normal hook @code{before-init-hook}.
-
-@item
-It loads the library @file{site-start} (if any), unless the option
-@samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
-name is usually @file{site-start.el}.
-@cindex @file{site-start.el}
-
-@item
-It loads your init file (usually @file{~/.emacs}), unless the option
-@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
-specified on the command line. The @samp{-u} option can specify
-another user whose home directory should be used instead of @file{~}.
-
-@item
-It loads the library @file{default} (if any), unless
-@code{inhibit-default-init} is non-@code{nil}. (This is not done in
-@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
-command line.) The library's file name is usually @file{default.el}.
-@cindex @file{default.el}
-
-@item
-It runs the normal hook @code{after-init-hook}.
-
-@item
-It sets the major mode according to @code{initial-major-mode}, provided
-the buffer @samp{*scratch*} is still current and still in Fundamental
-mode.
-
-@item
-It loads the terminal-specific Lisp file, if any, except when in batch
-mode or using a window system.
-
-@item
-It displays the initial echo area message, unless you have suppressed
-that with @code{inhibit-startup-echo-area-message}.
-
-@item
-It processes the action arguments from the command line.
-
-@item
-It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
-
-@item
-It calls @code{frame-notice-user-settings}, which modifies the
-parameters of the selected frame according to whatever the init files
-specify.
-
-@item
-It runs @code{window-setup-hook}. @xref{Window Systems}.
-
-@item
-It displays copyleft, nonwarranty, and basic use information, provided
-the value of @code{inhibit-startup-message} is @code{nil}, you didn't
-specify @samp{--no-splash} or @samp{-Q}.
-@end enumerate
-
-@defopt inhibit-startup-message
-This variable inhibits the initial startup messages (the nonwarranty,
-etc.). If it is non-@code{nil}, then the messages are not printed.
-
-This variable exists so you can set it in your personal init file, once
-you are familiar with the contents of the startup message. Do not set
-this variable in the init file of a new user, or in a way that affects
-more than one user, because that would prevent new users from receiving
-the information they are supposed to see.
-@end defopt
-
-@defopt inhibit-startup-echo-area-message
-This variable controls the display of the startup echo area message.
-You can suppress the startup echo area message by adding text with this
-form to your init file:
-
-@example
-(setq inhibit-startup-echo-area-message
- "@var{your-login-name}")
-@end example
-
-Emacs explicitly checks for an expression as shown above in your init
-file; your login name must appear in the expression as a Lisp string
-constant. Other methods of setting
-@code{inhibit-startup-echo-area-message} to the same value do not
-inhibit the startup message.
-
-This way, you can easily inhibit the message for yourself if you wish,
-but thoughtless copying of your init file will not inhibit the message
-for someone else.
-@end defopt
-
-@node Init File
-@subsection The Init File, @file{.emacs}
-@cindex init file
-@cindex @file{.emacs}
-
- When you start Emacs, it normally attempts to load your @dfn{init
-file}, a file in your home directory. Its normal name is
-@file{.emacs}, but you can also call it @file{.emacs.el}.
-Alternatively, you can use a file named @file{init.el} in a
-subdirectory @file{.emacs.d}. Whichever place you use, you can also
-compile the file (@pxref{Byte Compilation}); then the actual file
-loaded will be @file{.emacs.elc} or @file{init.elc}.
-
- The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
-control whether and where to find the init file; @samp{-q} (and the
-stronger @samp{-Q}) says not to load an init file, while @samp{-u
-@var{user}} says to load @var{user}'s init file instead of yours.
-@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
-option is specified, Emacs uses the @code{LOGNAME} environment
-variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
-systems) variable, to find your home directory and thus your init
-file; this way, even if you have su'd, Emacs still loads your own init
-file. If those environment variables are absent, though, Emacs uses
-your user-id to find your home directory.
-
-@cindex default init file
- A site may have a @dfn{default init file}, which is the library
-named @file{default.el}. Emacs finds the @file{default.el} file
-through the standard search path for libraries (@pxref{How Programs Do
-Loading}). The Emacs distribution does not come with this file; sites
-may provide one for local customizations. If the default init file
-exists, it is loaded whenever you start Emacs, except in batch mode or
-if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
-file, if any, is loaded first; if it sets @code{inhibit-default-init}
-to a non-@code{nil} value, then Emacs does not subsequently load the
-@file{default.el} file.
-
- Another file for site-customization is @file{site-start.el}. Emacs
-loads this @emph{before} the user's init file. You can inhibit the
-loading of this file with the option @samp{--no-site-file}.
-
-@defvar site-run-file
-This variable specifies the site-customization file to load before the
-user's init file. Its normal value is @code{"site-start"}. The only
-way you can change it with real effect is to do so before dumping
-Emacs.
-@end defvar
-
- @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
-examples of how to make various commonly desired customizations in your
-@file{.emacs} file.
-
-@defopt inhibit-default-init
-This variable prevents Emacs from loading the default initialization
-library file for your session of Emacs. If its value is non-@code{nil},
-then the default library is not loaded. The default value is
-@code{nil}.
-@end defopt
-
-@defvar before-init-hook
-This normal hook is run, once, just before loading all the init files
-(the user's init file, @file{default.el}, and/or @file{site-start.el}).
-(The only way to change it with real effect is before dumping Emacs.)
-@end defvar
-
-@defvar after-init-hook
-This normal hook is run, once, just after loading all the init files
-(the user's init file, @file{default.el}, and/or @file{site-start.el}),
-before loading the terminal-specific library and processing the
-command-line action arguments.
-@end defvar
-
-@defvar emacs-startup-hook
-This normal hook is run, once, just after handling the command line
-arguments, just before @code{term-setup-hook}.
-@end defvar
-
-@defvar user-init-file
-This variable holds the absolute file name of the user's init file. If the
-actual init file loaded is a compiled file, such as @file{.emacs.elc},
-the value refers to the corresponding source file.
-@end defvar
-
-@defvar user-emacs-directory
-This variable holds the name of the @file{.emacs.d} directory. It is
-ordinarily @file{~/.emacs.d}, but differs on some platforms.
-@end defvar
-
-@node Terminal-Specific
-@subsection Terminal-Specific Initialization
-@cindex terminal-specific initialization
-
- Each terminal type can have its own Lisp library that Emacs loads when
-run on that type of terminal. The library's name is constructed by
-concatenating the value of the variable @code{term-file-prefix} and the
-terminal type (specified by the environment variable @code{TERM}).
-Normally, @code{term-file-prefix} has the value
-@code{"term/"}; changing this is not recommended. Emacs finds the file
-in the normal manner, by searching the @code{load-path} directories, and
-trying the @samp{.elc} and @samp{.el} suffixes.
-
-@cindex Termcap
- The usual function of a terminal-specific library is to enable
-special keys to send sequences that Emacs can recognize. It may also
-need to set or add to @code{function-key-map} if the Termcap or
-Terminfo entry does not specify all the terminal's function keys.
-@xref{Terminal Input}.
-
- When the name of the terminal type contains a hyphen, and no library
-is found whose name is identical to the terminal's name, Emacs strips
-from the terminal's name the last hyphen and everything that follows
-it, and tries again. This process is repeated until Emacs finds a
-matching library or until there are no more hyphens in the name (the
-latter means the terminal doesn't have any library specific to it).
-Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
-libraries, Emacs will try the same library @file{term/aaa.el} for
-terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
-library can evaluate @code{(getenv "TERM")} to find the full name of
-the terminal type.@refill
-
- Your init file can prevent the loading of the
-terminal-specific library by setting the variable
-@code{term-file-prefix} to @code{nil}. This feature is useful when
-experimenting with your own peculiar customizations.
-
- You can also arrange to override some of the actions of the
-terminal-specific library by setting the variable
-@code{term-setup-hook}. This is a normal hook which Emacs runs using
-@code{run-hooks} at the end of Emacs initialization, after loading both
-your init file and any terminal-specific libraries. You can
-use this variable to define initializations for terminals that do not
-have their own libraries. @xref{Hooks}.
-
-@defvar term-file-prefix
-@cindex @code{TERM} environment variable
-If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
-a terminal-specific initialization file as follows:
-
-@example
-(load (concat term-file-prefix (getenv "TERM")))
-@end example
-
-@noindent
-You may set the @code{term-file-prefix} variable to @code{nil} in your
-init file if you do not wish to load the
-terminal-initialization file. To do this, put the following in
-your init file: @code{(setq term-file-prefix nil)}.
-
-On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
-uses @samp{internal} as the terminal type.
-@end defvar
-
-@defvar term-setup-hook
-This variable is a normal hook that Emacs runs after loading your
-init file, the default initialization file (if any) and the
-terminal-specific Lisp file.
-
-You can use @code{term-setup-hook} to override the definitions made by a
-terminal-specific file.
-@end defvar
-
- See @code{window-setup-hook} in @ref{Window Systems}, for a related
-feature.
-
-@node Command-Line Arguments
-@subsection Command-Line Arguments
-@cindex command-line arguments
-
- You can use command-line arguments to request various actions when you
-start Emacs. Since you do not need to start Emacs more than once per
-day, and will often leave your Emacs session running longer than that,
-command-line arguments are hardly ever used. As a practical matter, it
-is best to avoid making the habit of using them, since this habit would
-encourage you to kill and restart Emacs unnecessarily often. These
-options exist for two reasons: to be compatible with other editors (for
-invocation by other programs) and to enable shell scripts to run
-specific Lisp programs.
-
- This section describes how Emacs processes command-line arguments,
-and how you can customize them.
-
-@ignore
- (Note that some other editors require you to start afresh each time
-you want to edit a file. With this kind of editor, you will probably
-specify the file as a command-line argument. The recommended way to
-use GNU Emacs is to start it only once, just after you log in, and do
-all your editing in the same Emacs process. Each time you want to edit
-a different file, you visit it with the existing Emacs, which eventually
-comes to have many files in it ready for editing. Usually you do not
-kill the Emacs until you are about to log out.)
-@end ignore
-
-@defun command-line
-This function parses the command line that Emacs was called with,
-processes it, loads the user's init file and displays the
-startup messages.
-@end defun
-
-@defvar command-line-processed
-The value of this variable is @code{t} once the command line has been
-processed.
-
-If you redump Emacs by calling @code{dump-emacs}, you may wish to set
-this variable to @code{nil} first in order to cause the new dumped Emacs
-to process its new command-line arguments.
-@end defvar
-
-@defvar command-switch-alist
-@cindex switches on command line
-@cindex options on command line
-@cindex command-line options
-The value of this variable is an alist of user-defined command-line
-options and associated handler functions. This variable exists so you
-can add elements to it.
-
-A @dfn{command-line option} is an argument on the command line, which
-has the form:
-
-@example
--@var{option}
-@end example
-
-The elements of the @code{command-switch-alist} look like this:
-
-@example
-(@var{option} . @var{handler-function})
-@end example
-
-The @sc{car}, @var{option}, is a string, the name of a command-line
-option (not including the initial hyphen). The @var{handler-function}
-is called to handle @var{option}, and receives the option name as its
-sole argument.
-
-In some cases, the option is followed in the command line by an
-argument. In these cases, the @var{handler-function} can find all the
-remaining command-line arguments in the variable
-@code{command-line-args-left}. (The entire list of command-line
-arguments is in @code{command-line-args}.)
-
-The command-line arguments are parsed by the @code{command-line-1}
-function in the @file{startup.el} file. See also @ref{Emacs
-Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
-GNU Emacs Manual}.
-@end defvar
-
-@defvar command-line-args
-The value of this variable is the list of command-line arguments passed
-to Emacs.
-@end defvar
-
-@defvar command-line-functions
-This variable's value is a list of functions for handling an
-unrecognized command-line argument. Each time the next argument to be
-processed has no special meaning, the functions in this list are called,
-in order of appearance, until one of them returns a non-@code{nil}
-value.
-
-These functions are called with no arguments. They can access the
-command-line argument under consideration through the variable
-@code{argi}, which is bound temporarily at this point. The remaining
-arguments (not including the current one) are in the variable
-@code{command-line-args-left}.
-
-When a function recognizes and processes the argument in @code{argi}, it
-should return a non-@code{nil} value to say it has dealt with that
-argument. If it has also dealt with some of the following arguments, it
-can indicate that by deleting them from @code{command-line-args-left}.
-
-If all of these functions return @code{nil}, then the argument is used
-as a file name to visit.
-@end defvar
-
-@node Getting Out
-@section Getting Out of Emacs
-@cindex exiting Emacs
-
- There are two ways to get out of Emacs: you can kill the Emacs job,
-which exits permanently, or you can suspend it, which permits you to
-reenter the Emacs process later. As a practical matter, you seldom kill
-Emacs---only when you are about to log out. Suspending is much more
-common.
-
-@menu
-* Killing Emacs:: Exiting Emacs irreversibly.
-* Suspending Emacs:: Exiting Emacs reversibly.
-@end menu
-
-@node Killing Emacs
-@comment node-name, next, previous, up
-@subsection Killing Emacs
-@cindex killing Emacs
-
- Killing Emacs means ending the execution of the Emacs process. The
-parent process normally resumes control. The low-level primitive for
-killing Emacs is @code{kill-emacs}.
-
-@defun kill-emacs &optional exit-data
-This function exits the Emacs process and kills it.
-
-If @var{exit-data} is an integer, then it is used as the exit status
-of the Emacs process. (This is useful primarily in batch operation; see
-@ref{Batch Mode}.)
-
-If @var{exit-data} is a string, its contents are stuffed into the
-terminal input buffer so that the shell (or whatever program next reads
-input) can read them.
-@end defun
-
- All the information in the Emacs process, aside from files that have
-been saved, is lost when the Emacs process is killed. Because killing
-Emacs inadvertently can lose a lot of work, Emacs queries for
-confirmation before actually terminating if you have buffers that need
-saving or subprocesses that are running. This is done in the function
-@code{save-buffers-kill-emacs}, the higher level function from which
-@code{kill-emacs} is usually called.
-
-@defvar kill-emacs-query-functions
-After asking the standard questions, @code{save-buffers-kill-emacs}
-calls the functions in the list @code{kill-emacs-query-functions}, in
-order of appearance, with no arguments. These functions can ask for
-additional confirmation from the user. If any of them returns
-@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
-does not run the remaining functions in this hook. Calling
-@code{kill-emacs} directly does not run this hook.
-@end defvar
-
-@defvar kill-emacs-hook
-This variable is a normal hook; once @code{save-buffers-kill-emacs} is
-finished with all file saving and confirmation, it calls
-@code{kill-emacs} which runs the functions in this hook.
-@code{kill-emacs} does not run this hook in batch mode.
-
-@code{kill-emacs} may be invoked directly (that is not via
-@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
-similar situations where interaction with the user is not possible.
-Thus, if your hook needs to interact with the user, put it on
-@code{kill-emacs-query-functions}; if it needs to run regardless of
-how Emacs is killed, put it on @code{kill-emacs-hook}.
-@end defvar
-
-@node Suspending Emacs
-@subsection Suspending Emacs
-@cindex suspending Emacs
-
- @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
-control to its superior process, which is usually the shell. This
-allows you to resume editing later in the same Emacs process, with the
-same buffers, the same kill ring, the same undo history, and so on. To
-resume Emacs, use the appropriate command in the parent shell---most
-likely @code{fg}.
-
- Some operating systems do not support suspension of jobs; on these
-systems, ``suspension'' actually creates a new shell temporarily as a
-subprocess of Emacs. Then you would exit the shell to return to Emacs.
-
- Suspension is not useful with window systems, because the Emacs job
-may not have a parent that can resume it again, and in any case you can
-give input to some other job such as a shell merely by moving to a
-different window. Therefore, suspending is not allowed when Emacs is using
-a window system (X, MS Windows, or Mac).
-
-@defun suspend-emacs &optional string
-This function stops Emacs and returns control to the superior process.
-If and when the superior process resumes Emacs, @code{suspend-emacs}
-returns @code{nil} to its caller in Lisp.
-
-If @var{string} is non-@code{nil}, its characters are sent to be read
-as terminal input by Emacs's superior shell. The characters in
-@var{string} are not echoed by the superior shell; only the results
-appear.
-
-Before suspending, @code{suspend-emacs} runs the normal hook
-@code{suspend-hook}.
-
-After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
-@code{suspend-resume-hook}. @xref{Hooks}.
-
-The next redisplay after resumption will redraw the entire screen,
-unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
-(@pxref{Refresh Screen}).
-
-In the following example, note that @samp{pwd} is not echoed after
-Emacs is suspended. But it is read and executed by the shell.
-
-@smallexample
-@group
-(suspend-emacs)
- @result{} nil
-@end group
-
-@group
-(add-hook 'suspend-hook
- (function (lambda ()
- (or (y-or-n-p
- "Really suspend? ")
- (error "Suspend canceled")))))
- @result{} (lambda nil
- (or (y-or-n-p "Really suspend? ")
- (error "Suspend canceled")))
-@end group
-@group
-(add-hook 'suspend-resume-hook
- (function (lambda () (message "Resumed!"))))
- @result{} (lambda nil (message "Resumed!"))
-@end group
-@group
-(suspend-emacs "pwd")
- @result{} nil
-@end group
-@group
----------- Buffer: Minibuffer ----------
-Really suspend? @kbd{y}
----------- Buffer: Minibuffer ----------
-@end group
-
-@group
----------- Parent Shell ----------
-lewis@@slug[23] % /user/lewis/manual
-lewis@@slug[24] % fg
-@end group
-
-@group
----------- Echo Area ----------
-Resumed!
-@end group
-@end smallexample
-@end defun
-
-@defvar suspend-hook
-This variable is a normal hook that Emacs runs before suspending.
-@end defvar
-
-@defvar suspend-resume-hook
-This variable is a normal hook that Emacs runs on resuming
-after a suspension.
-@end defvar
-
-@node System Environment
-@section Operating System Environment
-@cindex operating system environment
-
- Emacs provides access to variables in the operating system environment
-through various functions. These variables include the name of the
-system, the user's @acronym{UID}, and so on.
-
-@defvar system-configuration
-This variable holds the standard GNU configuration name for the
-hardware/software configuration of your system, as a string. The
-convenient way to test parts of this string is with
-@code{string-match}.
-@end defvar
-
-@cindex system type and name
-@defvar system-type
-The value of this variable is a symbol indicating the type of operating
-system Emacs is operating on. Here is a table of the possible values:
-
-@table @code
-@item alpha-vms
-VMS on the Alpha.
-
-@item aix-v3
-AIX.
-
-@item berkeley-unix
-Berkeley BSD.
-
-@item cygwin
-Cygwin.
-
-@item dgux
-Data General DGUX operating system.
-
-@item gnu
-the GNU system (using the GNU kernel, which consists of the HURD and Mach).
-
-@item gnu/linux
-A GNU/Linux system---that is, a variant GNU system, using the Linux
-kernel. (These systems are the ones people often call ``Linux,'' but
-actually Linux is just the kernel, not the whole system.)
-
-@item hpux
-Hewlett-Packard HPUX operating system.
-
-@item irix
-Silicon Graphics Irix system.
-
-@item ms-dos
-Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
-MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
-MS-Windows.
-
-@item next-mach
-NeXT Mach-based system.
-
-@item rtu
-Masscomp RTU, UCB universe.
-
-@item unisoft-unix
-UniSoft UniPlus.
-
-@item usg-unix-v
-AT&T System V.
-
-@item vax-vms
-VAX VMS.
-
-@item windows-nt
-Microsoft windows NT. The same executable supports Windows 9X, but the
-value of @code{system-type} is @code{windows-nt} in either case.
-
-@item xenix
-SCO Xenix 386.
-@end table
-
-We do not wish to add new symbols to make finer distinctions unless it
-is absolutely necessary! In fact, we hope to eliminate some of these
-alternatives in the future. We recommend using
-@code{system-configuration} to distinguish between different operating
-systems.
-@end defvar
-
-@defun system-name
-This function returns the name of the machine you are running on.
-@example
-(system-name)
- @result{} "www.gnu.org"
-@end example
-@end defun
-
- The symbol @code{system-name} is a variable as well as a function. In
-fact, the function returns whatever value the variable
-@code{system-name} currently holds. Thus, you can set the variable
-@code{system-name} in case Emacs is confused about the name of your
-system. The variable is also useful for constructing frame titles
-(@pxref{Frame Titles}).
-
-@defvar mail-host-address
-If this variable is non-@code{nil}, it is used instead of
-@code{system-name} for purposes of generating email addresses. For
-example, it is used when constructing the default value of
-@code{user-mail-address}. @xref{User Identification}. (Since this is
-done when Emacs starts up, the value actually used is the one saved when
-Emacs was dumped. @xref{Building Emacs}.)
-@end defvar
-
-@deffn Command getenv var
-@cindex environment variable access
-This function returns the value of the environment variable @var{var},
-as a string. @var{var} should be a string. If @var{var} is undefined
-in the environment, @code{getenv} returns @code{nil}. If returns
-@samp{""} if @var{var} is set but null. Within Emacs, the environment
-variable values are kept in the Lisp variable @code{process-environment}.
-
-@example
-@group
-(getenv "USER")
- @result{} "lewis"
-@end group
-
-@group
-lewis@@slug[10] % printenv
-PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
-USER=lewis
-@end group
-@group
-TERM=ibmapa16
-SHELL=/bin/csh
-HOME=/user/lewis
-@end group
-@end example
-@end deffn
-
-@c Emacs 19 feature
-@deffn Command setenv variable &optional value
-This command sets the value of the environment variable named
-@var{variable} to @var{value}. @var{variable} should be a string.
-Internally, Emacs Lisp can handle any string. However, normally
-@var{variable} should be a valid shell identifier, that is, a sequence
-of letters, digits and underscores, starting with a letter or
-underscore. Otherwise, errors may occur if subprocesses of Emacs try
-to access the value of @var{variable}. If @var{value} is omitted or
-@code{nil}, @code{setenv} removes @var{variable} from the environment.
-Otherwise, @var{value} should be a string.
-
-@code{setenv} works by modifying @code{process-environment}; binding
-that variable with @code{let} is also reasonable practice.
-
-@code{setenv} returns the new value of @var{variable}, or @code{nil}
-if it removed @var{variable} from the environment.
-@end deffn
-
-@defvar process-environment
-This variable is a list of strings, each describing one environment
-variable. The functions @code{getenv} and @code{setenv} work by means
-of this variable.
-
-@smallexample
-@group
-process-environment
-@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
- "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
- "USER=lewis"
-@end group
-@group
- "TERM=ibmapa16"
- "SHELL=/bin/csh"
- "HOME=/user/lewis")
-@end group
-@end smallexample
-
-If @code{process-environment} contains ``duplicate'' elements that
-specify the same environment variable, the first of these elements
-specifies the variable, and the other ``duplicates'' are ignored.
-@end defvar
-
-@defvar path-separator
-This variable holds a string which says which character separates
-directories in a search path (as found in an environment variable). Its
-value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
-and MS-Windows.
-@end defvar
-
-@defun parse-colon-path path
-This function takes a search path string such as would be the value of
-the @code{PATH} environment variable, and splits it at the separators,
-returning a list of directory names. @code{nil} in this list stands for
-``use the current directory.'' Although the function's name says
-``colon,'' it actually uses the value of @code{path-separator}.
-
-@example
-(parse-colon-path ":/foo:/bar")
- @result{} (nil "/foo/" "/bar/")
-@end example
-@end defun
-
-@defvar invocation-name
-This variable holds the program name under which Emacs was invoked. The
-value is a string, and does not include a directory name.
-@end defvar
-
-@defvar invocation-directory
-This variable holds the directory from which the Emacs executable was
-invoked, or perhaps @code{nil} if that directory cannot be determined.
-@end defvar
-
-@defvar installation-directory
-If non-@code{nil}, this is a directory within which to look for the
-@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
-when Emacs can't find those directories in their standard installed
-locations, but can find them in a directory related somehow to the one
-containing the Emacs executable.
-@end defvar
-
-@defun load-average &optional use-float
-This function returns the current 1-minute, 5-minute, and 15-minute load
-averages, in a list.
-
-By default, the values are integers that are 100 times the system load
-averages, which indicate the average number of processes trying to run.
-If @var{use-float} is non-@code{nil}, then they are returned
-as floating point numbers and without multiplying by 100.
-
-If it is impossible to obtain the load average, this function signals
-an error. On some platforms, access to load averages requires
-installing Emacs as setuid or setgid so that it can read kernel
-information, and that usually isn't advisable.
-
-If the 1-minute load average is available, but the 5- or 15-minute
-averages are not, this function returns a shortened list containing
-the available averages.
-
-@example
-@group
-(load-average)
- @result{} (169 48 36)
-@end group
-@group
-(load-average t)
- @result{} (1.69 0.48 0.36)
-@end group
-
-@group
-lewis@@rocky[5] % uptime
- 11:55am up 1 day, 19:37, 3 users,
- load average: 1.69, 0.48, 0.36
-@end group
-@end example
-@end defun
-
-@defun emacs-pid
-This function returns the process @acronym{ID} of the Emacs process,
-as an integer.
-@end defun
-
-@defvar tty-erase-char
-This variable holds the erase character that was selected
-in the system's terminal driver, before Emacs was started.
-The value is @code{nil} if Emacs is running under a window system.
-@end defvar
-
-@defun setprv privilege-name &optional setp getprv
-This function sets or resets a VMS privilege. (It does not exist on
-other systems.) The first argument is the privilege name, as a string.
-The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
-whether the privilege is to be turned on or off. Its default is
-@code{nil}. The function returns @code{t} if successful, @code{nil}
-otherwise.
-
-If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
-does not change the privilege, but returns @code{t} or @code{nil}
-indicating whether the privilege is currently enabled.
-@end defun
-
-@node User Identification
-@section User Identification
-@cindex user identification
-
-@defvar init-file-user
-This variable says which user's init files should be used by
-Emacs---or @code{nil} if none. @code{""} stands for the user who
-originally logged in. The value reflects command-line options such as
-@samp{-q} or @samp{-u @var{user}}.
-
-Lisp packages that load files of customizations, or any other sort of
-user profile, should obey this variable in deciding where to find it.
-They should load the profile of the user name found in this variable.
-If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
-option was used, then Lisp packages should not load any customization
-files or user profile.
-@end defvar
-
-@defvar user-mail-address
-This holds the nominal email address of the user who is using Emacs.
-Emacs normally sets this variable to a default value after reading your
-init files, but not if you have already set it. So you can set the
-variable to some other value in your init file if you do not
-want to use the default value.
-@end defvar
-
-@defun user-login-name &optional uid
-If you don't specify @var{uid}, this function returns the name under
-which the user is logged in. If the environment variable @code{LOGNAME}
-is set, that value is used. Otherwise, if the environment variable
-@code{USER} is set, that value is used. Otherwise, the value is based
-on the effective @acronym{UID}, not the real @acronym{UID}.
-
-If you specify @var{uid}, the value is the user name that corresponds
-to @var{uid} (which should be an integer), or @code{nil} if there is
-no such user.
-
-@example
-@group
-(user-login-name)
- @result{} "lewis"
-@end group
-@end example
-@end defun
-
-@defun user-real-login-name
-This function returns the user name corresponding to Emacs's real
-@acronym{UID}. This ignores the effective @acronym{UID} and ignores the
-environment variables @code{LOGNAME} and @code{USER}.
-@end defun
-
-@defun user-full-name &optional uid
-This function returns the full name of the logged-in user---or the value
-of the environment variable @code{NAME}, if that is set.
-
-@c "Bil" is the correct spelling.
-@example
-@group
-(user-full-name)
- @result{} "Bil Lewis"
-@end group
-@end example
-
-If the Emacs job's user-id does not correspond to any known user (and
-provided @code{NAME} is not set), the value is @code{"unknown"}.
-
-If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
-or a string (a login name). Then @code{user-full-name} returns the full
-name corresponding to that user-id or login name. If you specify a
-user-id or login name that isn't defined, it returns @code{nil}.
-@end defun
-
-@vindex user-full-name
-@vindex user-real-login-name
-@vindex user-login-name
- The symbols @code{user-login-name}, @code{user-real-login-name} and
-@code{user-full-name} are variables as well as functions. The functions
-return the same values that the variables hold. These variables allow
-you to ``fake out'' Emacs by telling the functions what to return. The
-variables are also useful for constructing frame titles (@pxref{Frame
-Titles}).
-
-@defun user-real-uid
-This function returns the real @acronym{UID} of the user.
-The value may be a floating point number.
-
-@example
-@group
-(user-real-uid)
- @result{} 19
-@end group
-@end example
-@end defun
-
-@defun user-uid
-This function returns the effective @acronym{UID} of the user.
-The value may be a floating point number.
-@end defun
-
-@node Time of Day
-@section Time of Day
-
- This section explains how to determine the current time and the time
-zone.
-
-@defun current-time-string &optional time-value
-This function returns the current time and date as a human-readable
-string. The format of the string is unvarying; the number of characters
-used for each part is always the same, so you can reliably use
-@code{substring} to extract pieces of it. It is wise to count the
-characters from the beginning of the string rather than from the end, as
-additional information may some day be added at the end.
-
-@c Emacs 19 feature
-The argument @var{time-value}, if given, specifies a time to format
-instead of the current time. The argument should be a list whose first
-two elements are integers. Thus, you can use times obtained from
-@code{current-time} (see below) and from @code{file-attributes}
-(@pxref{Definition of file-attributes}). @var{time-value} can also be
-a cons of two integers, but this is considered obsolete.
-
-@example
-@group
-(current-time-string)
- @result{} "Wed Oct 14 22:21:05 1987"
-@end group
-@end example
-@end defun
-
-@c Emacs 19 feature
-@defun current-time
-This function returns the system's time value as a list of three
-integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
-@var{high} and @var{low} combine to give the number of seconds since
-0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
-
-The first two elements can be compared with file time values such as you
-get with the function @code{file-attributes}.
-@xref{Definition of file-attributes}.
-@end defun
-
-@c Emacs 19 feature
-@defun current-time-zone &optional time-value
-This function returns a list describing the time zone that the user is
-in.
-
-The value has the form @code{(@var{offset} @var{name})}. Here
-@var{offset} is an integer giving the number of seconds ahead of UTC
-(east of Greenwich). A negative value means west of Greenwich. The
-second element, @var{name}, is a string giving the name of the time
-zone. Both elements change when daylight saving time begins or ends;
-if the user has specified a time zone that does not use a seasonal time
-adjustment, then the value is constant through time.
-
-If the operating system doesn't supply all the information necessary to
-compute the value, the unknown elements of the list are @code{nil}.
-
-The argument @var{time-value}, if given, specifies a time to analyze
-instead of the current time. The argument should have the same form
-as for @code{current-time-string} (see above). Thus, you can use
-times obtained from @code{current-time} (see above) and from
-@code{file-attributes}. @xref{Definition of file-attributes}.
-@end defun
-
-@defun set-time-zone-rule tz
-This function specifies the local time zone according to @var{tz}. If
-@var{tz} is @code{nil}, that means to use an implementation-defined
-default time zone. If @var{tz} is @code{t}, that means to use
-Universal Time. Otherwise, @var{tz} should be a string specifying a
-time zone rule.
-@end defun
-
-@defun float-time &optional time-value
-This function returns the current time as a floating-point number of
-seconds since the epoch. The argument @var{time-value}, if given,
-specifies a time to convert instead of the current time. The argument
-should have the same form as for @code{current-time-string} (see
-above). Thus, it accepts the output of @code{current-time} and
-@code{file-attributes}.
-
-@emph{Warning}: Since the result is floating point, it may not be
-exact. Do not use this function if precise time stamps are required.
-@end defun
-
-@node Time Conversion
-@section Time Conversion
-
- These functions convert time values (lists of two or three integers)
-to calendrical information and vice versa. You can get time values
-from the functions @code{current-time} (@pxref{Time of Day}) and
-@code{file-attributes} (@pxref{Definition of file-attributes}).
-
- Many operating systems are limited to time values that contain 32 bits
-of information; these systems typically handle only the times from
-1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
-operating systems have larger time values, and can represent times far
-in the past or future.
-
- Time conversion functions always use the Gregorian calendar, even
-for dates before the Gregorian calendar was introduced. Year numbers
-count the number of years since the year 1 B.C., and do not skip zero
-as traditional Gregorian years do; for example, the year number
-@minus{}37 represents the Gregorian year 38 B.C@.
-
-@defun decode-time &optional time
-This function converts a time value into calendrical information. If
-you don't specify @var{time}, it decodes the current time. The return
-value is a list of nine elements, as follows:
-
-@example
-(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
-@end example
-
-Here is what the elements mean:
-
-@table @var
-@item seconds
-The number of seconds past the minute, as an integer between 0 and 59.
-On some operating systems, this is 60 for leap seconds.
-@item minutes
-The number of minutes past the hour, as an integer between 0 and 59.
-@item hour
-The hour of the day, as an integer between 0 and 23.
-@item day
-The day of the month, as an integer between 1 and 31.
-@item month
-The month of the year, as an integer between 1 and 12.
-@item year
-The year, an integer typically greater than 1900.
-@item dow
-The day of week, as an integer between 0 and 6, where 0 stands for
-Sunday.
-@item dst
-@code{t} if daylight saving time is effect, otherwise @code{nil}.
-@item zone
-An integer indicating the time zone, as the number of seconds east of
-Greenwich.
-@end table
-
-@strong{Common Lisp Note:} Common Lisp has different meanings for
-@var{dow} and @var{zone}.
-@end defun
-
-@defun encode-time seconds minutes hour day month year &optional zone
-This function is the inverse of @code{decode-time}. It converts seven
-items of calendrical data into a time value. For the meanings of the
-arguments, see the table above under @code{decode-time}.
-
-Year numbers less than 100 are not treated specially. If you want them
-to stand for years above 1900, or years above 2000, you must alter them
-yourself before you call @code{encode-time}.
-
-The optional argument @var{zone} defaults to the current time zone and
-its daylight saving time rules. If specified, it can be either a list
-(as you would get from @code{current-time-zone}), a string as in the
-@code{TZ} environment variable, @code{t} for Universal Time, or an
-integer (as you would get from @code{decode-time}). The specified
-zone is used without any further alteration for daylight saving time.
-
-If you pass more than seven arguments to @code{encode-time}, the first
-six are used as @var{seconds} through @var{year}, the last argument is
-used as @var{zone}, and the arguments in between are ignored. This
-feature makes it possible to use the elements of a list returned by
-@code{decode-time} as the arguments to @code{encode-time}, like this:
-
-@example
-(apply 'encode-time (decode-time @dots{}))
-@end example
-
-You can perform simple date arithmetic by using out-of-range values for
-the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
-arguments; for example, day 0 means the day preceding the given month.
-
-The operating system puts limits on the range of possible time values;
-if you try to encode a time that is out of range, an error results.
-For instance, years before 1970 do not work on some systems;
-on others, years as early as 1901 do work.
-@end defun
-
-@node Time Parsing
-@section Parsing and Formatting Times
-
- These functions convert time values (lists of two or three integers)
-to text in a string, and vice versa.
-
-@defun date-to-time string
-This function parses the time-string @var{string} and returns the
-corresponding time value.
-@end defun
-
-@defun format-time-string format-string &optional time universal
-This function converts @var{time} (or the current time, if @var{time} is
-omitted) to a string according to @var{format-string}. The argument
-@var{format-string} may contain @samp{%}-sequences which say to
-substitute parts of the time. Here is a table of what the
-@samp{%}-sequences mean:
-
-@table @samp
-@item %a
-This stands for the abbreviated name of the day of week.
-@item %A
-This stands for the full name of the day of week.
-@item %b
-This stands for the abbreviated name of the month.
-@item %B
-This stands for the full name of the month.
-@item %c
-This is a synonym for @samp{%x %X}.
-@item %C
-This has a locale-specific meaning. In the default locale (named C), it
-is equivalent to @samp{%A, %B %e, %Y}.
-@item %d
-This stands for the day of month, zero-padded.
-@item %D
-This is a synonym for @samp{%m/%d/%y}.
-@item %e
-This stands for the day of month, blank-padded.
-@item %h
-This is a synonym for @samp{%b}.
-@item %H
-This stands for the hour (00-23).
-@item %I
-This stands for the hour (01-12).
-@item %j
-This stands for the day of the year (001-366).
-@item %k
-This stands for the hour (0-23), blank padded.
-@item %l
-This stands for the hour (1-12), blank padded.
-@item %m
-This stands for the month (01-12).
-@item %M
-This stands for the minute (00-59).
-@item %n
-This stands for a newline.
-@item %p
-This stands for @samp{AM} or @samp{PM}, as appropriate.
-@item %r
-This is a synonym for @samp{%I:%M:%S %p}.
-@item %R
-This is a synonym for @samp{%H:%M}.
-@item %S
-This stands for the seconds (00-59).
-@item %t
-This stands for a tab character.
-@item %T
-This is a synonym for @samp{%H:%M:%S}.
-@item %U
-This stands for the week of the year (01-52), assuming that weeks
-start on Sunday.
-@item %w
-This stands for the numeric day of week (0-6). Sunday is day 0.
-@item %W
-This stands for the week of the year (01-52), assuming that weeks
-start on Monday.
-@item %x
-This has a locale-specific meaning. In the default locale (named
-@samp{C}), it is equivalent to @samp{%D}.
-@item %X
-This has a locale-specific meaning. In the default locale (named
-@samp{C}), it is equivalent to @samp{%T}.
-@item %y
-This stands for the year without century (00-99).
-@item %Y
-This stands for the year with century.
-@item %Z
-This stands for the time zone abbreviation (e.g., @samp{EST}).
-@item %z
-This stands for the time zone numerical offset (e.g., @samp{-0500}).
-@end table
-
-You can also specify the field width and type of padding for any of
-these @samp{%}-sequences. This works as in @code{printf}: you write
-the field width as digits in the middle of a @samp{%}-sequences. If you
-start the field width with @samp{0}, it means to pad with zeros. If you
-start the field width with @samp{_}, it means to pad with spaces.
-
-For example, @samp{%S} specifies the number of seconds since the minute;
-@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
-pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
-because that is how @samp{%S} normally pads to two positions.
-
-The characters @samp{E} and @samp{O} act as modifiers when used between
-@samp{%} and one of the letters in the table above. @samp{E} specifies
-using the current locale's ``alternative'' version of the date and time.
-In a Japanese locale, for example, @code{%Ex} might yield a date format
-based on the Japanese Emperors' reigns. @samp{E} is allowed in
-@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
-@samp{%EY}.
-
-@samp{O} means to use the current locale's ``alternative''
-representation of numbers, instead of the ordinary decimal digits. This
-is allowed with most letters, all the ones that output numbers.
-
-If @var{universal} is non-@code{nil}, that means to describe the time as
-Universal Time; @code{nil} means describe it using what Emacs believes
-is the local time zone (see @code{current-time-zone}).
-
-This function uses the C library function @code{strftime}
-(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
-Manual}) to do most of the work. In order to communicate with that
-function, it first encodes its argument using the coding system
-specified by @code{locale-coding-system} (@pxref{Locales}); after
-@code{strftime} returns the resulting string,
-@code{format-time-string} decodes the string using that same coding
-system.
-@end defun
-
-@defun seconds-to-time seconds
-This function converts @var{seconds}, a floating point number of
-seconds since the epoch, to a time value and returns that. To perform
-the inverse conversion, use @code{float-time}.
-@end defun
-
-@node Processor Run Time
-@section Processor Run time
-@cindex processor run time
-
-@defun get-internal-run-time
-This function returns the processor run time used by Emacs as a list
-of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
-integers @var{high} and @var{low} combine to give the number of
-seconds, which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds (or 0 for
-systems that return time with the resolution of only one second).
-
-If the system doesn't provide a way to determine the processor run
-time, get-internal-run-time returns the same time as current-time.
-@end defun
-
-@node Time Calculations
-@section Time Calculations
-
- These functions perform calendrical computations using time values
-(the kind of list that @code{current-time} returns).
-
-@defun time-less-p t1 t2
-This returns @code{t} if time value @var{t1} is less than time value
-@var{t2}.
-@end defun
-
-@defun time-subtract t1 t2
-This returns the time difference @var{t1} @minus{} @var{t2} between
-two time values, in the same format as a time value.
-@end defun
-
-@defun time-add t1 t2
-This returns the sum of two time values, one of which ought to
-represent a time difference rather than a point in time.
-Here is how to add a number of seconds to a time value:
-
-@example
-(time-add @var{time} (seconds-to-time @var{seconds}))
-@end example
-@end defun
-
-@defun time-to-days time
-This function returns the number of days between the beginning of year
-1 and @var{time}.
-@end defun
-
-@defun time-to-day-in-year time
-This returns the day number within the year corresponding to @var{time}.
-@end defun
-
-@defun date-leap-year-p year
-This function returns @code{t} if @var{year} is a leap year.
-@end defun
-
-@node Timers
-@section Timers for Delayed Execution
-@cindex timer
-
- You can set up a @dfn{timer} to call a function at a specified
-future time or after a certain length of idleness.
-
- Emacs cannot run timers at any arbitrary point in a Lisp program; it
-can run them only when Emacs could accept output from a subprocess:
-namely, while waiting or inside certain primitive functions such as
-@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
-timer's execution may be delayed if Emacs is busy. However, the time of
-execution is very precise if Emacs is idle.
-
- Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
-function, because quitting out of many timer functions can leave
-things in an inconsistent state. This is normally unproblematical
-because most timer functions don't do a lot of work. Indeed, for a
-timer to call a function that takes substantial time to run is likely
-to be annoying. If a timer function needs to allow quitting, it
-should use @code{with-local-quit} (@pxref{Quitting}). For example, if
-a timer function calls @code{accept-process-output} to receive output
-from an external process, that call should be wrapped inside
-@code{with-local-quit}, to ensure that @kbd{C-g} works if the external
-process hangs.
-
- It is usually a bad idea for timer functions to alter buffer
-contents. When they do, they usually should call @code{undo-boundary}
-both before and after changing the buffer, to separate the timer's
-changes from user commands' changes and prevent a single undo entry
-from growing to be quite large.
-
- Timer functions should also avoid calling functions that cause Emacs
-to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
-unpredictable effects, since other timers (or even the same timer) can
-run while waiting. If a timer function needs to perform an action
-after a certain time has elapsed, it can do this by scheduling a new
-timer.
-
- If a timer function calls functions that can change the match data,
-it should save and restore the match data. @xref{Saving Match Data}.
-
-@deffn Command run-at-time time repeat function &rest args
-This sets up a timer that calls the function @var{function} with
-arguments @var{args} at time @var{time}. If @var{repeat} is a number
-(integer or floating point), the timer is scheduled to run again every
-@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
-the timer runs only once.
-
-@var{time} may specify an absolute or a relative time.
-
-Absolute times may be specified using a string with a limited variety
-of formats, and are taken to be times @emph{today}, even if already in
-the past. The recognized forms are @samp{@var{xxxx}},
-@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
-and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
-@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
-@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
-@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
-to separate the hour and minute parts.
-
-To specify a relative time as a string, use numbers followed by units.
-For example:
-
-@table @samp
-@item 1 min
-denotes 1 minute from now.
-@item 1 min 5 sec
-denotes 65 seconds from now.
-@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
-denotes exactly 103 months, 123 days, and 10862 seconds from now.
-@end table
-
-For relative time values, Emacs considers a month to be exactly thirty
-days, and a year to be exactly 365.25 days.
-
-Not all convenient formats are strings. If @var{time} is a number
-(integer or floating point), that specifies a relative time measured in
-seconds. The result of @code{encode-time} can also be used to specify
-an absolute value for @var{time}.
-
-In most cases, @var{repeat} has no effect on when @emph{first} call
-takes place---@var{time} alone specifies that. There is one exception:
-if @var{time} is @code{t}, then the timer runs whenever the time is a
-multiple of @var{repeat} seconds after the epoch. This is useful for
-functions like @code{display-time}.
-
-The function @code{run-at-time} returns a timer value that identifies
-the particular scheduled future action. You can use this value to call
-@code{cancel-timer} (see below).
-@end deffn
-
- A repeating timer nominally ought to run every @var{repeat} seconds,
-but remember that any invocation of a timer can be late. Lateness of
-one repetition has no effect on the scheduled time of the next
-repetition. For instance, if Emacs is busy computing for long enough
-to cover three scheduled repetitions of the timer, and then starts to
-wait, it will immediately call the timer function three times in
-immediate succession (presuming no other timers trigger before or
-between them). If you want a timer to run again no less than @var{n}
-seconds after the last invocation, don't use the @var{repeat} argument.
-Instead, the timer function should explicitly reschedule the timer.
-
-@defvar timer-max-repeats
-This variable's value specifies the maximum number of times to repeat
-calling a timer function in a row, when many previously scheduled
-calls were unavoidably delayed.
-@end defvar
-
-@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
-Execute @var{body}, but give up after @var{seconds} seconds. If
-@var{body} finishes before the time is up, @code{with-timeout} returns
-the value of the last form in @var{body}. If, however, the execution of
-@var{body} is cut short by the timeout, then @code{with-timeout}
-executes all the @var{timeout-forms} and returns the value of the last
-of them.
-
-This macro works by setting a timer to run after @var{seconds} seconds. If
-@var{body} finishes before that time, it cancels the timer. If the
-timer actually runs, it terminates execution of @var{body}, then
-executes @var{timeout-forms}.
-
-Since timers can run within a Lisp program only when the program calls a
-primitive that can wait, @code{with-timeout} cannot stop executing
-@var{body} while it is in the midst of a computation---only when it
-calls one of those primitives. So use @code{with-timeout} only with a
-@var{body} that waits for input, not one that does a long computation.
-@end defmac
-
- The function @code{y-or-n-p-with-timeout} provides a simple way to use
-a timer to avoid waiting too long for an answer. @xref{Yes-or-No
-Queries}.
-
-@defun cancel-timer timer
-This cancels the requested action for @var{timer}, which should be a
-timer---usually, one previously returned by @code{run-at-time} or
-@code{run-with-idle-timer}. This cancels the effect of that call to
-one of these functions; the arrival of the specified time will not
-cause anything special to happen.
-@end defun
-
-@node Idle Timers
-@section Idle Timers
-
- Here is how to set up a timer that runs when Emacs is idle for a
-certain length of time. Aside from how to set them up, idle timers
-work just like ordinary timers.
-
-@deffn Command run-with-idle-timer secs repeat function &rest args
-Set up a timer which runs when Emacs has been idle for @var{secs}
-seconds. The value of @var{secs} may be an integer or a floating point
-number; a value of the type returned by @code{current-idle-time}
-is also allowed.
-
-If @var{repeat} is @code{nil}, the timer runs just once, the first time
-Emacs remains idle for a long enough time. More often @var{repeat} is
-non-@code{nil}, which means to run the timer @emph{each time} Emacs
-remains idle for @var{secs} seconds.
-
-The function @code{run-with-idle-timer} returns a timer value which you
-can use in calling @code{cancel-timer} (@pxref{Timers}).
-@end deffn
-
-@cindex idleness
- Emacs becomes ``idle'' when it starts waiting for user input, and it
-remains idle until the user provides some input. If a timer is set for
-five seconds of idleness, it runs approximately five seconds after Emacs
-first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
-will not run again as long as Emacs remains idle, because the duration
-of idleness will continue to increase and will not go down to five
-seconds again.
-
- Emacs can do various things while idle: garbage collect, autosave or
-handle data from a subprocess. But these interludes during idleness do
-not interfere with idle timers, because they do not reset the clock of
-idleness to zero. An idle timer set for 600 seconds will run when ten
-minutes have elapsed since the last user command was finished, even if
-subprocess output has been accepted thousands of times within those ten
-minutes, and even if there have been garbage collections and autosaves.
-
- When the user supplies input, Emacs becomes non-idle while executing the
-input. Then it becomes idle again, and all the idle timers that are
-set up to repeat will subsequently run another time, one by one.
-
-@c Emacs 19 feature
-@defun current-idle-time
-This function returns the length of time Emacs has been idle, as a
-list of three integers: @code{(@var{high} @var{low} @var{microsec})}.
-The integers @var{high} and @var{low} combine to give the number of
-seconds of idleness, which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
-
-The main use of this function is when an idle timer function wants to
-``take a break'' for a while. It can set up another idle timer to
-call the same function again, after a few seconds more idleness.
-Here's an example:
-
-@smallexample
-(defvar resume-timer nil
- "Timer that `timer-function' used to reschedule itself, or nil.")
-
-(defun timer-function ()
- ;; @r{If the user types a command while @code{resume-timer}}
- ;; @r{is active, the next time this function is called from}
- ;; @r{its main idle timer, deactivate @code{resume-timer}.}
- (when resume-timer
- (cancel-timer resume-timer))
- ...@var{do the work for a while}...
- (when @var{taking-a-break}
- (setq resume-timer
- (run-with-idle-timer
- ;; Compute an idle time @var{break-length}
- ;; more than the current value.
- (time-add (current-idle-time)
- (seconds-to-time @var{break-length}))
- nil
- 'timer-function))))
-@end smallexample
-@end defun
-
- Some idle timer functions in user Lisp packages have a loop that
-does a certain amount of processing each time around, and exits when
-@code{(input-pending-p)} is non-@code{nil}. That approach seems very
-natural but has two problems:
-
-@itemize
-@item
-It blocks out all process output (since Emacs accepts process output
-only while waiting).
-
-@item
-It blocks out any idle timers that ought to run during that time.
-@end itemize
-
-@noindent
-To avoid these problems, don't use that technique. Instead, write
-such idle timers to reschedule themselves after a brief pause, using
-the method in the @code{timer-function} example above.
-
-@node Terminal Input
-@section Terminal Input
-@cindex terminal input
-
- This section describes functions and variables for recording or
-manipulating terminal input. See @ref{Display}, for related
-functions.
-
-@menu
-* Input Modes:: Options for how input is processed.
-* Recording Input:: Saving histories of recent or all input events.
-@end menu
-
-@node Input Modes
-@subsection Input Modes
-@cindex input modes
-@cindex terminal input modes
-
-@defun set-input-mode interrupt flow meta &optional quit-char
-This function sets the mode for reading keyboard input. If
-@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode. The default setting is
-system-dependent. Some systems always use @sc{cbreak} mode regardless
-of what is specified.
-
-When Emacs communicates directly with X, it ignores this argument and
-uses interrupts if that is the way it knows how to communicate.
-
-If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
-(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
-has no effect except in @sc{cbreak} mode.
-
-@c Emacs 19 feature
-The argument @var{meta} controls support for input character codes
-above 127. If @var{meta} is @code{t}, Emacs converts characters with
-the 8th bit set into Meta characters. If @var{meta} is @code{nil},
-Emacs disregards the 8th bit; this is necessary when the terminal uses
-it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
-Emacs uses all 8 bits of input unchanged. This is good for terminals
-that use 8-bit character sets.
-
-@c Emacs 19 feature
-If @var{quit-char} is non-@code{nil}, it specifies the character to
-use for quitting. Normally this character is @kbd{C-g}.
-@xref{Quitting}.
-@end defun
-
-The @code{current-input-mode} function returns the input mode settings
-Emacs is currently using.
-
-@c Emacs 19 feature
-@defun current-input-mode
-This function returns the current mode for reading keyboard input. It
-returns a list, corresponding to the arguments of @code{set-input-mode},
-of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
-which:
-@table @var
-@item interrupt
-is non-@code{nil} when Emacs is using interrupt-driven input. If
-@code{nil}, Emacs is using @sc{cbreak} mode.
-@item flow
-is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
-flow control for output to the terminal. This value is meaningful only
-when @var{interrupt} is @code{nil}.
-@item meta
-is @code{t} if Emacs treats the eighth bit of input characters as
-the meta bit; @code{nil} means Emacs clears the eighth bit of every
-input character; any other value means Emacs uses all eight bits as the
-basic character code.
-@item quit
-is the character Emacs currently uses for quitting, usually @kbd{C-g}.
-@end table
-@end defun
-
-@node Recording Input
-@subsection Recording Input
-@cindex recording input
-
-@defun recent-keys
-This function returns a vector containing the last 300 input events from
-the keyboard or mouse. All input events are included, whether or not
-they were used as parts of key sequences. Thus, you always get the last
-100 input events, not counting events generated by keyboard macros.
-(These are excluded because they are less interesting for debugging; it
-should be enough to see the events that invoked the macros.)
-
-A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
-causes this function to return an empty vector immediately afterward.
-@end defun
-
-@deffn Command open-dribble-file filename
-@cindex dribble file
-This function opens a @dfn{dribble file} named @var{filename}. When a
-dribble file is open, each input event from the keyboard or mouse (but
-not those from keyboard macros) is written in that file. A
-non-character event is expressed using its printed representation
-surrounded by @samp{<@dots{}>}.
-
-You close the dribble file by calling this function with an argument
-of @code{nil}.
-
-This function is normally used to record the input necessary to
-trigger an Emacs bug, for the sake of a bug report.
-
-@example
-@group
-(open-dribble-file "~/dribble")
- @result{} nil
-@end group
-@end example
-@end deffn
-
- See also the @code{open-termscript} function (@pxref{Terminal Output}).
-
-@node Terminal Output
-@section Terminal Output
-@cindex terminal output
-
- The terminal output functions send output to a text terminal, or keep
-track of output sent to the terminal. The variable @code{baud-rate}
-tells you what Emacs thinks is the output speed of the terminal.
-
-@defvar baud-rate
-This variable's value is 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 such as
-padding.
-
- It also affects decisions about whether to scroll part of the
-screen or repaint on text terminals. @xref{Forcing Redisplay},
-for the corresponding functionality on graphical terminals.
-
-The value is measured in baud.
-@end defvar
-
- If you are running across a network, and different parts of the
-network work at different baud rates, the value returned by Emacs may be
-different from the value used by your local terminal. Some network
-protocols communicate the local terminal speed to the remote machine, so
-that Emacs and other programs can get the proper value, but others do
-not. If Emacs has the wrong value, it makes decisions that are less
-than optimal. To fix the problem, set @code{baud-rate}.
-
-@defun baud-rate
-This obsolete function returns the value of the variable
-@code{baud-rate}.
-@end defun
-
-@defun send-string-to-terminal string
-This function sends @var{string} to the terminal without alteration.
-Control characters in @var{string} have terminal-dependent effects.
-This function operates only on text terminals.
-
-One use of this function is to define function keys on terminals that
-have downloadable function key definitions. For example, this is how (on
-certain terminals) to define function key 4 to move forward four
-characters (by transmitting the characters @kbd{C-u C-f} to the
-computer):
-
-@example
-@group
-(send-string-to-terminal "\eF4\^U\^F")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@deffn Command open-termscript filename
-@cindex termscript file
-This function is used to open a @dfn{termscript file} that will record
-all the characters sent by Emacs to the terminal. It returns
-@code{nil}. Termscript files are useful for investigating problems
-where Emacs garbles the screen, problems that are due to incorrect
-Termcap entries or to undesirable settings of terminal options more
-often than to actual Emacs bugs. Once you are certain which characters
-were actually output, you can determine reliably whether they correspond
-to the Termcap specifications in use.
-
-You close the termscript file by calling this function with an
-argument of @code{nil}.
-
-See also @code{open-dribble-file} in @ref{Recording Input}.
-
-@example
-@group
-(open-termscript "../junk/termscript")
- @result{} nil
-@end group
-@end example
-@end deffn
-
-@node Sound Output
-@section Sound Output
-@cindex sound
-
- To play sound using Emacs, use the function @code{play-sound}. Only
-certain systems are supported; if you call @code{play-sound} on a system
-which cannot really do the job, it gives an error. Emacs version 20 and
-earlier did not support sound at all.
-
- The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
-or Sun Audio format (@samp{.au}).
-
-@defun play-sound sound
-This function plays a specified sound. The argument, @var{sound}, has
-the form @code{(sound @var{properties}...)}, where the @var{properties}
-consist of alternating keywords (particular symbols recognized
-specially) and values corresponding to them.
-
-Here is a table of the keywords that are currently meaningful in
-@var{sound}, and their meanings:
-
-@table @code
-@item :file @var{file}
-This specifies the file containing the sound to play.
-If the file name is not absolute, it is expanded against
-the directory @code{data-directory}.
-
-@item :data @var{data}
-This specifies the sound to play without need to refer to a file. The
-value, @var{data}, should be a string containing the same bytes as a
-sound file. We recommend using a unibyte string.
-
-@item :volume @var{volume}
-This specifies how loud to play the sound. It should be a number in the
-range of 0 to 1. The default is to use whatever volume has been
-specified before.
-
-@item :device @var{device}
-This specifies the system device on which to play the sound, as a
-string. The default device is system-dependent.
-@end table
-
-Before actually playing the sound, @code{play-sound}
-calls the functions in the list @code{play-sound-functions}.
-Each function is called with one argument, @var{sound}.
-@end defun
-
-@defun play-sound-file file &optional volume device
-This function is an alternative interface to playing a sound @var{file}
-specifying an optional @var{volume} and @var{device}.
-@end defun
-
-@defvar play-sound-functions
-A list of functions to be called before playing a sound. Each function
-is called with one argument, a property list that describes the sound.
-@end defvar
-
-@node X11 Keysyms
-@section Operating on X11 Keysyms
-@cindex X11 keysyms
-
-To define system-specific X11 keysyms, set the variable
-@code{system-key-alist}.
-
-@defvar system-key-alist
-This variable's value should be an alist with one element for each
-system-specific keysym. Each element has the form @code{(@var{code}
-. @var{symbol})}, where @var{code} is the numeric keysym code (not
-including the ``vendor specific'' bit,
-@ifnottex
--2**28),
-@end ifnottex
-@tex
-$-2^{28}$),
-@end tex
-and @var{symbol} is the name for the function key.
-
-For example @code{(168 . mute-acute)} defines a system-specific key (used
-by HP X servers) whose numeric code is
-@ifnottex
--2**28
-@end ifnottex
-@tex
-$-2^{28}$
-@end tex
-+ 168.
-
-It is not crucial to exclude from the alist the keysyms of other X
-servers; those do no harm, as long as they don't conflict with the ones
-used by the X server actually in use.
-
-The variable is always local to the current terminal, and cannot be
-buffer-local. @xref{Multiple Displays}.
-@end defvar
-
-You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
-
-@defvar x-alt-keysym
-@defvarx x-meta-keysym
-@defvarx x-hyper-keysym
-@defvarx x-super-keysym
-The name of the keysym that should stand for the Alt modifier
-(respectively, for Meta, Hyper, and Super). For example, here is
-how to swap the Meta and Alt modifiers within Emacs:
-@lisp
-(setq x-alt-keysym 'meta)
-(setq x-meta-keysym 'alt)
-@end lisp
-@end defvar
-
-@node Batch Mode
-@section Batch Mode
-@cindex batch mode
-
- The command-line option @samp{-batch} causes Emacs to run
-noninteractively. In this mode, Emacs does not read commands from the
-terminal, it does not alter the terminal modes, and it does not expect
-to be outputting to an erasable screen. The idea is that you specify
-Lisp programs to run; when they are finished, Emacs should exit. The
-way to specify the programs to run is with @samp{-l @var{file}}, which
-loads the library named @var{file}, or @samp{-f @var{function}}, which
-calls @var{function} with no arguments, or @samp{--eval @var{form}}.
-
- Any Lisp program output that would normally go to the echo area,
-either using @code{message}, or using @code{prin1}, etc., with @code{t}
-as the stream, goes instead to Emacs's standard error descriptor when
-in batch mode. Similarly, input that would normally come from the
-minibuffer is read from the standard input descriptor.
-Thus, Emacs behaves much like a noninteractive
-application program. (The echo area output that Emacs itself normally
-generates, such as command echoing, is suppressed entirely.)
-
-@defvar noninteractive
-This variable is non-@code{nil} when Emacs is running in batch mode.
-@end defvar
-
-@node Session Management
-@section Session Management
-@cindex session manager
-
-Emacs supports the X Session Management Protocol for suspension and
-restart of applications. In the X Window System, a program called the
-@dfn{session manager} has the responsibility to keep track of the
-applications that are running. During shutdown, the session manager
-asks applications to save their state, and delays the actual shutdown
-until they respond. An application can also cancel the shutdown.
-
-When the session manager restarts a suspended session, it directs
-these applications to individually reload their saved state. It does
-this by specifying a special command-line argument that says what
-saved session to restore. For Emacs, this argument is @samp{--smid
-@var{session}}.
-
-@defvar emacs-save-session-functions
-Emacs supports saving state by using a hook called
-@code{emacs-save-session-functions}. Each function in this hook is
-called when the session manager tells Emacs that the window system is
-shutting down. The functions are called with no arguments and with the
-current buffer set to a temporary buffer. Each function can use
-@code{insert} to add Lisp code to this buffer. At the end, Emacs
-saves the buffer in a file that a subsequent Emacs invocation will
-load in order to restart the saved session.
-
-If a function in @code{emacs-save-session-functions} returns
-non-@code{nil}, Emacs tells the session manager to cancel the
-shutdown.
-@end defvar
-
-Here is an example that just inserts some text into @samp{*scratch*} when
-Emacs is restarted by the session manager.
-
-@example
-@group
-(add-hook 'emacs-save-session-functions 'save-yourself-test)
-@end group
-
-@group
-(defun save-yourself-test ()
- (insert "(save-excursion
- (switch-to-buffer \"*scratch*\")
- (insert \"I am restored\"))")
- nil)
-@end group
-@end example
-
-@ignore
- arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
-@end ignore
+++ /dev/null
-@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/positions
-@node Positions, Markers, Frames, Top
-@chapter Positions
-@cindex position (in buffer)
-
- A @dfn{position} is the index of a character in the text of a buffer.
-More precisely, a position identifies the place between two characters
-(or before the first character, or after the last character), so we can
-speak of the character before or after a given position. However, we
-often speak of the character ``at'' a position, meaning the character
-after that position.
-
- Positions are usually represented as integers starting from 1, but
-can also be represented as @dfn{markers}---special objects that
-relocate automatically when text is inserted or deleted so they stay
-with the surrounding characters. Functions that expect an argument to
-be a position (an integer), but accept a marker as a substitute,
-normally ignore which buffer the marker points into; they convert the
-marker to an integer, and use that integer, exactly as if you had
-passed the integer as the argument, even if the marker points to the
-``wrong'' buffer. A marker that points nowhere cannot convert to an
-integer; using it instead of an integer causes an error.
-@xref{Markers}.
-
- See also the ``field'' feature (@pxref{Fields}), which provides
-functions that are used by many cursor-motion commands.
-
-@menu
-* 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.
-@end menu
-
-@node Point
-@section Point
-@cindex point
-
- @dfn{Point} is a special buffer position used by many editing
-commands, including the self-inserting typed characters and text
-insertion functions. Other commands move point through the text
-to allow editing and insertion at different places.
-
- Like other positions, point designates a place between two characters
-(or before the first character, or after the last character), rather
-than a particular character. Usually terminals display the cursor over
-the character that immediately follows point; point is actually before
-the character on which the cursor sits.
-
-@cindex point with narrowing
- The value of point is a number no less than 1, and no greater than the
-buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
-point is constrained to fall within the accessible portion of the buffer
-(possibly at one end of it).
-
- Each buffer has its own value of point, which is independent of the
-value of point in other buffers. Each window also has a value of point,
-which is independent of the value of point in other windows on the same
-buffer. This is why point can have different values in various windows
-that display the same buffer. When a buffer appears in only one window,
-the buffer's point and the window's point normally have the same value,
-so the distinction is rarely important. @xref{Window Point}, for more
-details.
-
-@defun point
-@cindex current buffer position
-This function returns the value of point in the current buffer,
-as an integer.
-
-@need 700
-@example
-@group
-(point)
- @result{} 175
-@end group
-@end example
-@end defun
-
-@defun point-min
-This function returns the minimum accessible value of point in the
-current buffer. This is normally 1, but if narrowing is in effect, it
-is the position of the start of the region that you narrowed to.
-(@xref{Narrowing}.)
-@end defun
-
-@defun point-max
-This function returns the maximum accessible value of point in the
-current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
-in effect, in which case it is the position of the end of the region
-that you narrowed to. (@xref{Narrowing}.)
-@end defun
-
-@defun buffer-end flag
-This function returns @code{(point-max)} if @var{flag} is greater than
-0, @code{(point-min)} otherwise. The argument @var{flag} must be a
-number.
-@end defun
-
-@defun buffer-size &optional buffer
-This function returns the total number of characters in the current
-buffer. In the absence of any narrowing (@pxref{Narrowing}),
-@code{point-max} returns a value one larger than this.
-
-If you specify a buffer, @var{buffer}, then the value is the
-size of @var{buffer}.
-
-@example
-@group
-(buffer-size)
- @result{} 35
-@end group
-@group
-(point-max)
- @result{} 36
-@end group
-@end example
-@end defun
-
-@node Motion
-@section Motion
-@cindex motion by chars, words, lines, lists
-
- Motion functions change the value of point, either relative to the
-current value of point, relative to the beginning or end of the buffer,
-or relative to the edges of the selected window. @xref{Point}.
-
-@menu
-* 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.
-@end menu
-
-@node Character Motion
-@subsection Motion by Characters
-
- These functions move point based on a count of characters.
-@code{goto-char} is the fundamental primitive; the other functions use
-that.
-
-@deffn Command goto-char position
-This function sets point in the current buffer to the value
-@var{position}. If @var{position} is less than 1, it moves point to the
-beginning of the buffer. If @var{position} is greater than the length
-of the buffer, it moves point to the end.
-
-If narrowing is in effect, @var{position} still counts from the
-beginning of the buffer, but point cannot go outside the accessible
-portion. If @var{position} is out of range, @code{goto-char} moves
-point to the beginning or the end of the accessible portion.
-
-When this function is called interactively, @var{position} is the
-numeric prefix argument, if provided; otherwise it is read from the
-minibuffer.
-
-@code{goto-char} returns @var{position}.
-@end deffn
-
-@deffn Command forward-char &optional count
-@c @kindex beginning-of-buffer
-@c @kindex end-of-buffer
-This function moves point @var{count} characters forward, towards the
-end of the buffer (or backward, towards the beginning of the buffer, if
-@var{count} is negative). If @var{count} is @code{nil}, the default
-is 1.
-
-If this attempts to move past the beginning or end of the buffer (or
-the limits of the accessible portion, when narrowing is in effect), it
-signals an error with error symbol @code{beginning-of-buffer} or
-@code{end-of-buffer}.
-
-In an interactive call, @var{count} is the numeric prefix argument.
-@end deffn
-
-@deffn Command backward-char &optional count
-This is just like @code{forward-char} except that it moves
-in the opposite direction.
-@end deffn
-
-@node Word Motion
-@subsection Motion by Words
-
- These functions for parsing words use the syntax table to decide
-whether a given character is part of a word. @xref{Syntax Tables}.
-
-@deffn Command forward-word &optional count
-This function moves point forward @var{count} words (or backward if
-@var{count} is negative). If @var{count} is @code{nil}, it moves
-forward one word.
-
-``Moving one word'' means moving until point crosses a
-word-constituent character and then encounters a word-separator
-character. However, this function cannot move point past the boundary
-of the accessible portion of the buffer, or across a field boundary
-(@pxref{Fields}). The most common case of a field boundary is the end
-of the prompt in the minibuffer.
-
-If it is possible to move @var{count} words, without being stopped
-prematurely by the buffer boundary or a field boundary, the value is
-@code{t}. Otherwise, the return value is @code{nil} and point stops at
-the buffer boundary or field boundary.
-
-If @code{inhibit-field-text-motion} is non-@code{nil},
-this function ignores field boundaries.
-
-In an interactive call, @var{count} is specified by the numeric prefix
-argument. If @var{count} is omitted or @code{nil}, it defaults to 1.
-@end deffn
-
-@deffn Command backward-word &optional count
-This function is just like @code{forward-word}, except that it moves
-backward until encountering the front of a word, rather than forward.
-@end deffn
-
-@defvar words-include-escapes
-@c Emacs 19 feature
-This variable affects the behavior of @code{forward-word} and everything
-that uses it. If it is non-@code{nil}, then characters in the
-``escape'' and ``character quote'' syntax classes count as part of
-words. Otherwise, they do not.
-@end defvar
-
-@defvar inhibit-field-text-motion
-If this variable is non-@code{nil}, certain motion functions including
-@code{forward-word}, @code{forward-sentence}, and
-@code{forward-paragraph} ignore field boundaries.
-@end defvar
-
-@node Buffer End Motion
-@subsection Motion to an End of the Buffer
-@cindex move to beginning or end of buffer
-
- To move point to the beginning of the buffer, write:
-
-@example
-@group
-(goto-char (point-min))
-@end group
-@end example
-
-@noindent
-Likewise, to move to the end of the buffer, use:
-
-@example
-@group
-(goto-char (point-max))
-@end group
-@end example
-
- Here are two commands that users use to do these things. They are
-documented here to warn you not to use them in Lisp programs, because
-they set the mark and display messages in the echo area.
-
-@deffn Command beginning-of-buffer &optional n
-This function moves point to the beginning of the buffer (or the limits
-of the accessible portion, when narrowing is in effect), setting the
-mark at the previous position (except in Transient Mark mode, if
-the mark is already active, it does not set the mark.)
-
-If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
-way from the beginning of the accessible portion of the buffer. In an
-interactive call, @var{n} is the numeric prefix argument, if provided;
-otherwise @var{n} defaults to @code{nil}.
-
-@strong{Warning:} Don't use this function in Lisp programs!
-@end deffn
-
-@deffn Command end-of-buffer &optional n
-This function moves point to the end of the buffer (or the limits of
-the accessible portion, when narrowing is in effect), setting the mark
-at the previous position (except in Transient Mark mode when the mark
-is already active). If @var{n} is non-@code{nil}, then it puts point
-@var{n} tenths of the way from the end of the accessible portion of
-the buffer.
-
-In an interactive call, @var{n} is the numeric prefix argument,
-if provided; otherwise @var{n} defaults to @code{nil}.
-
-@strong{Warning:} Don't use this function in Lisp programs!
-@end deffn
-
-@node Text Lines
-@subsection Motion by Text Lines
-@cindex lines
-
- Text lines are portions of the buffer delimited by newline characters,
-which are regarded as part of the previous line. The first text line
-begins at the beginning of the buffer, and the last text line ends at
-the end of the buffer whether or not the last character is a newline.
-The division of the buffer into text lines is not affected by the width
-of the window, by line continuation in display, or by how tabs and
-control characters are displayed.
-
-@deffn Command goto-line line
-This function moves point to the front of the @var{line}th line,
-counting from line 1 at beginning of the buffer. If @var{line} is less
-than 1, it moves point to the beginning of the buffer. If @var{line} is
-greater than the number of lines in the buffer, it moves point to the
-end of the buffer---that is, the @emph{end of the last line} of the
-buffer. This is the only case in which @code{goto-line} does not
-necessarily move to the beginning of a line.
-
-If narrowing is in effect, then @var{line} still counts from the
-beginning of the buffer, but point cannot go outside the accessible
-portion. So @code{goto-line} moves point to the beginning or end of the
-accessible portion, if the line number specifies an inaccessible
-position.
-
-The return value of @code{goto-line} is the difference between
-@var{line} and the line number of the line to which point actually was
-able to move (in the full buffer, before taking account of narrowing).
-Thus, the value is positive if the scan encounters the real end of the
-buffer before finding the specified line. The value is zero if scan
-encounters the end of the accessible portion but not the real end of the
-buffer.
-
-In an interactive call, @var{line} is the numeric prefix argument if
-one has been provided. Otherwise @var{line} is read in the minibuffer.
-@end deffn
-
-@deffn Command beginning-of-line &optional count
-This function moves point to the beginning of the current line. With an
-argument @var{count} not @code{nil} or 1, it moves forward
-@var{count}@minus{}1 lines and then to the beginning of the line.
-
-This function does not move point across a field boundary
-(@pxref{Fields}) unless doing so would move beyond there to a
-different line; therefore, if @var{count} is @code{nil} or 1, and
-point starts at a field boundary, point does not move. To ignore
-field boundaries, either bind @code{inhibit-field-text-motion} to
-@code{t}, or use the @code{forward-line} function instead. For
-instance, @code{(forward-line 0)} does the same thing as
-@code{(beginning-of-line)}, except that it ignores field boundaries.
-
-If this function reaches the end of the buffer (or of the accessible
-portion, if narrowing is in effect), it positions point there. No error
-is signaled.
-@end deffn
-
-@defun line-beginning-position &optional count
-Return the position that @code{(beginning-of-line @var{count})}
-would move to.
-@end defun
-
-@deffn Command end-of-line &optional count
-This function moves point to the end of the current line. With an
-argument @var{count} not @code{nil} or 1, it moves forward
-@var{count}@minus{}1 lines and then to the end of the line.
-
-This function does not move point across a field boundary
-(@pxref{Fields}) unless doing so would move beyond there to a
-different line; therefore, if @var{count} is @code{nil} or 1, and
-point starts at a field boundary, point does not move. To ignore
-field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
-
-If this function reaches the end of the buffer (or of the accessible
-portion, if narrowing is in effect), it positions point there. No error
-is signaled.
-@end deffn
-
-@defun line-end-position &optional count
-Return the position that @code{(end-of-line @var{count})}
-would move to.
-@end defun
-
-@deffn Command forward-line &optional count
-@cindex beginning of line
-This function moves point forward @var{count} lines, to the beginning of
-the line. If @var{count} is negative, it moves point
-@minus{}@var{count} lines backward, to the beginning of a line. If
-@var{count} is zero, it moves point to the beginning of the current
-line. If @var{count} is @code{nil}, that means 1.
-
-If @code{forward-line} encounters the beginning or end of the buffer (or
-of the accessible portion) before finding that many lines, it sets point
-there. No error is signaled.
-
-@code{forward-line} returns the difference between @var{count} and the
-number of lines actually moved. If you attempt to move down five lines
-from the beginning of a buffer that has only three lines, point stops at
-the end of the last line, and the value will be 2.
-
-In an interactive call, @var{count} is the numeric prefix argument.
-@end deffn
-
-@defun count-lines start end
-@cindex lines in region
-@anchor{Definition of count-lines}
-This function returns the number of lines between the positions
-@var{start} and @var{end} in the current buffer. If @var{start} and
-@var{end} are equal, then it returns 0. Otherwise it returns at least
-1, even if @var{start} and @var{end} are on the same line. This is
-because the text between them, considered in isolation, must contain at
-least one line unless it is empty.
-
-Here is an example of using @code{count-lines}:
-
-@example
-@group
-(defun current-line ()
- "Return the vertical position of point@dots{}"
- (+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)))
-@end group
-@end example
-@end defun
-
-@defun line-number-at-pos &optional pos
-@cindex line number
-This function returns the line number in the current buffer
-corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil}
-or omitted, the current buffer position is used.
-@end defun
-
-@ignore
-@c ================
-The @code{previous-line} and @code{next-line} commands are functions
-that should not be used in programs. They are for users and are
-mentioned here only for completeness.
-
-@deffn Command previous-line count
-@cindex goal column
-This function moves point up @var{count} lines (down if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
-(normally the same column that it was at the beginning of the move).
-
-If there is no character in the target line exactly under the current
-column, point is positioned after the character in that line which
-spans this column, or at the end of the line if it is not long enough.
-
-If it attempts to move beyond the top or bottom of the buffer (or clipped
-region), then point is positioned in the goal column in the top or
-bottom line. No error is signaled.
-
-In an interactive call, @var{count} will be the numeric
-prefix argument.
-
-The command @code{set-goal-column} can be used to create a semipermanent
-goal column to which this command always moves. Then it does not try to
-move vertically.
-
-If you are thinking of using this in a Lisp program, consider using
-@code{forward-line} with a negative argument instead. It is usually easier
-to use and more reliable (no dependence on goal column, etc.).
-@end deffn
-
-@deffn Command next-line count
-This function moves point down @var{count} lines (up if @var{count}
-is negative). In moving, it attempts to keep point in the ``goal column''
-(normally the same column that it was at the beginning of the move).
-
-If there is no character in the target line exactly under the current
-column, point is positioned after the character in that line which
-spans this column, or at the end of the line if it is not long enough.
-
-If it attempts to move beyond the top or bottom of the buffer (or clipped
-region), then point is positioned in the goal column in the top or
-bottom line. No error is signaled.
-
-In the case where the @var{count} is 1, and point is on the last
-line of the buffer (or clipped region), a new empty line is inserted at the
-end of the buffer (or clipped region) and point moved there.
-
-In an interactive call, @var{count} will be the numeric
-prefix argument.
-
-The command @code{set-goal-column} can be used to create a semipermanent
-goal column to which this command always moves. Then it does not try to
-move vertically.
-
-If you are thinking of using this in a Lisp program, consider using
-@code{forward-line} instead. It is usually easier
-to use and more reliable (no dependence on goal column, etc.).
-@end deffn
-
-@c ================
-@end ignore
-
- Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
-These functions do not move point, but test whether it is already at the
-beginning or end of a line.
-
-@node Screen Lines
-@subsection Motion by Screen Lines
-
- The line functions in the previous section count text lines, delimited
-only by newline characters. By contrast, these functions count screen
-lines, which are defined by the way the text appears on the screen. A
-text line is a single screen line if it is short enough to fit the width
-of the selected window, but otherwise it may occupy several screen
-lines.
-
- In some cases, text lines are truncated on the screen rather than
-continued onto additional screen lines. In these cases,
-@code{vertical-motion} moves point much like @code{forward-line}.
-@xref{Truncation}.
-
- Because the width of a given string depends on the flags that control
-the appearance of certain characters, @code{vertical-motion} behaves
-differently, for a given piece of text, depending on the buffer it is
-in, and even on the selected window (because the width, the truncation
-flag, and display table may vary between windows). @xref{Usual
-Display}.
-
- These functions scan text to determine where screen lines break, and
-thus take time proportional to the distance scanned. If you intend to
-use them heavily, Emacs provides caches which may improve the
-performance of your code. @xref{Truncation, cache-long-line-scans}.
-
-@defun vertical-motion count &optional window
-This function moves point to the start of the screen line @var{count}
-screen lines down from the screen line containing point. If @var{count}
-is negative, it moves up instead.
-
-@code{vertical-motion} returns the number of screen lines over which it
-moved point. The value may be less in absolute value than @var{count}
-if the beginning or end of the buffer was reached.
-
-The window @var{window} is used for obtaining parameters such as the
-width, the horizontal scrolling, and the display table. But
-@code{vertical-motion} always operates on the current buffer, even if
-@var{window} currently displays some other buffer.
-@end defun
-
-@defun count-screen-lines &optional beg end count-final-newline window
-This function returns the number of screen lines in the text from
-@var{beg} to @var{end}. The number of screen lines may be different
-from the number of actual lines, due to line continuation, the display
-table, etc. If @var{beg} and @var{end} are @code{nil} or omitted,
-they default to the beginning and end of the accessible portion of the
-buffer.
-
-If the region ends with a newline, that is ignored unless the optional
-third argument @var{count-final-newline} is non-@code{nil}.
-
-The optional fourth argument @var{window} specifies the window for
-obtaining parameters such as width, horizontal scrolling, and so on.
-The default is to use the selected window's parameters.
-
-Like @code{vertical-motion}, @code{count-screen-lines} always uses the
-current buffer, regardless of which buffer is displayed in
-@var{window}. This makes possible to use @code{count-screen-lines} in
-any buffer, whether or not it is currently displayed in some window.
-@end defun
-
-@deffn Command move-to-window-line count
-This function moves point with respect to the text currently displayed
-in the selected window. It moves point to the beginning of the screen
-line @var{count} screen lines from the top of the window. If
-@var{count} is negative, that specifies a position
-@w{@minus{}@var{count}} lines from the bottom (or the last line of the
-buffer, if the buffer ends above the specified screen position).
-
-If @var{count} is @code{nil}, then point moves to the beginning of the
-line in the middle of the window. If the absolute value of @var{count}
-is greater than the size of the window, then point moves to the place
-that would appear on that screen line if the window were tall enough.
-This will probably cause the next redisplay to scroll to bring that
-location onto the screen.
-
-In an interactive call, @var{count} is the numeric prefix argument.
-
-The value returned is the window line number point has moved to, with
-the top line in the window numbered 0.
-@end deffn
-
-@defun compute-motion from frompos to topos width offsets window
-This function scans the current buffer, calculating screen positions.
-It scans the buffer forward from position @var{from}, assuming that is
-at screen coordinates @var{frompos}, to position @var{to} or coordinates
-@var{topos}, whichever comes first. It returns the ending buffer
-position and screen coordinates.
-
-The coordinate arguments @var{frompos} and @var{topos} are cons cells of
-the form @code{(@var{hpos} . @var{vpos})}.
-
-The argument @var{width} is the number of columns available to display
-text; this affects handling of continuation lines. @code{nil} means
-the actual number of usable text columns in the window, which is
-equivalent to the value returned by @code{(window-width window)}.
-
-The argument @var{offsets} is either @code{nil} or a cons cell of the
-form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
-the number of columns not being displayed at the left margin; most
-callers get this by calling @code{window-hscroll}. Meanwhile,
-@var{tab-offset} is the offset between column numbers on the screen and
-column numbers in the buffer. This can be nonzero in a continuation
-line, when the previous screen lines' widths do not add up to a multiple
-of @code{tab-width}. It is always zero in a non-continuation line.
-
-The window @var{window} serves only to specify which display table to
-use. @code{compute-motion} always operates on the current buffer,
-regardless of what buffer is displayed in @var{window}.
-
-The return value is a list of five elements:
-
-@example
-(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
-@end example
-
-@noindent
-Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
-is the vertical screen position, and @var{hpos} is the horizontal screen
-position.
-
-The result @var{prevhpos} is the horizontal position one character back
-from @var{pos}. The result @var{contin} is @code{t} if the last line
-was continued after (or within) the previous character.
-
-For example, to find the buffer position of column @var{col} of screen line
-@var{line} of a certain window, pass the window's display start location
-as @var{from} and the window's upper-left coordinates as @var{frompos}.
-Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
-the end of the accessible portion of the buffer, and pass @var{line} and
-@var{col} as @var{topos}. Here's a function that does this:
-
-@example
-(defun coordinates-of-position (col line)
- (car (compute-motion (window-start)
- '(0 . 0)
- (point-max)
- (cons col line)
- (window-width)
- (cons (window-hscroll) 0)
- (selected-window))))
-@end example
-
-When you use @code{compute-motion} for the minibuffer, you need to use
-@code{minibuffer-prompt-width} to get the horizontal position of the
-beginning of the first screen line. @xref{Minibuffer Contents}.
-@end defun
-
-@node List Motion
-@comment node-name, next, previous, up
-@subsection Moving over Balanced Expressions
-@cindex sexp motion
-@cindex Lisp expression motion
-@cindex list motion
-@cindex balanced parenthesis motion
-
- Here are several functions concerned with balanced-parenthesis
-expressions (also called @dfn{sexps} in connection with moving across
-them in Emacs). The syntax table controls how these functions interpret
-various characters; see @ref{Syntax Tables}. @xref{Parsing
-Expressions}, for lower-level primitives for scanning sexps or parts of
-sexps. For user-level commands, see @ref{Parentheses,, Commands for
-Editing with Parentheses, emacs, The GNU Emacs Manual}.
-
-@deffn Command forward-list &optional arg
-This function moves forward across @var{arg} (default 1) balanced groups of
-parentheses. (Other syntactic entities such as words or paired string
-quotes are ignored.)
-@end deffn
-
-@deffn Command backward-list &optional arg
-This function moves backward across @var{arg} (default 1) balanced groups of
-parentheses. (Other syntactic entities such as words or paired string
-quotes are ignored.)
-@end deffn
-
-@deffn Command up-list &optional arg
-This function moves forward out of @var{arg} (default 1) levels of parentheses.
-A negative argument means move backward but still to a less deep spot.
-@end deffn
-
-@deffn Command down-list &optional arg
-This function moves forward into @var{arg} (default 1) levels of
-parentheses. A negative argument means move backward but still go
-deeper in parentheses (@minus{}@var{arg} levels).
-@end deffn
-
-@deffn Command forward-sexp &optional arg
-This function moves forward across @var{arg} (default 1) balanced expressions.
-Balanced expressions include both those delimited by parentheses and
-other kinds, such as words and string constants.
-@xref{Parsing Expressions}. For example,
-
-@example
-@group
----------- Buffer: foo ----------
-(concat@point{} "foo " (car x) y z)
----------- Buffer: foo ----------
-@end group
-
-@group
-(forward-sexp 3)
- @result{} nil
-
----------- Buffer: foo ----------
-(concat "foo " (car x) y@point{} z)
----------- Buffer: foo ----------
-@end group
-@end example
-@end deffn
-
-@deffn Command backward-sexp &optional arg
-This function moves backward across @var{arg} (default 1) balanced expressions.
-@end deffn
-
-@deffn Command beginning-of-defun &optional arg
-This function moves back to the @var{arg}th beginning of a defun. If
-@var{arg} is negative, this actually moves forward, but it still moves
-to the beginning of a defun, not to the end of one. @var{arg} defaults
-to 1.
-@end deffn
-
-@deffn Command end-of-defun &optional arg
-This function moves forward to the @var{arg}th end of a defun. If
-@var{arg} is negative, this actually moves backward, but it still moves
-to the end of a defun, not to the beginning of one. @var{arg} defaults
-to 1.
-@end deffn
-
-@defopt defun-prompt-regexp
-If non-@code{nil}, this buffer-local variable holds a regular
-expression that specifies what text can appear before the
-open-parenthesis that starts a defun. That is to say, a defun begins
-on a line that starts with a match for this regular expression,
-followed by a character with open-parenthesis syntax.
-@end defopt
-
-@defopt open-paren-in-column-0-is-defun-start
-If this variable's value is non-@code{nil}, an open parenthesis in
-column 0 is considered to be the start of a defun. If it is
-@code{nil}, an open parenthesis in column 0 has no special meaning.
-The default is @code{t}.
-@end defopt
-
-@defvar beginning-of-defun-function
-If non-@code{nil}, this variable holds a function for finding the
-beginning of a defun. The function @code{beginning-of-defun}
-calls this function instead of using its normal method.
-@end defvar
-
-@defvar end-of-defun-function
-If non-@code{nil}, this variable holds a function for finding the end of
-a defun. The function @code{end-of-defun} calls this function instead
-of using its normal method.
-@end defvar
-
-@node Skipping Characters
-@comment node-name, next, previous, up
-@subsection Skipping Characters
-@cindex skipping characters
-
- The following two functions move point over a specified set of
-characters. For example, they are often used to skip whitespace. For
-related functions, see @ref{Motion and Syntax}.
-
-These functions convert the set string to multibyte if the buffer is
-multibyte, and they convert it to unibyte if the buffer is unibyte, as
-the search functions do (@pxref{Searching and Matching}).
-
-@defun skip-chars-forward character-set &optional limit
-This function moves point in the current buffer forward, skipping over a
-given set of characters. It examines the character following point,
-then advances point if the character matches @var{character-set}. This
-continues until it reaches a character that does not match. The
-function returns the number of characters moved over.
-
-The argument @var{character-set} is a string, like the inside of a
-@samp{[@dots{}]} in a regular expression except that @samp{]} does not
-terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
-Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
-first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
-the first letter. See @xref{Regular Expressions}. Character classes
-can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}.
-
-If @var{limit} is supplied (it must be a number or a marker), it
-specifies the maximum position in the buffer that point can be skipped
-to. Point will stop at or before @var{limit}.
-
-In the following example, point is initially located directly before the
-@samp{T}. After the form is evaluated, point is located at the end of
-that line (between the @samp{t} of @samp{hat} and the newline). The
-function skips all letters and spaces, but not newlines.
-
-@example
-@group
----------- Buffer: foo ----------
-I read "@point{}The cat in the hat
-comes back" twice.
----------- Buffer: foo ----------
-@end group
-
-@group
-(skip-chars-forward "a-zA-Z ")
- @result{} nil
-
----------- Buffer: foo ----------
-I read "The cat in the hat@point{}
-comes back" twice.
----------- Buffer: foo ----------
-@end group
-@end example
-@end defun
-
-@defun skip-chars-backward character-set &optional limit
-This function moves point backward, skipping characters that match
-@var{character-set}, until @var{limit}. It is just like
-@code{skip-chars-forward} except for the direction of motion.
-
-The return value indicates the distance traveled. It is an integer that
-is zero or less.
-@end defun
-
-@node Excursions
-@section Excursions
-@cindex excursion
-
- It is often useful to move point ``temporarily'' within a localized
-portion of the program, or to switch buffers temporarily. This is
-called an @dfn{excursion}, and it is done with the @code{save-excursion}
-special form. This construct initially remembers the identity of the
-current buffer, and its values of point and the mark, and restores them
-after the completion of the excursion.
-
- The forms for saving and restoring the configuration of windows are
-described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
-Configurations}).
-
-@defspec save-excursion body@dots{}
-@cindex mark excursion
-@cindex point excursion
-The @code{save-excursion} special form saves the identity of the current
-buffer and the values of point and the mark in it, evaluates
-@var{body}, and finally restores the buffer and its saved values of
-point and the mark. All three saved values are restored even in case of
-an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
-
-The @code{save-excursion} special form is the standard way to switch
-buffers or move point within one part of a program and avoid affecting
-the rest of the program. It is used more than 4000 times in the Lisp
-sources of Emacs.
-
-@code{save-excursion} does not save the values of point and the mark for
-other buffers, so changes in other buffers remain in effect after
-@code{save-excursion} exits.
-
-@cindex window excursions
-Likewise, @code{save-excursion} does not restore window-buffer
-correspondences altered by functions such as @code{switch-to-buffer}.
-One way to restore these correspondences, and the selected window, is to
-use @code{save-window-excursion} inside @code{save-excursion}
-(@pxref{Window Configurations}).
-
-The value returned by @code{save-excursion} is the result of the last
-form in @var{body}, or @code{nil} if no body forms were given.
-
-@example
-@group
-(save-excursion @var{forms})
-@equiv{}
-(let ((old-buf (current-buffer))
- (old-pnt (point-marker))
-@end group
- (old-mark (copy-marker (mark-marker))))
- (unwind-protect
- (progn @var{forms})
- (set-buffer old-buf)
-@group
- (goto-char old-pnt)
- (set-marker (mark-marker) old-mark)))
-@end group
-@end example
-@end defspec
-
- @strong{Warning:} Ordinary insertion of text adjacent to the saved
-point value relocates the saved value, just as it relocates all markers.
-More precisely, the saved value is a marker with insertion type
-@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved
-point value is restored, it normally comes before the inserted text.
-
- Although @code{save-excursion} saves the location of the mark, it does
-not prevent functions which modify the buffer from setting
-@code{deactivate-mark}, and thus causing the deactivation of the mark
-after the command finishes. @xref{The Mark}.
-
-@node Narrowing
-@section Narrowing
-@cindex narrowing
-@cindex restriction (in a buffer)
-@cindex accessible portion (of a buffer)
-
- @dfn{Narrowing} means limiting the text addressable by Emacs editing
-commands to a limited range of characters in a buffer. The text that
-remains addressable is called the @dfn{accessible portion} of the
-buffer.
-
- Narrowing is specified with two buffer positions which become the
-beginning and end of the accessible portion. For most editing commands
-and most Emacs primitives, these positions replace the values of the
-beginning and end of the buffer. While narrowing is in effect, no text
-outside the accessible portion is displayed, and point cannot move
-outside the accessible portion.
-
- Values such as positions or line numbers, which usually count from the
-beginning of the buffer, do so despite narrowing, but the functions
-which use them refuse to operate on text that is inaccessible.
-
- The commands for saving buffers are unaffected by narrowing; they save
-the entire buffer regardless of any narrowing.
-
-@deffn Command narrow-to-region start end
-This function sets the accessible portion of the current buffer to start
-at @var{start} and end at @var{end}. Both arguments should be character
-positions.
-
-In an interactive call, @var{start} and @var{end} are set to the bounds
-of the current region (point and the mark, with the smallest first).
-@end deffn
-
-@deffn Command narrow-to-page &optional move-count
-This function sets the accessible portion of the current buffer to
-include just the current page. An optional first argument
-@var{move-count} non-@code{nil} means to move forward or backward by
-@var{move-count} pages and then narrow to one page. The variable
-@code{page-delimiter} specifies where pages start and end
-(@pxref{Standard Regexps}).
-
-In an interactive call, @var{move-count} is set to the numeric prefix
-argument.
-@end deffn
-
-@deffn Command widen
-@cindex widening
-This function cancels any narrowing in the current buffer, so that the
-entire contents are accessible. This is called @dfn{widening}.
-It is equivalent to the following expression:
-
-@example
-(narrow-to-region 1 (1+ (buffer-size)))
-@end example
-@end deffn
-
-@defspec save-restriction body@dots{}
-This special form saves the current bounds of the accessible portion,
-evaluates the @var{body} forms, and finally restores the saved bounds,
-thus restoring the same state of narrowing (or absence thereof) formerly
-in effect. The state of narrowing is restored even in the event of an
-abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
-Therefore, this construct is a clean way to narrow a buffer temporarily.
-
-The value returned by @code{save-restriction} is that returned by the
-last form in @var{body}, or @code{nil} if no body forms were given.
-
-@c Wordy to avoid overfull hbox. --rjc 16mar92
-@strong{Caution:} it is easy to make a mistake when using the
-@code{save-restriction} construct. Read the entire description here
-before you try it.
-
-If @var{body} changes the current buffer, @code{save-restriction} still
-restores the restrictions on the original buffer (the buffer whose
-restrictions it saved from), but it does not restore the identity of the
-current buffer.
-
-@code{save-restriction} does @emph{not} restore point and the mark; use
-@code{save-excursion} for that. If you use both @code{save-restriction}
-and @code{save-excursion} together, @code{save-excursion} should come
-first (on the outside). Otherwise, the old point value would be
-restored with temporary narrowing still in effect. If the old point
-value were outside the limits of the temporary narrowing, this would
-fail to restore it accurately.
-
-Here is a simple example of correct use of @code{save-restriction}:
-
-@example
-@group
----------- Buffer: foo ----------
-This is the contents of foo
-This is the contents of foo
-This is the contents of foo@point{}
----------- Buffer: foo ----------
-@end group
-
-@group
-(save-excursion
- (save-restriction
- (goto-char 1)
- (forward-line 2)
- (narrow-to-region 1 (point))
- (goto-char (point-min))
- (replace-string "foo" "bar")))
-
----------- Buffer: foo ----------
-This is the contents of bar
-This is the contents of bar
-This is the contents of foo@point{}
----------- Buffer: foo ----------
-@end group
-@end example
-@end defspec
-
-@ignore
- arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/processes
-@node Processes, Display, Abbrevs, Top
-@chapter Processes
-@cindex child process
-@cindex parent process
-@cindex subprocess
-@cindex process
-
- In the terminology of operating systems, a @dfn{process} is a space in
-which a program can execute. Emacs runs in a process. Emacs Lisp
-programs can invoke other programs in processes of their own. These are
-called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
-which is their @dfn{parent process}.
-
- A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
-depending on how it is created. When you create a synchronous
-subprocess, the Lisp program waits for the subprocess to terminate
-before continuing execution. When you create an asynchronous
-subprocess, it can run in parallel with the Lisp program. This kind of
-subprocess is represented within Emacs by a Lisp object which is also
-called a ``process.'' Lisp programs can use this object to communicate
-with the subprocess or to control it. For example, you can send
-signals, obtain status information, receive output from the process, or
-send input to it.
-
-@defun processp object
-This function returns @code{t} if @var{object} is a process,
-@code{nil} otherwise.
-@end defun
-
-@menu
-* 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.
-@end menu
-
-@node Subprocess Creation
-@section Functions that Create Subprocesses
-
- There are three functions that create a new subprocess in which to run
-a program. One of them, @code{start-process}, creates an asynchronous
-process and returns a process object (@pxref{Asynchronous Processes}).
-The other two, @code{call-process} and @code{call-process-region},
-create a synchronous process and do not return a process object
-(@pxref{Synchronous Processes}).
-
- Synchronous and asynchronous processes are explained in the following
-sections. Since the three functions are all called in a similar
-fashion, their common arguments are described here.
-
-@cindex execute program
-@cindex @code{PATH} environment variable
-@cindex @code{HOME} environment variable
- In all cases, the function's @var{program} argument specifies the
-program to be run. An error is signaled if the file is not found or
-cannot be executed. If the file name is relative, the variable
-@code{exec-path} contains a list of directories to search. Emacs
-initializes @code{exec-path} when it starts up, based on the value of
-the environment variable @code{PATH}. The standard file name
-constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
-usual in @code{exec-path}, but environment variable substitutions
-(@samp{$HOME}, etc.) are not recognized; use
-@code{substitute-in-file-name} to perform them (@pxref{File Name
-Expansion}). @code{nil} in this list refers to
-@code{default-directory}.
-
- Executing a program can also try adding suffixes to the specified
-name:
-
-@defvar exec-suffixes
-This variable is a list of suffixes (strings) to try adding to the
-specified program file name. The list should include @code{""} if you
-want the name to be tried exactly as specified. The default value is
-system-dependent.
-@end defvar
-
- @strong{Please note:} The argument @var{program} contains only the
-name of the program; it may not contain any command-line arguments. You
-must use @var{args} to provide those.
-
- Each of the subprocess-creating functions has a @var{buffer-or-name}
-argument which specifies where the standard output from the program will
-go. It should be a buffer or a buffer name; if it is a buffer name,
-that will create the buffer if it does not already exist. It can also
-be @code{nil}, which says to discard the output unless a filter function
-handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
-Normally, you should avoid having multiple processes send output to the
-same buffer because their output would be intermixed randomly.
-
-@cindex program arguments
- All three of the subprocess-creating functions have a @code{&rest}
-argument, @var{args}. The @var{args} must all be strings, and they are
-supplied to @var{program} as separate command line arguments. Wildcard
-characters and other shell constructs have no special meanings in these
-strings, since the strings are passed directly to the specified program.
-
- The subprocess gets its current directory from the value of
-@code{default-directory} (@pxref{File Name Expansion}).
-
-@cindex environment variables, subprocesses
- The subprocess inherits its environment from Emacs, but you can
-specify overrides for it with @code{process-environment}. @xref{System
-Environment}.
-
-@defvar exec-directory
-@pindex movemail
-The value of this variable is a string, the name of a directory that
-contains programs that come with GNU Emacs, programs intended for Emacs
-to invoke. The program @code{movemail} is an example of such a program;
-Rmail uses it to fetch new mail from an inbox.
-@end defvar
-
-@defopt exec-path
-The value of this variable is a list of directories to search for
-programs to run in subprocesses. Each element is either the name of a
-directory (i.e., a string), or @code{nil}, which stands for the default
-directory (which is the value of @code{default-directory}).
-@cindex program directories
-
-The value of @code{exec-path} is used by @code{call-process} and
-@code{start-process} when the @var{program} argument is not an absolute
-file name.
-@end defopt
-
-@node Shell Arguments
-@section Shell Arguments
-@cindex arguments for shell commands
-@cindex shell command arguments
-
- Lisp programs sometimes need to run a shell and give it a command
-that contains file names that were specified by the user. These
-programs ought to be able to support any valid file name. But the shell
-gives special treatment to certain characters, and if these characters
-occur in the file name, they will confuse the shell. To handle these
-characters, use the function @code{shell-quote-argument}:
-
-@defun shell-quote-argument argument
-This function returns a string which represents, in shell syntax,
-an argument whose actual contents are @var{argument}. It should
-work reliably to concatenate the return value into a shell command
-and then pass it to a shell for execution.
-
-Precisely what this function does depends on your operating system. The
-function is designed to work with the syntax of your system's standard
-shell; if you use an unusual shell, you will need to redefine this
-function.
-
-@example
-;; @r{This example shows the behavior on GNU and Unix systems.}
-(shell-quote-argument "foo > bar")
- @result{} "foo\\ \\>\\ bar"
-
-;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
-(shell-quote-argument "foo > bar")
- @result{} "\"foo > bar\""
-@end example
-
-Here's an example of using @code{shell-quote-argument} to construct
-a shell command:
-
-@example
-(concat "diff -c "
- (shell-quote-argument oldfile)
- " "
- (shell-quote-argument newfile))
-@end example
-@end defun
-
-@node Synchronous Processes
-@section Creating a Synchronous Process
-@cindex synchronous subprocess
-
- After a @dfn{synchronous process} is created, Emacs waits for the
-process to terminate before continuing. Starting Dired on GNU or
-Unix@footnote{On other systems, Emacs uses a Lisp emulation of
-@code{ls}; see @ref{Contents of Directories}.} is an example of this: it
-runs @code{ls} in a synchronous process, then modifies the output
-slightly. Because the process is synchronous, the entire directory
-listing arrives in the buffer before Emacs tries to do anything with it.
-
- While Emacs waits for the synchronous subprocess to terminate, the
-user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
-the subprocess with a @code{SIGINT} signal; but it waits until the
-subprocess actually terminates before quitting. If during that time the
-user types another @kbd{C-g}, that kills the subprocess instantly with
-@code{SIGKILL} and quits immediately (except on MS-DOS, where killing
-other processes doesn't work). @xref{Quitting}.
-
- The synchronous subprocess functions return an indication of how the
-process terminated.
-
- The output from a synchronous subprocess is generally decoded using a
-coding system, much like text read from a file. The input sent to a
-subprocess by @code{call-process-region} is encoded using a coding
-system, much like text written into a file. @xref{Coding Systems}.
-
-@defun call-process program &optional infile destination display &rest args
-This function calls @var{program} in a separate process and waits for
-it to finish.
-
-The standard input for the process comes from file @var{infile} if
-@var{infile} is not @code{nil}, and from the null device otherwise.
-The argument @var{destination} says where to put the process output.
-Here are the possibilities:
-
-@table @asis
-@item a buffer
-Insert the output in that buffer, before point. This includes both the
-standard output stream and the standard error stream of the process.
-
-@item a string
-Insert the output in a buffer with that name, before point.
-
-@item @code{t}
-Insert the output in the current buffer, before point.
-
-@item @code{nil}
-Discard the output.
-
-@item 0
-Discard the output, and return @code{nil} immediately without waiting
-for the subprocess to finish.
-
-In this case, the process is not truly synchronous, since it can run in
-parallel with Emacs; but you can think of it as synchronous in that
-Emacs is essentially finished with the subprocess as soon as this
-function returns.
-
-MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
-work there.
-
-@item @code{(@var{real-destination} @var{error-destination})}
-Keep the standard output stream separate from the standard error stream;
-deal with the ordinary output as specified by @var{real-destination},
-and dispose of the error output according to @var{error-destination}.
-If @var{error-destination} is @code{nil}, that means to discard the
-error output, @code{t} means mix it with the ordinary output, and a
-string specifies a file name to redirect error output into.
-
-You can't directly specify a buffer to put the error output in; that is
-too difficult to implement. But you can achieve this result by sending
-the error output to a temporary file and then inserting the file into a
-buffer.
-@end table
-
-If @var{display} is non-@code{nil}, then @code{call-process} redisplays
-the buffer as output is inserted. (However, if the coding system chosen
-for decoding output is @code{undecided}, meaning deduce the encoding
-from the actual data, then redisplay sometimes cannot continue once
-non-@acronym{ASCII} characters are encountered. There are fundamental
-reasons why it is hard to fix this; see @ref{Output from Processes}.)
-
-Otherwise the function @code{call-process} does no redisplay, and the
-results become visible on the screen only when Emacs redisplays that
-buffer in the normal course of events.
-
-The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
-
-The value returned by @code{call-process} (unless you told it not to
-wait) indicates the reason for process termination. A number gives the
-exit status of the subprocess; 0 means success, and any other value
-means failure. If the process terminated with a signal,
-@code{call-process} returns a string describing the signal.
-
-In the examples below, the buffer @samp{foo} is current.
-
-@smallexample
-@group
-(call-process "pwd" nil t)
- @result{} 0
-
----------- Buffer: foo ----------
-/usr/user/lewis/manual
----------- Buffer: foo ----------
-@end group
-
-@group
-(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
- @result{} 0
-
----------- Buffer: bar ----------
-lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
-
----------- Buffer: bar ----------
-@end group
-@end smallexample
-
-Here is a good example of the use of @code{call-process}, which used to
-be found in the definition of @code{insert-directory}:
-
-@smallexample
-@group
-(call-process insert-directory-program nil t nil @var{switches}
- (if full-directory-p
- (concat (file-name-as-directory file) ".")
- file))
-@end group
-@end smallexample
-@end defun
-
-@defun process-file program &optional infile buffer display &rest args
-This function processes files synchronously in a separate process. It
-is similar to @code{call-process} but may invoke a file handler based
-on the value of the variable @code{default-directory}. The current
-working directory of the subprocess is @code{default-directory}.
-
-The arguments are handled in almost the same way as for
-@code{call-process}, with the following differences:
-
-Some file handlers may not support all combinations and forms of the
-arguments @var{infile}, @var{buffer}, and @var{display}. For example,
-some file handlers might behave as if @var{display} were @code{nil},
-regardless of the value actually passed. As another example, some
-file handlers might not support separating standard output and error
-output by way of the @var{buffer} argument.
-
-If a file handler is invoked, it determines the program to run based
-on the first argument @var{program}. For instance, consider that a
-handler for remote files is invoked. Then the path that is used for
-searching the program might be different than @code{exec-path}.
-
-The second argument @var{infile} may invoke a file handler. The file
-handler could be different from the handler chosen for the
-@code{process-file} function itself. (For example,
-@code{default-directory} could be on a remote host, whereas
-@var{infile} is on another remote host. Or @code{default-directory}
-could be non-special, whereas @var{infile} is on a remote host.)
-
-If @var{buffer} is a list of the form @code{(@var{real-destination}
-@var{error-destination})}, and @var{error-destination} names a file,
-then the same remarks as for @var{infile} apply.
-
-The remaining arguments (@var{args}) will be passed to the process
-verbatim. Emacs is not involved in processing file names that are
-present in @var{args}. To avoid confusion, it may be best to avoid
-absolute file names in @var{args}, but rather to specify all file
-names as relative to @code{default-directory}. The function
-@code{file-relative-name} is useful for constructing such relative
-file names.
-@end defun
-
-@defun call-process-region start end program &optional delete destination display &rest args
-This function sends the text from @var{start} to @var{end} as
-standard input to a process running @var{program}. It deletes the text
-sent if @var{delete} is non-@code{nil}; this is useful when
-@var{destination} is @code{t}, to insert the output in the current
-buffer in place of the input.
-
-The arguments @var{destination} and @var{display} control what to do
-with the output from the subprocess, and whether to update the display
-as it comes in. For details, see the description of
-@code{call-process}, above. If @var{destination} is the integer 0,
-@code{call-process-region} discards the output and returns @code{nil}
-immediately, without waiting for the subprocess to finish (this only
-works if asynchronous subprocesses are supported).
-
-The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
-
-The return value of @code{call-process-region} is just like that of
-@code{call-process}: @code{nil} if you told it to return without
-waiting; otherwise, a number or string which indicates how the
-subprocess terminated.
-
-In the following example, we use @code{call-process-region} to run the
-@code{cat} utility, with standard input being the first five characters
-in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
-standard input into its standard output. Since the argument
-@var{destination} is @code{t}, this output is inserted in the current
-buffer.
-
-@smallexample
-@group
----------- Buffer: foo ----------
-input@point{}
----------- Buffer: foo ----------
-@end group
-
-@group
-(call-process-region 1 6 "cat" nil t)
- @result{} 0
-
----------- Buffer: foo ----------
-inputinput@point{}
----------- Buffer: foo ----------
-@end group
-@end smallexample
-
- The @code{shell-command-on-region} command uses
-@code{call-process-region} like this:
-
-@smallexample
-@group
-(call-process-region
- start end
- shell-file-name ; @r{Name of program.}
- nil ; @r{Do not delete region.}
- buffer ; @r{Send output to @code{buffer}.}
- nil ; @r{No redisplay during output.}
- "-c" command) ; @r{Arguments for the shell.}
-@end group
-@end smallexample
-@end defun
-
-@defun call-process-shell-command command &optional infile destination display &rest args
-This function executes the shell command @var{command} synchronously
-in a separate process. The final arguments @var{args} are additional
-arguments to add at the end of @var{command}. The other arguments
-are handled as in @code{call-process}.
-@end defun
-
-@defun process-file-shell-command command &optional infile destination display &rest args
-This function is like @code{call-process-shell-command}, but uses
-@code{process-file} internally. Depending on @code{default-directory},
-@var{command} can be executed also on remote hosts.
-@end defun
-
-@defun shell-command-to-string command
-This function executes @var{command} (a string) as a shell command,
-then returns the command's output as a string.
-@end defun
-
-@node Asynchronous Processes
-@section Creating an Asynchronous Process
-@cindex asynchronous subprocess
-
- After an @dfn{asynchronous process} is created, Emacs and the subprocess
-both continue running immediately. The process thereafter runs
-in parallel with Emacs, and the two can communicate with each other
-using the functions described in the following sections. However,
-communication is only partially asynchronous: Emacs sends data to the
-process only when certain functions are called, and Emacs accepts data
-from the process only when Emacs is waiting for input or for a time
-delay.
-
- Here we describe how to create an asynchronous process.
-
-@defun start-process name buffer-or-name program &rest args
-This function creates a new asynchronous subprocess and starts the
-program @var{program} running in it. It returns a process object that
-stands for the new subprocess in Lisp. The argument @var{name}
-specifies the name for the process object; if a process with this name
-already exists, then @var{name} is modified (by appending @samp{<1>},
-etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
-associate with the process.
-
-The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
-
-In the example below, the first process is started and runs (rather,
-sleeps) for 100 seconds. Meanwhile, the second process is started, and
-given the name @samp{my-process<1>} for the sake of uniqueness. It
-inserts the directory listing at the end of the buffer @samp{foo},
-before the first process finishes. Then it finishes, and a message to
-that effect is inserted in the buffer. Much later, the first process
-finishes, and another message is inserted in the buffer for it.
-
-@smallexample
-@group
-(start-process "my-process" "foo" "sleep" "100")
- @result{} #<process my-process>
-@end group
-
-@group
-(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
- @result{} #<process my-process<1>>
-
----------- Buffer: foo ----------
-total 2
-lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
--rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
-
-Process my-process<1> finished
-
-Process my-process finished
----------- Buffer: foo ----------
-@end group
-@end smallexample
-@end defun
-
-@defun start-file-process name buffer-or-name program &rest args
-Like @code{start-process}, this function starts a new asynchronous
-subprocess running @var{program} in it, and returns its process
-object---when @code{default-directory} is not a magic file name.
-
-If @code{default-directory} is magic, the function invokes its file
-handler instead. This handler ought to run @var{program}, perhaps on
-the local host, perhaps on a remote host that corresponds to
-@code{default-directory}. In the latter case, the local part of
-@code{default-directory} becomes the working directory of the process.
-
-This function does not try to invoke file name handlers for
-@var{program} or for the @var{program-args}.
-
-Depending on the implementation of the file handler, it might not be
-possible to apply @code{process-filter} or @code{process-sentinel} to
-the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
-
-Some file handlers may not support @code{start-file-process} (for
-example @code{ange-ftp-hook-function}). In such cases, the function
-does nothing and returns @code{nil}.
-@end defun
-
-@defun start-process-shell-command name buffer-or-name command &rest command-args
-This function is like @code{start-process} except that it uses a shell
-to execute the specified command. The argument @var{command} is a shell
-command name, and @var{command-args} are the arguments for the shell
-command. The variable @code{shell-file-name} specifies which shell to
-use.
-
-The point of running a program through the shell, rather than directly
-with @code{start-process}, is so that you can employ shell features such
-as wildcards in the arguments. It follows that if you include an
-arbitrary user-specified arguments in the command, you should quote it
-with @code{shell-quote-argument} first, so that any special shell
-characters do @emph{not} have their special shell meanings. @xref{Shell
-Arguments}.
-@end defun
-
-@defun start-file-process-shell-command name buffer-or-name command &rest command-args
-This function is like @code{start-process-shell-command}, but uses
-@code{start-file-process} internally. By this, @var{command} can be
-executed also on remote hosts, depending on @code{default-directory}.
-@end defun
-
-@defvar process-connection-type
-@cindex pipes
-@cindex @acronym{PTY}s
-This variable controls the type of device used to communicate with
-asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
-used, when available. Otherwise, pipes are used.
-
-@acronym{PTY}s are usually preferable for processes visible to the user, as
-in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
-etc.) to work between the process and its children, whereas pipes do
-not. For subprocesses used for internal purposes by programs, it is
-often better to use a pipe, because they are more efficient. In
-addition, the total number of @acronym{PTY}s is limited on many systems and
-it is good not to waste them.
-
-The value of @code{process-connection-type} takes effect when
-@code{start-process} is called. So you can specify how to communicate
-with one subprocess by binding the variable around the call to
-@code{start-process}.
-
-@smallexample
-@group
-(let ((process-connection-type nil)) ; @r{Use a pipe.}
- (start-process @dots{}))
-@end group
-@end smallexample
-
-To determine whether a given subprocess actually got a pipe or a
-@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
-Information}).
-@end defvar
-
-@node Deleting Processes
-@section Deleting Processes
-@cindex deleting processes
-
- @dfn{Deleting a process} disconnects Emacs immediately from the
-subprocess. Processes are deleted automatically after they terminate,
-but not necessarily right away. You can delete a process explicitly
-at any time. If you delete a terminated process explicitly before it
-is deleted automatically, no harm results. Deleting a running
-process sends a signal to terminate it (and its child processes if
-any), and calls the process sentinel if it has one. @xref{Sentinels}.
-
- When a process is deleted, the process object itself continues to
-exist as long as other Lisp objects point to it. All the Lisp
-primitives that work on process objects accept deleted processes, but
-those that do I/O or send signals will report an error. The process
-mark continues to point to the same place as before, usually into a
-buffer where output from the process was being inserted.
-
-@defopt delete-exited-processes
-This variable controls automatic deletion of processes that have
-terminated (due to calling @code{exit} or to a signal). If it is
-@code{nil}, then they continue to exist until the user runs
-@code{list-processes}. Otherwise, they are deleted immediately after
-they exit.
-@end defopt
-
-@defun delete-process process
-This function deletes a process, killing it with a @code{SIGKILL}
-signal. The argument may be a process, the name of a process, a
-buffer, or the name of a buffer. (A buffer or buffer-name stands for
-the process that @code{get-buffer-process} returns.) Calling
-@code{delete-process} on a running process terminates it, updates the
-process status, and runs the sentinel (if any) immediately. If the
-process has already terminated, calling @code{delete-process} has no
-effect on its status, or on the running of its sentinel (which will
-happen sooner or later).
-
-@smallexample
-@group
-(delete-process "*shell*")
- @result{} nil
-@end group
-@end smallexample
-@end defun
-
-@node Process Information
-@section Process Information
-
- Several functions return information about processes.
-@code{list-processes} is provided for interactive use.
-
-@deffn Command list-processes &optional query-only
-This command displays a listing of all living processes. In addition,
-it finally deletes any process whose status was @samp{Exited} or
-@samp{Signaled}. It returns @code{nil}.
-
-If @var{query-only} is non-@code{nil} then it lists only processes
-whose query flag is non-@code{nil}. @xref{Query Before Exit}.
-@end deffn
-
-@defun process-list
-This function returns a list of all processes that have not been deleted.
-
-@smallexample
-@group
-(process-list)
- @result{} (#<process display-time> #<process shell>)
-@end group
-@end smallexample
-@end defun
-
-@defun get-process name
-This function returns the process named @var{name}, or @code{nil} if
-there is none. An error is signaled if @var{name} is not a string.
-
-@smallexample
-@group
-(get-process "shell")
- @result{} #<process shell>
-@end group
-@end smallexample
-@end defun
-
-@defun process-command process
-This function returns the command that was executed to start
-@var{process}. This is a list of strings, the first string being the
-program executed and the rest of the strings being the arguments that
-were given to the program.
-
-@smallexample
-@group
-(process-command (get-process "shell"))
- @result{} ("/bin/csh" "-i")
-@end group
-@end smallexample
-@end defun
-
-@defun process-id process
-This function returns the @acronym{PID} of @var{process}. This is an
-integer that distinguishes the process @var{process} from all other
-processes running on the same computer at the current time. The
-@acronym{PID} of a process is chosen by the operating system kernel when the
-process is started and remains constant as long as the process exists.
-@end defun
-
-@defun process-name process
-This function returns the name of @var{process}.
-@end defun
-
-@defun process-status process-name
-This function returns the status of @var{process-name} as a symbol.
-The argument @var{process-name} must be a process, a buffer, a
-process name (string) or a buffer name (string).
-
-The possible values for an actual subprocess are:
-
-@table @code
-@item run
-for a process that is running.
-@item stop
-for a process that is stopped but continuable.
-@item exit
-for a process that has exited.
-@item signal
-for a process that has received a fatal signal.
-@item open
-for a network connection that is open.
-@item closed
-for a network connection that is closed. Once a connection
-is closed, you cannot reopen it, though you might be able to open
-a new connection to the same place.
-@item connect
-for a non-blocking connection that is waiting to complete.
-@item failed
-for a non-blocking connection that has failed to complete.
-@item listen
-for a network server that is listening.
-@item nil
-if @var{process-name} is not the name of an existing process.
-@end table
-
-@smallexample
-@group
-(process-status "shell")
- @result{} run
-@end group
-@group
-(process-status (get-buffer "*shell*"))
- @result{} run
-@end group
-@group
-x
- @result{} #<process xx<1>>
-(process-status x)
- @result{} exit
-@end group
-@end smallexample
-
-For a network connection, @code{process-status} returns one of the symbols
-@code{open} or @code{closed}. The latter means that the other side
-closed the connection, or Emacs did @code{delete-process}.
-@end defun
-
-@defun process-exit-status process
-This function returns the exit status of @var{process} or the signal
-number that killed it. (Use the result of @code{process-status} to
-determine which of those it is.) If @var{process} has not yet
-terminated, the value is 0.
-@end defun
-
-@defun process-tty-name process
-This function returns the terminal name that @var{process} is using for
-its communication with Emacs---or @code{nil} if it is using pipes
-instead of a terminal (see @code{process-connection-type} in
-@ref{Asynchronous Processes}).
-@end defun
-
-@defun process-coding-system process
-@anchor{Coding systems for a subprocess}
-This function returns a cons cell describing the coding systems in use
-for decoding output from @var{process} and for encoding input to
-@var{process} (@pxref{Coding Systems}). The value has this form:
-
-@example
-(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
-@end example
-@end defun
-
-@defun set-process-coding-system process &optional decoding-system encoding-system
-This function specifies the coding systems to use for subsequent output
-from and input to @var{process}. It will use @var{decoding-system} to
-decode subprocess output, and @var{encoding-system} to encode subprocess
-input.
-@end defun
-
- Every process also has a property list that you can use to store
-miscellaneous values associated with the process.
-
-@defun process-get process propname
-This function returns the value of the @var{propname} property
-of @var{process}.
-@end defun
-
-@defun process-put process propname value
-This function sets the value of the @var{propname} property
-of @var{process} to @var{value}.
-@end defun
-
-@defun process-plist process
-This function returns the process plist of @var{process}.
-@end defun
-
-@defun set-process-plist process plist
-This function sets the process plist of @var{process} to @var{plist}.
-@end defun
-
-@node Input to Processes
-@section Sending Input to Processes
-@cindex process input
-
- Asynchronous subprocesses receive input when it is sent to them by
-Emacs, which is done with the functions in this section. You must
-specify the process to send input to, and the input data to send. The
-data appears on the ``standard input'' of the subprocess.
-
- Some operating systems have limited space for buffered input in a
-@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
-periodically amidst the other characters, to force them through. For
-most programs, these @acronym{EOF}s do no harm.
-
- Subprocess input is normally encoded using a coding system before the
-subprocess receives it, much like text written into a file. You can use
-@code{set-process-coding-system} to specify which coding system to use
-(@pxref{Process Information}). Otherwise, the coding system comes from
-@code{coding-system-for-write}, if that is non-@code{nil}; or else from
-the defaulting mechanism (@pxref{Default Coding Systems}).
-
- Sometimes the system is unable to accept input for that process,
-because the input buffer is full. When this happens, the send functions
-wait a short while, accepting output from subprocesses, and then try
-again. This gives the subprocess a chance to read more of its pending
-input and make space in the buffer. It also allows filters, sentinels
-and timers to run---so take account of that in writing your code.
-
- In these functions, the @var{process} argument can be a process or
-the name of a process, or a buffer or buffer name (which stands
-for a process via @code{get-buffer-process}). @code{nil} means
-the current buffer's process.
-
-@defun process-send-string process string
-This function sends @var{process} the contents of @var{string} as
-standard input. If it is @code{nil}, the current buffer's process is used.
-
- The function returns @code{nil}.
-
-@smallexample
-@group
-(process-send-string "shell<1>" "ls\n")
- @result{} nil
-@end group
-
-
-@group
----------- Buffer: *shell* ----------
-...
-introduction.texi syntax-tables.texi~
-introduction.texi~ text.texi
-introduction.txt text.texi~
-...
----------- Buffer: *shell* ----------
-@end group
-@end smallexample
-@end defun
-
-@defun process-send-region process start end
-This function sends the text in the region defined by @var{start} and
-@var{end} as standard input to @var{process}.
-
-An error is signaled unless both @var{start} and @var{end} are
-integers or markers that indicate positions in the current buffer. (It
-is unimportant which number is larger.)
-@end defun
-
-@defun process-send-eof &optional process
-This function makes @var{process} see an end-of-file in its
-input. The @acronym{EOF} comes after any text already sent to it.
-
-The function returns @var{process}.
-
-@smallexample
-@group
-(process-send-eof "shell")
- @result{} "shell"
-@end group
-@end smallexample
-@end defun
-
-@defun process-running-child-p process
-This function will tell you whether a subprocess has given control of
-its terminal to its own child process. The value is @code{t} if this is
-true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
-that this is not so.
-@end defun
-
-@node Signals to Processes
-@section Sending Signals to Processes
-@cindex process signals
-@cindex sending signals
-@cindex signals
-
- @dfn{Sending a signal} to a subprocess is a way of interrupting its
-activities. There are several different signals, each with its own
-meaning. The set of signals and their names is defined by the operating
-system. For example, the signal @code{SIGINT} means that the user has
-typed @kbd{C-c}, or that some analogous thing has happened.
-
- Each signal has a standard effect on the subprocess. Most signals
-kill the subprocess, but some stop or resume execution instead. Most
-signals can optionally be handled by programs; if the program handles
-the signal, then we can say nothing in general about its effects.
-
- You can send signals explicitly by calling the functions in this
-section. Emacs also sends signals automatically at certain times:
-killing a buffer sends a @code{SIGHUP} signal to all its associated
-processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
-processes. (@code{SIGHUP} is a signal that usually indicates that the
-user hung up the phone.)
-
- Each of the signal-sending functions takes two optional arguments:
-@var{process} and @var{current-group}.
-
- The argument @var{process} must be either a process, a process
-name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
-stands for a process through @code{get-buffer-process}. @code{nil}
-stands for the process associated with the current buffer. An error
-is signaled if @var{process} does not identify a process.
-
- The argument @var{current-group} is a flag that makes a difference
-when you are running a job-control shell as an Emacs subprocess. If it
-is non-@code{nil}, then the signal is sent to the current process-group
-of the terminal that Emacs uses to communicate with the subprocess. If
-the process is a job-control shell, this means the shell's current
-subjob. If it is @code{nil}, the signal is sent to the process group of
-the immediate subprocess of Emacs. If the subprocess is a job-control
-shell, this is the shell itself.
-
- The flag @var{current-group} has no effect when a pipe is used to
-communicate with the subprocess, because the operating system does not
-support the distinction in the case of pipes. For the same reason,
-job-control shells won't work when a pipe is used. See
-@code{process-connection-type} in @ref{Asynchronous Processes}.
-
-@defun interrupt-process &optional process current-group
-This function interrupts the process @var{process} by sending the
-signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
-character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
-others) sends this signal. When the argument @var{current-group} is
-non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
-on the terminal by which Emacs talks to the subprocess.
-@end defun
-
-@defun kill-process &optional process current-group
-This function kills the process @var{process} by sending the
-signal @code{SIGKILL}. This signal kills the subprocess immediately,
-and cannot be handled by the subprocess.
-@end defun
-
-@defun quit-process &optional process current-group
-This function sends the signal @code{SIGQUIT} to the process
-@var{process}. This signal is the one sent by the ``quit
-character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
-Emacs.
-@end defun
-
-@defun stop-process &optional process current-group
-This function stops the process @var{process} by sending the
-signal @code{SIGTSTP}. Use @code{continue-process} to resume its
-execution.
-
-Outside of Emacs, on systems with job control, the ``stop character''
-(usually @kbd{C-z}) normally sends this signal. When
-@var{current-group} is non-@code{nil}, you can think of this function as
-``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
-subprocess.
-@end defun
-
-@defun continue-process &optional process current-group
-This function resumes execution of the process @var{process} by sending
-it the signal @code{SIGCONT}. This presumes that @var{process} was
-stopped previously.
-@end defun
-
-@c Emacs 19 feature
-@defun signal-process process signal
-This function sends a signal to process @var{process}. The argument
-@var{signal} specifies which signal to send; it should be an integer.
-
-The @var{process} argument can be a system process @acronym{ID}; that
-allows you to send signals to processes that are not children of
-Emacs.
-@end defun
-
-@node Output from Processes
-@section Receiving Output from Processes
-@cindex process output
-@cindex output from processes
-
- There are two ways to receive the output that a subprocess writes to
-its standard output stream. The output can be inserted in a buffer,
-which is called the associated buffer of the process, or a function
-called the @dfn{filter function} can be called to act on the output. If
-the process has no buffer and no filter function, its output is
-discarded.
-
- When a subprocess terminates, Emacs reads any pending output,
-then stops reading output from that subprocess. Therefore, if the
-subprocess has children that are still live and still producing
-output, Emacs won't receive that output.
-
- Output from a subprocess can arrive only while Emacs is waiting: when
-reading terminal input, in @code{sit-for} and @code{sleep-for}
-(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
-Output}). This minimizes the problem of timing errors that usually
-plague parallel programming. For example, you can safely create a
-process and only then specify its buffer or filter function; no output
-can arrive before you finish, if the code in between does not call any
-primitive that waits.
-
-@defvar process-adaptive-read-buffering
-On some systems, when Emacs reads the output from a subprocess, the
-output data is read in very small blocks, potentially resulting in
-very poor performance. This behavior can be remedied to some extent
-by setting the variable @var{process-adaptive-read-buffering} to a
-non-@code{nil} value (the default), as it will automatically delay reading
-from such processes, thus allowing them to produce more output before
-Emacs tries to read it.
-@end defvar
-
- It is impossible to separate the standard output and standard error
-streams of the subprocess, because Emacs normally spawns the subprocess
-inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
-you want to keep the output to those streams separate, you should
-redirect one of them to a file---for example, by using an appropriate
-shell command.
-
-@menu
-* 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.
-@end menu
-
-@node Process Buffers
-@subsection Process Buffers
-
- A process can (and usually does) have an @dfn{associated buffer},
-which is an ordinary Emacs buffer that is used for two purposes: storing
-the output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into Emacs Lisp.
-
- Unless the process has a filter function (@pxref{Filter Functions}),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the @code{process-mark}, which is then
-updated to point to the end of the text just inserted. Usually, but not
-always, the @code{process-mark} is at the end of the buffer.
-
-@defun process-buffer process
-This function returns the associated buffer of the process
-@var{process}.
-
-@smallexample
-@group
-(process-buffer (get-process "shell"))
- @result{} #<buffer *shell*>
-@end group
-@end smallexample
-@end defun
-
-@defun process-mark process
-This function returns the process marker for @var{process}, which is the
-marker that says where to insert output from the process.
-
-If @var{process} does not have a buffer, @code{process-mark} returns a
-marker that points nowhere.
-
-Insertion of process output in a buffer uses this marker to decide where
-to insert, and updates it to point after the inserted text. That is why
-successive batches of output are inserted consecutively.
-
-Filter functions normally should use this marker in the same fashion
-as is done by direct insertion of output in the buffer. A good
-example of a filter function that uses @code{process-mark} is found at
-the end of the following section.
-
-When the user is expected to enter input in the process buffer for
-transmission to the process, the process marker separates the new input
-from previous output.
-@end defun
-
-@defun set-process-buffer process buffer
-This function sets the buffer associated with @var{process} to
-@var{buffer}. If @var{buffer} is @code{nil}, the process becomes
-associated with no buffer.
-@end defun
-
-@defun get-buffer-process buffer-or-name
-This function returns a nondeleted process associated with the buffer
-specified by @var{buffer-or-name}. If there are several processes
-associated with it, this function chooses one (currently, the one most
-recently created, but don't count on that). Deletion of a process
-(see @code{delete-process}) makes it ineligible for this function to
-return.
-
-It is usually a bad idea to have more than one process associated with
-the same buffer.
-
-@smallexample
-@group
-(get-buffer-process "*shell*")
- @result{} #<process shell>
-@end group
-@end smallexample
-
-Killing the process's buffer deletes the process, which kills the
-subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
-@end defun
-
-@node Filter Functions
-@subsection Process Filter Functions
-@cindex filter function
-@cindex process filter
-
- A process @dfn{filter function} is a function that receives the
-standard output from the associated process. If a process has a filter,
-then @emph{all} output from that process is passed to the filter. The
-process buffer is used directly for output from the process only when
-there is no filter.
-
- The filter function can only be called when Emacs is waiting for
-something, because process output arrives only at such times. Emacs
-waits when reading terminal input, in @code{sit-for} and
-@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
-(@pxref{Accepting Output}).
-
- A filter function must accept two arguments: the associated process
-and a string, which is output just received from it. The function is
-then free to do whatever it chooses with the output.
-
- Quitting is normally inhibited within a filter function---otherwise,
-the effect of typing @kbd{C-g} at command level or to quit a user
-command would be unpredictable. If you want to permit quitting inside
-a filter function, bind @code{inhibit-quit} to @code{nil}. In most
-cases, the right way to do this is with the macro
-@code{with-local-quit}. @xref{Quitting}.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function was started. However, if
-@code{debug-on-error} is non-@code{nil}, the error-catching is turned
-off. This makes it possible to use the Lisp debugger to debug the
-filter function. @xref{Debugger}.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of Emacs when there is no
-filter. Such filter functions need to use @code{set-buffer} in order to
-be sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must save and restore the
-current buffer. They should also update the process marker, and in some
-cases update the value of point. Here is how to do these things:
-
-@smallexample
-@group
-(defun ordinary-insertion-filter (proc string)
- (with-current-buffer (process-buffer proc)
- (let ((moving (= (point) (process-mark proc))))
-@end group
-@group
- (save-excursion
- ;; @r{Insert the text, advancing the process marker.}
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))))
-@end group
-@end smallexample
-
-@noindent
-The reason to use @code{with-current-buffer}, rather than using
-@code{save-excursion} to save and restore the current buffer, is so as
-to preserve the change in point made by the second call to
-@code{goto-char}.
-
- To make the filter force the process buffer to be visible whenever new
-text arrives, insert the following line just before the
-@code{with-current-buffer} construct:
-
-@smallexample
-(display-buffer (process-buffer proc))
-@end smallexample
-
- To force point to the end of the new output, no matter where it was
-previously, eliminate the variable @code{moving} and call
-@code{goto-char} unconditionally.
-
- In earlier Emacs versions, every filter function that did regular
-expression searching or matching had to explicitly save and restore the
-match data. Now Emacs does this automatically for filter functions;
-they never need to do it explicitly. @xref{Match Data}.
-
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. The expression
-@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
-if the buffer is dead.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch of
-200 characters one time, and five batches of 40 characters the next. If
-the filter looks for certain text strings in the subprocess output, make
-sure to handle the case where one of these strings is split across two
-or more batches of output.
-
-@defun set-process-filter process filter
-This function gives @var{process} the filter function @var{filter}. If
-@var{filter} is @code{nil}, it gives the process no filter.
-@end defun
-
-@defun process-filter process
-This function returns the filter function of @var{process}, or @code{nil}
-if it has none.
-@end defun
-
- Here is an example of use of a filter function:
-
-@smallexample
-@group
-(defun keep-output (process output)
- (setq kept (cons output kept)))
- @result{} keep-output
-@end group
-@group
-(setq kept nil)
- @result{} nil
-@end group
-@group
-(set-process-filter (get-process "shell") 'keep-output)
- @result{} keep-output
-@end group
-@group
-(process-send-string "shell" "ls ~/other\n")
- @result{} nil
-kept
- @result{} ("lewis@@slug[8] % "
-@end group
-@group
-"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
-address.txt backup.psf kolstad.psf
-backup.bib~ david.mss resume-Dec-86.mss~
-backup.err david.psf resume-Dec.psf
-backup.mss dland syllabus.mss
-"
-"#backups.mss# backup.mss~ kolstad.mss
-")
-@end group
-@end smallexample
-
-@ignore @c The code in this example doesn't show the right way to do things.
-Here is another, more realistic example, which demonstrates how to use
-the process mark to do insertion in the same fashion as is done when
-there is no filter function:
-
-@smallexample
-@group
-;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
-;; @r{and make sure that buffer is shown in some window.}
-(defun my-process-filter (proc str)
- (let ((cur (selected-window))
- (pop-up-windows t))
- (pop-to-buffer my-shell-buffer)
-@end group
-@group
- (goto-char (point-max))
- (insert str)
- (set-marker (process-mark proc) (point-max))
- (select-window cur)))
-@end group
-@end smallexample
-@end ignore
-
-@node Decoding Output
-@subsection Decoding Process Output
-@cindex decode process output
-
- When Emacs writes process output directly into a multibyte buffer,
-it decodes the output according to the process output coding system.
-If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
-converts the unibyte output to multibyte using
-@code{string-to-multibyte}, and inserts the resulting multibyte text.
-
- You can use @code{set-process-coding-system} to specify which coding
-system to use (@pxref{Process Information}). Otherwise, the coding
-system comes from @code{coding-system-for-read}, if that is
-non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
-Coding Systems}).
-
- @strong{Warning:} Coding systems such as @code{undecided} which
-determine the coding system from the data do not work entirely
-reliably with asynchronous subprocess output. This is because Emacs
-has to process asynchronous subprocess output in batches, as it
-arrives. Emacs must try to detect the proper coding system from one
-batch at a time, and this does not always work. Therefore, if at all
-possible, specify a coding system that determines both the character
-code conversion and the end of line conversion---that is, one like
-@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
-
-@cindex filter multibyte flag, of process
-@cindex process filter multibyte flag
- When Emacs calls a process filter function, it provides the process
-output as a multibyte string or as a unibyte string according to the
-process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
-decodes the output according to the process output coding system to
-produce a multibyte string, and passes that to the process. If the
-flag is @code{nil}, Emacs puts the output into a unibyte string, with
-no decoding, and passes that.
-
- When you create a process, the filter multibyte flag takes its
-initial value from @code{default-enable-multibyte-characters}. If you
-want to change the flag later on, use
-@code{set-process-filter-multibyte}.
-
-@defun set-process-filter-multibyte process multibyte
-This function sets the filter multibyte flag of @var{process}
-to @var{multibyte}.
-@end defun
-
-@defun process-filter-multibyte-p process
-This function returns the filter multibyte flag of @var{process}.
-@end defun
-
-@node Accepting Output
-@subsection Accepting Output from Processes
-@cindex accept input from processes
-
- Output from asynchronous subprocesses normally arrives only while
-Emacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
-@defun accept-process-output &optional process seconds millisec just-this-one
-This function allows Emacs to read pending output from processes. The
-output is inserted in the associated buffers or given to their filter
-functions. If @var{process} is non-@code{nil} then this function does
-not return until some output has been received from @var{process}.
-
-@c Emacs 19 feature
-The arguments @var{seconds} and @var{millisec} let you specify timeout
-periods. The former specifies a period measured in seconds and the
-latter specifies one measured in milliseconds. The two time periods
-thus specified are added together, and @code{accept-process-output}
-returns after that much time, whether or not there has been any
-subprocess output.
-
-The argument @var{millisec} is semi-obsolete nowadays because
-@var{seconds} can be a floating point number to specify waiting a
-fractional number of seconds. If @var{seconds} is 0, the function
-accepts whatever output is pending but does not wait.
-
-@c Emacs 22.1 feature
-If @var{process} is a process, and the argument @var{just-this-one} is
-non-@code{nil}, only output from that process is handled, suspending output
-from other processes until some output has been received from that
-process or the timeout expires. If @var{just-this-one} is an integer,
-also inhibit running timers. This feature is generally not
-recommended, but may be necessary for specific applications, such as
-speech synthesis.
-
-The function @code{accept-process-output} returns non-@code{nil} if it
-did get some output, or @code{nil} if the timeout expired before output
-arrived.
-@end defun
-
-@node Sentinels
-@section Sentinels: Detecting Process Status Changes
-@cindex process sentinel
-@cindex sentinel (of process)
-
- A @dfn{process sentinel} is a function that is called whenever the
-associated process changes status for any reason, including signals
-(whether sent by Emacs or caused by the process's own actions) that
-terminate, stop, or continue the process. The process sentinel is
-also called if the process exits. The sentinel receives two
-arguments: the process for which the event occurred, and a string
-describing the type of event.
-
- The string describing the event looks like one of the following:
-
-@itemize @bullet
-@item
-@code{"finished\n"}.
-
-@item
-@code{"exited abnormally with code @var{exitcode}\n"}.
-
-@item
-@code{"@var{name-of-signal}\n"}.
-
-@item
-@code{"@var{name-of-signal} (core dumped)\n"}.
-@end itemize
-
- A sentinel runs only while Emacs is waiting (e.g., for terminal
-input, or for time to elapse, or for process output). This avoids the
-timing errors that could result from running them at random places in
-the middle of other Lisp programs. A program can wait, so that
-sentinels will run, by calling @code{sit-for} or @code{sleep-for}
-(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
-Output}). Emacs also allows sentinels to run when the command loop is
-reading input. @code{delete-process} calls the sentinel when it
-terminates a running process.
-
- Emacs does not keep a queue of multiple reasons to call the sentinel
-of one process; it records just the current status and the fact that
-there has been a change. Therefore two changes in status, coming in
-quick succession, can call the sentinel just once. However, process
-termination will always run the sentinel exactly once. This is
-because the process status can't change again after termination.
-
- Emacs explicitly checks for output from the process before running
-the process sentinel. Once the sentinel runs due to process
-termination, no further output can arrive from the process.
-
- A sentinel that writes the output into the buffer of the process
-should check whether the buffer is still alive. If it tries to insert
-into a dead buffer, it will get an error. If the buffer is dead,
-@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
-
- Quitting is normally inhibited within a sentinel---otherwise, the
-effect of typing @kbd{C-g} at command level or to quit a user command
-would be unpredictable. If you want to permit quitting inside a
-sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
-right way to do this is with the macro @code{with-local-quit}.
-@xref{Quitting}.
-
- If an error happens during execution of a sentinel, it is caught
-automatically, so that it doesn't stop the execution of whatever
-programs was running when the sentinel was started. However, if
-@code{debug-on-error} is non-@code{nil}, the error-catching is turned
-off. This makes it possible to use the Lisp debugger to debug the
-sentinel. @xref{Debugger}.
-
- While a sentinel is running, the process sentinel is temporarily
-set to @code{nil} so that the sentinel won't run recursively.
-For this reason it is not possible for a sentinel to specify
-a new sentinel.
-
- In earlier Emacs versions, every sentinel that did regular expression
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically for sentinels; they never need to do
-it explicitly. @xref{Match Data}.
-
-@defun set-process-sentinel process sentinel
-This function associates @var{sentinel} with @var{process}. If
-@var{sentinel} is @code{nil}, then the process will have no sentinel.
-The default behavior when there is no sentinel is to insert a message in
-the process's buffer when the process status changes.
-
-Changes in process sentinel take effect immediately---if the sentinel
-is slated to be run but has not been called yet, and you specify a new
-sentinel, the eventual call to the sentinel will use the new one.
-
-@smallexample
-@group
-(defun msg-me (process event)
- (princ
- (format "Process: %s had the event `%s'" process event)))
-(set-process-sentinel (get-process "shell") 'msg-me)
- @result{} msg-me
-@end group
-@group
-(kill-process (get-process "shell"))
- @print{} Process: #<process shell> had the event `killed'
- @result{} #<process shell>
-@end group
-@end smallexample
-@end defun
-
-@defun process-sentinel process
-This function returns the sentinel of @var{process}, or @code{nil} if it
-has none.
-@end defun
-
-@defun waiting-for-user-input-p
-While a sentinel or filter function is running, this function returns
-non-@code{nil} if Emacs was waiting for keyboard input from the user at
-the time the sentinel or filter function was called, @code{nil} if it
-was not.
-@end defun
-
-@node Query Before Exit
-@section Querying Before Exit
-
- When Emacs exits, it terminates all its subprocesses by sending them
-the @code{SIGHUP} signal. Because subprocesses may be doing
-valuable work, Emacs normally asks the user to confirm that it is ok
-to terminate them. Each process has a query flag which, if
-non-@code{nil}, says that Emacs should ask for confirmation before
-exiting and thus killing that process. The default for the query flag
-is @code{t}, meaning @emph{do} query.
-
-@defun process-query-on-exit-flag process
-This returns the query flag of @var{process}.
-@end defun
-
-@defun set-process-query-on-exit-flag process flag
-This function sets the query flag of @var{process} to @var{flag}. It
-returns @var{flag}.
-
-@smallexample
-@group
-;; @r{Don't query about the shell process}
-(set-process-query-on-exit-flag (get-process "shell") nil)
- @result{} t
-@end group
-@end smallexample
-@end defun
-
-@defun process-kill-without-query process &optional do-query
-This function clears the query flag of @var{process}, so that
-Emacs will not query the user on account of that process.
-
-Actually, the function does more than that: it returns the old value of
-the process's query flag, and sets the query flag to @var{do-query}.
-Please don't use this function to do those things any more---please
-use the newer, cleaner functions @code{process-query-on-exit-flag} and
-@code{set-process-query-on-exit-flag} in all but the simplest cases.
-The only way you should use @code{process-kill-without-query} nowadays
-is like this:
-
-@smallexample
-@group
-;; @r{Don't query about the shell process}
-(process-kill-without-query (get-process "shell"))
-@end group
-@end smallexample
-@end defun
-
-@node Transaction Queues
-@section Transaction Queues
-@cindex transaction queue
-
-You can use a @dfn{transaction queue} to communicate with a subprocess
-using transactions. First use @code{tq-create} to create a transaction
-queue communicating with a specified process. Then you can call
-@code{tq-enqueue} to send a transaction.
-
-@defun tq-create process
-This function creates and returns a transaction queue communicating with
-@var{process}. The argument @var{process} should be a subprocess
-capable of sending and receiving streams of bytes. It may be a child
-process, or it may be a TCP connection to a server, possibly on another
-machine.
-@end defun
-
-@defun tq-enqueue queue question regexp closure fn &optional delay-question
-This function sends a transaction to queue @var{queue}. Specifying the
-queue has the effect of specifying the subprocess to talk to.
-
-The argument @var{question} is the outgoing message that starts the
-transaction. The argument @var{fn} is the function to call when the
-corresponding answer comes back; it is called with two arguments:
-@var{closure}, and the answer received.
-
-The argument @var{regexp} is a regular expression that should match
-text at the end of the entire answer, but nothing before; that's how
-@code{tq-enqueue} determines where the answer ends.
-
-If the argument @var{delay-question} is non-nil, delay sending this
-question until the process has finished replying to any previous
-questions. This produces more reliable results with some processes.
-
-The return value of @code{tq-enqueue} itself is not meaningful.
-@end defun
-
-@defun tq-close queue
-Shut down transaction queue @var{queue}, waiting for all pending transactions
-to complete, and then terminate the connection or child process.
-@end defun
-
-Transaction queues are implemented by means of a filter function.
-@xref{Filter Functions}.
-
-@node Network
-@section Network Connections
-@cindex network connection
-@cindex TCP
-@cindex UDP
-
- Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
-connections to other processes on the same machine or other machines.
-A network connection is handled by Lisp much like a subprocess, and is
-represented by a process object. However, the process you are
-communicating with is not a child of the Emacs process, so it has no
-process @acronym{ID}, and you can't kill it or send it signals. All you
-can do is send and receive data. @code{delete-process} closes the
-connection, but does not kill the program at the other end; that
-program must decide what to do about closure of the connection.
-
- Lisp programs can listen for connections by creating network
-servers. A network server is also represented by a kind of process
-object, but unlike a network connection, the network server never
-transfers data itself. When it receives a connection request, it
-creates a new network connection to represent the connection just
-made. (The network connection inherits certain information, including
-the process plist, from the server.) The network server then goes
-back to listening for more connection requests.
-
- Network connections and servers are created by calling
-@code{make-network-process} with an argument list consisting of
-keyword/argument pairs, for example @code{:server t} to create a
-server process, or @code{:type 'datagram} to create a datagram
-connection. @xref{Low-Level Network}, for details. You can also use
-the @code{open-network-stream} function described below.
-
- You can distinguish process objects representing network connections
-and servers from those representing subprocesses with the
-@code{process-status} function. The possible status values for
-network connections are @code{open}, @code{closed}, @code{connect},
-and @code{failed}. For a network server, the status is always
-@code{listen}. None of those values is possible for a real
-subprocess. @xref{Process Information}.
-
- You can stop and resume operation of a network process by calling
-@code{stop-process} and @code{continue-process}. For a server
-process, being stopped means not accepting new connections. (Up to 5
-connection requests will be queued for when you resume the server; you
-can increase this limit, unless it is imposed by the operating
-system.) For a network stream connection, being stopped means not
-processing input (any arriving input waits until you resume the
-connection). For a datagram connection, some number of packets may be
-queued but input may be lost. You can use the function
-@code{process-command} to determine whether a network connection or
-server is stopped; a non-@code{nil} value means yes.
-
-@defun open-network-stream name buffer-or-name host service
-This function opens a TCP connection, and returns a process object
-that represents the connection.
-
-The @var{name} argument specifies the name for the process object. It
-is modified as necessary to make it unique.
-
-The @var{buffer-or-name} argument is the buffer to associate with the
-connection. Output from the connection is inserted in the buffer,
-unless you specify a filter function to handle the output. If
-@var{buffer-or-name} is @code{nil}, it means that the connection is not
-associated with any buffer.
-
-The arguments @var{host} and @var{service} specify where to connect to;
-@var{host} is the host name (a string), and @var{service} is the name of
-a defined network service (a string) or a port number (an integer).
-@end defun
-
-@defun process-contact process &optional key
-This function returns information about how a network process was set
-up. For a connection, when @var{key} is @code{nil}, it returns
-@code{(@var{hostname} @var{service})} which specifies what you
-connected to.
-
-If @var{key} is @code{t}, the value is the complete status information
-for the connection or server; that is, the list of keywords and values
-specified in @code{make-network-process}, except that some of the
-values represent the current status instead of what you specified:
-
-@table @code
-@item :buffer
-The associated value is the process buffer.
-@item :filter
-The associated value is the process filter function.
-@item :sentinel
-The associated value is the process sentinel function.
-@item :remote
-In a connection, the address in internal format of the remote peer.
-@item :local
-The local address, in internal format.
-@item :service
-In a server, if you specified @code{t} for @var{service},
-this value is the actual port number.
-@end table
-
-@code{:local} and @code{:remote} are included even if they were not
-specified explicitly in @code{make-network-process}.
-
-If @var{key} is a keyword, the function returns the value corresponding
-to that keyword.
-
-For an ordinary child process, this function always returns @code{t}.
-@end defun
-
-@node Network Servers
-@section Network Servers
-@cindex network servers
-
- You create a server by calling @code{make-network-process} with
-@code{:server t}. The server will listen for connection requests from
-clients. When it accepts a client connection request, that creates a
-new network connection, itself a process object, with the following
-parameters:
-
-@itemize @bullet
-@item
-The connection's process name is constructed by concatenating the
-server process' @var{name} with a client identification string. The
-client identification string for an IPv4 connection looks like
-@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
-unique number in brackets, as in @samp{<@var{nnn}>}. The number
-is unique for each connection in the Emacs session.
-
-@item
-If the server's filter is non-@code{nil}, the connection process does
-not get a separate process buffer; otherwise, Emacs creates a new
-buffer for the purpose. The buffer name is the server's buffer name
-or process name, concatenated with the client identification string.
-
-The server's process buffer value is never used directly by Emacs, but
-it is passed to the log function, which can log connections by
-inserting text there.
-
-@item
-The communication type and the process filter and sentinel are
-inherited from those of the server. The server never directly
-uses its filter and sentinel; their sole purpose is to initialize
-connections made to the server.
-
-@item
-The connection's process contact info is set according to the client's
-addressing information (typically an IP address and a port number).
-This information is associated with the @code{process-contact}
-keywords @code{:host}, @code{:service}, @code{:remote}.
-
-@item
-The connection's local address is set up according to the port
-number used for the connection.
-
-@item
-The client process' plist is initialized from the server's plist.
-@end itemize
-
-@node Datagrams
-@section Datagrams
-@cindex datagrams
-
- A datagram connection communicates with individual packets rather
-than streams of data. Each call to @code{process-send} sends one
-datagram packet (@pxref{Input to Processes}), and each datagram
-received results in one call to the filter function.
-
- The datagram connection doesn't have to talk with the same remote
-peer all the time. It has a @dfn{remote peer address} which specifies
-where to send datagrams to. Each time an incoming datagram is passed
-to the filter function, the peer address is set to the address that
-datagram came from; that way, if the filter function sends a datagram,
-it will go back to that place. You can specify the remote peer
-address when you create the datagram connection using the
-@code{:remote} keyword. You can change it later on by calling
-@code{set-process-datagram-address}.
-
-@defun process-datagram-address process
-If @var{process} is a datagram connection or server, this function
-returns its remote peer address.
-@end defun
-
-@defun set-process-datagram-address process address
-If @var{process} is a datagram connection or server, this function
-sets its remote peer address to @var{address}.
-@end defun
-
-@node Low-Level Network
-@section Low-Level Network Access
-
- You can also create network connections by operating at a lower
-level than that of @code{open-network-stream}, using
-@code{make-network-process}.
-
-@menu
-* 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.
-@end menu
-
-@node Network Processes
-@subsection @code{make-network-process}
-
- The basic function for creating network connections and network
-servers is @code{make-network-process}. It can do either of those
-jobs, depending on the arguments you give it.
-
-@defun make-network-process &rest args
-This function creates a network connection or server and returns the
-process object that represents it. The arguments @var{args} are a
-list of keyword/argument pairs. Omitting a keyword is always
-equivalent to specifying it with value @code{nil}, except for
-@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
-are the meaningful keywords:
-
-@table @asis
-@item :name @var{name}
-Use the string @var{name} as the process name. It is modified if
-necessary to make it unique.
-
-@item :type @var{type}
-Specify the communication type. A value of @code{nil} specifies a
-stream connection (the default); @code{datagram} specifies a datagram
-connection. Both connections and servers can be of either type.
-
-@item :server @var{server-flag}
-If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
-create a connection. For a stream type server, @var{server-flag} may
-be an integer which then specifies the length of the queue of pending
-connections to the server. The default queue length is 5.
-
-@item :host @var{host}
-Specify the host to connect to. @var{host} should be a host name or
-Internet address, as a string, or the symbol @code{local} to specify
-the local host. If you specify @var{host} for a server, it must
-specify a valid address for the local host, and only clients
-connecting to that address will be accepted.
-
-@item :service @var{service}
-@var{service} specifies a port number to connect to, or, for a server,
-the port number to listen on. It should be a service name that
-translates to a port number, or an integer specifying the port number
-directly. For a server, it can also be @code{t}, which means to let
-the system select an unused port number.
-
-@item :family @var{family}
-@var{family} specifies the address (and protocol) family for
-communication. @code{nil} means determine the proper address family
-automatically for the given @var{host} and @var{service}.
-@code{local} specifies a Unix socket, in which case @var{host} is
-ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
-respectively.
-
-@item :local @var{local-address}
-For a server process, @var{local-address} is the address to listen on.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
-
-@item :remote @var{remote-address}
-For a connection, @var{remote-address} is the address to connect to.
-It overrides @var{family}, @var{host} and @var{service}, and you
-may as well not specify them.
-
-For a datagram server, @var{remote-address} specifies the initial
-setting of the remote datagram address.
-
-The format of @var{local-address} or @var{remote-address} depends on
-the address family:
-
-@itemize -
-@item
-An IPv4 address is represented as a five-element vector of four 8-bit
-integers and one 16-bit integer
-@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
-numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
-@var{p}.
-
-@item
-An IPv6 address is represented as a nine-element vector of 16-bit
-integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
-@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
-@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
-port number @var{p}.
-
-@item
-A local address is represented as a string which specifies the address
-in the local address space.
-
-@item
-An ``unsupported family'' address is represented by a cons
-@code{(@var{f} . @var{av})}, where @var{f} is the family number and
-@var{av} is a vector specifying the socket address using one element
-per address data byte. Do not rely on this format in portable code,
-as it may depend on implementation defined constants, data sizes, and
-data structure alignment.
-@end itemize
-
-@item :nowait @var{bool}
-If @var{bool} is non-@code{nil} for a stream connection, return
-without waiting for the connection to complete. When the connection
-succeeds or fails, Emacs will call the sentinel function, with a
-second argument matching @code{"open"} (if successful) or
-@code{"failed"}. The default is to block, so that
-@code{make-network-process} does not return until the connection
-has succeeded or failed.
-
-@item :stop @var{stopped}
-Start the network connection or server in the `stopped' state if
-@var{stopped} is non-@code{nil}.
-
-@item :buffer @var{buffer}
-Use @var{buffer} as the process buffer.
-
-@item :coding @var{coding}
-Use @var{coding} as the coding system for this process. To specify
-different coding systems for decoding data from the connection and for
-encoding data sent to it, specify @code{(@var{decoding} .
-@var{encoding})} for @var{coding}.
-
-If you don't specify this keyword at all, the default
-is to determine the coding systems from the data.
-
-@item :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.
-@xref{Query Before Exit}.
-
-@item :filter @var{filter}
-Initialize the process filter to @var{filter}.
-
-@item :filter-multibyte @var{bool}
-If @var{bool} is non-@code{nil}, strings given to the process filter
-are multibyte, otherwise they are unibyte. If you don't specify this
-keyword at all, the default is that the strings are multibyte if
-@code{default-enable-multibyte-characters} is non-@code{nil}.
-
-@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
-
-@item :log @var{log}
-Initialize the log function of a server process to @var{log}. The log
-function is called each time the server accepts a network connection
-from a client. The arguments passed to the log function are
-@var{server}, @var{connection}, and @var{message}, where @var{server}
-is the server process, @var{connection} is the new process for the
-connection, and @var{message} is a string describing what has
-happened.
-
-@item :plist @var{plist}
-Initialize the process plist to @var{plist}.
-@end table
-
-The original argument list, modified with the actual connection
-information, is available via the @code{process-contact} function.
-@end defun
-
-@node Network Options
-@subsection Network Options
-
- The following network options can be specified when you create a
-network process. Except for @code{:reuseaddr}, you can also set or
-modify these options later, using @code{set-network-process-option}.
-
- For a server process, the options specified with
-@code{make-network-process} are not inherited by the client
-connections, so you will need to set the necessary options for each
-child connection as it is created.
-
-@table @asis
-@item :bindtodevice @var{device-name}
-If @var{device-name} is a non-empty string identifying a network
-interface name (see @code{network-interface-list}), only handle
-packets received on that interface. If @var{device-name} is @code{nil}
-(the default), handle packets received on any interface.
-
-Using this option may require special privileges on some systems.
-
-@item :broadcast @var{broadcast-flag}
-If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
-process will receive datagram packet sent to a broadcast address, and
-be able to send packets to a broadcast address. Ignored for a stream
-connection.
-
-@item :dontroute @var{dontroute-flag}
-If @var{dontroute-flag} is non-@code{nil}, the process can only send
-to hosts on the same network as the local host.
-
-@item :keepalive @var{keepalive-flag}
-If @var{keepalive-flag} is non-@code{nil} for a stream connection,
-enable exchange of low-level keep-alive messages.
-
-@item :linger @var{linger-arg}
-If @var{linger-arg} is non-@code{nil}, wait for successful
-transmission of all queued packets on the connection before it is
-deleted (see @code{delete-process}). If @var{linger-arg} is an
-integer, it specifies the maximum time in seconds to wait for queued
-packets to be sent before closing the connection. Default is
-@code{nil} which means to discard unsent queued packets when the
-process is deleted.
-
-@item :oobinline @var{oobinline-flag}
-If @var{oobinline-flag} is non-@code{nil} for a stream connection,
-receive out-of-band data in the normal data stream. Otherwise, ignore
-out-of-band data.
-
-@item :priority @var{priority}
-Set the priority for packets sent on this connection to the integer
-@var{priority}. The interpretation of this number is protocol
-specific, such as setting the TOS (type of service) field on IP
-packets sent on this connection. It may also have system dependent
-effects, such as selecting a specific output queue on the network
-interface.
-
-@item :reuseaddr @var{reuseaddr-flag}
-If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
-server process, allow this server to reuse a specific port number (see
-@code{:service}) unless another process on this host is already
-listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
-may be a period of time after the last use of that port (by any
-process on the host), where it is not possible to make a new server on
-that port.
-@end table
-
-@defun set-network-process-option process option value
-This function sets or modifies a network option for network process
-@var{process}. See @code{make-network-process} for details of options
-@var{option} and their corresponding values @var{value}.
-
-The current setting of an option is available via the
-@code{process-contact} function.
-@end defun
-
-@node Network Feature Testing
-@subsection Testing Availability of Network Features
-
- To test for the availability of a given network feature, use
-@code{featurep} like this:
-
-@example
-(featurep 'make-network-process '(@var{keyword} @var{value}))
-@end example
-
-@noindent
-The result of the first form is @code{t} if it works to specify
-@var{keyword} with value @var{value} in @code{make-network-process}.
-The result of the second form is @code{t} if @var{keyword} is
-supported by @code{make-network-process}. Here are some of the
-@var{keyword}---@var{value} pairs you can test in
-this way.
-
-@table @code
-@item (:nowait t)
-Non-@code{nil} if non-blocking connect is supported.
-@item (:type datagram)
-Non-@code{nil} if datagrams are supported.
-@item (:family local)
-Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
-@item (:family ipv6)
-Non-@code{nil} if IPv6 is supported.
-@item (:service t)
-Non-@code{nil} if the system can select the port for a server.
-@end table
-
- To test for the availability of a given network option, use
-@code{featurep} like this:
-
-@example
-(featurep 'make-network-process '@var{keyword})
-@end example
-
-@noindent
-Here are some of the options you can test in this way.
-
-@table @code
-@item :bindtodevice
-@itemx :broadcast
-@itemx :dontroute
-@itemx :keepalive
-@itemx :linger
-@itemx :oobinline
-@itemx :priority
-@itemx :reuseaddr
-That particular network option is supported by
-@code{make-network-process} and @code{set-network-process-option}.
-@end table
-
-@node Misc Network
-@section Misc Network Facilities
-
- These additional functions are useful for creating and operating
-on network connections.
-
-@defun network-interface-list
-This function returns a list describing the network interfaces
-of the machine you are using. The value is an alist whose
-elements have the form @code{(@var{name} . @var{address})}.
-@var{address} has the same form as the @var{local-address}
-and @var{remote-address} arguments to @code{make-network-process}.
-@end defun
-
-@defun network-interface-info ifname
-This function returns information about the network interface named
-@var{ifname}. The value is a list of the form
-@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
-
-@table @var
-@item addr
-The Internet protocol address.
-@item bcast
-The broadcast address.
-@item netmask
-The network mask.
-@item hwaddr
-The layer 2 address (Ethernet MAC address, for instance).
-@item flags
-The current flags of the interface.
-@end table
-@end defun
-
-@defun format-network-address address &optional omit-port
-This function converts the Lisp representation of a network address to
-a string.
-
-A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
-represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
-number @var{p}. @code{format-network-address} converts that to the
-string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
-
-A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
-@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
-with a port number. @code{format-network-address} converts that to
-the string
-@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
-
-If the vector does not include the port number, @var{p}, or if
-@var{omit-port} is non-@code{nil}, the result does not include the
-@code{:@var{p}} suffix.
-@end defun
-
-@node Byte Packing
-@section Packing and Unpacking Byte Arrays
-@cindex byte packing and unpacking
-
- This section describes how to pack and unpack arrays of bytes,
-usually for binary network protocols. These functions convert byte arrays
-to alists, and vice versa. The byte array can be represented as a
-unibyte string or as a vector of integers, while the alist associates
-symbols either with fixed-size objects or with recursive sub-alists.
-
-@cindex serializing
-@cindex deserializing
-@cindex packing
-@cindex unpacking
- Conversion from byte arrays to nested alists is also known as
-@dfn{deserializing} or @dfn{unpacking}, while going in the opposite
-direction is also known as @dfn{serializing} or @dfn{packing}.
-
-@menu
-* Bindat Spec:: Describing data layout.
-* Bindat Functions:: Doing the unpacking and packing.
-* Bindat Examples:: Samples of what bindat.el can do for you!
-@end menu
-
-@node Bindat Spec
-@subsection Describing Data Layout
-
- To control unpacking and packing, you write a @dfn{data layout
-specification}, a special nested list describing named and typed
-@dfn{fields}. This specification controls length of each field to be
-processed, and how to pack or unpack it. We normally keep bindat specs
-in variables whose names end in @samp{-bindat-spec}; that kind of name
-is automatically recognized as ``risky.''
-
-@cindex endianness
-@cindex big endian
-@cindex little endian
-@cindex network byte ordering
- A field's @dfn{type} describes the size (in bytes) of the object
-that the field represents and, in the case of multibyte fields, how
-the bytes are ordered within the field. The two possible orderings
-are ``big endian'' (also known as ``network byte ordering'') and
-``little endian.'' For instance, the number @code{#x23cd} (decimal
-9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
-and in little endian, @code{#xcd} @code{#x23}. Here are the possible
-type values:
-
-@table @code
-@item u8
-@itemx byte
-Unsigned byte, with length 1.
-
-@item u16
-@itemx word
-@itemx short
-Unsigned integer in network byte order, with length 2.
-
-@item u24
-Unsigned integer in network byte order, with length 3.
-
-@item u32
-@itemx dword
-@itemx long
-Unsigned integer in network byte order, with length 4.
-Note: These values may be limited by Emacs' integer implementation limits.
-
-@item u16r
-@itemx u24r
-@itemx u32r
-Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
-
-@item str @var{len}
-String of length @var{len}.
-
-@item strz @var{len}
-Zero-terminated string, in a fixed-size field with length @var{len}.
-
-@item vec @var{len} [@var{type}]
-Vector of @var{len} elements of type @var{type}, or bytes if not
-@var{type} is specified.
-The @var{type} is any of the simple types above, or another vector
-specified as a list @code{(vec @var{len} [@var{type}])}.
-
-@item ip
-Four-byte vector representing an Internet address. For example:
-@code{[127 0 0 1]} for localhost.
-
-@item bits @var{len}
-List of set bits in @var{len} bytes. The bytes are taken in big
-endian order and the bits are numbered starting with @code{8 *
-@var{len} @minus{} 1} and ending with zero. For example: @code{bits
-2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
-@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
-
-@item (eval @var{form})
-@var{form} is a Lisp expression evaluated at the moment the field is
-unpacked or packed. The result of the evaluation should be one of the
-above-listed type specifications.
-@end table
-
-For a fixed-size field, the length @var{len} is given as an integer
-specifying the number of bytes in the field.
-
-When the length of a field is not fixed, it typically depends on the
-value of a preceding field. In this case, the length @var{len} can be
-given either as a list @code{(@var{name} ...)} identifying a
-@dfn{field name} in the format specified for @code{bindat-get-field}
-below, or by an expression @code{(eval @var{form})} where @var{form}
-should evaluate to an integer, specifying the field length.
-
-A field specification generally has the form @code{([@var{name}]
-@var{handler})}. The square braces indicate that @var{name} is
-optional. (Don't use names that are symbols meaningful as type
-specifications (above) or handler specifications (below), since that
-would be ambiguous.) @var{name} can be a symbol or the expression
-@code{(eval @var{form})}, in which case @var{form} should evaluate to
-a symbol.
-
-@var{handler} describes how to unpack or pack the field and can be one
-of the following:
-
-@table @code
-@item @var{type}
-Unpack/pack this field according to the type specification @var{type}.
-
-@item eval @var{form}
-Evaluate @var{form}, a Lisp expression, for side-effect only. If the
-field name is specified, the value is bound to that field name.
-
-@item fill @var{len}
-Skip @var{len} bytes. In packing, this leaves them unchanged,
-which normally means they remain zero. In unpacking, this means
-they are ignored.
-
-@item align @var{len}
-Skip to the next multiple of @var{len} bytes.
-
-@item struct @var{spec-name}
-Process @var{spec-name} as a sub-specification. This describes a
-structure nested within another structure.
-
-@item union @var{form} (@var{tag} @var{spec})@dots{}
-@c ??? I don't see how one would actually use this.
-@c ??? what kind of expression would be useful for @var{form}?
-Evaluate @var{form}, a Lisp expression, find the first @var{tag}
-that matches it, and process its associated data layout specification
-@var{spec}. Matching can occur in one of three ways:
-
-@itemize
-@item
-If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
-@var{expr} with the variable @code{tag} dynamically bound to the value
-of @var{form}. A non-@code{nil} result indicates a match.
-
-@item
-@var{tag} matches if it is @code{equal} to the value of @var{form}.
-
-@item
-@var{tag} matches unconditionally if it is @code{t}.
-@end itemize
-
-@item repeat @var{count} @var{field-specs}@dots{}
-Process the @var{field-specs} recursively, in order, then repeat
-starting from the first one, processing all the specs @var{count}
-times overall. The @var{count} is given using the same formats as a
-field length---if an @code{eval} form is used, it is evaluated just once.
-For correct operation, each spec in @var{field-specs} must include a name.
-@end table
-
-For the @code{(eval @var{form})} forms used in a bindat specification,
-the @var{form} can access and update these dynamically bound variables
-during evaluation:
-
-@table @code
-@item last
-Value of the last field processed.
-
-@item bindat-raw
-The data as a byte array.
-
-@item bindat-idx
-Current index (within @code{bindat-raw}) for unpacking or packing.
-
-@item struct
-The alist containing the structured data that have been unpacked so
-far, or the entire structure being packed. You can use
-@code{bindat-get-field} to access specific fields of this structure.
-
-@item count
-@itemx index
-Inside a @code{repeat} block, these contain the maximum number of
-repetitions (as specified by the @var{count} parameter), and the
-current repetition number (counting from 0). Setting @code{count} to
-zero will terminate the inner-most repeat block after the current
-repetition has completed.
-@end table
-
-@node Bindat Functions
-@subsection Functions to Unpack and Pack Bytes
-
- In the following documentation, @var{spec} refers to a data layout
-specification, @code{bindat-raw} to a byte array, and @var{struct} to an
-alist representing unpacked field data.
-
-@defun bindat-unpack spec bindat-raw &optional bindat-idx
-This function unpacks data from the unibyte string or byte
-array @code{bindat-raw}
-according to @var{spec}. Normally this starts unpacking at the
-beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
-specifies a zero-based starting position to use instead.
-
-The value is an alist or nested alist in which each element describes
-one unpacked field.
-@end defun
-
-@defun bindat-get-field struct &rest name
-This function selects a field's data from the nested alist
-@var{struct}. Usually @var{struct} was returned by
-@code{bindat-unpack}. If @var{name} corresponds to just one argument,
-that means to extract a top-level field value. Multiple @var{name}
-arguments specify repeated lookup of sub-structures. An integer name
-acts as an array index.
-
-For example, if @var{name} is @code{(a b 2 c)}, that means to find
-field @code{c} in the third element of subfield @code{b} of field
-@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
-@end defun
-
- Although packing and unpacking operations change the organization of
-data (in memory), they preserve the data's @dfn{total length}, which is
-the sum of all the fields' lengths, in bytes. This value is not
-generally inherent in either the specification or alist alone; instead,
-both pieces of information contribute to its calculation. Likewise, the
-length of a string or array being unpacked may be longer than the data's
-total length as described by the specification.
-
-@defun bindat-length spec struct
-This function returns the total length of the data in @var{struct},
-according to @var{spec}.
-@end defun
-
-@defun bindat-pack spec struct &optional bindat-raw bindat-idx
-This function returns a byte array packed according to @var{spec} from
-the data in the alist @var{struct}. Normally it creates and fills a
-new byte array starting at the beginning. However, if @var{bindat-raw}
-is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
-pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
-offset for packing into @code{bindat-raw}.
-
-When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
-meets or exceeds the total length to avoid an out-of-range error.
-@end defun
-
-@defun bindat-ip-to-string ip
-Convert the Internet address vector @var{ip} to a string in the usual
-dotted notation.
-
-@example
-(bindat-ip-to-string [127 0 0 1])
- @result{} "127.0.0.1"
-@end example
-@end defun
-
-@node Bindat Examples
-@subsection Examples of Byte Unpacking and Packing
-
- Here is a complete example of byte unpacking and packing:
-
-@lisp
-(defvar fcookie-index-spec
- '((:version u32)
- (:count u32)
- (:longest u32)
- (:shortest u32)
- (:flags u32)
- (:delim u8)
- (:ignored fill 3)
- (:offset repeat (:count)
- (:foo u32)))
- "Description of a fortune cookie index file's contents.")
-
-(defun fcookie (cookies &optional index)
- "Display a random fortune cookie from file COOKIES.
-Optional second arg INDEX specifies the associated index
-filename, which is by default constructed by appending
-\".dat\" to COOKIES. Display cookie text in possibly
-new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
-is COOKIES without the directory part."
- (interactive "fCookies file: ")
- (let* ((info (with-temp-buffer
- (insert-file-contents-literally
- (or index (concat cookies ".dat")))
- (bindat-unpack fcookie-index-spec
- (buffer-string))))
- (sel (random (bindat-get-field info :count)))
- (beg (cdar (bindat-get-field info :offset sel)))
- (end (or (cdar (bindat-get-field info
- :offset (1+ sel)))
- (nth 7 (file-attributes cookies)))))
- (switch-to-buffer
- (get-buffer-create
- (format "*Fortune Cookie: %s*"
- (file-name-nondirectory cookies))))
- (erase-buffer)
- (insert-file-contents-literally
- cookies nil beg (- end 3))))
-
-(defun fcookie-create-index (cookies &optional index delim)
- "Scan file COOKIES, and write out its index file.
-Optional second arg INDEX specifies the index filename,
-which is by default constructed by appending \".dat\" to
-COOKIES. Optional third arg DELIM specifies the unibyte
-character which, when found on a line of its own in
-COOKIES, indicates the border between entries."
- (interactive "fCookies file: ")
- (setq delim (or delim ?%))
- (let ((delim-line (format "\n%c\n" delim))
- (count 0)
- (max 0)
- min p q len offsets)
- (unless (= 3 (string-bytes delim-line))
- (error "Delimiter cannot be represented in one byte"))
- (with-temp-buffer
- (insert-file-contents-literally cookies)
- (while (and (setq p (point))
- (search-forward delim-line (point-max) t)
- (setq len (- (point) 3 p)))
- (setq count (1+ count)
- max (max max len)
- min (min (or min max) len)
- offsets (cons (1- p) offsets))))
- (with-temp-buffer
- (set-buffer-multibyte nil)
- (insert
- (bindat-pack
- fcookie-index-spec
- `((:version . 2)
- (:count . ,count)
- (:longest . ,max)
- (:shortest . ,min)
- (:flags . 0)
- (:delim . ,delim)
- (:offset . ,(mapcar (lambda (o)
- (list (cons :foo o)))
- (nreverse offsets))))))
- (let ((coding-system-for-write 'raw-text-unix))
- (write-file (or index (concat cookies ".dat")))))))
-@end lisp
-
-Following is an example of defining and unpacking a complex structure.
-Consider the following C structures:
-
-@example
-struct header @{
- unsigned long dest_ip;
- unsigned long src_ip;
- unsigned short dest_port;
- unsigned short src_port;
-@};
-
-struct data @{
- unsigned char type;
- unsigned char opcode;
- unsigned short length; /* In network byte order */
- unsigned char id[8]; /* null-terminated string */
- unsigned char data[/* (length + 3) & ~3 */];
-@};
-
-struct packet @{
- struct header header;
- unsigned long counters[2]; /* In little endian order */
- unsigned char items;
- unsigned char filler[3];
- struct data item[/* items */];
-
-@};
-@end example
-
-The corresponding data layout specification:
-
-@lisp
-(setq header-spec
- '((dest-ip ip)
- (src-ip ip)
- (dest-port u16)
- (src-port u16)))
-
-(setq data-spec
- '((type u8)
- (opcode u8)
- (length u16) ;; network byte order
- (id strz 8)
- (data vec (length))
- (align 4)))
-
-(setq packet-spec
- '((header struct header-spec)
- (counters vec 2 u32r) ;; little endian order
- (items u8)
- (fill 3)
- (item repeat (items)
- (struct data-spec))))
-@end lisp
-
-A binary data representation:
-
-@lisp
-(setq binary-data
- [ 192 168 1 100 192 168 1 101 01 28 21 32
- 160 134 1 0 5 1 0 0 2 0 0 0
- 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
- 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
-@end lisp
-
-The corresponding decoded structure:
-
-@lisp
-(setq decoded (bindat-unpack packet-spec binary-data))
- @result{}
-((header
- (dest-ip . [192 168 1 100])
- (src-ip . [192 168 1 101])
- (dest-port . 284)
- (src-port . 5408))
- (counters . [100000 261])
- (items . 2)
- (item ((data . [1 2 3 4 5])
- (id . "ABCDEF")
- (length . 5)
- (opcode . 3)
- (type . 2))
- ((data . [6 7 8 9 10 11 12])
- (id . "BCDEFG")
- (length . 7)
- (opcode . 4)
- (type . 1))))
-@end lisp
-
-Fetching data from this structure:
-
-@lisp
-(bindat-get-field decoded 'item 1 'id)
- @result{} "BCDEFG"
-@end lisp
-
-@ignore
- arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/searching
-@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
-@chapter Searching and Matching
-@cindex searching
-
- GNU Emacs provides two ways to search through a buffer for specified
-text: exact string searches and regular expression searches. After a
-regular expression search, you can examine the @dfn{match data} to
-determine which text matched the whole regular expression or various
-portions of it.
-
-@menu
-* 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,...
-@end menu
-
- The @samp{skip-chars@dots{}} functions also perform a kind of searching.
-@xref{Skipping Characters}. To search for changes in character
-properties, see @ref{Property Search}.
-
-@node String Search
-@section Searching for Strings
-@cindex string search
-
- These are the primitive functions for searching through the text in a
-buffer. They are meant for use in programs, but you may call them
-interactively. If you do so, they prompt for the search string; the
-arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
-is 1.
-
- These search functions convert the search string to multibyte if the
-buffer is multibyte; they convert the search string to unibyte if the
-buffer is unibyte. @xref{Text Representations}.
-
-@deffn Command search-forward string &optional limit noerror repeat
-This function searches forward from point for an exact match for
-@var{string}. If successful, it sets point to the end of the occurrence
-found, and returns the new value of point. If no match is found, the
-value and side effects depend on @var{noerror} (see below).
-@c Emacs 19 feature
-
-In the following example, point is initially at the beginning of the
-line. Then @code{(search-forward "fox")} moves point after the last
-letter of @samp{fox}:
-
-@example
-@group
----------- Buffer: foo ----------
-@point{}The quick brown fox jumped over the lazy dog.
----------- Buffer: foo ----------
-@end group
-
-@group
-(search-forward "fox")
- @result{} 20
-
----------- Buffer: foo ----------
-The quick brown fox@point{} jumped over the lazy dog.
----------- Buffer: foo ----------
-@end group
-@end example
-
-The argument @var{limit} specifies the upper bound to the search. (It
-must be a position in the current buffer.) No match extending after
-that position is accepted. If @var{limit} is omitted or @code{nil}, it
-defaults to the end of the accessible portion of the buffer.
-
-@kindex search-failed
-What happens when the search fails depends on the value of
-@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
-error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
-returns @code{nil} and does nothing. If @var{noerror} is neither
-@code{nil} nor @code{t}, then @code{search-forward} moves point to the
-upper bound and returns @code{nil}. (It would be more consistent now to
-return the new position of point in that case, but some existing
-programs may depend on a value of @code{nil}.)
-
-The argument @var{noerror} only affects valid searches which fail to
-find a match. Invalid arguments cause errors regardless of
-@var{noerror}.
-
-If @var{repeat} is supplied (it must be a positive number), then the
-search is repeated that many times (each time starting at the end of the
-previous time's match). If these successive searches succeed, the
-function succeeds, moving point and returning its new value. Otherwise
-the search fails, with results depending on the value of
-@var{noerror}, as described above.
-@end deffn
-
-@deffn Command search-backward string &optional limit noerror repeat
-This function searches backward from point for @var{string}. It is
-just like @code{search-forward} except that it searches backwards and
-leaves point at the beginning of the match.
-@end deffn
-
-@deffn Command word-search-forward string &optional limit noerror repeat
-@c @cindex word search Redundant
-This function searches forward from point for a ``word'' match for
-@var{string}. If it finds a match, it sets point to the end of the
-match found, and returns the new value of point.
-@c Emacs 19 feature
-
-Word matching regards @var{string} as a sequence of words, disregarding
-punctuation that separates them. It searches the buffer for the same
-sequence of words. Each word must be distinct in the buffer (searching
-for the word @samp{ball} does not match the word @samp{balls}), but the
-details of punctuation and spacing are ignored (searching for @samp{ball
-boy} does match @samp{ball. Boy!}).
-
-In this example, point is initially at the beginning of the buffer; the
-search leaves it between the @samp{y} and the @samp{!}.
-
-@example
-@group
----------- Buffer: foo ----------
-@point{}He said "Please! Find
-the ball boy!"
----------- Buffer: foo ----------
-@end group
-
-@group
-(word-search-forward "Please find the ball, boy.")
- @result{} 35
-
----------- Buffer: foo ----------
-He said "Please! Find
-the ball boy@point{}!"
----------- Buffer: foo ----------
-@end group
-@end example
-
-If @var{limit} is non-@code{nil}, it must be a position in the current
-buffer; it specifies the upper bound to the search. The match found
-must not extend after that position.
-
-If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
-an error if the search fails. If @var{noerror} is @code{t}, then it
-returns @code{nil} instead of signaling an error. If @var{noerror} is
-neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
-end of the accessible portion of the buffer) and returns @code{nil}.
-
-If @var{repeat} is non-@code{nil}, then the search is repeated that many
-times. Point is positioned at the end of the last match.
-@end deffn
-
-@deffn Command word-search-backward string &optional limit noerror repeat
-This function searches backward from point for a word match to
-@var{string}. This function is just like @code{word-search-forward}
-except that it searches backward and normally leaves point at the
-beginning of the match.
-@end deffn
-
-@node Searching and Case
-@section Searching and Case
-@cindex searching and case
-
- By default, searches in Emacs ignore the case of the text they are
-searching through; if you specify searching for @samp{FOO}, then
-@samp{Foo} or @samp{foo} is also considered a match. This applies to
-regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
-@samp{A} or @samp{b} or @samp{B}.
-
- If you do not want this feature, set the variable
-@code{case-fold-search} to @code{nil}. Then all letters must match
-exactly, including case. This is a buffer-local variable; altering the
-variable affects only the current buffer. (@xref{Intro to
-Buffer-Local}.) Alternatively, you may change the value of
-@code{default-case-fold-search}, which is the default value of
-@code{case-fold-search} for buffers that do not override it.
-
- Note that the user-level incremental search feature handles case
-distinctions differently. When given a lower case letter, it looks for
-a match of either case, but when given an upper case letter, it looks
-for an upper case letter only. But this has nothing to do with the
-searching functions used in Lisp code.
-
-@defopt case-replace
-This variable determines whether the higher level replacement
-functions should preserve case. If the variable is @code{nil}, that
-means to use the replacement text verbatim. A non-@code{nil} value
-means to convert the case of the replacement text according to the
-text being replaced.
-
-This variable is used by passing it as an argument to the function
-@code{replace-match}. @xref{Replacing Match}.
-@end defopt
-
-@defopt case-fold-search
-This buffer-local variable determines whether searches should ignore
-case. If the variable is @code{nil} they do not ignore case; otherwise
-they do ignore case.
-@end defopt
-
-@defvar default-case-fold-search
-The value of this variable is the default value for
-@code{case-fold-search} in buffers that do not override it. This is the
-same as @code{(default-value 'case-fold-search)}.
-@end defvar
-
-@node Regular Expressions
-@section Regular Expressions
-@cindex regular expression
-@cindex regexp
-
- A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
-denotes a (possibly infinite) set of strings. Searching for matches for
-a regexp is a very powerful operation. This section explains how to write
-regexps; the following section says how to search for them.
-
-@findex re-builder
-@cindex regular expressions, developing
- For convenient interactive development of regular expressions, you
-can use the @kbd{M-x re-builder} command. It provides a convenient
-interface for creating regular expressions, by giving immediate visual
-feedback in a separate buffer. As you edit the regexp, all its
-matches in the target buffer are highlighted. Each parenthesized
-sub-expression of the regexp is shown in a distinct face, which makes
-it easier to verify even very complex regexps.
-
-@menu
-* Syntax of Regexps:: Rules for writing regular expressions.
-* Regexp Example:: Illustrates regular expression syntax.
-* Regexp Functions:: Functions for operating on regular expressions.
-@end menu
-
-@node Syntax of Regexps
-@subsection Syntax of Regular Expressions
-
- Regular expressions have a syntax in which a few characters are
-special constructs and the rest are @dfn{ordinary}. An ordinary
-character is a simple regular expression that matches that character
-and nothing else. The special characters are @samp{.}, @samp{*},
-@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
-special characters will be defined in the future. The character
-@samp{]} is special if it ends a character alternative (see later).
-The character @samp{-} is special inside a character alternative. A
-@samp{[:} and balancing @samp{:]} enclose a character class inside a
-character alternative. Any other character appearing in a regular
-expression is ordinary, unless a @samp{\} precedes it.
-
- For example, @samp{f} is not a special character, so it is ordinary, and
-therefore @samp{f} is a regular expression that matches the string
-@samp{f} and no other string. (It does @emph{not} match the string
-@samp{fg}, but it does match a @emph{part} of that string.) Likewise,
-@samp{o} is a regular expression that matches only @samp{o}.@refill
-
- Any two regular expressions @var{a} and @var{b} can be concatenated. The
-result is a regular expression that matches a string if @var{a} matches
-some amount of the beginning of that string and @var{b} matches the rest of
-the string.@refill
-
- As a simple example, we can concatenate the regular expressions @samp{f}
-and @samp{o} to get the regular expression @samp{fo}, which matches only
-the string @samp{fo}. Still trivial. To do something more powerful, you
-need to use one of the special regular expression constructs.
-
-@menu
-* Regexp Special:: Special characters in regular expressions.
-* Char Classes:: Character classes used in regular expressions.
-* Regexp Backslash:: Backslash-sequences in regular expressions.
-@end menu
-
-@node Regexp Special
-@subsubsection Special Characters in Regular Expressions
-
- Here is a list of the characters that are special in a regular
-expression.
-
-@need 800
-@table @asis
-@item @samp{.}@: @r{(Period)}
-@cindex @samp{.} in regexp
-is a special character that matches any single character except a newline.
-Using concatenation, we can make regular expressions like @samp{a.b}, which
-matches any three-character string that begins with @samp{a} and ends with
-@samp{b}.@refill
-
-@item @samp{*}
-@cindex @samp{*} in regexp
-is not a construct by itself; it is a postfix operator that means to
-match the preceding regular expression repetitively as many times as
-possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
-@samp{o}s).
-
-@samp{*} always applies to the @emph{smallest} possible preceding
-expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
-@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
-
-The matcher processes a @samp{*} construct by matching, immediately, as
-many repetitions as can be found. Then it continues with the rest of
-the pattern. If that fails, backtracking occurs, discarding some of the
-matches of the @samp{*}-modified construct in the hope that that will
-make it possible to match the rest of the pattern. For example, in
-matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
-first tries to match all three @samp{a}s; but the rest of the pattern is
-@samp{ar} and there is only @samp{r} left to match, so this try fails.
-The next alternative is for @samp{a*} to match only two @samp{a}s. With
-this choice, the rest of the regexp matches successfully.
-
-@strong{Warning:} Nested repetition operators can run for an
-indefinitely long time, if they lead to ambiguous matching. For
-example, trying to match the regular expression @samp{\(x+y*\)*a}
-against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
-take hours before it ultimately fails. Emacs must try each way of
-grouping the @samp{x}s before concluding that none of them can work.
-Even worse, @samp{\(x*\)*} can match the null string in infinitely
-many ways, so it causes an infinite loop. To avoid these problems,
-check nested repetitions carefully, to make sure that they do not
-cause combinatorial explosions in backtracking.
-
-@item @samp{+}
-@cindex @samp{+} in regexp
-is a postfix operator, similar to @samp{*} except that it must match
-the preceding expression at least once. So, for example, @samp{ca+r}
-matches the strings @samp{car} and @samp{caaaar} but not the string
-@samp{cr}, whereas @samp{ca*r} matches all three strings.
-
-@item @samp{?}
-@cindex @samp{?} in regexp
-is a postfix operator, similar to @samp{*} except that it must match the
-preceding expression either once or not at all. For example,
-@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
-
-@item @samp{*?}, @samp{+?}, @samp{??}
-These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
-and @samp{?}. Where those operators match the largest possible
-substring (consistent with matching the entire containing expression),
-the non-greedy variants match the smallest possible substring
-(consistent with matching the entire containing expression).
-
-For example, the regular expression @samp{c[ad]*a} when applied to the
-string @samp{cdaaada} matches the whole string; but the regular
-expression @samp{c[ad]*?a}, applied to that same string, matches just
-@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
-permits the whole expression to match is @samp{d}.)
-
-@item @samp{[ @dots{} ]}
-@cindex character alternative (in regexp)
-@cindex @samp{[} in regexp
-@cindex @samp{]} in regexp
-is a @dfn{character alternative}, which begins with @samp{[} and is
-terminated by @samp{]}. In the simplest case, the characters between
-the two brackets are what this character alternative can match.
-
-Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
-@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
-(including the empty string), from which it follows that @samp{c[ad]*r}
-matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
-
-You can also include character ranges in a character alternative, by
-writing the starting and ending characters with a @samp{-} between them.
-Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
-Ranges may be intermixed freely with individual characters, as in
-@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
-or @samp{$}, @samp{%} or period.
-
-Note that the usual regexp special characters are not special inside a
-character alternative. A completely different set of characters is
-special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
-
-To include a @samp{]} in a character alternative, you must make it the
-first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
-To include a @samp{-}, write @samp{-} as the first or last character of
-the character alternative, or put it after a range. Thus, @samp{[]-]}
-matches both @samp{]} and @samp{-}.
-
-To include @samp{^} in a character alternative, put it anywhere but at
-the beginning.
-
-The beginning and end of a range of multibyte characters must be in
-the same character set (@pxref{Character Sets}). Thus,
-@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
-with grave accent) is in the Emacs character set for Latin-1 but the
-character 0x97c (@samp{u} with diaeresis) is in the Emacs character
-set for Latin-2. (We use Lisp string syntax to write that example,
-and a few others in the next few paragraphs, in order to include hex
-escape sequences in them.)
-
-If a range starts with a unibyte character @var{c} and ends with a
-multibyte character @var{c2}, the range is divided into two parts: one
-is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
-@var{c1} is the first character of the charset to which @var{c2}
-belongs.
-
-You cannot always match all non-@acronym{ASCII} characters with the regular
-expression @code{"[\200-\377]"}. This works when searching a unibyte
-buffer or string (@pxref{Text Representations}), but not in a multibyte
-buffer or string, because many non-@acronym{ASCII} characters have codes
-above octal 0377. However, the regular expression @code{"[^\000-\177]"}
-does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
-in both multibyte and unibyte representations, because only the
-@acronym{ASCII} characters are excluded.
-
-A character alternative can also specify named
-character classes (@pxref{Char Classes}). This is a POSIX feature whose
-syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
-to mentioning each of the characters in that class; but the latter is
-not feasible in practice, since some classes include thousands of
-different characters.
-
-@item @samp{[^ @dots{} ]}
-@cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complemented character alternative}. This
-matches any character except the ones specified. Thus,
-@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
-digits.
-
-@samp{^} is not special in a character alternative unless it is the first
-character. The character following the @samp{^} is treated as if it
-were first (in other words, @samp{-} and @samp{]} are not special there).
-
-A complemented character alternative can match a newline, unless newline is
-mentioned as one of the characters not to match. This is in contrast to
-the handling of regexps in programs such as @code{grep}.
-
-@item @samp{^}
-@cindex beginning of line in regexp
-When matching a buffer, @samp{^} matches the empty string, but only at the
-beginning of a line in the text being matched (or the beginning of the
-accessible portion of the buffer). Otherwise it fails to match
-anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
-beginning of a line.
-
-When matching a string instead of a buffer, @samp{^} matches at the
-beginning of the string or after a newline character.
-
-For historical compatibility reasons, @samp{^} can be used only at the
-beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
-or @samp{\|}.
-
-@item @samp{$}
-@cindex @samp{$} in regexp
-@cindex end of line in regexp
-is similar to @samp{^} but matches only at the end of a line (or the
-end of the accessible portion of the buffer). Thus, @samp{x+$}
-matches a string of one @samp{x} or more at the end of a line.
-
-When matching a string instead of a buffer, @samp{$} matches at the end
-of the string or before a newline character.
-
-For historical compatibility reasons, @samp{$} can be used only at the
-end of the regular expression, or before @samp{\)} or @samp{\|}.
-
-@item @samp{\}
-@cindex @samp{\} in regexp
-has two functions: it quotes the special characters (including
-@samp{\}), and it introduces additional special constructs.
-
-Because @samp{\} quotes special characters, @samp{\$} is a regular
-expression that matches only @samp{$}, and @samp{\[} is a regular
-expression that matches only @samp{[}, and so on.
-
-Note that @samp{\} also has special meaning in the read syntax of Lisp
-strings (@pxref{String Type}), and must be quoted with @samp{\}. For
-example, the regular expression that matches the @samp{\} character is
-@samp{\\}. To write a Lisp string that contains the characters
-@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
-@samp{\}. Therefore, the read syntax for a regular expression matching
-@samp{\} is @code{"\\\\"}.@refill
-@end table
-
-@strong{Please note:} For historical compatibility, special characters
-are treated as ordinary ones if they are in contexts where their special
-meanings make no sense. For example, @samp{*foo} treats @samp{*} as
-ordinary since there is no preceding expression on which the @samp{*}
-can act. It is poor practice to depend on this behavior; quote the
-special character anyway, regardless of where it appears.@refill
-
-As a @samp{\} is not special inside a character alternative, it can
-never remove the special meaning of @samp{-} or @samp{]}. So you
-should not quote these characters when they have no special meaning
-either. This would not clarify anything, since backslashes can
-legitimately precede these characters where they @emph{have} special
-meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
-which matches any single character except a backslash.
-
-In practice, most @samp{]} that occur in regular expressions close a
-character alternative and hence are special. However, occasionally a
-regular expression may try to match a complex pattern of literal
-@samp{[} and @samp{]}. In such situations, it sometimes may be
-necessary to carefully parse the regexp from the start to determine
-which square brackets enclose a character alternative. For example,
-@samp{[^][]]} consists of the complemented character alternative
-@samp{[^][]} (which matches any single character that is not a square
-bracket), followed by a literal @samp{]}.
-
-The exact rules are that at the beginning of a regexp, @samp{[} is
-special and @samp{]} not. This lasts until the first unquoted
-@samp{[}, after which we are in a character alternative; @samp{[} is
-no longer special (except when it starts a character class) but @samp{]}
-is special, unless it immediately follows the special @samp{[} or that
-@samp{[} followed by a @samp{^}. This lasts until the next special
-@samp{]} that does not end a character class. This ends the character
-alternative and restores the ordinary syntax of regular expressions;
-an unquoted @samp{[} is special again and a @samp{]} not.
-
-@node Char Classes
-@subsubsection Character Classes
-@cindex character classes in regexp
-
- Here is a table of the classes you can use in a character alternative,
-and what they mean:
-
-@table @samp
-@item [:ascii:]
-This matches any @acronym{ASCII} character (codes 0--127).
-@item [:alnum:]
-This matches any letter or digit. (At present, for multibyte
-characters, it matches anything that has word syntax.)
-@item [:alpha:]
-This matches any letter. (At present, for multibyte characters, it
-matches anything that has word syntax.)
-@item [:blank:]
-This matches space and tab only.
-@item [:cntrl:]
-This matches any @acronym{ASCII} control character.
-@item [:digit:]
-This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
-matches any digit, as well as @samp{+} and @samp{-}.
-@item [:graph:]
-This matches graphic characters---everything except @acronym{ASCII} control
-characters, space, and the delete character.
-@item [:lower:]
-This matches any lower-case letter, as determined by
-the current case table (@pxref{Case Tables}).
-@item [:multibyte:]
-This matches any multibyte character (@pxref{Text Representations}).
-@item [:nonascii:]
-This matches any non-@acronym{ASCII} character.
-@item [:print:]
-This matches printing characters---everything except @acronym{ASCII} control
-characters and the delete character.
-@item [:punct:]
-This matches any punctuation character. (At present, for multibyte
-characters, it matches anything that has non-word syntax.)
-@item [:space:]
-This matches any character that has whitespace syntax
-(@pxref{Syntax Class Table}).
-@item [:unibyte:]
-This matches any unibyte character (@pxref{Text Representations}).
-@item [:upper:]
-This matches any upper-case letter, as determined by
-the current case table (@pxref{Case Tables}).
-@item [:word:]
-This matches any character that has word syntax (@pxref{Syntax Class
-Table}).
-@item [:xdigit:]
-This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
-through @samp{f} and @samp{A} through @samp{F}.
-@end table
-
-@node Regexp Backslash
-@subsubsection Backslash Constructs in Regular Expressions
-
- For the most part, @samp{\} followed by any character matches only
-that character. However, there are several exceptions: certain
-two-character sequences starting with @samp{\} that have special
-meanings. (The character after the @samp{\} in such a sequence is
-always ordinary when used on its own.) Here is a table of the special
-@samp{\} constructs.
-
-@table @samp
-@item \|
-@cindex @samp{|} in regexp
-@cindex regexp alternative
-specifies an alternative.
-Two regular expressions @var{a} and @var{b} with @samp{\|} in
-between form an expression that matches anything that either @var{a} or
-@var{b} matches.@refill
-
-Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
-but no other string.@refill
-
-@samp{\|} applies to the largest possible surrounding expressions. Only a
-surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
-@samp{\|}.@refill
-
-If you need full backtracking capability to handle multiple uses of
-@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
-Regexps}).
-
-@item \@{@var{m}\@}
-is a postfix operator that repeats the previous pattern exactly @var{m}
-times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
-and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
-@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
-
-@item \@{@var{m},@var{n}\@}
-is a more general postfix operator that specifies repetition with a
-minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
-is omitted, the minimum is 0; if @var{n} is omitted, there is no
-maximum.
-
-For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
-@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
-nothing else.@*
-@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @*
-@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @*
-@samp{\@{1,\@}} is equivalent to @samp{+}.
-
-@item \( @dots{} \)
-@cindex @samp{(} in regexp
-@cindex @samp{)} in regexp
-@cindex regexp grouping
-is a grouping construct that serves three purposes:
-
-@enumerate
-@item
-To enclose a set of @samp{\|} alternatives for other operations. Thus,
-the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
-or @samp{barx}.
-
-@item
-To enclose a complicated expression for the postfix operators @samp{*},
-@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
-@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
-number (zero or more) of @samp{na} strings.
-
-@item
-To record a matched substring for future reference with
-@samp{\@var{digit}} (see below).
-@end enumerate
-
-This last application is not a consequence of the idea of a
-parenthetical grouping; it is a separate feature that was assigned as a
-second meaning to the same @samp{\( @dots{} \)} construct because, in
-practice, there was usually no conflict between the two meanings. But
-occasionally there is a conflict, and that led to the introduction of
-shy groups.
-
-@item \(?: @dots{} \)
-is the @dfn{shy group} construct. A shy group serves the first two
-purposes of an ordinary group (controlling the nesting of other
-operators), but it does not get a number, so you cannot refer back to
-its value with @samp{\@var{digit}}.
-
-Shy groups are particularly useful for mechanically-constructed regular
-expressions because they can be added automatically without altering the
-numbering of any ordinary, non-shy groups.
-
-@item \(?@var{num}: @dots{} \)
-is the @dfn{explicitly numbered group} construct. Normal groups get
-their number implicitly, based on their position, which can be
-inconvenient. This construct allows you to force a particular group
-number. There is no particular restriction on the numbering,
-e.g.@: you can have several groups with the same number in which case
-the last one to match (i.e.@: the rightmost match) will win.
-Implicitly numbered groups always get the smallest integer larger than
-the one of any previous group.
-
-@item \@var{digit}
-matches the same text that matched the @var{digit}th occurrence of a
-grouping (@samp{\( @dots{} \)}) construct.
-
-In other words, after the end of a group, the matcher remembers the
-beginning and end of the text matched by that group. Later on in the
-regular expression you can use @samp{\} followed by @var{digit} to
-match that same text, whatever it may have been.
-
-The strings matching the first nine grouping constructs appearing in
-the entire regular expression passed to a search or matching function
-are assigned numbers 1 through 9 in the order that the open
-parentheses appear in the regular expression. So you can use
-@samp{\1} through @samp{\9} to refer to the text matched by the
-corresponding grouping constructs.
-
-For example, @samp{\(.*\)\1} matches any newline-free string that is
-composed of two identical halves. The @samp{\(.*\)} matches the first
-half, which may be anything, but the @samp{\1} that follows must match
-the same exact text.
-
-If a @samp{\( @dots{} \)} construct matches more than once (which can
-happen, for instance, if it is followed by @samp{*}), only the last
-match is recorded.
-
-If a particular grouping construct in the regular expression was never
-matched---for instance, if it appears inside of an alternative that
-wasn't used, or inside of a repetition that repeated zero times---then
-the corresponding @samp{\@var{digit}} construct never matches
-anything. To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2}
-cannot match @samp{lose}: the second alternative inside the larger
-group matches it, but then @samp{\2} is undefined and can't match
-anything. But it can match @samp{foobb}, because the first
-alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
-
-@item \w
-@cindex @samp{\w} in regexp
-matches any word-constituent character. The editor syntax table
-determines which characters these are. @xref{Syntax Tables}.
-
-@item \W
-@cindex @samp{\W} in regexp
-matches any character that is not a word constituent.
-
-@item \s@var{code}
-@cindex @samp{\s} in regexp
-matches any character whose syntax is @var{code}. Here @var{code} is a
-character that represents a syntax code: thus, @samp{w} for word
-constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
-etc. To represent whitespace syntax, use either @samp{-} or a space
-character. @xref{Syntax Class Table}, for a list of syntax codes and
-the characters that stand for them.
-
-@item \S@var{code}
-@cindex @samp{\S} in regexp
-matches any character whose syntax is not @var{code}.
-
-@item \c@var{c}
-matches any character whose category is @var{c}. Here @var{c} is a
-character that represents a category: thus, @samp{c} for Chinese
-characters or @samp{g} for Greek characters in the standard category
-table.
-
-@item \C@var{c}
-matches any character whose category is not @var{c}.
-@end table
-
- The following regular expression constructs match the empty string---that is,
-they don't use up any characters---but whether they match depends on the
-context. For all, the beginning and end of the accessible portion of
-the buffer are treated as if they were the actual beginning and end of
-the buffer.
-
-@table @samp
-@item \`
-@cindex @samp{\`} in regexp
-matches the empty string, but only at the beginning
-of the buffer or string being matched against.
-
-@item \'
-@cindex @samp{\'} in regexp
-matches the empty string, but only at the end of
-the buffer or string being matched against.
-
-@item \=
-@cindex @samp{\=} in regexp
-matches the empty string, but only at point.
-(This construct is not defined when matching against a string.)
-
-@item \b
-@cindex @samp{\b} in regexp
-matches the empty string, but only at the beginning or
-end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
-@samp{foo} as a separate word. @samp{\bballs?\b} matches
-@samp{ball} or @samp{balls} as a separate word.@refill
-
-@samp{\b} matches at the beginning or end of the buffer (or string)
-regardless of what text appears next to it.
-
-@item \B
-@cindex @samp{\B} in regexp
-matches the empty string, but @emph{not} at the beginning or
-end of a word, nor at the beginning or end of the buffer (or string).
-
-@item \<
-@cindex @samp{\<} in regexp
-matches the empty string, but only at the beginning of a word.
-@samp{\<} matches at the beginning of the buffer (or string) only if a
-word-constituent character follows.
-
-@item \>
-@cindex @samp{\>} in regexp
-matches the empty string, but only at the end of a word. @samp{\>}
-matches at the end of the buffer (or string) only if the contents end
-with a word-constituent character.
-
-@item \_<
-@cindex @samp{\_<} in regexp
-matches the empty string, but only at the beginning of a symbol. A
-symbol is a sequence of one or more word or symbol constituent
-characters. @samp{\_<} matches at the beginning of the buffer (or
-string) only if a symbol-constituent character follows.
-
-@item \_>
-@cindex @samp{\_>} in regexp
-matches the empty string, but only at the end of a symbol. @samp{\_>}
-matches at the end of the buffer (or string) only if the contents end
-with a symbol-constituent character.
-@end table
-
-@kindex invalid-regexp
- Not every string is a valid regular expression. For example, a string
-that ends inside a character alternative without terminating @samp{]}
-is invalid, and so is a string that ends with a single @samp{\}. If
-an invalid regular expression is passed to any of the search functions,
-an @code{invalid-regexp} error is signaled.
-
-@node Regexp Example
-@comment node-name, next, previous, up
-@subsection Complex Regexp Example
-
- Here is a complicated regexp which was formerly used by Emacs to
-recognize the end of a sentence together with any whitespace that
-follows. (Nowadays Emacs uses a similar but more complex default
-regexp constructed by the function @code{sentence-end}.
-@xref{Standard Regexps}.)
-
- First, we show the regexp as a string in Lisp syntax to distinguish
-spaces from tab characters. The string constant begins and ends with a
-double-quote. @samp{\"} stands for a double-quote as part of the
-string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
-tab and @samp{\n} for a newline.
-
-@example
-"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
-@end example
-
-@noindent
-In contrast, if you evaluate this string, you will see the following:
-
-@example
-@group
-"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
- @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
-]*"
-@end group
-@end example
-
-@noindent
-In this output, tab and newline appear as themselves.
-
- This regular expression contains four parts in succession and can be
-deciphered as follows:
-
-@table @code
-@item [.?!]
-The first part of the pattern is a character alternative that matches
-any one of three characters: period, question mark, and exclamation
-mark. The match must begin with one of these three characters. (This
-is one point where the new default regexp used by Emacs differs from
-the old. The new value also allows some non-@acronym{ASCII}
-characters that end a sentence without any following whitespace.)
-
-@item []\"')@}]*
-The second part of the pattern matches any closing braces and quotation
-marks, zero or more of them, that may follow the period, question mark
-or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
-a string. The @samp{*} at the end indicates that the immediately
-preceding regular expression (a character alternative, in this case) may be
-repeated zero or more times.
-
-@item \\($\\|@ $\\|\t\\|@ @ \\)
-The third part of the pattern matches the whitespace that follows the
-end of a sentence: the end of a line (optionally with a space), or a
-tab, or two spaces. The double backslashes mark the parentheses and
-vertical bars as regular expression syntax; the parentheses delimit a
-group and the vertical bars separate alternatives. The dollar sign is
-used to match the end of a line.
-
-@item [ \t\n]*
-Finally, the last part of the pattern matches any additional whitespace
-beyond the minimum needed to end a sentence.
-@end table
-
-@node Regexp Functions
-@subsection Regular Expression Functions
-
- These functions operate on regular expressions.
-
-@defun regexp-quote string
-This function returns a regular expression whose only exact match is
-@var{string}. Using this regular expression in @code{looking-at} will
-succeed only if the next characters in the buffer are @var{string};
-using it in a search function will succeed if the text being searched
-contains @var{string}.
-
-This allows you to request an exact string match or search when calling
-a function that wants a regular expression.
-
-@example
-@group
-(regexp-quote "^The cat$")
- @result{} "\\^The cat\\$"
-@end group
-@end example
-
-One use of @code{regexp-quote} is to combine an exact string match with
-context described as a regular expression. For example, this searches
-for the string that is the value of @var{string}, surrounded by
-whitespace:
-
-@example
-@group
-(re-search-forward
- (concat "\\s-" (regexp-quote string) "\\s-"))
-@end group
-@end example
-@end defun
-
-@defun regexp-opt strings &optional paren
-This function returns an efficient regular expression that will match
-any of the strings in the list @var{strings}. This is useful when you
-need to make matching or searching as fast as possible---for example,
-for Font Lock mode.
-
-If the optional argument @var{paren} is non-@code{nil}, then the
-returned regular expression is always enclosed by at least one
-parentheses-grouping construct. If @var{paren} is @code{words}, then
-that construct is additionally surrounded by @samp{\<} and @samp{\>}.
-
-This simplified definition of @code{regexp-opt} produces a
-regular expression which is equivalent to the actual value
-(but not as efficient):
-
-@example
-(defun regexp-opt (strings paren)
- (let ((open-paren (if paren "\\(" ""))
- (close-paren (if paren "\\)" "")))
- (concat open-paren
- (mapconcat 'regexp-quote strings "\\|")
- close-paren)))
-@end example
-@end defun
-
-@defun regexp-opt-depth regexp
-This function returns the total number of grouping constructs
-(parenthesized expressions) in @var{regexp}. (This does not include
-shy groups.)
-@end defun
-
-@node Regexp Search
-@section Regular Expression Searching
-@cindex regular expression searching
-@cindex regexp searching
-@cindex searching for regexp
-
- In GNU Emacs, you can search for the next match for a regular
-expression either incrementally or not. For incremental search
-commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
-The GNU Emacs Manual}. Here we describe only the search functions
-useful in programs. The principal one is @code{re-search-forward}.
-
- These search functions convert the regular expression to multibyte if
-the buffer is multibyte; they convert the regular expression to unibyte
-if the buffer is unibyte. @xref{Text Representations}.
-
-@deffn Command re-search-forward regexp &optional limit noerror repeat
-This function searches forward in the current buffer for a string of
-text that is matched by the regular expression @var{regexp}. The
-function skips over any amount of text that is not matched by
-@var{regexp}, and leaves point at the end of the first match found.
-It returns the new value of point.
-
-If @var{limit} is non-@code{nil}, it must be a position in the current
-buffer. It specifies the upper bound to the search. No match
-extending after that position is accepted.
-
-If @var{repeat} is supplied, it must be a positive number; the search
-is repeated that many times; each repetition starts at the end of the
-previous match. If all these successive searches succeed, the search
-succeeds, moving point and returning its new value. Otherwise the
-search fails. What @code{re-search-forward} does when the search
-fails depends on the value of @var{noerror}:
-
-@table @asis
-@item @code{nil}
-Signal a @code{search-failed} error.
-@item @code{t}
-Do nothing and return @code{nil}.
-@item anything else
-Move point to @var{limit} (or the end of the accessible portion of the
-buffer) and return @code{nil}.
-@end table
-
-In the following example, point is initially before the @samp{T}.
-Evaluating the search call moves point to the end of that line (between
-the @samp{t} of @samp{hat} and the newline).
-
-@example
-@group
----------- Buffer: foo ----------
-I read "@point{}The cat in the hat
-comes back" twice.
----------- Buffer: foo ----------
-@end group
-
-@group
-(re-search-forward "[a-z]+" nil t 5)
- @result{} 27
-
----------- Buffer: foo ----------
-I read "The cat in the hat@point{}
-comes back" twice.
----------- Buffer: foo ----------
-@end group
-@end example
-@end deffn
-
-@deffn Command re-search-backward regexp &optional limit noerror repeat
-This function searches backward in the current buffer for a string of
-text that is matched by the regular expression @var{regexp}, leaving
-point at the beginning of the first text found.
-
-This function is analogous to @code{re-search-forward}, but they are not
-simple mirror images. @code{re-search-forward} finds the match whose
-beginning is as close as possible to the starting point. If
-@code{re-search-backward} were a perfect mirror image, it would find the
-match whose end is as close as possible. However, in fact it finds the
-match whose beginning is as close as possible (and yet ends before the
-starting point). The reason for this is that matching a regular
-expression at a given spot always works from beginning to end, and
-starts at a specified beginning position.
-
-A true mirror-image of @code{re-search-forward} would require a special
-feature for matching regular expressions from end to beginning. It's
-not worth the trouble of implementing that.
-@end deffn
-
-@defun string-match regexp string &optional start
-This function returns the index of the start of the first match for
-the regular expression @var{regexp} in @var{string}, or @code{nil} if
-there is no match. If @var{start} is non-@code{nil}, the search starts
-at that index in @var{string}.
-
-For example,
-
-@example
-@group
-(string-match
- "quick" "The quick brown fox jumped quickly.")
- @result{} 4
-@end group
-@group
-(string-match
- "quick" "The quick brown fox jumped quickly." 8)
- @result{} 27
-@end group
-@end example
-
-@noindent
-The index of the first character of the
-string is 0, the index of the second character is 1, and so on.
-
-After this function returns, the index of the first character beyond
-the match is available as @code{(match-end 0)}. @xref{Match Data}.
-
-@example
-@group
-(string-match
- "quick" "The quick brown fox jumped quickly." 8)
- @result{} 27
-@end group
-
-@group
-(match-end 0)
- @result{} 32
-@end group
-@end example
-@end defun
-
-@defun looking-at regexp
-This function determines whether the text in the current buffer directly
-following point matches the regular expression @var{regexp}. ``Directly
-following'' means precisely that: the search is ``anchored'' and it can
-succeed only starting with the first character following point. The
-result is @code{t} if so, @code{nil} otherwise.
-
-This function does not move point, but it updates the match data, which
-you can access using @code{match-beginning} and @code{match-end}.
-@xref{Match Data}.
-
-In this example, point is located directly before the @samp{T}. If it
-were anywhere else, the result would be @code{nil}.
-
-@example
-@group
----------- Buffer: foo ----------
-I read "@point{}The cat in the hat
-comes back" twice.
----------- Buffer: foo ----------
-
-(looking-at "The cat in the hat$")
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun looking-back regexp &optional limit
-This function returns @code{t} if @var{regexp} matches text before
-point, ending at point, and @code{nil} otherwise.
-
-Because regular expression matching works only going forward, this is
-implemented by searching backwards from point for a match that ends at
-point. That can be quite slow if it has to search a long distance.
-You can bound the time required by specifying @var{limit}, which says
-not to search before @var{limit}. In this case, the match that is
-found must begin at or after @var{limit}.
-
-@example
-@group
----------- Buffer: foo ----------
-I read "@point{}The cat in the hat
-comes back" twice.
----------- Buffer: foo ----------
-
-(looking-back "read \"" 3)
- @result{} t
-(looking-back "read \"" 4)
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defvar search-spaces-regexp
-If this variable is non-@code{nil}, it should be a regular expression
-that says how to search for whitespace. In that case, any group of
-spaces in a regular expression being searched for stands for use of
-this regular expression. However, spaces inside of constructs such as
-@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
-@code{search-spaces-regexp}.
-
-Since this variable affects all regular expression search and match
-constructs, you should bind it temporarily for as small as possible
-a part of the code.
-@end defvar
-
-@node POSIX Regexps
-@section POSIX Regular Expression Searching
-
- The usual regular expression functions do backtracking when necessary
-to handle the @samp{\|} and repetition constructs, but they continue
-this only until they find @emph{some} match. Then they succeed and
-report the first match found.
-
- This section describes alternative search functions which perform the
-full backtracking specified by the POSIX standard for regular expression
-matching. They continue backtracking until they have tried all
-possibilities and found all matches, so they can report the longest
-match, as required by POSIX. This is much slower, so use these
-functions only when you really need the longest match.
-
- The POSIX search and match functions do not properly support the
-non-greedy repetition operators. This is because POSIX backtracking
-conflicts with the semantics of non-greedy repetition.
-
-@defun posix-search-forward regexp &optional limit noerror repeat
-This is like @code{re-search-forward} except that it performs the full
-backtracking specified by the POSIX standard for regular expression
-matching.
-@end defun
-
-@defun posix-search-backward regexp &optional limit noerror repeat
-This is like @code{re-search-backward} except that it performs the full
-backtracking specified by the POSIX standard for regular expression
-matching.
-@end defun
-
-@defun posix-looking-at regexp
-This is like @code{looking-at} except that it performs the full
-backtracking specified by the POSIX standard for regular expression
-matching.
-@end defun
-
-@defun posix-string-match regexp string &optional start
-This is like @code{string-match} except that it performs the full
-backtracking specified by the POSIX standard for regular expression
-matching.
-@end defun
-
-@node Match Data
-@section The Match Data
-@cindex match data
-
- Emacs keeps track of the start and end positions of the segments of
-text found during a search; this is called the @dfn{match data}.
-Thanks to the match data, you can search for a complex pattern, such
-as a date in a mail message, and then extract parts of the match under
-control of the pattern.
-
- Because the match data normally describe the most recent search only,
-you must be careful not to do another search inadvertently between the
-search you wish to refer back to and the use of the match data. If you
-can't avoid another intervening search, you must save and restore the
-match data around it, to prevent it from being overwritten.
-
-@menu
-* 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.
-@end menu
-
-@node Replacing Match
-@subsection Replacing the Text that Matched
-@cindex replace matched text
-
- This function replaces all or part of the text matched by the last
-search. It works by means of the match data.
-
-@cindex case in replacements
-@defun replace-match replacement &optional fixedcase literal string subexp
-This function replaces the text in the buffer (or in @var{string}) that
-was matched by the last search. It replaces that text with
-@var{replacement}.
-
-If you did the last search in a buffer, you should specify @code{nil}
-for @var{string} and make sure that the current buffer when you call
-@code{replace-match} is the one in which you did the searching or
-matching. Then @code{replace-match} does the replacement by editing
-the buffer; it leaves point at the end of the replacement text, and
-returns @code{t}.
-
-If you did the search in a string, pass the same string as @var{string}.
-Then @code{replace-match} does the replacement by constructing and
-returning a new string.
-
-If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
-the replacement text without case conversion; otherwise, it converts
-the replacement text depending upon the capitalization of the text to
-be replaced. If the original text is all upper case, this converts
-the replacement text to upper case. If all words of the original text
-are capitalized, this capitalizes all the words of the replacement
-text. If all the words are one-letter and they are all upper case,
-they are treated as capitalized words rather than all-upper-case
-words.
-
-If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
-exactly as it is, the only alterations being case changes as needed.
-If it is @code{nil} (the default), then the character @samp{\} is treated
-specially. If a @samp{\} appears in @var{replacement}, then it must be
-part of one of the following sequences:
-
-@table @asis
-@item @samp{\&}
-@cindex @samp{&} in replacement
-@samp{\&} stands for the entire text being replaced.
-
-@item @samp{\@var{n}}
-@cindex @samp{\@var{n}} in replacement
-@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
-matched the @var{n}th subexpression in the original regexp.
-Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
-If the @var{n}th subexpression never matched, an empty string is substituted.
-
-@item @samp{\\}
-@cindex @samp{\} in replacement
-@samp{\\} stands for a single @samp{\} in the replacement text.
-@end table
-
-These substitutions occur after case conversion, if any,
-so the strings they substitute are never case-converted.
-
-If @var{subexp} is non-@code{nil}, that says to replace just
-subexpression number @var{subexp} of the regexp that was matched, not
-the entire match. For example, after matching @samp{foo \(ba*r\)},
-calling @code{replace-match} with 1 as @var{subexp} means to replace
-just the text that matched @samp{\(ba*r\)}.
-@end defun
-
-@node Simple Match Data
-@subsection Simple Match Data Access
-
- This section explains how to use the match data to find out what was
-matched by the last search or match operation, if it succeeded.
-
- You can ask about the entire matching text, or about a particular
-parenthetical subexpression of a regular expression. The @var{count}
-argument in the functions below specifies which. If @var{count} is
-zero, you are asking about the entire match. If @var{count} is
-positive, it specifies which subexpression you want.
-
- Recall that the subexpressions of a regular expression are those
-expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
-@var{count}th subexpression is found by counting occurrences of
-@samp{\(} from the beginning of the whole regular expression. The first
-subexpression is numbered 1, the second 2, and so on. Only regular
-expressions can have subexpressions---after a simple string search, the
-only information available is about the entire match.
-
- Every successful search sets the match data. Therefore, you should
-query the match data immediately after searching, before calling any
-other function that might perform another search. Alternatively, you
-may save and restore the match data (@pxref{Saving Match Data}) around
-the call to functions that could perform another search.
-
- A search which fails may or may not alter the match data. In the
-past, a failing search did not do this, but we may change it in the
-future. So don't try to rely on the value of the match data after
-a failing search.
-
-@defun match-string count &optional in-string
-This function returns, as a string, the text matched in the last search
-or match operation. It returns the entire text if @var{count} is zero,
-or just the portion corresponding to the @var{count}th parenthetical
-subexpression, if @var{count} is positive.
-
-If the last such operation was done against a string with
-@code{string-match}, then you should pass the same string as the
-argument @var{in-string}. After a buffer search or match,
-you should omit @var{in-string} or pass @code{nil} for it; but you
-should make sure that the current buffer when you call
-@code{match-string} is the one in which you did the searching or
-matching.
-
-The value is @code{nil} if @var{count} is out of range, or for a
-subexpression inside a @samp{\|} alternative that wasn't used or a
-repetition that repeated zero times.
-@end defun
-
-@defun match-string-no-properties count &optional in-string
-This function is like @code{match-string} except that the result
-has no text properties.
-@end defun
-
-@defun match-beginning count
-This function returns the position of the start of text matched by the
-last regular expression searched for, or a subexpression of it.
-
-If @var{count} is zero, then the value is the position of the start of
-the entire match. Otherwise, @var{count} specifies a subexpression in
-the regular expression, and the value of the function is the starting
-position of the match for that subexpression.
-
-The value is @code{nil} for a subexpression inside a @samp{\|}
-alternative that wasn't used or a repetition that repeated zero times.
-@end defun
-
-@defun match-end count
-This function is like @code{match-beginning} except that it returns the
-position of the end of the match, rather than the position of the
-beginning.
-@end defun
-
- Here is an example of using the match data, with a comment showing the
-positions within the text:
-
-@example
-@group
-(string-match "\\(qu\\)\\(ick\\)"
- "The quick fox jumped quickly.")
- ;0123456789
- @result{} 4
-@end group
-
-@group
-(match-string 0 "The quick fox jumped quickly.")
- @result{} "quick"
-(match-string 1 "The quick fox jumped quickly.")
- @result{} "qu"
-(match-string 2 "The quick fox jumped quickly.")
- @result{} "ick"
-@end group
-
-@group
-(match-beginning 1) ; @r{The beginning of the match}
- @result{} 4 ; @r{with @samp{qu} is at index 4.}
-@end group
-
-@group
-(match-beginning 2) ; @r{The beginning of the match}
- @result{} 6 ; @r{with @samp{ick} is at index 6.}
-@end group
-
-@group
-(match-end 1) ; @r{The end of the match}
- @result{} 6 ; @r{with @samp{qu} is at index 6.}
-
-(match-end 2) ; @r{The end of the match}
- @result{} 9 ; @r{with @samp{ick} is at index 9.}
-@end group
-@end example
-
- Here is another example. Point is initially located at the beginning
-of the line. Searching moves point to between the space and the word
-@samp{in}. The beginning of the entire match is at the 9th character of
-the buffer (@samp{T}), and the beginning of the match for the first
-subexpression is at the 13th character (@samp{c}).
-
-@example
-@group
-(list
- (re-search-forward "The \\(cat \\)")
- (match-beginning 0)
- (match-beginning 1))
- @result{} (9 9 13)
-@end group
-
-@group
----------- Buffer: foo ----------
-I read "The cat @point{}in the hat comes back" twice.
- ^ ^
- 9 13
----------- Buffer: foo ----------
-@end group
-@end example
-
-@noindent
-(In this case, the index returned is a buffer position; the first
-character of the buffer counts as 1.)
-
-@node Entire Match Data
-@subsection Accessing the Entire Match Data
-
- The functions @code{match-data} and @code{set-match-data} read or
-write the entire match data, all at once.
-
-@defun match-data &optional integers reuse reseat
-This function returns a list of positions (markers or integers) that
-record all the information on what text the last search matched.
-Element zero is the position of the beginning of the match for the
-whole expression; element one is the position of the end of the match
-for the expression. The next two elements are the positions of the
-beginning and end of the match for the first subexpression, and so on.
-In general, element
-@ifnottex
-number 2@var{n}
-@end ifnottex
-@tex
-number {\mathsurround=0pt $2n$}
-@end tex
-corresponds to @code{(match-beginning @var{n})}; and
-element
-@ifnottex
-number 2@var{n} + 1
-@end ifnottex
-@tex
-number {\mathsurround=0pt $2n+1$}
-@end tex
-corresponds to @code{(match-end @var{n})}.
-
-Normally all the elements are markers or @code{nil}, but if
-@var{integers} is non-@code{nil}, that means to use integers instead
-of markers. (In that case, the buffer itself is appended as an
-additional element at the end of the list, to facilitate complete
-restoration of the match data.) If the last match was done on a
-string with @code{string-match}, then integers are always used,
-since markers can't point into a string.
-
-If @var{reuse} is non-@code{nil}, it should be a list. In that case,
-@code{match-data} stores the match data in @var{reuse}. That is,
-@var{reuse} is destructively modified. @var{reuse} does not need to
-have the right length. If it is not long enough to contain the match
-data, it is extended. If it is too long, the length of @var{reuse}
-stays the same, but the elements that were not used are set to
-@code{nil}. The purpose of this feature is to reduce the need for
-garbage collection.
-
-If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
-are reseated to point to nowhere.
-
-As always, there must be no possibility of intervening searches between
-the call to a search function and the call to @code{match-data} that is
-intended to access the match data for that search.
-
-@example
-@group
-(match-data)
- @result{} (#<marker at 9 in foo>
- #<marker at 17 in foo>
- #<marker at 13 in foo>
- #<marker at 17 in foo>)
-@end group
-@end example
-@end defun
-
-@defun set-match-data match-list &optional reseat
-This function sets the match data from the elements of @var{match-list},
-which should be a list that was the value of a previous call to
-@code{match-data}. (More precisely, anything that has the same format
-will work.)
-
-If @var{match-list} refers to a buffer that doesn't exist, you don't get
-an error; that sets the match data in a meaningless but harmless way.
-
-If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
-are reseated to point to nowhere.
-
-@findex store-match-data
-@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
-@end defun
-
-@node Saving Match Data
-@subsection Saving and Restoring the Match Data
-
- When you call a function that may do a search, you may need to save
-and restore the match data around that call, if you want to preserve the
-match data from an earlier search for later use. Here is an example
-that shows the problem that arises if you fail to save the match data:
-
-@example
-@group
-(re-search-forward "The \\(cat \\)")
- @result{} 48
-(foo) ; @r{Perhaps @code{foo} does}
- ; @r{more searching.}
-(match-end 0)
- @result{} 61 ; @r{Unexpected result---not 48!}
-@end group
-@end example
-
- You can save and restore the match data with @code{save-match-data}:
-
-@defmac save-match-data body@dots{}
-This macro executes @var{body}, saving and restoring the match
-data around it. The return value is the value of the last form in
-@var{body}.
-@end defmac
-
- You could use @code{set-match-data} together with @code{match-data} to
-imitate the effect of the special form @code{save-match-data}. Here is
-how:
-
-@example
-@group
-(let ((data (match-data)))
- (unwind-protect
- @dots{} ; @r{Ok to change the original match data.}
- (set-match-data data)))
-@end group
-@end example
-
- Emacs automatically saves and restores the match data when it runs
-process filter functions (@pxref{Filter Functions}) and process
-sentinels (@pxref{Sentinels}).
-
-@ignore
- Here is a function which restores the match data provided the buffer
-associated with it still exists.
-
-@smallexample
-@group
-(defun restore-match-data (data)
-@c It is incorrect to split the first line of a doc string.
-@c If there's a problem here, it should be solved in some other way.
- "Restore the match data DATA unless the buffer is missing."
- (catch 'foo
- (let ((d data))
-@end group
- (while d
- (and (car d)
- (null (marker-buffer (car d)))
-@group
- ;; @file{match-data} @r{buffer is deleted.}
- (throw 'foo nil))
- (setq d (cdr d)))
- (set-match-data data))))
-@end group
-@end smallexample
-@end ignore
-
-@node Search and Replace
-@section Search and Replace
-@cindex replacement after search
-@cindex searching and replacing
-
- If you want to find all matches for a regexp in part of the buffer,
-and replace them, the best way is to write an explicit loop using
-@code{re-search-forward} and @code{replace-match}, like this:
-
-@example
-(while (re-search-forward "foo[ \t]+bar" nil t)
- (replace-match "foobar"))
-@end example
-
-@noindent
-@xref{Replacing Match,, Replacing the Text that Matched}, for a
-description of @code{replace-match}.
-
- However, replacing matches in a string is more complex, especially
-if you want to do it efficiently. So Emacs provides a function to do
-this.
-
-@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
-This function copies @var{string} and searches it for matches for
-@var{regexp}, and replaces them with @var{rep}. It returns the
-modified copy. If @var{start} is non-@code{nil}, the search for
-matches starts at that index in @var{string}, so matches starting
-before that index are not changed.
-
-This function uses @code{replace-match} to do the replacement, and it
-passes the optional arguments @var{fixedcase}, @var{literal} and
-@var{subexp} along to @code{replace-match}.
-
-Instead of a string, @var{rep} can be a function. In that case,
-@code{replace-regexp-in-string} calls @var{rep} for each match,
-passing the text of the match as its sole argument. It collects the
-value @var{rep} returns and passes that to @code{replace-match} as the
-replacement string. The match-data at this point are the result
-of matching @var{regexp} against a substring of @var{string}.
-@end defun
-
- If you want to write a command along the lines of @code{query-replace},
-you can use @code{perform-replace} to do the work.
-
-@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
-This function is the guts of @code{query-replace} and related
-commands. It searches for occurrences of @var{from-string} in the
-text between positions @var{start} and @var{end} and replaces some or
-all of them. If @var{start} is @code{nil} (or omitted), point is used
-instead, and the end of the buffer's accessible portion is used for
-@var{end}.
-
-If @var{query-flag} is @code{nil}, it replaces all
-occurrences; otherwise, it asks the user what to do about each one.
-
-If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
-considered a regular expression; otherwise, it must match literally. If
-@var{delimited-flag} is non-@code{nil}, then only replacements
-surrounded by word boundaries are considered.
-
-The argument @var{replacements} specifies what to replace occurrences
-with. If it is a string, that string is used. It can also be a list of
-strings, to be used in cyclic order.
-
-If @var{replacements} is a cons cell, @code{(@var{function}
-. @var{data})}, this means to call @var{function} after each match to
-get the replacement text. This function is called with two arguments:
-@var{data}, and the number of replacements already made.
-
-If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
-it specifies how many times to use each of the strings in the
-@var{replacements} list before advancing cyclically to the next one.
-
-If @var{from-string} contains upper-case letters, then
-@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
-it uses the @code{replacements} without altering the case of them.
-
-Normally, the keymap @code{query-replace-map} defines the possible
-user responses for queries. The argument @var{map}, if
-non-@code{nil}, specifies a keymap to use instead of
-@code{query-replace-map}.
-@end defun
-
-@defvar query-replace-map
-This variable holds a special keymap that defines the valid user
-responses for @code{perform-replace} and the commands that use it, as
-well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
-in two ways:
-
-@itemize @bullet
-@item
-The ``key bindings'' are not commands, just symbols that are meaningful
-to the functions that use this map.
-
-@item
-Prefix keys are not supported; each key binding must be for a
-single-event key sequence. This is because the functions don't use
-@code{read-key-sequence} to get the input; instead, they read a single
-event and look it up ``by hand.''
-@end itemize
-@end defvar
-
-Here are the meaningful ``bindings'' for @code{query-replace-map}.
-Several of them are meaningful only for @code{query-replace} and
-friends.
-
-@table @code
-@item act
-Do take the action being considered---in other words, ``yes.''
-
-@item skip
-Do not take action for this question---in other words, ``no.''
-
-@item exit
-Answer this question ``no,'' and give up on the entire series of
-questions, assuming that the answers will be ``no.''
-
-@item act-and-exit
-Answer this question ``yes,'' and give up on the entire series of
-questions, assuming that subsequent answers will be ``no.''
-
-@item act-and-show
-Answer this question ``yes,'' but show the results---don't advance yet
-to the next question.
-
-@item automatic
-Answer this question and all subsequent questions in the series with
-``yes,'' without further user interaction.
-
-@item backup
-Move back to the previous place that a question was asked about.
-
-@item edit
-Enter a recursive edit to deal with this question---instead of any
-other action that would normally be taken.
-
-@item delete-and-edit
-Delete the text being considered, then enter a recursive edit to replace
-it.
-
-@item recenter
-Redisplay and center the window, then ask the same question again.
-
-@item quit
-Perform a quit right away. Only @code{y-or-n-p} and related functions
-use this answer.
-
-@item help
-Display some help, then ask again.
-@end table
-
-@node Standard Regexps
-@section Standard Regular Expressions Used in Editing
-@cindex regexps used standardly in editing
-@cindex standard regexps used in editing
-
- This section describes some variables that hold regular expressions
-used for certain purposes in editing:
-
-@defvar page-delimiter
-This is the regular expression describing line-beginnings that separate
-pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
-@code{"^\C-l"}); this matches a line that starts with a formfeed
-character.
-@end defvar
-
- The following two regular expressions should @emph{not} assume the
-match always starts at the beginning of a line; they should not use
-@samp{^} to anchor the match. Most often, the paragraph commands do
-check for a match only at the beginning of a line, which means that
-@samp{^} would be superfluous. When there is a nonzero left margin,
-they accept matches that start after the left margin. In that case, a
-@samp{^} would be incorrect. However, a @samp{^} is harmless in modes
-where a left margin is never used.
-
-@defvar paragraph-separate
-This is the regular expression for recognizing the beginning of a line
-that separates paragraphs. (If you change this, you may have to
-change @code{paragraph-start} also.) The default value is
-@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
-spaces, tabs, and form feeds (after its left margin).
-@end defvar
-
-@defvar paragraph-start
-This is the regular expression for recognizing the beginning of a line
-that starts @emph{or} separates paragraphs. The default value is
-@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
-whitespace or starting with a form feed (after its left margin).
-@end defvar
-
-@defvar sentence-end
-If non-@code{nil}, the value should be a regular expression describing
-the end of a sentence, including the whitespace following the
-sentence. (All paragraph boundaries also end sentences, regardless.)
-
-If the value is @code{nil}, the default, then the function
-@code{sentence-end} has to construct the regexp. That is why you
-should always call the function @code{sentence-end} to obtain the
-regexp to be used to recognize the end of a sentence.
-@end defvar
-
-@defun sentence-end
-This function returns the value of the variable @code{sentence-end},
-if non-@code{nil}. Otherwise it returns a default value based on the
-values of the variables @code{sentence-end-double-space}
-(@pxref{Definition of sentence-end-double-space}),
-@code{sentence-end-without-period} and
-@code{sentence-end-without-space}.
-@end defun
-
-@ignore
- arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/sequences
-@node Sequences Arrays Vectors, Hash Tables, Lists, Top
-@chapter Sequences, Arrays, and Vectors
-@cindex sequence
-
- Recall that the @dfn{sequence} type is the union of two other Lisp
-types: lists and arrays. In other words, any list is a sequence, and
-any array is a sequence. The common property that all sequences have is
-that each is an ordered collection of elements.
-
- An @dfn{array} is a single primitive object that has a slot for each
-of its elements. All the elements are accessible in constant time, but
-the length of an existing array cannot be changed. Strings, vectors,
-char-tables and bool-vectors are the four types of arrays.
-
- A list is a sequence of elements, but it is not a single primitive
-object; it is made of cons cells, one cell per element. Finding the
-@var{n}th element requires looking through @var{n} cons cells, so
-elements farther from the beginning of the list take longer to access.
-But it is possible to add elements to the list, or remove elements.
-
- The following diagram shows the relationship between these types:
-
-@example
-@group
- _____________________________________________
- | |
- | Sequence |
- | ______ ________________________________ |
- | | | | | |
- | | List | | Array | |
- | | | | ________ ________ | |
- | |______| | | | | | | |
- | | | Vector | | String | | |
- | | |________| |________| | |
- | | ____________ _____________ | |
- | | | | | | | |
- | | | Char-table | | Bool-vector | | |
- | | |____________| |_____________| | |
- | |________________________________| |
- |_____________________________________________|
-@end group
-@end example
-
- The elements of vectors and lists may be any Lisp objects. The
-elements of strings are all characters.
-
-@menu
-* 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.
-@end menu
-
-@node Sequence Functions
-@section Sequences
-
- In Emacs Lisp, a @dfn{sequence} is either a list or an array. The
-common property of all sequences is that they are ordered collections of
-elements. This section describes functions that accept any kind of
-sequence.
-
-@defun sequencep object
-Returns @code{t} if @var{object} is a list, vector, string,
-bool-vector, or char-table, @code{nil} otherwise.
-@end defun
-
-@defun length sequence
-@cindex string length
-@cindex list length
-@cindex vector length
-@cindex sequence length
-@cindex char-table length
-This function returns the number of elements in @var{sequence}. If
-@var{sequence} is a dotted list, a @code{wrong-type-argument} error is
-signaled. Circular lists may cause an infinite loop. For a
-char-table, the value returned is always one more than the maximum
-Emacs character code.
-
-@xref{Definition of safe-length}, for the related function @code{safe-length}.
-
-@example
-@group
-(length '(1 2 3))
- @result{} 3
-@end group
-@group
-(length ())
- @result{} 0
-@end group
-@group
-(length "foobar")
- @result{} 6
-@end group
-@group
-(length [1 2 3])
- @result{} 3
-@end group
-@group
-(length (make-bool-vector 5 nil))
- @result{} 5
-@end group
-@end example
-@end defun
-
-@noindent
-See also @code{string-bytes}, in @ref{Text Representations}.
-
-@defun elt sequence index
-@cindex elements of sequences
-This function returns the element of @var{sequence} indexed by
-@var{index}. Legitimate values of @var{index} are integers ranging
-from 0 up to one less than the length of @var{sequence}. If
-@var{sequence} is a list, out-of-range values behave as for
-@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values
-trigger an @code{args-out-of-range} error.
-
-@example
-@group
-(elt [1 2 3 4] 2)
- @result{} 3
-@end group
-@group
-(elt '(1 2 3 4) 2)
- @result{} 3
-@end group
-@group
-;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
-(string (elt "1234" 2))
- @result{} "3"
-@end group
-@group
-(elt [1 2 3 4] 4)
- @error{} Args out of range: [1 2 3 4], 4
-@end group
-@group
-(elt [1 2 3 4] -1)
- @error{} Args out of range: [1 2 3 4], -1
-@end group
-@end example
-
-This function generalizes @code{aref} (@pxref{Array Functions}) and
-@code{nth} (@pxref{Definition of nth}).
-@end defun
-
-@defun copy-sequence sequence
-@cindex copying sequences
-Returns a copy of @var{sequence}. The copy is the same type of object
-as the original sequence, and it has the same elements in the same order.
-
-Storing a new element into the copy does not affect the original
-@var{sequence}, and vice versa. However, the elements of the new
-sequence are not copies; they are identical (@code{eq}) to the elements
-of the original. Therefore, changes made within these elements, as
-found via the copied sequence, are also visible in the original
-sequence.
-
-If the sequence is a string with text properties, the property list in
-the copy is itself a copy, not shared with the original's property
-list. However, the actual values of the properties are shared.
-@xref{Text Properties}.
-
-This function does not work for dotted lists. Trying to copy a
-circular list may cause an infinite loop.
-
-See also @code{append} in @ref{Building Lists}, @code{concat} in
-@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
-for other ways to copy sequences.
-
-@example
-@group
-(setq bar '(1 2))
- @result{} (1 2)
-@end group
-@group
-(setq x (vector 'foo bar))
- @result{} [foo (1 2)]
-@end group
-@group
-(setq y (copy-sequence x))
- @result{} [foo (1 2)]
-@end group
-
-@group
-(eq x y)
- @result{} nil
-@end group
-@group
-(equal x y)
- @result{} t
-@end group
-@group
-(eq (elt x 1) (elt y 1))
- @result{} t
-@end group
-
-@group
-;; @r{Replacing an element of one sequence.}
-(aset x 0 'quux)
-x @result{} [quux (1 2)]
-y @result{} [foo (1 2)]
-@end group
-
-@group
-;; @r{Modifying the inside of a shared element.}
-(setcar (aref x 1) 69)
-x @result{} [quux (69 2)]
-y @result{} [foo (69 2)]
-@end group
-@end example
-@end defun
-
-@node Arrays
-@section Arrays
-@cindex array
-
- An @dfn{array} object has slots that hold a number of other Lisp
-objects, called the elements of the array. Any element of an array may
-be accessed in constant time. In contrast, an element of a list
-requires access time that is proportional to the position of the element
-in the list.
-
- Emacs defines four types of array, all one-dimensional: @dfn{strings},
-@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a
-general array; its elements can be any Lisp objects. A string is a
-specialized array; its elements must be characters. Each type of array
-has its own read syntax.
-@xref{String Type}, and @ref{Vector Type}.
-
- All four kinds of array share these characteristics:
-
-@itemize @bullet
-@item
-The first element of an array has index zero, the second element has
-index 1, and so on. This is called @dfn{zero-origin} indexing. For
-example, an array of four elements has indices 0, 1, 2, @w{and 3}.
-
-@item
-The length of the array is fixed once you create it; you cannot
-change the length of an existing array.
-
-@item
-For purposes of evaluation, the array is a constant---in other words,
-it evaluates to itself.
-
-@item
-The elements of an array may be referenced or changed with the functions
-@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
-@end itemize
-
- When you create an array, other than a char-table, you must specify
-its length. You cannot specify the length of a char-table, because that
-is determined by the range of character codes.
-
- In principle, if you want an array of text characters, you could use
-either a string or a vector. In practice, we always choose strings for
-such applications, for four reasons:
-
-@itemize @bullet
-@item
-They occupy one-fourth the space of a vector of the same elements.
-
-@item
-Strings are printed in a way that shows the contents more clearly
-as text.
-
-@item
-Strings can hold text properties. @xref{Text Properties}.
-
-@item
-Many of the specialized editing and I/O facilities of Emacs accept only
-strings. For example, you cannot insert a vector of characters into a
-buffer the way you can insert a string. @xref{Strings and Characters}.
-@end itemize
-
- By contrast, for an array of keyboard input characters (such as a key
-sequence), a vector may be necessary, because many keyboard input
-characters are outside the range that will fit in a string. @xref{Key
-Sequence Input}.
-
-@node Array Functions
-@section Functions that Operate on Arrays
-
- In this section, we describe the functions that accept all types of
-arrays.
-
-@defun arrayp object
-This function returns @code{t} if @var{object} is an array (i.e., a
-vector, a string, a bool-vector or a char-table).
-
-@example
-@group
-(arrayp [a])
- @result{} t
-(arrayp "asdf")
- @result{} t
-(arrayp (syntax-table)) ;; @r{A char-table.}
- @result{} t
-@end group
-@end example
-@end defun
-
-@defun aref array index
-@cindex array elements
-This function returns the @var{index}th element of @var{array}. The
-first element is at index zero.
-
-@example
-@group
-(setq primes [2 3 5 7 11 13])
- @result{} [2 3 5 7 11 13]
-(aref primes 4)
- @result{} 11
-@end group
-@group
-(aref "abcdefg" 1)
- @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
-@end group
-@end example
-
-See also the function @code{elt}, in @ref{Sequence Functions}.
-@end defun
-
-@defun aset array index object
-This function sets the @var{index}th element of @var{array} to be
-@var{object}. It returns @var{object}.
-
-@example
-@group
-(setq w [foo bar baz])
- @result{} [foo bar baz]
-(aset w 0 'fu)
- @result{} fu
-w
- @result{} [fu bar baz]
-@end group
-
-@group
-(setq x "asdfasfd")
- @result{} "asdfasfd"
-(aset x 3 ?Z)
- @result{} 90
-x
- @result{} "asdZasfd"
-@end group
-@end example
-
-If @var{array} is a string and @var{object} is not a character, a
-@code{wrong-type-argument} error results. The function converts a
-unibyte string to multibyte if necessary to insert a character.
-@end defun
-
-@defun fillarray array object
-This function fills the array @var{array} with @var{object}, so that
-each element of @var{array} is @var{object}. It returns @var{array}.
-
-@example
-@group
-(setq a [a b c d e f g])
- @result{} [a b c d e f g]
-(fillarray a 0)
- @result{} [0 0 0 0 0 0 0]
-a
- @result{} [0 0 0 0 0 0 0]
-@end group
-@group
-(setq s "When in the course")
- @result{} "When in the course"
-(fillarray s ?-)
- @result{} "------------------"
-@end group
-@end example
-
-If @var{array} is a string and @var{object} is not a character, a
-@code{wrong-type-argument} error results.
-@end defun
-
-The general sequence functions @code{copy-sequence} and @code{length}
-are often useful for objects known to be arrays. @xref{Sequence Functions}.
-
-@node Vectors
-@section Vectors
-@cindex vector (type)
-
- Arrays in Lisp, like arrays in most languages, are blocks of memory
-whose elements can be accessed in constant time. A @dfn{vector} is a
-general-purpose array of specified length; its elements can be any Lisp
-objects. (By contrast, a string can hold only characters as elements.)
-Vectors in Emacs are used for obarrays (vectors of symbols), and as part
-of keymaps (vectors of commands). They are also used internally as part
-of the representation of a byte-compiled function; if you print such a
-function, you will see a vector in it.
-
- In Emacs Lisp, the indices of the elements of a vector start from zero
-and count up from there.
-
- Vectors are printed with square brackets surrounding the elements.
-Thus, a vector whose elements are the symbols @code{a}, @code{b} and
-@code{a} is printed as @code{[a b a]}. You can write vectors in the
-same way in Lisp input.
-
- A vector, like a string or a number, is considered a constant for
-evaluation: the result of evaluating it is the same vector. This does
-not evaluate or even examine the elements of the vector.
-@xref{Self-Evaluating Forms}.
-
- Here are examples illustrating these principles:
-
-@example
-@group
-(setq avector [1 two '(three) "four" [five]])
- @result{} [1 two (quote (three)) "four" [five]]
-(eval avector)
- @result{} [1 two (quote (three)) "four" [five]]
-(eq avector (eval avector))
- @result{} t
-@end group
-@end example
-
-@node Vector Functions
-@section Functions for Vectors
-
- Here are some functions that relate to vectors:
-
-@defun vectorp object
-This function returns @code{t} if @var{object} is a vector.
-
-@example
-@group
-(vectorp [a])
- @result{} t
-(vectorp "asdf")
- @result{} nil
-@end group
-@end example
-@end defun
-
-@defun vector &rest objects
-This function creates and returns a vector whose elements are the
-arguments, @var{objects}.
-
-@example
-@group
-(vector 'foo 23 [bar baz] "rats")
- @result{} [foo 23 [bar baz] "rats"]
-(vector)
- @result{} []
-@end group
-@end example
-@end defun
-
-@defun make-vector length object
-This function returns a new vector consisting of @var{length} elements,
-each initialized to @var{object}.
-
-@example
-@group
-(setq sleepy (make-vector 9 'Z))
- @result{} [Z Z Z Z Z Z Z Z Z]
-@end group
-@end example
-@end defun
-
-@defun vconcat &rest sequences
-@cindex copying vectors
-This function returns a new vector containing all the elements of the
-@var{sequences}. The arguments @var{sequences} may be true lists,
-vectors, strings or bool-vectors. If no @var{sequences} are given, an
-empty vector is returned.
-
-The value is a newly constructed vector that is not @code{eq} to any
-existing vector.
-
-@example
-@group
-(setq a (vconcat '(A B C) '(D E F)))
- @result{} [A B C D E F]
-(eq a (vconcat a))
- @result{} nil
-@end group
-@group
-(vconcat)
- @result{} []
-(vconcat [A B C] "aa" '(foo (6 7)))
- @result{} [A B C 97 97 foo (6 7)]
-@end group
-@end example
-
-The @code{vconcat} function also allows byte-code function objects as
-arguments. This is a special feature to make it easy to access the entire
-contents of a byte-code function object. @xref{Byte-Code Objects}.
-
-In Emacs versions before 21, the @code{vconcat} function allowed
-integers as arguments, converting them to strings of digits, but that
-feature has been eliminated. The proper way to convert an integer to
-a decimal number in this way is with @code{format} (@pxref{Formatting
-Strings}) or @code{number-to-string} (@pxref{String Conversion}).
-
-For other concatenation functions, see @code{mapconcat} in @ref{Mapping
-Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
-in @ref{Building Lists}.
-@end defun
-
- The @code{append} function also provides a way to convert a vector into a
-list with the same elements:
-
-@example
-@group
-(setq avector [1 two (quote (three)) "four" [five]])
- @result{} [1 two (quote (three)) "four" [five]]
-(append avector nil)
- @result{} (1 two (quote (three)) "four" [five])
-@end group
-@end example
-
-@node Char-Tables
-@section Char-Tables
-@cindex char-tables
-@cindex extra slots of char-table
-
- A char-table is much like a vector, except that it is indexed by
-character codes. Any valid character code, without modifiers, can be
-used as an index in a char-table. You can access a char-table's
-elements with @code{aref} and @code{aset}, as with any array. In
-addition, a char-table can have @dfn{extra slots} to hold additional
-data not associated with particular character codes. Char-tables are
-constants when evaluated.
-
-@cindex subtype of char-table
- Each char-table has a @dfn{subtype} which is a symbol. The subtype
-has two purposes: to distinguish char-tables meant for different uses,
-and to control the number of extra slots. For example, display tables
-are char-tables with @code{display-table} as the subtype, and syntax
-tables are char-tables with @code{syntax-table} as the subtype. A valid
-subtype must have a @code{char-table-extra-slots} property which is an
-integer between 0 and 10. This integer specifies the number of
-@dfn{extra slots} in the char-table.
-
-@cindex parent of char-table
- A char-table can have a @dfn{parent}, which is another char-table. If
-it does, then whenever the char-table specifies @code{nil} for a
-particular character @var{c}, it inherits the value specified in the
-parent. In other words, @code{(aref @var{char-table} @var{c})} returns
-the value from the parent of @var{char-table} if @var{char-table} itself
-specifies @code{nil}.
-
-@cindex default value of char-table
- A char-table can also have a @dfn{default value}. If so, then
-@code{(aref @var{char-table} @var{c})} returns the default value
-whenever the char-table does not specify any other non-@code{nil} value.
-
-@defun make-char-table subtype &optional init
-Return a newly created char-table, with subtype @var{subtype}. Each
-element is initialized to @var{init}, which defaults to @code{nil}. You
-cannot alter the subtype of a char-table after the char-table is
-created.
-
-There is no argument to specify the length of the char-table, because
-all char-tables have room for any valid character code as an index.
-@end defun
-
-@defun char-table-p object
-This function returns @code{t} if @var{object} is a char-table,
-otherwise @code{nil}.
-@end defun
-
-@defun char-table-subtype char-table
-This function returns the subtype symbol of @var{char-table}.
-@end defun
-
-@defun set-char-table-default char-table char new-default
-This function sets the default value of generic character @var{char}
-in @var{char-table} to @var{new-default}.
-
-There is no special function to access default values in a char-table.
-To do that, use @code{char-table-range} (see below).
-@end defun
-
-@defun char-table-parent char-table
-This function returns the parent of @var{char-table}. The parent is
-always either @code{nil} or another char-table.
-@end defun
-
-@defun set-char-table-parent char-table new-parent
-This function sets the parent of @var{char-table} to @var{new-parent}.
-@end defun
-
-@defun char-table-extra-slot char-table n
-This function returns the contents of extra slot @var{n} of
-@var{char-table}. The number of extra slots in a char-table is
-determined by its subtype.
-@end defun
-
-@defun set-char-table-extra-slot char-table n value
-This function stores @var{value} in extra slot @var{n} of
-@var{char-table}.
-@end defun
-
- A char-table can specify an element value for a single character code;
-it can also specify a value for an entire character set.
-
-@defun char-table-range char-table range
-This returns the value specified in @var{char-table} for a range of
-characters @var{range}. Here are the possibilities for @var{range}:
-
-@table @asis
-@item @code{nil}
-Refers to the default value.
-
-@item @var{char}
-Refers to the element for character @var{char}
-(supposing @var{char} is a valid character code).
-
-@item @var{charset}
-Refers to the value specified for the whole character set
-@var{charset} (@pxref{Character Sets}).
-
-@item @var{generic-char}
-A generic character stands for a character set, or a row of a
-character set; specifying the generic character as argument is
-equivalent to specifying the character set name. @xref{Splitting
-Characters}, for a description of generic characters.
-@end table
-@end defun
-
-@defun set-char-table-range char-table range value
-This function sets the value in @var{char-table} for a range of
-characters @var{range}. Here are the possibilities for @var{range}:
-
-@table @asis
-@item @code{nil}
-Refers to the default value.
-
-@item @code{t}
-Refers to the whole range of character codes.
-
-@item @var{char}
-Refers to the element for character @var{char}
-(supposing @var{char} is a valid character code).
-
-@item @var{charset}
-Refers to the value specified for the whole character set
-@var{charset} (@pxref{Character Sets}).
-
-@item @var{generic-char}
-A generic character stands for a character set; specifying the generic
-character as argument is equivalent to specifying the character set
-name. @xref{Splitting Characters}, for a description of generic characters.
-@end table
-@end defun
-
-@defun map-char-table function char-table
-This function calls @var{function} for each element of @var{char-table}.
-@var{function} is called with two arguments, a key and a value. The key
-is a possible @var{range} argument for @code{char-table-range}---either
-a valid character or a generic character---and the value is
-@code{(char-table-range @var{char-table} @var{key})}.
-
-Overall, the key-value pairs passed to @var{function} describe all the
-values stored in @var{char-table}.
-
-The return value is always @code{nil}; to make this function useful,
-@var{function} should have side effects. For example,
-here is how to examine each element of the syntax table:
-
-@example
-(let (accumulator)
- (map-char-table
- #'(lambda (key value)
- (setq accumulator
- (cons (list key value) accumulator)))
- (syntax-table))
- accumulator)
-@result{}
-((475008 nil) (474880 nil) (474752 nil) (474624 nil)
- ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
-@end example
-@end defun
-
-@node Bool-Vectors
-@section Bool-vectors
-@cindex Bool-vectors
-
- A bool-vector is much like a vector, except that it stores only the
-values @code{t} and @code{nil}. If you try to store any non-@code{nil}
-value into an element of the bool-vector, the effect is to store
-@code{t} there. As with all arrays, bool-vector indices start from 0,
-and the length cannot be changed once the bool-vector is created.
-Bool-vectors are constants when evaluated.
-
- There are two special functions for working with bool-vectors; aside
-from that, you manipulate them with same functions used for other kinds
-of arrays.
-
-@defun make-bool-vector length initial
-Return a new bool-vector of @var{length} elements,
-each one initialized to @var{initial}.
-@end defun
-
-@defun bool-vector-p object
-This returns @code{t} if @var{object} is a bool-vector,
-and @code{nil} otherwise.
-@end defun
-
- Here is an example of creating, examining, and updating a
-bool-vector. Note that the printed form represents up to 8 boolean
-values as a single character.
-
-@example
-(setq bv (make-bool-vector 5 t))
- @result{} #&5"^_"
-(aref bv 1)
- @result{} t
-(aset bv 3 nil)
- @result{} nil
-bv
- @result{} #&5"^W"
-@end example
-
-@noindent
-These results make sense because the binary codes for control-_ and
-control-W are 11111 and 10111, respectively.
-
-@ignore
- arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
-@end ignore
+++ /dev/null
-ARPA
-Abbrev
-Acknowledgements
-Alan
-Arnold
-Autoloading
-BAppend
-Backquote
-Beeping
-Beverly
-Boyes
-Brian
-CL
-CSWKg
-Carl
-Carroll
-Chris
-Cleanups
-DEC
-DStandard
-Dan
-Dired's
-Disassembly
-Duff
-EMAC
-EMACSLOADPATH
-Eckelkamp
-Edward
-Eirik
-Emacses
-Eric
-Erlebacher
-Fcar
-Fcdr
-Fcons
-Fcoordinates
-Feval
-Frazzle
-Frederick
-Fri
-Gardiner
-Gentlemen
-HAL
-HATTED
-HS
-HU
-Hanchrow
-Hartzell
-Hess
-Hewlett
-IBM
-ISBN
-Impl
-Interning
-Ithought
-J's
-Jacobson
-Jak
-Joe
-Jones
-Jr
-Jul
-Keymaps
-Kimmo
-Kirman
-Knighten
-Korz
-Krawitz
-LTsHm
-LaLiberte
-LaTeX
-Lammens
-Local'
-MAC
-MONIES
-MSS
-Maclisp
-Magill
-Marick
-Matthew
-Minibuf
-Misc
-Miscellany
-Mocklisp
-Montanaro
-Myers
-NFS
-Nathan
-Nope
-OS
-OSITIONS
-Oct
-Ovwrt
-PURESIZE
-Packard
-Qlistp
-Qnil
-RMAIL
-Raul
-Resizing
-Robbins
-Rockwell
-SCO
-SIGCONT
-SIGHUP
-SIGINT
-SIGKILL
-SIGQUIT
-SIGTSTP
-SLOAD
-Scoordinates
-Set'
-Setcar
-Setcdr
-Shinichirou
-Snarf
-Sor
-SourceFile
-Stops'
-Subprocess
-Sugou
-Sunview
-Suominen
-T's
-TCP
-ThXs
-Tharp
-Thu
-Trost
-UCB
-UNEVALLED
-UNGCPRO
-UniPlus
-UniSoft's
-VMS
-Vip
-Void'
-Warren
-Welty
-Wethought
-Wilding
-Worley
-Wright
-XDVI
-XFASTINT
-XINT
-XWINDOW
-Xs
-Yo
-Zuhn
-aB
-aa
-aaa
-abbrevname
-abbrevs
-abc
-abcdefg
-abcxyz
-abd
-above'
-abracadabra
-address'
-after'
-alist
-alists
-anchored'
-and'
-ar
-aref
-arg'th
-argdecl
-arith
-arrayp
-arrow'
-asa
-asdZasfd
-asdf
-asdfasfd
-aset
-assoc
-assq
-at'
-aug
-autoload
-automatic'
-automatically'
-avector
-bBuffer
-bFrobnicate
-ba
-back'
-bananana
-barfoo
-barx
-bballs
-before'
-beforep
-bfoo
-bil
-binding's
-bish
-bobp
-bolp
-bottommost
-boundp
-brief'
-buf
-buffer'
-bufferp
-buttercup
-ca
-caaaar
-caaar
-caddaar
-cadr
-callable
-cbreak
-ce
-cell'
-cells'
-cf
-chaprm
-character'
-childp
-chistory
-ck
-column'
-commandp
-concat
-cond
-conses
-consing
-consp
-constant'
-contains'
-continuable
-convert'
-copyleft
-correct'
-counterintuitive
-cr
-creatable
-customie
-deactivate
-deactivated
-deassigns
-decrement'
-deffnx
-definition'
-defmacro
-defsubr
-deletable
-deletion'
-delq
-depiction
-descendents
-deselecting
-destructive'
-destructively'
-diffs
-ding
-directory'
-dired
-dirname
-disassembler
-dland
-docfile
-docstring
-doesnt
-dont
-down'
-downcasing
-downloadable
-dribble
-dup
-ef
-efg
-electric'
-elided
-elt
-enablement
-endkeyfun
-endrecfun
-environment'
-eobp
-eof
-eol
-eolp
-eq
-eqlsign
-erminal
-erste
-etags
-eval
-evalled
-evals
-evaluate'
-excess'
-exec
-exitcode
-expression'
-extendible
-extra'
-fails'
-fascist
-fboundp
-featurep
-ff
-fg
-fi
-file'
-filespec
-filesystems
-fillarray
-firstchar
-firstonly
-fixedcase
-fixit
-fixup
-floatp
-fmakunbound
-fns
-fo
-fol
-folded'
-following'
-fooba
-foobaz
-foox
-for'
-formfeed
-forms'
-forw
-forwa
-found'
-frob
-from'
-front'
-fset
-fstab
-ftp
-fu
-funtions
-garbles
-gc
-gcpro
-gd
-getenv
-getprv
-gid
-gnuemacs
-gp
-grep
-gtr
-halves'
-hand'
-hashes'
-hd
-hexadecimal
-hf
-hfil
-hookvar
-horsechestnut
-hostname
-hpux
-hscroll
-ibmapa
-ick
-id
-idiom
-ii
-indrm
-inode
-input'
-inputinput
-inserting'
-integerp
-intermixed
-ints
-inturned
-irreversibly
-jum
-keymapp
-kill'
-killed'
-killp
-kludge
-kolstad
-language'
-lastchar
-lcl
-ledit
-leif
-lessp
-level'
-lewis
-library'
-link'
-lisplib
-listexp
-loadable
-loadst
-loadup
-logand
-logior
-lognot
-logxor
-long'
-loop's
-lru
-lrwxrwxrwx
-ls
-lsh
-m's
-macroexpand
-makunbound
-malloc
-mapatoms
-mapconcat
-mapvar
-mark'
-marker's
-markerp
-mathsurround
-medit
-memq
-mh
-mim
-mini
-minibuffer's
-minibuffers
-misalignment
-misnamed
-mode's
-modename
-modes'
-mods
-modtime
-mqueue
-msg
-multicharacter
-myfile
-nCount
-nXExpression
-na
-name's
-natnump
-nb
-nbBuffer
-nconc
-newdef
-newelt
-newname
-nextrecfun
-nfsusr
-ninett
-nlines
-nlinks
-nlistp
-noconfirm
-nodigits
-noerror
-noforce
-nomessage
-nominees
-nomsg
-nonblank
-nonconstant
-nondestructive
-nondirectory
-nonidentical
-noninteractive
-noninteractively
-nonletter
-nonletters
-nonlocally
-nonoverlapping
-nonprinting
-nonselected
-nonsequentially
-nonvoid
-nonwarranty
-nonwritable
-noop
-noprint
-norecord
-normal'
-noselect
-nosuffix
-nots
-noundo
-nr
-nreverse
-ns
-nsRename
-nth
-nthcdr
-num
-number'
-numberp
-nums
-obarray
-obarrays
-object'
-oldbuf
-olddef
-oldname
-oo
-oops
-op
-or'
-otl
-out'
-over'
-overful
-overfullrule
-overstrike
-overstriking
-overstruck
-p'
-paren
-part'
-passwd
-pe
-ped
-perverse
-pid
-plist
-pnt
-pointer'
-pointm
-pos
-preallocate
-predicale
-preload
-prepend
-prepended
-prepends
-pretty'
-prin
-princ
-print'
-printenv
-printer'
-proc
-process'
-processp
-programmer'
-prolog
-protect'
-ps
-psf
-psychotherapy
-pty
-purecopy
-qu
-quux
-rassq
-reader'
-readin
-rebind
-rec
-rechecking
-recursively'
-recycler'
-redo
-redrawing
-redraws
-redump
-reenabled
-reexposed
-reg
-region'
-reindent
-reindents
-reinitialization
-reinitialize
-reinitialized
-reinstall
-reinstalled
-resize
-resized
-resizes
-reversibly
-reworded
-rhetorical
-right'
-ring'
-risky
-rmailedit
-rms
-rplaca
-rplacd
-rtu
-runnable
-rw
-rwxrwxrwx
-sDescribe
-sans
-se
-searching'
-section'
-seed'
-sequence'
-sequencep
-setp
-setplist
-setprv
-settable
-setuid
-sexp
-sexps
-shape'
-shell's
-sideline
-special'
-specpdl
-st
-stanford
-startkeyfun
-str
-stringp
-stty
-subcategories
-subcommands
-subexp
-subform
-subforms
-subjob
-submap
-subprocesses
-subr
-subr'
-subroutine'
-subrp
-subrs
-subwindows
-sugar'
-suid
-supersession
-suspension'
-symbolp
-symlink
-syms
-syntatic
-tabname
-temacs
-temporarily'
-tempvar
-tenths
-termcap
-termcaps
-terminfo
-termscript
-termtype
-terpri
-text'
-textrm
-textsl
-texttt
-than'
-the'
-tildes
-time's
-to'
-towars
-transportable
-txt
-types'
-uid
-unbind
-unbinding
-unbinds
-unchanged'
-unclutters
-undefine
-undefines
-underfull
-undo's
-undodata
-unevaluated'
-unexec
-unexpand
-unhesitatingly
-uninterned
-unisoft
-unpaired
-unread
-unreadable
-unreading
-unsaved
-untyped
-ununderline
-up'
-uptime
-usecount
-used'
-user'
-userlock
-usg
-val
-varbind
-varname
-varref
-vars
-varset
-vb
-vconcat
-vectorp
-vfil
-vi
-vn
-voidness
-vrs
-vt
-window'
-windowing
-windowp
-wrapped'
-xSpecify
-xcoord
-xcssun
-xemacs
-xenix
-xf
-xfirst
-xoff
-xon
-xx
-xxxxx
-xxxxxxxxx
-xy
-xyz
-ycoord
-yes'
-zA
-zap
-zerop
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 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/streams
-@node Read and Print, Minibuffers, Debugging, Top
-@comment node-name, next, previous, up
-@chapter Reading and Printing Lisp Objects
-
- @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
-objects to textual form and vice versa. They use the printed
-representations and read syntax described in @ref{Lisp Data Types}.
-
- This chapter describes the Lisp functions for reading and printing.
-It also describes @dfn{streams}, which specify where to get the text (if
-reading) or where to put it (if printing).
-
-@menu
-* 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.
-@end menu
-
-@node Streams Intro
-@section Introduction to Reading and Printing
-@cindex Lisp reader
-@cindex printing
-@cindex reading
-
- @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
-form and producing a corresponding Lisp object. This is how Lisp
-programs get into Lisp from files of Lisp code. We call the text the
-@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
-is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
-@sc{cdr} is the number 5.
-
- @dfn{Printing} a Lisp object means producing text that represents that
-object---converting the object to its @dfn{printed representation}
-(@pxref{Printed Representation}). Printing the cons cell described
-above produces the text @samp{(a .@: 5)}.
-
- Reading and printing are more or less inverse operations: printing the
-object that results from reading a given piece of text often produces
-the same text, and reading the text that results from printing an object
-usually produces a similar-looking object. For example, printing the
-symbol @code{foo} produces the text @samp{foo}, and reading that text
-returns the symbol @code{foo}. Printing a list whose elements are
-@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
-text produces a list (but not the same list) with elements @code{a}
-and @code{b}.
-
- However, these two operations are not precisely inverse to each other.
-There are three kinds of exceptions:
-
-@itemize @bullet
-@item
-Printing can produce text that cannot be read. For example, buffers,
-windows, frames, subprocesses and markers print as text that starts
-with @samp{#}; if you try to read this text, you get an error. There is
-no way to read those data types.
-
-@item
-One object can have multiple textual representations. For example,
-@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
-@samp{(a .@: (b))} represent the same list. Reading will accept any of
-the alternatives, but printing must choose one of them.
-
-@item
-Comments can appear at certain points in the middle of an object's
-read sequence without affecting the result of reading it.
-@end itemize
-
-@node Input Streams
-@section Input Streams
-@cindex stream (for reading)
-@cindex input stream
-
- Most of the Lisp functions for reading text take an @dfn{input stream}
-as an argument. The input stream specifies where or how to get the
-characters of the text to be read. Here are the possible types of input
-stream:
-
-@table @asis
-@item @var{buffer}
-@cindex buffer input stream
-The input characters are read from @var{buffer}, starting with the
-character directly after point. Point advances as characters are read.
-
-@item @var{marker}
-@cindex marker input stream
-The input characters are read from the buffer that @var{marker} is in,
-starting with the character directly after the marker. The marker
-position advances as characters are read. The value of point in the
-buffer has no effect when the stream is a marker.
-
-@item @var{string}
-@cindex string input stream
-The input characters are taken from @var{string}, starting at the first
-character in the string and using as many characters as required.
-
-@item @var{function}
-@cindex function input stream
-The input characters are generated by @var{function}, which must support
-two kinds of calls:
-
-@itemize @bullet
-@item
-When it is called with no arguments, it should return the next character.
-
-@item
-When it is called with one argument (always a character), @var{function}
-should save the argument and arrange to return it on the next call.
-This is called @dfn{unreading} the character; it happens when the Lisp
-reader reads one character too many and wants to ``put it back where it
-came from.'' In this case, it makes no difference what value
-@var{function} returns.
-@end itemize
-
-@item @code{t}
-@cindex @code{t} input stream
-@code{t} used as a stream means that the input is read from the
-minibuffer. In fact, the minibuffer is invoked once and the text
-given by the user is made into a string that is then used as the
-input stream. If Emacs is running in batch mode, standard input is used
-instead of the minibuffer. For example,
-@example
-(message "%s" (read t))
-@end example
-will read a Lisp expression from standard input and print the result
-to standard output.
-
-@item @code{nil}
-@cindex @code{nil} input stream
-@code{nil} supplied as an input stream means to use the value of
-@code{standard-input} instead; that value is the @dfn{default input
-stream}, and must be a non-@code{nil} input stream.
-
-@item @var{symbol}
-A symbol as input stream is equivalent to the symbol's function
-definition (if any).
-@end table
-
- Here is an example of reading from a stream that is a buffer, showing
-where point is located before and after:
-
-@example
-@group
----------- Buffer: foo ----------
-This@point{} is the contents of foo.
----------- Buffer: foo ----------
-@end group
-
-@group
-(read (get-buffer "foo"))
- @result{} is
-@end group
-@group
-(read (get-buffer "foo"))
- @result{} the
-@end group
-
-@group
----------- Buffer: foo ----------
-This is the@point{} contents of foo.
----------- Buffer: foo ----------
-@end group
-@end example
-
-@noindent
-Note that the first read skips a space. Reading skips any amount of
-whitespace preceding the significant text.
-
- Here is an example of reading from a stream that is a marker,
-initially positioned at the beginning of the buffer shown. The value
-read is the symbol @code{This}.
-
-@example
-@group
-
----------- Buffer: foo ----------
-This is the contents of foo.
----------- Buffer: foo ----------
-@end group
-
-@group
-(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
- @result{} #<marker at 1 in foo>
-@end group
-@group
-(read m)
- @result{} This
-@end group
-@group
-m
- @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
-@end group
-@end example
-
- Here we read from the contents of a string:
-
-@example
-@group
-(read "(When in) the course")
- @result{} (When in)
-@end group
-@end example
-
- The following example reads from the minibuffer. The
-prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
-used when you read from the stream @code{t}.) The user's input is shown
-following the prompt.
-
-@example
-@group
-(read t)
- @result{} 23
----------- Buffer: Minibuffer ----------
-Lisp expression: @kbd{23 @key{RET}}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
- Finally, here is an example of a stream that is a function, named
-@code{useless-stream}. Before we use the stream, we initialize the
-variable @code{useless-list} to a list of characters. Then each call to
-the function @code{useless-stream} obtains the next character in the list
-or unreads a character by adding it to the front of the list.
-
-@example
-@group
-(setq useless-list (append "XY()" nil))
- @result{} (88 89 40 41)
-@end group
-
-@group
-(defun useless-stream (&optional unread)
- (if unread
- (setq useless-list (cons unread useless-list))
- (prog1 (car useless-list)
- (setq useless-list (cdr useless-list)))))
- @result{} useless-stream
-@end group
-@end example
-
-@noindent
-Now we read using the stream thus constructed:
-
-@example
-@group
-(read 'useless-stream)
- @result{} XY
-@end group
-
-@group
-useless-list
- @result{} (40 41)
-@end group
-@end example
-
-@noindent
-Note that the open and close parentheses remain in the list. The Lisp
-reader encountered the open parenthesis, decided that it ended the
-input, and unread it. Another attempt to read from the stream at this
-point would read @samp{()} and return @code{nil}.
-
-@defun get-file-char
-This function is used internally as an input stream to read from the
-input file opened by the function @code{load}. Don't use this function
-yourself.
-@end defun
-
-@node Input Functions
-@section Input Functions
-
- This section describes the Lisp functions and variables that pertain
-to reading.
-
- In the functions below, @var{stream} stands for an input stream (see
-the previous section). If @var{stream} is @code{nil} or omitted, it
-defaults to the value of @code{standard-input}.
-
-@kindex end-of-file
- An @code{end-of-file} error is signaled if reading encounters an
-unterminated list, vector, or string.
-
-@defun read &optional stream
-This function reads one textual Lisp expression from @var{stream},
-returning it as a Lisp object. This is the basic Lisp input function.
-@end defun
-
-@defun read-from-string string &optional start end
-@cindex string to object
-This function reads the first textual Lisp expression from the text in
-@var{string}. It returns a cons cell whose @sc{car} is that expression,
-and whose @sc{cdr} is an integer giving the position of the next
-remaining character in the string (i.e., the first one not read).
-
-If @var{start} is supplied, then reading begins at index @var{start} in
-the string (where the first character is at index 0). If you specify
-@var{end}, then reading is forced to stop just before that index, as if
-the rest of the string were not there.
-
-For example:
-
-@example
-@group
-(read-from-string "(setq x 55) (setq y 5)")
- @result{} ((setq x 55) . 11)
-@end group
-@group
-(read-from-string "\"A short string\"")
- @result{} ("A short string" . 16)
-@end group
-
-@group
-;; @r{Read starting at the first character.}
-(read-from-string "(list 112)" 0)
- @result{} ((list 112) . 10)
-@end group
-@group
-;; @r{Read starting at the second character.}
-(read-from-string "(list 112)" 1)
- @result{} (list . 5)
-@end group
-@group
-;; @r{Read starting at the seventh character,}
-;; @r{and stopping at the ninth.}
-(read-from-string "(list 112)" 6 8)
- @result{} (11 . 8)
-@end group
-@end example
-@end defun
-
-@defvar standard-input
-This variable holds the default input stream---the stream that
-@code{read} uses when the @var{stream} argument is @code{nil}.
-The default is @code{t}, meaning use the minibuffer.
-@end defvar
-
-@node Output Streams
-@section Output Streams
-@cindex stream (for printing)
-@cindex output stream
-
- An output stream specifies what to do with the characters produced
-by printing. Most print functions accept an output stream as an
-optional argument. Here are the possible types of output stream:
-
-@table @asis
-@item @var{buffer}
-@cindex buffer output stream
-The output characters are inserted into @var{buffer} at point.
-Point advances as characters are inserted.
-
-@item @var{marker}
-@cindex marker output stream
-The output characters are inserted into the buffer that @var{marker}
-points into, at the marker position. The marker position advances as
-characters are inserted. The value of point in the buffer has no effect
-on printing when the stream is a marker, and this kind of printing
-does not move point (except that if the marker points at or before the
-position of point, point advances with the surrounding text, as
-usual).
-
-@item @var{function}
-@cindex function output stream
-The output characters are passed to @var{function}, which is responsible
-for storing them away. It is called with a single character as
-argument, as many times as there are characters to be output, and
-is responsible for storing the characters wherever you want to put them.
-
-@item @code{t}
-@cindex @code{t} output stream
-The output characters are displayed in the echo area.
-
-@item @code{nil}
-@cindex @code{nil} output stream
-@code{nil} specified as an output stream means to use the value of
-@code{standard-output} instead; that value is the @dfn{default output
-stream}, and must not be @code{nil}.
-
-@item @var{symbol}
-A symbol as output stream is equivalent to the symbol's function
-definition (if any).
-@end table
-
- Many of the valid output streams are also valid as input streams. The
-difference between input and output streams is therefore more a matter
-of how you use a Lisp object, than of different types of object.
-
- Here is an example of a buffer used as an output stream. Point is
-initially located as shown immediately before the @samp{h} in
-@samp{the}. At the end, point is located directly before that same
-@samp{h}.
-
-@cindex print example
-@example
-@group
----------- Buffer: foo ----------
-This is t@point{}he contents of foo.
----------- Buffer: foo ----------
-@end group
-
-(print "This is the output" (get-buffer "foo"))
- @result{} "This is the output"
-
-@group
----------- Buffer: foo ----------
-This is t
-"This is the output"
-@point{}he contents of foo.
----------- Buffer: foo ----------
-@end group
-@end example
-
- Now we show a use of a marker as an output stream. Initially, the
-marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
-the word @samp{the}. At the end, the marker has advanced over the
-inserted text so that it remains positioned before the same @samp{h}.
-Note that the location of point, shown in the usual fashion, has no
-effect.
-
-@example
-@group
----------- Buffer: foo ----------
-This is the @point{}output
----------- Buffer: foo ----------
-@end group
-
-@group
-(setq m (copy-marker 10))
- @result{} #<marker at 10 in foo>
-@end group
-
-@group
-(print "More output for foo." m)
- @result{} "More output for foo."
-@end group
-
-@group
----------- Buffer: foo ----------
-This is t
-"More output for foo."
-he @point{}output
----------- Buffer: foo ----------
-@end group
-
-@group
-m
- @result{} #<marker at 34 in foo>
-@end group
-@end example
-
- The following example shows output to the echo area:
-
-@example
-@group
-(print "Echo Area output" t)
- @result{} "Echo Area output"
----------- Echo Area ----------
-"Echo Area output"
----------- Echo Area ----------
-@end group
-@end example
-
- Finally, we show the use of a function as an output stream. The
-function @code{eat-output} takes each character that it is given and
-conses it onto the front of the list @code{last-output} (@pxref{Building
-Lists}). At the end, the list contains all the characters output, but
-in reverse order.
-
-@example
-@group
-(setq last-output nil)
- @result{} nil
-@end group
-
-@group
-(defun eat-output (c)
- (setq last-output (cons c last-output)))
- @result{} eat-output
-@end group
-
-@group
-(print "This is the output" 'eat-output)
- @result{} "This is the output"
-@end group
-
-@group
-last-output
- @result{} (10 34 116 117 112 116 117 111 32 101 104
- 116 32 115 105 32 115 105 104 84 34 10)
-@end group
-@end example
-
-@noindent
-Now we can put the output in the proper order by reversing the list:
-
-@example
-@group
-(concat (nreverse last-output))
- @result{} "
-\"This is the output\"
-"
-@end group
-@end example
-
-@noindent
-Calling @code{concat} converts the list to a string so you can see its
-contents more clearly.
-
-@node Output Functions
-@section Output Functions
-
- This section describes the Lisp functions for printing Lisp
-objects---converting objects into their printed representation.
-
-@cindex @samp{"} in printing
-@cindex @samp{\} in printing
-@cindex quoting characters in printing
-@cindex escape characters in printing
- Some of the Emacs printing functions add quoting characters to the
-output when necessary so that it can be read properly. The quoting
-characters used are @samp{"} and @samp{\}; they distinguish strings from
-symbols, and prevent punctuation characters in strings and symbols from
-being taken as delimiters when reading. @xref{Printed Representation},
-for full details. You specify quoting or no quoting by the choice of
-printing function.
-
- If the text is to be read back into Lisp, then you should print with
-quoting characters to avoid ambiguity. Likewise, if the purpose is to
-describe a Lisp object clearly for a Lisp programmer. However, if the
-purpose of the output is to look nice for humans, then it is usually
-better to print without quoting.
-
- Lisp objects can refer to themselves. Printing a self-referential
-object in the normal way would require an infinite amount of text, and
-the attempt could cause infinite recursion. Emacs detects such
-recursion and prints @samp{#@var{level}} instead of recursively printing
-an object already being printed. For example, here @samp{#0} indicates
-a recursive reference to the object at level 0 of the current print
-operation:
-
-@example
-(setq foo (list nil))
- @result{} (nil)
-(setcar foo foo)
- @result{} (#0)
-@end example
-
- In the functions below, @var{stream} stands for an output stream.
-(See the previous section for a description of output streams.) If
-@var{stream} is @code{nil} or omitted, it defaults to the value of
-@code{standard-output}.
-
-@defun print object &optional stream
-@cindex Lisp printer
-The @code{print} function is a convenient way of printing. It outputs
-the printed representation of @var{object} to @var{stream}, printing in
-addition one newline before @var{object} and another after it. Quoting
-characters are used. @code{print} returns @var{object}. For example:
-
-@example
-@group
-(progn (print 'The\ cat\ in)
- (print "the hat")
- (print " came back"))
- @print{}
- @print{} The\ cat\ in
- @print{}
- @print{} "the hat"
- @print{}
- @print{} " came back"
- @result{} " came back"
-@end group
-@end example
-@end defun
-
-@defun prin1 object &optional stream
-This function outputs the printed representation of @var{object} to
-@var{stream}. It does not print newlines to separate output as
-@code{print} does, but it does use quoting characters just like
-@code{print}. It returns @var{object}.
-
-@example
-@group
-(progn (prin1 'The\ cat\ in)
- (prin1 "the hat")
- (prin1 " came back"))
- @print{} The\ cat\ in"the hat"" came back"
- @result{} " came back"
-@end group
-@end example
-@end defun
-
-@defun princ object &optional stream
-This function outputs the printed representation of @var{object} to
-@var{stream}. It returns @var{object}.
-
-This function is intended to produce output that is readable by people,
-not by @code{read}, so it doesn't insert quoting characters and doesn't
-put double-quotes around the contents of strings. It does not add any
-spacing between calls.
-
-@example
-@group
-(progn
- (princ 'The\ cat)
- (princ " in the \"hat\""))
- @print{} The cat in the "hat"
- @result{} " in the \"hat\""
-@end group
-@end example
-@end defun
-
-@defun terpri &optional stream
-@cindex newline in print
-This function outputs a newline to @var{stream}. The name stands
-for ``terminate print.''
-@end defun
-
-@defun write-char character &optional stream
-This function outputs @var{character} to @var{stream}. It returns
-@var{character}.
-@end defun
-
-@defun prin1-to-string object &optional noescape
-@cindex object to string
-This function returns a string containing the text that @code{prin1}
-would have printed for the same argument.
-
-@example
-@group
-(prin1-to-string 'foo)
- @result{} "foo"
-@end group
-@group
-(prin1-to-string (mark-marker))
- @result{} "#<marker at 2773 in strings.texi>"
-@end group
-@end example
-
-If @var{noescape} is non-@code{nil}, that inhibits use of quoting
-characters in the output. (This argument is supported in Emacs versions
-19 and later.)
-
-@example
-@group
-(prin1-to-string "foo")
- @result{} "\"foo\""
-@end group
-@group
-(prin1-to-string "foo" t)
- @result{} "foo"
-@end group
-@end example
-
-See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
-the printed representation of a Lisp object as a string.
-@end defun
-
-@defmac with-output-to-string body@dots{}
-This macro executes the @var{body} forms with @code{standard-output} set
-up to feed output into a string. Then it returns that string.
-
-For example, if the current buffer name is @samp{foo},
-
-@example
-(with-output-to-string
- (princ "The buffer is ")
- (princ (buffer-name)))
-@end example
-
-@noindent
-returns @code{"The buffer is foo"}.
-@end defmac
-
-@node Output Variables
-@section Variables Affecting Output
-@cindex output-controlling variables
-
-@defvar standard-output
-The value of this variable is the default output stream---the stream
-that print functions use when the @var{stream} argument is @code{nil}.
-The default is @code{t}, meaning display in the echo area.
-@end defvar
-
-@defvar print-quoted
-If this is non-@code{nil}, that means to print quoted forms using
-abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo},
-@code{(function foo)} as @code{#'foo}, and backquoted forms print
-using modern backquote syntax.
-@end defvar
-
-@defvar print-escape-newlines
-@cindex @samp{\n} in print
-@cindex escape characters
-If this variable is non-@code{nil}, then newline characters in strings
-are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
-Normally these characters are printed as actual newlines and formfeeds.
-
-This variable affects the print functions @code{prin1} and @code{print}
-that print with quoting. It does not affect @code{princ}. Here is an
-example using @code{prin1}:
-
-@example
-@group
-(prin1 "a\nb")
- @print{} "a
- @print{} b"
- @result{} "a
-b"
-@end group
-
-@group
-(let ((print-escape-newlines t))
- (prin1 "a\nb"))
- @print{} "a\nb"
- @result{} "a
-b"
-@end group
-@end example
-
-@noindent
-In the second expression, the local binding of
-@code{print-escape-newlines} is in effect during the call to
-@code{prin1}, but not during the printing of the result.
-@end defvar
-
-@defvar print-escape-nonascii
-If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
-characters in strings are unconditionally printed as backslash sequences
-by the print functions @code{prin1} and @code{print} that print with
-quoting.
-
-Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
-characters, regardless of the value of this variable, when the output
-stream is a multibyte buffer or a marker pointing into one.
-@end defvar
-
-@defvar print-escape-multibyte
-If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
-characters in strings are unconditionally printed as backslash sequences
-by the print functions @code{prin1} and @code{print} that print with
-quoting.
-
-Those functions also use backslash sequences for multibyte
-non-@acronym{ASCII} characters, regardless of the value of this variable,
-when the output stream is a unibyte buffer or a marker pointing into
-one.
-@end defvar
-
-@defvar print-length
-@cindex printing limits
-The value of this variable is the maximum number of elements to print in
-any list, vector or bool-vector. If an object being printed has more
-than this many elements, it is abbreviated with an ellipsis.
-
-If the value is @code{nil} (the default), then there is no limit.
-
-@example
-@group
-(setq print-length 2)
- @result{} 2
-@end group
-@group
-(print '(1 2 3 4 5))
- @print{} (1 2 ...)
- @result{} (1 2 ...)
-@end group
-@end example
-@end defvar
-
-@defvar print-level
-The value of this variable is the maximum depth of nesting of
-parentheses and brackets when printed. Any list or vector at a depth
-exceeding this limit is abbreviated with an ellipsis. A value of
-@code{nil} (which is the default) means no limit.
-@end defvar
-
-@defopt eval-expression-print-length
-@defoptx eval-expression-print-level
-These are the values for @code{print-length} and @code{print-level}
-used by @code{eval-expression}, and thus, indirectly, by many
-interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
-Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
-@end defopt
-
- These variables are used for detecting and reporting circular
-and shared structure:
-
-@defvar print-circle
-If non-@code{nil}, this variable enables detection of circular
-and shared structure in printing.
-@end defvar
-
-@defvar print-gensym
-If non-@code{nil}, this variable enables detection of uninterned symbols
-(@pxref{Creating Symbols}) in printing. When this is enabled,
-uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
-reader to produce an uninterned symbol.
-@end defvar
-
-@defvar print-continuous-numbering
-If non-@code{nil}, that means number continuously across print calls.
-This affects the numbers printed for @samp{#@var{n}=} labels and
-@samp{#@var{m}#} references.
-
-Don't set this variable with @code{setq}; you should only bind it
-temporarily to @code{t} with @code{let}. When you do that, you should
-also bind @code{print-number-table} to @code{nil}.
-@end defvar
-
-@defvar print-number-table
-This variable holds a vector used internally by printing to implement
-the @code{print-circle} feature. You should not use it except
-to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
-@end defvar
-
-@defvar float-output-format
-This variable specifies how to print floating point numbers. Its
-default value is @code{nil}, meaning use the shortest output
-that represents the number without losing information.
-
-To control output format more precisely, you can put a string in this
-variable. The string should hold a @samp{%}-specification to be used
-in the C function @code{sprintf}. For further restrictions on what
-you can use, see the variable's documentation string.
-@end defvar
-
-@ignore
- arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/strings
-@node Strings and Characters, Lists, Numbers, Top
-@comment node-name, next, previous, up
-@chapter Strings and Characters
-@cindex strings
-@cindex character arrays
-@cindex characters
-@cindex bytes
-
- A string in Emacs Lisp is an array that contains an ordered sequence
-of characters. Strings are used as names of symbols, buffers, and
-files; to send messages to users; to hold text being copied between
-buffers; and for many other purposes. Because strings are so important,
-Emacs Lisp has many functions expressly for manipulating them. Emacs
-Lisp programs use strings more often than individual characters.
-
- @xref{Strings of Events}, for special considerations for strings of
-keyboard character events.
-
-@menu
-* Basics: 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 to and from characters and strings.
-* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
-* Case Conversion:: Case conversion functions.
-* Case Tables:: Customizing case conversion.
-@end menu
-
-@node String Basics
-@section String and Character Basics
-
- Characters are represented in Emacs Lisp as integers;
-whether an integer is a character or not is determined only by how it is
-used. Thus, strings really contain integers.
-
- The length of a string (like any array) is fixed, and cannot be
-altered once the string exists. Strings in Lisp are @emph{not}
-terminated by a distinguished character code. (By contrast, strings in
-C are terminated by a character with @acronym{ASCII} code 0.)
-
- Since strings are arrays, and therefore sequences as well, you can
-operate on them with the general array and sequence functions.
-(@xref{Sequences Arrays Vectors}.) For example, you can access or
-change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}).
-
- There are two text representations for non-@acronym{ASCII} characters in
-Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
-Representations}). An @acronym{ASCII} character always occupies one byte in a
-string; in fact, when a string is all @acronym{ASCII}, there is no real
-difference between the unibyte and multibyte representations.
-For most Lisp programming, you don't need to be concerned with these two
-representations.
-
- Sometimes key sequences are represented as strings. When a string is
-a key sequence, string elements in the range 128 to 255 represent meta
-characters (which are large integers) rather than character
-codes in the range 128 to 255.
-
- Strings cannot hold characters that have the hyper, super or alt
-modifiers; they can hold @acronym{ASCII} control characters, but no other
-control characters. They do not distinguish case in @acronym{ASCII} control
-characters. If you want to store such characters in a sequence, such as
-a key sequence, you must use a vector instead of a string.
-@xref{Character Type}, for more information about the representation of meta
-and other modifiers for keyboard input characters.
-
- Strings are useful for holding regular expressions. You can also
-match regular expressions against strings with @code{string-match}
-(@pxref{Regexp Search}). The functions @code{match-string}
-(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing
-Match}) are useful for decomposing and modifying strings after
-matching regular expressions against them.
-
- Like a buffer, a string can contain text properties for the characters
-in it, as well as the characters themselves. @xref{Text Properties}.
-All the Lisp primitives that copy text from strings to buffers or other
-strings also copy the properties of the characters being copied.
-
- @xref{Text}, for information about functions that display strings or
-copy them into buffers. @xref{Character Type}, and @ref{String Type},
-for information about the syntax of characters and strings.
-@xref{Non-ASCII Characters}, for functions to convert between text
-representations and to encode and decode character codes.
-
-@node Predicates for Strings
-@section The Predicates for Strings
-
-For more information about general sequence and array predicates,
-see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
-
-@defun stringp object
-This function returns @code{t} if @var{object} is a string, @code{nil}
-otherwise.
-@end defun
-
-@defun string-or-null-p object
-This function returns @code{t} if @var{object} is a string or nil,
-@code{nil} otherwise.
-@end defun
-
-@defun char-or-string-p object
-This function returns @code{t} if @var{object} is a string or a
-character (i.e., an integer), @code{nil} otherwise.
-@end defun
-
-@node Creating Strings
-@section Creating Strings
-
- The following functions create strings, either from scratch, or by
-putting strings together, or by taking them apart.
-
-@defun make-string count character
-This function returns a string made up of @var{count} repetitions of
-@var{character}. If @var{count} is negative, an error is signaled.
-
-@example
-(make-string 5 ?x)
- @result{} "xxxxx"
-(make-string 0 ?x)
- @result{} ""
-@end example
-
- Other functions to compare with this one include @code{char-to-string}
-(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
-@code{make-list} (@pxref{Building Lists}).
-@end defun
-
-@defun string &rest characters
-This returns a string containing the characters @var{characters}.
-
-@example
-(string ?a ?b ?c)
- @result{} "abc"
-@end example
-@end defun
-
-@defun substring string start &optional end
-This function returns a new string which consists of those characters
-from @var{string} in the range from (and including) the character at the
-index @var{start} up to (but excluding) the character at the index
-@var{end}. The first character is at index zero.
-
-@example
-@group
-(substring "abcdefg" 0 3)
- @result{} "abc"
-@end group
-@end example
-
-@noindent
-Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
-index for @samp{c} is 2. Thus, three letters, @samp{abc}, are copied
-from the string @code{"abcdefg"}. The index 3 marks the character
-position up to which the substring is copied. The character whose index
-is 3 is actually the fourth character in the string.
-
-A negative number counts from the end of the string, so that @minus{}1
-signifies the index of the last character of the string. For example:
-
-@example
-@group
-(substring "abcdefg" -3 -1)
- @result{} "ef"
-@end group
-@end example
-
-@noindent
-In this example, the index for @samp{e} is @minus{}3, the index for
-@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
-Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
-
-When @code{nil} is used for @var{end}, it stands for the length of the
-string. Thus,
-
-@example
-@group
-(substring "abcdefg" -3 nil)
- @result{} "efg"
-@end group
-@end example
-
-Omitting the argument @var{end} is equivalent to specifying @code{nil}.
-It follows that @code{(substring @var{string} 0)} returns a copy of all
-of @var{string}.
-
-@example
-@group
-(substring "abcdefg" 0)
- @result{} "abcdefg"
-@end group
-@end example
-
-@noindent
-But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
-Functions}).
-
-If the characters copied from @var{string} have text properties, the
-properties are copied into the new string also. @xref{Text Properties}.
-
-@code{substring} also accepts a vector for the first argument.
-For example:
-
-@example
-(substring [a b (c) "d"] 1 3)
- @result{} [b (c)]
-@end example
-
-A @code{wrong-type-argument} error is signaled if @var{start} is not
-an integer or if @var{end} is neither an integer nor @code{nil}. An
-@code{args-out-of-range} error is signaled if @var{start} indicates a
-character following @var{end}, or if either integer is out of range
-for @var{string}.
-
-Contrast this function with @code{buffer-substring} (@pxref{Buffer
-Contents}), which returns a string containing a portion of the text in
-the current buffer. The beginning of a string is at index 0, but the
-beginning of a buffer is at index 1.
-@end defun
-
-@defun substring-no-properties string &optional start end
-This works like @code{substring} but discards all text properties from
-the value. Also, @var{start} may be omitted or @code{nil}, which is
-equivalent to 0. Thus, @w{@code{(substring-no-properties
-@var{string})}} returns a copy of @var{string}, with all text
-properties removed.
-@end defun
-
-@defun concat &rest sequences
-@cindex copying strings
-@cindex concatenating strings
-This function returns a new string consisting of the characters in the
-arguments passed to it (along with their text properties, if any). The
-arguments may be strings, lists of numbers, or vectors of numbers; they
-are not themselves changed. If @code{concat} receives no arguments, it
-returns an empty string.
-
-@example
-(concat "abc" "-def")
- @result{} "abc-def"
-(concat "abc" (list 120 121) [122])
- @result{} "abcxyz"
-;; @r{@code{nil} is an empty sequence.}
-(concat "abc" nil "-def")
- @result{} "abc-def"
-(concat "The " "quick brown " "fox.")
- @result{} "The quick brown fox."
-(concat)
- @result{} ""
-@end example
-
-@noindent
-The @code{concat} function always constructs a new string that is
-not @code{eq} to any existing string.
-
-In Emacs versions before 21, when an argument was an integer (not a
-sequence of integers), it was converted to a string of digits making up
-the decimal printed representation of the integer. This obsolete usage
-no longer works. The proper way to convert an integer to its decimal
-printed form is with @code{format} (@pxref{Formatting Strings}) or
-@code{number-to-string} (@pxref{String Conversion}).
-
-For information about other concatenation functions, see the
-description of @code{mapconcat} in @ref{Mapping Functions},
-@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
-Lists}.
-@end defun
-
-@defun split-string string &optional separators omit-nulls
-This function splits @var{string} into substrings at matches for the
-regular expression @var{separators}. Each match for @var{separators}
-defines a splitting point; the substrings between the splitting points
-are made into a list, which is the value returned by
-@code{split-string}.
-
-If @var{omit-nulls} is @code{nil}, the result contains null strings
-whenever there are two consecutive matches for @var{separators}, or a
-match is adjacent to the beginning or end of @var{string}. If
-@var{omit-nulls} is @code{t}, these null strings are omitted from the
-result.
-
-If @var{separators} is @code{nil} (or omitted),
-the default is the value of @code{split-string-default-separators}.
-
-As a special case, when @var{separators} is @code{nil} (or omitted),
-null strings are always omitted from the result. Thus:
-
-@example
-(split-string " two words ")
- @result{} ("two" "words")
-@end example
-
-The result is not @code{("" "two" "words" "")}, which would rarely be
-useful. If you need such a result, use an explicit value for
-@var{separators}:
-
-@example
-(split-string " two words "
- split-string-default-separators)
- @result{} ("" "two" "words" "")
-@end example
-
-More examples:
-
-@example
-(split-string "Soup is good food" "o")
- @result{} ("S" "up is g" "" "d f" "" "d")
-(split-string "Soup is good food" "o" t)
- @result{} ("S" "up is g" "d f" "d")
-(split-string "Soup is good food" "o+")
- @result{} ("S" "up is g" "d f" "d")
-@end example
-
-Empty matches do count, except that @code{split-string} will not look
-for a final empty match when it already reached the end of the string
-using a non-empty match or when @var{string} is empty:
-
-@example
-(split-string "aooob" "o*")
- @result{} ("" "a" "" "b" "")
-(split-string "ooaboo" "o*")
- @result{} ("" "" "a" "b" "")
-(split-string "" "")
- @result{} ("")
-@end example
-
-However, when @var{separators} can match the empty string,
-@var{omit-nulls} is usually @code{t}, so that the subtleties in the
-three previous examples are rarely relevant:
-
-@example
-(split-string "Soup is good food" "o*" t)
- @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
-(split-string "Nice doggy!" "" t)
- @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
-(split-string "" "" t)
- @result{} nil
-@end example
-
-Somewhat odd, but predictable, behavior can occur for certain
-``non-greedy'' values of @var{separators} that can prefer empty
-matches over non-empty matches. Again, such values rarely occur in
-practice:
-
-@example
-(split-string "ooo" "o*" t)
- @result{} nil
-(split-string "ooo" "\\|o+" t)
- @result{} ("o" "o" "o")
-@end example
-@end defun
-
-@defvar split-string-default-separators
-The default value of @var{separators} for @code{split-string}. Its
-usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
-@end defvar
-
-@node Modifying Strings
-@section Modifying Strings
-
- The most basic way to alter the contents of an existing string is with
-@code{aset} (@pxref{Array Functions}). @code{(aset @var{string}
-@var{idx} @var{char})} stores @var{char} into @var{string} at index
-@var{idx}. Each character occupies one or more bytes, and if @var{char}
-needs a different number of bytes from the character already present at
-that index, @code{aset} signals an error.
-
- A more powerful function is @code{store-substring}:
-
-@defun store-substring string idx obj
-This function alters part of the contents of the string @var{string}, by
-storing @var{obj} starting at index @var{idx}. The argument @var{obj}
-may be either a character or a (smaller) string.
-
-Since it is impossible to change the length of an existing string, it is
-an error if @var{obj} doesn't fit within @var{string}'s actual length,
-or if any new character requires a different number of bytes from the
-character currently present at that point in @var{string}.
-@end defun
-
- To clear out a string that contained a password, use
-@code{clear-string}:
-
-@defun clear-string string
-This makes @var{string} a unibyte string and clears its contents to
-zeros. It may also change @var{string}'s length.
-@end defun
-
-@need 2000
-@node Text Comparison
-@section Comparison of Characters and Strings
-@cindex string equality
-
-@defun char-equal character1 character2
-This function returns @code{t} if the arguments represent the same
-character, @code{nil} otherwise. This function ignores differences
-in case if @code{case-fold-search} is non-@code{nil}.
-
-@example
-(char-equal ?x ?x)
- @result{} t
-(let ((case-fold-search nil))
- (char-equal ?x ?X))
- @result{} nil
-@end example
-@end defun
-
-@defun string= string1 string2
-This function returns @code{t} if the characters of the two strings
-match exactly. Symbols are also allowed as arguments, in which case
-their print names are used.
-Case is always significant, regardless of @code{case-fold-search}.
-
-@example
-(string= "abc" "abc")
- @result{} t
-(string= "abc" "ABC")
- @result{} nil
-(string= "ab" "ABC")
- @result{} nil
-@end example
-
-The function @code{string=} ignores the text properties of the two
-strings. When @code{equal} (@pxref{Equality Predicates}) compares two
-strings, it uses @code{string=}.
-
-For technical reasons, a unibyte and a multibyte string are
-@code{equal} if and only if they contain the same sequence of
-character codes and all these codes are either in the range 0 through
-127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
-However, when a unibyte string gets converted to a multibyte string,
-all characters with codes in the range 160 through 255 get converted
-to characters with higher codes, whereas @acronym{ASCII} characters
-remain unchanged. Thus, a unibyte string and its conversion to
-multibyte are only @code{equal} if the string is all @acronym{ASCII}.
-Character codes 160 through 255 are not entirely proper in multibyte
-text, even though they can occur. As a consequence, the situation
-where a unibyte and a multibyte string are @code{equal} without both
-being all @acronym{ASCII} is a technical oddity that very few Emacs
-Lisp programmers ever get confronted with. @xref{Text
-Representations}.
-@end defun
-
-@defun string-equal string1 string2
-@code{string-equal} is another name for @code{string=}.
-@end defun
-
-@cindex lexical comparison
-@defun string< string1 string2
-@c (findex string< causes problems for permuted index!!)
-This function compares two strings a character at a time. It
-scans both the strings at the same time to find the first pair of corresponding
-characters that do not match. If the lesser character of these two is
-the character from @var{string1}, then @var{string1} is less, and this
-function returns @code{t}. If the lesser character is the one from
-@var{string2}, then @var{string1} is greater, and this function returns
-@code{nil}. If the two strings match entirely, the value is @code{nil}.
-
-Pairs of characters are compared according to their character codes.
-Keep in mind that lower case letters have higher numeric values in the
-@acronym{ASCII} character set than their upper case counterparts; digits and
-many punctuation characters have a lower numeric value than upper case
-letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII}
-character; a unibyte non-@acronym{ASCII} character is always less than any
-multibyte non-@acronym{ASCII} character (@pxref{Text Representations}).
-
-@example
-@group
-(string< "abc" "abd")
- @result{} t
-(string< "abd" "abc")
- @result{} nil
-(string< "123" "abc")
- @result{} t
-@end group
-@end example
-
-When the strings have different lengths, and they match up to the
-length of @var{string1}, then the result is @code{t}. If they match up
-to the length of @var{string2}, the result is @code{nil}. A string of
-no characters is less than any other string.
-
-@example
-@group
-(string< "" "abc")
- @result{} t
-(string< "ab" "abc")
- @result{} t
-(string< "abc" "")
- @result{} nil
-(string< "abc" "ab")
- @result{} nil
-(string< "" "")
- @result{} nil
-@end group
-@end example
-
-Symbols are also allowed as arguments, in which case their print names
-are used.
-@end defun
-
-@defun string-lessp string1 string2
-@code{string-lessp} is another name for @code{string<}.
-@end defun
-
-@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
-This function compares the specified part of @var{string1} with the
-specified part of @var{string2}. The specified part of @var{string1}
-runs from index @var{start1} up to index @var{end1} (@code{nil} means
-the end of the string). The specified part of @var{string2} runs from
-index @var{start2} up to index @var{end2} (@code{nil} means the end of
-the string).
-
-The strings are both converted to multibyte for the comparison
-(@pxref{Text Representations}) so that a unibyte string and its
-conversion to multibyte are always regarded as equal. If
-@var{ignore-case} is non-@code{nil}, then case is ignored, so that
-upper case letters can be equal to lower case letters.
-
-If the specified portions of the two strings match, the value is
-@code{t}. Otherwise, the value is an integer which indicates how many
-leading characters agree, and which string is less. Its absolute value
-is one plus the number of characters that agree at the beginning of the
-two strings. The sign is negative if @var{string1} (or its specified
-portion) is less.
-@end defun
-
-@defun assoc-string key alist &optional case-fold
-This function works like @code{assoc}, except that @var{key} must be a
-string or symbol, and comparison is done using @code{compare-strings}.
-Symbols are converted to strings before testing.
-If @var{case-fold} is non-@code{nil}, it ignores case differences.
-Unlike @code{assoc}, this function can also match elements of the alist
-that are strings or symbols rather than conses. In particular, @var{alist} can
-be a list of strings or symbols rather than an actual alist.
-@xref{Association Lists}.
-@end defun
-
- See also the @code{compare-buffer-substrings} function in
-@ref{Comparing Text}, for a way to compare text in buffers. The
-function @code{string-match}, which matches a regular expression
-against a string, can be used for a kind of string comparison; see
-@ref{Regexp Search}.
-
-@node String Conversion
-@comment node-name, next, previous, up
-@section Conversion of Characters and Strings
-@cindex conversion of strings
-
- This section describes functions for conversions between characters,
-strings and integers. @code{format} (@pxref{Formatting Strings})
-and @code{prin1-to-string}
-(@pxref{Output Functions}) can also convert Lisp objects into strings.
-@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
-string representation of a Lisp object into an object. The functions
-@code{string-make-multibyte} and @code{string-make-unibyte} convert the
-text representation of a string (@pxref{Converting Representations}).
-
- @xref{Documentation}, for functions that produce textual descriptions
-of text characters and general input events
-(@code{single-key-description} and @code{text-char-description}). These
-are used primarily for making help messages.
-
-@defun char-to-string character
-@cindex character to string
-This function returns a new string containing one character,
-@var{character}. This function is semi-obsolete because the function
-@code{string} is more general. @xref{Creating Strings}.
-@end defun
-
-@defun string-to-char string
-@cindex string to character
- This function returns the first character in @var{string}. If the
-string is empty, the function returns 0. The value is also 0 when the
-first character of @var{string} is the null character, @acronym{ASCII} code
-0.
-
-@example
-(string-to-char "ABC")
- @result{} 65
-
-(string-to-char "xyz")
- @result{} 120
-(string-to-char "")
- @result{} 0
-@group
-(string-to-char "\000")
- @result{} 0
-@end group
-@end example
-
-This function may be eliminated in the future if it does not seem useful
-enough to retain.
-@end defun
-
-@defun number-to-string number
-@cindex integer to string
-@cindex integer to decimal
-This function returns a string consisting of the printed base-ten
-representation of @var{number}, which may be an integer or a floating
-point number. The returned value starts with a minus sign if the argument is
-negative.
-
-@example
-(number-to-string 256)
- @result{} "256"
-@group
-(number-to-string -23)
- @result{} "-23"
-@end group
-(number-to-string -23.5)
- @result{} "-23.5"
-@end example
-
-@cindex int-to-string
-@code{int-to-string} is a semi-obsolete alias for this function.
-
-See also the function @code{format} in @ref{Formatting Strings}.
-@end defun
-
-@defun string-to-number string &optional base
-@cindex string to number
-This function returns the numeric value of the characters in
-@var{string}. If @var{base} is non-@code{nil}, it must be an integer
-between 2 and 16 (inclusive), and integers are converted in that base.
-If @var{base} is @code{nil}, then base ten is used. Floating point
-conversion only works in base ten; we have not implemented other
-radices for floating point numbers, because that would be much more
-work and does not seem useful. If @var{string} looks like an integer
-but its value is too large to fit into a Lisp integer,
-@code{string-to-number} returns a floating point result.
-
-The parsing skips spaces and tabs at the beginning of @var{string},
-then reads as much of @var{string} as it can interpret as a number in
-the given base. (On some systems it ignores other whitespace at the
-beginning, not just spaces and tabs.) If the first character after
-the ignored whitespace is neither a digit in the given base, nor a
-plus or minus sign, nor the leading dot of a floating point number,
-this function returns 0.
-
-@example
-(string-to-number "256")
- @result{} 256
-(string-to-number "25 is a perfect square.")
- @result{} 25
-(string-to-number "X256")
- @result{} 0
-(string-to-number "-4.5")
- @result{} -4.5
-(string-to-number "1e5")
- @result{} 100000.0
-@end example
-
-@findex string-to-int
-@code{string-to-int} is an obsolete alias for this function.
-@end defun
-
- Here are some other functions that can convert to or from a string:
-
-@table @code
-@item concat
-@code{concat} can convert a vector or a list into a string.
-@xref{Creating Strings}.
-
-@item vconcat
-@code{vconcat} can convert a string into a vector. @xref{Vector
-Functions}.
-
-@item append
-@code{append} can convert a string into a list. @xref{Building Lists}.
-@end table
-
-@node Formatting Strings
-@comment node-name, next, previous, up
-@section Formatting Strings
-@cindex formatting strings
-@cindex strings, formatting them
-
- @dfn{Formatting} means constructing a string by substitution of
-computed values at various places in a constant string. This constant string
-controls how the other values are printed, as well as where they appear;
-it is called a @dfn{format string}.
-
- Formatting is often useful for computing messages to be displayed. In
-fact, the functions @code{message} and @code{error} provide the same
-formatting feature described here; they differ from @code{format} only
-in how they use the result of formatting.
-
-@defun format string &rest objects
-This function returns a new string that is made by copying
-@var{string} and then replacing any format specification
-in the copy with encodings of the corresponding @var{objects}. The
-arguments @var{objects} are the computed values to be formatted.
-
-The characters in @var{string}, other than the format specifications,
-are copied directly into the output, including their text properties,
-if any.
-@end defun
-
-@cindex @samp{%} in format
-@cindex format specification
- A format specification is a sequence of characters beginning with a
-@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the
-@code{format} function replaces it with the printed representation of
-one of the values to be formatted (one of the arguments @var{objects}).
-For example:
-
-@example
-@group
-(format "The value of fill-column is %d." fill-column)
- @result{} "The value of fill-column is 72."
-@end group
-@end example
-
- Since @code{format} interprets @samp{%} characters as format
-specifications, you should @emph{never} pass an arbitrary string as
-the first argument. This is particularly true when the string is
-generated by some Lisp code. Unless the string is @emph{known} to
-never include any @samp{%} characters, pass @code{"%s"}, described
-below, as the first argument, and the string as the second, like this:
-
-@example
- (format "%s" @var{arbitrary-string})
-@end example
-
- If @var{string} contains more than one format specification, the
-format specifications correspond to successive values from
-@var{objects}. Thus, the first format specification in @var{string}
-uses the first such value, the second format specification uses the
-second such value, and so on. Any extra format specifications (those
-for which there are no corresponding values) cause an error. Any
-extra values to be formatted are ignored.
-
- Certain format specifications require values of particular types. If
-you supply a value that doesn't fit the requirements, an error is
-signaled.
-
- Here is a table of valid format specifications:
-
-@table @samp
-@item %s
-Replace the specification with the printed representation of the object,
-made without quoting (that is, using @code{princ}, not
-@code{prin1}---@pxref{Output Functions}). Thus, strings are represented
-by their contents alone, with no @samp{"} characters, and symbols appear
-without @samp{\} characters.
-
-If the object is a string, its text properties are
-copied into the output. The text properties of the @samp{%s} itself
-are also copied, but those of the object take priority.
-
-@item %S
-Replace the specification with the printed representation of the object,
-made with quoting (that is, using @code{prin1}---@pxref{Output
-Functions}). Thus, strings are enclosed in @samp{"} characters, and
-@samp{\} characters appear where necessary before special characters.
-
-@item %o
-@cindex integer to octal
-Replace the specification with the base-eight representation of an
-integer.
-
-@item %d
-Replace the specification with the base-ten representation of an
-integer.
-
-@item %x
-@itemx %X
-@cindex integer to hexadecimal
-Replace the specification with the base-sixteen representation of an
-integer. @samp{%x} uses lower case and @samp{%X} uses upper case.
-
-@item %c
-Replace the specification with the character which is the value given.
-
-@item %e
-Replace the specification with the exponential notation for a floating
-point number.
-
-@item %f
-Replace the specification with the decimal-point notation for a floating
-point number.
-
-@item %g
-Replace the specification with notation for a floating point number,
-using either exponential notation or decimal-point notation, whichever
-is shorter.
-
-@item %%
-Replace the specification with a single @samp{%}. This format
-specification is unusual in that it does not use a value. For example,
-@code{(format "%% %d" 30)} returns @code{"% 30"}.
-@end table
-
- Any other format character results in an @samp{Invalid format
-operation} error.
-
- Here are several examples:
-
-@example
-@group
-(format "The name of this buffer is %s." (buffer-name))
- @result{} "The name of this buffer is strings.texi."
-
-(format "The buffer object prints as %s." (current-buffer))
- @result{} "The buffer object prints as strings.texi."
-
-(format "The octal value of %d is %o,
- and the hex value is %x." 18 18 18)
- @result{} "The octal value of 18 is 22,
- and the hex value is 12."
-@end group
-@end example
-
-@cindex field width
-@cindex padding
- A specification can have a @dfn{width}, which is a signed decimal
-number between the @samp{%} and the specification character. If the
-printed representation of the object contains fewer characters than
-this width, @code{format} extends it with padding. The padding goes
-on the left if the width is positive (or starts with zero) and on the
-right if the width is negative. The padding character is normally a
-space, but it's @samp{0} if the width starts with a zero.
-
- Some of these conventions are ignored for specification characters
-for which they do not make sense. That is, @samp{%s}, @samp{%S} and
-@samp{%c} accept a width starting with 0, but still pad with
-@emph{spaces} on the left. Also, @samp{%%} accepts a width, but
-ignores it. Here are some examples of padding:
-
-@example
-(format "%06d is padded on the left with zeros" 123)
- @result{} "000123 is padded on the left with zeros"
-
-(format "%-6d is padded on the right" 123)
- @result{} "123 is padded on the right"
-@end example
-
-@noindent
-If the width is too small, @code{format} does not truncate the
-object's printed representation. Thus, you can use a width to specify
-a minimum spacing between columns with no risk of losing information.
-
- In the following three examples, @samp{%7s} specifies a minimum
-width of 7. In the first case, the string inserted in place of
-@samp{%7s} has only 3 letters, it needs 4 blank spaces as padding. In
-the second case, the string @code{"specification"} is 13 letters wide
-but is not truncated. In the third case, the padding is on the right.
-
-@smallexample
-@group
-(format "The word `%7s' actually has %d letters in it."
- "foo" (length "foo"))
- @result{} "The word ` foo' actually has 3 letters in it."
-@end group
-
-@group
-(format "The word `%7s' actually has %d letters in it."
- "specification" (length "specification"))
- @result{} "The word `specification' actually has 13 letters in it."
-@end group
-
-@group
-(format "The word `%-7s' actually has %d letters in it."
- "foo" (length "foo"))
- @result{} "The word `foo ' actually has 3 letters in it."
-@end group
-@end smallexample
-
-@cindex precision in format specifications
- All the specification characters allow an optional @dfn{precision}
-before the character (after the width, if present). The precision is
-a decimal-point @samp{.} followed by a digit-string. For the
-floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
-precision specifies how many decimal places to show; if zero, the
-decimal-point itself is also omitted. For @samp{%s} and @samp{%S},
-the precision truncates the string to the given width, so @samp{%.3s}
-shows only the first three characters of the representation for
-@var{object}. Precision has no effect for other specification
-characters.
-
-@cindex flags in format specifications
- Immediately after the @samp{%} and before the optional width and
-precision, you can put certain ``flag'' characters.
-
- @samp{+} as a flag inserts a plus sign before a positive number, so
-that it always has a sign. A space character as flag inserts a space
-before a positive number. (Otherwise, positive numbers start with the
-first digit.) Either of these two flags ensures that positive numbers
-and negative numbers use the same number of columns. These flags are
-ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if
-both flags are used, the @samp{+} takes precedence.
-
- The flag @samp{#} specifies an ``alternate form'' which depends on
-the format in use. For @samp{%o} it ensures that the result begins
-with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result
-with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g},
-the @samp{#} flag means include a decimal point even if the precision
-is zero.
-
-@node Case Conversion
-@comment node-name, next, previous, up
-@section Case Conversion in Lisp
-@cindex upper case
-@cindex lower case
-@cindex character case
-@cindex case conversion in Lisp
-
- The character case functions change the case of single characters or
-of the contents of strings. The functions normally convert only
-alphabetic characters (the letters @samp{A} through @samp{Z} and
-@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other
-characters are not altered. You can specify a different case
-conversion mapping by specifying a case table (@pxref{Case Tables}).
-
- These functions do not modify the strings that are passed to them as
-arguments.
-
- The examples below use the characters @samp{X} and @samp{x} which have
-@acronym{ASCII} codes 88 and 120 respectively.
-
-@defun downcase string-or-char
-This function converts a character or a string to lower case.
-
-When the argument to @code{downcase} is a string, the function creates
-and returns a new string in which each letter in the argument that is
-upper case is converted to lower case. When the argument to
-@code{downcase} is a character, @code{downcase} returns the
-corresponding lower case character. This value is an integer. If the
-original character is lower case, or is not a letter, then the value
-equals the original character.
-
-@example
-(downcase "The cat in the hat")
- @result{} "the cat in the hat"
-
-(downcase ?X)
- @result{} 120
-@end example
-@end defun
-
-@defun upcase string-or-char
-This function converts a character or a string to upper case.
-
-When the argument to @code{upcase} is a string, the function creates
-and returns a new string in which each letter in the argument that is
-lower case is converted to upper case.
-
-When the argument to @code{upcase} is a character, @code{upcase}
-returns the corresponding upper case character. This value is an integer.
-If the original character is upper case, or is not a letter, then the
-value returned equals the original character.
-
-@example
-(upcase "The cat in the hat")
- @result{} "THE CAT IN THE HAT"
-
-(upcase ?x)
- @result{} 88
-@end example
-@end defun
-
-@defun capitalize string-or-char
-@cindex capitalization
-This function capitalizes strings or characters. If
-@var{string-or-char} is a string, the function creates and returns a new
-string, whose contents are a copy of @var{string-or-char} in which each
-word has been capitalized. This means that the first character of each
-word is converted to upper case, and the rest are converted to lower
-case.
-
-The definition of a word is any sequence of consecutive characters that
-are assigned to the word constituent syntax class in the current syntax
-table (@pxref{Syntax Class Table}).
-
-When the argument to @code{capitalize} is a character, @code{capitalize}
-has the same result as @code{upcase}.
-
-@example
-@group
-(capitalize "The cat in the hat")
- @result{} "The Cat In The Hat"
-@end group
-
-@group
-(capitalize "THE 77TH-HATTED CAT")
- @result{} "The 77th-Hatted Cat"
-@end group
-
-@group
-(capitalize ?x)
- @result{} 88
-@end group
-@end example
-@end defun
-
-@defun upcase-initials string-or-char
-If @var{string-or-char} is a string, this function capitalizes the
-initials of the words in @var{string-or-char}, without altering any
-letters other than the initials. It returns a new string whose
-contents are a copy of @var{string-or-char}, in which each word has
-had its initial letter converted to upper case.
-
-The definition of a word is any sequence of consecutive characters that
-are assigned to the word constituent syntax class in the current syntax
-table (@pxref{Syntax Class Table}).
-
-When the argument to @code{upcase-initials} is a character,
-@code{upcase-initials} has the same result as @code{upcase}.
-
-@example
-@group
-(upcase-initials "The CAT in the hAt")
- @result{} "The CAT In The HAt"
-@end group
-@end example
-@end defun
-
- @xref{Text Comparison}, for functions that compare strings; some of
-them ignore case differences, or can optionally ignore case differences.
-
-@node Case Tables
-@section The Case Table
-
- You can customize case conversion by installing a special @dfn{case
-table}. A case table specifies the mapping between upper case and lower
-case letters. It affects both the case conversion functions for Lisp
-objects (see the previous section) and those that apply to text in the
-buffer (@pxref{Case Changes}). Each buffer has a case table; there is
-also a standard case table which is used to initialize the case table
-of new buffers.
-
- A case table is a char-table (@pxref{Char-Tables}) whose subtype is
-@code{case-table}. This char-table maps each character into the
-corresponding lower case character. It has three extra slots, which
-hold related tables:
-
-@table @var
-@item upcase
-The upcase table maps each character into the corresponding upper
-case character.
-@item canonicalize
-The canonicalize table maps all of a set of case-related characters
-into a particular member of that set.
-@item equivalences
-The equivalences table maps each one of a set of case-related characters
-into the next character in that set.
-@end table
-
- In simple cases, all you need to specify is the mapping to lower-case;
-the three related tables will be calculated automatically from that one.
-
- For some languages, upper and lower case letters are not in one-to-one
-correspondence. There may be two different lower case letters with the
-same upper case equivalent. In these cases, you need to specify the
-maps for both lower case and upper case.
-
- The extra table @var{canonicalize} maps each character to a canonical
-equivalent; any two characters that are related by case-conversion have
-the same canonical equivalent character. For example, since @samp{a}
-and @samp{A} are related by case-conversion, they should have the same
-canonical equivalent character (which should be either @samp{a} for both
-of them, or @samp{A} for both of them).
-
- The extra table @var{equivalences} is a map that cyclically permutes
-each equivalence class (of characters with the same canonical
-equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into
-@samp{A} and @samp{A} into @samp{a}, and likewise for each set of
-equivalent characters.)
-
- When you construct a case table, you can provide @code{nil} for
-@var{canonicalize}; then Emacs fills in this slot from the lower case
-and upper case mappings. You can also provide @code{nil} for
-@var{equivalences}; then Emacs fills in this slot from
-@var{canonicalize}. In a case table that is actually in use, those
-components are non-@code{nil}. Do not try to specify @var{equivalences}
-without also specifying @var{canonicalize}.
-
- Here are the functions for working with case tables:
-
-@defun case-table-p object
-This predicate returns non-@code{nil} if @var{object} is a valid case
-table.
-@end defun
-
-@defun set-standard-case-table table
-This function makes @var{table} the standard case table, so that it will
-be used in any buffers created subsequently.
-@end defun
-
-@defun standard-case-table
-This returns the standard case table.
-@end defun
-
-@defun current-case-table
-This function returns the current buffer's case table.
-@end defun
-
-@defun set-case-table table
-This sets the current buffer's case table to @var{table}.
-@end defun
-
-@defmac with-case-table table body@dots{}
-The @code{with-case-table} macro saves the current case table, makes
-@var{table} the current case table, evaluates the @var{body} forms,
-and finally restores the case table. The return value is the value of
-the last form in @var{body}. The case table is restored even in case
-of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
-Exits}).
-@end defmac
-
- Some language environments may modify the case conversions of
-@acronym{ASCII} characters; for example, in the Turkish language
-environment, the @acronym{ASCII} character @samp{I} is downcased into
-a Turkish ``dotless i''. This can interfere with code that requires
-ordinary ASCII case conversion, such as implementations of
-@acronym{ASCII}-based network protocols. In that case, use the
-@code{with-case-table} macro with the variable @var{ascii-case-table},
-which stores the unmodified case table for the @acronym{ASCII}
-character set.
-
-@defvar ascii-case-table
-The case table for the @acronym{ASCII} character set. This should not be
-modified by any language environment settings.
-@end defvar
-
- The following three functions are convenient subroutines for packages
-that define non-@acronym{ASCII} character sets. They modify the specified
-case table @var{case-table}; they also modify the standard syntax table.
-@xref{Syntax Tables}. Normally you would use these functions to change
-the standard case table.
-
-@defun set-case-syntax-pair uc lc case-table
-This function specifies a pair of corresponding letters, one upper case
-and one lower case.
-@end defun
-
-@defun set-case-syntax-delims l r case-table
-This function makes characters @var{l} and @var{r} a matching pair of
-case-invariant delimiters.
-@end defun
-
-@defun set-case-syntax char syntax case-table
-This function makes @var{char} case-invariant, with syntax
-@var{syntax}.
-@end defun
-
-@deffn Command describe-buffer-case-table
-This command displays a description of the contents of the current
-buffer's case table.
-@end deffn
-
-@ignore
- arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/symbols
-@node Symbols, Evaluation, Hash Tables, Top
-@chapter Symbols
-@cindex symbol
-
- A @dfn{symbol} is an object with a unique name. This chapter
-describes symbols, their components, their property lists, and how they
-are created and interned. Separate chapters describe the use of symbols
-as variables and as function names; see @ref{Variables}, and
-@ref{Functions}. For the precise read syntax for symbols, see
-@ref{Symbol Type}.
-
- You can test whether an arbitrary Lisp object is a symbol
-with @code{symbolp}:
-
-@defun symbolp object
-This function returns @code{t} if @var{object} is a symbol, @code{nil}
-otherwise.
-@end defun
-
-@menu
-* 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.
-@end menu
-
-@node Symbol Components, Definitions, Symbols, Symbols
-@section Symbol Components
-@cindex symbol components
-
- Each symbol has four components (or ``cells''), each of which
-references another object:
-
-@table @asis
-@item Print name
-@cindex print name cell
-The @dfn{print name cell} holds a string that names the symbol for
-reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
-
-@item Value
-@cindex value cell
-The @dfn{value cell} holds the current value of the symbol as a
-variable. When a symbol is used as a form, the value of the form is the
-contents of the symbol's value cell. See @code{symbol-value} in
-@ref{Accessing Variables}.
-
-@item Function
-@cindex function cell
-The @dfn{function cell} holds the function definition of the symbol.
-When a symbol is used as a function, its function definition is used in
-its place. This cell is also used to make a symbol stand for a keymap
-or a keyboard macro, for editor command execution. Because each symbol
-has separate value and function cells, variables names and function names do
-not conflict. See @code{symbol-function} in @ref{Function Cells}.
-
-@item Property list
-@cindex property list cell
-The @dfn{property list cell} holds the property list of the symbol. See
-@code{symbol-plist} in @ref{Property Lists}.
-@end table
-
- The print name cell always holds a string, and cannot be changed. The
-other three cells can be set individually to any specified Lisp object.
-
- The print name cell holds the string that is the name of the symbol.
-Since symbols are represented textually by their names, it is important
-not to have two symbols with the same name. The Lisp reader ensures
-this: every time it reads a symbol, it looks for an existing symbol with
-the specified name before it creates a new one. (In GNU Emacs Lisp,
-this lookup uses a hashing algorithm and an obarray; see @ref{Creating
-Symbols}.)
-
- The value cell holds the symbol's value as a variable
-(@pxref{Variables}). That is what you get if you evaluate the symbol as
-a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate
-value. Certain symbols have values that cannot be changed; these
-include @code{nil} and @code{t}, and any symbol whose name starts with
-@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}.
-
- We often refer to ``the function @code{foo}'' when we really mean
-the function stored in the function cell of the symbol @code{foo}. We
-make the distinction explicit only when necessary. In normal
-usage, the function cell usually contains a function
-(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
-Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
-macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
-autoload objects (@pxref{Autoloading}) are also sometimes stored in
-the function cells of symbols.
-
- The property list cell normally should hold a correctly formatted
-property list (@pxref{Property Lists}), as a number of functions expect
-to see a property list there.
-
- The function cell or the value cell may be @dfn{void}, which means
-that the cell does not reference any object. (This is not the same
-thing as holding the symbol @code{void}, nor the same as holding the
-symbol @code{nil}.) Examining a function or value cell that is void
-results in an error, such as @samp{Symbol's value as variable is void}.
-
- The four functions @code{symbol-name}, @code{symbol-value},
-@code{symbol-plist}, and @code{symbol-function} return the contents of
-the four cells of a symbol. Here as an example we show the contents of
-the four cells of the symbol @code{buffer-file-name}:
-
-@example
-(symbol-name 'buffer-file-name)
- @result{} "buffer-file-name"
-(symbol-value 'buffer-file-name)
- @result{} "/gnu/elisp/symbols.texi"
-(symbol-function 'buffer-file-name)
- @result{} #<subr buffer-file-name>
-(symbol-plist 'buffer-file-name)
- @result{} (variable-documentation 29529)
-@end example
-
-@noindent
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the Emacs Lisp Manual.
-The property list cell contains the list @code{(variable-documentation
-29529)} which tells the documentation functions where to find the
-documentation string for the variable @code{buffer-file-name} in the
-@file{DOC-@var{version}} file. (29529 is the offset from the beginning
-of the @file{DOC-@var{version}} file to where that documentation string
-begins---see @ref{Documentation Basics}.) The function cell contains
-the function for returning the name of the file.
-@code{buffer-file-name} names a primitive function, which has no read
-syntax and prints in hash notation (@pxref{Primitive Function Type}). A
-symbol naming a function written in Lisp would have a lambda expression
-(or a byte-code object) in this cell.
-
-@node Definitions, Creating Symbols, Symbol Components, Symbols
-@section Defining Symbols
-@cindex definitions of symbols
-
- A @dfn{definition} in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way. In Emacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
- A definition construct typically specifies a value or meaning for the
-symbol for one kind of use, plus documentation for its meaning when used
-in this way. Thus, when you define a symbol as a variable, you can
-supply an initial value for the variable, plus documentation for the
-variable.
-
- @code{defvar} and @code{defconst} are special forms that define a
-symbol as a global variable. They are documented in detail in
-@ref{Defining Variables}. For defining user option variables that can
-be customized, use @code{defcustom} (@pxref{Customization}).
-
- @code{defun} defines a symbol as a function, creating a lambda
-expression and storing it in the function cell of the symbol. This
-lambda expression thus becomes the function definition of the symbol.
-(The term ``function definition,'' meaning the contents of the function
-cell, is derived from the idea that @code{defun} gives the symbol its
-definition as a function.) @code{defsubst} and @code{defalias} are two
-other ways of defining a function. @xref{Functions}.
-
- @code{defmacro} defines a symbol as a macro. It creates a macro
-object and stores it in the function cell of the symbol. Note that a
-given symbol can be a macro or a function, but not both at once, because
-both macro and function definitions are kept in the function cell, and
-that cell can hold only one Lisp object at any given time.
-@xref{Macros}.
-
- In Emacs Lisp, a definition is not required in order to use a symbol
-as a variable or function. Thus, you can make a symbol a global
-variable with @code{setq}, whether you define it first or not. The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
-@emph{intended} to be used as variables, or as functions. In addition,
-utilities such as @file{etags} and @file{make-docfile} recognize
-definitions, and add appropriate information to tag tables and the
-@file{DOC-@var{version}} file. @xref{Accessing Documentation}.
-
-@node Creating Symbols, Property Lists, Definitions, Symbols
-@section Creating and Interning Symbols
-@cindex reading symbols
-
- To understand how symbols are created in GNU Emacs Lisp, you must know
-how Lisp reads them. Lisp must ensure that it finds the same symbol
-every time it reads the same set of characters. Failure to do so would
-cause complete confusion.
-
-@cindex symbol name hashing
-@cindex hashing
-@cindex obarray
-@cindex bucket (in obarray)
- When the Lisp reader encounters a symbol, it reads all the characters
-of the name. Then it ``hashes'' those characters to find an index in a
-table called an @dfn{obarray}. Hashing is an efficient method of
-looking something up. For example, instead of searching a telephone
-book cover to cover when looking up Jan Jones, you start with the J's
-and go from there. That is a simple version of hashing. Each element
-of the obarray is a @dfn{bucket} which holds all the symbols with a
-given hash code; to look for a given name, it is sufficient to look
-through all the symbols in the bucket for that name's hash code. (The
-same idea is used for general Emacs hash tables, but they are a
-different data type; see @ref{Hash Tables}.)
-
-@cindex interning
- If a symbol with the desired name is found, the reader uses that
-symbol. If the obarray does not contain a symbol with that name, the
-reader makes a new symbol and adds it to the obarray. Finding or adding
-a symbol with a certain name is called @dfn{interning} it, and the
-symbol is then called an @dfn{interned symbol}.
-
- Interning ensures that each obarray has just one symbol with any
-particular name. Other like-named symbols may exist, but not in the
-same obarray. Thus, the reader gets the same symbols for the same
-names, as long as you keep reading with the same obarray.
-
- Interning usually happens automatically in the reader, but sometimes
-other programs need to do it. For example, after the @kbd{M-x} command
-obtains the command name as a string using the minibuffer, it then
-interns the string, to get the interned symbol with that name.
-
-@cindex symbol equality
-@cindex uninterned symbol
- No obarray contains all symbols; in fact, some symbols are not in any
-obarray. They are called @dfn{uninterned symbols}. An uninterned
-symbol has the same four cells as other symbols; however, the only way
-to gain access to it is by finding it in some other object or as the
-value of a variable.
-
- Creating an uninterned symbol is useful in generating Lisp code,
-because an uninterned symbol used as a variable in the code you generate
-cannot clash with any variables used in other Lisp programs.
-
- In Emacs Lisp, an obarray is actually a vector. Each element of the
-vector is a bucket; its value is either an interned symbol whose name
-hashes to that bucket, or 0 if the bucket is empty. Each interned
-symbol has an internal link (invisible to the user) to the next symbol
-in the bucket. Because these links are invisible, there is no way to
-find all the symbols in an obarray except using @code{mapatoms} (below).
-The order of symbols in a bucket is not significant.
-
- In an empty obarray, every element is 0, so you can create an obarray
-with @code{(make-vector @var{length} 0)}. @strong{This is the only
-valid way to create an obarray.} Prime numbers as lengths tend
-to result in good hashing; lengths one less than a power of two are also
-good.
-
- @strong{Do not try to put symbols in an obarray yourself.} This does
-not work---only @code{intern} can enter a symbol in an obarray properly.
-
-@cindex CL note---symbol in obarrays
-@quotation
-@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
-several obarrays.
-@end quotation
-
- Most of the functions below take a name and sometimes an obarray as
-arguments. A @code{wrong-type-argument} error is signaled if the name
-is not a string, or if the obarray is not a vector.
-
-@defun symbol-name symbol
-This function returns the string that is @var{symbol}'s name. For example:
-
-@example
-@group
-(symbol-name 'foo)
- @result{} "foo"
-@end group
-@end example
-
-@strong{Warning:} Changing the string by substituting characters does
-change the name of the symbol, but fails to update the obarray, so don't
-do it!
-@end defun
-
-@defun make-symbol name
-This function returns a newly-allocated, uninterned symbol whose name is
-@var{name} (which must be a string). Its value and function definition
-are void, and its property list is @code{nil}. In the example below,
-the value of @code{sym} is not @code{eq} to @code{foo} because it is a
-distinct uninterned symbol whose name is also @samp{foo}.
-
-@example
-(setq sym (make-symbol "foo"))
- @result{} foo
-(eq sym 'foo)
- @result{} nil
-@end example
-@end defun
-
-@defun intern name &optional obarray
-This function returns the interned symbol whose name is @var{name}. If
-there is no such symbol in the obarray @var{obarray}, @code{intern}
-creates a new one, adds it to the obarray, and returns it. If
-@var{obarray} is omitted, the value of the global variable
-@code{obarray} is used.
-
-@example
-(setq sym (intern "foo"))
- @result{} foo
-(eq sym 'foo)
- @result{} t
-
-(setq sym1 (intern "foo" other-obarray))
- @result{} foo
-(eq sym1 'foo)
- @result{} nil
-@end example
-@end defun
-
-@cindex CL note---interning existing symbol
-@quotation
-@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
-in an obarray. In Emacs Lisp, you cannot do this, because the argument
-to @code{intern} must be a string, not a symbol.
-@end quotation
-
-@defun intern-soft name &optional obarray
-This function returns the symbol in @var{obarray} whose name is
-@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
-Therefore, you can use @code{intern-soft} to test whether a symbol with
-a given name is already interned. If @var{obarray} is omitted, the
-value of the global variable @code{obarray} is used.
-
-The argument @var{name} may also be a symbol; in that case,
-the function returns @var{name} if @var{name} is interned
-in the specified obarray, and otherwise @code{nil}.
-
-@smallexample
-(intern-soft "frazzle") ; @r{No such symbol exists.}
- @result{} nil
-(make-symbol "frazzle") ; @r{Create an uninterned one.}
- @result{} frazzle
-@group
-(intern-soft "frazzle") ; @r{That one cannot be found.}
- @result{} nil
-@end group
-@group
-(setq sym (intern "frazzle")) ; @r{Create an interned one.}
- @result{} frazzle
-@end group
-@group
-(intern-soft "frazzle") ; @r{That one can be found!}
- @result{} frazzle
-@end group
-@group
-(eq sym 'frazzle) ; @r{And it is the same one.}
- @result{} t
-@end group
-@end smallexample
-@end defun
-
-@defvar obarray
-This variable is the standard obarray for use by @code{intern} and
-@code{read}.
-@end defvar
-
-@defun mapatoms function &optional obarray
-@anchor{Definition of mapatoms}
-This function calls @var{function} once with each symbol in the obarray
-@var{obarray}. Then it returns @code{nil}. If @var{obarray} is
-omitted, it defaults to the value of @code{obarray}, the standard
-obarray for ordinary symbols.
-
-@smallexample
-(setq count 0)
- @result{} 0
-(defun count-syms (s)
- (setq count (1+ count)))
- @result{} count-syms
-(mapatoms 'count-syms)
- @result{} nil
-count
- @result{} 1871
-@end smallexample
-
-See @code{documentation} in @ref{Accessing Documentation}, for another
-example using @code{mapatoms}.
-@end defun
-
-@defun unintern symbol &optional obarray
-This function deletes @var{symbol} from the obarray @var{obarray}. If
-@code{symbol} is not actually in the obarray, @code{unintern} does
-nothing. If @var{obarray} is @code{nil}, the current obarray is used.
-
-If you provide a string instead of a symbol as @var{symbol}, it stands
-for a symbol name. Then @code{unintern} deletes the symbol (if any) in
-the obarray which has that name. If there is no such symbol,
-@code{unintern} does nothing.
-
-If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
-it returns @code{nil}.
-@end defun
-
-@node Property Lists,, Creating Symbols, Symbols
-@section Property Lists
-@cindex property list
-@cindex plist
-
- A @dfn{property list} (@dfn{plist} for short) is a list of paired
-elements stored in the property list cell of a symbol. Each of the
-pairs associates a property name (usually a symbol) with a property or
-value. Property lists are generally used to record information about a
-symbol, such as its documentation as a variable, the name of the file
-where it was defined, or perhaps even the grammatical class of the
-symbol (representing a word) in a language-understanding system.
-
- Character positions in a string or buffer can also have property lists.
-@xref{Text Properties}.
-
- The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols. Property list functions
-compare the property names using @code{eq}. Here is an example of a
-property list, found on the symbol @code{progn} when the compiler is
-loaded:
-
-@example
-(lisp-indent-function 0 byte-compile byte-compile-progn)
-@end example
-
-@noindent
-Here @code{lisp-indent-function} and @code{byte-compile} are property
-names, and the other two elements are the corresponding values.
-
-@menu
-* 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.
-@end menu
-
-@node Plists and Alists
-@subsection Property Lists and Association Lists
-@cindex plist vs. alist
-@cindex alist vs. plist
-
-@cindex property lists vs association lists
- Association lists (@pxref{Association Lists}) are very similar to
-property lists. In contrast to association lists, the order of the
-pairs in the property list is not significant since the property names
-must be distinct.
-
- Property lists are better than association lists for attaching
-information to various Lisp function names or variables. If your
-program keeps all of its associations in one association list, it will
-typically need to search that entire list each time it checks for an
-association. This could be slow. By contrast, if you keep the same
-information in the property lists of the function names or variables
-themselves, each search will scan only the length of one property list,
-which is usually short. This is why the documentation for a variable is
-recorded in a property named @code{variable-documentation}. The byte
-compiler likewise uses properties to record those functions needing
-special treatment.
-
- However, association lists have their own advantages. Depending on
-your application, it may be faster to add an association to the front of
-an association list than to update a property. All properties for a
-symbol are stored in the same property list, so there is a possibility
-of a conflict between different uses of a property name. (For this
-reason, it is a good idea to choose property names that are probably
-unique, such as by beginning the property name with the program's usual
-name-prefix for variables and functions.) An association list may be
-used like a stack where associations are pushed on the front of the list
-and later discarded; this is not possible with a property list.
-
-@node Symbol Plists
-@subsection Property List Functions for Symbols
-
-@defun symbol-plist symbol
-This function returns the property list of @var{symbol}.
-@end defun
-
-@defun setplist symbol plist
-This function sets @var{symbol}'s property list to @var{plist}.
-Normally, @var{plist} should be a well-formed property list, but this is
-not enforced. The return value is @var{plist}.
-
-@smallexample
-(setplist 'foo '(a 1 b (2 3) c nil))
- @result{} (a 1 b (2 3) c nil)
-(symbol-plist 'foo)
- @result{} (a 1 b (2 3) c nil)
-@end smallexample
-
-For symbols in special obarrays, which are not used for ordinary
-purposes, it may make sense to use the property list cell in a
-nonstandard fashion; in fact, the abbrev mechanism does so
-(@pxref{Abbrevs}).
-@end defun
-
-@defun get symbol property
-This function finds the value of the property named @var{property} in
-@var{symbol}'s property list. If there is no such property, @code{nil}
-is returned. Thus, there is no distinction between a value of
-@code{nil} and the absence of the property.
-
-The name @var{property} is compared with the existing property names
-using @code{eq}, so any object is a legitimate property.
-
-See @code{put} for an example.
-@end defun
-
-@defun put symbol property value
-This function puts @var{value} onto @var{symbol}'s property list under
-the property name @var{property}, replacing any previous property value.
-The @code{put} function returns @var{value}.
-
-@smallexample
-(put 'fly 'verb 'transitive)
- @result{}'transitive
-(put 'fly 'noun '(a buzzing little bug))
- @result{} (a buzzing little bug)
-(get 'fly 'verb)
- @result{} transitive
-(symbol-plist 'fly)
- @result{} (verb transitive noun (a buzzing little bug))
-@end smallexample
-@end defun
-
-@node Other Plists
-@subsection Property Lists Outside Symbols
-
- These functions are useful for manipulating property lists
-that are stored in places other than symbols:
-
-@defun plist-get plist property
-This returns the value of the @var{property} property
-stored in the property list @var{plist}. For example,
-
-@example
-(plist-get '(foo 4) 'foo)
- @result{} 4
-(plist-get '(foo 4 bad) 'foo)
- @result{} 4
-(plist-get '(foo 4 bad) 'bar)
- @result{} @code{wrong-type-argument} error
-@end example
-
-It accepts a malformed @var{plist} argument and always returns @code{nil}
-if @var{property} is not found in the @var{plist}. For example,
-
-@example
-(plist-get '(foo 4 bad) 'bar)
- @result{} nil
-@end example
-@end defun
-
-@defun plist-put plist property value
-This stores @var{value} as the value of the @var{property} property in
-the property list @var{plist}. It may modify @var{plist} destructively,
-or it may construct a new list structure without altering the old. The
-function returns the modified property list, so you can store that back
-in the place where you got @var{plist}. For example,
-
-@example
-(setq my-plist '(bar t foo 4))
- @result{} (bar t foo 4)
-(setq my-plist (plist-put my-plist 'foo 69))
- @result{} (bar t foo 69)
-(setq my-plist (plist-put my-plist 'quux '(a)))
- @result{} (bar t foo 69 quux (a))
-@end example
-@end defun
-
- You could define @code{put} in terms of @code{plist-put} as follows:
-
-@example
-(defun put (symbol prop value)
- (setplist symbol
- (plist-put (symbol-plist symbol) prop value)))
-@end example
-
-@defun lax-plist-get plist property
-Like @code{plist-get} except that it compares properties
-using @code{equal} instead of @code{eq}.
-@end defun
-
-@defun lax-plist-put plist property value
-Like @code{plist-put} except that it compares properties
-using @code{equal} instead of @code{eq}.
-@end defun
-
-@defun plist-member plist property
-This returns non-@code{nil} if @var{plist} contains the given
-@var{property}. Unlike @code{plist-get}, this allows you to distinguish
-between a missing property and a property with the value @code{nil}.
-The value is actually the tail of @var{plist} whose @code{car} is
-@var{property}.
-@end defun
-
-@ignore
- arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/syntax
-@node Syntax Tables, Abbrevs, Searching and Matching, Top
-@chapter Syntax Tables
-@cindex parsing buffer text
-@cindex syntax table
-@cindex text parsing
-
- A @dfn{syntax table} specifies the syntactic textual function of each
-character. This information is used by the @dfn{parsing functions}, the
-complex movement commands, and others to determine where words, symbols,
-and other syntactic constructs begin and end. The current syntax table
-controls the meaning of the word motion functions (@pxref{Word Motion})
-and the list motion functions (@pxref{List Motion}), as well as the
-functions in this chapter.
-
-@menu
-* Basics: Syntax Basics. Basic concepts of syntax tables.
-* Desc: 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.
-@end menu
-
-@node Syntax Basics
-@section Syntax Table Concepts
-
-@ifnottex
- A @dfn{syntax table} provides Emacs with the information that
-determines the syntactic use of each character in a buffer. This
-information is used by the parsing commands, the complex movement
-commands, and others to determine where words, symbols, and other
-syntactic constructs begin and end. The current syntax table controls
-the meaning of the word motion functions (@pxref{Word Motion}) and the
-list motion functions (@pxref{List Motion}) as well as the functions in
-this chapter.
-@end ifnottex
-
- A syntax table is a char-table (@pxref{Char-Tables}). The element at
-index @var{c} describes the character with code @var{c}. The element's
-value should be a list that encodes the syntax of the character in
-question.
-
- Syntax tables are used only for moving across text, not for the Emacs
-Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
-expressions, and these rules cannot be changed. (Some Lisp systems
-provide ways to redefine the read syntax, but we decided to leave this
-feature out of Emacs Lisp for simplicity.)
-
- Each buffer has its own major mode, and each major mode has its own
-idea of the syntactic class of various characters. For example, in Lisp
-mode, the character @samp{;} begins a comment, but in C mode, it
-terminates a statement. To support these variations, Emacs makes the
-choice of syntax table local to each buffer. Typically, each major
-mode has its own syntax table and installs that table in each buffer
-that uses that mode. Changing this table alters the syntax in all
-those buffers as well as in any buffers subsequently put in that mode.
-Occasionally several similar modes share one syntax table.
-@xref{Example Major Modes}, for an example of how to set up a syntax
-table.
-
-A syntax table can inherit the data for some characters from the
-standard syntax table, while specifying other characters itself. The
-``inherit'' syntax class means ``inherit this character's syntax from
-the standard syntax table.'' Just changing the standard syntax for a
-character affects all syntax tables that inherit from it.
-
-@defun syntax-table-p object
-This function returns @code{t} if @var{object} is a syntax table.
-@end defun
-
-@node Syntax Descriptors
-@section Syntax Descriptors
-@cindex syntax class
-
- This section describes the syntax classes and flags that denote the
-syntax of a character, and how they are represented as a @dfn{syntax
-descriptor}, which is a Lisp string that you pass to
-@code{modify-syntax-entry} to specify the syntax you want.
-
- The syntax table specifies a syntax class for each character. There
-is no necessary relationship between the class of a character in one
-syntax table and its class in any other table.
-
- Each class is designated by a mnemonic character, which serves as the
-name of the class when you need to specify a class. Usually the
-designator character is one that is often assigned that class; however,
-its meaning as a designator is unvarying and independent of what syntax
-that character currently has. Thus, @samp{\} as a designator character
-always gives ``escape character'' syntax, regardless of what syntax
-@samp{\} currently has.
-
-@cindex syntax descriptor
- A syntax descriptor is a Lisp string that specifies a syntax class, a
-matching character (used only for the parenthesis classes) and flags.
-The first character is the designator for a syntax class. The second
-character is the character to match; if it is unused, put a space there.
-Then come the characters for any desired flags. If no matching
-character or flags are needed, one character is sufficient.
-
- For example, the syntax descriptor for the character @samp{*} in C
-mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
-unused, second character of a comment-starter, first character of a
-comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
-punctuation, matching character slot unused, first character of a
-comment-starter, second character of a comment-ender).
-
-@menu
-* Syntax Class Table:: Table of syntax classes.
-* Syntax Flags:: Additional flags each character can have.
-@end menu
-
-@node Syntax Class Table
-@subsection Table of Syntax Classes
-
- Here is a table of syntax classes, the characters that stand for them,
-their meanings, and examples of their use.
-
-@deffn {Syntax class} @w{whitespace character}
-@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
-separate symbols and words from each other. Typically, whitespace
-characters have no other syntactic significance, and multiple whitespace
-characters are syntactically equivalent to a single one. Space, tab,
-newline and formfeed are classified as whitespace in almost all major
-modes.
-@end deffn
-
-@deffn {Syntax class} @w{word constituent}
-@dfn{Word constituents} (designated by @samp{w}) are parts of words in
-human languages, and are typically used in variable and command names
-in programs. All upper- and lower-case letters, and the digits, are
-typically word constituents.
-@end deffn
-
-@deffn {Syntax class} @w{symbol constituent}
-@dfn{Symbol constituents} (designated by @samp{_}) are the extra
-characters that are used in variable and command names along with word
-constituents. For example, the symbol constituents class is used in
-Lisp mode to indicate that certain characters may be part of symbol
-names even though they are not part of English words. These characters
-are @samp{$&*+-_<>}. In standard C, the only non-word-constituent
-character that is valid in symbols is underscore (@samp{_}).
-@end deffn
-
-@deffn {Syntax class} @w{punctuation character}
-@dfn{Punctuation characters} (designated by @samp{.}) are those
-characters that are used as punctuation in English, or are used in some
-way in a programming language to separate symbols from one another.
-Some programming language modes, such as Emacs Lisp mode, have no
-characters in this class since the few characters that are not symbol or
-word constituents all have other uses. Other programming language modes,
-such as C mode, use punctuation syntax for operators.
-@end deffn
-
-@deffn {Syntax class} @w{open parenthesis character}
-@deffnx {Syntax class} @w{close parenthesis character}
-@cindex parenthesis syntax
-Open and close @dfn{parenthesis characters} are characters used in
-dissimilar pairs to surround sentences or expressions. Such a grouping
-is begun with an open parenthesis character and terminated with a close.
-Each open parenthesis character matches a particular close parenthesis
-character, and vice versa. Normally, Emacs indicates momentarily the
-matching open parenthesis when you insert a close parenthesis.
-@xref{Blinking}.
-
-The class of open parentheses is designated by @samp{(}, and that of
-close parentheses by @samp{)}.
-
-In English text, and in C code, the parenthesis pairs are @samp{()},
-@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and
-vectors (@samp{()} and @samp{[]}) are classified as parenthesis
-characters.
-@end deffn
-
-@deffn {Syntax class} @w{string quote}
-@dfn{String quote characters} (designated by @samp{"}) are used in
-many languages, including Lisp and C, to delimit string constants. The
-same string quote character appears at the beginning and the end of a
-string. Such quoted strings do not nest.
-
-The parsing facilities of Emacs consider a string as a single token.
-The usual syntactic meanings of the characters in the string are
-suppressed.
-
-The Lisp modes have two string quote characters: double-quote (@samp{"})
-and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it
-is used in Common Lisp. C also has two string quote characters:
-double-quote for strings, and single-quote (@samp{'}) for character
-constants.
-
-English text has no string quote characters because English is not a
-programming language. Although quotation marks are used in English,
-we do not want them to turn off the usual syntactic properties of
-other characters in the quotation.
-@end deffn
-
-@deffn {Syntax class} @w{escape-syntax character}
-An @dfn{escape character} (designated by @samp{\}) starts an escape
-sequence such as is used in C string and character constants. The
-character @samp{\} belongs to this class in both C and Lisp. (In C, it
-is used thus only inside strings, but it turns out to cause no trouble
-to treat it this way throughout C code.)
-
-Characters in this class count as part of words if
-@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
-@end deffn
-
-@deffn {Syntax class} @w{character quote}
-A @dfn{character quote character} (designated by @samp{/}) quotes the
-following character so that it loses its normal syntactic meaning. This
-differs from an escape character in that only the character immediately
-following is ever affected.
-
-Characters in this class count as part of words if
-@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
-
-This class is used for backslash in @TeX{} mode.
-@end deffn
-
-@deffn {Syntax class} @w{paired delimiter}
-@dfn{Paired delimiter characters} (designated by @samp{$}) are like
-string quote characters except that the syntactic properties of the
-characters between the delimiters are not suppressed. Only @TeX{} mode
-uses a paired delimiter presently---the @samp{$} that both enters and
-leaves math mode.
-@end deffn
-
-@deffn {Syntax class} @w{expression prefix}
-An @dfn{expression prefix operator} (designated by @samp{'}) is used for
-syntactic operators that are considered as part of an expression if they
-appear next to one. In Lisp modes, these characters include the
-apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
-macros), and @samp{#} (used in the read syntax for certain data types).
-@end deffn
-
-@deffn {Syntax class} @w{comment starter}
-@deffnx {Syntax class} @w{comment ender}
-@cindex comment syntax
-The @dfn{comment starter} and @dfn{comment ender} characters are used in
-various languages to delimit comments. These classes are designated
-by @samp{<} and @samp{>}, respectively.
-
-English text has no comment characters. In Lisp, the semicolon
-(@samp{;}) starts a comment and a newline or formfeed ends one.
-@end deffn
-
-@deffn {Syntax class} @w{inherit standard syntax}
-This syntax class does not specify a particular syntax. It says to look
-in the standard syntax table to find the syntax of this character. The
-designator for this syntax class is @samp{@@}.
-@end deffn
-
-@deffn {Syntax class} @w{generic comment delimiter}
-A @dfn{generic comment delimiter} (designated by @samp{!}) starts
-or ends a special kind of comment. @emph{Any} generic comment delimiter
-matches @emph{any} generic comment delimiter, but they cannot match
-a comment starter or comment ender; generic comment delimiters can only
-match each other.
-
-This syntax class is primarily meant for use with the
-@code{syntax-table} text property (@pxref{Syntax Properties}). You can
-mark any range of characters as forming a comment, by giving the first
-and last characters of the range @code{syntax-table} properties
-identifying them as generic comment delimiters.
-@end deffn
-
-@deffn {Syntax class} @w{generic string delimiter}
-A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends
-a string. This class differs from the string quote class in that @emph{any}
-generic string delimiter can match any other generic string delimiter; but
-they do not match ordinary string quote characters.
-
-This syntax class is primarily meant for use with the
-@code{syntax-table} text property (@pxref{Syntax Properties}). You can
-mark any range of characters as forming a string constant, by giving the
-first and last characters of the range @code{syntax-table} properties
-identifying them as generic string delimiters.
-@end deffn
-
-@node Syntax Flags
-@subsection Syntax Flags
-@cindex syntax flags
-
- In addition to the classes, entries for characters in a syntax table
-can specify flags. There are seven possible flags, represented by the
-characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n},
-and @samp{p}.
-
- All the flags except @samp{n} and @samp{p} are used to describe
-multi-character comment delimiters. The digit flags indicate that a
-character can @emph{also} be part of a comment sequence, in addition to
-the syntactic properties associated with its character class. The flags
-are independent of the class and each other for the sake of characters
-such as @samp{*} in C mode, which is a punctuation character, @emph{and}
-the second character of a start-of-comment sequence (@samp{/*}),
-@emph{and} the first character of an end-of-comment sequence
-(@samp{*/}).
-
- Here is a table of the possible flags for a character @var{c},
-and what they mean:
-
-@itemize @bullet
-@item
-@samp{1} means @var{c} is the start of a two-character comment-start
-sequence.
-
-@item
-@samp{2} means @var{c} is the second character of such a sequence.
-
-@item
-@samp{3} means @var{c} is the start of a two-character comment-end
-sequence.
-
-@item
-@samp{4} means @var{c} is the second character of such a sequence.
-
-@item
-@c Emacs 19 feature
-@samp{b} means that @var{c} as a comment delimiter belongs to the
-alternative ``b'' comment style.
-
-Emacs supports two comment styles simultaneously in any one syntax
-table. This is for the sake of C++. Each style of comment syntax has
-its own comment-start sequence and its own comment-end sequence. Each
-comment must stick to one style or the other; thus, if it starts with
-the comment-start sequence of style ``b,'' it must also end with the
-comment-end sequence of style ``b.''
-
-The two comment-start sequences must begin with the same character; only
-the second character may differ. Mark the second character of the
-``b''-style comment-start sequence with the @samp{b} flag.
-
-A comment-end sequence (one or two characters) applies to the ``b''
-style if its first character has the @samp{b} flag set; otherwise, it
-applies to the ``a'' style.
-
-The appropriate comment syntax settings for C++ are as follows:
-
-@table @asis
-@item @samp{/}
-@samp{124b}
-@item @samp{*}
-@samp{23}
-@item newline
-@samp{>b}
-@end table
-
-This defines four comment-delimiting sequences:
-
-@table @asis
-@item @samp{/*}
-This is a comment-start sequence for ``a'' style because the
-second character, @samp{*}, does not have the @samp{b} flag.
-
-@item @samp{//}
-This is a comment-start sequence for ``b'' style because the second
-character, @samp{/}, does have the @samp{b} flag.
-
-@item @samp{*/}
-This is a comment-end sequence for ``a'' style because the first
-character, @samp{*}, does not have the @samp{b} flag.
-
-@item newline
-This is a comment-end sequence for ``b'' style, because the newline
-character has the @samp{b} flag.
-@end table
-
-@item
-@samp{n} on a comment delimiter character specifies
-that this kind of comment can be nested. For a two-character
-comment delimiter, @samp{n} on either character makes it
-nestable.
-
-@item
-@c Emacs 19 feature
-@samp{p} identifies an additional ``prefix character'' for Lisp syntax.
-These characters are treated as whitespace when they appear between
-expressions. When they appear within an expression, they are handled
-according to their usual syntax classes.
-
-The function @code{backward-prefix-chars} moves back over these
-characters, as well as over characters whose primary syntax class is
-prefix (@samp{'}). @xref{Motion and Syntax}.
-@end itemize
-
-@node Syntax Table Functions
-@section Syntax Table Functions
-
- In this section we describe functions for creating, accessing and
-altering syntax tables.
-
-@defun make-syntax-table &optional table
-This function creates a new syntax table, with all values initialized
-to @code{nil}. If @var{table} is non-@code{nil}, it becomes the
-parent of the new syntax table, otherwise the standard syntax table is
-the parent. Like all char-tables, a syntax table inherits from its
-parent. Thus the original syntax of all characters in the returned
-syntax table is determined by the parent. @xref{Char-Tables}.
-
-Most major mode syntax tables are created in this way.
-@end defun
-
-@defun copy-syntax-table &optional table
-This function constructs a copy of @var{table} and returns it. If
-@var{table} is not supplied (or is @code{nil}), it returns a copy of the
-standard syntax table. Otherwise, an error is signaled if @var{table} is
-not a syntax table.
-@end defun
-
-@deffn Command modify-syntax-entry char syntax-descriptor &optional table
-This function sets the syntax entry for @var{char} according to
-@var{syntax-descriptor}. The syntax is changed only for @var{table},
-which defaults to the current buffer's syntax table, and not in any
-other syntax table. The argument @var{syntax-descriptor} specifies the
-desired syntax; this is a string beginning with a class designator
-character, and optionally containing a matching character and flags as
-well. @xref{Syntax Descriptors}.
-
-This function always returns @code{nil}. The old syntax information in
-the table for this character is discarded.
-
-An error is signaled if the first character of the syntax descriptor is not
-one of the seventeen syntax class designator characters. An error is also
-signaled if @var{char} is not a character.
-
-@example
-@group
-@exdent @r{Examples:}
-
-;; @r{Put the space character in class whitespace.}
-(modify-syntax-entry ?\s " ")
- @result{} nil
-@end group
-
-@group
-;; @r{Make @samp{$} an open parenthesis character,}
-;; @r{with @samp{^} as its matching close.}
-(modify-syntax-entry ?$ "(^")
- @result{} nil
-@end group
-
-@group
-;; @r{Make @samp{^} a close parenthesis character,}
-;; @r{with @samp{$} as its matching open.}
-(modify-syntax-entry ?^ ")$")
- @result{} nil
-@end group
-
-@group
-;; @r{Make @samp{/} a punctuation character,}
-;; @r{the first character of a start-comment sequence,}
-;; @r{and the second character of an end-comment sequence.}
-;; @r{This is used in C mode.}
-(modify-syntax-entry ?/ ". 14")
- @result{} nil
-@end group
-@end example
-@end deffn
-
-@defun char-syntax character
-This function returns the syntax class of @var{character}, represented
-by its mnemonic designator character. This returns @emph{only} the
-class, not any matching parenthesis or flags.
-
-An error is signaled if @var{char} is not a character.
-
-The following examples apply to C mode. The first example shows that
-the syntax class of space is whitespace (represented by a space). The
-second example shows that the syntax of @samp{/} is punctuation. This
-does not show the fact that it is also part of comment-start and -end
-sequences. The third example shows that open parenthesis is in the class
-of open parentheses. This does not show the fact that it has a matching
-character, @samp{)}.
-
-@example
-@group
-(string (char-syntax ?\s))
- @result{} " "
-@end group
-
-@group
-(string (char-syntax ?/))
- @result{} "."
-@end group
-
-@group
-(string (char-syntax ?\())
- @result{} "("
-@end group
-@end example
-
-We use @code{string} to make it easier to see the character returned by
-@code{char-syntax}.
-@end defun
-
-@defun set-syntax-table table
-This function makes @var{table} the syntax table for the current buffer.
-It returns @var{table}.
-@end defun
-
-@defun syntax-table
-This function returns the current syntax table, which is the table for
-the current buffer.
-@end defun
-
-@defmac with-syntax-table @var{table} @var{body}@dots{}
-This macro executes @var{body} using @var{table} as the current syntax
-table. It returns the value of the last form in @var{body}, after
-restoring the old current syntax table.
-
-Since each buffer has its own current syntax table, we should make that
-more precise: @code{with-syntax-table} temporarily alters the current
-syntax table of whichever buffer is current at the time the macro
-execution starts. Other buffers are not affected.
-@end defmac
-
-@node Syntax Properties
-@section Syntax Properties
-@kindex syntax-table @r{(text property)}
-
-When the syntax table is not flexible enough to specify the syntax of
-a language, you can use @code{syntax-table} text properties to
-override the syntax table for specific character occurrences in the
-buffer. @xref{Text Properties}. You can use Font Lock mode to set
-@code{syntax-table} text properties. @xref{Setting Syntax
-Properties}.
-
-The valid values of @code{syntax-table} text property are:
-
-@table @asis
-@item @var{syntax-table}
-If the property value is a syntax table, that table is used instead of
-the current buffer's syntax table to determine the syntax for this
-occurrence of the character.
-
-@item @code{(@var{syntax-code} . @var{matching-char})}
-A cons cell of this format specifies the syntax for this
-occurrence of the character. (@pxref{Syntax Table Internals})
-
-@item @code{nil}
-If the property is @code{nil}, the character's syntax is determined from
-the current syntax table in the usual way.
-@end table
-
-@defvar parse-sexp-lookup-properties
-If this is non-@code{nil}, the syntax scanning functions pay attention
-to syntax text properties. Otherwise they use only the current syntax
-table.
-@end defvar
-
-@node Motion and Syntax
-@section Motion and Syntax
-
- This section describes functions for moving across characters that
-have certain syntax classes.
-
-@defun skip-syntax-forward syntaxes &optional limit
-This function moves point forward across characters having syntax
-classes mentioned in @var{syntaxes} (a string of syntax class
-characters). It stops when it encounters the end of the buffer, or
-position @var{limit} (if specified), or a character it is not supposed
-to skip.
-
-If @var{syntaxes} starts with @samp{^}, then the function skips
-characters whose syntax is @emph{not} in @var{syntaxes}.
-
-The return value is the distance traveled, which is a nonnegative
-integer.
-@end defun
-
-@defun skip-syntax-backward syntaxes &optional limit
-This function moves point backward across characters whose syntax
-classes are mentioned in @var{syntaxes}. It stops when it encounters
-the beginning of the buffer, or position @var{limit} (if specified), or
-a character it is not supposed to skip.
-
-If @var{syntaxes} starts with @samp{^}, then the function skips
-characters whose syntax is @emph{not} in @var{syntaxes}.
-
-The return value indicates the distance traveled. It is an integer that
-is zero or less.
-@end defun
-
-@defun backward-prefix-chars
-This function moves point backward over any number of characters with
-expression prefix syntax. This includes both characters in the
-expression prefix syntax class, and characters with the @samp{p} flag.
-@end defun
-
-@node Parsing Expressions
-@section Parsing Expressions
-
- This section describes functions for parsing and scanning balanced
-expressions, also known as @dfn{sexps}. Basically, a sexp is either a
-balanced parenthetical grouping, a string, or a symbol name (a
-sequence of characters whose syntax is either word constituent or
-symbol constituent). However, characters whose syntax is expression
-prefix are treated as part of the sexp if they appear next to it.
-
- The syntax table controls the interpretation of characters, so these
-functions can be used for Lisp expressions when in Lisp mode and for C
-expressions when in C mode. @xref{List Motion}, for convenient
-higher-level functions for moving over balanced expressions.
-
- A character's syntax controls how it changes the state of the
-parser, rather than describing the state itself. For example, a
-string delimiter character toggles the parser state between
-``in-string'' and ``in-code,'' but the syntax of characters does not
-directly say whether they are inside a string. For example (note that
-15 is the syntax code for generic string delimiters),
-
-@example
-(put-text-property 1 9 'syntax-table '(15 . nil))
-@end example
-
-@noindent
-does not tell Emacs that the first eight chars of the current buffer
-are a string, but rather that they are all string delimiters. As a
-result, Emacs treats them as four consecutive empty string constants.
-
-@menu
-* 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.
-@end menu
-
-@node Motion via Parsing
-@subsection Motion Commands Based on Parsing
-
- This section describes simple point-motion functions that operate
-based on parsing expressions.
-
-@defun scan-lists from count depth
-This function scans forward @var{count} balanced parenthetical groupings
-from position @var{from}. It returns the position where the scan stops.
-If @var{count} is negative, the scan moves backwards.
-
-If @var{depth} is nonzero, parenthesis depth counting begins from that
-value. The only candidates for stopping are places where the depth in
-parentheses becomes zero; @code{scan-lists} counts @var{count} such
-places and then stops. Thus, a positive value for @var{depth} means go
-out @var{depth} levels of parenthesis.
-
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
-non-@code{nil}.
-
-If the scan reaches the beginning or end of the buffer (or its
-accessible portion), and the depth is not zero, an error is signaled.
-If the depth is zero but the count is not used up, @code{nil} is
-returned.
-@end defun
-
-@defun scan-sexps from count
-This function scans forward @var{count} sexps from position @var{from}.
-It returns the position where the scan stops. If @var{count} is
-negative, the scan moves backwards.
-
-Scanning ignores comments if @code{parse-sexp-ignore-comments} is
-non-@code{nil}.
-
-If the scan reaches the beginning or end of (the accessible part of) the
-buffer while in the middle of a parenthetical grouping, an error is
-signaled. If it reaches the beginning or end between groupings but
-before count is used up, @code{nil} is returned.
-@end defun
-
-@defun forward-comment count
-This function moves point forward across @var{count} complete comments
- (that is, including the starting delimiter and the terminating
-delimiter if any), plus any whitespace encountered on the way. It
-moves backward if @var{count} is negative. If it encounters anything
-other than a comment or whitespace, it stops, leaving point at the
-place where it stopped. This includes (for instance) finding the end
-of a comment when moving forward and expecting the beginning of one.
-The function also stops immediately after moving over the specified
-number of complete comments. If @var{count} comments are found as
-expected, with nothing except whitespace between them, it returns
-@code{t}; otherwise it returns @code{nil}.
-
-This function cannot tell whether the ``comments'' it traverses are
-embedded within a string. If they look like comments, it treats them
-as comments.
-@end defun
-
-To move forward over all comments and whitespace following point, use
-@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good
-argument to use, because the number of comments in the buffer cannot
-exceed that many.
-
-@node Position Parse
-@subsection Finding the Parse State for a Position
-
- For syntactic analysis, such as in indentation, often the useful
-thing is to compute the syntactic state corresponding to a given buffer
-position. This function does that conveniently.
-
-@defun syntax-ppss &optional pos
-This function returns the parser state (see next section) that the
-parser would reach at position @var{pos} starting from the beginning
-of the buffer. This is equivalent to @code{(parse-partial-sexp
-(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache
-to speed up the computation. Due to this optimization, the 2nd value
-(previous complete subexpression) and 6th value (minimum parenthesis
-depth) of the returned parser state are not meaningful.
-@end defun
-
- @code{syntax-ppss} automatically hooks itself to
-@code{before-change-functions} to keep its cache consistent. But
-updating can fail if @code{syntax-ppss} is called while
-@code{before-change-functions} is temporarily let-bound, or if the
-buffer is modified without obeying the hook, such as when using
-@code{inhibit-modification-hooks}. For this reason, it is sometimes
-necessary to flush the cache manually.
-
-@defun syntax-ppss-flush-cache beg
-This function flushes the cache used by @code{syntax-ppss}, starting at
-position @var{beg}.
-@end defun
-
- Major modes can make @code{syntax-ppss} run faster by specifying
-where it needs to start parsing.
-
-@defvar syntax-begin-function
-If this is non-@code{nil}, it should be a function that moves to an
-earlier buffer position where the parser state is equivalent to
-@code{nil}---in other words, a position outside of any comment,
-string, or parenthesis. @code{syntax-ppss} uses it to further
-optimize its computations, when the cache gives no help.
-@end defvar
-
-@node Parser State
-@subsection Parser State
-@cindex parser state
-
- A @dfn{parser state} is a list of ten elements describing the final
-state of parsing text syntactically as part of an expression. The
-parsing functions in the following sections return a parser state as
-the value, and in some cases accept one as an argument also, so that
-you can resume parsing after it stops. Here are the meanings of the
-elements of the parser state:
-
-@enumerate 0
-@item
-The depth in parentheses, counting from 0. @strong{Warning:} this can
-be negative if there are more close parens than open parens between
-the start of the defun and point.
-
-@item
-@cindex innermost containing parentheses
-The character position of the start of the innermost parenthetical
-grouping containing the stopping point; @code{nil} if none.
-
-@item
-@cindex previous complete subexpression
-The character position of the start of the last complete subexpression
-terminated; @code{nil} if none.
-
-@item
-@cindex inside string
-Non-@code{nil} if inside a string. More precisely, this is the
-character that will terminate the string, or @code{t} if a generic
-string delimiter character should terminate it.
-
-@item
-@cindex inside comment
-@code{t} if inside a comment (of either style),
-or the comment nesting level if inside a kind of comment
-that can be nested.
-
-@item
-@cindex quote character
-@code{t} if point is just after a quote character.
-
-@item
-The minimum parenthesis depth encountered during this scan.
-
-@item
-What kind of comment is active: @code{nil} for a comment of style
-``a'' or when not inside a comment, @code{t} for a comment of style
-``b,'' and @code{syntax-table} for a comment that should be ended by a
-generic comment delimiter character.
-
-@item
-The string or comment start position. While inside a comment, this is
-the position where the comment began; while inside a string, this is the
-position where the string began. When outside of strings and comments,
-this element is @code{nil}.
-
-@item
-Internal data for continuing the parsing. The meaning of this
-data is subject to change; it is used if you pass this list
-as the @var{state} argument to another call.
-@end enumerate
-
- Elements 1, 2, and 6 are ignored in a state which you pass as an
-argument to continue parsing, and elements 8 and 9 are used only in
-trivial cases. Those elements serve primarily to convey information
-to the Lisp program which does the parsing.
-
- One additional piece of useful information is available from a
-parser state using this function:
-
-@defun syntax-ppss-toplevel-pos state
-This function extracts, from parser state @var{state}, the last
-position scanned in the parse which was at top level in grammatical
-structure. ``At top level'' means outside of any parentheses,
-comments, or strings.
-
-The value is @code{nil} if @var{state} represents a parse which has
-arrived at a top level position.
-@end defun
-
- We have provided this access function rather than document how the
-data is represented in the state, because we plan to change the
-representation in the future.
-
-@node Low-Level Parsing
-@subsection Low-Level Parsing
-
- The most basic way to use the expression parser is to tell it
-to start at a given position with a certain state, and parse up to
-a specified end position.
-
-@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
-This function parses a sexp in the current buffer starting at
-@var{start}, not scanning past @var{limit}. It stops at position
-@var{limit} or when certain criteria described below are met, and sets
-point to the location where parsing stops. It returns a parser state
-describing the status of the parse at the point where it stops.
-
-@cindex parenthesis depth
-If the third argument @var{target-depth} is non-@code{nil}, parsing
-stops if the depth in parentheses becomes equal to @var{target-depth}.
-The depth starts at 0, or at whatever is given in @var{state}.
-
-If the fourth argument @var{stop-before} is non-@code{nil}, parsing
-stops when it comes to any character that starts a sexp. If
-@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
-start of a comment. If @var{stop-comment} is the symbol
-@code{syntax-table}, parsing stops after the start of a comment or a
-string, or the end of a comment or a string, whichever comes first.
-
-If @var{state} is @code{nil}, @var{start} is assumed to be at the top
-level of parenthesis structure, such as the beginning of a function
-definition. Alternatively, you might wish to resume parsing in the
-middle of the structure. To do this, you must provide a @var{state}
-argument that describes the initial status of parsing. The value
-returned by a previous call to @code{parse-partial-sexp} will do
-nicely.
-@end defun
-
-@node Control Parsing
-@subsection Parameters to Control Parsing
-
-@defvar multibyte-syntax-as-symbol
-If this variable is non-@code{nil}, @code{scan-sexps} treats all
-non-@acronym{ASCII} characters as symbol constituents regardless
-of what the syntax table says about them. (However, text properties
-can still override the syntax.)
-@end defvar
-
-@defopt parse-sexp-ignore-comments
-@cindex skipping comments
-If the value is non-@code{nil}, then comments are treated as
-whitespace by the functions in this section and by @code{forward-sexp},
-@code{scan-lists} and @code{scan-sexps}.
-@end defopt
-
-@vindex parse-sexp-lookup-properties
-The behavior of @code{parse-partial-sexp} is also affected by
-@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
-
-You can use @code{forward-comment} to move forward or backward over
-one comment or several comments.
-
-@node Standard Syntax Tables
-@section Some Standard Syntax Tables
-
- Most of the major modes in Emacs have their own syntax tables. Here
-are several of them:
-
-@defun standard-syntax-table
-This function returns the standard syntax table, which is the syntax
-table used in Fundamental mode.
-@end defun
-
-@defvar text-mode-syntax-table
-The value of this variable is the syntax table used in Text mode.
-@end defvar
-
-@defvar c-mode-syntax-table
-The value of this variable is the syntax table for C-mode buffers.
-@end defvar
-
-@defvar emacs-lisp-mode-syntax-table
-The value of this variable is the syntax table used in Emacs Lisp mode
-by editing commands. (It has no effect on the Lisp @code{read}
-function.)
-@end defvar
-
-@node Syntax Table Internals
-@section Syntax Table Internals
-@cindex syntax table internals
-
- Lisp programs don't usually work with the elements directly; the
-Lisp-level syntax table functions usually work with syntax descriptors
-(@pxref{Syntax Descriptors}). Nonetheless, here we document the
-internal format. This format is used mostly when manipulating
-syntax properties.
-
- Each element of a syntax table is a cons cell of the form
-@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car},
-@var{syntax-code}, is an integer that encodes the syntax class, and any
-flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if
-a character to match was specified.
-
- This table gives the value of @var{syntax-code} which corresponds
-to each syntactic type.
-
-@multitable @columnfractions .05 .3 .3 .31
-@item
-@tab
-@i{Integer} @i{Class}
-@tab
-@i{Integer} @i{Class}
-@tab
-@i{Integer} @i{Class}
-@item
-@tab
-0 @ @ whitespace
-@tab
-5 @ @ close parenthesis
-@tab
-10 @ @ character quote
-@item
-@tab
-1 @ @ punctuation
-@tab
-6 @ @ expression prefix
-@tab
-11 @ @ comment-start
-@item
-@tab
-2 @ @ word
-@tab
-7 @ @ string quote
-@tab
-12 @ @ comment-end
-@item
-@tab
-3 @ @ symbol
-@tab
-8 @ @ paired delimiter
-@tab
-13 @ @ inherit
-@item
-@tab
-4 @ @ open parenthesis
-@tab
-9 @ @ escape
-@tab
-14 @ @ generic comment
-@item
-@tab
-15 @ generic string
-@end multitable
-
- For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
-(41 is the character code for @samp{)}.)
-
- The flags are encoded in higher order bits, starting 16 bits from the
-least significant bit. This table gives the power of two which
-corresponds to each syntax flag.
-
-@multitable @columnfractions .05 .3 .3 .3
-@item
-@tab
-@i{Prefix} @i{Flag}
-@tab
-@i{Prefix} @i{Flag}
-@tab
-@i{Prefix} @i{Flag}
-@item
-@tab
-@samp{1} @ @ @code{(lsh 1 16)}
-@tab
-@samp{4} @ @ @code{(lsh 1 19)}
-@tab
-@samp{b} @ @ @code{(lsh 1 21)}
-@item
-@tab
-@samp{2} @ @ @code{(lsh 1 17)}
-@tab
-@samp{p} @ @ @code{(lsh 1 20)}
-@tab
-@samp{n} @ @ @code{(lsh 1 22)}
-@item
-@tab
-@samp{3} @ @ @code{(lsh 1 18)}
-@end multitable
-
-@defun string-to-syntax @var{desc}
-This function returns the internal form corresponding to the syntax
-descriptor @var{desc}, a cons cell @code{(@var{syntax-code}
-. @var{matching-char})}.
-@end defun
-
-@defun syntax-after pos
-This function returns the syntax code of the character in the buffer
-after position @var{pos}, taking account of syntax properties as well
-as the syntax table. If @var{pos} is outside the buffer's accessible
-portion (@pxref{Narrowing, accessible portion}), this function returns
-@code{nil}.
-@end defun
-
-@defun syntax-class syntax
-This function returns the syntax class of the syntax code
-@var{syntax}. (It masks off the high 16 bits that hold the flags
-encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it
-returns @code{nil}; this is so evaluating the expression
-
-@example
-(syntax-class (syntax-after pos))
-@end example
-
-@noindent
-where @code{pos} is outside the buffer's accessible portion, will
-yield @code{nil} without throwing errors or producing wrong syntax
-class codes.
-@end defun
-
-@node Categories
-@section Categories
-@cindex categories of characters
-@cindex character categories
-
- @dfn{Categories} provide an alternate way of classifying characters
-syntactically. You can define several categories as needed, then
-independently assign each character to one or more categories. Unlike
-syntax classes, categories are not mutually exclusive; it is normal for
-one character to belong to several categories.
-
-@cindex category table
- Each buffer has a @dfn{category table} which records which categories
-are defined and also which characters belong to each category. Each
-category table defines its own categories, but normally these are
-initialized by copying from the standard categories table, so that the
-standard categories are available in all modes.
-
- Each category has a name, which is an @acronym{ASCII} printing character in
-the range @w{@samp{ }} to @samp{~}. You specify the name of a category
-when you define it with @code{define-category}.
-
- The category table is actually a char-table (@pxref{Char-Tables}).
-The element of the category table at index @var{c} is a @dfn{category
-set}---a bool-vector---that indicates which categories character @var{c}
-belongs to. In this category set, if the element at index @var{cat} is
-@code{t}, that means category @var{cat} is a member of the set, and that
-character @var{c} belongs to category @var{cat}.
-
-For the next three functions, the optional argument @var{table}
-defaults to the current buffer's category table.
-
-@defun define-category char docstring &optional table
-This function defines a new category, with name @var{char} and
-documentation @var{docstring}, for the category table @var{table}.
-@end defun
-
-@defun category-docstring category &optional table
-This function returns the documentation string of category @var{category}
-in category table @var{table}.
-
-@example
-(category-docstring ?a)
- @result{} "ASCII"
-(category-docstring ?l)
- @result{} "Latin"
-@end example
-@end defun
-
-@defun get-unused-category &optional table
-This function returns a category name (a character) which is not
-currently defined in @var{table}. If all possible categories are in use
-in @var{table}, it returns @code{nil}.
-@end defun
-
-@defun category-table
-This function returns the current buffer's category table.
-@end defun
-
-@defun category-table-p object
-This function returns @code{t} if @var{object} is a category table,
-otherwise @code{nil}.
-@end defun
-
-@defun standard-category-table
-This function returns the standard category table.
-@end defun
-
-@defun copy-category-table &optional table
-This function constructs a copy of @var{table} and returns it. If
-@var{table} is not supplied (or is @code{nil}), it returns a copy of the
-standard category table. Otherwise, an error is signaled if @var{table}
-is not a category table.
-@end defun
-
-@defun set-category-table table
-This function makes @var{table} the category table for the current
-buffer. It returns @var{table}.
-@end defun
-
-@defun make-category-table
-This creates and returns an empty category table. In an empty category
-table, no categories have been allocated, and no characters belong to
-any categories.
-@end defun
-
-@defun make-category-set categories
-This function returns a new category set---a bool-vector---whose initial
-contents are the categories listed in the string @var{categories}. The
-elements of @var{categories} should be category names; the new category
-set has @code{t} for each of those categories, and @code{nil} for all
-other categories.
-
-@example
-(make-category-set "al")
- @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
-@end example
-@end defun
-
-@defun char-category-set char
-This function returns the category set for character @var{char} in the
-current buffer's category table. This is the bool-vector which
-records which categories the character @var{char} belongs to. The
-function @code{char-category-set} does not allocate storage, because
-it returns the same bool-vector that exists in the category table.
-
-@example
-(char-category-set ?a)
- @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
-@end example
-@end defun
-
-@defun category-set-mnemonics category-set
-This function converts the category set @var{category-set} into a string
-containing the characters that designate the categories that are members
-of the set.
-
-@example
-(category-set-mnemonics (char-category-set ?a))
- @result{} "al"
-@end example
-@end defun
-
-@defun modify-category-entry character category &optional table reset
-This function modifies the category set of @var{character} in category
-table @var{table} (which defaults to the current buffer's category
-table).
-
-Normally, it modifies the category set by adding @var{category} to it.
-But if @var{reset} is non-@code{nil}, then it deletes @var{category}
-instead.
-@end defun
-
-@deffn Command describe-categories &optional buffer-or-name
-This function describes the category specifications in the current
-category table. It inserts the descriptions in a buffer, and then
-displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it
-describes the category table of that buffer instead.
-@end deffn
-
-@ignore
- arch-tag: 4d914e96-0283-445c-9233-75d33662908c
-@end ignore
+++ /dev/null
-@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-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{\<f\w*\>}. The resulting expression looks like this:
-
-@example
-@group
-(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
- (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.
-@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
+++ /dev/null
-#! /usr/bin/perl
-
-# Copyright (C) 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.
-
-require 5;
-use Getopt::Long;
-
-my $USAGE = <<ENDUSAGE;
-Remove \@tindex lines from files that were already present in previous
-versions.
-
-Usage: $0 [--old=EXT] FILE...
- $0 --help
- $0 --version
-
- --help display this help and exit
- --version print version and exit
- --old=DIR find old files in DIR
-
-The script performs two passes. In the first pass, Texinfo files from
-DIR are scanned for \@tindex lines, and identifiers in them are
-recorded. In a second pass, Texinfo files in the current directory
-are scanned, and \@tindex lines for identifiers that were recorded in
-the first pass are removed. Old file contents are saved in files
-with extension ".orig". A list of modified files and removed \@tindex
-identifiers is printed to stdout at the end.
-ENDUSAGE
-
-sub fatal {
- print STDERR "$0: ", @_, ".\n";
- exit 1;
-}
-
-my $help = 0;
-my $version = 0;
-my $old;
-
-my $rc = GetOptions ('help' => \$help, 'version' => \$version,
- 'old=s' => \$old);
-if ($version) {
- print "0.1\n";
- exit 0;
-} elsif (!$rc || !$old || @ARGV) {
- print $USAGE;
- exit 1;
-} elsif ($help) {
- print $USAGE;
- exit 0;
-}
-
-# Fill the hash %tindex with associations VAR -> COUNT where
-# the keys VAR are identifiers mentioned in @tindex lines in the older
-# files to process and COUNT is the number of times they are seen in
-# the files.
-
-my %tindex;
-my %removed;
-my @old_files = glob "$old/*.texi";
-my @new_files = glob "*.texi";
-fatal ("No Texinfo files found in `$old'") unless @old_files;
-fatal ("No Texinfo files found in current directory") unless @new_files;
-
-print "Scanning old files for \@tindex lines\n";
-foreach $file (@old_files) {
- open (IN, "<$file") or fatal "Cannot open $file: $!";
- while (<IN>) {
- ++$tindex{$1} if /^\s*\@tindex\s+(\S+)/;
- }
- close IN;
-}
-
-# Process current files and remove those @tindex lines which we
-# know were already present in the files scanned above.
-
-print "Removing old \@tindex lines\n";
-foreach $file (@new_files) {
- my $modified = 0;
- my $contents = "";
-
- open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!";
- while (<IN>) {
- if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) {
- ++$removed{$1};
- $modified = 1;
- } else {
- $contents = $contents . $_;
- }
- }
-
- close IN;
-
- if ($modified) {
- print " $file\n";
- system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!";
- open (OUT, ">$file") or fatal "Cannot open $file for writing: $!";
- print OUT $contents;
- close OUT;
- }
-}
-
-# Print a list of identifiers removed.
-
-print "Removed \@tindex commands for:\n";
-my $key;
-foreach $key (keys %removed) {
- print " $key\n";
-}
-
-# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa
+++ /dev/null
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 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/tips
-@node Tips, GNU Emacs Internals, GPL, Top
-@appendix Tips and Conventions
-@cindex tips for writing Lisp
-@cindex standards of coding style
-@cindex coding standards
-
- This chapter describes no additional features of Emacs Lisp. Instead
-it gives advice on making effective use of the features described in the
-previous chapters, and describes conventions Emacs Lisp programmers
-should follow.
-
- You can automatically check some of the conventions described below by
-running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
-It cannot check all of the conventions, and not all the warnings it
-gives necessarily correspond to problems, but it is worth examining them
-all.
-
-@menu
-* 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.
-@end menu
-
-@node Coding Conventions
-@section Emacs Lisp Coding Conventions
-
-@cindex coding conventions in Emacs Lisp
- Here are conventions that you should follow when writing Emacs Lisp
-code intended for widespread use:
-
-@itemize @bullet
-@item
-Simply loading the package should not change Emacs's editing behavior.
-Include a command or commands to enable and disable the feature,
-or to invoke it.
-
-This convention is mandatory for any file that includes custom
-definitions. If fixing such a file to follow this convention requires
-an incompatible change, go ahead and make the incompatible change;
-don't postpone it.
-
-@item
-Since all global variables share the same name space, and all
-functions share another name space, you should choose a short word to
-distinguish your program from other Lisp programs@footnote{The
-benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}. Then take care to begin the names of all global
-variables, constants, and functions in your program with the chosen
-prefix. This helps avoid name conflicts.
-
-Occasionally, for a command name intended for users to use, it is more
-convenient if some words come before the package's name prefix. And
-constructs that define functions, variables, etc., work better if they
-start with @samp{defun} or @samp{defvar}, so put the name prefix later
-on in the name.
-
-This recommendation applies even to names for traditional Lisp
-primitives that are not primitives in Emacs Lisp---such as
-@code{copy-list}. Believe it or not, there is more than one plausible
-way to define @code{copy-list}. Play it safe; append your name prefix
-to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
-instead.
-
-If you write a function that you think ought to be added to Emacs under
-a certain name, such as @code{twiddle-files}, don't call it by that name
-in your program. Call it @code{mylib-twiddle-files} in your program,
-and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
-it to Emacs. If and when we do, we can change the name easily enough.
-
-If one prefix is insufficient, your package can use two or three
-alternative common prefixes, so long as they make sense.
-
-Separate the prefix from the rest of the symbol name with a hyphen,
-@samp{-}. This will be consistent with Emacs itself and with most Emacs
-Lisp programs.
-
-@item
-Put a call to @code{provide} at the end of each separate Lisp file.
-
-@item
-If a file requires certain other Lisp programs to be loaded
-beforehand, then the comments at the beginning of the file should say
-so. Also, use @code{require} to make sure they are loaded.
-
-@item
-If one file @var{foo} uses a macro defined in another file @var{bar},
-@var{foo} should contain this expression before the first use of the
-macro:
-
-@example
-(eval-when-compile (require '@var{bar}))
-@end example
-
-@noindent
-(And the library @var{bar} should contain @code{(provide '@var{bar})},
-to make the @code{require} work.) This will cause @var{bar} to be
-loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
-@var{foo} without the necessary macro loaded, and that would produce
-compiled code that won't work right. @xref{Compiling Macros}.
-
-Using @code{eval-when-compile} avoids loading @var{bar} when
-the compiled version of @var{foo} is @emph{used}.
-
-@item
-Please don't require the @code{cl} package of Common Lisp extensions at
-run time. Use of this package is optional, and it is not part of the
-standard Emacs namespace. If your package loads @code{cl} at run time,
-that could cause name clashes for users who don't use that package.
-
-However, there is no problem with using the @code{cl} package at
-compile time, with @code{(eval-when-compile (require 'cl))}. That's
-sufficient for using the macros in the @code{cl} package, because the
-compiler expands them before generating the byte-code.
-
-@item
-When defining a major mode, please follow the major mode
-conventions. @xref{Major Mode Conventions}.
-
-@item
-When defining a minor mode, please follow the minor mode
-conventions. @xref{Minor Mode Conventions}.
-
-@item
-If the purpose of a function is to tell you whether a certain condition
-is true or false, give the function a name that ends in @samp{p}. If
-the name is one word, add just @samp{p}; if the name is multiple words,
-add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
-
-@item
-If a user option variable records a true-or-false condition, give it a
-name that ends in @samp{-flag}.
-
-@item
-If the purpose of a variable is to store a single function, give it a
-name that ends in @samp{-function}. If the purpose of a variable is
-to store a list of functions (i.e., the variable is a hook), please
-follow the naming conventions for hooks. @xref{Hooks}.
-
-@item
-@cindex unloading packages, preparing for
-If loading the file adds functions to hooks, define a function
-@code{@var{feature}-unload-hook}, where @var{feature} is the name of
-the feature the package provides, and make it undo any such changes.
-Using @code{unload-feature} to unload the file will run this function.
-@xref{Unloading}.
-
-@item
-It is a bad idea to define aliases for the Emacs primitives. Normally
-you should use the standard names instead. The case where an alias
-may be useful is where it facilitates backwards compatibility or
-portability.
-
-@item
-If a package needs to define an alias or a new function for
-compatibility with some other version of Emacs, name it with the package
-prefix, not with the raw name with which it occurs in the other version.
-Here is an example from Gnus, which provides many examples of such
-compatibility issues.
-
-@example
-(defalias 'gnus-point-at-bol
- (if (fboundp 'point-at-bol)
- 'point-at-bol
- 'line-beginning-position))
-@end example
-
-@item
-Redefining (or advising) an Emacs primitive is a bad idea. It may do
-the right thing for a particular program, but there is no telling what
-other programs might break as a result. In any case, it is a problem
-for debugging, because the advised function doesn't do what its source
-code says it does. If the programmer investigating the problem is
-unaware that there is advice on the function, the experience can be
-very frustrating.
-
-We hope to remove all the places in Emacs that advise primitives.
-In the mean time, please don't add any more.
-
-@item
-It is likewise a bad idea for one Lisp package to advise a function
-in another Lisp package.
-
-@item
-Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
-Loading}) in libraries and packages. This feature is meant for
-personal customizations; using it in a Lisp program is unclean,
-because it modifies the behavior of another Lisp file in a way that's
-not visible in that file. This is an obstacle for debugging, much
-like advising a function in the other package.
-
-@item
-If a file does replace any of the functions or library programs of
-standard Emacs, prominent comments at the beginning of the file should
-say which functions are replaced, and how the behavior of the
-replacements differs from that of the originals.
-
-@item
-Constructs that define a function or variable should be macros,
-not functions, and their names should start with @samp{def}.
-
-@item
-A macro that defines a function or variable should have a name that
-starts with @samp{define-}. The macro should receive the name to be
-defined as the first argument. That will help various tools find the
-definition automatically. Avoid constructing the names in the macro
-itself, since that would confuse these tools.
-
-@item
-Please keep the names of your Emacs Lisp source files to 13 characters
-or less. This way, if the files are compiled, the compiled files' names
-will be 14 characters or less, which is short enough to fit on all kinds
-of Unix systems.
-
-@item
-In some other systems there is a convention of choosing variable names
-that begin and end with @samp{*}. We don't use that convention in Emacs
-Lisp, so please don't use it in your programs. (Emacs uses such names
-only for special-purpose buffers.) The users will find Emacs more
-coherent if all libraries use the same conventions.
-
-@item
-If your program contains non-ASCII characters in string or character
-constants, you should make sure Emacs always decodes these characters
-the same way, regardless of the user's settings. There are two ways
-to do that:
-
-@itemize -
-@item
-Use coding system @code{emacs-mule}, and specify that for
-@code{coding} in the @samp{-*-} line or the local variables list.
-
-@example
-;; XXX.el -*- coding: emacs-mule; -*-
-@end example
-
-@item
-Use one of the coding systems based on ISO 2022 (such as
-iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
-the end for @code{coding}. (The @samp{!} turns off any possible
-character translation.)
-
-@example
-;; XXX.el -*- coding: iso-latin-2!; -*-
-@end example
-@end itemize
-
-@item
-Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
-default indentation parameters.
-
-@item
-Don't make a habit of putting close-parentheses on lines by themselves;
-Lisp programmers find this disconcerting. Once in a while, when there
-is a sequence of many consecutive close-parentheses, it may make sense
-to split the sequence in one or two significant places.
-
-@item
-Please put a copyright notice and copying permission notice on the
-file if you distribute copies. Use a notice like this one:
-
-@smallexample
-;; Copyright (C) @var{year} @var{name}
-
-;; This program 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 of
-;; the License, or (at your option) any later version.
-
-;; This program 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 this program; if not, write to the Free
-;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-;; Boston, MA 02110-1301 USA
-@end smallexample
-
-If you have signed papers to assign the copyright to the Foundation,
-then use @samp{Free Software Foundation, Inc.} as @var{name}.
-Otherwise, use your name. See also @xref{Library Headers}.
-@end itemize
-
-@node Key Binding Conventions
-@section Key Binding Conventions
-@cindex key binding, conventions for
-
-@itemize @bullet
-@item
-@cindex mouse-2
-@cindex references, following
-Special major modes used for read-only text should usually redefine
-@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
-Modes such as Dired, Info, Compilation, and Occur redefine it in this
-way.
-
-In addition, they should mark the text as a kind of ``link'' so that
-@kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}.
-
-@item
-@cindex reserved keys
-@cindex keys, reserved
-Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
-Sequences consisting of @kbd{C-c} and a letter (either upper or lower
-case) are reserved for users; they are the @strong{only} sequences
-reserved for users, so do not block them.
-
-Changing all the Emacs major modes to respect this convention was a
-lot of work; abandoning this convention would make that work go to
-waste, and inconvenience users. Please comply with it.
-
-@item
-Function keys @key{F5} through @key{F9} without modifier keys are
-also reserved for users to define.
-
-@item
-Applications should not bind mouse events based on button 1 with the
-shift key held down. These events include @kbd{S-mouse-1},
-@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
-users.
-
-@item
-Sequences consisting of @kbd{C-c} followed by a control character or a
-digit are reserved for major modes.
-
-@item
-Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
-@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
-
-@item
-Sequences consisting of @kbd{C-c} followed by any other punctuation
-character are allocated for minor modes. Using them in a major mode is
-not absolutely prohibited, but if you do that, the major mode binding
-may be shadowed from time to time by minor modes.
-
-@item
-Do not bind @kbd{C-h} following any prefix character (including
-@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
-as a help character for listing the subcommands of the prefix character.
-
-@item
-Do not bind a key sequence ending in @key{ESC} except following
-another @key{ESC}. (That is, it is OK to bind a sequence ending in
-@kbd{@key{ESC} @key{ESC}}.)
-
-The reason for this rule is that a non-prefix binding for @key{ESC} in
-any context prevents recognition of escape sequences as function keys in
-that context.
-
-@item
-Anything which acts like a temporary mode or state which the user can
-enter and leave should define @kbd{@key{ESC} @key{ESC}} or
-@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
-
-For a state which accepts ordinary Emacs commands, or more generally any
-kind of state in which @key{ESC} followed by a function key or arrow key
-is potentially meaningful, then you must not define @kbd{@key{ESC}
-@key{ESC}}, since that would preclude recognizing an escape sequence
-after @key{ESC}. In these states, you should define @kbd{@key{ESC}
-@key{ESC} @key{ESC}} as the way to escape. Otherwise, define
-@kbd{@key{ESC} @key{ESC}} instead.
-@end itemize
-
-@node Programming Tips
-@section Emacs Programming Tips
-@cindex programming conventions
-
- Following these conventions will make your program fit better
-into Emacs when it runs.
-
-@itemize @bullet
-@item
-Don't use @code{next-line} or @code{previous-line} in programs; nearly
-always, @code{forward-line} is more convenient as well as more
-predictable and robust. @xref{Text Lines}.
-
-@item
-Don't call functions that set the mark, unless setting the mark is one
-of the intended features of your program. The mark is a user-level
-feature, so it is incorrect to change the mark except to supply a value
-for the user's benefit. @xref{The Mark}.
-
-In particular, don't use any of these functions:
-
-@itemize @bullet
-@item
-@code{beginning-of-buffer}, @code{end-of-buffer}
-@item
-@code{replace-string}, @code{replace-regexp}
-@item
-@code{insert-file}, @code{insert-buffer}
-@end itemize
-
-If you just want to move point, or replace a certain string, or insert
-a file or buffer's contents, without any of the other features
-intended for interactive users, you can replace these functions with
-one or two lines of simple Lisp code.
-
-@item
-Use lists rather than vectors, except when there is a particular reason
-to use a vector. Lisp has more facilities for manipulating lists than
-for vectors, and working with lists is usually more convenient.
-
-Vectors are advantageous for tables that are substantial in size and are
-accessed in random order (not searched front to back), provided there is
-no need to insert or delete elements (only lists allow that).
-
-@item
-The recommended way to show a message in the echo area is with
-the @code{message} function, not @code{princ}. @xref{The Echo Area}.
-
-@item
-When you encounter an error condition, call the function @code{error}
-(or @code{signal}). The function @code{error} does not return.
-@xref{Signaling Errors}.
-
-Do not use @code{message}, @code{throw}, @code{sleep-for},
-or @code{beep} to report errors.
-
-@item
-An error message should start with a capital letter but should not end
-with a period.
-
-@item
-A question asked in the minibuffer with @code{y-or-n-p} or
-@code{yes-or-no-p} should start with a capital letter and end with
-@samp{? }.
-
-@item
-When you mention a default value in a minibuffer prompt,
-put it and the word @samp{default} inside parentheses.
-It should look like this:
-
-@example
-Enter the answer (default 42):
-@end example
-
-@item
-In @code{interactive}, if you use a Lisp expression to produce a list
-of arguments, don't try to provide the ``correct'' default values for
-region or position arguments. Instead, provide @code{nil} for those
-arguments if they were not specified, and have the function body
-compute the default value when the argument is @code{nil}. For
-instance, write this:
-
-@example
-(defun foo (pos)
- (interactive
- (list (if @var{specified} @var{specified-pos})))
- (unless pos (setq pos @var{default-pos}))
- ...)
-@end example
-
-@noindent
-rather than this:
-
-@example
-(defun foo (pos)
- (interactive
- (list (if @var{specified} @var{specified-pos}
- @var{default-pos})))
- ...)
-@end example
-
-@noindent
-This is so that repetition of the command will recompute
-these defaults based on the current circumstances.
-
-You do not need to take such precautions when you use interactive
-specs @samp{d}, @samp{m} and @samp{r}, because they make special
-arrangements to recompute the argument values on repetition of the
-command.
-
-@item
-Many commands that take a long time to execute display a message that
-says something like @samp{Operating...} when they start, and change it to
-@samp{Operating...done} when they finish. Please keep the style of
-these messages uniform: @emph{no} space around the ellipsis, and
-@emph{no} period after @samp{done}.
-
-@item
-Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
-command does: use a new local keymap that contains one command defined
-to switch back to the old local keymap. Or do what the
-@code{edit-options} command does: switch to another buffer and let the
-user switch back at will. @xref{Recursive Editing}.
-@end itemize
-
-@node Compilation Tips
-@section Tips for Making Compiled Code Fast
-@cindex execution speed
-@cindex speedups
-
- Here are ways of improving the execution speed of byte-compiled
-Lisp programs.
-
-@itemize @bullet
-@item
-@cindex profiling
-@cindex timing programs
-@cindex @file{elp.el}
-Profile your program with the @file{elp} library. See the file
-@file{elp.el} for instructions.
-
-@item
-@cindex @file{benchmark.el}
-@cindex benchmarking
-Check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library. See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
-
-@item
-Use iteration rather than recursion whenever possible.
-Function calls are slow in Emacs Lisp even when a compiled function
-is calling another compiled function.
-
-@item
-Using the primitive list-searching functions @code{memq}, @code{member},
-@code{assq}, or @code{assoc} is even faster than explicit iteration. It
-can be worth rearranging a data structure so that one of these primitive
-search functions can be used.
-
-@item
-Certain built-in functions are handled specially in byte-compiled code,
-avoiding the need for an ordinary function call. It is a good idea to
-use these functions rather than alternatives. To see whether a function
-is handled specially by the compiler, examine its @code{byte-compile}
-property. If the property is non-@code{nil}, then the function is
-handled specially.
-
-For example, the following input will show you that @code{aref} is
-compiled specially (@pxref{Array Functions}):
-
-@example
-@group
-(get 'aref 'byte-compile)
- @result{} byte-compile-two-args
-@end group
-@end example
-
-@item
-If calling a small function accounts for a substantial part of your
-program's running time, make the function inline. This eliminates
-the function call overhead. Since making a function inline reduces
-the flexibility of changing the program, don't do it unless it gives
-a noticeable speedup in something slow enough that users care about
-the speed. @xref{Inline Functions}.
-@end itemize
-
-@node Warning Tips
-@section Tips for Avoiding Compiler Warnings
-@cindex byte compiler warnings, how to avoid
-
-@itemize @bullet
-@item
-Try to avoid compiler warnings about undefined free variables, by adding
-dummy @code{defvar} definitions for these variables, like this:
-
-@example
-(defvar foo)
-@end example
-
-Such a definition has no effect except to tell the compiler
-not to warn about uses of the variable @code{foo} in this file.
-
-@item
-If you use many functions and variables from a certain file, you can
-add a @code{require} for that package to avoid compilation warnings
-for them. For instance,
-
-@example
-(eval-when-compile
- (require 'foo))
-@end example
-
-@item
-If you bind a variable in one function, and use it or set it in
-another function, the compiler warns about the latter function unless
-the variable has a definition. But adding a definition would be
-unclean if the variable has a short name, since Lisp packages should
-not define short variable names. The right thing to do is to rename
-this variable to start with the name prefix used for the other
-functions and variables in your package.
-
-@item
-The last resort for avoiding a warning, when you want to do something
-that usually is a mistake but it's not a mistake in this one case,
-is to put a call to @code{with-no-warnings} around it.
-@end itemize
-
-@node Documentation Tips
-@section Tips for Documentation Strings
-@cindex documentation strings, conventions and tips
-
-@findex checkdoc-minor-mode
- Here are some tips and conventions for the writing of documentation
-strings. You can check many of these conventions by running the command
-@kbd{M-x checkdoc-minor-mode}.
-
-@itemize @bullet
-@item
-Every command, function, or variable intended for users to know about
-should have a documentation string.
-
-@item
-An internal variable or subroutine of a Lisp program might as well have
-a documentation string. In earlier Emacs versions, you could save space
-by using a comment instead of a documentation string, but that is no
-longer the case---documentation strings now take up very little space in
-a running Emacs.
-
-@item
-Format the documentation string so that it fits in an Emacs window on an
-80-column screen. It is a good idea for most lines to be no wider than
-60 characters. The first line should not be wider than 67 characters
-or it will look bad in the output of @code{apropos}.
-
-You can fill the text if that looks good. However, rather than blindly
-filling the entire documentation string, you can often make it much more
-readable by choosing certain line breaks with care. Use blank lines
-between topics if the documentation string is long.
-
-@item
-The first line of the documentation string should consist of one or two
-complete sentences that stand on their own as a summary. @kbd{M-x
-apropos} displays just the first line, and if that line's contents don't
-stand on their own, the result looks bad. In particular, start the
-first line with a capital letter and end with a period.
-
-For a function, the first line should briefly answer the question,
-``What does this function do?'' For a variable, the first line should
-briefly answer the question, ``What does this value mean?''
-
-Don't limit the documentation string to one line; use as many lines as
-you need to explain the details of how to use the function or
-variable. Please use complete sentences for the rest of the text too.
-
-@item
-When the user tries to use a disabled command, Emacs displays just the
-first paragraph of its documentation string---everything through the
-first blank line. If you wish, you can choose which information to
-include before the first blank line so as to make this display useful.
-
-@item
-The first line should mention all the important arguments of the
-function, and should mention them in the order that they are written
-in a function call. If the function has many arguments, then it is
-not feasible to mention them all in the first line; in that case, the
-first line should mention the first few arguments, including the most
-important arguments.
-
-@item
-When a function's documentation string mentions the value of an argument
-of the function, use the argument name in capital letters as if it were
-a name for that value. Thus, the documentation string of the function
-@code{eval} refers to its second argument as @samp{FORM}, because the
-actual argument name is @code{form}:
-
-@example
-Evaluate FORM and return its value.
-@end example
-
-Also write metasyntactic variables in capital letters, such as when you
-show the decomposition of a list or vector into subunits, some of which
-may vary. @samp{KEY} and @samp{VALUE} in the following example
-illustrate this practice:
-
-@example
-The argument TABLE should be an alist whose elements
-have the form (KEY . VALUE). Here, KEY is ...
-@end example
-
-@item
-Never change the case of a Lisp symbol when you mention it in a doc
-string. If the symbol's name is @code{foo}, write ``foo,'' not
-``Foo'' (which is a different symbol).
-
-This might appear to contradict the policy of writing function
-argument values, but there is no real contradiction; the argument
-@emph{value} is not the same thing as the @emph{symbol} which the
-function uses to hold the value.
-
-If this puts a lower-case letter at the beginning of a sentence
-and that annoys you, rewrite the sentence so that the symbol
-is not at the start of it.
-
-@item
-Do not start or end a documentation string with whitespace.
-
-@item
-@strong{Do not} indent subsequent lines of a documentation string so
-that the text is lined up in the source code with the text of the first
-line. This looks nice in the source code, but looks bizarre when users
-view the documentation. Remember that the indentation before the
-starting double-quote is not part of the string!
-
-@anchor{Docstring hyperlinks}
-@item
-@iftex
-When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with single-quotes
-around it. For example: @samp{`lambda'}. There are two exceptions:
-write @code{t} and @code{nil} without single-quotes.
-@end iftex
-@ifnottex
-When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with single-quotes
-around it. For example: @samp{lambda}. There are two exceptions: write
-t and nil without single-quotes. (In this manual, we use a different
-convention, with single-quotes for all symbols.)
-@end ifnottex
-
-@cindex hyperlinks in documentation strings
-Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name inside single quotes, if the symbol has either a
-function or a variable definition. You do not need to do anything
-special to make use of this feature. However, when a symbol has both a
-function definition and a variable definition, and you want to refer to
-just one of them, you can specify which one by writing one of the words
-@samp{variable}, @samp{option}, @samp{function}, or @samp{command},
-immediately before the symbol name. (Case makes no difference in
-recognizing these indicator words.) For example, if you write
-
-@example
-This function sets the variable `buffer-file-name'.
-@end example
-
-@noindent
-then the hyperlink will refer only to the variable documentation of
-@code{buffer-file-name}, and not to its function documentation.
-
-If a symbol has a function definition and/or a variable definition, but
-those are irrelevant to the use of the symbol that you are documenting,
-you can write the words @samp{symbol} or @samp{program} before the
-symbol name to prevent making any hyperlink. For example,
-
-@example
-If the argument KIND-OF-RESULT is the symbol `list',
-this function returns a list of all the objects
-that satisfy the criterion.
-@end example
-
-@noindent
-does not make a hyperlink to the documentation, irrelevant here, of the
-function @code{list}.
-
-Normally, no hyperlink is made for a variable without variable
-documentation. You can force a hyperlink for such variables by
-preceding them with one of the words @samp{variable} or
-@samp{option}.
-
-Hyperlinks for faces are only made if the face name is preceded or
-followed by the word @samp{face}. In that case, only the face
-documentation will be shown, even if the symbol is also defined as a
-variable or as a function.
-
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) in single quotes, preceded by @samp{info node},
-@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info
-file name defaults to @samp{emacs}. For example,
-
-@smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
-@end smallexample
-
-Finally, to create a hyperlink to URLs, write the URL in single
-quotes, preceded by @samp{URL}. For example,
-
-@smallexample
-The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
-@end smallexample
-
-@item
-Don't write key sequences directly in documentation strings. Instead,
-use the @samp{\\[@dots{}]} construct to stand for them. For example,
-instead of writing @samp{C-f}, write the construct
-@samp{\\[forward-char]}. When Emacs displays the documentation string,
-it substitutes whatever key is currently bound to @code{forward-char}.
-(This is normally @samp{C-f}, but it may be some other character if the
-user has moved key bindings.) @xref{Keys in Documentation}.
-
-@item
-In documentation strings for a major mode, you will want to refer to the
-key bindings of that mode's local map, rather than global ones.
-Therefore, use the construct @samp{\\<@dots{}>} once in the
-documentation string to specify which key map to use. Do this before
-the first use of @samp{\\[@dots{}]}. The text inside the
-@samp{\\<@dots{}>} should be the name of the variable containing the
-local keymap for the major mode.
-
-It is not practical to use @samp{\\[@dots{}]} very many times, because
-display of the documentation string will become slow. So use this to
-describe the most important commands in your major mode, and then use
-@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
-
-@item
-For consistency, phrase the verb in the first sentence of a function's
-documentation string as an imperative---for instance, use ``Return the
-cons of A and B.'' in preference to ``Returns the cons of A and B@.''
-Usually it looks good to do likewise for the rest of the first
-paragraph. Subsequent paragraphs usually look better if each sentence
-is indicative and has a proper subject.
-
-@item
-The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if,'' to indicate
-explicitly what constitutes ``truth.'' The word ``return'' avoids
-starting the sentence with lower-case ``t,'' which could be somewhat
-distracting.
-
-@item
-If a line in a documentation string begins with an open-parenthesis,
-write a backslash before the open-parenthesis, like this:
-
-@example
-The argument FOO can be either a number
-\(a buffer position) or a string (a file name).
-@end example
-
-This prevents the open-parenthesis from being treated as the start of a
-defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
-
-@item
-Write documentation strings in the active voice, not the passive, and in
-the present tense, not the future. For instance, use ``Return a list
-containing A and B.'' instead of ``A list containing A and B will be
-returned.''
-
-@item
-Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
-
-@item
-Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
-since many people are unfamiliar with it and mistake it for a typo. In
-most cases, the meaning is clear with just ``if''. Otherwise, try to
-find an alternate phrasing that conveys the meaning.
-
-@item
-When a command is meaningful only in a certain mode or situation,
-do mention that in the documentation string. For example,
-the documentation of @code{dired-find-file} is:
-
-@example
-In Dired, visit the file or directory named on this line.
-@end example
-
-@item
-When you define a variable that users ought to set interactively, you
-normally should use @code{defcustom}. However, if for some reason you
-use @code{defvar} instead, start the doc string with a @samp{*}.
-@xref{Defining Variables}.
-
-@item
-The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means,'' to make it clear that
-all non-@code{nil} values are equivalent and indicate explicitly what
-@code{nil} and non-@code{nil} mean.
-@end itemize
-
-@node Comment Tips
-@section Tips on Writing Comments
-@cindex comments, Lisp convention for
-
- We recommend these conventions for where to put comments and how to
-indent them:
-
-@table @samp
-@item ;
-Comments that start with a single semicolon, @samp{;}, should all be
-aligned to the same column on the right of the source code. Such
-comments usually explain how the code on the same line does its job. In
-Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
-command automatically inserts such a @samp{;} in the right place, or
-aligns such a comment if it is already present.
-
-This and following examples are taken from the Emacs sources.
-
-@smallexample
-@group
-(setq base-version-list ; there was a base
- (assoc (substring fn 0 start-vn) ; version to which
- file-version-assoc-list)) ; this looks like
- ; a subversion
-@end group
-@end smallexample
-
-@item ;;
-Comments that start with two semicolons, @samp{;;}, should be aligned to
-the same level of indentation as the code. Such comments usually
-describe the purpose of the following lines or the state of the program
-at that point. For example:
-
-@smallexample
-@group
-(prog1 (setq auto-fill-function
- @dots{}
- @dots{}
- ;; update mode line
- (force-mode-line-update)))
-@end group
-@end smallexample
-
-We also normally use two semicolons for comments outside functions.
-
-@smallexample
-@group
-;; This Lisp code is run in Emacs
-;; when it is to operate as a server
-;; for other processes.
-@end group
-@end smallexample
-
-Every function that has no documentation string (presumably one that is
-used only internally within the package it belongs to), should instead
-have a two-semicolon comment right before the function, explaining what
-the function does and how to call it properly. Explain precisely what
-each argument means and how the function interprets its possible values.
-
-@item ;;;
-Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin. These are used, occasionally, for comments within
-functions that should start at the margin. We also use them sometimes
-for comments that are between functions---whether to use two or three
-semicolons depends on whether the comment should be considered a
-``heading'' by Outline minor mode. By default, comments starting with
-at least three semicolons (followed by a single space and a
-non-whitespace character) are considered headings, comments starting
-with two or less are not.
-
-Another use for triple-semicolon comments is for commenting out lines
-within a function. We use three semicolons for this precisely so that
-they remain at the left margin. By default, Outline minor mode does
-not consider a comment to be a heading (even if it starts with at
-least three semicolons) if the semicolons are followed by at least two
-spaces. Thus, if you add an introductory comment to the commented out
-code, make sure to indent it by at least two spaces after the three
-semicolons.
-
-@smallexample
-(defun foo (a)
-;;; This is no longer necessary.
-;;; (force-mode-line-update)
- (message "Finished with %s" a))
-@end smallexample
-
-When commenting out entire functions, use two semicolons.
-
-@item ;;;;
-Comments that start with four semicolons, @samp{;;;;}, should be aligned
-to the left margin and are used for headings of major sections of a
-program. For example:
-
-@smallexample
-;;;; The kill ring
-@end smallexample
-@end table
-
-@noindent
-The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
-(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
-automatically indent comments according to these conventions,
-depending on the number of semicolons. @xref{Comments,,
-Manipulating Comments, emacs, The GNU Emacs Manual}.
-
-@node Library Headers
-@section Conventional Headers for Emacs Libraries
-@cindex header comments
-@cindex library header comments
-
- Emacs has conventions for using special comments in Lisp libraries
-to divide them into sections and give information such as who wrote
-them. This section explains these conventions.
-
- We'll start with an example, a package that is included in the Emacs
-distribution.
-
- Parts of this example reflect its status as part of Emacs; for
-example, the copyright notice lists the Free Software Foundation as the
-copyright holder, and the copying permission says the file is part of
-Emacs. When you write a package and post it, the copyright holder would
-be you (unless your employer claims to own it instead), and you should
-get the suggested copying permission from the end of the GNU General
-Public License itself. Don't say your file is part of Emacs
-if we haven't installed it in Emacs yet!
-
- With that warning out of the way, on to the example:
-
-@smallexample
-@group
-;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
-
-;; Copyright (C) 1992 Free Software Foundation, Inc.
-@end group
-
-;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
-;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
-;; Created: 14 Jul 1992
-;; Version: 1.2
-@group
-;; Keywords: docs
-
-;; This file is part of GNU Emacs.
-@dots{}
-;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-;; Boston, MA 02110-1301, USA.
-@end group
-@end smallexample
-
- The very first line should have this format:
-
-@example
-;;; @var{filename} --- @var{description}
-@end example
-
-@noindent
-The description should be complete in one line. If the file
-needs a @samp{-*-} specification, put it after @var{description}.
-
- After the copyright notice come several @dfn{header comment} lines,
-each beginning with @samp{;; @var{header-name}:}. Here is a table of
-the conventional possibilities for @var{header-name}:
-
-@table @samp
-@item Author
-This line states the name and net address of at least the principal
-author of the library.
-
-If there are multiple authors, you can list them on continuation lines
-led by @code{;;} and a tab character, like this:
-
-@smallexample
-@group
-;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
-;; Dave Sill <de5@@ornl.gov>
-;; Dave Brennan <brennan@@hal.com>
-;; Eric Raymond <esr@@snark.thyrsus.com>
-@end group
-@end smallexample
-
-@item Maintainer
-This line should contain a single name/address as in the Author line, or
-an address only, or the string @samp{FSF}. If there is no maintainer
-line, the person(s) in the Author field are presumed to be the
-maintainers. The example above is mildly bogus because the maintainer
-line is redundant.
-
-The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
-possible a Lisp function to ``send mail to the maintainer'' without
-having to mine the name out by hand.
-
-Be sure to surround the network address with @samp{<@dots{}>} if
-you include the person's full name as well as the network address.
-
-@item Created
-This optional line gives the original creation date of the
-file. For historical interest only.
-
-@item Version
-If you wish to record version numbers for the individual Lisp program, put
-them in this line.
-
-@item Adapted-By
-In this header line, place the name of the person who adapted the
-library for installation (to make it fit the style conventions, for
-example).
-
-@item Keywords
-This line lists keywords for the @code{finder-by-keyword} help command.
-Please use that command to see a list of the meaningful keywords.
-
-This field is important; it's how people will find your package when
-they're looking for things by topic area. To separate the keywords, you
-can use spaces, commas, or both.
-@end table
-
- Just about every Lisp library ought to have the @samp{Author} and
-@samp{Keywords} header comment lines. Use the others if they are
-appropriate. You can also put in header lines with other header
-names---they have no standard meanings, so they can't do any harm.
-
- We use additional stylized comments to subdivide the contents of the
-library file. These should be separated by blank lines from anything
-else. Here is a table of them:
-
-@table @samp
-@item ;;; Commentary:
-This begins introductory comments that explain how the library works.
-It should come right after the copying permissions, terminated by a
-@samp{Change Log}, @samp{History} or @samp{Code} comment line. This
-text is used by the Finder package, so it should make sense in that
-context.
-
-@item ;;; Documentation:
-This was used in some files in place of @samp{;;; Commentary:},
-but it is deprecated.
-
-@item ;;; Change Log:
-This begins change log information stored in the library file (if you
-store the change history there). For Lisp files distributed with Emacs,
-the change history is kept in the file @file{ChangeLog} and not in the
-source file at all; these files generally do not have a @samp{;;; Change
-Log:} line. @samp{History} is an alternative to @samp{Change Log}.
-
-@item ;;; Code:
-This begins the actual code of the program.
-
-@item ;;; @var{filename} ends here
-This is the @dfn{footer line}; it appears at the very end of the file.
-Its purpose is to enable people to detect truncated versions of the file
-from the lack of a footer line.
-@end table
-
-@ignore
- arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e
-@end ignore
+++ /dev/null
-Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
- Free Software Foundation, Inc.
- See end for copying conditions.
-
-Two Volume Cross References
-===========================
-
-12 June 2007 (karl)
-
-For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly
-Makefile, in the file two-volume.make, to encapsulate all the steps
-below, without manual intervention. In theory, simply running "make -f
-two-volume.make" should create a vol1.pdf and vol2.pdf with all the
-niceties worked out.
-
-One issue not explicitly discussed below is getting page numbers right.
-It's not enough to go through the whole process. You have to go through
-the whole process twice -- otherwise, some index entries and/or toc
-entries will be off by one. See two-volume.make for a few more comments.
-
-For future editions, it should suffice to update the usual things in
-vol[12].texi (as well as elisp.texi). That was my hope, anyway.
-
-
-18 March 1992 (bob)
-
-This enables you to create manuals in *two* volumes, with tables of
-contents, cross references, and indices in each volume referring to
-*both* volumes.
-
-The procedure is tedious. However, the resulting two volumes are
-conveniently organized. Each has an index of the whole two volumes.
-Each volume starts with page 1. (I don't like multi-volume works
-where each volume starts with a higher page number since I find it
-harder to go to the right place in the volume.)
-
-References to the same volume are just the page number; references to
-the other volume are a volumne number (in Roman numerals) preceding
-the page number.
-
-For example, in Volume I:
-
- list length ......... 90
- list motion ......II:117
-
-and in Volume II:
-
- list length ....... I:90
- list motion .........117
-
-All other references and the table of contents work the same way. I
-find this *very* helpful.
-
-
-In brief: you run tex on a .texi file with
-
- a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file
- b. redone .aux file
- c. redone .fns file
-
-\f
-Here are the steps in detail:
-
-% tex vol1.texi
-% texindex vol1.??
-% tex vol1.texi
-
-% tex vol2.texi
-% texindex vol2.??
-% tex vol2.texi
-
-### Create .aux files with volume numbers for other volume.
-
-% cp vol1.aux elisp1-aux
-% cp vol2.aux elisp2-aux
-
-% cp vol1.aux elisp1-aux-vol-added
-% cp vol2.aux elisp2-aux-vol-added
-
-on elisp1-aux-vol-number-added
-(volume-aux-markup 1) see defun for volume-aux-markup below.
-to create elisp1-aux-vol-added
-
-on elisp2-aux-vol-number-added
-(volume-aux-markup 2)
-to create elisp2-aux-vol-added
-
-insert elisp2-aux-vol-added into vol1.aux (append)
-insert elisp1-aux-vol-added into vol2.aux (prepend)
-
-(so you dont have to do it again)
-% cp vol1.aux elisp1-aux-ready
-% cp vol2.aux elisp2-aux-ready
-
-
-### Create .fn files with volume numbers for other volume.
-
-% cp vol1.fn elisp1-fn
-% cp vol2.fn elisp2-fn
-
-% cp vol1.fn elisp1-fn-vol-number-added
-% cp vol2.fn elisp2-fn-vol-number-added
-
-on elisp1-fn-vol-number-added
-(volume-index-markup "I")
-to create elisp1-fn-vol-number-added
-
-on elisp2-fn-vol-number-added
-(volume-index-markup "II")
-to create elisp2-fn-vol-number-added
-
-insert elisp2-fn-vol-number-added into vol1.fn: do following `cat'
-insert elisp1-fn-vol-number-added into vol2.fn: do following `cat'
-
-% cat elisp2-fn-vol-number-added >> vol1.fn
-% cat elisp1-fn-vol-number-added >> vol2.fn
-
-Be sure to handle special case entries by hand.
-Be sure that .fn file has no blank lines.
-
-% texindex vol1.fn
-% texindex vol2.fn
-
-(so you dont have to do it again)
-% cp vol1.fns elisp1-fns-2vol-ready
-% cp vol2.fns elisp2-fns-2vol-ready
-
-### Create merged .toc file with volume number headings.
-
-append vol2.toc to vol1.toc with following `cat'
-
-% cat vol1.toc vol2.toc > elisp-toc-2vol.toc
-
-and edit in Volume titles
-
-\unnumbchapentry {Volume 1}{}
-\unnumbchapentry {}{}
-
-\unnumbchapentry {Index}{295}
-\unnumbchapentry {}{}
-\unnumbchapentry {Volume 2}{}
-\unnumbchapentry {}{}
-
-If you want to put in volume numbers for TOC, then do this:
-Create volume specific .toc files with volume numbers in them.
-
-% cp elisp-toc-2vol.toc elisp1-toc.toc
-% cp elisp-toc-2vol.toc elisp2-toc.toc
-
-Use keyboard macro to put I: in first half of elisp1-toc.toc and
-II: in first half of elisp2-toc.toc
-
-Copy the tocs to something you can remember more easily
-
-% cp elisp2-toc.toc elisp1-toc-ready.toc
-% cp elisp1-toc.toc elisp2-toc-ready.toc
-
-Then, edit vol1.texi to input elisp1-toc-ready.toc
-and vol2.texi to input elisp2-toc-ready.toc
-
-
-### Now format the two volumes:
-
-% cp elisp1-aux-2vol-ready vol1.aux
-% cp elisp2-aux-2vol-ready vol2.aux
-
-% tex vol1.texi
-% tex vol2.texi
-
-
-\f
-For every additional run:
-
-### recopy aux files so the correct ones are read:
-% cp elisp1-aux-2vol-ready vol1.aux
-% cp elisp2-aux-2vol-ready vol2.aux
-
-Do not run texindex. Then proper sorted index will stay.
- else do: % cp elisp2-fns-2vol-ready vol2.fns
-
-Do not change the .texi files; they will call the elisp-toc-2vol.toc file.
-
-% tex vol1.texi
-% tex vol2.texi
-
-================================================================
-\f
-
-(defun volume-aux-markup (arg)
- "Append `vol. NUMBER' to page number.
-Apply to aux file that you save.
-Then insert marked file into other volume's .aux file."
- (interactive "sType volume number, 1 or 2: " )
- (goto-char (point-min))
- (while (search-forward "-pg" nil t)
- (end-of-line 1)
- (delete-backward-char 1 nil)
- (insert ", vol.'tie" arg "}")))
-
-(defun volume-index-markup (arg)
- "Prepend `NUMBER:' to page number. Use Roman Numeral.
-Apply only to unsorted index file,
-Then insert marked file into other volume's unsorted index file.
-Then run texindex on that file and save."
- (interactive
- "sType volume number, roman number I or II: " )
- (goto-char (point-min))
- (while (search-forward "\\entry" nil t)
- (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
- (insert arg ":")))
-
-
-================================================================
-\f
-
-The steps:
-
-1. Run TeX, texindex and TeX on file1.
-2. Run TeX, texindex and TeX on file2.
-
-3. Copy both .aux files into specially named files
-
-4. In the case of the elisp ref manual,
-
- copy the *unsorted* function index files into specially named files
- (no other index used in elisp ref manual)
-
-
-5. For aux files:
-
- Run a function on the specially named .aux files to label each
- entry according to volume. Save these files.
-
- i.e., convert
- 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1}
-
-5a.Insert each specially named .aux file into the regular .aux file of
- the other volume.
-
-6. For index files:
-
- Run a function on the specially named unsorted index files to label
- each entry according to volume. Save these files.
-
-6b.Insert each specially named marked unsorted index file into the
- regular unsorted file of the other volume. Run texindex on this
-
-7. Insert the other volumes .toc file into the .toc, edit, and rename to
- elisp-toc-2vol.toc
-
-7a. insert special @contents and @summarycontents defs into .texi files.
-
-8. Run TeX on each .texi file.
-
-================
-
-
-\f
-Here is the discursive commentary:
-
-I've been running some small test files, called test1.texi and
-test2.texi. As far as I can see, if we run tex on the two test files,
-tex creates a .aux for each that includes the names of all the nodes
-in that file. The node names are used for cross references.
-
-If you insert the .aux file for the second test file, test2.aux, into
-the .aux file for the first test file, test1.aux, then when you next
-run TeX on the first test file, test1.texi, the second volume cross
-references are inserted.
-
-You can edit the text of the cross reference in test2.aux to include
-the volume number.
-
-For example, you can take the following two lines from test1.texi and
-insert them into test2.texi:
-
- 'xrdef {Special-pg}{7}
- 'xrdef {Special-snt}{Section'tie1.6}
-
-You can re-edit this to show that the page is in volume 1:
-
- 'xrdef {Special-pg}{7, vol.'tie1}
- 'xrdef {Special-snt}{Section'tie1.6}
-
-(The 'tie is a TeX special command to keep the number tied on one
-line to the previous word. I don't know if it works after a period in
-the "vol." but figure it is worth trying. {The ' is the @ of .aux files.}
-Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the
-definition for 'tie is the following:
-
- \def\tie{\penalty 10000\ } % Save plain tex definition of ~.
-
-)
-
-After running tex on the test2.texi file with the augmented test2.aux
-file, you can see the following in the resulting DVI file:
-
- See Section 1.6 [Special], page 7, vol. 1
-
-Note that TeX rewrites the .aux file each time TeX is run, so after
-running Tex using an .aux file augmented with the .aux file from the
-other volume, the new .aux file will *lack* the other volumes cross
-references. Save your augmented .aux file in some other name for
-another run!
-
-
-COPYING CONDITIONS
-
-This file 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.
-
-This file 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 this file; see the file COPYING. If not, write to
-the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-Boston, MA 02110-1301, USA.
+++ /dev/null
-# Copyright 2007 Free Software Foundation, Inc.
-# See end for copying conditions.
-
-# although it would be nice to use tex rather than pdftex to avoid
-# colors, spurious warnings about names being referenced but not
-# existing, etc., dvips | ps2pdf doesn't preserve the page size.
-# Instead of creating a special dvips config file, put up with the warnings.
-tex = pdftex -interaction=nonstopmode
-
-all: vol1.pdf vol2.pdf
-
-# vol1.texi and vol2.texi specially define \tocreadfilename so we can
-# use our premade .toc's.
-#
-vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready
- @echo -e "\f Final TeX run for volume 1..."
- cp elisp1med-toc-ready elisp1-toc-ready.toc
- cp elisp1med-fns-ready vol1.fns
- cp elisp1med-aux-ready vol1.aux
- $(tex) vol1.texi
-#
-vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready
- @echo "Final TeX run for volume 2..."
- cp elisp2med-toc-ready elisp2-toc-ready.toc
- cp elisp2med-fns-ready vol2.fns
- cp elisp2med-aux-ready vol2.aux
- $(tex) vol2.texi
-
-# \f intermediate toc files.
-#
-# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
-elisp1med-toc-ready: elisp1med-init elisp2med-init
- echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
- cat elisp1med-toc >>$@
- echo '@page' >>$@
- echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
- sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@
-#
-# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
-elisp2med-toc-ready: elisp1med-init elisp2med-init
- echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
- sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@
- echo '@page' >>$@
- echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
- cat elisp2med-toc >>$@
-
-
-# \f intermediate aux files.
-#
-# append vol2's fixed aux to normal vol1.
-elisp1med-aux-ready: elisp2med-aux-vol-added
- cat elisp1med-aux $< >$@
-#
-# prepend vol1's fixed aux to vol2.
-elisp2med-aux-ready: elisp1med-aux-vol-added
- cat $< elisp2med-aux >$@
-
-# on -pg entries, append volume number after page number.
-elisp1med-aux-vol-added: elisp1med-init
- sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@
-#
-elisp2med-aux-vol-added: elisp2med-init
- sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@
-
-
-
-# \f intermediate index (fns) file.
-#
-elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
- cat elisp2med-fn-vol-added >>vol1.fn
- texindex vol1.fn
- cp vol1.fns $@
-#
-elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
- cat elisp1med-fn-vol-added >>vol2.fn
- texindex vol2.fn
- cp vol2.fns $@
-
-# Insert volume number (I: or II:) into index file.
-elisp1med-fn-vol-added: elisp1med-init
- cp vol1.fn elisp1med-fn
- sed 's/}{/}{I:/' elisp1med-fn >$@
-#
-elisp2med-fn-vol-added: elisp2med-init
- cp vol2.fn elisp2med-fn
- sed 's/}{/}{II:/' elisp2med-fn >$@
-
-# -----------------------------------------------------------------------------
-# everything above is essentially a duplicate of everything below. sorry.
-# -----------------------------------------------------------------------------
-
-# \f intermediate TeX runs.
-#
-# this generates what would be the final versions -- except the page
-# numbers aren't right. The process of adding the I: and II: changes
-# the page breaks, so a few index entries, at least are wrong. (In
-# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had
-# it on page 375 from the initial run.)
-#
-# So, we start all over again, from these fns/aux/toc files.
-#
-elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready texinfo.tex
- @echo -e "\f Intermediate TeX run for volume 1..."
- cp elisp1init-toc-ready elisp1-toc-ready.toc
- cp elisp1-fns-ready vol1.fns
- cp elisp1-aux-ready vol1.aux
- $(tex) vol1.texi
- texindex vol1.??
- mv vol1.aux elisp1med-aux
- mv vol1.toc elisp1med-toc
-#
-elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready texinfo.tex
- @echo "Final TeX run for volume 2..."
- cp elisp2init-toc-ready elisp2-toc-ready.toc
- cp elisp2-fns-ready vol2.fns
- cp elisp2-aux-ready vol2.aux
- $(tex) vol2.texi
- texindex vol2.??
- mv vol2.aux elisp2med-aux
- mv vol2.toc elisp2med-toc
-
-
-# \f initial toc files.
-#
-# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
-elisp1init-toc-ready: elisp1-init elisp2-init
- echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
- cat elisp1-toc >>$@
- echo '@page' >>$@
- echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
- sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@
-#
-# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
-elisp2init-toc-ready: elisp1-init elisp2-init
- echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
- sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@
- echo '@page' >>$@
- echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
- cat elisp2-toc >>$@
-
-
-# \f initial aux files.
-#
-# append vol2's fixed aux to normal vol1. The initial runs saved
-# elisp1-aux and elisp2-aux.
-elisp1-aux-ready: elisp2-aux-vol-added
- cat elisp1-aux $< >$@
-#
-# prepend vol1's fixed aux to vol2.
-elisp2-aux-ready: elisp1-aux-vol-added
- cat $< elisp2-aux >$@
-
-# on -pg entries, append volume number after page number.
-elisp1-aux-vol-added: elisp1-init
- sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@
-#
-elisp2-aux-vol-added: elisp2-init
- sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@
-
-
-# \f initial index (fns) file.
-#
-# Append other volume's index entries to this one's.
-# Index entries in this volume will then take precedence.
-elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
- cat elisp2-fn-vol-added >>vol1.fn
- texindex vol1.fn
- cp vol1.fns $@
-#
-elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
- cat elisp1-fn-vol-added >>vol2.fn
- texindex vol2.fn
- cp vol2.fns $@
-
-# Insert volume number (I: or II:) into index file.
-elisp1-fn-vol-added: elisp1-init
- cp vol1.fn elisp1-fn
- sed 's/}{/}{I:/' elisp1-fn >$@
-#
-elisp2-fn-vol-added: elisp2-init
- cp vol2.fn elisp2-fn
- sed 's/}{/}{II:/' elisp2-fn >$@
-
-
-# \f initial TeX runs.
-#
-# We use the .fn, .aux, and .toc files created here in subsequent
-# processing. The page numbers generated here will not be correct yet,
-# but we run texindex and TeX a second time just to get them closer.
-# Otherwise it might take even longer for them to converge.
-#
-elisp1-init: vol1.texi
- @echo -e "\f Initial TeX run for volume 1..."
- rm -f vol1.aux vol1.toc
- $(tex) $<
- texindex vol1.??
- mv vol1.aux elisp1-aux
- mv vol1.toc elisp1-toc
- touch $@
-#
-elisp2-init: vol2.texi
- @echo "Initial TeX run for volume 2..."
- rm -f vol2.aux vol2.toc
- $(tex) $<
- texindex vol2.??
- mv vol2.aux elisp2-aux
- mv vol2.toc elisp2-toc
- touch $@
-
-# COPYING CONDITIONS
-#
-# This file 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.
-#
-# This file 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 this file; 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: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb
+++ /dev/null
-;; Auxiliary functions for preparing a two volume manual.
-
-;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
-;; Free Software Foundation, Inc.
-
-;; --rjc 30mar92
-
-;; This file 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.
-
-;; This file 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 this file; see the file COPYING. If not, write to
-;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-;; Boston, MA 02110-1301, USA.
-
-(defun volume-aux-markup (arg)
- "Append `vol. NUMBER' to page number.
-Apply to aux file that you save.
-Then insert marked file into other volume's .aux file."
- (interactive "sType volume number, 1 or 2: " )
- (goto-char (point-min))
- (while (search-forward "-pg" nil t)
- (end-of-line 1)
- (delete-backward-char 1 nil)
- (insert ", vol.'tie" arg "}")))
-
-(defun volume-index-markup (arg)
- "Prepend `NUMBER:' to page number. Use Roman Numeral.
-Apply only to unsorted index file,
-Then insert marked file into other volume's unsorted index file.
-Then run texindex on that file and save."
- (interactive
- "sType volume number, roman number I or II: " )
- (goto-char (point-min))
- (while (search-forward "\\entry" nil t)
- (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
- (insert arg ":")))
-
-(defun volume-numbers-toc-markup (arg)
- (interactive
- "sType volume number, roman number I or II: " )
- (goto-char (point-min))
- (while (search-forward "chapentry" nil t)
- (end-of-line)
- (search-backward "{" nil t)
- (forward-char 1)
- (insert arg ":")))
-
-(defun volume-header-toc-markup ()
- "Insert Volume I and Volume II text into .toc file.
-NOTE: this auxilary function is file specific.
-This is for the *Elisp Ref Manual*"
- (interactive)
- (goto-char (point-min))
- (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n")
- (search-forward "\\unnumbchapentry {Index}")
- (forward-line 1)
- (insert
- "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n"))
-
-
-;;; In batch mode, you cannot call functions with args; hence this kludge:
-
-(defun volume-aux-markup-1 () (volume-aux-markup "1"))
-(defun volume-aux-markup-2 () (volume-aux-markup "2"))
-
-(defun volume-index-markup-I () (volume-index-markup "I"))
-(defun volume-index-markup-II () (volume-index-markup "II"))
-
-(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I"))
-(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II"))
-
-;;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5
+++ /dev/null
-@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,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/variables
-@node Variables, Functions, Control Structures, Top
-@chapter Variables
-@cindex variable
-
- A @dfn{variable} is a name used in a program to stand for a value.
-Nearly all programming languages have variables of some sort. In the
-text of a Lisp program, variables are written using the syntax for
-symbols.
-
- In Lisp, unlike most programming languages, programs are represented
-primarily as Lisp objects and only secondarily as text. The Lisp
-objects used for variables are symbols: the symbol name is the variable
-name, and the variable's value is stored in the value cell of the
-symbol. The use of a symbol as a variable is independent of its use as
-a function name. @xref{Symbol Components}.
-
- The Lisp objects that constitute a Lisp program determine the textual
-form of the program---it is simply the read syntax for those Lisp
-objects. This is why, for example, a variable in a textual Lisp program
-is written using the read syntax for the symbol that represents the
-variable.
-
-@menu
-* 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.
-@end menu
-
-@node Global Variables
-@section Global Variables
-@cindex global variable
-
- The simplest way to use a variable is @dfn{globally}. This means that
-the variable has just one value at a time, and this value is in effect
-(at least for the moment) throughout the Lisp system. The value remains
-in effect until you specify a new one. When a new value replaces the
-old one, no trace of the old value remains in the variable.
-
- You specify a value for a symbol with @code{setq}. For example,
-
-@example
-(setq x '(a b))
-@end example
-
-@noindent
-gives the variable @code{x} the value @code{(a b)}. Note that
-@code{setq} does not evaluate its first argument, the name of the
-variable, but it does evaluate the second argument, the new value.
-
- Once the variable has a value, you can refer to it by using the symbol
-by itself as an expression. Thus,
-
-@example
-@group
-x @result{} (a b)
-@end group
-@end example
-
-@noindent
-assuming the @code{setq} form shown above has already been executed.
-
- If you do set the same variable again, the new value replaces the old
-one:
-
-@example
-@group
-x
- @result{} (a b)
-@end group
-@group
-(setq x 4)
- @result{} 4
-@end group
-@group
-x
- @result{} 4
-@end group
-@end example
-
-@node Constant Variables
-@section Variables that Never Change
-@kindex setting-constant
-@cindex keyword symbol
-@cindex variable with constant value
-@cindex constant variables
-@cindex symbol that evaluates to itself
-@cindex symbol with constant value
-
- In Emacs Lisp, certain symbols normally evaluate to themselves. These
-include @code{nil} and @code{t}, as well as any symbol whose name starts
-with @samp{:} (these are called @dfn{keywords}). These symbols cannot
-be rebound, nor can their values be changed. Any attempt to set or bind
-@code{nil} or @code{t} signals a @code{setting-constant} error. The
-same is true for a keyword (a symbol whose name starts with @samp{:}),
-if it is interned in the standard obarray, except that setting such a
-symbol to itself is not an error.
-
-@example
-@group
-nil @equiv{} 'nil
- @result{} nil
-@end group
-@group
-(setq nil 500)
-@error{} Attempt to set constant symbol: nil
-@end group
-@end example
-
-@defun keywordp object
-function returns @code{t} if @var{object} is a symbol whose name
-starts with @samp{:}, interned in the standard obarray, and returns
-@code{nil} otherwise.
-@end defun
-
-@node Local Variables
-@section Local Variables
-@cindex binding local variables
-@cindex local variables
-@cindex local binding
-@cindex global binding
-
- Global variables have values that last until explicitly superseded
-with new values. Sometimes it is useful to create variable values that
-exist temporarily---only until a certain part of the program finishes.
-These values are called @dfn{local}, and the variables so used are
-called @dfn{local variables}.
-
- For example, when a function is called, its argument variables receive
-new local values that last until the function exits. The @code{let}
-special form explicitly establishes new local values for specified
-variables; these last until exit from the @code{let} form.
-
-@cindex shadowing of variables
- Establishing a local value saves away the previous value (or lack of
-one) of the variable. When the life span of the local value is over,
-the previous value is restored. In the mean time, we say that the
-previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
-local values may be shadowed (@pxref{Scope}).
-
- If you set a variable (such as with @code{setq}) while it is local,
-this replaces the local value; it does not alter the global value, or
-previous local values, that are shadowed. To model this behavior, we
-speak of a @dfn{local binding} of the variable as well as a local value.
-
- The local binding is a conceptual place that holds a local value.
-Entry to a function, or a special form such as @code{let}, creates the
-local binding; exit from the function or from the @code{let} removes the
-local binding. As long as the local binding lasts, the variable's value
-is stored within it. Use of @code{setq} or @code{set} while there is a
-local binding stores a different value into the local binding; it does
-not create a new binding.
-
- We also speak of the @dfn{global binding}, which is where
-(conceptually) the global value is kept.
-
-@cindex current binding
- A variable can have more than one local binding at a time (for
-example, if there are nested @code{let} forms that bind it). In such a
-case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable. (This rule is called
-@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
-local bindings, the variable's global binding is its current binding.
-We sometimes call the current binding the @dfn{most-local existing
-binding}, for emphasis. Ordinary evaluation of a symbol always returns
-the value of its current binding.
-
- The special forms @code{let} and @code{let*} exist to create
-local bindings.
-
-@defspec let (bindings@dots{}) forms@dots{}
-This special form binds variables according to @var{bindings} and then
-evaluates all of the @var{forms} in textual order. The @code{let}-form
-returns the value of the last form in @var{forms}.
-
-Each of the @var{bindings} is either @w{(i) a} symbol, in which case
-that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
-@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
-bound to the result of evaluating @var{value-form}. If @var{value-form}
-is omitted, @code{nil} is used.
-
-All of the @var{value-form}s in @var{bindings} are evaluated in the
-order they appear and @emph{before} binding any of the symbols to them.
-Here is an example of this: @code{z} is bound to the old value of
-@code{y}, which is 2, not the new value of @code{y}, which is 1.
-
-@example
-@group
-(setq y 2)
- @result{} 2
-@end group
-@group
-(let ((y 1)
- (z y))
- (list y z))
- @result{} (1 2)
-@end group
-@end example
-@end defspec
-
-@defspec let* (bindings@dots{}) forms@dots{}
-This special form is like @code{let}, but it binds each variable right
-after computing its local value, before computing the local value for
-the next variable. Therefore, an expression in @var{bindings} can
-reasonably refer to the preceding symbols bound in this @code{let*}
-form. Compare the following example with the example above for
-@code{let}.
-
-@example
-@group
-(setq y 2)
- @result{} 2
-@end group
-@group
-(let* ((y 1)
- (z y)) ; @r{Use the just-established value of @code{y}.}
- (list y z))
- @result{} (1 1)
-@end group
-@end example
-@end defspec
-
- Here is a complete list of the other facilities that create local
-bindings:
-
-@itemize @bullet
-@item
-Function calls (@pxref{Functions}).
-
-@item
-Macro calls (@pxref{Macros}).
-
-@item
-@code{condition-case} (@pxref{Errors}).
-@end itemize
-
- Variables can also have buffer-local bindings (@pxref{Buffer-Local
-Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
-few variables have terminal-local bindings (@pxref{Multiple Displays}).
-These kinds of bindings work somewhat like ordinary local bindings, but
-they are localized depending on ``where'' you are in Emacs, rather than
-localized in time.
-
-@defvar max-specpdl-size
-@anchor{Definition of max-specpdl-size}
-@cindex variable limit error
-@cindex evaluation error
-@cindex infinite recursion
-This variable defines the limit on the total number of local variable
-bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
-Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
-error (with data @code{"Variable binding depth exceeds
-max-specpdl-size"}).
-
-This limit, with the associated error when it is exceeded, is one way
-that Lisp avoids infinite recursion on an ill-defined function.
-@code{max-lisp-eval-depth} provides another limit on depth of nesting.
-@xref{Definition of max-lisp-eval-depth,, Eval}.
-
-The default value is 1000. Entry to the Lisp debugger increases the
-value, if there is little room left, to make sure the debugger itself
-has room to execute.
-@end defvar
-
-@node Void Variables
-@section When a Variable is ``Void''
-@kindex void-variable
-@cindex void variable
-
- If you have never given a symbol any value as a global variable, we
-say that that symbol's global value is @dfn{void}. In other words, the
-symbol's value cell does not have any Lisp object in it. If you try to
-evaluate the symbol, you get a @code{void-variable} error rather than
-a value.
-
- Note that a value of @code{nil} is not the same as void. The symbol
-@code{nil} is a Lisp object and can be the value of a variable just as any
-other object can be; but it is @emph{a value}. A void variable does not
-have any value.
-
- After you have given a variable a value, you can make it void once more
-using @code{makunbound}.
-
-@defun makunbound symbol
-This function makes the current variable binding of @var{symbol} void.
-Subsequent attempts to use this symbol's value as a variable will signal
-the error @code{void-variable}, unless and until you set it again.
-
-@code{makunbound} returns @var{symbol}.
-
-@example
-@group
-(makunbound 'x) ; @r{Make the global value of @code{x} void.}
- @result{} x
-@end group
-@group
-x
-@error{} Symbol's value as variable is void: x
-@end group
-@end example
-
-If @var{symbol} is locally bound, @code{makunbound} affects the most
-local existing binding. This is the only way a symbol can have a void
-local binding, since all the constructs that create local bindings
-create them with values. In this case, the voidness lasts at most as
-long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous local or global binding is
-reexposed as usual, and the variable is no longer void unless the newly
-reexposed binding was void all along.
-
-@smallexample
-@group
-(setq x 1) ; @r{Put a value in the global binding.}
- @result{} 1
-(let ((x 2)) ; @r{Locally bind it.}
- (makunbound 'x) ; @r{Void the local binding.}
- x)
-@error{} Symbol's value as variable is void: x
-@end group
-@group
-x ; @r{The global binding is unchanged.}
- @result{} 1
-
-(let ((x 2)) ; @r{Locally bind it.}
- (let ((x 3)) ; @r{And again.}
- (makunbound 'x) ; @r{Void the innermost-local binding.}
- x)) ; @r{And refer: it's void.}
-@error{} Symbol's value as variable is void: x
-@end group
-
-@group
-(let ((x 2))
- (let ((x 3))
- (makunbound 'x)) ; @r{Void inner binding, then remove it.}
- x) ; @r{Now outer @code{let} binding is visible.}
- @result{} 2
-@end group
-@end smallexample
-@end defun
-
- A variable that has been made void with @code{makunbound} is
-indistinguishable from one that has never received a value and has
-always been void.
-
- You can use the function @code{boundp} to test whether a variable is
-currently void.
-
-@defun boundp variable
-@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
-more precisely, if its current binding is not void. It returns
-@code{nil} otherwise.
-
-@smallexample
-@group
-(boundp 'abracadabra) ; @r{Starts out void.}
- @result{} nil
-@end group
-@group
-(let ((abracadabra 5)) ; @r{Locally bind it.}
- (boundp 'abracadabra))
- @result{} t
-@end group
-@group
-(boundp 'abracadabra) ; @r{Still globally void.}
- @result{} nil
-@end group
-@group
-(setq abracadabra 5) ; @r{Make it globally nonvoid.}
- @result{} 5
-@end group
-@group
-(boundp 'abracadabra)
- @result{} t
-@end group
-@end smallexample
-@end defun
-
-@node Defining Variables
-@section Defining Global Variables
-@cindex variable definition
-
- You may announce your intention to use a symbol as a global variable
-with a @dfn{variable definition}: a special form, either @code{defconst}
-or @code{defvar}.
-
- In Emacs Lisp, definitions serve three purposes. First, they inform
-people who read the code that certain symbols are @emph{intended} to be
-used a certain way (as variables). Second, they inform the Lisp system
-of these things, supplying a value and documentation. Third, they
-provide information to utilities such as @code{etags} and
-@code{make-docfile}, which create data bases of the functions and
-variables in a program.
-
- The difference between @code{defconst} and @code{defvar} is primarily
-a matter of intent, serving to inform human readers of whether the value
-should ever change. Emacs Lisp does not restrict the ways in which a
-variable can be used based on @code{defconst} or @code{defvar}
-declarations. However, it does make a difference for initialization:
-@code{defconst} unconditionally initializes the variable, while
-@code{defvar} initializes it only if it is void.
-
-@ignore
- One would expect user option variables to be defined with
-@code{defconst}, since programs do not change them. Unfortunately, this
-has bad results if the definition is in a library that is not preloaded:
-@code{defconst} would override any prior value when the library is
-loaded. Users would like to be able to set user options in their init
-files, and override the default values given in the definitions. For
-this reason, user options must be defined with @code{defvar}.
-@end ignore
-
-@defspec defvar symbol [value [doc-string]]
-This special form defines @var{symbol} as a variable and can also
-initialize and document it. The definition informs a person reading
-your code that @var{symbol} is used as a variable that might be set or
-changed. Note that @var{symbol} is not evaluated; the symbol to be
-defined must appear explicitly in the @code{defvar}.
-
-If @var{symbol} is void and @var{value} is specified, @code{defvar}
-evaluates it and sets @var{symbol} to the result. But if @var{symbol}
-already has a value (i.e., it is not void), @var{value} is not even
-evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
-is omitted, the value of @var{symbol} is not changed in any case.
-
-If @var{symbol} has a buffer-local binding in the current buffer,
-@code{defvar} operates on the default value, which is buffer-independent,
-not the current (buffer-local) binding. It sets the default value if
-the default value is void. @xref{Buffer-Local Variables}.
-
-When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
-Emacs Lisp mode (@code{eval-defun}), a special feature of
-@code{eval-defun} arranges to set the variable unconditionally, without
-testing whether its value is void.
-
-If the @var{doc-string} argument appears, it specifies the documentation
-for the variable. (This opportunity to specify documentation is one of
-the main benefits of defining the variable.) The documentation is
-stored in the symbol's @code{variable-documentation} property. The
-Emacs help functions (@pxref{Documentation}) look for this property.
-
-If the variable is a user option that users would want to set
-interactively, you should use @samp{*} as the first character of
-@var{doc-string}. This lets users set the variable conveniently using
-the @code{set-variable} command. Note that you should nearly always
-use @code{defcustom} instead of @code{defvar} to define these
-variables, so that users can use @kbd{M-x customize} and related
-commands to set them. @xref{Customization}.
-
-Here are some examples. This form defines @code{foo} but does not
-initialize it:
-
-@example
-@group
-(defvar foo)
- @result{} foo
-@end group
-@end example
-
-This example initializes the value of @code{bar} to @code{23}, and gives
-it a documentation string:
-
-@example
-@group
-(defvar bar 23
- "The normal weight of a bar.")
- @result{} bar
-@end group
-@end example
-
-The following form changes the documentation string for @code{bar},
-making it a user option, but does not change the value, since @code{bar}
-already has a value. (The addition @code{(1+ nil)} would get an error
-if it were evaluated, but since it is not evaluated, there is no error.)
-
-@example
-@group
-(defvar bar (1+ nil)
- "*The normal weight of a bar.")
- @result{} bar
-@end group
-@group
-bar
- @result{} 23
-@end group
-@end example
-
-Here is an equivalent expression for the @code{defvar} special form:
-
-@example
-@group
-(defvar @var{symbol} @var{value} @var{doc-string})
-@equiv{}
-(progn
- (if (not (boundp '@var{symbol}))
- (setq @var{symbol} @var{value}))
- (if '@var{doc-string}
- (put '@var{symbol} 'variable-documentation '@var{doc-string}))
- '@var{symbol})
-@end group
-@end example
-
-The @code{defvar} form returns @var{symbol}, but it is normally used
-at top level in a file where its value does not matter.
-@end defspec
-
-@defspec defconst symbol value [doc-string]
-This special form defines @var{symbol} as a value and initializes it.
-It informs a person reading your code that @var{symbol} has a standard
-global value, established here, that should not be changed by the user
-or by other programs. Note that @var{symbol} is not evaluated; the
-symbol to be defined must appear explicitly in the @code{defconst}.
-
-@code{defconst} always evaluates @var{value}, and sets the value of
-@var{symbol} to the result. If @var{symbol} does have a buffer-local
-binding in the current buffer, @code{defconst} sets the default value,
-not the buffer-local value. (But you should not be making
-buffer-local bindings for a symbol that is defined with
-@code{defconst}.)
-
-Here, @code{pi} is a constant that presumably ought not to be changed
-by anyone (attempts by the Indiana State Legislature notwithstanding).
-As the second form illustrates, however, this is only advisory.
-
-@example
-@group
-(defconst pi 3.1415 "Pi to five places.")
- @result{} pi
-@end group
-@group
-(setq pi 3)
- @result{} pi
-@end group
-@group
-pi
- @result{} 3
-@end group
-@end example
-@end defspec
-
-@defun user-variable-p variable
-@cindex user option
-This function returns @code{t} if @var{variable} is a user option---a
-variable intended to be set by the user for customization---and
-@code{nil} otherwise. (Variables other than user options exist for the
-internal purposes of Lisp programs, and users need not know about them.)
-
-User option variables are distinguished from other variables either
-though being declared using @code{defcustom}@footnote{They may also be
-declared equivalently in @file{cus-start.el}.} or by the first character
-of their @code{variable-documentation} property. If the property exists
-and is a string, and its first character is @samp{*}, then the variable
-is a user option. Aliases of user options are also user options.
-@end defun
-
-@kindex variable-interactive
- If a user option variable has a @code{variable-interactive} property,
-the @code{set-variable} command uses that value to control reading the
-new value for the variable. The property's value is used as if it were
-specified in @code{interactive} (@pxref{Using Interactive}). However,
-this feature is largely obsoleted by @code{defcustom}
-(@pxref{Customization}).
-
- @strong{Warning:} If the @code{defconst} and @code{defvar} special
-forms are used while the variable has a local binding (made with
-@code{let}, or a function argument), they set the local-binding's
-value; the top-level binding is not changed. This is not what you
-usually want. To prevent it, use these special forms at top level in
-a file, where normally no local binding is in effect, and make sure to
-load the file before making a local binding for the variable.
-
-@node Tips for Defining
-@section Tips for Defining Variables Robustly
-
- When you define a variable whose value is a function, or a list of
-functions, use a name that ends in @samp{-function} or
-@samp{-functions}, respectively.
-
- There are several other variable name conventions;
-here is a complete list:
-
-@table @samp
-@item @dots{}-hook
-The variable is a normal hook (@pxref{Hooks}).
-
-@item @dots{}-function
-The value is a function.
-
-@item @dots{}-functions
-The value is a list of functions.
-
-@item @dots{}-form
-The value is a form (an expression).
-
-@item @dots{}-forms
-The value is a list of forms (expressions).
-
-@item @dots{}-predicate
-The value is a predicate---a function of one argument that returns
-non-@code{nil} for ``good'' arguments and @code{nil} for ``bad''
-arguments.
-
-@item @dots{}-flag
-The value is significant only as to whether it is @code{nil} or not.
-
-@item @dots{}-program
-The value is a program name.
-
-@item @dots{}-command
-The value is a whole shell command.
-
-@item @dots{}-switches
-The value specifies options for a command.
-@end table
-
- When you define a variable, always consider whether you should mark
-it as ``risky''; see @ref{File Local Variables}.
-
- When defining and initializing a variable that holds a complicated
-value (such as a keymap with bindings in it), it's best to put the
-entire computation of the value into the @code{defvar}, like this:
-
-@example
-(defvar my-mode-map
- (let ((map (make-sparse-keymap)))
- (define-key map "\C-c\C-a" 'my-command)
- @dots{}
- map)
- @var{docstring})
-@end example
-
-@noindent
-This method has several benefits. First, if the user quits while
-loading the file, the variable is either still uninitialized or
-initialized properly, never in-between. If it is still uninitialized,
-reloading the file will initialize it properly. Second, reloading the
-file once the variable is initialized will not alter it; that is
-important if the user has run hooks to alter part of the contents (such
-as, to rebind keys). Third, evaluating the @code{defvar} form with
-@kbd{C-M-x} @emph{will} reinitialize the map completely.
-
- Putting so much code in the @code{defvar} form has one disadvantage:
-it puts the documentation string far away from the line which names the
-variable. Here's a safe way to avoid that:
-
-@example
-(defvar my-mode-map nil
- @var{docstring})
-(unless my-mode-map
- (let ((map (make-sparse-keymap)))
- (define-key map "\C-c\C-a" 'my-command)
- @dots{}
- (setq my-mode-map map)))
-@end example
-
-@noindent
-This has all the same advantages as putting the initialization inside
-the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
-each form, if you do want to reinitialize the variable.
-
- But be careful not to write the code like this:
-
-@example
-(defvar my-mode-map nil
- @var{docstring})
-(unless my-mode-map
- (setq my-mode-map (make-sparse-keymap))
- (define-key my-mode-map "\C-c\C-a" 'my-command)
- @dots{})
-@end example
-
-@noindent
-This code sets the variable, then alters it, but it does so in more than
-one step. If the user quits just after the @code{setq}, that leaves the
-variable neither correctly initialized nor void nor @code{nil}. Once
-that happens, reloading the file will not initialize the variable; it
-will remain incomplete.
-
-@node Accessing Variables
-@section Accessing Variable Values
-
- The usual way to reference a variable is to write the symbol which
-names it (@pxref{Symbol Forms}). This requires you to specify the
-variable name when you write the program. Usually that is exactly what
-you want to do. Occasionally you need to choose at run time which
-variable to reference; then you can use @code{symbol-value}.
-
-@defun symbol-value symbol
-This function returns the value of @var{symbol}. This is the value in
-the innermost local binding of the symbol, or its global value if it
-has no local bindings.
-
-@example
-@group
-(setq abracadabra 5)
- @result{} 5
-@end group
-@group
-(setq foo 9)
- @result{} 9
-@end group
-
-@group
-;; @r{Here the symbol @code{abracadabra}}
-;; @r{is the symbol whose value is examined.}
-(let ((abracadabra 'foo))
- (symbol-value 'abracadabra))
- @result{} foo
-@end group
-
-@group
-;; @r{Here, the value of @code{abracadabra},}
-;; @r{which is @code{foo},}
-;; @r{is the symbol whose value is examined.}
-(let ((abracadabra 'foo))
- (symbol-value abracadabra))
- @result{} 9
-@end group
-
-@group
-(symbol-value 'abracadabra)
- @result{} 5
-@end group
-@end example
-
-A @code{void-variable} error is signaled if the current binding of
-@var{symbol} is void.
-@end defun
-
-@node Setting Variables
-@section How to Alter a Variable Value
-
- The usual way to change the value of a variable is with the special
-form @code{setq}. When you need to compute the choice of variable at
-run time, use the function @code{set}.
-
-@defspec setq [symbol form]@dots{}
-This special form is the most common method of changing a variable's
-value. Each @var{symbol} is given a new value, which is the result of
-evaluating the corresponding @var{form}. The most-local existing
-binding of the symbol is changed.
-
-@code{setq} does not evaluate @var{symbol}; it sets the symbol that you
-write. We say that this argument is @dfn{automatically quoted}. The
-@samp{q} in @code{setq} stands for ``quoted.''
-
-The value of the @code{setq} form is the value of the last @var{form}.
-
-@example
-@group
-(setq x (1+ 2))
- @result{} 3
-@end group
-x ; @r{@code{x} now has a global value.}
- @result{} 3
-@group
-(let ((x 5))
- (setq x 6) ; @r{The local binding of @code{x} is set.}
- x)
- @result{} 6
-@end group
-x ; @r{The global value is unchanged.}
- @result{} 3
-@end example
-
-Note that the first @var{form} is evaluated, then the first
-@var{symbol} is set, then the second @var{form} is evaluated, then the
-second @var{symbol} is set, and so on:
-
-@example
-@group
-(setq x 10 ; @r{Notice that @code{x} is set before}
- y (1+ x)) ; @r{the value of @code{y} is computed.}
- @result{} 11
-@end group
-@end example
-@end defspec
-
-@defun set symbol value
-This function sets @var{symbol}'s value to @var{value}, then returns
-@var{value}. Since @code{set} is a function, the expression written for
-@var{symbol} is evaluated to obtain the symbol to set.
-
-The most-local existing binding of the variable is the binding that is
-set; shadowed bindings are not affected.
-
-@example
-@group
-(set one 1)
-@error{} Symbol's value as variable is void: one
-@end group
-@group
-(set 'one 1)
- @result{} 1
-@end group
-@group
-(set 'two 'one)
- @result{} one
-@end group
-@group
-(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.}
- @result{} 2
-@end group
-@group
-one ; @r{So it is @code{one} that was set.}
- @result{} 2
-(let ((one 1)) ; @r{This binding of @code{one} is set,}
- (set 'one 3) ; @r{not the global value.}
- one)
- @result{} 3
-@end group
-@group
-one
- @result{} 2
-@end group
-@end example
-
-If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
-error is signaled.
-
-@example
-(set '(x y) 'z)
-@error{} Wrong type argument: symbolp, (x y)
-@end example
-
-Logically speaking, @code{set} is a more fundamental primitive than
-@code{setq}. Any use of @code{setq} can be trivially rewritten to use
-@code{set}; @code{setq} could even be defined as a macro, given the
-availability of @code{set}. However, @code{set} itself is rarely used;
-beginners hardly need to know about it. It is useful only for choosing
-at run time which variable to set. For example, the command
-@code{set-variable}, which reads a variable name from the user and then
-sets the variable, needs to use @code{set}.
-
-@cindex CL note---@code{set} local
-@quotation
-@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
-symbol's ``special'' or dynamic value, ignoring any lexical bindings.
-In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
-always affects the most local existing binding.
-@end quotation
-@end defun
-
-@node Variable Scoping
-@section Scoping Rules for Variable Bindings
-
- A given symbol @code{foo} can have several local variable bindings,
-established at different places in the Lisp program, as well as a global
-binding. The most recently established binding takes precedence over
-the others.
-
-@cindex scope
-@cindex extent
-@cindex dynamic scoping
-@cindex lexical scoping
- Local bindings in Emacs Lisp have @dfn{indefinite scope} and
-@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
-the source code the binding can be accessed. ``Indefinite scope'' means
-that any part of the program can potentially access the variable
-binding. @dfn{Extent} refers to @emph{when}, as the program is
-executing, the binding exists. ``Dynamic extent'' means that the binding
-lasts as long as the activation of the construct that established it.
-
- The combination of dynamic extent and indefinite scope is called
-@dfn{dynamic scoping}. By contrast, most programming languages use
-@dfn{lexical scoping}, in which references to a local variable must be
-located textually within the function or block that binds the variable.
-
-@cindex CL note---special variables
-@quotation
-@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
-dynamically scoped, like all variables in Emacs Lisp.
-@end quotation
-
-@menu
-* 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.
-@end menu
-
-@node Scope
-@subsection Scope
-
- Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
-This means that any function anywhere in the program text might access a
-given binding of a variable. Consider the following function
-definitions:
-
-@example
-@group
-(defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
- (foo 5)) ; @r{@code{foo} is some other function.}
-@end group
-
-@group
-(defun user () ; @r{@code{x} is used ``free'' in @code{user}.}
- (list x))
-@end group
-@end example
-
- In a lexically scoped language, the binding of @code{x} in
-@code{binder} would never be accessible in @code{user}, because
-@code{user} is not textually contained within the function
-@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user}
-may or may not refer to the binding of @code{x} established in
-@code{binder}, depending on the circumstances:
-
-@itemize @bullet
-@item
-If we call @code{user} directly without calling @code{binder} at all,
-then whatever binding of @code{x} is found, it cannot come from
-@code{binder}.
-
-@item
-If we define @code{foo} as follows and then call @code{binder}, then the
-binding made in @code{binder} will be seen in @code{user}:
-
-@example
-@group
-(defun foo (lose)
- (user))
-@end group
-@end example
-
-@item
-However, if we define @code{foo} as follows and then call @code{binder},
-then the binding made in @code{binder} @emph{will not} be seen in
-@code{user}:
-
-@example
-(defun foo (x)
- (user))
-@end example
-
-@noindent
-Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
-(The binding in @code{foo} is said to @dfn{shadow} the one made in
-@code{binder}.) Therefore, @code{user} will access the @code{x} bound
-by @code{foo} instead of the one bound by @code{binder}.
-@end itemize
-
-Emacs Lisp uses dynamic scoping because simple implementations of
-lexical scoping are slow. In addition, every Lisp system needs to offer
-dynamic scoping at least as an option; if lexical scoping is the norm,
-there must be a way to specify dynamic scoping instead for a particular
-variable. It might not be a bad thing for Emacs to offer both, but
-implementing it with dynamic scoping only was much easier.
-
-@node Extent
-@subsection Extent
-
- @dfn{Extent} refers to the time during program execution that a
-variable name is valid. In Emacs Lisp, a variable is valid only while
-the form that bound it is executing. This is called @dfn{dynamic
-extent}. ``Local'' or ``automatic'' variables in most languages,
-including C and Pascal, have dynamic extent.
-
- One alternative to dynamic extent is @dfn{indefinite extent}. This
-means that a variable binding can live on past the exit from the form
-that made the binding. Common Lisp and Scheme, for example, support
-this, but Emacs Lisp does not.
-
- To illustrate this, the function below, @code{make-add}, returns a
-function that purports to add @var{n} to its own argument @var{m}. This
-would work in Common Lisp, but it does not do the job in Emacs Lisp,
-because after the call to @code{make-add} exits, the variable @code{n}
-is no longer bound to the actual argument 2.
-
-@example
-(defun make-add (n)
- (function (lambda (m) (+ n m)))) ; @r{Return a function.}
- @result{} make-add
-(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
- ; @r{with @code{(make-add 2)}.}
- @result{} (lambda (m) (+ n m))
-(add2 4) ; @r{Try to add 2 to 4.}
-@error{} Symbol's value as variable is void: n
-@end example
-
-@cindex closures not available
- Some Lisp dialects have ``closures,'' objects that are like functions
-but record additional variable bindings. Emacs Lisp does not have
-closures.
-
-@node Impl of Scope
-@subsection Implementation of Dynamic Scoping
-@cindex deep binding
-
- A simple sample implementation (which is not how Emacs Lisp actually
-works) may help you understand dynamic binding. This technique is
-called @dfn{deep binding} and was used in early Lisp systems.
-
- Suppose there is a stack of bindings, which are variable-value pairs.
-At entry to a function or to a @code{let} form, we can push bindings
-onto the stack for the arguments or local variables created there. We
-can pop those bindings from the stack at exit from the binding
-construct.
-
- We can find the value of a variable by searching the stack from top to
-bottom for a binding for that variable; the value from that binding is
-the value of the variable. To set the variable, we search for the
-current binding, then store the new value into that binding.
-
- As you can see, a function's bindings remain in effect as long as it
-continues execution, even during its calls to other functions. That is
-why we say the extent of the binding is dynamic. And any other function
-can refer to the bindings, if it uses the same variables while the
-bindings are in effect. That is why we say the scope is indefinite.
-
-@cindex shallow binding
- The actual implementation of variable scoping in GNU Emacs Lisp uses a
-technique called @dfn{shallow binding}. Each variable has a standard
-place in which its current value is always found---the value cell of the
-symbol.
-
- In shallow binding, setting the variable works by storing a value in
-the value cell. Creating a new binding works by pushing the old value
-(belonging to a previous binding) onto a stack, and storing the new
-local value in the value cell. Eliminating a binding works by popping
-the old value off the stack, into the value cell.
-
- We use shallow binding because it has the same results as deep
-binding, but runs faster, since there is never a need to search for a
-binding.
-
-@node Using Scoping
-@subsection Proper Use of Dynamic Scoping
-
- Binding a variable in one function and using it in another is a
-powerful technique, but if used without restraint, it can make programs
-hard to understand. There are two clean ways to use this technique:
-
-@itemize @bullet
-@item
-Use or bind the variable only in a few related functions, written close
-together in one file. Such a variable is used for communication within
-one program.
-
-You should write comments to inform other programmers that they can see
-all uses of the variable before them, and to advise them not to add uses
-elsewhere.
-
-@item
-Give the variable a well-defined, documented meaning, and make all
-appropriate functions refer to it (but not bind it or set it) wherever
-that meaning is relevant. For example, the variable
-@code{case-fold-search} is defined as ``non-@code{nil} means ignore case
-when searching''; various search and replace functions refer to it
-directly or through their subroutines, but do not bind or set it.
-
-Then you can bind the variable in other programs, knowing reliably what
-the effect will be.
-@end itemize
-
- In either case, you should define the variable with @code{defvar}.
-This helps other people understand your program by telling them to look
-for inter-function usage. It also avoids a warning from the byte
-compiler. Choose the variable's name to avoid name conflicts---don't
-use short names like @code{x}.
-
-@node Buffer-Local Variables
-@section Buffer-Local Variables
-@cindex variable, buffer-local
-@cindex buffer-local variables
-
- Global and local variable bindings are found in most programming
-languages in one form or another. Emacs, however, also supports additional,
-unusual kinds of variable binding: @dfn{buffer-local} bindings, which
-apply only in one buffer, and @dfn{frame-local} bindings, which apply only in
-one frame. Having different values for a variable in different buffers
-and/or frames is an important customization method.
-
- This section describes buffer-local bindings; for frame-local
-bindings, see the following section, @ref{Frame-Local Variables}. (A few
-variables have bindings that are local to each terminal; see
-@ref{Multiple Displays}.)
-
-@menu
-* 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.
-@end menu
-
-@node Intro to Buffer-Local
-@subsection Introduction to Buffer-Local Variables
-
- A buffer-local variable has a buffer-local binding associated with a
-particular buffer. The binding is in effect when that buffer is
-current; otherwise, it is not in effect. If you set the variable while
-a buffer-local binding is in effect, the new value goes in that binding,
-so its other bindings are unchanged. This means that the change is
-visible only in the buffer where you made it.
-
- The variable's ordinary binding, which is not associated with any
-specific buffer, is called the @dfn{default binding}. In most cases,
-this is the global binding.
-
- A variable can have buffer-local bindings in some buffers but not in
-other buffers. The default binding is shared by all the buffers that
-don't have their own bindings for the variable. (This includes all
-newly-created buffers.) If you set the variable in a buffer that does
-not have a buffer-local binding for it, this sets the default binding
-(assuming there are no frame-local bindings to complicate the matter),
-so the new value is visible in all the buffers that see the default
-binding.
-
- The most common use of buffer-local bindings is for major modes to change
-variables that control the behavior of commands. For example, C mode and
-Lisp mode both set the variable @code{paragraph-start} to specify that only
-blank lines separate paragraphs. They do this by making the variable
-buffer-local in the buffer that is being put into C mode or Lisp mode, and
-then setting it to the new value for that mode. @xref{Major Modes}.
-
- The usual way to make a buffer-local binding is with
-@code{make-local-variable}, which is what major mode commands typically
-use. This affects just the current buffer; all other buffers (including
-those yet to be created) will continue to share the default value unless
-they are explicitly given their own buffer-local bindings.
-
-@cindex automatically buffer-local
- A more powerful operation is to mark the variable as
-@dfn{automatically buffer-local} by calling
-@code{make-variable-buffer-local}. You can think of this as making the
-variable local in all buffers, even those yet to be created. More
-precisely, the effect is that setting the variable automatically makes
-the variable local to the current buffer if it is not already so. All
-buffers start out by sharing the default value of the variable as usual,
-but setting the variable creates a buffer-local binding for the current
-buffer. The new value is stored in the buffer-local binding, leaving
-the default binding untouched. This means that the default value cannot
-be changed with @code{setq} in any buffer; the only way to change it is
-with @code{setq-default}.
-
- @strong{Warning:} When a variable has buffer-local or frame-local
-bindings in one or more buffers, @code{let} rebinds the binding that's
-currently in effect. For instance, if the current buffer has a
-buffer-local value, @code{let} temporarily rebinds that. If no
-buffer-local or frame-local bindings are in effect, @code{let} rebinds
-the default value. If inside the @code{let} you then change to a
-different current buffer in which a different binding is in effect,
-you won't see the @code{let} binding any more. And if you exit the
-@code{let} while still in the other buffer, you won't see the
-unbinding occur (though it will occur properly). Here is an example
-to illustrate:
-
-@example
-@group
-(setq foo 'g)
-(set-buffer "a")
-(make-local-variable 'foo)
-@end group
-(setq foo 'a)
-(let ((foo 'temp))
- ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}}
- (set-buffer "b")
- ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}}
- @var{body}@dots{})
-@group
-foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},}
- ; @r{but we don't see that in buffer @samp{b}}
-@end group
-@group
-(set-buffer "a") ; @r{verify the local value was restored}
-foo @result{} 'a
-@end group
-@end example
-
- Note that references to @code{foo} in @var{body} access the
-buffer-local binding of buffer @samp{b}.
-
- When a file specifies local variable values, these become buffer-local
-values when you visit the file. @xref{File Variables,,, emacs, The
-GNU Emacs Manual}.
-
-@node Creating Buffer-Local
-@subsection Creating and Deleting Buffer-Local Bindings
-
-@deffn Command make-local-variable variable
-This function creates a buffer-local binding in the current buffer for
-@var{variable} (a symbol). Other buffers are not affected. The value
-returned is @var{variable}.
-
-@c Emacs 19 feature
-The buffer-local value of @var{variable} starts out as the same value
-@var{variable} previously had. If @var{variable} was void, it remains
-void.
-
-@example
-@group
-;; @r{In buffer @samp{b1}:}
-(setq foo 5) ; @r{Affects all buffers.}
- @result{} 5
-@end group
-@group
-(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
- @result{} foo
-@end group
-@group
-foo ; @r{That did not change}
- @result{} 5 ; @r{the value.}
-@end group
-@group
-(setq foo 6) ; @r{Change the value}
- @result{} 6 ; @r{in @samp{b1}.}
-@end group
-@group
-foo
- @result{} 6
-@end group
-
-@group
-;; @r{In buffer @samp{b2}, the value hasn't changed.}
-(save-excursion
- (set-buffer "b2")
- foo)
- @result{} 5
-@end group
-@end example
-
-Making a variable buffer-local within a @code{let}-binding for that
-variable does not work reliably, unless the buffer in which you do this
-is not current either on entry to or exit from the @code{let}. This is
-because @code{let} does not distinguish between different kinds of
-bindings; it knows only which variable the binding was made for.
-
-If the variable is terminal-local, this function signals an error. Such
-variables cannot have buffer-local bindings as well. @xref{Multiple
-Displays}.
-
-@strong{Warning:} do not use @code{make-local-variable} for a hook
-variable. The hook variables are automatically made buffer-local as
-needed if you use the @var{local} argument to @code{add-hook} or
-@code{remove-hook}.
-@end deffn
-
-@deffn Command make-variable-buffer-local variable
-This function marks @var{variable} (a symbol) automatically
-buffer-local, so that any subsequent attempt to set it will make it
-local to the current buffer at the time.
-
-A peculiar wrinkle of this feature is that binding the variable (with
-@code{let} or other binding constructs) does not create a buffer-local
-binding for it. Only setting the variable (with @code{set} or
-@code{setq}), while the variable does not have a @code{let}-style
-binding that was made in the current buffer, does so.
-
-If @var{variable} does not have a default value, then calling this
-command will give it a default value of @code{nil}. If @var{variable}
-already has a default value, that value remains unchanged.
-Subsequently calling @code{makunbound} on @var{variable} will result
-in a void buffer-local value and leave the default value unaffected.
-
-The value returned is @var{variable}.
-
-@strong{Warning:} Don't assume that you should use
-@code{make-variable-buffer-local} for user-option variables, simply
-because users @emph{might} want to customize them differently in
-different buffers. Users can make any variable local, when they wish
-to. It is better to leave the choice to them.
-
-The time to use @code{make-variable-buffer-local} is when it is crucial
-that no two buffers ever share the same binding. For example, when a
-variable is used for internal purposes in a Lisp program which depends
-on having separate values in separate buffers, then using
-@code{make-variable-buffer-local} can be the best solution.
-@end deffn
-
-@defun local-variable-p variable &optional buffer
-This returns @code{t} if @var{variable} is buffer-local in buffer
-@var{buffer} (which defaults to the current buffer); otherwise,
-@code{nil}.
-@end defun
-
-@defun local-variable-if-set-p variable &optional buffer
-This returns @code{t} if @var{variable} will become buffer-local in
-buffer @var{buffer} (which defaults to the current buffer) if it is
-set there.
-@end defun
-
-@defun buffer-local-value variable buffer
-This function returns the buffer-local binding of @var{variable} (a
-symbol) in buffer @var{buffer}. If @var{variable} does not have a
-buffer-local binding in buffer @var{buffer}, it returns the default
-value (@pxref{Default Value}) of @var{variable} instead.
-@end defun
-
-@defun buffer-local-variables &optional buffer
-This function returns a list describing the buffer-local variables in
-buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
-used.) It returns an association list (@pxref{Association Lists}) in
-which each element contains one buffer-local variable and its value.
-However, when a variable's buffer-local binding in @var{buffer} is void,
-then the variable appears directly in the resulting list.
-
-@example
-@group
-(make-local-variable 'foobar)
-(makunbound 'foobar)
-(make-local-variable 'bind-me)
-(setq bind-me 69)
-@end group
-(setq lcl (buffer-local-variables))
- ;; @r{First, built-in variables local in all buffers:}
-@result{} ((mark-active . nil)
- (buffer-undo-list . nil)
- (mode-name . "Fundamental")
- @dots{}
-@group
- ;; @r{Next, non-built-in buffer-local variables.}
- ;; @r{This one is buffer-local and void:}
- foobar
- ;; @r{This one is buffer-local and nonvoid:}
- (bind-me . 69))
-@end group
-@end example
-
-Note that storing new values into the @sc{cdr}s of cons cells in this
-list does @emph{not} change the buffer-local values of the variables.
-@end defun
-
-@deffn Command kill-local-variable variable
-This function deletes the buffer-local binding (if any) for
-@var{variable} (a symbol) in the current buffer. As a result, the
-default binding of @var{variable} becomes visible in this buffer. This
-typically results in a change in the value of @var{variable}, since the
-default value is usually different from the buffer-local value just
-eliminated.
-
-If you kill the buffer-local binding of a variable that automatically
-becomes buffer-local when set, this makes the default value visible in
-the current buffer. However, if you set the variable again, that will
-once again create a buffer-local binding for it.
-
-@code{kill-local-variable} returns @var{variable}.
-
-This function is a command because it is sometimes useful to kill one
-buffer-local variable interactively, just as it is useful to create
-buffer-local variables interactively.
-@end deffn
-
-@defun kill-all-local-variables
-This function eliminates all the buffer-local variable bindings of the
-current buffer except for variables marked as ``permanent.'' As a
-result, the buffer will see the default values of most variables.
-
-This function also resets certain other information pertaining to the
-buffer: it sets the local keymap to @code{nil}, the syntax table to the
-value of @code{(standard-syntax-table)}, the case table to
-@code{(standard-case-table)}, and the abbrev table to the value of
-@code{fundamental-mode-abbrev-table}.
-
-The very first thing this function does is run the normal hook
-@code{change-major-mode-hook} (see below).
-
-Every major mode command begins by calling this function, which has the
-effect of switching to Fundamental mode and erasing most of the effects
-of the previous major mode. To ensure that this does its job, the
-variables that major modes set should not be marked permanent.
-
-@code{kill-all-local-variables} returns @code{nil}.
-@end defun
-
-@defvar change-major-mode-hook
-The function @code{kill-all-local-variables} runs this normal hook
-before it does anything else. This gives major modes a way to arrange
-for something special to be done if the user switches to a different
-major mode. It is also useful for buffer-specific minor modes
-that should be forgotten if the user changes the major mode.
-
-For best results, make this variable buffer-local, so that it will
-disappear after doing its job and will not interfere with the
-subsequent major mode. @xref{Hooks}.
-@end defvar
-
-@c Emacs 19 feature
-@cindex permanent local variable
-A buffer-local variable is @dfn{permanent} if the variable name (a
-symbol) has a @code{permanent-local} property that is non-@code{nil}.
-Permanent locals are appropriate for data pertaining to where the file
-came from or how to save it, rather than with how to edit the contents.
-
-@node Default Value
-@subsection The Default Value of a Buffer-Local Variable
-@cindex default value
-
- The global value of a variable with buffer-local bindings is also
-called the @dfn{default} value, because it is the value that is in
-effect whenever neither the current buffer nor the selected frame has
-its own binding for the variable.
-
- The functions @code{default-value} and @code{setq-default} access and
-change a variable's default value regardless of whether the current
-buffer has a buffer-local binding. For example, you could use
-@code{setq-default} to change the default setting of
-@code{paragraph-start} for most buffers; and this would work even when
-you are in a C or Lisp mode buffer that has a buffer-local value for
-this variable.
-
-@c Emacs 19 feature
- The special forms @code{defvar} and @code{defconst} also set the
-default value (if they set the variable at all), rather than any
-buffer-local or frame-local value.
-
-@defun default-value symbol
-This function returns @var{symbol}'s default value. This is the value
-that is seen in buffers and frames that do not have their own values for
-this variable. If @var{symbol} is not buffer-local, this is equivalent
-to @code{symbol-value} (@pxref{Accessing Variables}).
-@end defun
-
-@c Emacs 19 feature
-@defun default-boundp symbol
-The function @code{default-boundp} tells you whether @var{symbol}'s
-default value is nonvoid. If @code{(default-boundp 'foo)} returns
-@code{nil}, then @code{(default-value 'foo)} would get an error.
-
-@code{default-boundp} is to @code{default-value} as @code{boundp} is to
-@code{symbol-value}.
-@end defun
-
-@defspec setq-default [symbol form]@dots{}
-This special form gives each @var{symbol} a new default value, which is
-the result of evaluating the corresponding @var{form}. It does not
-evaluate @var{symbol}, but does evaluate @var{form}. The value of the
-@code{setq-default} form is the value of the last @var{form}.
-
-If a @var{symbol} is not buffer-local for the current buffer, and is not
-marked automatically buffer-local, @code{setq-default} has the same
-effect as @code{setq}. If @var{symbol} is buffer-local for the current
-buffer, then this changes the value that other buffers will see (as long
-as they don't have a buffer-local value), but not the value that the
-current buffer sees.
-
-@example
-@group
-;; @r{In buffer @samp{foo}:}
-(make-local-variable 'buffer-local)
- @result{} buffer-local
-@end group
-@group
-(setq buffer-local 'value-in-foo)
- @result{} value-in-foo
-@end group
-@group
-(setq-default buffer-local 'new-default)
- @result{} new-default
-@end group
-@group
-buffer-local
- @result{} value-in-foo
-@end group
-@group
-(default-value 'buffer-local)
- @result{} new-default
-@end group
-
-@group
-;; @r{In (the new) buffer @samp{bar}:}
-buffer-local
- @result{} new-default
-@end group
-@group
-(default-value 'buffer-local)
- @result{} new-default
-@end group
-@group
-(setq buffer-local 'another-default)
- @result{} another-default
-@end group
-@group
-(default-value 'buffer-local)
- @result{} another-default
-@end group
-
-@group
-;; @r{Back in buffer @samp{foo}:}
-buffer-local
- @result{} value-in-foo
-(default-value 'buffer-local)
- @result{} another-default
-@end group
-@end example
-@end defspec
-
-@defun set-default symbol value
-This function is like @code{setq-default}, except that @var{symbol} is
-an ordinary evaluated argument.
-
-@example
-@group
-(set-default (car '(a b c)) 23)
- @result{} 23
-@end group
-@group
-(default-value 'a)
- @result{} 23
-@end group
-@end example
-@end defun
-
-@node Frame-Local Variables
-@section Frame-Local Variables
-@cindex frame-local variables
-
- Just as variables can have buffer-local bindings, they can also have
-frame-local bindings. These bindings belong to one frame, and are in
-effect when that frame is selected. Frame-local bindings are actually
-frame parameters: you create a frame-local binding in a specific frame
-by calling @code{modify-frame-parameters} and specifying the variable
-name as the parameter name.
-
- To enable frame-local bindings for a certain variable, call the function
-@code{make-variable-frame-local}.
-
-@deffn Command make-variable-frame-local variable
-Enable the use of frame-local bindings for @var{variable}. This does
-not in itself create any frame-local bindings for the variable; however,
-if some frame already has a value for @var{variable} as a frame
-parameter, that value automatically becomes a frame-local binding.
-
-If @var{variable} does not have a default value, then calling this
-command will give it a default value of @code{nil}. If @var{variable}
-already has a default value, that value remains unchanged.
-
-If the variable is terminal-local, this function signals an error,
-because such variables cannot have frame-local bindings as well.
-@xref{Multiple Displays}. A few variables that are implemented
-specially in Emacs can be buffer-local, but can never be frame-local.
-
-This command returns @var{variable}.
-@end deffn
-
- Buffer-local bindings take precedence over frame-local bindings. Thus,
-consider a variable @code{foo}: if the current buffer has a buffer-local
-binding for @code{foo}, that binding is active; otherwise, if the
-selected frame has a frame-local binding for @code{foo}, that binding is
-active; otherwise, the default binding of @code{foo} is active.
-
- Here is an example. First we prepare a few bindings for @code{foo}:
-
-@example
-(setq f1 (selected-frame))
-(make-variable-frame-local 'foo)
-
-;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
-(set-buffer (get-buffer-create "b1"))
-(make-local-variable 'foo)
-(setq foo '(b 1))
-
-;; @r{Make a frame-local binding for @code{foo} in a new frame.}
-;; @r{Store that frame in @code{f2}.}
-(setq f2 (make-frame))
-(modify-frame-parameters f2 '((foo . (f 2))))
-@end example
-
- Now we examine @code{foo} in various contexts. Whenever the
-buffer @samp{b1} is current, its buffer-local binding is in effect,
-regardless of the selected frame:
-
-@example
-(select-frame f1)
-(set-buffer (get-buffer-create "b1"))
-foo
- @result{} (b 1)
-
-(select-frame f2)
-(set-buffer (get-buffer-create "b1"))
-foo
- @result{} (b 1)
-@end example
-
-@noindent
-Otherwise, the frame gets a chance to provide the binding; when frame
-@code{f2} is selected, its frame-local binding is in effect:
-
-@example
-(select-frame f2)
-(set-buffer (get-buffer "*scratch*"))
-foo
- @result{} (f 2)
-@end example
-
-@noindent
-When neither the current buffer nor the selected frame provides
-a binding, the default binding is used:
-
-@example
-(select-frame f1)
-(set-buffer (get-buffer "*scratch*"))
-foo
- @result{} nil
-@end example
-
-@noindent
-When the active binding of a variable is a frame-local binding, setting
-the variable changes that binding. You can observe the result with
-@code{frame-parameters}:
-
-@example
-(select-frame f2)
-(set-buffer (get-buffer "*scratch*"))
-(setq foo 'nobody)
-(assq 'foo (frame-parameters f2))
- @result{} (foo . nobody)
-@end example
-
-@node Future Local Variables
-@section Possible Future Local Variables
-
- We have considered the idea of bindings that are local to a category
-of frames---for example, all color frames, or all frames with dark
-backgrounds. We have not implemented them because it is not clear that
-this feature is really useful. You can get more or less the same
-results by adding a function to @code{after-make-frame-functions}, set up to
-define a particular frame parameter according to the appropriate
-conditions for each frame.
-
- It would also be possible to implement window-local bindings. We
-don't know of many situations where they would be useful, and it seems
-that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
-bindings offer a way to handle these situations more robustly.
-
- If sufficient application is found for either of these two kinds of
-local bindings, we will provide it in a subsequent Emacs version.
-
-@node File Local Variables
-@section File Local Variables
-@cindex file local variables
-
- A file can specify local variable values; Emacs uses these to create
-buffer-local bindings for those variables in the buffer visiting that
-file. @xref{File variables, , Local Variables in Files, emacs, The
-GNU Emacs Manual}, for basic information about file local variables.
-This section describes the functions and variables that affect
-processing of file local variables.
-
-@defopt enable-local-variables
-This variable controls whether to process file local variables.
-The possible values are:
-
-@table @asis
-@item @code{t} (the default)
-Set the safe variables, and query (once) about any unsafe variables.
-@item @code{:safe}
-Set only the safe variables and do not query.
-@item @code{:all}
-Set all the variables and do not query.
-@item @code{nil}
-Don't set any variables.
-@item anything else
-Query (once) about all the variables.
-@end table
-@end defopt
-
-@defun hack-local-variables &optional mode-only
-This function parses, and binds or evaluates as appropriate, any local
-variables specified by the contents of the current buffer. The variable
-@code{enable-local-variables} has its effect here. However, this
-function does not look for the @samp{mode:} local variable in the
-@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking
-@code{enable-local-variables} into account (@pxref{Auto Major Mode}).
-
-If the optional argument @var{mode-only} is non-@code{nil}, then all
-this function does is return @code{t} if the @w{@samp{-*-}} line or
-the local variables list specifies a mode and @code{nil} otherwise.
-It does not set the mode nor any other file local variable.
-@end defun
-
- If a file local variable could specify a function that would
-be called later, or an expression that would be executed later, simply
-visiting a file could take over your Emacs. Emacs takes several
-measures to prevent this.
-
-@cindex safe local variable
- You can specify safe values for a variable with a
-@code{safe-local-variable} property. The property has to be
-a function of one argument; any value is safe if the function
-returns non-@code{nil} given that value. Many commonly encountered
-file variables standardly have @code{safe-local-variable} properties,
-including @code{fill-column}, @code{fill-prefix}, and
-@code{indent-tabs-mode}. For boolean-valued variables that are safe,
-use @code{booleanp} as the property value. Lambda expressions should
-be quoted so that @code{describe-variable} can display the predicate.
-
-@defopt safe-local-variable-values
-This variable provides another way to mark some variable values as
-safe. It is a list of cons cells @code{(@var{var} . @var{val})},
-where @var{var} is a variable name and @var{val} is a value which is
-safe for that variable.
-
-When Emacs asks the user whether or not to obey a set of file local
-variable specifications, the user can choose to mark them as safe.
-Doing so adds those variable/value pairs to
-@code{safe-local-variable-values}, and saves it to the user's custom
-file.
-@end defopt
-
-@defun safe-local-variable-p sym val
-This function returns non-@code{nil} if it is safe to give @var{sym}
-the value @var{val}, based on the above criteria.
-@end defun
-
-@c @cindex risky local variable Duplicates risky-local-variable
- Some variables are considered @dfn{risky}. A variable whose name
-ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function},
-@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
-@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
-@samp{-program}, or @samp{-predicate} is considered risky. The
-variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
-followed by a digit, and @samp{font-lock-syntactic-keywords} are also
-considered risky. Finally, any variable whose name has a
-non-@code{nil} @code{risky-local-variable} property is considered
-risky.
-
-@defun risky-local-variable-p sym
-This function returns non-@code{nil} if @var{sym} is a risky variable,
-based on the above criteria.
-@end defun
-
- If a variable is risky, it will not be entered automatically into
-@code{safe-local-variable-values} as described above. Therefore,
-Emacs will always query before setting a risky variable, unless the
-user explicitly allows the setting by customizing
-@code{safe-local-variable-values} directly.
-
-@defvar ignored-local-variables
-This variable holds a list of variables that should not be given local
-values by files. Any value specified for one of these variables is
-completely ignored.
-@end defvar
-
- The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
-normally asks for confirmation before handling it.
-
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in @samp{-*-} lines
-or local variables
-lists in files being visited. A value of @code{t} means process them
-unconditionally; @code{nil} means ignore them; anything else means ask
-the user what to do for each file. The default value is @code{maybe}.
-@end defopt
-
-@defopt safe-local-eval-forms
-This variable holds a list of expressions that are safe to
-evaluate when found in the @samp{Eval:} ``variable'' in a file
-local variables list.
-@end defopt
-
- If the expression is a function call and the function has a
-@code{safe-local-eval-function} property, the property value
-determines whether the expression is safe to evaluate. The property
-value can be a predicate to call to test the expression, a list of
-such predicates (it's safe if any predicate succeeds), or @code{t}
-(always safe provided the arguments are constant).
-
- Text properties are also potential loopholes, since their values
-could include functions to call. So Emacs discards all text
-properties from string values specified for file local variables.
-
-@node Variable Aliases
-@section Variable Aliases
-@cindex variable aliases
-
- It is sometimes useful to make two variables synonyms, so that both
-variables always have the same value, and changing either one also
-changes the other. Whenever you change the name of a
-variable---either because you realize its old name was not well
-chosen, or because its meaning has partly changed---it can be useful
-to keep the old name as an @emph{alias} of the new one for
-compatibility. You can do this with @code{defvaralias}.
-
-@defun defvaralias new-alias base-variable &optional docstring
-This function defines the symbol @var{new-alias} as a variable alias
-for symbol @var{base-variable}. This means that retrieving the value
-of @var{new-alias} returns the value of @var{base-variable}, and
-changing the value of @var{new-alias} changes the value of
-@var{base-variable}. The two aliased variable names always share the
-same value and the same bindings.
-
-If the @var{docstring} argument is non-@code{nil}, it specifies the
-documentation for @var{new-alias}; otherwise, the alias gets the same
-documentation as @var{base-variable} has, if any, unless
-@var{base-variable} is itself an alias, in which case @var{new-alias} gets
-the documentation of the variable at the end of the chain of aliases.
-
-This function returns @var{base-variable}.
-@end defun
-
- Variable aliases are convenient for replacing an old name for a
-variable with a new name. @code{make-obsolete-variable} declares that
-the old name is obsolete and therefore that it may be removed at some
-stage in the future.
-
-@defun make-obsolete-variable obsolete-name current-name &optional when
-This function makes the byte-compiler warn that the variable
-@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is
-the variable's new name; then the warning message says to use
-@var{current-name} instead of @var{obsolete-name}. If @var{current-name}
-is a string, this is the message and there is no replacement variable.
-
-If provided, @var{when} should be a string indicating when the
-variable was first made obsolete---for example, a date or a release
-number.
-@end defun
-
- You can make two variables synonyms and declare one obsolete at the
-same time using the macro @code{define-obsolete-variable-alias}.
-
-@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring
-This macro marks the variable @var{obsolete-name} as obsolete and also
-makes it an alias for the variable @var{current-name}. It is
-equivalent to the following:
-
-@example
-(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
-(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
-@end example
-@end defmac
-
-@defun indirect-variable variable
-This function returns the variable at the end of the chain of aliases
-of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is
-not defined as an alias, the function returns @var{variable}.
-
-This function signals a @code{cyclic-variable-indirection} error if
-there is a loop in the chain of symbols.
-@end defun
-
-@example
-(defvaralias 'foo 'bar)
-(indirect-variable 'foo)
- @result{} bar
-(indirect-variable 'bar)
- @result{} bar
-(setq bar 2)
-bar
- @result{} 2
-@group
-foo
- @result{} 2
-@end group
-(setq foo 0)
-bar
- @result{} 0
-foo
- @result{} 0
-@end example
-
-@node Variables with Restricted Values
-@section Variables with Restricted Values
-
- Ordinary Lisp variables can be assigned any value that is a valid
-Lisp object. However, certain Lisp variables are not defined in Lisp,
-but in C. Most of these variables are defined in the C code using
-@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on
-any value. However, some variables are defined using
-@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp
-variables in C,, Writing Emacs Primitives}, in particular the
-description of functions of the type @code{syms_of_@var{filename}},
-for a brief discussion of the C implementation.
-
- Variables of type @code{DEFVAR_BOOL} can only take on the values
-@code{nil} or @code{t}. Attempting to assign them any other value
-will set them to @code{t}:
-
-@example
-(let ((display-hourglass 5))
- display-hourglass)
- @result{} t
-@end example
-
-@defvar byte-boolean-vars
-This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
-@end defvar
-
- Variables of type @code{DEFVAR_INT} can only take on integer values.
-Attempting to assign them any other value will result in an error:
-
-@example
-(setq window-min-height 5.0)
-@error{} Wrong type argument: integerp, 5.0
-@end example
-
-@ignore
- arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c This file is used for printing the GNU Emacs Lisp Reference Manual
-@c in two volumes. It is a modified version of elisp.texi.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c %**start of header
-@setfilename elisp
-@settitle GNU Emacs Lisp Reference Manual: Volume 1
-@c %**end of header
-
-@c See two-volume-cross-refs.txt.
-@tex
-\message{Formatting for two volume edition...Volume 1...}
-%
-% Read special toc file, set up in two-volume.make.
-\gdef\tocreadfilename{elisp1-toc-ready.toc}
-%
-% Don't make outlines, they're not needed and \readdatafile can't pay
-% attention to the special definition above.
-\global\let\pdfmakeoutlines=\relax
-%
-% Start volume 1 chapter numbering at 1; this must be listed as chapno0.
-\global\chapno=0
-@end tex
-
-@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 22
-
-@dircategory Emacs
-@direntry
-* Elisp: (elisp). The Emacs Lisp Reference Manual.
-@end direntry
-
-@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.
-@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
-\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
-
-@titlepage
-@title GNU Emacs Lisp Reference Manual
-@subtitle Volume 1
-@subtitle For Emacs Version @value{EMACSVER}
-@subtitle Revision @value{VERSION}, June 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.
-* 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.
-* Saving Properties:: Saving text properties in files, and reading
- them back.
-* 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
-
-@c ================ Beginning of Volume 2 ================
-@c include buffers.texi
-@c include windows.texi
-@c include frames.texi
-
-@c include positions.texi
-@c include markers.texi
-@c include text.texi
-@c include nonascii.texi
-
-@c include searching.texi
-@c include syntax.texi
-@c include abbrevs.texi
-@c include processes.texi
-
-@c include display.texi
-@c include os.texi
-
-@c MOVE to Emacs Manual: include misc-modes.texi
-
-@c appendices
-
-@c REMOVE this: include non-hacker.texi
-
-@c include anti.texi
-@c include doclicense.texi
-@c include gpl.texi
-@c include tips.texi
-@c include internals.texi
-@c include errors.texi
-@c include locals.texi
-@c include maps.texi
-@c include hooks.texi
-
-@include index.texi
-
-@ignore
-@node New Symbols, , Index, Top
-@unnumbered New Symbols Since the Previous Edition
-
-@printindex tp
-@end ignore
-
-@bye
-
-\f
-These words prevent "local variables" above from confusing Emacs.
-
-@ignore
- arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2
-@end ignore
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c This file is used for printing the GNU Emacs Lisp Reference Manual
-@c in two volumes. It is a modified version of elisp.texi.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c %**start of header
-@setfilename elisp
-@settitle GNU Emacs Lisp Reference Manual: Volume 2
-@c %**end of header
-
-@c See two-volume-cross-refs.txt.
-@tex
-\message{Formatting for two volume edition...Volume 2...}
-%
-% Read special toc file, set up in two-volume.make.
-\gdef\tocreadfilename{elisp2-toc-ready.toc}
-%
-% Don't make outlines, they're not needed and \readdatafile can't pay
-% attention to the special definition above.
-\global\let\pdfmakeoutlines=\relax
-%
-% Start volume 2 chapter numbering at 27; this must be listed as chapno26
-\global\chapno=26
-@end tex
-
-@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 22
-
-@dircategory Emacs
-@direntry
-* Elisp: (elisp). The Emacs Lisp Reference Manual.
-@end direntry
-
-@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.
-@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
-\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
-
-@titlepage
-@title GNU Emacs Lisp Reference Manual
-@subtitle Volume 2
-@subtitle For Emacs Version @value{EMACSVER}
-@subtitle Revision @value{VERSION}, June 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.
-* 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.
-* Saving Properties:: Saving text properties in files, and reading
- them back.
-* 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
-
-@c include intro.texi
-@c include objects.texi
-@c include numbers.texi
-@c include strings.texi
-
-@c include lists.texi
-@c include sequences.texi
-@c include hash.texi
-@c include symbols.texi
-@c include eval.texi
-
-@c include control.texi
-@c include variables.texi
-@c include functions.texi
-@c include macros.texi
-
-@c include customize.texi
-@c include loading.texi
-@c include compile.texi
-@c include advice.texi
-
-@c include debugging.texi
-@c include streams.texi
-@c include minibuf.texi
-@c include commands.texi
-
-@c include keymaps.texi
-@c include modes.texi
-@c include help.texi
-@c include files.texi
-
-@c include backups.texi
-
-@c ================ Beginning of Volume 2 ================
-@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
-
-\f
-These words prevent "local variables" above from confusing Emacs.
-
-@ignore
- arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849
-@end ignore
+++ /dev/null
-@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,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/windows
-@node Windows, Frames, Buffers, Top
-@chapter Windows
-
- This chapter describes most of the functions and variables related to
-Emacs windows. See @ref{Display}, for information on how text is
-displayed in windows.
-
-@menu
-* 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.
-@end menu
-
-@node Basic Windows
-@section Basic Concepts of Emacs Windows
-@cindex window
-@cindex selected window
-
- A @dfn{window} in Emacs is the physical area of the screen in which a
-buffer is displayed. The term is also used to refer to a Lisp object that
-represents that screen area in Emacs Lisp. It should be
-clear from the context which is meant.
-
- Emacs groups windows into frames. A frame represents an area of
-screen available for Emacs to use. Each frame always contains at least
-one window, but you can subdivide it vertically or horizontally into
-multiple nonoverlapping Emacs windows.
-
- In each frame, at any time, one and only one window is designated as
-@dfn{selected within the frame}. The frame's cursor appears in that
-window, but the other windows have ``non-selected'' cursors, normally
-less visible. At any time, one frame is the selected frame; and the
-window selected within that frame is @dfn{the selected window}. The
-selected window's buffer is usually the current buffer (except when
-@code{set-buffer} has been used). @xref{Current Buffer}.
-
-@defvar cursor-in-non-selected-windows
-If this variable is @code{nil}, Emacs displays only one cursor,
-in the selected window. Other windows have no cursor at all.
-@end defvar
-
- For practical purposes, a window exists only while it is displayed in
-a frame. Once removed from the frame, the window is effectively deleted
-and should not be used, @emph{even though there may still be references
-to it} from other Lisp objects. Restoring a saved window configuration
-is the only way for a window no longer on the screen to come back to
-life. (@xref{Deleting Windows}.)
-
- Each window has the following attributes:
-
-@itemize @bullet
-@item
-containing frame
-
-@item
-window height
-
-@item
-window width
-
-@item
-window edges with respect to the screen or frame
-
-@item
-the buffer it displays
-
-@item
-position within the buffer at the upper left of the window
-
-@item
-amount of horizontal scrolling, in columns
-
-@item
-point
-
-@item
-the mark
-
-@item
-how recently the window was selected
-
-@item
-fringe settings
-
-@item
-display margins
-
-@item
-scroll-bar settings
-@end itemize
-
-@cindex multiple windows
- Users create multiple windows so they can look at several buffers at
-once. Lisp libraries use multiple windows for a variety of reasons, but
-most often to display related information. In Rmail, for example, you
-can move through a summary buffer in one window while the other window
-shows messages one at a time as they are reached.
-
- The meaning of ``window'' in Emacs is similar to what it means in the
-context of general-purpose window systems such as X, but not identical.
-The X Window System places X windows on the screen; Emacs uses one or
-more X windows as frames, and subdivides them into
-Emacs windows. When you use Emacs on a character-only terminal, Emacs
-treats the whole terminal screen as one frame.
-
-@cindex terminal screen
-@cindex screen of terminal
-@cindex tiled windows
- Most window systems support arbitrarily located overlapping windows.
-In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
-together they fill the whole screen or frame. Because of the way in
-which Emacs creates new windows and resizes them, not all conceivable
-tilings of windows on an Emacs frame are actually possible.
-@xref{Splitting Windows}, and @ref{Size of Window}.
-
- @xref{Display}, for information on how the contents of the
-window's buffer are displayed in the window.
-
-@defun windowp object
-This function returns @code{t} if @var{object} is a window.
-@end defun
-
-@node Splitting Windows
-@section Splitting Windows
-@cindex splitting windows
-@cindex window splitting
-
- The functions described here are the primitives used to split a window
-into two windows. Two higher level functions sometimes split a window,
-but not always: @code{pop-to-buffer} and @code{display-buffer}
-(@pxref{Displaying Buffers}).
-
- The functions described here do not accept a buffer as an argument.
-The two ``halves'' of the split window initially display the same buffer
-previously visible in the window that was split.
-
-@deffn Command split-window &optional window size horizontal
-This function splits a new window out of @var{window}'s screen area.
-It returns the new window.
-
-If @var{horizontal} is non-@code{nil}, then @var{window} splits into
-two side by side windows. The original window @var{window} keeps the
-leftmost @var{size} columns, and gives the rest of the columns to the
-new window. Otherwise, it splits into windows one above the other, and
-@var{window} keeps the upper @var{size} lines and gives the rest of the
-lines to the new window. The original window is therefore the
-left-hand or upper of the two, and the new window is the right-hand or
-lower.
-
-If @var{window} is omitted or @code{nil}, that stands for the selected
-window. When you split the selected window, it remains selected.
-
-If @var{size} is omitted or @code{nil}, then @var{window} is divided
-evenly into two parts. (If there is an odd line, it is allocated to
-the new window.) When @code{split-window} is called interactively,
-all its arguments are @code{nil}.
-
-If splitting would result in making a window that is smaller than
-@code{window-min-height} or @code{window-min-width}, the function
-signals an error and does not split the window at all.
-
-The following example starts with one window on a screen that is 50
-lines high by 80 columns wide; then it splits the window.
-
-@smallexample
-@group
-(setq w (selected-window))
- @result{} #<window 8 on windows.texi>
-(window-edges) ; @r{Edges in order:}
- @result{} (0 0 80 50) ; @r{left--top--right--bottom}
-@end group
-
-@group
-;; @r{Returns window created}
-(setq w2 (split-window w 15))
- @result{} #<window 28 on windows.texi>
-@end group
-@group
-(window-edges w2)
- @result{} (0 15 80 50) ; @r{Bottom window;}
- ; @r{top is line 15}
-@end group
-@group
-(window-edges w)
- @result{} (0 0 80 15) ; @r{Top window}
-@end group
-@end smallexample
-
-The screen looks like this:
-
-@smallexample
-@group
- __________
- | | line 0
- | w |
- |__________|
- | | line 15
- | w2 |
- |__________|
- line 50
- column 0 column 80
-@end group
-@end smallexample
-
-Next, split the top window horizontally:
-
-@smallexample
-@group
-(setq w3 (split-window w 35 t))
- @result{} #<window 32 on windows.texi>
-@end group
-@group
-(window-edges w3)
- @result{} (35 0 80 15) ; @r{Left edge at column 35}
-@end group
-@group
-(window-edges w)
- @result{} (0 0 35 15) ; @r{Right edge at column 35}
-@end group
-@group
-(window-edges w2)
- @result{} (0 15 80 50) ; @r{Bottom window unchanged}
-@end group
-@end smallexample
-
-@need 3000
-Now the screen looks like this:
-
-@smallexample
-@group
- column 35
- __________
- | | | line 0
- | w | w3 |
- |___|______|
- | | line 15
- | w2 |
- |__________|
- line 50
- column 0 column 80
-@end group
-@end smallexample
-
-Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|}
-characters. The display table can specify alternative border
-characters; see @ref{Display Tables}.
-@end deffn
-
-@deffn Command split-window-vertically &optional size
-This function splits the selected window into two windows, one above the
-other, leaving the upper of the two windows selected, with @var{size}
-lines. (If @var{size} is negative, then the lower of the two windows
-gets @minus{} @var{size} lines and the upper window gets the rest, but
-the upper window is still the one selected.) However, if
-@code{split-window-keep-point} (see below) is @code{nil}, then either
-window can be selected.
-
-In other respects, this function is similar to @code{split-window}.
-In particular, the upper window is the original one and the return
-value is the new, lower window.
-@end deffn
-
-@defopt split-window-keep-point
-If this variable is non-@code{nil} (the default), then
-@code{split-window-vertically} behaves as described above.
-
-If it is @code{nil}, then @code{split-window-vertically} adjusts point
-in each of the two windows to avoid scrolling. (This is useful on
-slow terminals.) It selects whichever window contains the screen line
-that point was previously on.
-
-This variable only affects the behavior of @code{split-window-vertically}.
-It has no effect on the other functions described here.
-@end defopt
-
-@deffn Command split-window-horizontally &optional size
-This function splits the selected window into two windows
-side-by-side, leaving the selected window on the left with @var{size}
-columns. If @var{size} is negative, the rightmost window gets
-@minus{} @var{size} columns, but the leftmost window still remains
-selected.
-
-This function is basically an interface to @code{split-window}.
-You could define a simplified version of the function like this:
-
-@smallexample
-@group
-(defun split-window-horizontally (&optional arg)
- "Split selected window into two windows, side by side..."
- (interactive "P")
-@end group
-@group
- (let ((size (and arg (prefix-numeric-value arg))))
- (and size (< size 0)
- (setq size (+ (window-width) size)))
- (split-window nil size t)))
-@end group
-@end smallexample
-@end deffn
-
-@defun one-window-p &optional no-mini all-frames
-This function returns non-@code{nil} if there is only one window. The
-argument @var{no-mini}, if non-@code{nil}, means don't count the
-minibuffer even if it is active; otherwise, the minibuffer window is
-counted when it is active.
-
-The argument @var{all-frames} specifies which frames to consider. Here
-are the possible values and their meanings:
-
-@table @asis
-@item @code{nil}
-Count the windows in the selected frame, plus the minibuffer used
-by that frame even if it lies in some other frame.
-
-@item @code{t}
-Count all windows in all existing frames.
-
-@item @code{visible}
-Count all windows in all visible frames.
-
-@item 0
-Count all windows in all visible or iconified frames.
-
-@item anything else
-Count precisely the windows in the selected frame, and no others.
-@end table
-@end defun
-
-@node Deleting Windows
-@section Deleting Windows
-@cindex deleting windows
-
-A window remains visible on its frame unless you @dfn{delete} it by
-calling certain functions that delete windows. A deleted window cannot
-appear on the screen, but continues to exist as a Lisp object until
-there are no references to it. There is no way to cancel the deletion
-of a window aside from restoring a saved window configuration
-(@pxref{Window Configurations}). Restoring a window configuration also
-deletes any windows that aren't part of that configuration.
-
- When you delete a window, the space it took up is given to one
-adjacent sibling.
-
-@c Emacs 19 feature
-@defun window-live-p window
-This function returns @code{nil} if @var{window} is deleted, and
-@code{t} otherwise.
-
-@strong{Warning:} Erroneous information or fatal errors may result from
-using a deleted window as if it were live.
-@end defun
-
-@deffn Command delete-window &optional window
-This function removes @var{window} from display, and returns @code{nil}.
-If @var{window} is omitted, then the selected window is deleted. An
-error is signaled if there is only one window when @code{delete-window}
-is called.
-@end deffn
-
-@deffn Command delete-other-windows &optional window
-This function makes @var{window} the only window on its frame, by
-deleting the other windows in that frame. If @var{window} is omitted or
-@code{nil}, then the selected window is used by default.
-
-The return value is @code{nil}.
-@end deffn
-
-@deffn Command delete-windows-on buffer-or-name &optional frame
-This function deletes all windows showing @var{buffer-or-name}. If
-there are no windows showing @var{buffer-or-name}, it does nothing.
-@var{buffer-or-name} must be a buffer or the name of an existing
-buffer.
-
-@code{delete-windows-on} operates frame by frame. If a frame has
-several windows showing different buffers, then those showing
-@var{buffer-or-name} are removed, and the others expand to fill the
-space. If all windows in some frame are showing @var{buffer-or-name}
-(including the case where there is only one window), then the frame
-winds up with a single window showing another buffer chosen with
-@code{other-buffer}. @xref{The Buffer List}.
-
-The argument @var{frame} controls which frames to operate on. This
-function does not use it in quite the same way as the other functions
-which scan all windows; specifically, the values @code{t} and @code{nil}
-have the opposite of their meanings in other functions. Here are the
-full details:
-
-@itemize @bullet
-@item
-If it is @code{nil}, operate on all frames.
-@item
-If it is @code{t}, operate on the selected frame.
-@item
-If it is @code{visible}, operate on all visible frames.
-@item
-If it is 0, operate on all visible or iconified frames.
-@item
-If it is a frame, operate on that frame.
-@end itemize
-
-This function always returns @code{nil}.
-@end deffn
-
-@node Selecting Windows
-@section Selecting Windows
-@cindex selecting a window
-
- When a window is selected, the buffer in the window becomes the current
-buffer, and the cursor will appear in it.
-
-@defun selected-window
-This function returns the selected window. This is the window in
-which the cursor appears and to which many commands apply.
-@end defun
-
-@defun select-window window &optional norecord
-This function makes @var{window} the selected window. The cursor then
-appears in @var{window} (on redisplay). Unless @var{window} was
-already selected, @code{select-window} makes @var{window}'s buffer the
-current buffer.
-
-Normally @var{window}'s selected buffer is moved to the front of the
-buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
-order is unchanged.
-
-The return value is @var{window}.
-
-@example
-@group
-(setq w (next-window))
-(select-window w)
- @result{} #<window 65 on windows.texi>
-@end group
-@end example
-@end defun
-
-@defmac save-selected-window forms@dots{}
-This macro records the selected frame, as well as the selected window
-of each frame, executes @var{forms} in sequence, then restores the
-earlier selected frame and windows. It also saves and restores the
-current buffer. It returns the value of the last form in @var{forms}.
-
-This macro does not save or restore anything about the sizes,
-arrangement or contents of windows; therefore, if the @var{forms}
-change them, the change persists. If the previously selected window
-of some frame is no longer live at the time of exit from @var{forms},
-that frame's selected window is left alone. If the previously
-selected window is no longer live, then whatever window is selected at
-the end of @var{forms} remains selected.
-@end defmac
-
-@defmac with-selected-window window forms@dots{}
-This macro selects @var{window} (without changing the buffer list),
-executes @var{forms} in sequence, then restores the previously
-selected window and current buffer. It is just like
-@code{save-selected-window}, except that it explicitly selects
-@var{window}, also without altering the buffer list sequence.
-@end defmac
-
-@cindex finding windows
- The following functions choose one of the windows on the screen,
-offering various criteria for the choice.
-
-@defun get-lru-window &optional frame dedicated
-This function returns the window least recently ``used'' (that is,
-selected). If any full-width windows are present, it only considers
-these. The selected window is always the most recently used window.
-
-The selected window can be the least recently used window if it is the
-only window. A newly created window becomes the least recently used
-window until it is selected. A minibuffer window is never a
-candidate. Dedicated windows are never candidates unless the
-@var{dedicated} argument is non-@code{nil}, so if all
-existing windows are dedicated, the value is @code{nil}.
-
-The argument @var{frame} controls which windows are considered.
-
-@itemize @bullet
-@item
-If it is @code{nil}, consider windows on the selected frame.
-@item
-If it is @code{t}, consider windows on all frames.
-@item
-If it is @code{visible}, consider windows on all visible frames.
-@item
-If it is 0, consider windows on all visible or iconified frames.
-@item
-If it is a frame, consider windows on that frame.
-@end itemize
-@end defun
-
-@defun get-largest-window &optional frame dedicated
-This function returns the window with the largest area (height times
-width). If there are no side-by-side windows, then this is the window
-with the most lines. A minibuffer window is never a candidate.
-Dedicated windows are never candidates unless the
-@var{dedicated} argument is non-@code{nil}, so if all existing windows
-are dedicated, the value is @code{nil}.
-
-If there are two candidate windows of the same size, this function
-prefers the one that comes first in the cyclic ordering of windows
-(see following section), starting from the selected window.
-
-The argument @var{frame} controls which set of windows to
-consider. See @code{get-lru-window}, above.
-@end defun
-
-@cindex window that satisfies a predicate
-@cindex conditional selection of windows
-@defun get-window-with-predicate predicate &optional minibuf all-frames default
-This function returns a window satisfying @var{predicate}. It cycles
-through all visible windows using @code{walk-windows} (@pxref{Cyclic
-Window Ordering}), calling @var{predicate} on each one of them
-with that window as its argument. The function returns the first
-window for which @var{predicate} returns a non-@code{nil} value; if
-that never happens, it returns @var{default}.
-
-The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to include in the scan. See the description of
-@code{next-window} in @ref{Cyclic Window Ordering}, for details.
-@end defun
-
-@node Cyclic Window Ordering
-@comment node-name, next, previous, up
-@section Cyclic Ordering of Windows
-@cindex cyclic ordering of windows
-@cindex ordering of windows, cyclic
-@cindex window ordering, cyclic
-
- When you use the command @kbd{C-x o} (@code{other-window}) to select
-the next window, it moves through all the windows on the screen in a
-specific cyclic order. For any given configuration of windows, this
-order never varies. It is called the @dfn{cyclic ordering of windows}.
-
- This ordering generally goes from top to bottom, and from left to
-right. But it may go down first or go right first, depending on the
-order in which the windows were split.
-
- If the first split was vertical (into windows one above each other),
-and then the subwindows were split horizontally, then the ordering is
-left to right in the top of the frame, and then left to right in the
-next lower part of the frame, and so on. If the first split was
-horizontal, the ordering is top to bottom in the left part, and so on.
-In general, within each set of siblings at any level in the window tree,
-the order is left to right, or top to bottom.
-
-@defun next-window &optional window minibuf all-frames
-@cindex minibuffer window, and @code{next-window}
-This function returns the window following @var{window} in the cyclic
-ordering of windows. This is the window that @kbd{C-x o} would select
-if typed when @var{window} is selected. If @var{window} is the only
-window visible, then this function returns @var{window}. If omitted,
-@var{window} defaults to the selected window.
-
-The value of the argument @var{minibuf} determines whether the
-minibuffer is included in the window order. Normally, when
-@var{minibuf} is @code{nil}, the minibuffer is included if it is
-currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
-window is active while the minibuffer is in use. @xref{Minibuffers}.)
-
-If @var{minibuf} is @code{t}, then the cyclic ordering includes the
-minibuffer window even if it is not active.
-
-If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
-window is not included even if it is active.
-
-The argument @var{all-frames} specifies which frames to consider. Here
-are the possible values and their meanings:
-
-@table @asis
-@item @code{nil}
-Consider all the windows in @var{window}'s frame, plus the minibuffer
-used by that frame even if it lies in some other frame. If the
-minibuffer counts (as determined by @var{minibuf}), then all windows on
-all frames that share that minibuffer count too.
-
-@item @code{t}
-Consider all windows in all existing frames.
-
-@item @code{visible}
-Consider all windows in all visible frames. (To get useful results, you
-must ensure @var{window} is in a visible frame.)
-
-@item 0
-Consider all windows in all visible or iconified frames.
-
-@item a frame
-Consider all windows on that frame.
-
-@item anything else
-Consider precisely the windows in @var{window}'s frame, and no others.
-@end table
-
-This example assumes there are two windows, both displaying the
-buffer @samp{windows.texi}:
-
-@example
-@group
-(selected-window)
- @result{} #<window 56 on windows.texi>
-@end group
-@group
-(next-window (selected-window))
- @result{} #<window 52 on windows.texi>
-@end group
-@group
-(next-window (next-window (selected-window)))
- @result{} #<window 56 on windows.texi>
-@end group
-@end example
-@end defun
-
-@defun previous-window &optional window minibuf all-frames
-This function returns the window preceding @var{window} in the cyclic
-ordering of windows. The other arguments specify which windows to
-include in the cycle, as in @code{next-window}.
-@end defun
-
-@deffn Command other-window count &optional all-frames
-This function selects the @var{count}th following window in the cyclic
-order. If count is negative, then it moves back @minus{}@var{count}
-windows in the cycle, rather than forward. It returns @code{nil}.
-
-The argument @var{all-frames} has the same meaning as in
-@code{next-window}, but the @var{minibuf} argument of @code{next-window}
-is always effectively @code{nil}.
-
-In an interactive call, @var{count} is the numeric prefix argument.
-@end deffn
-
-@c Emacs 19 feature
-@defun walk-windows proc &optional minibuf all-frames
-This function cycles through all windows. It calls the function
-@code{proc} once for each window, with the window as its sole
-argument.
-
-The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to include in the scan. See @code{next-window}, above,
-for details.
-@end defun
-
-@defun window-list &optional frame minibuf window
-This function returns a list of the windows on @var{frame}, starting
-with @var{window}. If @var{frame} is @code{nil} or omitted,
-@code{window-list} uses the selected frame instead; if @var{window} is
-@code{nil} or omitted, it uses the selected window.
-
-The value of @var{minibuf} determines if the minibuffer window is
-included in the result list. If @var{minibuf} is @code{t}, the result
-always includes the minibuffer window. If @var{minibuf} is @code{nil}
-or omitted, that includes the minibuffer window if it is active. If
-@var{minibuf} is neither @code{nil} nor @code{t}, the result never
-includes the minibuffer window.
-@end defun
-
-@node Buffers and Windows
-@section Buffers and Windows
-@cindex examining windows
-@cindex windows, controlling precisely
-@cindex buffers, controlled in windows
-
- This section describes low-level functions to examine windows or to
-display buffers in windows in a precisely controlled fashion.
-@iftex
-See the following section for
-@end iftex
-@ifnottex
-@xref{Displaying Buffers}, for
-@end ifnottex
-related functions that find a window to use and specify a buffer for it.
-The functions described there are easier to use than these, but they
-employ heuristics in choosing or creating a window; use these functions
-when you need complete control.
-
-@defun set-window-buffer window buffer-or-name &optional keep-margins
-This function makes @var{window} display @var{buffer-or-name} as its
-contents. It returns @code{nil}. @var{buffer-or-name} must be a
-buffer, or the name of an existing buffer. This is the fundamental
-primitive for changing which buffer is displayed in a window, and all
-ways of doing that call this function.
-
-@example
-@group
-(set-window-buffer (selected-window) "foo")
- @result{} nil
-@end group
-@end example
-
-Normally, displaying @var{buffer} in @var{window} resets the window's
-display margins, fringe widths, scroll bar settings, and position
-based on the local variables of @var{buffer}. However, if
-@var{keep-margins} is non-@code{nil}, the display margins and fringe
-widths of @var{window} remain unchanged. @xref{Fringes}.
-@end defun
-
-@defvar buffer-display-count
-This buffer-local variable records the number of times a buffer is
-displayed in a window. It is incremented each time
-@code{set-window-buffer} is called for the buffer.
-@end defvar
-
-@defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying. If
-@var{window} is omitted, this function returns the buffer for the
-selected window.
-
-@example
-@group
-(window-buffer)
- @result{} #<buffer windows.texi>
-@end group
-@end example
-@end defun
-
-@defun get-buffer-window buffer-or-name &optional all-frames
-This function returns a window currently displaying
-@var{buffer-or-name}, or @code{nil} if there is none. If there are
-several such windows, then the function returns the first one in the
-cyclic ordering of windows, starting from the selected window.
-@xref{Cyclic Window Ordering}.
-
-The argument @var{all-frames} controls which windows to consider.
-
-@itemize @bullet
-@item
-If it is @code{nil}, consider windows on the selected frame.
-@item
-If it is @code{t}, consider windows on all frames.
-@item
-If it is @code{visible}, consider windows on all visible frames.
-@item
-If it is 0, consider windows on all visible or iconified frames.
-@item
-If it is a frame, consider windows on that frame.
-@end itemize
-@end defun
-
-@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
-This function returns a list of all the windows currently displaying
-@var{buffer-or-name}.
-
-The two optional arguments work like the optional arguments of
-@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
-like the single optional argument of @code{get-buffer-window}. Perhaps
-we should change @code{get-buffer-window} in the future to make it
-compatible with the other functions.
-@end defun
-
-@defvar buffer-display-time
-This variable records the time at which a buffer was last made visible
-in a window. It is always local in each buffer; each time
-@code{set-window-buffer} is called, it sets this variable to
-@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
-When a buffer is first created, @code{buffer-display-time} starts out
-with the value @code{nil}.
-@end defvar
-
-@node Displaying Buffers
-@section Displaying Buffers in Windows
-@cindex switching to a buffer
-@cindex displaying a buffer
-
- In this section we describe convenient functions that choose a window
-automatically and use it to display a specified buffer. These functions
-can also split an existing window in certain circumstances. We also
-describe variables that parameterize the heuristics used for choosing a
-window.
-@iftex
-See the preceding section for
-@end iftex
-@ifnottex
-@xref{Buffers and Windows}, for
-@end ifnottex
-low-level functions that give you more precise control. All of these
-functions work by calling @code{set-window-buffer}.
-
- Do not use the functions in this section in order to make a buffer
-current so that a Lisp program can access or modify it; they are too
-drastic for that purpose, since they change the display of buffers in
-windows, which would be gratuitous and surprise the user. Instead, use
-@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
-Buffer}), which designate buffers as current for programmed access
-without affecting the display of buffers in windows.
-
-@deffn Command switch-to-buffer buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer, and also
-displays the buffer in the selected window. This means that a human can
-see the buffer and subsequent keyboard commands will apply to it.
-Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window.
-@xref{Current Buffer}.
-
-If @var{buffer-or-name} does not identify an existing buffer, then a new
-buffer by that name is created. The major mode for the new buffer is
-set according to the variable @code{default-major-mode}. @xref{Auto
-Major Mode}. If @var{buffer-or-name} is @code{nil},
-@code{switch-to-buffer} chooses a buffer using @code{other-buffer}.
-
-Normally the specified buffer is put at the front of the buffer list
-(both the selected frame's buffer list and the frame-independent buffer
-list). This affects the operation of @code{other-buffer}. However, if
-@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
-List}.
-
-The @code{switch-to-buffer} function is often used interactively, as
-the binding of @kbd{C-x b}. It is also used frequently in programs. It
-returns the buffer that it switched to.
-@end deffn
-
-The next two functions are similar to @code{switch-to-buffer}, except
-for the described features.
-
-@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer and
-displays it in a window not currently selected. It then selects that
-window. The handling of the buffer is the same as in
-@code{switch-to-buffer}.
-
-The currently selected window is absolutely never used to do the job.
-If it is the only window, then it is split to make a distinct window for
-this purpose. If the selected window is already displaying the buffer,
-then it continues to do so, but another window is nonetheless found to
-display it in as well.
-
-This function updates the buffer list just like @code{switch-to-buffer}
-unless @var{norecord} is non-@code{nil}.
-@end deffn
-
-@defun pop-to-buffer buffer-or-name &optional other-window norecord
-This function makes @var{buffer-or-name} the current buffer and
-switches to it in some window, preferably not the window previously
-selected. The ``popped-to'' window becomes the selected window within
-its frame. The return value is the buffer that was switched to.
-If @var{buffer-or-name} is @code{nil}, that means to choose some
-other buffer, but you don't specify which.
-
-If the variable @code{pop-up-frames} is non-@code{nil},
-@code{pop-to-buffer} looks for a window in any visible frame already
-displaying the buffer; if there is one, it returns that window and makes
-it be selected within its frame. If there is none, it creates a new
-frame and displays the buffer in it.
-
-If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
-operates entirely within the selected frame. (If the selected frame has
-just a minibuffer, @code{pop-to-buffer} operates within the most
-recently selected frame that was not just a minibuffer.)
-
-If the variable @code{pop-up-windows} is non-@code{nil}, windows may
-be split to create a new window that is different from the original
-window. For details, see @ref{Choosing Window}.
-
-If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
-creates another window even if @var{buffer-or-name} is already visible
-in the selected window. Thus @var{buffer-or-name} could end up
-displayed in two windows. On the other hand, if @var{buffer-or-name} is
-already displayed in the selected window and @var{other-window} is
-@code{nil}, then the selected window is considered sufficient display
-for @var{buffer-or-name}, so that nothing needs to be done.
-
-All the variables that affect @code{display-buffer} affect
-@code{pop-to-buffer} as well. @xref{Choosing Window}.
-
-If @var{buffer-or-name} is a string that does not name an existing
-buffer, a buffer by that name is created. The major mode for the new
-buffer is set according to the variable @code{default-major-mode}.
-@xref{Auto Major Mode}.
-
-This function updates the buffer list just like @code{switch-to-buffer}
-unless @var{norecord} is non-@code{nil}.
-@end defun
-
-@deffn Command replace-buffer-in-windows buffer-or-name
-This function replaces @var{buffer-or-name} with some other buffer in all
-windows displaying it. It chooses the other buffer with
-@code{other-buffer}. In the usual applications of this function, you
-don't care which other buffer is used; you just want to make sure that
-@var{buffer-or-name} is no longer displayed.
-
-This function returns @code{nil}.
-@end deffn
-
-@node Choosing Window
-@section Choosing a Window for Display
-
- This section describes the basic facility that chooses a window to
-display a buffer in---@code{display-buffer}. All the higher-level
-functions and commands use this subroutine. Here we describe how to use
-@code{display-buffer} and how to customize it.
-
-@deffn Command display-buffer buffer-or-name &optional not-this-window frame
-This command makes @var{buffer-or-name} appear in some window, like
-@code{pop-to-buffer}, but it does not select that window and does not
-make the buffer current. The identity of the selected window is
-unaltered by this function. @var{buffer-or-name} must be a buffer, or
-the name of an existing buffer.
-
-If @var{not-this-window} is non-@code{nil}, it means to display the
-specified buffer in a window other than the selected one, even if it is
-already on display in the selected window. This can cause the buffer to
-appear in two windows at once. Otherwise, if @var{buffer-or-name} is
-already being displayed in any window, that is good enough, so this
-function does nothing.
-
-@code{display-buffer} returns the window chosen to display
-@var{buffer-or-name}.
-
-If the argument @var{frame} is non-@code{nil}, it specifies which frames
-to check when deciding whether the buffer is already displayed. If the
-buffer is already displayed in some window on one of these frames,
-@code{display-buffer} simply returns that window. Here are the possible
-values of @var{frame}:
-
-@itemize @bullet
-@item
-If it is @code{nil}, consider windows on the selected frame.
-(Actually, the last non-minibuffer frame.)
-@item
-If it is @code{t}, consider windows on all frames.
-@item
-If it is @code{visible}, consider windows on all visible frames.
-@item
-If it is 0, consider windows on all visible or iconified frames.
-@item
-If it is a frame, consider windows on that frame.
-@end itemize
-
-Precisely how @code{display-buffer} finds or creates a window depends on
-the variables described below.
-@end deffn
-
-@defopt display-buffer-reuse-frames
-If this variable is non-@code{nil}, @code{display-buffer} searches
-existing frames for a window displaying the buffer. If the buffer is
-already displayed in a window in some frame, @code{display-buffer} makes
-the frame visible and raises it, to use that window. If the buffer is
-not already displayed, or if @code{display-buffer-reuse-frames} is
-@code{nil}, @code{display-buffer}'s behavior is determined by other
-variables, described below.
-@end defopt
-
-@defopt pop-up-windows
-This variable controls whether @code{display-buffer} makes new windows.
-If it is non-@code{nil} and there is only one window, then that window
-is split. If it is @code{nil}, then @code{display-buffer} does not
-split the single window, but uses it whole.
-@end defopt
-
-@defopt split-height-threshold
-This variable determines when @code{display-buffer} may split a window,
-if there are multiple windows. @code{display-buffer} always splits the
-largest window if it has at least this many lines. If the largest
-window is not this tall, it is split only if it is the sole window and
-@code{pop-up-windows} is non-@code{nil}.
-@end defopt
-
-@defopt even-window-heights
-This variable determines if @code{display-buffer} should even out window
-heights if the buffer gets displayed in an existing window, above or
-beneath another existing window. If @code{even-window-heights} is
-@code{t}, the default, window heights will be evened out. If
-@code{even-window-heights} is @code{nil}, the original window heights
-will be left alone.
-@end defopt
-
-@c Emacs 19 feature
-@defopt pop-up-frames
-This variable controls whether @code{display-buffer} makes new frames.
-If it is non-@code{nil}, @code{display-buffer} looks for an existing
-window already displaying the desired buffer, on any visible frame. If
-it finds one, it returns that window. Otherwise it makes a new frame.
-The variables @code{pop-up-windows} and @code{split-height-threshold} do
-not matter if @code{pop-up-frames} is non-@code{nil}.
-
-If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
-splits a window or reuses one.
-
-@xref{Frames}, for more information.
-@end defopt
-
-@c Emacs 19 feature
-@defopt pop-up-frame-function
-This variable specifies how to make a new frame if @code{pop-up-frames}
-is non-@code{nil}.
-
-Its value should be a function of no arguments. When
-@code{display-buffer} makes a new frame, it does so by calling that
-function, which should return a frame. The default value of the
-variable is a function that creates a frame using parameters from
-@code{pop-up-frame-alist}.
-@end defopt
-
-@defopt pop-up-frame-alist
-This variable holds an alist specifying frame parameters used when
-@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
-more information about frame parameters.
-@end defopt
-
-@defopt special-display-buffer-names
-A list of buffer names for buffers that should be displayed specially.
-If the buffer's name is in this list, @code{display-buffer} handles the
-buffer specially.
-
-By default, special display means to give the buffer a dedicated frame.
-
-If an element is a list, instead of a string, then the @sc{car} of the
-list is the buffer name, and the rest of the list says how to create
-the frame. There are two possibilities for the rest of the list (its
-@sc{cdr}). It can be an alist, specifying frame parameters, or it can
-contain a function and arguments to give to it. (The function's first
-argument is always the buffer to be displayed; the arguments from the
-list come after that.)
-
-For example:
-
-@example
-(("myfile" (minibuffer) (menu-bar-lines . 0)))
-@end example
-
-@noindent
-specifies to display a buffer named @samp{myfile} in a dedicated frame
-with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
-
-The list of frame parameters can also use the phony frame parameters
-@code{same-frame} and @code{same-window}. If the specified frame
-parameters include @code{(same-window . @var{value})} and @var{value}
-is non-@code{nil}, that means to display the buffer in the current
-selected window. Otherwise, if they include @code{(same-frame .
-@var{value})} and @var{value} is non-@code{nil}, that means to display
-the buffer in a new window in the currently selected frame.
-@end defopt
-
-@defopt special-display-regexps
-A list of regular expressions that specify buffers that should be
-displayed specially. If the buffer's name matches any of the regular
-expressions in this list, @code{display-buffer} handles the buffer
-specially.
-
-By default, special display means to give the buffer a dedicated frame.
-
-If an element is a list, instead of a string, then the @sc{car} of the
-list is the regular expression, and the rest of the list says how to
-create the frame. See above, under @code{special-display-buffer-names}.
-@end defopt
-
-@defun special-display-p buffer-name
-This function returns non-@code{nil} if displaying a buffer
-named @var{buffer-name} with @code{display-buffer} would
-create a special frame. The value is @code{t} if it would
-use the default frame parameters, or else the specified list
-of frame parameters.
-@end defun
-
-@defvar special-display-function
-This variable holds the function to call to display a buffer specially.
-It receives the buffer as an argument, and should return the window in
-which it is displayed.
-
-The default value of this variable is
-@code{special-display-popup-frame}.
-@end defvar
-
-@defun special-display-popup-frame buffer &optional args
-This function makes @var{buffer} visible in a frame of its own. If
-@var{buffer} is already displayed in a window in some frame, it makes
-the frame visible and raises it, to use that window. Otherwise, it
-creates a frame that will be dedicated to @var{buffer}. This
-function returns the window it used.
-
-If @var{args} is an alist, it specifies frame parameters for the new
-frame.
-
-If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
-@var{args})} is called as a function to actually create and set up the
-frame; it is called with @var{buffer} as first argument, and @code{(cdr
-@var{args})} as additional arguments.
-
-This function always uses an existing window displaying @var{buffer},
-whether or not it is in a frame of its own; but if you set up the above
-variables in your init file, before @var{buffer} was created, then
-presumably the window was previously made by this function.
-@end defun
-
-@defopt special-display-frame-alist
-@anchor{Definition of special-display-frame-alist}
-This variable holds frame parameters for
-@code{special-display-popup-frame} to use when it creates a frame.
-@end defopt
-
-@defopt same-window-buffer-names
-A list of buffer names for buffers that should be displayed in the
-selected window. If the buffer's name is in this list,
-@code{display-buffer} handles the buffer by switching to it in the
-selected window.
-@end defopt
-
-@defopt same-window-regexps
-A list of regular expressions that specify buffers that should be
-displayed in the selected window. If the buffer's name matches any of
-the regular expressions in this list, @code{display-buffer} handles the
-buffer by switching to it in the selected window.
-@end defopt
-
-@defun same-window-p buffer-name
-This function returns @code{t} if displaying a buffer
-named @var{buffer-name} with @code{display-buffer} would
-put it in the selected window.
-@end defun
-
-@c Emacs 19 feature
-@defvar display-buffer-function
-This variable is the most flexible way to customize the behavior of
-@code{display-buffer}. If it is non-@code{nil}, it should be a function
-that @code{display-buffer} calls to do the work. The function should
-accept two arguments, the first two arguments that @code{display-buffer}
-received. It should choose or create a window, display the specified
-buffer in it, and then return the window.
-
-This hook takes precedence over all the other options and hooks
-described above.
-@end defvar
-
-@c Emacs 19 feature
-@cindex dedicated window
-A window can be marked as ``dedicated'' to its buffer. Then
-@code{display-buffer} will not try to use that window to display any
-other buffer.
-
-@defun window-dedicated-p window
-This function returns non-@code{nil} if @var{window} is marked as
-dedicated; otherwise @code{nil}.
-@end defun
-
-@defun set-window-dedicated-p window flag
-This function marks @var{window} as dedicated if @var{flag} is
-non-@code{nil}, and nondedicated otherwise.
-@end defun
-
-@node Window Point
-@section Windows and Point
-@cindex window position
-@cindex window point
-@cindex position in window
-@cindex point in window
-
- Each window has its own value of point, independent of the value of
-point in other windows displaying the same buffer. This makes it useful
-to have multiple windows showing one buffer.
-
-@itemize @bullet
-@item
-The window point is established when a window is first created; it is
-initialized from the buffer's point, or from the window point of another
-window opened on the buffer if such a window exists.
-
-@item
-Selecting a window sets the value of point in its buffer from the
-window's value of point. Conversely, deselecting a window sets the
-window's value of point from that of the buffer. Thus, when you switch
-between windows that display a given buffer, the point value for the
-selected window is in effect in the buffer, while the point values for
-the other windows are stored in those windows.
-
-@item
-As long as the selected window displays the current buffer, the window's
-point and the buffer's point always move together; they remain equal.
-@end itemize
-
-@noindent
-@xref{Positions}, for more details on buffer positions.
-
-@cindex cursor
- As far as the user is concerned, point is where the cursor is, and
-when the user switches to another buffer, the cursor jumps to the
-position of point in that buffer.
-
-@defun window-point &optional window
-This function returns the current position of point in @var{window}.
-For a nonselected window, this is the value point would have (in that
-window's buffer) if that window were selected. If @var{window} is
-@code{nil}, the selected window is used.
-
-When @var{window} is the selected window and its buffer is also the
-current buffer, the value returned is the same as point in that buffer.
-
-Strictly speaking, it would be more correct to return the
-``top-level'' value of point, outside of any @code{save-excursion}
-forms. But that value is hard to find.
-@end defun
-
-@defun set-window-point window position
-This function positions point in @var{window} at position
-@var{position} in @var{window}'s buffer. It returns @var{position}.
-
-If @var{window} is selected, and its buffer is current,
-this simply does @code{goto-char}.
-@end defun
-
-@node Window Start
-@section The Window Start Position
-@cindex window start position
-
- Each window contains a marker used to keep track of a buffer position
-that specifies where in the buffer display should start. This position
-is called the @dfn{display-start} position of the window (or just the
-@dfn{start}). The character after this position is the one that appears
-at the upper left corner of the window. It is usually, but not
-inevitably, at the beginning of a text line.
-
-@defun window-start &optional window
-@cindex window top line
-This function returns the display-start position of window
-@var{window}. If @var{window} is @code{nil}, the selected window is
-used. For example,
-
-@example
-@group
-(window-start)
- @result{} 7058
-@end group
-@end example
-
-When you create a window, or display a different buffer in it, the
-display-start position is set to a display-start position recently used
-for the same buffer, or 1 if the buffer doesn't have any.
-
-Redisplay updates the window-start position (if you have not specified
-it explicitly since the previous redisplay)---for example, to make sure
-point appears on the screen. Nothing except redisplay automatically
-changes the window-start position; if you move point, do not expect the
-window-start position to change in response until after the next
-redisplay.
-
-For a realistic example of using @code{window-start}, see the
-description of @code{count-lines}. @xref{Definition of count-lines}.
-@end defun
-
-@defun window-end &optional window update
-This function returns the position of the end of the display in window
-@var{window}. If @var{window} is @code{nil}, the selected window is
-used.
-
-Simply changing the buffer text or moving point does not update the
-value that @code{window-end} returns. The value is updated only when
-Emacs redisplays and redisplay completes without being preempted.
-
-If the last redisplay of @var{window} was preempted, and did not finish,
-Emacs does not know the position of the end of display in that window.
-In that case, this function returns @code{nil}.
-
-If @var{update} is non-@code{nil}, @code{window-end} always returns an
-up-to-date value for where the window ends, based on the current
-@code{window-start} value. If the saved value is valid,
-@code{window-end} returns that; otherwise it computes the correct
-value by scanning the buffer text.
-
-Even if @var{update} is non-@code{nil}, @code{window-end} does not
-attempt to scroll the display if point has moved off the screen, the
-way real redisplay would do. It does not alter the
-@code{window-start} value. In effect, it reports where the displayed
-text will end if scrolling is not required.
-@end defun
-
-@defun set-window-start window position &optional noforce
-This function sets the display-start position of @var{window} to
-@var{position} in @var{window}'s buffer. It returns @var{position}.
-
-The display routines insist that the position of point be visible when a
-buffer is displayed. Normally, they change the display-start position
-(that is, scroll the window) whenever necessary to make point visible.
-However, if you specify the start position with this function using
-@code{nil} for @var{noforce}, it means you want display to start at
-@var{position} even if that would put the location of point off the
-screen. If this does place point off screen, the display routines move
-point to the left margin on the middle line in the window.
-
-For example, if point @w{is 1} and you set the start of the window @w{to
-2}, then point would be ``above'' the top of the window. The display
-routines will automatically move point if it is still 1 when redisplay
-occurs. Here is an example:
-
-@example
-@group
-;; @r{Here is what @samp{foo} looks like before executing}
-;; @r{the @code{set-window-start} expression.}
-@end group
-
-@group
----------- Buffer: foo ----------
-@point{}This is the contents of buffer foo.
-2
-3
-4
-5
-6
----------- Buffer: foo ----------
-@end group
-
-@group
-(set-window-start
- (selected-window)
- (1+ (window-start)))
-@result{} 2
-@end group
-
-@group
-;; @r{Here is what @samp{foo} looks like after executing}
-;; @r{the @code{set-window-start} expression.}
----------- Buffer: foo ----------
-his is the contents of buffer foo.
-2
-3
-@point{}4
-5
-6
----------- Buffer: foo ----------
-@end group
-@end example
-
-If @var{noforce} is non-@code{nil}, and @var{position} would place point
-off screen at the next redisplay, then redisplay computes a new window-start
-position that works well with point, and thus @var{position} is not used.
-@end defun
-
-@defun pos-visible-in-window-p &optional position window partially
-This function returns non-@code{nil} if @var{position} is within the
-range of text currently visible on the screen in @var{window}. It
-returns @code{nil} if @var{position} is scrolled vertically out of
-view. Locations that are partially obscured are not considered
-visible unless @var{partially} is non-@code{nil}. The argument
-@var{position} defaults to the current position of point in
-@var{window}; @var{window}, to the selected window.
-
-If @var{position} is @code{t}, that means to check the last visible
-position in @var{window}.
-
-The @code{pos-visible-in-window-p} function considers only vertical
-scrolling. If @var{position} is out of view only because @var{window}
-has been scrolled horizontally, @code{pos-visible-in-window-p} returns
-non-@code{nil} anyway. @xref{Horizontal Scrolling}.
-
-If @var{position} is visible, @code{pos-visible-in-window-p} returns
-@code{t} if @var{partially} is @code{nil}; if @var{partially} is
-non-@code{nil}, and the character after @var{position} is fully
-visible, it returns a list of the form @code{(@var{x} @var{y})}, where
-@var{x} and @var{y} are the pixel coordinates relative to the top left
-corner of the window; otherwise it returns an extended list of the
-form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh}
-@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number
-of off-window pixels at the top and bottom of the row at
-@var{position}, @var{rowh} specifies the visible height of that row,
-and @var{vpos} specifies the vertical position (zero-based row number)
-of that row.
-
-Here is an example:
-
-@example
-@group
-;; @r{If point is off the screen now, recenter it now.}
-(or (pos-visible-in-window-p
- (point) (selected-window))
- (recenter 0))
-@end group
-@end example
-@end defun
-
-@defun window-line-height &optional line window
-This function returns information about text line @var{line} in @var{window}.
-If @var{line} is one of @code{header-line} or @code{mode-line},
-@code{window-line-height} returns information about the corresponding
-line of the window. Otherwise, @var{line} is a text line number
-starting from 0. A negative number counts from the end of the window.
-The argument @var{line} defaults to the current line in @var{window};
-@var{window}, to the selected window.
-
-If the display is not up to date, @code{window-line-height} returns
-@code{nil}. In that case, @code{pos-visible-in-window-p} may be used
-to obtain related information.
-
-If there is no line corresponding to the specified @var{line},
-@code{window-line-height} returns @code{nil}. Otherwise, it returns
-a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
-where @var{height} is the height in pixels of the visible part of the
-line, @var{vpos} and @var{ypos} are the vertical position in lines and
-pixels of the line relative to the top of the first text line, and
-@var{offbot} is the number of off-window pixels at the bottom of the
-text line. If there are off-window pixels at the top of the (first)
-text line, @var{ypos} is negative.
-@end defun
-
-@node Textual Scrolling
-@section Textual Scrolling
-@cindex textual scrolling
-@cindex scrolling textually
-
- @dfn{Textual scrolling} means moving the text up or down through a
-window. It works by changing the value of the window's display-start
-location. It may also change the value of @code{window-point} to keep
-point on the screen.
-
- Textual scrolling was formerly called ``vertical scrolling,'' but we
-changed its name to distinguish it from the new vertical fractional
-scrolling feature (@pxref{Vertical Scrolling}).
-
- In the commands @code{scroll-up} and @code{scroll-down}, the directions
-``up'' and ``down'' refer to the motion of the text in the buffer at which
-you are looking through the window. Imagine that the text is
-written on a long roll of paper and that the scrolling commands move the
-paper up and down. Thus, if you are looking at text in the middle of a
-buffer and repeatedly call @code{scroll-down}, you will eventually see
-the beginning of the buffer.
-
- Some people have urged that the opposite convention be used: they
-imagine that the window moves over text that remains in place. Then
-``down'' commands would take you to the end of the buffer. This view is
-more consistent with the actual relationship between windows and the
-text in the buffer, but it is less like what the user sees. The
-position of a window on the terminal does not move, and short scrolling
-commands clearly move the text up or down on the screen. We have chosen
-names that fit the user's point of view.
-
- The textual scrolling functions (aside from
-@code{scroll-other-window}) have unpredictable results if the current
-buffer is different from the buffer that is displayed in the selected
-window. @xref{Current Buffer}.
-
- If the window contains a row which is taller than the height of the
-window (for example in the presence of a large image), the scroll
-functions will adjust the window vscroll to scroll the partially
-visible row. To disable this feature, Lisp code may bind the variable
-`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
-
-@deffn Command scroll-up &optional count
-This function scrolls the text in the selected window upward
-@var{count} lines. If @var{count} is negative, scrolling is actually
-downward.
-
-If @var{count} is @code{nil} (or omitted), then the length of scroll
-is @code{next-screen-context-lines} lines less than the usable height of
-the window (not counting its mode line).
-
-@code{scroll-up} returns @code{nil}, unless it gets an error
-because it can't scroll any further.
-@end deffn
-
-@deffn Command scroll-down &optional count
-This function scrolls the text in the selected window downward
-@var{count} lines. If @var{count} is negative, scrolling is actually
-upward.
-
-If @var{count} is omitted or @code{nil}, then the length of the scroll
-is @code{next-screen-context-lines} lines less than the usable height of
-the window (not counting its mode line).
-
-@code{scroll-down} returns @code{nil}, unless it gets an error because
-it can't scroll any further.
-@end deffn
-
-@deffn Command scroll-other-window &optional count
-This function scrolls the text in another window upward @var{count}
-lines. Negative values of @var{count}, or @code{nil}, are handled
-as in @code{scroll-up}.
-
-You can specify which buffer to scroll by setting the variable
-@code{other-window-scroll-buffer} to a buffer. If that buffer isn't
-already displayed, @code{scroll-other-window} displays it in some
-window.
-
-When the selected window is the minibuffer, the next window is normally
-the one at the top left corner. You can specify a different window to
-scroll, when the minibuffer is selected, by setting the variable
-@code{minibuffer-scroll-window}. This variable has no effect when any
-other window is selected. When it is non-@code{nil} and the
-minibuffer is selected, it takes precedence over
-@code{other-window-scroll-buffer}. @xref{Definition of
-minibuffer-scroll-window}.
-
-When the minibuffer is active, it is the next window if the selected
-window is the one at the bottom right corner. In this case,
-@code{scroll-other-window} attempts to scroll the minibuffer. If the
-minibuffer contains just one line, it has nowhere to scroll to, so the
-line reappears after the echo area momentarily displays the message
-@samp{Beginning of buffer}.
-@end deffn
-
-@c Emacs 19 feature
-@defvar other-window-scroll-buffer
-If this variable is non-@code{nil}, it tells @code{scroll-other-window}
-which buffer to scroll.
-@end defvar
-
-@defopt scroll-margin
-This option specifies the size of the scroll margin---a minimum number
-of lines between point and the top or bottom of a window. Whenever
-point gets within this many lines of the top or bottom of the window,
-redisplay scrolls the text automatically (if possible) to move point
-out of the margin, closer to the center of the window.
-@end defopt
-
-@defopt scroll-conservatively
-This variable controls how scrolling is done automatically when point
-moves off the screen (or into the scroll margin). If the value is a
-positive integer @var{n}, then redisplay scrolls the text up to
-@var{n} lines in either direction, if that will bring point back into
-proper view. This action is called @dfn{conservative scrolling}.
-Otherwise, scrolling happens in the usual way, under the control of
-other variables such as @code{scroll-up-aggressively} and
-@code{scroll-down-aggressively}.
-
-The default value is zero, which means that conservative scrolling
-never happens.
-@end defopt
-
-@defopt scroll-down-aggressively
-The value of this variable should be either @code{nil} or a fraction
-@var{f} between 0 and 1. If it is a fraction, that specifies where on
-the screen to put point when scrolling down. More precisely, when a
-window scrolls down 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.
-
-A value of @code{nil} is equivalent to .5, since its effect is to center
-point. This variable automatically becomes buffer-local when set in any
-fashion.
-@end defopt
-
-@defopt scroll-up-aggressively
-Likewise, for scrolling up. 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 scrolls more aggressively.
-@end defopt
-
-@defopt scroll-step
-This variable is an older variant of @code{scroll-conservatively}. The
-difference is that it if its value is @var{n}, that permits scrolling
-only by precisely @var{n} lines, not a smaller number. This feature
-does not work with @code{scroll-margin}. The default value is zero.
-@end defopt
-
-@defopt scroll-preserve-screen-position
-If this option is @code{t}, scrolling which would move the current
-point position out of the window chooses the new position of point
-so that the vertical position of the cursor is unchanged, if possible.
-
-If it is non-@code{nil} and not @code{t}, then the scrolling functions
-always preserve the vertical position of point, if possible.
-@end defopt
-
-@defopt next-screen-context-lines
-The value of this variable is the number of lines of continuity to
-retain when scrolling by full screens. For example, @code{scroll-up}
-with an argument of @code{nil} scrolls so that this many lines at the
-bottom of the window appear instead at the top. The default value is
-@code{2}.
-@end defopt
-
-@deffn Command recenter &optional count
-@cindex centering point
-This function scrolls the text in the selected window so that point is
-displayed at a specified vertical position within the window. It does
-not ``move point'' with respect to the text.
-
-If @var{count} is a nonnegative number, that puts the line containing
-point @var{count} lines down from the top of the window. If
-@var{count} is a negative number, then it counts upward from the
-bottom of the window, so that @minus{}1 stands for the last usable
-line in the window. If @var{count} is a non-@code{nil} list, then it
-stands for the line in the middle of the window.
-
-If @var{count} is @code{nil}, @code{recenter} puts the line containing
-point in the middle of the window, then clears and redisplays the entire
-selected frame.
-
-When @code{recenter} is called interactively, @var{count} is the raw
-prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
-@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
-@var{count} to 4, which positions the current line four lines from the
-top.
-
-With an argument of zero, @code{recenter} positions the current line at
-the top of the window. This action is so handy that some people make a
-separate key binding to do this. For example,
-
-@example
-@group
-(defun line-to-top-of-window ()
- "Scroll current line to top of window.
-Replaces three keystroke sequence C-u 0 C-l."
- (interactive)
- (recenter 0))
-
-(global-set-key [kp-multiply] 'line-to-top-of-window)
-@end group
-@end example
-@end deffn
-
-@node Vertical Scrolling
-@section Vertical Fractional Scrolling
-@cindex vertical fractional scrolling
-
- @dfn{Vertical fractional scrolling} means shifting the image in the
-window up or down by a specified multiple or fraction of a line.
-Each window has a @dfn{vertical scroll position},
-which is a number, never less than zero. It specifies how far to raise
-the contents of the window. Raising the window contents generally makes
-all or part of some lines disappear off the top, and all or part of some
-other lines appear at the bottom. The usual value is zero.
-
- The vertical scroll position is measured in units of the normal line
-height, which is the height of the default font. Thus, if the value is
-.5, that means the window contents are scrolled up half the normal line
-height. If it is 3.3, that means the window contents are scrolled up
-somewhat over three times the normal line height.
-
- What fraction of a line the vertical scrolling covers, or how many
-lines, depends on what the lines contain. A value of .5 could scroll a
-line whose height is very short off the screen, while a value of 3.3
-could scroll just part of the way through a tall line or an image.
-
-@defun window-vscroll &optional window pixels-p
-This function returns the current vertical scroll position of
-@var{window}. If @var{window} is @code{nil}, the selected window is
-used. If @var{pixels-p} is non-@code{nil}, the return value is
-measured in pixels, rather than in units of the normal line height.
-
-@example
-@group
-(window-vscroll)
- @result{} 0
-@end group
-@end example
-@end defun
-
-@defun set-window-vscroll window lines &optional pixels-p
-This function sets @var{window}'s vertical scroll position to
-@var{lines}. The argument @var{lines} should be zero or positive; if
-not, it is taken as zero.
-
-If @var{window} is @code{nil}, the selected window is used.
-
-The actual vertical scroll position must always correspond
-to an integral number of pixels, so the value you specify
-is rounded accordingly.
-
-The return value is the result of this rounding.
-
-@example
-@group
-(set-window-vscroll (selected-window) 1.2)
- @result{} 1.13
-@end group
-@end example
-
-If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
-pixels. In this case, the return value is @var{lines}.
-@end defun
-
-@defvar auto-window-vscroll
-If this variable is non-@code{nil}, the line-move, scroll-up, and
-scroll-down functions will automatically modify the window vscroll to
-scroll through display rows that are taller that the height of the
-window, for example in the presence of large images.
-@end defvar
-
-@node Horizontal Scrolling
-@section Horizontal Scrolling
-@cindex horizontal scrolling
-
- @dfn{Horizontal scrolling} means shifting the image in the window left
-or right by a specified multiple of the normal character width. Each
-window has a @dfn{horizontal scroll position}, which is a number, never
-less than zero. It specifies how far to shift the contents left.
-Shifting the window contents left generally makes all or part of some
-characters disappear off the left, and all or part of some other
-characters appear at the right. The usual value is zero.
-
- The horizontal scroll position is measured in units of the normal
-character width, which is the width of space in the default font. Thus,
-if the value is 5, that means the window contents are scrolled left by 5
-times the normal character width. How many characters actually
-disappear off to the left depends on their width, and could vary from
-line to line.
-
- Because we read from side to side in the ``inner loop,'' and from top
-to bottom in the ``outer loop,'' the effect of horizontal scrolling is
-not like that of textual or vertical scrolling. Textual scrolling
-involves selection of a portion of text to display, and vertical
-scrolling moves the window contents contiguously; but horizontal
-scrolling causes part of @emph{each line} to go off screen.
-
- Usually, no horizontal scrolling is in effect; then the leftmost
-column is at the left edge of the window. In this state, scrolling to
-the right is meaningless, since there is no data to the left of the edge
-to be revealed by it; so this is not allowed. Scrolling to the left is
-allowed; it scrolls the first columns of text off the edge of the window
-and can reveal additional columns on the right that were truncated
-before. Once a window has a nonzero amount of leftward horizontal
-scrolling, you can scroll it back to the right, but only so far as to
-reduce the net horizontal scroll to zero. There is no limit to how far
-left you can scroll, but eventually all the text will disappear off the
-left edge.
-
-@vindex auto-hscroll-mode
- If @code{auto-hscroll-mode} is set, redisplay automatically alters
-the horizontal scrolling of a window as necessary to ensure that point
-is always visible. However, you can still set the horizontal
-scrolling value explicitly. The value you specify serves as a lower
-bound for automatic scrolling, i.e. automatic scrolling will not
-scroll a window to a column less than the specified one.
-
-@deffn Command scroll-left &optional count set-minimum
-This function scrolls the selected window @var{count} columns to the
-left (or to the right if @var{count} is negative). The default
-for @var{count} is the window width, minus 2.
-
-The return value is the total amount of leftward horizontal scrolling in
-effect after the change---just like the value returned by
-@code{window-hscroll} (below).
-
-Once you scroll a window as far right as it can go, back to its normal
-position where the total leftward scrolling is zero, attempts to scroll
-any farther right have no effect.
-
-If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
-the lower bound for automatic scrolling; that is, automatic scrolling
-will not scroll a window to a column less than the value returned by
-this function. Interactive calls pass non-@code{nil} for
-@var{set-minimum}.
-@end deffn
-
-@deffn Command scroll-right &optional count set-minimum
-This function scrolls the selected window @var{count} columns to the
-right (or to the left if @var{count} is negative). The default
-for @var{count} is the window width, minus 2. Aside from the direction
-of scrolling, this works just like @code{scroll-left}.
-@end deffn
-
-@defun window-hscroll &optional window
-This function returns the total leftward horizontal scrolling of
-@var{window}---the number of columns by which the text in @var{window}
-is scrolled left past the left margin.
-
-The value is never negative. It is zero when no horizontal scrolling
-has been done in @var{window} (which is usually the case).
-
-If @var{window} is @code{nil}, the selected window is used.
-
-@example
-@group
-(window-hscroll)
- @result{} 0
-@end group
-@group
-(scroll-left 5)
- @result{} 5
-@end group
-@group
-(window-hscroll)
- @result{} 5
-@end group
-@end example
-@end defun
-
-@defun set-window-hscroll window columns
-This function sets horizontal scrolling of @var{window}. The value of
-@var{columns} specifies the amount of scrolling, in terms of columns
-from the left margin. The argument @var{columns} should be zero or
-positive; if not, it is taken as zero. Fractional values of
-@var{columns} are not supported at present.
-
-Note that @code{set-window-hscroll} may appear not to work if you test
-it by evaluating a call with @kbd{M-:} in a simple way. What happens
-is that the function sets the horizontal scroll value and returns, but
-then redisplay adjusts the horizontal scrolling to make point visible,
-and this overrides what the function did. You can observe the
-function's effect if you call it while point is sufficiently far from
-the left margin that it will remain visible.
-
-The value returned is @var{columns}.
-
-@example
-@group
-(set-window-hscroll (selected-window) 10)
- @result{} 10
-@end group
-@end example
-@end defun
-
- Here is how you can determine whether a given position @var{position}
-is off the screen due to horizontal scrolling:
-
-@example
-@group
-(defun hscroll-on-screen (window position)
- (save-excursion
- (goto-char position)
- (and
- (>= (- (current-column) (window-hscroll window)) 0)
- (< (- (current-column) (window-hscroll window))
- (window-width window)))))
-@end group
-@end example
-
-@node Size of Window
-@section The Size of a Window
-@cindex window size
-@cindex size of window
-
- An Emacs window is rectangular, and its size information consists of
-the height (the number of lines) and the width (the number of character
-positions in each line). The mode line is included in the height. But
-the width does not count the scroll bar or the column of @samp{|}
-characters that separates side-by-side windows.
-
- The following three functions return size information about a window:
-
-@defun window-height &optional window
-This function returns the number of lines in @var{window}, including
-its mode line and header line, if any. If @var{window} fills its
-entire frame except for the echo area, this is typically one less than
-the value of @code{frame-height} on that frame.
-
-If @var{window} is @code{nil}, the function uses the selected window.
-
-@example
-@group
-(window-height)
- @result{} 23
-@end group
-@group
-(split-window-vertically)
- @result{} #<window 4 on windows.texi>
-@end group
-@group
-(window-height)
- @result{} 11
-@end group
-@end example
-@end defun
-
-@defun window-body-height &optional window
-Like @code{window-height} but the value does not include the
-mode line (if any) or the header line (if any).
-@end defun
-
-@defun window-width &optional window
-This function returns the number of columns in @var{window}. If
-@var{window} fills its entire frame, this is the same as the value of
-@code{frame-width} on that frame. The width does not include the
-window's scroll bar or the column of @samp{|} characters that separates
-side-by-side windows.
-
-If @var{window} is @code{nil}, the function uses the selected window.
-
-@example
-@group
-(window-width)
- @result{} 80
-@end group
-@end example
-@end defun
-
-@defun window-full-width-p &optional window
-This function returns non-@code{nil} if @var{window} is as wide as
-the frame that contains it; otherwise @code{nil}.
-If @var{window} is @code{nil}, the function uses the selected window.
-@end defun
-
-@defun window-edges &optional window
-This function returns a list of the edge coordinates of @var{window}.
-If @var{window} is @code{nil}, the selected window is used.
-
-The order of the list is @code{(@var{left} @var{top} @var{right}
-@var{bottom})}, all elements relative to 0, 0 at the top left corner of
-the frame. The element @var{right} of the value is one more than the
-rightmost column used by @var{window}, and @var{bottom} is one more than
-the bottommost row used by @var{window} and its mode-line.
-
-The edges include the space used by the window's scroll bar, display
-margins, fringes, header line, and mode line, if it has them. Also,
-if the window has a neighbor on the right, its right edge value
-includes the width of the separator line between the window and that
-neighbor. Since the width of the window does not include this
-separator, the width does not usually equal the difference between the
-right and left edges.
-@end defun
-
-@defun window-inside-edges &optional window
-This is similar to @code{window-edges}, but the edge values
-it returns include only the text area of the window. They
-do not include the header line, mode line, scroll bar or
-vertical separator, fringes, or display margins.
-@end defun
-
-Here are the results obtained on a typical 24-line terminal with just
-one window, with menu bar enabled:
-
-@example
-@group
-(window-edges (selected-window))
- @result{} (0 1 80 23)
-@end group
-@group
-(window-inside-edges (selected-window))
- @result{} (0 1 80 22)
-@end group
-@end example
-
-@noindent
-The bottom edge is at line 23 because the last line is the echo area.
-The bottom inside edge is at line 22, which is the window's mode line.
-
-If @var{window} is at the upper left corner of its frame, and there is
-no menu bar, then @var{bottom} returned by @code{window-edges} is the
-same as the value of @code{(window-height)}, @var{right} is almost the
-same as the value of @code{(window-width)}, and @var{top} and
-@var{left} are zero. For example, the edges of the following window
-are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
-columns, the last column of the window (column 7) holds a border
-rather than text. The last row (row 4) holds the mode line, shown
-here with @samp{xxxxxxxxx}.
-
-@example
-@group
- 0
- _______
- 0 | |
- | |
- | |
- | |
- xxxxxxxxx 4
-
- 7
-@end group
-@end example
-
-In the following example, let's suppose that the frame is 7
-columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
-and the edges of the right window are @w{@samp{4 0 7 3}}.
-The inside edges of the left window are @w{@samp{0 0 3 2}},
-and the inside edges of the right window are @w{@samp{4 0 7 2}},
-
-@example
-@group
- ___ ___
- | | |
- | | |
- xxxxxxxxx
-
- 0 34 7
-@end group
-@end example
-
-@defun window-pixel-edges &optional window
-This function is like @code{window-edges} except that, on a graphical
-display, the edge values are measured in pixels instead of in
-character lines and columns.
-@end defun
-
-@defun window-inside-pixel-edges &optional window
-This function is like @code{window-inside-edges} except that, on a
-graphical display, the edge values are measured in pixels instead of
-in character lines and columns.
-@end defun
-
-@node Resizing Windows
-@section Changing the Size of a Window
-@cindex window resizing
-@cindex resize window
-@cindex changing window size
-@cindex window size, changing
-
- The window size functions fall into two classes: high-level commands
-that change the size of windows and low-level functions that access
-window size. Emacs does not permit overlapping windows or gaps between
-windows, so resizing one window affects other windows.
-
-@deffn Command enlarge-window size &optional horizontal
-This function makes the selected window @var{size} lines taller,
-stealing lines from neighboring windows. It takes the lines from one
-window at a time until that window is used up, then takes from another.
-If a window from which lines are stolen shrinks below
-@code{window-min-height} lines, that window disappears.
-
-If @var{horizontal} is non-@code{nil}, this function makes
-@var{window} wider by @var{size} columns, stealing columns instead of
-lines. If a window from which columns are stolen shrinks below
-@code{window-min-width} columns, that window disappears.
-
-If the requested size would exceed that of the window's frame, then the
-function makes the window occupy the entire height (or width) of the
-frame.
-
-If there are various other windows from which lines or columns can be
-stolen, and some of them specify fixed size (using
-@code{window-size-fixed}, see below), they are left untouched while
-other windows are ``robbed.'' If it would be necessary to alter the
-size of a fixed-size window, @code{enlarge-window} gets an error
-instead.
-
-If @var{size} is negative, this function shrinks the window by
-@minus{}@var{size} lines or columns. If that makes the window smaller
-than the minimum size (@code{window-min-height} and
-@code{window-min-width}), @code{enlarge-window} deletes the window.
-
-@code{enlarge-window} returns @code{nil}.
-@end deffn
-
-@deffn Command enlarge-window-horizontally columns
-This function makes the selected window @var{columns} wider.
-It could be defined as follows:
-
-@example
-@group
-(defun enlarge-window-horizontally (columns)
- (interactive "p")
- (enlarge-window columns t))
-@end group
-@end example
-@end deffn
-
-@deffn Command shrink-window size &optional horizontal
-This function is like @code{enlarge-window} but negates the argument
-@var{size}, making the selected window smaller by giving lines (or
-columns) to the other windows. If the window shrinks below
-@code{window-min-height} or @code{window-min-width}, then it disappears.
-
-If @var{size} is negative, the window is enlarged by @minus{}@var{size}
-lines or columns.
-@end deffn
-
-@deffn Command shrink-window-horizontally columns
-This function makes the selected window @var{columns} narrower.
-It could be defined as follows:
-
-@example
-@group
-(defun shrink-window-horizontally (columns)
- (interactive "p")
- (shrink-window columns t))
-@end group
-@end example
-@end deffn
-
-@defun adjust-window-trailing-edge window delta horizontal
-This function makes the selected window @var{delta} lines taller or
-@var{delta} columns wider, by moving the bottom or right edge. This
-function does not delete other windows; if it cannot make the
-requested size adjustment, it signals an error. On success, this
-function returns @code{nil}.
-@end defun
-
-@defun fit-window-to-buffer &optional window max-height min-height
-This function makes @var{window} the right height to display its
-contents exactly. If @var{window} is omitted or @code{nil}, it uses
-the selected window.
-
-The argument @var{max-height} specifies the maximum height the window
-is allowed to be; @code{nil} means use the frame height. The argument
-@var{min-height} specifies the minimum height for the window;
-@code{nil} means use @code{window-min-height}. All these height
-values include the mode-line and/or header-line.
-@end defun
-
-@deffn Command shrink-window-if-larger-than-buffer &optional window
-This command shrinks @var{window} vertically to be as small as
-possible while still showing the full contents of its buffer---but not
-less than @code{window-min-height} lines. If @var{window} is not
-given, it defaults to the selected window.
-
-However, the command does nothing if the window is already too small to
-display the whole text of the buffer, or if part of the contents are
-currently scrolled off screen, or if the window is not the full width of
-its frame, or if the window is the only window in its frame.
-
-This command returns non-@code{nil} if it actually shrank the window
-and @code{nil} otherwise.
-@end deffn
-
-@defvar window-size-fixed
-If this variable is non-@code{nil}, in any given buffer,
-then the size of any window displaying the buffer remains fixed
-unless you explicitly change it or Emacs has no other choice.
-
-If the value is @code{height}, then only the window's height is fixed;
-if the value is @code{width}, then only the window's width is fixed.
-Any other non-@code{nil} value fixes both the width and the height.
-
-This variable automatically becomes buffer-local when set.
-
-Explicit size-change functions such as @code{enlarge-window}
-get an error if they would have to change a window size which is fixed.
-Therefore, when you want to change the size of such a window,
-you should bind @code{window-size-fixed} to @code{nil}, like this:
-
-@example
-(let ((window-size-fixed nil))
- (enlarge-window 10))
-@end example
-
-Note that changing the frame size will change the size of a
-fixed-size window, if there is no other alternative.
-@end defvar
-
-@cindex minimum window size
- The following two variables constrain the window-structure-changing
-functions to a minimum height and width.
-
-@defopt window-min-height
-The value of this variable determines how short a window may become
-before it is automatically deleted. Making a window smaller than
-@code{window-min-height} automatically deletes it, and no window may
-be created shorter than this. The default value is 4.
-
-The absolute minimum window height is one; actions that change window
-sizes reset this variable to one if it is less than one.
-@end defopt
-
-@defopt window-min-width
-The value of this variable determines how narrow a window may become
-before it is automatically deleted. Making a window smaller than
-@code{window-min-width} automatically deletes it, and no window may be
-created narrower than this. The default value is 10.
-
-The absolute minimum window width is two; actions that change window
-sizes reset this variable to two if it is less than two.
-@end defopt
-
-@node Coordinates and Windows
-@section Coordinates and Windows
-
-This section describes how to relate screen coordinates to windows.
-
-@defun window-at x y &optional frame
-This function returns the window containing the specified cursor
-position in the frame @var{frame}. The coordinates @var{x} and @var{y}
-are measured in characters and count from the top left corner of the
-frame. If they are out of range, @code{window-at} returns @code{nil}.
-
-If you omit @var{frame}, the selected frame is used.
-@end defun
-
-@defun coordinates-in-window-p coordinates window
-This function checks whether a particular frame position falls within
-the window @var{window}.
-
-The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
-. @var{y})}. The coordinates @var{x} and @var{y} are measured in
-characters, and count from the top left corner of the screen or frame.
-
-The value returned by @code{coordinates-in-window-p} is non-@code{nil}
-if the coordinates are inside @var{window}. The value also indicates
-what part of the window the position is in, as follows:
-
-@table @code
-@item (@var{relx} . @var{rely})
-The coordinates are inside @var{window}. The numbers @var{relx} and
-@var{rely} are the equivalent window-relative coordinates for the
-specified position, counting from 0 at the top left corner of the
-window.
-
-@item mode-line
-The coordinates are in the mode line of @var{window}.
-
-@item header-line
-The coordinates are in the header line of @var{window}.
-
-@item vertical-line
-The coordinates are in the vertical line between @var{window} and its
-neighbor to the right. This value occurs only if the window doesn't
-have a scroll bar; positions in a scroll bar are considered outside the
-window for these purposes.
-
-@item left-fringe
-@itemx right-fringe
-The coordinates are in the left or right fringe of the window.
-
-@item left-margin
-@itemx right-margin
-The coordinates are in the left or right margin of the window.
-
-@item nil
-The coordinates are not in any part of @var{window}.
-@end table
-
-The function @code{coordinates-in-window-p} does not require a frame as
-argument because it always uses the frame that @var{window} is on.
-@end defun
-
-@node Window Tree
-@section The Window Tree
-@cindex window tree
-
- A @dfn{window tree} specifies the layout, size, and relationship
-between all windows in one frame.
-
-@defun window-tree &optional frame
-This function returns the window tree for frame @var{frame}.
-If @var{frame} is omitted, the selected frame is used.
-
-The return value is a list of the form @code{(@var{root} @var{mini})},
-where @var{root} represents the window tree of the frame's
-root window, and @var{mini} is the frame's minibuffer window.
-
-If the root window is not split, @var{root} is the root window itself.
-Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
-@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split,
-and @code{t} for a vertical split, @var{edges} gives the combined size and
-position of the subwindows in the split, and the rest of the elements
-are the subwindows in the split. Each of the subwindows may again be
-a window or a list representing a window split, and so on. The
-@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})}
-similar to the value returned by @code{window-edges}.
-@end defun
-
-@node Window Configurations
-@section Window Configurations
-@cindex window configurations
-@cindex saving window information
-
- A @dfn{window configuration} records the entire layout of one
-frame---all windows, their sizes, which buffers they contain, what
-part of each buffer is displayed, and the values of point and the
-mark; also their fringes, margins, and scroll bar settings. It also
-includes the values of @code{window-min-height},
-@code{window-min-width} and @code{minibuffer-scroll-window}. An
-exception is made for point in the selected window for the current
-buffer; its value is not saved in the window configuration.
-
- You can bring back an entire previous layout by restoring a window
-configuration previously saved. If you want to record all frames
-instead of just one, use a frame configuration instead of a window
-configuration. @xref{Frame Configurations}.
-
-@defun current-window-configuration &optional frame
-This function returns a new object representing @var{frame}'s current
-window configuration. If @var{frame} is omitted, the selected frame
-is used.
-@end defun
-
-@defun set-window-configuration configuration
-This function restores the configuration of windows and buffers as
-specified by @var{configuration}, for the frame that @var{configuration}
-was created for.
-
-The argument @var{configuration} must be a value that was previously
-returned by @code{current-window-configuration}. This configuration is
-restored in the frame from which @var{configuration} was made, whether
-that frame is selected or not. This always counts as a window size
-change and triggers execution of the @code{window-size-change-functions}
-(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
-know how to tell whether the new configuration actually differs from the
-old one.
-
-If the frame which @var{configuration} was saved from is dead, all this
-function does is restore the three variables @code{window-min-height},
-@code{window-min-width} and @code{minibuffer-scroll-window}. In this
-case, the function returns @code{nil}. Otherwise, it returns @code{t}.
-
-Here is a way of using this function to get the same effect
-as @code{save-window-excursion}:
-
-@example
-@group
-(let ((config (current-window-configuration)))
- (unwind-protect
- (progn (split-window-vertically nil)
- @dots{})
- (set-window-configuration config)))
-@end group
-@end example
-@end defun
-
-@defspec save-window-excursion forms@dots{}
-This special form records the window configuration, executes @var{forms}
-in sequence, then restores the earlier window configuration. The window
-configuration includes, for each window, the value of point and the
-portion of the buffer that is visible. It also includes the choice of
-selected window. However, it does not include the value of point in
-the current buffer; use @code{save-excursion} also, if you wish to
-preserve that.
-
-Don't use this construct when @code{save-selected-window} is sufficient.
-
-Exit from @code{save-window-excursion} always triggers execution of the
-@code{window-size-change-functions}. (It doesn't know how to tell
-whether the restored configuration actually differs from the one in
-effect at the end of the @var{forms}.)
-
-The return value is the value of the final form in @var{forms}.
-For example:
-
-@example
-@group
-(split-window)
- @result{} #<window 25 on control.texi>
-@end group
-@group
-(setq w (selected-window))
- @result{} #<window 19 on control.texi>
-@end group
-@group
-(save-window-excursion
- (delete-other-windows w)
- (switch-to-buffer "foo")
- 'do-something)
- @result{} do-something
- ;; @r{The screen is now split again.}
-@end group
-@end example
-@end defspec
-
-@defun window-configuration-p object
-This function returns @code{t} if @var{object} is a window configuration.
-@end defun
-
-@defun compare-window-configurations config1 config2
-This function compares two window configurations as regards the
-structure of windows, but ignores the values of point and mark and the
-saved scrolling positions---it can return @code{t} even if those
-aspects differ.
-
-The function @code{equal} can also compare two window configurations; it
-regards configurations as unequal if they differ in any respect, even a
-saved point or mark.
-@end defun
-
-@defun window-configuration-frame config
-This function returns the frame for which the window configuration
-@var{config} was made.
-@end defun
-
- Other primitives to look inside of window configurations would make
-sense, but are not implemented because we did not need them. See the
-file @file{winner.el} for some more operations on windows
-configurations.
-
-@node Window Hooks
-@section Hooks for Window Scrolling and Changes
-@cindex hooks for window operations
-
-This section describes how a Lisp program can take action whenever a
-window displays a different part of its buffer or a different buffer.
-There are three actions that can change this: scrolling the window,
-switching buffers in the window, and changing the size of the window.
-The first two actions run @code{window-scroll-functions}; the last runs
-@code{window-size-change-functions}.
-
-@defvar window-scroll-functions
-This variable holds a list of functions that Emacs should call before
-redisplaying a window with scrolling. It is not a normal hook, because
-each function is called with two arguments: the window, and its new
-display-start position.
-
-Displaying a different buffer in the window also runs these functions.
-
-These functions must be careful in using @code{window-end}
-(@pxref{Window Start}); if you need an up-to-date value, you must use
-the @var{update} argument to ensure you get it.
-
-@strong{Warning:} don't use this feature to alter the way the window
-is scrolled. It's not designed for that, and such use probably won't
-work.
-@end defvar
-
-@defvar window-size-change-functions
-This variable holds a list of functions to be called if the size of any
-window changes for any reason. The functions are called just once per
-redisplay, and just once for each frame on which size changes have
-occurred.
-
-Each function receives the frame as its sole argument. There is no
-direct way to find out which windows on that frame have changed size, or
-precisely how. However, if a size-change function records, at each
-call, the existing windows and their sizes, it can also compare the
-present sizes and the previous sizes.
-
-Creating or deleting windows counts as a size change, and therefore
-causes these functions to be called. Changing the frame size also
-counts, because it changes the sizes of the existing windows.
-
-It is not a good idea to use @code{save-window-excursion} (@pxref{Window
-Configurations}) in these functions, because that always counts as a
-size change, and it would cause these functions to be called over and
-over. In most cases, @code{save-selected-window} (@pxref{Selecting
-Windows}) is what you need here.
-@end defvar
-
-@defvar redisplay-end-trigger-functions
-This abnormal hook is run whenever redisplay in a window uses text that
-extends past a specified end trigger position. You set the end trigger
-position with the function @code{set-window-redisplay-end-trigger}. The
-functions are called with two arguments: the window, and the end trigger
-position. Storing @code{nil} for the end trigger position turns off the
-feature, and the trigger value is automatically reset to @code{nil} just
-after the hook is run.
-@end defvar
-
-@defun set-window-redisplay-end-trigger window position
-This function sets @var{window}'s end trigger position at
-@var{position}.
-@end defun
-
-@defun window-redisplay-end-trigger &optional window
-This function returns @var{window}'s current end trigger position.
-If @var{window} is @code{nil} or omitted, it uses the selected window.
-@end defun
-
-@defvar window-configuration-change-hook
-A normal hook that is run every time you change the window configuration
-of an existing frame. This includes splitting or deleting windows,
-changing the sizes of windows, or displaying a different buffer in a
-window. The frame whose window configuration has changed is the
-selected frame when this hook runs.
-@end defvar
-
-@ignore
- arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
-@end ignore