diff options
| author | Ken Raeburn <raeburn@raeburn.org> | 2015-11-01 01:42:21 -0400 |
|---|---|---|
| committer | Ken Raeburn <raeburn@raeburn.org> | 2015-11-01 01:42:21 -0400 |
| commit | 39372e1a1032521be74575bb06f95a3898fbae30 (patch) | |
| tree | 754bd242a23d2358ea116126fcb0a629947bd9ec /doc/lispref | |
| parent | 6a3121904d76e3b2f63007341d48c5c1af55de80 (diff) | |
| parent | e11aaee266da52937a3a031cb108fe13f68958c3 (diff) | |
| download | emacs-39372e1a1032521be74575bb06f95a3898fbae30.tar.gz | |
merge from trunk
Diffstat (limited to 'doc/lispref')
58 files changed, 9913 insertions, 4531 deletions
diff --git a/doc/lispref/.gitignore b/doc/lispref/.gitignore deleted file mode 100644 index ba74d365995..00000000000 --- a/doc/lispref/.gitignore +++ /dev/null @@ -1,13 +0,0 @@ -texput.log -elisp.?? -elisp.??? -config.log -config.cache -config.status -Makefile -makefile -elisp -elisp-? -elisp-?? -elisp1* -elisp2* diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog.1 index d2e86c25cc1..e508839cd5b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog.1 @@ -1,3 +1,1634 @@ +2015-03-29 Glenn Morris <rgm@gnu.org> + + * objects.texi (Equality Predicates): Fix typo in example. + +2015-03-25 Stefan Monnier <monnier@iro.umontreal.ca> + + * positions.texi (Excursions, Narrowing): `save-excursion' does not + save&restore the mark any more. + +2015-03-24 Paul Eggert <eggert@cs.ucla.edu> + + * numbers.texi (Float Basics): Improve ldexp documentation. + +2015-03-23 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Event Input Misc): Fix incorrect usage of @code. + (Bug#20174) + (Accessing Mouse): Expand documentation of 'posn-actual-col-row'. + (Bug#20169) + More accurate description of 'posn-object-x-y'. (Bug#20168) + +2015-03-23 Daiki Ueno <ueno@gnu.org> + + * processes.texi (Asynchronous Processes): Mention `make-process'. + +2015-03-18 Eli Zaretskii <eliz@gnu.org> + + * minibuf.texi (Basic Completion): Fix a typo. (Bug#20108) + +2015-03-09 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (seq-into): Add documentation for the new + seq-into function. + +2015-03-03 Eli Zaretskii <eliz@gnu.org> + + * processes.texi (Synchronous Processes): Update documentation of + call-process-shell-command and process-file-shell-command. + +2015-03-03 Daniel Colascione <dancol@dancol.org> + + * control.texi (Generators): Correct missing word. Clarify which + forms are legal in which parts of `unwind-protect'. Fix orphaned + close parenthesis. + + * objects.texi (Finalizer Type): New section for finalizer objects. + (Type Predicates): Mention finalizers in `type-of' documentation. + * elisp.texi (Top): Link to finalizer type. + +2015-03-02 Daniel Colascione <dancol@dancol.org> + + * control.texi (Generators): New section + * elisp.texi: Reference new section. + +2015-02-28 Eli Zaretskii <eliz@gnu.org> + + * searching.texi (Char Classes): Update the documentation of + [:alpha:] and [:alnum:]. (Bug#19878) + +2015-02-27 Eli Zaretskii <eliz@gnu.org> + + * os.texi (Startup Summary): + * display.texi (Window Systems): Mention peculiarities of daemon + mode on MS-Windows. + +2015-02-11 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters): Update description of + fullscreen frame parameter. Describe `fullscreen-restore' + parameter. + +2015-02-09 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (Sequence Functions): Update documentation + examples for seq-group-by. + +2015-02-09 Eli Zaretskii <eliz@gnu.org> + + * positions.texi (Screen Lines): Update the documentation of + vertical-motion to document the new additional argument. + +2015-02-06 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (Sequence Functions): Add documentation for + seq-mapcat, seq-partition and seq-group-by. + +2015-02-05 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Size of Displayed Text): Remove description of + optional argument BUFFER of `window-text-pixel-size'. + +2015-02-01 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Size of Displayed Text): Describe optional + argument BUFFER of `window-text-pixel-size'. + +2015-01-28 Eli Zaretskii <eliz@gnu.org> + + * searching.texi (Regexp Search): Add a cross-reference to "Syntax + of Regexps". (Bug#19668) + +2015-01-28 Daniel Koning <dk@danielkoning.com> (tiny change) + + * commands.texi (Drag Events, Motion Events, Event Examples) + (Accessing Mouse): Describe actual range of values that mouse + position objects can have. + +2015-01-28 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Manipulating Buttons): Explain more about the + 'action' property. (Bug#19628) + + * text.texi (Clickable Text): Improve indexing. (Bug#19629) + + * variables.texi (Creating Buffer-Local): Improve indexing. (Bug#19608) + + * frames.texi (Display Feature Testing): Make the description of + x-server-version and x-server-vendor less X-specific. (Bug#19502) + +2015-01-15 Eli Zaretskii <eliz@gnu.org> + + * streams.texi (Input Functions): Document 'set-binary-mode'. + (Output Functions): Cross-reference to documentation of + 'set-binary-mode'. + +2015-01-04 Paul Eggert <eggert@cs.ucla.edu> + + batch write-region no longer says "Wrote FOO" + * files.texi (Writing to Files): Document this. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/elisp.info, elisp.html): + Use them. + +2014-12-30 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Amend description of + `with-temp-buffer-window'. Add descriptions for + `with-current-buffer-window', `with-displayed-buffer-window' and + `temp-buffer-resize-mode', `temp-buffer-max-height' and + `temp-buffer-max-width'. + +2014-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (System Environment): Update for system-name changes. + +2014-12-27 Glenn Morris <rgm@gnu.org> + + * control.texi (Pattern matching case statement): + * os.texi (Desktop Notifications): + * modes.texi (Defining Minor Modes, SMIE Lexer): Markup fixes. + +2014-12-27 Eli Zaretskii <eliz@gnu.org> + + * windows.texi (Recombining Windows): Index subject of sections. + + * variables.texi (Variables with Restricted Values) + (Generalized Variables): Index subject of sections. + + * text.texi (Buffer Contents, Examining Properties) + (Changing Properties, Property Search, Substitution): Index + subject of sections. + + * syntax.texi (Motion and Syntax, Parsing Expressions) + (Motion via Parsing, Position Parse, Control Parsing): Index + subject of sections. + + * strings.texi (Predicates for Strings, Creating Strings) + (Modifying Strings, Text Comparison): Index subject of sections. + + * searching.texi (Syntax of Regexps, Regexp Special) + (Regexp Functions, Regexp Functions): Index subject of sections. + + * processes.texi (Subprocess Creation, Process Information): Index + subject of sections. + + * positions.texi (Screen Lines): Index subject of sections. + + * nonascii.texi (Scanning Charsets, Specifying Coding Systems): + Index subject of sections. + + * minibuf.texi (Text from Minibuffer, Object from Minibuffer) + (Multiple Queries, Minibuffer Contents): Index subject of + sections. + + * markers.texi (Predicates on Markers, Creating Markers) + (Information from Markers, Moving Markers): Index subject of + sections. + + * macros.texi (Defining Macros, Problems with Macros): Index + subject of sections. + + * loading.texi (Loading Non-ASCII, Where Defined): Index subject + of sections. + + * lists.texi (List-related Predicates, List Variables, Setcar) + (Setcdr, Plist Access): Index subject of sections. + + * keymaps.texi (Controlling Active Maps, Scanning Keymaps) + (Modifying Menus): Index subject of sections. + + * help.texi (Accessing Documentation, Help Functions): Index + subject of sections. + + * hash.texi (Hash Access): Index subject of sections. + + * functions.texi (Core Advising Primitives) + (Advising Named Functions, Porting old advices): Index subject of + sections. + + * frames.texi (Creating Frames, Initial Parameters) + (Position Parameters, Buffer Parameters, Minibuffers and Frames) + (Pop-Up Menus, Drag and Drop): Index subject of sections. + + * files.texi (Visiting Functions, Kinds of Files) + (Unique File Names): Index subject of sections. + + * display.texi (Refresh Screen, Echo Area Customization) + (Warning Variables, Warning Options, Delayed Warnings) + (Temporary Displays, Managing Overlays, Overlay Properties) + (Finding Overlays, Size of Displayed Text, Defining Faces) + (Attribute Functions, Displaying Faces, Face Remapping) + (Basic Faces, Font Lookup, Fontsets, Replacing Specs) + (Defining Images, Showing Images): Index subject of sections. + + * debugging.texi (Debugging, Explicit Debug) + (Invoking the Debugger, Excess Open, Excess Close): Index subject + of sections. + + * customize.texi (Defining New Types, Applying Customizations) + (Custom Themes): Index subject of sections. + + * control.texi (Sequencing, Combining Conditions) + (Processing of Errors, Cleanups): Index subject of sections. + + * compile.texi (Eval During Compile): Index subject of sections. + + * commands.texi (Using Interactive, Distinguish Interactive) + (Command Loop Info, Classifying Events, Event Mod) + (Invoking the Input Method): Index subject of sections. + + * buffers.texi (Buffer List, Buffer Gap): Index subject of sections. + + * backups.texi (Making Backups, Numbered Backups, Backup Names) + (Reverting): Index subject of sections. + + * abbrevs.texi (Abbrev Tables, Defining Abbrevs, Abbrev Files) + (Abbrev Expansion, Standard Abbrev Tables, Abbrev Properties) + (Abbrev Table Properties): Index subject of sections. + + * os.texi (Time of Day, Time Conversion, Time Parsing) + (Time Calculations, Idle Timers): Index subject of sections. + +2014-12-25 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows): Resync @menu order with @node order. + + * minibuf.texi (Minibuffer Windows): Add descriptions of + `resize-mini-windows' and `max-mini-window-height'. + +2014-12-25 Glenn Morris <rgm@gnu.org> + + * windows.texi (Windows): Sync @menu order with @node order. + + * sequences.texi (Sequence Functions): Copyedits. + + * control.texi (Pattern matching case statement): + * positions.texi (List Motion): + * streams.texi (Output Functions): + * strings.texi (Text Comparison): + * text.texi (Document Object Model): Markup fixes. + +2014-12-22 Paul Eggert <eggert@cs.ucla.edu> + + Remove obsolete references to pre-C99 builds + * internals.texi (C Integer Types): Don't mention pre-C99 compilers. + +2014-12-19 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Resizing Windows): Describe new argument of + `fit-window-to-buffer'. Move description of `window-size-fixed' + to new section below. + (Preserving Window Sizes): New section describing + `window-size-fixed' and `window-preserve-size'. + (Display Action Functions): Describe `preserve-size' alist + entry. + (Window Parameters): Describe `preserved-size' parameter. + +2014-12-18 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Low-Level Font): Document font-info and query-font. + +2014-12-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * display.texi (Forcing Redisplay): Remove references to + redisplay-dont-pause and redisplay-preemption-period (which doesn't + even exist). + +2014-12-16 Nicolas Petton <petton.nicolas@gmail.com> + + * sequences.texi (Seq Library): Add documentation for seq.el. + +2014-12-15 Alan Mackenzie <acm@muc.de> + + "Advice" is a mass noun. Amend text accordingly. + * functions.texi: (Advising Functions, Core Advising Primitives) + (Advising Named Functions, Advice combinators) + (Porting old advice): Replace, e.g., "an advice" with "advice". + +2014-12-13 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Relative File Names): Mention `directory-name-p'. + +2014-12-13 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Comparing Text): Prevent a text string from being + broken between 2 lines. (Bug#19257) + +2014-12-09 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Contents of Directories): + Document directory-files-recursively. + +2014-12-04 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'buffer-substring-with-bidi-context'. + + * text.texi (Buffer Contents): + Mention 'buffer-substring-with-bidi-context' with a cross-reference. + +2014-12-02 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'bidi-find-overridden-directionality'. + +2014-11-29 Paul Eggert <eggert@cs.ucla.edu> + + Lessen focus on ChangeLog files, as opposed to change log entries. + * intro.texi (Acknowledgments): ChangeLog file -> change log entries. + * tips.texi (Library Headers): Emacs uses a version control system. + +2014-11-27 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): Mention `dom-pp'. + +2014-11-26 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): New node to document dom.el. + +2014-11-24 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network Security): Made into its own section and + fleshed out. + (Network Security): Mention more NSM variables. + (Processes): Move the Network Security Manager stuff to the Emacs + manual. + +2014-11-23 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network): Mention the new :warn-unless-encrypted + parameter to `open-network-stream'. + (Network): Mention the Network Security Manager. + +2014-11-21 Ulf Jasper <ulf.jasper@web.de> + + * text.texi (Parsing HTML/XML): Document new optional parameter + 'discard-comments' of 'libxml-parse(html|xml)-region'. + +2014-11-18 Leo Liu <sdl.web@gmail.com> + + * functions.texi (Advising Named Functions): + Document define-advice. + +2014-11-17 Paul Eggert <eggert@cs.ucla.edu> + + Improve time stamp handling, and be more consistent about it. + * os.texi (Time of Day, Time Conversion, Time Parsing) + (Processor Run Time, Time Calculations): + Document the new behavior, plus be clearer about the old behavior. + (Idle Timers): Take advantage of new functionality. + +2014-11-16 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Special Properties): Mention `inhibit-read-only'. + +2014-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (Time of Day): + Use leading zero with 24-hour times less than 10:00. + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-11-07 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): Rewrite description of + `frame-inhibit-implied-resize'. + +2014-10-22 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters): Replace "frame contents" by + "frame's text area". Add reference to Size and Position + section. + (Size and Position): Major rewrite. Add explanations for + frame's default font, text and display areas. Add descriptions + for `set-frame-font', `frame-text-height', `frame-text-width' + and `frame-inhibit-implied-resize'. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-20 Tom Tromey <tom@tromey.com> + + * objects.texi (Type Predicates): Don't mention display-table-p. + +2014-10-15 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Character Properties): Document the new + properties 'bracket-type' and 'paired-bracket'. + + * display.texi (Bidirectional Display): Update the version of the + UBA to which we are conforming. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-10-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi (DATE): Bump to October 2014. + +2014-10-09 Glenn Morris <rgm@gnu.org> + + * frames.texi (Multiple Terminals): Copyedits. + +2014-10-09 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Multiple Terminals): Improve the description of X + display names. Add index entries. + (Basic Parameters): Add a cross-reference to where X display names + are described. + (Position Parameters): Mention that positional parameters of the + form (+ POS) can be negative if they are on a non-primary monitor + of a multi-monitor display. (Bug#18636) + (Creating Frames): Mention that on multi-monitor displays the + frame might be positioned differently than specified by the frame + parameters alist. + +2014-10-08 Leo Liu <sdl.web@gmail.com> + + * streams.texi (Output Functions): Document new argument ENSURE to + terpri. (Bug#18652) + +2014-10-04 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Scroll Bars): Add description of horizontal scroll + bars and associated functions. + * frames.texi (Layout Parameters): Add horizontal scroll bar + entries. Remove paragraph on "combined fringe widths". + * windows.texi (Window Sizes): Describe affects of horizontal + scroll bars on window layout and sizes. Fix description of + window-full-height-p. + (Resizing Windows): Mention horizontal scroll bar. + +2014-10-04 Glenn Morris <rgm@gnu.org> + + * commands.texi (Generic Commands): Copyedits. + + * display.texi (Scroll Bars): + * modes.texi (Header Lines): Copyedits. + + * buffers.texi (Buffer List): + * display.texi (Image Descriptors, Defining Images): + * functions.texi (Core Advising Primitives): Small fixes re @var usage. + + * windows.texi (Window Sizes, Resizing Windows): Copyedits. + + * frames.texi (Multiple Terminals): Copyedits re multiple monitors. + +2014-10-03 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters, Size and Position): Mention that + with some window managers you have to set `frame-resize-pixelwise' + in order make a frame truly fullscreen or maximized. + +2014-10-01 Paul Eggert <eggert@cs.ucla.edu> + + Improve doc for use of 'int', and discuss 'ssize_t'. + * internals.texi (C Integer Types): Mention 'int' for other + randomish values that lie in 'int' range. Mention 'ssize_t'. See: + http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html + + Use AUTO_CONS instead of SCOPED_CONS, etc. + * internals.texi (Stack-allocated Objects): + Adjust to match the revised, less error-prone macros. + +2014-09-30 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (Stack-allocated Objects): Further improvements. + Give an example of misuse. + +2014-09-30 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Stack-allocated Objects): Minor improvements of + the wording and the indexing. + +2014-09-30 Dmitry Antipov <dmantipov@yandex.ru> + + * internals.texi (Stack-allocated Objects): Describe this feature. + +2014-09-15 Daniel Colascione <dancol@dancol.org> + + * text.texi (Registers): Make `insert-register' documentation + reflect interface change. + +2014-09-08 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Core Advising Primitives): Add a note about the + confusing treatment of `interactive' for :filter-args (bug#18399). + +2014-09-07 Michael Albinus <michael.albinus@gmx.de> + + * strings.texi (Text Comparison): Describe `string-collate-equalp' + and `string-collate-lessp'. + +2014-09-06 Leo Liu <sdl.web@gmail.com> + + * control.texi (Pattern matching case statement): Document vector + qpattern. (Bug#18327) + +2014-08-29 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Functions that Rearrange Lists): + Remove description of sort ... + * sequences.texi (Sequence Functions): ... and generalize + it for sequences. Add an example. + +2014-08-28 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): Update the Emacs's class + of bidirectional conformance. + +2014-08-27 Dmitry Antipov <dmantipov@yandex.ru> + + * eval.texi (Eval): Mention possible recovery from stack overflow. + +2014-07-11 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Garbage Collection): Fix last change. + +2014-07-11 Dmitry Antipov <dmantipov@yandex.ru> + + * internals.texi (Garbage Collection): Mention memory-info. + +2014-07-11 Michael Albinus <michael.albinus@gmx.de> + + * minibuf.texi (Intro to Minibuffers, Reading a Password): + Password hiding is available in batch mode, do not mention it in + the exclusion list. Mention `read-hide-char'. (Bug#17839) + +2014-07-09 Stefan Monnier <monnier@iro.umontreal.ca> + + * debugging.texi (Function Debugging, Debugger Commands): + Update debug-on-entry w.r.t behavior after redefinitions (bug#17902). + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * help.texi (Help Functions): "Online" help doesn't mean what it + used to any more. + +2014-07-02 Stefan Monnier <monnier@iro.umontreal.ca> + + * keymaps.texi (Key Lookup): Remove mention of indirect entries. + (Scanning Keymaps): Reword the `noindirect' argument. + +2014-06-28 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Intro to Minibuffers): Batch mode is basic. + (Reading a Password): Mention batch mode. (Bug#17839) + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (html): Declare as PHONY. + (${buildinfodir}): New rule. + ($(buildinfodir)/elisp.info): Use order-only prereq for output dir. + Use $<. + (elisp.dvi, elisp.html, elisp.pdf): Use $<. + (elisp.ps): New rule. + +2014-06-21 Eli Zaretskii <eliz@gnu.org> + + * positions.texi (Screen Lines): Clarify how columns are counted + by vertical-motion. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-15 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Accessing Mouse): Improve the wording of the + posn-col-row documentation. (Bug#17768) + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-09 Paul Eggert <eggert@cs.ucla.edu> + + Say (accept-process-output P)'s result pertains to P if P is non-nil. + * processes.texi (Accepting Output): Mention that if PROCESS is non-nil, + the return value is about PROCESS, not about other processes. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * os.texi (Startup Summary): Small fix for initial-buffer-choice. + + * files.texi (Subroutines of Visiting): Mention uniquify. + + * numbers.texi (Comparison of Numbers): Copyedits. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * display.texi (Window Systems): Remove window-setup-hook. + * os.texi (Startup Summary, Init File): + Improve description of window-setup-hook. + (Terminal-Specific): Update window-setup-hook cross-reference. + * hooks.texi (Standard Hooks): Update window-setup-hook cross-reference. + + * display.texi (Overlay Properties): Update re priority. (Bug#17234) + + * package.texi (Package Archives): Mention signing packages. + +2014-06-07 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Click Events): Update contents of click event's + position list due to last changes in make_lispy_position. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * text.texi (Buffer Contents): + Update for filter-buffer-substring changes. + + * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. + * functions.texi (Advising Functions): Standardize menu case. + +2014-05-26 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Invisible Text): Clarify the description of + line-move-ignore-invisible. (Bug#17511) + +2014-05-22 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Don't mention when and how + SEQ to nreverse is mutated. + +2014-05-21 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Update nreverse. + +2014-05-19 Paul Eggert <eggert@cs.ucla.edu> + + Allow any non-nil value to count as true in bool-vector. + * sequences.texi (Bool-Vectors): Coalesce discussion of how to + print them. bool-vector's args need not be t or nil. + +2014-05-19 Dmitry Antipov <dmantipov@yandex.ru> + + * sequences.texi (Bool-vectors): Mention bool-vector. + +2014-05-17 Paul Eggert <eggert@cs.ucla.edu> + + Assume C99 or later (Bug#17487). + * internals.texi (C Dialect): Document this. + +2014-05-15 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Building Cons Cells and Lists): + Remove description of `reverse' and `'nreverse' to generalize them... + * sequences.texi (Sequences): ...for sequences here. + +2014-05-14 Glenn Morris <rgm@gnu.org> + + * files.texi (Changing Files): Mention with-file-modes. + +2014-05-08 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (C Dialect): New section. + (C Integer Types): Mention bool_bf. + +2014-04-30 Stefan Monnier <monnier@iro.umontreal.ca> + + * processes.texi (Filter Functions, Sentinels): Advertise add-function. + +2014-04-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * windows.texi (Window Configurations, Window Configurations): + Window configs don't store marks any more. + +2014-04-25 Eli Zaretskii <eliz@gnu.org> + + * strings.texi (Text Comparison): Mention equal-including-properties + for when text properties of the strings matter for comparison. + +2014-04-22 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Registers): Document register-read-with-preview. + + * internals.texi (Building Emacs): Improve indexing. + +2014-04-17 Daniel Colascione <dancol@dancol.org> + + * frames.texi (Terminal Parameters): Document new + tty-mode-set-strings and tty-mode-reset-strings terminal + parameters. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-04-09 Daniel Colascione <dancol@dancol.org> + + * errors.texi (Standard Errors): Document required error + parameters for `scan-error'. + + * positions.texi (List Motion): Explain new `up-list' arguments. + Mention `backward-up-list'. + +2014-04-08 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Programmed Completion): Improve phrasing, remove + incorrect bullet count. + +2014-04-07 Glenn Morris <rgm@gnu.org> + + * os.texi (Recording Input): Dribble files may contain passwords. + + * backups.texi (Making Backups, Reverting): + Update for default values of some -function vars no longer being nil. + (Reverting): Update for buffer-stale-function + also applying to file-buffers. + +2014-03-31 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Completion in Buffers): Discuss using lazy + completion tables for inline completion. + +2014-03-28 Glenn Morris <rgm@gnu.org> + + * os.texi (Terminal-Specific): Mention term-file-aliases. + +2014-03-26 Eli Zaretskii <eliz@gnu.org> + + * files.texi (Kinds of Files): Improve documentation of + file-symlink-p. (Bug#17073) Add cross-references. + +2014-03-26 Barry O'Reilly <gundaetiapo@gmail.com> + + * markers.texi (Moving Marker Positions): The 2014-03-02 doc + change mentioning undo's inability to handle relocated markers no + longer applies. See bug#16818. + * text.texi (Undo): Expand documentation of (TEXT . POS) and + (MARKER . ADJUSTMENT) undo elements. + +2014-03-26 Glenn Morris <rgm@gnu.org> + + * files.texi (File Locks): All systems support locking. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * commands.texi (Defining Commands): + Mention that interactive-only also affects describe-function. + + * functions.texi (Declare Form): Add interactive-only. + * commands.texi (Defining Commands) Mention declare. + + * commands.texi (Defining Commands): List interactive-only values. + +2014-03-22 Eli Zaretskii <eliz@gnu.org> + + * functions.texi (Core Advising Primitives): Fix cross-reference + in last change. + +2014-03-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): Explain a bit more how + arguments work. + (Advice combinators): New node. + (Core Advising Primitives): Use it. Expand description of "depth". + (Advising Named Functions): Document limitation of advices on macros. + +2014-03-21 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): In `frame-resize-pixelwise' + description drop remark about frame maximization. + * windows.texi (Display Action Functions): Add description for + `display-buffer-no-window' and explain use of `allow-no-window' + alist entries. + +2014-03-21 Glenn Morris <rgm@gnu.org> + + * commands.texi (Defining Commands): Copyedit re `interactive-only'. + +2014-03-20 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (C Integer Types): Prefer 'false' and 'true' + to '0' and '1' for booleans. + +2014-03-19 Paul Eggert <eggert@cs.ucla.edu> + + * numbers.texi: Improve and clarify a bit, and fix some minor bugs. + Remove now-obsolete hypothetical note about negative division, + as the C standard has changed. + + Fix porting inconsistency about rounding to even. + * numbers.texi (Numeric Conversions, Rounding Operations): + Document that 'round' and 'fround' round to even. + +2014-03-18 Juanma Barranquero <lekktu@gmail.com> + + * customize.texi (Variable Definitions): Recommend avoiding + destructive modification of the value argument of :set (bug#16755). + +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * modes.texi (Auto-Indentation): Mention electric-indent variables. + +2014-03-18 Juanma Barranquero <lekktu@gmail.com> + + * functions.texi (Advising Named Functions): Fix reference. + +2014-03-18 Paul Eggert <eggert@cs.ucla.edu> + + Improve documentation for integer and floating-point basics. + * numbers.texi (Numbers, Integer Basics, Float Basics): + Document the basics a bit more precisely. Say more clearly + that Emacs floating-point numbers are IEEE doubles on all + current platforms. Give more details about frexp. + Say more clearly that '1.' is an integer. + (Predicates on Numbers): Fix wholenump typo. + * objects.texi (Integer Type): Adjust to match numbers.texi. + +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): Try and improve the text. + Add example use of advice-add (bug#16959). + (Core Advising Primitives): Rename. Explain handling of interactive + specs, including advice-eval-interactive-spec. + (Advising Named Functions): Try and better explain the difference with + add-function. + (Porting old advices): New node. + +2014-03-18 Paul Eggert <eggert@cs.ucla.edu> + + Style fixes for floating-point doc. + * commands.texi, customize.texi, display.texi, elisp.texi, files.texi: + * frames.texi, hash.texi, internals.texi, keymaps.texi, lists.texi: + * minibuf.texi, nonascii.texi, numbers.texi, objects.texi, os.texi: + * processes.texi, streams.texi, strings.texi, text.texi: + * variables.texi, windows.texi: + Hyphenate "floating-point" iff it precedes a noun. + Reword to avoid nouns and hyphenation when that's easy. + Prefer "integer" to "integer number" and "is floating point" + to "is a floating point number". + Prefer "@minus{}" to "-" when it's a minus. + +2014-03-16 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Rewrite descriptions of + `with-output-to-temp-buffer' and `with-temp-buffer-window'. + * help.texi (Help Functions): Rewrite description of `with-help-window'. + +2014-03-15 Dmitry Gutov <dgutov@yandex.ru> + + * display.texi (Blinking): Update WRT to the new + `blink-matchin-paren' behavior. + +2014-03-14 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Say that + `with-temp-buffer-window' makes its buffer current. + * frames.texi (Size and Position): Describe new option + `frame-resize-pixelwise'. Rewrite descriptions of + `set-frame-size', `set-frame-height' and `set-frame-width'. + +2014-03-09 Martin Rudalics <rudalics@gmx.at> + + * elisp.texi (Top): Rename section "Width" to "Size of Displayed Text". + * text.texi (Primitive Indent): + * strings.texi (String Basics): + * sequences.texi (Sequence Functions): Update references accordingly. + * display.texi (Size of Displayed Text): Rename section from + "Width". Add description for `window-text-pixel-size'. + (Window Dividers): Reword description of window dividers. + * frames.texi (Layout Parameters): Improve description of window + divider parameters. + * windows.texi (Window Sizes): Add descriptions of + `window-mode-line-height' and `window-header-line-height'. + (Coordinates and Windows): Mention window dividers. + +2014-03-07 Martin Rudalics <rudalics@gmx.at> + + * buffers.texi (The Buffer List): Rename node to Buffer List. + Describe `buffer-list-update-hook'. + * elisp.texi (Top): "The Buffer List" renamed to "Buffer List". + Add node for Window Dividers. + * hooks.texi (Standard Hooks): Add reference to + `buffer-list-update-hook'. + * windows.texi (Window Sizes): Describe `window-min-size'. + (Splitting Windows): Update description of `split-window'. + (Selecting Windows): Update description of `select-window'. + +2014-03-06 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): Rewrite entries for + `fit-frame-to-buffer' and `fit-frame-to-buffer-margins'. + Add description for `fit-frame-to-buffer-sizes'. + * windows.texi (Resizing Windows): Add descriptions for + pixelwise resizing. Add entries for `window-resize-pixelwise' + and `fit-window-to-buffer-horizontally'. + Rewrite `fit-window-to-buffer' entry. + +2014-03-06 Xue Fuqiao <xfq@gnu.org> + + * internals.texi (Window Internals): Remove field `region_showing'. + +2014-03-06 Glenn Morris <rgm@gnu.org> + + * searching.texi (Replacing Match): + Remove incorrect, uninteresting return value. (Bug#16942) + +2014-03-05 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Window Dividers): New section. + * frames.texi (Layout Parameters): Add right-divider-width and + bottom-divider-width. + * windows.texi (Window Sizes): Redraw schematic and rewrite its + description. Rewrite descriptions of `window-total-height', + `window-total-width', `window-total-size', `window-body-height', + `window-body-width' and `window-size-fixed'. Add descriptions + for `window-pixel-height', `window-pixel-width', + `window-min-height' and `window-min-width'. Remove description + of `window-size-fixed-p' moving part of it to that of + `window-size-fixed'. + (Resizing Windows): Mention dividers when talking about minimum sizes. + +2014-03-05 Glenn Morris <rgm@gnu.org> + + * modes.texi (SMIE Customization): New section. + * elisp.texi (Top): Update detailed menu. + +2014-03-04 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows and Frames): Add some missing &optional + designators. Adjust description of window-in-direction. + +2014-03-02 Barry O'Reilly <gundaetiapo@gmail.com> + + * markers.texi (Moving Marker Positions): Clarify guidance about + when to move markers and when to create a new one, as discussed at + http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16818#17 + +2014-03-02 Glenn Morris <rgm@gnu.org> + + * text.texi (Decompression): New node. + * elisp.texi (Top): Update detailed menu. + +2014-03-01 Glenn Morris <rgm@gnu.org> + + * display.texi (Forcing Redisplay): Mention pre-redisplay-function. + +2014-02-28 Xue Fuqiao <xfq@gnu.org> + + * functions.texi (Advising Functions, Advising Named Functions): + Tweak markup. + + * display.texi (Defining Faces): Doc fix for `face-spec-set'. + + * elisp.texi (Top): + * commands.texi (Generic Commands, Defining Commands): + Document `define-alternatives'. + +2014-02-27 Xue Fuqiao <xfq@gnu.org> + + * windows.texi (Window Sizes): Document `window-size'. + (Display Action Functions): Document `display-buffer-at-bottom'. + (Window Configurations): Minor fixes. + + * modes.texi (Header Lines): Document `window-header-line-height'. + + * display.texi (Scroll Bars): Document `window-scroll-bar-width'. + + * windows.texi (Window Sizes, Resizing Windows): Document some + pixelwise window operations. + + * text.texi (Margins): Fix the description of RET and `C-j'. + + * frames.texi (Multiple Terminals): Document + `display-monitor-attributes-list' and `display-monitor-attributes'. + (Display Feature Testing): Add some notes about multi-monitor. + +2014-02-27 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Programmed Completion): + Mention completion-table-with-cache. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * display.texi (Window Systems): + Replace term-setup-hook with emacs-startup-hook. + * hooks.texi (Standard Hooks): + Replace term-setup-hook with tty-setup-hook. + * os.texi (Startup Summary, Init File, Terminal-Specific): + Replace term-setup-hook with tty-setup-hook, and update. + +2014-02-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Declare Form): Document gv-expander, gv-setter, + and compiler-macro (bug#16829, bug#15093). + +2014-02-21 Juanma Barranquero <lekktu@gmail.com> + + * windows.texi (Window Configurations): Doc fix. + (Windows and Frames): Fix typo. + +2014-02-21 Glenn Morris <rgm@gnu.org> + + * internals.texi (Process Internals): + * processes.texi (Subprocess Creation, Deleting Processes) + (Output from Processes, Process Buffers, Filter Functions) + (Accepting Output, Sentinels, Network, Network Servers): + Filters and sentinels can no longer be nil. + * elisp.texi (Top): Menu update. + +2014-02-20 Glenn Morris <rgm@gnu.org> + + * functions.texi (Defining Functions): Mention defalias-fset-function. + +2014-02-17 Stefan Monnier <monnier@iro.umontreal.ca> + + * minibuf.texi (Completion Commands): Don't document obsolete + `common-substring' arg of display-completion-list. + +2014-02-17 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Text from Minibuffer): Update read-regexp details. + Mention read-regexp-defaults-function. + +2014-02-13 Glenn Morris <rgm@gnu.org> + + * debugging.texi (Debugger Commands): Tiny edits. + +2014-02-12 Glenn Morris <rgm@gnu.org> + + * package.texi (Simple Packages): Describe URL and Keywords headers. + +2014-02-10 Lars Ingebrigtsen <larsi@gnus.org> + + * text.texi (User-Level Deletion): + Document `delete-trailing-whitespace' (bug#15309). + +2014-02-09 Lars Ingebrigtsen <larsi@gnus.org> + + * text.texi (Changing Properties): Clarify `propertize' (bug#9825). + + * display.texi (Blinking): Clarify doc string in example (bug#10658). + + * commands.texi (Accessing Mouse): Mention that these function + also work on keyboard events (bug#14228). + (Quitting): Refer to the right node for `set-input-mode' (bug#11458). + +2014-02-08 Lars Ingebrigtsen <larsi@gnus.org> + + * display.texi (Face Attributes): Add an index (bug#14924). + + * keymaps.texi (Menu Bar): Minor clarification (bug#15657). + +2014-02-06 Glenn Morris <rgm@gnu.org> + + * display.texi (Truncation): + * positions.texi (Screen Lines): Do not mention cache-long-scans. + +2014-01-31 Juri Linkov <juri@jurta.org> + + * searching.texi (String Search): Incremental word search fixes. + +2014-01-28 Glenn Morris <rgm@gnu.org> + + * text.texi (Indent Tabs): Update related to tab-stops. + +2014-01-24 Glenn Morris <rgm@gnu.org> + + * control.texi (Handling Errors): Update with-demoted-errors. + + * files.texi (File Locks): Every platform supports locking now. + +2014-01-22 Glenn Morris <rgm@gnu.org> + + * display.texi (ImageMagick Images): Expand on image-format-suffixes. + +2014-01-20 Glenn Morris <rgm@gnu.org> + + * hash.texi (Other Hash): Do not mention subr-x.el functions; + reverts 2013-12-22 change. + +2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): New section. + * modes.texi (Running Hooks): Don't document with-wrapper-hook and + run-hook-wrapped any more. + (Hooks): Link to the new Advising Functions node. + * elisp.texi (Top): Don't include advice.texi. + * advice.texi: Remove. + * makefile.w32-in (srcs): + * Makefile.in (srcs): Adjust accordingly. + +2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * text.texi (Parsing HTML/XML): Document `shr-insert-document'. + + * strings.texi (Text Comparison): Document `string-suffix-p'. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * files.texi (File Attributes): Fix superscipt typo. + +2014-01-07 Chong Yidong <cyd@gnu.org> + + * files.texi (Changing Files): Document copy-file changes. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * display.texi (Logging Messages): Copyedits re messages-buffer. + +2014-01-06 Paul Eggert <eggert@cs.ucla.edu> + + Specify .texi encoding (Bug#16292). + * back.texi, book-spine.texi, lay-flat.texi: + Add @documentencoding. + +2014-01-05 Chong Yidong <cyd@gnu.org> + + * backups.texi (Making Backups): Document backup-buffer change. + + * files.texi (Visiting Files): Copyedits. + (Testing Accessibility): Mention ACLs. Move file-modes here from + File Attributes. + (Truenames): Move file-equal-p here from Kinds of Files. + (File Attributes): Move file-newer-than-file-p here from Testing + Accessibility. + (Extended Attributes): New node. Add file-extended-attributes. + (Changing Files): Document set-file-extended-attributes. + + * commands.texi (Defining Commands): Document the interactive-form + property more carefully. Document interactive-only. + + * compile.texi (Compiler Errors): Copyedits. Note that the + details for byte-compile-warnings are in its docstring. + + * minibuf.texi (Minibuffer Contents): Remove obsolete function + minibuffer-completion-contents. + + * variables.texi (Defining Variables): Note that defvar acts + always on the dynamic value. + + * customize.texi (Variable Definitions): Likewise. + +2014-01-05 Paul Eggert <eggert@cs.ucla.edu> + + Document vconcat and the empty vector (Bug#16246). + * sequences.texi (Vector Functions): + Document behavior better when the result is empty. + + Document behavior of (string-to-number "+@") (Bug#16293). + * strings.texi (String Conversion): Document behavior of + string-to-number on invalid strings that begin with "+", too. + +2014-01-03 Chong Yidong <cyd@gnu.org> + + * help.texi (Documentation, Accessing Documentation): Copyedits. + (Documentation Basics): Rewrite, avoiding a repeat discussion of + docstring conventions. + + * tips.texi (Documentation Tips): Move discussion of + emacs-lisp-docstring-fill-column here from Documentation Basics. + + * compile.texi (Docs and Compilation): Copyedits. + +2014-01-02 Glenn Morris <rgm@gnu.org> + + * numbers.texi (Numeric Conversions): Fix a typo. + +2013-12-29 Paul Eggert <eggert@cs.ucla.edu> + + Plain copy-file no longer chmods an existing destination (Bug#16133). + * files.texi (Changing Files): Document this. + +2013-12-28 Chong Yidong <cyd@gnu.org> + + * modes.texi (Auto Major Mode): Document interpreter-mode-alist change. + + * buffers.texi (Modification Time): Document visited-file-modtime + change. + +2013-12-28 Glenn Morris <rgm@gnu.org> + + * control.texi (Pattern matching case statement): Brevity. + +2013-12-27 Chong Yidong <cyd@gnu.org> + + * functions.texi (Function Cells): + * eval.texi (Function Indirection): Update for the fact that + symbol-function no longer signals an error. + + * commands.texi (Reading One Event): Mention keyboard coding. + + * keymaps.texi (Translation Keymaps, Translation Keymaps): + * nonascii.texi (Terminal I/O Encoding): Copyedits. + +2013-12-26 Chong Yidong <cyd@gnu.org> + + * advice.texi (Advising Functions, Defining Advice): Special forms + can no longer be advised. + +2013-12-25 Chong Yidong <cyd@gnu.org> + + * keymaps.texi (Active Keymaps): Re-organize the text. + (Searching Keymaps): Rewrite the pseudo-code for 24.4 changes. + (Controlling Active Maps): Note that set-transient-map uses + overriding-terminal-local-map. + + * tips.texi (Coding Conventions): Tweak the coding system tip; + Emacs now uses utf-8 by default for Emacs Lisp source files. + + * display.texi (Font Selection): Tweak example. + + * commands.texi (Event Input Misc): Document new arg to input-pending-p. + + * nonascii.texi (Specifying Coding Systems): Don't refer to + emacs-mule-dos. + (Lisp and Coding Systems): Describe emacs-mule return value in + modern terms. + +2013-12-25 Tassilo Horn <tsdh@gnu.org> + + * control.texi (Pattern matching case statement): Rephrase lexical + binding requirement: the example needs it, not `pcase' itself. + +2013-12-25 Chong Yidong <cyd@gnu.org> + + * eval.texi (Eval): Document the LEXICAL arg to eval. + + * variables.texi (Variables, Void Variables): Use "scoping rule" + terminology consistently. + (Variable Scoping): Add index entries, and use "dynamic scope" + terminology in place of "indefinite scope" to reduce confusion. + (Lexical Binding): Document lexical environment format. + (Using Lexical Binding): Add index entries for error messages. + +2013-12-24 Tassilo Horn <tsdh@gnu.org> + + * control.texi (Pattern matching case statement): Fix missing + argument in simple expression language sample (Bug#16238). + Add some sample programs written in that language. Mention that + `pcase' requires lexical binding. + +2013-12-23 Xue Fuqiao <xfq.free@gmail.com> + + * eval.texi (Special Forms): Document `special-form-p'. + + * macros.texi (Simple Macro): Document `macrop'. + + * files.texi (Changing Files): Fix an argument of `copy-file'. + + * strings.texi (Creating Strings): Document TRIM in `split-string'. + +2013-12-23 Chong Yidong <cyd@gnu.org> + + * keymaps.texi (Controlling Active Maps): + Rename set-temporary-overlay-map to set-transient map. Doc fixes. + (Searching Keymaps): The transient keymap takes precedence. + +2013-12-23 Glenn Morris <rgm@gnu.org> + + * loading.texi (How Programs Do Loading, Load Suffixes): + Mention `load-prefer-newer'. + +2013-12-22 Xue Fuqiao <xfq.free@gmail.com> + + * hash.texi (Other Hash): Document `hash-table-keys' + and `hash-table-values'. + +2013-12-22 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Character Properties): NAME or OLD-NAME + properties can be nil (there's no empty string). + (Character Properties): Update the reference to the UCD. + +2013-12-22 Xue Fuqiao <xfq.free@gmail.com> + + * sequences.texi (Bool-Vectors): Document new bool-vector set + operation functions. + + * text.texi (Examining Properties): Document `get-pos-property'. + + * variables.texi (Directory Local Variables): + Document `enable-dir-local-variables'. + + * debugging.texi (Debugger Commands): + Document `debugger-toggle-locals'. + +2013-12-21 Chong Yidong <cyd@gnu.org> + + * text.texi (Region Indent): Note the new interactive behavior of + indent-rigidly. + +2013-12-20 Tassilo Horn <tsdh@gnu.org> + + * numbers.texi (numbers): Document that =, <, <=, >, >= now accept + one or many arguments. + + * display.texi: Document `messages-buffer'. + + * os.texi: Document `initial-buffer-choice' changes. + +2013-12-20 Chong Yidong <cyd@gnu.org> + + * text.texi (Changing Properties): Improve documentation for + add-face-text-property. + (Special Properties): Mention add-face-text-property. + +2013-12-18 Chong Yidong <cyd@gnu.org> + + * customize.texi (Custom Themes): Document custom-known-themes + (Bug#15717). + + * modes.texi (Defining Minor Modes): Fix typo (Bug#14874). + (Keymaps and Minor Modes): Fix binding convention (Bug#11522). + +2013-12-13 Glenn Morris <rgm@gnu.org> + + * internals.texi (Building Emacs): + * loading.texi (Library Search): Mention that site-load, + site-init cannot change load-path. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi: Tweak dircategory. + +2013-12-12 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Encoding and I/O): Document file-name encoding + peculiarities on MS-Windows. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi: Sync direntry with info/dir version. + +2013-12-08 Juanma Barranquero <lekktu@gmail.com> + + * display.texi (Progress, Face Remapping): + * processes.texi (Serial Ports): + * windows.texi (Recombining Windows): Fix typos. (Bug#16089) + +2013-12-04 Juri Linkov <juri@jurta.org> + + * searching.texi (Search and Replace): Fix `unread-command-events' + and add ref. + +2013-12-03 Juri Linkov <juri@jurta.org> + + * windows.texi (Choosing Window): Rename `no-display-ok' to + `allow-no-window'. (Bug#13594) + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-11-29 Andreas Politz <politza@fh-trier.de> + + * modes.texi (Imenu): Make it clear that sub-alist is the cdr + (Bug#14029). + +2013-11-27 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): + * os.texi (Startup Summary): No more leim directory. + +2013-11-26 Glenn Morris <rgm@gnu.org> + + * os.texi (Startup Summary): Update for leim-list being preloaded. + +2013-11-23 Brian Jenkins <brian@brianjenkins.org> (tiny change) + + * frames.texi (Input Focus): + * hooks.texi (Standard Hooks): Mention focus-in-hook, focus-out-hook. + +2013-11-23 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): + Empty elements in EMACSLOADPATH now mean the default load-path. + +2013-11-22 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): Minor clarification. + +2013-11-20 Leo Liu <sdl.web@gmail.com> + + * windows.texi (Choosing Window): Mention `no-display-ok'. (Bug#13594) + +2013-11-19 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (File Notifications): Add an index. + + * loading.texi (Loading): Add an cross-reference. + +2013-11-18 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Session Management, Desktop Notifications): Add some + indexes and a cross-reference. + +2013-11-17 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Time Parsing, Processor Run Time, Input Modes) + (Terminal Output): Minor fixes. + +2013-11-14 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): Update section. + +2013-11-11 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (User Identification, Time of Day, Time Conversion): + Minor fixes. + +2013-11-10 Jan Djärv <jan.h.d@swipnet.se> + + * keymaps.texi (Tool Bar): Mention that Gtk+/NS ignores item 1 to 3. + +2013-11-09 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Startup Summary): Add an index about startup screen. + Typo fix. + (Command-Line Arguments): Add cross-reference for `dump-emacs'. + +2013-11-08 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Truncation): Document that cache-long-scans is now + non-nil by default. (Bug#15797) + +2013-11-05 Eli Zaretskii <eliz@gnu.org> + + * lists.texi (Rearrangement): Fix indexing. + + * display.texi (Bidirectional Display): Fix indexing. + +2013-11-05 Xue Fuqiao <xfq.free@gmail.com> + + * lists.texi (Rearrangement): Improve indexing. + + * display.texi (Glyphs): Add an index for glyph code. + (Bidirectional Display): Improve indexing. + +2013-11-01 Jan Djärv <jan.h.d@swipnet.se> + + * display.texi (Face Attributes): Document :distant-foreground. + +2013-10-30 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Abstract Display): Improve indexing. + +2013-10-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * display.texi (Selective Display): Discourage the use of explicit + selective display. + +2013-10-29 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Showing Images): Add an index for image-size. + Use @code instead of @var for a normal variable. + (Multi-Frame Images): Improve indexing. + (Button Buffer Commands): Use @code instead of @var for a normal + variable. + (Abstract Display): Explain the meaning of Ewoc. + +2013-10-27 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Image Descriptors): Improve indexing. + +2013-10-26 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Fringe Indicators): Add indexes for fringe indicators. + (Customizing Bitmaps): Add an index for customizing fringe bitmaps. + +2013-10-25 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Fontsets): Minor wording fix. + (Low-Level Font): Improve indexing. + + * nonascii.texi (Character Properties): Add an index for script symbols. + +2013-10-24 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Face Remapping): Add indexes for face remapping. + (Font Selection): Add indexes. + (Low-Level Font): Add an index for font registry. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * eval.texi, files.texi, intro.texi, objects.texi, searching.texi: + Nuke @refill. + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-10-19 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Face Attributes): Add indexes for the ‘:box’ + face attribute. + +2013-10-18 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Line Height): Add indexes for line height. + +2013-10-17 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Width): Fix arguments of ‘truncate-string-to-width’. + +2013-10-16 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Selective Display): Add an index for explicit + selective display. + +2013-10-15 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Warning Basics): Mention the ‘*Warnings*’ buffer. + +2013-10-13 Glenn Morris <rgm@gnu.org> + + * intro.texi (Acknowledgments): Use accented form of some names. + +2013-10-09 Glenn Morris <rgm@gnu.org> + + * control.texi (Conditionals): Copyedits. (Bug#15558) + +2013-10-08 Eli Zaretskii <eliz@gnu.org> + + Support menus on text-mode terminals. + * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar): + Modify wording to the effect that menus are supported on TTYs. + + * frames.texi (Pop-Up Menus, Dialog Boxes) + (Display Feature Testing): Update for menu support on TTYs. + +2013-10-07 Stefan Monnier <monnier@iro.umontreal.ca> + + * tips.texi (Comment Tips): Discourage use of triple semi-colons for + non-headings. + +2013-10-05 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Categories): Add an index for category sets. + +2013-10-03 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Syntax Flags, Syntax Table Functions): Add indexes. + +2013-10-02 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Syntax Class Table): Add an index for syntax class table. + +2013-09-29 Xue Fuqiao <xfq.free@gmail.com> + + * searching.texi (Regexp Search): Refine. + +2013-09-22 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Default Coding Systems): Typo fix. + +2013-09-21 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Coding System Basics): Add information about + carriage-return. + +2013-09-14 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Display Margins): State the units of measuring + margin width. (Bug#15375) + +2013-09-13 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Not Intervals): Minor wording fix. + +2013-09-12 Xue Fuqiao <xfq.free@gmail.com> + + * functions.texi (Obsolete Functions): Add an index for obsolete + functions. + +2013-09-11 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Character Properties): Character properties fix + for decimal-digit-value and digit-value. + +2013-09-08 Stefan Monnier <monnier@iro.umontreal.ca> + + * macros.texi (Defining Macros): Prefer "function" to "lambda + expression" (bug#15296). + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + +2013-08-26 Stefan Monnier <monnier@iro.umontreal.ca> + + * variables.texi (File Local Variables): Don't recommend quoting! Ever! + 2013-08-20 Eli Zaretskii <eliz@gnu.org> * files.texi (Information about Files): Mention file names with @@ -29,8 +1660,8 @@ (Undo): Doc fix for `buffer-undo-list'. * positions.texi (Character Motion): - * markers.texi (Moving Markers): - (Creating Markers): Comment out undefined behavior. + * markers.texi (Moving Markers, Creating Markers): + Comment out undefined behavior. 2013-08-15 Xue Fuqiao <xfq.free@gmail.com> @@ -66,8 +1697,8 @@ (dvi, html, pdf, ps): Use *_TARGETS variables. (elisp.html): Use HTML_OPTS. (elisp.ps): Remove explicit rule. - (.PHONY): install-dvi, install-html, install-pdf, install-ps - ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + (.PHONY): install-dvi, install-html, install-pdf, install-ps, + install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (install-dvi, install-html, install-pdf, install-ps, install-doc) (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) @@ -112,7 +1743,8 @@ 2013-07-31 Xue Fuqiao <xfq.free@gmail.com> * nonascii.texi (Non-ASCII Characters): Update menu. - (Disabling Multibyte): Move here from doc/emacs/mule.texi. Fix cross-references. + (Disabling Multibyte): Move here from doc/emacs/mule.texi. + Fix cross-references. * elisp.texi (Top): Update menu. @@ -137,8 +1769,8 @@ 2013-07-22 Michael Albinus <michael.albinus@gmx.de> * files.texi (Magic File Names): Add file-notify-add-watch, - file-notify-rm-watch and file-notify-supported-p. Move - file-remote-p down. + file-notify-rm-watch and file-notify-supported-p. + Move file-remote-p down. * errors.texi (Standard Errors): Add file-notify-error. @@ -277,7 +1909,7 @@ 2013-04-21 Xue Fuqiao <xfq.free@gmail.com> * internals.texi (Writing Emacs Primitives): Remove unnecessary - references to the sources. (Bug#13800) + references to the sources. (Bug#13800) * searching.texi (Regexp Backslash): Doc fix for backslash constructs in regular expressions. @@ -510,7 +2142,7 @@ 2012-12-14 Paul Eggert <eggert@cs.ucla.edu> - Fix permissions bugs with setgid directories etc. (Bug#13125) + Fix permissions bugs with setgid directories etc. (Bug#13125) * files.texi (Testing Accessibility): Document GROUP arg of file-ownership-preserved-p. (File Attributes): Document that 9th element is now @@ -928,14 +2560,16 @@ Tweak markup. Remove domain-error and friends, which seem to be unused after the floating-point code revamp. - * functions.texi (Obsolete Functions): Obsolescence also affects + * functions.texi (Defining Functions): defun is now a macro. + (Obsolete Functions): Obsolescence also affects documentation commands. Various clarifications. (Declare Form): New node. * strings.texi (String Basics): Copyedits. - * os.texi (Idle Timers): Minor clarifications. + * os.texi (Startup Summary): Document leim-list.el change. (User Identification): Add system-users and system-groups. + (Idle Timers): Minor clarifications. * macros.texi (Defining Macros): Move description of `declare' to Declare Form node. @@ -951,14 +2585,6 @@ the machine-independence of negative division since it does not happen in practice. -2012-09-28 Chong Yidong <cyd@gnu.org> - - * os.texi (Startup Summary): Document leim-list.el change. - -2012-09-25 Chong Yidong <cyd@gnu.org> - - * functions.texi (Defining Functions): defun is now a macro. - 2012-09-28 Leo Liu <sdl.web@gmail.com> * files.texi (Files): Fix typo. @@ -1151,7 +2777,7 @@ 2012-07-06 Richard Stallman <rms@gnu.org> - * intro.texi (Evaluation Notation, A Sample Function Description): + * intro.texi (Evaluation Notation, A Sample Function Description) (A Sample Variable Description): Improve/undo previous changes. 2012-07-05 Glenn Morris <rgm@gnu.org> @@ -1466,7 +3092,7 @@ (Resizing Windows, Deleting Windows, Selecting Windows) (Choosing Window Options, Horizontal Scrolling) (Cyclic Window Ordering, Window History, Dedicated Windows) - (Quitting Windows, Window Configurations, Textual Scrolling): + (Quitting Windows, Window Configurations, Textual Scrolling) (Coordinates and Windows, Window Configurations) (Window Parameters, Window Hooks): Copyedits. (Splitting Windows, Deleting Windows): @@ -1544,7 +3170,7 @@ * processes.texi (Output from Processes, Filter Functions): Mention waiting-for-user-input-p. - (Sentinels, Query Before Exit, System Processes, Transaction Queues): + (Sentinels, Query Before Exit, System Processes, Transaction Queues) (Network Servers, Datagrams, Network Processes, Network Options) (Network Feature Testing, Serial Ports): Copyedits. (Network): Add encrypted network overview paragraph. @@ -1566,7 +3192,7 @@ 2012-04-15 Glenn Morris <rgm@gnu.org> - * processes.texi (Processes, Subprocess Creation, Shell Arguments): + * processes.texi (Processes, Subprocess Creation, Shell Arguments) (Synchronous Processes, Asynchronous Processes, Deleting Processes): Copyedits. (Subprocess Creation): Discourage modifying exec-path directly. @@ -1586,8 +3212,7 @@ 2012-04-14 Chong Yidong <cyd@gnu.org> - * customize.texi (Applying Customizations): - (Custom Themes): New nodes. + * customize.texi (Applying Customizations, Custom Themes): New nodes. * display.texi (Defining Faces): Reference custom-set-faces. @@ -1716,8 +3341,8 @@ 2012-03-28 Glenn Morris <rgm@gnu.org> - * searching.texi (Regular Expressions, Regexp Special): - (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search): + * searching.texi (Regular Expressions, Regexp Special) + (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search) (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits. (Regexp Special): Mention collation. Clarify char classes with an example. @@ -1948,7 +3573,7 @@ (Pure Storage): Small changes. (Memory Usage): Copyedit. (Writing Emacs Primitives): Update Fcoordinates_in_window_p and For - example definitions. Give examples of things with non-nil + example definitions. Give examples of things with non-nil interactive args. Mention eval_sub. Remove old info about strings and GCPRO. Mention cus-start.el. (Buffer Internals, Window Internals, Process Internals): @@ -2124,7 +3749,7 @@ (Syntax Class Table): Use a table. (Syntax Properties): Document syntax-propertize-function and syntax-propertize-extend-region-functions. - (Motion via Parsing): Clarify scan-lists. Fix indentation. + (Motion via Parsing): Clarify scan-lists. Fix indentation. (Parser State): Update for the new "c" comment style. Fix description of item 7 (comment style). @@ -2991,7 +4616,7 @@ 2011-07-16 Lars Magne Ingebrigtsen <larsi@gnus.org> Tim Cross <theophilusx@gmail.com> (tiny change) - Glenn Morris <rgm@gnu.org> + Glenn Morris <rgm@gnu.org> * keymaps.texi (Toolkit Differences): New node. (Bug#8176) @@ -3163,7 +4788,7 @@ Document wide integers better. * files.texi (File Attributes): Document ino_t values better. ino_t values no longer map to anything larger than a single cons. - * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): + * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations) (Bitwise Operations): * objects.texi (Integer Type): Use a binary notation that is a bit easier to read, and that will port better if 62-bits becomes the default. @@ -3446,7 +5071,7 @@ (texinputdir, $(infodir)/elisp): Use $(MAKEINFO_OPTS). 2011-01-25 Chong Yidong <cyd@stupidchicken.com> - Richard Kim <emacs18@gmail.com> + Richard Kim <emacs18@gmail.com> * loading.texi (Library Search): Document list-load-path-shadows (Bug#7757). @@ -6611,8 +8236,7 @@ * 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): + (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) @@ -8887,7 +10511,7 @@ * variables.texi (Variable Aliases): Simplify. - * anti.texi, backups.texi, compile.texi, customization.texi: + * anti.texi, backups.texi, compile.texi, customize.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: @@ -11251,15 +12875,12 @@ 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}. + * anti.texi, backups.texi, commands.texi, customize.texi: + * display.texi, files.texi, internals.texi, keymaps.texi: + * loading.texi, modes.texi, nonascii.texi, numbers.texi: + * objects.texi, os.texi, positions.texi, processes.texi: + * searching.texi, sequences.texi, streams.texi, strings.texi: + * syntax.texi, text.texi: Replace @sc{foo} with @acronym{FOO}. 2003-10-27 Luc Teirlinck <teirllm@auburn.edu> @@ -12210,7 +13831,7 @@ 1998-01-30 Richard Stallman <rms@psilocin.gnu.org> - * Makefile (SHELL): Defined. + * Makefile (SHELL): Define. 1998-01-27 Richard Stallman <rms@psilocin.gnu.org> @@ -12368,7 +13989,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1998-2013 Free Software Foundation, Inc. + Copyright (C) 1998-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 675cac7949d..6ac2840cb9a 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1990-1996, 1998-2013 Free Software Foundation, Inc. +# Copyright (C) 1990-1996, 1998-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,7 +17,7 @@ # You should have received a copy of the GNU General Public License # along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. -SHELL = /bin/sh +SHELL = @SHELL@ # NB If you add any more configure variables, # update the sed rules in the dist target below. @@ -25,12 +25,10 @@ SHELL = /bin/sh # Standard configure variables. srcdir = @srcdir@ -version=@version@ - buildinfodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. +# Directory with docstyle.tex and emacsver.texi. emacsdir = $(srcdir)/../emacs prefix = @prefix@ @@ -49,9 +47,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -62,8 +59,17 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = elisp.dvi HTML_TARGETS = elisp.html @@ -74,9 +80,9 @@ PS_TARGETS = elisp.ps srcs = \ $(srcdir)/elisp.texi \ + $(emacsdir)/docstyle.texi \ $(emacsdir)/emacsver.texi \ $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ $(srcdir)/anti.texi \ $(srcdir)/backups.texi \ $(srcdir)/buffers.texi \ @@ -127,36 +133,36 @@ srcs = \ $(srcdir)/gpl.texi \ $(srcdir)/doclicense.texi -mkinfodir = @${MKDIR_P} ${buildinfodir} - -.PHONY: info dvi pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< +.PHONY: info dvi html pdf ps -info: $(buildinfodir)/elisp$(INFO_EXT) +info: $(buildinfodir)/elisp.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) -## Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/elisp$(INFO_EXT): $(srcs) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi +${buildinfodir}: + ${MKDIR_P} $@ + +$(buildinfodir)/elisp.info: $(srcs) | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< elisp.dvi: $(srcs) - $(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2DVI) $< elisp.html: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $(srcdir)/elisp.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< elisp.pdf: $(srcs) - $(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2PDF) $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +elisp.ps: elisp.dvi + $(DVIPS) -o $@ $< + +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## [12] stuff is from two-volume.make. mostlyclean: @@ -167,56 +173,36 @@ mostlyclean: clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) rm -f vol[12].dvi vol[12].pdf vol[12].ps - rm -f emacs-lispref-${version}.tar* distclean: clean + rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f elisp$(INFO_EXT) elisp$(INFO_EXT)-[1-9] elisp$(INFO_EXT)-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Note this excludes the two-volume stuff. -dist: - rm -rf emacs-lispref-${version} - mkdir emacs-lispref-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - $(emacsdir)/emacsver.texi ${srcdir}/ChangeLog* \ - ${srcdir}/README emacs-lispref-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispref-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispref-${version}.tar emacs-lispref-${version} - rm -rf emacs-lispref-${version} + rm -f \ + $(buildinfodir)/elisp.info \ + $(buildinfodir)/elisp.info-[1-9] \ + $(buildinfodir)/elisp.info-[1-9][0-9] + +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -227,20 +213,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/lispref/README b/doc/lispref/README index b94bd10789c..fd943ce97c2 100644 --- a/doc/lispref/README +++ b/doc/lispref/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. -*- outline -*- +Copyright (C) 2001-2015 Free Software Foundation, Inc. -*- outline -*- See the end of the file for license conditions. @@ -21,15 +21,15 @@ Buying a manual from the Free Software Foundation helps support our GNU development work. See <http://shop.fsf.org/>. (At time of writing, this manual is out of print.) -* The master file for formatting this manual for Tex is called `elisp.texi'. +* 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. * This distribution contains a Makefile that you can use with GNU Make. -** To make an Info file, you need to install Texinfo, then run `make info'. +** To make an Info file, you need to install Texinfo, then run 'make info'. -** Use `make elisp.pdf' or `make elisp.html' to create PDF or HTML versions. +** Use 'make elisp.pdf' or 'make elisp.html' to create PDF or HTML versions. This file is part of GNU Emacs. diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 7cc558f9391..bcbea87c04d 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1994, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Abbrevs @@ -59,6 +59,7 @@ expanded in the buffer. For the user-level commands for abbrevs, see @node Abbrev Tables @section Abbrev Tables +@cindex abbrev tables This section describes how to create and manipulate abbrev tables. @@ -126,13 +127,14 @@ to add these to @var{name} separately.) @node Defining Abbrevs @section Defining Abbrevs +@cindex defining abbrevs @code{define-abbrev} is the low-level basic function for defining an abbrev in an abbrev table. When a major mode defines a system abbrev, it should call @code{define-abbrev} and specify @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored +property. Be aware that any saved non-system abbrevs are restored at startup, i.e., before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded. @@ -143,13 +145,13 @@ This function defines an abbrev named @var{name}, in with properties @var{props} (@pxref{Abbrev Properties}). The return value is @var{name}. The @code{:system} property in @var{props} is treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of +overwrite an existing definition even for a non-system abbrev of the same name. @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}. +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 @@ -181,6 +183,7 @@ callers. @node Abbrev Files @section Saving Abbrevs in Files +@cindex save 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 @@ -232,6 +235,9 @@ define the same abbrevs. If @var{filename} is @code{nil} or omitted, @node Abbrev Expansion @section Looking Up and Expanding Abbreviations +@cindex looking up abbrevs +@cindex expanding abbrevs +@cindex abbrevs, looking up and expanding Abbrevs are usually expanded by certain interactive commands, including @code{self-insert-command}. This section describes the @@ -257,13 +263,16 @@ as in @code{abbrev-symbol}. @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 that 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. +follow an abbrev, this command does nothing. To do the expansion, it +calls the function that is the value of the @code{abbrev-expand-function} +variable, with no arguments, and returns whatever that function does. + +The default expansion function returns the abbrev symbol if it did +expansion, and @code{nil} otherwise. If the abbrev symbol has a hook +function that 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 the default expansion function returns @code{nil}, +even though expansion did occur. @end deffn @defun abbrev-insert abbrev &optional name start end @@ -331,24 +340,21 @@ has already been unexpanded. This contains information left by @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. @end defvar -@defvar abbrev-expand-functions -This is a wrapper hook (@pxref{Running Hooks}) run around the -@code{expand-abbrev} function. Each function on this hook is called -with a single argument: a function that performs the normal abbrev -expansion. The hook function can hence do anything it wants before -and after performing the expansion. It can also choose not to call -its argument, thus overriding the default behavior; or it may even -call it several times. The function should return the abbrev symbol -if expansion took place. +@defvar abbrev-expand-function +The value of this variable is a function that @code{expand-abbrev} +will call with no arguments to do the expansion. The function can do +anything it wants before and after performing the expansion. +It should return the abbrev symbol if expansion took place. @end defvar The following sample code shows a simple use of -@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a +@code{abbrev-expand-function}. 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. @xref{Standard Abbrev Tables}, for the definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. +@xref{Advising Functions}, for details of @code{add-function}. @smallexample (defun foo-mode-abbrev-expand-function (expand) @@ -361,13 +367,13 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. (add-hook 'foo-mode-hook #'(lambda () - (add-hook 'abbrev-expand-functions - 'foo-mode-abbrev-expand-function - nil t))) + (add-function :around (local 'abbrev-expand-function) + #'foo-mode-abbrev-expand-function))) @end smallexample @node Standard Abbrev Tables @section Standard Abbrev Tables +@cindex standard abbrev tables Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs. @@ -410,6 +416,7 @@ Properties}. @node Abbrev Properties @section Abbrev Properties +@cindex abbrev properties Abbrevs have properties, some of which influence the way they work. You can provide them as arguments to @code{define-abbrev}, and @@ -450,6 +457,7 @@ modifies the capitalization of the expansion. @node Abbrev Table Properties @section Abbrev Table Properties +@cindex abbrev table properties Like abbrevs, abbrev tables have properties, some of which influence the way they work. You can provide them as arguments to diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi deleted file mode 100644 index e8d1bd3cdbc..00000000000 --- a/doc/lispref/advice.texi +++ /dev/null @@ -1,748 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2013 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Advising Functions -@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}, each of -which can be separately defined and then @dfn{enabled} or -@dfn{disabled}. 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. - - Advice is useful for altering the behavior of existing calls to an -existing function. If you want the new behavior for new function -calls or new key bindings, you should define a new function or -command, and have it use the existing function as a subroutine. - - 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 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, Emacs's own source -files should not put advice on functions in Emacs. There are -currently a few exceptions to this convention, but we aim to correct -them. - - Unless you know what you are doing, do @emph{not} advise a primitive -(@pxref{What Is a Function}). Some primitives are used by the advice -mechanism; advising them could cause an infinite recursion. Also, -many primitives 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. - -@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. -* 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 all pieces of 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 - -@noindent -Here, @var{protected} and @var{enabled} are flags; if @var{protected} -is non-@code{nil}, the advice is protected against non-local exits -(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the -advice is initially disabled (@pxref{Enabling Advice}). -@var{definition} should have the form - -@example -(advice . @var{lambda}) -@end example - -@noindent -where @var{lambda} is a lambda expression; this lambda expression is -called in order to perform the advice. @xref{Lambda Expressions}. - -If the @var{function} argument to @code{ad-add-advice} 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. 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}; or you can activate the advice separately 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 their -(zero-based) 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 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. diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index 577411ba9df..2fc43da8e53 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2013 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This node must have no pointers. @@ -30,7 +30,7 @@ minimum of fuss. But @xref{Dynamic Binding Tips}, for tips to avoid making your programs hard to understand. @item -Calling a minor mode function from Lisp with a nil or omitted argument +Calling a minor mode function from Lisp with a @code{nil} or omitted argument does not enable the minor mode unconditionally; instead, it toggles the minor mode---which is the straightforward thing to do, since that is the behavior when invoked interactively. One downside is that it @@ -56,8 +56,8 @@ there is no need to worry about the insertion of right-to-left text messing up how lines and paragraphs are displayed, the function @code{bidi-string-mark-left-to-right} has been removed; so have many other functions and variables related to bidirectional display. -Unicode directionality characters like @code{U+200E} ("left-to-right -mark") have no special effect on display. +Unicode directionality characters like @code{U+200E} LEFT-TO-RIGHT +MARK have no special effect on display. @item Emacs windows now have most of their internal state hidden from Lisp. @@ -66,7 +66,7 @@ Internal windows are no longer visible to Lisp; functions such as and window-local buffer lists have all been removed. Functions for resizing windows can delete windows if they become too small. -The ``action function'' feature for controlling buffer display has +The action-function feature for controlling buffer display has been removed, including @code{display-buffer-overriding-action} and related variables, as well as the @var{action} argument to @code{display-buffer} and other functions. The way to @@ -78,7 +78,7 @@ other variables. The standard completion interface has been simplified, eliminating the @code{completion-extra-properties} variable, the @code{metadata} action flag for completion functions, and the concept of -``completion categories''. Lisp programmers may now find the choice +completion categories. Lisp programmers may now find the choice of methods for tuning completion less bewildering, but if a package finds the streamlined interface insufficient for its needs, it must implement its own specialized completion feature. diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi index ef20f8b79e0..c4f2b5eb852 100644 --- a/doc/lispref/back.texi +++ b/doc/lispref/back.texi @@ -1,11 +1,12 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 2001-2015 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 +@include docstyle.texi @c %**end of header . @sp 7 @@ -16,7 +17,7 @@ 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 +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. diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index f2599c773ea..d37df25d267 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1995, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Backups and Auto-Saving @@ -50,6 +50,7 @@ don't want them any more, or Emacs can delete them automatically. @node Making Backups @subsection Making Backup Files +@cindex making backup files @defun backup-buffer This function makes a backup of the file visited by the current @@ -57,13 +58,15 @@ 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{context} @var{backupname}), where +the form (@var{modes} @var{extra-alist} @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}), @var{context} is a list describing the original file's -SELinux context (@pxref{File Attributes}), 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}. +@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist} +is an alist describing the original file's extended attributes, as +returned by @code{file-extended-attributes} (@pxref{Extended +Attributes}), and @var{backupname} is the name of the backup. + +In all other cases (i.e., if a backup was made by copying or if no +backup was made), this function returns @code{nil}. @end defun @defvar buffer-backed-up @@ -88,8 +91,7 @@ save disk space. (You would put this code in your init file.) @smallexample @group (add-hook 'rmail-mode-hook - (lambda () - (set (make-local-variable 'make-backup-files) nil))) + (lambda () (setq-local make-backup-files nil))) @end group @end smallexample @end defopt @@ -148,13 +150,12 @@ ignored. @end defopt @defopt 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. +This variable's value is a function to use for making backup file names. +The function @code{make-backup-file-name} calls it. @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 +files. If you change it, you may need to change @code{backup-file-name-p} and @code{file-name-sans-versions} too. @end defopt @@ -238,6 +239,7 @@ The default is 200. @node Numbered Backups @subsection Making and Deleting Numbered Backup Files +@cindex numbered backups 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 @@ -299,6 +301,7 @@ file. The default is@tie{}2. @node Backup Names @subsection Naming Backup Files +@cindex naming backup files The functions in this section are documented mainly because you can customize the naming conventions for backup files by redefining them. @@ -395,7 +398,7 @@ 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'' +to use for the new backup file, and @file{~rms/foo.~3~} is an excess version that the caller should consider deleting now. @smallexample @@ -668,6 +671,7 @@ not initialize @code{auto-save-list-file-name}. @node Reverting @section Reverting +@cindex reverting buffers 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 @@ -725,25 +729,24 @@ 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 +buffer. 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. +@code{revert-buffer} received. 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. +fashion, can give this variable a buffer-local value that is a special +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 +The value of this variable 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 +The reason for a mode to change 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 @@ -751,21 +754,23 @@ 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}. +This normal hook is run by the default @code{revert-buffer-function} +before inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @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}. +This normal hook is run by the default @code{revert-buffer-function} +after inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @c FIXME? Move this section from arevert-xtra to here? @defvar buffer-stale-function -The value of this variable, if non-@code{nil}, specifies a function -to call to check whether a non-file buffer needs reverting +The value of this variable specifies a function to call to check +whether a buffer needs reverting. The default value only handles +buffers that are visiting files, by checking their modification time. +Buffers that are not visiting files require a custom function @iftex (@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). @end iftex diff --git a/doc/lispref/book-spine.texi b/doc/lispref/book-spine.texi index 721416316d2..8c6381f3d81 100644 --- a/doc/lispref/book-spine.texi +++ b/doc/lispref/book-spine.texi @@ -2,6 +2,7 @@ @c %**start of header @setfilename book-spine @settitle book-spine +@include docstyle.texi @c %**end of header @include emacsver.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 01269851250..45a21c8e806 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Buffers @@ -23,9 +23,9 @@ not be displayed in any windows. * 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". + 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. +* 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. @@ -632,13 +632,12 @@ 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} -@var{microsec} @var{picosec})}. -(This is the same format that @code{file-attributes} uses to return -time values; see @ref{File Attributes}.) +@var{microsec} @var{picosec})}. (This is the same format that +@code{file-attributes} uses to return time values; @pxref{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 @@ -648,17 +647,9 @@ visiting a file or if the time has been explicitly cleared by 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 @minus{} 1.} -@end ifnottex -@tex -@math{2^{16}-1}. -@end tex +If the buffer is not visiting a file, this function returns -1. @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} @@ -768,9 +759,10 @@ 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 +@node Buffer List @section The Buffer List @cindex buffer list +@cindex listing all buffers The @dfn{buffer list} is a list of all live buffers. The order of the buffers in this list is based primarily on how recently each buffer has @@ -852,7 +844,7 @@ names start with a space are not considered at all. If @var{buffer} is not supplied (or if it is not a live buffer), then @code{other-buffer} returns the first buffer in the selected frame's -local buffer list. (If @var{frame} is non-@code{nil}, it returns the +local buffer list. (If @var{frame} is non-@code{nil}, it returns the first buffer in @var{frame}'s local buffer list instead.) If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, @@ -872,7 +864,7 @@ If no suitable buffer exists, the buffer @file{*scratch*} is returned @defun last-buffer &optional buffer visible-ok frame This function returns the last buffer in @var{frame}'s buffer list other -than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the +than @var{buffer}. If @var{frame} is omitted or @code{nil}, it uses the selected frame's buffer list. The argument @var{visible-ok} is handled as with @code{other-buffer}, @@ -901,7 +893,7 @@ another buffer is shown in it. More precisely, if the selected window is dedicated (@pxref{Dedicated Windows}) and there are other windows on its frame, the window is deleted. If it is the only window on its frame and that frame is not the only frame on its terminal, the frame is -``dismissed'' by calling the function specified by +dismissed by calling the function specified by @code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show another buffer in that window. If @var{buffer-or-name} is displayed in @@ -919,6 +911,13 @@ buffer returned by @code{last-buffer} (see above), in the selected window. @end deffn +@defvar buffer-list-update-hook +This is a normal hook run whenever the buffer list changes. Functions +(implicitly) running this hook are @code{get-buffer-create} +(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}), +@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see +above) and @code{select-window} (@pxref{Selecting Windows}). +@end defvar @node Creating Buffers @section Creating Buffers @@ -1033,7 +1032,7 @@ memory for other uses or to be returned to the operating system. If buffer. Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} (``hangup'') signal, which normally causes them +sent the @code{SIGHUP} (hangup) signal, which normally causes them to terminate. @xref{Signals to Processes}. If the buffer is visiting a file and contains unsaved changes, @@ -1140,7 +1139,7 @@ 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 +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. @@ -1217,6 +1216,7 @@ in the text it is swapped with will not interfere with auto-saving. @node Buffer Gap @section The Buffer Gap +@cindex buffer gap Emacs buffers are implemented using an invisible @dfn{gap} to make insertion and deletion faster. Insertion works by filling in part of diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 846d6f3a4a9..7ddf5ee8f74 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Command Loop @@ -108,24 +108,46 @@ command does. The special form @code{interactive} turns a Lisp function into a command. The @code{interactive} form must be located at top-level in -the function body (usually as the first form in the body), or in the -@code{interactive-form} property of the function symbol. When the -@code{interactive} form is located in the function body, it does -nothing when actually executed. Its presence serves as a flag, which -tells the Emacs command loop that the function can be called -interactively. The argument of the @code{interactive} form controls -the reading of arguments for an interactive call. +the function body, usually as the first form in the body; this applies +to both lambda expressions (@pxref{Lambda Expressions}) and +@code{defun} forms (@pxref{Defining Functions}). This form does +nothing during the actual execution of the function; its presence +serves as a flag, telling the Emacs command loop that the function can +be called interactively. The argument of the @code{interactive} form +specifies how the arguments for an interactive call should be read. + +@cindex @code{interactive-form} property + Alternatively, an @code{interactive} form may be specified in a +function symbol's @code{interactive-form} property. A non-@code{nil} +value for this property takes precedence over any @code{interactive} +form in the function body itself. This feature is seldom used. + +@anchor{The interactive-only property} +@cindex @code{interactive-only} property + Sometimes, a function is only intended to be called interactively, +never directly from Lisp. In that case, give the function a +non-@code{nil} @code{interactive-only} property, either directly +or via @code{declare} (@pxref{Declare Form}). This causes the +byte compiler to warn if the command is called from Lisp. The output +of @code{describe-function} will include similar information. +The value of the property can be: a string, which the byte-compiler +will use directly in its warning (it should end with a period, and not +start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any +other symbol, which should be an alternative function to use in Lisp +code. @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. +* Generic Commands:: Select among command alternatives. @end menu @node Using Interactive @subsection Using @code{interactive} @cindex arguments, interactive entry +@cindex interactive spec, using This section describes how to write the @code{interactive} form that makes a Lisp function an interactively-callable command, and how to @@ -189,7 +211,7 @@ argument. 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 +@code{format-message} (@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: @@ -562,6 +584,34 @@ Put them into three windows, selecting the last one." @end group @end example +@node Generic Commands +@subsection Select among Command Alternatives +@cindex generic commands +@cindex alternatives, defining + +The macro @code{define-alternatives} can be used to define +@dfn{generic commands}. These are interactive functions whose +implementation can be selected from several alternatives, as a matter +of user preference. + +@defmac define-alternatives command &rest customizations +Define the new command @var{command}, a symbol. + +When a user runs @kbd{M-x @var{command} @key{RET}} for the first time, +Emacs prompts for which real form of the command to use, and records +the selection by way of a custom variable. Using a prefix argument +repeats this process of choosing an alternative. + +The variable @code{@var{command}-alternatives} should contain an alist +with alternative implementations of @var{command}. +Until this variable is set, @code{define-alternatives} has no effect. + +If @var{customizations} is non-@code{nil}, it should consist of +alternating @code{defcustom} keywords (typically @code{:group} and +@code{:version}) and values to add to the declaration of +@code{@var{command}-alternatives}. +@end defmac + @node Interactive Call @section Interactive Call @cindex interactive call @@ -698,6 +748,8 @@ part of the prompt. @node Distinguish Interactive @section Distinguish Interactive Calls +@cindex distinguish interactive calls +@cindex is this call interactive Sometimes a command should display additional visual feedback (such as an informative message in the echo area) for interactive calls @@ -786,6 +838,7 @@ Here is another example that contrasts direct and indirect calls to @node Command Loop Info @section Information from the Command Loop +@cindex command loop variables The editor command loop sets several Lisp variables to keep status records for itself and for commands that are run. With the exception of @@ -990,8 +1043,8 @@ the current Emacs session. If a symbol has not yet been so used, @end defun @menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. +* 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. @@ -1342,8 +1395,9 @@ The position in the string where the click occurred. @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. +the window. For clicks on the mode line or the header line, this is +@code{nil}. For other events, it is the buffer position closest to +the click. @item @var{col}, @var{row} These are the actual column and row coordinate numbers of the glyph @@ -1408,7 +1462,7 @@ the symbols @code{handle} (the scroll bar handle), @code{above-handle} (the area above the handle), @code{below-handle} (the area below the handle), @code{up} (the up arrow at one end of the scroll bar), or @code{down} (the down arrow at one end of the scroll bar). -@c The `top', `bottom', and `end-scroll' codes don't seem to be used. +@c The 'top', 'bottom', and 'end-scroll' codes don't seem to be used. @end table @@ -1435,8 +1489,10 @@ 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, as mouse position lists (@pxref{Click Events}). You can access -the second element of any mouse event in the same way, with no need to -distinguish drag events from others. +the second element of any mouse event in the same way. However, the +drag event may end outside the boundaries of the frame that was +initially selected. In that case, the third element's position list +contains that frame in place of a window. The @samp{drag-} prefix follows the modifier key prefixes such as @samp{C-} and @samp{M-}. @@ -1501,8 +1557,8 @@ 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 +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 @@ -1581,7 +1637,10 @@ represented by lists that look like this: @noindent @var{position} is a mouse position list (@pxref{Click Events}), -specifying the current position of the mouse cursor. +specifying the current position of the mouse cursor. As with the +end-position of a drag event, this position list may represent a +location outside the boundaries of the initially selected frame, in +which case the list contains that frame in place of a window. The special form @code{track-mouse} enables generation of motion events within its body. Outside of @code{track-mouse} forms, Emacs @@ -1661,7 +1720,7 @@ occurred. @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some +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 @@ -1796,6 +1855,14 @@ into another window. That produces a pair of events like these: -453816)) @end smallexample +The frame with input focus might not take up the entire screen, and +the user might move the mouse outside the scope of the frame. Inside +the @code{track-mouse} special form, that produces an event like this: + +@smallexample +(mouse-movement (#<frame *ielm* 0x102849a30> nil (563 . 205) 532301936)) +@end smallexample + To handle a SIGUSR1 signal, define an interactive function, and bind it to the @code{signal usr1} event sequence: @@ -1809,6 +1876,7 @@ bind it to the @code{signal usr1} event sequence: @node Classifying Events @subsection Classifying Events @cindex event type +@cindex classifying events Every event has an @dfn{event type}, which classifies the event for key binding purposes. For a keyboard event, the event type equals the @@ -1921,9 +1989,12 @@ must be the last element of the list. For example, @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in +@cindex keyboard events, data in This section describes convenient functions for accessing the data in -a mouse button or motion event. +a mouse button or motion event. Keyboard event data can be accessed +using the same functions, but data elements that aren't applicable to +keyboard events are zero or @code{nil}. The following two functions return a mouse position list (@pxref{Click Events}), specifying the position of a mouse event. @@ -1956,7 +2027,9 @@ Events}); and @code{nil} otherwise. various parts of it: @defun posn-window position -Return the window that @var{position} is in. +Return the window that @var{position} is in. If @var{position} +represents a location outside the frame where the event was initiated, +return that frame instead. @end defun @defun posn-area position @@ -1995,23 +2068,30 @@ POSITION is assumed to lie in a window text area." @defun posn-col-row position This function returns a cons cell @code{(@var{col} . @var{row})}, containing the estimated column and row corresponding to buffer -position @var{position}. The return value is given in units of the -frame's default character width and height, as computed from the -@var{x} and @var{y} values corresponding to @var{position}. (So, if -the actual characters have non-default sizes, the actual row and -column may differ from these computed values.) +position in @var{position}. The return value is given in units of the +frame's default character width and default line height (including +spacing), as computed from the @var{x} and @var{y} values +corresponding to @var{position}. (So, if the actual characters have +non-default sizes, the actual row and column may differ from these +computed values.) Note that @var{row} is counted from the top of the text area. If the -window possesses a header line (@pxref{Header Lines}), it is -@emph{not} counted as the first line. +window given by @var{position} possesses a header line (@pxref{Header +Lines}), it is @emph{not} included in the @var{row} count. @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 and -column numbers in the window. @xref{Click Events}, for details. It -returns @code{nil} if @var{position} does not include actual positions -values. +column numbers in the window given by @var{position}. @xref{Click +Events}, for details. The function returns @code{nil} if +@var{position} does not include actual position values; in that case +@code{posn-col-row} can be used to get approximate values. + +Note that this function doesn't account for the visual width of +characters on display, like the number of visual columns taken by a +tab character or an image. If you need the coordinates in canonical +character units, use @code{posn-col-row} instead. @end defun @defun posn-string position @@ -2033,8 +2113,9 @@ Return the image or string object in @var{position}, either @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. +. @var{dy})}. If the @var{position} is on buffer text, return the +relative position of the buffer-text character closest to that +position. @end defun @defun posn-object-width-height position @@ -2363,7 +2444,7 @@ 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}, +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 @@ -2395,9 +2476,12 @@ and key sequences read from keyboard macros being executed. @code{read-char}, and @code{read-char-exclusive}. @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. +This function reads and returns the next event of command input, +waiting if necessary until an event is available. + +The returned event may come directly from the user, or from a keyboard +macro. It is not decoded by the keyboard's input coding system +(@pxref{Terminal I/O Encoding}). 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, @@ -2418,7 +2502,7 @@ 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 +@code{nil}. A floating point @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 @@ -2503,7 +2587,7 @@ If you wish to read a single key taking these translations into account, use the function @code{read-key}: @defun read-key &optional prompt -This function reads a single key. It is ``intermediate'' between +This function reads a single key. It is intermediate between @code{read-key-sequence} and @code{read-event}. Unlike the former, it reads a single key, not a key sequence. Unlike the latter, it does not return a raw event, but decodes and translates the user input @@ -2527,6 +2611,9 @@ then continues to wait for a valid input character, or keyboard-quit. @node Event Mod @subsection Modifying and Translating Input Events +@cindex modifiers of events +@cindex translating input events +@cindex event translation Emacs modifies every event it reads according to @code{extra-keyboard-modifiers}, then translates it through @@ -2546,7 +2633,7 @@ 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 +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. @@ -2608,6 +2695,7 @@ at the level of @code{read-key-sequence}. @node Invoking the Input Method @subsection Invoking the Input Method +@cindex invoking input method The event-reading functions invoke the current input method, if any (@pxref{Input Methods}). If the value of @code{input-method-function} @@ -2695,7 +2783,7 @@ What character @kbd{1 7 7}- @node Event Input Misc @subsection Miscellaneous Event Input Features -This section describes how to ``peek ahead'' at events without using +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}). @@ -2730,7 +2818,7 @@ 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})} +the first time. An element of the form @w{@code{(t . @var{event})}} forces @var{event} to be added to the current command's key sequence. @end defvar @@ -2739,12 +2827,16 @@ 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 -@defun input-pending-p +@defun input-pending-p &optional check-timers @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. + +If the optional argument @var{check-timers} is non-@code{nil}, then if +no input is available, Emacs runs any timers which are ready. +@xref{Timers}. @end defun @defvar last-input-event @@ -2858,8 +2950,8 @@ 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. +The argument @var{seconds} need not be an integer. If it is floating +point, @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. @@ -2885,8 +2977,8 @@ 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. +The argument @var{seconds} need not be an integer. If it is floating +point, @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. @@ -2956,7 +3048,7 @@ usual result of this---a quit---is prevented. Eventually, 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. +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 @@ -3024,7 +3116,7 @@ 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}. +See the function @code{set-input-mode} in @ref{Input Modes}. @node Prefix Command Arguments @section Prefix Command Arguments @@ -3219,7 +3311,7 @@ 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 +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.) diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 95f7341c19c..8c23086e8d1 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Byte Compilation @chapter Byte Compilation @@ -140,7 +140,7 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}). If @var{symbol}'s definition is a byte-code function object, @code{byte-compile} does nothing and returns @code{nil}. It does not -``compile the symbol's definition again'', since the original +compile the symbol's definition again, since the original (non-compiled) code has already been replaced in the symbol's function cell by the byte-compiled code. @@ -240,60 +240,50 @@ $ emacs -batch -f batch-byte-compile *.el @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. + When Emacs loads functions and variables from a byte-compiled file, +it normally does not load their documentation strings into memory. +Each documentation string is dynamically loaded from the +byte-compiled file only when needed. This saves memory, and speeds up +loading by skipping the processing of the documentation strings. - Dynamic access to documentation strings does have drawbacks: + This feature has a drawback: if you delete, move, or alter the +compiled file (such as by compiling a new version), Emacs may no +longer be able to access the documentation string of previously-loaded +functions or variables. Such a problem normally only occurs if you +build Emacs yourself, and happen to edit and/or recompile the Lisp +source files. To solve it, just reload each file after recompilation. -@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 + Dynamic loading of documentation strings from byte-compiled files is +determined, at compile time, for each byte-compiled file. It can be +disabled via the option @code{byte-compile-dynamic-docstrings}. -@noindent -These problems normally occur only if you build Emacs yourself and use -it from the directory where you built it, and you happen to edit -and/or recompile the Lisp source files. They can be easily cured by -reloading each file after recompiling it. +@defopt 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. -@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. - - You can disable the dynamic documentation string 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: +To disable the dynamic loading feature for a specific file, set this +option to @code{nil} in its header line (@pxref{File Variables, , +Local Variables in Files, emacs, The GNU Emacs Manual}), like this: -@example +@smallexample -*-byte-compile-dynamic-docstrings: nil;-*- -@end example +@end smallexample -@defopt 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. +This is useful mainly if you expect to change the file, and you want +Emacs sessions that have already loaded it to keep working when the +file changes. @end defopt +@cindex @samp{#@@@var{count}} +@cindex @samp{#$} +Internally, the dynamic loading of documentation strings is +accomplished by writing compiled files with 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. Do not use these +constructs in Lisp source files; they are not designed to be clear to +humans reading the file. + @node Dynamic Loading @section Dynamic Loading of Individual Functions @@ -357,6 +347,7 @@ it does nothing. It always returns @var{function}. @node Eval During Compile @section Evaluation During Compilation +@cindex eval during compilation These features permit you to write code to be evaluated during compilation of a program. @@ -440,29 +431,35 @@ to what @code{eval-when-compile} does. @section Compiler Errors @cindex compiler errors - Byte compilation outputs all errors and warnings into the buffer -@file{*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 + Error and warning messages from byte compilation are printed in a +buffer named @file{*Compile-Log*}. These messages include file names +and line numbers identifying the location of the problem. The usual +Emacs commands for operating on compiler output can be used on these messages. When an error is due to invalid syntax in the program, the byte compiler might get confused about the errors' exact location. One way -to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}. -(This buffer name starts with a space, so it does not show up in -@kbd{M-x list-buffers}.) This buffer contains the program being +to investigate is to switch to the buffer @w{@file{ *Compiler +Input*}}. (This buffer name starts with a space, so it does not show +up in the Buffer Menu.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read; the cause of the error might be nearby. @xref{Syntax Errors}, for some tips for locating syntax errors. - When the byte compiler warns about functions that were used but not -defined, it always reports the line number for the end of the file, -not the locations where the missing functions were called. To find -the latter, you must search for the function names. + A common type of warning issued by the byte compiler is for +functions and variables that were used but not defined. Such warnings +report the line number for the end of the file, not the locations +where the missing functions or variables were used; to find these, you +must search the file manually. + + If you are sure that a warning message about a missing function or +variable is unjustified, there are several ways to suppress it: - 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: +@itemize @bullet +@item +You can suppress the warning for a specific call to a function +@var{func} by conditionalizing it on an @code{fboundp} test, like +this: @example (if (fboundp '@var{func}) ...(@var{func} ...)...) @@ -473,14 +470,10 @@ 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.) - You can tell the compiler that a function is defined using -@code{declare-function} (@pxref{Declaring Functions}). Likewise, you -can tell the compiler that a variable is defined using @code{defvar} -with no initial value. - - You can suppress the compiler warning for a specific use of an -undefined variable @var{variable} by conditionalizing its use on a -@code{boundp} test, like this: +@item +Likewise, you can suppress the warning for a specific use of a +variable @var{variable} by conditionalizing it on a @code{boundp} +test: @example (if (boundp '@var{variable}) ...@var{variable}...) @@ -491,7 +484,17 @@ 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 and all compiler warnings within a certain +@item +You can tell the compiler that a function is defined using +@code{declare-function}. @xref{Declaring Functions}. + +@item +Likewise, you can tell the compiler that a variable is defined using +@code{defvar} with no initial value. (Note that this marks the +variable as special.) @xref{Defining Variables}. +@end itemize + + You can also suppress any and all compiler warnings within a certain expression using the construct @code{with-no-warnings}: @c This is implemented with a defun, but conceptually it is @@ -507,8 +510,9 @@ possible piece of code, to avoid missing possible warnings other than one you intend to suppress. @end defspec - More precise control of warnings is possible by setting the variable -@code{byte-compile-warnings}. + Byte compiler warnings can be controlled more precisely by setting +the variable @code{byte-compile-warnings}. See its documentation +string for details. @node Byte-Code Objects @section Byte-Code Function Objects diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 70eabcd84a4..412903f8fbc 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Control Structures @@ -39,11 +39,14 @@ structure constructs (@pxref{Macros}). * Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. * Combining Conditions:: @code{and}, @code{or}, @code{not}. * Iteration:: @code{while} loops. +* Generators:: Generic sequences and coroutines. * Nonlocal Exits:: Jumping out of a sequence. @end menu @node Sequencing @section Sequencing +@cindex sequencing +@cindex sequential execution 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 @@ -70,7 +73,7 @@ The value of the last form in the body becomes the value of the entire 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}'': +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. @@ -217,16 +220,12 @@ list is the @var{condition}; the remaining elements, if any, the @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. +non-@code{nil}, the clause succeeds; then @code{cond} evaluates its +@var{body-forms}, and returns the value of the last of @var{body-forms}. +Any 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}. +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}. A clause may also look like this: @@ -235,8 +234,11 @@ A clause may also look like this: @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. +Then, if @var{condition} is non-@code{nil} when tested, the @code{cond} +form returns the value of @var{condition}. + +If every @var{condition} evaluates to @code{nil}, so that every clause +fails, @code{cond} returns @code{nil}. The following example has four clauses, which test for the cases where the value of @code{x} is a number, string, buffer and symbol, @@ -323,18 +325,19 @@ In the last clause, @code{code} is a variable that gets bound to the value that was returned by @code{(get-return-code x)}. To give a more complex example, a simple interpreter for a little -expression language could look like: +expression language could look like (note that this example requires +lexical binding): @example (defun evaluate (exp env) (pcase exp - (`(add ,x ,y) (+ (evaluate x env) (evaluate y env))) - (`(call ,fun ,arg) (funcall (evaluate fun) (evaluate arg env))) - (`(fn ,arg ,body) (lambda (val) - (evaluate body (cons (cons arg val) env)))) - ((pred numberp) exp) - ((pred symbolp) (cdr (assq exp env))) - (_ (error "Unknown expression %S" exp)))) + (`(add ,x ,y) (+ (evaluate x env) (evaluate y env))) + (`(call ,fun ,arg) (funcall (evaluate fun env) (evaluate arg env))) + (`(fn ,arg ,body) (lambda (val) + (evaluate body (cons (cons arg val) env)))) + ((pred numberp) exp) + ((pred symbolp) (cdr (assq exp env))) + (_ (error "Unknown expression %S" exp)))) @end example Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three @@ -343,6 +346,15 @@ third elements and binds them to the variables @code{x} and @code{y}. @code{(pred numberp)} is a pattern that simply checks that @code{exp} is a number, and @code{_} is the catch-all pattern that matches anything. +Here are some sample programs including their evaluation results: + +@example +(evaluate '(add 1 2) nil) ;=> 3 +(evaluate '(add x y) '((x . 1) (y . 2))) ;=> 3 +(evaluate '(call (fn x (add 1 x)) 2) nil) ;=> 3 +(evaluate '(sub 1 2) nil) ;=> error +@end example + There are two kinds of patterns involved in @code{pcase}, called @emph{U-patterns} and @emph{Q-patterns}. The @var{upattern} mentioned above are U-patterns and can take the following forms: @@ -359,8 +371,12 @@ that location. More specifically, a Q-pattern can take the following forms: @table @code @item (@var{qpattern1} . @var{qpattern2}) -This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and -whose @code{cdr} matches @var{PATTERN2}. +This pattern matches any cons cell whose @code{car} matches @var{qpattern1} and +whose @code{cdr} matches @var{qpattern2}. +@item [@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}] +This pattern matches a vector of length @var{M} whose 0..(@var{M}-1)th +elements match @var{qpattern1}, @var{qpattern2} @dots{} @var{qpatternm}, +respectively. @item @var{atom} This pattern matches any atom @code{equal} to @var{atom}. @item ,@var{upattern} @@ -392,6 +408,7 @@ the variable @code{x}. @node Combining Conditions @section Constructs for Combining Conditions +@cindex combining conditions This section describes three constructs that are often used together with @code{if} and @code{cond} to express complicated conditions. The @@ -554,7 +571,7 @@ The value of a @code{while} form is always @code{nil}. @end group @end example -To write a ``repeat...until'' loop, which will execute something on each +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: @@ -604,6 +621,123 @@ Here is an example of using @code{dotimes} to do something 100 times: @end example @end defmac +@node Generators +@section Generators +@cindex generators + + A @dfn{generator} is a function that produces a potentially-infinite +stream of values. Each time the function produces a value, it +suspends itself and waits for a caller to request the next value. + +@defmac iter-defun name args [doc] [declare] [interactive] body@dots{} +@code{iter-defun} defines a generator function. A generator function +has the same signature as a normal function, but works differently. +Instead of executing @var{body} when called, a generator function +returns an iterator object. That iterator runs @var{body} to generate +values, emitting a value and pausing where @code{iter-yield} or +@code{iter-yield-from} appears. When @var{body} returns normally, +@code{iter-next} signals @code{iter-end-of-sequence} with @var{body}'s +result as its condition data. + +Any kind of Lisp code is valid inside @var{body}, but +@code{iter-yield} and @code{iter-yield-from} cannot appear inside +@code{unwind-protect} forms. + +@end defmac + +@defmac iter-lambda args [doc] [interactive] body@dots{} +@code{iter-lambda} produces an unnamed generator function that works +just like a generator function produced with @code{iter-defun}. +@end defmac + +@defmac iter-yield value +When it appears inside a generator function, @code{iter-yield} +indicates that the current iterator should pause and return +@var{value} from @code{iter-next}. @code{iter-yield} evaluates to the +@code{value} parameter of next call to @code{iter-next}. +@end defmac + +@defmac iter-yield-from iterator +@code{iter-yield-from} yields all the values that @var{iterator} +produces and evaluates to the value that @var{iterator}'s generator +function returns normally. While it has control, @var{iterator} +receives values sent to the iterator using @code{iter-next}. +@end defmac + + To use a generator function, first call it normally, producing a +@dfn{iterator} object. An iterator is a specific instance of a +generator. Then use @code{iter-next} to retrieve values from this +iterator. When there are no more values to pull from an iterator, +@code{iter-next} raises an @code{iter-end-of-sequence} condition with +the iterator's final value. + +It's important to note that generator function bodies only execute +inside calls to @code{iter-next}. A call to a function defined with +@code{iter-defun} produces an iterator; you must drive this +iterator with @code{iter-next} for anything interesting to happen. +Each call to a generator function produces a @emph{different} +iterator, each with its own state. + +@defun iter-next iterator value +Retrieve the next value from @var{iterator}. If there are no more +values to be generated (because @var{iterator}'s generator function +returned), @code{iter-next} signals the @code{iter-end-of-sequence} +condition; the data value associated with this condition is the value +with which @var{iterator}'s generator function returned. + +@var{value} is sent into the iterator and becomes the value to which +@code{iter-yield} evaluates. @var{value} is ignored for the first +@code{iter-next} call to a given iterator, since at the start of +@var{iterator}'s generator function, the generator function is not +evaluating any @code{iter-yield} form. +@end defun + +@defun iter-close iterator +If @var{iterator} is suspended inside an @code{unwind-protect}'s +@code{bodyform} and becomes unreachable, Emacs will eventually run +unwind handlers after a garbage collection pass. (Note that +@code{iter-yield} is illegal inside an @code{unwind-protect}'s +@code{unwindforms}.) To ensure that these handlers are run before +then, use @code{iter-close}. +@end defun + +Some convenience functions are provided to make working with +iterators easier: + +@defmac iter-do (var iterator) body @dots{} +Run @var{body} with @var{var} bound to each value that +@var{iterator} produces. +@end defmac + +The Common Lisp loop facility also contains features for working with +iterators. See @xref{Loop Facility,,,cl,Common Lisp Extensions}. + +The following piece of code demonstrates some important principles of +working with iterators. + +@example +(iter-defun my-iter (x) + (iter-yield (1+ (iter-yield (1+ x)))) + ;; Return normally + -1) + +(let* ((iter (my-iter 5)) + (iter2 (my-iter 0))) + ;; Prints 6 + (print (iter-next iter)) + ;; Prints 9 + (print (iter-next iter 8)) + ;; Prints 1; iter and iter2 have distinct states + (print (iter-next iter2 nil)) + + ;; We expect the iter sequence to end now + (condition-case x + (iter-next iter) + (iter-end-of-sequence + ;; Prints -1, which my-iter returned normally + (print (cdr x))))) +@end example + @node Nonlocal Exits @section Nonlocal Exits @cindex nonlocal exits @@ -724,7 +858,7 @@ error is signaled with data @code{(@var{tag} @var{value})}. @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 ``goto''.) +nested loop. (In most languages, this would be done with a @code{goto}.) Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} varying from 0 to 9: @@ -838,7 +972,7 @@ 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 + 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 @@ -856,7 +990,7 @@ 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 +applying @code{format-message} (@pxref{Formatting Strings}) to @var{format-string} and @var{args}. These examples show typical uses of @code{error}: @@ -868,19 +1002,25 @@ These examples show typical uses of @code{error}: @end group @group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors +(error "Invalid name `%s'" "A%%B") + @error{} Invalid name ‘A%%B’ @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}. +@code{format-message}. + +In a format string containing single quotes, curved quotes @t{‘like +this’} and grave quotes @t{`like this'} work better than straight +quotes @t{'like this'}, as @code{error} typically formats every +straight quote as a curved closing quote. @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})}. +@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be +reformatted, with undesirable results. Instead, use @code{(error "%s" +@var{string})}. @end defun @defun signal error-symbol data @@ -891,7 +1031,7 @@ the circumstances of the error. The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol defined with @code{define-error}. This is how Emacs Lisp classifies different -sorts of errors. @xref{Error Symbols}, for a description of error symbols, +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 @@ -949,6 +1089,7 @@ concept of continuable errors. @node Processing of Errors @subsubsection How Emacs Processes Errors +@cindex processing of errors When an error is signaled, @code{signal} searches for an active @dfn{handler} for the error. A handler is a sequence of Lisp @@ -1243,10 +1384,13 @@ Here's the example at the beginning of this subsection rewritten using @end example @end defmac -@defmac with-demoted-errors body@dots{} +@defmac with-demoted-errors format body@dots{} This macro is like a milder version of @code{ignore-errors}. Rather than suppressing errors altogether, it converts them into messages. -Use this form around code that is not expected to signal errors, but +It uses the string @var{format} to format the message. +@var{format} should contain a single @samp{%}-sequence; e.g., +@code{"Error: %S"}. Use @code{with-demoted-errors} around code +that is not expected to signal errors, but should be robust if one does occur. Note that this macro uses @code{condition-case-unless-debug} rather than @code{condition-case}. @end defmac @@ -1351,6 +1495,7 @@ and their conditions. @node Cleanups @subsection Cleaning Up from Nonlocal Exits +@cindex nonlocal exits, cleaning up The @code{unwind-protect} construct is essential whenever you temporarily put a data structure in an inconsistent state; it permits diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index e9260309057..51d729f665c 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2013 Free Software Foundation, Inc. +@c Copyright (C) 1997-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Customization @chapter Customization Settings @@ -287,13 +287,17 @@ customizable variable). You should not quote @var{option}. 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. +evaluates @var{standard}, but does not necessarily bind the option to +that value. If @var{option} already has a default value, it is left +unchanged. If the user has already saved a customization for +@var{option}, the user's customized value is installed as the default +value. Otherwise, the result of evaluating @var{standard} is +installed as the default value. + +Like @code{defvar}, this macro marks @code{option} as a special +variable, meaning that it should always be dynamically bound. If +@var{option} is already lexically bound, that lexical binding remains +in effect until the binding construct exits. @xref{Variable Scoping}. The expression @var{standard} can be evaluated at various other times, too---whenever the customization facility needs to know @var{option}'s @@ -349,8 +353,9 @@ option when using the Customize interface. 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}. +the option as a Lisp variable); preferably, though, it should not +modify its value argument destructively. The default for +@var{setfunction} is @code{set-default}. If you specify this keyword, the variable's documentation string should describe how to do the same job in hand-written Lisp code. @@ -360,7 +365,7 @@ should describe how to do the same job in hand-written Lisp code. 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 +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 @@ -436,7 +441,7 @@ those other variables already have their intended values. @end table It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the +that turns on a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. @xref{Common Keywords}. Here is an example, from the library @file{saveplace.el}: @@ -567,7 +572,7 @@ The value must be an integer. The value must be a number (floating point or integer). @item float -The value must be a floating point number. +The value must be floating point. @item string The value must be a string. The customization buffer shows the string @@ -718,7 +723,7 @@ simply atoms, which stand for themselves. For example: @end example @noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, +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 @@ -837,7 +842,7 @@ 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 +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). @@ -1222,6 +1227,8 @@ arguments, which will be used when creating the @code{radio-button} or @node Defining New Types @subsection Defining New Types +@cindex customization types, define new +@cindex define new customization types In the previous sections we have described how to construct elaborate type specifications for @code{defcustom}. In some cases you may want @@ -1291,6 +1298,7 @@ its @code{:type} argument only when needed. @node Applying Customizations @section Applying Customizations +@cindex applying customizations The following functions are responsible for installing the user's customization settings for variables and faces, respectively. When @@ -1348,6 +1356,7 @@ evaluated. @var{comment} is a string describing the customization. @node Custom Themes @section Custom Themes +@cindex custom themes @dfn{Custom themes} are collections of settings that can be enabled or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs Manual}. Each Custom theme is defined by an Emacs Lisp source file, @@ -1369,8 +1378,8 @@ the theme; this is the description shown when the user invokes the Themes*} buffer. Two special theme names are disallowed (using them causes an error): -@code{user} is a ``dummy'' theme that stores the user's direct -customization settings, and @code{changed} is a ``dummy'' theme that +@code{user} is a dummy theme that stores the user's direct +customization settings, and @code{changed} is a dummy theme that stores changes made outside of the Customize system. @end defmac @@ -1413,7 +1422,7 @@ where the list entries have the same meanings as in @end defun In theory, a theme file can also contain other Lisp forms, which -would be evaluated when loading the theme, but that is ``bad form''. +would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. @@ -1428,6 +1437,17 @@ loaded into Emacs, whether or not the theme is enabled). Otherwise, it returns @code{nil}. @end defun +@defvar custom-known-themes +The value of this variable is a list of themes loaded into Emacs. +Each theme is represented by a Lisp symbol (the theme name). The +default value of this variable is a list containing two dummy +themes: @code{(user changed)}. The @code{changed} theme stores +settings made before any Custom themes are applied (e.g., variables +set outside of Customize). The @code{user} theme stores settings the +user has customized and saved. Any additional themes declared with +the @code{deftheme} macro are added to the front of this list. +@end defvar + @deffn Command load-theme theme &optional no-confirm no-enable This function loads the Custom theme named @var{theme} from its source file, looking for the source file in the directories specified by the diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 335e3f802d2..e82efbb0b72 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1,10 +1,11 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Debugging @chapter Debugging Lisp Programs +@cindex debugging lisp programs There are several ways to find and investigate problems in an Emacs Lisp program. @@ -226,9 +227,7 @@ 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. +time it is called. 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. @@ -244,11 +243,6 @@ When @code{debug-on-entry} is called interactively, it prompts for 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 @@ -277,12 +271,6 @@ Debugger entered--entering a function: ------ 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 @@ -297,6 +285,8 @@ not currently set up to break on entry. @node Explicit Debug @subsection Explicit Entry to the Debugger +@cindex debugger, explicit entry +@cindex force entry to 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 @@ -388,6 +378,7 @@ 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. +@c FIXME: Add @findex for the following commands? --xfq Here is a list of Debugger mode commands: @table @kbd @@ -424,7 +415,8 @@ Flag the current frame like @kbd{b}. Then continue execution like 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 +Read a Lisp expression in the minibuffer, evaluate it (with the +relevant lexical environment, if applicable), 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 @@ -459,13 +451,15 @@ 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. +@code{debug-on-entry}. + +@item v +Toggle the display of local variables of the current stack frame. @end table @node Invoking the Debugger @subsection Invoking the Debugger +@cindex invoking lisp debugger Here we describe in full detail the function @code{debug} that is used to invoke the debugger. @@ -690,11 +684,11 @@ If @var{frame-number} is out of range, @code{backtrace-frame} returns @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 +problem is. For example, the error @samp{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 +been. Likewise, @samp{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? @@ -717,6 +711,7 @@ find the mismatch.) @node Excess Open @subsection Excess Open Parentheses +@cindex 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 @@ -751,6 +746,7 @@ anything. @node Excess Close @subsection Excess Close Parentheses +@cindex 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 @@ -819,6 +815,7 @@ be cleaner to combine them. @node Profiling @section Profiling @cindex profiling +@cindex profile @cindex measuring resource usage @cindex memory usage diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index ff9d98170d1..ad248b116ed 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Display @chapter Emacs Display @@ -18,12 +18,13 @@ that Emacs presents to the user. * 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. +* Size of Displayed Text:: How large displayed text is. * 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. +* Scroll Bars:: Controlling scroll bars. +* Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. @@ -38,6 +39,8 @@ that Emacs presents to the user. @node Refresh Screen @section Refreshing the Screen +@cindex refresh the screen +@cindex screen refresh The function @code{redraw-frame} clears and redisplays the entire contents of a given frame (@pxref{Frames}). This is useful if the @@ -84,10 +87,7 @@ waiting for input. @defun redisplay &optional force This function tries immediately to redisplay. The optional argument @var{force}, if non-@code{nil}, forces the redisplay to be performed, -instead of being preempted, even if input is pending and the variable -@code{redisplay-dont-pause} is @code{nil} (see below). If -@code{redisplay-dont-pause} is non-@code{nil} (the default), this -function redisplays in any case, i.e., @var{force} does nothing. +instead of being preempted if input is pending. The function returns @code{t} if it actually tried to redisplay, and @code{nil} otherwise. A value of @code{t} does not mean that @@ -95,26 +95,9 @@ redisplay proceeded to completion; it could have been preempted by newly arriving input. @end defun -@defvar redisplay-dont-pause -If this variable is @code{nil}, arriving input events preempt -redisplay; Emacs avoids starting a redisplay, and stops any redisplay -that is in progress, until the input has been processed. In -particular, @code{(redisplay)} returns @code{nil} without actually -redisplaying, if there is pending input. - -The default value is @code{t}, which means that pending input does not -preempt redisplay. -@end defvar - -@defvar redisplay-preemption-period -If @code{redisplay-dont-pause} is @code{nil}, this variable specifies -how many seconds Emacs waits between checks for new input during -redisplay; if input arrives during this interval, redisplay stops and -the input is processed. The default value is 0.1; if the value is -@code{nil}, Emacs does not check for input during redisplay. - -This variable has no effect when @code{redisplay-dont-pause} is -non-@code{nil} (the default). +@defvar pre-redisplay-function +A function run just before redisplay. It is called with one argument, +the set of windows to redisplay. @end defvar Although @code{redisplay} tries immediately to redisplay, it does @@ -143,7 +126,7 @@ it waits for input, or when the function @code{redisplay} is called. @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 +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; @@ -155,7 +138,7 @@ boundary. @xref{Filling}. 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 +wraps. (The display table can specify alternate characters to use for this; @pxref{Display Tables}). @defopt truncate-lines @@ -168,6 +151,7 @@ entire frame width). @end defopt @defopt truncate-partial-width-windows +@cindex partial-width windows This variable controls line truncation in @dfn{partial-width} windows. A partial-width window is one that does not occupy the entire frame width (@pxref{Splitting Windows}). If the value is @code{nil}, line @@ -213,28 +197,28 @@ A line prefix may also be specified for regions of text using the over the @code{line-prefix} variable. @xref{Special Properties}. @end defvar - If your buffer contains @emph{very} long lines, and you use -continuation to display them, computing the continuation lines can -make redisplay slow. The column computation and indentation functions -also become slow. Then you might find it advisable to set -@code{cache-long-scans} to @code{t}. +@ignore + If your buffer contains only very short lines, you might find it +advisable to set @code{cache-long-scans} to @code{nil}. @defvar cache-long-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. +If this variable is non-@code{nil} (the default), 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. +Turning off the cache speeds up processing of short lines somewhat. This variable is automatically buffer-local in every buffer. @end defvar +@end ignore @node The Echo Area @section The Echo Area @cindex error display @cindex echo area +@c FIXME: Why not use @xref{Minibuffers} directly? --xfq 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, @@ -263,16 +247,24 @@ messages in the echo area. @defun message format-string &rest arguments This function displays a message in the echo area. @var{format-string} is a format string, and @var{arguments} are the -objects for its format specifications, like in the @code{format} +objects for its format specifications, like in the @code{format-message} function (@pxref{Formatting Strings}). The resulting formatted string is displayed in the echo area; if it contains @code{face} text properties, it is displayed with the specified faces (@pxref{Faces}). The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). +In a format string containing single quotes, curved quotes @t{‘like +this’} and grave quotes @t{`like this'} work better than straight +quotes @t{'like this'}, as @code{message} typically formats every +straight quote as a curved closing quote. + In batch mode, the message is printed to the standard error stream, followed by a newline. +When @code{inhibit-message} is non-@code{nil}, no message will be displayed +in the echo area, it will only be logged to @samp{*Messages*}. + 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 @@ -281,23 +273,33 @@ onto the screen immediately. @example @group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." +(message "Reverting `%s'..." (buffer-name)) + @print{} Reverting ‘subr.el’... +@result{} "Reverting ‘subr.el’..." @end group @group ---------- Echo Area ---------- -Minibuffer depth is 0. +Reverting ‘subr.el’... ---------- 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). + +@strong{Warning:} If you want to use your own string as a message +verbatim, don't just write @code{(message @var{string})}. If +@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be +reformatted, with undesirable results. Instead, use @code{(message +"%s" @var{string})}. @end defun +@defvar inhibit-message +When this variable is non-@code{nil}, @code{message} and related functions +will not use the Echo Area to display messages. +@end defvar + @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 @@ -383,12 +385,12 @@ 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 +on a filename, for instance, use @code{format-message} before calling this function. The arguments @var{min-value} and @var{max-value} should be numbers standing for the starting and final states of the operation. For -instance, an operation that ``scans'' a buffer should set these to the +instance, an operation that scans a buffer should set these to the results of @code{point-min} and @code{point-max} correspondingly. @var{max-value} should be greater than @var{min-value}. @@ -440,20 +442,20 @@ 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 +you to change the message of the @var{reporter}. Since this function 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 +prints the message of @var{reporter} followed by word @samp{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 +@code{progress-reporter-update} to print @samp{100%}. Firstly, it may never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. +Secondly, @samp{done} is more explicit. @end defun @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} @@ -479,7 +481,17 @@ this macro this way: Almost all the messages displayed in the echo area are also recorded in the @file{*Messages*} buffer so that the user can refer back to them. This includes all the messages that are output with -@code{message}. +@code{message}. By default, this buffer is read-only and uses the major +mode @code{messages-buffer-mode}. Nothing prevents the user from +killing the @file{*Messages*} buffer, but the next display of a message +recreates it. Any Lisp code that needs to access the +@file{*Messages*} buffer directly and wants to ensure that it exists +should use the function @code{messages-buffer}. + +@defun messages-buffer +This function returns the @file{*Messages*} buffer. If it does not +exist, it creates it, and switches it to @code{messages-buffer-mode}. +@end defun @defopt message-log-max This variable specifies how many lines to keep in the @file{*Messages*} @@ -498,13 +510,13 @@ 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 + A question followed by an answer has 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 + A series of progress messages has 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 @@ -517,6 +529,7 @@ are logged that share a common prefix ending in @samp{...}. @node Echo Area Customization @subsection Echo Area Customization +@cindex echo area customization These variables control details of how the echo area works. @@ -537,8 +550,7 @@ This normal hook is run whenever the echo area is cleared---either by @defopt 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 +characters echo. Its value must be a number, and 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 @@ -609,6 +621,9 @@ 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.) +@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply +@c "bytecomp" here? The parens are part of warning-type-format but +@c not part of the warning type. --xfq @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 @@ -627,13 +642,13 @@ for logging the warning. By default, it is @file{*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}. +This function reports a warning using the value of @code{(format-message +@var{message} @var{args}...)} as the message in the @file{*Warnings*} +buffer. 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 +This function reports a warning using the value of @code{(format-message @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 @@ -642,6 +657,7 @@ specify a specific warning type. @node Warning Variables @subsection Warning Variables +@cindex warning variables Programs can customize how their warnings appear by binding the variables described in this section. @@ -719,6 +735,7 @@ all. @node Warning Options @subsection Warning Options +@cindex warning options These variables are used by users to control what happens when a Lisp program reports a warning. @@ -752,6 +769,7 @@ that warning is not logged. @node Delayed Warnings @subsection Delayed Warnings +@cindex delayed warnings Sometimes, you may wish to avoid showing a warning while a command is running, and only show it only after the end of the command. You can @@ -911,12 +929,14 @@ current value of @code{buffer-invisibility-spec}. @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 -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 at the boundary of +whether the text is invisible, they process invisible characters and +visible characters alike. The user-level line motion commands, +such as @code{next-line}, @code{previous-line}, ignore invisible +newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the +default), i.e., behave like these invisible newlines didn't exist in +the buffer, but only because they are explicitly programmed to do so. + + If a command ends with point inside or at the boundary of invisible text, the main editing loop relocates point to one of the two ends of the invisible text. Emacs chooses the direction of relocation so that it is the same as the overall movement direction of @@ -933,6 +953,10 @@ command moved point forward into an invisible range, Emacs moves point forward to the first visible character that follows the invisible text and then forward one more character. + These @dfn{adjustments} of point that ended up in the middle of +invisible text can be disabled by setting @code{disable-point-adjustment} +to a non-@code{nil} value. @xref{Adjusting Point}. + 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} @@ -956,11 +980,11 @@ make it invisible again. @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. +@cindex explicit selective display + The first variant, explicit selective display, was designed for use in a Lisp +program: it controls which lines are hidden by altering the text. This kind of +hiding is now obsolete; instead you can get the same effect with the +@code{invisible} property (@pxref{Invisible Text}). In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a @@ -1069,34 +1093,36 @@ You can use a display table to substitute other text for the ellipsis @node Temporary Displays @section Temporary Displays +@cindex temporary display +@cindex temporary buffer display 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. -@defmac 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. (See the similar -form @code{with-temp-buffer-window} below.) - -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 +@defmac with-output-to-temp-buffer buffer-name body@dots{} +This function executes the forms in @var{body} 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. (See the similar +form @code{with-temp-buffer-window} below.) Finally, the buffer is +displayed in some window, but that window is not selected. + +If the forms in @var{body} 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. +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 +temporary buffer, then it evaluates the forms in @var{body}. Output +using the Lisp output functions within @var{body} 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}. @@ -1104,7 +1130,7 @@ they are ``output'' in the general sense of the word, are not affected). 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. +The value of the last form in @var{body} is returned. @example @group @@ -1120,6 +1146,7 @@ The value of the last form in @var{forms} is returned. @result{} #<buffer foo> ---------- Buffer: foo ---------- + 20 #<buffer foo> @@ -1153,29 +1180,28 @@ displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected. @end defvar -@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{} -This macro is similar to @code{with-output-to-temp-buffer}. -Like that construct, it executes @var{forms} while arranging to insert -any output they print into the buffer named @var{buffer-or-name}. -Finally, the buffer is displayed in some window, but not selected. -Unlike @code{with-output-to-temp-buffer}, this does not switch to Help -mode. +@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{} +This macro is similar to @code{with-output-to-temp-buffer}. Like that +construct, it executes @var{body} while arranging to insert any output +it prints into the buffer named @var{buffer-or-name} and displays that +buffer in some window. Unlike @code{with-output-to-temp-buffer}, +however, it does not automatically switch that buffer to Help mode. -The argument @var{buffer-or-name} specifies the temporary buffer. -It can be either a buffer, which must already exist, or a string, -in which case a buffer of that name is created if necessary. -The buffer is marked as unmodified and read-only when -@code{with-temp-buffer-window} exits. +The argument @var{buffer-or-name} specifies the temporary buffer. It +can be either a buffer, which must already exist, or a string, in which +case a buffer of that name is created, if necessary. The buffer is +marked as unmodified and read-only when @code{with-temp-buffer-window} +exits. This macro does not call @code{temp-buffer-show-function}. Rather, it -passes the @var{action} argument to @code{display-buffer} in order to -display the buffer. +passes the @var{action} argument to @code{display-buffer} +(@pxref{Choosing Window}) in order to display the buffer. -The value of the last form in @var{forms} is returned, unless the -argument @var{quit-function} is specified. In that case, -it is called with two arguments: the window showing the buffer -and the result of @var{forms}. The final return value is then -whatever @var{quit-function} returns. +The value of the last form in @var{body} is returned, unless the +argument @var{quit-function} is specified. In that case, it is called +with two arguments: the window showing the buffer and the result of +@var{body}. The final return value is then whatever @var{quit-function} +returns. @vindex temp-buffer-window-setup-hook @vindex temp-buffer-window-show-hook @@ -1184,6 +1210,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks run by @code{with-output-to-temp-buffer}. @end defmac +The two constructs described next are mostly identical to +@code{with-temp-buffer-window} but differ from it as specified: + +@defmac with-current-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-temp-buffer-window} but unlike that makes +the buffer specified by @var{buffer-or-name} current for running +@var{body}. +@end defmac + +@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-current-buffer-window} but unlike that +displays the buffer specified by @var{buffer-or-name} @emph{before} +running @var{body}. +@end defmac + +A window showing a temporary buffer can be fit to the size of that +buffer using the following mode: + +@defopt temp-buffer-resize-mode +When this minor mode is enabled, windows showing a temporary buffer are +automatically resized to fit their buffer's contents. + +A window is resized if and only if it has been specially created for the +buffer. In particular, windows that have shown another buffer before +are not resized. By default, this mode uses @code{fit-window-to-buffer} +(@pxref{Resizing Windows}) for resizing. You can specify a different +function by customizing the options @code{temp-buffer-max-height} and +@code{temp-buffer-max-width} below. +@end defopt + +@defopt temp-buffer-max-height +This option specifies the maximum height (in lines) of a window +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the height +for such a buffer. It gets one argument, the buffer, and should return +a positive integer. At the time the function is called, the window to +be resized is selected. +@end defopt + +@defopt temp-buffer-max-width +This option specifies the maximum width of a window (in columns) +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the width for +such a buffer. It gets one argument, the buffer, and should return a +positive integer. At the time the function is called, the window to be +resized is selected. +@end defopt + +The following function uses the current buffer for temporal display: + @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 @@ -1252,6 +1328,7 @@ beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. @cindex scalability of overlays +@cindex overlays, scalability The visual effect of an overlay is the same as of the corresponding text property (@pxref{Text Properties}). However, due to a different implementation, overlays generally don't scale well (many operations @@ -1274,6 +1351,8 @@ inside the overlay or outside, and likewise for the end of the overlay. @node Managing Overlays @subsection Managing Overlays +@cindex managing overlays +@cindex overlays, managing This section describes the functions to create, delete and move overlays, and to examine their contents. Overlay changes are not @@ -1291,6 +1370,15 @@ 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. +@cindex empty overlay +@cindex overlay, empty +An overlay whose @var{start} and @var{end} specify the same buffer +position is known as @dfn{empty}. A non-empty overlay can become +empty if the text between its @var{start} and @var{end} is deleted. +When that happens, the overlay is by default not deleted, but you can +cause it to be deleted by giving it the @samp{evaporate} property +(@pxref{Overlay Properties, evaporate property}). + 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 @@ -1341,7 +1429,7 @@ 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''. +lost. @end defun @defun remove-overlays &optional start end name value @@ -1418,7 +1506,7 @@ foo @end example Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position''. One list extends backwards +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. @@ -1434,6 +1522,7 @@ faster if you do @code{(overlay-recenter (point-max))} first. @node Overlay Properties @subsection Overlay Properties +@cindex 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 @@ -1450,8 +1539,10 @@ the buffer's undo list. Since more than one overlay can specify a property value for the same character, Emacs lets you specify a priority value of each -overlay. You should not make assumptions about which overlay will -prevail when there is a conflict and they have the same priority. +overlay. In case two overlays have the same priority value, and one +is nested in the other, then the inner one will have priority over the +outer one. If neither is nested in the other then you should not make +assumptions about which overlay will prevail. These functions read and set the properties of an overlay: @@ -1482,9 +1573,9 @@ of them: @table @code @item priority @kindex priority @r{(overlay property)} -This property's value (which should be a non-negative integer number) -determines the priority of the overlay. No priority, or @code{nil}, -means zero. +This property's value determines the priority of the overlay. +If you want to specify a priority value, use either @code{nil} +(or zero), or a positive integer. Any other value has undefined behavior. The priority matters when two or more overlays cover the same character and both specify the same property; the one whose @@ -1494,9 +1585,13 @@ completely override the other value; instead, its face attributes override the face attributes of the lower priority @code{face} property. -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. +Currently, all overlays take priority over text properties. + +Note that Emacs sometimes uses non-numeric priority values for some of +its internal overlays, so do not try to do arithmetic on the +priority of an overlay (unless it is one that you created). If you +need to put overlays in priority order, use the @var{sorted} argument +of @code{overlays-at}. @xref{Finding Overlays}. @item window @kindex window @r{(overlay property)} @@ -1653,8 +1748,11 @@ line at display-time. @xref{Truncation}. @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. +an empty overlay (@pxref{Managing Overlays, empty overlay}) a +non-@code{nil} @code{evaporate} property, that deletes it immediately. +Note that, unless an overlay has this property, it will not be deleted +when the text between its starting and ending positions is deleted +from the buffer. @item keymap @cindex keymap of character (and overlays) @@ -1680,12 +1778,15 @@ Properties}. @node Finding Overlays @subsection Searching for Overlays +@cindex searching for overlays +@cindex overlays, searching for -@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}. +@defun overlays-at pos &optional sorted +This function returns a list of all the overlays that cover the character at +position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil}, +the list is in decreasing order of priority, otherwise it 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: @@ -1705,12 +1806,11 @@ overlays that specify property @var{prop} for the character at point: @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}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. +@var{beg} through @var{end}. An overlay overlaps with a region if it +contains one or more characters in the region; empty overlays +(@pxref{Managing Overlays, empty overlay}) overlap if they are at +@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} +when @var{end} denotes the position at the end of the buffer. @end defun @defun next-overlay-change pos @@ -1744,8 +1844,10 @@ changes. (point))) @end smallexample -@node Width -@section Width +@node Size of Displayed Text +@section Size of Displayed Text +@cindex size of text on display +@cindex character width on display Since not all characters have the same width, these functions let you check the width of a character. @xref{Primitive Indent}, and @@ -1788,9 +1890,9 @@ 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 +replace the end of @var{string} (including any padding) if it extends +beyond @var{width}, unless the display width of @var{string} 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{"..."}. @@ -1802,20 +1904,69 @@ equal to or less than the display width of @var{ellipsis}. If @end example @end defun +The following function returns the size in pixels of text as if it were +displayed in a given window. This function is used by +@code{fit-window-to-buffer} and @code{fit-frame-to-buffer} +(@pxref{Resizing Windows}) to make a window exactly as large as the text +it contains. + +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line +This function returns the size of the text of @var{window}'s buffer in +pixels. @var{window} must be a live window and defaults to the selected +one. The return value is a cons of the maximum pixel-width of any text +line and the maximum pixel-height of all text lines. + +The optional argument @var{from}, if non-@code{nil}, specifies the first +text position to consider and defaults to the minimum accessible +position of the buffer. If @var{from} is @code{t}, it uses the minimum +accessible position that is not a newline character. The optional +argument @var{to}, if non-@code{nil}, specifies the last text position +to consider and defaults to the maximum accessible position of the +buffer. If @var{to} is @code{t}, it uses the maximum accessible +position that is not a newline character. + +The optional argument @var{x-limit}, if non-@code{nil}, specifies the +maximum pixel-width that can be returned. @var{x-limit} @code{nil} or +omitted, means to use the pixel-width of @var{window}'s body +(@pxref{Window Sizes}); this is useful when the caller does not intend +to change the width of @var{window}. Otherwise, the caller should +specify here the maximum width @var{window}'s body may assume. Text +whose x-coordinate is beyond @var{x-limit} is ignored. Since +calculating the width of long lines can take some time, it's always a +good idea to make this argument as small as needed; in particular, if +the buffer might contain long lines that will be truncated anyway. + +The optional argument @var{y-limit}, if non-@code{nil}, specifies the +maximum pixel-height that can be returned. Text lines whose +y-coordinate is beyond @var{y-limit} are ignored. Since calculating the +pixel-height of a large buffer can take some time, it makes sense to +specify this argument; in particular, if the caller does not know the +size of the buffer. + +The optional argument @var{mode-and-header-line} @code{nil} or omitted +means to not include the height of the mode- or header-line of +@var{window} in the return value. If it is either the symbol +@code{mode-line} or @code{header-line}, include only the height of that +line, if present, in the return value. If it is @code{t}, include the +height of both, if present, in the return value. +@end defun + + @node Line Height @section Line Height @cindex line height +@cindex height of a line 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.) + 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 corresponding frame's default font, see @ref{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 @@ -1839,6 +1990,7 @@ First Emacs uses @var{height} as a height spec to control extra space to bring the total line height up to @var{total}. In this case, the other ways to specify the line spacing are ignored. +@cindex height spec 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: @@ -1873,14 +2025,14 @@ parts of Emacs text. lines in a frame, using the @code{line-spacing} frame parameter (@pxref{Layout Parameters}). However, if the default value of @code{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. A floating point number specifies +frame's @code{line-spacing} parameter. An integer specifies the +number of pixels put below lines. 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. A floating point number +buffer-local @code{line-spacing} variable. An integer specifies +the number of pixels put below lines. A floating-point number specifies the spacing relative to the default frame line height. This overrides line spacings specified for the frame. @@ -1994,11 +2146,11 @@ Relative character width. This should be one of the symbols The height of the font. In the simplest case, this is an integer in units of 1/10 point. -The value can also be a floating point number or a function, which +The value can also be floating point or a function, which specifies the height relative to an @dfn{underlying face} -(@pxref{Displaying Faces}). If the value is a floating point number, -that specifies the amount by which to scale the height of the -underlying face. If the value is a function, that function is called +(@pxref{Displaying Faces}). A floating-point value +specifies the amount by which to scale the height of the +underlying face. A function value is called with one argument, the height of the underlying face, and returns the height of the new face. If the function is passed an integer argument, it must return an integer. @@ -2028,6 +2180,15 @@ name, or a hexadecimal color specification. @xref{Color Names}. On black-and-white displays, certain shades of gray are implemented by stipple patterns. +@item :distant-foreground +Alternative foreground color, a string. This is like @code{:foreground} +but the color is only used as a foreground when the background color is +near to the foreground that would have been used. This is useful for +example when marking text (i.e., the region face). If the text has a foreground +that is visible with the region face, that foreground is used. +If the foreground is near the region face background, +@code{:distant-foreground} is used instead so the text is readable. + @item :background Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. @xref{Color Names}. @@ -2068,6 +2229,8 @@ value @code{nil} means do not overline. Whether or not characters should be strike-through, and in what color. The value is used like that of @code{:overline}. +@cindex 2D box +@cindex 3D box @item :box Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance. Here are the possible @@ -2141,6 +2304,7 @@ font matching those wildcards. Specifying this attribute also changes the values of the @code{:family}, @code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and @code{:slant} attributes. +@cindex inheritance, for faces @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 @@ -2174,6 +2338,7 @@ suitable for use with @code{:stipple} (see above). It returns @node Defining Faces @subsection Defining Faces +@cindex defining faces @cindex face spec The usual way to define a face is through the @code{defface} macro. @@ -2330,20 +2495,25 @@ This function applies @var{spec} as a face spec for @code{face}. @var{spec} should be a face spec, as described in the above documentation for @code{defface}. +This function also defines @var{face} as a valid face name if it is +not already one, and (re)calculates its attributes on existing frames. + @cindex override spec @r{(for a face)} The argument @var{spec-type} determines which spec to set. If it is @code{nil} or @code{face-override-spec}, this function sets the @dfn{override spec}, which overrides over all other face specs on -@var{face}. If it is @code{face-defface-spec}, this function sets the -default face spec (the same one set by @code{defface}). If it is -@code{reset}, this function clears out all customization specs and -override specs from @var{face} (in this case, the value of @var{spec} -is ignored). Any other value of @var{spec-type} is reserved for -internal use. +@var{face}. If it is @code{customized-face} or @code{saved-face}, +this function sets the customized spec or the saved custom spec. If +it is @code{face-defface-spec}, this function sets the default face +spec (the same one set by @code{defface}). If it is @code{reset}, +this function clears out all customization specs and override specs +from @var{face} (in this case, the value of @var{spec} is ignored). +Any other value of @var{spec-type} is reserved for internal use. @end defun @node Attribute Functions @subsection Face Attribute Functions +@cindex face attributes, access and modification This section describes functions for directly accessing and modifying the attributes of a named face. @@ -2381,6 +2551,7 @@ For example, @end example @end defun +@c FIXME: Add an index for "relative face attribute", maybe here? --xfq @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 @@ -2544,6 +2715,8 @@ a non-@code{nil} @code{:inverse-video} attribute. @node Displaying Faces @subsection Displaying Faces +@cindex displaying faces +@cindex face merging When Emacs displays a given piece of text, the visual appearance of the text may be determined by faces drawn from different sources. If @@ -2565,8 +2738,8 @@ Manual}. @item If the text lies within an overlay with a non-@code{nil} @code{face} property, Emacs applies the face(s) specified by that property. If -the overlay has a @code{mouse-face} property and the mouse is ``near -enough'' to the overlay, Emacs applies the face or face attributes +the overlay has a @code{mouse-face} property and the mouse is near +enough to the overlay, Emacs applies the face or face attributes specified by the @code{mouse-face} property instead. @xref{Overlay Properties}. @@ -2599,6 +2772,7 @@ at the next level of face merging. @node Face Remapping @subsection Face Remapping +@cindex face remapping The variable @code{face-remapping-alist} is used for buffer-local or global changes in the appearance of a face. For instance, it is used @@ -2639,12 +2813,14 @@ then the new definition of the @code{mode-line} face inherits from the @code{mode-line} face. @end defvar +@cindex relative remapping, faces +@cindex base remapping, faces The following functions implement a higher-level interface to @code{face-remapping-alist}. Most Lisp code should use these functions instead of setting @code{face-remapping-alist} directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make -@code{face-remapping-alist} buffer-local as a side-effect. They manage +@code{face-remapping-alist} buffer-local as a side-effect. They manage @code{face-remapping-alist} entries of the form @example @@ -2664,21 +2840,21 @@ and @code{face-remap-reset-base} functions; it is intended for major modes to remap faces in the buffers they control. @defun face-remap-add-relative face &rest specs -This functions adds the face spec in @var{specs} as relative +This function adds the face spec in @var{specs} as relative remappings for face @var{face} in the current buffer. The remaining arguments, @var{specs}, should form either a list of face names, or a property list of attribute/value pairs. -The return value is a Lisp object that serves as a ``cookie''; you can +The return value is a Lisp object that serves as a cookie; you can pass this object as an argument to @code{face-remap-remove-relative} if you need to remove the remapping later. @example -;; Remap the `escape-glyph' face into a combination -;; of the `highlight' and `italic' faces: +;; Remap the 'escape-glyph' face into a combination +;; of the 'highlight' and 'italic' faces: (face-remap-add-relative 'escape-glyph 'highlight 'italic) -;; Increase the size of the `default' face by 50%: +;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example @end defun @@ -2794,12 +2970,13 @@ usually assign faces to around 400 to 600 characters at each call. @node Basic Faces @subsection Basic Faces +@cindex basic faces If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users have customized the basic faces to give Emacs a certain look, your -program will ``fit in'' without additional customization. +program will fit in without additional customization. Some of the basic faces defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces @@ -2824,14 +3001,14 @@ has a bold @code{:weight} attribute), with all other attributes unspecified (and so given by @code{default}). @item shadow -For ``dimmed out'' text. For example, it is used for the ignored +For dimmed-out text. For example, it is used for the ignored part of a filename in the minibuffer (@pxref{Minibuffer File,, Minibuffers for File Names, emacs, The GNU Emacs Manual}). @item link @itemx link-visited For clickable text buttons that send the user to a different -buffer or ``location''. +buffer or location. @item highlight For stretches of text that should temporarily stand out. For example, @@ -2850,6 +3027,8 @@ these are used for messages in @file{*Compilation*} buffers. @node Font Selection @subsection Font Selection +@cindex font selection +@cindex selecting a font Before Emacs can draw a character on a graphical display, it must select a @dfn{font} for that character@footnote{In this context, the @@ -2920,6 +3099,7 @@ other registries given in @var{alternate-registries}, one by one, until it finds a registry that does exist. @end defopt +@cindex scalable fonts Emacs can make use of scalable fonts, but by default it does not use them. @@ -2933,11 +3113,11 @@ 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$")) +(setq scalable-fonts-allowed '("iso10646-1$")) @end example @noindent -allows the use of scalable fonts with registry @code{muleindian-2}. +allows the use of scalable fonts with registry @code{iso10646-1}. @end defopt @defvar face-font-rescale-alist @@ -2957,6 +3137,8 @@ nominal heights and widths would suggest. @node Font Lookup @subsection Looking Up Fonts +@cindex font lookup +@cindex looking up fonts @defun x-list-fonts name &optional reference-face frame maximum width This function returns a list of available font names that match @@ -3014,12 +3196,13 @@ encoding of the font. @node Fontsets @subsection Fontsets +@cindex fontset 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 +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 @@ -3047,7 +3230,7 @@ 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 +is made by altering @var{fontpattern} to indicate the bold and/or italic status. The specification string also says which fonts to use in the fontset. @@ -3110,7 +3293,7 @@ field. @defun set-fontset-font name character font-spec &optional frame add This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. +matching with @var{font-spec} for the specified @var{character}. If @var{name} is @code{nil}, this function modifies the fontset of the selected frame or that of @var{frame} if @var{frame} is not @@ -3119,10 +3302,10 @@ selected frame or that of @var{frame} if @var{frame} is not If @var{name} is @code{t}, 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 character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). +In addition to specifying a single codepoint, @var{character} may be a +cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are +character codepoints. In that case, use @var{font-spec} for all the +characters in the range @var{from} and @var{to} (inclusive). @var{character} may be a charset. In that case, use @var{font-spec} for all character in the charsets. @@ -3130,6 +3313,9 @@ fontset, whose short name is @samp{fontset-default}. @var{character} may be a script name. In that case, use @var{font-spec} for all character in the charsets. +@var{font-spec} may be a font-spec object created by the function +@code{font-spec} (@pxref{Low-Level Font}). + @var{font-spec} 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 @@ -3137,6 +3323,12 @@ foundry name at the head), @var{registry} is a registry name of a font @var{font-spec} may be a font name string. +@var{font-spec} may be @code{nil}, which explicitly specifies that +there's no font for the specified @var{character}. This is useful, +for example, to avoid expensive system-wide search for fonts for +characters that have no glyphs, like those from the Unicode Private +Use Area (PUA). + The optional argument @var{add}, if non-@code{nil}, specifies how to add @var{font-spec} to the font specifications previously set. If it is @code{prepend}, @var{font-spec} is prepended. If it is @@ -3164,6 +3356,7 @@ does that, this function's value may not be accurate. @node Low-Level Font @subsection Low-Level Font Representation +@cindex font property Normally, it is not necessary to manipulate fonts directly. In case you need to do so, this section explains how. @@ -3182,6 +3375,7 @@ should be one of @code{font-object}, @code{font-spec}, or @code{font-entity}. @end defun +@cindex font object A font object is a Lisp object that represents a font that Emacs has @dfn{opened}. Font objects cannot be modified in Lisp, but they can be inspected. @@ -3195,6 +3389,7 @@ otherwise, @var{string} should be a string, and @var{position} specifies a position in that string. @end defun +@cindex font spec A font spec is a Lisp object that contains a set of specifications that can be used to find a font. More than one font may match the specifications in a font spec. @@ -3219,12 +3414,13 @@ These have the same meanings as the face attributes of the same name. @item :size The font size---either a non-negative integer that specifies the pixel -size, or a floating point number that specifies the point size. +size, or a floating-point number that specifies the point size. @item :adstyle Additional typographic style information for the font, such as @samp{sans}. The value should be a string or a symbol. +@cindex font registry @item :registry The charset registry and encoding of the font, such as @samp{iso8859-1}. The value should be a string or a symbol. @@ -3232,11 +3428,21 @@ The charset registry and encoding of the font, such as @item :script The script that the font must support (a symbol). +@item :lang +The language that the font should support. The value should be a +symbol whose name is a two-letter ISO-639 language name. On X, the +value is matched against the ``Additional Style'' field of the XLFD +name of a font, if it is non-empty. On MS-Windows, fonts matching the +spec are required to support codepages needed for the language. +Currently, only a small set of CJK languages is supported with this +property: @samp{ja}, @samp{ko}, and @samp{zh}. + @item :otf +@cindex OpenType font The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form +features, provided Emacs is compiled with a library, such as +@samp{libotf} on GNU/Linux, that supports complex text layout for +scripts which need that. The value must be a list of the form @smallexample @code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} @@ -3259,6 +3465,7 @@ Set the font property @var{property} in the font-spec @var{font-spec} to @var{value}. @end defun +@cindex font entity A font entity is a reference to a font that need not be open. Its properties are intermediate between a font object and a font spec: like a font object, and unlike a font spec, it refers to a single, @@ -3283,13 +3490,13 @@ frame on which the fonts are to be displayed. The optional argument maximum length of the returned list. The optional argument @var{prefer}, if non-@code{nil}, should be another font spec, which is used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font +entities are sorted in order of decreasing closeness to that font spec. @end defun If you call @code{set-face-attribute} and pass a font spec, font entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available +attribute, Emacs opens the best matching font that is available for display. It then stores the corresponding font object as the actual value of the @code{:font} attribute for that face. @@ -3334,6 +3541,124 @@ If the optional argument @var{fold-wildcards} is non-@code{nil}, consecutive wildcards in the XLFD are folded into one. @end defun +The following two functions return important information about a font. + +@defun font-info name &optional frame +This function returns information about a font specified by its +@var{name}, a string, as it is used on @var{frame}. If @var{frame} is +omitted or @code{nil}, it defaults to the selected frame. + +The value returned by the function is a vector of the form +@code{[@var{opened-name} @var{full-name} @var{size} @var{height} +@var{baseline-offset} @var{relative-compose} @var{default-ascent} +@var{max-width} @var{ascent} @var{descent} @var{space-width} +@var{average-width} @var{filename} @var{capability}]}. Here's the +description of each components of this vector: + +@table @var +@item opened-name +The name used to open the font, a string. + +@item full-name +The full name of the font, a string. + +@item size +The pixel size of the font. + +@item height +The height of the font in pixels. + +@item baseline-offset +The offset in pixels from the @acronym{ASCII} baseline, positive +upward. + +@item relative-compose +@itemx default-ascent +Numbers controlling how to compose characters. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +should be equal to the value of @var{height} above. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + +@defun query-font font-object +This function returns information about a @var{font-object}. (This is +in contrast to @code{font-info}, which takes the font name, a string, +as its argument.) + +The value returned by the function is a vector of the form +@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width} +@var{ascent} @var{descent} @var{space-width} @var{average-width} +@var{capability}]}. Here's the description of each components of this +vector: + +@table @var +@item name +The font name, a string. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item pixel-size +The pixel size of the font used to open the font. + +@item max-width +The maximum advance width of the font. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +gives the font height. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + @node Fringes @section Fringes @cindex fringes @@ -3417,6 +3742,7 @@ etc. @defopt indicate-empty-lines @cindex fringes, and empty line indication +@cindex empty lines, indicating 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 @@ -3424,6 +3750,7 @@ buffer-local in every buffer. @end defopt @defopt indicate-buffer-boundaries +@cindex buffer boundaries, indicating This buffer-local variable controls how the buffer boundaries and window scrolling are indicated in the window fringes. @@ -3552,6 +3879,8 @@ See the next subsection for details. @xref{Fringe Bitmaps}. @end ifnottex +@c FIXME: I can't find the fringes-indicator-alist variable. Maybe +@c it should be fringe-indicator-alist or fringe-cursor-alist? --xfq 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 default value of @code{fringes-indicator-alist} is used. @@ -3643,6 +3972,7 @@ If @var{pos} is @code{nil}, that stands for the value of point in @node Customizing Bitmaps @subsection Customizing Fringe Bitmaps +@cindex fringe bitmaps, customizing @defun define-fringe-bitmap bitmap bits &optional height width align This function defines the symbol @var{bitmap} as a new fringe bitmap, @@ -3745,95 +4075,227 @@ 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}. +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). + + The frame parameter @code{horizontal-scroll-bars} controls whether +the windows in the frame have horizontal scroll bars. The frame +parameter @code{scroll-bar-height} specifies how high they are +(@code{nil} meaning the default). @xref{Layout Parameters}. + +@vindex horizontal-scroll-bars-available-p + Horizontal scroll bars are not available on all platforms. The +function @code{horizontal-scroll-bars-available-p} which takes no +argument returns non-@code{nil} if they are available on your system. + + The following three functions take as argument a live frame which +defaults to the selected one. @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. +This function reports the scroll bar types 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 vertical scroll +bar.) @var{horizontal-type} is either @code{bottom} or @code{nil} +(which means no horizontal scroll bar). +@end defun + +@defun frame-scroll-bar-width &optional Lisp_Object &optional frame +This function returns the width of vertical scroll bars of @var{frame} +in pixels. +@end defun - 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 frame-scroll-bar-height &optional Lisp_Object &optional frame +This function returns the height of horizontal scroll bars of +@var{frame} in pixels. +@end defun -@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}. +You can override the frame specific settings for individual windows by +using the following function: -@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. +@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type +This function sets the width and/or height and the types of scroll bars +for window @var{window}. -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. +@var{width} specifies the width of the vertical scroll bar 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}, +@code{t}, which means to use the frame's default, and @code{nil} for no +vertical scroll bar. + +@var{height} specifies the height of the horizontal scroll bar in pixels +(@code{nil} means use the height specified for the frame). +@var{horizontal-type} specifies whether to have a horizontal scroll bar. +The possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no horizontal scroll bar. + +If @var{window} is @code{nil}, the selected window is used. @end defun +The following four functions take as argument a live window which +defaults to the selected one. + @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. +This function returns a list of the form @code{(@var{width} +@var{columns} @var{vertical-type} @var{height} @var{lines} +@var{horizontal-type})}. + +The value @var{width} is the value that was specified for the width of +the vertical scroll bar (which may be @code{nil}); @var{columns} is the +(possibly rounded) number of columns that the vertical scroll bar +actually occupies. + +The value @var{height} is the value that was specified for the height of +the horizontal scroll bar (which may be @code{nil}); @var{lines} is the +(possibly rounded) number of lines that the horizontally scroll bar +actually occupies. +@end defun + +@defun window-current-scroll-bars &optional window +This function reports the scroll bar type for window @var{window}. 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 -@var{horizontal-type} is not actually meaningful. +@defun window-scroll-bar-width &optional window +This function returns the width in pixels of @var{window}'s vertical +scrollbar. +@end defun + +@defun window-scroll-bar-height &optional window +This function returns the height in pixels of @var{window}'s horizontal +scrollbar. @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{vertical-scroll-bar}, @code{horizontal-scroll-bar}, +@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being +displayed control the window's 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} +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. +You can control the appearance of scroll bars for a particular buffer by +setting the following variables which automatically become buffer-local +when set. + +@defvar vertical-scroll-bar +This variable specifies the location of the vertical scroll bar. 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. +@end defvar + +@defvar horizontal-scroll-bar +This variable specifies the location of the horizontal scroll bar. The +possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no scroll bar. +@end defvar + +@defvar scroll-bar-width +This variable specifies the width of the buffer's vertical scroll bars, +measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +@defvar scroll-bar-height +This variable specifies the height of the buffer's horizontal scroll +bar, measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +Finally you can toggle the display of scroll bars on all frames by +customizing the variables @code{scroll-bar-mode} and +@code{horizontal-scroll-bar-mode}. + @defopt 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. +This variable controls whether and where to put vertical scroll bars in +all frames. The possible values are @code{nil} for no scroll bars, +@code{left} to put scroll bars on the left and @code{right} to put +scroll bars on the right. @end defopt -@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. +@defopt horizontal-scroll-bar-mode +This variable controls whether to display horizontal scroll bars on all +frames. +@end defopt + + +@node Window Dividers +@section Window Dividers +@cindex window dividers +@cindex right dividers +@cindex bottom dividers + +Window dividers are bars drawn between a frame's windows. A right +divider is drawn between a window and any adjacent windows on the right. +Its width (thickness) is specified by the frame parameter +@code{right-divider-width}. A bottom divider is drawn between a +window and adjacent windows on the bottom or the echo area. Its width +is specified by the frame parameter @code{bottom-divider-width}. In +either case, specifying a width of zero means to not draw such dividers. +@xref{Layout Parameters}. + + Technically, a right divider belongs to the window on its left, +which means that its width contributes to the total width of that +window. A bottom divider belongs to the window above it, which +means that its width contributes to the total height of that window. +@xref{Window Sizes}. When a window has both, a right and a bottom +divider, the bottom divider prevails. This means that a bottom +divider is drawn over the full total width of its window while the right +divider ends above the bottom divider. + + Dividers can be dragged with the mouse and are therefore useful for +adjusting the sizes of adjacent windows with the mouse. They also serve +to visually set apart adjacent windows when no scroll bars or mode lines +are present. The following three faces allow to customize the +appearance of dividers: + +@table @code +@item window-divider +When a divider is less than three pixels wide, it is drawn solidly with +the foreground of this face. For larger dividers this face is used for +the inner part only, excluding the first and last pixel. + +@item window-divider-first-pixel +This is the face used for drawing the first pixel of a divider that is +at least three pixels wide. To obtain a solid appearance, set this to +the same value used for the @code{window-divider} face. + +@item window-divider-last-pixel +This is the face used for drawing the last pixel of a divider that is at +least three pixels wide. To obtain a solid appearance, set this to the +same value used for the @code{window-divider} face. +@end table + +You can get the sizes of the dividers of a specific window with the +following two functions. + +@defun window-right-divider-width &optional window +Return the width (thickness) in pixels of @var{window}'s right divider. +@var{window} must be a live window and defaults to the selected one. +The return value is always zero for a rightmost window. +@end defun + +@defun window-bottom-divider-width &optional window +Return the width (thickness) in pixels of @var{window}'s bottom divider. +@var{window} must be a live window and defaults to the selected one. +The return value is zero for the minibuffer window or a bottommost +window on a minibuffer-less frame. @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 @@ -3866,6 +4328,7 @@ display specifications and what they mean. @node Replacing Specs @subsection Display Specs That Replace The Text +@cindex replacing display specs Some kinds of display specifications specify something to display instead of the text that has the property. These are called @@ -3878,8 +4341,8 @@ display specification, the first overrides the rest. Replacing display specifications make most other display specifications irrelevant, since those don't apply to the replacement. - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same + For replacing display specifications, @dfn{the text that has the +property} means all the consecutive characters that have the same Lisp object as their @code{display} property; these characters are replaced as a single unit. If two characters have different Lisp objects as their @code{display} properties (i.e., objects which are @@ -3925,7 +4388,7 @@ 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 +If @var{width} is a 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}). @@ -3933,8 +4396,10 @@ width. @var{width} can also be a @dfn{pixel width} 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}. +same @code{display} property. The space width is the pixel width of +that character, multiplied by @var{factor}. (On text-mode terminals, +the ``pixel width'' of a character is usually 1, but it could be more +for TABs and double-width CJK characters.) @item :align-to @var{hpos} Specifies that the space should be wide enough to reach @var{hpos}. @@ -3949,7 +4414,7 @@ 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 +If @var{height} is a 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}). @@ -4072,7 +4537,7 @@ 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 +slice. Integers 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. @@ -4104,7 +4569,8 @@ 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 +@c FIXME: Add an index for "step"? --xfq +This means to use a font that is @var{n} steps larger. A @dfn{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 @@ -4141,7 +4607,7 @@ 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 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, @@ -4189,13 +4655,15 @@ 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. +This variable specifies the width of the left margin, in character +cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers. +A value of @code{nil} means no left marginal area. @end defvar @defvar right-margin-width -This variable specifies the width of the right margin. -It is buffer-local in all buffers. +This variable specifies the width of the right margin, in character +cell units. It is buffer-local in all buffers. A value of @code{nil} +means no right marginal area. @end defvar Setting these variables does not immediately affect the window. These @@ -4206,15 +4674,18 @@ Thus, you can make changes take effect by calling 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}). +This function specifies the margin widths for window @var{window}, in +character cell units. 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. +This function returns the width of the left and right margins of +@var{window} as a cons cell of the form @w{@code{(@var{left} +. @var{right})}}. If one of the two marginal areas does not exist, +its width is returned as @code{nil}; if neither of the two margins exist, +the function returns @code{(nil)}. If @var{window} is @code{nil}, the +selected window is used. @end defun @node Images @@ -4306,7 +4777,7 @@ functions to insert images into buffers. Each image descriptor has the form @code{(image . @var{props})}, where @var{props} is a property list of alternating keyword symbols -and values, including at least the pair @code{:type @var{TYPE}} which +and values, including at least the pair @code{:type @var{type}} that specifies the image type. The following is a list of properties that are meaningful for all @@ -4376,9 +4847,10 @@ which algorithm. 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. +disabled button. @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) +@cindex edge detection, images 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 @@ -4440,7 +4912,7 @@ $$\pmatrix{ 2 & -1 & 0 \cr @end ifnottex @item disabled -Specifies transforming the image so that it looks ``disabled''. +Specifies transforming the image so that it looks disabled. @end table @item :mask @var{mask} @@ -4462,6 +4934,7 @@ This specifies the pointer shape when the mouse pointer is over this image. @xref{Pointer Shape}, for available pointer shapes. @item :map @var{map} +@cindex image maps This associates an image map of @dfn{hot spots} with this image. An image map is an alist where each element has the format @@ -4639,6 +5112,16 @@ should never be rendered using ImageMagick, regardless of the value of ImageMagick entirely. @end defopt +@defvar image-format-suffixes +This variable is an alist mapping image types to file name extensions. +Emacs uses this in conjunction with the @code{:format} image property +(see below) to give a hint to the ImageMagick library as to the type +of an image. Each element has the form @code{(@var{type} +@var{extension})}, where @var{type} is a symbol specifying an image +content-type, and @var{extension} is a string that specifies the +associated file name extension. +@end defvar + Images loaded with ImageMagick support the following additional image descriptor properties: @@ -4649,13 +5132,13 @@ color, which is used as the image's background color if the image supports transparency. If the value is @code{nil}, it defaults to the frame's background color. -@item :width, :height +@item :width @var{width}, :height @var{height} The @code{:width} and @code{:height} keywords are used for scaling the image. If only one of them is specified, the other one will be calculated so as to preserve the aspect ratio. If both are specified, aspect ratio may not be preserved. -@item :max-width, :max-height +@item :max-width @var{max-width}, :max-height @var{max-height} The @code{:max-width} and @code{:max-height} keywords are used for scaling if the size of the image of the image exceeds these values. If @code{:width} is set it will have precedence over @code{max-width}, @@ -4664,18 +5147,16 @@ and if @code{:height} is set it will have precedence over wish. @code{:max-width} and @code{:max-height} will always preserve the aspect ratio. -@item :format -ImageMagick tries to auto-detect the image type, but it isn't always -able to. By using @code{:format-type}, we can give ImageMagick a hint -to try to help it. It's used in conjunction with the -@code{image-format-suffixes} variable, which provides a mapping from -content types to file name suffixes. This is then given to -ImageMagick as a file name hint. +@item :format @var{type} +The value, @var{type}, should be a symbol specifying the type of the +image data, as found in @code{image-format-suffixes}. This is used +when the image does not have an associated file name, to provide a +hint to ImageMagick to help it detect the image type. -@item :rotation +@item :rotation @var{angle} Specifies a rotation angle in degrees. -@item :index +@item :index @var{frame} @c Doesn't work: http://debbugs.gnu.org/7978 @xref{Multi-Frame Images}. @end table @@ -4726,6 +5207,7 @@ Supports the @code{:index} property. @xref{Multi-Frame Images}. @node Defining Images @subsection Defining Images +@cindex define image The functions @code{create-image}, @code{defimage} and @code{find-image} provide convenient ways to create image descriptors. @@ -4744,6 +5226,7 @@ from the file's name. The remaining arguments, @var{props}, specify additional image properties---for example, +@c ':heuristic-mask' is not documented? @example (create-image "foo.xpm" 'xpm nil :heuristic-mask t) @end example @@ -4787,7 +5270,7 @@ 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 +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 @@ -4852,6 +5335,7 @@ Here is an example of using @code{image-load-path-for-library}: @node Showing Images @subsection Showing Images +@cindex show image You can use an image descriptor by setting up the @code{display} property yourself, but it is easier to use the functions in this @@ -4876,7 +5360,7 @@ The argument @var{slice} specifies a slice of the image to insert. If 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 +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. @@ -4892,8 +5376,8 @@ 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. -If an image is inserted ``sliced'', Emacs displays each slice as a -separate image, and allow more intuitive scrolling up/down, instead of +Emacs displays each slice as a +separate image, and allows more intuitive scrolling up/down, instead of jumping up/down the entire image when paging through a buffer that displays (large) images. @end defun @@ -4930,14 +5414,14 @@ This removes only images that were put into @var{buffer} the way @end defun @defun image-size spec &optional pixels frame +@cindex size of image 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}). +specification. @var{pixels} non-@code{nil} means return sizes measured +in pixels, otherwise return sizes measured in the default character size +of @var{frame} (@pxref{Frame 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 @@ -4946,8 +5430,8 @@ 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 +image height and width, measured in pixels. If it is floating +point, 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. @@ -4955,11 +5439,12 @@ 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}). +@code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar @node Multi-Frame Images @subsection Multi-Frame Images +@cindex multi-frame images @cindex animation @cindex image animation @@ -4969,7 +5454,7 @@ are multiple ``frames'' in the image. At present, Emacs supports multiple frames for GIF, TIFF, and certain ImageMagick formats such as DJVM@. -The frames can be used either to represent multiple ``pages'' (this is +The frames can be used either to represent multiple pages (this is usually the case with multi-frame TIFF files, for example), or to create animation (usually the case with multi-frame GIF files). @@ -5007,6 +5492,8 @@ or @code{nil}, the image animates once only; if @code{t} it loops forever; if a number animation stops after that many seconds. @end defun +@vindex image-minimum-frame-delay +@vindex image-default-frame-delay @noindent Animation operates by means of a timer. Note that Emacs imposes a minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds. If the image itself does not specify a delay, Emacs uses @@ -5190,7 +5677,7 @@ 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} (a symbol). +Define a button type called @var{name} (a symbol). 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 @@ -5297,10 +5784,12 @@ 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. +Call @var{button}'s @code{action} property (i.e., invoke the function +that is the value of that property, passing it the single argument +@var{button}). 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 @@ -5341,7 +5830,7 @@ Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. 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' +@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 local keymap in the button's overlay or text properties. Commands that are useful outside the buttons itself, @@ -5351,7 +5840,7 @@ additionally available in the keymap stored in @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 +@code{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click will also activate the @code{push-button} command. @xref{Clickable Text}. @@ -5390,7 +5879,7 @@ is skipped over. Returns the button found. @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 +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. @@ -5407,7 +5896,8 @@ in the search, instead of starting at the next button. 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. +``model--view--controller'' design paradigm. Ewoc means ``Emacs's +Widget for Object Collections''. An @dfn{ewoc} is a structure that organizes information required to construct buffer text that represents certain Lisp data. The buffer @@ -5427,6 +5917,8 @@ The text's start position in the buffer. The header and footer strings. @item +@cindex node, ewoc +@c or "@cindex node, abstract display"? A doubly-linked chain of @dfn{nodes}, each of which contains: @itemize @@ -5451,6 +5943,8 @@ between buffer positions and nodes, move point from one node's textual representation to another, and so forth. @xref{Abstract Display Functions}. +@cindex encapsulation, ewoc +@c or "@cindex encapsulation, abstract display"? 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 @@ -5466,7 +5960,7 @@ new value in its place, like so: @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 +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. @@ -5502,7 +5996,7 @@ 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} +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 @@ -5622,7 +6116,7 @@ Any @var{args} are passed to @var{map-function}. @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 +implement a @dfn{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. @@ -5681,10 +6175,10 @@ The buffer is in Color Components mode." @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'' + 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 +and to finish the selection process, and a keymap to tie it all together conveniently. @smallexample @@ -5758,25 +6252,26 @@ 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. +This variable specifies the number of seconds to keep indicating 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. +assumes that point follows a character with close parenthesis syntax +and applies the appropriate effect 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 () - "Indicate momentarily the start of sexp before point." + "Indicate momentarily the start of parenthesized sexp before point." (interactive) @end group @group @@ -5933,9 +6428,9 @@ display the character @var{c} as those glyphs; @pxref{Glyphs}). @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''. +line. - The display table also has six ``extra slots'' which serve special + The display table also has six @dfn{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. @@ -6046,8 +6541,11 @@ no buffer display table. @defvar standard-display-table The value of this variable is the standard display table, which is used when Emacs is displaying a buffer in a window with neither a -window display table nor a buffer display table defined. Its default -is @code{nil}. +window display table nor a buffer display table defined, or when Emacs +is outputting text to the standard output or error streams. Although its +default is typically @code{nil}, in an interactive session if the +terminal cannot display curved quotes, its default maps curved quotes +to ASCII approximations. @xref{Keys in Documentation}. @end defvar The @file{disp-table} library defines several functions for changing @@ -6057,6 +6555,7 @@ the standard display table. @subsection Glyphs @cindex glyph +@cindex glyph code A @dfn{glyph} is a graphical symbol which occupies a single character position on the screen. Each glyph is represented in Lisp as a @dfn{glyph code}, which specifies a character and optionally a @@ -6146,7 +6645,8 @@ Display a box containing the Unicode codepoint of the character, in hexadecimal notation. @item an @acronym{ASCII} string -Display a box containing that string. +Display a box containing that string. The string should contain at +most 6 @acronym{ASCII} characters. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -6157,7 +6657,8 @@ must be one of the display methods described above. @noindent The @code{thin-space}, @code{empty-box}, @code{hex-code}, and @acronym{ASCII} string display methods are drawn with the -@code{glyphless-char} face. +@code{glyphless-char} face. On text terminals, a box is emulated by +square brackets, @samp{[]}. The char-table has one extra slot, which determines how to display any character that cannot be displayed with any available font, or cannot @@ -6196,7 +6697,7 @@ Non-@acronym{ASCII}, non-printing characters @code{U+0080} to @samp{\230}). @item format-control -Characters of Unicode General Category `Cf', such as @samp{U+200E} +Characters of Unicode General Category [Cf], such as @samp{U+200E} (Left-to-Right Mark), but excluding characters that have graphic images, such as @samp{U+00AD} (Soft Hyphen). @@ -6205,9 +6706,9 @@ Characters for there is no suitable font, or which cannot be encoded by the terminal's coding system. @end table -@c FIXME: this can also be `acronym', but that's not currently +@c FIXME: this can also be 'acronym', but that's not currently @c completely implemented; it applies only to the format-control -@c group, and only works if the acronym is in `char-acronym-table'. +@c group, and only works if the acronym is in 'char-acronym-table'. The @var{method} symbol should be one of @code{zero-width}, @code{thin-space}, @code{empty-box}, or @code{hex-code}. These have the same meanings as in @code{glyphless-char-display}, above. @@ -6243,8 +6744,8 @@ 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 +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 @@ -6281,8 +6782,9 @@ Emacs is displaying the frame on a character-based terminal. This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) +frames, so @code{initial-window-system} is @code{nil}, except on +MS-Windows, where it is still @code{w32}. @xref{Initial Options, +daemon,, emacs, The GNU Emacs Manual}.) @end defvar @defun window-system &optional frame @@ -6300,18 +6802,6 @@ indicator of Emacs capabilities on a given display type. Instead, use @code{display-graphic-p} or any of the other @code{display-*-p} predicates described in @ref{Display Feature Testing}. -@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 - @node Bidirectional Display @section Bidirectional Display @cindex bidirectional display @@ -6332,7 +6822,9 @@ and displaying bidirectional text. @cindex reading order @cindex visual order @cindex unicode bidirectional algorithm +@cindex UBA @cindex bidirectional reordering +@cindex reordering, of bidirectional text Text is stored in Emacs buffers and strings in @dfn{logical} (or @dfn{reading}) order, i.e., the order in which a human would read each character. In right-to-left and bidirectional text, the order in @@ -6343,7 +6835,8 @@ position. In performing this @dfn{bidirectional reordering}, Emacs follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), which is described in Annex #9 of the Unicode standard (@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full -Bidirectionality'' class implementation of the @acronym{UBA}. +Bidirectionality'' class implementation of the @acronym{UBA}, +consistent with the requirements of the Unicode Standard v8.0. @defvar bidi-display-reordering If the value of this buffer-local variable is non-@code{nil} (the @@ -6468,7 +6961,7 @@ The function returns the new buffer position as its value. when two strings with bidirectional content are juxtaposed in a buffer, or otherwise programmatically concatenated into a string of text. A typical problematic case is when a buffer consists of -sequences of text ``fields'' separated by whitespace or punctuation +sequences of text fields separated by whitespace or punctuation characters, like Buffer Menu mode or Rmail Summary Mode. Because the punctuation characters used as separators have @dfn{weak directionality}, they take on the directionality of surrounding text. @@ -6528,3 +7021,81 @@ affect all Emacs frames and windows. appropriate mirrored character in the reordered text. Lisp programs can affect the mirrored display by changing this property. Again, any such changes affect all of Emacs display. + +@cindex overriding bidirectional properties +@cindex directional overrides +@cindex LRO +@cindex RLO + The bidirectional properties of characters can be overridden by +inserting into the text special directional control characters, +LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE +(@acronym{RLO}). Any characters between a @acronym{RLO} and the +following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF}) +control character, whichever comes first, will be displayed as if they +were strong right-to-left characters, i.e.@: they will be reversed on +display. Similarly, any characters between @acronym{LRO} and +@acronym{PDF} or newline will display as if they were strong +left-to-right, and will @emph{not} be reversed even if they are strong +right-to-left characters. + +@cindex phishing using directional overrides +@cindex malicious use of directional overrides + These overrides are useful when you want to make some text +unaffected by the reordering algorithm, and instead directly control +the display order. But they can also be used for malicious purposes, +known as @dfn{phishing}. Specifically, a URL on a Web page or a link +in an email message can be manipulated to make its visual appearance +unrecognizable, or similar to some popular benign location, while the +real location, interpreted by a browser in the logical order, is very +different. + + Emacs provides a primitive that applications can use to detect +instances of text whose bidirectional properties were overridden so as +to make a left-to-right character display as if it were a +right-to-left character, or vise versa. + +@defun bidi-find-overridden-directionality from to &optional object +This function looks at the text of the specified @var{object} between +positions @var{from} (inclusive) and @var{to} (exclusive), and returns +the first position where it finds a strong left-to-right character +whose directional properties were forced to display the character as +right-to-left, or for a strong right-to-left character that was forced +to display as left-to-right. If it finds no such characters in the +specified region of text, it returns @code{nil}. + +The optional argument @var{object} specifies which text to search, and +defaults to the current buffer. If @var{object} is non-@code{nil}, it +can be some other buffer, or it can be a string or a window. If it is +a string, the function searches that string. If it is a window, the +function searches the buffer displayed in that window. If a buffer +whose text you want to examine is displayed in some window, we +recommend to specify it by that window, rather than pass the buffer to +the function. This is because telling the function about the window +allows it to correctly account for window-specific overlays, which +might change the result of the function if some text in the buffer is +covered by overlays. +@end defun + +@cindex copying bidirectional text, preserve visual order +@cindex visual order, preserve when copying bidirectional text + When text that includes mixed right-to-left and left-to-right +characters and bidirectional controls is copied into a different +location, it can change its visual appearance, and also can affect the +visual appearance of the surrounding text at destination. This is +because reordering of bidirectional text specified by the +@acronym{UBA} has non-trivial context-dependent effects both on the +copied text and on the text at copy destination that will surround it. + + Sometimes, a Lisp program may need to preserve the exact visual +appearance of the copied text at destination, and of the text that +surrounds the copy. Lisp programs can use the following function to +achieve that effect. + +@defun buffer-substring-with-bidi-context start end &optional no-properties +This function works similar to @code{buffer-substring} (@pxref{Buffer +Contents}), but it prepends and appends to the copied text bidi +directional control characters necessary to preserve the visual +appearance of the text when it is inserted at another place. Optional +argument @var{no-properties}, if non-@code{nil}, means remove the text +properties from the copy of the text. +@end defun diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 8384c31a380..96bb03b34c0 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1,6 +1,6 @@ @comment -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1992-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @@ -281,6 +281,26 @@ can still stop the program by typing @kbd{S}, or any editing command. 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. +When you enter a new Edebug level, Edebug will normally stop at the +first instrumented function it encounters. If you prefer to stop only +at a break point, or not at all (for example, when gathering coverage +data), change the value of @code{edebug-initial-mode} from its default +@code{step} to @code{go}, or @code{Go-nonstop}, or one of its other +values (@pxref{Edebug Options}). You can do this readily with +@kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}): + +@deffn Command edebug-set-initial-mode +@kindex C-x C-a C-m +This command, bound to @kbd{C-x C-a C-m}, sets +@code{edebug-initial-mode}. It prompts you for a key to indicate the +mode. You should enter one of the eight keys listed above, which sets +the corresponding mode. +@end deffn + +Note that you may reenter the same Edebug level several times if, for +example, an instrumented function is called several times from one +command. + 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 @@ -300,13 +320,6 @@ 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 in @ref{Edebug Options}. -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode} -(@pxref{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 or continue mode. The default is 1 second. @@ -363,7 +376,7 @@ 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} (@code{edebug-where}) to move point there, and then type @kbd{f}. -The @kbd{o} command continues ``out of'' an expression. It places a +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 @@ -875,7 +888,7 @@ lines inserted. frequency. Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' +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 @@ -908,7 +921,7 @@ 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. +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}. @@ -978,14 +991,14 @@ unless @code{edebug-continue-kbd-macro} is non-@code{nil}. @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 +the current window configuration from outside Edebug (@pxref{Window Configurations}). When you exit Edebug, 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. +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. @@ -1563,7 +1576,8 @@ 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}. +The default value is @code{step}. This variable can be set +interactively with @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}). @xref{Edebug Execution Modes}. @end defopt @@ -1605,7 +1619,7 @@ and consider a macro of the form: If you instrument the @code{test} macro and step through it, then by default the result of the @code{symbol-function} call has numerous @code{edebug-after} and @code{edebug-before} forms, which can make it -difficult to see the ``actual'' result. If +difficult to see the actual result. If @code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove these forms from the result. @end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index e05253638d7..b2b3bbc31d3 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename elisp +@setfilename ../../info/elisp.info @ifset VOL1 @set volflag @@ -18,6 +18,7 @@ @ifclear volflag @settitle GNU Emacs Lisp Reference Manual @end ifclear +@include docstyle.texi @c %**end of header @@ -56,7 +57,7 @@ @c (See comments for EDITION in emacs.texi) @set VERSION 3.1 @include emacsver.texi -@set DATE January 2013 +@set DATE October 2014 @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 @@ -98,14 +99,14 @@ This is the @cite{GNU Emacs Lisp Reference Manual} @end ifnottex corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990--1996, 1998--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1990--1996, 1998--2015 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.3 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 +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.'' @@ -115,11 +116,9 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@documentencoding UTF-8 - -@dircategory GNU Emacs Lisp +@dircategory Emacs lisp @direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. +* Elisp: (elisp). The Emacs Lisp Reference Manual. @end direntry @titlepage @@ -194,7 +193,6 @@ To view this manual in other formats, click * 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. @@ -249,9 +247,9 @@ Appendices @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 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. +@c value of 'texinfo-master-menu-header'. See texnfo-upd.el. @detailmenu --- The Detailed Node Listing --- @@ -298,7 +296,7 @@ Lisp Data Types Programming Types * Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. +* 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, @@ -318,6 +316,7 @@ Programming Types * Byte-Code Type:: A function written in Lisp, then compiled. * Autoload Type:: A type used for automatically loading seldom-used functions. +* Finalizer Type:: Runs code when no longer reachable. Character Type @@ -363,7 +362,7 @@ 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. +* 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. @@ -455,7 +454,7 @@ Kinds of Forms 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, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -466,6 +465,7 @@ Control Structures * Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. * Combining Conditions:: @code{and}, @code{or}, @code{not}. * Iteration:: @code{while} loops. +* Generators:: Generic sequences and coroutines. * Nonlocal Exits:: Jumping out of a sequence. Nonlocal Exits @@ -486,7 +486,7 @@ Errors Variables * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. +* Constant Variables:: Variables 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. @@ -600,7 +600,7 @@ Loading * 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. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @@ -615,19 +615,6 @@ Byte Compilation * 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. -* Combined Definition:: How advice is implemented. - Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. @@ -761,11 +748,13 @@ Defining Commands * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Generic Commands:: Select among command alternatives. + Input Events -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. +* 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. @@ -916,6 +905,7 @@ Simple Minded Indentation Engine * SMIE Indentation:: Specifying indentation rules. * SMIE Indentation Helpers:: Helper functions for indentation rules. * SMIE Indentation Example:: Sample indentation rules. +* SMIE Customization:: Customizing indentation. Documentation @@ -952,7 +942,8 @@ 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. +* File Attributes:: File sizes, modification times, etc. +* Extended Attributes:: Extended file attributes for access control. * Locating Files:: How to find a file in standard places. File Names @@ -1000,10 +991,10 @@ Buffers 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". + 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. +* 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 @@ -1017,6 +1008,7 @@ Windows * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Recombining Windows:: Preserving the frame layout when splitting and @@ -1050,6 +1042,7 @@ Frames * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -1073,12 +1066,18 @@ Frames * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal. +Frame Geometry + +* Frame Layout:: Basic layout of frames. +* Frame Font:: The default font of a frame and how to set it. +* Size and Position:: Changing the size and position of a frame. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. + 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 @@ -1119,8 +1118,8 @@ Markers * 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". +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. Text @@ -1150,10 +1149,11 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Transposition:: Swapping two portions of a buffer. +* Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. The Kill Ring @@ -1325,7 +1325,7 @@ Processes Receiving Output from Processes -* Process Buffers:: If no filter, output is put in a buffer. +* Process Buffers:: By default, 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. @@ -1354,18 +1354,19 @@ Emacs Display * 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. +* Size of Displayed Text:: How large displayed text is. * 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. +* Scroll Bars:: Controlling scroll bars. +* Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. * Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. +* Character Display:: How Emacs displays individual characters. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used. * Bidirectional Display:: Display of bidirectional scripts, such as @@ -1400,10 +1401,10 @@ Faces * Attribute Functions:: Functions to examine and set face attributes. * Displaying Faces:: How Emacs combines the faces specified for a character. -* Face Remapping:: Remapping faces to alternative definitions. +* Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. @@ -1493,6 +1494,7 @@ Operating System Interface * Desktop Notifications:: Desktop notifications. * File Notifications:: File notifications. * Dynamic Libraries:: On-demand loading of support libraries. +* Security Considerations:: Running Emacs in an unfriendly environment. Starting Up Emacs @@ -1567,7 +1569,6 @@ Object Internals @include customize.texi @include loading.texi @include compile.texi -@include advice.texi @c This includes edebug.texi. @include debugging.texi diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 8a10fbf0c47..d485b3b6f15 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Errors @@ -157,7 +157,10 @@ The message is @samp{Attempt to modify a protected file}. @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched -parentheses. @xref{List Motion}, and @xref{Parsing Expressions}. +parentheses. Conventionally raised with three argument: a +human-readable error message, the start of the obstacle that cannot be +moved over, and the end of the obstacle. @xref{List Motion}, and +@xref{Parsing Expressions}. @item search-failed The message is @samp{Search failed}. @xref{Searching and Matching}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 4b83d575fef..067dbd2d99f 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1994, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Evaluation @@ -104,9 +104,9 @@ interpretation. @xref{Command Loop}. A Lisp object that is intended to be evaluated is called a @dfn{form} (or an @dfn{expression}). 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. +that are evaluated differently: symbols, lists, and all other +types. This section describes all three kinds, one by one, starting +with the other types, which are self-evaluating forms. @menu * Self-Evaluating Forms:: Forms that evaluate to themselves. @@ -116,7 +116,7 @@ with the ``all other types'' which are self-evaluating forms. 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, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -146,7 +146,7 @@ contents unchanged. @result{} 123 @end group @group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} +(eval '123) ; @r{Evaluated "by hand"---result is the same.} @result{} 123 @end group @group @@ -242,11 +242,9 @@ it obtains a non-symbol. @xref{Function Names}, for more information about symbol function indirection. 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. +event that a symbol's function cell refers to the same symbol. +Otherwise, 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 @@ -255,12 +253,12 @@ 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, Emacs signals an @code{invalid-function} error. - The following example illustrates the symbol indirection process. We -use @code{fset} to set the function cell of a symbol and + 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}. +(@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}. @example @group @@ -440,6 +438,11 @@ begins with @code{lambda} but is not a well-formed @code{lambda} expression, so Emacs may signal an error, or may return 3 or 4 or @code{nil}, or may behave in other ways. +@defun special-form-p object +This predicate tests whether its argument is a special form, and +returns @code{t} if so, @code{nil} otherwise. +@end defun + Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described. @@ -523,7 +526,7 @@ GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and 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 +values). @end quotation @node Autoloading @@ -710,12 +713,18 @@ arguments. @defun eval form &optional lexical This is the basic function for 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}). - -The argument @var{lexical}, if non-@code{nil}, means to evaluate -@var{form} using lexical scoping rules for variables, instead of the -default dynamic scoping rules. @xref{Lexical Binding}. +@var{form} in the current environment, and returns the result. The +type of the @var{form} object determines how it is evaluated. +@xref{Forms}. + +The argument @var{lexical} specifies the scoping rule for local +variables (@pxref{Variable Scoping}). If it is omitted or @code{nil}, +that means to evaluate @var{form} using the default dynamic scoping +rule. If it is @code{t}, that means to use the lexical scoping rule. +The value of @var{lexical} can also be a non-empty alist specifying a +particular @dfn{lexical environment} for lexical bindings; however, +this feature is only useful for specialized purposes, such as in Emacs +Lisp debuggers. @xref{Lexical Binding}. Since @code{eval} is a function, the argument expression that appears in a call to @code{eval} is evaluated twice: once as preparation before @@ -796,7 +805,12 @@ 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. +code can cause stack overflow instead. On some systems, this overflow +can be handled. In that case, normal Lisp evaluation is interrupted +and control is transferred back to the top level command loop +(@code{top-level}). Note that there is no way to enter Emacs Lisp +debugger in this situation. @xref{Error Debugging}. + @cindex Lisp nesting error The depth limit counts internal uses of @code{eval}, @code{apply}, and diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 1f7169522cc..9a1b2cd217f 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1,27 +1,27 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Files @chapter Files This chapter describes the Emacs Lisp functions and variables to -find, create, view, save, and otherwise work with files and file +find, create, view, save, and otherwise work with files and directories. A few other file-related functions 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 +names. A file name is a string. Most of these functions expand file +name arguments using the function @code{expand-file-name}, so that @file{~} is handled correctly, as are relative file names (including -@samp{../}). @xref{File Name Expansion}. +@file{../}). @xref{File Name Expansion}. In addition, certain @dfn{magic} file names are handled specially. For example, when a remote file name is specified, Emacs accesses the -file over the network via an appropriate protocol (@pxref{Remote -Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is +file over the network via an appropriate protocol. @xref{Remote +Files,, Remote Files, emacs, The GNU Emacs Manual}. This handling is done at a very low level, so you may assume that all the functions described in this chapter accept magic file names as file name arguments, except where noted. @xref{Magic File Names}, for details. @@ -55,25 +55,24 @@ to locale @code{system-messages-locale}, and decoded using coding system 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. +file @dfn{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. +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). When a buffer is visiting a file, it contains information +copied from the file. The copy in the buffer is what you modify with +editing commands. Changes to the buffer do not change the file; to +make the changes permanent, you must @dfn{save} the buffer, which +means copying the altered buffer contents back into the file. + + Despite 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. @@ -82,6 +81,8 @@ however, it is good to keep the distinction in mind. @node Visiting Functions @subsection Functions for Visiting Files +@cindex visiting files, functions for +@cindex how to visit files This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with @@ -255,11 +256,16 @@ is permanent local, so it is unaffected by changes of major modes. which are sometimes useful in user Lisp code: @code{create-file-buffer} and @code{after-find-file}. This section explains how to use them. +@c FIXME This does not describe the default behavior, because +@c uniquify is enabled by default and advises this function. +@c This is confusing. uniquify should be folded into the function proper. @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}. +Note that the @file{uniquify} library affects the result of this +function. @xref{Uniquify,,, emacs, The GNU Emacs Manual}. @strong{Please note:} @code{create-file-buffer} does @emph{not} associate the new buffer with a file and does not select the buffer. @@ -417,7 +423,7 @@ To do so, execute the following code: 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}. +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 @@ -507,9 +513,9 @@ Name}). @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. + To copy the contents of a file into a buffer, use the function +@code{insert-file-contents}. (Don't use the 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 @@ -647,8 +653,9 @@ and also calls the functions in the list @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 +@var{filename}} in the echo area. This message is inhibited if +@var{visit} is neither @code{t} nor @code{nil} nor a string, or if +Emacs is operating in batch mode (@pxref{Batch Mode}). This feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn @@ -677,14 +684,15 @@ with-temp-buffer,, The Current Buffer}. 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.) +modified. 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. +stored in the same directory as the file you are editing. (On file +systems that do not support symbolic links, a regular file is used.) When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. +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 @@ -709,22 +717,17 @@ some other job. 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. +file, or is not modified, or if the option @code{create-lockfiles} is +@code{nil}. @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. +does nothing if the current buffer is not visiting a file, or is not locked. @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}. It is also -possible to disable locking, by setting the variable @code{create-lockfiles}. - @defopt create-lockfiles If this variable is @code{nil}, Emacs does not lock files. @end defopt @@ -761,34 +764,31 @@ 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}. +with your own version that makes the decision in another way. @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. + This section describes the functions for retrieving various types of +information about files (or directories or symbolic links), such as +whether a file is readable or writable, and its size. These functions +all take arguments which are file names. Except where noted, these +arguments need to specify existing files, or an error is signaled. @cindex file names, trailing whitespace @cindex trailing blanks in file names -Be careful with file names that end in blanks: some filesystems -(notably, MS-Windows) will ignore trailing whitespace in file names, -and return information about the file after stripping those blanks -from the name, not about the file whose name you passed to the -functions described in this section. + Be careful with file names that end in spaces. On some filesystems +(notably, MS-Windows), trailing whitespace characters in file names +are silently and automatically ignored. @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. +* File Attributes:: File sizes, modification times, etc. +* Extended Attributes:: Extended file attributes for access control. * Locating Files:: How to find a file in standard places. @end menu @@ -797,10 +797,16 @@ functions described in this section. @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). + These functions test for permission to access a file for reading, +writing, or execution. 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). + + On some operating systems, more complex sets of access permissions +can be specified, via mechanisms such as Access Control Lists (ACLs). +@xref{Extended Attributes}, for how to query and set those +permissions. @defun file-exists-p filename This function returns @code{t} if a file named @var{filename} appears @@ -810,9 +816,8 @@ true if the file exists and you have execute permission on the containing directories, regardless of the permissions 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}. +If the file does not exist, or if access control policies prevent you +from finding its attributes, 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 @@ -823,24 +828,8 @@ name only if the target file exists. @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 @@ -856,27 +845,18 @@ 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. +In the 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}; @@ -885,16 +865,13 @@ 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, +For example, from the following we deduce that any attempt to read a +file in @file{/foo/} will give an error: @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 @@ -917,43 +894,65 @@ 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}. +@defun file-modes filename +@cindex mode bits +@cindex file permissions +@cindex permissions, file +@cindex file modes +This function returns the @dfn{mode bits} of @var{filename}---an +integer summarizing its read, write, and execution permissions. +Symbolic links in @var{filename} are recursively followed at all +levels. If the file does not exist, the return value is @code{nil}. -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. +@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} +Manual}, for a description of mode bits. For example, if the +low-order bit is 1, the file is executable by all users; if the +second-lowest-order bit is 1, the file is writable by all users; etc. +The highest possible value is 4095 (7777 octal), meaning that everyone +has read, write, and execute permission, the @acronym{SUID} bit is set +for both others and group, and the sticky bit is set. + +@xref{Changing Files}, for the @code{set-file-modes} function, which +can be used to set these permissions. @example @group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil +(file-modes "~/junk/diffs") + @result{} 492 ; @r{Decimal integer.} @end group @group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t +(format "%o" 492) + @result{} "754" ; @r{Convert to octal.} @end group + @group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t +(set-file-modes "~/junk/diffs" #o666) + @result{} nil @end group + @group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil +$ ls -l diffs +-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs @end group @end example -You can use @code{file-attributes} to get a file's last modification -time as a list of four integers. @xref{File Attributes}. +@cindex MS-DOS and file modes +@cindex file modes and MS-DOS +@strong{MS-DOS note:} On MS-DOS, there is no such thing as an +executable file mode bit. So @code{file-modes} 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 executable. +Directories are also reported as executable, for compatibility with +Unix. These conventions are also followed by @code{file-attributes} +(@pxref{File Attributes}). @end defun @node Kinds of Files @subsection Distinguishing Kinds of Files +@cindex file classification +@cindex classification of file types This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files. @@ -961,22 +960,26 @@ 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} function returns its (non-recursive) link target +as a string. (The link target string is not necessarily the full +absolute file name of the target; determining the full file name that +the link points to is nontrivial, see below.) If the leading +directories of @var{filename} include symbolic links, this function +recursively follows them. + +If the file @var{filename} is not a symbolic link, or does not exist, @code{file-symlink-p} returns @code{nil}. +Here are a few examples of using this function: + @example @group -(file-symlink-p "foo") +(file-symlink-p "not-a-symlink") @result{} nil @end group @group (file-symlink-p "sym-link") - @result{} "foo" + @result{} "not-a-symlink" @end group @group (file-symlink-p "sym-link2") @@ -988,7 +991,39 @@ If the file @var{filename} is not a symbolic link (or there is no such file), @end group @end example -@c !!! file-symlink-p: should show output of ls -l for comparison +Note that in the third example, the function returned @file{sym-link}, +but did not proceed to resolve it, although that file is itself a +symbolic link. This is what we meant by ``non-recursive'' above---the +process of following the symbolic links does not recurse if the link +target is itself a link. + +The string that this function returns is what is recorded in the +symbolic link; it may or may not include any leading directories. +This function does @emph{not} expand the link target to produce a +fully-qualified file name, and in particular does not use the leading +directories, if any, of the @var{filename} argument if the link target +is not an absolute file name. Here's an example: + +@example +@group +(file-symlink-p "/foo/bar/baz") + @result{} "some-file" +@end group +@end example + +@noindent +Here, although @file{/foo/bar/baz} was given as a fully-qualified file +name, the result is not, and in fact does not have any leading +directories at all. And since @file{some-file} might itself be a +symbolic link, you cannot simply prepend leading directories to it, +nor even naively use @code{expand-file-name} (@pxref{File Name +Expansion}) to produce its absolute file name. + +For this reason, this function is seldom useful if you need to +determine more than just the fact that a file is or isn't a symbolic +link. If you actually need the file name of the link target, use +@code{file-chase-links} or @code{file-truename}, described in +@ref{Truenames}. @end defun The next two functions recursively follow symbolic links at @@ -1029,21 +1064,6 @@ a regular file (not a directory, named pipe, terminal, or other I/O device). @end defun -@defun file-equal-p file1 file2 -This function returns @code{t} if the files @var{file1} and -@var{file2} name the same file. If @var{file1} or @var{file2} does -not exist, the return value is unspecified. -@end defun - -@defun file-in-directory-p file dir -This function returns @code{t} if @var{file} is a file in directory -@var{dir}, or in a subdirectory of @var{dir}. It also returns -@code{t} if @var{file} and @var{dir} are the same directory. It -compares the @code{file-truename} values of the two directories -(@pxref{Truenames}). If @var{dir} does not name an existing -directory, the return value is @code{nil}. -@end defun - @node Truenames @subsection Truenames @cindex truename (of file) @@ -1066,14 +1086,14 @@ This function does not expand environment variables. Only 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}. +appearing as a name component, call @code{file-truename} without prior +direct or indirect calls to @code{expand-file-name}. 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 @@ -1102,70 +1122,61 @@ we would have: @result{} "/home/foo/hello" @end example - @xref{Buffer File Name}, for related information. +@defun file-equal-p file1 file2 +This function returns @code{t} if the files @var{file1} and +@var{file2} name the same file. This is similar to comparing their +truenames, except that remote file names are also handled in an +appropriate manner. If @var{file1} or @var{file2} does not exist, the +return value is unspecified. +@end defun + +@defun file-in-directory-p file dir +This function returns @code{t} if @var{file} is a file in directory +@var{dir}, or in a subdirectory of @var{dir}. It also returns +@code{t} if @var{file} and @var{dir} are the same directory. It +compares the truenames of the two directories. If @var{dir} does not +name an existing directory, the return value is @code{nil}. +@end defun @node File Attributes -@subsection Other Information about Files +@subsection File Attributes +@cindex file attributes 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 permissions, the owner and -group numbers, the number of names, the inode number, the size, and -the times of access and modification. +information about a file, including 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 file permissions -@cindex permissions, file -@cindex file attributes -@cindex file modes -This function returns the @dfn{mode bits} describing the @dfn{file -permissions} of @var{filename}, as an integer. It recursively follows -symbolic links in @var{filename} at all levels. If @var{filename} -does not exist, the return value is @code{nil}. +@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}. -@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bits. 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. +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-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} +(file-newer-than-file-p "aug-19" "aug-20") + @result{} nil @end group @group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} +(file-newer-than-file-p "aug-20" "aug-19") + @result{} t @end group - @group -(set-file-modes "~/junk/diffs" #o666) - @result{} nil +(file-newer-than-file-p "aug-19" "no-file") + @result{} t @end group - @group -$ ls -l diffs --rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs +(file-newer-than-file-p "no-file" "aug-19") + @result{} nil @end group @end example - -@xref{Changing Files}, for functions that change file permissions, -such as @code{set-file-modes}. - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS -@strong{MS-DOS note:} On MS-DOS, there is no such thing as an -``executable'' file mode bit. So @code{file-modes} 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 executable. -Directories are also reported as executable, for compatibility with -Unix. These conventions are also followed by @code{file-attributes}, -below. @end defun If the @var{filename} argument to the next two functions is a @@ -1173,31 +1184,6 @@ 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 function returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, 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 rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms 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 @@ -1224,8 +1210,7 @@ links, can be created by using the @code{add-name-to-file} function @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. +not correspond to a named user, the value is a number. @item The file's @acronym{GID}, likewise. @@ -1249,8 +1234,8 @@ its owner and group, and other information recorded in the filesystem for the file, beyond the file's contents. @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. +The size of the file in bytes. This is floating point if the size is +too large to fit in a Lisp integer. @item The file's modes, as a string of ten letters or dashes, @@ -1262,7 +1247,7 @@ An unspecified value, present for backward compatibility. @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 but dividing it by @math{2^16} yields a representable integer, +Lisp but dividing it by @math{2^{16}} yields a representable integer, then the value has the form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 bits. If the inode number is too wide for even that, the value is of the form @@ -1306,10 +1291,10 @@ has only one name (the name @file{files.texi} in the current default directory). @item "lh" -is owned by the user with name "lh". +is owned by the user with name @samp{lh}. @item "users" -is in the group with name "users". +is in the group with name @samp{users}. @item (20614 64019 50040 152000) was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. @@ -1339,52 +1324,99 @@ is on the file-system device whose number is 1014478468. @end table @end defun -@cindex SELinux context - SELinux is a Linux kernel feature which provides more sophisticated -file access controls than ordinary ``Unix-style'' file permissions. -If Emacs has been compiled with SELinux support on a system with -SELinux enabled, you can use the function @code{file-selinux-context} -to retrieve a file's SELinux security context. For the function -@code{set-file-selinux-context}, see @ref{Changing Files}. +@defun file-nlinks filename +This function returns the number of names (i.e., hard links) that +file @var{filename} has. If the file does not exist, 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. -@defun file-selinux-context filename -This function returns the SELinux security context of the file -@var{filename}. This return value is a list of the form -@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements -are the context's user, role, type, and range respectively, as Lisp -strings. See the SELinux documentation for details about what these -actually mean. +@example +@group +$ ls -l foo* +-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo +-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1 +@end group -If the file does not exist or is inaccessible, or if the system does -not support SELinux, or if Emacs was not compiled with SELinux -support, then the return value is @code{(nil nil nil nil)}. +@group +(file-nlinks "foo") + @result{} 2 +@end group +@group +(file-nlinks "doesnt-exist") + @result{} nil +@end group +@end example @end defun +@node Extended Attributes +@subsection Extended File Attributes +@cindex extended file attributes + +On some operating systems, each file can be associated with arbitrary +@dfn{extended file attributes}. At present, Emacs supports querying +and setting two specific sets of extended file attributes: Access +Control Lists (ACLs) and SELinux contexts. These extended file +attributes are used, on some systems, to impose more sophisticated +file access controls than the basic Unix-style permissions +discussed in the previous sections. + @cindex access control list @cindex ACL entries - If Emacs has been compiled with @dfn{ACL} (access control list) -support, you can use the function @code{file-acl} to retrieve a file's -ACL entries. The interface implementation is platform-specific; on -GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on -MS-Windows Emacs emulates the POSIX ACL interface with native file -security APIs. +@cindex SELinux context + A detailed explanation of ACLs and SELinux is beyond the scope of +this manual. For our purposes, each file can be associated with an +@dfn{ACL}, which specifies its properties under an ACL-based file +control system, and/or an @dfn{SELinux context}, which specifies its +properties under the SELinux system. @defun file-acl filename -This function returns the ACL entries of the file @var{filename}. The -return value is a platform-dependent object containing some -representation of the ACL entries. Don't use it for anything except -passing it to the @code{set-file-acl} function (@pxref{Changing Files, -set-file-acl}). +This function returns the ACL for the file @var{filename}. The exact +Lisp representation of the ACL is unspecified (and may change in +future Emacs versions), but it is the same as what @code{set-file-acl} +takes for its @var{acl} argument (@pxref{Changing Files}). -If the file does not exist or is inaccessible, or if Emacs was unable to -determine the ACL entries, then the return value is @code{nil}. The -latter can happen for local files if Emacs was not compiled with ACL -support, or for remote files if the file handler returns nil for the -file's ACL entries. +The underlying ACL implementation is platform-specific; on GNU/Linux +and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs +emulates the POSIX ACL interface with native file security APIs. + +If Emacs was not compiled with ACL support, or the file does not exist +or is inaccessible, or Emacs was unable to determine the ACL entries +for any other reason, then the return value is @code{nil}. +@end defun + +@defun file-selinux-context filename +This function returns the SELinux context of the file @var{filename}, +as a list of the form @code{(@var{user} @var{role} @var{type} +@var{range})}. The list elements are the context's user, role, type, +and range respectively, as Lisp strings; see the SELinux documentation +for details about what these actually mean. The return value has the +same form as what @code{set-file-selinux-context} takes for its +@var{context} argument (@pxref{Changing Files}). + +If Emacs was not compiled with SELinux support, or the file does not +exist or is inaccessible, or if the system does not support SELinux, +then the return value is @code{(nil nil nil nil)}. +@end defun + +@defun file-extended-attributes filename +This function returns an alist of the Emacs-recognized extended +attributes of file @var{filename}. Currently, it serves as a +convenient way to retrieve both the ACL and SELinux context; you can +then call the function @code{set-file-extended-attributes}, with the +returned alist as its second argument, to apply the same file access +attributes to another file (@pxref{Changing Files}). + +One of the elements is @code{(acl . @var{acl})}, where @var{acl} has +the same form returned by @code{file-acl}. + +Another element is @code{(selinux-context . @var{context})}, where +@var{context} is the SELinux context, in the same form returned by +@code{file-selinux-context}. @end defun @node Locating Files -@subsection How to Locate Files in Standard Places +@subsection Locating Files in Standard Places @cindex locate file in path @cindex find file in path @@ -1449,7 +1481,10 @@ in @code{exec-path}, and tries all the file-name extensions in @cindex setting modes of files The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. +the modes (permissions) of files. They all signal a @code{file-error} +error if they fail to perform their function, reporting the +system-dependent error message that describes the reason for the +failure. 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 @@ -1477,8 +1512,8 @@ replaces it with its (recursive) target. @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}. +@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}. @@ -1550,7 +1585,7 @@ 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 preserve-selinux +@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-extended-attributes 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, @@ -1563,8 +1598,6 @@ some operating systems.) If setting the time gets an error, 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 @@ -1572,10 +1605,16 @@ 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. -If the optional argument @var{preserve-extended-attributes} is -non-@code{nil}, and Emacs has been built with the appropriate support, -this function attempts to copy the file's extended attributes, such as -its SELinux context and ACL entries (@pxref{File Attributes}). +If the optional argument @var{preserve-permissions} is non-@code{nil}, +this function copies the file modes (or ``permissions'') of +@var{oldname} to @var{newname}, as well as the Access Control List and +SELinux context (if any). @xref{Information about Files}. + +Otherwise, the file modes of @var{newname} are left unchanged if it is +an existing file, and set to those of @var{oldname}, masked by the +default file permissions (see @code{set-default-file-modes} below), if +@var{newname} is to be newly created. The Access Control List or +SELinux context are not copied over in either case. @end deffn @deffn Command make-symbolic-link filename newname &optional ok-if-exists @@ -1617,7 +1656,7 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}. @cindex permissions, file @cindex file modes, setting @deffn Command set-file-modes filename mode -This function sets the @dfn{file mode} (or @dfn{file permissions}) of +This function sets the @dfn{file mode} (or @dfn{permissions}) of @var{filename} to @var{mode}. It recursively follows symbolic links at all levels for @var{filename}. @@ -1646,13 +1685,12 @@ returns the permissions of a file. @defun set-default-file-modes mode @cindex umask -This function sets the default file permissions for new files created -by Emacs and its subprocesses. Every file created with Emacs -initially has these permissions, or a subset of them -(@code{write-region} will not grant execute permissions even if the -default file permissions allow execution). On Unix and GNU/Linux, the -default permissions are given by the bitwise complement of the -``umask'' value. +This function sets the default permissions for new files created by +Emacs and its subprocesses. Every file created with Emacs initially +has these permissions, or a subset of them (@code{write-region} will +not grant execute permissions even if the default file permissions +allow execution). On Unix and GNU/Linux, the default permissions are +given by the bitwise complement of the @samp{umask} value. The argument @var{mode} should be an integer which specifies the permissions, similar to @code{set-file-modes} above. Only the lowest @@ -1663,6 +1701,16 @@ version of an existing file; saving a file preserves its existing permissions. @end defun +@defmac with-file-modes mode body@dots{} +This macro evaluates the @var{body} forms with the default +permissions for new files temporarily set to @var{modes} (whose value +is as for @code{set-file-modes} above). When finished, it restores +the original default file permissions, and returns the value of the +last form in @var{body}. + +This is useful for creating private files, for example. +@end defmac + @defun default-file-modes This function returns the default file permissions, as an integer. @end defun @@ -1691,7 +1739,7 @@ specifications. @defun file-modes-symbolic-to-number modes &optional base-modes This function converts a symbolic file mode specification in -@var{modes} into the equivalent integer value. If the symbolic +@var{modes} into the equivalent integer. If the symbolic specification is based on an existing file, that file's mode bits are taken from the optional argument @var{base-modes}; if that argument is omitted or @code{nil}, it defaults to 0, i.e., no access rights at @@ -1706,25 +1754,33 @@ time and must be in the format returned by @code{current-time} (@pxref{Time of Day}). @end defun +@defun set-file-extended-attributes filename attribute-alist +This function sets the Emacs-recognized extended file attributes for +@code{filename}. The second argument @var{attribute-alist} should be +an alist of the same form returned by @code{file-extended-attributes}. +The return value is @code{t} if the attributes are successfully set, +otherwise it is @code{nil}. +@xref{Extended Attributes}. +@end defun + @defun set-file-selinux-context filename context -This function sets the SELinux security context of the file -@var{filename} to @var{context}. @xref{File Attributes}, for a brief -description of SELinux contexts. The @var{context} argument should be -a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the -return value of @code{file-selinux-context}. The function returns -@code{t} if it succeeds to set the SELinux security context of -@var{filename}, @code{nil} otherwise. The function does nothing and -returns @code{nil} if SELinux is disabled, or if Emacs was compiled -without SELinux support. -@end defun - -@defun set-file-acl filename acl-string -This function sets the ACL entries of the file @var{filename} to -@var{acl-string}. @xref{File Attributes}, for a brief description of -ACLs. The @var{acl-string} argument should be a string containing the -textual representation of the desired ACL entries as returned by -@code{file-acl} (@pxref{File Attributes, file-acl}). The function -returns @code{t} if it succeeds to set the ACL entries of +This function sets the SELinux security context for @var{filename} to +@var{context}. The @var{context} argument should be a list +@code{(@var{user} @var{role} @var{type} @var{range})}, where each +element is a string. @xref{Extended Attributes}. + +The function returns @code{t} if it succeeds in setting the SELinux +context of @var{filename}. It returns @code{nil} if the context was +not set (e.g., if SELinux is disabled, or if Emacs was compiled +without SELinux support). +@end defun + +@defun set-file-acl filename acl +This function sets the Access Control List for @var{filename} to +@var{acl}. The @var{acl} argument should have the same form returned +by the function @code{file-acl}. @xref{Extended Attributes}. + +The function returns @code{t} if it successfully sets the ACL of @var{filename}, @code{nil} otherwise. @end defun @@ -1857,7 +1913,7 @@ return value, but backup version numbers are kept. @end defun @defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, +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 follows the last @samp{.} in the last name component (minus any @@ -1867,7 +1923,7 @@ 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 +extension. Thus, @file{.emacs}'s extension is @code{nil}, not @samp{.emacs}. If @var{period} is non-@code{nil}, then the returned value includes @@ -1974,35 +2030,43 @@ form. @end example @end defun +@defun directory-name-p filename +This function returns non-@code{nil} if @var{filename} ends with a +forward slash (@samp{/}) character. +@end defun + @node Directory Names @subsection Directory Names @cindex directory name +@cindex directory file 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 -the relationship is more complicated. - - The difference between a directory name and its name as a file is +actually a kind of file, so it has a file name (called the +@dfn{directory 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 +file name lacks that slash. On MS-DOS the relationship is more +complicated. + + The difference between directory name and directory file name 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 +described as being a directory name, a directory file name 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{..}. + The following two functions convert between directory names and +directory 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). +that the operating system will interpret as the name of a directory (a +directory name). On most systems, this means appending a slash to the +string (if it does not already end in one). @example @group @@ -2013,10 +2077,10 @@ already end in one). @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. +This function returns a string representing @var{dirname} in a form +that the operating system will interpret as the name of a file (a +directory file name). On most systems, this means removing the final +slash (or backslash) from the string. @example @group @@ -2058,6 +2122,13 @@ Don't try concatenating a slash by hand, as in because this is not portable. Always use @code{file-name-as-directory}. + To avoid the issues mentioned above, or if the @var{dirname} value +might be nil (for example, from an element of @code{load-path}), use: + +@example +(expand-file-name @var{relfile} @var{dirname}) +@end example + To convert a directory name to its abbreviation, use this function: @@ -2142,7 +2213,7 @@ In some cases, a leading @samp{..} component can remain in the output: @noindent This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, +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 @@ -2201,7 +2272,7 @@ 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 +converted to @samp{$}; this gives the user a way to quote a @samp{$}. The environment variable name is the series of alphanumeric characters @@ -2249,6 +2320,8 @@ through the immediately preceding @samp{/}). @node Unique File Names @subsection Generating Unique File Names +@cindex unique file names +@cindex temporary files Some programs need to write temporary files. Here is the usual way to construct a name for such a file: @@ -2378,7 +2451,7 @@ buffer's default directory is prepended to @var{directory}, if 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 +@file{file.c.~2~}. @example @group @@ -2409,7 +2482,7 @@ function returns @code{t}. The function returns @code{nil} if directory 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 +@file{file.c.~2~}. @example @group @@ -2438,7 +2511,7 @@ has five files whose names begin with @samp{f}: @file{foo}, @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 +on @code{file-name-all-completions}. A typical value might look like this: @@ -2559,6 +2632,14 @@ An error is signaled if @var{directory} is not the name of a directory that can be read. @end defun +@defun directory-files-recursively directory match &optional include-directories +Return all files under @var{directory} whose file names match +@var{match} recursively. The file names are returned depth first, +meaning that contents of sub-directories are returned before contents +of the directories. If @var{include-directories} is non-@code{nil}, +also return directory names that have matching names. +@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 @@ -2788,6 +2869,7 @@ first, before handlers for jobs such as remote file access. @code{file-name-nondirectory}, @code{file-name-sans-versions}, @code{file-newer-than-file-p}, @code{file-notify-add-watch}, @code{file-notify-rm-watch}, +@code{file-notify-valid-p}, @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, @@ -2841,6 +2923,7 @@ first, before handlers for jobs such as remote file access. @code{file-name-nondirec@discretionary{}{}{}tory}, @code{file-name-sans-versions}, @code{file-newer-than-file-p}, @code{file-notify-add-watch}, @code{file-notify-rm-watch}, +@code{file-notify-valid-p}, @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, @@ -2877,7 +2960,7 @@ unlocking the buffer if it is locked. 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 +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 @@ -2910,7 +2993,7 @@ each have handlers. 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 +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} @@ -2998,12 +3081,12 @@ 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. If @var{filename} is not accessible -from a local process, then the file name handler should indicate it by -returning @code{nil}. +This function returns the name of a directory that is not magic. For +a non-magic @var{filename} it returns the corresponding directory name +(@pxref{Directory Names}). For a magic @var{filename}, it invokes the +file name handler, which therefore decides what value to return. If +@var{filename} is not accessible from a local process, then the file +name handler should indicate that by returning @code{nil}. This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function @@ -3286,8 +3369,8 @@ 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 +@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 @@ -3340,8 +3423,8 @@ 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 +@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 diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 370098c8b62..3ae33082fc4 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Frames @@ -80,6 +80,7 @@ for @code{framep} above. @menu * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -106,6 +107,7 @@ for @code{framep} above. @node Creating Frames @section Creating Frames +@cindex frame creation To create a new frame, call the function @code{make-frame}. @@ -131,6 +133,13 @@ applies any parameters listed in @code{frame-inherited-parameters} (see below) and not present in the argument, taking the values from the frame that was selected when @code{make-frame} was called. +Note that on multi-monitor displays (@pxref{Multiple Terminals}), the +window manager might position the frame differently than specified by +the positional parameters in @var{alist} (@pxref{Position +Parameters}). For example, some window managers have a policy of +displaying the frame on the monitor that contains the largest part of +the window (a.k.a.@: the @dfn{dominating} monitor). + This function itself does not make the new frame the selected frame. @xref{Input Focus}. The previously selected frame remains selected. On graphical terminals, however, the windowing system may select the @@ -253,30 +262,40 @@ variable, or by the @samp{--display} option (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). Emacs can connect to other X displays via the command @code{make-frame-on-display}. Each X display has its own selected frame and its own minibuffer windows; however, only one -of those frames is ``@emph{the} selected frame'' at any given moment +of those frames is @emph{the} selected frame at any given moment (@pxref{Input Focus}). Emacs can even connect to other text terminals, by interacting with the @command{emacsclient} program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@cindex X display names +@cindex display name on X A single X server can handle more than one display. Each X display -has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. -The first two parts, @var{host} and @var{server}, identify the X -server; the third part, @var{screen}, identifies a screen number on -that X server. When you use two or more screens belonging to one -server, Emacs knows by the similarity in their names that they share a -single keyboard. - - On some ``multi-monitor'' setups, a single X display outputs to more -than one physical monitor. Currently, there is no way for Emacs to -distinguish between the different physical monitors. +has a three-part name, +@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The +first part, @var{hostname}, specifies the name of the machine to which +the display is physically connected. The second part, +@var{displaynumber}, is a zero-based number that identifies one or +more monitors connected to that machine that share a common keyboard +and pointing device (mouse, tablet, etc.). The third part, +@var{screennumber}, identifies a zero-based screen number (a separate +monitor) that is part of a single monitor collection on that X server. +When you use two or more screens belonging to one server, Emacs knows +by the similarity in their names that they share a single keyboard. + + Systems that don't use the X window system, such as MS-Windows, +don't support the notion of X displays, and have only one display on +each host. The display name on these systems doesn't follow the above +3-part format; for example, the display name on MS-Windows systems is +a constant string @samp{w32}, and exists for compatibility, so that +you could pass it to functions that expect a display name. @deffn Command make-frame-on-display display &optional parameters This function creates and returns a new frame on @var{display}, taking the other frame parameters from the alist @var{parameters}. @var{display} should be the name of an X display (a string). -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X +Before creating the frame, this function ensures that Emacs is set +up to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text terminal), it does so at this time. In all other respects, this function behaves like @code{make-frame} (@pxref{Creating Frames}). @@ -316,6 +335,627 @@ you can do this, you must first delete all the frames that were open on that display (@pxref{Deleting Frames}). @end defun +@cindex multi-monitor + On some multi-monitor setups, a single X display outputs to more +than one physical monitor. You can use the functions +@code{display-monitor-attributes-list} and @code{frame-monitor-attributes} +to obtain information about such setups. + +@defun display-monitor-attributes-list &optional display +This function returns a list of physical monitor attributes on +@var{display}, which can be a display name (a string), a terminal, or +a frame; if omitted or @code{nil}, it defaults to the selected frame's +display. Each element of the list is an association list, +representing the attributes of a physical monitor. The first element +corresponds to the primary monitor. The attribute keys and values +are: + +@table @samp +@item geometry +Position of the top-left corner of the monitor's screen and its size, +in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note +that, if the monitor is not the primary monitor, some of the +coordinates might be negative. + +@item workarea +Position of the top-left corner and size of the work area (usable +space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}. +This may be different from @samp{geometry} in that space occupied by +various window manager features (docks, taskbars, etc.)@: may be +excluded from the work area. Whether or not such features actually +subtract from the work area depends on the platform and environment. +Again, if the monitor is not the primary monitor, some of the +coordinates might be negative. + +@item mm-size +Width and height in millimeters as @samp{(@var{width} @var{height})} + +@item frames +List of frames that this physical monitor dominates (see below). + +@item name +Name of the physical monitor as @var{string}. + +@item source +Source of the multi-monitor information as @var{string}; +e.g., @samp{XRandr} or @samp{Xinerama}. +@end table + +@var{x}, @var{y}, @var{width}, and @var{height} are integers. +@samp{name} and @samp{source} may be absent. + +A frame is @dfn{dominated} by a physical monitor when either the +largest area of the frame resides in that monitor, or (if the frame +does not intersect any physical monitors) that monitor is the closest +to the frame. Every (non-tooltip) frame (whether visible or not) in a +graphical display is dominated by exactly one physical monitor at a +time, though the frame can span multiple (or no) physical monitors. + +Here's an example of the data produced by this function on a 2-monitor +display: + +@lisp + (display-monitor-attributes-list) + @result{} + (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor} + (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height} + (mm-size 677 381) + (name . "DISPLAY1") + (frames #<frame emacs@@host *Messages* 0x11578c0> + #<frame emacs@@host *scratch* 0x114b838>)) + ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor} + (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used} + (mm-size 593 370) + (name . "DISPLAY2") + (frames))) +@end lisp + +@end defun + +@defun frame-monitor-attributes &optional frame +This function returns the attributes of the physical monitor +dominating (see above) @var{frame}, which defaults to the selected frame. +@end defun + + +@node Frame Geometry +@section Frame Geometry +@cindex frame geometry +@cindex frame position +@cindex position of frame +@cindex frame size +@cindex size of frame + +The geometry of a frame depends on the toolkit that was used to build +this instance of Emacs and the terminal that displays the frame. This +chapter describes these dependencies and some of the functions to deal +with them. Note that the @var{frame} argument of all of these functions +has to specify a live frame (@pxref{Deleting Frames}). If omitted or +@code{nil}, it specifies the selected frame (@pxref{Input Focus}). + +@menu +* Frame Layout:: Basic layout of frames. +* Frame Font:: The default font of a frame and how to set it. +* Size and Position:: Changing the size and position of a frame. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. +@end menu + + +@node Frame Layout +@subsection Frame Layout +@cindex frame layout +@cindex layout of frame + +The drawing below sketches the layout of a frame on a graphical +terminal: +@smallexample +@group + + <------------ Outer Frame Width -----------> + ___________________________________________ + ^(0) ___________ External Border __________ | + | | |_____________ Title Bar ______________| | + | | (1)_____________ Menu Bar ______________| | ^ + | | (2)_____________ Tool Bar ______________| | ^ + | | (3) _________ Internal Border ________ | | ^ + | | | | ^ | | | | + | | | | | | | | | +Outer | | | Inner | | | Native +Frame | | | Frame | | | Frame +Height | | | Height | | | Height + | | | | | | | | | + | | | |<--+--- Inner Frame Width ------->| | | | + | | | | | | | | | + | | | |___v______________________________| | | | + | | |___________ Internal Border __________| | v + v |______________ External Border _____________| + <-------- Native Frame Width --------> + +@end group +@end smallexample + +In practice not all of the areas shown in the drawing will or may be +present. The meaning of these areas is: + +@table @samp +@item Outer Frame +@cindex outer frame +@cindex outer edges +@cindex outer width +@cindex outer height +The @dfn{outer frame} is a rectangle comprising all areas shown in the +drawing. The edges of that rectangle are called the @dfn{outer edges} +of the frame. The @dfn{outer width} and @dfn{outer height} of the frame +specify the size of that rectangle. + +@cindex outer position +The upper left corner of the outer frame (indicated by @samp{(0)} in the +drawing above) is the @dfn{outer position} or the frame. It is +specified by and settable via the @code{left} and @code{top} frame +parameters (@pxref{Position Parameters}) as well as the functions +@code{frame-position} and @code{set-frame-position} (@pxref{Size and +Position}). + +@item External Border +@cindex external border +The @dfn{external border} is part of the decorations supplied by the +window manager. It's typically used for resizing the frame with the +mouse. The external border is normally not shown on ``fullboth'' and +maximized frames (@pxref{Size Parameters}) and doesn't exist for text +terminal frames. + + The external border should not be confused with the @dfn{outer +border} specified by the @code{border-width} frame parameter +(@pxref{Layout Parameters}). Since the outer border is usually ignored +on most platforms it is not covered here. + +@item Title Bar +@cindex title bar +The @dfn{title bar} is also part of the window manager's decorations and +typically displays the title of the frame (@pxref{Frame Titles}) as well +as buttons for minimizing, maximizing and deleting the frame. The title +bar is usually not displayed on fullboth (@pxref{Size Parameters}) +or tooltip frames. Title bars don't exist for text terminal frames. + +@item Menu Bar +@cindex internal menu bar +@cindex external menu bar +The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs +itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid, +Motif and Windows) rely on an external menu bar. NS also uses an +external menu bar which, however, is not part of the outer frame. +Non-toolkit builds can provide an internal menu bar. On text terminal +frames, the menu bar is part of the frame's root window (@pxref{Windows +and Frames}). + +@item Tool Bar +@cindex internal tool bar +@cindex external tool bar +Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either +internal (drawn by Emacs itself) or external (drawn by a toolkit). The +GTK+ and NS builds have the tool bar drawn by the toolkit. The +remaining builds use internal tool bars. With GTK+ the tool bar can be +located on either side of the frame, immediately outside the internal +border, see below. + +@item Native Frame +@cindex native frame +@cindex native edges +@cindex native width +@cindex native height +@cindex display area +The @dfn{native frame} is a rectangle located entirely within the outer +frame. It excludes the areas occupied by the external border, the title +bar and any external menu or external tool bar. The area enclosed by +the native frame is sometimes also referred to as the @dfn{display area} +of the frame. The edges of the native frame are called the @dfn{native +edges} of the frame. The @dfn{native width} and @dfn{native height} of +the frame specify the size of the rectangle. + +@cindex native position +The top left corner of the native frame specifies the @dfn{native +position} of the frame. (1)--(3) in the drawing above indicate that +position for the various builds: + +@itemize @w +@item (1) non-toolkit and terminal frames + +@item (2) Lucid, Motif and Windows frames + +@item (3) GTK+ and NS frames +@end itemize + +Accordingly, the native height of a frame includes the height of the +tool bar but not that of the menu bar (Lucid, Motif, Windows) or those +of the menu bar and the tool bar (non-toolkit and text terminal frames). + +The native position of a frame is the reference position of functions +that set or return the current position of the mouse (@pxref{Mouse +Position}) and for functions dealing with the position of windows like +@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p} +(@pxref{Coordinates and Windows}). + +@item Internal Border +The internal border (@pxref{Layout Parameters}) is a border drawn by +Emacs around the inner frame (see below). + +@item Inner Frame +@cindex inner frame +@cindex inner edges +@cindex inner width +@cindex inner height +The @dfn{inner frame} is the rectangle reserved for the frame's windows. +It's enclosed by the internal border which, however, is not part of the +inner frame. Its edges are called the @dfn{inner edges} of the frame. +The @dfn{inner width} and @dfn{inner height} specify the size of the +rectangle. + +@cindex minibuffer-less frame +@cindex minibuffer-only frame +As a rule, the inner frame is subdivided into the frame's root window +(@pxref{Windows and Frames}) and the frame's minibuffer window +(@pxref{Minibuffer Windows}). There are two notable exceptions to this +rule: A @dfn{minibuffer-less frame} contains a root window only and does +not contain a minibuffer window. A @dfn{minibuffer-only frame} contains +only a minibuffer window which also serves as that frame's root window. +See @ref{Initial Parameters} for how to create such frame +configurations. + +@item Text Area +@cindex text area +The @dfn{text area} of a frame is a somewhat fictitious area located +entirely within the native frame. It can be obtained by removing from +the native frame any internal borders, one vertical and one horizontal +scroll bar, and one left and one right fringe as specified for this +frame, see @ref{Layout Parameters}. +@end table + +@cindex absolute position +The @dfn{absolute position} of a frame or its edges is usually given in +terms of pixels counted from an origin at position (0, 0) of the frame's +display. Note that with multiple monitors the origin does not +necessarily coincide with the top left corner of the entire usable +display area. Hence the absolute outer position of a frame or the +absolute positions of the edges of the outer, native or inner frame can +be negative in such an environment even when that frame is completely +visible. + + For a frame on a graphical terminal the following function returns the +sizes of the areas described above: + +@defun frame-geometry &optional frame +This function returns geometric attributes of @var{frame}. The return +value is an association list of the attributes listed below. All +coordinate, height and width values are integers counting pixels. + +@table @code +@item outer-position +A cons of the absolute X- and Y-coordinates of the outer position of +@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s +display. + +@item outer-size +A cons of the outer width and height of @var{frame}. + +@item external-border-size +A cons of the horizontal and vertical width of @var{frame}'s external +borders as supplied by the window manager. If the window manager +doesn't supply these values, Emacs will try to guess them from the +coordinates of the outer and inner frame. + +@item title-bar-size +A cons of the width and height of the title bar of @var{frame} as +supplied by the window manager or operating system. If both of them are +zero, the frame has no title bar. If only the width is zero, Emacs was +not able to retrieve the width information. + +@item menu-bar-external +If non-@code{nil}, this means the menu bar is external (not part of the +native frame of @var{frame}). + +@item menu-bar-size +A cons of the width and height of the menu bar of @var{frame}. + +@item tool-bar-external +If non-@code{nil}, this means the tool bar is external (not part of the +native frame of @var{frame}). + +@item tool-bar-position +This tells on which side the tool bar on @var{frame} is and can be one +of @code{left}, @code{top}, @code{right} or @code{bottom}. The only +toolkit that currently supports a value other than @code{top} is GTK+. + +@item tool-bar-size +A cons of the width and height of the tool bar of @var{frame}. + +@item internal-border-width +The width of the internal border of @var{frame}. +@end table +@end defun + +The following function can be used to retrieve the edges of the outer, +native and inner frame. + +@defun frame-edges &optional frame type +This function returns the edges of the outer, native or inner frame of +@var{frame}. @var{frame} must be a live frame and defaults to the +selected one. The list returned has the form (@var{left} @var{top} +@var{right} @var{bottom}) where all values are in pixels relative to the +position (0, 0) of @var{frame}'s display. For terminal frames +@var{left} and @var{top} are both zero. + +Optional argument @var{type} specifies the type of the edges to return: +@var{type} @code{outer-edges} means to return the outer edges of +@var{frame}, @code{native-edges} (or @code{nil}) means to return its +native edges and @code{inner-edges} means to return its inner edges. + +Notice that the pixels at the positions @var{bottom} and @var{right} +lie immediately outside the corresponding frame. This means that if you +have, for example, two side-by-side frames positioned such that the +right outer edge of the frame on the left equals the left outer edge of +the frame on the right, the pixels representing that edge are part +of the frame on the right. +@end defun + + +@node Frame Font +@subsection Frame Font +@cindex default font +@cindex default character size +@cindex default character width +@cindex default width of character +@cindex default character height +@cindex default height of character +Each frame has a @dfn{default font} which specifies the default +character size for that frame. This size is meant when retrieving or +changing the size of a frame in terms of columns or lines +(@pxref{Size Parameters}). It is also used when resizing (@pxref{Window +Sizes}) or splitting (@pxref{Splitting Windows}) windows. + +@cindex line height +@cindex column width +The term @dfn{line height} is sometimes used instead of ``default +character height''. Similarly, the term @dfn{column width} is used as +shorthand for ``default character width''. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the default height and width of a character in +@var{frame}, measured in pixels. Together, these values establish the +size of the default font on @var{frame}. The values depend on the +choice of font for @var{frame}, see @ref{Font and Color Parameters}. +@end defun + +The default font can be also set directly with the following function: + +@deffn Command set-frame-font font &optional keep-size frames +This sets the default font to @var{font}. When called interactively, it +prompts for the name of a font, and uses that font on the selected +frame. When called from Lisp, @var{font} should be a font name (a +string), a font object, font entity, or a font spec. + +If the optional argument @var{keep-size} is @code{nil}, this keeps the +number of frame lines and columns fixed. (If non-@code{nil}, the option +@code{frame-inhibit-implied-resize} described in the next section will +override this.) If @var{keep-size} is non-@code{nil} (or with a prefix +argument), it tries to keep the size of the display area of the current +frame fixed by adjusting the number of lines and columns. + +If the optional argument @var{frames} is @code{nil}, this applies the +font to the selected frame only. If @var{frames} is non-@code{nil}, it +should be a list of frames to act upon, or @code{t} meaning all existing +and all future graphical frames. +@end deffn + + +@node Size and Position +@subsection Size and Position +@cindex frame size +@cindex frame position +@cindex position of frame + +You can read or change the position of a frame using the frame +parameters @code{left} and @code{top} (@pxref{Position Parameters}) and +its size using the @code{height} and @code{width} parameters +(@pxref{Size Parameters}). Here are some special features for working +with sizes and positions. For all of these functions the argument +@var{frame} must denote a live frame and defaults to the selected frame. + +@defun frame-position &optional Lisp_Object &optional frame +This function returns the outer position (@pxref{Frame Layout}) of +@var{frame} in pixels. The value is a cons giving the coordinates of +the top left corner of the outer frame of @var{frame} relative to an +origin at the position (0, 0) of the frame's display. On a text +terminal frame both values are zero. +@end defun + +@defun set-frame-position frame X Y +This function sets the outer frame position of @var{frame} to @var{X} +and @var{Y}. The latter arguments specify pixels and normally count +from an origin at the position (0, 0) of @var{frame}'s display. + +A negative parameter value positions the right edge of the outer frame +by @var{-x} pixels left from the right edge of the screen or the bottom +edge by @var{-y} pixels up from the bottom edge of the screen. + +This function has no effect on text terminal frames. +@end defun + +@defun frame-pixel-height &optional frame +@defunx frame-pixel-width &optional frame + These functions return the inner height and width (the height and +width of the display area, see @ref{Frame Layout}) of @var{frame} in +pixels. For a text terminal, the results are in characters rather than +pixels. +@end defun + +@defun frame-text-height &optional frame +@defunx frame-text-width &optional frame +These functions return the height and width of the text area of +@var{frame} (@pxref{Frame Layout}), measured in pixels. For a text +terminal, the results are in characters rather than pixels. + +The value returned by @code{frame-text-height} differs from that +returned by @code{frame-pixel-height} by not including the heights of +any internal tool bar or menu bar, the height of one horizontal scroll +bar and the widths of the internal border. + +The value returned by @code{frame-text-width} differs from that returned +by @code{frame-pixel-width} by not including the width of one vertical +scroll bar, the widths of one left and one right fringe and the widths +of the internal border. +@end defun + +@defun frame-height &optional frame +@defunx frame-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in units of the default font height and width of +@var{frame} (@pxref{Frame Font}). These functions are plain shorthands +for writing @code{(frame-parameter frame 'height)} and +@code{(frame-parameter frame 'width)}. + +If the text area of @var{frame} measured in pixels is not a multiple of +its default font size, the values returned by these functions are +rounded down to the number of characters of the default font that fully +fit into the text area. +@end defun + +@defopt frame-resize-pixelwise +If this option is @code{nil}, a frame's size is usually rounded to a +multiple of the current values of that frame's @code{frame-char-height} +and @code{frame-char-width} whenever the frame is resized. If this is +non-@code{nil}, no rounding occurs, hence frame sizes can +increase/decrease by one pixel. + +Setting this variable usually causes the next resize operation to pass +the corresponding size hints to the window manager. This means that +this variable should be set only in a user's initial file; applications +should never bind it temporarily. + +The precise meaning of a value of @code{nil} for this option depends on +the toolkit used. Dragging the external border with the mouse is done +character-wise provided the window manager is willing to process the +corresponding size hints. Calling @code{set-frame-size} (see below) +with arguments that do not specify the frame size as an integer multiple +of its character size, however, may: be ignored, cause a rounding +(GTK+), or be accepted (Lucid, Motif, MS-Windows). + +With some window managers you may have to set this to non-@code{nil} in +order to make a frame appear truly maximized or full-screen. +@end defopt + +@defun set-frame-size frame width height pixelwise +This function sets the size of the text area of @var{frame}, measured in +terms of the canonical height and width of a character on @var{frame} +(@pxref{Frame Font}). + +The optional argument @var{pixelwise} non-@code{nil} means to measure +the new width and height in units of pixels instead. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame size +to a multiple of its character size. +@end defun + +@defun set-frame-height frame height &optional pretend pixelwise +This function resizes the text area of @var{frame} to a height of +@var{height} 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{height} +lines of output in @var{frame}, but does not change its value for the +actual height of the frame. This is only useful on text terminals. +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 directly does not always work, because knowing the correct +actual size may be necessary for correct cursor positioning on +text terminals. + +The optional fourth argument @var{pixelwise} non-@code{nil} means that +@var{frame} should be @var{height} pixels high. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame +height to a multiple of its character height. +@end defun + +@defun set-frame-width frame width &optional pretend pixelwise +This function sets the width of the text area of @var{frame}, measured +in characters. The argument @var{pretend} has the same meaning as in +@code{set-frame-height}. + +The optional fourth argument @var{pixelwise} non-@code{nil} means that +@var{frame} should be @var{width} pixels wide. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame width +to a multiple of its character width. +@end defun + +None of these three functions will make a frame smaller than needed to +display all of its windows together with their scroll bars, fringes, +margins, dividers, mode and header lines. This contrasts with requests +by the window manager triggered, for example, by dragging the external +border of a frame with the mouse. Such requests are always honored by +clipping, if necessary, portions that cannot be displayed at the right, +bottom corner of the frame. + + +@node Implied Frame Resizing +@subsection Implied Frame Resizing +@cindex implied frame resizing +@cindex implied resizing of frame + +By default, Emacs tries to keep the number of lines and columns of a +frame's text area unaltered when, for example, adding or removing the +menu bar, changing the default font or setting the width of the frame's +scroll bars. This means, however, that in such case Emacs must ask the +window manager to resize the outer frame in order to accommodate the +size change. Note that wrapping a menu or tool bar usually does not +resize the frame's outer size, hence this will alter the number of +displayed lines. + + Occasionally, such @dfn{implied frame resizing} may be unwanted, for +example, when the frame is maximized or made full-screen (where it's +turned off by default). In other cases you can disable implied resizing +with the following option: + +@defopt frame-inhibit-implied-resize +If this option is @code{nil}, changing font, menu bar, tool bar, +internal borders, fringes or scroll bars of a specific frame may +implicitly resize the frame's display area in order to preserve the +number of columns or lines the frame displays. If this option is +non-@code{nil}, no implied resizing is done. + +The value of this option can be also be a list of frame parameters. In +that case, implied resizing is inhibited when changing a parameter that +appears in this list. The frame parameters currently handled by this +option are: @code{font}, @code{font-backend}, +@code{internal-border-width}, @code{menu-bar-lines} and +@code{tool-bar-lines}. + +Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, +@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, +@code{left-fringe} and @code{right-fringe} frame parameters is handled +as if the frame contained just one live window. This means, for +example, that removing vertical scroll bars on a frame containing +several side by side windows will shrink the outer frame width by the +width of one scroll bar provided this option is @code{nil} and keep it +unchanged if this option is either @code{t} or a list containing +@code{vertical-scroll-bars}. + +The default value is @code{'(tool-bar-lines)} for Lucid, Motif and +Windows (which means that adding/removing a tool bar there does not +change the outer frame height), @code{nil} on all other window systems +including GTK+ (which means that changing any of the parameters listed +above may change the size of the outer frame), and @code{t} otherwise +(which means the outer frame size never changes implicitly when there's +no window system support). + +Note that when a frame is not large enough to accommodate a change of +any of the parameters listed above, Emacs may try to enlarge the frame +even if this option is non-@code{nil}. +@end defopt + + @node Frame Parameters @section Frame Parameters @cindex frame parameters @@ -338,7 +978,6 @@ frame transparency, the parameter @code{alpha} is also meaningful. * 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 @@ -385,6 +1024,7 @@ parameter values to frames that will be created henceforth. @node Initial Parameters @subsection Initial Frame Parameters +@cindex parameters of initial frame You can specify the parameters for the initial startup frame by setting @code{initial-frame-alist} in your init file (@pxref{Init @@ -485,8 +1125,9 @@ frame. @code{title} and @code{name} are meaningful on all terminals. @vindex display, a frame parameter @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 -@env{DISPLAY} environment variable. +form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the +@env{DISPLAY} environment variable. @xref{Multiple Terminals}, for +more details about display names. @vindex display-type, a frame parameter @item display-type @@ -523,6 +1164,7 @@ named, this parameter will be @code{nil}. @node Position Parameters @subsubsection Position Parameters @cindex window position on display +@cindex frame position Position parameters' values are normally measured in pixels, but on text terminals they count characters or lines instead. @@ -542,18 +1184,30 @@ right screen edge. @item @code{(+ @var{pos})} This specifies the position of the left frame edge relative to the left screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @item @code{(- @var{pos})} This specifies the position of the right frame edge relative to the right screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @end table 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. +If the window manager refuses to align a frame at the left or top screen +edge, combining position notation and @code{user-position} as in + +@example +(modify-frame-parameters + nil '((user-position . t) (left . (+ -4)))) +@end example + +may help to override that. + @vindex top, a frame parameter @item top The screen position of the top (or bottom) edge, in pixels, with respect @@ -596,6 +1250,7 @@ parameters represent the user's stated preference; otherwise, use @code{nil}. @end table + @node Size Parameters @subsubsection Size Parameters @cindex window size on display @@ -607,13 +1262,13 @@ pixel sizes of these character units (@pxref{Face Attributes}). @table @code @vindex height, a frame parameter @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}.) +The height of the frame's text area (@pxref{Frame Geometry}), in +characters. @vindex width, a frame parameter @item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) +The width of the frame's text area (@pxref{Frame Geometry}), in +characters. @vindex user-size, a frame parameter @item user-size @@ -622,21 +1277,57 @@ the @code{user-position} parameter (@pxref{Position Parameters, user-position}) does for the position parameters @code{top} and @code{left}. -@cindex full-screen frames +@cindex fullboth frames +@cindex fullheight frames +@cindex fullwidth frames +@cindex maximized frames @vindex fullscreen, a frame parameter @item fullscreen -Specify that width, height or both shall be maximized. The value -@code{fullwidth} specifies that width shall be as wide as possible. -The value @code{fullheight} specifies that height shall be as tall as -possible. The value @code{fullboth} specifies that both the width and -the height shall be set to the size of the screen. The value -@code{maximized} specifies that the frame shall be maximized. The -difference between @code{maximized} and @code{fullboth} is that the -former can still be resized by dragging window manager decorations -with the mouse, while the latter really covers the whole screen and -does not allow resizing by mouse dragging. +This parameter specifies whether to maximize the frame's width, height +or both. Its value can be @code{fullwidth}, @code{fullheight}, +@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as +wide as possible, a @dfn{fullheight} frame is as tall as possible, and +a @dfn{fullboth} frame is both as wide and as tall as possible. A +@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually +keeps its title bar and the buttons for resizing +and closing the frame. Also, maximized frames typically avoid hiding +any task bar or panels displayed on the desktop. A ``fullboth'' frame, +on the other hand, usually omits the title bar and occupies the entire +available screen space. + +Full-height and full-width frames are more similar to maximized +frames in this regard. However, these typically display an external +border which might be absent with maximized frames. Hence the heights +of maximized and full-height frames and the widths of maximized and +full-width frames often differ by a few pixels. + +With some window managers you may have to customize the variable +@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to +make a frame truly appear maximized or full-screen. Moreover, +some window managers might not support smooth transition between the +various full-screen or maximization states. Customizing the variable +@code{x-frame-normalize-before-maximize} can help to overcome that. + +@vindex fullscreen-restore, a frame parameter +@item fullscreen-restore +This parameter specifies the desired fullscreen state of the frame +after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame +Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state. +Normally this parameter is installed automatically by that command when +toggling the state to fullboth. If, however, you start Emacs in the +``fullboth'' state, you have to specify the desired behavior in your initial +file as, for example + +@example +(setq default-frame-alist + '((fullscreen . fullboth) (fullscreen-restore . fullheight))) +@end example + +This will give a new frame full height after typing in it @key{F11} for +the first time. @end table + @node Layout Parameters @subsubsection Layout Parameters @cindex layout parameters of frames @@ -660,19 +1351,21 @@ 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 @vindex horizontal-scroll-bars, a frame parameter @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 +Whether the frame has scroll bars for horizontal scrolling (@code{t} and +@code{bottom} mean yes, @code{nil} means no). @vindex scroll-bar-width, a frame parameter @item scroll-bar-width The width of vertical scroll bars, in pixels, or @code{nil} meaning to use the default width. +@vindex scroll-bar-height, a frame parameter +@item scroll-bar-height +The height of horizontal scroll bars, in pixels, or @code{nil} meaning +to use the default height. + @vindex left-fringe, a frame parameter @vindex right-fringe, a frame parameter @item left-fringe @@ -686,13 +1379,17 @@ these two frame parameters, the return value is always an integer. When using @code{set-frame-parameter}, passing a @code{nil} value imposes an actual default value of 8 pixels. -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width 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. +@vindex right-divider-width, a frame parameter +@item right-divider-width +The width (thickness) reserved for the right divider (@pxref{Window +Dividers}) of any window on the frame, in pixels. A value of zero means +to not draw right dividers. + +@vindex bottom-divider-width, a frame parameter +@item bottom-divider-width +The width (thickness) reserved for the bottom divider (@pxref{Window +Dividers}) of any window on the frame, in pixels. A value of zero means +to not draw bottom dividers. @vindex menu-bar-lines frame parameter @item menu-bar-lines @@ -720,6 +1417,8 @@ integer). @xref{Line Height}, for more information. @node Buffer Parameters @subsubsection Buffer Parameters +@cindex frame, which buffers to display +@cindex buffers to display on frame These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in the frame. @@ -877,12 +1576,25 @@ means use a standard modification of the usual cursor type (solid box becomes hollow box, and bar becomes a narrower bar). @end defopt +@defopt x-stretch-cursor +This variable controls the width of the block cursor displayed on +extra-wide glyphs such as a tab or a stretch of white space. By +default, the block cursor is only as wide as the font's default +character, and will not cover all of the width of the glyph under it +if that glyph is extra-wide. A non-@code{nil} value of this variable +means draw the block cursor as wide as the glyph under it. The +default value is @code{nil}. + +This variable has no effect on text-mode frames, since the text-mode +cursor is drawn by the terminal out of Emacs's control. +@end defopt + @defopt 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} +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 @@ -903,7 +1615,7 @@ variable do not take effect immediately, only when you specify the A list of symbols, specifying the @dfn{font backends} to use for drawing fonts in the frame, in order of priority. On X, there are currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On Windows, there are +driver) and @code{xft} (the Xft font driver). On MS-Windows, there are currently two available font backends: @code{gdi} and @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs Manual}). On other systems, there is only one available font backend, @@ -933,9 +1645,9 @@ used instead. @vindex screen-gamma, a frame parameter @item screen-gamma @cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts +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. +your display. 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 @@ -968,8 +1680,8 @@ variable, Emacs uses the latter. By default, @code{frame-alpha-lower-limit} is 20. The @code{alpha} frame parameter can also be a cons cell -@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the -opacity of the frame when it is selected, and @samp{inactive} is the +@code{(@var{active} . @var{inactive})}, where @var{active} is the +opacity of the frame when it is selected, and @var{inactive} is the opacity when it is not selected. @end table @@ -1023,112 +1735,6 @@ 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 frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. -@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 on text terminals. -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 -text terminals. -@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 - -@c FIXME? Belongs more in Emacs manual than here? -@c But, e.g., fit-window-to-buffer is in this manual. -@deffn Command fit-frame-to-buffer &optional frame max-height min-height -This command adjusts the height of @var{frame} (the default is the -selected frame) to fit its contents. The optional arguments -@var{max-height} and @var{min-height} specify the maximum and minimum -new frame heights, respectively. - -@vindex fit-frame-to-buffer-bottom-margin -The default minimum height corresponds to @code{window-min-height}. -The default maximum height is the screen height below the current top -position of the frame, minus any margin specified by the option -@code{fit-frame-to-buffer-bottom-margin}. -@end deffn @node Geometry @subsection Geometry @@ -1189,7 +1795,7 @@ symbol) of @var{terminal}. If @var{terminal} has no setting for @end defun @defun set-terminal-parameter terminal parameter value -This function sets the parameter @var{parm} of @var{terminal} to the +This function sets the parameter @var{parameter} of @var{terminal} to the specified @var{value}, and returns the previous value of that parameter. @end defun @@ -1208,6 +1814,18 @@ terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. @item terminal-initted After the terminal is initialized, this is set to the terminal-specific initialization function. +@item tty-mode-set-strings +When present, a list of strings containing escape sequences that Emacs +will output while configuring a tty for rendering. Emacs emits these +strings only when configuring a terminal: if you want to enable a mode +on a terminal that is already active (for example, while in +@code{tty-setup-hook}), explicitly output the necessary escape +sequence using @code{send-string-to-terminal} in addition to adding +the sequence to @code{tty-mode-set-strings}. +@item tty-mode-reset-strings +When present, a list of strings that undo the effects of the strings +in @code{tty-mode-set-strings}. Emacs emits these strings when +exiting, deleting a terminal, or suspending itself. @end table @node Frame Titles @@ -1266,7 +1884,8 @@ 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. +A frame cannot be deleted as long as its minibuffer serves as surrogate +minibuffer for another frame (@pxref{Minibuffers and Frames}). Normally, you cannot delete a frame if all other frames are invisible, but if @var{force} is non-@code{nil}, then you are allowed to do so. @end deffn @@ -1298,13 +1917,13 @@ internals of Emacs. @defun visible-frame-list This function returns a list of just the currently visible frames. @xref{Visibility of Frames}. Frames on text terminals always count as -``visible'', even though only the selected one is actually displayed. +visible, even though only the selected one is actually displayed. @end defun @defun next-frame &optional frame minibuf This function 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 +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}). @@ -1341,12 +1960,19 @@ 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 explicitly specify 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. +@cindex frame without a minibuffer +@cindex surrogate minibuffer frame +However, you can also create a frame without a minibuffer. Such a frame +must use the minibuffer window of some other frame. That other frame +will serve as @dfn{surrogate minibuffer frame} for this frame and cannot +be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as +this frame is live. + +When you create the frame, you can explicitly specify 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 @@ -1369,7 +1995,7 @@ window always resides on the selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs +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 @@ -1389,7 +2015,7 @@ way, Emacs automatically keeps track of which frame has the focus. To explicitly 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 +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. @@ -1479,6 +2105,14 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun +@defvar focus-in-hook +This is a normal hook run when an Emacs frame gains input focus. +@end defvar + +@defvar focus-out-hook +This is a normal hook run when an Emacs frame loses input focus. +@end defvar + @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. @@ -1510,7 +2144,7 @@ This function 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 terminal, all frames are considered ``visible'' for the +On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. @xref{Raising and Lowering}. @end defun @@ -1634,6 +2268,19 @@ 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. + +The @code{track-mouse} form causes Emacs to generate mouse motion +events by binding the variable @code{track-mouse} to a +non-@code{nil} value. If that variable has the special value +@code{dragging}, it additionally instructs the display engine to +refrain from changing the shape of the mouse pointer. This is +desirable in Lisp programs that require mouse dragging across large +portions of Emacs display, which might otherwise cause the mouse +pointer to change its shape according to the display portion it hovers +on (@pxref{Pointer Shape}). Therefore, Lisp programs that need the +mouse pointer to retain its original shape during dragging should bind +@code{track-mouse} to the value @code{dragging} at the beginning of +their @var{body}. @end defspec The usual purpose of tracking mouse motion is to indicate on the screen @@ -1691,8 +2338,10 @@ 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}. +and @var{y} are integers giving the (possibly rounded) position in +multiples of the default character size of @var{frame} (@pxref{Frame +Font}) relative to the native position of @var{frame} (@pxref{Frame +Geometry}). @end defun @defvar mouse-position-function @@ -1708,9 +2357,13 @@ This abnormal hook exists for the benefit of packages like @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. +giving the position in multiples of the default character size of +@var{frame} (@pxref{Frame Font}) relative to the native position of +@var{frame} (@pxref{Frame Geometry}). + +The resulting mouse position is constrained to the native frame 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 @@ -1721,12 +2374,31 @@ coordinates in units of pixels rather than units of characters. @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. +characters. -If @var{frame} is not visible, this function does nothing. The return -value is not significant. +The resulting mouse position is not constrained to the native frame of +@var{frame}. If @var{frame} is not visible, this function does nothing. +The return value is not significant. @end defun +On a graphical terminal the following two functions allow to retrieve +and set the absolute position of the mouse cursor. + +@defun mouse-absolute-pixel-position +This function returns a cons cell (@var{x} . @var{y}) of the coordinates +of the mouse cursor position in pixels, relative to a position (0, 0) of +the selected frame's display. +@end defun + +@defun set-mouse-absolute-pixel-position x y +This function moves the mouse cursor to the position (@var{x}, @var{y}). +The coordinates @var{x} and @var{y} are interpreted in pixels relative +to a position (0, 0) of the selected frame's display. +@end defun + +The following function can tell whether the mouse cursor is currently +visible on a frame: + @defun frame-pointer-visible-p &optional frame This predicate function returns non-@code{nil} if the mouse pointer displayed on @var{frame} is visible; otherwise it returns @code{nil}. @@ -1740,9 +2412,12 @@ allows to know if the pointer has been hidden. @node Pop-Up Menus @section Pop-Up Menus +@cindex menus, popup - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. + A Lisp program can pop up a menu so that the user can choose an +alternative with the mouse. On a text terminal, if the mouse is not +available, the user can choose an alternative using the keyboard +motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys. @defun x-popup-menu position menu This function displays a pop-up menu and returns an indication of @@ -1763,20 +2438,22 @@ 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. +position (or the top-left corner of the frame if the mouse is not +available on a text terminal). 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.) On toolkits that support -menu titles, the title is taken from the prompt string of @var{menu} -if @var{menu} is a keymap, or from the prompt string of the first -keymap in @var{menu} if it is a list of keymaps (@pxref{Defining -Menus}). +command bound to that sequence of events.) On text terminals and +toolkits that support menu titles, the title is taken from the prompt +string of @var{menu} if @var{menu} is a keymap, or from the prompt +string of the first keymap in @var{menu} if it is a list of keymaps +(@pxref{Defining Menus}). Alternatively, @var{menu} can have the following form: @@ -1800,7 +2477,7 @@ cell; this makes a non-selectable menu item. 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 +@kbd{C-g}, 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}. @@ -1872,7 +2549,8 @@ 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}). +for @code{message-box} (@pxref{message-box}). (On text terminals, the +box title is not displayed.) 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 @@ -1999,6 +2677,7 @@ clipboard as empty. @node Drag and Drop @section Drag and Drop +@cindex drag and drop @vindex x-dnd-test-function @vindex x-dnd-known-types @@ -2226,7 +2905,7 @@ If you specify them, the key is @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 +resources for other application names by binding this variable to some other string, around a call to @code{x-get-resource}. @end defvar @@ -2284,9 +2963,9 @@ 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. +@var{display}, @code{nil} if not. Support for popup menus requires +that the mouse be available, since the menu is popped up by clicking +the mouse on some portion of the Emacs display. @end defun @defun display-graphic-p &optional display @@ -2319,7 +2998,7 @@ This function returns @code{t} if the screen can display shades of gray. 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 +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 @@ -2329,14 +3008,14 @@ way that's different in appearance than the default face, and @item -`close in spirit' to what the attributes specify, if not exact. +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 +the tty display code's automatic substitution of a dim face for italic. @end defun @@ -2361,8 +3040,8 @@ This function returns the number of screens associated with the 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 +For graphical terminals, note that on multi-monitor setups this +refers to the pixel height for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -2370,7 +3049,7 @@ refers to the pixel width for all physical monitors associated with 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 +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 Terminals}. @end defun @@ -2378,11 +3057,19 @@ refers to the pixel width for all physical monitors associated with @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. + +For graphical terminals, note that on multi-monitor setups this +refers to the height for all physical monitors associated with +@var{display}. @xref{Multiple Terminals}. @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. + +For graphical terminals, note that on multi-monitor setups this +refers to the width for all physical monitors associated with +@var{display}. @xref{Multiple Terminals}. @end defun @defopt display-mm-dimensions-alist @@ -2431,20 +3118,26 @@ colors). This function returns the number of color cells the screen supports. @end defun - These functions obtain additional information specifically -about X displays. + These functions obtain additional information about the window +system in use where Emacs shows the specified @var{display}. (Their +names begin with @code{x-} for historical reasons.) @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. +This function returns the list of version numbers of the GUI window +system running on @var{display}, such as the X server on GNU and Unix +systems. The value is a list of three integers: the major and minor +version numbers of the protocol, and the distributor-specific release +number of the window system software itself. On GNU and Unix systems, +these are normally the version of the X protocol and the +distributor-specific release number of the X server software. On +MS-Windows, this is the version of the Windows OS. @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. +This function returns the vendor that provided the window system +software (as a string). On GNU and Unix systems this really means +whoever distributes the X server. On MS-Windows this is the vendor ID +string of the Windows OS (Microsoft). When the developers of X labeled software distributors as ``vendors'', they showed their false assumption that no system could diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 39a9ff6b62c..8835667b82d 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Functions @@ -11,22 +11,23 @@ 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 +* 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. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Functions that the compiler will expand inline. -* Declare Form:: Adding additional information about a function. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives +* Closures:: Functions that enclose a lexical environment. +* Advising Functions:: Adding to the definition of a function. +* Obsolete Functions:: Declaring functions obsolete. +* Inline Functions:: Functions that the compiler will expand inline. +* Declare Form:: Adding additional information about a function. +* Declaring Functions:: Telling the compiler that a function is defined. +* 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 @@ -117,7 +118,7 @@ Components}); such a @dfn{named command} can be invoked with @item closure A function object that is much like a lambda expression, except that -it also encloses an ``environment'' of lexical variable bindings. +it also encloses an environment of lexical variable bindings. @xref{Closures}. @item byte-code function @@ -207,10 +208,10 @@ Before going into these details, the following subsections describe the components of a lambda expression and what they do. @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. +* 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 @@ -367,7 +368,7 @@ This is what @code{substring} does; @code{nil} as the third argument to @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'' +always uses @code{nil}. Emacs Lisp does not support @code{supplied-p} variables that tell you whether an argument was explicitly passed. @end quotation @@ -591,6 +592,11 @@ If @var{doc} is non-@code{nil}, it becomes the function documentation of @var{name}. Otherwise, any documentation provided by @var{definition} is used. +@cindex defalias-fset-function property +Internally, @code{defalias} normally uses @code{fset} to set the definition. +If @var{name} has a @code{defalias-fset-function} property, however, +the associated value is used as a function to call in place of @code{fset}. + 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 @@ -654,7 +660,7 @@ 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 +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. @@ -906,7 +912,7 @@ This macro returns an anonymous function with argument list @var{args}, documentation string @var{doc} (if any), interactive spec @var{interactive} (if any), and body forms given by @var{body}. -In effect, this macro makes @code{lambda} forms ``self-quoting'': +In effect, this macro makes @code{lambda} forms self-quoting: evaluating a form whose @sc{car} is @code{lambda} yields the form itself: @@ -1001,12 +1007,12 @@ 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 returns the object in the function cell of @var{symbol}. It does +not check that the returned object is a legitimate function. -This function does not check that the returned object is a legitimate -function. +If the function cell is void, the return value is @code{nil}. To +distinguish between a function cell that is void and one set to +@code{nil}, use @code{fboundp} (see below). @example @group @@ -1026,10 +1032,10 @@ function. @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. + 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 +the symbol as a function, Emacs 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, @@ -1077,12 +1083,10 @@ This function stores @var{definition} in the function cell of this is not checked. The argument @var{symbol} is an ordinary evaluated argument. -The primary use of this function is as a subroutine by constructs that -define or alter functions, like @code{defadvice} (@pxref{Advising -Functions}). (If @code{defun} were not a primitive, it could be -written as a Lisp macro using @code{fset}.) You can also use it to -give a symbol a function definition that is not a list, e.g., a -keyboard macro (@pxref{Keyboard Macros}): +The primary use of this function is as a subroutine by constructs that define +or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising +Functions}). You can also use it to give a symbol a function definition that +is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): @example ;; @r{Define a named keyboard macro.} @@ -1129,12 +1133,467 @@ argument list and body forms as the remaining elements: @noindent However, the fact that the internal structure of a closure is -``exposed'' to the rest of the Lisp world is considered an internal +exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. +@node Advising Functions +@section Advising Emacs Lisp Functions +@cindex advising functions +@cindex piece of advice + +When you need to modify a function defined in another library, or when you need +to modify a hook like @code{@var{foo}-function}, a process filter, or basically +any variable or object field which holds a function value, you can use the +appropriate setter function, such as @code{fset} or @code{defun} for named +functions, @code{setq} for hook variables, or @code{set-process-filter} for +process filters, but those are often too blunt, completely throwing away the +previous value. + + The @dfn{advice} feature lets you add to the existing definition of +a function, by @dfn{advising the function}. This is a cleaner method +than redefining the whole function. + +Emacs's advice system provides two sets of primitives for that: the core set, +for function values held in variables and object fields (with the corresponding +primitives being @code{add-function} and @code{remove-function}) and another +set layered on top of it for named functions (with the main primitives being +@code{advice-add} and @code{advice-remove}). + +For example, in order to trace the calls to the process filter of a process +@var{proc}, you could use: + +@example +(defun my-tracing-function (proc string) + (message "Proc %S received %S" proc string)) + +(add-function :before (process-filter @var{proc}) #'my-tracing-function) +@end example + +This will cause the process's output to be passed to @code{my-tracing-function} +before being passed to the original process filter. @code{my-tracing-function} +receives the same arguments as the original function. When you're done with +it, you can revert to the untraced behavior with: + +@example +(remove-function (process-filter @var{proc}) #'my-tracing-function) +@end example + +Similarly, if you want to trace the execution of the function named +@code{display-buffer}, you could use: + +@example +(defun his-tracing-function (orig-fun &rest args) + (message "display-buffer called with args %S" args) + (let ((res (apply orig-fun args))) + (message "display-buffer returned %S" res) + res)) + +(advice-add 'display-buffer :around #'his-tracing-function) +@end example + +Here, @code{his-tracing-function} is called instead of the original function +and receives the original function (additionally to that function's arguments) +as argument, so it can call it if and when it needs to. +When you're tired of seeing this output, you can revert to the untraced +behavior with: + +@example +(advice-remove 'display-buffer #'his-tracing-function) +@end example + +The arguments @code{:before} and @code{:around} used in the above examples +specify how the two functions are composed, since there are many different +ways to do it. The added function is also called a piece of @emph{advice}. + +@menu +* Core Advising Primitives:: Primitives to manipulate advice. +* Advising Named Functions:: Advising named functions. +* Advice combinators:: Ways to compose advice. +* Porting old advice:: Adapting code using the old defadvice. +@end menu + +@node Core Advising Primitives +@subsection Primitives to manipulate advices +@cindex advice, add and remove + +@defmac add-function where place function &optional props +This macro is the handy way to add the advice @var{function} to the function +stored in @var{place} (@pxref{Generalized Variables}). + +@var{where} determines how @var{function} is composed with the +existing function, e.g., whether @var{function} should be called before, or +after the original function. @xref{Advice combinators}, for the list of +available ways to compose the two functions. + +When modifying a variable (whose name will usually end with @code{-function}), +you can choose whether @var{function} is used globally or only in the current +buffer: if @var{place} is just a symbol, then @var{function} is added to the +global value of @var{place}. Whereas if @var{place} is of the form +@code{(local @var{symbol})}, where @var{symbol} is an expression which returns +the variable name, then @var{function} will only be added in the +current buffer. Finally, if you want to modify a lexical variable, you will +have to use @code{(var @var{variable})}. + +Every function added with @code{add-function} can be accompanied by an +association list of properties @var{props}. Currently only two of those +properties have a special meaning: + +@table @code +@item name +This gives a name to the advice, which @code{remove-function} can use to +identify which function to remove. Typically used when @var{function} is an +anonymous function. + +@item depth +This specifies how to order the advice, should several pieces of +advice be present. By default, the depth is 0. A depth of 100 +indicates that this piece of advice should be kept as deep as +possible, whereas a depth of -100 indicates that it should stay as the +outermost piece. When two pieces of advice specify the same depth, +the most recently added one will be outermost. + +For @code{:before} advice, being outermost means that this advice will +be run first, before any other advice, whereas being innermost means +that it will run right before the original function, with no other +advice run between itself and the original function. Similarly, for +@code{:after} advice innermost means that it will run right after the +original function, with no other advice run in between, whereas +outermost means that it will be run right at the end after all other +advice. An innermost @code{:override} piece of advice will only +override the original function and other pieces of advice will apply +to it, whereas an outermost @code{:override} piece of advice will +override not only the original function but all other advice applied +to it as well. +@end table + +If @var{function} is not interactive, then the combined function will inherit +the interactive spec, if any, of the original function. Else, the combined +function will be interactive and will use the interactive spec of +@var{function}. One exception: if the interactive spec of @var{function} +is a function (rather than an expression or a string), then the interactive +spec of the combined function will be a call to that function with as sole +argument the interactive spec of the original function. To interpret the spec +received as argument, use @code{advice-eval-interactive-spec}. + +Note: The interactive spec of @var{function} will apply to the combined +function and should hence obey the calling convention of the combined function +rather than that of @var{function}. In many cases, it makes no difference +since they are identical, but it does matter for @code{:around}, +@code{:filter-args}, and @code{filter-return}, where @var{function}. +@end defmac + +@defmac remove-function place function +This macro removes @var{function} from the function stored in +@var{place}. This only works if @var{function} was added to @var{place} +using @code{add-function}. + +@var{function} is compared with functions added to @var{place} using +@code{equal}, to try and make it work also with lambda expressions. It is +additionally compared also with the @code{name} property of the functions added +to @var{place}, which can be more reliable than comparing lambda expressions +using @code{equal}. +@end defmac + +@defun advice-function-member-p advice function-def +Return non-@code{nil} if @var{advice} is already in @var{function-def}. +Like for @code{remove-function} above, instead of @var{advice} being the actual +function, it can also be the @code{name} of the piece of advice. +@end defun + +@defun advice-function-mapc f function-def +Call the function @var{f} for every piece of advice that was added to +@var{function-def}. @var{f} is called with two arguments: the advice function +and its properties. +@end defun + +@defun advice-eval-interactive-spec spec +Evaluate the interactive @var{spec} just like an interactive call to a function +with such a spec would, and then return the corresponding list of arguments +that was built. E.g., @code{(advice-eval-interactive-spec "r\nP")} will +return a list of three elements, containing the boundaries of the region and +the current prefix argument. +@end defun + +@node Advising Named Functions +@subsection Advising Named Functions +@cindex advising named functions + +A common use of advice is for named functions and macros. +You could just use @code{add-function} as in: + +@example +(add-function :around (symbol-function '@var{fun}) #'his-tracing-function) +@end example + + But you should use @code{advice-add} and @code{advice-remove} for that +instead. This separate set of functions to manipulate pieces of advice applied +to named functions, offers the following extra features compared to +@code{add-function}: they know how to deal with macros and autoloaded +functions, they let @code{describe-function} preserve the original docstring as +well as document the added advice, and they let you add and remove advice +before a function is even defined. + + @code{advice-add} can be useful for altering the behavior of existing calls +to an existing function without having to redefine the whole function. +However, it can be a source of bugs, since existing callers to the function may +assume the old behavior, and work incorrectly when the behavior is changed by +advice. Advice can also cause confusion in debugging, if the person doing the +debugging does not notice or remember that the function has been modified +by advice. + + For these reasons, advice should be reserved for the cases where you +cannot modify a function's behavior in any other way. If it is +possible to do the same thing via a hook, that is preferable +(@pxref{Hooks}). If you simply want to change what a particular key +does, it may be better to write a new command, and remap the old +command's key bindings to the new one (@pxref{Remapping Commands}). +In particular, Emacs's own source files should not put advice on +functions in Emacs. (There are currently a few exceptions to this +convention, but we aim to correct them.) + + Special forms (@pxref{Special Forms}) cannot be advised, however macros can +be advised, in much the same way as functions. Of course, this will not affect +code that has already been macro-expanded, so you need to make sure the advice +is installed before the macro is expanded. + + It is possible to advise a primitive (@pxref{What Is a Function}), +but one should typically @emph{not} do so, for two reasons. Firstly, +some primitives are used by the advice mechanism, and advising them +could cause an infinite recursion. Secondly, many primitives are +called directly from C, and such calls ignore advice; hence, one ends +up in a confusing situation where some calls (occurring from Lisp +code) obey the advice and other calls (from C code) do not. + +@defmac define-advice symbol (where lambda-list &optional name depth) &rest body +This macro defines a piece of advice and adds it to the function named +@var{symbol}. The advice is an anonymous function if @var{name} is +nil or a function named @code{symbol@@name}. See @code{advice-add} +for explanation of other arguments. +@end defmac + +@defun advice-add symbol where function &optional props +Add the advice @var{function} to the named function @var{symbol}. +@var{where} and @var{props} have the same meaning as for @code{add-function} +(@pxref{Core Advising Primitives}). +@end defun + +@defun advice-remove symbol function +Remove the advice @var{function} from the named function @var{symbol}. +@var{function} can also be the @code{name} of a piece of advice. +@end defun + +@defun advice-member-p function symbol +Return non-@code{nil} if the advice @var{function} is already in the named +function @var{symbol}. @var{function} can also be the @code{name} of +a piece of advice. +@end defun + +@defun advice-mapc function symbol +Call @var{function} for every piece of advice that was added to the +named function @var{symbol}. @var{function} is called with two +arguments: the advice function and its properties. +@end defun + +@node Advice combinators +@subsection Ways to compose advice + +Here are the different possible values for the @var{where} argument of +@code{add-function} and @code{advice-add}, specifying how the advice +@var{function} and the original function should be composed. + +@table @code +@item :before +Call @var{function} before the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r)) +@end example +@code{(add-function :before @var{funvar} @var{function})} is comparable for +single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} for +normal hooks. + +@item :after +Call @var{function} after the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after @var{funvar} @var{function})} is comparable for +single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} for normal hooks. + +@item :override +This completely replaces the old function with the new one. The old function +can of course be recovered if you later call @code{remove-function}. + +@item :around +Call @var{function} instead of the old function, but provide the old function +as an extra argument to @var{function}. This is the most flexible composition. +For example, it lets you call the old function with different arguments, or +many times, or within a let-binding, or you can sometimes delegate the work to +the old function and sometimes override it completely. More specifically, the +composition of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{function} @var{oldfun} r)) +@end example + +@item :before-while +Call @var{function} before the old function and don't call the old +function if @var{function} returns @code{nil}. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r))) +@end example +@code{(add-function :before-while @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} +when @var{hookvar} is run via @code{run-hook-with-args-until-failure}. + +@item :before-until +Call @var{function} before the old function and only call the old function if +@var{function} returns @code{nil}. More specifically, the composition of the +two functions behaves like: +@example +(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r))) +@end example +@code{(add-function :before-until @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} +when @var{hookvar} is run via @code{run-hook-with-args-until-success}. + +@item :after-while +Call @var{function} after the old function and only if the old function +returned non-@code{nil}. Both functions receive the same arguments, and the +return value of the composition is the return value of @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after-while @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} when @var{hookvar} is run via +@code{run-hook-with-args-until-failure}. + +@item :after-until +Call @var{function} after the old function and only if the old function +returned @code{nil}. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after-until @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} when @var{hookvar} is run via +@code{run-hook-with-args-until-success}. + +@item :filter-args +Call @var{function} first and use the result (which should be a list) as the +new arguments to pass to the old function. More specifically, the composition +of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r))) +@end example + +@item :filter-return +Call the old function first and pass the result to @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r))) +@end example +@end table + + +@node Porting old advice +@subsection Adapting code using the old defadvice +@cindex old advices, porting + +A lot of code uses the old @code{defadvice} mechanism, which is largely made +obsolete by the new @code{advice-add}, whose implementation and semantics is +significantly simpler. + +An old piece of advice such as: + +@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 + +could be translated in the new advice mechanism into a plain function: + +@example +(defun previous-line--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 + +Obviously, this does not actually modify @code{previous-line}. For that the +old advice needed: +@example +(ad-activate 'previous-line) +@end example +whereas the new advice mechanism needs: +@example +(advice-add 'previous-line :before #'previous-line--next-line-at-end) +@end example + +Note that @code{ad-activate} had a global effect: it activated all pieces of +advice enabled for that specified function. If you wanted to only activate or +deactivate a particular piece, you needed to @emph{enable} or @emph{disable} +it with @code{ad-enable-advice} and @code{ad-disable-advice}. +The new mechanism does away with this distinction. + +Around advice such as: + +@example +(defadvice foo (around foo-around) + "Ignore case in `foo'." + (let ((case-fold-search t)) + ad-do-it)) +(ad-activate 'foo) +@end example + +could translate into: + +@example +(defun foo--foo-around (orig-fun &rest args) + "Ignore case in `foo'." + (let ((case-fold-search t)) + (apply orig-fun args))) +(advice-add 'foo :around #'foo--foo-around) +@end example + +Regarding the advice's @emph{class}, note that the new @code{:before} is not +quite equivalent to the old @code{before}, because in the old advice you could +modify the function's arguments (e.g., with @code{ad-set-arg}), and that would +affect the argument values seen by the original function, whereas in the new +@code{:before}, modifying an argument via @code{setq} in the advice has no +effect on the arguments seen by the original function. +When porting @code{before} advice which relied on this behavior, you'll need +to turn it into new @code{:around} or @code{:filter-args} advice instead. + +Similarly old @code{after} advice could modify the returned value by +changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so +when porting such old @code{after} advice, you'll need to turn it into new +@code{:around} or @code{:filter-return} advice instead. + @node Obsolete Functions @section Declaring Functions Obsolete +@cindex obsolete functions You can mark a named function as @dfn{obsolete}, meaning that it may be removed at some point in the future. This causes Emacs to warn @@ -1261,7 +1720,7 @@ performed later on in the same file, just like macros. @section The @code{declare} Form @findex declare - @code{declare} is a special macro which can be used to add ``meta'' + @code{declare} is a special macro which can be used to add meta properties to a function or macro: for example, marking it as obsolete, or giving its forms a special @key{TAB} indentation convention in Emacs Lisp mode. @@ -1286,20 +1745,27 @@ following effects: This acts like a call to @code{set-advertised-calling-convention} (@pxref{Obsolete Functions}); @var{signature} specifies the correct argument list for calling the function or macro, and @var{when} should -be a string indicating when the variable was first made obsolete. +be a string indicating when the old argument list was first made obsolete. @item (debug @var{edebug-form-spec}) This is valid for macros only. When stepping through the macro with Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}. @item (doc-string @var{n}) -Use element number @var{n}, if any, as the documentation string. +This is used when defining a function or macro which itself will be used to +define entities like functions, macros, or variables. It indicates that +the @var{n}th argument, if any, should be considered +as a documentation string. @item (indent @var{indent-spec}) Indent calls to this function or macro according to @var{indent-spec}. This is typically used for macros, though it works for functions too. @xref{Indenting Macros}. +@item (interactive-only @var{value}) +Set the function's @code{interactive-only} property to @var{value}. +@xref{The interactive-only property}. + @item (obsolete @var{current-name} @var{when}) Mark the function or macro as obsolete, similar to a call to @code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name} @@ -1308,7 +1774,37 @@ instead), a string (specifying the warning message), or @code{nil} (in which case the warning message gives no extra details). @var{when} should be a string indicating when the function or macro was first made obsolete. + +@item (compiler-macro @var{expander}) +This can only be used for functions, and tells the compiler to use +@var{expander} as an optimization function. When encountering a call to the +function, of the form @code{(@var{function} @var{args}@dots{})}, the macro +expander will call @var{expander} with that form as well as with +@var{args}@dots{}, and @var{expander} can either return a new expression to use +instead of the function call, or it can return just the form unchanged, +to indicate that the function call should be left alone. @var{expander} can +be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in +which case @var{arg} will hold the original function call expression, and the +(unevaluated) arguments to the function can be accessed using the function's +formal arguments. + +@item (gv-expander @var{expander}) +Declare @var{expander} to be the function to handle calls to the macro (or +function) as a generalized variable, similarly to @code{gv-define-expander}. +@var{expander} can be a symbol or it can be of the form @code{(lambda +(@var{arg}) @var{body})} in which case that function will additionally have +access to the macro (or function)'s arguments. + +@item (gv-setter @var{setter}) +Declare @var{setter} to be the function to handle calls to the macro (or +function) as a generalized variable. @var{setter} can be a symbol in which +case it will be passed to @code{gv-define-simple-setter}, or it can be of the +form @code{(lambda (@var{arg}) @var{body})} in which case that function will +additionally have access to the macro (or function)'s arguments and it will +passed to @code{gv-define-setter}. + @end table + @end defmac @node Declaring Functions @@ -1325,7 +1821,7 @@ example, byte-compiling @file{fortran.el} used to warn: @example In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not +fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not known to be defined. @end example @@ -1416,7 +1912,7 @@ list of buffer-local bindings. 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 +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 diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 655f31ab114..22b7217506f 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Hash Tables @chapter Hash Tables @@ -31,10 +31,10 @@ the way two alists can share a common tail. with a series of functions for operating on them. Hash tables have a special printed representation, which consists of @samp{#s} followed by a list specifying the hash table properties and contents. -@xref{Creating Hash}. (Note that the term ``hash notation'', which -refers to the initial @samp{#} character used in the printed +@xref{Creating Hash}. +(Hash notation, the initial @samp{#} character used in the printed representations of objects with no read representation, has nothing to -do with the term ``hash table''. @xref{Printed Representation}.) +do with hash tables. @xref{Printed Representation}.) Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols @@ -71,16 +71,16 @@ alternatives: @table @code @item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that +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''. +are floating point; otherwise, two distinct objects are never +the same. @item eq -Any two distinct Lisp objects are ``different'' as keys. +Any two distinct Lisp objects are different as keys. @item equal -Two Lisp objects are ``the same'', as keys, if they are equal +Two Lisp objects are the same, as keys, if they are equal according to @code{equal}. @end table @@ -128,35 +128,27 @@ 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'', +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 +@var{rehash-size} is floating point, 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 +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 +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 - You can also create a new hash table using the printed representation for hash tables. The Lisp reader can read this printed representation, provided each element in the specified hash table has @@ -188,6 +180,8 @@ Such objects may be added to the hash table after it is created. @node Hash Access @section Hash Table Access +@cindex accessing hash tables +@cindex 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 @@ -259,14 +253,14 @@ 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. +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''. +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, +an integer that is the hash code of that key. For good results, the +function should use the whole range of integers for hash codes, including negative integers. The specified functions are stored in the property list of @var{name} diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index aa77ba1f36d..387587a4203 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Documentation @@ -10,8 +10,13 @@ GNU Emacs has convenient built-in help facilities, most of which derive their information from documentation strings associated with functions and variables. This chapter describes how to access -documentation strings in Lisp programs. @xref{Documentation Tips}, -for how to write good documentation strings. +documentation strings in Lisp programs. + + The contents of a documentation string should follow certain +conventions. In particular, its first line should be a complete +sentence (or two complete sentences) that briefly describes what the +function or variable does. @xref{Documentation Tips}, for how to +write good documentation strings. Note that the documentation strings for Emacs are not the same thing as the Emacs manual. Manuals have their own source files, written in @@ -40,80 +45,52 @@ Help, emacs, The GNU Emacs Manual}. @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) that briefly describes -what the function or variable does. 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 documentation strings; see -@ref{Documentation Tips}. - - Documentation strings can contain several special text sequences, -referring to key bindings which are looked up in the current keymaps -when the user views the documentation. This allows the help commands -to display the correct keys even if a user rearranges the default key -bindings. @xref{Keys in Documentation}. - - In the documentation string of an autoloaded command -(@pxref{Autoload}), these special text sequences have an additional -special effect: they cause @kbd{C-h f} (@code{describe-function}) on -the command to trigger autoloading. (This is needed for correctly -setting up the hyperlinks in the @file{*Help*} buffer). - -@vindex emacs-lisp-docstring-fill-column - Emacs Lisp mode fills documentation strings to the width -specified by @code{emacs-lisp-docstring-fill-column}. - - Exactly where a documentation string is stored depends on how its -function or variable was defined or loaded into memory: - -@itemize @bullet -@item -@kindex function-documentation -When you define a function (@pxref{Lambda Expressions}, and -@pxref{Function Documentation}), the documentation string is stored in -the function definition itself. You can also put function -documentation in the @code{function-documentation} property of a -function name. That is useful for function definitions which can't -hold a documentation string, such as keyboard macros. - -@item -@kindex variable-documentation -When you define a variable with a @code{defvar} or related form -(@pxref{Defining Variables}), the documentation is stored in the -variable's @code{variable-documentation} property. +with double-quote characters surrounding the text. It is, in fact, an +actual Lisp string. When the string appears in the proper place in a +function or variable definition, it serves as the function's or +variable's documentation. + +@cindex @code{function-documentation} property + In a function definition (a @code{lambda} or @code{defun} form), the +documentation string is specified after the argument list, and is +normally stored directly in the function object. @xref{Function +Documentation}. You can also put function documentation in the +@code{function-documentation} property of a function name +(@pxref{Accessing Documentation}). + +@cindex @code{variable-documentation} property + In a variable definition (a @code{defvar} form), the documentation +string is specified after the initial value. @xref{Defining +Variables}. The string is stored in the variable's +@code{variable-documentation} property. @cindex @file{DOC} (documentation) file -@item -To save memory, the documentation for preloaded functions and -variables (including primitive functions and autoloaded functions) is -not kept in memory, but in the file -@file{emacs/etc/DOC}). - -@item -When a function or variable is loaded from a byte-compiled file during -the Emacs session, its documentation string is not loaded into memory. -Instead, Emacs looks it up in the byte-compiled file as needed. -@xref{Docs and Compilation}. -@end itemize + Sometimes, Emacs does not keep documentation strings in memory. +There are two such circumstances. Firstly, to save memory, the +documentation for preloaded functions and variables (including +primitives) is kept in a file named @file{DOC}, in the directory +specified by @code{doc-directory} (@pxref{Accessing Documentation}). +Secondly, when a function or variable is loaded from a byte-compiled +file, Emacs avoids loading its documentation string (@pxref{Docs and +Compilation}). In both cases, Emacs looks up the documentation string +from the file only when needed, such as when the user calls @kbd{C-h +f} (@code{describe-function}) for a function. + + Documentation strings can contain special @dfn{key substitution +sequences}, referring to key bindings which are looked up only when +the user views the documentation. This allows the help commands to +display the correct keys even if a user rearranges the default key +bindings. @xref{Keys in Documentation}. -@noindent -Regardless of where the documentation string is stored, you can -retrieve it using the @code{documentation} or -@code{documentation-property} function, described in the next section. + In the documentation string of an autoloaded command +(@pxref{Autoload}), these key-substitution sequences have an +additional special effect: they cause @kbd{C-h f} on the command to +trigger autoloading. (This is needed for correctly setting up the +hyperlinks in the @file{*Help*} buffer.) @node Accessing Documentation @section Access to Documentation Strings +@cindex accessing documentation strings @defun documentation-property symbol property &optional verbatim This function returns the documentation string recorded in @@ -122,18 +99,20 @@ most often used to look up the documentation strings of variables, for which @var{property} is @code{variable-documentation}. However, it can also be used to look up other kinds of documentation, such as for customization groups (but for function documentation, use the -@code{documentation} command, below). +@code{documentation} function, below). + +If the property value refers to a documentation string stored in the +@file{DOC} file or a byte-compiled file, this function looks up that +string and returns it. -If the value recorded in the property list refers to a documentation -string stored in a @file{DOC} file or a byte-compiled -file, it looks up that string and returns it. 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 as a Lisp expression to obtain a string. +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 as a Lisp expression to +obtain a string. -The last thing this function does is pass the string through -@code{substitute-command-keys} to substitute actual key bindings -(@pxref{Keys in Documentation}). However, it skips this step if -@var{verbatim} is non-@code{nil}. +Finally, this function passes the string through +@code{substitute-command-keys} to substitute key bindings (@pxref{Keys +in Documentation}). It skips this step if @var{verbatim} is +non-@code{nil}. @smallexample @group @@ -160,16 +139,18 @@ 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. +value is not a string, it is evaluated). -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. +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. -The function @code{documentation} signals a @code{void-function} error +Finally, unless @var{verbatim} is non-@code{nil}, this function calls +@code{substitute-command-keys}. The result is the documentation +string to return. + +The @code{documentation} function 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}. @@ -180,7 +161,6 @@ 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 @file{*Help*} buffer. @@ -191,7 +171,7 @@ several symbols in a @file{*Help*} buffer. (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." +in the *Help* buffer." (interactive "sDescribe symbols matching: ") (let ((describe-func (function @@ -262,6 +242,11 @@ Semipermanent goal column for vertical motion, as set by @dots{} @c That makes them incorrect. @group +minibuffer-temporary-goal-position Variable +not documented +@end group + +@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 @@ -269,17 +254,26 @@ Set the current horizontal position as a goal for C-n and C-p. @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 +With a non-nil argument ARG, 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'. +The goal column is stored in the variable ‘goal-column’. + +(fn ARG) @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. +It is the column where point was at the start of the current run +of vertical motion commands. + +When moving by visual lines via the function ‘line-move-visual’, it is a cons +cell (COL . HSCROLL), where COL is the x-position, in pixels, +divided by the default column width, and HSCROLL is the number of +columns by which window is scrolled from left margin. + +When the ‘track-eol’ feature is doing its job, the value is +‘most-positive-fixnum’. ---------- Buffer: *Help* ---------- @end group @end smallexample @@ -313,6 +307,7 @@ without actually installing it. @xref{Definition of data-directory}. @cindex documentation, keys in @cindex keys in documentation strings @cindex substituting keys in documentation +@cindex key substitution sequence When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text @@ -337,15 +332,38 @@ 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 ‘ +@itemx ` +(left single quotation mark and grave accent) both stand for a left quote. + +@item ’ +@itemx ' +(right single quotation mark and apostrophe) both stand for a right quote. + @item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. +quotes the following character and is discarded; thus, @samp{\=`} puts +@samp{`} into the output, @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. +@defvar text-quoting-style +@cindex curved quotes +@cindex curly quotes +The value of this variable specifies the style used to generate text +quotes. If the variable's value is @code{curve}, the style is +@t{‘like this’} with curved single quotes. If the value is +@code{straight}, the style is @t{'like this'} with straight +apostrophes. If the value is @code{grave}, the style is @t{`like +this'} with grave accent and apostrophe. The default value @code{nil} +acts like @code{curve} if curved single quotes are displayable, and +like @code{grave} otherwise. To use the traditional @code{grave} +style, put the line @code{(setq text-quoting-style 'grave)} into your +@file{~/.emacs} file. +@end defvar + @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. @@ -373,8 +391,8 @@ specifies a key binding that the command does not actually have. @smallexample @group (substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" + "To abort recursive edit, type `\\[abort-recursive-edit]'.") +@result{} "To abort recursive edit, type ‘C-]’." @end group @group @@ -394,9 +412,9 @@ 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." + "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 @@ -527,18 +545,19 @@ non-@code{nil}, the return value is always a vector. @node Help Functions @section Help Functions +@cindex help functions - Emacs provides a variety of on-line help functions, all accessible to + Emacs provides a variety of built-in 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 +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 +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: @@ -603,7 +622,7 @@ subcommands of the prefix key. @defopt 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 +alternative help characters. These events are handled just like the event specified by @code{help-char}. @end defopt @@ -638,7 +657,7 @@ sequence. (The last event is, presumably, the help character.) @end deffn The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. +help without relinquishing control, such as the electric modes. Their names begin with @samp{Helper} to distinguish them from the ordinary help functions. @@ -669,14 +688,17 @@ This function returns the name of the help buffer, which is normally @file{*Help*}; if such a buffer does not exist, it is first created. @end defun +@vindex help-window-select @defmac with-help-window buffer-name body@dots{} -This macro evaluates the @var{body} forms, inserting any output they -produce into a buffer named @var{buffer-name} like -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). -(Usually, @var{buffer-name} should be the value returned by the -function @code{help-buffer}.) It also puts the specified buffer into -Help mode and displays a message telling the user how to quit and -scroll the help window. +This macro evaluates @var{body} like @code{with-output-to-temp-buffer} +(@pxref{Temporary Displays}), inserting any output produced by its forms +into a buffer named @var{buffer-name}. (Usually, @var{buffer-name} +should be the value returned by the function @code{help-buffer}.) It +also puts the specified buffer into Help mode and displays a message +telling the user how to quit and scroll the help window. It selects the +help window if the current value of the user option +@code{help-window-select} has been set accordingly. It returns the last +value in @var{body}. @end defmac @defun help-setup-xref item interactive-p diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 745393f8166..eb2e34318fd 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Hooks @@ -56,6 +56,7 @@ not exactly a hook, but does a similar job. @item after-init-hook @itemx before-init-hook @itemx emacs-startup-hook +@itemx window-setup-hook @xref{Init File}. @item after-insert-file-functions @@ -99,11 +100,11 @@ Hook run after a frame's font changes. @item buffer-list-update-hook @vindex buffer-list-update-hook -Hook run when the buffer list changes. +Hook run when the buffer list changes (@pxref{Buffer List}). @item buffer-quit-function @vindex buffer-quit-function -Function to call to ``quit'' the current buffer. +Function to call to quit the current buffer. @item change-major-mode-hook @xref{Creating Buffer-Local}. @@ -115,6 +116,12 @@ Function to call to ``quit'' the current buffer. @vindex delayed-warnings-hook The command loop runs this soon after @code{post-command-hook} (q.v.). +@item focus-in-hook +@vindex focus-in-hook +@itemx focus-out-hook +@vindex focus-out-hook +@xref{Input Focus}. + @item delete-frame-functions @xref{Deleting Frames}. @@ -207,7 +214,7 @@ Hook run when about to switch windows with a mouse command. @itemx temp-buffer-show-hook @xref{Temporary Displays}. -@item term-setup-hook +@item tty-setup-hook @xref{Terminal-Specific}. @item window-configuration-change-hook @@ -215,9 +222,6 @@ Hook run when about to switch windows with a mouse command. @itemx window-size-change-functions @xref{Window Hooks}. -@item window-setup-hook -@xref{Window Systems}. - @item window-text-change-functions @vindex window-text-change-functions Functions to call in redisplay when text in the window might change. @@ -235,11 +239,9 @@ choose-completion-string-functions completing-read-function completion-annotate-function completion-at-point-functions -completion-in-region-functions completion-list-insert-choice-function deactivate-current-input-method-function describe-current-input-method-function -filter-buffer-substring-functions font-lock-function menu-bar-select-buffer-function read-file-name-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 06375c1e18e..e620da0b4ff 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1993, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node GNU Emacs Internals @@ -14,7 +14,9 @@ internal aspects of GNU Emacs that may be of interest to C programmers. * Building Emacs:: How the dumped Emacs is made. * Pure Storage:: Kludge to make preloaded Lisp functions shareable. * Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Stack-allocated Objects:: Temporary conses and strings on C stack. * Memory Usage:: Info about total size of Lisp objects made so far. +* C Dialect:: What C variant Emacs is written in. * Writing Emacs Primitives:: Writing C code for Emacs. * Object Internals:: Data formats of buffers, windows, processes. * C Integer Types:: How C integer types are used inside Emacs. @@ -111,11 +113,18 @@ drawback that the documentation strings take up space in Emacs all the time.) @end itemize +@cindex change @code{load-path} at configure time +@cindex @option{--enable-locallisppath} option to @command{configure} 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}. +Note that if either @file{site-load.el} or @file{site-init.el} changes +@code{load-path}, the changes will be lost after dumping. +@xref{Library Search}. To make a permanent change to +@code{load-path}, use the @option{--enable-locallisppath} option +of @command{configure}. In a package that can be preloaded, it is sometimes necessary (or useful) to delay certain evaluations until Emacs subsequently starts @@ -249,7 +258,7 @@ accessible objects are also accessible. 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. +(sweep) phase of the garbage collector arranges to reuse them. @c ??? Maybe add something describing weak hash tables here? @@ -505,6 +514,11 @@ created in this Emacs session. Each of these counters increments for a certain kind of object. See the documentation string for details. @end defun +@defun memory-info +This functions returns an amount of total system memory and how much +of it is free. On an unsupported system, the value may be @code{nil}. +@end defun + @defvar gcs-done This variable contains the total number of garbage collections done so far in this Emacs session. @@ -512,10 +526,39 @@ done so far in this Emacs session. @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. +during garbage collection so far in this Emacs session, as a +floating-point number. @end defvar +@node Stack-allocated Objects +@section Stack-allocated Objects + +@cindex stack allocated Lisp objects +@cindex Lisp objects, stack-allocated + The garbage collector described above is used to manage data visible +from Lisp programs, as well as most of the data internally used by the +Lisp interpreter. Sometimes it may be useful to allocate temporary +internal objects using the C stack of the interpreter. This can help +performance, as stack allocation is typically faster than using heap +memory to allocate and the garbage collector to free. The downside is +that using such objects after they are freed results in undefined +behavior, so uses should be well thought out and carefully debugged by +using the @code{GC_CHECK_MARKED_OBJECTS} feature (see +@file{src/alloc.c}). In particular, stack-allocated objects should +never be made visible to user Lisp code. + + Currently, cons cells and strings can be allocated this way. This +is implemented by C macros like @code{AUTO_CONS} and +@code{AUTO_STRING} that define a named @code{Lisp_Object} with block +lifetime. These objects are not freed by the garbage collector; +instead, they have automatic storage duration, i.e., they are +allocated like local variables and are automatically freed at the end +of execution of the C block that defined the object. + + For performance reasons, stack-allocated strings are limited to +@acronym{ASCII} characters, and many of these strings are immutable, +i.e., calling @code{ASET} on them produces undefined behavior. + @node Memory Usage @section Memory Usage @cindex memory usage @@ -568,6 +611,19 @@ The total number of strings that have been allocated so far in this Emacs session. @end defvar +@node C Dialect +@section C Dialect +@cindex C programming language + +The C part of Emacs is portable to C99 or later: C11-specific features such +as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check, +typically at configuration time, and the Emacs build procedure +provides a substitute implementation if necessary. Some C11 features, +such as anonymous structures and unions, are too difficult to emulate, +so they are avoided entirely. + +At some point in the future the base C dialect will no doubt change to C11. + @node Writing Emacs Primitives @section Writing Emacs Primitives @cindex primitive function internals @@ -582,7 +638,6 @@ to read the source, but we can explain some things here. @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, @@ -592,15 +647,10 @@ The remaining args are not evalled at all. If all args return nil, return nil. @end group @group -usage: (or CONDITIONS ...) */) +usage: (or CONDITIONS...) */) (Lisp_Object args) @{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); + Lisp_Object val = Qnil; @end group @group @@ -610,11 +660,11 @@ usage: (or CONDITIONS ...) */) if (!NILP (val)) break; args = XCDR (args); + QUIT; @} @end group @group - UNGCPRO; return val; @} @end group @@ -718,36 +768,25 @@ a primitive 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 -@cindex @code{GCPRO} and @code{UNGCPRO} +@cindex garbage collection protection @cindex protect C variables from garbage collection - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the -sake of the few platforms which do not use Emacs' default -stack-marking garbage collector. The @code{GCPRO1} macro ``protects'' -a variable from garbage collection, explicitly informing the garbage -collector that that variable and all its contents must be as -accessible. GC protection is necessary in any function which can -perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as -a subroutine, either directly or indirectly. - - It suffices to ensure that at least one pointer to each object is -GC-protected. 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 that -has 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}. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. + Within the function @code{For} itself, the local variable +@code{args} refers to objects controlled by Emacs's stack-marking +garbage collector. Although the garbage collector does not reclaim +objects reachable from C @code{Lisp_Object} stack variables, it may +move non-object components of an object, such as string contents; so +functions that access non-object components must take care to refetch +their addresses after performing Lisp evaluation. Lisp evaluation can +occur via calls to @code{eval_sub} or @code{Feval}, either directly or +indirectly. + +@cindex @code{QUIT}, use in Lisp primitives + Note the call to the @code{QUIT} macro inside the loop: this macro +checks whether the user pressed @kbd{C-g}, and if so, aborts the +processing. You should do that in any loop that can potentially +require a large number of iterations; in this case, the list of +arguments could be very long. This increases Emacs responsiveness and +improves user experience. You must not use C initializers for static or global variables unless the variables are never written once Emacs is dumped. These variables @@ -842,14 +881,14 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, @group switch (coordinates_in_window (w, x, y)) @{ - case ON_NOTHING: /* NOT in window at all. */ + case ON_NOTHING: /* NOT in window at all. */ return Qnil; @end group ... @group - case ON_MODE_LINE: /* In mode line of window. */ + case ON_MODE_LINE: /* In mode line of window. */ return Qmode_line; @end group @@ -876,9 +915,7 @@ 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}. +pass to it. The C functions @code{call0}, @code{call1}, @code{call2}, and so on, provide handy ways to call a Lisp function conveniently with a fixed @@ -912,7 +949,7 @@ following basic data types: integer, symbol, string, cons cell, float, vectorlike or miscellaneous object. Each of these data types has the corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the -bits is the value itself. Integer values are immediate, i.e., directly +bits is the value itself. Integers are immediate, i.e., directly represented by those @dfn{value bits}, and all other objects are represented by the C pointers to a corresponding object allocated from the heap. Width of the @code{Lisp_Object} is platform- and configuration-dependent: usually @@ -940,7 +977,7 @@ Array, a fixed-size set of Lisp objects which may be accessed by an index. Symbol, the unique-named entity commonly used as an identifier. @item struct Lisp_Float -Floating point value. +Floating-point value. @item union Lisp_Misc Miscellaneous kinds of objects which don't fit into any of the above. @@ -1261,6 +1298,8 @@ 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. +@c FIXME: These two slots and the 'buffer' slot below were replaced +@c with a single slot 'contents' on 2013-03-28. --xfq @item hchild @itemx vchild These fields contain the window's leftmost child and its topmost child @@ -1338,7 +1377,7 @@ 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 +A non-@code{nil} value means the window's buffer was modified when the window was last updated. @item vertical_scroll_bar @@ -1432,11 +1471,6 @@ The position in the buffer for which the line number is known, or @code{nil} meaning none is known. If it is a buffer, don't display the line number as long as the window shows that buffer. -@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. @@ -1464,12 +1498,10 @@ process. For a network or serial process, it is @code{nil} if the process is running or @code{t} if the process is stopped. @item filter -If non-@code{nil}, a function used to accept output from the process -instead of a buffer. +A function used to accept output from the process. @item sentinel -If non-@code{nil}, a function called whenever the state of the process -changes. +A function called whenever the state of the process changes. @item buffer The associated buffer of the process. @@ -1561,7 +1593,7 @@ fit in @code{int} range. Do not assume that signed integer arithmetic wraps around on overflow. This is no longer true of Emacs porting targets: signed integer overflow has undefined behavior in practice, and can dump core or -even cause earlier or later code to behave ``illogically''. Unsigned +even cause earlier or later code to behave illogically. Unsigned overflow does wrap around reliably, modulo a power of two. @item @@ -1573,7 +1605,9 @@ similar advice may apply to the unsigned counterparts (e.g., of @code{intptr_t}). @item -Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF. +Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF@. +More generally, prefer @code{int} for integers known to be in +@code{int} range, e.g., screen column counts. @item Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the @@ -1585,6 +1619,17 @@ anyway since they would break pointer subtraction, so this does not impose an arbitrary limit. @item +Avoid @code{ssize_t} except when communicating to low-level APIs that +have @code{ssize_t}-related limitations. Although it's equivalent to +@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally +narrower, so using it for size-related calculations could overflow. +Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has +standard @code{printf} formats, and is the basis for Emacs's internal +size-overflow checking. When using @code{ssize_t}, please note that +POSIX requires support only for values in the range @minus{}1 ..@: +@code{SSIZE_MAX}. + +@item Prefer @code{intptr_t} for internal representations of pointers, or for integers bounded only by the number of objects that can exist at any given time or by the total number of bytes that can be allocated. @@ -1606,7 +1651,7 @@ although @code{off_t} is always signed, @code{time_t} need not be. @item Prefer the Emacs-defined type @code{printmax_t} for representing -values that might be any signed integer value that can be printed, +values that might be any signed integer that can be printed, using a @code{printf}-family function. @item @@ -1614,20 +1659,21 @@ Prefer @code{intmax_t} for representing values that might be any signed integer value. @item -In bitfields, prefer @code{unsigned int} or @code{signed int} to -@code{int}, as @code{int} is less portable: it might be signed, and -might not be. Single-bit bit fields are invariably @code{unsigned -int} so that their values are 0 and 1. - -@item -In C, Emacs commonly uses @code{bool}, 1, and 0 for boolean values. -Using @code{bool} for booleans can make programs easier to read and a -bit faster than using @code{int}. Although it is also OK to use -@code{int}, this older style is gradually being phased out. When +Prefer @code{bool}, @code{false} and @code{true} for booleans. +Using @code{bool} can make programs easier to read and a bit faster than +using @code{int}. Although it is also OK to use @code{int}, @code{0} +and @code{1}, this older style is gradually being phased out. When using @code{bool}, respect the limitations of the replacement implementation of @code{bool}, as documented in the source file -@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99 -platforms. +@file{lib/stdbool.in.h}. In particular, boolean bitfields should be of type +@code{bool_bf}, not @code{bool}, so that they work correctly even when +compiling Objective C with standard GCC. + +@item +In bitfields, prefer @code{unsigned int} or @code{signed int} to +@code{int}, as @code{int} is less portable: it might be signed, and +might not be. Single-bit bit fields should be @code{unsigned int} or +@code{bool_bf} so that their values are 0 or 1. @end itemize @c FIXME Mention src/globals.h somewhere in this file? diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 803e5229f6e..865c6984864 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -1,6 +1,6 @@ @c -*-coding: utf-8-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Introduction @@ -9,7 +9,7 @@ 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 +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. @@ -148,8 +148,8 @@ manual. You may want to skip this section and refer back to it later. 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 +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 typographic conventions @@ -287,7 +287,7 @@ the echo area. @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 +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 @@ -456,7 +456,7 @@ 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 +variable. @defvar electric-future-map The value of this variable is a full keymap used by Electric Command @@ -480,8 +480,8 @@ running. It is useful to include this string in bug reports. @smallexample @group (emacs-version) - @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) - of 2009-06-01 on cyd.mit.edu" + @result{} "GNU Emacs 24.5.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.16) + of 2015-06-01" @end group @end smallexample @@ -545,11 +545,11 @@ Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper Harder, 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, Stefan Monnier, Skip -Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, +Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potortì, Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. For a more complete list of contributors, please see the relevant -ChangeLog file in the Emacs sources. +change log entries in the Emacs source repository. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ef020364082..9bea4b0af1c 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Keymaps @chapter Keymaps @@ -622,75 +622,67 @@ string for the keymap. The prompt string should be given for menu keymaps @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, -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 (if the -underlying buffer text contains map properties in its text properties -or overlays, they are ignored). - - 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. - -The very highest precedence keymap comes from -@code{overriding-terminal-local-map}; it operates on a per-terminal basis and -is normally used for modal/transient keybindings. -@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. + Emacs contains many keymaps, but at any time only a few keymaps are +@dfn{active}. When Emacs receives user input, it translates the input +event (@pxref{Translation Keymaps}), and looks for a key binding in +the active keymaps. + + Usually, the active keymaps are: (i) the keymap specified by the +@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii) +the current buffer's local keymap, and (iv) the global keymap, in that +order. Emacs searches for each input key sequence in all these +keymaps. + + Of these usual keymaps, the highest-precedence one is specified +by the @code{keymap} text or overlay property at point, if any. (For +a mouse input event, Emacs uses the event position instead of point; +@iftex +see the next section for details.) +@end iftex +@ifnottex +@pxref{Searching Keymaps}.) +@end ifnottex + + Next in precedence are keymaps specified by enabled minor modes. +These keymaps, if any, are specified by the variables +@code{emulation-mode-map-alists}, +@code{minor-mode-overriding-map-alist}, and +@code{minor-mode-map-alist}. @xref{Controlling Active Maps}. - 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. +@cindex local keymap + Next in precedence is the buffer's @dfn{local keymap}, containing +key bindings specific to the buffer. The minibuffer also has a local +keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map} +text or overlay property at point, that specifies the local keymap to +use, in place of the buffer's default local keymap. - The minibuffer has local keymaps, too; they contain various completion -and exit commands. @xref{Intro to Minibuffers}. +@cindex major mode keymap + The local keymap is normally set by the buffer's major mode, and +every buffer with the same major mode shares the same local keymap. +Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands}) +to change the local keymap in one buffer, that also affects the local +keymaps in other buffers with the same major mode. - Emacs has other keymaps that are used in a different way---translating -events within @code{read-key-sequence}. @xref{Translation Keymaps}. +@cindex global keymap + Finally, the @dfn{global keymap} contains key bindings that are +defined regardless of the current buffer, such as @kbd{C-f}. It is +always active, and is bound to the variable @code{global-map}. + + Apart from the above usual keymaps, Emacs provides special ways +for programs to make other keymaps active. Firstly, the variable +@code{overriding-local-map} specifies a keymap that replaces the usual +active keymaps, except for the global keymap. Secondly, the +terminal-local variable @code{overriding-terminal-local-map} specifies +a keymap that takes precedence over @emph{all} other keymaps +(including @code{overriding-local-map}); this is normally used for +modal/transient keybindings (the function @code{set-transient-map} +provides a convenient interface for this). @xref{Controlling Active +Maps}, for details. + + Making keymaps active is not the only way to use them. Keymaps are +also used in other ways, such as for translating events within +@code{read-key-sequence}. @xref{Translation Keymaps}. @xref{Standard Keymaps}, for a list of some standard keymaps. @@ -727,7 +719,7 @@ 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. +Emacs signals an error if @var{key} is not a string or a vector. @example @group @@ -741,49 +733,56 @@ An error is signaled if @var{key} is not a string or a vector. @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: +Here is a pseudo-Lisp summary of how Emacs searches the active +keymaps: @lisp -(or (cond - (overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map)) - (overriding-local-map - (@var{find-in} overriding-local-map)) - ((or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in} @var{temp-map}) +(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-local-map))))) (@var{find-in} (current-global-map))) @end lisp @noindent -@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, 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. @var{temp-map} is a pseudo variable that -represents the effect of a @code{set-temporary-overlay-map} call. - - 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. - - The function finally found might also be remapped. @xref{Remapping -Commands}. +Here, @var{find-in} and @var{find-in-any} are pseudo functions that +search in one keymap and in an alist of keymaps, respectively. Note +that the @code{set-transient-map} function works by setting +@code{overriding-terminal-local-map} (@pxref{Controlling Active +Maps}). + + In the above pseudo-code, if a key sequence starts with a mouse +event (@pxref{Mouse Events}), that event's position is used instead of +point, and the event's buffer is used instead of the current buffer. +In particular, this affects how the @code{keymap} and @code{local-map} +properties are looked up. If a mouse event occurs on a string +embedded with a @code{display}, @code{before-string}, or +@code{after-string} property (@pxref{Special Properties}), and the +string has a non-@code{nil} @code{keymap} or @code{local-map} +property, that overrides the corresponding property in the underlying +buffer text (i.e., the property specified by the underlying text is +ignored). + + When a key binding is found in one of the active keymaps, and that +binding is a command, the search is over---the command is executed. +However, if the binding 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. @xref{Key +Lookup}. + + The command which is finally found might also be remapped. +@xref{Remapping Commands}. @node Controlling Active Maps @section Controlling the Active Keymaps +@cindex active keymap, controlling @defvar global-map This variable contains the default global keymap that maps Emacs @@ -857,7 +856,6 @@ 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 @@ -942,28 +940,34 @@ 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 +This variable holds a list of keymap alists to use for emulation 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 +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 -@defun set-temporary-overlay-map keymap &optional keep -This function adds @var{keymap} as a temporary keymap that takes -precedence over most other keymaps. It does not take precedence over -the ``overriding'' maps (see above); and unlike them, if no match for -a key is found in @var{keymap}, the search continues. - -Normally, @var{keymap} is used only once. If the optional argument -@var{pred} is @code{t}, the map stays active if a key from @var{keymap} -is used. @var{pred} can also be a function of no arguments: if it returns -non-@code{nil} then @var{keymap} stays active. - -For a pseudo-Lisp description of exactly how and when this keymap applies, -@pxref{Searching Keymaps}. +@cindex transient keymap +@defun set-transient-map keymap &optional keep +This function adds @var{keymap} as a @dfn{transient} keymap, which +takes precedence over other keymaps for one (or more) subsequent keys. + +Normally, @var{keymap} is used just once, to look up the very next +key. If the optional argument @var{pred} is @code{t}, the map stays +active as long as the user types keys defined in @var{keymap}; when +the user types a key that is not in @var{keymap}, the transient keymap +is deactivated and normal key lookup continues for that key. + +The @var{pred} argument can also be a function. In that case, the +function is called with no arguments, prior to running each command, +while @var{keymap} is active; it should return non-@code{nil} if +@var{keymap} should stay active. + +This function works by adding and removing @code{keymap} from the +variable @code{overriding-terminal-local-map}, which takes precedence +over all other active keymaps (@pxref{Searching Keymaps}). @end defun @node Key Lookup @@ -979,7 +983,7 @@ not part of key lookup. 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, +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 @@ -1040,22 +1044,6 @@ 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} @@ -1063,9 +1051,7 @@ binding of @kbd{Meta-@key{SPC}}, whatever that may be''. 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. +a keymap, a command, or a keyboard macro. Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its @@ -1083,7 +1069,7 @@ thing that is done automatically for an undefined key: it rings the bell @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 +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. @@ -1094,8 +1080,7 @@ 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}. +macro, a symbol that leads to one of them, or @code{nil}. @node Functions for Key Lookup @section Functions for Key Lookup @@ -1123,7 +1108,7 @@ the other functions described in this chapter that look up keys use @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'' +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. @@ -1548,32 +1533,36 @@ specifies a list of keymaps to search in. This argument is ignored if @node Translation Keymaps @section Keymaps for Translating Sequences of Events +@cindex translation keymap @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{input-decode-map}, then -@code{local-function-key-map}, and then against @code{key-translation-map}. - -These keymaps have the same structure as other keymaps, but they are used -differently: they specify translations to make while reading key sequences, -rather than bindings for key sequences. - -If one of these keymaps ``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{input-decode-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]}. + When the @code{read-key-sequence} function reads a key sequence +(@pxref{Key Sequence Input}), it uses @dfn{translation keymaps} to +translate certain event sequences into others. The translation +keymaps are @code{input-decode-map}, @code{local-function-key-map}, +and @code{key-translation-map} (in order of priority). + + Translation keymaps have the same structure as other keymaps, but +are used differently: they specify translations to make while reading +key sequences, rather than bindings for complete key sequences. As +each key sequence is read, it is checked against each translation +keymap. If one of the translation keymaps binds @var{k} to a +vector @var{v}, then whenever @var{k} appears as a sub-sequence +@emph{anywhere} in a key sequence, that sub-sequence is replaced with +the events in @var{v}. + + For example, VT100 terminals send @kbd{@key{ESC} O P} when the +keypad key @key{PF1} is pressed. On such terminals, Emacs must +translate that sequence of events into a single event @code{pf1}. +This is done by binding @kbd{@key{ESC} O P} to @code{[pf1]} in +@code{input-decode-map}. Thus, when you type @kbd{C-c @key{PF1}} on +the terminal, the terminal emits the character sequence @kbd{C-c +@key{ESC} O P}, and @code{read-key-sequence} translates this back into +@kbd{C-c @key{PF1}} and returns it as the vector @code{[?\C-c pf1]}. + + Translation keymaps take effect only after Emacs has decoded the +keyboard input (via the input coding system specified by +@code{keyboard-coding-system}). @xref{Terminal I/O Encoding}. @defvar input-decode-map This variable holds a keymap that describes the character sequences sent @@ -1626,7 +1615,7 @@ to @code{self-insert-command}. @cindex key translation function You can use @code{input-decode-map}, @code{local-function-key-map}, and @code{key-translation-map} for more than simple aliases, by using -a function, instead of a key sequence, as the ``translation'' of a +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. @@ -1661,10 +1650,6 @@ to turn the character that follows into a Hyper character: @end group @end example - If you have enabled keyboard character set decoding using -@code{set-keyboard-coding-system}, decoding is done before the -translations listed above. @xref{Terminal I/O Encoding}. - @subsection Interaction with normal keymaps The end of a key sequence is detected when that key sequence either is bound @@ -1732,14 +1717,14 @@ 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 +(global-set-key "ö" 'my-function) ; bind o-umlaut @end smallexample @noindent or @smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut +(global-set-key ?ö 'my-function) ; bind o-umlaut @end smallexample @noindent @@ -1822,6 +1807,8 @@ local map. @node Scanning Keymaps @section Scanning Keymaps +@cindex scanning keymaps +@cindex keymaps, scanning This section describes functions used to scan all the current keymaps for the sake of printing help information. @@ -1942,9 +1929,9 @@ 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. +If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't look +inside menu-items to find their commands. This makes it possible to search for +a menu-item itself. The fifth argument, @var{no-remap}, determines how this function treats command remappings (@pxref{Remapping Commands}). There are two @@ -2023,7 +2010,7 @@ which is a string that appears as an element of the keymap. 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 +toolkit, e.g., on a text terminal.} Keyboard menus also display the overall prompt string. The easiest way to construct a keymap with a prompt string is to @@ -2084,7 +2071,7 @@ the GTK+ toolkit). @end example @noindent -@var{help} specifies a ``help-echo'' string to display while the mouse +@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}). @@ -2101,7 +2088,7 @@ the menu but cannot be selected. 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 +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 @@ -2157,7 +2144,7 @@ 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 +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} @@ -2169,7 +2156,7 @@ 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'' +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 @@ -2187,7 +2174,7 @@ 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 +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 @@ -2316,7 +2303,7 @@ 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'' + 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 @@ -2331,7 +2318,7 @@ items. Here's an example that makes two aliases for @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 +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, @@ -2371,16 +2358,17 @@ if the menu keymap contains a single nested keymap and no other menu items, the menu shows the contents of the nested keymap directly, not as a submenu. - However, if Emacs is compiled without X toolkit support, submenus -are not supported. Each nested keymap is shown as a menu item, but -clicking on it does not automatically pop up the submenu. If you wish -to imitate the effect of submenus, you can do that by giving a nested -keymap an item string which starts with @samp{@@}. This causes Emacs -to display the nested keymap using a separate @dfn{menu pane}; the -rest of the item string after the @samp{@@} is the pane label. If -Emacs is compiled without X toolkit support, menu panes are not used; -in that case, a @samp{@@} at the beginning of an item string is -omitted when the menu label is displayed, and has no other effect. + However, if Emacs is compiled without X toolkit support, or on text +terminals, submenus are not supported. Each nested keymap is shown as +a menu item, but clicking on it does not automatically pop up the +submenu. If you wish to imitate the effect of submenus, you can do +that by giving a nested keymap an item string which starts with +@samp{@@}. This causes Emacs to display the nested keymap using a +separate @dfn{menu pane}; the rest of the item string after the +@samp{@@} is the pane label. If Emacs is compiled without X toolkit +support, or if a menu is displayed on a text terminal, menu panes are +not used; in that case, a @samp{@@} at the beginning of an item string +is omitted when the menu label is displayed, and has no other effect. @node Keyboard Menus @subsection Menus and the Keyboard @@ -2439,19 +2427,19 @@ Next we define the menu items: @end smallexample @noindent -Note the symbols which the bindings are ``made for''; these appear +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 +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 +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 +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. @@ -2485,17 +2473,17 @@ can do it this way: @subsection The Menu Bar @cindex menu bar - On graphical displays, there is usually a @dfn{menu bar} at the top -of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu -bar items are subcommands of the fake ``function key'' -@code{menu-bar}, as defined in the active keymaps. + Emacs usually shows a @dfn{menu bar} at the top of each frame. +@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are +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 + 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 ``function key'' + When more than one active keymap defines the same 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 @@ -2555,7 +2543,7 @@ at the end of the menu bar, following local menu items. @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 +before redisplaying the menu bar. You can use it to update menus 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. @@ -2575,7 +2563,7 @@ in Documentation}. A @dfn{tool bar} is a row of clickable icons at the top of a frame, just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs -Manual}. +Manual}. Emacs normally shows a tool bar on graphical displays. On each frame, the frame parameter @code{tool-bar-lines} controls how many lines' worth of height to reserve for the tool bar. A zero @@ -2586,7 +2574,7 @@ If the value is @code{grow-only}, the tool bar expands automatically, but does not contract automatically. 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 +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: @@ -2595,7 +2583,7 @@ bar is controlled). So you define a tool bar item using @end example @noindent -where @var{key} is a fake ``function key'' to distinguish this item from +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. @@ -2605,7 +2593,7 @@ 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 + 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}). @@ -2630,6 +2618,9 @@ Used when the item is disabled and deselected. @end table @end table +The GTK+ and NS versions of Emacs ignores items 1 to 3, because disabled and/or +deselected images are autocomputed from item 0. + 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. @@ -2753,7 +2744,7 @@ The value is an integer, a number of pixels. The default is 1. @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. +bar area. An integer 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. @@ -2787,6 +2778,7 @@ function keys. @node Modifying Menus @subsection Modifying Menus +@cindex menu modification 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 @@ -2894,7 +2886,7 @@ Documentation}). @item :key-sequence @var{keys} @var{keys} is a hint for speeding up Emacs's first display of the -menu. It should be nil if you know that the menu item has no keyboard +menu. It should be @code{nil} if you know that the menu item has no keyboard equivalent; otherwise it should be a string or vector specifying a keyboard equivalent for the menu item. @@ -2922,7 +2914,7 @@ anything else (meaning an ordinary menu item). @item :selected @var{selected} @var{selected} is an expression; the checkbox or radio button is -selected whenever the expression's value is non-nil. +selected whenever the expression's value is non-@code{nil}. @item :help @var{help} @var{help} is a string describing the menu item. diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi index f12e724d6a9..04aabd814fc 100644 --- a/doc/lispref/lay-flat.texi +++ b/doc/lispref/lay-flat.texi @@ -1,11 +1,12 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 2001-2015 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 +@include docstyle.texi @smallbook @comment %**end of header @@ -20,9 +21,9 @@ 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. +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 +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. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 9daf01cd0a2..48e1b57eede 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lists @@ -41,7 +41,7 @@ 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 + 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 @@ -84,6 +84,8 @@ structure made out of cons cells as a @dfn{list structure}. @node List-related Predicates @section Predicates on Lists +@cindex predicates for lists +@cindex list predicates 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 @@ -601,25 +603,6 @@ 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 @@ -646,8 +629,8 @@ 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 +All arguments are numbers. +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 @@ -681,6 +664,8 @@ Some examples: @node List Variables @section Modifying List Variables +@cindex modify a list +@cindex list modification These functions, and one macro, provide convenient ways to modify a list which is stored in a variable. @@ -814,7 +799,7 @@ foo ;; @r{@code{foo} was changed.} @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'' +primitives @code{setcar} and @code{setcdr}. These are destructive operations because they change existing list structure. @cindex CL note---@code{rplaca} vs @code{setcar} @@ -837,6 +822,8 @@ new @sc{car} or @sc{cdr}. @node Setcar @subsection Altering List Elements with @code{setcar} +@cindex replace list element +@cindex list, replace element 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 @@ -942,6 +929,7 @@ x2: | @node Setcdr @subsection Altering the CDR of a List +@cindex replace part of list The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: @@ -1044,11 +1032,12 @@ x1 @node Rearrangement @subsection Functions that Rearrange Lists @cindex rearrangement of lists +@cindex reordering, of elements in 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 + Here are some functions that rearrange lists destructively by +modifying the @sc{cdr}s of their component cons cells. These functions +are 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. @@ -1142,126 +1131,6 @@ each time you run it! Here is what happens: @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 @@ -1404,7 +1273,7 @@ sample-list @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. +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}. @@ -1653,7 +1522,7 @@ 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. +this as reverse @code{assoc}, finding the key for a given value. @end defun @defun assq key alist @@ -1694,7 +1563,7 @@ 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. +this as reverse @code{assq}, finding the key for a given value. For example: @@ -1897,6 +1766,8 @@ and later discarded; this is not possible with a property list. @node Plist Access @subsection Property Lists Outside Symbols +@cindex plist access +@cindex accessing plist properties The following functions can be used to manipulate property lists. They all compare property names using @code{eq}. diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index dab8e8d1255..82de765876e 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Loading @@ -29,6 +29,8 @@ into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. +For on-demand loading of external libraries, @pxref{Dynamic Libraries}. + @menu * How Programs Do Loading:: The @code{load} function and others. * Load Suffixes:: Details about the suffixes that @code{load} tries. @@ -38,7 +40,7 @@ definitions. * 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. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @end menu @@ -74,7 +76,7 @@ If Auto Compression mode is enabled, as it is by default, then if 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 +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 @@ -91,6 +93,10 @@ If the optional argument @var{must-suffix} is non-@code{nil}, then @samp{.el} or @samp{.elc} (possibly extended with a compression suffix), unless it contains an explicit directory name. +If the option @code{load-prefer-newer} is non-@code{nil}, then when +searching suffixes, @code{load} selects whichever version of a file +(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. + 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 @@ -244,6 +250,12 @@ value of @code{(get-load-suffixes)} and then those in it skips the former group, and if @var{must-suffix} is non-@code{nil}, it skips the latter group. +@defopt load-prefer-newer +If this option is non-@code{nil}, then rather than stopping at the +first suffix that exists, @code{load} tests them all, and uses +whichever file is the newest. +@end defopt + @node Library Search @section Library Search @cindex library search @@ -253,37 +265,41 @@ it skips the latter group. in a list of directories specified by the variable @code{load-path}. @defvar load-path -@cindex @env{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 defvar - Each time Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} to the -directories specified by the environment variable @env{EMACSLOADPATH}, -if that exists. The syntax of @env{EMACSLOADPATH} is the same as used -for @code{PATH}; directory names are separated by @samp{:} (or -@samp{;}, on some operating systems), and @samp{.} stands for the -current default directory. Here is an example of how to set -@env{EMACSLOADPATH} variable from @command{sh}: + When Emacs starts up, it sets up the value of @code{load-path} +in several steps. First, it initializes @code{load-path} using +default locations set when Emacs was compiled. Normally, this +is a directory something like @example -export EMACSLOADPATH -EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp +"/usr/local/share/emacs/@var{version}/lisp" @end example -@noindent -Here is how to set it from @code{csh}: - -@example -setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp -@end example +(In this and the following examples, replace @file{/usr/local} with +the installation prefix appropriate for your Emacs.) +These directories contain the standard Lisp files that come with +Emacs. If Emacs cannot find them, it will not start correctly. + +If you run Emacs from the directory where it was built---that is, an +executable that has not been formally installed---Emacs instead +initializes @code{load-path} using the @file{lisp} +directory in the directory containing the sources from which it +was built. +@c Though there should be no *.el files in builddir/lisp, so it's pointless. +If you built Emacs in a separate directory from the +sources, it also adds the lisp directories from the build directory. +(In all cases, elements are represented as absolute file names.) @cindex site-lisp directories - If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs -initializes @code{load-path} with the following two directories: +Unless you start Emacs with the @option{--no-site-lisp} option, +it then adds two more @file{site-lisp} directories to the front of +@code{load-path}. These are intended for locally installed Lisp files, +and are normally of the form: @example "/usr/local/share/emacs/@var{version}/site-lisp" @@ -297,26 +313,54 @@ and @end example @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. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs puts two more -directories in @code{load-path}. These are the @code{lisp} and -@code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - - Next, Emacs ``expands'' the initial list of directories in -@code{load-path} by adding the subdirectories of those directories. -Both immediate subdirectories and subdirectories multiple levels down -are added. But it excludes subdirectories whose names do not start -with a letter or digit, and subdirectories named @file{RCS} or -@file{CVS}, and subdirectories containing a file named -@file{.nosearch}. - - Next, Emacs adds any extra load directory that you specify using the -@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The +The first one is for locally installed files for a specific Emacs +version; the second is for locally installed files meant for use +with all installed Emacs versions. (If Emacs is running uninstalled, +it also adds @file{site-lisp} directories from the source and build +directories, if they exist. Normally these directories do not contain +@file{site-lisp} directories.) + +@cindex @env{EMACSLOADPATH} environment variable +If the environment variable @env{EMACSLOADPATH} is set, it modifies +the above initialization procedure. Emacs initializes +@code{load-path} based on the value of the environment variable. + +The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH}; +directory names are separated by @samp{:} (or @samp{;}, on some +operating systems). +@ignore +@c AFAICS, does not (yet) work right to specify non-absolute elements. +and @samp{.} stands for the current default directory. +@end ignore +Here is an example of how to set @env{EMACSLOADPATH} variable (from a +@command{sh}-style shell): + +@example +export EMACSLOADPATH=/home/foo/.emacs.d/lisp: +@end example + +An empty element in the value of the environment variable, whether +trailing (as in the above example), leading, or embedded, is replaced +by the default value of @code{load-path} as determined by the standard +initialization procedure. If there are no such empty elements, then +@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must +include either an empty element, or the explicit path to the directory +containing the standard Lisp files, else Emacs will not function. +(Another way to modify @code{load-path} is to use the @option{-L} +command-line option when starting Emacs; see below.) + + For each directory in @code{load-path}, Emacs then checks to see if +it contains a file @file{subdirs.el}, and if so, loads it. The +@file{subdirs.el} file is created when Emacs is built/installed, +and contains code that causes Emacs to add any subdirectories of those +directories to @code{load-path}. Both immediate subdirectories and +subdirectories multiple levels down are added. But it excludes +subdirectories whose names do not start with a letter or digit, and +subdirectories named @file{RCS} or @file{CVS}, and subdirectories +containing a file named @file{.nosearch}. + + Next, Emacs adds any extra load directories that you specify using the +@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The GNU Emacs Manual}). It also adds the directories where optional packages are installed, if any (@pxref{Packaging Basics}). @@ -327,12 +371,10 @@ add one or more directories to @code{load-path}. For example: (push "~/.emacs.d/lisp" load-path) @end example - 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. + Dumping Emacs uses a special value of @code{load-path}. If you use +a @file{site-load.el} or @file{site-init.el} file to customize the +dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} +that these files make will be lost after dumping. @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It @@ -377,6 +419,8 @@ the shadowed files as a string. @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters +@cindex loading, and non-ASCII characters +@cindex non-ASCII characters in loaded files When Emacs Lisp programs contain string constants with non-@acronym{ASCII} characters, these can be represented within Emacs either as unibyte @@ -412,7 +456,7 @@ Autoloading can also be triggered by looking up the documentation of the function or macro (@pxref{Documentation Basics}). There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the +@code{autoload}, and by writing a ``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 @@ -624,7 +668,7 @@ value of this variable is @code{";;;###autoload"}. @defvar generated-autoload-file The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a +override that, e.g., in the local variables section of a @file{.el} file (@pxref{File Local Variables}). The autoload file is assumed to contain a trailer starting with a formfeed character. @end defvar @@ -865,6 +909,8 @@ with a call to @code{provide}. The order of the elements in the @node Where Defined @section Which File Defined a Certain Symbol +@cindex symbol, where defined +@cindex where was a symbol defined @defun symbol-file symbol &optional type This function returns the name of the file that defined @var{symbol}. diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 5520bbbd1df..a90c6f1da6f 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1995, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Macros @@ -55,6 +55,11 @@ expansion, which is @code{(setq x (1+ x))}. Once the macro definition returns this expansion, Lisp proceeds to evaluate it, thus incrementing @code{x}. +@defun macrop object +This predicate tests whether its argument is a macro, and returns +@code{t} if so, @code{nil} otherwise. +@end defun + @node Expansion @section Expansion of a Macro Call @cindex expansion of macros @@ -189,10 +194,12 @@ During Compile}). @node Defining Macros @section Defining Macros +@cindex defining macros +@cindex macro, how to define A Lisp macro object is a list whose @sc{car} is @code{macro}, and -whose @sc{cdr} is a lambda expression. Expansion of the macro works -by applying the lambda expression (with @code{apply}) to the list of +whose @sc{cdr} is a function. Expansion of the macro works +by applying the function (with @code{apply}) to the list of @emph{unevaluated} arguments from the macro call. It is possible to use an anonymous Lisp macro just like an anonymous @@ -248,6 +255,7 @@ Form}. @node Problems with Macros @section Common Problems Using Macros +@cindex macro caveats Macro expansion can have counterintuitive consequences. This section describes some important consequences that can lead to @@ -299,7 +307,7 @@ program is actually run. 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 ``for'' loop construct. +problem. This macro allows us to write a for-loop construct. @findex for @example @@ -337,7 +345,7 @@ For example, (for i from 1 to 10 do (print i))." @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 +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. @@ -560,7 +568,7 @@ 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 +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 diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in deleted file mode 100644 index 00b938dbf68..00000000000 --- a/doc/lispref/makefile.w32-in +++ /dev/null @@ -1,129 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003-2013 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 of the License, 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. If not, see <http://www.gnu.org/licenses/>. - - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../../info - -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -INFO_EXT=.info -INFO_OPTS=--no-split - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -I$(emacsdir) - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -# List of all the texinfo files in the manual: - -srcs = \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.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)/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)/package.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$(INFO_EXT) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp$(INFO_EXT): $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) $(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 - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) elisp$(INFO_EXT) elisp$(INFO_EXT)-? elisp$(INFO_EXT)-?? elisp.dvi elisp.oaux diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi index d92f6a89f0a..cc127264478 100644 --- a/doc/lispref/maps.texi +++ b/doc/lispref/maps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Keymaps diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index d94908994e9..3eaba419034 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Markers @@ -20,8 +20,8 @@ deleted, so that it stays with the two characters on either side of it. * 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". +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. @end menu @node Overview of Markers @@ -118,6 +118,8 @@ m1 @node Predicates on Markers @section Predicates on Markers +@cindex predicates for markers +@cindex markers, predicates for 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 @@ -141,6 +143,8 @@ integer or floating point) or a marker, @code{nil} otherwise. @node Creating Markers @section Functions that Create Markers +@cindex creating markers +@cindex marker creation 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 @@ -269,6 +273,7 @@ if they both point nowhere. @node Information from Markers @section Information from Markers +@cindex marker information This section describes the functions for accessing the components of a marker object. @@ -282,8 +287,8 @@ This function returns the position that @var{marker} points to, or This function returns the buffer that @var{marker} points into, or @code{nil} if it points nowhere. -@c FIXME: The `buffer' argument of `set-marker' already defaults to -@c the current buffer, why use `(current-buffer)' explicitly here? +@c FIXME: The 'buffer' argument of 'set-marker' already defaults to +@c the current buffer, why use '(current-buffer)' explicitly here? @example @group (setq m (make-marker)) @@ -342,6 +347,8 @@ specify the insertion type, create them with insertion type @node Moving Markers @section Moving Marker Positions +@cindex moving markers +@cindex marker, how to move position 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 @@ -397,7 +404,7 @@ This is another name for @code{set-marker}. Each buffer has a special marker, which is designated @dfn{the mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that +not point anywhere; this means that the mark doesn't exist in that buffer yet. Subsequent commands can set the mark. The mark specifies a position to bound a range of text for many @@ -417,7 +424,7 @@ 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. - Once the mark ``exists'' in a buffer, it normally never ceases to + 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 buffer-local variable @code{mark-active}, if non-@code{nil}, means that the mark is active. A command can call the @@ -613,7 +620,7 @@ This piece of command_loop_1, run unless deactivating the mark: @end defvar @defun handle-shift-selection -This function implements the ``shift-selection'' behavior of +This function implements the shift-selection behavior of point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs Manual}. It is called automatically by the Emacs command loop whenever a command with a @samp{^} character in its @code{interactive} @@ -654,8 +661,8 @@ more marks than this are pushed onto the @code{mark-ring}, @node The Region @section The Region -@c The index entry must be just ``region'' to make it the first hit -@c when the user types ``i region RET'', because otherwise the Info +@c The index entry must be just "region" to make it the first hit +@c when the user types "i region RET", because otherwise the Info @c reader will present substring matches in alphabetical order, @c putting this one near the end, with something utterly unrelated as @c the first hit. @@ -705,4 +712,3 @@ A region is valid if it has a non-zero size, or if the user option cases, you should not use @code{region-active-p}, since if the region is empty it is often more appropriate to operate on point. @end defun - diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 9a1ec477b9f..0b1a4a90ba9 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Minibuffers @@ -81,7 +81,7 @@ there is an active minibuffer; such a minibuffer is called a 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'' +entered) is the active minibuffer. We usually call this @emph{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 (@xref{Recursive Mini}.) @@ -101,10 +101,13 @@ the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. 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. +was supplied when Emacs was started. This supports only basic input: +none of the special minibuffer features (history, completion, etc.)@: +are available in batch mode. @node Text from Minibuffer @section Reading Text Strings with the Minibuffer +@cindex minibuffer input, reading text strings The most basic primitive for minibuffer input is @code{read-from-minibuffer}, which can be used to read either a string @@ -211,25 +214,39 @@ This function works by calling the @end smallexample @end defun -@defun read-regexp prompt &optional default history +@defun read-regexp prompt &optional defaults history This function reads a regular expression as a string from the -minibuffer and returns it. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. +minibuffer and returns it. If the minibuffer prompt string +@var{prompt} does not end in @samp{:} (followed by optional +whitespace), the function adds @samp{: } to the end, preceded by the +default return value (see below), if that is non-empty. -The optional argument @var{default} specifies a default value to -return if the user enters null input; it should be a string, or -@code{nil}, which is equivalent to an empty string. +The optional argument @var{defaults} controls the default value to +return if the user enters null input, and should be one of: a string; +@code{nil}, which is equivalent to an empty string; a list of strings; +or a symbol. -The optional argument @var{history}, if non-@code{nil}, is a symbol -specifying a minibuffer history list to use (@pxref{Minibuffer -History}). If it is omitted or @code{nil}, the history list defaults -to @code{regexp-history}. +If @var{defaults} is a symbol, @code{read-regexp} consults the value +of the variable @code{read-regexp-defaults-function} (see below), and +if that is non-@code{nil} uses it in preference to @var{defaults}. +The value in this case should be either: -@code{read-regexp} also collects a few useful candidates for input and -passes them to @code{read-from-minibuffer}, to make them available to -the user as the ``future minibuffer history list'' (@pxref{Minibuffer -History, future list,, emacs, The GNU Emacs Manual}). These -candidates are: +@itemize @minus +@item +@code{regexp-history-last}, which means to use the first element of +the appropriate minibuffer history list (see below). + +@item +A function of no arguments, whose return value (which should be +@code{nil}, a string, or a list of strings) becomes the value of +@var{defaults}. +@end itemize + +@code{read-regexp} now ensures that the result of processing +@var{defaults} is a list (i.e., if the value is @code{nil} or a +string, it converts it to a list of one element). To this list, +@code{read-regexp} then appends a few potentially useful candidates for +input. These are: @itemize @minus @item @@ -242,10 +259,37 @@ The last string used in an incremental search. The last string or pattern used in query-replace commands. @end itemize -This function works by calling the @code{read-from-minibuffer} -function, after computing the list of defaults as described above. +The function now has a list of regular expressions that it passes to +@code{read-from-minibuffer} to obtain the user's input. The first +element of the list is the default result in case of empty input. All +elements of the list are available to the user as the ``future +minibuffer history'' list (@pxref{Minibuffer History, future list,, +emacs, The GNU Emacs Manual}). + +The optional argument @var{history}, if non-@code{nil}, is a symbol +specifying a minibuffer history list to use (@pxref{Minibuffer +History}). If it is omitted or @code{nil}, the history list defaults +to @code{regexp-history}. @end defun +@defvar read-regexp-defaults-function +The function @code{read-regexp} may use the value of this variable to +determine its list of default regular expressions. If non-@code{nil}, +the value of this variable should be either: + +@itemize @minus +@item +The symbol @code{regexp-history-last}. + +@item +A function of no arguments that returns either @code{nil}, a string, +or a list of strings. +@end itemize + +@noindent +See @code{read-regexp} above for details of how these values are used. +@end defvar + @defvar minibuffer-allow-text-properties If this variable is @code{nil}, then @code{read-from-minibuffer} and @code{read-string} strip all text properties from the minibuffer @@ -347,6 +391,7 @@ following bindings, in addition to those of @code{minibuffer-local-map}: @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer +@cindex minibuffer input, reading lisp objects This section describes functions for reading Lisp objects with the minibuffer. @@ -678,7 +723,7 @@ just one matching completion, and the match is exact, it returns @code{t}. Otherwise, it returns the longest initial sequence common to all possible matching completions. -If @var{collection} is an list, the permissible completions are +If @var{collection} is a list, the permissible completions are specified by the elements of the list, each of which should be either a string, or a cons cell whose @sc{car} is either a string or a symbol (a symbol is converted to a string using @code{symbol-name}). If the @@ -850,7 +895,7 @@ pertains to the area after @code{"/usr/"} and before @code{"/doc"}. @end defun If you store a completion alist in a variable, you should mark the -variable as ``risky'' by giving it a non-@code{nil} +variable as risky by giving it a non-@code{nil} @code{risky-local-variable} property. @xref{File Local Variables}. @defvar completion-ignore-case @@ -889,6 +934,7 @@ Here is an example: @c FIXME? completion-table-with-context? @findex completion-table-case-fold @findex completion-table-in-turn +@findex completion-table-merge @findex completion-table-subvert @findex completion-table-with-quoting @findex completion-table-with-predicate @@ -897,9 +943,10 @@ Here is an example: @cindex completion tables, combining There are several functions that take an existing completion table and return a modified version. @code{completion-table-case-fold} returns -a case-insensitive table. @code{completion-table-in-turn} combines -multiple input tables. @code{completion-table-subvert} alters a table -to use a different initial prefix. @code{completion-table-with-quoting} +a case-insensitive table. @code{completion-table-in-turn} and +@code{completion-table-merge} combine multiple input tables in +different ways. @code{completion-table-subvert} alters a table to use +a different initial prefix. @code{completion-table-with-quoting} returns a table suitable for operating on quoted text. @code{completion-table-with-predicate} filters a table with a predicate function. @code{completion-table-with-terminator} adds a @@ -928,6 +975,9 @@ 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}. +@xref{Programmed Completion}, for detailed requirements when +@var{collection} is a function. + The value of the optional argument @var{require-match} determines how the user may exit the minibuffer: @@ -1099,7 +1149,7 @@ The list of completions is displayed as text in a buffer named @file{*Completions*}. @end deffn -@defun display-completion-list completions &optional common-substring +@defun display-completion-list completions 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 @@ -1110,13 +1160,6 @@ 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}. A common way to use it is together with @code{with-output-to-temp-buffer}, like this: @@ -1124,8 +1167,7 @@ common way to use it is together with @example (with-output-to-temp-buffer "*Completions*" (display-completion-list - (all-completions (buffer-string) my-alist) - (buffer-string))) + (all-completions (buffer-string) my-alist))) @end example @end defun @@ -1699,7 +1741,7 @@ possible match, and ignore the match if the predicate returns @item A flag specifying the type of completion operation to perform. This -is one of the following four values: +flag may be one of the following values. @table @code @item nil @@ -1779,6 +1821,13 @@ possible completions of it. You can think of and the interface for programmed completion functions. @end defun +@defun completion-table-with-cache function &optional ignore-case +This is a wrapper for @code{completion-table-dynamic} that saves the +last argument-result pair. This means that multiple lookups with the +same argument only need to call @var{function} once. This can be useful +when a slow operation is involved, such as calling an external process. +@end defun + @node Completion in Buffers @subsection Completion in Ordinary Buffers @cindex inline completion @@ -1831,11 +1880,34 @@ next function in @code{completion-at-point-functions} instead of reporting a completion failure. @end table +Supplying a function for @var{collection} is strongly recommended if +generating the list of completions is an expensive operation. Emacs +may internally call functions in @code{completion-at-point-functions} +many times, but care about the value of @var{collection} for only some +of these calls. By supplying a function for @var{collection}, Emacs +can defer generating completions until necessary. You can use +@var{completion-table-dynamic} to create a wrapper function: + +@smallexample +;; Avoid this pattern. +(let ((beg ...) (end ...) (my-completions (my-make-completions))) + (list beg end my-completions)) + +;; Use this instead. +(let ((beg ...) (end ...)) + (list beg + end + (completion-table-dynamic + (lambda (_) + (my-make-completions))))) +@end smallexample + A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. +function instead of a list as described above. In that case, that +returned function is called, with no argument, and it is entirely +responsible for performing the completion. We discourage this usage; +it is intended to help convert old code to using +@code{completion-at-point}. The first function in @code{completion-at-point-functions} to return a non-@code{nil} value is used by @code{completion-at-point}. The @@ -1889,7 +1961,7 @@ the call. 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 +and @key{DEL} to mean no. It accepts @kbd{C-]} to 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 @@ -1925,7 +1997,7 @@ appears on the screen at a time. 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}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. +The argument @var{seconds} should be a number. @end defun @defun yes-or-no-p prompt @@ -1977,9 +2049,10 @@ Do you really want to remove everything? (yes or no) @node Multiple Queries @section Asking Multiple Y-or-N Questions +@cindex multiple yes-or-no 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 +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 @@ -2050,7 +2123,7 @@ answer); @var{function} is a function of one argument (an object from 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 +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. @@ -2080,8 +2153,10 @@ 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. +not echo the password as the user types it; instead, it echoes +@samp{.} for each character in the password. If you want to apply +another character to hide the password, let-bind the variable +@code{read-hide-char} with that character. 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 @@ -2149,8 +2224,8 @@ contents of the minibuffer before the point. @section Minibuffer Windows @cindex minibuffer windows - These functions access and select minibuffer windows -and test whether they are active. +These functions access and select minibuffer windows, test whether they +are active and control how they get resized. @defun active-minibuffer-window This function returns the currently active minibuffer window, or @@ -2191,8 +2266,33 @@ This function returns non-@code{nil} if @var{window} is the currently active minibuffer window. @end defun +The following two options control whether minibuffer windows are resized +automatically and how large they can get in the process. + +@defopt resize-mini-windows +This option specifies whether minibuffer windows are resized +automatically. The default value is @code{grow-only}, which means that +a minibuffer window by default expands automatically to accommodate the +text it displays and shrinks back to one line as soon as the minibuffer +gets empty. If the value is @code{t}, Emacs will always try to fit the +height of a minibuffer window to the text it displays (with a minimum of +one line). If the value is @code{nil}, a minibuffer window never +changes size automatically. In that case the window resizing commands +(@pxref{Resizing Windows}) can be used to adjust its height. +@end defopt + +@defopt max-mini-window-height +This option provides a maximum height for resizing minibuffer windows +automatically. A floating-point number specifies a fraction of the +frame's height; an integer specifies the maximum number of lines. The +default value is 0.25. +@end defopt + + @node Minibuffer Contents @section Minibuffer Contents +@cindex access minibuffer contents +@cindex minibuffer contents, accessing These functions access the minibuffer prompt and contents. @@ -2224,12 +2324,6 @@ 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, @@ -2322,7 +2416,7 @@ arrives, whichever comes first. The variable @code{minibuffer-message-timeout} specifies the number of seconds to wait in the absence of input. It defaults to 2. If @var{args} is non-@code{nil}, the actual message is obtained by passing @var{string} -and @var{args} through @code{format}. @xref{Formatting Strings}. +and @var{args} through @code{format-message}. @xref{Formatting Strings}. @end defun @deffn Command minibuffer-inactive-mode diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 180fef7241d..a1747707d11 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Modes @@ -69,11 +69,13 @@ 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. +convention. By convention, abnormal hook names end in @samp{-functions}. - By convention, abnormal hook names end in @samp{-functions}. If the -variable's name ends in @samp{-function}, then its value is just a single -function, not a list of functions. +@cindex single-function hook +If the variable's name ends in @samp{-function}, then its value is +just a single function, not a list of functions. @code{add-hook} cannot be +used to modify such a @emph{single function hook}, and you have to use +@code{add-function} instead (@pxref{Advising Functions}). @menu * Running Hooks:: How to run a hook. @@ -114,7 +116,7 @@ This function runs an abnormal hook by calling all the hook functions in @defun run-hook-with-args-until-failure hook &rest args This function runs an abnormal hook by calling each hook function in -turn, stopping if one of them ``fails'' by returning @code{nil}. Each +turn, stopping if one of them fails by returning @code{nil}. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions fails, it returns @code{nil}; otherwise it returns a non-@code{nil} value. @@ -122,54 +124,13 @@ otherwise it returns a non-@code{nil} value. @defun run-hook-with-args-until-success hook &rest args This function runs an abnormal hook by calling each hook function, -stopping if one of them ``succeeds'' by returning a non-@code{nil} +stopping if one of them succeeds by returning a non-@code{nil} value. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions returns a non-@code{nil} value, it returns that value; otherwise it returns @code{nil}. @end defun -@defmac with-wrapper-hook hook args &rest body -This macro runs the abnormal hook @code{hook} as a series of nested -``wrapper functions'' around the @var{body} forms. The effect is -similar to nested @code{around} advices (@pxref{Around-Advice}). - -Each hook function should accept an argument list consisting of a function -@var{fun}, followed by the additional arguments listed in @var{args}. -The first hook function is passed a function @var{fun} that, if it is -called with arguments @var{args}, performs @var{body} (i.e., the default -operation). The @var{fun} passed to each successive hook function is -constructed from all the preceding hook functions (and @var{body}); if -this @var{fun} is called with arguments @var{args}, it does what the -@code{with-wrapper-hook} call would if the preceding hook functions were -the only ones in @var{hook}. - -Each hook function may call its @var{fun} argument as many times as it -wishes, including never. In that case, such a hook function acts to -replace the default definition altogether, and any preceding hook -functions. Of course, a subsequent hook function may do the same thing. - -Each hook function definition is used to construct the @var{fun} passed -to the next hook function in @var{hook}, if any. The last or -``outermost'' @var{fun} is called once to produce the overall effect. - -When might you want to use a wrapper hook? The function -@code{filter-buffer-substring} illustrates a common case. There is a -basic functionality, performed by @var{body}---in this case, to extract -a buffer-substring. Then any number of hook functions can act in -sequence to modify that string, before returning the final result. -A wrapper-hook also allows for a hook function to completely replace the -default definition (by not calling @var{fun}). -@end defmac - -@defun run-hook-wrapped hook wrap-function &rest args -This function is similar to @code{run-hook-with-args-until-success}. -Like that function, it runs the functions on the abnormal hook -@code{hook}, stopping at the first one that returns non-@code{nil}. -Instead of calling the hook functions directly, though, it actually -calls @code{wrap-function} with arguments @code{fun} and @code{args}. -@end defun - @node Setting Hooks @subsection Setting Hooks @@ -385,14 +346,14 @@ 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 +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 +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 +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 @@ -646,10 +607,10 @@ mode command. The default value is @code{lisp-interaction-mode}. @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}. +elements of the form @code{(@var{regexp} . @var{mode})}; this says to +use mode @var{mode} if the file specifies an interpreter which matches +@code{\\`@var{regexp}\\'}. For example, one of the default elements +is @code{("python[0-9.]*" . python-mode)}. @end defvar @defvar magic-mode-alist @@ -741,7 +702,7 @@ mode and minor modes. It uses the @code{documentation} function to retrieve the documentation strings of the major and minor mode commands (@pxref{Accessing Documentation}). -If called from Lisp with a non-nil @var{buffer} argument, this +If called from Lisp with a non-@code{nil} @var{buffer} argument, this function displays the documentation for that buffer's major and minor modes, rather than those of the current buffer. @end deffn @@ -788,7 +749,7 @@ The new mode has its own abbrev table, kept in the variable @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}. +@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 @@ -997,9 +958,9 @@ Menu,,, emacs, The GNU Emacs Manual}). way, specifying @code{tabulated-list-mode} as the second argument (@pxref{Derived Modes}). The body of the @code{define-derived-mode} form should specify the format of the tabulated data, by assigning -values to the variables documented below; then, it should call the -function @code{tabulated-list-init-header} to initialize the header -line. +values to the variables documented below; optionally, it can then call +the function @code{tabulated-list-init-header}, which will populate a +header with the names of the columns. The derived mode should also define a @dfn{listing command}. This, not the mode command, is what the user calls (e.g., @kbd{M-x @@ -1042,7 +1003,7 @@ should have the form @w{@code{(@var{id} @var{contents})}}, where @itemize @item @var{id} is either @code{nil}, or a Lisp object that identifies the -entry. If the latter, the cursor stays on the ``same'' entry when +entry. If the latter, the cursor stays on the same entry when re-sorting entries. Comparison is done with @code{equal}. @item @@ -1094,7 +1055,7 @@ the above variables (in particular, only after setting @code{tabulated-list-format}). @end defun -@defun tabulated-list-print &optional remember-pos +@defun tabulated-list-print &optional remember-pos update This function populates the current buffer with entries. It should be called by the listing command. It erases the buffer, sorts the entries specified by @code{tabulated-list-entries} according to @@ -1104,6 +1065,13 @@ specified by @code{tabulated-list-entries} according to If the optional argument @var{remember-pos} is non-@code{nil}, this function looks for the @var{id} element on the current line, if any, and tries to move to that entry after all the entries are (re)inserted. + +If the optional argument @var{update} is non-@code{nil}, this function +will only erase or add entries that have changed since the last print. +This is several times faster if most entries haven't changed since the +last time this function was called. The only difference in outcome is +that tags placed via @code{tabulated-list-put-tag} will not be removed +from entries that haven't changed (normally all tags are removed). @end defun @node Generic Modes @@ -1124,8 +1092,8 @@ documentation for the mode command. If you do not supply it, 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''. +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. @@ -1161,7 +1129,7 @@ the conventions listed above: (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'. + ;; 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'.") @@ -1506,9 +1474,11 @@ 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.) +Minor modes may bind commands to key sequences consisting of @kbd{C-c} +followed by a punctuation character. However, sequences consisting of +@kbd{C-c} followed by one of @kbd{@{@}<>:;}, or a control character or +digit, are reserved for major modes. Also, @kbd{C-c @var{letter}} is +reserved for users. @xref{Key Binding Conventions}. @node Defining Minor Modes @subsection Defining Minor Modes @@ -1527,7 +1497,7 @@ A positive prefix argument enables the mode, any other prefix argument disables it. From Lisp, an argument of @code{toggle} toggles the mode, whereas an omitted or @code{nil} argument enables the mode. This makes it easy to enable the minor mode in a major mode hook, for example. -If @var{doc} is nil, the macro supplies a default documentation string +If @var{doc} is @code{nil}, the macro supplies a default documentation string explaining the above. By default, it also defines a variable named @var{mode}, which is set to @@ -1683,7 +1653,7 @@ minor modes don't need any. 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 +@var{turn-on}; to turn off the minor mode, it calls @var{mode} with @minus{}1 as argument. Globally enabling the mode also affects buffers subsequently created @@ -1812,7 +1782,7 @@ 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 +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 @@ -2258,6 +2228,12 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). It is normally @code{nil}, so that ordinary buffers have no header line. @end defvar +@defun window-header-line-height &optional window +This function returns the height in pixels of @var{window}'s header +line. @var{window} must be a live window, and defaults to the +selected window. +@end defun + 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 @@ -2432,10 +2408,10 @@ variables @code{imenu-prev-index-position-function} and @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 +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 +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. @@ -2483,7 +2459,7 @@ Selecting a special element performs: A nested sub-alist element looks like this: @example -(@var{menu-title} @var{sub-alist}) +(@var{menu-title} . @var{sub-alist}) @end example It creates the submenu @var{menu-title} specified by @var{sub-alist}. @@ -2551,7 +2527,7 @@ 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{}]]]]) + [@var{syntax-alist} @var{other-vars}@dots{}]]]) @end example The first element, @var{keywords}, indirectly specifies the value of @@ -2583,11 +2559,6 @@ fontification; the resulting syntax table is stored in @code{nil}, syntactic fontification uses the syntax table returned by the @code{syntax-table} function. @xref{Syntax Table Functions}. -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 @@ -3050,7 +3021,7 @@ default value is the symbol itself. Thus, the default value of @code{font-lock-comment-face} is @code{font-lock-comment-face}. The faces are listed with descriptions of their typical usage, and in -order of greater to lesser ``prominence''. If a mode's syntactic +order of greater to lesser prominence. If a mode's syntactic categories do not fit well with the usage descriptions, the faces can be assigned using the ordering as a guide. @@ -3148,26 +3119,6 @@ is @code{nil}, syntactic fontification uses the buffer's syntax table Table Functions}). @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. The value is normally set through an -@var{other-vars} element in @code{font-lock-defaults}. If it is -@code{nil}, Font Lock uses @code{syntax-begin-function} to move back -outside of any comment, string, or sexp (@pxref{Position Parse}). - -This variable is semi-obsolete; we usually recommend setting -@code{syntax-begin-function} instead. One of its uses is to tune the -behavior of syntactic fontification, e.g., to ensure that different -kinds of strings or comments are highlighted differently. - -The specified 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. -@end defvar - @defvar font-lock-syntactic-face-function If this variable is non-@code{nil}, it should be a function to determine which face to use for a given syntactic element (a string or a comment). @@ -3331,18 +3282,28 @@ reasonably fast. @section Automatic Indentation of code For programming languages, an important feature of a major mode is to -provide automatic indentation. This is controlled in Emacs by -@code{indent-line-function} (@pxref{Mode-Specific Indent}). -Writing a good indentation function can be difficult and to a large -extent it is still a black art. - -Many major mode authors will start by writing a simple indentation -function that works for simple cases, for example by comparing with the -indentation of the previous text line. For most programming languages -that are not really line-based, this tends to scale very poorly: -improving such a function to let it handle more diverse situations tends -to become more and more difficult, resulting in the end with a large, -complex, unmaintainable indentation function which nobody dares to touch. +provide automatic indentation. There are two parts: one is to decide what +is the right indentation of a line, and the other is to decide when to +reindent a line. By default, Emacs reindents a line whenever you +type a character in @code{electric-indent-chars}, which by default only +includes Newline. Major modes can add chars to @code{electric-indent-chars} +according to the syntax of the language. + +Deciding what is the right indentation is controlled in Emacs by +@code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes, +the @emph{right} indentation cannot be known reliably, typically because +indentation is significant so several indentations are valid but with different +meanings. In that case, the mode should set @code{electric-indent-inhibit} to +make sure the line is not constantly re-indented against the user's wishes. + +Writing a good indentation function can be difficult and to a large extent it +is still a black art. Many major mode authors will start by writing a simple +indentation function that works for simple cases, for example by comparing with +the indentation of the previous text line. For most programming languages that +are not really line-based, this tends to scale very poorly: improving +such a function to let it handle more diverse situations tends to become more +and more difficult, resulting in the end with a large, complex, unmaintainable +indentation function which nobody dares to touch. A good indentation function will usually need to actually parse the text, according to the syntax of the language. Luckily, it is not @@ -3352,15 +3313,15 @@ indentation code will want to be somewhat friendly to syntactically incorrect code. Good maintainable indentation functions usually fall into two categories: -either parsing forward from some ``safe'' starting point until the +either parsing forward from some safe starting point until the position of interest, or parsing backward from the position of interest. Neither of the two is a clearly better choice than the other: parsing backward is often more difficult than parsing forward because programming languages are designed to be parsed forward, but for the purpose of indentation it has the advantage of not needing to -guess a ``safe'' starting point, and it generally enjoys the property +guess a safe starting point, and it generally enjoys the property that only a minimum of text will be analyzed to decide the indentation -of a line, so indentation will tend to be unaffected by syntax errors in +of a line, so indentation will tend to be less affected by syntax errors in some earlier unrelated piece of code. Parsing forward on the other hand is usually easier and has the advantage of making it possible to reindent efficiently a whole region at a time, with a single parse. @@ -3384,8 +3345,8 @@ of Lisp sexps and adapts it to non-Lisp languages. @cindex SMIE SMIE is a package that provides a generic navigation and indentation -engine. Based on a very simple parser using an ``operator precedence -grammar'', it lets major modes extend the sexp-based navigation of Lisp +engine. Based on a very simple parser using an operator precedence +grammar, it lets major modes extend the sexp-based navigation of Lisp to non-Lisp languages as well as provide a simple to use but reliable auto-indentation. @@ -3411,6 +3372,7 @@ resorting to some special tricks (@pxref{SMIE Tricks}). * SMIE Indentation:: Specifying indentation rules. * SMIE Indentation Helpers:: Helper functions for indentation rules. * SMIE Indentation Example:: Sample indentation rules. +* SMIE Customization:: Customizing indentation. @end menu @node SMIE setup @@ -3445,7 +3407,7 @@ provided grammar is precise enough, @code{transpose-sexps} can correctly transpose the two arguments of a @code{+} operator, taking into account the precedence rules of the language. -Calling `smie-setup' is also sufficient to make TAB indentation work in +Calling @code{smie-setup} is also sufficient to make TAB indentation work in the expected way, extends @code{blink-matching-paren} to apply to elements like @code{begin...end}, and provides some commands that you can bind in the major mode keymap. @@ -3679,7 +3641,7 @@ For example: Notice how those lexers return the empty string when in front of parentheses. This is because SMIE automatically takes care of the parentheses defined in the syntax table. More specifically if the lexer -returns nil or an empty string, SMIE tries to handle the corresponding +returns @code{nil} or an empty string, SMIE tries to handle the corresponding text as a sexp according to syntax tables. @node SMIE Tricks @@ -3821,8 +3783,8 @@ expressions (not separated by any token) rather than an expression. @end itemize When @var{arg} is a token, the function is called with point just before -that token. A return value of nil always means to fallback on the -default behavior, so the function should return nil for arguments it +that token. A return value of @code{nil} always means to fallback on the +default behavior, so the function should return @code{nil} for arguments it does not expect. @var{offset} can be: @@ -3894,7 +3856,7 @@ of instructions (enclosed in a @code{@{...@}} or @code{begin...end} block). @var{method} should be the method name that was passed to -`smie-rules-function'. +@code{smie-rules-function}. @end defun @node SMIE Indentation Example @@ -3921,7 +3883,7 @@ A few things to note: @itemize @item The first case indicates the basic indentation increment to use. -If @code{sample-indent-basic} is nil, then SMIE uses the global +If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global setting @code{smie-indent-basic}. The major mode could have set @code{smie-indent-basic} buffer-locally instead, but that is discouraged. @@ -3989,6 +3951,52 @@ the previous @code{"else"}, rather than going all the way back to the first @code{"if"} of the sequence. @end itemize +@c In some sense this belongs more in the Emacs manual. +@node SMIE Customization +@subsubsection Customizing Indentation + +If you are using a mode whose indentation is provided by SMIE, you can +customize the indentation to suit your preferences. You can do this +on a per-mode basis (using the option @code{smie-config}), or a +per-file basis (using the function @code{smie-config-local} in a +file-local variable specification). + +@defopt smie-config +This option lets you customize indentation on a per-mode basis. +It is an alist with elements of the form @code{(@var{mode} . @var{rules})}. +For the precise form of rules, see the variable's documentation; but +you may find it easier to use the command @code{smie-config-guess}. +@end defopt + +@deffn Command smie-config-guess +This command tries to work out appropriate settings to produce +your preferred style of indentation. Simply call the command while +visiting a file that is indented with your style. +@end deffn + +@deffn Command smie-config-save +Call this command after using @code{smie-config-guess}, to save your +settings for future sessions. +@end deffn + +@deffn Command smie-config-show-indent &optional move +This command displays the rules that are used to indent the current +line. +@end deffn + +@deffn Command smie-config-set-indent +This command adds a local rule to adjust the indentation of the current line. +@end deffn + +@defun smie-config-local rules +This function adds @var{rules} as indentation rules for the current buffer. +These add to any mode-specific rules defined by the @code{smie-config} option. +To specify custom indentation rules for a specific file, add an entry +to the file's local variables of the form: +@code{eval: (smie-config-local '(@var{rules}))}. +@end defun + + @node Desktop Save Mode @section Desktop Save Mode @cindex desktop save mode diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 090310c5545..3351b841f45 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1998-1999, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Non-ASCII Characters @chapter Non-@acronym{ASCII} Characters @@ -50,7 +50,7 @@ inclusive. Emacs extends this range with codepoints in the range @code{#x110000..#x3FFFFF}, which it uses for representing characters that are not unified with Unicode and @dfn{raw 8-bit bytes} that cannot be interpreted as characters. Thus, a character codepoint in -Emacs is a 22-bit integer number. +Emacs is a 22-bit integer. @cindex internal representation of characters @cindex characters, representation in buffers and strings @@ -248,6 +248,7 @@ unibyte string, it is returned unchanged. Use this function for characters. @end defun +@c FIXME: Should '@var{character}' be '@var{byte}'? @defun byte-to-string byte @cindex byte to string This function returns a unibyte string containing a single byte of @@ -258,7 +259,7 @@ character data, @var{character}. It signals an error if @defun multibyte-char-to-unibyte char This converts the multibyte character @var{char} to a unibyte character, and returns that character. If @var{char} is neither -@acronym{ASCII} nor eight-bit, the function returns -1. +@acronym{ASCII} nor eight-bit, the function returns @minus{}1. @end defun @defun unibyte-char-to-multibyte char @@ -401,12 +402,14 @@ specifies how the character behaves and how it should be handled during text processing and display. Thus, character properties are an important part of specifying the character's semantics. +@c FIXME: Use the latest URI of this chapter? +@c http://www.unicode.org/versions/latest/ch04.pdf On the whole, Emacs follows the Unicode Standard in its implementation of character properties. In particular, Emacs supports the @uref{http://www.unicode.org/reports/tr23/, Unicode Character Property Model}, and the Emacs character property database is derived from the Unicode Character Database (@acronym{UCD}). See the -@uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character +@uref{http://www.unicode.org/versions/Unicode6.2.0/ch04.pdf, Character Properties chapter of the Unicode Standard}, for a detailed description of Unicode character properties and their meaning. This section assumes you are already familiar with that chapter of the @@ -437,7 +440,7 @@ properties that Emacs knows about: Corresponds to the @code{Name} Unicode property. The value is a string consisting of upper-case Latin letters A to Z, digits, spaces, and hyphen @samp{-} characters. For unassigned codepoints, the value -is an empty string. +is @code{nil}. @cindex unicode general category @item general-category @@ -448,7 +451,7 @@ is @code{Cn}. @item canonical-combining-class Corresponds to the @code{Canonical_Combining_Class} Unicode property. -The value is an integer number. For unassigned codepoints, the value +The value is an integer. For unassigned codepoints, the value is zero. @cindex bidirectional class of characters @@ -471,32 +474,36 @@ inside @samp{<..>} brackets, but the tag names in Emacs do not include the brackets; e.g., Unicode specifies @samp{<small>} where Emacs uses @samp{small}. }; the other elements are characters that give the compatibility decomposition sequence of this character. For -unassigned codepoints, the value is the character itself. +characters that don't have decomposition sequences, and for unassigned +codepoints, the value is a list with a single member, the character +itself. @item decimal-digit-value Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Digit}. The value is an -integer number. For unassigned codepoints, the value is @code{nil}, -which means @acronym{NaN}, or ``not-a-number''. +characters whose @code{Numeric_Type} is @samp{Decimal}. The value is +an integer, or @code{nil} if the character has no decimal digit value. +For unassigned codepoints, the value is @code{nil}, which means +@acronym{NaN}, or ``not a number''. @item digit-value Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Decimal}. The value is -an integer number. Examples of such characters include compatibility -subscript and superscript digits, for which the value is the -corresponding number. For unassigned codepoints, the value is -@code{nil}, which means @acronym{NaN}. +characters whose @code{Numeric_Type} is @samp{Digit}. The value is an +integer. Examples of such characters include compatibility subscript +and superscript digits, for which the value is the corresponding +number. For characters that don't have any numeric value, and for +unassigned codepoints, the value is @code{nil}, which means +@acronym{NaN}. @item numeric-value Corresponds to the Unicode @code{Numeric_Value} property for characters whose @code{Numeric_Type} is @samp{Numeric}. The value of -this property is an integer or a floating-point number. Examples of -characters that have this property include fractions, subscripts, -superscripts, Roman numerals, currency numerators, and encircled -numbers. For example, the value of this property for the character -@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For -unassigned codepoints, the value is @code{nil}, which means -@acronym{NaN}. +this property is a number. Examples of characters that have this +property include fractions, subscripts, superscripts, Roman numerals, +currency numerators, and encircled numbers. For example, the value of +this property for the character @code{U+2155} (@sc{vulgar fraction one +fifth}) is @code{0.2}. For characters that don't have any numeric +value, and for unassigned codepoints, the value is @code{nil}, which +means @acronym{NaN}. @cindex mirroring of characters @item mirrored @@ -517,13 +524,33 @@ property to display mirror images of characters when appropriate (@pxref{Bidirectional Display}). For unassigned codepoints, the value is @code{nil}. +@item paired-bracket +Corresponds to the Unicode @code{Bidi_Paired_Bracket} property. The +value of this property is the codepoint of a character's @dfn{paired +bracket}, or @code{nil} if the character is not a bracket character. +This establishes a mapping between characters that are treated as +bracket pairs by the Unicode Bidirectional Algorithm; Emacs uses this +property when it decides how to reorder for display parentheses, +braces, and other similar characters (@pxref{Bidirectional Display}). + +@item bracket-type +Corresponds to the Unicode @code{Bidi_Paired_Bracket_Type} property. +For characters whose @code{paired-bracket} property is non-@code{nil}, +the value of this property is a symbol, either @code{o} (for opening +bracket characters) or @code{c} (for closing bracket characters). For +characters whose @code{paired-bracket} property is @code{nil}, the +value is the symbol @code{n} (None). Like @code{paired-bracket}, this +property is used for bidirectional display. + @item old-name Corresponds to the Unicode @code{Unicode_1_Name} property. The value -is a string. For unassigned codepoints, the value is an empty string. +is a string. For unassigned codepoints, and characters that have no +value for this property, the value is @code{nil}. @item iso-10646-comment Corresponds to the Unicode @code{ISO_Comment} property. The value is -a string. For unassigned codepoints, the value is an empty string. +either a string or @code{nil}. For unassigned codepoints, the value +is @code{nil}. @item uppercase Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. @@ -548,28 +575,36 @@ This function returns the value of @var{char}'s @var{propname} property. @example @group -(get-char-code-property ? 'general-category) +(get-char-code-property ?\s 'general-category) @result{} Zs @end group @group -(get-char-code-property ?1 'general-category) +(get-char-code-property ?1 'general-category) @result{} Nd @end group @group -;; subscript 4 +;; U+2084 SUBSCRIPT FOUR (get-char-code-property ?\u2084 'digit-value) @result{} 4 @end group @group -;; one fifth +;; U+2155 VULGAR FRACTION ONE FIFTH (get-char-code-property ?\u2155 'numeric-value) @result{} 0.2 @end group @group -;; Roman IV +;; U+2163 ROMAN NUMERAL FOUR (get-char-code-property ?\u2163 'numeric-value) @result{} 4 @end group +@group +(get-char-code-property ?\( 'paired-bracket) + @result{} 41 ;; closing parenthesis +@end group +@group +(get-char-code-property ?\) 'bracket-type) + @result{} c +@end group @end example @end defun @@ -605,6 +640,7 @@ property as a symbol. @end defvar @defvar char-script-table +@cindex script symbols The value of this variable is a char-table that specifies, for each character, a symbol whose name is the script to which the character belongs, according to the Unicode Standard classification of the @@ -681,6 +717,7 @@ which case the returned charset must be supported by that coding system (@pxref{Coding Systems}). @end defun +@c TODO: Explain the properties here and add indexes such as 'charset property'. @defun charset-plist charset This function returns the property list of the character set @var{charset}. Although @var{charset} is a symbol, this is not the @@ -751,6 +788,8 @@ of them is @code{nil}, it defaults to the first or last codepoint of @node Scanning Charsets @section Scanning for Character Sets +@cindex scanning for character sets +@cindex character set, searching Sometimes it is useful to find out which character set a particular character belongs to. One use for this is in determining which coding @@ -846,6 +885,8 @@ systems specifies its own translation tables, the table that is the value of this variable, if non-@code{nil}, is applied after them. @end defvar +@c FIXME: This variable is obsolete since 23.1. We should mention +@c that here or simply remove this defvar. --xfq @defvar translation-table-for-input Self-inserting characters are translated through this translation table before they are inserted. Search commands also translate their @@ -954,7 +995,8 @@ Unix convention, used on GNU and Unix systems, is to use the linefeed character (also called newline). The DOS convention, used on MS-Windows and MS-DOS systems, is to use a carriage-return and a linefeed at the end of a line. The Mac convention is to use just -carriage-return. +carriage-return. (This was the convention used on the Macintosh +system prior to OS X.) @cindex base coding system @cindex variant coding system @@ -1098,6 +1140,16 @@ 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. +@cindex file-name encoding, MS-Windows + On Windows 2000 and later, Emacs by default uses Unicode APIs to +pass file names to the OS, so the value of +@code{file-name-coding-system} is largely ignored. Lisp applications +that need to encode or decode file names on the Lisp level should use +@code{utf-8} coding-system when @code{system-type} is +@code{windows-nt}; the conversion of UTF-8 encoded file names to the +encoding appropriate for communicating with the OS is performed +internally by Emacs. + @node Lisp and Coding Systems @subsection Coding Systems in Lisp @@ -1268,17 +1320,18 @@ Sets}) supported by @var{coding-system}. Some coding systems that support too many character sets to list them all yield special values: @itemize @bullet @item -If @var{coding-system} supports all the ISO-2022 charsets, the value -is @code{iso-2022}. -@item If @var{coding-system} supports all Emacs characters, the value is @code{(emacs)}. @item -If @var{coding-system} supports all emacs-mule characters, the value -is @code{emacs-mule}. -@item If @var{coding-system} supports all Unicode characters, the value is @code{(unicode)}. +@item +If @var{coding-system} supports all ISO-2022 charsets, the value is +@code{iso-2022}. +@item +If @var{coding-system} supports all the characters in the internal +coding system used by Emacs version 21 (prior to the implementation of +internal Unicode support), the value is @code{emacs-mule}. @end itemize @end defun @@ -1327,7 +1380,7 @@ 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} +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 @@ -1389,7 +1442,7 @@ don't change these variables; instead, override them using @cindex file contents, and default coding system @defopt auto-coding-regexp-alist This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} +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 @@ -1563,7 +1616,7 @@ 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} +@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 @@ -1574,6 +1627,9 @@ contents (as it usually does), it should examine the contents of @node Specifying Coding Systems @subsection Specifying a Coding System for One Operation +@cindex specify coding system +@cindex force coding system for operation +@cindex coding system for operation You can specify the coding system for a specific operation by binding the variables @code{coding-system-for-read} and/or @@ -1596,8 +1652,7 @@ 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)) +(let ((coding-system-for-read 'no-conversion)) (insert-file-contents filename)) @end example @@ -1767,7 +1822,7 @@ original text: @example @group (decode-coding-string "Gr\374ss Gott" 'latin-1) - @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) + @result{} #("Grüss Gott" 0 9 (charset iso-8859-1)) @end group @end example @end defun @@ -1786,24 +1841,23 @@ decoding, you can call this function. @node Terminal I/O Encoding @subsection Terminal I/O Encoding - Emacs can decode keyboard input using a coding system, and encode + Emacs can use coding systems to decode keyboard input 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 of +display text using a particular encoding, such as Latin-1. Emacs does +not set @code{last-coding-system-used} when encoding or decoding terminal I/O. @defun keyboard-coding-system &optional terminal -This function returns the coding system that is in use for decoding -keyboard input from @var{terminal}---or @code{nil} if no coding system -is to be used for that terminal. If @var{terminal} is omitted or -@code{nil}, it means the selected frame's terminal. @xref{Multiple -Terminals}. +This function returns the coding system used for decoding keyboard +input from @var{terminal}. A value of @code{no-conversion} means no +decoding is done. If @var{terminal} is omitted or @code{nil}, it +means the selected frame's terminal. @xref{Multiple Terminals}. @end defun @deffn Command set-keyboard-coding-system coding-system &optional terminal This command specifies @var{coding-system} as the coding system to use for decoding keyboard input from @var{terminal}. If -@var{coding-system} is @code{nil}, that means do not decode keyboard +@var{coding-system} is @code{nil}, that means not to decode keyboard input. If @var{terminal} is a frame, it means that frame's terminal; if it is @code{nil}, that means the currently selected frame's terminal. @xref{Multiple Terminals}. @@ -1811,18 +1865,19 @@ terminal. @xref{Multiple Terminals}. @defun terminal-coding-system &optional terminal This function returns the coding system that is in use for encoding -terminal output from @var{terminal}---or @code{nil} if the output is -not encoded. If @var{terminal} is a frame, it means that frame's -terminal; if it is @code{nil}, that means the currently selected -frame's terminal. +terminal output from @var{terminal}. A value of @code{no-conversion} +means no encoding is done. If @var{terminal} is a frame, it means +that frame's terminal; if it is @code{nil}, that means the currently +selected frame's terminal. @end defun @deffn Command set-terminal-coding-system coding-system &optional terminal This command specifies @var{coding-system} as the coding system to use for encoding terminal output from @var{terminal}. If -@var{coding-system} is @code{nil}, terminal output is not encoded. If -@var{terminal} is a frame, it means that frame's terminal; if it is -@code{nil}, that means the currently selected frame's terminal. +@var{coding-system} is @code{nil}, that means not to encode terminal +output. If @var{terminal} is a frame, it means that frame's terminal; +if it is @code{nil}, that means the currently selected frame's +terminal. @end deffn @node Input Methods @@ -1901,7 +1956,7 @@ and @ref{Invoking the Input Method}. @section Locales @cindex locale - POSIX defines a concept of ``locales'' which control which language + In POSIX, locales control which language to use in language-related features. These Emacs variables control how Emacs interacts with these features. @@ -1909,6 +1964,7 @@ how Emacs interacts with these features. @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 +sending batch output to the standard output and error streams, for encoding the format argument to @code{format-time-string}, and for decoding the return value of @code{format-time-string}. @end defvar diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 2b6f31b670b..54c8d3e5988 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Numbers @@ -9,13 +9,14 @@ @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. +@dfn{floating-point numbers}. Integers are whole numbers such as +@minus{}3, 0, 7, 13, and 511. Floating-point numbers are numbers with +fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can +also be expressed in exponential notation: @samp{1.5e2} is the same as +@samp{150.0}; here, @samp{e2} stands for ten to the second power, and +that is multiplied by 1.5. Integer computations are exact, though +they may overflow. Floating-point computations often involve rounding +errors, as the numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -24,7 +25,7 @@ exact; they have a fixed, limited amount of precision. * 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. +* 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. @@ -34,9 +35,9 @@ exact; they have a fixed, limited amount of precision. @section Integer Basics The range of values for an integer depends on the machine. The -minimum range is @minus{}536870912 to 536870911 (30 bits; i.e., +minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex --2**29 +@minus{}2**29 @end ifnottex @tex @math{-2^{29}} @@ -61,7 +62,8 @@ Emacs range is treated as a floating-point number. 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 1073741825 ; @r{The floating point number 1073741825.0.} + 9000000000000000000 + ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -114,15 +116,15 @@ use the @samp{...} notation to make binary integers easier to read.) @minus{}1 is represented as 30 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, + Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. +In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example 1111...111011 (30 bits total) @end example - In this implementation, the largest 30-bit binary integer value is + In this implementation, the largest 30-bit binary integer is 536,870,911 in decimal. In binary, it looks like this: @example @@ -145,111 +147,143 @@ 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. -@cindex largest Lisp integer number -@cindex maximum Lisp integer number +@cindex largest Lisp integer +@cindex maximum Lisp integer @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp -can handle. +The value of this variable is the largest integer that Emacs Lisp can +handle. Typical values are +@ifnottex +2**29 @minus{} 1 +@end ifnottex +@tex +@math{2^{29}-1} +@end tex +on 32-bit and +@ifnottex +2**61 @minus{} 1 +@end ifnottex +@tex +@math{2^{61}-1} +@end tex +on 64-bit platforms. @end defvar -@cindex smallest Lisp integer number -@cindex minimum Lisp integer number +@cindex smallest Lisp integer +@cindex minimum Lisp integer @defvar most-negative-fixnum The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. +handle. It is negative. Typical values are +@ifnottex +@minus{}2**29 +@end ifnottex +@tex +@math{-2^{29}} +@end tex +on 32-bit and +@ifnottex +@minus{}2**61 +@end ifnottex +@tex +@math{-2^{61}} +@end tex +on 64-bit platforms. @end defvar In Emacs Lisp, text characters are represented by integers. Any -integer between zero and the value of @code{max-char}, inclusive, is -considered to be valid as a character. @xref{String Basics}. +integer between zero and the value of @code{(max-char)}, inclusive, is +considered to be valid as a character. @xref{Character Codes}. @node Float Basics -@section Floating Point Basics +@section Floating-Point Basics @cindex @acronym{IEEE} floating point - 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. Emacs uses the -@acronym{IEEE} floating point standard, which is supported by all -modern computers. - - 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}. - - Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with -respect to @code{equal} and @code{=}), even though the two are -distinguishable in the @acronym{IEEE} floating point standard. + Floating-point numbers are useful for representing numbers that are +not integral. The range of floating-point numbers is +the same as the range of the C data type @code{double} on the machine +you are using. On all computers currently supported by Emacs, this is +double-precision @acronym{IEEE} floating point. + + The read syntax for floating-point numbers requires either a decimal +point, an exponent, or both. Optional signs (@samp{+} or @samp{-}) +precede the number and its exponent. For example, @samp{1500.0}, +@samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are +five ways of writing a floating-point number whose value is 1500. +They are all equivalent. Like Common Lisp, Emacs Lisp requires at +least one digit after any decimal point in a floating-point number; +@samp{1500.} is an integer, not a floating-point number. + + Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero +with respect to @code{equal} and @code{=}. This follows the +@acronym{IEEE} floating-point standard, which says @code{-0.0} and +@code{0.0} are numerically equal even though other operations can +distinguish them. @cindex positive infinity @cindex negative infinity @cindex infinity @cindex NaN - The @acronym{IEEE} floating point standard supports positive -infinity and negative infinity as floating point values. It also -provides for a class of values called NaN or ``not-a-number''; + The @acronym{IEEE} floating-point standard supports 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@. (NaN -values can also carry a sign, but for practical purposes there's no -significant difference between different NaN values in Emacs Lisp.) - -When a function is documented to return a NaN, it returns an -implementation-defined value when Emacs is running on one of the -now-rare platforms that do not use @acronym{IEEE} floating point. For -example, @code{(log -1.0)} typically returns a NaN, but on -non-@acronym{IEEE} platforms it returns an implementation-defined -value. +correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. +Although NaN values carry a sign, for practical purposes there is no other +significant difference between different NaN values in Emacs Lisp. -Here are the read syntaxes for these special floating point values: +Here are 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}. +@item infinity +@samp{1.0e+INF} and @samp{-1.0e+INF} +@item not-a-number +@samp{0.0e+NaN} and @samp{-0.0e+NaN} @end table -@defun isnan number -This predicate tests whether its argument is NaN, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. -@end defun - - The following functions are specialized for handling floating point + The following functions are specialized for handling floating-point numbers: -@defun frexp x -This function returns a cons cell @code{(@var{sig} . @var{exp})}, -where @var{sig} and @var{exp} are respectively the significand and -exponent of the floating point number @var{x}: +@defun isnan x +This predicate returns @code{t} if its floating-point argument is a NaN, +@code{nil} otherwise. +@end defun -@smallexample -@var{x} = @var{sig} * 2^@var{exp} -@end smallexample +@defun frexp x +This function returns a cons cell @code{(@var{s} . @var{e})}, +where @var{s} and @var{e} are respectively the significand and +exponent of the floating-point number @var{x}. -@var{sig} is a floating point number between 0.5 (inclusive) and 1.0 -(exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}. +If @var{x} is finite, then @var{s} is a floating-point number between 0.5 +(inclusive) and 1.0 (exclusive), @var{e} is an integer, and +@ifnottex +@var{x} = @var{s} * 2**@var{e}. +@end ifnottex +@tex +@math{x = s 2^e}. +@end tex +If @var{x} is zero or infinity, then @var{s} is the same as @var{x}. +If @var{x} is a NaN, then @var{s} is also a NaN@. +If @var{x} is zero, then @var{e} is 0. @end defun -@defun ldexp sig &optional exp -This function returns a floating point number corresponding to the -significand @var{sig} and exponent @var{exp}. +@defun ldexp s e +Given a numeric significand @var{s} and an integer exponent @var{e}, +this function returns the floating point number +@ifnottex +@var{s} * 2**@var{e}. +@end ifnottex +@tex +@math{s 2^e}. +@end tex @end defun @defun copysign x1 x2 This function copies the sign of @var{x2} to the value of @var{x1}, -and returns the result. @var{x1} and @var{x2} must be floating point -numbers. +and returns the result. @var{x1} and @var{x2} must be floating point. @end defun -@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 +@defun logb x +This function returns the binary exponent of @var{x}. More +precisely, the value is the logarithm base 2 of @math{|x|}, rounded down to an integer. @example @@ -272,8 +306,8 @@ 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. +This predicate tests whether its argument is floating point +and returns @code{t} if so, @code{nil} otherwise. @end defun @defun integerp object @@ -293,8 +327,8 @@ 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 wholenump number -This is a synonym for @code{natnump}. +@findex wholenump +@code{wholenump} is a synonym for @code{natnump}. @end defun @defun zerop number @@ -310,13 +344,13 @@ if so, @code{nil} otherwise. The argument must be a number. @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 +@code{=}, not @code{eq}. There can be many distinct floating-point +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. - In Emacs Lisp, each integer value is a unique Lisp object. + In Emacs Lisp, each integer is a unique Lisp object. 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 @@ -328,18 +362,18 @@ use @code{=} if you can, even for comparing integers. Sometimes it is useful to compare numbers with @code{equal}, which 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. +@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. + There is another wrinkle: because floating-point arithmetic is not +exact, it is often a bad idea to check for equality of 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)) + (or (= x y) (< (/ (abs (- x y)) (max (abs x) (abs y))) fuzz-factor))) @@ -351,12 +385,12 @@ Here's a function to do this: @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. +limited range of integers. @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. +@defun = number-or-marker &rest number-or-markers +This function tests whether all its arguments are numerically equal, +and returns @code{t} if so, @code{nil} otherwise. @end defun @defun eql value1 value2 @@ -371,32 +405,29 @@ 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. +@defun < number-or-marker &rest number-or-markers +This function tests whether each argument is strictly less than the +following 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. +@defun <= number-or-marker &rest number-or-markers +This function tests whether each argument is less than or equal to +the following 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. +@defun > number-or-marker &rest number-or-markers +This function tests whether each argument is strictly greater than +the following 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. +@defun >= number-or-marker &rest number-or-markers +This function tests whether each argument is greater than or equal to +the following 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 +If any of the arguments is floating point, the value is returned as floating point, even if it was given as an integer. @example @@ -411,7 +442,7 @@ as floating point, even if it was given as an integer. @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 +If any of the arguments is floating point, the value is returned as floating point, even if it was given as an integer. @example @@ -434,20 +465,20 @@ 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 +If @var{number} is already floating point, @code{float} returns it unchanged. @end defun - There are four functions to convert floating point numbers to + 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 +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. integer. If @var{divisor} is zero (whether integer or -floating-point), Emacs signals an @code{arith-error} error. +integer. If @var{divisor} is zero (whether integer or +floating point), Emacs signals an @code{arith-error} error. @defun truncate number &optional divisor This returns @var{number}, converted to an integer by rounding towards @@ -505,8 +536,7 @@ This returns @var{number}, converted to an integer by rounding upward @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. +returns the even integer. @example (round 1.2) @@ -528,11 +558,11 @@ depending on your machine. (addition, subtraction, multiplication, and division), as well as remainder and modulus functions, and functions to add or subtract 1. Except for @code{%}, each of these functions accepts both integer and -floating point arguments, and returns a floating point number if any -argument is a floating point number. +floating-point arguments, and returns a floating-point number if any +argument is floating point. - It is important to note that in Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to + Emacs Lisp arithmetic functions do not check for integer overflow. +Thus @code{(1+ 536870911)} may evaluate to @minus{}536870912, depending on your hardware. @defun 1+ number-or-marker @@ -612,18 +642,15 @@ product. When given no arguments, @code{*} returns 1. @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 +@defun / number &rest divisors +With one or more @var{divisors}, this function divides @var{number} +by each divisor in @var{divisors} in turn, and returns the quotient. +With no @var{divisors}, this function returns 1/@var{number}, i.e., +the multiplicative inverse of @var{number}. Each argument may be a number or a marker. If all the arguments are integers, the result is an integer, obtained by rounding the quotient towards zero after each division. -(Hypothetically, some machines may have different rounding behavior -for negative arguments, because @code{/} is implemented using the C -division operator, which permits machine-dependent rounding; but this -does not happen in practice.) @example @group @@ -647,6 +674,14 @@ does not happen in practice.) @result{} 2.5 @end group @group +(/ 4.0) + @result{} 0.25 +@end group +@group +(/ 4) + @result{} 0 +@end group +@group (/ 25 3 2) @result{} 4 @end group @@ -658,9 +693,9 @@ does not happen in practice.) @cindex @code{arith-error} in division If you divide an integer by the integer 0, Emacs signals an -@code{arith-error} error (@pxref{Errors}). If you divide a floating -point number by 0, or divide by the floating point number 0.0, the -result is either positive or negative infinity (@pxref{Float Basics}). +@code{arith-error} error (@pxref{Errors}). Floating-point division of +a nonzero number by zero yields either positive or negative infinity +(@pxref{Float Basics}). @end defun @defun % dividend divisor @@ -678,8 +713,7 @@ For any two integers @var{dividend} and @var{divisor}, @end example @noindent -always equals @var{dividend}. If @var{divisor} is zero, Emacs signals -an @code{arith-error} error. +always equals @var{dividend} if @var{divisor} is nonzero. @example (% 9 4) @@ -700,7 +734,7 @@ 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} permits floating point arguments; it +Unlike @code{%}, @code{mod} permits floating-point arguments; it rounds the quotient downward (towards minus infinity) to an integer, and uses that quotient to compute the remainder. @@ -741,7 +775,8 @@ For any two numbers @var{dividend} and @var{divisor}, @noindent always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric +argument is floating point and to an @code{arith-error} if @var{dividend} is an +integer and @var{divisor} is 0. For @code{floor}, see @ref{Numeric Conversions}. @end defun @@ -750,30 +785,31 @@ Conversions}. @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 +@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. +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. +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. +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. +and returns that value as a floating-point number. +Rounding a value equidistant between two integers returns the even integer. @end defun @node Bitwise Operations @@ -785,7 +821,7 @@ and returns that value as a floating point number. 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''. +reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. @@ -962,17 +998,16 @@ Here are other examples: @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.) +This function returns the bitwise AND of the arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in all +the arguments. -For example, using 4-bit binary numbers, the ``logical and'' of 13 and +For example, using 4-bit binary numbers, the bitwise 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. +In both the binary numbers, the leftmost two bits are both 1 +so the leftmost two bits of the returned value are both 1. +However, for the rightmost two bits, each is 0 in at least one of +the arguments, so the rightmost two bits of the returned value are both 0. @noindent Therefore, @@ -1013,9 +1048,9 @@ because its binary representation consists entirely of ones. If @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, +This function returns the bitwise inclusive OR of its arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in at +least one of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If @code{logior} is passed just one argument, it returns that argument. @@ -1038,9 +1073,9 @@ passed just one argument, it returns that argument. @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 +This function returns the bitwise exclusive OR of its arguments: the +@var{n}th bit is 1 in the result if, and only if, the @var{n}th bit is +1 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. @@ -1063,7 +1098,7 @@ result is 0, which is an identity element for this operation. If @end defun @defun lognot integer -This function returns the logical complement of its argument: the @var{n}th +This function returns the bitwise 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. @@ -1082,7 +1117,7 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @cindex mathematical functions @cindex floating-point functions - These mathematical functions allow integers as well as floating point + These mathematical functions allow integers as well as floating-point numbers as arguments. @defun sin arg @@ -1165,8 +1200,8 @@ non-integer, @code{expt} returns a NaN. @end defun @defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -@code{sqrt} returns a NaN. +This returns the square root of @var{arg}. If @var{arg} is finite +and less than zero, @code{sqrt} returns a NaN. @end defun In addition, Emacs defines the following common mathematical @@ -1191,7 +1226,8 @@ 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. - Pseudo-random numbers are generated from a ``seed''. Starting from +@cindex seed, for random number generation + Pseudo-random numbers are generated from a @dfn{seed value}. Starting from any given seed, the @code{random} function always generates the same sequence of numbers. By default, Emacs initializes the random seed at startup, in such a way that the sequence of values of @code{random} @@ -1215,8 +1251,8 @@ any integer representable in Lisp, i.e., an integer between @code{most-negative-fixnum} and @code{most-positive-fixnum} (@pxref{Integer Basics}). -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. +If @var{limit} is @code{t}, it means to choose a new seed as if Emacs +were restarting. If @var{limit} is a string, it means to choose a new seed based on the string's contents. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 61007cc5a12..ec83f0b957a 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lisp Data Types @@ -18,7 +18,7 @@ possible objects. 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. +but not for @emph{the} type of an object. @cindex primitive type A few fundamental object types are built into Emacs. These, from @@ -136,7 +136,7 @@ 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. +* 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, @@ -156,15 +156,17 @@ latter are unique to Emacs Lisp. * Byte-Code Type:: A function written in Lisp, then compiled. * Autoload Type:: A type used for automatically loading seldom-used functions. +* Finalizer Type:: Runs code when no longer reachable. + @end menu @node Integer Type @subsection Integer Type - The range of values for integers in Emacs Lisp is @minus{}536870912 to -536870911 (30 bits; i.e., + The range of values for an integer depends on the machine. The +minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex --2**29 +@minus{}2**29 @end ifnottex @tex @math{-2^{29}} @@ -176,9 +178,9 @@ to @tex @math{2^{29}-1}) @end tex -on typical 32-bit machines. (Some machines provide a wider range.) -Emacs Lisp arithmetic functions do not check for overflow. Thus -@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits. +but many machines provide a wider range. +Emacs Lisp arithmetic functions do not check for integer overflow. Thus +@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. 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 @@ -187,7 +189,7 @@ leading @samp{+} or a final @samp{.}. @example @group --1 ; @r{The integer -1.} +-1 ; @r{The integer @minus{}1.} 1 ; @r{The integer 1.} 1. ; @r{Also the integer 1.} +1 ; @r{Also the integer 1.} @@ -197,26 +199,26 @@ leading @samp{+} or a final @samp{.}. @noindent As a special exception, if a sequence of digits specifies an integer too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating Point Type}). +reads it as a floating-point number (@pxref{Floating-Point Type}). For instance, if Emacs integers are 30 bits, @code{536870912} is read as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information. -@node Floating Point Type -@subsection Floating Point Type +@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 + 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 + 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 +both. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2}, +@samp{+1500000e-3}, 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. @@ -308,7 +310,7 @@ 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, +the Super modifier to the following character.) Thus, @example ?\a @result{} 7 ; @r{control-g, @kbd{C-g}} @@ -327,7 +329,7 @@ the ``super'' modifier to the following character.) Thus, @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 +escape character; this 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. @@ -373,13 +375,7 @@ that, Emacs signals an error. codes. A hexadecimal escape sequence consists of a backslash, @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and -@code{?\xe0} is the character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex +@code{?\xe0} is the character @kbd{à } (@kbd{a} with grave accent). You can use any number of hex digits, so you can represent any character code in this way. @@ -560,7 +556,7 @@ 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 +folded to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct. @end quotation @@ -593,8 +589,8 @@ FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} @cindex @samp{##} read syntax @ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu +@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 @@ -648,7 +644,7 @@ same object, @code{nil}. 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} any -Lisp object. We also say that ``the @sc{car} of this cons cell is'' +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}. @@ -664,13 +660,13 @@ of lists, we refer to any structure made out of cons cells as a @quotation A note to C programmers: a Lisp list thus works as a @dfn{linked list} built up of cons cells. Because pointers in Lisp are implicit, we do -not distinguish between a cons cell slot ``holding'' a value versus -``pointing to'' the value. +not distinguish between a cons cell slot holding a value versus +pointing to the value. @end quotation @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 +an object which is not a cons cell. These objects are called @dfn{atoms}. @cindex parenthesis @@ -699,10 +695,10 @@ 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 +divided words into two parts, the address 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 +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. @@ -741,7 +737,7 @@ 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 +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 @@ -997,7 +993,7 @@ of a string returns the same string. The read syntax for a string 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 +@code{"\""} is a string containing just one double-quote character. Likewise, you can include a backslash by preceding it with another backslash, like this: @code{"this \\ is a single embedded backslash"}. @@ -1180,7 +1176,7 @@ a whole character set. @cindex @samp{#^} read syntax The printed representation of a char-table is like a vector except that there is an extra @samp{#^} at the beginning.@footnote{You -may also encounter @samp{#^^}, used for ``sub-char-tables''.} +may also encounter @samp{#^^}, used for sub-char-tables.} @xref{Char-Tables}, for special functions to operate on char-tables. Uses of char-tables include: @@ -1208,7 +1204,7 @@ 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 +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. @@ -1283,8 +1279,8 @@ 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 +@code{defmacro} macro, 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 @@ -1301,7 +1297,7 @@ 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 +(@pxref{Special Forms}). 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 @@ -1361,6 +1357,31 @@ in the loaded file. @code{autoload}, which stores the object in the function cell of a symbol. @xref{Autoload}, for more details. +@node Finalizer Type +@subsection Finalizer Type + + A @dfn{finalizer object} helps Lisp code clean up after objects that +are no longer needed. A finalizer holds a Lisp function object. +When a finalizer object becomes unreachable after a garbage collection +pass, Emacs calls the finalizer's associated function object. +When deciding whether a finalizer is reachable, Emacs does not count +references from finalizer objects themselves, allowing you to use +finalizers without having to worry about accidentally capturing +references to finalized objects themselves. + +Errors in finalizers are printed to @code{*Messages*}. Emacs runs +a given finalizer object's associated function exactly once, even +if that function fails. + +@defun make-finalizer function +Make a finalizer that will run @var{function}. @var{function} will be +called after garbage collection when the returned finalizer object +becomes unreachable. If the finalizer object is reachable only +through references from finalizer objects, it does not count as +reachable for the purpose of deciding whether to run @var{function}. +@var{function} will be run once per finalizer object. +@end defun + @node Editing Types @section Editing Types @cindex editing types @@ -1402,7 +1423,7 @@ buffer}. 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'' +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. @@ -1481,8 +1502,8 @@ 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. +selected window usually displays the current buffer (@pxref{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}. @@ -1694,7 +1715,7 @@ look alike but are not the same Lisp object. This shows the difference: @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: +appears as an element within itself. Here is an example: @example #1=(a #1#) @@ -1805,9 +1826,6 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. -@item display-table-p -@xref{Display Tables, display-table-p}. - @item floatp @xref{Predicates on Numbers, floatp}. @@ -1919,12 +1937,12 @@ types. In most cases, it is more convenient to use type predicates than This function returns a symbol naming the primitive type of @var{object}. The value is one of the symbols @code{bool-vector}, @code{buffer}, @code{char-table}, @code{compiled-function}, -@code{condition-variable}, @code{cons}, @code{float}, -@code{font-entity}, @code{font-object}, @code{font-spec}, -@code{frame}, @code{hash-table}, @code{integer}, @code{marker}, -@code{mutex}, @code{overlay}, @code{process}, @code{string}, -@code{subr}, @code{symbol}, @code{thread}, @code{vector}, -@code{window}, or @code{window-configuration}. +@code{condition-variable}, @code{cons}, @code{finalizer}, +@code{float}, @code{font-entity}, @code{font-object}, +@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, +@code{marker}, @code{mutex}, @code{overlay}, @code{process}, +@code{string}, @code{subr}, @code{symbol}, @code{thread}, +@code{vector}, @code{window}, or @code{window-configuration}. @example (type-of 1) @@ -2121,12 +2139,12 @@ that for two strings to be equal, they have the same text properties. @example @group -(equal "asdf" (propertize "asdf" '(asdf t))) +(equal "asdf" (propertize "asdf" 'asdf t)) @result{} t @end group @group (equal-including-properties "asdf" - (propertize "asdf" '(asdf t))) + (propertize "asdf" 'asdf t)) @result{} nil @end group @end example diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 071fcf526da..7050df86a18 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node System Interface @@ -37,6 +37,7 @@ terminal and the screen. * Desktop Notifications:: Desktop notifications. * File Notifications:: File notifications. * Dynamic Libraries:: On-demand loading of support libraries. +* Security Considerations:: Running Emacs in an unfriendly environment. @end menu @node Starting Up @@ -71,11 +72,12 @@ in their turn. The files @file{subdirs.el} are normally generated automatically when Emacs is installed. @item -If the library @file{leim-list.el} exists, Emacs loads it. This -optional library is intended for registering input methods; Emacs -looks for it in @code{load-path} (@pxref{Library Search}), skipping -those directories containing the standard Emacs libraries (since -@file{leim-list.el} should not exist in those directories). +It loads any @file{leim-list.el} that it finds in the @code{load-path} +directories. This file is intended for registering input methods. +The search is only for any personal @file{leim-list.el} files that you +may have created; it skips the directories containing the standard Emacs +libraries (these should contain only a single @file{leim-list.el} file, +which is compiled into the Emacs executable). @vindex before-init-time @item @@ -174,8 +176,8 @@ If the buffer @file{*scratch*} exists and is still in Fundamental mode @item If started on a text terminal, it loads the terminal-specific -Lisp library, which is specified by the variable -@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done +Lisp library (@pxref{Terminal-Specific}), and runs the hook +@code{tty-setup-hook}. This is not done in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. @c Now command-line calls command-line-1. @@ -193,9 +195,23 @@ It processes any command-line options that were not handled earlier. It now exits if the option @code{--batch} was specified. @item -If @code{initial-buffer-choice} is a string, it visits the file with -that name. If the @file{*scratch*} buffer exists and is -empty, it inserts @code{initial-scratch-message} into that buffer. +If the @file{*scratch*} buffer exists and is empty, it inserts +@code{(substitute-command-keys initial-scratch-message)} into that buffer. + +@item +If @code{initial-buffer-choice} is a string, it visits the file (or +directory) with that name. If it is a function, it calls the function +with no arguments and selects the buffer that it returns. If one file +is given as a command line argument, that file is visited and its +buffer displayed alongside @code{initial-buffer-choice}. If more than +one file is given, all of the files are visited and the @file{*Buffer +List*} buffer is displayed alongside @code{initial-buffer-choice}. + +@ignore +@c I do not think this should be mentioned. AFAICS it is just a dodge +@c around inhibit-startup-screen not being settable on a site-wide basis. +If it is @code{t}, it selects the @file{*scratch*} buffer. +@end ignore @c To make things nice and confusing, the next three items can be @c called from two places. If displaying a startup screen, they are @@ -207,7 +223,7 @@ empty, it inserts @code{initial-scratch-message} into that buffer. @c daemon/session restore step? @item -It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. +It runs @code{emacs-startup-hook}. @item It calls @code{frame-notice-user-settings}, which modifies the @@ -215,9 +231,12 @@ parameters of the selected frame according to whatever the init files specify. @item -It runs @code{window-setup-hook}. @xref{Window Systems}. +It runs @code{window-setup-hook}. The only difference between this +hook and @code{emacs-startup-hook} is that this one runs after the +previously mentioned modifications to the frame parameters. @item +@cindex startup screen It displays the @dfn{startup screen}, which is a special buffer that contains information about copyleft and basic Emacs usage. This is not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice} @@ -233,8 +252,9 @@ options were specified. @item If the option @code{--daemon} was specified, it calls -@code{server-start} and detaches from the controlling terminal. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@code{server-start}, and on Posix systems also detaches from the +controlling terminal. @xref{Emacs Server,,, emacs, The GNU Emacs +Manual}. @item If started by the X session manager, it calls @@ -269,11 +289,9 @@ aliases for this variable. If non-@code{nil}, this variable is a string that specifies a file or directory for Emacs to display after starting up, instead of the startup screen. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. +If its value is a function, Emacs calls that function which must +return a buffer which is then displayed. If its value is @code{t}, Emacs displays the @file{*scratch*} buffer. -@end ignore @end defopt @defopt inhibit-startup-echo-area-message @@ -297,6 +315,7 @@ file will not inhibit the message for someone else. @defopt initial-scratch-message This variable, if non-@code{nil}, should be a string, which is +treated as documentation to be inserted into the @file{*scratch*} buffer when Emacs starts up. If it is @code{nil}, the @file{*scratch*} buffer is empty. @end defopt @@ -316,7 +335,7 @@ Run without an interactive terminal. @xref{Batch Mode}. Do not initialize any display; just start a server in the background. @item --no-init-file -@itemx -Q +@itemx -q Do not load either the init file, or the @file{default} library. @item --no-site-file @@ -406,8 +425,13 @@ terminal) and processing the command-line action arguments. @defvar emacs-startup-hook This normal hook is run, once, just after handling the command line -arguments, just before @code{term-setup-hook}. In batch mode, Emacs -does not run either of these hooks. +arguments. In batch mode, Emacs does not run this hook. +@end defvar + +@defvar window-setup-hook +This normal hook is very similar to @code{emacs-startup-hook}. +The only difference is that it runs slightly later, after setting +of the frame parameters. @xref{Startup Summary, window-setup-hook}. @end defvar @defvar user-init-file @@ -429,21 +453,24 @@ This variable holds the name of the @file{.emacs.d} directory. It is 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 @env{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. +Normally, @code{term-file-prefix} has the value @code{"term/"}; +changing this is not recommended. If there is an entry matching +@env{TERM} in the @code{term-file-aliases} association list, +Emacs uses the associated value in place of @env{TERM}. +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 role 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{input-decode-map} if the Termcap or Terminfo entry -does not specify all the terminal's function keys. @xref{Terminal -Input}. +does not specify all the terminal's function keys. @xref{Terminal Input}. - When the name of the terminal type contains a hyphen or underscore, and no library -is found whose name is identical to the terminal's name, Emacs strips -from the terminal's name the last hyphen or underscore and everything that follows + When the name of the terminal type contains a hyphen or underscore, +and no library is found whose name is identical to the terminal's +name, Emacs strips from the terminal's name the last hyphen or +underscore 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 or underscores in the name (i.e., there is no terminal-specific library). For example, if the @@ -452,20 +479,16 @@ terminal name is @samp{xterm-256color} and there is no @file{term/xterm.el}. If necessary, the terminal library can evaluate @code{(getenv "TERM")} to find the full name of the terminal type. - 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. + Your init file can prevent the loading of the terminal-specific +library by setting the variable @code{term-file-prefix} to @code{nil}. 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 that Emacs runs -at the end of its initialization, after loading both -your init file and any terminal-specific libraries. You could -use this hook to define initializations for terminals that do not +terminal-specific library by using @code{tty-setup-hook}. This is +a normal hook that Emacs runs after initializing a new text terminal. +You could use this hook to define initializations for terminals that do not have their own libraries. @xref{Hooks}. -@defvar term-file-prefix +@defopt term-file-prefix @cindex @env{TERM} environment variable If the value of this variable is non-@code{nil}, Emacs loads a terminal-specific initialization file as follows: @@ -480,17 +503,24 @@ init file if you do not wish to load the terminal-initialization file. On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}. -@end defvar +@end defopt -@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. +@defopt term-file-aliases +This variable is an an association list mapping terminal types to +their aliases. For example, an element of the form @code{("vt102" +. "vt100")} means to treat a terminal of type @samp{vt102} like one of +type @samp{vt100}. +@end defopt -You can use @code{term-setup-hook} to override the definitions made by a -terminal-specific file. +@defvar tty-setup-hook +This variable is a normal hook that Emacs runs after initializing a +new text terminal. (This applies when Emacs starts up in non-windowed +mode, and when making a tty @command{emacsclient} connection.) The +hook runs after loading your init file (if applicable) and the +terminal-specific Lisp file, so you can use it to adjust the +definitions made by that file. -For a related feature, @pxref{Window Systems, window-setup-hook}. +For a related feature, @pxref{Init File, window-setup-hook}. @end defvar @node Command-Line Arguments @@ -516,9 +546,10 @@ displays the startup messages. 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. +If you redump Emacs by calling @code{dump-emacs} (@pxref{Building +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 @@ -550,8 +581,8 @@ 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}.) +@code{command-line-args-left} (see below). (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 @@ -695,7 +726,7 @@ another application without doing anything special to Emacs. @c have SIGTSTP? @cindex SIGTSTP Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do -not support suspension of jobs; on these systems, ``suspension'' +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. @@ -737,7 +768,7 @@ Here is an example of how you could use these hooks: (add-hook 'suspend-resume-hook (lambda () (message "Resumed!") (sit-for 2))) @end smallexample -@c The sit-for prevents the ``nil'' that suspend-emacs returns +@c The sit-for prevents the @code{nil} that suspend-emacs returns @c hiding the message. Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}: @@ -896,13 +927,6 @@ This function returns the name of the machine you are running on, as a string. @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}). - @c FIXME seems like this section is not the best place for this option? @defopt mail-host-address If this variable is non-@code{nil}, it is used instead of @@ -959,6 +983,7 @@ to access the value of @var{variable}. If @var{value} is omitted or removes @var{variable} from the environment. Otherwise, @var{value} should be a string. +@c FIXME: Document 'substitute-env-vars'? --xfq If the optional argument @var{substitute} is non-@code{nil}, Emacs calls the function @code{substitute-env-vars} to expand any environment variables in @var{value}. @@ -989,9 +1014,9 @@ process-environment @end group @end smallexample -If @code{process-environment} contains ``duplicate'' elements that +If @code{process-environment} contains multiple elements that specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. +specifies the variable, and the others are ignored. @end defvar @defvar initial-environment @@ -1044,7 +1069,7 @@ number of processes trying to run on the system. By default, the values are integers that are 100 times the system load averages, but if @var{use-float} is non-@code{nil}, then they are -returned as floating point numbers without multiplying by 100. +returned as floating-point numbers 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 @@ -1095,9 +1120,9 @@ originally logged in. The value reflects command-line options such as 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. +If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}, +@samp{-Q}, or @samp{-batch} option was used, then Lisp packages should +not load any customization files or user profile. @end defvar @defopt user-mail-address @@ -1143,29 +1168,31 @@ user-id or login name that isn't defined, it returns @code{nil}. 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 +you to fake out Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (@pxref{Frame Titles}). +@cindex UID @defun user-real-uid This function returns the real @acronym{UID} of the user. -The value may be a floating point number, in the (unlikely) event that +The value may be floating point, in the (unlikely) event that the UID is too large to fit in a Lisp integer. @end defun @defun user-uid This function returns the effective @acronym{UID} of the user. -The value may be a floating point number. +The value may be floating point. @end defun +@cindex GID @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. -The value may be a floating point number. +The value may be floating point. @end defun @defun group-real-gid This function returns the real @acronym{GID} of the Emacs process. -The value may be a floating point number. +The value may be floating point. @end defun @defun system-users @@ -1184,44 +1211,42 @@ return value is @code{nil}. @node Time of Day @section Time of Day +@cindex time of day This section explains how to determine the current time and time zone. @cindex epoch - Most of these functions represent time as a list of either four -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, or of three -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of -two integers, @code{(@var{sec-high} @var{sec-low})}. The integers -@var{sec-high} and @var{sec-low} give the high and low bits of an -integer number of seconds. This integer number, + Most of these functions represent time as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. +This represents the number of seconds from the @dfn{epoch} (January +1, 1970 at 00:00 UTC), using the formula: @ifnottex -@var{high} * 2**16 + @var{low}, +@var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + +@var{pico} * 10**@minus{}12. @end ifnottex @tex -$high*2^{16}+low$, +$high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970 -UTC) to the specified time. The third list element @var{microsec}, if -present, gives the number of microseconds from the start of that -second to the specified time. -Similarly, the fourth list element @var{picosec}, if present, gives -the number of picoseconds from the start of that microsecond to the -specified time. - - The return value of @code{current-time} represents time using four -integers, as do the timestamps in the return value of -@code{file-attributes} (@pxref{Definition of -file-attributes}). In function arguments, e.g., the @var{time-value} -argument to @code{current-time-string}, two-, three-, and four-integer -lists are accepted. You can convert times from the list -representation into standard human-readable strings using -@code{current-time}, or to other forms using the @code{decode-time} -and @code{format-time-string} functions documented in the following -sections. - -@defun current-time-string &optional time-value +The return value of @code{current-time} represents time using this +form, as do the timestamps in the return values of other functions +such as @code{file-attributes} (@pxref{Definition of +file-attributes}). In some cases, functions may return two- or +three-element lists, with omitted @var{microsec} and @var{picosec} +components defaulting to zero. + +@cindex time value + Function arguments, e.g., the @var{time} argument to +@code{current-time-string}, accept a more-general @dfn{time value} +format, which can be a list of integers as above, or a single number +for seconds since the epoch, or @code{nil} for the current time. You +can convert a time value into a human-readable string using +@code{current-time-string} and @code{format-time-string}, into a list +of integers using @code{seconds-to-time}, and into other forms using +@code{decode-time} and @code{float-time}. These functions are +described in the following sections. + +@defun current-time-string &optional time zone This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day @@ -1232,8 +1257,9 @@ characters from the beginning of the string rather than from the end, as the year might not have exactly four digits, and additional information may some day be added at the end. -The argument @var{time-value}, if given, specifies a time to format -(represented as a list of integers), instead of the current time. +The argument @var{time}, if given, specifies a time to format, +instead of the current time. The optional argument @var{zone} +defaults to the current time zone rule. @example @group @@ -1252,17 +1278,26 @@ multiple of 1000, but this may change as higher-resolution clocks become available. @end defun -@defun float-time &optional time-value +@defun float-time &optional time This function returns the current time as a floating-point number of -seconds since the epoch. The optional argument @var{time-value}, if -given, specifies a time (represented as a list of integers) to convert -instead of the current time. +seconds since the epoch. The optional argument @var{time}, if +given, specifies a time to convert instead of the current time. @emph{Warning}: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required. + +@code{time-to-seconds} is an alias for this function. @end defun -@defun current-time-zone &optional time-value +@defun seconds-to-time time +This function converts a time value to list-of-integer form. +For example, if @var{time} is a number, @code{(time-to-seconds +(seconds-to-time @var{time}))} equals the number unless overflow +or rounding errors occur. +@end defun + +@defun current-time-zone &optional time zone +@cindex time zone, current This function returns a list describing the time zone that the user is in. @@ -1277,28 +1312,42 @@ 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 (represented -as a list of integers) to analyze instead of the current time. +The argument @var{time}, if given, specifies a time value to +analyze instead of the current time. The optional argument @var{zone} +defaults to the current time zone rule. @end defun -The current time zone is determined by the @env{TZ} environment +@vindex TZ, environment variable +The default time zone is determined by the @env{TZ} environment variable. @xref{System Environment}. For example, you can tell Emacs -to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ} -is not in the environment, Emacs uses a platform-dependent default -time zone. +to default to universal time with @code{(setenv "TZ" "UTC0")}. If +@env{TZ} is not in the environment, Emacs uses system wall clock time, +which is a platform-dependent default time zone. + +@cindex time zone rule +Functions that convert to and from local time accept an optional +@dfn{time zone rule} argument, which specifies the conversion's time +zone and daylight saving time history. If the time zone rule is +omitted or @code{nil}, the conversion uses Emacs's default time zone. +If it is @code{t}, the conversion uses Universal Time. If it is +@code{wall}, the conversion uses the system wall clock time. If it is +a string, the conversion uses the time zone rule equivalent to setting +@env{TZ} to that string. @node Time Conversion @section Time Conversion +@cindex calendrical information +@cindex time conversion - These functions convert time values (lists of two to four integers, -as explained in the previous section) into calendrical information and -vice versa. + These functions convert time values (@pxref{Time of Day}) into +calendrical information and vice versa. - Many 32-bit operating systems are limited to time values containing -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, 64-bit and some 32-bit operating systems have larger time -values, and can represent times far in the past or future. + Many 32-bit operating systems are limited to system times containing +32 bits of information in their seconds component; these systems +typically handle only the times from 1901-12-13 20:45:52 UTC through +2038-01-19 03:14:07 UTC@. However, 64-bit and some 32-bit operating +systems have larger seconds components, 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 @@ -1306,13 +1355,14 @@ 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 +@defun decode-time &optional time zone This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return +you don't specify @var{time}, it decodes the current time, and similarly +@var{zone} defaults to the current time zone rule. 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}) +(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{utcoff}) @end example Here is what the elements mean: @@ -1336,30 +1386,30 @@ 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. +@item utcoff +An integer indicating the UTC offset in seconds, i.e., the number of +seconds east of Greenwich. @end table @strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. +@var{dow} and @var{utcoff}. @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}. +items of calendrical data into a list-of-integer 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 -@env{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. +The optional argument @var{zone} defaults to the current time zone rule. +In addition to the usual time zone rule values, it can also be a list +(as you would get from @code{current-time-zone}) or an integer (as +from @code{decode-time}), applied 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 @@ -1383,6 +1433,9 @@ on others, years as early as 1901 do work. @node Time Parsing @section Parsing and Formatting Times +@cindex time parsing +@cindex time formatting +@cindex formatting time values These functions convert time values to text in a string, and vice versa. Time values are lists of two to four integers (@pxref{Time of Day}). @@ -1392,9 +1445,12 @@ 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 +@defun format-time-string format-string &optional time zone + +This function converts @var{time} (or the current time, if +@var{time} is omitted) to a string according to +@var{format-string}. The conversion uses the time zone rule @var{zone} +(or the current time zone rule, if omitted). 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: @@ -1490,13 +1546,13 @@ 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. +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'' +@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. @@ -1514,12 +1570,6 @@ specified by @code{locale-coding-system} (@pxref{Locales}); after 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 - @defun format-seconds format-string seconds This function converts its argument @var{seconds} into a string of years, days, hours, etc., according to @var{format-string}. The @@ -1579,6 +1629,7 @@ most-positive-fixnum}). both elapsed and processor time, used by the Emacs process. @deffn Command emacs-uptime &optional format +@cindex uptime of Emacs This function returns a string representing the Emacs @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is running. The string is formatted by @code{format-seconds} according @@ -1592,7 +1643,7 @@ When called interactively, it prints the uptime in the echo area. @defun get-internal-run-time This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{high} @var{low} @var{microsec} +of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}, using the same format as @code{current-time} (@pxref{Time of Day}). @@ -1614,9 +1665,12 @@ interactively, it prints the duration in the echo area. @node Time Calculations @section Time Calculations +@cindex time calculations +@cindex comparing time values +@cindex calendrical computations These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). +(@pxref{Time of Day}). @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @@ -1625,26 +1679,26 @@ This returns @code{t} if time value @var{t1} is less than time value @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. +two time values, 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. +This returns the sum of two time values, as a time value. +One argument should 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})) +(time-add @var{time} @var{seconds}) @end example @end defun -@defun time-to-days time +@defun time-to-days time-value This function returns the number of days between the beginning of year -1 and @var{time}. +1 and @var{time-value}. @end defun -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. +@defun time-to-day-in-year time-value +This returns the day number within the year corresponding to @var{time-value}. @end defun @defun date-leap-year-p year @@ -1794,6 +1848,7 @@ cause anything special to happen. @node Idle Timers @section Idle Timers +@cindex 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 @@ -1801,9 +1856,8 @@ work just like ordinary timers. @deffn Command run-with-idle-timer secs repeat function &rest args Set up a timer which runs the next time Emacs is 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. +seconds. The value of @var{secs} may be a number or a value of the type +returned by @code{current-idle-time}. 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 @@ -1889,8 +1943,7 @@ idleness. Here's an example: (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})) + (time-add (current-idle-time) @var{break-length}) nil 'my-timer-function)))) @end example @@ -1915,10 +1968,10 @@ functions. @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. +@var{interrupt} is non-@code{nil}, 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. @@ -1988,20 +2041,11 @@ 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{}>}. +surrounded by @samp{<@dots{}>}. Be aware that sensitive information +(such as passwords) may end up recorded in the dribble file. 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}). @@ -2068,17 +2112,17 @@ 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 + +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}. @end deffn @node Sound Output @@ -2089,6 +2133,7 @@ See also @code{open-dribble-file} in @ref{Recording Input}. certain systems are supported; if you call @code{play-sound} on a system which cannot really do the job, it gives an error. +@c FIXME: Add indexes for Au and WAV? --xfq The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) or Sun Audio format (@samp{.au}). @@ -2148,9 +2193,9 @@ To define system-specific X11 keysyms, set the variable 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, +including the vendor-specific bit, @ifnottex --2**28), +@minus{}2**28), @end ifnottex @tex $-2^{28}$), @@ -2160,7 +2205,7 @@ 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 +@minus{}2**28 @end ifnottex @tex $-2^{28}$ @@ -2235,6 +2280,7 @@ saved session to restore. For Emacs, this argument is @samp{--smid @var{session}}. @defvar emacs-save-session-functions +@cindex session file Emacs supports saving state via a hook called @code{emacs-save-session-functions}. Emacs runs this hook when the session manager tells it that the window system is shutting down. The @@ -2274,11 +2320,13 @@ Emacs is restarted by the session manager. @node Desktop Notifications @section Desktop Notifications @cindex desktop notifications +@cindex notifications, on desktop Emacs is able to send @dfn{notifications} on systems that support the freedesktop.org Desktop Notifications Specification. In order to use this functionality, Emacs must have been compiled with D-Bus support, -and the @code{notifications} library must be loaded. +and the @code{notifications} library must be loaded. @xref{Top, , +D-Bus,dbus,D-Bus integration in Emacs}. @defun notifications-notify &rest params This function sends a notification to the desktop via D-Bus, @@ -2321,10 +2369,10 @@ be anything, though implementations are free not to display it. @item :timeout @var{timeout} The timeout time in milliseconds since the display of the notification -at which the notification should automatically close. If -1, the +at which the notification should automatically close. If @minus{}1, the notification's expiration time is dependent on the notification server's settings, and may vary for the type of notification. If 0, -the notification never expires. Default value is -1. +the notification never expires. Default value is @minus{}1. @item :urgency @var{urgency} The urgency level. It can be @code{low}, @code{normal}, or @code{critical}. @@ -2359,7 +2407,7 @@ The path to a sound file to play when the notification pops up. @item :sound-name @var{name} A themable named sound from the freedesktop.org sound naming specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the -notification pops up. Similar to the icon name, only for sounds. An +notification pops up. Similar to the icon name, only for sounds. An example would be @samp{"message-new-instant"}. @item :suppress-sound @@ -2368,9 +2416,9 @@ ability. @item :resident When set the server will not automatically remove the notification -when an action has been invoked. The notification will remain resident +when an action has been invoked. The notification will remain resident in the server until it is explicitly removed by the user or by the -sender. This hint is likely only useful when the server has the +sender. This hint is likely only useful when the server has the @code{:persistence} capability. @item :transient @@ -2433,7 +2481,7 @@ argument of another @code{notifications-notify} call. For example: @end group @group -A message window opens on the desktop. Press "I agree" +A message window opens on the desktop. Press ``I agree''. @result{} Message 22, key "Confirm" pressed Message 22, closed due to "dismissed" @end group @@ -2507,17 +2555,18 @@ The server's version number. The specification version the server is compliant with. @end table -If @var{SPEC_VERSION} is @code{nil}, the server supports a +If @var{spec_version} is @code{nil}, the server supports a specification prior to @samp{"1.0"}. @end defun @node File Notifications @section Notifications on File Changes @cindex file notifications +@cindex watch, for filesystem events Several operating systems support watching of filesystems for changes of files. If configured properly, Emacs links a respective library -like @file{gfilenotify}, @file{inotify}, or @file{w32notify} +like @file{gfilenotify}, @file{inotify}, or @file{w32notify} statically. These libraries enable watching of filesystems on the local machine. @@ -2577,13 +2626,26 @@ any one of the following symbols: @item deleted @var{file} was deleted @item changed -@var{file} has changed +@var{file}'s contents has changed; with @file{w32notify} library, +reports attribute changes as well @item renamed @var{file} has been renamed to @var{file1} @item attribute-changed a @var{file} attribute was changed +@item stopped +watching @var{file} has been stopped @end table +Note that the @file{w32notify} library does not report +@code{attribute-changed} events. When some file's attribute, like +permissions or modification time, has changed, this library reports a +@code{changed} event. + +The @code{stopped} event reports, that watching the file has been +stopped. This could be because @code{file-notify-rm-watch} was called +(see below), or because the file being watched was deleted, or due to +another error reported from the underlying library. + @var{file} and @var{file1} are the name of the file(s) whose event is being reported. For example: @@ -2627,10 +2689,8 @@ being reported. For example: @end example Whether the action @code{renamed} is returned, depends on the used -watch library. It can be expected, when a directory is watched, and -both @var{file} and @var{file1} belong to this directory. Otherwise, -the actions @code{deleted} and @code{created} could be returned in a -random order. +watch library. Otherwise, the actions @code{deleted} and +@code{created} could be returned in a random order. @example @group @@ -2639,19 +2699,8 @@ random order. @end group @group -(file-notify-add-watch - "/var/tmp" '(change attribute-change) 'my-notify-callback) - @result{} 35025504 -@end group - -@group -(rename-file "/tmp/bla" "/var/tmp/bla") - @result{} ;; gfilenotify - Event (35025468 renamed "/tmp/bla" "/var/tmp/bla") - - @result{} ;; inotify - Event (35025504 created "/var/tmp/bla") - Event (35025468 deleted "/tmp/bla") +(delete-file "/tmp/bla") + @result{} Event (35025468 deleted "/tmp/bla") @end group @end example @end defun @@ -2662,6 +2711,71 @@ Removes an existing file watch specified by its @var{descriptor}. @code{file-notify-add-watch}. @end defun +@defun file-notify-valid-p descriptor +Checks a watch specified by its @var{descriptor} for validity. +@var{descriptor} should be an object returned by +@code{file-notify-add-watch}. + +A watch can become invalid if the file or directory it watches is +deleted, or if the watcher thread exits abnormally for any other +reason. Removing the watch by calling @code{file-notify-rm-watch} +also makes it invalid. + +@example +@group +(make-directory "/tmp/foo") + @result{} nil +@end group + +@group +(setq desc + (file-notify-add-watch + "/tmp/foo" '(change) 'my-notify-callback)) + @result{} 35025468 +@end group + +@group +(file-notify-valid-p desc) + @result{} t +@end group + +@group +(write-region "bla" nil "/tmp/foo/bla") + @result{} Event (35025468 created "/tmp/foo/.#bla") + Event (35025468 created "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/.#bla") +@end group + +@group +;; Deleting a file in the directory doesn't invalidate the watch. +(delete-file "/tmp/foo/bla") + @result{} Event (35025468 deleted "/tmp/foo/bla") +@end group + +@group +(write-region "bla" nil "/tmp/foo/bla") + @result{} Event (35025468 created "/tmp/foo/.#bla") + Event (35025468 created "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/.#bla") +@end group + +@group +;; Deleting the directory invalidates the watch. +(delete-directory "/tmp/foo" 'recursive) + @result{} Event (35025468 deleted "/tmp/foo/bla") + Event (35025468 deleted "/tmp/foo") + Event (35025468 stopped "/tmp/foo") +@end group + +@group +(file-notify-valid-p desc) + @result{} nil +@end group +@end example +@end defun + @node Dynamic Libraries @section Dynamically Loaded Libraries @cindex dynamic libraries @@ -2713,3 +2827,106 @@ be loaded through it. This variable is ignored if the given @var{library} is statically linked into Emacs. @end defvar + +@node Security Considerations +@section Security Considerations +@cindex security +@cindex hardening + +Like any application, Emacs can be run in a secure environment, where +the operating system enforces rules about access and the like. With +some care, Emacs-based applications can also be part of a security +perimeter that checks such rules. Although the default settings for +Emacs work well for a typical software development environment, they +may require adjustment in environments containing untrusted users that +may include attackers. Here is a compendium of security issues that +may be helpful if you are developing such applications. It is by no +means complete; it is intended to give you an idea of the security +issues involved, rather than to be a security checklist. + +@table @asis +@item Access control +Although Emacs normally respects access permissions of the underlying +operating system, in some cases it handles accesses specially. For +example, file names can have handlers that treat the files specially, +with their own access checking. @xref{Magic File Names}. Also, a +buffer can be read-only even if the corresponding file is writeable, +and vice versa, which can result in messages such as @samp{File passwd +is write-protected; try to save anyway? (yes or no)}. @xref{Read Only +Buffers}. + +@item Authentication +Emacs has several functions that deal with passwords, e.g., +@code{password-read}. Although these functions do not attempt to +broadcast passwords to the world, their implementations are not proof +against determined attackers with access to Emacs internals. For +example, even if Elisp code attempts to scrub a password from +its memory after using it, remnants of the password may still reside +in the garbage-collected free list. + +@item Code injection +Emacs can send commands to many other applications, and applications +should take care that strings sent as operands of these commands are +not misinterpreted as directives. For example, when sending a shell +command to rename a file @var{a} to @var{b}, do not simply use the +string @code{mv @var{a} @var{b}}, because either file name might start +with @samp{-}, or might contain shell metacharacters like @samp{;}. +Although functions like @code{shell-quote-argument} can help avoid +this sort of problem, they are not panaceas; for example, on a POSIX +platform @code{shell-quote-argument} quotes shell metacharacters but +not leading @samp{-}. @xref{Shell Arguments}. + +@item Coding systems +Emacs attempts to infer the coding systems of the files and network +connections it accesses. If it makes a mistake, or if the other +parties to the network connection disagree with Emacs's deductions, +the resulting system could be unreliable. Also, even when it infers +correctly, Emacs often can use bytes that other programs cannot. For +example, although to Emacs the NUL (all bits zero) byte is just a +character like any other, many other applications treat it as a string +terminator and mishandle strings or files containing NUL bytes. + +@item Environment and configuration variables +POSIX specifies several environment variables that can affect how +Emacs behaves. Any environment variable whose name consists entirely +of uppercase ASCII letters, digits, and the underscore may affect the +internal behavior of Emacs. Emacs uses several such variables, e.g., +@env{EMACSLOADPATH}. @xref{Library Search}. On some platforms some +environment variables (e.g., @env{PATH}, @env{POSIXLY_CORRECT}, +@env{SHELL}, @env{TMPDIR}) need to have properly-configured values in +order to get standard behavior for any utility Emacs might invoke. +Even seemingly-benign variables like @env{TZ} may have security +implications. + +Emacs has customization and other variables with similar +considerations. For example, if the variable @code{shell-file-name} +specifies a shell with nonstandard behavior, an Emacs-based +application may misbehave. + +@item Installation +When Emacs is installed, if the installation directory hierarchy can +be modified by untrusted users, the application cannot be trusted. +This applies also to the directory hierarchies of the programs that +Emacs uses, and of the files that Emacs reads and writes. + +@item Network access +Emacs often accesses the network, and you may want to configure it to +avoid network accesses that it would normally do. For example, unless +you set @code{tramp-mode} to @code{nil}, file names using a certain +syntax are interpreted as being network files, and are retrieved +across the network. @xref{Top, The Tramp Manual,, tramp, The Tramp +Manual}. + +@item Race conditions +Emacs applications have the same sort of race-condition issues that +other applications do. For example, even when +@code{(file-readable-p "foo.txt")} returns @code{t}, it could be that +@file{foo.txt} is unreadable because some other program changed the +file's permissions between the call to @code{file-readable-p} and now. + +@item Resource limits +When Emacs exhausts memory or other operating system resources, its +behavior can be less reliable, in that computations that ordinarily +run to completion may abort back to the top level. This may cause +Emacs to neglect operations that it normally would have done. +@end table diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index f4d6b590c77..21a8ddd5d03 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2013 Free Software Foundation, Inc. +@c Copyright (C) 2010-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Packaging @chapter Preparing Lisp code for distribution @@ -113,8 +113,10 @@ package loading is disabled if the user option This function initializes Emacs' internal record of which packages are installed, and loads them. The user option @code{package-load-list} specifies which packages to load; by default, all installed packages -are loaded. @xref{Package Installation,,, emacs, The GNU Emacs -Manual}. +are loaded. If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +loading the packages twice. @xref{Package Installation,,, emacs, The +GNU Emacs Manual}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually @@ -141,7 +143,8 @@ the various headers, as illustrated by the following example: ;; Author: J. R. Hacker <jrh@@example.com> ;; Version: 1.3 ;; Package-Requires: ((flange "1.0")) -;; Keywords: frobnicate +;; Keywords: multimedia, frobnicate +;; URL: http://example.com/jrhacker/superfrobnicate @dots{} @@ -177,6 +180,11 @@ on the @samp{flange} package, version 1.0 or higher. @xref{Library Headers}, for a description of the @samp{Package-Requires} header. If the header is omitted, the package has no dependencies. + The @samp{Keywords} and @samp{URL} headers are optional, but recommended. +The command @code{describe-package} uses these to add links to its +output. The @samp{Keywords} header should contain at least one +standard keyword from the @code{finder-known-keywords} list. + The file ought to also contain one or more autoload magic comments, as explained in @ref{Packaging Basics}. In the above example, a magic comment autoloads @code{superfrobnicator-mode}. @@ -284,7 +292,7 @@ case for the default GNU archive). Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file -access. Such ``local'' archives are mainly useful for testing. +access. Such local archives are mainly useful for testing. @end defopt A package archive is simply a directory in which the package files, @@ -336,3 +344,38 @@ otherwise, an error is raised. @noindent After you create an archive, remember that it is not accessible in the Package Menu interface unless it is in @code{package-archives}. + +@cindex package archive security +@cindex package signing +Maintaining a public package archive entails a degree of responsibility. +When Emacs users install packages from your archive, those packages +can cause Emacs to run arbitrary code with the permissions of the +installing user. (This is true for Emacs code in general, not just +for packages.) So you should ensure that your archive is +well-maintained and keep the hosting system secure. + + One way to increase the security of your packages is to @dfn{sign} +them using a cryptographic key. If you have generated a +private/public gpg key pair, you can use gpg to sign the package like +this: + +@c FIXME EasyPG / package-x way to do this. +@example +gpg -ba -o @var{file}.sig @var{file} +@end example + +@noindent +For a single-file package, @var{file} is the package Lisp file; +for a multi-file package, it is the package tar file. +You can also sign the archive's contents file in the same way. +Make the @file{.sig} files available in the same location as the packages. +You should also make your public key available for people to download; +e.g., by uploading it to a key server such as @url{http://pgp.mit.edu/}. +When people install packages from your archive, they can use +your public key to verify the signatures. + +A full explanation of these matters is outside the scope of this +manual. For more information on cryptographic keys and signing, +@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes +with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, +Emacs EasyPG Assistant Manual}. diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 69f1b80c431..72b76ce5c8f 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Positions @chapter Positions @@ -22,11 +22,11 @@ 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 +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 + See also the field feature (@pxref{Fields}), which provides functions that are used by many cursor-motion commands. @menu @@ -227,7 +227,7 @@ backward until encountering the front of a word, rather than forward. @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 +escape and character-quote syntax classes count as part of words. Otherwise, they do not. @end defopt @@ -350,10 +350,11 @@ would move to. @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. +the line following that. If @var{count} is negative, it moves point +@minus{}@var{count} lines backward, to the beginning of a line +preceding that. 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 @@ -362,7 +363,11 @@ 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. +the end of the last line, and the value will be 2. As an explicit +exception, if the last accessible line is non-empty, but has no +newline (e.g., if the buffer ends without a newline), the function +sets point to the end of that line, and the value returned by the +function counts that line as one line successfully moved. In an interactive call, @var{count} is the numeric prefix argument. @end deffn @@ -404,7 +409,7 @@ 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'' +is negative). In moving, it attempts to keep point in the @dfn{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 @@ -429,7 +434,7 @@ to use and more reliable (no dependence on goal column, etc.). @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'' +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 @@ -465,6 +470,7 @@ beginning or end of a line. @node Screen Lines @subsection Motion by Screen Lines +@cindex screen lines, moving by The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen @@ -486,11 +492,13 @@ 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-scans}. +thus take time proportional to the distance scanned. +@ignore +If you intend to use them heavily, Emacs provides caches which may +improve the performance of your code. @xref{Truncation, cache-long-scans}. +@end ignore -@defun vertical-motion count &optional window +@defun vertical-motion count &optional window cur-col 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. @@ -498,7 +506,11 @@ is negative, it moves up instead. The @var{count} argument can be a cons cell, @code{(@var{cols} . @var{lines})}, instead of an integer. Then the function moves by @var{lines} screen lines, and puts point @var{cols} columns from the -start of that screen line. +visual start of that screen line. Note that @var{cols} are counted +from the @emph{visual} start of the line; if the window is scrolled +horizontally (@pxref{Horizontal Scrolling}), the column on which point +will end is in addition to the number of columns by which the text is +scrolled. The return value is the number of screen lines over which point was moved. The value may be less in absolute value than @var{count} if @@ -508,6 +520,14 @@ 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. + +The optional argument @var{cur-col} specifies the current column when +the function is called. This is the window-relative horizontal +coordinate of point, measured in units of font width of the frame's +default face. Providing it speeds up the function, especially in very +long lines, because it doesn't have to go back in the buffer in order +to determine the current column. Note that @var{cur-col} is also +counted from the visual start of the line. @end defun @defun count-screen-lines &optional beg end count-final-newline window @@ -645,9 +665,19 @@ 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. +@deffn Command up-list &optional arg escape-strings no-syntax-crossing +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. If @var{escape-strings} is non-@code{nil} (as it is +interactively), move out of enclosing strings as well. If +@var{no-syntax-crossing} is non-@code{nil} (as it is interactively), prefer +to break out of any enclosing string instead of moving to the start of +a list broken across multiple strings. On error, location of point is +unspecified. +@end deffn + +@deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing +This function is just like @code{up-list}, but with a negated argument. @end deffn @deffn Command down-list &optional arg @@ -797,11 +827,11 @@ is zero or less. @section Excursions @cindex excursion - It is often useful to move point ``temporarily'' within a localized + It is often useful to move point temporarily within a localized portion of the program. This is called an @dfn{excursion}, and it is done with the @code{save-excursion} special form. This construct -remembers the initial identity of the current buffer, and its values -of point and the mark, and restores them after the excursion +remembers the initial identity of the current buffer, and its value +of point, and restores them after the excursion completes. It is the standard way to move point within one part of a program and avoid affecting the rest of the program, and is used thousands of times in the Lisp sources of Emacs. @@ -813,27 +843,26 @@ window configurations, see the forms described in @ref{Window Configurations} and in @ref{Frame Configurations}. @c frameset? @defspec save-excursion body@dots{} -@cindex mark excursion @cindex point excursion This 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 +value of point in it, evaluates @var{body}, and finally +restores the buffer and its saved value of point. Both saved values are +restored even in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). 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. @end defspec - Because @code{save-excursion} only saves point and mark for the + Because @code{save-excursion} only saves point for the buffer that was current at the start of the excursion, any changes -made to point and/or mark in other buffers, during the excursion, will +made to point in other buffers, during the excursion, will remain in effect afterward. This frequently leads to unintended consequences, so the byte compiler warns if you call @code{set-buffer} during an excursion: @example -Warning: Use `with-current-buffer' rather than +Warning: Use ‘with-current-buffer’ rather than save-excursion+set-buffer @end example @@ -863,10 +892,13 @@ 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}. +@defmac save-mark-and-excursion body@dots{} +@cindex mark excursion +@cindex point excursion +This macro is like @code{save-excursion}, but also saves and restores +the mark location and @code{mark-active}. This macro does what +@code{save-excursion} did before Emacs 25.1. +@end defmac @node Narrowing @section Narrowing @@ -955,7 +987,7 @@ 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-restriction} does @emph{not} restore point; 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 diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index e869bb86e40..35f3c6ca470 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Processes @@ -63,6 +63,8 @@ Processes}. @node Subprocess Creation @section Functions that Create Subprocesses +@cindex create subprocess +@cindex process creation There are three primitives that create a new subprocess in which to run a program. One of them, @code{start-process}, creates an asynchronous @@ -112,7 +114,7 @@ described below. argument that 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 +be @code{nil}, which says to discard the output, unless a custom 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. @@ -178,7 +180,7 @@ 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. +function. @xref{Security Considerations}. @example ;; @r{This example shows the behavior on GNU and Unix systems.} @@ -194,7 +196,7 @@ Here's an example of using @code{shell-quote-argument} to construct a shell command: @example -(concat "diff -c " +(concat "diff -u " (shell-quote-argument oldfile) " " (shell-quote-argument newfile)) @@ -288,7 +290,7 @@ Here are the possibilities: 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 +@item a buffer name (a string) Insert the output in a buffer with that name, before point. @item @code{t} @@ -501,17 +503,21 @@ inputinput@point{} @c It actually uses shell-command-switch, but no need to mention that here. @end defun -@defun call-process-shell-command command &optional infile destination display &rest args +@defun call-process-shell-command command &optional infile destination display This function executes the shell command @var{command} synchronously. -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}. +The arguments are handled as in @code{call-process}. An old calling +convention allowed to pass any number of additional arguments after +@var{display}, which were concatenated to @var{command}; this is still +supported, but strongly discouraged. @end defun -@defun process-file-shell-command command &optional infile destination display &rest args +@defun process-file-shell-command command &optional infile destination display 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. +@var{command} can be executed also on remote hosts. An old calling +convention allowed to pass any number of additional arguments after +@var{display}, which were concatenated to @var{command}; this is still +supported, but strongly discouraged. @end defun @defun shell-command-to-string command @@ -686,6 +692,113 @@ use the function @code{process-tty-name} (@pxref{Process Information}). @end defvar +@defun make-process &rest args +This function is like @code{start-process}, but takes keyword arguments. + +The arguments @var{args} are a list of keyword/argument pairs. +Omitting a keyword is always equivalent to specifying it with value +@code{nil}. 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 :buffer @var{buffer} +Use @var{buffer} as the process buffer. + +@item :command @var{command} +Use @var{command} as the command line of the process. @var{command} +is a list starting with the program's executable file name, followed +by strings to give to program as arguments. + +@item :coding @var{coding} +If @var{coding} is a symbol, it specifies the coding system to be +used for both reading and writing of data from and to the +connection. If @var{coding} is a cons cell +@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding} +will be used for reading and @var{encoding} for writing. + +If @var{coding} is @code{nil}, the default rules for finding the +coding system will apply. @xref{Default Coding Systems}. + +@item :connection-type @var{TYPE} +Initialize the type of device used to communicate with the subprocess. +Possible values are @code{pty} to use a pty, @code{pipe} to use a +pipe, or @code{nil} to use the default derived from the value of +the @code{process-connection-type} variable. + +@item :noquery @var{query-flag} +Initialize the process query flag to @var{query-flag}. +@xref{Query Before Exit}. + +@item :stop @var{stopped} +If @var{stopped} is non-@code{nil}, start the process in the +stopped state. + +@item :filter @var{filter} +Initialize the process filter to @var{filter}. + +@item :sentinel @var{sentinel} +Initialize the process sentinel to @var{sentinel}. + +@item :stderr @var{stderr} +Associate @var{stderr} with the standard error of the process. +@var{stderr} is either a buffer or a pipe process created with +@code{make-pipe-process}. +@end table + +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + +@defun make-pipe-process &rest args +This function creates a bidirectional pipe which can be attached to a +child process (currently only useful with the @code{:stderr} keyword +of @code{make-process}). + +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}. +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 :buffer @var{buffer} +Use @var{buffer} as the process buffer. + +@item :coding @var{coding} +If @var{coding} is a symbol, it specifies the coding system to be +used for both reading and writing of data from and to the +connection. If @var{coding} is a cons cell +@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding} +will be used for reading and @var{encoding} for writing. + +If @var{coding} is @code{nil}, the default rules for finding the +coding system will apply. @xref{Default Coding Systems}. + +@item :noquery @var{query-flag} +Initialize the process query flag to @var{query-flag}. +@xref{Query Before Exit}. + +@item :stop @var{stopped} +If @var{stopped} is non-@code{nil}, start the process in the +stopped state. + +@item :filter @var{filter} +Initialize the process filter to @var{filter}. + +@item :sentinel @var{sentinel} +Initialize the process sentinel to @var{sentinel}. +@end table + +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -696,7 +809,7 @@ but not necessarily right away. You can delete a process explicitly at any time. If you explicitly delete a terminated process 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}. +any), and calls the process sentinel. @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 @@ -719,7 +832,7 @@ 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 status, and runs the sentinel 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). @@ -734,6 +847,7 @@ happen sooner or later). @node Process Information @section Process Information +@cindex process information Several functions return information about processes. @@ -956,7 +1070,7 @@ This function sets the process plist of @var{process} to @var{plist}. 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. +data appears on the standard input of the subprocess. @c FIXME which? Some operating systems have limited space for buffered input in a @@ -1075,10 +1189,10 @@ job-control shells won't work when a pipe is used. See @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 @key{DEL} on +signal @code{SIGINT}. Outside of Emacs, typing the interrupt +character (normally @kbd{C-c} on some systems, and @key{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}'' +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 @@ -1090,10 +1204,8 @@ and cannot be handled by the subprocess. @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 -@c FIXME? Never heard of C-b being used for this. In readline, e.g., -@c bash, that is backward-word. -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside +@var{process}. This signal is the one sent by the quit +character (usually @kbd{C-\}) when you are not inside Emacs. @end defun @@ -1102,10 +1214,10 @@ 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'' +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 +typing @kbd{C-z} on the terminal Emacs uses to communicate with the subprocess. @end defun @@ -1130,12 +1242,12 @@ children of Emacs. @xref{System 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 (@pxref{Process -Buffers}), 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. + The output that a subprocess writes to its standard output stream +is passed to a function called the @dfn{filter function}. The default +filter function simply inserts the output into a buffer, which is +called the associated buffer of the process (@pxref{Process +Buffers}). If the process has no buffer then the default filter +discards the output. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1170,7 +1282,7 @@ 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. +* Process Buffers:: By default, 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. @@ -1188,11 +1300,12 @@ 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. + By default, process output is inserted in the associated buffer. +(You can change this by defining a custom filter function, +@pxref{Filter Functions}.) 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. @findex process-kill-buffer-query-function Killing the associated buffer of a process also kills the process. @@ -1221,13 +1334,12 @@ 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. +The default filter function uses this marker to decide where to +insert process output, 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. For an -example of a filter function that uses @code{process-mark}, +Custom filter functions normally should use this marker in the same fashion. +For an example of a filter function that uses @code{process-mark}, @pxref{Process Filter Example}. When the user is expected to enter input in the process buffer for @@ -1269,10 +1381,9 @@ subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). @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. +standard output from the associated process. @emph{All} output from +that process is passed to the filter. The default filter simply +outputs directly to the process buffer. The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs @@ -1301,8 +1412,8 @@ This makes it possible to use the Lisp debugger to debug the filter function. @xref{Debugger}. Many filter functions sometimes (or always) insert the output in the -process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to make sure that they save the +process's buffer, mimicking the actions of the default filter. +Such filter functions need to make sure that they save the current buffer, select the correct buffer (if different) before inserting output, and then restore the original buffer. They should also check whether the buffer is still alive, update the @@ -1358,14 +1469,18 @@ received text into a temporary buffer, which can then be searched. @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. +@var{filter} is @code{nil}, it gives the process the default filter, +which inserts the process output into the process buffer. @end defun @defun process-filter process -This function returns the filter function of @var{process}, or @code{nil} -if it has none. +This function returns the filter function of @var{process}. @end defun +In case the process's output needs to be passed to several filters, you can +use @code{add-function} to combine an existing filter with a new one. +@xref{Advising Functions}. + Here is an example of the use of a filter function: @smallexample @@ -1402,8 +1517,7 @@ backup.mss dland syllabus.mss @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: +the process mark to do insertion in the same fashion as the default filter: @smallexample @group @@ -1475,19 +1589,19 @@ 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}. +output is 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}. 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 +returns after that much time, even if there is no subprocess output. The argument @var{millisec} is obsolete (and should not be used), -because @var{seconds} can be a floating point number to specify +because @var{seconds} can be floating point to specify waiting a fractional number of seconds. If @var{seconds} is 0, the function accepts whatever output is pending but does not wait. @@ -1501,7 +1615,8 @@ 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 +got output from @var{process}, or from any process if @var{process} is +@code{nil}. It returns @code{nil} if the timeout expired before output arrived. @end defun @@ -1621,9 +1736,9 @@ while executing sentinels. @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. +@var{sentinel} is @code{nil}, then the process will have the default +sentinel, which inserts a message in the process's buffer when the +process status changes. Changes in process sentinels take effect immediately---if the sentinel is slated to be run but has not been called yet, and you specify a new @@ -1633,23 +1748,26 @@ sentinel, the eventual call to the sentinel will use the new one. @group (defun msg-me (process event) (princ - (format "Process: %s had the event `%s'" process event))) + (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' + @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. +This function returns the sentinel of @var{process}. @end defun +In case a process status changes need to be passed to several sentinels, you +can use @code{add-function} to combine an existing sentinel with a new one. +@xref{Advising Functions}. + @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 @@ -1717,7 +1835,7 @@ attribute and @var{value} is the value of that attribute. The various attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating-point, +Values that are numbers can be either integer or floating point, depending on the magnitude of the value. @table @code @@ -1759,7 +1877,7 @@ interruptible sleep (waiting for some event) @item "T" stopped, e.g., by a job control signal @item "Z" -``zombie'': a process that terminated, but was not reaped by its parent +zombie: a process that terminated, but was not reaped by its parent @end table @noindent @@ -1984,7 +2102,7 @@ server is stopped; a non-@code{nil} value means yes. @cindex @acronym{STARTTLS} network connections Emacs can create encrypted network connections, using either built-in or external support. The built-in support uses the GnuTLS -(``Transport Layer Security'') library; see +Transport Layer Security Library; see @uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. If your Emacs was compiled with GnuTLS support, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. For @@ -2004,7 +2122,7 @@ is modified as necessary to make it unique. The @var{buffer} 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 +unless you specify your own filter function to handle the output. If @var{buffer} is @code{nil}, it means that the connection is not associated with any buffer. @@ -2028,7 +2146,7 @@ The type of connection. Options are: An ordinary, unencrypted connection. @item tls @itemx ssl -A @acronym{TLS} (``Transport Layer Security'') connection. +A @acronym{TLS} (Transport Layer Security) connection. @item nil @itemx network Start with a plain connection, and if parameters @samp{:success} @@ -2065,6 +2183,12 @@ Regular expression matching a successful @acronym{STARTTLS} negotiation. If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs doesn't have built-in @acronym{TLS} support. +@item :warn-unless-encrypted @var{boolean} +If non-@code{nil}, and @code{:return-value} is also non-@code{nil}, +Emacs will warn if the connection isn't encrypted. This is useful for +protocols like @acronym{IMAP} and the like, where most users would +expect the network traffic to be encrypted. + @item :client-certificate @var{list-or-t} Either a list of the form @code{(@var{key-file} @var{cert-file})}, naming the certificate key file and certificate file itself, or @@ -2090,6 +2214,7 @@ The connection type: @samp{plain} or @samp{tls}. @end defun + @node Network Servers @section Network Servers @cindex network servers @@ -2112,7 +2237,7 @@ 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 +If the server has a non-default filter, 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. @@ -2209,7 +2334,7 @@ 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; @code{seqpacket} specifies a ``sequenced packet stream'' +connection; @code{seqpacket} specifies a sequenced packet stream connection. Both connections and servers can be of these types. @item :server @var{server-flag} @@ -2276,7 +2401,7 @@ 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 +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, @@ -2295,7 +2420,7 @@ has succeeded or failed. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or -server in the ``stopped'' state. +server in the stopped state. @item :buffer @var{buffer} Use @var{buffer} as the process buffer. @@ -2603,7 +2728,7 @@ Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. The flags defaults to @code{nil} if unspecified. @item :stop @var{bool} -Start process in the ``stopped'' state if @var{bool} is +Start process in the stopped state if @var{bool} is non-@code{nil}. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by @code{continue-process} and set by @@ -2643,7 +2768,7 @@ Here is an example: @cindex stopbits, in serial connections @cindex flowcontrol, in serial connections -This functions configures a serial port connection. Arguments are +This function configures a serial port connection. Arguments are specified as keyword/argument pairs. Attributes that are not given are re-initialized from the process's current configuration (available via the function @code{process-contact}), or set to reasonable default @@ -2733,7 +2858,7 @@ specification}, a special nested list describing named and typed @dfn{fields}. This specification controls the 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''. +is automatically recognized as risky. @cindex endianness @cindex big endian @@ -2742,8 +2867,8 @@ is automatically recognized as ``risky''. 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 +are @dfn{big endian} (also known as ``network byte ordering'') and +@dfn{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: diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 386d5bdde4c..adaf43159af 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Searching and Matching @@ -113,7 +113,7 @@ match. @end deffn @deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for +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. @@ -137,7 +137,7 @@ the ball boy!" @group (word-search-forward "Please find the ball, boy.") - @result{} 36 + @result{} 39 ---------- Buffer: foo ---------- He said "Please! Find @@ -160,16 +160,17 @@ 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. @findex word-search-regexp -Internal, @code{word-search-forward} and related functions use the +Internally, @code{word-search-forward} and related functions use the function @code{word-search-regexp} to convert @var{string} to a regular expression that ignores punctuation. @end deffn @deffn Command word-search-forward-lax string &optional limit noerror repeat This command is identical to @code{word-search-forward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. For instance, searching for @samp{ball boy} matches -@samp{ball boyee}, but does not match @samp{aball boy}. +the beginning or the end of @var{string} need not match a word +boundary, unless @var{string} begins or ends in whitespace. +For instance, searching for @samp{ball boy} matches @samp{ball boyee}, +but does not match @samp{balls boy}. @end deffn @deffn Command word-search-backward string &optional limit noerror repeat @@ -181,8 +182,8 @@ beginning of the match. @deffn Command word-search-backward-lax string &optional limit noerror repeat This command is identical to @code{word-search-backward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. +the beginning or the end of @var{string} need not match a word +boundary, unless @var{string} begins or ends in whitespace. @end deffn @node Searching and Case @@ -256,6 +257,8 @@ it easier to verify even very complex regexps. @node Syntax of Regexps @subsection Syntax of Regular Expressions +@cindex regexp syntax +@cindex 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 @@ -273,12 +276,12 @@ expression is ordinary, unless a @samp{\} precedes it. 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 +@samp{o} is a regular expression that matches only @samp{o}. 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 +the string. 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 @@ -293,6 +296,7 @@ need to use one of the special regular expression constructs. @node Regexp Special @subsubsection Special Characters in Regular Expressions +@cindex regexp, special characters in Here is a list of the characters that are special in a regular expression. @@ -304,7 +308,7 @@ expression. 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 +@samp{b}. @item @samp{*} @cindex @samp{*} in regexp @@ -355,7 +359,7 @@ preceding expression either once or not at all. For example, @item @samp{*?}, @samp{+?}, @samp{??} @cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} +These are @dfn{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 @@ -488,7 +492,7 @@ 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 +@samp{\} is @code{"\\\\"}. @end table @strong{Please note:} For historical compatibility, special characters @@ -496,7 +500,7 @@ 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 +special character anyway, regardless of where it appears. As a @samp{\} is not special inside a character alternative, it can never remove the special meaning of @samp{-} or @samp{]}. So you @@ -537,11 +541,15 @@ and what they mean: @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.) +This matches any letter or digit. For multibyte characters, it +matches characters whose Unicode @samp{general-category} property +(@pxref{Character Properties}) indicates they are alphabetic or +decimal number characters. @item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) +This matches any letter. For multibyte characters, it matches +characters whose Unicode @samp{general-category} property +(@pxref{Character Properties}) indicates they are alphabetic +characters. @item [:blank:] This matches space and tab only. @item [:cntrl:] @@ -550,8 +558,11 @@ This matches any @acronym{ASCII} control character. 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. +This matches graphic characters---everything except whitespace, +@acronym{ASCII} and non-@acronym{ASCII} control characters, +surrogates, and codepoints unassigned by Unicode, as indicated by the +Unicode @samp{general-category} property (@pxref{Character +Properties}). @item [:lower:] This matches any lower-case letter, as determined by the current case table (@pxref{Case Tables}). If @code{case-fold-search} is @@ -561,8 +572,8 @@ 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. +This matches any printing character---either whitespace, or a graphic +character matched by @samp{[:graph:]}. @item [:punct:] This matches any punctuation character. (At present, for multibyte characters, it matches anything that has non-word syntax.) @@ -599,14 +610,14 @@ a table of the special @samp{\} constructs. 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 +@var{b} matches. Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill +but no other string. @samp{\|} applies to the largest possible surrounding expressions. Only a surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill +@samp{\|}. If you need full backtracking capability to handle multiple uses of @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX @@ -785,7 +796,7 @@ matches the empty string, but only at point. 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{ball} or @samp{balls} as a separate word. @samp{\b} matches at the beginning or end of the buffer (or string) regardless of what text appears next to it. @@ -893,6 +904,7 @@ beyond the minimum needed to end a sentence. These functions operate on regular expressions. +@cindex quote special characters in regexp @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 @@ -923,6 +935,7 @@ whitespace: @end example @end defun +@cindex optimize regexp @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 @@ -982,10 +995,11 @@ list of characters @var{chars}. @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}. +expression (@pxref{Syntax of Regexps}) 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 @@ -1088,7 +1102,7 @@ For example, 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 +If this function finds a match, the index of the first character beyond the match is available as @code{(match-end 0)}. @xref{Match Data}. @example @@ -1146,13 +1160,7 @@ 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}. - -If @var{greedy} is non-@code{nil}, this function extends the match -backwards as far as possible, stopping when a single additional -previous character cannot be part of a match for regexp. When the -match is extended, its starting position is allowed to occur before -@var{limit}. +found must begin at or after @var{limit}. Here's an example: @example @group @@ -1168,6 +1176,12 @@ comes back" twice. @end group @end example +If @var{greedy} is non-@code{nil}, this function extends the match +backwards as far as possible, stopping when a single additional +previous character cannot be part of a match for regexp. When the +match is extended, its starting position is allowed to occur before +@var{limit}. + @c http://debbugs.gnu.org/5689 As a general recommendation, try to avoid using @code{looking-back} wherever possible, since it is slow. For this reason, there are no @@ -1283,7 +1297,7 @@ If you did the last search in a buffer, you should omit the the current buffer is the one in which you performed the last search. Then this function edits the buffer, replacing the matched text with @var{replacement}. It leaves point at the end of the replacement -text, and returns @code{t}. +text. If you performed the last search on a string, pass the same string as @var{string}. Then this function returns a new string, in which the @@ -1411,8 +1425,9 @@ has no text properties. @end defun @defun match-beginning count -This function returns the position of the start of the text matched by the -last regular expression searched for, or a subexpression of it. +If the last regular expression search found a match, this function +returns the position of the start of the matching text or of 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 @@ -1744,7 +1759,7 @@ in two ways: @itemize @bullet @item -The ``key bindings'' are not commands, just symbols that are meaningful +The key bindings are not commands, just symbols that are meaningful to the functions that use this map. @item @@ -1755,7 +1770,7 @@ event and look it up ``by hand''. @end itemize @end defvar -Here are the meaningful ``bindings'' for @code{query-replace-map}. +Here are the meaningful bindings for @code{query-replace-map}. Several of them are meaningful only for @code{query-replace} and friends. @@ -1772,7 +1787,7 @@ questions, assuming that the answers will be ``no''. @item exit-prefix Like @code{exit}, but add the key that was pressed to -@code{unread-comment-events}. +@code{unread-command-events} (@pxref{Event Input Misc}). @item act-and-exit Answer this question ``yes'', and give up on the entire series of @@ -1820,7 +1835,7 @@ Display some help, then ask again. @defvar multi-query-replace-map This variable holds a keymap that extends @code{query-replace-map} by providing additional keybindings that are useful in multi-buffer -replacements. The additional ``bindings'' are: +replacements. The additional bindings are: @table @code @item automatic-all diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 00384de7ec8..84a7c325424 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Sequences Arrays Vectors @@ -72,6 +72,7 @@ string, bool-vector, or char-table, @code{nil} otherwise. @cindex vector length @cindex sequence length @cindex char-table length +@anchor{Definition of 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 @@ -107,12 +108,13 @@ Emacs character code. @noindent See also @code{string-bytes}, in @ref{Text Representations}. -If you need to compute the width of a string on display, you should -use @code{string-width} (@pxref{Width}), not @code{length}, since -@code{length} only counts the number of characters, but does not +If you need to compute the width of a string on display, you should use +@code{string-width} (@pxref{Size of Displayed Text}), not @code{length}, +since @code{length} only counts the number of characters, but does not account for the display width of each character. @defun elt sequence index +@anchor{Definition of elt} @cindex elements of sequences This function returns the element of @var{sequence} indexed by @var{index}. Legitimate values of @var{index} are integers ranging @@ -217,6 +219,794 @@ y @result{} [foo (69 2)] @end example @end defun +@defun reverse sequence +@cindex string reverse +@cindex list reverse +@cindex vector reverse +@cindex sequence reverse +This function creates a new sequence whose elements are the elements +of @var{sequence}, but in reverse order. The original argument @var{sequence} +is @emph{not} altered. Note that char-tables cannot be reversed. + +@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 +@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 +@group +(setq x "xyzzy") + @result{} "xyzzy" +@end group +@group +(reverse x) + @result{} "yzzyx" +x + @result{} "xyzzy" +@end group +@end example +@end defun + +@defun nreverse sequence +@cindex reversing a string +@cindex reversing a list +@cindex reversing a vector + This function reverses the order of the elements of @var{sequence}. +Unlike @code{reverse} the original @var{sequence} may be modified. + + 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 + + For the vector, it is even simpler because you don't need setq: + +@example +(setq x [1 2 3 4]) + @result{} [1 2 3 4] +(nreverse x) + @result{} [4 3 2 1] +x + @result{} [4 3 2 1] +@end example + +Note that unlike @code{reverse}, this function doesn't work with strings. +Although you can alter string data by using @code{aset}, it is strongly +encouraged to treat strings as immutable. + +@end defun + +@defun sort sequence predicate +@cindex stable sort +@cindex sorting lists +@cindex sorting vectors +This function sorts @var{sequence} stably. Note that this function doesn't work +for all sequences; it may be used only for lists and vectors. If @var{sequence} +is a list, it is modified destructively. This functions returns the sorted +@var{sequence} and 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{sequence}. 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} for lists is that it rearranges the +cons cells forming @var{sequence} 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{sequence}; +the cons cell that originally contained the element @code{a} in +@var{sequence} 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 + +For the better understanding of what stable sort is, consider the following +vector example. After sorting, all items whose @code{car} is 8 are grouped +at the beginning of @code{vector}, but their relative order is preserved. +All items whose @code{car} is 9 are grouped at the end of @code{vector}, +but their relative order is also preserved: + +@example +@group +(setq + vector + (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz") + '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff"))) + @result{} [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz") + (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")] +@end group +@group +(sort vector (lambda (x y) (< (car x) (car y)))) + @result{} [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee") + (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")] +@end group +@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 + +@cindex sequence functions in seq +@cindex seq library + The @file{seq.el} library provides the following additional sequence +manipulation macros and functions, prefixed with @code{seq-}. To use +them, you must first load the @file{seq} library. + + All functions defined in this library are free of side-effects; +i.e., they do not modify any sequence (list, vector, or string) that +you pass as an argument. Unless otherwise stated, the result is a +sequence of the same type as the input. For those functions that take +a predicate, this should be a function of one argument. + + The @file{seq.el} library can be extended to work with additional +types of sequential data-structures. For that purpose, all functions +are defined using @code{cl-defgeneric}. + +@defun seq-elt sequence index + This function the element at the index @var{index} in +@var{sequence}. @var{index} can be an integer from zero up to the +length of @var{sequence} minus one. For out-of-range values on +built-in sequence types, @code{seq-elt} behaves like @code{elt}. +@xref{Definition of elt}. + +@example +@group +(seq-elt [1 2 3 4] 2) +@result{} 3 +@end group + + @code{seq-elt} returns settable places using @code{setf}. + +@group +(setq vec [1 2 3 4]) +(setf (seq-elt vec 2) 5) +vec +@result{} [1 2 5 4] +@end group +@end example +@end defun + +@defun seq-length sequence + This function returns the number of elements in @var{sequence}. For +built-in sequence types, @code{seq-length} behaves like @code{length}. +@xref{Definition of length}. +@end defun + +@defun seq-p sequence + This function returns non-@code{nil} if @var{sequence} is a sequence +(a list or array), or any additional type of sequence defined via +@file{seq.el} generic functions. + +@example +@group +(seq-p [1 2]) +@result{} t +@end group +@group +(seq-p 2) +@result{} nil +@end group +@end example +@end defun + +@defun seq-drop sequence n + This function returns all but the first @var{n} (an integer) +elements of @var{sequence}. If @var{n} is negative or zero, +the result is @var{sequence}. + +@example +@group +(seq-drop [1 2 3 4 5 6] 3) +@result{} [4 5 6] +@end group +@group +(seq-drop "hello world" -4) +@result{} "hello world" +@end group +@end example +@end defun + +@defun seq-take sequence n + This function returns the first @var{n} (an integer) elements of +@var{sequence}. If @var{n} is negative or zero, the result +is @code{nil}. + +@example +@group +(seq-take '(1 2 3 4) 3) +@result{} (1 2 3) +@end group +@group +(seq-take [1 2 3 4] 0) +@result{} [] +@end group +@end example +@end defun + +@defun seq-take-while predicate sequence + This function returns the members of @var{sequence} in order, +stopping before the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (1 2 3) +@end group +@group +(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6]) +@result{} [] +@end group +@end example +@end defun + +@defun seq-drop-while predicate sequence + This function returns the members of @var{sequence} in order, +starting from the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (-1 -2) +@end group +@group +(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6]) +@result{} [1 4 6] +@end group +@end example +@end defun + +@defun seq-do function sequence + This function applies @var{function} to each element of +@var{sequence} in turn (presumably for side effects) and returns +@var{sequence}. +@end defun + +@defun seq-map function sequence + This function returns the result of applying @var{function} to each +element of @var{sequence}. The returned value is a list. + +@example +@group +(seq-map #'1+ '(2 4 6)) +@result{} (3 5 7) +@end group +@group +(seq-map #'symbol-name [foo bar]) +@result{} ("foo" "bar") +@end group +@end example +@end defun + +@defun seq-mapn function &rest sequences + This function returns the result of applying @var{function} to each +element of @var{sequences}. The arity of @var{function} must match +the number of sequences. Mapping stops at the shortest sequence, and +the returned value is a list. + +@example +@group +(seq-mapn #'+ '(2 4 6) '(20 40 60)) +@result{} (22 44 66) +@end group +@group +(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"]) +@result{} ("moskitobee" "bitesting") +@end group +@end example +@end defun + +@defun seq-filter predicate sequence +@cindex filtering sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns non-@code{nil}. + +@example +@group +(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (1 3 5) +@end group +@group +(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-remove predicate sequence +@cindex removing from sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (-1 -3) +@end group +@group +(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-reduce function sequence initial-value +@cindex reducing sequences + This function returns the result of calling @var{function} with +@var{initial-value} and the first element of @var{sequence}, then calling +@var{function} with that result and the second element of @var{sequence}, +then with that result and the third element of @var{sequence}, etc. +@var{function} should be a function of two arguments. If +@var{sequence} is empty, this returns @var{initial-value} without +calling @var{function}. + +@example +@group +(seq-reduce #'+ [1 2 3 4] 0) +@result{} 10 +@end group +@group +(seq-reduce #'+ '(1 2 3 4) 5) +@result{} 15 +@end group +@group +(seq-reduce #'+ '() 3) +@result{} 3 +@end group +@end example +@end defun + +@defun seq-some predicate sequence + This function returns the first non-@code{nil} value returned by +applying @var{predicate} to each element of @var{sequence} in turn. + +@example +@group +(seq-some #'numberp ["abc" 1 nil]) +@result{} t +@end group +@group +(seq-some #'numberp ["abc" "def"]) +@result{} nil +@end group +@group +(seq-some #'null ["abc" 1 nil]) +@result{} t +@end group +@group +(seq-some #'1+ [2 4 6]) +@result{} 3 +@end group +@end example +@end defun + +@defun seq-find predicate sequence &optional default + This function returns the first element for which @var{predicate} +returns non-@code{nil} in @var{sequence}. If no element matches +@var{predicate}, @var{default} is returned. + +Note that this function has an ambiguity if the found element is +identical to @var{default}, as it cannot be known if an element was +found or not. + +@example +@group +(seq-find #'numberp ["abc" 1 nil]) +@result{} 1 +@end group +@group +(seq-find #'numberp ["abc" "def"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-every-p predicate sequence + This function returns non-@code{nil} if applying @var{predicate} +to every element of @var{sequence} returns non-@code{nil}. + +@example +@group +(seq-every-p #'numberp [2 4 6]) +@result{} t +@end group +@group +(seq-some #'numberp [2 4 "6"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-empty-p sequence + This function returns non-@code{nil} if @var{sequence} is empty. + +@example +@group +(seq-empty-p "not empty") +@result{} nil +@end group +@group +(seq-empty-p "") +@result{} t +@end group +@end example +@end defun + +@defun seq-count predicate sequence + This function returns the number of elements in @var{sequence} for which +@var{predicate} returns non-@code{nil}. + +@example +(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2]) +@result{} 2 +@end example +@end defun + +@cindex sorting sequences +@defun seq-sort function sequence + This function returns a copy of @var{sequence} that is sorted +according to @var{function}, a function of two arguments that returns +non-@code{nil} if the first argument should sort before the second. +@end defun + +@defun seq-contains sequence elt &optional function + This function returns the first element in @var{sequence} that is equal to +@var{elt}. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-contains '(symbol1 symbol2) 'symbol1) +@result{} symbol1 +@end group +@group +(seq-contains '(symbol1 symbol2) 'symbol3) +@result{} nil +@end group +@end example + +@end defun + +@defun seq-position sequence elt &optional function + This function returns the index of the first element in +@var{sequence} that is equal to @var{elt}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use instead of the default @code{equal}. + +@example +@group +(seq-position '(a b c) 'b) +@result{} 1 +@end group +@group +(seq-position '(a b c) 'd) +@result{} nil +@end group +@end example +@end defun + + +@defun seq-uniq sequence &optional function + This function returns a list of the elements of @var{sequence} with +duplicates removed. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-uniq '(1 2 2 1 3)) +@result{} (1 2 3) +@end group +@group +(seq-uniq '(1 2 2.0 1.0) #'=) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-subseq sequence start &optional end + This function returns a subset of @var{sequence} from @var{start} +to @var{end}, both integers (@var{end} defaults to the last element). +If @var{start} or @var{end} is negative, it counts from the end of +@var{sequence}. + +@example +@group +(seq-subseq '(1 2 3 4 5) 1) +@result{} (2 3 4 5) +@end group +@group +(seq-subseq '[1 2 3 4 5] 1 3) +@result{} [2 3] +@end group +@group +(seq-subseq '[1 2 3 4 5] -3 -1) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-concatenate type &rest sequences + This function returns a sequence of type @var{type} made of the +concatenation of @var{sequences}. @var{type} may be: @code{vector}, +@code{list} or @code{string}. + +@example +@group +(seq-concatenate 'list '(1 2) '(3 4) [5 6]) +@result{} (1 2 3 5 6) +@end group +@group +(seq-concatenate 'string "Hello " "world") +@result{} "Hello world" +@end group +@end example +@end defun + +@defun seq-mapcat function sequence &optional type + This function returns the result of applying @code{seq-concatenate} +to the result of applying @var{function} to each element of +@var{sequence}. The result is a sequence of type @var{type}, or a +list if @var{type} is @code{nil}. + +@example +@group +(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4))) +@result{} (1 2 3 4 5 6) +@end group +@end example +@end defun + +@defun seq-partition sequence n + This function returns a list of the elements of @var{sequence} +grouped into sub-sequences of length @var{n}. The last sequence may +contain less elements than @var{n}. @var{n} must be an integer. If +@var{n} is a negative integer or 0, nil is returned. + +@example +@group +(seq-partition '(0 1 2 3 4 5 6 7) 3) +@result{} ((0 1 2) (3 4 5) (6 7)) +@end group +@end example +@end defun + +@defun seq-intersection sequence1 sequence2 &optional function + This function returns a list of the elements that appear both in +@var{sequence1} and @var{sequence2}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use to compare elements instead of the default @code{equal}. + +@example +@group +(seq-intersection [2 3 4 5] [1 3 5 6 7]) +@result{} (3 5) +@end group +@end example +@end defun + + +@defun seq-difference sequence1 sequence2 &optional function + This function returns a list of the elements that appear in +@var{sequence1} but not in @var{sequence2}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use to compare elements instead of the default @code{equal}. + +@example +@group +(seq-difference '(2 3 4 5) [1 3 5 6 7]) +@result{} (2 4) +@end group +@end example +@end defun + +@defun seq-group-by function sequence + This function separates the elements of @var{sequence} into an alist +whose keys are the result of applying @var{function} to each element +of @var{sequence}. Keys are compared using @code{equal}. + +@example +@group +(seq-group-by #'integerp '(1 2.1 3 2 3.2)) +@result{} ((t 1 3 2) (nil 2.1 3.2)) +@end group +@group +(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4))) +@result{} ((b (b 2)) (a (a 1) (a 3)) (c (c 4))) +@end group +@end example +@end defun + +@defun seq-into sequence type + This function converts the sequence @var{sequence} into a sequence +of type @var{type}. @var{type} can be one of the following symbols: +@code{vector}, @code{string} or @code{list}. + +@example +@group +(seq-into [1 2 3] 'list) +@result{} (1 2 3) +@end group +@group +(seq-into nil 'vector) +@result{} [] +@end group +@group +(seq-into "hello" 'vector) +@result{} [104 101 108 108 111] +@end group +@end example +@end defun + +@defun seq-min sequence + This function returns the smallest element of +@var{sequence}. @var{sequence} must be a sequence of numbers or +markers. + +@example +@group +(seq-min [3 1 2]) +@result{} 1 +@end group +@group +(seq-min "Hello") +@result{} 72 +@end group +@end example +@end defun + +@defun seq-max sequence + This function returns the largest element of +@var{sequence}. @var{sequence} must be a sequence of numbers or +markers. + +@example +@group +(seq-max [1 3 2]) +@result{} 3 +@end group +@group +(seq-max "Hello") +@result{} 111 +@end group +@end example +@end defun + +@defmac seq-doseq (var sequence) body@dots{} +@cindex sequence iteration + This macro is like @code{dolist}, except that @var{sequence} can be a list, +vector or string (@pxref{Iteration} for more information about the +@code{dolist} macro). This is primarily useful for side-effects. +@end defmac + +@defmac seq-let arguments sequence body@dots{} +@cindex sequence destructuring + This macro binds the variables defined in @var{arguments} to the +elements of the sequence @var{sequence}. @var{arguments} can itself +include sequences allowing for nested destructuring. + +The @var{arguments} sequence can also include the @code{&rest} marker +followed by a variable name to be bound to the rest of +@code{sequence}. + +@example +@group +(seq-let [first second] [1 2 3 4] + (list first second)) +@result{} (1 2) +@end group +@group +(seq-let (_ a _ b) '(1 2 3 4) + (list a b)) +@result{} (2 4) +@end group +@group +(seq-let [a [b [c]]] [1 [2 [3]]] + (list a b c)) +@result{} (1 2 3) +@end group +@group +(seq-let [a b &rest others] [1 2 3 4] + others) +@end group +@result{} [3 4] +@end example +@end defmac + + @node Arrays @section Arrays @cindex array @@ -471,11 +1261,11 @@ each initialized to @var{object}. @cindex copying vectors This function returns a new vector containing all the elements of @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. +vectors, strings or bool-vectors. If no @var{sequences} are given, +the empty vector is returned. -The value is a newly constructed vector that is not @code{eq} to any -existing vector. +The value is either the empty vector, or is a newly constructed +nonempty vector that is not @code{eq} to any existing vector. @example @group @@ -600,13 +1390,13 @@ 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 +This function returns the contents of extra slot @var{n} (zero based) +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 +This function stores @var{value} in extra slot @var{n} (zero based) of @var{char-table}. @end defun @@ -699,7 +1489,7 @@ value into an element of the bool-vector, the effect is to store 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 + Several functions work specifically with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays. @@ -708,14 +1498,87 @@ Return a new bool-vector of @var{length} elements, each one initialized to @var{initial}. @end defun +@defun bool-vector &rest objects +This function creates and returns a bool-vector whose elements are the +arguments, @var{objects}. +@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. +There are also some bool-vector set operation functions, described below: + +@defun bool-vector-exclusive-or a b &optional c +Return @dfn{bitwise exclusive or} of bool vectors @var{a} and @var{b}. +If optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-union a b &optional c +Return @dfn{bitwise or} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-intersection a b &optional c +Return @dfn{bitwise and} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-set-difference a b &optional c +Return @dfn{set difference} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-not a &optional b +Return @dfn{set complement} of bool vector @var{a}. If optional +argument @var{b} is given, the result of this operation is stored into +@var{b}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-subsetp a b +Return @code{t} if every @code{t} value in @var{a} is also t in +@var{b}, @code{nil} otherwise. All arguments should be bool vectors of the +same length. +@end defun + +@defun bool-vector-count-consecutive a b i +Return the number of consecutive elements in @var{a} equal @var{b} +starting at @var{i}. @code{a} is a bool vector, @var{b} is @code{t} +or @code{nil}, and @var{i} is an index into @code{a}. +@end defun + +@defun bool-vector-count-population a +Return the number of elements that are @code{t} in bool vector @var{a}. +@end defun + + The printed form represents up to 8 boolean values as a single +character: + +@example +@group +(bool-vector t nil t nil) + @result{} #&4"^E" +(bool-vector) + @result{} #&0"" +@end group +@end example + +You can use @code{vconcat} to print a bool-vector like other vectors: + +@example +@group +(vconcat (bool-vector nil t nil t)) + @result{} [nil t nil t] +@end group +@end example + + Here is another example of creating, examining, and updating a +bool-vector: @example (setq bv (make-bool-vector 5 t)) @@ -741,7 +1604,7 @@ deletion, rotation, and modulo-indexed reference and traversal. An efficient ring data structure is implemented by the @code{ring} package. It provides the functions listed in this section. - Note that several ``rings'' in Emacs, like the kill ring and the + Note that several rings in Emacs, like the kill ring and the mark ring, are actually implemented as simple lists, @emph{not} using the @code{ring} package; thus the following functions won't work on them. diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 5b7e833b235..025b0e95c4e 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Read and Print @@ -113,8 +113,8 @@ When it is called with no arguments, it should return the next character. 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 +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 @@ -339,6 +339,25 @@ shared structures. @xref{Circular Objects}. Its default value is @code{t}. @end defvar +@cindex binary I/O in batch mode +When reading or writing from the standard input/output streams of the +Emacs process in batch mode, it is sometimes required to make sure any +arbitrary binary data will be read/written verbatim, and/or that no +translation of newlines to or from CR-LF pairs are performed. This +issue does not exist on Posix hosts, only on MS-Windows and MS-DOS@. +The following function allows to control the I/O mode of any standard +stream of the Emacs process. + +@defun set-binary-mode stream mode +Switch @var{stream} into binary or text I/O mode. If @var{mode} is +non-@code{nil}, switch to binary mode, otherwise switch to text mode. +The value of @var{stream} can be one of @code{stdin}, @code{stdout}, +or @code{stderr}. This function flushes any pending output data of +@var{stream} as a side effect, and returns the previous value of I/O +mode for @var{stream}. On Posix hosts, it always returns a +non-@code{nil} value and does nothing except flushing pending output. +@end defun + @node Output Streams @section Output Streams @cindex stream (for printing) @@ -615,10 +634,13 @@ spacing between calls. @end example @end defun -@defun terpri &optional stream +@defun terpri &optional stream ensure @cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. +This function outputs a newline to @var{stream}. The name stands for +``terminate print''. If @var{ensure} is non-@code{nil} no newline is printed +if @var{stream} is already at the beginning of a line. Note in this +case @var{stream} can not be a function and an error is signalled if +it is. This function returns @code{t} if a newline is printed. @end defun @defun write-char character &optional stream @@ -679,10 +701,15 @@ returns @code{"The buffer is foo"}. @defun pp object &optional stream This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a more ``pretty'' way. That is, it'll +@code{prin1}, but does it in a prettier way. That is, it'll indent and fill the object to make it more readable for humans. @end defun +If you need to use binary I/O in batch mode, e.g., use the functions +described in this section to write out arbitrary binary data or avoid +conversion of newlines on non-Posix hosts, see @ref{Input Functions, +set-binary-mode}. + @node Output Variables @section Variables Affecting Output @cindex output-controlling variables @@ -824,7 +851,7 @@ 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. The +This variable specifies how to print floating-point numbers. The default is @code{nil}, meaning use the shortest output that represents the number without losing information. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 340115062f9..143de82d9ad 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Strings and Characters @@ -48,13 +48,13 @@ Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated by a distinguished character code. Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions -documented in @ref{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}). However, note -that @code{length} should @emph{not} be used for computing the width -of a string on display; use @code{string-width} (@pxref{Width}) -instead. +operate on them with the general array and sequence functions documented +in @ref{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}). However, note that +@code{length} should @emph{not} be used for computing the width of a +string on display; use @code{string-width} (@pxref{Size of Displayed +Text}) instead. There are two text representations for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte and multibyte. @@ -92,6 +92,8 @@ representations and to encode and decode character codes. @node Predicates for Strings @section Predicates for Strings +@cindex predicates for strings +@cindex string predicates For more information about general sequence and array predicates, see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. @@ -113,6 +115,8 @@ character (i.e., an integer), @code{nil} otherwise. @node Creating Strings @section Creating Strings +@cindex creating strings +@cindex string creation The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. @@ -268,7 +272,7 @@ string to be used as a shell command, see @ref{Shell Arguments, combine-and-quote-strings}. @end defun -@defun split-string string &optional separators omit-nulls +@defun split-string string &optional separators omit-nulls trim This function splits @var{string} into substrings based on the regular expression @var{separators} (@pxref{Regular Expressions}). Each match for @var{separators} defines a splitting point; the substrings between @@ -350,6 +354,11 @@ practice: @result{} ("o" "o" "o") @end example +If the optional argument @var{trim} is non-@code{nil}, it should be a +regular expression to match text to trim from the beginning and end of +each substring. If trimming makes the substring empty, it is treated +as null. + If you need to split a string into a list of individual command-line arguments suitable for @code{call-process} or @code{start-process}, see @ref{Shell Arguments, split-string-and-unquote}. @@ -362,6 +371,8 @@ usual value is @w{@code{"[ \f\t\n\r\v]+"}}. @node Modifying Strings @section Modifying Strings +@cindex modifying strings +@cindex string modification The most basic way to alter the contents of an existing string is with @code{aset} (@pxref{Array Functions}). @code{(aset @var{string} @@ -395,6 +406,7 @@ zeros. It may also change @var{string}'s length. @node Text Comparison @section Comparison of Characters and Strings @cindex string equality +@cindex text comparison @defun char-equal character1 character2 This function returns @code{t} if the arguments represent the same @@ -418,8 +430,10 @@ the symbol names are used. Case is always significant, regardless of This function is equivalent to @code{equal} for comparing two strings (@pxref{Equality Predicates}). In particular, the text properties of -the two strings are ignored. But if either argument is not a string -or symbol, an error is signaled. +the two strings are ignored; use @code{equal-including-properties} if +you need to distinguish between strings that differ only in their text +properties. However, unlike @code{equal}, if either argument is not a +string or symbol, @code{string=} signals an error. @example (string= "abc" "abc") @@ -451,6 +465,59 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@defun string-collate-equalp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} and @var{string2} are +equal with respect to collation rules. A collation rule is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, characters with different coding points but +the same meaning might be considered as equal, like different grave +accent Unicode characters: + +@example +@group +(string-collate-equalp (string ?\uFF40) (string ?\u1FEF)) + @result{} t +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX +systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows +systems. + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-equal}. + +Do @emph{not} use this function to compare file names for equality, only +for sorting them. +@end defun + +@defun string-prefix-p string1 string2 &optional ignore-case +This function returns non-@code{nil} if @var{string1} is a prefix of +@var{string2}; i.e., if @var{string2} starts with @var{string1}. If +the optional argument @var{ignore-case} is non-@code{nil}, the +comparison ignores case differences. +@end defun + +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @cindex lexical comparison @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) @@ -509,6 +576,50 @@ are used. @code{string-lessp} is another name for @code{string<}. @end defun +@defun string-collate-lessp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} is less than +@var{string2} in collation order. A collation order is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, punctuation and whitespace characters might be considered +less significant for @ref{Sorting,,sorting}. + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp) + @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2") +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX +systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows +systems. The @var{locale} @code{"POSIX"} lets @code{string-collate-lessp} +behave like @code{string-lessp}: + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") + (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX"))) + @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12") +@end group +@end example + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-lessp}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If @@ -516,6 +627,13 @@ the optional argument @var{ignore-case} is non-@code{nil}, the comparison ignores case differences. @end defun +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case This function compares a specified part of @var{string1} with a specified part of @var{string2}. The specified part of @var{string1} @@ -526,7 +644,7 @@ string. Likewise, the specified part of @var{string2} runs from index @var{start2} up to index @var{end2}. The strings are compared by the numeric values of their characters. -For instance, @var{str1} is considered ``smaller than'' @var{str2} if +For instance, @var{str1} is considered less than @var{str2} if its first differing character has a smaller numeric value. If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case before comparing them. Unibyte strings are converted to @@ -567,7 +685,7 @@ against a string, can be used for a kind of string comparison; see 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 +Functions}) can convert a string representation of a Lisp object into an object. The functions @code{string-to-multibyte} and @code{string-to-unibyte} convert the text representation of a string (@pxref{Converting Representations}). @@ -581,9 +699,8 @@ are used primarily for making help messages. @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. +representation of @var{number}. The returned value starts with a +minus sign if the argument is negative. @example (number-to-string 256) @@ -607,20 +724,18 @@ See also the function @code{format} in @ref{Formatting Strings}. 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 +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 +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. +@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. +beginning, not just spaces and tabs.) If @var{string} cannot be +interpreted as a number, this function returns 0. @example (string-to-number "256") @@ -686,7 +801,7 @@ 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 +formatting feature described here; they differ from @code{format-message} only in how they use the result of formatting. @defun format string &rest objects @@ -700,6 +815,16 @@ are copied directly into the output, including their text properties, if any. @end defun +@defun format-message string &rest objects +@cindex curved quotes +@cindex curly quotes +This function acts like @code{format}, except it also converts any +curved single quotes in @var{string} as per the value of +@code{text-quoting-style}, and treats grave accent (@t{`}) and +apostrophe (@t{'}) as if they were curved single quotes. @xref{Keys +in Documentation}. +@end defun + @cindex @samp{%} in format @cindex format specification A format specification is a sequence of characters beginning with a @@ -777,15 +902,15 @@ integer. @samp{%x} uses lower case and @samp{%X} uses upper case. 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. +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. +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, +Replace the specification with notation for a floating-point number, using either exponential notation or decimal-point notation, whichever is shorter. @@ -798,20 +923,23 @@ specification is unusual in that it does not use a value. For example, Any other format character results in an @samp{Invalid format operation} error. - Here are several examples: + Here are several examples, which assume the typical +@code{text-quoting-style} settings: @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." + +(format-message + "The name of this buffer is ‘%s’." (buffer-name)) + @result{} "The name of this buffer is ‘strings.texi’." + +(format-message + "The buffer object prints as `%s'." (current-buffer)) + @result{} "The buffer object prints as ‘strings.texi’." @end group @end example @@ -833,7 +961,7 @@ the width specifier normally consists of spaces inserted on the left: 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 +In the following two 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, and needs 4 blank spaces as padding. In the second case, the string @code{"specification"} is 13 letters wide but @@ -841,12 +969,12 @@ is not truncated. @example @group -(format "The word `%7s' has %d letters in it." +(format "The word '%7s' has %d letters in it." "foo" (length "foo")) - @result{} "The word ` foo' has 3 letters in it." -(format "The word `%7s' has %d letters in it." + @result{} "The word ' foo' has 3 letters in it." +(format "The word '%7s' has %d letters in it." "specification" (length "specification")) - @result{} "The word `specification' has 13 letters in it." + @result{} "The word 'specification' has 13 letters in it." @end group @end example @@ -862,7 +990,7 @@ numbers and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. - The flag @samp{#} specifies an ``alternate form'' which depends on + 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}, @@ -885,12 +1013,12 @@ ignored. (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" +(format "'%-6d' is padded on the right" 123) + @result{} "'123 ' is padded on the right" -(format "The word `%-7s' actually has %d letters in it." +(format "The word '%-7s' actually has %d letters in it." "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." + @result{} "The word 'foo ' actually has 3 letters in it." @end group @end example @@ -1117,8 +1245,8 @@ Exits}). Some language environments 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 +environment, the @acronym{ASCII} capital I is downcased into +a Turkish dotless i (@samp{ı}). This can interfere with code that requires ordinary @acronym{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}, diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 82dfa0f4917..2605a3e7b5a 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Symbols @@ -176,7 +176,7 @@ cause complete confusion. @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 +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 @@ -525,7 +525,7 @@ The value is an expression for determining whether the named menu item should be enabled in menus. @xref{Simple Menu Items}. @item mode-class -If the value is @code{special}, the named major mode is ``special''. +If the value is @code{special}, the named major mode is special. @xref{Major Mode Conventions}. @item permanent-local diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 6bbd7a3a7b7..7a984e3d87b 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Syntax Tables @@ -98,7 +98,7 @@ serves as the name of the class when you need to specify a class. Usually, this 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 means ``escape character'' +@samp{\} as a designator character always stands for escape character syntax, regardless of whether the @samp{\} character actually has that syntax in the current syntax table. @ifnottex @@ -141,6 +141,7 @@ Internals}. @node Syntax Class Table @subsection Table of Syntax Classes +@cindex syntax class table Here is a table of syntax classes, the characters that designate them, their meanings, and examples of their use. @@ -202,7 +203,7 @@ 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 +double-quote for strings, and apostrophe (@samp{'}) for character constants. Human text has no string quote characters. We do not want quotation @@ -335,6 +336,7 @@ that this kind of comment can be nested. For a two-character comment delimiter, @samp{n} on either character makes it nestable. +@cindex comment style Emacs supports several comment styles simultaneously in any one syntax table. A comment style is a set of flags @samp{b}, @samp{c}, and @samp{n}, so there can be up to 8 different comment styles. @@ -375,7 +377,7 @@ character does not have the @samp{b} flag. @end table @item -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. +@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. @@ -409,6 +411,7 @@ is not a syntax table. @end defun @deffn Command modify-syntax-entry char syntax-descriptor &optional table +@cindex syntax entry, setting This function sets the syntax entry for @var{char} according to @var{syntax-descriptor}. @var{char} must be a character, or a cons cell of the form @code{(@var{min} . @var{max})}; in the latter case, @@ -589,6 +592,8 @@ in turn, repeatedly, until they all return @code{nil}. @node Motion and Syntax @section Motion and Syntax +@cindex moving across syntax classes +@cindex skipping characters of certain syntax This section describes functions for moving across characters that have certain syntax classes. @@ -628,12 +633,14 @@ expression prefix syntax class, and characters with the @samp{p} flag. @node Parsing Expressions @section Parsing Expressions +@cindex parsing expressions +@cindex scanning expressions This section describes functions for parsing and scanning balanced expressions. We will refer to such expressions as @dfn{sexps}, following the terminology of Lisp, even though these functions can act on languages other than Lisp. Basically, a sexp is either a balanced -parenthetical grouping, a string, or a ``symbol'' (i.e., a sequence +parenthetical grouping, a string, or a symbol (i.e., a sequence of characters whose syntax is either word constituent or symbol constituent). However, characters in the expression prefix syntax class (@pxref{Syntax Class Table}) are treated as part of the sexp if @@ -647,7 +654,7 @@ 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 +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), @@ -670,6 +677,7 @@ result, Emacs treats them as four consecutive empty string constants. @node Motion via Parsing @subsection Motion Commands Based on Parsing +@cindex motion based on parsing This section describes simple point-motion functions that operate based on parsing expressions. @@ -723,7 +731,7 @@ 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 +This function cannot tell whether the comments it traverses are embedded within a string. If they look like comments, it treats them as comments. @@ -735,6 +743,7 @@ cannot exceed that many. @node Position Parse @subsection Finding the Parse State for a Position +@cindex 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 @@ -916,6 +925,7 @@ nicely. @node Control Parsing @subsection Parameters to Control Parsing +@cindex parsing, control parameters @defvar multibyte-syntax-as-symbol If this variable is non-@code{nil}, @code{scan-sexps} treats all @@ -1057,6 +1067,7 @@ standard categories are available in all modes. the range @w{@samp{ }} to @samp{~}. You specify the name of a category when you define it with @code{define-category}. +@cindex category set 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} @@ -1073,18 +1084,27 @@ documentation @var{docstring}, for the category table @var{table}. Here's an example of defining a new category for characters that have strong right-to-left directionality (@pxref{Bidirectional Display}) -and using it in a special category table: +and using it in a special category table. To obtain the information +about the directionality of characters, the example code uses the +@samp{bidi-class} Unicode property (@pxref{Character Properties, +bidi-class}). @example (defvar special-category-table-for-bidi + ;; Make an empty category-table. (let ((category-table (make-category-table)) - (uniprop-table (unicode-property-table-internal 'bidi-class))) + ;; Create a char-table which gives the 'bidi-class' Unicode + ;; property for each character. + (uniprop-table (unicode-property-table-internal 'bidi-class))) (define-category ?R "Characters of bidi-class R, AL, or RLO" category-table) + ;; Modify the category entry of each character whose 'bidi-class' + ;; Unicode property is R, AL, or RLO -- these have a + ;; right-to-left directionality. (map-char-table #'(lambda (key val) - (if (memq val '(R AL RLO)) - (modify-category-entry key ?R category-table))) + (if (memq val '(R AL RLO)) + (modify-category-entry key ?R category-table))) uniprop-table) category-table)) @end example diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index c4250f2f0ba..6d9d26f0ad1 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Text @chapter Text @@ -54,10 +54,11 @@ the character after point. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Transposition:: Swapping two portions of a buffer. +* Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -161,6 +162,7 @@ the end of a line. @node Buffer Contents @section Examining Buffer Contents +@cindex buffer portion as string This section describes functions that allow a Lisp program to convert any portion of the text in the buffer into a string. @@ -218,16 +220,24 @@ This function returns the contents of the entire accessible portion of the current buffer, as a string. @end defun + If you need to make sure the resulting string, when copied to a +different location, will not change its visual appearance due to +reordering of bidirectional text, use the +@code{buffer-substring-with-bidi-context} function +(@pxref{Bidirectional Display, buffer-substring-with-bidi-context}). + @defun filter-buffer-substring start end &optional delete -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the wrapper hook -@code{filter-buffer-substring-functions}, and returns the result. The -obsolete variable @code{buffer-substring-filters} is also consulted. -If both of these variables are @code{nil}, the value is the unaltered -text from the buffer, i.e., what @code{buffer-substring} would -return. - -If @var{delete} is non-@code{nil}, this function deletes the text +This function filters the buffer text between @var{start} and @var{end} +using a function specified by the variable +@code{filter-buffer-substring-function}, and returns the result. + +The default filter function consults the obsolete wrapper hook +@code{filter-buffer-substring-functions}, and the obsolete variable +@code{buffer-substring-filters}. If both of these are @code{nil}, it +returns the unaltered text from the buffer, i.e., what +@code{buffer-substring} would return. + +If @var{delete} is non-@code{nil}, the function deletes the text between @var{start} and @var{end} after copying it, like @code{delete-and-extract-region}. @@ -235,20 +245,29 @@ 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{filter-buffer-substring-functions} to alter such text as it is -copied out of the buffer. +Major and minor modes can modify @code{filter-buffer-substring-function} +to alter such text as it is copied out of the buffer. @end defun -@c FIXME: `filter-buffer-substring-function' should be documented. +@defvar filter-buffer-substring-function +The value of this variable is a function that @code{filter-buffer-substring} +will call to do the actual work. The function receives three +arguments, the same as those of @code{filter-buffer-substring}, +which it should treat as per the documentation of that function. It +should return the filtered text (and optionally delete the source text). +@end defvar + +@noindent The following two variables are obsoleted by +@code{filter-buffer-substring-function}, but are still supported for +backward compatibility. + @defvar filter-buffer-substring-functions -This variable is a wrapper hook (@pxref{Running Hooks}), whose members -should be functions that accept four arguments: @var{fun}, -@var{start}, @var{end}, and @var{delete}. @var{fun} is a function -that takes three arguments (@var{start}, @var{end}, and @var{delete}), -and returns a string. In both cases, the @var{start}, @var{end}, and -@var{delete} arguments are the same as those of -@code{filter-buffer-substring}. +This obsolete variable is a wrapper hook, whose members should be functions +that accept four arguments: @var{fun}, @var{start}, @var{end}, and +@var{delete}. @var{fun} is a function that takes three arguments +(@var{start}, @var{end}, and @var{delete}), and returns a string. In +both cases, the @var{start}, @var{end}, and @var{delete} arguments are +the same as those of @code{filter-buffer-substring}. The first hook function is passed a @var{fun} that is equivalent to the default operation of @code{filter-buffer-substring}, i.e., it @@ -262,14 +281,12 @@ hook functions acting in sequence. @end defvar @defvar buffer-substring-filters -This variable is obsoleted by -@code{filter-buffer-substring-functions}, but is still supported for -backward compatibility. Its value should should be a list of -functions which accept a single string argument and return another -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 passed to @code{filter-buffer-substring-functions}. +The value of this obsolete variable should be a list of functions +that accept a single string argument and return another string. +The default @code{filter-buffer-substring} function 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 passed to @code{filter-buffer-substring-functions}. @end defvar @defun current-word &optional strict really-word @@ -333,10 +350,10 @@ 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. +Suppose you have the text @w{@samp{foobarbar haha!rara!}} in the +current buffer; 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) @@ -495,7 +512,7 @@ non-@code{nil} and the character inserted is in the table @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 +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}). @@ -561,7 +578,7 @@ error; if some of the text in it is read-only, it signals a 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, +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. @@ -771,6 +788,9 @@ space, or @var{n} spaces if @var{n} is specified. It returns @code{nil}. @end deffn +@c There is also cycle-spacing, but I cannot see it being useful in +@c Lisp programs, so it is not mentioned here. + @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 @@ -784,6 +804,19 @@ A blank line is defined as a line containing only tabs and spaces. @code{delete-blank-lines} returns @code{nil}. @end deffn +@deffn Command delete-trailing-whitespace start end +Delete trailing whitespace in the region defined by @var{start} and +@var{end}. + +This command deletes whitespace characters after the last +non-whitespace character in each line in the region. + +If this command acts on the entire buffer (i.e., if called +interactively with the mark inactive, or called from Lisp with +@var{end} @code{nil}), it also deletes all trailing lines at the end of the +buffer if the variable @code{delete-trailing-lines} is non-@code{nil}. +@end deffn + @node The Kill Ring @section The Kill Ring @cindex kill ring @@ -792,7 +825,7 @@ A blank line is defined as a line containing only tabs and spaces. 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'' +yanking (though they can still be undone); these are deletion functions. Most of the kill commands are primarily for interactive use, and are @@ -813,8 +846,8 @@ 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 +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 @@ -849,9 +882,9 @@ 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 + 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. @@ -859,7 +892,7 @@ list. @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 +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 @@ -1068,7 +1101,7 @@ because they take care of interaction with 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 +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}, @@ -1115,13 +1148,13 @@ 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 +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. To facilitate support for window systems that support multiple selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all +case, the first string is used as the most recent kill, and all the other strings are pushed onto the kill ring, for easy access by @code{yank-pop}. @@ -1153,7 +1186,7 @@ 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 +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 @@ -1205,7 +1238,7 @@ killed first. @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 +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 @@ -1253,7 +1286,8 @@ 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. +was at the end. Zero or more (@var{marker} . @var{adjustment}) +elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became @@ -1279,8 +1313,10 @@ Here's how you might undo the change: @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. +@var{adjustment} character positions. If the marker's location is +consistent with the (@var{text} . @var{position}) element preceding it +in the undo list, then 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 @@ -1387,7 +1423,7 @@ cannot specify any other buffer. This function returns @code{nil}. 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'' +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 @@ -1612,8 +1648,8 @@ Manual}. @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. @xref{Hard and Soft +newlines that have the @code{hard} text property. These hard +newlines act as paragraph separators. @xref{Hard and Soft Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. @end defvar @@ -1701,7 +1737,7 @@ is value of @code{indent-line-function} in Paragraph-Indent Text mode. @defopt left-margin This variable specifies the base left margin column. In Fundamental -mode, @kbd{C-j} indents to this column. This variable automatically +mode, @kbd{RET} indents to this column. This variable automatically becomes buffer-local when set in any fashion. @end defopt @@ -1787,7 +1823,7 @@ 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'' +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 @@ -1800,7 +1836,7 @@ whitespace. 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 +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 @@ -2185,7 +2221,7 @@ count from zero at the left margin. 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. +primitives. @xref{Size of Displayed Text}, for related functions. @defun current-indentation @comment !!Type Primitive Function @@ -2344,21 +2380,19 @@ a different meaning and does not use this variable. @end defvar @deffn Command indent-rigidly start end count -This command indents all lines starting between @var{start} +This function 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. +This preserves the shape of the affected region, moving it as a +rigid unit. -For example, if @var{count} is 3, this command adds 3 columns of -indentation to each of the lines beginning in the region specified. +This 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 every +line that begins in the specified region. -@c FIXME: I suggest using message-indent-citation as the example, or -@c just remove this paragraph. --xfq -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. +If called interactively with no prefix argument, this command invokes +a transient mode for adjusting indentation rigidly. @xref{Indentation +Commands,,, emacs, The GNU Emacs Manual}. @end deffn @deffn Command indent-code-rigidly start end columns &optional nochange-regexp @@ -2447,10 +2481,10 @@ column, this command does nothing. @end deffn @node Indent Tabs -@subsection Adjustable ``Tab Stops'' +@subsection Adjustable Tab Stops @cindex tabs stops for indentation - This section explains the mechanism for user-specified ``tab stops'' + 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 @@ -2462,19 +2496,19 @@ stop feature only in a few major modes, such as Text mode. @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. +stop column defined by @code{tab-stop-list}. @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. +This variable defines the tab stop columns used by @code{tab-to-tab-stop}. +It should be either @code{nil}, or a list of increasing integers, +which need not be evenly spaced. The list is implicitly +extended to infinity through repetition of the interval between the +last and penultimate elements (or @code{tab-width} if the list has +fewer than two elements). A value of @code{nil} means a tab stop +every @code{tab-width} columns. + +Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively. @end defopt @node Motion by Indent @@ -2646,6 +2680,8 @@ along with the characters; this includes such diverse functions as @node Examining Properties @subsection Examining Text Properties +@cindex examining text properties +@cindex text properties, examining The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use @@ -2681,6 +2717,13 @@ followed by the text properties. If @var{object} is a string, only text properties are considered, since strings never have overlays. @end defun +@defun get-pos-property position prop &optional object +This function is like @code{get-char-property}, except that it pays +attention to properties' stickiness and overlays' advancement settings +instead of the property of the character at (i.e., right after) +@var{position}. +@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. @@ -2730,6 +2773,8 @@ used instead. Here is an example: @node Changing Properties @subsection Changing Text Properties +@cindex changing text properties +@cindex text properties, changing The primitives for changing properties apply to a specified range of text in a buffer or string. The function @code{set-text-properties} @@ -2825,36 +2870,43 @@ Do not rely on the return value of this function. @end defun @defun add-face-text-property start end face &optional appendp object -@code{face} text attributes can be combined. If you want to make a -section both italic and green, you can either define a new face that -have those attributes, or you can add both these attributes separately -to text: +This function acts on the text between @var{start} and @var{end}, +adding the face @var{face} to the @code{face} text property. +@var{face} should be a valid value for the @code{face} property +(@pxref{Special Properties}), such as a face name or an anonymous face +(@pxref{Faces}). + +If any text in the region already has a non-@code{nil} @code{face} property, +those face(s) are retained. This function sets the @code{face} +property to a list of faces, with @var{face} as the first element (by +default) and the pre-existing faces as the remaining elements. If the +optional argument @var{append} is non-@code{nil}, @var{face} is +appended to the end of the list instead. Note that in a face list, +the first occurring value for each attribute takes precedence. + +For example, the following code would assign a italicized green face +to the text between @var{start} and @var{end}: @example (add-face-text-property @var{start} @var{end} 'italic) -(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00")) +(add-face-text-property @var{start} @var{end} '(:foreground "red")) +(add-face-text-property @var{start} @var{end} '(:foreground "green")) @end example -The attribute is (by default) prepended to the list of face -attributes, and the first attribute of the same type takes -precedence. So if you have two @code{:foreground} specifications, the -first one will take effect. - -If you pass in @var{appendp}, the attribute will be appended instead -of prepended, which means that it will have no effect if there is -already an attribute of the same type. - +The optional argument @var{object}, if non-@code{nil}, specifies a +buffer or string to act on, rather than the current buffer. If +@var{object} is a string, then @var{start} and @var{end} are +zero-based indices into the string. @end defun - The easiest way to make a string with text properties -is with @code{propertize}: + 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: +This function returns a copy of @var{string} with the text properties +@var{properties} added. 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 @@ -2886,6 +2938,8 @@ buffer but does not copy its properties. @node Property Search @subsection Text Property Search Functions +@cindex searching text properties +@cindex text properties, searching In typical use of text properties, most of the time several or many consecutive characters have the same value for a property. Rather than @@ -3081,6 +3135,9 @@ Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by dynamically updating the @code{face} property of characters based on the context. +The @code{add-face-text-property} function provides a convenient way +to set this text property. @xref{Changing Properties}. + @item font-lock-face @kindex font-lock-face @r{(text property)} This property specifies a value for the @code{face} property that Font @@ -3108,7 +3165,7 @@ 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. +the just-in-time font locking code. @item display This property activates various features that change the @@ -3197,6 +3254,11 @@ 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 inhibit-read-only +@kindex inhibit-read-only @r{(text property)} +If a character has the property @code{inhibit-read-only}, and the +buffer is read-only, editing the character in question is allowed. + @item invisible @kindex invisible @r{(text property)} A non-@code{nil} @code{invisible} property can make a character invisible @@ -3237,7 +3299,7 @@ overlay and text property strings present at the current buffer position. You can place the cursor on any desired character of these strings by giving that character a non-@code{nil} @code{cursor} text property. In addition, if the value of the @code{cursor} property is -an integer number, it specifies the number of buffer's character +an integer, it specifies the number of buffer's character positions, starting with the position where the overlay or the @code{display} property begins, for which the cursor should be displayed on that character. Specifically, if the value of the @@ -3251,7 +3313,7 @@ text property begins in the buffer. In other words, the string character with the @code{cursor} property of any non-@code{nil} value is the character where to display the cursor. The value of the property says for which buffer positions to -display the cursor there. If the value is an integer number @var{n}, +display the cursor there. If the value is an integer @var{n}, the cursor is displayed there when point is anywhere between the beginning of the overlay or @code{display} property and @var{n} positions after that. If the value is anything else and @@ -3410,8 +3472,10 @@ 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. +string to display, which is passed through +@code{substitute-command-keys} before being given to the function; see +@ref{Keys in Documentation}. Tooltip mode (@pxref{Tooltips,,, emacs, +The GNU Emacs Manual}) provides an example. @end defvar @node Format Properties @@ -3447,10 +3511,12 @@ of the text. @cindex sticky text properties @cindex inheritance, text property - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. + Self-inserting characters, the ones that get inserted into a buffer +when the user types them (@pxref{Commands for Insertion}), normally +take on the same properties as the preceding character. This is +called @dfn{inheritance} of properties. - A Lisp program can do insertion with inheritance or without, + By contrast, a Lisp program can do insertion with inheritance or without, depending on the 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 @@ -3557,8 +3623,8 @@ once for the same part of the buffer, you can use the variable @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''. +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} @@ -3669,16 +3735,17 @@ clicks on the link quickly without moving the mouse. This behavior is controlled by the user option @code{mouse-1-click-follows-link}. @xref{Mouse References,,, emacs, The GNU Emacs Manual}. +@cindex follow-link (text or overlay property) To set up the link so that it obeys @code{mouse-1-click-follows-link}, you must either (1) apply a @code{follow-link} text or overlay property to the link text, or (2) bind the @code{follow-link} event to a keymap (which can be a major mode keymap or a local keymap specified via the @code{keymap} text property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for +binding for the @code{follow-link} event, acts as a condition for the link action. This condition tells Emacs two things: the circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' +occurring inside the link, and how to compute an action code that says what to translate the @kbd{Mouse-1} click into. The link action condition can be one of the following: @@ -3844,7 +3911,7 @@ 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 +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}. @@ -3862,7 +3929,7 @@ 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''. +field is also considered to be on the boundary. Commands like @kbd{C-a} with no argument, that normally move backward to a specific kind of location and stay there once there, probably @@ -3890,7 +3957,7 @@ You can cause @code{constrain-to-field} to ignore all field boundaries @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 +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 @@ -3908,22 +3975,23 @@ 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 + Suppose we attempt to 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 +one interval. Once 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. + However, it is easy to arrange for editing to behave consistently +for questions of the form, ``What are the properties of text at this +buffer or string position?'' 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 @@ -3935,6 +4003,8 @@ coalesced whenever possible. @xref{Property Search}. @node Substitution @section Substituting for a Character Code +@cindex replace characters in region +@cindex substitute characters The following functions replace characters within a specified region based on their character codes. @@ -4069,8 +4139,9 @@ 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. + +When called interactively, the command defaults to putting point after +text, and a prefix argument inverts this behavior. If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted @@ -4081,6 +4152,18 @@ a rectangle (a list), currently useless things happen. This may be changed in the future. @end deffn +@defun register-read-with-preview prompt +@cindex register preview +This function reads and returns a register name, prompting with +@var{prompt} and possibly showing a preview of the existing registers +and their contents. The preview is shown in a temporary window, after +the delay specified by the user option @code{register-preview-delay}, +if its value and @code{register-alist} are both non-@code{nil}. The +preview is also shown if the user requests help (e.g., by typing the +help character). We recommend that all interactive commands which +read register names use this function. +@end defun + @node Transposition @section Transposition of Text @@ -4100,6 +4183,35 @@ is non-@code{nil}, @code{transpose-regions} does not do this---it leaves all markers unrelocated. @end defun +@node Decompression +@section Dealing With Compressed Data + +When @code{auto-compression-mode} is enabled, Emacs automatically +uncompresses compressed files when you visit them, and automatically +recompresses them if you alter and save them. @xref{Compressed +Files,,, emacs, The GNU Emacs Manual}. + +The above feature works by calling an external executable (e.g., +@command{gzip}). Emacs can also be compiled with support for built-in +decompression using the zlib library, which is faster than calling an +external program. + +@defun zlib-available-p +This function returns non-@code{nil} if built-in zlib decompression is +available. +@end defun + +@defun zlib-decompress-region start end +This function decompresses the region between @var{start} and +@var{end}, using built-in zlib decompression. The region should +contain data that were compressed with gzip or zlib. On success, the +function replaces the contents of the region with the decompressed +data. On failure, the function leaves the region unchanged and +returns @code{nil}. This function can be called only in unibyte +buffers. +@end defun + + @node Base 64 @section Base 64 Encoding @cindex base 64 encoding @@ -4165,7 +4277,7 @@ The decoding functions ignore newline characters in the encoded text. @cindex cryptographic hash Emacs has built-in support for computing @dfn{cryptographic hashes}. -A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint'' +A cryptographic hash, or @dfn{checksum}, is a digital fingerprint of a piece of data (e.g., a block of text) which can be used to check that you have an unaltered copy of that data. @@ -4174,7 +4286,7 @@ that you have an unaltered copy of that data. SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the oldest of these algorithms, and is commonly used in @dfn{message digests} to check the integrity of messages transmitted over a -network. MD5 is not ``collision resistant'' (i.e., it is possible to +network. MD5 is not collision resistant (i.e., it is possible to deliberately design different pieces of data which have the same MD5 hash), so you should not used it for anything security-related. A similar theoretical weakness also exists in SHA-1. Therefore, for @@ -4232,15 +4344,18 @@ coding instead. When Emacs is compiled with libxml2 support, the following functions are available to parse HTML or XML text into Lisp object trees. -@defun libxml-parse-html-region start end &optional base-url +@defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It -attempts to handle ``real world'' HTML by robustly coping with syntax +attempts to handle real-world HTML by robustly coping with syntax mistakes. The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. +If the optional argument @var{discard-comments} is non-@code{nil}, +then the parse tree is created without any comments. + In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second element is an alist of node attributes, and the remaining elements are @@ -4254,26 +4369,163 @@ document: @end example @noindent -A call to @code{libxml-parse-html-region} returns this: +A call to @code{libxml-parse-html-region} returns this @acronym{DOM} +(document object model): @example -(html () - (head ()) - (body ((width . "101")) - (div ((class . "thing")) - "Foo" - (div () - "Yes")))) +(html nil + (head nil) + (body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes")))) @end example @end defun +@cindex rendering html +@defun shr-insert-document dom +This function renders the parsed HTML in @var{dom} into the current +buffer. The argument @var{dom} should be a list as generated by +@code{libxml-parse-html-region}. This function is, e.g., used by +@ref{Top, EWW,, eww, The Emacs Web Wowser Manual}. +@end defun + @cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url +@defun libxml-parse-xml-region start end &optional base-url discard-comments This function is the same as @code{libxml-parse-html-region}, except that it parses the text as XML rather than HTML (so it is stricter about syntax). @end defun +@menu +* Document Object Model:: Access, manipulate and search the @acronym{DOM}. +@end menu + +@node Document Object Model +@subsection Document Object Model +@cindex HTML DOM +@cindex XML DOM +@cindex DOM +@cindex Document Object Model + +The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the +other @acronym{XML} parsing functions) is a tree structure where each +node has a node name (called a @dfn{tag}), and optional key/value +@dfn{attribute} list, and then a list of @dfn{child nodes}. The child +nodes are either strings or @acronym{DOM} objects. + +@example +(body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes"))) +@end example + +@defun dom-node tag &optional attributes &rest children +This function creates a @acronym{DOM} node of type @var{tag}. If +given, @var{attributes} should be a key/value pair list. +If given, @var{children} should be @acronym{DOM} nodes. +@end defun + +The following functions can be used to work with this structure. Each +function takes a @acronym{DOM} node, or a list of nodes. In the +latter case, only the first node in the list is used. + +Simple accessors: + +@table @code +@item dom-tag @var{node} +Return the @dfn{tag} (also called ``node name'') of the node. + +@item dom-attr @var{node} @var{attribute} +Return the value of @var{attribute} in the node. A common usage +would be: + +@lisp +(dom-attr img 'href) +=> "http://fsf.org/logo.png" +@end lisp + +@item dom-children @var{node} +Return all the children of the node. + +@item dom-non-text-children @var{node} +Return all the non-string children of the node. + +@item dom-attributes @var{node} +Return the key/value pair list of attributes of the node. + +@item dom-text @var{node} +Return all the textual elements of the node as a concatenated string. + +@item dom-texts @var{node} +Return all the textual elements of the node, as well as the textual +elements of all the children of the node, recursively, as a +concatenated string. This function also takes an optional separator +to be inserted between the textual elements. + +@item dom-parent @var{dom} @var{node} +Return the parent of @var{node} in @var{dom}. +@end table + +The following are functions for altering the @acronym{DOM}. + +@table @code +@item dom-set-attribute @var{node} @var{attribute} @var{value} +Set the @var{attribute} of the node to @var{value}. + +@item dom-append-child @var{node} @var{child} +Append @var{child} as the last child of @var{node}. + +@item dom-add-child-before @var{node} @var{child} @var{before} +Add @var{child} to @var{node}'s child list before the @var{before} +node. If @var{before} is @code{nil}, make @var{child} the first child. + +@item dom-set-attributes @var{node} @var{attributes} +Replace all the attributes of the node with a new key/value list. +@end table + +The following are functions for searching for elements in the +@acronym{DOM}. They all return lists of matching nodes. + +@table @code +@item dom-by-tag @var{dom} @var{tag} +Return all nodes in @var{dom} that are of type @var{tag}. A typical +use would be: + +@lisp +(dom-by-tag dom 'td) +=> '((td ...) (td ...) (td ...)) +@end lisp + +@item dom-by-class @var{dom} @var{match} +Return all nodes in @var{dom} that have class names that match +@var{match}, which is a regular expression. + +@item dom-by-style @var{dom} @var{style} +Return all nodes in @var{dom} that have styles that match @var{match}, +which is a regular expression. + +@item dom-by-id @var{dom} @var{style} +Return all nodes in @var{dom} that have IDs that match @var{match}, +which is a regular expression. + +@item dom-strings @var{dom} +Return all strings in @var{DOM}. + +@end table + +Utility functions: + +@table @code +@item dom-pp @var{dom} &optional @var{remove-empty} +Pretty-print @var{dom} at point. If @var{remove-empty}, don't print +textual nodes that just contain white-space. +@end table + + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -4307,7 +4559,7 @@ 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 +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 diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 2e3760e573e..d9cbf473306 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Tips @@ -223,18 +223,13 @@ only for special-purpose buffers.) People 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. The easiest way to -do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding -System Basics}), and specify that coding in the @samp{-*-} line or the +The default file coding system for Emacs Lisp source files is UTF-8 +(@pxref{Text Representations}). In the rare event that your program +contains characters which are @emph{not} in UTF-8, you should specify +an appropriate coding system in the source file's @samp{-*-} line or local variables list. @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}. -@example -;; XXX.el -*- coding: utf-8-emacs; -*- -@end example - @item Indent the file using the default indentation parameters. @@ -403,7 +398,7 @@ Enter the answer (default 42): @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 +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 @@ -578,10 +573,13 @@ Format the documentation string so that it fits in an Emacs window on an 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 sections if the documentation string is long. +@vindex emacs-lisp-docstring-fill-column +You can fill the text if that looks good. Emacs Lisp mode fills +documentation strings to the width specified by +@code{emacs-lisp-docstring-fill-column}. However, you can sometimes +make a documentation string much more readable by adjusting its line +breaks with care. Use blank lines between sections if the +documentation string is long. @item The first line of the documentation string should consist of one or two @@ -659,23 +657,29 @@ 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 +@cindex curly quotes +@cindex curved quotes 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 +would be printed (which usually means in lower case), surrounding +it with curved single quotes (@t{‘} and @t{’}). There are +two exceptions: write @code{t} and @code{nil} without surrounding +punctuation. For example: @samp{CODE can be ‘lambda’, nil, or t}. +@xref{Quotation Marks,,, emacs, The GNU Emacs Manual}, for how to +enter curved single quotes. + +Documentation strings can also use an older single-quoting convention, +which quotes symbols with grave accent @t{`} and apostrophe +@t{'}: @t{`like-this'} rather than @t{‘like-this’}. This +older convention was designed for now-obsolete displays in which grave +accent and apostrophe were mirror images. + +Documentation using either convention is converted to the user's +preferred format when it is copied into a help buffer. @xref{Keys in +Documentation}. @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 +uses a single-quoted symbol name, 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 @@ -717,17 +721,17 @@ 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, +To make a hyperlink to Info documentation, write the single-quoted +name of the Info node (or anchor), 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, +Finally, to create a hyperlink to URLs, write the single-quoted URL, +preceded by @samp{URL}. For example, @smallexample The home page for the GNU project has more information (see URL @@ -768,7 +772,7 @@ 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 +explicitly what constitutes truth. The word ``return'' avoids starting the sentence with lower-case ``t'', which could be somewhat distracting. @@ -836,10 +840,10 @@ For example: @smallexample @group -(setq base-version-list ; there was a base +(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 + ; a subversion. @end group @end smallexample @@ -877,30 +881,14 @@ strings, though. @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 +the left margin. We use them +for comments which 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 fewer 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 +with two or fewer are not. Historically, triple-semicolon comments have +also been used for commenting out lines within a function, but this use +is discouraged. When commenting out entire functions, use two semicolons. @@ -936,7 +924,7 @@ explains these conventions, starting with an example: @group ;;; foo.el --- Support for the Foo programming language -;; Copyright (C) 2010-2013 Your Name +;; Copyright (C) 2010-2015 Your Name @end group ;; Author: Your Name <yourname@@example.com> @@ -1080,9 +1068,9 @@ context. @item ;;; Change Log: This begins an optional log of changes to the file over time. Don't put too much information in this section---it is better to keep the -detailed logs in a separate @file{ChangeLog} file (as Emacs does), -and/or to use a version control system. @samp{History} is an -alternative to @samp{Change Log}. +detailed logs in a version control system (as Emacs does) or in a +separate @file{ChangeLog} file. @samp{History} is an alternative to +@samp{Change Log}. @item ;;; Code: This begins the actual code of the program. diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt index a134b8c4783..89336e1d43b 100644 --- a/doc/lispref/two-volume-cross-refs.txt +++ b/doc/lispref/two-volume-cross-refs.txt @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. +Copyright (C) 2001-2015 Free Software Foundation, Inc. See end for copying conditions. Two Volume Cross References @@ -108,8 +108,8 @@ 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' +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 @@ -126,7 +126,7 @@ Be sure that .fn file has no blank lines. ### Create merged .toc file with volume number headings. -append vol2.toc to vol1.toc with following `cat' +append vol2.toc to vol1.toc with following 'cat' % cat vol1.toc vol2.toc > elisp-toc-2vol.toc diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index 9ae4a33df44..bdcdb2f4fdd 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -1,4 +1,4 @@ -# Copyright (C) 2007-2013 Free Software Foundation, Inc. +# Copyright (C) 2007-2015 Free Software Foundation, Inc. # See end for copying conditions. # although it would be nice to use tex rather than pdftex to avoid @@ -26,9 +26,9 @@ tex2 = sed '/^@setfilename/a\ # elisp.texi specially defines \tocreadfilename when VOL1 or VOL2 is # set, 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..." + @printf '\f Final TeX run for volume 1...\n' cp elisp1med-toc-ready elisp1-toc-ready.toc cp elisp1med-fns-ready vol1.fns cp elisp1med-aux-ready vol1.aux @@ -42,27 +42,27 @@ vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready $(tex2) # 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 >>$@ + 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 >>$@ + sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ cat elisp2med-toc >>$@ # intermediate aux files. -# -# append vol2's fixed aux to normal vol1. +# +# append vol2's fixed aux to normal vol1. elisp1med-aux-ready: elisp2med-aux-vol-added cat elisp1med-aux $< >$@ # @@ -78,7 +78,7 @@ elisp2med-aux-vol-added: elisp2med-init sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ # 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 @@ -103,17 +103,17 @@ elisp2med-fn-vol-added: elisp2med-init # ----------------------------------------------------------------------------- # 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 $(texinfodir)/texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." + @printf '\f Intermediate TeX run for volume 1...\n' cp elisp1init-toc-ready elisp1-toc-ready.toc cp elisp1-fns-ready vol1.fns cp elisp1-aux-ready vol1.aux @@ -134,26 +134,26 @@ elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfo # 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 >>$@ + 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 >>$@ + sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ cat elisp2-toc >>$@ # 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 @@ -171,7 +171,7 @@ elisp2-aux-vol-added: elisp2-init sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ # 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 @@ -195,14 +195,14 @@ elisp2-fn-vol-added: elisp2-init # 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: elisp.texi - @echo -e "\f Initial TeX run for volume 1..." + @printf '\f Initial TeX run for volume 1...\n' rm -f vol1.aux vol1.toc $(tex1) texindex vol1.?? @@ -220,17 +220,16 @@ elisp2-init: elisp.texi 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 of the License, 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. If not, see <http://www.gnu.org/licenses/>. - diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 557add738ba..1d920942d10 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Variables @chapter Variables @@ -10,10 +10,10 @@ In Lisp, each variable is represented by a Lisp symbol (@pxref{Symbols}). The variable name is simply the symbol's name, and the variable's value is stored in the symbol's value cell@footnote{To -be precise, under the default @dfn{dynamic binding} rules the value +be precise, under the default @dfn{dynamic scoping} rule, the value cell always holds the variable's current value, but this is not the -case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for -details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a +case under the @dfn{lexical scoping} rule. @xref{Variable Scoping}, +for details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a symbol as a variable is independent of its use as a function name. As previously noted in this manual, a Lisp program is represented @@ -25,7 +25,7 @@ representing the variable. @menu * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. +* Constant Variables:: Variables 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. @@ -131,7 +131,7 @@ starts with @samp{:}, interned in the standard obarray, and returns @code{nil} otherwise. @end defun -These constants are fundamentally different from the ``constants'' +These constants are fundamentally different from the constants defined using the @code{defconst} special form (@pxref{Defining Variables}). A @code{defconst} form serves to inform human readers that you do not intend to change the value of a variable, but Emacs @@ -178,7 +178,7 @@ It determines the value returned by evaluating the variable symbol, and it is the binding acted on by @code{setq}. For most purposes, you can think of the current binding as the -``innermost'' local binding, or the global binding if there is no +innermost local binding, or the global binding if there is no local binding. To be more precise, a rule called the @dfn{scoping rule} determines where in a program a local binding takes effect. The default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, @@ -263,7 +263,7 @@ Macro calls (@pxref{Macros}). Variables}); a few variables have terminal-local bindings (@pxref{Multiple Terminals}). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs. +where you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -287,25 +287,27 @@ has room to execute. @end defopt @node Void Variables -@section When a Variable is ``Void'' +@section When a Variable is Void @cindex @code{void-variable} error @cindex void variable We say that a variable is void if its symbol has an unassigned value -cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic -binding rules (@pxref{Variable Scoping}), the value cell stores the -variable's current (local or global) value. Note that an unassigned -value cell is @emph{not} the same as having @code{nil} in the value -cell. 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 still a value. -If a variable is void, trying to evaluate the variable signals a -@code{void-variable} error rather than a value. - - Under lexical binding rules, the value cell only holds the -variable's global value, i.e., the value outside of any lexical -binding construct. When a variable is lexically bound, the local value -is determined by the lexical environment; the variable may have a -local value if its symbol's value cell is unassigned. +cell (@pxref{Symbol Components}). + + Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable +Scoping}), the value cell stores the variable's current (local or +global) value. Note that an unassigned value cell is @emph{not} the +same as having @code{nil} in the value cell. 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 still a value. If a variable is void, trying +to evaluate the variable signals a @code{void-variable} error, instead +of returning a value. + + Under the optional lexical scoping rule, the value cell only holds +the variable's global value---the value outside of any lexical binding +construct. When a variable is lexically bound, the local value is +determined by the lexical environment; hence, variables can have local +values even if their symbols' value cells are unassigned. @defun makunbound symbol This function empties out the value cell of @var{symbol}, making the @@ -414,18 +416,23 @@ explicitly in the @code{defvar} form. The variable is marked as @dfn{special}, meaning that it should always be dynamically bound (@pxref{Variable Scoping}). -If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates @var{value} 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{value} is specified, and @var{symbol} is void (i.e., it has no +dynamically bound value; @pxref{Void Variables}), then @var{value} is +evaluated and @var{symbol} is set to the result. But if @var{symbol} +is not void, @var{value} is not evaluated, and @var{symbol}'s value is +left 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 +@code{defvar} acts on the default value, which is buffer-independent, +rather than the buffer-local binding. It sets the default value if the default value is void. @xref{Buffer-Local Variables}. +If @var{symbol} is already lexically bound (e.g., if the @code{defvar} +form occurs in a @code{let} form with lexical binding enabled), then +@code{defvar} sets the dynamic value. The lexical binding remains in +effect until its binding construct exits. @xref{Variable Scoping}. + 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 @@ -538,8 +545,7 @@ 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. +non-@code{nil} for success and @code{nil} for failure. @item @dots{}-flag The value is significant only as to whether it is @code{nil} or not. @@ -557,7 +563,7 @@ The value specifies options for a command. @end table When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. +it as safe or 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 @@ -761,6 +767,7 @@ error is signaled. @node Variable Scoping @section Scoping Rules for Variable Bindings +@cindex scoping rule When you create a local binding for a variable, that binding takes effect only within a limited portion of the program (@pxref{Local @@ -774,12 +781,12 @@ binding can be accessed. @dfn{Extent} refers to @emph{when}, as the program is executing, the binding exists. @cindex dynamic binding -@cindex indefinite scope +@cindex dynamic scope @cindex dynamic extent By default, the local bindings that Emacs creates are @dfn{dynamic -bindings}. Such a binding has @dfn{indefinite scope}, meaning that -any part of the program can potentially access the variable binding. -It also has @dfn{dynamic extent}, meaning that the binding lasts only +bindings}. Such a binding has @dfn{dynamic scope}, meaning that any +part of the program can potentially access the variable binding. It +also has @dfn{dynamic extent}, meaning that the binding lasts only while the binding construct (such as the body of a @code{let} form) is being executed. @@ -788,11 +795,12 @@ being executed. @cindex indefinite extent Emacs can optionally create @dfn{lexical bindings}. A lexical binding has @dfn{lexical scope}, meaning that any reference to the -variable must be located textually within the binding construct. It -also has @dfn{indefinite extent}, meaning that under some -circumstances the binding can live on even after the binding construct -has finished executing, by means of special objects called -@dfn{closures}. +variable must be located textually within the binding +construct@footnote{With some exceptions; for instance, a lexical +binding can also be accessed from the Lisp debugger.}. It also has +@dfn{indefinite extent}, meaning that under some circumstances the +binding can live on even after the binding construct has finished +executing, by means of special objects called @dfn{closures}. The following subsections describe dynamic binding and lexical binding in greater detail, and how to enable lexical binding in Emacs @@ -814,22 +822,22 @@ at any point in the execution of the Lisp program is simply the most recently-created dynamic local binding for that symbol, or the global binding if there is no such local binding. - Dynamic bindings have indefinite scope and dynamic extent, as shown -by the following example: + Dynamic bindings have dynamic scope and extent, as shown by the +following example: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is dynamically bound.} (getx)) @result{} 1 ;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} +;; @r{previous value, which is @minus{}99.} (getx) @result{} -99 @@ -837,20 +845,20 @@ by the following example: @end example @noindent -The function @code{getx} refers to @code{x}. This is a ``free'' +The function @code{getx} refers to @code{x}. This is a @dfn{free} reference, in the sense that there is no binding for @code{x} within that @code{defun} construct itself. When we call @code{getx} from within a @code{let} form in which @code{x} is (dynamically) bound, it -retrieves the local value of @code{x} (i.e., 1). But when we call -@code{getx} outside the @code{let} form, it retrieves the global value -of @code{x} (i.e., -99). +retrieves the local value (i.e., 1). But when we call @code{getx} +outside the @code{let} form, it retrieves the global value (i.e., +@minus{}99). Here is another example, which illustrates setting a dynamically bound variable using @code{setq}: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun addx () (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} @@ -861,7 +869,7 @@ bound variable using @code{setq}: @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} ;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} +;; @r{previous value, which is @minus{}99.} (addx) @result{} -98 @@ -888,12 +896,11 @@ technique: @itemize @bullet @item If a variable has no global definition, use it as a local variable -only within a binding construct, e.g., the body of the @code{let} -form where the variable was bound, or the body of the function for an -argument variable. If this convention is followed consistently -throughout a program, the value of the variable will not affect, nor -be affected by, any uses of the same variable symbol elsewhere in the -program. +only within a binding construct, such as the body of the @code{let} +form where the variable was bound. If this convention is followed +consistently throughout a program, the value of the variable will not +affect, nor be affected by, any uses of the same variable symbol +elsewhere in the program. @item Otherwise, define the variable with @code{defvar}, @code{defconst}, or @@ -925,12 +932,16 @@ variables like @code{case-fold-search}: @node Lexical Binding @subsection Lexical Binding -Optionally, you can create lexical bindings in Emacs Lisp. A -lexically bound variable has @dfn{lexical scope}, meaning that any -reference to the variable must be located textually within the binding -construct. + Lexical binding was introduced to Emacs, as an optional feature, in +version 24.1. We expect its importance to increase in the future. +Lexical binding opens up many more opportunities for optimization, so +programs using it are likely to run faster in future Emacs versions. +Lexical binding is also more compatible with concurrency, which we +want to add to Emacs in the future. - Here is an example + A lexically-bound variable has @dfn{lexical scope}, meaning that any +reference to the variable must be located textually within the binding +construct. Here is an example @iftex (see the next subsection, for how to actually enable lexical binding): @end iftex @@ -945,7 +956,7 @@ construct. @result{} 4 (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is lexically bound.} (getx)) @@ -969,6 +980,14 @@ wants the current value of a variable, it looks first in the lexical environment; if the variable is not specified in there, it looks in the symbol's value cell, where the dynamic value is stored. + (Internally, the lexical environment is an alist of symbol-value +pairs, with the final element in the alist being the symbol @code{t} +rather than a cons cell. Such an alist can be passed as the second +argument to the @code{eval} function, in order to specify a lexical +environment in which to evaluate a form. @xref{Eval}. Most Emacs +Lisp programs, however, should not interact directly with lexical +environments in this way; only specialized programs like debuggers.) + @cindex closures, example of using Lexical bindings have indefinite extent. Even after a binding construct has finished executing, its lexical environment can be @@ -1019,13 +1038,6 @@ binding of @code{x} in that lexical environment. the body of a @code{defun} or @code{defmacro} cannot refer to surrounding lexical variables. - Currently, lexical binding is not much used within the Emacs -sources. However, we expect its importance to increase in the future. -Lexical binding opens up a lot more opportunities for optimization, so -Emacs Lisp code that makes use of lexical binding is likely to run -faster in future Emacs versions. Such code is also much more friendly -to concurrency, which we want to add to Emacs in the near future. - @node Using Lexical Binding @subsection Using Lexical Binding @@ -1069,19 +1081,22 @@ discouraged. Doing so gives rise to unspecified behavior when lexical binding mode is enabled (it may use lexical binding sometimes, and dynamic binding other times). - Converting an Emacs Lisp program to lexical binding is pretty easy. -First, add a file-local variable setting of @code{lexical-binding} to -@code{t} in the Emacs Lisp source file. Second, check that every -variable in the program which needs to be dynamically bound has a -variable definition, so that it is not inadvertently bound lexically. + Converting an Emacs Lisp program to lexical binding is easy. First, +add a file-local variable setting of @code{lexical-binding} to +@code{t} in the header line of the Emacs Lisp source file (@pxref{File +Local Variables}). Second, check that every variable in the program +which needs to be dynamically bound has a variable definition, so that +it is not inadvertently bound lexically. +@cindex free variable +@cindex unused lexical variable A simple way to find out which variables need a variable definition is to byte-compile the source file. @xref{Byte Compilation}. If a non-special variable is used outside of a @code{let} form, the -byte-compiler will warn about reference or assignment to a ``free -variable''. If a non-special variable is bound but not used within a -@code{let} form, the byte-compiler will warn about an ``unused lexical -variable''. The byte-compiler will also issue a warning if you use a +byte-compiler will warn about reference or assignment to a free +variable. If a non-special variable is bound but not used within a +@code{let} form, the byte-compiler will warn about an unused lexical +variable. The byte-compiler will also issue a warning if you use a special variable as a function argument. (To silence byte-compiler warnings about unused variables, just use @@ -1387,9 +1402,10 @@ buffer-local variable interactively, just as it is useful to create buffer-local variables interactively. @end deffn +@cindex local variables, killed by major mode @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local +current buffer except for variables marked as permanent and local hook functions that have a non-@code{nil} @code{permanent-local-hook} property (@pxref{Setting Hooks}). As a result, the buffer will see the default values of most variables. @@ -1649,8 +1665,7 @@ non-@code{nil} given that value. Many commonly-encountered file variables have @code{safe-local-variable} properties; these include @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. +property value. When defining a user option using @code{defcustom}, you can set its @code{safe-local-variable} property by adding the arguments @@ -1835,6 +1850,12 @@ modification times of the associated directory local variables file updates this list. @end defvar +@defvar enable-dir-local-variables +If @code{nil}, directory-local variables are ignored. This variable +may be useful for modes that want to ignore directory-locals while +still respecting file-local variables (@pxref{File Local Variables}). +@end defvar + @node Variable Aliases @section Variable Aliases @cindex variable aliases @@ -1881,8 +1902,8 @@ the variable was first made obsolete (usually a version number string). The optional argument @var{access-type}, if non-@code{nil}, should -should specify the kind of access that will trigger obsolescence -warnings; it can be either @code{get} or @code{set}. +specify the kind of access that will trigger obsolescence warnings; it +can be either @code{get} or @code{set}. @end defun You can make two variables synonyms and declare one obsolete at the @@ -1930,6 +1951,7 @@ foo @node Variables with Restricted Values @section Variables with Restricted Values +@cindex lisp variables defined in C, restrictions Ordinary Lisp variables can be assigned any value that is a valid Lisp object. However, certain Lisp variables are not defined in Lisp, @@ -1955,7 +1977,7 @@ will set them to @code{t}: 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. + Variables of type @code{DEFVAR_INT} can take on only integer values. Attempting to assign them any other value will result in an error: @example @@ -1966,13 +1988,15 @@ Attempting to assign them any other value will result in an error: @node Generalized Variables @section Generalized Variables +@cindex generalized variable +@cindex place form A @dfn{generalized variable} or @dfn{place form} is one of the many places in Lisp memory where values can be stored. The simplest place form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. -Generalized variables are analogous to ``lvalues'' in the C +Generalized variables are analogous to lvalues in the C language, where @samp{x = a[i]} gets an element from an array and @samp{a[i] = x} stores an element using the same notation. Just as certain forms like @code{a[i]} can be lvalues in C, there @@ -2145,7 +2169,7 @@ of Common Lisp. Consult the source file @file{gv.el} for more details. @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the -@code{setf} behavior of a function, namely ``@code{setf} functions'', +@code{setf} behavior of a function, namely @code{setf} functions, whose names are lists @code{(setf @var{name})} rather than symbols. For example, @code{(defun (setf foo) @dots{})} defines the function that is used when @code{setf} is applied to @code{foo}. Emacs does diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 13c9ca53222..1da2d1cfe7b 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Windows @@ -16,6 +16,7 @@ is displayed in windows. * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Creating a new window. * Deleting Windows:: Removing a window from its frame. * Recombining Windows:: Preserving the frame layout when splitting and @@ -137,7 +138,7 @@ window). Each window belongs to exactly one frame (@pxref{Frames}). -@defun window-frame window +@defun window-frame &optional window This function returns the frame that the window @var{window} belongs to. If @var{window} is @code{nil}, it defaults to the selected window. @@ -252,19 +253,19 @@ child windows form a horizontal combination, consisting of the live window @var{W2} and the internal window @var{W3}. The child windows of @var{W3} form a vertical combination, consisting of the live windows @var{W4} and @var{W5}. Hence, the live windows in this -window tree are @var{W2} @var{W4}, and @var{W5}. +window tree are @var{W2}, @var{W4}, and @var{W5}. The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. -@defun window-top-child window +@defun window-top-child &optional window This function returns the topmost child window of @var{window}, if @var{window} is an internal window whose children form a vertical combination. For any other type of window, the return value is @code{nil}. @end defun -@defun window-left-child window +@defun window-left-child &optional window This function returns the leftmost child window of @var{window}, if @var{window} is an internal window whose children form a horizontal combination. For any other type of window, the return value is @@ -322,7 +323,7 @@ the assumption that the frame from our canonical example is selected @end defun @cindex window in direction -@defun window-in-direction direction &optional window ignore +@defun window-in-direction direction &optional window ignore sign wrap mini This function returns the nearest live window in direction @var{direction} as seen from the position of @code{window-point} in window @var{window}. The argument @var{direction} must be one of @@ -338,6 +339,23 @@ function tries to find another window in the indicated direction whose argument @var{ignore} is non-@code{nil}, a window may be returned even if its @code{no-other-window} parameter is non-@code{nil}. +If the optional argument @var{sign} is a negative number, it means to +use the right or bottom edge of @var{window} as reference position +instead of @code{window-point}. If @var{sign} is a positive number, it +means to use the left or top edge of @var{window} as reference position. + +If the optional argument @var{wrap} is non-@code{nil}, this means to +wrap @var{direction} around frame borders. For example, if @var{window} +is at the top of the frame and @var{direction} is @code{above}, then +return the minibuffer window provided the frame has one, and a window at +the bottom of the frame otherwise. + +If the optional argument @var{mini} is @code{nil}, this means to return +the minibuffer window if and only if it is currently active. If +@var{mini} is non-@code{nil}, it returns the minibuffer window even when +it's not active. However, if @var{wrap} non-@code{nil}, it always acts +as if @var{mini} were @code{nil}. + If it doesn't find a suitable window, this function returns @code{nil}. @end defun @@ -365,6 +383,7 @@ internal window). The @var{edges} element is a list @code{(@var{left} @code{window-edges} (@pxref{Coordinates and Windows}). @end defun + @node Window Sizes @section Window Sizes @cindex window size @@ -374,18 +393,19 @@ internal window). The @var{edges} element is a list @code{(@var{left} @smallexample @group - _________________________________________ - ^ |______________ Header Line_______________| - | |LS|LF|LM| |RM|RF|RS| ^ - | | | | | | | | | | - Window | | | | Text Area | | | | Window - Total | | | | (Window Body) | | | | Body - Height | | | | | | | | Height - | | | | |<- Window Body Width ->| | | | | - | |__|__|__|_______________________|__|__|__| v - v |_______________ Mode Line _______________| - - <----------- Window Total Width --------> + ____________________________________________ + |______________ Header Line ______________|RD| ^ + ^ |LS|LM|LF| |RF|RM|RS| | | + | | | | | | | | | | | +Window | | | | Text Area | | | | | Window +Body | | | | | (Window Body) | | | | | Total +Height | | | | | | | | | Height + | | | | |<- Window Body Width ->| | | | | | + v |__|__|__|_______________________|__|__|__| | | + |_________ Horizontal Scroll Bar _________| | | + |_______________ Mode Line _______________|__| | + |_____________ Bottom Divider _______________| v + <---------- Window Total Width ------------> @end group @end smallexample @@ -394,59 +414,125 @@ internal window). The @var{edges} element is a list @code{(@var{left} @cindex text area of a window @cindex body of a window At the center of the window is the @dfn{text area}, or @dfn{body}, -where the buffer text is displayed. On each side of the text area is -a series of vertical areas; from innermost to outermost, these are the -left and right margins, denoted by LM and RM in the schematic -(@pxref{Display Margins}); the left and right fringes, denoted by LF -and RF (@pxref{Fringes}); and the left or right scroll bar, only one of -which is present at any time, denoted by LS and RS (@pxref{Scroll -Bars}). At the top of the window is an optional header line -(@pxref{Header Lines}), and at the bottom of the window is the mode -line (@pxref{Mode Line Format}). - - Emacs provides several functions for finding the height and width of -a window. Except where noted, Emacs reports window heights and widths -as integer numbers of lines and columns, respectively. On a graphical -display, each ``line'' and ``column'' actually corresponds to the -height and width of a ``default'' character specified by the frame's -default font. Thus, if a window is displaying text with a different -font or size, the reported height and width for that window may differ -from the actual number of text lines or columns displayed within it. +where the buffer text is displayed. The text area can be surrounded by +a series of optional areas. On the left and right, from innermost to +outermost, these are the left and right fringes, denoted by LF and RF +(@pxref{Fringes}); the left and right margins, denoted by LM and RM in +the schematic (@pxref{Display Margins}); the left or right vertical +scroll bar, only one of which is present at any time, denoted by LS and +RS (@pxref{Scroll Bars}); and the right divider, denoted by RD +(@pxref{Window Dividers}). At the top of the window is the header line +(@pxref{Header Lines}). At the bottom of the window are the horizontal +scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line +Format}); and the bottom divider (@pxref{Window Dividers}). + + Emacs provides miscellaneous functions for finding the height and +width of a window. The return value of many of these functions can be +specified either in units of pixels or in units of lines and columns. +On a graphical display, the latter actually correspond to the height and +width of a default character specified by the frame's default font +as returned by @code{frame-char-height} and @code{frame-char-width} +(@pxref{Frame Font}). Thus, if a window is displaying text with a +different font or size, the reported line height and column width for +that window may differ from the actual number of text lines or columns +displayed within it. @cindex window height @cindex height of a window @cindex total height of a window + The @dfn{total height} of a window is the number of lines comprising +the window's body, the header line, the horizontal scroll bar, the mode +line and the bottom divider (if any). + +@defun window-total-height &optional window round +This function returns the total height, in lines, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If @var{window} is an internal window, the return +value is the total height occupied by its descendant windows. + + If a window's pixel height is not an integral multiple of its frame's +default character height, the number of lines occupied by the window is +rounded internally. This is done in a way such that, if the window is a +parent window, the sum of the total heights of all its child windows +internally equals the total height of their parent. This means that +although two windows have the same pixel height, their internal total +heights may differ by one line. This means also, that if window is +vertically combined and has a next sibling, the topmost row of that +sibling can be calculated as the sum of this window's topmost row and +total height (@pxref{Coordinates and Windows}) + + If the optional argument @var{round} is @code{ceiling}, this +function returns the smallest integer larger than @var{window}'s pixel +height divided by the character height of its frame; if it is +@code{floor}, it returns the largest integer smaller than said value; +with any other @var{round} it returns the internal value of +@var{windows}'s total height. +@end defun + @cindex window width @cindex width of a window @cindex total width of a window - The @dfn{total height} of a window is the distance between the top -and bottom of the window, including the header line (if one exists) -and the mode line. The @dfn{total width} of a window is the distance -between the left and right edges of the mode line. Note that the -height of a frame is not the same as the height of its windows, since -a frame may also contain an echo area, menu bar, and tool bar -(@pxref{Size and Position}). +The @dfn{total width} of a window is the number of lines comprising the +window's body, its margins, fringes, scroll bars and a right divider (if +any). -@defun window-total-height &optional window -This function returns the total height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is an internal window, the -return value is the total height occupied by its descendant windows. +@defun window-total-width &optional window round +This function returns the total width, in columns, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If @var{window} is internal, the return value is +the total width occupied by its descendant windows. + + If a window's pixel width is not an integral multiple of its frame's +character width, the number of lines occupied by the window is rounded +internally. This is done in a way such that, if the window is a parent +window, the sum of the total widths of all its children internally +equals the total width of their parent. This means that although two +windows have the same pixel width, their internal total widths may +differ by one column. This means also, that if this window is +horizontally combined and has a next sibling, the leftmost column of +that sibling can be calculated as the sum of this window's leftmost +column and total width (@pxref{Coordinates and Windows}). The optional +argument @var{round} behaves as it does for @code{window-total-height}. @end defun -@defun window-total-width &optional window -This function returns the total width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is internal, the return value -is the total width occupied by its descendant windows. +@defun window-total-size &optional window horizontal round +This function returns either the total height in lines or the total +width in columns of the window @var{window}. If @var{horizontal} is +omitted or @code{nil}, this is equivalent to calling +@code{window-total-height} for @var{window}; otherwise it is equivalent +to calling @code{window-total-width} for @var{window}. The optional +argument @var{round} behaves as it does for @code{window-total-height}. @end defun -@defun window-total-size &optional window horizontal -This function returns either the total height or width of the window -@var{window}. If @var{horizontal} is omitted or @code{nil}, this is -equivalent to calling @code{window-total-height} for @var{window}; -otherwise it is equivalent to calling @code{window-total-width} for -@var{window}. +The following two functions can be used to return the total size of a +window in units of pixels. + +@cindex window pixel height +@cindex pixel height of a window +@cindex total pixel height of a window + +@defun window-pixel-height &optional window +This function returns the total height of window @var{window} in pixels. +@var{window} must be a valid window and defaults to the selected one. + +The return value includes mode and header line, a horizontal scroll bar +and a bottom divider, if any. If @var{window} is an internal window, +its pixel height is the pixel height of the screen areas spanned by its +children. +@end defun + +@cindex window pixel height +@cindex pixel height of a window +@cindex total pixel height of a window + +@defun window-pixel-width &optional Lisp_Object &optional window +This function returns the width of window @var{window} in pixels. +@var{window} must be a valid window and defaults to the selected one. + +The return value includes the fringes and margins of @var{window} as +well as any vertical dividers or scroll bars belonging to @var{window}. +If @var{window} is an internal window, its pixel width is the width of +the screen areas spanned by its children. @end defun @cindex full-width window @@ -455,10 +541,12 @@ otherwise it is equivalent to calling @code{window-total-width} for window has any adjacent windows. @defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window above or below it in its frame, i.e., its total height equals -the total height of the root window on that frame. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. +This function returns non-@code{nil} if @var{window} has no other window +above or below it in its frame. More precisely, this means that the +total height of @var{window} equals the total height of the root window +on that frame. The minibuffer window does not count in this regard. If +@var{window} is omitted or @code{nil}, it defaults to the selected +window. @end defun @defun window-full-width-p &optional window @@ -471,40 +559,52 @@ that of the root window on that frame. If @var{window} is omitted or @cindex window body height @cindex body height of a window @cindex window body width +The @dfn{body height} of a window is the height of its text area, which +does not include a mode or header line, a horizontal scroll bar, or a +bottom divider. + +@defun window-body-height &optional window pixelwise +This function returns the height, in lines, of the body of window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window; otherwise it must be a live window. + +If the optional argument @var{pixelwise} is non-@code{nil}, this +function returns the body height of @var{window} counted in pixels. + +If @var{pixelwise} is @code{nil}, the return value is rounded down to +the nearest integer, if necessary. This means that if a line at the +bottom of the text area is only partially visible, that line is not +counted. It also means that the height of a window's body can never +exceed its total height as returned by @code{window-total-height}. +@end defun + @cindex body width of a window @cindex body size of a window @cindex window body size - The @dfn{body height} of a window is the height of its text area, -which does not include the mode or header line. Similarly, the -@dfn{body width} is the width of the text area, which does not include -the scroll bar, fringes, or margins. - -@defun window-body-height &optional window -This function returns the body height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. - -If there is a partially-visible line at the bottom of the text area, -that counts as a whole line; to exclude such a partially-visible line, -use @code{window-text-height}, below. -@end defun - -@defun window-body-width &optional window -This function returns the body width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. -@end defun - -@defun window-body-size &optional window horizontal -This function returns the body height or body width of @var{window}. -If @var{horizontal} is omitted or @code{nil}, it is equivalent to -calling @code{window-body-height} for @var{window}; otherwise it is -equivalent to calling @code{window-body-width}. +The @dfn{body width} of a window is the width of its text area, which +does not include the scroll bar, fringes, margins or a right divider. + +@defun window-body-width &optional window pixelwise +This function returns the width, in columns, of the body of window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window; otherwise it must be a live window. + +If the optional argument @var{pixelwise} is non-@code{nil}, this +function returns the body width of @var{window} in units of pixels. + +If @var{pixelwise} is @code{nil}, the return value is rounded down to +the nearest integer, if necessary. This means that if a column on the +right of the text area is only partially visible, that column is not +counted. It also means that the width of a window's body can never +exceed its total width as returned by @code{window-total-width}. @end defun -@defun window-text-height &optional window -This function is like @code{window-body-height}, except that any -partially-visible line at the bottom of the text area is not counted. +@defun window-body-size &optional window horizontal pixelwise +This function returns the body height or body width of @var{window}. If +@var{horizontal} is omitted or @code{nil}, it is equivalent to calling +@code{window-body-height} for @var{window}; otherwise it is equivalent +to calling @code{window-body-width}. In either case, the optional +argument @var{pixelwise} is passed to the function called. @end defun For compatibility with previous versions of Emacs, @@ -512,47 +612,84 @@ partially-visible line at the bottom of the text area is not counted. @code{window-width} is an alias for @code{window-body-width}. These aliases are considered obsolete and will be removed in the future. + The pixel heights of a window's mode and header line can be retrieved +with the functions given below. Their return value is usually accurate +unless the window has not been displayed before: In that case, the +return value is based on an estimate of the font used for the window's +frame. + +@defun window-mode-line-height &optional window +This function returns the height in pixels of @var{window}'s mode line. +@var{window} must be a live window and defaults to the selected one. If +@var{window} has no mode line, the return value is zero. +@end defun + +@defun window-header-line-height &optional window +This function returns the height in pixels of @var{window}'s header +line. @var{window} must be a live window and defaults to the selected +one. If @var{window} has no header line, the return value is zero. +@end defun + +Functions for retrieving the height and/or width of window dividers +(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars +(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are +described in the corresponding sections. + @cindex fixed-size window @vindex window-min-height @vindex window-min-width Commands that change the size of windows (@pxref{Resizing Windows}), or split them (@pxref{Splitting Windows}), obey the variables -@code{window-min-height} and @code{window-min-width}, which specify -the smallest allowable window height and width. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. They also obey the variable @code{window-size-fixed}, with -which a window can be @dfn{fixed} in size: - -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no 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. -@end defvar +@code{window-min-height} and @code{window-min-width}, which specify the +smallest allowable window height and width. They also obey the variable +@code{window-size-fixed}, with which a window can be @dfn{fixed} in +size: + +@defopt window-min-height +This option specifies the minimum total height, in lines, of any window. +Its value has to accommodate at least one text line as well as a mode +and header line, a horizontal scroll bar and a bottom divider, if +present. +@end defopt -@defun window-size-fixed-p &optional window horizontal -This function returns a non-@code{nil} value if @var{window}'s height -is fixed. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If the optional argument @var{horizontal} is -non-@code{nil}, the return value is non-@code{nil} if @var{window}'s -width is fixed. +@defopt window-min-width +This option specifies the minimum total width, in columns, of any +window. Its value has to accommodate two text columns as well as +margins, fringes, a scroll bar and a right divider, if present. +@end defopt -A @code{nil} return value does not necessarily mean that @var{window} -can be resized in the desired direction. To determine that, use the -function @code{window-resizable}. @xref{Resizing Windows}. +The following function tells how small a specific window can get taking +into account the sizes of its areas and the values of +@code{window-min-height}, @code{window-min-width} and +@code{window-size-fixed}. + +@defun window-min-size &optional window horizontal ignore pixelwise +This function returns the minimum size of @var{window}. @var{window} +must be a valid window and defaults to the selected one. The optional +argument @var{horizontal} non-@code{nil} means to return the minimum +number of columns of @var{window}; otherwise return the minimum number +of @var{window}'s lines. + +The return value makes sure that all components of @var{window} remain +fully visible if @var{window}'s size were actually set to it. With +@var{horizontal} @code{nil} it includes the mode and header line, the +horizontal scroll bar and the bottom divider. With @var{horizontal} +non-@code{nil} it includes the fringes, a scroll bar, and a right +divider, if present. It does not, however, include the space reserved +for the margins. + +The optional argument @var{ignore}, if non-@code{nil}, means ignore +restrictions imposed by fixed size windows, @code{window-min-height} or +@code{window-min-width} settings. If @var{ignore} equals @code{safe}, +live windows may get as small as @code{window-safe-min-height} lines and +@code{window-safe-min-width} columns. If @var{ignore} is a window, +ignore restrictions for that window only. Any other non-@code{nil} +value means ignore all of the above restrictions for all windows. + +The optional argument @var{pixelwise} non-@code{nil} means to return the +minimum size of @var{window} counted in pixels. @end defun - @xref{Coordinates and Windows}, for more functions that report the -positions of various parts of a window relative to the frame, from -which you can calculate its size. In particular, you can use the -functions @code{window-pixel-edges} and -@code{window-inside-pixel-edges} to find the size in pixels, for -graphical displays. - @node Resizing Windows @section Resizing Windows @cindex window resizing @@ -571,7 +708,7 @@ changed except by resizing the frame (@pxref{Size and Position}). arguments. Resizing an internal window causes its child windows to be resized to fit the same space. -@defun window-resizable window delta &optional horizontal ignore +@defun window-resizable window delta &optional horizontal ignore pixelwise This function returns @var{delta} if the size of @var{window} can be changed vertically by @var{delta} lines. If the optional argument @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if @@ -587,18 +724,21 @@ lines or columns. If @var{delta} is non-zero, a return value of 0 means that the window cannot be resized. Normally, the variables @code{window-min-height} and -@code{window-min-width} specify the smallest allowable window size. -@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU -Emacs Manual}. However, if the optional argument @var{ignore} is -non-@code{nil}, this function ignores @code{window-min-height} and -@code{window-min-width}, as well as @code{window-size-fixed}. -Instead, it considers the minimum-height window to be one consisting -of a header (if any), a mode line, plus a text area one line tall; and -a minimum-width window as one consisting of fringes, margins, and -scroll bar (if any), plus a text area two columns wide. -@end defun - -@defun window-resize window delta &optional horizontal ignore +@code{window-min-width} specify the smallest allowable window size +(@pxref{Window Sizes}). However, if the optional argument @var{ignore} +is non-@code{nil}, this function ignores @code{window-min-height} and +@code{window-min-width}, as well as @code{window-size-fixed}. Instead, +it considers the minimum-height window to be one consisting of a header +and a mode line, a horizontal scrollbar and a bottom divider (if any), +plus a text area one line tall; and a minimum-width window as one +consisting of fringes, margins, a scroll bar and a right divider (if +any), plus a text area two columns wide. + +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. +@end defun + +@defun window-resize window delta &optional horizontal ignore pixelwise This function resizes @var{window} by @var{delta} increments. If @var{horizontal} is @code{nil}, it changes the height by @var{delta} lines; otherwise, it changes the width by @var{delta} columns. A @@ -611,24 +751,30 @@ the window cannot be resized as demanded, an error is signaled. The optional argument @var{ignore} has the same meaning as for the function @code{window-resizable} above. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} will be interpreted as pixels. + The choice of which window edges this function alters depends on the values of the option @code{window-combination-resize} and the combination limits of the involved windows; in some cases, it may alter both edges. @xref{Recombining Windows}. To resize by moving only the bottom or right edge of a window, use the function -@code{adjust-window-trailing-edge}, below. +@code{adjust-window-trailing-edge}. @end defun @c The commands enlarge-window, enlarge-window-horizontally, @c shrink-window, and shrink-window-horizontally are documented in the @c Emacs manual. They are not preferred for calling from Lisp. -@defun adjust-window-trailing-edge window delta &optional horizontal +@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise This function moves @var{window}'s bottom edge by @var{delta} lines. If optional argument @var{horizontal} is non-@code{nil}, it instead moves the right edge by @var{delta} columns. If @var{window} is @code{nil}, it defaults to the selected window. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. + A positive @var{delta} moves the edge downwards or to the right; a negative @var{delta} moves it upwards or to the left. If the edge cannot be moved as far as specified by @var{delta}, this function @@ -639,31 +785,119 @@ moved. If this is not possible for some reason (e.g., if that adjacent window is fixed-size), it may resize other windows. @end defun +@cindex pixelwise, resizing windows +@defopt window-resize-pixelwise +If the value of this option is non-@code{nil}, Emacs resizes windows in +units of pixels. This currently affects functions like +@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window}, +@code{minimize-window}, @code{fit-window-to-buffer}, +@code{fit-frame-to-buffer} and +@code{shrink-window-if-larger-than-buffer} (all listed below). + +Note that when a frame's pixel size is not a multiple of its character +size, at least one window may get resized pixelwise even if this +option is @code{nil}. The default value is @code{nil}. +@end defopt + The following commands resize windows in more specific ways. When called interactively, they act on the selected window. -@deffn Command fit-window-to-buffer &optional window max-height min-height override -This command adjusts the height of @var{window} to fit the text in it. -It returns non-@code{nil} if it was able to resize @var{window}, and -@code{nil} otherwise. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. Otherwise, it should be a live -window. +@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size +This command adjusts the height or width of @var{window} to fit the text +in it. It returns non-@code{nil} if it was able to resize @var{window}, +and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it +defaults to the selected window. Otherwise, it should be a live window. + +If @var{window} is part of a vertical combination, this function adjusts +@var{window}'s height. The new height is calculated from the actual +height of the accessible portion of its buffer. The optional argument +@var{max-height}, if non-@code{nil}, specifies the maximum total height +that this function can give @var{window}. The optional argument +@var{min-height}, if non-@code{nil}, specifies the minimum total height +that it can give, which overrides the variable @code{window-min-height}. +Both @var{max-height} and @var{min-height} are specified in lines and +include mode and header line and a bottom divider, if any. + +If @var{window} is part of a horizontal combination and the value of the +option @code{fit-window-to-buffer-horizontally} (see below) is +non-@code{nil}, this function adjusts @var{window}'s height. The new +width of @var{window} is calculated from the maximum length of its +buffer's lines that follow the current start position of @var{window}. +The optional argument @var{max-width} specifies a maximum width and +defaults to the width of @var{window}'s frame. The optional argument +@var{min-width} specifies a minimum width and defaults to +@code{window-min-width}. Both @var{max-width} and @var{min-width} are +specified in columns and include fringes, margins and scrollbars, if +any. -The optional argument @var{max-height}, if non-@code{nil}, specifies -the maximum total height that this function can give @var{window}. -The optional argument @var{min-height}, if non-@code{nil}, specifies -the minimum total height that it can give, which overrides the -variable @code{window-min-height}. +The optional argument @var{preserve-size}, if non-@code{nil}, will +install a parameter to preserve the size of @var{window} during future +resize operations (@pxref{Preserving Window Sizes}). -If the optional argument @var{override} is non-@code{nil}, this -function ignores any size restrictions imposed by -@code{window-min-height} and @code{window-min-width}. +If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, +this function will try to resize the frame of @var{window} to fit its +contents by calling @code{fit-frame-to-buffer} (see below). +@end deffn -@vindex fit-frame-to-buffer -If the option @code{fit-frame-to-buffer} is non-@code{nil}, this -command may resize the frame to fit its contents. +@defopt fit-window-to-buffer-horizontally +If this is non-@code{nil}, @code{fit-window-to-buffer} can resize +windows horizontally. If this is @code{nil} (the default) +@code{fit-window-to-buffer} never resizes windows horizontally. If this +is @code{only}, it can resize windows horizontally only. Any other +value means @code{fit-window-to-buffer} can resize windows in both +dimensions. +@end defopt + +@defopt fit-frame-to-buffer +If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a +frame to its buffer. A frame is fit if and only if its root window is a +live window and this option is non-@code{nil}. If this is +@code{horizontally}, frames are fit horizontally only. If this is +@code{vertically}, frames are fit vertically only. Any other +non-@code{nil} value means frames can be resized in both dimensions. +@end defopt + +If you have a frame that displays only one window, you can fit that +frame to its buffer using the command @code{fit-frame-to-buffer}. + +@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only +This command adjusts the size of @var{frame} to display the contents of +its buffer exactly. @var{frame} can be any live frame and defaults to +the selected one. Fitting is done only if @var{frame}'s root window is +live. The arguments @var{max-height}, @var{min-height}, @var{max-width} +and @var{min-width} specify bounds on the new total size of +@var{frame}'s root window. @var{min-height} and @var{min-width} default +to the values of @code{window-min-height} and @code{window-min-width} +respectively. + +If the optional argument @var{only} is @code{vertically}, this function +may resize the frame vertically only. If @var{only} is +@code{horizontally}, it may resize the frame horizontally only. @end deffn +The behavior of @code{fit-frame-to-buffer} can be controlled with the +help of the two options listed next. + +@defopt fit-frame-to-buffer-margins +This option can be used to specify margins around frames to be fit by +@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for +example, that such frames overlap the taskbar. + +It specifies the numbers of pixels to be left free on the left, above, +the right, and below a frame that shall be fit. The default specifies +@code{nil} for each which means to use no margins. The value specified +here can be overridden for a specific frame by that frame's +@code{fit-frame-to-buffer-margins} parameter, if present. +@end defopt + +@defopt fit-frame-to-buffer-sizes +This option specifies size boundaries for @code{fit-frame-to-buffer}. +It specifies the total maximum and minimum lines and maximum and minimum +columns of the root window of any frame that shall be fit to its buffer. +If any of these values is non-@code{nil}, it overrides the corresponding +argument of @code{fit-frame-to-buffer}. +@end defopt + @deffn Command shrink-window-if-larger-than-buffer &optional window This command attempts to reduce @var{window}'s height as much as possible while still showing its full buffer, but no less than @@ -675,8 +909,12 @@ it should be a live window. This command does nothing if the window is already too short to display all of its buffer, or if any of the buffer is scrolled off-screen, or if the window is the only live window in its frame. + +This command calls @code{fit-window-to-buffer} (see above) to do its +work. @end deffn + @cindex balancing window sizes @deffn Command balance-windows &optional window-or-frame This function balances windows in a way that gives more space to @@ -709,6 +947,98 @@ window. @end deffn +@node Preserving Window Sizes +@section Preserving Window Sizes +@cindex preserving window sizes + +A window can get resized explicitly by using one of the functions from +the preceding section or implicitly, for example, when resizing an +adjacent window, when splitting or deleting a window (@pxref{Splitting +Windows}, @pxref{Deleting Windows}) or when resizing the window's frame +(@pxref{Size and Position}). + + It is possible to avoid implicit resizing of a specific window when +there are one or more other resizable windows on the same frame. For +this purpose, Emacs must be advised to @dfn{preserve} the size of that +window. There are two basic ways to do that. + +@defvar window-size-fixed +If this buffer-local variable is non-@code{nil}, the size of any window +displaying the buffer cannot normally be changed. Deleting a window or +changing the frame's size may still change the window's size, if there +is no 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. + +If this variable is @code{nil}, this does not necessarily mean that any +window showing the buffer can be resized in the desired direction. To +determine that, use the function @code{window-resizable}. +@xref{Resizing Windows}. +@end defvar + +Often @code{window-size-fixed} is overly aggressive because it inhibits +any attempt to explicitly resize or split an affected window as well. +This may even happen after the window has been resized implicitly, for +example, when deleting an adjacent window or resizing the window's +frame. The following function tries hard to never disallow resizing +such a window explicitly: + +@defun window-preserve-size &optional window horizontal preserve +This function (un-)marks the height of window @var{window} as preserved +for future resize operations. @var{window} must be a live window and +defaults to the selected one. If the optional argument @var{horizontal} +is non-@code{nil}, it (un-)marks the width of @var{window} as preserved. + +If the optional argument @var{preserve} is @code{t}, this means to +preserve the current height/width of @var{window}'s body. The +height/width of @var{window} will change only if Emacs has no better +choice. Resizing a window whose height/width is preserved by this +function never throws an error. + +If @var{preserve} is @code{nil}, this means to stop preserving the +height/width of @var{window}, lifting any respective restraint induced +by a previous call of this function for @var{window}. Calling +@code{enlarge-window}, @code{shrink-window} or +@code{fit-window-to-buffer} with @var{window} as argument may also +remove the respective restraint. +@end defun + +@code{window-preserve-size} is currently invoked by the following +functions: + +@table @code +@item fit-window-to-buffer +If the optional argument @var{preserve-size} of that function +(@pxref{Resizing Windows}) is non-@code{nil}, the size established by +that function is preserved. + +@item display-buffer +If the @var{alist} argument of that function (@pxref{Choosing Window}) +contains a @code{preserve-size} entry, the size of the window produced +by that function is preserved. +@end table + + @code{window-preserve-size} installs a window parameter (@pxref{Window +Parameters}) called @code{preserved-size} which is consulted by the +window resizing functions. This parameter will not prevent resizing the +window when the window shows another buffer than the one when +@code{window-preserve-size} was invoked or if its size has changed since +then. + +The following function can be used to check whether the height of a +particular window is preserved: + +@defun window-preserved-size &optional window horizontal +This function returns the preserved height of window @var{window} in +pixels. @var{window} must be a live window and defaults to the selected +one. If the optional argument @var{horizontal} is non-@code{nil}, it +returns the preserved width of @var{window}. It returns @code{nil} if +the size of @var{window} is not preserved. +@end defun + + @node Splitting Windows @section Splitting Windows @cindex splitting windows @@ -717,10 +1047,10 @@ window. This section describes functions for creating a new window by @dfn{splitting} an existing one. -@defun split-window &optional window size side +@defun split-window &optional window size side pixelwise This function creates a new live window next to the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. That window is ``split'', and reduced in +to the selected window. That window is split, and reduced in size. The space is taken up by the new window, which is returned. The optional second argument @var{size} determines the sizes of @@ -732,15 +1062,25 @@ value of @var{side}). If @var{size} is a negative number, the new window is given @minus{}@var{size} lines (or columns). If @var{size} is @code{nil}, this function obeys the variables -@code{window-min-height} and @code{window-min-width}. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. Thus, it signals an error if splitting would result in -making a window smaller than those variables specify. However, a +@code{window-min-height} and @code{window-min-width} (@pxref{Window +Sizes}). Thus, it signals an error if splitting would result in making +a window smaller than those variables specify. However, a non-@code{nil} value for @var{size} causes those variables to be -ignored; in that case, the smallest allowable window is considered to -be one that has space for a text area one line tall and/or two columns +ignored; in that case, the smallest allowable window is considered to be +one that has space for a text area one line tall and/or two columns wide. +Hence, if @var{size} is specified, it's the caller's responsibility to +check whether the emanating windows are large enough to encompass all +areas like a mode line or a scroll bar. The function +@code{window-min-size} (@pxref{Window Sizes}) can be used to determine +the minimum requirements of @var{window} in this regard. Since the new +window usually inherits areas like the mode line or the scroll bar +from @var{window}, that function is also a good guess for the minimum +size of the new window. The caller should specify a smaller size only +if it correspondingly removes an inherited area before the next +redisplay. + The optional third argument @var{side} determines the position of the new window relative to @var{window}. If it is @code{nil} or @code{below}, the new window is placed below @var{window}. If it is @@ -752,6 +1092,10 @@ the right of @var{window}. If @var{side} is @code{left}, the new window is placed on the left of @var{window}. In both these cases, @var{size} specifies a total window width, in columns. +The optional fourth argument @var{pixelwise}, if non-@code{nil}, means +to interpret @var{size} in units of pixels, instead of lines and +columns. + If @var{window} is a live window, the new window inherits various properties from it, including margins and scroll bars. If @var{window} is an internal window, the new window inherits the @@ -855,6 +1199,7 @@ point was previously on. Note that this only affects function. @end defopt + @node Deleting Windows @section Deleting Windows @cindex deleting windows @@ -947,6 +1292,8 @@ are the opposite of what they are in those other functions. @node Recombining Windows @section Recombining Windows +@cindex recombining windows +@cindex windows, recombining When deleting the last sibling of a window @var{W}, its parent window is deleted too, with @var{W} replacing it in the window tree. This @@ -1164,7 +1511,7 @@ vertical combination @var{W1}. @cindex window combination limit @defun set-window-combination-limit window limit -This functions sets the @dfn{combination limit} of the window +This function sets the @dfn{combination limit} of the window @var{window} to @var{limit}. This value can be retrieved via the function @code{window-combination-limit}. See below for its effects; note that it is only meaningful for internal windows. The @@ -1298,16 +1645,27 @@ windows. @defun select-window window &optional norecord This function makes @var{window} the selected window and the window selected within its frame (@pxref{Basic Windows}) and selects that -frame. @var{window} must be a live window. This function also makes -@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets -that buffer's value of @code{point} to the value of @code{window-point} -(@pxref{Window Point}) in @var{window}. The return value is -@var{window}. +frame. It also makes @var{window}'s buffer (@pxref{Buffers and +Windows}) current and sets that buffer's value of @code{point} to the +value of @code{window-point} (@pxref{Window Point}) in @var{window}. +@var{window} must be a live window. The return value is @var{window}. By default, this function also moves @var{window}'s buffer to the front -of the buffer list (@pxref{The Buffer List}), and makes @var{window} the +of the buffer list (@pxref{Buffer List}), and makes @var{window} the most recently selected window. However, if the optional argument @var{norecord} is non-@code{nil}, these additional actions are omitted. + +This function runs @code{buffer-list-update-hook} (@pxref{Buffer List}) +unless @var{norecord} is non-@code{nil}. Note that applications and +internal routines often temporarily select a window in order to simplify +coding. As a rule, such selections (including those made by the macros +@code{save-selected-window} and @code{with-selected-window} below) are +not recorded thus avoiding to pollute @code{buffer-list-update-hook}. +Selections that really count are those causing a visible change in +the next redisplay of @var{window}'s frame and should be always +recorded. This also means that to run a function each time a window +gets selected, putting it on @code{buffer-list-update-hook} should be +the right choice. @end defun @cindex most recently selected windows @@ -1367,6 +1725,20 @@ function does not alter the list of most recently selected windows, nor the buffer list. @end defun +@cindex window use time +@cindex use time of window +@cindex window order by time of last use +@defun window-use-time &optional window +This functions returns the use time of window @var{window}. +@var{window} must be a live window and defaults to the selected one. +The @dfn{use time} of a window is not really a time value, but it does +increase monotonically with each window selection, so the window with +the lowest use time is the least recently selected one, and the +window with the highest use time is the most recently selected +one. +@end defun + + @node Cyclic Window Ordering @section Cyclic Ordering of Windows @cindex cyclic ordering of windows @@ -1393,7 +1765,7 @@ if omitted or @code{nil}, it defaults to the selected window. The optional argument @var{minibuf} specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when @var{minibuf} is @code{nil}, a minibuffer window is included only if it is currently -``active''; this matches the behavior of @kbd{C-x o}. (Note that a +active; this matches the behavior of @kbd{C-x o}. (Note that a minibuffer window is active as long as its minibuffer is in use; see @ref{Minibuffers}). @@ -1487,8 +1859,8 @@ criterion, without selecting it: @cindex least recently used window @defun get-lru-window &optional all-frames dedicated not-selected -This function returns a live window which is heuristically the ``least -recently used'' window. The optional argument @var{all-frames} has +This function returns a live window which is heuristically the least +recently used. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. If any full-width windows are present, only those windows are @@ -1500,6 +1872,13 @@ the optional argument @var{not-selected} is non-@code{nil}, this function returns @code{nil} in that case. @end defun +@cindex most recently used window +@defun get-mru-window &optional all-frames dedicated not-selected +This function is like @code{get-lru-window}, but it returns the most +recently used window instead. The meaning of the arguments is the +same as described for @code{get-lru-window}. +@end defun + @cindex largest window @defun get-largest-window &optional all-frames dedicated not-selected This function returns the window with the largest area (height times @@ -1626,7 +2005,9 @@ to eliminate this discrepancy. This function returns a list of all windows currently displaying @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the name of an existing buffer. If omitted or @code{nil}, it defaults to -the current buffer. +the current buffer. If the currently selected window displays +@var{buffer-or-name}, it will be the first in the list returned by +this function. The arguments @var{minibuf} and @var{all-frames} have the same meanings as in the function @code{next-window} (@pxref{Cyclic Window @@ -1676,7 +2057,7 @@ window and make it the current buffer. It is often used interactively return value is the buffer switched to. If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If +returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} @@ -1684,19 +2065,52 @@ buffer's major mode is determined by the variable @code{major-mode} Normally, the specified buffer is put at the front of the buffer list---both the global buffer list and the selected frame's buffer -list (@pxref{The Buffer List}). However, this is not done if the +list (@pxref{Buffer List}). However, this is not done if the optional argument @var{norecord} is non-@code{nil}. -Sometimes, @code{switch-to-buffer} may be unable to display the buffer -in the selected window. This happens if the selected window is a -minibuffer window, or if the selected window is strongly dedicated to -its buffer (@pxref{Dedicated Windows}). In that case, the command -normally tries to display the buffer in some other window, by invoking -@code{pop-to-buffer} (see below). However, if the optional argument -@var{force-same-window} is non-@code{nil}, it signals an error -instead. +Sometimes, the selected window may not be suitable for displaying the +buffer. This happens if the selected window is a minibuffer window, or +if the selected window is strongly dedicated to its buffer +(@pxref{Dedicated Windows}). In such cases, the command normally tries +to display the buffer in some other window, by invoking +@code{pop-to-buffer} (see below). + +If the optional argument @var{force-same-window} is non-@code{nil} and +the selected window is not suitable for displaying the buffer, this +function always signals an error when called non-interactively. In +interactive use, if the selected window is a minibuffer window, this +function will try to use some other window instead. If the selected +window is strongly dedicated to its buffer, the option +@code{switch-to-buffer-in-dedicated-window} described next can be used +to proceed. @end deffn +@defopt switch-to-buffer-in-dedicated-window +This option, if non-@code{nil}, allows @code{switch-to-buffer} to +proceed when called interactively and the selected window is strongly +dedicated to its buffer. + +The following values are respected: + +@table @code +@item nil +Disallows switching and signals an error as in non-interactive use. + +@item prompt +Prompts the user whether to allow switching. + +@item pop +Invokes @code{pop-to-buffer} to proceed. + +@item t +Marks the selected window as non-dedicated and proceeds. +@end table + +When called non-interactively, @code{switch-to-buffer} always signals an +error when the selected window is dedicated to its buffer and +@var{force-same-window} is non-@code{nil}. +@end defopt + By default, @code{switch-to-buffer} shows the buffer at its position of @code{point}. This behavior can be tuned using the following option. @@ -1762,7 +2176,7 @@ possible (@pxref{Input Focus}). The return value is the buffer that was switched to. If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If +returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} @@ -1842,7 +2256,10 @@ The constant @code{display-buffer-fallback-action}. @noindent Each action function is called in turn, passing the buffer as the first argument and the combined action alist as the second argument, -until one of the functions returns non-@code{nil}. +until one of the functions returns non-@code{nil}. The caller can +pass @code{(allow-no-window . t)} as an element of the action alist to +indicate its readiness to handle the case of not displaying the +buffer in a window. The argument @var{action} can also have a non-@code{nil}, non-list value. This has the special meaning that the buffer should be @@ -1876,7 +2293,7 @@ corresponding display action to display the buffer. @defopt display-buffer-base-action The value of this option should be a display action. This option can -be used to define a ``standard'' display action for calls to +be used to define a standard display action for calls to @code{display-buffer}. @end defopt @@ -1902,7 +2319,7 @@ to another buffer (@pxref{Dedicated Windows}). It also fails if @end defun @defun display-buffer-reuse-window buffer alist -This function tries to ``display'' @var{buffer} by finding a window +This function tries to display @var{buffer} by finding a window that is already displaying it. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, @@ -1947,6 +2364,25 @@ the function specified in @code{pop-up-frame-function} is added to the newly created frame's parameters. @end defun +@defun display-buffer-use-some-frame buffer alist +This function tries to display @var{buffer} by trying to find a +frame that meets a predicate (by default any frame other than the +current frame). + +If this function chooses a window on another frame, it makes that frame +visible and, unless @var{alist} contains an @code{inhibit-switch-frame} +entry (@pxref{Choosing Window Options}), raises that frame if necessary. + +If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a +function taking one argument (a frame), returning non-nil if the +frame is a candidate; this function replaces the default predicate. + +If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, +the selected window is used; thus if the selected frame has a single +window, it is not used. + +@end defun + @defun display-buffer-pop-up-window buffer alist This function tries to display @var{buffer} by splitting the largest or least recently-used window (typically one on the selected frame). @@ -1965,7 +2401,7 @@ adjust the window's height, use an entry whose @sc{car} is @item A number specifies the desired height of the new window. An integer -number specifies the number of lines of the window. A floating point +specifies the number of lines of the window. A floating-point number gives the fraction of the window's height with respect to the height of the frame's root window. @@ -1986,7 +2422,7 @@ To adjust the window's width, use an entry whose @sc{car} is @item A number specifies the desired width of the new window. An integer -number specifies the number of columns of the window. A floating point +specifies the number of columns of the window. A floating-point number gives the fraction of the window's width with respect to the width of the frame's root window. @@ -1996,6 +2432,13 @@ argument: the new window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize +If @var{alist} contains a @code{preserve-size} entry, Emacs will try to +preserve the size of the new window during future resize operations +(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a +cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width +of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve +the height of the window. + This function can fail if no window splitting can be performed for some reason (e.g., if the selected frame has an @code{unsplittable} frame parameter; @pxref{Buffer Parameters}). @@ -2022,12 +2465,30 @@ specified by that entry will override any other window found by the methods above, even if that window never showed @var{buffer} before. @end defun +@defun display-buffer-at-bottom buffer alist +This function tries to display @var{buffer} in a window at the bottom +of the selected frame. + +This either splits the window at the bottom of the frame or the +frame's root window, or reuses an existing window at the bottom of the +selected frame. +@end defun + @defun display-buffer-use-some-window buffer alist This function tries to display @var{buffer} by choosing an existing window and displaying the buffer in that window. It can fail if all windows are dedicated to another buffer (@pxref{Dedicated Windows}). @end defun +@defun display-buffer-no-window buffer alist +If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then +this function does not display @code{buffer}. This allows to override +the default action and avoid displaying the buffer. It is assumed that +when the caller specifies a non-@code{nil} @code{allow-no-window} value +it can handle a @code{nil} value returned from @code{display-buffer} in +this case. +@end defun + To illustrate the use of action functions, consider the following example. @@ -2056,7 +2517,7 @@ buffer there. If all these steps fail, it will proceed using whatever (provided *foo* was put by @code{display-buffer} there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead -of the number ``10'', we specified the function +of the number 10, we specified the function @code{fit-window-to-buffer}, @code{display-buffer} would come up with a one-line window to fit the empty buffer. If the window is part of a horizontal combination, it sets its width to 40 columns. Whether a new @@ -2066,7 +2527,7 @@ the window split and the values of and @code{split-width-threshold} (@pxref{Choosing Window Options}). Now suppose we combine this call with a preexisting setup for -`display-buffer-alist' as follows. +@code{display-buffer-alist} as follows. @example @group @@ -2097,7 +2558,7 @@ window below the selected window. selected one is dedicated to its buffer, @code{display-buffer} will proceed as described in the previous example. Note, however, that when it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to ``5'' since that value +in any case try to set its number of lines to 5 since that value overrides the corresponding specification in the @var{action} argument of @code{display-buffer}. @@ -2168,6 +2629,21 @@ least that many columns. If the value is @code{nil}, that means not to split this way. @end defopt +@defopt even-window-sizes +This variable, if non-nil, causes @code{display-buffer} to even window +sizes whenever it reuses an existing window and that window is adjacent +to the selected one. + +If its value is @code{width-only}, sizes are evened only if the reused +window is on the left or right of the selected one and the selected +window is wider than the reused one. If its value is @code{height-only} +sizes are evened only if the reused window is above or beneath the +selected window and the selected window is higher than the reused one. +Any other non-@code{nil} value means to even sizes in any of these cases +provided the selected window is larger than the reused one in the sense +of their combination. +@end defopt + @defopt pop-up-frames If the value of this variable is non-@code{nil}, that means @code{display-buffer} may display buffers by making new frames. The @@ -2306,9 +2782,9 @@ or killed, or has been already shown by a recent invocation of If repeated invocations of this command have already shown all buffers previously shown in @var{window}, further invocations will show buffers -from the buffer list of the frame @var{window} appears on (@pxref{The -Buffer List}), trying to skip buffers that are already shown in another -window on that frame. +from the buffer list of the frame @var{window} appears on (@pxref{Buffer +List}), trying to skip buffers that are already shown in another window +on that frame. @end deffn @deffn Command switch-to-next-buffer &optional window @@ -2319,7 +2795,7 @@ defaults to the selected one. If there is no recent invocation of @code{switch-to-prev-buffer} that can be undone, this function tries to show a buffer from the buffer list -of the frame @var{window} appears on (@pxref{The Buffer List}). +of the frame @var{window} appears on (@pxref{Buffer List}). @end deffn By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} @@ -2366,7 +2842,7 @@ called when a buffer gets killed, deletes the window in case (1) and behaves like @code{delete-windows-on} otherwise. @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)? - When @code{bury-buffer} (@pxref{The Buffer List}) operates on the + When @code{bury-buffer} (@pxref{Buffer List}) operates on the selected window (which shows the buffer that shall be buried), it handles case (2) by calling @code{frame-auto-hide-function} (@pxref{Quitting Windows}) to deal with the selected frame. The other @@ -2405,7 +2881,7 @@ buffer is shown on a separate frame, you might want to call hand, a window has been reused for displaying the buffer, you might prefer showing the buffer previously shown in that window, by calling the function @code{switch-to-prev-buffer} (@pxref{Window History}). -Finally, you might want to either bury (@pxref{The Buffer List}) or kill +Finally, you might want to either bury (@pxref{Buffer List}) or kill (@pxref{Killing Buffers}) the window's buffer. The following command uses information on how the window for @@ -2487,11 +2963,12 @@ one window that should be either quit, or whose buffer should be buried. The function specified by this option is called to automatically hide frames. This function is called with one argument---a frame. -The function specified here is called by @code{bury-buffer} (@pxref{The -Buffer List}) when the selected window is dedicated and shows the buffer -to bury. It is also called by @code{quit-restore-window} (see above) -when the frame of the window to quit has been specially created for -displaying that window's buffer and the buffer is not killed. +The function specified here is called by @code{bury-buffer} +(@pxref{Buffer List}) when the selected window is dedicated and shows +the buffer to bury. It is also called by @code{quit-restore-window} +(see above) when the frame of the window to quit has been specially +created for displaying that window's buffer and the buffer is not +killed. The default is to call @code{iconify-frame} (@pxref{Visibility of Frames}). Alternatively, you may specify either @code{delete-frame} @@ -2548,7 +3025,7 @@ window's buffer) if that window were selected. The default for When @var{window} is the selected window, the value returned is the value of point in that window's buffer. Strictly speaking, it would be -more correct to return the ``top-level'' value of point, outside of any +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 @@ -2645,7 +3122,7 @@ 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 37}, the start of the next line, point will be ``above'' the top +@w{to 37}, the start of the next line, point will 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: @@ -2697,12 +3174,14 @@ position that works well with point, and thus @var{position} is not used. @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}. +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} defaults to the selected window. If +@var{position} is @code{t}, that means to check either the first +visible position of the last screen line in @var{window}, or the +end-of-buffer position, whichever comes first. This function considers only vertical scrolling. If @var{position} is out of view only because @var{window} has been scrolled horizontally, @@ -2952,7 +3431,7 @@ only if point is already on that position do they signal an error. @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. +not move point with respect to the text. If @var{count} is a non-negative number, that puts the line containing point @var{count} lines down from the top of the window. If @@ -3087,8 +3566,8 @@ 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 + 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 @@ -3208,33 +3687,28 @@ is off the screen due to horizontal scrolling: @end group @end example + @node Coordinates and Windows @section Coordinates and Windows @cindex frame-relative coordinate @cindex coordinate, relative to frame @cindex window position - This section describes functions that report the position of a -window. Most of these functions report positions relative to the -window's frame. In this case, the coordinate origin @samp{(0,0)} lies -near the upper left corner of the frame. For technical reasons, on -graphical displays the origin is not located at the exact corner of -the graphical window as it appears on the screen. If Emacs is built -with the GTK+ toolkit, the origin is at the upper left corner of the -frame area used for displaying Emacs windows, below the title-bar, -GTK+ menu bar, and tool bar (since these are drawn by the window -manager and/or GTK+, not by Emacs). But if Emacs is not built with -GTK+, the origin is at the upper left corner of the tool bar (since in -this case Emacs itself draws the tool bar). In both cases, the X and -Y coordinates increase rightward and downward respectively. - - Except where noted, X and Y coordinates are reported in integer -character units, i.e., numbers of lines and columns respectively. On a -graphical display, each ``line'' and ``column'' corresponds to the -height and width of a default character specified by the frame's -default font. - -@defun window-edges &optional window +This section describes functions that report the position of a window. +Most of these functions report positions relative to an origin at the +native position of the window's frame (@pxref{Frame Geometry}). Some +functions report positions relative to the origin of the display of the +window's frame. In any case, the origin has the coordinates (0, 0) and +X and Y coordinates increase rightward and downward +respectively. + + For the following functions, X and Y coordinates are reported in +integer character units, i.e., numbers of lines and columns +respectively. On a graphical display, each ``line'' and ``column'' +corresponds to the height and width of the default character specified by +the frame's default font (@pxref{Frame Font}). + +@defun window-edges &optional window body absolute pixelwise This function returns a list of the edge coordinates of @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. @@ -3246,49 +3720,78 @@ coordinate of the topmost row, the X coordinate one column to the right of the rightmost column, and the Y coordinate one row down from the bottommost row. -Note that these are the actual outer edges of the window, including -any header line, mode line, scroll bar, fringes, and display margins. -On a text terminal, if the window has a neighbor on its right, its -right edge includes the separator line between the window and its +Note that these are the actual outer edges of the window, including any +header line, mode line, scroll bar, fringes, window divider and display +margins. On a text terminal, if the window has a neighbor on its right, +its right edge includes the separator line between the window and its neighbor. -@end defun -@defun window-inside-edges &optional window -This function is similar to @code{window-edges}, but the returned edge -values are for the text area of the window. They exclude any header -line, mode line, scroll bar, fringes, display margins, and vertical -separator. +If the optional argument @var{body} is @code{nil}, this means to +return the edges corresponding to the total size of @var{window}. +@var{body} non-@code{nil} means to return the edges of @var{window}'s +body (aka text area). If @var{body} is non-@code{nil}, @var{window} +must specify a live window. + +If the optional argument @var{absolute} is @code{nil}, this means to +return edges relative to the native position of @var{window}'s frame. +@var{absolute} non-@code{nil} means to return coordinates relative to +the origin (0, 0) of @var{window}'s display. On non-graphical systems +this argument has no effect. + +If the optional argument @var{pixelwise} is @code{nil}, this means to +return the coordinates in terms of the default character width and +height of @var{window}'s frame (@pxref{Frame Font}), rounded if +necessary. @var{pixelwise} non-@code{nil} means to return the +coordinates in pixels. Note that the pixel specified by @var{right} and +@var{bottom} is immediately outside of these edges. If @var{absolute} +is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too. @end defun -@defun window-top-line &optional window -This function returns the Y coordinate of the topmost row of -@var{window}, equivalent to the @var{top} entry in the list returned -by @code{window-edges}. +@defun window-body-edges &optional window +This function returns the edges of @var{window}'s body (@pxref{Window +Sizes}). Calling @code{(window-body-edges window)} is equivalent to +calling @code{(window-edges window t)}, see above. @end defun +@comment The following two functions are confusing and hardly used. +@ignore @defun window-left-column &optional window -This function returns the X coordinate of the leftmost column of -@var{window}, equivalent to the @var{left} entry in the list returned -by @code{window-edges}. +This function returns the leftmost column of @var{window}. This value +equals the @var{left} entry in the list returned by @code{(window-edges +window)} minus the number of columns occupied by the internal border of +@var{window}'s frame. +@end defun + +@defun window-top-line &optional window +This function returns the topmost row of @var{window}. This value is +equal to the @var{top} entry in the list returned by @code{(window-edges +window)} minus the number of lines occupied by the internal border of +@var{window}'s frame. @end defun +@end ignore The following functions can be used to relate a set of frame-relative coordinates to a window: @defun window-at x y &optional frame -This function returns the live window at the frame-relative -coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no -window at that position, the return value is @code{nil}. If -@var{frame} is omitted or @code{nil}, it defaults to the selected +This function returns the live window at the coordinates @var{x} and +@var{y} given in default character sizes (@pxref{Frame Font}) relative +to the native position of @var{frame} (@pxref{Frame Geometry}). + +If there is no window at that position, the return value is @code{nil}. +If @var{frame} is omitted or @code{nil}, it defaults to the selected frame. @end defun @defun coordinates-in-window-p coordinates window -This function checks whether a window @var{window} occupies the -frame-relative coordinates @var{coordinates}, and if so, which part of -the window that is. @var{window} should be a live window. +This function checks whether a window @var{window} occupies the frame +relative coordinates @var{coordinates}, and if so, which part of the +window that is. @var{window} should be a live window. + @var{coordinates} should be a cons cell of the form @code{(@var{x} -. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. +. @var{y})}, where @var{x} and @var{y} are given in default character +sizes (@pxref{Frame Font}) relative to the native position of +@var{window}'s frame (@pxref{Frame Geometry}). If there is no window at the specified position, the return value is @code{nil} . Otherwise, the return value is one of the following: @@ -3306,6 +3809,14 @@ The coordinates are in the mode line of @var{window}. @item header-line The coordinates are in the header line of @var{window}. +@item right-divider +The coordinates are in the divider separating @var{window} from a +window on the right. + +@item bottom-divider +The coordinates are in the divider separating @var{window} from a +window beneath. + @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 @@ -3331,42 +3842,103 @@ argument because it always uses the frame that @var{window} is on. The following functions return window positions in pixels, rather than character units. Though mostly useful on graphical displays, they can also be called on text terminals, where the screen area of -each text character is taken to be ``one pixel''. +each text character is taken to be one pixel. @defun window-pixel-edges &optional window This function returns a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. +@var{window}. Calling @code{(window-pixel-edges window)} is equivalent +to calling @code{(window-edges window nil nil t)}, see above. +@end defun -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X pixel -coordinate of the left window edge, the Y pixel coordinate of the top -edge, one more than the X pixel coordinate of the right edge, and one -more than the Y pixel coordinate of the bottom edge. +@comment The following two functions are confusing and hardly used. +@ignore +@defun window-pixel-left &optional window +This function returns the left pixel edge of window @var{window}. This +value equals the @var{left} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. +@end defun + +@defun window-pixel-top &optional window +This function returns the top pixel edge of window @var{window}. This +value is equal to the @var{top} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. @end defun +@end ignore -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the pixel coordinates for the edges of the window's text area, -rather than the pixel coordinates for the edges of the window itself. -@var{window} must specify a live window. +@defun window-body-pixel-edges &optional window +This function returns the pixel edges of @var{window}'s body. Calling +@code{(window-body-pixel-edges window)} is equivalent to calling +@code{(window-edges window t nil t)}, see above. @end defun - The following functions return window positions in pixels, relative -to the display screen rather than the frame: + The following functions return window positions in pixels, relative to +the origin of the display screen rather than that of the frame: @defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. +This function returns the pixel coordinates of @var{WINDOW} relative to +an origin at (0, 0) of the display of @var{window}'s frame. Calling +@code{(window-absolute-pixel-edges)} is equivalent to calling +@code{(window-edges window nil t t)}, see above. +@end defun + +@defun window-absolute-body-pixel-edges &optional window +This function returns the pixel coordinates of @var{WINDOW}'s body +relative to an origin at (0, 0) of the display of @var{window}'s frame. +Calling @code{(window-absolute-body-pixel-edges window)} is equivalent +to calling @code{(window-edges window t t t)}, see above. + +Combined with @code{set-mouse-absolute-pixel-position}, this function +can be used to move the mouse pointer to an arbitrary buffer position +visible in some window: + +@example +@group +(let ((edges (window-absolute-body-pixel-edges)) + (position (pos-visible-in-window-p nil nil t))) + (x-set-mouse-absolute-pixel-position + (+ (nth 0 edges) (nth 0 position)) + (+ (nth 1 edges) (nth 1 position)))) +@end group +@end example + +On a graphical terminal this form ``warps'' the mouse cursor to the +upper left corner of the glyph at the selected window's point. A +position calculated this way can be also used to show a tooltip window +there. @end defun -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. @var{window} must specify a live window. +The following function returns the screen coordinates of a buffer +position visible in a window: + +@defun window-absolute-pixel-position &optional position window +If the buffer position @var{position} is visible in window @var{window}, +this function returns the display coordinates of the upper/left corner +of the glyph at @var{position}. The return value is a cons of the X- +and Y-coordinates of that corner, relative to an origin at (0, 0) of +@var{window}'s display. It returns @code{nil} if @var{position} is not +visible in @var{window}. + +@var{window} must be a live window and defaults to the selected +window. @var{position} defaults to the value of @code{window-point} +of @var{window}. + +This means that in order to move the mouse pointer to the position of +point in the selected window, it's sufficient to write: + +@example +@group +(let ((position (window-absolute-pixel-position))) + (set-mouse-absolute-pixel-position + (car position) (cdr position))) +@end group +@end example @end defun + @node Window Configurations @section Window Configurations @cindex window configurations @@ -3374,7 +3946,7 @@ the display screen. @var{window} must specify a live window. A @dfn{window configuration} records the entire layout of one frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their +buffers are scrolled, and their value of point; also their fringes, margins, and scroll bar settings. It also includes the value of @code{minibuffer-scroll-window}. As a special exception, the window configuration does not record the value of point in the selected window @@ -3450,13 +4022,13 @@ This function returns @code{t} if @var{object} is a window configuration. @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 +structure of windows, but ignores the values of point 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. +saved point. @end defun @defun window-configuration-frame config @@ -3477,6 +4049,7 @@ to clone the state of a frame into an arbitrary live window (@code{set-window-configuration} effectively clones the windows of a frame into the root window of that very frame only). +@cindex window state @defun window-state-get &optional window writable This function returns the state of @var{window} as a Lisp object. The argument @var{window} must be a valid window and defaults to the root @@ -3498,11 +4071,13 @@ written to disk and read back in another session. In either case, use the following function to restore the state of the window. @defun window-state-put state &optional window ignore -This function puts the window state @var{state} into @var{window}. The -argument @var{state} should be the state of a window returned by an -earlier invocation of @code{window-state-get}, see above. The optional -argument @var{window} must specify a live window and defaults to the -selected one. +This function puts the window state @var{state} into @var{window}. +The argument @var{state} should be the state of a window returned by +an earlier invocation of @code{window-state-get}, see above. The +optional argument @var{window} can be either a live window or an +internal window (@pxref{Windows and Frames}) and defaults to the +selected one. If @var{window} is not live, it is replaced by a live +window before putting @var{state} into it. If the optional argument @var{ignore} is non-@code{nil}, it means to ignore minimum window sizes and fixed-size restrictions. If @var{ignore} @@ -3622,6 +4197,15 @@ This parameter specifies the window that this one has been cloned from. It is installed by @code{window-state-get} (@pxref{Window Configurations}). +@item @code{preserved-size} +This parameter specifies a buffer, a direction where @code{nil} means +vertical and @code{t} horizontal, and a size in pixels. If this window +displays the specified buffer and its size in the indicated direction +equals the size specified by this parameter, then Emacs will try to +preserve the size of this window in the indicated direction. This +parameter is installed and updated by the function +@code{window-preserve-size} (@pxref{Preserving Window Sizes}). + @item @code{quit-restore} This parameter is installed by the buffer display functions (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} |