From 6e408ba539112b1d7a5fd2e1558936e440e82af8 Mon Sep 17 00:00:00 2001 From: Juri Linkov Date: Wed, 8 Jun 2005 03:18:35 +0000 Subject: (Standard Faces): Add `shadow' face. --- lispref/display.texi | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lispref') diff --git a/lispref/display.texi b/lispref/display.texi index 7b4db373f63..890c636b2f5 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -1775,6 +1775,11 @@ This face forces use of a particular fixed-width font. This face forces use of a particular variable-width font. It's reasonable to customize this to use a different variable-width font, if you like, but you should not make it a fixed-width font. + +@item shadow +@kindex shadow @r{(face name)} +This face is used for making the text less noticeable than the +surrounding ordinary text. @end table @defvar show-trailing-whitespace -- cgit v1.2.1 From ecc8893aa3cd26a2d1a601b605ab59e74ffb0eac Mon Sep 17 00:00:00 2001 From: Juri Linkov Date: Wed, 8 Jun 2005 03:21:08 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 6077deea9bb..1536f0a2d93 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2005-06-08 Juri Linkov + + * display.texi (Standard Faces): Add `shadow' face. + 2005-05-29 Luc Teirlinck * modes.texi (Major Mode Conventions): A derived mode only needs -- cgit v1.2.1 From 03de4399116421aa6d96ee93f4ace948304339da Mon Sep 17 00:00:00 2001 From: Richard M. Stallman Date: Wed, 8 Jun 2005 15:32:01 +0000 Subject: (Mode Line Data): Minor cleanup. (Customizing Keywords): Node split out of Search-based Fontification. Add example of using font-lock-add-keywords from a hook. Clarify when MODE should be non-nil, and when nil. --- lispref/modes.texi | 96 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 36 deletions(-) (limited to 'lispref') diff --git a/lispref/modes.texi b/lispref/modes.texi index f8c1ae82a4e..2366fca5b96 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -1650,13 +1650,13 @@ properties specified by @var{props} to the result. The argument @var{value}. (This feature is new as of Emacs 22.1.) @item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies a -conditional. Its meaning depends on the value of @var{symbol}. If the -value is non-@code{nil}, the second element, @var{then}, is processed -recursively as a mode-line element. But if the value of @var{symbol} is -@code{nil}, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode-line element displays nothing if -the value of @var{symbol} is @code{nil}. +A list whose first element is a symbol that is not a keyword specifies +a conditional. Its meaning depends on the value of @var{symbol}. If +@var{symbol} has a non-@code{nil} value, the second element, +@var{then}, is processed recursively as a mode-line element. +Otherwise, the third element, @var{else}, is processed recursively. +You may omit @var{else}; then the mode-line element displays nothing +if the value of @var{symbol} is @code{nil} or void. @item (@var{width} @var{rest}@dots{}) A list whose first element is an integer specifies truncation or @@ -2319,6 +2319,7 @@ Search-based fontification happens second. @menu * Font Lock Basics:: Overview of customizing Font Lock. * Search-based Fontification:: Fontification based on regexps. +* Customizing Keywords:: Customizing search-based fontification. * Other Font Lock Variables:: Additional customization facilities. * Levels of Font Lock:: Each mode can define alternative levels so that the user can select more or less. @@ -2624,19 +2625,27 @@ Non-@code{nil} means that regular expression matching for the sake of @code{font-lock-keywords} should be case-insensitive. @end defvar -You can use @code{font-lock-add-keywords} to add additional +@node Customizing Keywords +@subsection Customizing Search-Based Fontification + + You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and @code{font-lock-remove-keywords} to removes rules. @defun font-lock-add-keywords mode keywords &optional append -This function adds highlighting @var{keywords} for @var{mode}. The -argument @var{keywords} should be a list with the same format as the -variable @code{font-lock-keywords}. @var{mode} should be a symbol, -the major mode command name, such as @code{c-mode}. When Font Lock -mode is turned on in @var{mode}, it adds @var{keywords} to -@code{font-lock-keywords}. @var{mode} can also be @code{nil}; the -highlighting @var{keywords} are immediately added to -@code{font-lock-keywords} in the current buffer in that case. +This function adds highlighting @var{keywords}, for the current buffer +or for major mode @var{mode}. The argument @var{keywords} should be a +list with the same format as the variable @code{font-lock-keywords}. + +If @var{mode} is a symbol which is a major mode command name, such as +@code{c-mode}, the effect is that enabling Font Lock mode in +@var{mode} will add @var{keywords} to @code{font-lock-keywords}. +Calling with a non-@code{nil} value of @var{mode} is correct only in +your @file{~/.emacs} file. + +If @var{mode} is @code{nil}, this function adds @var{keywords} to +@code{font-lock-keywords} in the current buffer. This way of calling +@code{font-lock-add-keywords} is usually used in mode hook functions. By default, @var{keywords} are added at the beginning of @code{font-lock-keywords}. If the optional argument @var{append} is @@ -2645,7 +2654,29 @@ By default, @var{keywords} are added at the beginning of non-@code{nil} value, they are added at the end of @code{font-lock-keywords}. -For example: +Some modes provide specialized support you can use in additional +highlighting patterns. See the variables +@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, +@code{objc-font-lock-extra-types} and +@code{java-font-lock-extra-types}, for example. + +@strong{Warning:} major mode functions must not call +@code{font-lock-add-keywords} under any circumstances, either directly +or indirectly, except through their mode hooks. (Doing so would lead +to incorrect behavior for some minor modes.) They should set up their +rules for search-based fontification by setting +@code{font-lock-keywords}. +@end defun + +@defun font-lock-remove-keywords mode keywords +This function removes @var{keywords} from @code{font-lock-keywords} +for the current buffer or for major mode @var{mode}. As in +@code{font-lock-add-keywords}, @var{mode} should be a major mode +command name or @code{nil}. All the caveats and requirments for +@code{font-lock-add-keywords} apply here too. +@end defun + + For example, this code @smallexample (font-lock-add-keywords 'c-mode @@ -2653,30 +2684,23 @@ For example: ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) @end smallexample +@noindent adds two fontification patterns for C mode: one to fontify the word @samp{FIXME}, even in comments, and another to fontify the words @samp{and}, @samp{or} and @samp{not} as keywords. -Some modes have specialized support for additional patterns. See the -variables @code{c-font-lock-extra-types}, -@code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types} -and @code{java-font-lock-extra-types}, for example. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes highlighting @var{keywords} for @var{mode}. As -in @code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. If @code{nil}, the highlighting -@var{keywords} are immediately removed in the current buffer. -@end defun +@noindent +That example affects only C mode proper. To add the same patterns to +C mode @emph{and} all modes derived from it, do this instead: -@strong{Warning:} Only use a non-@code{nil} @var{mode} argument when -you use @code{font-lock-add-keywords} or -@code{font-lock-remove-keywords} in your @file{.emacs} file. When you -use these functions from a Lisp program (such as a minor mode), we -recommend that you use @code{nil} for @var{mode} (and place the call -on a hook) to avoid subtle problems due to the details of the -implementation. +@smallexample +(add-hook 'c-mode-hook + (lambda () + (font-lock-add-keywords nil + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) + ("\\<\\(and\\|or\\|not\\)\\>" . + font-lock-keyword-face))))) +@end smallexample @node Other Font Lock Variables @subsection Other Font Lock Variables -- cgit v1.2.1 From b74f585b6b787349a5a0dda29fe788baa0f3d6c9 Mon Sep 17 00:00:00 2001 From: Richard M. Stallman Date: Wed, 8 Jun 2005 15:33:10 +0000 Subject: (Defining Faces): Explain that face name should not end in `-face'. --- lispref/display.texi | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'lispref') diff --git a/lispref/display.texi b/lispref/display.texi index 890c636b2f5..87520fb4d4f 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -1795,14 +1795,15 @@ end of a line. The way to define a new face is with @code{defface}. This creates a kind of customization item (@pxref{Customization}) which the user can customize using the Customization buffer (@pxref{Easy Customization,,, -emacs, The GNU Emacs Manual}). +emacs, The GNU Emacs Manual}). @defmac defface face spec doc [keyword value]... -This declares @var{face} as a customizable face that defaults according -to @var{spec}. You should not quote the symbol @var{face}. The +This declares @var{face} as a customizable face that defaults +according to @var{spec}. You should not quote the symbol @var{face}, +and it should not end in @samp{-face} (that would be redundant). The argument @var{doc} specifies the face documentation. The keywords you -can use in @code{defface} are the same ones that are meaningful in both -@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). +can use in @code{defface} are the same as in @code{defgroup} and +@code{defcustom} (@pxref{Common Keywords}). When @code{defface} executes, it defines the face according to @var{spec}, then uses any customizations that were read from the -- cgit v1.2.1 From 8135a25a77598b1673852f12bd0cdeeab0790752 Mon Sep 17 00:00:00 2001 From: Richard M. Stallman Date: Wed, 8 Jun 2005 15:34:13 +0000 Subject: (Entire Match Data): Clarify when match-data returns markers and when integers. --- lispref/searching.texi | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) (limited to 'lispref') diff --git a/lispref/searching.texi b/lispref/searching.texi index 1f4a82d3f1f..01d055c4a45 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -1486,12 +1486,13 @@ character of the buffer counts as 1.) write the entire match data, all at once. @defun match-data &optional integers reuse -This function returns a newly constructed list containing all the -information on what text the last search matched. Element zero is the -position of the beginning of the match for the whole expression; element -one is the position of the end of the match for the expression. The -next two elements are the positions of the beginning and end of the -match for the first subexpression, and so on. In general, element +This function returns a list of positions (markers or integers) that +record all the information on what text the last search matched. +Element zero is the position of the beginning of the match for the +whole expression; element one is the position of the end of the match +for the expression. The next two elements are the positions of the +beginning and end of the match for the first subexpression, and so on. +In general, element @ifnottex number 2@var{n} @end ifnottex @@ -1508,15 +1509,13 @@ number {\mathsurround=0pt $2n+1$} @end tex corresponds to @code{(match-end @var{n})}. -All the elements are markers or @code{nil} if matching was done on a -buffer and all are integers or @code{nil} if matching was done on a -string with @code{string-match}. If @var{integers} is -non-@code{nil}, then the elements are integers or @code{nil}, even if -matching was done on a buffer. In that case, the buffer itself is -appended as an additional element at the end of the list -to facilitate complete restoration of the match data. Also, -@code{match-beginning} and -@code{match-end} always return integers or @code{nil}. +Normally all the elements are markers or @code{nil}, but if +@var{integers} is non-@code{nil}, that means to use integers instead +of markers. (In that case, the buffer itself is appended as an +additional element at the end of the list, to facilitate complete +restoration of the match data.) If the last match was done on a +string with @code{string-match}, then integers are always used, +since markers can't point into a string. If @var{reuse} is non-@code{nil}, it should be a list. In that case, @code{match-data} stores the match data in @var{reuse}. That is, @@ -1524,8 +1523,8 @@ If @var{reuse} is non-@code{nil}, it should be a list. In that case, have the right length. If it is not long enough to contain the match data, it is extended. If it is too long, the length of @var{reuse} stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to avoid producing too -much garbage, that would later have to be collected. +@code{nil}. The purpose of this feature is to reduce the need for +garbage collection. As always, there must be no possibility of intervening searches between the call to a search function and the call to @code{match-data} that is -- cgit v1.2.1 From 995987378d97aed8094f27262f37aefcf6b7f2cc Mon Sep 17 00:00:00 2001 From: Richard M. Stallman Date: Wed, 8 Jun 2005 15:55:18 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 1536f0a2d93..6eb1c7be5e1 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,23 @@ +2005-06-08 Richard M. Stallman + + * searching.texi (Entire Match Data): Clarify when match-data + returns markers and when integers. + + * display.texi (Defining Faces): Explain that face name should not + end in `-face'. + + * modes.texi (Mode Line Data): Minor cleanup. + (Customizing Keywords): Node split out of Search-based Fontification. + Add example of using font-lock-add-keywords from a hook. + Clarify when MODE should be non-nil, and when nil. + +2005-06-06 Richard M. Stallman + + * modes.texi (Mode Line Data): Explain what happens when the car + of a list is a void symbol. + (Search-based Fontification): Explain MODE arg to + font-lock-add-keywords and warn about calls from major modes. + 2005-06-08 Juri Linkov * display.texi (Standard Faces): Add `shadow' face. -- cgit v1.2.1 From 4e370af25a24a401f5f5577da13078c318fc96ad Mon Sep 17 00:00:00 2001 From: Kim F. Storm Date: Wed, 8 Jun 2005 23:03:29 +0000 Subject: (Entire Match Data): Explain new `reseat' argument to match-data and set-match-data. --- lispref/searching.texi | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) (limited to 'lispref') diff --git a/lispref/searching.texi b/lispref/searching.texi index 01d055c4a45..15037068dd2 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -1485,7 +1485,7 @@ character of the buffer counts as 1.) The functions @code{match-data} and @code{set-match-data} read or write the entire match data, all at once. -@defun match-data &optional integers reuse +@defun match-data &optional integers reuse reseat This function returns a list of positions (markers or integers) that record all the information on what text the last search matched. Element zero is the position of the beginning of the match for the @@ -1526,6 +1526,14 @@ stays the same, but the elements that were not used are set to @code{nil}. The purpose of this feature is to reduce the need for garbage collection. +If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list +are reseated to point to nowhere, and if the value is @code{evaporate}, +the markers are put back on the free list. + +@strong{Warning:} When @code{evaporate} is specified for @var{reseat}, +no other references to the markers on the @var{reuse} list; otherwise, +Emacs may crash during the next garbage collection. + As always, there must be no possibility of intervening searches between the call to a search function and the call to @code{match-data} that is intended to access the match data for that search. @@ -1541,7 +1549,7 @@ intended to access the match data for that search. @end example @end defun -@defun set-match-data match-list +@defun set-match-data match-list &optional reseat This function sets the match data from the elements of @var{match-list}, which should be a list that was the value of a previous call to @code{match-data}. (More precisely, anything that has the same format @@ -1550,6 +1558,14 @@ will work.) If @var{match-list} refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way. +If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list +are reseated to point to nowhere, and if the value is @code{evaporate}, +the markers are put back on the free list. + +@strong{Warning:} When @code{evaporate} is specified for @var{reseat}, +no other references to the markers on the @var{match-list} list; otherwise, +Emacs may crash during the next garbage collection. + @findex store-match-data @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. @end defun -- cgit v1.2.1 From b7aae902ed6d45976a249e44e296df9a97737c16 Mon Sep 17 00:00:00 2001 From: Kim F. Storm Date: Wed, 8 Jun 2005 23:04:27 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 6eb1c7be5e1..6742080bd03 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,8 @@ +2005-06-09 Kim F. Storm + + * searching.texi (Entire Match Data): Explain new `reseat' argument to + match-data and set-match-data. + 2005-06-08 Richard M. Stallman * searching.texi (Entire Match Data): Clarify when match-data -- cgit v1.2.1 From 342c350fb7ae8f950e857555adbdf4a1af029cce Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Fri, 10 Jun 2005 08:47:07 +0000 Subject: Remove eol whitespace; nfc. --- lispref/Makefile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lispref') diff --git a/lispref/Makefile.in b/lispref/Makefile.in index 2fab86ab876..f2e5e46874f 100644 --- a/lispref/Makefile.in +++ b/lispref/Makefile.in @@ -124,7 +124,7 @@ distclean: clean maintainer-clean: clean rm -f elisp.dvi elisp.oaux - cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9] + cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9] dist: $(infodir)/elisp elisp.dvi -rm -rf temp -- cgit v1.2.1 From ccf9222ca4ffc2d23d892c4d2f8f3c6b7c9d3d87 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Fri, 10 Jun 2005 10:03:29 +0000 Subject: Use EMACSVER to refer to the current version of Emacs. (Top): Give it a title. Correct version number. Give the detailed node listing a more prominent header. --- lispref/elisp.texi | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'lispref') diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 7a19f8a47da..1e816487e14 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -4,8 +4,10 @@ @settitle GNU Emacs Lisp Reference Manual @c %**end of header -@c Versino of the manual. -@set VERSION 2.9 +@c Version of the manual and of Emacs. +@c Please remember to update the edition number in README as well. +@set VERSION 2.9 +@set EMACSVER 22.0.50 @dircategory Emacs @direntry @@ -26,9 +28,7 @@ @ifnottex This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to Emacs version 22.1. -@c Please REMEMBER to update edition number in *four* places in this file -@c and also in *one* place in intro.texi and *one* in README. +Reference Manual, corresponding to Emacs version @value{EMACSVER}. Published by the Free Software Foundation 59 Temple Place, Suite 330 @@ -52,9 +52,7 @@ Software Foundation raise funds for GNU development.'' @titlepage @title GNU Emacs Lisp Reference Manual -@subtitle For Emacs Version 22 -@c The edition number appears in several places in this file -@c and also in the file intro.texi. +@subtitle For Emacs Version @value{EMACSVER} @subtitle Revision @value{VERSION}, January 2002 @author by Bil Lewis, Dan LaLiberte, Richard Stallman @@ -66,7 +64,7 @@ Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* @sp 2 Edition @value{VERSION} @* -Revised for Emacs Version 22.1,@* +Revised for Emacs Version @value{EMACSVER},@* January 2002.@* @sp 2 ISBN 1-882114-73-6 @@ -92,11 +90,12 @@ Cover art by Etienne Suvasa. @end titlepage @page +@ifnottex @node Top, Introduction, (dir), (dir) +@top Emacs Lisp -@ifnottex This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version 22.1. +Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. @end ifnottex @menu @@ -156,7 +155,7 @@ Reference Manual, corresponding to GNU Emacs version 22.1. Appendices -* Antinews:: Info for users downgrading to Emacs 20. +* Antinews:: Info for users downgrading to Emacs 21. * GNU Free Documentation License:: The license for this documentation * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. @@ -171,9 +170,10 @@ Appendices * Index:: Index including concepts, functions, variables, and other terms. -* New Symbols:: New functions and variables in Emacs 22. +* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. - --- The Detailed Node Listing --- +Detailed Node Listing +--------------------- Here are other nodes that are inferiors of those already listed, mentioned here so you can get to them in one step: -- cgit v1.2.1 From 4435c8d403d17192fe5f4f86225b81aece6dcb44 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Fri, 10 Jun 2005 10:05:22 +0000 Subject: Don't set VERSION here a second time. Mention Emacs' version too. --- lispref/intro.texi | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'lispref') diff --git a/lispref/intro.texi b/lispref/intro.texi index 999db7ad722..bb264c81c46 100644 --- a/lispref/intro.texi +++ b/lispref/intro.texi @@ -5,9 +5,6 @@ @c See the file elisp.texi for copying conditions. @setfilename ../info/intro -@c Versino of the manual. -@set VERSION 2.9 - @node Introduction, Lisp Data Types, Top, Top @comment node-name, next, previous, up @chapter Introduction @@ -38,7 +35,8 @@ Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing. - This is edition @value{VERSION}. + This is edition @value{VERSION} of the GNU Emacs Lisp Reference +Manual, corresponding to Emacs version @value{EMACSVER}. @menu * Caveats:: Flaws and a request for help. -- cgit v1.2.1 From 0b3a296941e9e5759d36f9bd3cc9e10eb055fd34 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Fri, 10 Jun 2005 10:11:22 +0000 Subject: (Antinews): Use EMACSVER to refer to the current version of Emacs. --- lispref/anti.texi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'lispref') diff --git a/lispref/anti.texi b/lispref/anti.texi index 458409f2603..46375f3f157 100644 --- a/lispref/anti.texi +++ b/lispref/anti.texi @@ -10,7 +10,8 @@ For those users who live backwards in time, here is information about downgrading to Emacs version 21.4. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs 22 features. +simplicity that results from the absence of many Emacs @value{EMACSVER} +features. @section Old Lisp Features in Emacs 21 -- cgit v1.2.1 From 257914aaabe89bb14c22b9430a21fbc8b5b05657 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Fri, 10 Jun 2005 11:00:43 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 6742080bd03..b476dc4efde 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,14 @@ +2005-06-10 Lute Kamstra + + * elisp.texi: Use EMACSVER to refer to the current version of + Emacs. + (Top): Give it a title. Correct version number. Give the + detailed node listing a more prominent header. + * intro.texi: Don't set VERSION here a second time. Mention + Emacs' version too. + * anti.texi (Antinews): Use EMACSVER to refer to the current + version of Emacs. + 2005-06-09 Kim F. Storm * searching.texi (Entire Match Data): Explain new `reseat' argument to -- cgit v1.2.1 From 9bd4c3ad3e747a187315a820651fa9c20e7ce552 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Fri, 10 Jun 2005 15:43:48 +0000 Subject: (Error Debugging): Minor rewording. (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' is optional. --- lispref/ChangeLog | 6 ++++++ lispref/debugging.texi | 8 ++++---- 2 files changed, 10 insertions(+), 4 deletions(-) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index b476dc4efde..e2694edd093 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,9 @@ +2005-06-10 Luc Teirlinck + + * debugging.texi (Error Debugging): Minor rewording. + (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' + is optional. + 2005-06-10 Lute Kamstra * elisp.texi: Use EMACSVER to refer to the current version of diff --git a/lispref/debugging.texi b/lispref/debugging.texi index 07dfe18f283..ff9e90f7747 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -118,8 +118,8 @@ the error. The easiest way is usually to set @end defopt @defopt eval-expression-debug-on-error -If you set this variable to a non-@code{nil} value, then -@code{debug-on-error} will be set to @code{t} when evaluating with the +If this variable has a non-@code{nil} value, then +@code{debug-on-error} is set to @code{t} when evaluating with the command @code{eval-expression}. If @code{eval-expression-debug-on-error} is @code{nil}, then the value of @code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating @@ -267,11 +267,11 @@ Debugger entered--entering a function: @end example @end deffn -@deffn Command cancel-debug-on-entry function-name +@deffn Command cancel-debug-on-entry &optional function-name This function undoes the effect of @code{debug-on-entry} on @var{function-name}. When called interactively, it prompts for @var{function-name} in the minibuffer. If @var{function-name} is -@code{nil} or the empty string, it cancels break-on-entry for all +omitted, @code{nil}, or the empty string, it cancels break-on-entry for all functions. Calling @code{cancel-debug-on-entry} does nothing to a function which is -- cgit v1.2.1 From b5305167d412a51265145d230c3b495b5d7c02bd Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Fri, 10 Jun 2005 22:20:25 +0000 Subject: (Parsing Expressions): Document syntax-ppss. --- lispref/ChangeLog | 52 +++++++++++++++++++++++++++------------------------- lispref/syntax.texi | 16 +++++++++++++--- 2 files changed, 40 insertions(+), 28 deletions(-) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index e2694edd093..6696bf6b0b9 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2005-06-10 Stefan Monnier + + * syntax.texi (Parsing Expressions): Document syntax-ppss. + 2005-06-10 Luc Teirlinck * debugging.texi (Error Debugging): Minor rewording. @@ -6,12 +10,11 @@ 2005-06-10 Lute Kamstra - * elisp.texi: Use EMACSVER to refer to the current version of - Emacs. + * elisp.texi: Use EMACSVER to refer to the current version of Emacs. (Top): Give it a title. Correct version number. Give the detailed node listing a more prominent header. - * intro.texi: Don't set VERSION here a second time. Mention - Emacs' version too. + * intro.texi: Don't set VERSION here a second time. + Mention Emacs's version too. * anti.texi (Antinews): Use EMACSVER to refer to the current version of Emacs. @@ -95,8 +98,8 @@ 2005-05-21 Eli Zaretskii - * files.texi (Locating Files): New subsection. Describe - locate-file and executable-find. + * files.texi (Locating Files): New subsection. + Describe locate-file and executable-find. 2005-05-21 Kevin Ryde @@ -111,8 +114,8 @@ (Major Mode Conventions): Refer to `Auto Major Mode' in more appropriate place. (Derived Modes): Small clarifications. - (Minor Mode Conventions, Keymaps and Minor Modes): Replace - references to nodes with references to anchors. + (Minor Mode Conventions, Keymaps and Minor Modes): + Replace references to nodes with references to anchors. (Mode Line Data): Warn that `(:eval FORM)' should not load any files. Clarify description of lists whose first element is an integer. (Mode Line Variables): Add anchor. @@ -264,10 +267,10 @@ (Font Lock Basics): Say that font-lock-defaults is buffer-local when set and that some parts are optional. Add cross references. (Search-based Fontification): Say how to specify font-lock-keywords. - Add cross references. Add font-lock-multiline to index. Move - font-lock-keywords-case-fold-search here from node "Other Font + Add cross references. Add font-lock-multiline to index. + Move font-lock-keywords-case-fold-search here from node "Other Font Lock Variables". Document font-lock-add-keywords and - font-lock-remove-keywords + font-lock-remove-keywords. (Other Font Lock Variables): Move font-lock-keywords-only, font-lock-syntax-table, font-lock-beginning-of-syntax-function, and font-lock-syntactic-face-function to node "Syntactic Font @@ -282,8 +285,8 @@ and font-lock-syntactic-face-function here from node "Other Font Lock Variables". Move font-lock-syntactic-keywords to "Setting Syntax Properties". Add cross references. - (Setting Syntax Properties): New node. Move - font-lock-syntactic-keywords here from "Syntactic Font Lock". + (Setting Syntax Properties): New node. + Move font-lock-syntactic-keywords here from "Syntactic Font Lock". * syntax.texi (Syntax Properties): Add cross reference. * hooks.texi (Standard Hooks): Add Font-Lock hooks. @@ -342,7 +345,7 @@ 2005-04-19 Kevin Ryde - * streams.texi (Output Functions): Fix xref. + * streams.texi (Output Functions): Fix xref. * strings.texi (String Conversion): Fix xref. 2005-04-19 Kim F. Storm @@ -436,8 +439,8 @@ * markers.texi (The Mark): Document temporary Transient Mark mode. - * minibuf.texi (Reading File Names): Document - read-file-name-completion-ignore-case. + * minibuf.texi (Reading File Names): + Document read-file-name-completion-ignore-case. * positions.texi (Screen Lines): Document nil for width argument to compute-motion. @@ -457,11 +460,10 @@ (Managing Overlays): Document remove-overlays. (Standard Faces): Document escape-glyph face. - * minibuf.texi (Reading File Names): Document - read-file-name-function. + * minibuf.texi (Reading File Names): Document read-file-name-function. - * modes.texi (Other Font Lock Variables): Document - font-lock-lines-before. + * modes.texi (Other Font Lock Variables): + Document font-lock-lines-before. * positions.texi (Skipping Characters): skip-chars-forward allows character classes. @@ -515,18 +517,18 @@ (Progress): Clarify. (Invisible Text): Explain that main loop moves point out. (Selective Display): Say "hidden", not "invisible". - (Managing Overlays): Moved up. Describe relation to Undo here. + (Managing Overlays): Move up. Describe relation to Undo here. (Overlay Properties): Clarify intro. (Finding Overlays): Explain return values when nothing found. (Width): truncate-string-to-width has added arg. (Displaying Faces): Clarify and update mode line face handling. (Face Functions): Minor cleanup. - (Conditional Display): Merged into Other Display Specs. + (Conditional Display): Merge into Other Display Specs. (Pixel Specification, Other Display Specs): Minor cleanups. (Images, Image Descriptors): Minor cleanups. (GIF Images): Patents have expired. (Showing Images): Explain default text for insert-image. - (Manipulating Button Types): Merged into Manipulating Buttons. + (Manipulating Button Types): Merge into Manipulating Buttons. (Making Buttons): Explain return values. (Button Buffer Commands): Add xref. (Inverse Video): Update mode-line-inverse-video. @@ -886,8 +888,8 @@ * commands.texi (Misc Events): Describe the help-echo event. * text.texi (Special Properties) : Use `pos' - consistently in description of the help-echo property. Use - @code{nil} instead of @var{nil}. + consistently in description of the help-echo property. + Use @code{nil} instead of @var{nil}. * display.texi (Overlay Properties): Fix the index entry for help-echo overlay property. diff --git a/lispref/syntax.texi b/lispref/syntax.texi index a9df79e9f57..28298ba0f34 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -256,7 +256,7 @@ English text has no comment characters. In Lisp, the semicolon @deffn {Syntax class} @w{inherit} This syntax class does not specify a particular syntax. It says to look in the standard syntax table to find the syntax of this character. The -designator for this syntax code is @samp{@@}. +designator for this syntax class is @samp{@@}. @end deffn @deffn {Syntax class} @w{generic comment delimiter} @@ -385,7 +385,7 @@ nestable. @samp{p} identifies an additional ``prefix character'' for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled -according to their usual syntax codes. +according to their usual syntax classes. The function @code{backward-prefix-chars} moves back over these characters, as well as over characters whose primary syntax class is @@ -566,7 +566,7 @@ have certain syntax classes. @defun skip-syntax-forward syntaxes &optional limit This function moves point forward across characters having syntax -classes mentioned in @var{syntaxes} (a string of syntax code +classes mentioned in @var{syntaxes} (a string of syntax class characters). It stops when it encounters the end of the buffer, or position @var{limit} (if specified), or a character it is not supposed to skip. @@ -730,6 +730,16 @@ This function is most often used to compute indentation for languages that have nested parentheses. @end defun +@defun syntax-ppss &optional pos +This function returns the state that the parser would have at position +@var{pos}, if it were started with a default start state at the +beginning of the buffer. Thus, it is equivalent to +@code(parse-partial-sexp (point-min) @var{pos}), except that +@code{syntax-ppss} uses a cache to speed up the computation. Also, +the 2nd value (previous complete subexpression) and 6th value (minimum +parenthesis depth) of the returned state are not meaningful. +@end defun + @defun scan-lists from count depth This function scans forward @var{count} balanced parenthetical groupings from position @var{from}. It returns the position where the scan stops. -- cgit v1.2.1 From 4b53b8d7eed13c7b1487c8afbc1246cd590e317d Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Fri, 10 Jun 2005 22:59:17 +0000 Subject: (Parsing Expressions): Fix Texinfo error. --- lispref/ChangeLog | 4 ++++ lispref/syntax.texi | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 6696bf6b0b9..8ae4ff7dedb 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2005-06-10 Luc Teirlinck + + * syntax.texi (Parsing Exprssions): Fix Texinfo error. + 2005-06-10 Stefan Monnier * syntax.texi (Parsing Expressions): Document syntax-ppss. diff --git a/lispref/syntax.texi b/lispref/syntax.texi index 28298ba0f34..8efda55b18d 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -734,7 +734,7 @@ that have nested parentheses. This function returns the state that the parser would have at position @var{pos}, if it were started with a default start state at the beginning of the buffer. Thus, it is equivalent to -@code(parse-partial-sexp (point-min) @var{pos}), except that +@code{(parse-partial-sexp (point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache to speed up the computation. Also, the 2nd value (previous complete subexpression) and 6th value (minimum parenthesis depth) of the returned state are not meaningful. @@ -789,7 +789,7 @@ whitespace by the functions in this section and by @code{forward-sexp}. @end defopt @vindex parse-sexp-lookup-properties -The behaviour of @code{parse-partial-sexp} is also affected by +The behavior of @code{parse-partial-sexp} is also affected by @code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). You can use @code{forward-comment} to move forward or backward over -- cgit v1.2.1 From 0c2cfb962aa5fc48e1a5c2fd4e0d2b44ca747c6a Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 11 Jun 2005 13:53:34 +0000 Subject: (Adaptive Fill): Amplify the description of fill-context-prefix. --- lispref/text.texi | 80 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 17 deletions(-) (limited to 'lispref') diff --git a/lispref/text.texi b/lispref/text.texi index 1d4dc0fce8a..1c0fd09322b 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -1667,8 +1667,12 @@ line won't be broken there. @section Adaptive Fill Mode @cindex Adaptive Fill mode - Adaptive Fill mode chooses a fill prefix automatically from the text -in each paragraph being filled. + When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill +prefix automatically from the text in each paragraph being filled +rather than using a predetermined value. During filling, this fill +prefix gets inserted at the start of the second and subsequent lines +of the paragraph as described in @ref{Filling}, and in @ref{Auto +Filling}. @defopt adaptive-fill-mode Adaptive Fill mode is enabled when this variable is non-@code{nil}. @@ -1677,38 +1681,80 @@ It is @code{t} by default. @defun fill-context-prefix from to This function implements the heart of Adaptive Fill mode; it chooses a -fill prefix based on the text between @var{from} and @var{to}. It does -this by looking at the first two lines of the paragraph, based on the -variables described below. +fill prefix based on the text between @var{from} and @var{to}, +typically the start and end of a paragraph. It does this by looking +at the first two lines of the paragraph, based on the variables +described below. @c The optional argument first-line-regexp is not documented @c because it exists for internal purposes and might be eliminated @c in the future. + +Usually, this function returns the fill prefix, a string. However, +before doing this, the function makes a final check (not specially +mentioned in the following) that a line starting with this prefix +wouldn't look like the start of a paragraph. Should this happen, the +function signals the anomaly by returning @code{nil} instead. + +In detail, @code{fill-context-prefix} does this: + +@enumerate +@item +It takes a candidate for the fill prefix from the first line---it +tries first the function in @code{adaptive-fill-function} (if any), +then the regular expression @code{adaptive-fill-regexp} (see below). +The first non-@code{nil} result of these, or the empty string if +they're both @code{nil}, becomes the first line's candidate. +@item +If the paragraph has as yet only one line, the function tests the +validity of the prefix candidate just found. The function then +returns the candidate if it's valid, or a string of spaces otherwise. +(see the description of @code{adaptive-fill-first-line-regexp} below). +@item +When the paragraph already has two lines, the function next looks for +a prefix candidate on the second line, in just the same way it did for +the first line. If it doesn't find one, it returns @code{nil}. +@item +The function now compares the two candidate prefixes heuristically: if +the non-whitespace characters in the line 2 candidate occur in the +same order in the line 1 candidate, the function returns the line 2 +candidate. Otherwise, it returns the largest initial substring which +is common to both candidates (which might be the empty string). +@end enumerate @end defun @defopt adaptive-fill-regexp -This variable holds a regular expression to control Adaptive Fill mode. Adaptive Fill mode matches this regular expression against the text starting after the left margin whitespace (if any) on a line; the characters it matches are that line's candidate for the fill prefix. + +The default value of this variable is +@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}. This +matches a number enclosed in parentheses or followed by a period, +or certain punctuation characters, or any sequence of these +intermingled with whitespace. In particular, it matches a sequence of +whitespace, possibly empty. @end defopt @defopt adaptive-fill-first-line-regexp -In a one-line paragraph, if the candidate fill prefix matches this -regular expression, or if it matches @code{comment-start-skip}, then it -is used---otherwise, spaces amounting to the same width are used -instead. - -However, the fill prefix is never taken from a one-line paragraph -if it would act as a paragraph starter on subsequent lines. +Used only in one-line paragraphs, this regular expression acts as an +additional check of the validity of the one available candidate fill +prefix: the candidate must match this regular expression, or match +@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} +replaces the candidate with a string of spaces ``of the same width'' +as it. + +The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which +matches only a string of whitespace. The effect of this default is to +force the fill prefixes found in one-line paragraphs always to be pure +whitespace. @end defopt @defopt adaptive-fill-function You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is -called when @code{adaptive-fill-regexp} does not match, with point after -the left margin of a line, and it should return the appropriate fill -prefix based on that line. If it returns @code{nil}, that means it sees -no fill prefix in that line. +called with point after the left margin (if any) of a line, and it +must preserve point. It should return either ``that line's'' fill +prefix or @code{nil}, meaning it has failed to determine a prefix. @end defopt @node Auto Filling -- cgit v1.2.1 From 98d1a1cf4c4f14b1d8e17416ddca18c3579e9a9c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 11 Jun 2005 13:54:09 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 8ae4ff7dedb..8e65ee5ac6b 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,8 @@ +2005-06-11 Alan Mackenzie + + * text.texi (Adaptive Fill): Amplify the description of + fill-context-prefix. + 2005-06-10 Luc Teirlinck * syntax.texi (Parsing Exprssions): Fix Texinfo error. -- cgit v1.2.1 From 9edbd0074e6117b4171f9e2289742a9834d6f5a8 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Sat, 11 Jun 2005 23:42:13 +0000 Subject: (Function Debugging): Delete mention of empty string argument to `cancel-debug-on-entry'. Delete inaccurate description of the return value of that command. --- lispref/debugging.texi | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'lispref') diff --git a/lispref/debugging.texi b/lispref/debugging.texi index ff9e90f7747..ae3fbdbb480 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -271,12 +271,9 @@ Debugger entered--entering a function: This function undoes the effect of @code{debug-on-entry} on @var{function-name}. When called interactively, it prompts for @var{function-name} in the minibuffer. If @var{function-name} is -omitted, @code{nil}, or the empty string, it cancels break-on-entry for all -functions. - +omitted or @code{nil}, it cancels break-on-entry for all functions. Calling @code{cancel-debug-on-entry} does nothing to a function which is -not currently set up to break on entry. It always returns -@var{function-name}. +not currently set up to break on entry. @end deffn @node Explicit Debug -- cgit v1.2.1 From 32cc0b00092810d3821cb3c4096d4922342a9444 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Sun, 12 Jun 2005 00:03:20 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 8e65ee5ac6b..be47508ca84 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,9 @@ +2005-06-11 Luc Teirlinck + + * debugging.texi (Function Debugging): Delete mention of empty + string argument to `cancel-debug-on-entry'. Delete inaccurate + description of the return value of that command. + 2005-06-11 Alan Mackenzie * text.texi (Adaptive Fill): Amplify the description of -- cgit v1.2.1 From 9d42ffaa3cb02d03f709a205a99be6231033ee3f Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Sun, 12 Jun 2005 23:46:50 +0000 Subject: (Special Properties): Fix cross reference. --- lispref/ChangeLog | 4 ++++ lispref/text.texi | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index be47508ca84..d7f3b91f3ad 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2005-06-13 Lute Kamstra + + * text.texi (Special Properties): Fix cross reference. + 2005-06-11 Luc Teirlinck * debugging.texi (Function Debugging): Delete mention of empty diff --git a/lispref/text.texi b/lispref/text.texi index 1c0fd09322b..cddeeb8fbde 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -3124,8 +3124,8 @@ that character a non-@code{nil} @var{cursor} text property. @item pointer @kindex pointer @r{(text property)} This specifies a specific pointer shape when the mouse pointer is over -this text or image. See the variable @var{void-area-text-pointer} -for possible pointer shapes. +this text or image. @xref{Pointer Shape}, for possible pointer +shapes. @item line-spacing @kindex line-spacing @r{(text property)} -- cgit v1.2.1 From f99ed2f84b36c6b383b213976561d08b10a4192a Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Mon, 13 Jun 2005 14:21:21 +0000 Subject: (Parsing Expressions): Document aux functions and vars of syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. --- lispref/ChangeLog | 5 +++++ lispref/syntax.texi | 20 ++++++++++++++++++++ 2 files changed, 25 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index d7f3b91f3ad..c24bd01e8aa 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,8 @@ +2005-06-13 Stefan Monnier + + * syntax.texi (Parsing Expressions): Document aux functions and vars of + syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. + 2005-06-13 Lute Kamstra * text.texi (Special Properties): Fix cross reference. diff --git a/lispref/syntax.texi b/lispref/syntax.texi index 8efda55b18d..e8707709fe2 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -740,6 +740,26 @@ the 2nd value (previous complete subexpression) and 6th value (minimum parenthesis depth) of the returned state are not meaningful. @end defun +@defun syntax-ppss-flush-cache beg +This function flushes the cache used by @code{syntax-ppss}, starting at +position @var{beg}. + +When @code{syntax-ppss} is called, it automatically hooks itself +to @code{before-change-functions} to keep its cache consistent. +But this can fail if @code{syntax-ppss} is called while +@code{before-change-functions} is temporarily let-bound, or if the +buffer is modified without obeying the hook, such as when using +@code{inhibit-modification-hooks}. For this reason, it is sometimes +necessary to flush the cache manually. +@end defun + +@defvar syntax-begin-function +If this is non-nil, it should be a function that moves to an earlier +buffer position where the parser state is equivalent to @code{nil}, +i.e., a position outside of any comment, string, or parenthesis. +@code{syntax-ppss} uses it to supplement its cache. +@end defvar + @defun scan-lists from count depth This function scans forward @var{count} balanced parenthetical groupings from position @var{from}. It returns the position where the scan stops. -- cgit v1.2.1 From a5c99dc903381b6d96689a12a340d023b8e216cd Mon Sep 17 00:00:00 2001 From: Kim F. Storm Date: Tue, 14 Jun 2005 11:11:31 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index c24bd01e8aa..7d5e0125a50 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2005-06-14 Kim F. Storm + + * variables.texi (Setting Variables): Add add-to-ordered-list. + 2005-06-13 Stefan Monnier * syntax.texi (Parsing Expressions): Document aux functions and vars of -- cgit v1.2.1 From cf02d3ed214a099fa56b4007d472d69e46411de0 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Tue, 14 Jun 2005 11:36:41 +0000 Subject: (Function Debugging): Primitives can break on entry too. --- lispref/debugging.texi | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'lispref') diff --git a/lispref/debugging.texi b/lispref/debugging.texi index ae3fbdbb480..739dd1fe298 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -210,15 +210,19 @@ called shortly before the problem, step quickly over the call to that function, and then step through its caller. @deffn Command debug-on-entry function-name -This function requests @var{function-name} to invoke the debugger each time -it is called. It works by inserting the form @code{(debug 'debug)} into -the function definition as the first form. - -Any function defined as Lisp code may be set to break on entry, -regardless of whether it is interpreted code or compiled code. If the -function is a command, it will enter the debugger when called from Lisp -and when called interactively (after the reading of the arguments). You -can't debug primitive functions (i.e., those written in C) this way. +This function requests @var{function-name} to invoke the debugger each +time it is called. It works by inserting the form +@code{(implement-debug-on-entry)} into the function definition as the +first form. + +Any function or macro defined as Lisp code may be set to break on +entry, regardless of whether it is interpreted code or compiled code. +If the function is a command, it will enter the debugger when called +from Lisp and when called interactively (after the reading of the +arguments). You can also set debug-on-entry for primitive functions +(i.e., those written in C) this way, but it only takes effect when the +primitive is called from Lisp code. Debug-on-entry is not allowed for +special forms. When @code{debug-on-entry} is called interactively, it prompts for @var{function-name} in the minibuffer. If the function is already set -- cgit v1.2.1 From b59f605b06d8ab6eac60de0744a5ae8c63ec6b40 Mon Sep 17 00:00:00 2001 From: Lute Kamstra Date: Tue, 14 Jun 2005 12:11:54 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 7d5e0125a50..3bf39082407 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,8 @@ +2005-06-14 Lute Kamstra + + * debugging.texi (Function Debugging): Primitives can break on + entry too. + 2005-06-14 Kim F. Storm * variables.texi (Setting Variables): Add add-to-ordered-list. -- cgit v1.2.1 From fe2a99725b49815c39bd873fd7c90f4c36c193b5 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Tue, 14 Jun 2005 23:29:17 +0000 Subject: *** empty log message *** --- lispref/ChangeLog | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 3bf39082407..dccb76c4dae 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,22 @@ +2005-06-14 Luc Teirlinck + + * edebug.texi (Edebug): Update menu. + (Instrumenting): Update xrefs. + (Edebug Execution Modes): Correct xref. + (Jumping): Clarify description of `h' command. + Eliminate redundant @ref. + (Breaks): New node. + (Breakpoints): is now a subsubsection. + (Global Break Condition): Mention `C-x X X'. + (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. + (Trace Buffer): Clarify STRING arg of `edebug-tracing'. + (Edebug Display Update): Correct pxref. + (Edebug and Macros): New node. + (Instrumenting Macro Calls): Is now a subsubsection. + Neither arg of `def-edebug-spec' is evaluated. + (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. + (Specification Examples): Fix typo. + 2005-06-14 Lute Kamstra * debugging.texi (Function Debugging): Primitives can break on -- cgit v1.2.1 From c5f8bf2df4ae7cb5581ee1e0387110e8bfe35749 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Tue, 14 Jun 2005 23:33:21 +0000 Subject: (Edebug): Update menu. (Instrumenting): Update xrefs. (Edebug Execution Modes): Correct xref. (Jumping): Clarify description of `h' command. Eliminate redundant @ref. (Breaks): New node. (Breakpoints): is now a subsubsection. (Global Break Condition): Mention `C-x X X'. (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. (Trace Buffer): Clarify STRING arg of `edebug-tracing'. (Edebug Display Update): Correct pxref. (Edebug and Macros): New node. (Instrumenting Macro Calls): Is now a subsubsection. Neither arg of `def-edebug-spec' is evaluated. (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. (Specification Examples): Fix typo. --- lispref/edebug.texi | 99 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 61 insertions(+), 38 deletions(-) (limited to 'lispref') diff --git a/lispref/edebug.texi b/lispref/edebug.texi index cc42926ecf7..981afbb894c 100644 --- a/lispref/edebug.texi +++ b/lispref/edebug.texi @@ -65,7 +65,7 @@ enable you to use it. * Modes: Edebug Execution Modes. Execution modes, stopping more or less often. * Jumping:: Commands to jump to a specified place. * Misc: Edebug Misc. Miscellaneous commands. -* Breakpoints:: Setting breakpoints to make the program stop. +* Breaks:: Setting breakpoints to make the program stop. * Trapping Errors:: Trapping errors with Edebug. * Views: Edebug Views. Views inside and outside of Edebug. * Eval: Edebug Eval. Evaluating expressions within Edebug. @@ -75,7 +75,7 @@ enable you to use it. * Trace Buffer:: How to produce trace output in a buffer. * Coverage Testing:: How to test evaluation coverage. * The Outside Context:: Data that Edebug saves and restores. -* Instrumenting Macro Calls:: Specifying how to handle macro calls. +* Edebug and Macros:: Specifying how to handle macro calls. * Options: Edebug Options. Option variables for customizing Edebug. @end menu @@ -203,13 +203,13 @@ function. @code{interactive} forms with an expression argument, anonymous lambda expressions, and other defining forms. However, Edebug cannot determine on its own what a user-defined macro will do with the arguments of a -macro call, so you must provide that information; see @ref{Instrumenting -Macro Calls}, for details. +macro call, so you must provide that information; see @ref{Edebug and +Macros}, for details. When Edebug is about to instrument code for the first time in a session, it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}. You can use this to load Edebug specifications -(@pxref{Instrumenting Macro Calls}) associated with a package you are +(@pxref{Edebug and Macros}) associated with a package you are using, but only when you use Edebug. @findex eval-expression @r{(Edebug)} @@ -253,7 +253,7 @@ Step: stop at the next stop point encountered (@code{edebug-step-mode}). @item n Next: stop at the next stop point encountered after an expression (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Edebug Misc}. +@ref{Jumping}. @item t Trace: pause (normally one second) at each Edebug stop point @@ -341,9 +341,8 @@ Run the program until the end of the containing sexp. Step into the function or macro called by the form after point. @end table -The @kbd{h} command proceeds to the stop point near the current location -of point, using a temporary breakpoint. See @ref{Breakpoints}, for more -information about breakpoints. +The @kbd{h} command proceeds to the stop point at or after the current +location of point, using a temporary breakpoint. The @kbd{f} command runs the program forward over one expression. More precisely, it sets a temporary breakpoint at the position that @@ -427,14 +426,23 @@ recursively. Whenever Edebug is active, you can quit to the top level with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can display a backtrace of all the pending evaluations with @kbd{d}. -@node Breakpoints -@subsection Breakpoints +@node Breaks +@subsection Breaks -@cindex breakpoints Edebug's step mode stops execution when the next stop point is reached. There are three other ways to stop Edebug execution once it has started: breakpoints, the global break condition, and source breakpoints. +@menu +* Breakpoints:: Breakpoints at stop points. +* Global Break Condition:: Breaking on an event. +* Source Breakpoints:: Embedding breakpoints in source code. +@end menu + +@node Breakpoints +@subsubsection Breakpoints + +@cindex breakpoints While using Edebug, you can specify @dfn{breakpoints} in the program you are testing: these are places where execution should stop. You can set a breakpoint at any stop point, as defined in @ref{Using Edebug}. For @@ -494,12 +502,6 @@ function, or to the first breakpoint if there are no following breakpoints. This command does not continue execution---it just moves point in the buffer. -@menu -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - - @node Global Break Condition @subsubsection Global Break Condition @@ -515,7 +517,9 @@ evaluating the condition gets an error, execution does not stop. @findex edebug-set-global-break-condition The condition expression is stored in @code{edebug-global-break-condition}. You can specify a new expression -using the @kbd{X} command (@code{edebug-set-global-break-condition}). +using the @kbd{X} command from the source code buffer while Edebug is +active, or using @kbd{C-x X X} from any buffer at any time, as long as +Edebug is loaded (@code{edebug-set-global-break-condition}). The global break condition is the simplest way to find where in your code some event occurs, but it makes code run much more slowly. So you @@ -582,13 +586,14 @@ effect outside of Edebug. @table @kbd @item v -Temporarily view the outside window configuration -(@code{edebug-view-outside}). +View the outside window configuration (@code{edebug-view-outside}). +Type @kbd{C-x X w} to return to Edebug. @item p -Temporarily display the outside current buffer with point at its outside -position (@code{edebug-bounce-point}). With a prefix argument @var{n}, -pause for @var{n} seconds instead. +Temporarily display the outside current buffer with point at its +outside position (@code{edebug-bounce-point}), pausing for one second +before returning to Edebug. With a prefix argument @var{n}, pause for +@var{n} seconds instead. @item w Move point back to the current stop point in the source code buffer @@ -610,8 +615,12 @@ source code buffer, you must use @kbd{C-x X W} from the global keymap. You can view the outside window configuration with @kbd{v} or just bounce to the point in the current buffer with @kbd{p}, even if -it is not normally displayed. After moving point, you may wish to jump -back to the stop point with @kbd{w} from a source code buffer. +it is not normally displayed. + + After moving point, you may wish to jump back to the stop point. +You can do that with @kbd{w} from a source code buffer. You can jump +back to the stop point in the source code buffer from any buffer using +@kbd{C-x X w}. Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the saved outside window configuration---so that even if you turn saving @@ -838,8 +847,9 @@ redefining the functions @code{edebug-print-trace-before} and @defmac edebug-tracing string body@dots{} This macro requests additional trace information around the execution of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer. All the arguments are evaluated, and -@code{edebug-tracing} returns the value of the last form in @var{body}. +to put in the trace buffer, after the @samp{@{} or @samp{@}}. All +the arguments are evaluated, and @code{edebug-tracing} returns the +value of the last form in @var{body}. @end defmac @defun edebug-trace format-string &rest format-args @@ -990,7 +1000,7 @@ current buffer, are saved and restored. @item @cindex window configuration (Edebug) The outside window configuration is saved and restored if -@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}). +@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). The window configuration is not restored on error or quit, but the outside selected window @emph{is} reselected even on error or quit in @@ -1061,8 +1071,21 @@ Edebug is active, @code{defining-kbd-macro} is bound to @code{edebug-continue-kbd-macro}. @end itemize +@node Edebug and Macros +@subsection Edebug and Macros + +To make Edebug properly instrument expressions that call macros, some +extra care is needed. This subsection explains the details. + +@menu +* Instrumenting Macro Calls:: The basic problem. +* Specification List:: How to specify complex patterns of evaluation. +* Backtracking:: What Edebug does when matching fails. +* Specification Examples:: To help understand specifications. +@end menu + @node Instrumenting Macro Calls -@subsection Instrumenting Macro Calls +@subsubsection Instrumenting Macro Calls When Edebug instruments an expression that calls a Lisp macro, it needs additional information about the macro to do the job properly. This is @@ -1101,7 +1124,7 @@ define Edebug specifications for special forms implemented in C. @deffn Macro def-edebug-spec macro specification Specify which expressions of a call to macro @var{macro} are forms to be evaluated. @var{specification} should be the edebug specification. -It is not evaluated. +Neither argument is evaluated. The @var{macro} argument can actually be any symbol, not just a macro name. @@ -1128,12 +1151,12 @@ calling form. The possible elements of a specification list are described in the following sections. @end table -@menu -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. -@end menu - +@vindex edebug-eval-macro-args +If a macro has no Edebug specification, neither through a @code{debug} +declaration nor through a @code{def-edebug-spec} call, the variable +@code{edebug-eval-macro-args} comes into play. If it is @code{nil}, +the default, none of the arguments is instrumented for evaluation. +If it is non-@code{nil}, all arguments are instrumented. @node Specification List @subsubsection Specification List @@ -1406,7 +1429,7 @@ inside of the sublist to prevent backtracking once a sublist is found. Edebug uses the following specifications for @code{defun} and @code{defmacro} and the associated argument list and @code{interactive} specifications. It is necessary to handle interactive forms specially -since an expression argument it is actually evaluated outside of the +since an expression argument is actually evaluated outside of the function body. @smallexample -- cgit v1.2.1 From 67774855068c4b87aeb0b75d003e77347fe97a47 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Tue, 14 Jun 2005 23:36:31 +0000 Subject: (Top): Update detailed menu. --- lispref/ChangeLog | 2 ++ lispref/elisp.texi | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'lispref') diff --git a/lispref/ChangeLog b/lispref/ChangeLog index dccb76c4dae..c565e8bdb5f 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,5 +1,7 @@ 2005-06-14 Luc Teirlinck + * elisp.texi (Top): Update detailed menu. + * edebug.texi (Edebug): Update menu. (Instrumenting): Update xrefs. (Edebug Execution Modes): Correct xref. diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 1e816487e14..4be680969a1 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -514,7 +514,7 @@ Edebug * Edebug Execution Modes:: Execution modes, stopping more or less often. * Jumping:: Commands to jump to a specified place. * Edebug Misc:: Miscellaneous commands. -* Breakpoints:: Setting breakpoints to make the program stop. +* Breaks:: Setting breakpoints to make the program stop. * Trapping Errors:: Trapping errors with Edebug. * Edebug Views:: Views inside and outside of Edebug. * Edebug Eval:: Evaluating expressions within Edebug. @@ -524,7 +524,7 @@ Edebug * Trace Buffer:: How to produce trace output in a buffer. * Coverage Testing:: How to test evaluation coverage. * The Outside Context:: Data that Edebug saves and restores. -* Instrumenting Macro Calls:: Specifying how to handle macro calls. +* Edebug and Macros:: Specifying how to handle macro calls. * Edebug Options:: Option variables for customizing Edebug. Debugging Invalid Lisp Syntax -- cgit v1.2.1