diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/ChangeLog | 431 | ||||
| -rw-r--r-- | doc/lispref/Makefile.in | 55 | ||||
| -rw-r--r-- | doc/lispref/commands.texi | 22 | ||||
| -rw-r--r-- | doc/lispref/control.texi | 4 | ||||
| -rw-r--r-- | doc/lispref/display.texi | 494 | ||||
| -rw-r--r-- | doc/lispref/elisp.texi | 5 | ||||
| -rw-r--r-- | doc/lispref/errors.texi | 5 | ||||
| -rw-r--r-- | doc/lispref/eval.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/files.texi | 29 | ||||
| -rw-r--r-- | doc/lispref/frames.texi | 271 | ||||
| -rw-r--r-- | doc/lispref/functions.texi | 88 | ||||
| -rw-r--r-- | doc/lispref/internals.texi | 64 | ||||
| -rw-r--r-- | doc/lispref/keymaps.texi | 29 | ||||
| -rw-r--r-- | doc/lispref/lists.texi | 139 | ||||
| -rw-r--r-- | doc/lispref/minibuf.texi | 71 | ||||
| -rw-r--r-- | doc/lispref/nonascii.texi | 26 | ||||
| -rw-r--r-- | doc/lispref/objects.texi | 3 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 162 | ||||
| -rw-r--r-- | doc/lispref/positions.texi | 16 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 12 | ||||
| -rw-r--r-- | doc/lispref/sequences.texi | 518 | ||||
| -rw-r--r-- | doc/lispref/streams.texi | 9 | ||||
| -rw-r--r-- | doc/lispref/strings.texi | 97 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 165 | ||||
| -rw-r--r-- | doc/lispref/windows.texi | 217 |
25 files changed, 2327 insertions, 612 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 83aaf6e8a3d..bb4f1835868 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,10 +1,26 @@ -2014-12-24 Glenn Morris <rgm@gnu.org> +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-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-23 Eli Zaretskii <eliz@gnu.org> +2014-12-27 Eli Zaretskii <eliz@gnu.org> * windows.texi (Recombining Windows): Index subject of sections. @@ -105,44 +121,194 @@ * 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). + * 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-11 Eli Zaretskii <eliz@gnu.org> +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-11-19 Paul Eggert <eggert@cs.ucla.edu> +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> - * Version 24.4 released. + * 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-09 Glenn Morris <rgm@gnu.org> +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-08 Eli Zaretskii <eliz@gnu.org> +2014-10-09 Eli Zaretskii <eliz@gnu.org> * frames.texi (Multiple Terminals): Improve the description of X display names. Add index entries. @@ -155,6 +321,22 @@ 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. @@ -173,45 +355,141 @@ 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. + 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> -2014-09-04 Stefan Monnier <monnier@iro.umontreal.ca> + 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-08-19 Eli Zaretskii <eliz@gnu.org> +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-07-08 Stefan Monnier <monnier@iro.umontreal.ca> +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-06-29 Glenn Morris <rgm@gnu.org> +2014-07-03 Glenn Morris <rgm@gnu.org> * help.texi (Help Functions): "Online" help doesn't mean what it used to any more. -2014-06-26 Glenn Morris <rgm@gnu.org> +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-14 Eli Zaretskii <eliz@gnu.org> +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. @@ -220,7 +498,7 @@ * numbers.texi (Comparison of Numbers): Copyedits. -2014-06-06 Glenn Morris <rgm@gnu.org> +2014-06-08 Glenn Morris <rgm@gnu.org> * display.texi (Window Systems): Remove window-setup-hook. * os.texi (Startup Summary, Init File): @@ -230,11 +508,14 @@ * display.texi (Overlay Properties): Update re priority. (Bug#17234) -2014-06-05 Glenn Morris <rgm@gnu.org> - * package.texi (Package Archives): Mention signing packages. -2014-05-27 Glenn Morris <rgm@gnu.org> +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. @@ -242,53 +523,117 @@ * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. * functions.texi (Advising Functions): Standardize menu case. -2014-05-17 Eli Zaretskii <eliz@gnu.org> +2014-05-26 Eli Zaretskii <eliz@gnu.org> * display.texi (Invisible Text): Clarify the description of line-move-ignore-invisible. (Bug#17511) -2014-05-07 Paul Eggert <eggert@cs.ucla.edu> +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-29 Stefan Monnier <monnier@iro.umontreal.ca> +2014-04-30 Stefan Monnier <monnier@iro.umontreal.ca> * processes.texi (Filter Functions, Sentinels): Advertise add-function. -2014-04-24 Eli Zaretskii <eliz@gnu.org> +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-21 Eli Zaretskii <eliz@gnu.org> +2014-04-22 Eli Zaretskii <eliz@gnu.org> * text.texi (Registers): Document register-read-with-preview. * internals.texi (Building Emacs): Improve indexing. -2014-04-15 Stefan Monnier <monnier@iro.umontreal.ca> +2014-04-17 Daniel Colascione <dancol@dancol.org> - * display.texi (Overlay Properties): Reword the doc of `priority'. - (Finding Overlays): Document new arg of `overlays-at'. + * frames.texi (Terminal Parameters): Document new + tty-mode-set-strings and tty-mode-reset-strings terminal + parameters. -2014-04-05 Glenn Morris <rgm@gnu.org> +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> - * os.texi (Recording Input): Dribble files may contain passwords. + * 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> -2014-04-04 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-25 Eli Zaretskii <eliz@gnu.org> +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-24 Barry O'Reilly <gundaetiapo@gmail.com> +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 @@ -296,8 +641,18 @@ * 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> @@ -305,7 +660,7 @@ * functions.texi (Core Advising Primitives): Fix cross-reference in last change. -2014-03-21 Stefan Monnier <monnier@iro.umontreal.ca> +2014-03-22 Stefan Monnier <monnier@iro.umontreal.ca> * functions.texi (Advising Functions): Explain a bit more how arguments work. @@ -13342,7 +13697,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> diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index c120d123c45..ab9abeff80c 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -47,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@ @@ -60,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 @@ -123,36 +131,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) $< + +elisp.ps: elisp.dvi + $(DVIPS) -o $@ $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## [12] stuff is from two-volume.make. mostlyclean: @@ -168,9 +176,12 @@ 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] + rm -f \ + $(buildinfodir)/elisp.info \ + $(buildinfodir)/elisp.info-[1-9] \ + $(buildinfodir)/elisp.info-[1-9][0-9] -maintainer-clean: distclean infoclean +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 45654cf5e3f..c2b7038e2ec 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -122,16 +122,19 @@ 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. This causes the -byte compiler to warn if the command is called from Lisp. 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. ``use @dots{} instead.''); @code{t}; -any other symbol, which should be an alternative function to use in -Lisp code. +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. ``use @dots{} 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}. @@ -1392,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 diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 9511f682bc8..1e9f3461d0f 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -372,6 +372,10 @@ More specifically, a Q-pattern can take the following forms: @item (@var{qpattern1} . @var{qpattern2}) This pattern matches any cons cell whose @code{car} matches @var{qpattern1} and whose @code{cdr} matches @var{pattern2}. +@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} diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 5d3202e67ef..14a98f32ffb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -23,7 +23,7 @@ that Emacs presents to the user. * 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. @@ -87,7 +87,10 @@ 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 if input is pending. +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. 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,6 +98,28 @@ 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). +@end defvar + @defvar pre-redisplay-function A function run just before redisplay. It is called with one argument, the set of windows to redisplay. @@ -1169,12 +1194,6 @@ 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. -Like @code{with-output-to-temp-buffer} it neither makes the buffer -specified by @var{buffer-or-name} current when executing @var{body}. -@findex with-current-buffer-window -The otherwise identical macro @code{with-current-buffer-window} can be -used to execute @var{body} with that buffer current. - 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 @@ -1182,14 +1201,14 @@ 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{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. +@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 @@ -1198,6 +1217,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 @@ -3348,9 +3417,9 @@ The script that the font must support (a symbol). @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})} @@ -3449,6 +3518,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 @@ -3865,102 +4052,164 @@ 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 - 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-width &optional Lisp_Object &optional frame +This function returns the width of vertical 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}. +@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 -@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. +You can override the frame specific settings for individual windows by +using the following function: -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. +@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}. + +@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. -@var{horizontal-type} is not actually meaningful. +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 @defun window-scroll-bar-width &optional window This function returns the width in pixels of @var{window}'s vertical -scrollbar. @var{window} must be a live window, and defaults to the -selected window. +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. -@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. -@end defopt +You can control the appearance of scroll bars for a particular buffer by +setting the following variables which automatically become buffer-local +when set. -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun +@defvar 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, 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. +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 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 + +@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 @@ -6553,10 +6802,9 @@ positions do not increase monotonically with string or buffer 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 currently provides -a ``Non-isolate Bidirectionality'' class implementation of the -@acronym{UBA}: it does not yet support the isolate directional -formatting characters introduced with Unicode Standard v6.3.0. +(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full +Bidirectionality'' class implementation of the @acronym{UBA}, +consistent with the requirements of the Unicode Standard v7.0. @defvar bidi-display-reordering If the value of this buffer-local variable is non-@code{nil} (the @@ -6741,3 +6989,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/elisp.texi b/doc/lispref/elisp.texi index 973ee6f930c..f6e7729e646 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 @@ -1006,6 +1006,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 @@ -1343,7 +1344,7 @@ Emacs Display * 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. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index e00496e3478..dba8d219774 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -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 05250233b00..6ffc7db8abf 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -805,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 895ae426a5f..55da631a3f7 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -716,15 +716,15 @@ 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 @defopt create-lockfiles @@ -1697,6 +1697,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 @@ -2014,6 +2024,11 @@ 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 @@ -2601,6 +2616,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 diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index df8efee6e0c..c1da337c6cc 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -712,13 +712,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{Size and Position}), 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{Size and Position}), in +characters. @vindex user-size, a frame parameter @item user-size @@ -742,9 +742,9 @@ with the mouse, while the latter really covers the whole screen and does not allow resizing by mouse dragging. With some window managers you may have to customize the variable -@code{frame-resize-pixelwise} to a non-@code{nil} value in order to make -a frame appear ``maximized'' or ``fullscreen''. - +@code{frame-resize-pixelwise} (@pxref{Size and Position}) to a +non-@code{nil} value in order to make a frame appear ``maximized'' or +``fullscreen''. @end table @node Layout Parameters @@ -770,19 +770,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 @@ -796,14 +798,6 @@ 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 @@ -1147,65 +1141,137 @@ equivalent to the @code{:background} attribute of the @code{scroll-bar} face. @end table + @node Size and Position -@subsection Frame 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. +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}.) +Most of the functions described below use a @var{frame} argument which +has to specify a live frame. If omitted or @code{nil}, it specifies the +selected frame, 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. +normally count from the top left corner of the screen to the top left +corner of the rectangle allotted to the frame by the window manager. -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. +Negative parameter values position the bottom edge of that rectangle up +from the bottom edge of the screen, or the right rectangle 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 +@cindex frame default font +@cindex default font of a frame +Each frame has a @dfn{default font} which specifies the canonical height +and width of a character on that frame. The default font is used when +retrieving or changing the size of a frame in terms of columns or lines. +It is also used when resizing (@pxref{Window Sizes}) or splitting +(@pxref{Splitting Windows}) windows. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the canonical 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 below 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 +graphical frames. +@end deffn + +@cindex frame display area +@cindex display area of a frame +The @dfn{display area} of a frame is a rectangular area within the area +allotted to the frame by the window manager. The display area neither +includes the title bar (@pxref{Frame Titles}) nor any other decorations +provided by the window manager (like an external border used for +resizing frames via mouse dragging). + + The actual height of the display area depends on the window-system +and toolkit in use. With GTK+, the display area does not include any +tool bar or menu bar. With the Motif or Lucid toolkits and with +Windows, the display area 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. On a text terminal, the display area includes the menu +bar. @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. + These functions return the height and width of the display area of +@var{frame}, measured in pixels. For a text terminal, the results are +in characters rather than pixels. +@end defun + +@cindex frame text area +@cindex text area of a frame + The @dfn{text area} of a frame is a concept implicitly used by all +functions that change a frame's height or width. It is a rectangle +located within the display area. Its size is obtained from that of the +display area by subtracting the sizes of any tool or menu bars that are +part of the display area, 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}. + +@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}, 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 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-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. +@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}. 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 pixles is not a multiple of +its default font size, the values returned by this 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 @@ -1231,9 +1297,9 @@ order to make a frame appear truly ``maximized'' or ``fullscreen''. @end defopt @defun set-frame-size frame width height pixelwise -This function sets the size of @var{frame}, measured in characters; -@var{width} and @var{height} specify the new width in columns and the -new height in lines. +This function sets the size of the text area of @var{frame}, measured in +characters; @var{width} and @var{height} specify the new width in +columns and the new height in lines. The optional argument @var{pixelwise} non-@code{nil} means to measure the new width and height in units of pixels instead. Note that if @@ -1243,9 +1309,9 @@ to a multiple of its character size. @end defun @defun set-frame-height frame height &optional pretend pixelwise -This function resizes @var{frame} to a height of @var{height} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. +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 @@ -1265,8 +1331,8 @@ 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 @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in +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 @@ -1276,6 +1342,65 @@ 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. + + 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 a 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 display area of the frame in order to +accommodate the size change. Note that wrapping a menu or tool bar +usually does not resize the frame's display area, hence this will alter +the number of displayed lines. + + Occasionally, such implied resizing of the display area may be +unwanted, for example, when the frame is maximized or made fullscreen +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 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 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 frame), and @code{t} otherwise (which +means the 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 + @c FIXME? Belongs more in Emacs manual than here? @c But, e.g., fit-window-to-buffer is in this manual. If you have a frame that displays only one window, you can fit that @@ -1398,6 +1523,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 diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index d9477d2c0b1..9555c218da5 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1204,13 +1204,13 @@ behavior with: 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 an @emph{advice}. +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 advices. -* Porting old advices:: Adapting code using the old defadvice. +* Advice combinators:: Ways to compose advice. +* Porting old advice:: Adapting code using the old defadvice. @end menu @node Core Advising Primitives @@ -1246,22 +1246,25 @@ identify which function to remove. Typically used when @var{function} is an anonymous function. @item depth -This specifies how to order the advices, in case several advices are present. -By default, the depth is 0. A depth of 100 indicates that this advice should -be kept as deep as possible, whereas a depth of -100 indicates that it -should stay as the outermost advice. When two advices specify the same depth, -the most recently added advice will be outermost. - -For a @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 an @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 very last after all -other advices. An innermost @code{:override} advice will only override the -original function and other advices will apply to it, whereas an outermost -@code{:override} advice will override not only the original function but all -other advices applied to it as well. +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 @@ -1299,7 +1302,7 @@ 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 advice that was added to +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 @@ -1328,7 +1331,7 @@ 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 advices +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 @@ -1362,6 +1365,13 @@ 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} @@ -1370,23 +1380,23 @@ Add the advice @var{function} to the named function @var{symbol}. @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 an advice. +@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 -an advice. +a piece of advice. @end defun @defun advice-mapc function symbol -Call @var{function} for every advice that was added to the named function -@var{symbol}. @var{function} is called with two arguments: the advice function -and its properties. +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 advices +@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 @@ -1498,7 +1508,7 @@ More specifically, the composition of the two functions behaves like: @end table -@node Porting old advices +@node Porting old advice @subsection Adapting code using the old defadvice @cindex old advices, porting @@ -1506,7 +1516,7 @@ 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 advice such as: +An old piece of advice such as: @example (defadvice previous-line (before next-line-at-end @@ -1543,11 +1553,11 @@ whereas the new advice mechanism needs: 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 advice, you needed to @emph{enable} or @emph{disable} -that advice with @code{ad-enable-advice} and @code{ad-disable-advice}. +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. -An around advice such as: +Around advice such as: @example (defadvice foo (around foo-around) @@ -1573,12 +1583,12 @@ 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 a @code{before} advice which relied on this behavior, you'll need -to turn it into a new @code{:around} or @code{:filter-args} advice instead. +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 an old @code{after} advice could modify the returned value by -changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so -when porting such an old @code{after} advice, you'll need to turn it into a new +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 @@ -1752,6 +1762,10 @@ 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} diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index bfc9d491c5e..092ec003fb5 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -14,6 +14,7 @@ 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. @@ -513,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. @@ -524,6 +530,35 @@ 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 @@ -580,15 +615,14 @@ Emacs session. @section C Dialect @cindex C programming language -The C part of Emacs is portable to C89: C99-specific features such as -@samp{<stdbool.h>} and @samp{inline} are not used without a check, +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 C99 features, -such as declarations after statements, are too difficult to provide -substitutes for, so they are avoided entirely. +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 not-too-distant future the base C dialect will -change from C89 to C99, and eventually it will no doubt change to C11. +At some point in the future the base C dialect will no doubt change to C11. @node Writing Emacs Primitives @section Writing Emacs Primitives @@ -1591,6 +1625,8 @@ of @code{intptr_t}). @item 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 @@ -1602,6 +1638,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. @@ -1637,8 +1684,7 @@ 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. In particular, boolean bitfields should be of type +@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. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index d4299520510..91dc5ea464e 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1044,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} @@ -1067,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 @@ -1098,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 @@ -1948,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 diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 2e7b7384ae8..e4383354f6f 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -603,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 @@ -1150,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 diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index cf36953098f..e6d6ad001e5 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -102,8 +102,8 @@ 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. This supports only basic input: -none of the special minibuffer features (history, completion, -password hiding, etc.) are available in batch mode. +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 @@ -1738,7 +1738,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 @@ -1877,11 +1877,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 @@ -2127,9 +2150,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. (Note that in batch mode, the -input is not hidden.) +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 @@ -2197,8 +2221,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 @@ -2239,6 +2263,29 @@ 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 diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index d5fabe71b07..fedf933b2d9 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -520,6 +520,24 @@ 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. Unassigned codepoints, and characters that have no value @@ -574,6 +592,14 @@ This function returns the value of @var{char}'s @var{propname} property. (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 diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 4e8182ccf34..a93f34f573b 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1805,9 +1805,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}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 2188c958032..91bd19036f7 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -443,10 +443,13 @@ 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 @@ -475,7 +478,7 @@ 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: @@ -490,7 +493,14 @@ 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 + +@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 @defvar tty-setup-hook This variable is a normal hook that Emacs runs after initializing a @@ -907,13 +917,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 @@ -1204,37 +1207,34 @@ return value is @code{nil}. 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, + 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-string}, or to other forms using the -@code{decode-time} and @code{format-time-string} functions documented -in the following sections. +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-value} 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-value This function returns the current time and date as a human-readable @@ -1247,8 +1247,8 @@ 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-value}, if given, specifies a time to format, +instead of the current time. @example @group @@ -1270,11 +1270,19 @@ become available. @defun float-time &optional time-value 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. +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 seconds-to-time time-value +This function converts a time value to list-of-integer form. +For example, if @var{time-value} is a number, @code{(time-to-seconds +(seconds-to-time @var{time-value}))} equals the number unless overflow +or rounding errors occur. @end defun @defun current-time-zone &optional time-value @@ -1293,8 +1301,8 @@ 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-value}, if given, specifies a time value to +analyze instead of the current time. @end defun The current time zone is determined by the @env{TZ} environment @@ -1308,15 +1316,15 @@ time zone. @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 @@ -1324,9 +1332,9 @@ 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-value 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-value}, it decodes the current time. The return value is a list of nine elements, as follows: @example @@ -1365,8 +1373,9 @@ Greenwich. @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 @@ -1413,9 +1422,11 @@ 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-value universal + +This function converts @var{time-value} (or the current time, if +@var{time-value} is omitted) to a string according to +@var{format-string}. The argument @var{format-string} may contain @samp{%}-sequences which say to substitute parts of the time. Here is a table of what the @samp{%}-sequences mean: @@ -1535,12 +1546,6 @@ specified by @code{locale-coding-system} (@pxref{Locales}); after system. @end defun -@defun seconds-to-time seconds -This function converts @var{seconds}, the number of seconds since the -epoch, to a time value and returns that. To convert back, use -@code{float-time} (@pxref{Time of Day}). -@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 @@ -1614,7 +1619,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}). @@ -1641,7 +1646,7 @@ interactively, it prints the duration in the echo area. @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 @@ -1650,26 +1655,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 @@ -1914,8 +1919,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 diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index b8608cc1197..24ff5d8c86b 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -652,9 +652,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 diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 798f2116623..856831d16c6 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1487,7 +1487,7 @@ 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), @@ -1505,7 +1505,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 @@ -2043,6 +2044,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 @@ -2068,6 +2075,7 @@ The connection type: @samp{plain} or @samp{tls}. @end defun + @node Network Servers @section Network Servers @cindex network servers diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index b518bfc6b73..b1e315c7987 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -217,6 +217,491 @@ 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. + +@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-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-p predicate sequence + This function returns the first member of sequence for which @var{predicate} +returns non-@code{nil}. + +@example +@group +(seq-some-p #'numberp ["abc" 1 nil]) +@result{} 1 +@end group +@group +(seq-some-p #'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-p #'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-p 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-p '(symbol1 symbol2) 'symbol1) +@result{} symbol1 +@end group +@group +(seq-contains-p '(symbol1 symbol2) 'symbol3) +@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 + +@defmac seq-doseq (var sequence [result]) 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 + @node Arrays @section Arrays @cindex array @@ -699,7 +1184,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,6 +1193,11 @@ 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. @@ -761,9 +1251,29 @@ or @code{nil}, and @var{i} is an index into @code{a}. Return the number of elements that are @code{t} in bool vector @var{a}. @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. + 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)) diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 1d549ae8916..b12adcf3dcf 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -615,10 +615,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 diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 0fd7fd1ef3f..026c7a77df2 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -465,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} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "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 "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!!) @@ -523,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} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "enu_USA.1252" on MS-Windows +systems. The @var{locale} "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 "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 diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 27ea8bcbd91..379fb295654 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -220,6 +220,12 @@ 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 filters the buffer text between @var{start} and @var{end} using a function specified by the variable @@ -3248,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 @@ -4123,8 +4134,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 @@ -4327,7 +4339,7 @@ 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 @@ -4336,6 +4348,9 @@ 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 @@ -4349,16 +4364,17 @@ 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 @@ -4371,12 +4387,137 @@ buffer. The argument @var{dom} should be a list as generated by @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. + +@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 diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index aa6ec2c9943..a172a4a4d87 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -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 @@ -394,13 +395,14 @@ internal window). The @var{edges} element is a list @code{(@var{left} @group ____________________________________________ |______________ Header Line ______________|RD| ^ - ^ |LS|LF|LM| |RM|RF|RS| | | + ^ |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 ------------> @@ -414,15 +416,15 @@ Height | | | | | | | | | Height At the center of the window is the @dfn{text area}, or @dfn{body}, 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 margins, denoted by LM and RM in -the schematic (@pxref{Display Margins}); the left and right fringes, -denoted by LF and RF (@pxref{Fringes}); the left or right 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 +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 is the mode line -(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window -Dividers}). +(@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 @@ -439,11 +441,8 @@ displayed within it. @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 mode line and the bottom divider -(if any). Note that the height of a frame is not the same as the height -of its root window (@pxref{Windows and Frames}), since a frame may also -contain an echo area, a menu bar, and a tool bar (@pxref{Size and -Position}). +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 @@ -457,8 +456,8 @@ 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 this window is -vertically combined and has a right sibling, the topmost row of that +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}) @@ -490,11 +489,10 @@ 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 right sibling, the leftmost column of +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}. +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-size &optional window horizontal round @@ -517,9 +515,10 @@ window in units of pixels. 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 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. +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 @@ -542,10 +541,12 @@ the screen areas spanned by its children. 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 @@ -559,7 +560,8 @@ that of the root window on that frame. If @var{window} is omitted or @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 or a bottom divider. +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 @@ -646,7 +648,8 @@ 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 and a bottom divider, if present. +and header line, a horizontal scroll bar and a bottom divider, if +present. @end defopt @defopt window-min-width @@ -655,22 +658,6 @@ 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 -@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. - -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 - 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 @@ -685,10 +672,11 @@ 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 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. +@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 @@ -740,11 +728,11 @@ Normally, the variables @code{window-min-height} and (@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, -a mode line 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. +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. @@ -814,7 +802,7 @@ option is @code{nil}. The default value is @code{nil}. 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 max-width min-width +@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 @@ -842,6 +830,10 @@ defaults to the width of @var{window}'s frame. The optional argument specified in columns and include fringes, margins and scrollbars, if any. +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 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} (@pxref{Size and @@ -915,6 +907,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 @@ -1075,6 +1159,7 @@ point was previously on. Note that this only affects function. @end defopt + @node Deleting Windows @section Deleting Windows @cindex deleting windows @@ -2232,6 +2317,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}). @@ -3648,7 +3740,7 @@ This function returns the top pixel edge of window @var{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 @@ -3724,13 +3816,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 @@ -3899,6 +3991,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} |